Heartbeat Skill

心跳任务完成技能 (Heartbeat Task Completion Skill)

自动化任务完成流程：标记完成 + TG 通知 + 归档

触发条件

当任务完成时调用此技能：

• Agent 手动完成任务
• 自动化任务执行结束
• 架构师审查完成
• 任何需要标记任务完成的场景

使用方式

方式 1：直接执行脚本

cd ~/.claude/skills/heartbeat-skill
./execute.sh --task-id <任务ID> --title "任务标题" --description "完成内容"

方式 2：通过环境变量

export TASK_ID="abc123"
export TASK_TITLE="完成任务标题"
export TASK_DESCRIPTION="完成内容描述"
export TASK_FILES="file1.ts,file2.ts"
cd ~/.claude/skills/heartbeat-skill && ./execute.sh

方式 3：从 AI 工作区调用

cd /Users/douba/Projects/XM
python3 ~/.claude/skills/heartbeat-skill/task_completion.py \
  --task-id abc123 \
  --title "完成任务" \
  --description "实现了新功能"

核心流程

1. 验证任务
   ├─ 通过 API 获取任务状态
   └─ 验证任务存在且未完成

2. 标记任务完成（通过 API）
   ├─ 调用 POST /api/todos/{task_id}/complete
   ├─ 设置 completed: true
   ├─ 设置 completed_at: 当前时间
   └─ 清除 processing 状态

3. 发送 TG 通知
   ├─ 格式化消息（标准格式）
   ├─ 调用 telegram_notifier
   └─ 记录发送结果

4. 归档已完成任务
   ├─ 运行 archive_completed_todos.sh
   └─ 移动已完成任务到 archives/

5. 报告结果
   └─ 输出完成状态和归档路径

重要: 所有任务状态变更都通过 API 完成，不直接修改 todos.json 文件。

输入参数

输出格式

✅ 任务完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
任务ID: abc123
任务标题: 实现新功能
完成时间: 2026-02-04 12:35:00

TG 通知: ✅ 已发送
归档: ✅ 已完成 (archives/completed_20260204_123500.json)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TG 通知格式

✅ 任务完成

📋 **任务标题**: 任务标题
🆔 **任务ID**: `abc123`

📝 **完成内容**:

实现了新功能的核心逻辑

• 添加了 API 端点
• 完成了单元测试

📂 **影响文件**:
  • `src/api/endpoint.ts`
  • `src/tests/test.ts`

⏰ **完成时间**: 2026-02-04 12:35:00

错误处理

与现有系统的关系

依赖

• scripts/todos_manager.py - 任务管理
• scripts/archive_completed_todos.sh - 归档脚本
• telegram_ops_bot/telegram_notifier.py - TG 通知
• scripts/tg_notifier.py - TG 通知封装（新增）

调用方

• Agent 手动完成任务时
• 自动化任务执行结束时
• 架构师审查完成时
• 任何需要标记任务完成的场景

替代方案

旧方式（分散且易冲突）：

# ❌ 禁止：直接修改 todos.json（可能导致并发冲突）
vi AI工作区/待办/todos.json

# 2. 手动运行归档脚本
./scripts/archive_completed_todos.sh

# 3. 手动发送 TG 通知（经常忘记！）
cd telegram_ops_bot
.venv312/bin/python -c "..."

新方式（API 驱动）：

# ✅ 推荐：一键完成所有步骤（通过 API）
~/.claude/skills/heartbeat-skill/execute.sh --task-id abc123 --title "完成任务"

# ✅ 或直接使用 API（极简）
curl -X POST "http://localhost:18920/api/todos/abc123/complete" \
  -H "Content-Type: application/json" \
  -d '{"summary": "完成了核心功能"}'

设计原则：所有任务状态变更都通过 API 完成，避免直接文件操作导致的并发冲突。

测试

# 测试 TG 通知（不修改 todos.json）
cd ~/.claude/skills/heartbeat-skill
./task_completion.py --test-notify

# 测试完整流程（使用虚拟任务）
./task_completion.py --test-completion

# 实际完成任务
./execute.sh --task-id abc123 --title "测试任务"

版本历史

• v1.0 (2026-02-04): 初始版本
  • 标记任务完成
  • TG 通知
  • 自动归档