Comind

CoMind AI 成员操作手册

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

环境变量

变量说明COMIND_BASE_URLCoMind 实例地址（如 http://localhost:3000）COMIND_API_TOKENMCP External API 鉴权 Token

配置获取方式

方式一：WebSocket 主动请求（推荐） 当 CoMind 已与 OpenClaw Gateway 建立 WebSocket 连接时，Gateway 可主动请求 MCP 配置： // 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 服务文件或环境变量中配置： # /etc/systemd/system/openclaw.service 或 .env COMIND_BASE_URL=http://localhost:3000 COMIND_API_TOKEN=your_api_token_here 获取 API Token 登录 CoMind 平台 进入「成员管理」页面 找到对应的 AI 成员，点击编辑 复制或生成 openclawApiToken 或通过 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 是核心通道和兜底保障： ┌─────────────────────────────────────────────────────────────────────┐ │ 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 兜底方案文档同步创建任务后无即时验证，不知道是否成功get_task(task_id) 确认存在Actions 执行后无错误反馈，可能静默失败get_task(task_id) 验证状态关键状态变更可能因断连丢失MCP 独立请求，确保送达批量操作验证同步失败仅日志list_my_tasks 验证结果

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

触发方式：创建/更新包含特殊 Front Matter 的 Markdown 文档 执行链路： AI 创建文档 → API 保存 → syncMarkdownToDatabase() → 解析 Front Matter → 写入数据库 支持的同步类型： Front Matter type同步目标说明comind:tasks / task_listtasks 表批量创建/更新任务comind:schedulesschedules 表创建定时任务delivery_status: pendingdeliveries 表创建交付记录 可靠性机制： ✅ 防循环同步：标记正在同步的文档 ID ✅ 成员名自动匹配：@成员名 → memberId ✅ 项目名自动匹配：项目名 → projectId 能力边界： ❌ Front Matter 格式要求严格：解析失败无反馈 ❌ 同步失败仅记录日志：AI 无法获知失败原因 ❌ 无即时验证：无法在创建时确认结果 适用场景： 批量创建任务（≥2 条） 批量提交交付物 必须配合 MCP 验证：同步后调用 MCP 确认结果

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

• 模式一：文档同步 + MCP 验证
• # 1. 通过文档同步创建任务（便捷）
• create_document({
• title: "任务看板",
• content: "---
• type: comind:tasks
• project: 项目名
• ---
• [ ] 任务1 @AI成员
• [ ] 任务2 @AI成员"
• })
• # 2. 通过 MCP 验证创建结果（可靠）
• list_my_tasks(status: "todo") → 确认任务数量正确
• get_task(task_id: "xxx") → 确认任务详情正确
• 模式二：对话 Actions + MCP 验证
• # 1. 通过对话 Actions 更新状态（高效）
• {"actions": [{"type": "update_task_status", "task_id": "xxx", "status": "in_progress"}]}
• # 2. 通过 MCP 验证更新结果（可靠）
• get_task(task_id: "xxx") → 确认 status 已变为 in_progress
• 模式三：交付提交 + MCP 验证
• # 1. 通过 Front Matter 提交交付（便捷）
• create_document({
• title: "技术方案",
• content: "---
• delivery_status: pending
• delivery_assignee: AI成员名
• related_tasks: [task_xxx]
• ---
• # 技术方案内容..."
• })
• # 2. 通过 MCP 验证交付记录（可靠）
• get_delivery(delivery_id: "xxx") → 确认交付记录已创建
• list_my_deliveries(status: "pending") → 确认在待审核队列中

方法选择决策树

需要执行操作 │ ├─ 是否需要 100% 确认结果？ │ └─ YES → 使用 MCP API（唯一可靠通道） │ ├─ 是否在对话中回复用户？ │ ├─ YES → 操作是否支持对话信道 Actions？ │ │ ├─ YES → 使用 Actions（便捷）+ MCP 验证（可靠） │ │ └─ NO → 使用 MCP API │ │ │ └─ NO → 是否批量写入 ≥2 条记录？ │ ├─ YES → Markdown 同步 + MCP 验证 │ └─ NO → MCP API 单条操作

⚠️ 能力限制对比表

对话信道 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 内置以下调用脚本模板：

基础调用模板

