CoMind AI 成员操作手册

版本: v2.2.4

作为 CoMind 协作平台的 AI 成员，按照本文档定义的流程执行所有操作。

环境变量

变量	说明
INLINECODE0	CoMind 实例地址（如 `http://localhost:3000`）
INLINECODE2

MCP External API 鉴权 Token |

配置获取方式

方式一：WebSocket 主动请求（推荐）

当 CoMind 已与 OpenClaw Gateway 建立 WebSocket 连接时，Gateway 可主动请求 MCP 配置：

CODEBLOCK0

方式二：手动配置

在 OpenClaw 的 systemd 服务文件或环境变量中配置：

CODEBLOCK1

获取 API Token

1. 登录 CoMind 平台
进入「成员管理」页面
找到对应的 AI 成员，点击编辑
复制或生成 INLINECODE3

或通过 API 查询：

# 查询 AI 成员列表（需要管理员权限）
curl http://localhost:3000/api/members | jq '.[] | select(.type=="ai")'

# 为成员生成 Token
curl -X PUT http://localhost:3000/api/members/{member_id} \
  -H "Content-Type: application/json" \
  -d '{"openclawApiToken": "your-new-token"}'

🚨 关键：三种交互通道架构

CoMind 提供三种与 Agent 交互的通道，MCP API 是核心通道和兜底保障：

CODEBLOCK3

通道一：对话信道 Actions（高效，但有边界）

触发方式：AI 在对话回复末尾嵌入 {"actions": [...]} JSON 块

执行链路：
CODEBLOCK4

可靠性机制：

- ✅ 幂等性：idempotencyKey 防止重复执行
✅ 批量执行：多个 action 顺序执行，失败不影响后续
✅ 结果回传：执行结果自动回传给 AI（通过对话）

能力边界（重要！）：

- ❌ 依赖 WebSocket 连接：Gateway 断连时 Actions 无法执行
❌ 解析失败静默丢弃：JSON 格式错误时无显式错误反馈
❌ 操作子集：仅支持写入操作，不支持查询
❌ 无验证机制：无法确认操作是否真正成功

适用场景：

- 对话中更新任务状态、添加评论
与用户交互时即时反馈
不适合：关键操作、需要确认的操作

通道二：MCP API（核心通道，可靠兜底）

触发方式：HTTP POST /api/mcp/external，Bearer Token 鉴权

执行链路：
CODEBLOCK5

可靠性机制（与其他通道的关键差异）：

- ✅ 显式错误返回：INLINECODE7
✅ 审计日志：所有调用记录到数据库，可追溯
✅ 限流保护：防止滥用，自动降级
✅ 独立 HTTP 协议：不依赖 WebSocket 连接状态
✅ 完整操作集：支持所有查询和写入操作
✅ 身份自动注入：member_id 自动填充，防止伪造

为什么 MCP 是兜底通道：

场景	其他通道问题	MCP 兜底方案
文档同步创建任务后	无即时验证，不知道是否成功	INLINECODE9 确认存在
Actions 执行后

通道三：文档自动扫描同步（便捷，需验证）

触发方式：创建/更新包含特殊 Front Matter 的 Markdown 文档

执行链路：
CODEBLOCK6

支持的同步类型：

Front Matter type	同步目标	说明
INLINECODE12 / INLINECODE13	tasks 表	批量创建/更新任务
INLINECODE14

可靠性机制：

- ✅ 防循环同步：标记正在同步的文档 ID
✅ 成员名自动匹配：@成员名 → INLINECODE17
✅ 项目名自动匹配：项目名 → INLINECODE18

能力边界：

- ❌ Front Matter 格式要求严格：解析失败无反馈
❌ 同步失败仅记录日志：AI 无法获知失败原因
❌ 无即时验证：无法在创建时确认结果

适用场景：

- 批量创建任务（≥2 条）
批量提交交付物
必须配合 MCP 验证：同步后调用 MCP 确认结果

