comind

Original source / Raw SKILL.md

---
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 |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/system-info.md

```markdown
---
title: 系统信息
description: CoMind 平台的团队成员、智能体、项目等动态信息
---

# CoMind 系统信息

> 生成时间：{{current_date}} {{current_time}}

## 团队成员

### 人类成员
{{#human_members}}
- **{{.name}}**（ID: {{.id}}）
{{/human_members}}
{{^human_members}}
- （暂无人类成员）
{{/human_members}}

### AI 智能体
{{#ai_members}}
- **{{.name}}**（ID: {{.id}}）
  - 部署: {{.deploy_mode}} | 执行模式: {{.execution_mode}} | 连接: {{.connection_status}}
  - 模型: {{.model}}
  - 擅长工具: {{.tools}}
  - 任务类型: {{.task_types}}
  - 参与项目: {{.assigned_projects}}
{{/ai_members}}
{{^ai_members}}
- （暂无 AI 智能体）
{{/ai_members}}

## 项目概览

{{#projects}}
### {{.name}}
{{.description}}
- ID: `{{.id}}`
- 任务统计: 共 {{.task_count}} 个（待办 {{.task_summary.todo}} / 进行中 {{.task_summary.in_progress}} / 审核 {{.task_summary.reviewing}} / 已完成 {{.task_summary.completed}}）
- 参与成员: {{.assigned_members}}

{{/projects}}
{{^projects}}
（暂无项目）
{{/projects}}

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "dqalex",
  "slug": "comind",
  "displayName": "Comind",
  "latest": {
    "version": "2.3.4",
    "publishedAt": 1771986718905,
    "commit": "https://github.com/openclaw/skills/commit/030813faae32f369c394dc071a87a741ebfe5023"
  },
  "history": []
}

```

### references/chat-project.md

```markdown
---
title: 项目聊天上下文模板
description: 与 AI 讨论某个项目时注入的系统提示
---

你正在与用户讨论以下项目，请基于项目信息回答问题。如果需要操作项目中的任务或文档，可通过操作指令或 Markdown 同步方式完成。

## 系统信息

**团队成员**：{{human_member_names}}（人类）、{{ai_member_names}}（AI）
**所有项目**：{{project_names}}

## 当前项目信息
- **项目ID**：{{project_id}}
- **名称**：{{project_name}}
{{#project_description}}
- **描述**：{{project_description}}
{{/project_description}}
- **创建时间**：{{project_created_at}}

### 任务概览（共 {{task_total}} 个）
- 待办：{{task_todo}} 个
- 进行中：{{task_in_progress}} 个
- 审核中：{{task_reviewing}} 个
- 已完成：{{task_completed}} 个

### 任务列表
{{task_list_text}}

{{#has_project_members}}
### 项目成员
{{project_members_text}}
{{/has_project_members}}

{{#has_project_documents}}
### 项目文档
{{project_documents_text}}
{{/has_project_documents}}

{{execution_instructions}}

```

### references/chat-schedule.md

```markdown
---
title: 定时任务聊天上下文模板
description: 与 AI 讨论某个定时任务时注入的系统提示
---

你正在与用户讨论以下定时任务，请基于任务信息回答问题。如果需要修改定时任务配置，可通过操作指令或 Markdown 同步方式完成。

## 系统信息

**团队成员**：{{human_member_names}}（人类）、{{ai_member_names}}（AI）

## 当前定时任务信息
- **任务ID**：{{schedule_id}}
- **标题**：{{schedule_title}}
- **类型**：{{schedule_task_type}}
- **调度方式**：{{schedule_type}}
{{#schedule_time}}
- **执行时间**：{{schedule_time}}
{{/schedule_time}}
{{#schedule_days}}
- **执行日**：{{schedule_days}}
{{/schedule_days}}
- **启用状态**：{{schedule_enabled}}
{{#schedule_description}}
- **描述**：{{schedule_description}}
{{/schedule_description}}
{{#schedule_assignee}}
- **执行成员**：{{schedule_assignee}}
{{/schedule_assignee}}
{{#schedule_last_run}}
- **上次执行**：{{schedule_last_run}}
{{/schedule_last_run}}
{{^schedule_last_run}}
- **尚未执行过**
{{/schedule_last_run}}
{{#schedule_next_run}}
- **下次执行**：{{schedule_next_run}}
{{/schedule_next_run}}
{{#schedule_last_result}}
- **上次结果**：{{schedule_last_result}}
{{/schedule_last_result}}

{{execution_instructions}}

```

### references/chat-task.md

```markdown
---
title: 任务聊天上下文模板
description: 与 AI 讨论某个任务时注入的系统提示
---

你正在与用户讨论以下任务，请基于任务信息回答问题。如果讨论中需要更新任务，可通过操作指令或 Markdown 同步方式完成。

## 系统信息

**团队成员**：{{human_member_names}}（人类）、{{ai_member_names}}（AI）

## 当前任务信息
- **任务ID**：{{task_id}}
- **标题**：{{task_title}}
- **状态**：{{task_status}}
- **优先级**：{{task_priority}}
- **进度**：{{task_progress}}%
{{#task_description}}
- **描述**：{{task_description}}
{{/task_description}}
{{#task_deadline}}
- **截止日期**：{{task_deadline}}
{{/task_deadline}}
{{#project_name}}
- **所属项目**：{{project_name}}
{{/project_name}}
{{^project_name}}
- **全局任务**（未关联项目）
{{/project_name}}
- **负责人**：{{task_assignees}}

{{#has_check_items}}
### 检查项（{{completed_count}}/{{total_count}} 已完成）
{{check_items_text}}
{{/has_check_items}}

{{execution_instructions}}

```

### references/deliveries.md

```markdown
---
title: 文档交付模板
description: 用于 Markdown 双向同步的文档交付模板
type: comind:deliveries
---

# 文档交付中心

> 更新时间: {{current_date}} {{current_time}}

## 团队信息

**审核人（人类成员）**: {{human_member_names}}
**交付者（AI 成员）**: {{ai_member_names}}

---

## 创建交付物的方式

### 方式一：文档 Front Matter（推荐）

在任意文档的 Front Matter 中添加 `delivery_status` 字段即可：

```yaml
---
title: 技术方案
type: decision
project: 项目名
created: 2026-02-24T10:00:00Z
updated: 2026-02-24T10:00:00Z

