comind
# 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 |
标签
skill
ai