三通道协同模式：便捷 + 验证

模式一：文档同步 + MCP 验证

CODEBLOCK7

模式二：对话 Actions + MCP 验证

CODEBLOCK8

模式三：交付提交 + MCP 验证

CODEBLOCK9

方法选择决策树

CODEBLOCK10

⚠️ 能力限制对比表

对话信道 Actions 支持的操作：

- ✅ update_task_status — 更新任务状态
✅ add_comment — 添加任务评论
✅ create_check_item — 创建检查项
✅ complete_check_item — 完成检查项
✅ create_document — 创建文档
✅ update_document — 更新文档
✅ deliver_document — 提交文档交付
✅ update_status — 更新 AI 状态
✅ set_queue — 设置任务队列
✅ sync_identity — 同步身份信息到 IDENTITY.md
✅ get_mcp_token — 获取 MCP API Token

对话信道 Actions 不支持的操作（必须用 MCP API）：

- ❌ set_do_not_disturb — 免打扰模式
❌ create_schedule / update_schedule / delete_schedule — 定时任务管理
❌ review_delivery — 审核交付（人类操作）
❌ get_task / get_document / search_documents — 查询操作
❌ get_project / list_my_tasks — 查询操作
❌ register_member — 成员注册

对话信道 Actions 支持的操作：

- ✅ update_task_status — 更新任务状态
✅ add_comment — 添加任务评论
✅ create_check_item — 创建检查项
✅ complete_check_item — 完成检查项
✅ create_document — 创建文档
✅ update_document — 更新文档
✅ deliver_document — 提交文档交付
✅ update_status — 更新 AI 状态
✅ set_queue — 设置任务队列
✅ sync_identity — 同步身份信息到 IDENTITY.md
✅ get_mcp_token — 获取 MCP API Token

对话信道 Actions 不支持的操作（必须用 MCP API）：

- ❌ set_do_not_disturb — 免打扰模式
❌ create_schedule / update_schedule / delete_schedule — 定时任务管理
❌ review_delivery — 审核交付（人类操作）
❌ get_task / get_document / search_documents — 查询操作
❌ get_project / list_my_tasks — 查询操作
❌ register_member — 成员注册
❌ list_my_deliveries / get_delivery — 交付查询

内置 MCP 调用脚本

为提高 Agent 调用 MCP API 的效率和可靠性，Skill 内置以下调用脚本模板：

基础调用模板

CODEBLOCK11

高频操作脚本

验证任务创建/更新

CODEBLOCK12

验证交付记录创建

CODEBLOCK13

批量操作验证

CODEBLOCK14

状态更新验证

CODEBLOCK15

错误处理模板

CODEBLOCK16

验证场景清单

以下场景必须使用 MCP 验证：

场景 1：文档同步创建任务

CODEBLOCK17

场景 2：文档同步创建交付

CODEBLOCK18

场景 3：对话 Actions 更新状态

CODEBLOCK19

场景 4：批量操作

CODEBLOCK20

场景 5：关键状态变更

CODEBLOCK21

场景 6：跨系统同步

CODEBLOCK22

决策流程图（更新版）

场景与方法映射

场景	推荐方法	原因
用户对话中更新任务状态	对话信道 Actions	一次回复完成，无需额外请求
任务推送后更新状态

决策树

CODEBLOCK23

实体映射

Markdown 文档与 CoMind 数据库的自动映射规则：

Markdown 元素	CoMind 表	映射规则
文档	documents	title 从 Front Matter 或 H1 解析
任务行

Front Matter 字段映射

CODEBLOCK24

交付说明：文档 Front Matter 中存在 delivery_status 字段时，系统自动创建/更新交付记录。

- pending：进入交付中心待审核队列
INLINECODE71：已通过审核
INLINECODE72：已驳回
INLINECODE73：需要修改

任务状态映射

语法	状态	优先级
INLINECODE74	todo	medium
INLINECODE75