# 环境变量（由 Agent 自动注入） COMIND_BASE_URL="${COMIND_BASE_URL:-http://localhost:3000}" COMIND_API_TOKEN="${COMIND_API_TOKEN}" # 通用调用函数 mcp_call() { local tool="$1" local params="$2" curl -s -X POST "${COMIND_BASE_URL}/api/mcp/external" \ -H "Authorization: Bearer ${COMIND_API_TOKEN}" \ -H "Content-Type: application/json" \ -d "{\"tool\": \"${tool}\", \"parameters\": ${params}}" }

高频操作脚本

验证任务创建/更新 # 文档同步创建任务后验证 verify_task() { local task_id="$1" local expected_status="${2:-todo}" result=$(mcp_call "get_task" "{\"task_id\": \"${task_id}\"}") if echo "$result" | jq -e '.success == true' > /dev/null; then actual_status=$(echo "$result" | jq -r '.data.status') if [ "$actual_status" = "$expected_status" ]; then echo "✅ 任务验证成功: $task_id 状态为 $actual_status" return 0 else echo "⚠️ 任务状态不符: 期望 $expected_status，实际 $actual_status" return 1 fi else echo "❌ 任务验证失败: $(echo "$result" | jq -r '.error')" return 1 fi } 验证交付记录创建 # Front Matter 提交交付后验证 verify_delivery() { local document_id="$1" # 先查询该文档关联的交付记录 result=$(mcp_call "list_my_deliveries" "{\"status\": \"all\"}") delivery_id=$(echo "$result" | jq -r ".data.deliveries[] | select(.document_id == \"${document_id}\") | .id") if [ -n "$delivery_id" ]; then echo "✅ 交付记录已创建: $delivery_id" # 获取详情确认 detail=$(mcp_call "get_delivery" "{\"delivery_id\": \"${delivery_id}\"}") echo "交付状态: $(echo "$detail" | jq -r '.data.status')" return 0 else echo "❌ 未找到关联的交付记录" return 1 fi } 批量操作验证 # 文档同步批量创建任务后验证 verify_bulk_tasks() { local expected_count="$1" local project_id="$2" result=$(mcp_call "list_my_tasks" "{\"status\": \"todo\"}") actual_count=$(echo "$result" | jq '.data.tasks | length') if [ "$actual_count" -ge "$expected_count" ]; then echo "✅ 批量任务验证成功: 创建了 $actual_count 个任务" return 0 else echo "⚠️ 任务数量不足: 期望 $expected_count，实际 $actual_count" return 1 fi } 状态更新验证 # Actions 更新状态后验证 verify_status_update() { local task_id="$1" local expected_status="$2" local max_retries=3 local retry=0 while [ $retry -lt $max_retries ]; do result=$(mcp_call "get_task" "{\"task_id\": \"${task_id}\"}") actual_status=$(echo "$result" | jq -r '.data.status // empty') if [ "$actual_status" = "$expected_status" ]; then echo "✅ 状态验证成功: $task_id → $actual_status" return 0 fi retry=$((retry + 1)) sleep 1 done echo "❌ 状态验证失败: 期望 $expected_status，实际 $actual_status" return 1 }

错误处理模板

# 带重试的 MCP 调用 mcp_call_with_retry() { local tool="$1" local params="$2" local max_retries="${3:-3}" local retry=0 while [ $retry -lt $max_retries ]; do result=$(mcp_call "$tool" "$params") if echo "$result" | jq -e '.success == true' > /dev/null; then echo "$result" return 0 fi error=$(echo "$result" | jq -r '.error') # 限流错误，等待重试 if echo "$error" | grep -q "rate limit"; then sleep $((2 ** retry)) retry=$((retry + 1)) continue fi # 其他错误，直接返回 echo "$result" return 1 done echo '{"success": false, "error": "Max retries exceeded"}' return 1 }

验证场景清单

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

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

操作: create_document({ type: "comind:tasks", ... }) 验证: list_my_tasks() → 确认任务数量和内容 原因: Front Matter 解析失败静默，需显式验证

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

操作: create_document({ delivery_status: "pending", ... }) 验证: list_my_deliveries(status: "pending") → 确认交付记录存在 原因: 交付记录关联复杂，需确认 memberId、documentId 正确

场景 3：对话 Actions 更新状态

操作: {"actions": [{"type": "update_task_status", ...}]} 验证: get_task(task_id) → 确认状态已变更 原因: WebSocket 断连时 Actions 可能丢失

场景 4：批量操作

操作: 文档同步批量创建 N 条记录 验证: list_my_tasks() / list_my_deliveries() → 确认数量 原因: 部分记录可能因解析失败被跳过

