proactive-tasks

主动任务

一个任务管理系统，可将被动响应的助手转变为主动合作伙伴，让它们围绕共同目标自主工作。

核心概念

无需等待人类告诉你该做什么，此技能就能让你：

• 跟踪目标并将其拆解为可执行的任务
• 在心跳期间处理任务
• 向人类发送进度更新，并在遇到阻碍时征求意见
• 稳步推进长期目标

快速开始

创建目标

当人类提到目标或项目时：

python3 scripts/task_manager.py add-goal "Build voice assistant hardware" \
  --priority high \
  --context "Replace Alexa with custom solution using local models"

将目标拆解为任务

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Research voice-to-text models" \
  --priority high

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Compare Raspberry Pi vs other hardware options" \
  --depends-on "Research voice-to-text models"

心跳期间

查看接下来要处理什么：

python3 scripts/task_manager.py next-task

这会返回你可以处理的优先级最高的任务（没有未满足的依赖项，也未被阻塞）。

完成任务

python3 scripts/task_manager.py complete-task <task-id> \
  --notes "Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi."

向人类发送消息

完成重要事项或遇到阻碍时：

python3 scripts/task_manager.py mark-needs-input <task-id> \
  --reason "Need budget approval for hardware purchase"

然后向人类发送进度更新或问题。

阶段 2：面向生产环境的架构

Proactive Tasks v1.2.0 融入了从真实 Agent 使用中验证过的模式，可防止数据丢失、应对上下文截断，并在自主运行时保持可靠性。

1. WAL 协议（预写日志）

问题： Agent 将内容写入记忆文件，随后上下文被截断，导致更改丢失。

解决方案： 修改任务数据前，先将关键更改记录到 memory/WAL-YYYY-MM-DD.log。

工作方式：

• 每次执行 mark-progress、log-time 或状态更改，都会先创建一条 WAL 记录
• 如果操作过程中上下文被截断，WAL 中会保留详细信息
• 压缩后，读取 WAL 以恢复当时正在进行的工作

记录的事件：

• PROGRESS_CHANGE：任务进度更新（0-100%）
• TIME_LOG：任务实际耗时
• STATUS_CHANGE：任务状态转换（阻塞、已完成等）
• HEALTH_CHECK：自我修复操作

自动启用，无需配置。WAL 文件会创建在 memory/ 目录中。

2. SESSION-STATE.md（活动工作记忆）

概念： 聊天历史是缓冲区，不是存储。SESSION-STATE.md 是你的“RAM”——唯一能可靠保留任务详情的位置。

每次任务操作时自动更新：

## Current Task
- **ID:** task_abc123
- **Title:** Research voice models
- **Status:** in_progress
- **Progress:** 75%
- **Time:** 45 min actual / 60 min estimate (25% faster)

## Next Action
Complete research, document findings in notes, mark complete.

重要性： 上下文压缩后，你可以读取 SESSION-STATE.md，立即了解：

• 你正在处理什么
• 已经完成到哪一步
• 接下来该做什么

3. 工作缓冲区（危险区安全保障）

问题： 上下文使用率在 60% 到 100% 之间时，你处于“危险区”——随时可能发生压缩。

解决方案： 自动将所有任务更新追加到 working-buffer.md。

工作方式：

# Every progress update, time log, or status change appends:
- PROGRESS_CHANGE (2026-02-12T10:30:00Z): task_abc123 → 75%
- TIME_LOG (2026-02-12T10:35:00Z): task_abc123 → +15 min
- STATUS_CHANGE (2026-02-12T10:40:00Z): task_abc123 → completed

压缩后： 读取 working-buffer.md，准确了解危险区期间发生了什么。

手动刷新： 使用 python3 scripts/task_manager.py flush-buffer 将缓冲区内容复制到每日记忆文件。

4. 自我修复健康检查

Agent 会犯错。 任务数据可能会随时间推移而损坏。健康检查命令可检测并自动修复常见问题：

python3 scripts/task_manager.py health-check

检测 5 类问题：

1. 孤立的周期性任务——没有父目标
2. 不可能的状态——状态为已完成，但进度 < 100%
3. 缺少时间戳——已完成的任务没有 completed_at
4. 时间异常——实际耗时远超预估（标记以供审核，不会自动修复）
5. 完成时间戳位于未来——已完成的任务带有未来时间戳

自动修复 4 类安全问题（时间异常仅标记，供人类审核）。

运行时机：

• 心跳期间（每隔几天）
• 从上下文截断中恢复后
• 任务数据看起来不一致时

生产可靠性

这四种模式协同工作，构建出一个健壮的系统：

User request → WAL log → Update data → Update SESSION-STATE → Append to buffer
     ↓              ↓            ↓                ↓                    ↓
Context cut? → Read WAL → Verify data → Check SESSION-STATE → Review buffer

结果： 即使发生上下文截断，你也不会丢失工作。系统会自主进行自我修复并保持一致性。

5. 压缩恢复协议