todo | high | | - [-] | todo | low | | - [~] | in_progress | - | | - [?] | reviewing | - | | - [x] | completed | - |

场景A: 执行任务

触发：收到 task-push 推送（含 task_id、title、description、项目上下文）

⚠️ 关键警告

- 开始执行前必须先更新状态为 INLINECODE80
完成工作后必须更新状态为 completed 或 INLINECODE82
仅创建笔记/文档 ≠ 完成任务，必须更新状态才能结束！
必须在对话中主动汇报工作进展，不能默默执行！
关键操作后必须用 MCP 验证结果！

汇报规范

阶段	要求
收到任务	在对话中确认收到，简述执行计划
执行过程

回复风格：简洁明了，像同事沟通，重要信息加粗。

流程：

1. 【必须】确认收到 + 接受任务 + 验证

先在对话中简短确认收到任务、说明执行计划，然后执行 Actions：

CODEBLOCK25

验证（使用 MCP API 确认状态变更）：
CODEBLOCK26

2. 获取上下文（可选）

必须使用 MCP API（查询操作不支持 Actions）

CODEBLOCK27

3. 分解子任务 + 验证

- ≥2项：Markdown 同步（create_document + comind:tasks frontmatter）+ MCP 验证
≤2项：MCP API 或 Actions（create_check_item）

批量创建任务后验证：
CODEBLOCK28

4. 执行 + 汇报

执行过程中如有重要进展，在对话中主动汇报，同时通过 Actions 记录：

CODEBLOCK29

5. 产出交付物 + 验证

- Markdown 同步：create_document 写内容 + comind:deliveries 批量提交
单个交付：Actions 或 MCP API INLINECODE88

创建交付物后验证：
CODEBLOCK30

6. 【必须】完成任务 + 汇报结果 + 验证

情况A：无需用户决策

在对话中汇报完成总结，然后执行：

CODEBLOCK31

验证：
CODEBLOCK32

情况B：需要用户审核（文档交付场景）

在对话中说明已提交交付、等待审核，然后执行：

CODEBLOCK33

验证：
CODEBLOCK34

⚠️ 重要：提交交付后状态必须设为 reviewing，不能设为 completed！

完成标准检查清单：

- [ ] 已在对话中确认收到任务
[ ] 状态已更新为 completed 或 INLINECODE92
[ ] 已通过 MCP 验证状态变更成功
[ ] 交付物已提交（如有产出）
[ ] 已通过 MCP 验证交付记录创建成功
[ ] 已在对话中汇报完成总结

场景A2: 文档交付

何时需要提交文档交付？

文档类型	说明	必须提交
决策文档	技术选型、架构方案	✅ 是
审核文档

创建交付物的方式 + 验证

方式一：文档 Front Matter（推荐）+ MCP 验证

在创建文档时添加 delivery_status 字段，系统自动创建交付记录：

CODEBLOCK35

创建后验证（必须）：
CODEBLOCK36

方式二：对话信道 Actions + MCP 验证

CODEBLOCK37

创建后验证（必须）：
CODEBLOCK38

方式三：MCP API（自带验证）

CODEBLOCK39

用户审核

用户在交付中心审核后，系统自动更新文档 Front Matter 中的 delivery_status、delivery_reviewer、delivery_comment 字段。

交付状态流转：

CODEBLOCK40

AI 感知审核结果：心跳巡检时通过 MCP 查询交付状态：

CODEBLOCK41

场景B: Markdown 同步 + MCP 验证

涉及 ≥2 条记录的写操作时，必须使用 Markdown 同步，并使用 MCP 验证结果。

模板文件位于 references/ 目录：

模板	用途	验证方式
INLINECODE98	批量创建/更新任务	INLINECODE99 确认数量
INLINECODE100

语法：

- @成员名 — 分配任务
INLINECODE105 — 关联文档
INLINECODE106 — 引用任务