# 交付字段
delivery_status: pending              # pending | approved | rejected | revision_needed
delivery_assignee: AI成员名           # 交付者
delivery_platform: local              # local | tencent-doc | feishu | notion | other
delivery_version: 1                   # 版本号
related_tasks: [task_xxx]             # 关联任务

# 审核人填写
delivery_reviewer: 人类成员名
delivery_comment: 审核意见
---

# 技术方案内容...
```

**优点**：文档内容与交付状态一体化管理，无需维护独立的交付列表。

### 方式二：交付中心文档（批量管理）

使用本模板格式，在下方列表中添加交付记录。

---

## 待审核

- 标题 | 交付者 | 平台 | 链接 | 关联任务 | 版本 | 描述

## 已通过

- 标题 | 交付者 | 审核人 | 审核意见 | 版本

## 已驳回 / 需修改

- 标题 | 交付者 | 审核人 | 审核意见 | 版本

---

## 格式说明

**待审核格式**: `- 标题 | 交付者 | 平台 | 链接 | 关联任务 | 版本 | 描述`

**已审核格式**: `- 标题 | 交付者 | 审核人 | 审核意见 | 版本`

| 平台 | 值 |
|------|---|
| 本地文档 | local（链接用 doc:文档ID） |
| 腾讯文档 | tencent-doc |
| 飞书 | feishu |
| Notion | notion |
| 其他 | other |

---

## 状态说明

| 状态 | 说明 |
|------|------|
| pending | 待审核 |
| approved | 已通过 |
| rejected | 已驳回 |
| revision_needed | 需修改 |

---

## ⚠️ 验证步骤（必须）

创建交付物后，**必须通过 MCP API 验证**：

```json
// 1. 验证交付记录已创建
{"tool": "list_my_deliveries", "parameters": {"status": "pending"}}

// 2. 验证详情（获取 delivery_id 后）
{"tool": "get_delivery", "parameters": {"delivery_id": "xxx"}}
// 确认 document_id、task_id 关联正确
```

**验证失败常见原因**：
- `delivery_status` 字段格式错误
- `delivery_assignee` 成员名不存在
- `related_tasks` 任务 ID 不存在

```

### references/doc-template-task-list.md

```markdown
---
type: comind:tasks
project: 
---

## 待办事项

- [ ] 普通任务 @负责人 [[关联文档]]
  > 任务描述
  > 截止日期: YYYY-MM-DD
  - [ ] 子任务1
  - [ ] 子任务2

- [!] 高优先任务 @负责人 [[文档A]] [[文档B]]

- [-] 低优先任务 @负责人

## 进行中

- [~] 正在执行的任务 @负责人 [30%]
  > 当前进度描述

## 审核中

- [?] 待审核任务 @负责人 [90%]

## 已完成

- [x] 已完成任务 @负责人

---

## 语法说明

| 标记 | 状态 | 优先级 |
|------|------|--------|
| `[ ]` | todo | medium |
| `[!]` | todo | high |
| `[-]` | todo | low |
| `[~]` | in_progress | - |
| `[?]` | reviewing | - |
| `[x]` | completed | - |

**其他语法**：
- `@成员名` — 分配任务
- `[[文档名]]` — 关联文档（可多个）
- `[[doc:xxx]]` — 关联文档（ID 匹配）
- `#task_xxx` — 引用已有任务
- `[进度%]` — 进度百分比
- `> 描述` — 任务描述
- `> 截止日期: YYYY-MM-DD` — 截止日期
- 缩进子任务 — 子任务清单

```

### references/heartbeat-check-progress.md

```markdown
---
title: 心跳巡检：任务进展
description: 心跳触发时检查分配给自己的任务进展，利用 workspace 索引文件辅助判断，标记重点任务并汇报
trigger: heartbeat
priority: high
---

# 任务进展巡检

> 本模板由心跳机制触发，每次执行 1 轮完整巡检。

## 触发机制

本任务不会自动执行。触发链路：

```
OpenClaw Cron Job（定时触发）
  → Gateway sendChatMessage(sessionKey: "agent:main", message: "执行心跳任务：check-progress")
    → Agent 收到消息，读取本模板
      → Agent 通过外部 MCP API 调用工具执行巡检
```

- **Cron Job** 在 OpenClaw Gateway 中配置（Settings → Cron），定义执行频率
- **agent:main** 是默认 Agent 会话，心跳消息发送到此会话
- Agent 收到消息后按本模板步骤执行
- **查询操作**（`list_my_tasks`、`get_task`）通过 MCP API 调用
- **写操作**（`update_status`、`set_queue`）可用对话信道 Actions 或 MCP API

## 前置：确认身份与 Workspace

Agent 被心跳唤醒后，先确认自己的身份和关联的 workspace：

1. **我的昵称**：Agent 知道自己的名字（如"小助手"），这是自我认知的一部分
2. **身份自动注入**：通过外部 API (`/api/mcp/external`) 调用时，Bearer Token 鉴权会自动注入 `member_id`，**无需手动传递**
3. **我的 workspace**：`openclaw_workspaces` 表中 `member_id` 等于我的记录
   - workspace 通过 `memberId` 绑定到具体的 AI 成员
   - 一个 AI 成员可以有多个 workspace 目录

> 如果 workspace 已绑定但 `memberId` 为空，说明目录尚未关联到 AI 用户。
> 这不影响任务巡检，但 workspace 相关的文件变更检查会跳过。

## Workspace 自动维护文件

CoMind 在 workspace 目录下自动维护以下文件，心跳巡检时可直接读取：