场景 5：关键状态变更

操作: 任务完成 / 交付提交 / 状态切换 验证: get_task() / get_delivery() → 确认状态 原因: 关键操作需 100% 确认成功

场景 6：跨系统同步

操作: 外部文档系统同步到 CoMind 验证: search_documents(query) → 确认文档已同步 原因: 外部系统可能延迟或失败

场景与方法映射

场景推荐方法原因用户对话中更新任务状态对话信道 Actions一次回复完成，无需额外请求任务推送后更新状态对话信道 Actions回复即执行，用户可见进度用户对话中查询任务MCP API查询操作不支持 Actions批量创建任务Markdown 同步一次调用创建多条记录定时任务管理MCP APIActions 不支持定时任务获取待办任务列表MCP API (list_my_tasks)查询操作不支持 Actions

决策树

收到指令 ├─ task-push 模板 → 场景A: 执行任务（必须在对话中汇报进展） ├─ chat-* 模板 → 场景E: 对话协作 ├─ 需要全局上下文 → 读取 references/system-info.md 模板格式，调 API 获取数据 └─ 自主巡检 → 场景D: 任务巡检 执行中: ├─ 批量写操作(≥2条) → Markdown 同步 ├─ 单字段更新 → 对话信道 Actions 或 MCP API ├─ 状态面板 → 对话信道 Actions 或 MCP API ├─ 查询数据 → MCP API ├─ 关键进展 → 在对话中主动汇报 └─ 完成 → 在对话中汇报总结 + update_task_status(completed) + update_status(idle)

实体映射

Markdown 文档与 CoMind 数据库的自动映射规则： Markdown 元素CoMind 表映射规则文档documentstitle 从 Front Matter 或 H1 解析任务行tasks按标题匹配，自动创建/更新@成员名members按名称模糊匹配，转 ID 存入 assignees[[文档名]]documents按标题匹配，建立关联关系#task_xxxtasks精确 ID 引用或标题模糊匹配Front Matter各表字段自动解析填充

Front Matter 字段映射

# 必填字段 title: 文档标题 # → documents.title type: report # → documents.docType project: comind-v2 # → documents.projectId（按项目名匹配） created: 2026-02-18 # → documents.createdAt updated: 2026-02-18 # → documents.updatedAt # 可选字段 tags: [标签] # → documents.tags related_tasks: [task_id] # → 关联任务 contains_tasks: true # → 触发任务解析 task_assignees: [成员] # → 任务默认分配 # 交付字段（有 delivery_status 即自动创建交付记录） delivery_status: pending # → deliveries.status（pending | approved | rejected | revision_needed） delivery_assignee: AI成员名 # → deliveries.memberId（按成员名匹配） delivery_platform: local # → deliveries.platform（local | tencent-doc | feishu | notion | other） delivery_version: 1 # → deliveries.version delivery_reviewer: 人类成员名 # → deliveries.reviewerId（审核人填写） delivery_comment: 审核意见 # → deliveries.reviewComment（审核人填写） 交付说明：文档 Front Matter 中存在 delivery_status 字段时，系统自动创建/更新交付记录。 pending：进入交付中心待审核队列 approved：已通过审核 rejected：已驳回 revision_needed：需要修改

任务状态映射

语法状态优先级- [ ]todomedium- [!]todohigh- [-]todolow- [~]in_progress-- [?]reviewing-- [x]completed-

场景A: 执行任务

触发：收到 task-push 推送（含 task_id、title、description、项目上下文） ⚠️ 关键警告 开始执行前必须先更新状态为 in_progress 完成工作后必须更新状态为 completed 或 reviewing 仅创建笔记/文档 ≠ 完成任务，必须更新状态才能结束！ 必须在对话中主动汇报工作进展，不能默默执行！ 关键操作后必须用 MCP 验证结果！

汇报规范

阶段要求收到任务在对话中确认收到，简述执行计划执行过程遇到关键节点或重要发现时，主动在对话中汇报完成时在对话中发送完成总结：做了什么、产出了什么遇到问题立即在对话中说明问题和处理方案 回复风格：简洁明了，像同事沟通，重要信息加粗。 流程：

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

先在对话中简短确认收到任务、说明执行计划，然后执行 Actions： {"actions": [ {"type": "update_task_status", "task_id": "xxx", "status": "in_progress"}, {"type": "update_status", "status": "working", "current_action": "开始执行", "task_id": "xxx"} ]} 验证（使用 MCP API 确认状态变更）： {"tool": "get_task", "parameters": {"task_id": "xxx"}} // 确认返回的 status 为 "in_progress"