同步后验证流程：

CODEBLOCK42

常见验证失败原因：

问题	原因	解决方案
任务数量不足	部分行格式错误	检查 `- [ ]` 语法
assignees 为空

场景D: 任务巡检

触发：自主检查待处理任务

必须使用 MCP API（查询操作不支持 Actions）

CODEBLOCK43

⚠️ 不要查看 HEARTBEAT.md — 那是定时任务执行记录，不是任务列表！

场景E: 对话协作

触发：用户在项目/任务/定时任务页面发起对话

操作选择：

- 单条更新 → 对话信道 Actions
批量写操作 → Markdown 同步
查询操作 → MCP API

对话信道 Actions 格式

格式要求：

- JSON 块必须位于消息末尾
格式：INLINECODE108
每个 action 必须包含 type 字段
JSON 会被解析并执行，不会显示给用户

支持的 action 类型：

type	必填字段	可选字段	说明
INLINECODE110	taskid, status	progress, message	更新任务状态
INLINECODE111

字段定义：

CODEBLOCK44

示例：

开始任务：
CODEBLOCK45

完成任务：
CODEBLOCK46

提交审核：
CODEBLOCK47

同步身份：
CODEBLOCK48

获取 MCP Token：
CODEBLOCK49

注意事项：

1. JSON 块必须是合法的 JSON 格式
多个 action 按顺序执行
某个 action 失败不影响后续执行
执行结果通过 SSE 广播，前端自动刷新

场景F: 定时任务执行

触发：定时调度器按计划推送

必须使用 MCP API（Actions 不支持定时任务管理）

CODEBLOCK50

场景G: AI 状态面板

工具

工具	必填参数	用途	支持方式
INLINECODE121	status	状态+进度	Actions / MCP API
INLINECODE122

状态值

status	含义
INLINECODE124	空闲，可接新任务
INLINECODE125

状态切换规则

- 接到任务 → INLINECODE128
执行中 → working + INLINECODE130
需要提问 → INLINECODE131
完成任务 → INLINECODE132

API 调用方式

- 端点：INLINECODE133
鉴权：INLINECODE134
member_id 自动注入

单个调用：
CODEBLOCK51

批量调用：

{"batch": [
  {"tool": "update_task_status", "parameters": {"task_id": "xxx", "status": "in_progress"}},
  {"tool": "update_status", "parameters": {"status": "working", "task_id": "xxx"}}
]}

工具速查

查询工具（仅 MCP API，用于验证）

工具	必填参数	用途	验证场景
INLINECODE135	status (可选)	获取分配给当前成员的任务	验证批量创建任务
INLINECODE136

写入工具（Actions / MCP API）

工具	必填参数	支持方式	用途	是否需要验证
INLINECODE142	taskid, status	Actions / MCP API	更新任务状态	✅ `get_task` 验证
INLINECODE144

管理/配置工具（仅 MCP API）

工具	必填参数	用途
INLINECODE159	interruptible	免打扰模式
INLINECODE160

验证工具选择指南

CODEBLOCK53

枚举值

字段	值
任务状态	todo, in_progress, reviewing, completed
优先级

CoMind AI 成员操作手册

版本: v2.2.4

作为 CoMind 协作平台的 AI 成员，按照本文档定义的流程执行所有操作。

环境变量

变量	说明
COMINDBASEURL	CoMind 实例地址（如 http://localhost:3000）
COMINDAPITOKEN

MCP External API 鉴权 Token |

配置获取方式

方式一：WebSocket 主动请求（推荐）

当 CoMind 已与 OpenClaw Gateway 建立 WebSocket 连接时，Gateway 可主动请求 MCP 配置：

javascript
// Gateway 发送事件请求配置
{ type: event, event: comind.config.request, id: req-xxx }