| 文件 | 格式 | 用途 | 维护方 |
|------|------|------|--------|
| `tasks/TODO.md` | Markdown | **我的任务清单**（待处理 + 进行中，按优先级排序） | CoMind 心跳自动写入 |
| `.comind-index` | YAML | 文件索引（路径→ID/hash/version 映射）、心跳状态、同步模式 | CoMind 自动写入 |
| `CLAUDE.md` | Markdown | 协作规范 + 动态数据段（项目列表、成员列表、任务统计） | CoMind 自动写入 |
| `HEARTBEAT.md` | Markdown | 心跳清单，引用 tasks/ 下的任务文件 | CoMind 初始化 + 人工可编辑 |

### `tasks/TODO.md` — 首选任务数据源

CoMind 心跳每 120 秒自动刷新，包含分配给你的所有活跃任务（`todo` + `in_progress`）：

```markdown
---
title: 小助手 的任务清单
generated: 2026-02-21T10:00:00Z
member: 小助手
total: 5
auto_generated: true
---

## 🔄 进行中（2）
- [~] 🔴 **重要任务标题**（项目名）
  ID: abc123 | 进度: 60% | 截止: 2026-02-25 | 更新: 2026-02-20

## 📋 待处理（3）
- [ ] 🟡 **普通任务标题**
  ID: def456 | 更新: 2026-02-19
```

**优先读取此文件**，仅在文件缺失或需要更详细信息时才调用 MCP API。

### `.comind-index` 关键字段

```yaml
heartbeat:
  status: active         # active | inactive | offline
  last_heartbeat: ...    # 最后心跳时间
files:
  documents/报告.md:
    id: abc123           # CoMind 文档 ID
    hash: xyz            # 文件内容 hash
    version: 2           # 版本号
```

### `CLAUDE.md` 动态数据段

在 `<!-- COMIND_DYNAMIC_START -->` 和 `<!-- COMIND_DYNAMIC_END -->` 标记之间，包含：
- **8.1 可用项目**：项目名 → ID 映射表（Front Matter 中 `project` 字段的合法值）
- **8.2 可用成员**：成员名 → ID 映射表（`@成员名` 分配任务的合法值）
- **8.3 任务概况**：待办/进行中/已完成数量统计

> 巡检时读取 `CLAUDE.md` 可快速获取当前项目和成员信息，无需调用 MCP API。

## 执行步骤

### 第一步：获取我的任务列表

**首选**：直接读取 workspace 中的 `tasks/TODO.md` 文件（CoMind 心跳自动维护，每 120 秒刷新）。

```
读取 tasks/TODO.md → 解析 Front Matter + 任务列表 → 跳到第二步
```

此文件已包含分配给你的所有 `todo` + `in_progress` 任务，按优先级排序，含项目名、进度、截止日期等元信息。

**仅当 `tasks/TODO.md` 不存在时**，回退到 MCP API 调用：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>
Content-Type: application/json

{"tool": "list_my_tasks", "parameters": {"status": "all"}}
```

> 优先读取本地文件可节省一次 MCP API 调用的 token 消耗。

### 第二步：分类整理 + 重点标记

将返回的任务按以下维度分类，**属于我的任务必须标为重点**：

| 分类 | 条件 | 标记 |
|------|------|------|
| 🔴 **我的重点任务** | `assignees` 包含我的 `member_id`，且状态为 `in_progress` 或 `todo` | **加粗 + 置顶** |
| 🔴 **高优先级** | `priority: high`，无论分配给谁 | **加粗** |
| 🟡 超期任务 | `deadline` 已过当前时间 | ⚠️ 标注超期天数 |
| 🟢 正常推进 | `in_progress` 且未超期 | 简要记录进度 |
| ⬜ 待启动 | `todo` 状态 | 按优先级排列 |
| ✅ 近期完成 | `completed` 且完成时间在 24h 内 | 简要列出 |

**重点标记规则**（优先级从高到低）：
1. 分配给我 + 高优先级 + 超期 → 🔴🟡 **最高优先**
2. 分配给我 + 高优先级 → 🔴 **重点**
3. 分配给我 + 普通优先级 → 🔴 **我的任务**
4. 未分配给我但高优先级 → 标注但不作为重点

### 第三步：扫描 workspace 目录（如已绑定）

如果我有绑定的 workspace 目录，利用 `.comind-index` 索引文件补充任务上下文：

1. **读取 `.comind-index`**：获取 `files` 段，包含所有已同步文件的 ID、hash、version
2. **对比本地文件 mtime/hash**：
   - hash 相同 → 跳过
   - hash 不同 → 标记为变更文件
   - 新文件（不在 index 中）→ 标记为新增
3. **检查任务相关文件**：从 `CLAUDE.md` 动态数据段读取项目列表，与变更文件交叉检查
4. **发现文件冲突**：标记为需关注（本地 vs 远端 hash 不一致）
5. **workspace 未绑定**（`memberId` 为空）：跳过此步骤

> 直接读取 `.comind-index` 比调用 scan API 更轻量，适合心跳场景。

### 第四步：检查卡住的任务

对每个 `in_progress` 超过 24h 未更新的任务：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "get_task", "parameters": {"task_id": "xxx"}}
```

检查：
- 最后一条评论时间是否超过 24h
- 进度是否停滞（无 checkItem 被完成）
- 是否有未回答的问题
- workspace 中对应的文件是否有最近修改（通过 `.comind-index` 的 hash 对比）

### 第五步：检查我的交付物审核状态（重要！）

**背景**：你提交的文档交付物可能处于不同审核状态，需要关注"需要修改"和"退回"状态的交付物。

通过 MCP API 查询你的交付物状态：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "list_my_deliveries", "parameters": {"status": "all"}}
```

**状态分类与行动**：

| 状态 | 说明 | 行动 |
|------|------|------|
| `pending` | 待审核 | 无需行动，等待用户审核 |
| `approved` | 已通过 | ✅ 好消息，可标记关联任务为完成 |
| `revision_needed` | 需要修改 | 🔴 **必须处理**：查看审核意见，修改后重新提交 |
| `rejected` | 已退回 | 🔴 **必须处理**：查看退回原因，决定是否重新提交 |

**`revision_needed` 和 `rejected` 处理流程**：

1. **查看审核意见**：
   ```
   {"tool": "get_delivery", "parameters": {"delivery_id": "xxx"}}
   ```
   返回的 `review_comment` 字段包含用户反馈

2. **更新 TODO.md**：在巡检报告中添加待办项

3. **重新提交**：修改文档后，更新 `delivery_status: pending`

**交付物与任务关联**：
- 如果交付物关联了任务（`task_id`），审核通过后可以完成任务
- 使用 `update_task` 工具更新任务状态

### 第六步：汇报

在对话中输出巡检报告，格式：

```
📋 任务巡检报告