2. 获取上下文（可选）

必须使用 MCP API（查询操作不支持 Actions） {"tool": "get_task", "parameters": {"task_id": "xxx"}} {"tool": "get_project", "parameters": {"project_id": "xxx"}}

3. 分解子任务 + 验证

≥2项：Markdown 同步（create_document + comind:tasks frontmatter）+ MCP 验证 ≤2项：MCP API 或 Actions（create_check_item） 批量创建任务后验证： {"tool": "list_my_tasks", "parameters": {"status": "todo"}} // 确认任务数量和内容正确

4. 执行 + 汇报

执行过程中如有重要进展，在对话中主动汇报，同时通过 Actions 记录： {"actions": [ {"type": "add_comment", "task_id": "xxx", "content": "进展：正在分析需求..."}, {"type": "update_status", "status": "working", "progress": 30} ]}

5. 产出交付物 + 验证

Markdown 同步：create_document 写内容 + comind:deliveries 批量提交 单个交付：Actions 或 MCP API deliver_document 创建交付物后验证： {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 确认交付记录已创建，document_id 正确关联

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

情况A：无需用户决策 在对话中汇报完成总结，然后执行： {"actions": [ {"type": "update_task_status", "task_id": "xxx", "status": "completed"}, {"type": "add_comment", "task_id": "xxx", "content": "✅ 任务已完成！"}, {"type": "update_status", "status": "idle"} ]} 验证： {"tool": "get_task", "parameters": {"task_id": "xxx"}} // 确认 status 为 "completed" 情况B：需要用户审核（文档交付场景） 在对话中说明已提交交付、等待审核，然后执行： {"actions": [ {"type": "deliver_document", "title": "技术方案", "platform": "local", "document_id": "doc_xxx", "task_id": "xxx"}, {"type": "update_task_status", "task_id": "xxx", "status": "reviewing"}, {"type": "add_comment", "task_id": "xxx", "content": "📄 已提交交付中心，等待审核"} ]} 验证： {"tool": "get_task", "parameters": {"task_id": "xxx"}} // 确认 status 为 "reviewing" {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 确认交付记录已创建 ⚠️ 重要：提交交付后状态必须设为 reviewing，不能设为 completed！ 完成标准检查清单： 已在对话中确认收到任务 状态已更新为 completed 或 reviewing 已通过 MCP 验证状态变更成功 交付物已提交（如有产出） 已通过 MCP 验证交付记录创建成功 已在对话中汇报完成总结

场景A2: 文档交付

何时需要提交文档交付？ 文档类型说明必须提交决策文档技术选型、架构方案✅ 是审核文档预算报告、合同草案✅ 是外部发布公众号文章、产品公告✅ 是临时笔记学习笔记、过程记录❌ 否工作日志过程记录、信息整理❌ 否

创建交付物的方式 + 验证

方式一：文档 Front Matter（推荐）+ MCP 验证 在创建文档时添加 delivery_status 字段，系统自动创建交付记录： --- title: 技术方案 type: decision project: 项目名 created: 2026-02-24T10:00:00Z updated: 2026-02-24T10:00:00Z # 交付字段 delivery_status: pending delivery_assignee: 你的名字 delivery_platform: local delivery_version: 1 related_tasks: [task_xxx] --- # 技术方案内容... 创建后验证（必须）： // 验证交付记录已创建 {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 验证文档关联正确 {"tool": "get_delivery", "parameters": {"delivery_id": "从上面返回的 ID"}} // 确认 document_id、task_id 关联正确 方式二：对话信道 Actions + MCP 验证 {"actions": [ {"type": "deliver_document", "title": "技术方案", "platform": "local", "document_id": "doc_xxx", "task_id": "xxx"} ]} 创建后验证（必须）： {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 确认交付记录存在，document_id 正确 方式三：MCP API（自带验证） {"tool": "deliver_document", "parameters": { "title": "技术方案", "platform": "local", "document_id": "doc_xxx", "task_id": "xxx" }} // 返回结果包含 delivery_id，可确认创建成功

用户审核

用户在交付中心审核后，系统自动更新文档 Front Matter 中的 delivery_status、delivery_reviewer、delivery_comment 字段。 交付状态流转： pending → approved (用户批准) → 任务可 completed → rejected (用户拒绝) → revision_needed (需要修改) AI 感知审核结果：心跳巡检时通过 MCP 查询交付状态： {"tool": "list_my_deliveries", "parameters": {"status": "revision_needed"}} {"tool": "get_delivery", "parameters": {"delivery_id": "xxx"}} // 获取 review_comment 了解审核意见

场景B: Markdown 同步 + MCP 验证

涉及 ≥2 条记录的写操作时，必须使用 Markdown 同步，**并使用 MCP 验证结果。 模板文件位于 references/ 目录： 模板用途验证方式task-board.md批量创建/更新任务list_my_tasks 确认数量schedules.md管理定时调度list_schedules 确认创建deliveries.md批量提交交付物list_my_deliveries 确认 语法： @成员名 — 分配任务 [[文档名]] — 关联文档 #task_xxx — 引用任务 同步后验证流程： # 1. 执行文档同步 create_document({ type: "comind:tasks", content: "..." }) # 2. 验证同步结果 list_my_tasks(status: "todo") # 确认： # - 任务数量正确 # - assignees 正确（@成员名 匹配成功） # - project_id 正确（项目名匹配成功） # 3. 如果验证失败 # - 检查 Front Matter 格式 # - 检查成员名/项目名是否存在 # - 手动通过 MCP API 补救 常见验证失败原因： 问题原因解决方案任务数量不足部分行格式错误检查 - [ ] 语法assignees 为空成员名不存在确认成员名拼写或手动分配project_id 为空项目名不存在使用项目 ID 或确认项目存在交付记录未创建delivery_status 格式错误确认 YAML 格式正确

场景D: 任务巡检

触发：自主检查待处理任务 必须使用 MCP API（查询操作不支持 Actions） // 获取待办任务 {"tool": "list_my_tasks", "parameters": {"status": "todo"}} // 获取所有未完成任务 {"tool": "list_my_tasks", "parameters": {"status": "all"}} ⚠️ 不要查看 HEARTBEAT.md — 那是定时任务执行记录，不是任务列表！

场景E: 对话协作

触发：用户在项目/任务/定时任务页面发起对话 操作选择： 单条更新 → 对话信道 Actions 批量写操作 → Markdown 同步 查询操作 → MCP API

对话信道 Actions 格式

格式要求： JSON 块必须位于消息末尾 格式：{"actions": [action1, action2, ...]} 每个 action 必须包含 type 字段 JSON 会被解析并执行，不会显示给用户 支持的 action 类型： type必填字段可选字段说明update_task_statustask_id, statusprogress, message更新任务状态add_commenttask_id, content—添加任务评论create_check_itemtask_id, text—创建检查项complete_check_itemtask_id, item_id—完成检查项create_documenttitle, contentdoc_type, project_id创建文档update_documentdocument_id, contentdoc_type更新文档deliver_documenttitle, platformdocument_id, external_url, task_id提交文档交付update_statusstatuscurrent_action, task_id, progress更新 AI 状态set_queuequeued_tasks—设置任务队列sync_identity—name, creature, vibe, emoji, avatar同步身份信息get_mcp_tokenmember_id—获取 MCP Token 字段定义： // 任务状态 status: 'todo' | 'in_progress' | 'reviewing' | 'completed' // AI 状态 status: 'idle' | 'working' | 'waiting' | 'offline' // 文档类型 doc_type: 'note' | 'report' | 'decision' | 'scheduled_task' | 'task_list' | 'other' // 交付平台 platform: 'tencent-doc' | 'feishu' | 'notion' | 'local' | 'other' // 任务队列 queued_tasks: Array<{ id: string; title: string }> 示例： 开始任务： {"actions": [ {"type": "update_task_status", "task_id": "GS4FcWg6twz", "status": "in_progress"}, {"type": "add_comment", "task_id": "GS4FcWg6twz", "content": "开始执行任务"}, {"type": "update_status", "status": "working", "task_id": "GS4FcWg6twz"} ]} 完成任务： {"actions": [ {"type": "update_task_status", "task_id": "GS4FcWg6twz", "status": "completed"}, {"type": "add_comment", "task_id": "GS4FcWg6twz", "content": "✅ 任务已完成！"}, {"type": "update_status", "status": "idle"} ]} 提交审核： {"actions": [ {"type": "deliver_document", "title": "技术方案", "platform": "local", "document_id": "doc_abc", "task_id": "GS4FcWg6twz"}, {"type": "update_task_status", "task_id": "GS4FcWg6twz", "status": "reviewing"}, {"type": "add_comment", "task_id": "GS4FcWg6twz", "content": "📄 已提交交付中心"} ]} 同步身份： {"actions": [ {"type": "sync_identity", "name": "Scout", "creature": "智能助手", "vibe": "专业、高效", "emoji": "🤖"} ]} 获取 MCP Token： {"actions": [ {"type": "get_mcp_token", "member_id": "member_xxx"} ]} 注意事项： JSON 块必须是合法的 JSON 格式 多个 action 按顺序执行 某个 action 失败不影响后续执行 执行结果通过 SSE 广播，前端自动刷新

场景F: 定时任务执行

触发：定时调度器按计划推送 必须使用 MCP API（Actions 不支持定时任务管理） {"tool": "create_schedule", "parameters": { "title": "每日报告", "task_type": "report", "schedule_type": "daily", "schedule_time": "09:00" }}

工具

工具必填参数用途支持方式update_statusstatus状态+进度Actions / MCP APIset_queuequeued_tasks任务队列Actions / MCP APIset_do_not_disturbinterruptible免打扰模式仅 MCP API

状态值

status含义idle空闲，可接新任务working执行任务中waiting等待用户回复/外部资源offline离线

状态切换规则

接到任务 → working 执行中 → working + progress 需要提问 → waiting 完成任务 → idle

API 调用方式

端点：POST ${COMIND_BASE_URL}/api/mcp/external 鉴权：Authorization: Bearer ${COMIND_API_TOKEN} member_id 自动注入 单个调用： {"tool": "update_task_status", "parameters": {"task_id": "xxx", "status": "in_progress"}} 批量调用： {"batch": [ {"tool": "update_task_status", "parameters": {"task_id": "xxx", "status": "in_progress"}}, {"tool": "update_status", "parameters": {"status": "working", "task_id": "xxx"}} ]}

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

工具必填参数用途验证场景list_my_tasksstatus (可选)获取分配给当前成员的任务验证批量创建任务get_tasktask_id获取任务详情验证状态变更get_documentdocument_id 或 title获取文档验证文档创建search_documentsquery搜索文档验证文档同步get_projectproject_id获取项目详情验证项目上下文list_my_deliveriesstatus (可选)获取当前成员的交付物列表验证交付创建get_deliverydelivery_id获取交付物详情（含审核意见）验证交付状态

写入工具（Actions / MCP API）

工具必填参数支持方式用途是否需要验证update_task_statustask_id, statusActions / MCP API更新任务状态✅ get_task 验证add_task_commenttask_id, contentActions / MCP API添加评论❌ 不需要create_check_itemtask_id, textActions / MCP API创建检查项✅ get_task 验证complete_check_itemtask_id, item_idActions / MCP API完成检查项✅ get_task 验证create_documenttitle, contentActions / MCP API创建文档✅ get_document 验证update_documentdocument_id, contentActions / MCP API更新文档✅ get_document 验证deliver_documenttitle, platformActions / MCP API提交交付✅ list_my_deliveries 验证update_statusstatusActions / MCP APIAI 状态面板❌ 不需要set_queuequeued_tasksActions / MCP API任务队列❌ 不需要sync_identity—Actions同步身份信息❌ 不需要get_mcp_tokenmember_idActions获取 MCP Token❌ 不需要

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

工具必填参数用途set_do_not_disturbinterruptible免打扰模式create_scheduletitle, task_type, schedule_type创建定时任务list_schedules—列出定时任务delete_scheduleschedule_id删除定时任务update_scheduleschedule_id, ...更新定时任务register_membername, endpointAI 自注册review_deliverydelivery_id, status审核交付（人类操作）

验证工具选择指南

操作类型 验证工具 ───────────────────────────────────────── 状态变更 (update_task_status) → get_task 批量创建任务 → list_my_tasks 创建/更新文档 → get_document / search_documents 提交交付 → list_my_deliveries + get_delivery 定时任务 → list_schedules

枚举值

字段值任务状态todo, in_progress, reviewing, completed优先级high, medium, lowAI 状态idle, working, waiting, offline文档类型note, report, decision, scheduled_task, task_list, other交付平台tencent-doc, feishu, notion, local, other审核结果approved, rejected, revision_needed定时周期once, daily, weekly, monthly定时类型report, summary, backup, notification, custom