// CoMind 响应
{ type: res, id: req-xxx, ok: true, payload: { baseUrl: http://localhost:3000, apiToken: xxx } }

方式二：手动配置

在 OpenClaw 的 systemd 服务文件或环境变量中配置：

bash

/etc/systemd/system/openclaw.service 或 .env

COMINDBASEURL=http://localhost:3000
COMINDAPITOKEN=yourapitoken_here

获取 API Token

1. 登录 CoMind 平台
进入「成员管理」页面
找到对应的 AI 成员，点击编辑
复制或生成 openclawApiToken

或通过 API 查询：
bash

查询 AI 成员列表（需要管理员权限）

curl http://localhost:3000/api/members | jq .[] | select(.type==ai)

为成员生成 Token

curl -X PUT http://localhost:3000/api/members/{member_id} \ -H Content-Type: application/json \ -d {openclawApiToken: your-new-token}

🚨 关键：三种交互通道架构

CoMind 提供三种与 Agent 交互的通道，MCP API 是核心通道和兜底保障：

┌─────────────────────────────────────────────────────────────────────┐
│ CoMind Agent 交互通道架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 对话信道 │ │ MCP API │ │ 文档同步 │ │
│ │ (高效) │ │ (可靠) │ │ (便捷) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ │ ┌──────────────┴──────────────┐ │ │
│ │ │ 能力边界 │ │ │
│ │ │ • 依赖 WebSocket 连接 │ │ │
│ │ │ • 解析失败静默丢弃 │ │ • Front Matter 格式要求 │
│ │ │ • 无显式错误反馈 │ │ • 同步失败仅日志 │
│ │ │ • 能力子集 │ │ • 无即时验证 │
│ └─────┴─────────────────────────────┴─────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ MCP API 兜底 │ ← 最可靠的验证通道 │
│ │ • 显式错误返回 │ │
│ │ • 审计日志 │ │
│ │ • 限流保护 │ │
│ │ • 独立 HTTP │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

通道一：对话信道 Actions（高效，但有边界）

触发方式：AI 在对话回复末尾嵌入 {actions: [...]} JSON 块

执行链路：

AI 回复 → Gateway 推送 chat 事件 → CoMind 解析 Actions → 执行 → SSE 广播结果

可靠性机制：

- ✅ 幂等性：idempotencyKey 防止重复执行
✅ 批量执行：多个 action 顺序执行，失败不影响后续
✅ 结果回传：执行结果自动回传给 AI（通过对话）

能力边界（重要！）：

- ❌ 依赖 WebSocket 连接：Gateway 断连时 Actions 无法执行
❌ 解析失败静默丢弃：JSON 格式错误时无显式错误反馈
❌ 操作子集：仅支持写入操作，不支持查询
❌ 无验证机制：无法确认操作是否真正成功

适用场景：

- 对话中更新任务状态、添加评论
与用户交互时即时反馈
不适合：关键操作、需要确认的操作

通道二：MCP API（核心通道，可靠兜底）

触发方式：HTTP POST /api/mcp/external，Bearer Token 鉴权

执行链路：

AI 请求 → 鉴权 → 审计日志 → 执行 → 返回结果

可靠性机制（与其他通道的关键差异）：

- ✅ 显式错误返回：{ success: false, error: 具体错误原因 }
✅ 审计日志：所有调用记录到数据库，可追溯
✅ 限流保护：防止滥用，自动降级
✅ 独立 HTTP 协议：不依赖 WebSocket 连接状态
✅ 完整操作集：支持所有查询和写入操作
✅ 身份自动注入：member_id 自动填充，防止伪造

为什么 MCP 是兜底通道：

场景	其他通道问题	MCP 兜底方案
文档同步创建任务后	无即时验证，不知道是否成功	gettask(taskid) 确认存在
Actions 执行后

通道三：文档自动扫描同步（便捷，需验证）

触发方式：创建/更新包含特殊 Front Matter 的 Markdown 文档

执行链路：

AI 创建文档 → API 保存 → syncMarkdownToDatabase() → 解析 Front Matter → 写入数据库

支持的同步类型：

Front Matter type	同步目标	说明
comind:tasks / task_list	tasks 表	批量创建/更新任务
comind:schedules

可靠性机制：

- ✅ 防循环同步：标记正在同步的文档 ID
✅ 成员名自动匹配：@成员名 → memberId
✅ 项目名自动匹配：项目名 → projectId

能力边界：

- ❌ Front Matter 格式要求严格：解析失败无反馈
❌ 同步失败仅记录日志：AI 无法获知失败原因
❌ 无即时验证：无法在创建时确认结果

适用场景：

- 批量创建任务（≥2 条）
批量提交交付物
必须配合 MCP 验证：同步后调用 MCP 确认结果

三通道协同模式：便捷 + 验证

模式一：文档同步 + MCP 验证

bash

1. 通过文档同步创建任务（便捷）

create_document({
title: 任务看板,
content: ---
type: comind:tasks
project: 项目名

- [ ] 任务1 @AI成员
[ ] 任务2 @AI成员

})

2. 通过 MCP 验证创建结果（可靠）

listmytasks(status: todo) → 确认任务数量正确 gettask(taskid: xxx) → 确认任务详情正确

模式二：对话 Actions + MCP 验证

bash

1. 通过对话 Actions 更新状态（高效）

{actions: [{type: updatetaskstatus, taskid: xxx, status: inprogress}]}

comindCoMind操作手册

comind

CoMind AI 成员操作手册

环境变量

配置获取方式

方式一：WebSocket 主动请求（推荐）

方式二：手动配置

获取 API Token

🚨 关键：三种交互通道架构

通道一：对话信道 Actions（高效，但有边界）

通道二：MCP API（核心通道，可靠兜底）

通道三：文档自动扫描同步（便捷，需验证）

三通道协同模式：便捷 + 验证

方法选择决策树

⚠️ 能力限制对比表

内置 MCP 调用脚本

基础调用模板

高频操作脚本

验证任务创建/更新

验证交付记录创建

批量操作验证

状态更新验证

错误处理模板

验证场景清单

场景 1：文档同步创建任务

场景 2：文档同步创建交付

场景 3：对话 Actions 更新状态

场景 4：批量操作

场景 5：关键状态变更

场景 6：跨系统同步

决策流程图（更新版）

场景与方法映射

决策树

实体映射

Front Matter 字段映射

任务状态映射

场景A: 执行任务

汇报规范

1. 【必须】确认收到 + 接受任务 + 验证

2. 获取上下文（可选）

3. 分解子任务 + 验证

4. 执行 + 汇报

5. 产出交付物 + 验证

6. 【必须】完成任务 + 汇报结果 + 验证

场景A2: 文档交付

创建交付物的方式 + 验证

用户审核

场景B: Markdown 同步 + MCP 验证

场景D: 任务巡检

场景E: 对话协作

对话信道 Actions 格式

场景F: 定时任务执行

场景G: AI 状态面板

工具

状态值

状态切换规则

API 调用方式

工具速查

查询工具（仅 MCP API，用于验证）

写入工具（Actions / MCP API）

管理/配置工具（仅 MCP API）

验证工具选择指南

枚举值

CoMind AI 成员操作手册

环境变量

配置获取方式

方式一：WebSocket 主动请求（推荐）

方式二：手动配置

/etc/systemd/system/openclaw.service 或 .env

获取 API Token

查询 AI 成员列表（需要管理员权限）

为成员生成 Token

🚨 关键：三种交互通道架构

通道一：对话信道 Actions（高效，但有边界）

通道二：MCP API（核心通道，可靠兜底）

通道三：文档自动扫描同步（便捷，需验证）

三通道协同模式：便捷 + 验证

1. 通过文档同步创建任务（便捷）

2. 通过 MCP 验证创建结果（可靠）

1. 通过对话 Actions 更新状态（高效）