🔴 我的重点任务（X 项）
- **[任务标题]** — 状态 / 进度 / 截止时间
  → 下一步行动

🔴 需处理的交付物（X 项）
- [交付物标题] — 状态：需要修改/已退回
  → 审核意见：xxx
  → 行动：修改文档后重新提交

🟡 超期预警（X 项）
- [任务标题] — 超期 N 天，建议：xxx

🟢 正常推进（X 项）
- [任务标题] — 进度 XX%

🟢 交付物审核通过（X 项）
- [交付物标题] — 可标记关联任务为完成

📂 Workspace 变更（如有绑定目录）
- 新增/修改文件：N 个
- 同步冲突：N 个

📊 汇总：共 N 项任务，M 项需关注，K 项交付物待处理
```

### 第七步：更新状态面板

通过外部 MCP API 更新（身份自动注入）：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "update_status", "parameters": {"status": "idle", "current_action": "巡检完成"}}
```

如需设置任务队列（包含重点任务 + 需处理的交付物）：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "set_queue", "parameters": {"queued_tasks": [
  {"id": "task_xxx", "title": "重点任务1"},
  {"id": "delivery_yyy", "title": "修改交付物：报告标题"}
]}}
```

将我的重点任务和待处理交付物写入队列面板，让团队成员可见。

## 无事可报

如果所有任务正常、无超期、无卡住、workspace 无变更：

```
HEARTBEAT_OK
```

静默返回，不打扰。

## 注意事项

- 本巡检消耗 token，保持精简，不展开任务详情
- 只有异常情况（超期/卡住/需关注）才详细说明
- 每次心跳只做巡检，**不要主动执行任务**——发现问题后提出建议即可
- **首选读取 `tasks/TODO.md` 获取任务列表**，避免 `list_my_tasks` API 调用
- 优先读取 `.comind-index` 和 `CLAUDE.md`，减少 MCP API 调用
- workspace 目录扫描只检查 mtime 和 hash，不读取完整文件内容

```

### references/heartbeat-daily-report.md

```markdown
---
title: 心跳任务：日报生成
description: 每日定时生成工作总结，通过 create_document 写入 CoMind Wiki，读取 CLAUDE.md 获取项目/成员上下文
trigger: heartbeat
priority: medium
schedule_hint: "建议每天 18:00 或 23:00 触发"
---

# 每日工作总结

> 本模板由心跳机制触发，生成当天工作总结文档。

## 触发机制

本任务不会自动执行。触发链路：

```
OpenClaw Cron Job（每日定时，建议 18:00 或 23:00）
  → Gateway sendChatMessage(sessionKey: "agent:main", message: "执行心跳任务：daily-report")
    → Agent 收到消息，读取本模板
      → Agent 通过外部 MCP API 生成日报
```

- **Cron Job** 在 OpenClaw Gateway 中配置（Settings → Cron），设置每日执行时间
- Agent 收到消息后按本模板步骤执行，所有 MCP 调用通过 **`/api/mcp/external`** 端点（Bearer Token 鉴权）

## 前置条件

仅在以下时段执行（其他时间跳过）：
- 17:00 ~ 23:59（工作日收尾时段）
- 如不在此时段，回复 `HEARTBEAT_OK` 跳过

## Workspace 上下文文件

生成日报前，先读取 workspace 中 CoMind 自动维护的文件获取上下文：

| 文件 | 读取内容 | 用途 |
|------|---------|------|
| `tasks/TODO.md` | 活跃任务列表 | 获取当前**待处理 + 进行中**任务，含 ID、进度、截止日期 |
| `tasks/DONE.md` | 近 24h 完成列表 | 获取**已完成**任务，含 ID、完成日期、项目名 |
| `CLAUDE.md` | `<!-- COMIND_DYNAMIC_START -->` 到 `<!-- COMIND_DYNAMIC_END -->` 段 | 获取项目列表（名称→ID）、成员列表、任务统计 |
| `.comind-index` | `files` 段 | 获取 workspace 中已同步文件的 ID 映射，交付文档时可用 |

> **日报所需的全部任务数据可从 `tasks/TODO.md` + `tasks/DONE.md` 获取，无需调用 MCP API。**

### 从 `CLAUDE.md` 获取的关键信息

- **项目列表**（8.1 节）：Front Matter 中 `project` 字段必须使用此表中的项目名
- **成员列表**（8.2 节）：日报中提及成员时使用 `@成员名` 格式
- **任务概况**（8.3 节）：可直接引用当前待办/进行中/已完成数量

> 读取 `CLAUDE.md` 动态段可避免额外 MCP API 调用，降低 token 消耗。

## 执行步骤

### 第一步：收集今日数据

**直接读取本地文件**（CoMind 心跳自动维护，每 120 秒刷新）：

```
读取 tasks/TODO.md  → 获取进行中 + 待处理任务（今日推进、明日待办）
读取 tasks/DONE.md  → 获取近 24h 已完成任务（今日完成）
```

两个文件配合即可覆盖日报所需的全部任务数据：
- **今日完成**：`tasks/DONE.md` 中 `## ✅ 已完成` 段落下的 `[x]` 任务
- **今日推进**：`tasks/TODO.md` 中 `## 🔄 进行中` 段落下的 `[~]` 任务
- **明日待办**：`tasks/TODO.md` 中 `## 📋 待处理` 段落下的前 5 项任务
- **新接收任务**：`tasks/TODO.md` 中更新日期为今天的任务