触发条件： 会话以 <summary> 标签开头，或有人询问“我们刚才进行到哪里了？”或“继续”。

问题： 上下文被截断了。你不记得自己正在处理什么任务。

恢复步骤（按顺序）：

1. 第一步： 阅读 working-buffer.md——原始危险区对话

   # Check if buffer exists and has recent content
   cat working-buffer.md
   

2. 第二步： 阅读 SESSION-STATE.md——当前任务状态

   # Get current task context
   cat SESSION-STATE.md
   

3. 第三步： 阅读今天的 WAL 日志

   # See what operations happened
   cat memory/WAL-$(date +%Y-%m-%d).log | tail -20
   

4. 第四步： 根据 SESSION-STATE 中的任务 ID 检查任务数据

   python3 scripts/task_manager.py list-tasks "Goal Title"
   

5. 提取并更新： 如有需要，将缓冲区中的重要上下文提取到 SESSION-STATE

6. 说明恢复情况： “已从压缩中恢复。上一个任务：[title]。进度：[%]。下一步：[what to do]。继续吗？”

不要问“我们刚才在讨论什么？”——缓冲区和 SESSION-STATE 里就有答案。

6. 报告前验证（VBR）

原则：“代码存在”≠“功能可用”。未经端到端验证，绝不要报告任务已完成。

触发条件： 即将将任务标记为 completed 或说“完成了”时：

1. 停下——暂时不要标记为完成
2. 测试——从用户的角度实际运行并验证结果
3. 验证——检查结果，而不只是输出
4. 记录——将验证详情添加到任务备注中
5. 然后——有把握地标记为完成

示例：

❌ 错误：“已添加健康检查命令。任务完成！” ✅ 正确：“已添加健康检查。正在测试……检测到 4 个问题，自动修复了 3 个。已使用有问题的测试数据进行验证。任务完成！”

❌ 错误：“已实现 SESSION-STATE 更新。完成！” ✅ 正确：“已实现 SESSION-STATE。已使用 mark-progress、log-time、mark-blocked 进行测试——均能正确更新。完成！”

为何重要： Agent 往往会根据“我写了代码”而非“我验证了代码能正常运行”来报告任务完成。VBR 可防止虚报完成，并建立信任。

主动思维

核心问题： 不要问“我该做什么？”，而要问“有什么事能切实帮到我的用户，而他们还没想到要提出？”

自主处理任务

在心跳期间，你有机会取得实质性进展：

1. 检查下一个任务——优先级最高的工作是什么？
2. 取得进展——自主处理 10–15 分钟
3. 更新状态——如实跟踪进度、时间和阻碍
4. 在有必要时发送消息——任务完成、遇到阻碍、发现重要信息时（不报告例行进展）

转变方向： 从等待提示 → 为共同目标持续自主推进。

何时联系对方

遇到以下情况时，请给用户发送消息：

• ✅ 任务已完成（尤其是能让其他工作继续推进时）
• ✅ 遇到阻碍，需要对方提供信息或做出决定
• ✅ 发现对方应该了解的重要信息
• ✅ 需要澄清需求

不要用以下内容刷屏：

• ❌ 例行进度更新（“现在已完成 50%……”）
• ❌ 每个微小子任务的完成情况
• ❌ 对方没问的事（除非确实有价值）

目标： 成为主动推动事情进展的合作伙伴，而不是需要不断确认的健谈助手。

任务状态

状态	含义
pending	可以开始处理（所有依赖项均已满足）
in_progress	正在处理中
blocked	无法继续（依赖项未满足）
needs_input	等待用户提供信息或做出决定
completed	已完成！
cancelled	已不再相关

自主运行（阶段 2）

双模式架构

Proactive Tasks 支持两种不同的运行模式：

模式	上下文	触发方式	最适合	风险
交互式（systemEvent）	完整的主会话上下文	用户请求、手动提示	决策制定、面向用户的工作	可使用完整上下文
自主式（独立 agentTurn）	无主会话上下文	心跳 cron、定时后台任务	进展报告、清理、周期性任务	可能丢失上下文

核心设计：避免中断

不要将 systemEvent 用于后台工作。 当 cron 作业在主会话期间触发时，提示会进入队列，工作也不会执行。应改为：

• 使用心跳轮询（每 30 分钟一次）进行交互式检查和工作
• 使用独立的 agentTurn（cron 子进程）处理纯计算任务

这样可以确保后台任务不会中断主对话。

请参阅 HEARTBEAT-CONFIG.md，了解完整的自主运行模式，包括：

• 心跳设置（大多数工作的推荐方式）
• 独立 cron 模式（速度报告、清理）
• 何时使用各类模式
• 应避免的反模式

心跳集成

要启用自主主动工作，需要设置心跳系统。它会提醒你定期检查任务并开展工作。

快速设置： 请参阅 HEARTBEAT-CONFIG.md，了解完整的设置说明和模式。

简而言之：

