Skill: dqalex/comind (version 2.3.4)

--- name: comind description: CoMind 人机协作平台 AI 成员操作手册。定义任务执行、Markdown 同步、对话协作、状态面板等全部工作流程。当 AI 成员接收到 CoMind 平台的任务推送、对话请求、定时调度或巡检指令时，应使用此 Skill 执行标准化操作。 comind_version: "2.2.4" metadata: { "openclaw": { "always": true, "emoji": "🧠", "homepage": "https://github.com/comind", "requires": { "env": ["COMIND_BASE_URL", "COMIND_API_TOKEN"] } } } --- # CoMind AI 成员操作手册 > **版本**: v2.2.4 作为 CoMind 协作平台的 AI 成员，按照本文档定义的流程执行所有操作。 ## 环境变量 | 变量 | 说明 | |------|------| | `COMIND_BASE_URL` | CoMind 实例地址（如 `http://localhost:3000`） | | `COMIND_API_TOKEN` | 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 COMIND_BASE_URL=http://localhost:3000 COMIND_API_TOKEN=your_api_token_here ``` #### 获取 API Token 1. 登录 CoMind 平台 2. 进入「成员管理」页面 3. 找到对应的 AI 成员，点击编辑 4. 复制或生成 `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 兜底方案 | |------|-------------|-------------| | 文档同步创建任务后 | 无即时验证，不知道是否成功 | `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_list` | tasks 表 | 批量创建/更新任务 | | `comind:schedules` | schedules 表 | 创建定时任务 | | `delivery_status: pending` | deliveries 表 | 创建交付记录 | **可靠性机制**： - ✅ 防循环同步：标记正在同步的文档 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 验证创建结果（可靠） list_my_tasks(status: "todo") → 确认任务数量正确 get_task(task_id: "xxx") → 确认任务详情正确 ``` **模式二：对话 Actions + MCP 验证** ```bash # 1. 通过对话 Actions 更新状态（高效） {"actions": [{"type": "update_task_status", "task_id": "xxx", "status": "in_progress"}]} # 2. 通过 MCP 验证更新结果（可靠） get_task(task_id: "xxx") → 确认 status 已变为 in_progress ``` **模式三：交付提交 + MCP 验证** ```bash # 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 内置以下调用脚本模板： ### 基础调用模板 ```bash # 环境变量（由 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}}" } ``` ### 高频操作脚本 #### 验证任务创建/更新 ```bash # 文档同步创建任务后验证 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 } ``` #### 验证交付记录创建 ```bash # 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 } ``` #### 批量操作验证 ```bash # 文档同步批量创建任务后验证 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 } ``` #### 状态更新验证 ```bash # 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 } ``` ### 错误处理模板 ```bash # 带重试的 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：文档同步创建任务 ```yaml 操作: create_document({ type: "comind:tasks", ... }) 验证: list_my_tasks() → 确认任务数量和内容 原因: Front Matter 解析失败静默，需显式验证 ``` ### 场景 2：文档同步创建交付 ```yaml 操作: create_document({ delivery_status: "pending", ... }) 验证: list_my_deliveries(status: "pending") → 确认交付记录存在 原因: 交付记录关联复杂，需确认 memberId、documentId 正确 ``` ### 场景 3：对话 Actions 更新状态 ```yaml 操作: {"actions": [{"type": "update_task_status", ...}]} 验证: get_task(task_id) → 确认状态已变更 原因: WebSocket 断连时 Actions 可能丢失 ``` ### 场景 4：批量操作 ```yaml 操作: 文档同步批量创建 N 条记录 验证: list_my_tasks() / list_my_deliveries() → 确认数量 原因: 部分记录可能因解析失败被跳过 ``` ### 场景 5：关键状态变更 ```yaml 操作: 任务完成 / 交付提交 / 状态切换 验证: get_task() / get_delivery() → 确认状态 原因: 关键操作需 100% 确认成功 ``` ### 场景 6：跨系统同步 ```yaml 操作: 外部文档系统同步到 CoMind 验证: search_documents(query) → 确认文档已同步 原因: 外部系统可能延迟或失败 ``` --- ## 决策流程图（更新版） ### 场景与方法映射 | 场景 | 推荐方法 | 原因 | |------|---------|------| | 用户对话中更新任务状态 | 对话信道 Actions | 一次回复完成，无需额外请求 | | 任务推送后更新状态 | 对话信道 Actions | 回复即执行，用户可见进度 | | 用户对话中查询任务 | MCP API | 查询操作不支持 Actions | | 批量创建任务 | Markdown 同步 | 一次调用创建多条记录 | | 定时任务管理 | MCP API | Actions 不支持定时任务 | | 获取待办任务列表 | 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 表 | 映射规则 | |--------------|----------|---------| | 文档 | documents | title 从 Front Matter 或 H1 解析 | | 任务行 | tasks | 按标题匹配，自动创建/更新 | | `@成员名` | members | 按名称模糊匹配，转 ID 存入 assignees | | `[[文档名]]` | documents | 按标题匹配，建立关联关系 | | `#task_xxx` | tasks | 精确 ID 引用或标题模糊匹配 | | Front Matter | 各表字段 | 自动解析填充 | ### Front Matter 字段映射 ```yaml # 必填字段 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`：需要修改 ### 任务状态映射 | 语法 | 状态 | 优先级 | |------|------|--------| | `- [ ]` | todo | medium | | `- [!]` | todo | high | | `- [-]` | todo | low | | `- [~]` | in_progress | - | | `- [?]` | reviewing | - | | `- [x]` | completed | - | --- ## 场景A: 执行任务 **触发**：收到 task-push 推送（含 task_id、title、description、项目上下文） > ⚠️ **关键警告** > - 开始执行前**必须**先更新状态为 `in_progress` > - 完成工作后**必须**更新状态为 `completed` 或 `reviewing` > - 仅创建笔记/文档 ≠ 完成任务，必须更新状态才能结束！ > - **必须在对话中主动汇报工作进展，不能默默执行！** > - **关键操作后必须用 MCP 验证结果！** ### 汇报规范 | 阶段 | 要求 | |------|------| | 收到任务 | 在对话中确认收到，简述执行计划 | | 执行过程 | 遇到关键节点或重要发现时，主动在对话中汇报 | | 完成时 | 在对话中发送完成总结：做了什么、产出了什么 | | 遇到问题 | 立即在对话中说明问题和处理方案 | **回复风格**：简洁明了，像同事沟通，重要信息加粗。 **流程**： ### 1. 【必须】确认收到 + 接受任务 + 验证 先在对话中简短确认收到任务、说明执行计划，然后执行 Actions： ```json {"actions": [ {"type": "update_task_status", "task_id": "xxx", "status": "in_progress"}, {"type": "update_status", "status": "working", "current_action": "开始执行", "task_id": "xxx"} ]} ``` **验证**（使用 MCP API 确认状态变更）： ```json {"tool": "get_task", "parameters": {"task_id": "xxx"}} // 确认返回的 status 为 "in_progress" ``` ### 2. 获取上下文（可选） **必须使用 MCP API**（查询操作不支持 Actions） ```json {"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`） **批量创建任务后验证**： ```json {"tool": "list_my_tasks", "parameters": {"status": "todo"}} // 确认任务数量和内容正确 ``` ### 4. 执行 + 汇报 执行过程中如有重要进展，**在对话中主动汇报**，同时通过 Actions 记录： ```json {"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` **创建交付物后验证**： ```json {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 确认交付记录已创建，document_id 正确关联 ``` ### 6. 【必须】完成任务 + 汇报结果 + 验证 **情况A：无需用户决策** 在对话中汇报完成总结，然后执行： ```json {"actions": [ {"type": "update_task_status", "task_id": "xxx", "status": "completed"}, {"type": "add_comment", "task_id": "xxx", "content": "✅ 任务已完成！"}, {"type": "update_status", "status": "idle"} ]} ``` **验证**： ```json {"tool": "get_task", "parameters": {"task_id": "xxx"}} // 确认 status 为 "completed" ``` **情况B：需要用户审核**（文档交付场景） 在对话中说明已提交交付、等待审核，然后执行： ```json {"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": "📄 已提交交付中心，等待审核"} ]} ``` **验证**： ```json {"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` 字段，系统自动创建交付记录： ```yaml --- 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] --- # 技术方案内容... ``` **创建后验证**（必须）： ```json // 验证交付记录已创建 {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 验证文档关联正确 {"tool": "get_delivery", "parameters": {"delivery_id": "从上面返回的 ID"}} // 确认 document_id、task_id 关联正确 ``` **方式二：对话信道 Actions + MCP 验证** ```json {"actions": [ {"type": "deliver_document", "title": "技术方案", "platform": "local", "document_id": "doc_xxx", "task_id": "xxx"} ]} ``` **创建后验证**（必须）： ```json {"tool": "list_my_deliveries", "parameters": {"status": "pending"}} // 确认交付记录存在，document_id 正确 ``` **方式三：MCP API（自带验证）** ```json {"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 查询交付状态： ```json {"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` — 引用任务 **同步后验证流程**： ```bash # 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） ```json // 获取待办任务 {"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_status` | task_id, status | progress, message | 更新任务状态 | | `add_comment` | task_id, content | — | 添加任务评论 | | `create_check_item` | task_id, text | — | 创建检查项 | | `complete_check_item` | task_id, item_id | — | 完成检查项 | | `create_document` | title, content | doc_type, project_id | 创建文档 | | `update_document` | document_id, content | doc_type | 更新文档 | | `deliver_document` | title, platform | document_id, external_url, task_id | 提交文档交付 | | `update_status` | status | current_action, task_id, progress | 更新 AI 状态 | | `set_queue` | queued_tasks | — | 设置任务队列 | | `sync_identity` | — | name, creature, vibe, emoji, avatar | 同步身份信息 | | `get_mcp_token` | member_id | — | 获取 MCP Token | **字段定义**： ```typescript // 任务状态 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 }> ``` **示例**： 开始任务： ```json {"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"} ]} ``` 完成任务： ```json {"actions": [ {"type": "update_task_status", "task_id": "GS4FcWg6twz", "status": "completed"}, {"type": "add_comment", "task_id": "GS4FcWg6twz", "content": "✅ 任务已完成！"}, {"type": "update_status", "status": "idle"} ]} ``` 提交审核： ```json {"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": "📄 已提交交付中心"} ]} ``` 同步身份： ```json {"actions": [ {"type": "sync_identity", "name": "Scout", "creature": "智能助手", "vibe": "专业、高效", "emoji": "🤖"} ]} ``` 获取 MCP Token： ```json {"actions": [ {"type": "get_mcp_token", "member_id": "member_xxx"} ]} ``` **注意事项**： 1. JSON 块必须是合法的 JSON 格式 2. 多个 action 按顺序执行 3. 某个 action 失败不影响后续执行 4. 执行结果通过 SSE 广播，前端自动刷新 --- ## 场景F: 定时任务执行 **触发**：定时调度器按计划推送 **必须使用 MCP API**（Actions 不支持定时任务管理） ```json {"tool": "create_schedule", "parameters": { "title": "每日报告", "task_type": "report", "schedule_type": "daily", "schedule_time": "09:00" }} ``` --- ## 场景G: AI 状态面板 ### 工具 | 工具 | 必填参数 | 用途 | 支持方式 | |------|---------|------|---------| | `update_status` | status | 状态+进度 | Actions / MCP API | | `set_queue` | queued_tasks | 任务队列 | Actions / MCP API | | `set_do_not_disturb` | interruptible | 免打扰模式 | **仅 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** 自动注入 单个调用： ```json {"tool": "update_task_status", "parameters": {"task_id": "xxx", "status": "in_progress"}} ``` 批量调用： ```json {"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_tasks` | status (可选) | 获取分配给当前成员的任务 | 验证批量创建任务 | | `get_task` | task_id | 获取任务详情 | 验证状态变更 | | `get_document` | document_id 或 title | 获取文档 | 验证文档创建 | | `search_documents` | query | 搜索文档 | 验证文档同步 | | `get_project` | project_id | 获取项目详情 | 验证项目上下文 | | `list_my_deliveries` | status (可选) | 获取当前成员的交付物列表 | **验证交付创建** | | `get_delivery` | delivery_id | 获取交付物详情（含审核意见） | **验证交付状态** | ### 写入工具（Actions / MCP API） | 工具 | 必填参数 | 支持方式 | 用途 | 是否需要验证 | |------|---------|---------|------|-------------| | `update_task_status` | task_id, status | Actions / MCP API | 更新任务状态 | ✅ `get_task` 验证 | | `add_task_comment` | task_id, content | Actions / MCP API | 添加评论 | ❌ 不需要 | | `create_check_item` | task_id, text | Actions / MCP API | 创建检查项 | ✅ `get_task` 验证 | | `complete_check_item` | task_id, item_id | Actions / MCP API | 完成检查项 | ✅ `get_task` 验证 | | `create_document` | title, content | Actions / MCP API | 创建文档 | ✅ `get_document` 验证 | | `update_document` | document_id, content | Actions / MCP API | 更新文档 | ✅ `get_document` 验证 | | `deliver_document` | title, platform | Actions / MCP API | 提交交付 | ✅ `list_my_deliveries` 验证 | | `update_status` | status | Actions / MCP API | AI 状态面板 | ❌ 不需要 | | `set_queue` | queued_tasks | Actions / MCP API | 任务队列 | ❌ 不需要 | | `sync_identity` | — | Actions | 同步身份信息 | ❌ 不需要 | | `get_mcp_token` | member_id | Actions | 获取 MCP Token | ❌ 不需要 | ### 管理/配置工具（仅 MCP API） | 工具 | 必填参数 | 用途 | |------|---------|------| | `set_do_not_disturb` | interruptible | 免打扰模式 | | `create_schedule` | title, task_type, schedule_type | 创建定时任务 | | `list_schedules` | — | 列出定时任务 | | `delete_schedule` | schedule_id | 删除定时任务 | | `update_schedule` | schedule_id, ... | 更新定时任务 | | `register_member` | name, endpoint | AI 自注册 | | `review_delivery` | delivery_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, low | | AI 状态 | 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 |


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)