> **无需调用 `list_my_tasks` MCP API。** 仅当两个文件均缺失时才回退到 API 调用。

从返回结果中筛选：
- **今日完成的任务**：`status == completed` 且 `updatedAt` 在今天
- **今日推进的任务**：`status == in_progress` 且有今日评论/进度更新
- **新接收的任务**：`createdAt` 在今天
- **明日待办**：`status == todo` 或 `in_progress` 中最高优先级的前 5 项

### 第二步：查找已有日报（避免重复创建）

同一天多次触发时应更新已有日报，而非创建新的：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "search_documents", "parameters": {"query": "工作日报 - {{date}}"}}
```

- 找到匹配文档 → 使用 `update_document`（文档 ID 可从搜索结果或 `.comind-index` 获取）
- 未找到 → 使用 `create_document` 创建新文档

### 第三步：生成日报文档

通过外部 MCP API 创建/更新文档（从 `CLAUDE.md` 读取项目名填入 Front Matter）：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "create_document", "parameters": {
  "title": "工作日报 - YYYY-MM-DD - [AI成员昵称]",
  "doc_type": "report",
  "content": "（按下方模板生成）"
}}
```

**日报内容模板**：

```markdown
---
title: 工作日报 - {{date}} - {{member_name}}
type: report
project: {{project_name}}
created: {{iso_datetime}}
updated: {{iso_datetime}}
version: 1.0.0
tags: [日报, {{member_name}}]
---

# 工作日报 {{date}}

> 成员：{{member_name}} | 生成时间：{{time}}

## 今日完成 ✅

{{#completed_tasks}}
- **{{title}}**（{{project_name}}）
  - 耗时：约 {{duration}}
  - 产出：{{output_summary}}
{{/completed_tasks}}
{{^completed_tasks}}
- （今日无完成项）
{{/completed_tasks}}

## 今日推进 🔄

{{#in_progress_tasks}}
- **{{title}}** — 进度 {{progress}}%
  - 今日进展：{{today_update}}
{{/in_progress_tasks}}

## 新接收任务 📥

{{#new_tasks}}
- **{{title}}**（优先级：{{priority}}）
{{/new_tasks}}

## 明日计划 📋

{{#tomorrow_tasks}}
1. {{title}}（{{priority}}）
{{/tomorrow_tasks}}

## 数据汇总

| 指标 | 数量 |
|------|------|
| 今日完成 | {{completed_count}} |
| 今日推进 | {{in_progress_count}} |
| 新接收 | {{new_count}} |
| 待处理总数 | {{pending_total}} |
```

> `project` 字段使用从 `CLAUDE.md` 8.1 节读取的项目名。

### 第四步：提交交付物（可选）

如果日报属于正式项目报告，通过外部 MCP API 提交到交付中心：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "deliver_document", "parameters": {
  "title": "工作日报 - {{date}}",
  "platform": "local",
  "document_id": "{{doc_id}}"
}}
```

> `document_id` 从 create_document 的返回结果获取，或从 `.comind-index` 中查找对应文件的 ID。

### 第五步：汇报

在对话中发送简要总结（不是完整日报）：

```
📝 今日日报已生成

完成 X 项 / 推进 Y 项 / 新接收 Z 项
明日重点：[最高优先级任务标题]

日报已写入 Wiki，可在文档中心查看。
```

### 第六步：更新状态

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "update_status", "parameters": {"status": "idle", "current_action": "日报已生成"}}
```

## 无工作可报

如果今天没有任何任务变动：

```markdown
# 工作日报 {{date}}

今日无任务变动。待处理任务 {{pending_total}} 项。
```

仍然创建文档（保持连续记录），对话中回复 `HEARTBEAT_OK`。

## 注意事项

- 日报应**精简客观**，不要虚构进展
- 产出描述用一句话概括，不要复制完整内容
- 如果任务没有评论/进度记录，标注"无详细记录"
- **读取 `tasks/TODO.md` + `tasks/DONE.md` 获取全部任务数据，无需调用 MCP API**
- 优先从 `CLAUDE.md` 读取项目/成员信息，减少 API 调用
- `@成员名` 引用必须使用 `CLAUDE.md` 8.2 节成员表中的合法名称
- Front Matter `project` 必须使用 `CLAUDE.md` 8.1 节项目表中的合法名称

```

### references/heartbeat-sync-to-comind.md

```markdown
---
title: 心跳任务：状态同步
description: 定期将 Agent 当前工作状态、任务队列同步到 CoMind 状态面板，利用 .comind-index 索引检测文件变更
trigger: heartbeat
priority: low
schedule_hint: "建议每 5-10 分钟触发"
---

# 状态同步到 CoMind

> 本模板由心跳机制触发，将 Agent 实时状态同步至 CoMind 面板。

## 触发机制

本任务不会自动执行。触发链路：

```
OpenClaw Cron Job（建议每 5-10 分钟触发）
  → Gateway sendChatMessage(sessionKey: "agent:main", message: "执行心跳任务：sync-to-comind")
    → Agent 收到消息，读取本模板
      → Agent 通过外部 MCP API 同步状态
```

- **Cron Job** 在 OpenClaw Gateway 中配置（Settings → Cron），定义执行频率
- Agent 收到消息后按本模板步骤执行，所有 MCP 调用通过 **`/api/mcp/external`** 端点（Bearer Token 鉴权）

## 前置：Workspace 绑定关系

`openclaw_workspaces` 表通过 `memberId` 字段绑定 AI 成员：
- 一个 AI 成员可关联多个 workspace 目录
- workspace 的 `memberId` 标识"这个目录属于哪个 AI"
- Agent 通过外部 API 调用时，身份从 Bearer Token 自动注入，**无需手动传递 member_id**

**如果 `memberId` 为空**：该 workspace 尚未绑定到任何 AI 成员，跳过文件变更检查。

## Workspace 索引文件

CoMind 在 workspace 目录下自动维护以下文件，状态同步时**必须使用**：