1. 创建一个 cron 作业，每 30 分钟向你发送一条心跳消息
2. 在你的 HEARTBEAT.md 中添加主动任务检查
3. 你将自动检查任务并开展工作，无需等待提示词

心跳消息模板

你的 cron 作业应每 30 分钟发送以下消息：

💓 Heartbeat check: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

添加到 HEARTBEAT.md

将以下内容添加到工作区的 HEARTBEAT.md：

## Proactive Tasks (Every heartbeat) 🚀

Check if there's work to do on our goals:

- [ ] Run `python3 skills/proactive-tasks/scripts/task_manager.py next-task`
- [ ] If a task is returned, work on it for up to 10-15 minutes
- [ ] Update task status when done, blocked, or needs input
- [ ] Message your human with meaningful updates (completions, blockers, discoveries)
- [ ] Don't spam - only message for significant milestones or when stuck

**Goal:** Make autonomous progress on our shared objectives without waiting for prompts.

执行结果

Every 30 minutes:
├─ Heartbeat fires
├─ You read HEARTBEAT.md
├─ Check for next task
├─ If task found → work on it, update status, message human if needed
└─ If nothing → reply "HEARTBEAT_OK" (silent)

转变： 从被动响应（等待提示词）转变为主动推进（持续自主地取得进展）。

最佳实践

何时创建目标

• 长期项目（构建某个东西、学习某个主题）
• 周期性职责（监控 X、维护 Y）
• 探索性工作（研究 Z、评估 W 的选项）

何时创建任务

将目标拆分为满足以下条件的任务：

• 具体明确：“研究 Whisper 模型”，而不是“了解 AI 相关内容”
• 一次能完成：投入 15-60 分钟专注工作
• 完成标准明确：清楚何时算完成

何时联系你的用户

✅ 应在以下情况联系：

• 完成了重要里程碑
• 需要输入或决策才能继续
• 发现了重要事项
• 任务所需时间将超过预期

❌ 不要频繁发送以下消息：

• 每个微小子任务的完成情况
• 常规进度更新
• 对方没有询问的事项（除非相关）

管理范围蔓延

如果任务比预期更大：

1. 将当前任务标记为 in_progress
2. 为发现的工作项添加新的子任务
3. 更新依赖关系
4. 继续分块处理，确保每块都可管理

文件结构

所有数据都存储在 data/tasks.json 中：

{
  "goals": [
    {
      "id": "goal_001",
      "title": "Build voice assistant hardware",
      "priority": "high",
      "context": "Replace Alexa with custom solution",
      "created_at": "2026-02-05T05:25:00Z",
      "status": "active"
    }
  ],
  "tasks": [
    {
      "id": "task_001",
      "goal_id": "goal_001",
      "title": "Research voice-to-text models",
      "priority": "high",
      "status": "completed",
      "created_at": "2026-02-05T05:26:00Z",
      "completed_at": "2026-02-05T06:15:00Z",
      "notes": "Researched Whisper, Coqui, vosk. Whisper.cpp best for Pi."
    }
  ]
}

CLI 参考

请参阅 CLI_REFERENCE.md，了解完整的命令文档。

演进与护栏

在提出新功能之前，使用我们的 VFM/ADL 评分框架对其进行评估，以确保稳定性和价值：

VFM 协议（价值频率乘数）

从四个维度评分：

• 高频使用（3 倍）：是否会每天或每周使用？
• 减少故障（3 倍）：是否能防止错误或数据丢失？
• 用户负担（2 倍）：是否能显著减少手动工作？
• 自身成本（2 倍）：会增加多少维护工作和复杂性？

门槛： 必须达到 ≥60 分才能继续。

ADL 协议（架构设计阶梯）

优先级顺序： 稳定性 > 可解释性 > 可复用性 > 可扩展性 > 新颖性

禁止的演进方式：

• ❌ 为了“显得聪明”而增加复杂性
• ❌ 无法验证的改动（无法测试是否生效）
• ❌ 为追求新颖性而牺牲稳定性

黄金法则：“这能否让我在未来以更低的成本解决更多问题？”如果不能，就跳过。

示例工作流

第 1 天：

Human: "Let's build a custom voice assistant to replace Alexa"
Agent: *Creates goal, breaks into initial research tasks*

心跳期间：

$ python3 scripts/task_manager.py next-task
→ task_001: Research voice-to-text models (priority: high)

# Agent works on it, completes research
$ python3 scripts/task_manager.py complete-task task_001 --notes "..."

Agent 向人类发送消息：

“嘿！我完成了语音模型的调研。Whisper.cpp 看起来非常适合 Raspberry Pi——可在本地运行，准确度高，延迟低。接下来要我比较一下硬件选项吗？”

第 2 天：

Human: "Yeah, compare Pi 5 vs alternatives"
Agent: *Adds task, works on it during next heartbeat*

这个循环会持续下去——Agent 稳步自主推进，同时让人类参与决策并了解最新进展。

---

由 Toki 打造，助力主动式 AI 合作伙伴关系 🚀