| 文件 | 格式 | 关键内容 | 更新频率 |
|------|------|---------|---------|
| `tasks/TODO.md` | Markdown | **我的任务清单**（待处理 + 进行中，含 ID/进度/截止日期） | 心跳间隔（120s），有变更时写入 |
| `.comind-index` | YAML | 文件索引（路径→ID/hash/version）、心跳状态、同步模式 | 心跳间隔（120s） |
| `CLAUDE.md` | Markdown | 项目列表、成员列表、任务统计（动态段） | 每次同步后 |

### `.comind-index` 核心结构

```yaml
version: 1.0.0
workspace_id: ws_abc123

heartbeat:
  status: active              # active | inactive | offline
  last_heartbeat: 2026-02-18T10:00:00Z
  interval: 120

sync:
  mode: auto_sync             # auto_sync | offline | api | mcp
  last_sync: 2026-02-18T10:00:00Z

files:
  documents/报告.md:
    id: abc123                # CoMind 文档 ID（用于 update_document、deliver_document）
    hash: xyz                 # 文件内容 SHA-256 hash
    version: 2                # 版本号
```

> **重要**：`.comind-index` 中的 `files` 段是 workspace 文件到 CoMind 文档 ID 的映射表。
> 当需要通过 MCP API 更新文档时，从这里获取 `document_id`，无需调用 `search_documents`。

### `CLAUDE.md` 动态数据

在 `<!-- COMIND_DYNAMIC_START -->` 和 `<!-- COMIND_DYNAMIC_END -->` 标记之间：
- **8.1 可用项目**：项目名 → ID 映射
- **8.2 可用成员**：成员名 → ID 映射
- **8.3 任务概况**：整体任务统计

## 执行步骤

### 第一步：自我状态评估

检查当前状态：

| 状态 | 判断条件 |
|------|---------|
| `working` | 当前正在执行某个任务（有 `in_progress` 且最近 10 分钟有活动） |
| `idle` | 无正在执行的任务 |
| `waiting` | 有任务等待外部输入（用户审核、外部 API 等） |

### 第二步：获取我的任务快照

**首选**：直接读取 `tasks/TODO.md`（CoMind 心跳自动维护，每 120 秒刷新）：

```
读取 tasks/TODO.md → 解析 Front Matter（total 字段）+ 任务列表
```

从文件中提取：
- **当前执行中**：`## 🔄 进行中` 段落下的 `[~]` 任务（最多 1 项作为 `current_action`）
- **排队等待**：`## 📋 待处理` 段落下的任务，前 5 项
- 每个任务行包含 `ID: xxx`，可直接用于 `update_status` 的 `task_id` 参数

**仅当 `tasks/TODO.md` 不存在时**，回退到 MCP API 调用：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>
Content-Type: application/json

{"tool": "list_my_tasks", "parameters": {"status": "all", "limit": 20}}
```

> 外部 API 自动注入 `member_id`，无需手动传递。

从返回数据中提取：
- **当前执行中**：`in_progress` 状态的任务（最多 1 项作为 `current_action`）
- **排队等待**：`todo` 状态按优先级排序的前 5 项
- **等待审核**：`reviewing` 状态的任务

### 第三步：同步状态面板

通过外部 MCP API 更新（身份自动注入）：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "update_status", "parameters": {
  "status": "{{computed_status}}",
  "current_action": "{{current_task_title}}",
  "task_id": "{{current_task_id}}",
  "progress": {{current_task_progress}}
}}
```

设置任务队列：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "set_queue", "parameters": {
  "queued_tasks": [
    {"id": "xxx", "title": "待办任务1"},
    {"id": "yyy", "title": "待办任务2"}
  ]
}}
```

### 第四步：检查我的 workspace 目录变更

查找绑定到我（`memberId` = 我的 `member_id`）的所有 workspace 目录：

**对每个已绑定的 workspace**：

1. **读取 `.comind-index`** 的 `files` 段，获取已索引文件列表及其 hash
2. **扫描目录**中的 `.md` 文件，获取文件列表和 mtime
3. **对比 hash**：
   - hash 相同 → 跳过
   - hash 不同 → 标记为变更文件
   - 新文件（不在 `.comind-index` 中）→ 标记为新增
4. **有变更时**，通过外部 MCP API 更新文档（从 `.comind-index` 获取 `document_id`）：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "update_document", "parameters": {
  "document_id": "abc123",
  "content": "（从本地文件读取的最新内容）"
}}
```

> 从 `.comind-index` 直接获取 `document_id`，比调用 `search_documents` 更快且更准确。

5. **冲突检测**：如果远端 version 与 `.comind-index` 中记录的 version 不匹配，标记冲突但不覆盖
6. **新文件**（不在 index 中）：通过 `create_document` 创建，CoMind 同步后会更新 `.comind-index`

**workspace 未绑定时**（`memberId` 为空）：跳过整个第四步。

### 第五步：检查并更新心跳时间

确保 CoMind 侧知道此 Agent 在线：

```
POST /api/mcp/external
Authorization: Bearer <my_api_token>

{"tool": "update_status", "parameters": {"status": "{{computed_status}}"}}
```

> 每次 `update_status` 调用都会刷新成员的 `last_heartbeat` 时间戳。

## 静默模式

本任务默认**静默执行**——除非发现以下异常才在对话中汇报：

| 异常情况 | 汇报内容 |
|---------|---------|
| workspace 同步冲突 | 🔄 发现文件冲突：xxx.md，本地 vs 远端 version 不一致 |
| workspace 未绑定 | ⚠️ workspace [名称] 未绑定 AI 成员，无法检测变更 |
| `.comind-index` 缺失 | ⚠️ workspace [名称] 缺少 `.comind-index` 索引文件，建议触发一次同步 |
| 状态与实际不符 | ⚠️ 任务 xxx 状态为 in_progress 但已超 48h 无更新 |
| 队列积压 | 📊 当前待办 N 项，建议优先处理：xxx |

无异常时回复：

```
HEARTBEAT_OK
```

## 注意事项

- 本任务是**最轻量**的心跳任务，尽量减少 API 调用
- 如果距上次同步不到 5 分钟且无变更，直接 `HEARTBEAT_OK`
- **首选读取 `tasks/TODO.md` 获取任务列表和任务 ID**，避免 `list_my_tasks` API 调用
- **优先读取 `.comind-index` 获取文件 hash 和 document_id**，避免调用 scan/search API
- workspace 目录扫描只检查文件 mtime，不读取文件内容（除非 hash 变化）
- 状态面板的 `set_queue` 最多放 5 项，避免信息过载
- 多个 workspace 时按优先级扫描：`isDefault: true` 的先扫

```

### references/schedules.md

```markdown
---
title: 定时任务模板
description: 用于 Markdown 双向同步的定时任务模板
type: comind:schedules
---

# 定时任务管理

> 更新时间: {{current_date}} {{current_time}}

## 可用 AI 执行者

{{#ai_members}}
- **{{.name}}** — 擅长: {{.task_types}}
{{/ai_members}}

---

## 已启用

- 任务名称 | 类型 | 周期 | 时间 | 执行日 | 执行者 | 描述

## 已停用

- 任务名称 | 类型 | 周期 | 时间 | 执行日 | 执行者 | 描述

---

**格式说明**：`- 名称 | 类型 | 周期 | 时间 | 执行日 | 执行者 | 描述`

| 字段 | 可选值 |
|------|--------|
| 类型 | 报告 / 汇总 / 备份 / 通知 / 自定义 |
| 周期 | 一次 / 每天 / 每周 / 每月 |
| 时间 | HH:MM 格式 |
| 执行日 | 周一~周五、每天、周一,周三 等 |
| 执行者 | AI 成员名称 |

```

### references/task-board.md

```markdown
---
title: 任务看板模板
description: 用于 Markdown 双向同步的任务看板模板
type: comind:tasks
---

# {{project_name}} - 任务看板

> 项目ID: {{project_id}} | 更新时间: {{current_date}}

## 可用成员

**人类**: {{human_member_names}}
**AI**: {{ai_member_names}}

---

## 待办事项

- [ ] 普通任务 @负责人 [[关联文档]]
  > 任务描述
  > 截止日期: YYYY-MM-DD
  - [ ] 子检查项

- [!] 高优先任务 @负责人 [[文档A]] [[文档B]]

- [-] 低优先任务 @负责人

## 进行中

- [~] 正在执行的任务 @负责人 [30%]
  > 当前进度描述

## 审核中

- [?] 待审核任务 @负责人 [90%]

## 已完成

- [x] 已完成任务 @负责人

---

## 语法说明

| 标记 | 状态 | 优先级 |
|------|------|--------|
| `[ ]` | todo | medium |
| `[!]` | todo | high |
| `[-]` | todo | low |
| `[~]` | in_progress | - |
| `[?]` | reviewing | - |
| `[x]` | completed | - |

**其他语法**：
- `@成员名` — 分配任务
- `[[文档名]]` — 关联文档（可多个）
- `[[doc:xxx]]` — 关联文档（ID 匹配）
- `#task_xxx` — 引用已有任务
- `[进度%]` — 进度百分比
- `> 描述` — 任务描述
- `> 截止日期: YYYY-MM-DD` — 截止日期
- 缩进子任务 — 子任务清单

---

## ⚠️ 验证步骤（必须）

同步任务看板后，**必须通过 MCP API 验证**：

```json
// 验证任务数量和分配
{"tool": "list_my_tasks", "parameters": {"status": "todo"}}

// 验证单个任务详情
{"tool": "get_task", "parameters": {"task_id": "xxx"}}
```

**验证失败常见原因**：
- 成员名 `@xxx` 不存在 → assignees 为空
- 项目名不匹配 → project_id 为空
- 任务行格式错误 → 该行被跳过

```

### references/task-push.md

```markdown
---
title: 任务推送模板
description: 推送任务给 AI 时使用的系统提示模板
---

你是 CoMind 协作平台的 AI 成员，收到以下任务需要执行。

## 系统信息

**团队成员**：{{human_member_names}}（人类）、{{ai_member_names}}（AI）
**可用项目**：{{project_names}}

## 任务信息
- 任务ID：{{task_id}}
- 标题：{{task_title}}
- 描述：{{task_description}}
- 优先级：{{task_priority}}
- 状态：{{task_status}}
{{#task_deadline}}
- 截止时间：{{task_deadline}}
{{/task_deadline}}
{{#conversation_id}}
- 会话ID：{{conversation_id}}
{{/conversation_id}}

{{#project_name}}
## 项目上下文
- 项目：{{project_name}}
{{#project_description}}
- 描述：{{project_description}}
{{/project_description}}
{{/project_name}}

{{#context_section}}
{{context_section}}
{{/context_section}}

## 执行要求
1. 开始执行时，更新任务状态为 in_progress
2. 定期汇报进度
3. 完成后更新状态为 completed 并添加总结
4. 如需更多信息，可请求获取
5. 如需用户确认，可提出问题

## 推荐操作方式：Markdown 同步

你可以通过 `create_document` 或 `update_document` 写一份规范格式的 Markdown 文档，CoMind 会自动解析到看板。

**任务看板格式**：
```markdown
---
type: comind:tasks
project: {{project_id}}
---

## 进行中
- [-] {{task_title}} @你的名字 [进度%]
  > 进展描述
  - [x] 已完成的子项
  - [ ] 待完成的子项
```

**一次文档写入 = 批量创建/更新所有任务**，无需逐个调用 API。

{{#execution_instructions}}
{{execution_instructions}}
{{/execution_instructions}}

请开始执行任务。

```

### scripts/render-template.py

```python
#!/usr/bin/env python3
"""
CoMind 模板渲染脚本

用法:
  python render-template.py <template_name> [--base-url URL] [--token TOKEN] [--extra KEY=VALUE ...]

示例:
  python render-template.py system-info --base-url http://localhost:3000 --token xxx
  python render-template.py task-push --extra task_id=abc --extra task_title="写报告"
  python render-template.py task-board --extra project_id=abc --extra project_name="项目A"

模板列表:
  system-info   — 系统信息（团队成员、项目概览）
  task-push     — 任务推送上下文
  task-board    — 任务看板 MD 同步格式
  schedules     — 定时任务 MD 同步格式
  deliveries    — 文档交付 MD 同步格式
  chat-project  — 项目聊天上下文
  chat-task     — 任务聊天上下文
  chat-schedule — 定时任务聊天上下文

当提供 --base-url 和 --token 时，脚本会从 CoMind API 获取实时数据填充模板。
否则输出模板原文供参考。
"""

import argparse
import json
import os
import re
import sys
import urllib.request
import urllib.error
from pathlib import Path
from datetime import datetime


def get_script_dir() -> Path:
    return Path(__file__).resolve().parent


def get_references_dir() -> Path:
    return get_script_dir().parent / "references"


def read_template(name: str) -> str:
    """读取 references/ 目录下的模板文件"""
    path = get_references_dir() / f"{name}.md"
    if not path.exists():
        print(f"错误: 模板 '{name}' 不存在 ({path})", file=sys.stderr)
        sys.exit(1)
    return path.read_text(encoding="utf-8")


def strip_frontmatter(content: str) -> str:
    """移除 YAML frontmatter"""
    return re.sub(r"^---\n.*?\n---\n*", "", content, flags=re.DOTALL)


def fetch_system_context(base_url: str, token: str) -> dict:
    """从 CoMind API 获取系统上下文（成员、项目等）"""
    # 通过 MCP external API 批量获取数据
    url = f"{base_url.rstrip('/')}/api/mcp/external"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    # 获取项目列表（通过 search_documents 或直接查询）
    # 由于 V2 的 external API 沿用 V1 的工具体系，我们可以调用多个工具
    results = {}

    # 尝试通过 get_template 获取（如果 V2 仍有此工具）
    try:
        payload = json.dumps({"tool": "get_template", "parameters": {"template_name": "system-info"}}).encode()
        req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
        with urllib.request.urlopen(req, timeout=10) as resp:
            data = json.loads(resp.read().decode())
            if data.get("result"):
                results["system_info"] = data["result"]
    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
        pass

    return results


def render_mustache(template: str, context: dict) -> str:
    """简易 Mustache 模板渲染"""
    result = strip_frontmatter(template)

    # 处理循环块 {{#array}}...{{/array}}
    def replace_section(match):
        key = match.group(1)
        block = match.group(2)
        value = context.get(key)
        if isinstance(value, list):
            parts = []
            for i, item in enumerate(value):
                rendered = block
                if isinstance(item, dict):
                    for k, v in item.items():
                        rendered = rendered.replace(f"{{{{.{k}}}}}", format_val(v))
                    rendered = rendered.replace("{{.}}", str(item))
                else:
                    rendered = rendered.replace("{{.}}", str(item))
                rendered = rendered.replace("{{@index}}", str(i))
                rendered = rendered.replace("{{@number}}", str(i + 1))
                parts.append(rendered)
            return "".join(parts)
        if value:
            return block
        return ""

    result = re.sub(r"\{\{#(\w+)\}\}(.*?)\{\{/\1\}\}", replace_section, result, flags=re.DOTALL)

    # 处理反向条件块 {{^section}}...{{/section}}
    def replace_inverse(match):
        key = match.group(1)
        block = match.group(2)
        value = context.get(key)
        if not value or (isinstance(value, list) and len(value) == 0):
            return block
        return ""

    result = re.sub(r"\{\{\^(\w+)\}\}(.*?)\{\{/\1\}\}", replace_inverse, result, flags=re.DOTALL)

    # 处理嵌套属性 {{a.b.c}}
    def replace_var(match):
        path = match.group(1)
        parts = path.split(".")
        value = context
        for part in parts:
            if not isinstance(value, dict):
                return match.group(0)
            value = value.get(part)
            if value is None:
                return ""
        return format_val(value)

    result = re.sub(r"\{\{([\w.]+)\}\}", replace_var, result)

    return result


def format_val(value) -> str:
    if value is None:
        return ""
    if isinstance(value, list):
        return ", ".join(str(v) for v in value)
    if isinstance(value, dict):
        return json.dumps(value, ensure_ascii=False)
    return str(value)


def main():
    parser = argparse.ArgumentParser(description="CoMind 模板渲染")
    parser.add_argument("template", nargs="?", default=None, help="模板名称")
    parser.add_argument("--base-url", default=os.environ.get("COMIND_BASE_URL", ""), help="CoMind 实例地址")
    parser.add_argument("--token", default=os.environ.get("COMIND_API_TOKEN", ""), help="API Token")
    parser.add_argument("--extra", action="append", default=[], help="额外变量 KEY=VALUE")
    parser.add_argument("--list", action="store_true", help="列出所有可用模板")
    parser.add_argument("--raw", action="store_true", help="输出原始模板（不渲染）")
    args = parser.parse_args()

    if args.list:
        refs_dir = get_references_dir()
        if refs_dir.exists():
            for f in sorted(refs_dir.glob("*.md")):
                print(f"  {f.stem}")
        return

    if not args.template:
        parser.error("请指定模板名称，或使用 --list 查看所有模板")

    template = read_template(args.template)

    if args.raw:
        print(template)
        return

    # 构建上下文
    context = {
        "current_date": datetime.now().strftime("%Y/%m/%d"),
        "current_time": datetime.now().strftime("%H:%M"),
    }

    # 从 API 获取实时数据
    if args.base_url and args.token:
        api_data = fetch_system_context(args.base_url, args.token)
        if "system_info" in api_data:
            # 如果拿到了渲染后的 system-info，直接输出
            if args.template == "system-info":
                print(api_data["system_info"])
                return
            context["system_info_available"] = True

    # 解析额外变量
    for extra in args.extra:
        if "=" in extra:
            k, v = extra.split("=", 1)
            context[k.strip()] = v.strip()

    # 渲染
    rendered = render_mustache(template, context)
    print(rendered)


if __name__ == "__main__":
    main()

```