| name | proactive-tasks |
| description | 主动的目标和任务管理系统。在管理目标、将项目分解为任务、跟踪进度或自主实现目标时使用。使代理能够在心跳期间主动工作，向人员发送更新消息，并在不等待提示的情况下取得进展。 |
主动任务
任务管理系统可将被动的助手转变为积极主动的合作伙伴，为共同的目标自主工作。
核心理念
这项技能可以让您：
- 跟踪目标并将其分解为可操作的任务
- 在心跳期间完成任务
- 向您的人员发送更新消息，并在被阻止时请求输入
- 在长期目标上稳步前进
快速入门
创造目标
当您的人员提到目标或项目时：
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 包括来自真实代理使用情况的经过实战测试的模式，以防止数据丢失、避免上下文截断并在自主操作下保持可靠性。
1. WAL 协议（预写日志记录）
问题： 代理写入内存文件，然后上下文被截断。变化消失。
解决方案： 在修改任务数据之前，将关键更改记录到 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。
它是如何工作的：
- 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 以准确了解危险区域期间发生的情况。
手动刷新：python3scripts/task_manager.pyflush-buffer将缓冲区内容复制到日常内存文件中。
4.自我修复健康检查
代理会犯错误。 任务数据可能会随着时间的推移而损坏。 health-check 命令检测并自动修复常见问题：
python3 scripts/task_manager.py health-check
检测 5 类问题：
- 孤立的重复任务 - 无父目标
- 不可能的状态 - 状态=已完成但进度 < 100%
- 缺少时间戳 - 已完成的任务没有“completed_at”
- 时间异常 - 实际时间>>估计（用于审查的标记，不会自动修复）
- 未来日期的完成 - 具有未来时间戳的已完成任务
自动修复 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. 压缩恢复协议
Trigger: Session starts with <summary> tag, or you're asked "where were we?"或“继续”。
问题： 上下文被截断。您不记得自己正在执行什么任务。
恢复步骤（按顺序）：
-
首先： 阅读 working-buffer.md - 原始危险区域交换
cat working-buffer.md
-
第二： 读取 SESSION-STATE.md - 活动任务状态
cat SESSION-STATE.md
-
第三： 阅读今天的 WAL 日志
cat memory/WAL-$(date +%Y-%m-%d).log | tail -20
-
第四： 从SESSION-STATE中检查任务ID的任务数据
python3 scripts/task_manager.py list-tasks "Goal Title"
-
提取和更新： 如果需要，将重要上下文从缓冲区拉入会话状态
-
当前恢复：“从压缩中恢复。上一个任务：[标题]。进度：[%]。下一步操作：[做什么]。继续？”
不要问“我们在讨论什么？” - 缓冲区和会话状态确实有答案。
6. 报告前验证 (VBR)
法则： “代码存在”≠“功能作品”。未经端到端验证，切勿报告任务完成情况。
**触发器：**即将标记任务“已完成”或说“完成”：
- 停止 - 尚未标记为完成
- 测试 - 从用户角度实际运行/验证结果
- 验证 - 检查结果，而不仅仅是输出
- 文档 - 将验证详细信息添加到任务注释中
- 那么 - 自信地标记完成
示例：
❌ 错误：“添加了健康检查命令。任务完成！”
✅ 右：“添加了健康检查。测试...检测到 4 个问题，自动修复 3。验证了损坏的测试数据。任务完成！”
❌ 错误：“实施了会话状态更新。完成！”
✅ 右：“实现了会话状态。使用标记进度、日志时间、标记阻止进行测试 - 所有更新均正确。完成！”
为什么这很重要： 代理通常根据“我编写了代码”而不是“我验证了它的工作原理”来报告完成情况。 VBR 可防止错误完成并建立信任。
积极主动的心态
核心问题： 不要问“我应该做什么？”问“什么可以真正帮助我的人类，而他们却没有想过要要求？”
自主任务工作
在心跳期间，你有机会取得真正的进步：
- 检查下一个任务 - 最高优先级的工作是什么？
- 取得进展 - 自主完成 10-15 分钟
- 更新状态 - 诚实地跟踪进度、时间、阻碍因素
- 重要时发出消息 - 完成、阻碍、发现（非常规进展）
**转变：**从等待提示→在共同目标上稳步自主进步。
何时伸出援手
请在以下情况下向您的人员发送消息：
- ✅ 任务已完成（特别是如果它解除了其他工作的阻碍）
- ✅ 被阻止并需要输入/决定
- ✅ 发现了他们应该知道的重要事情
- ✅ 需要澄清要求
请勿发送垃圾邮件：
- ❌ 日常进度更新（“现在为 50%...”）
- ❌每一个微小的子任务完成
- ❌ 他们没有询问的事情（除非真正有价值）
目标： 成为一个积极主动的合作伙伴，让事情发生，而不是一个需要不断验证的健谈助手。
任务状态
| 状态 | 意义 |
|---|
pending | 准备工作（满足所有依赖关系） |
进行中 | 目前正在努力 |
被阻止 | 无法继续（不满足依赖关系） |
需要输入 | 等待人工输入/决定 |
已完成 | 完毕！ |
已取消 | 不再相关 |
自主操作（第二阶段）
两种模式架构
主动任务支持两种不同的操作模式：
| 模式 | 背景 | 触发 | 最适合 | 风险 |
|---|
| 交互式（系统事件） | 完整的主会议背景 | 用户请求，手动提示 | 决策、人性化工作 | 提供完整的上下文 |
| 自主（隔离代理转向） | 没有主会话上下文 | 心跳cron，定时后台 | 速度报告、清理、重复任务 | 可能会失去上下文 |
关键设计：避免中断
**不要使用“systemEvent”进行后台工作。**当 cron 作业在主会话期间触发时，提示会排队并且不会发生工作。相反：
- 使用心跳轮询（每 30 分钟）进行交互式检查 + 工作
- 使用隔离的agentTurn（cron子进程）进行纯计算工作
这可确保后台任务永远不会中断您的主要对话。
请参阅 HEARTBEAT-CONFIG.md 了解完整的自主操作模式，包括：
- 心跳设置（推荐用于大多数工作）
- Isolated cron patterns (velocity reports, cleanup)
- 何时使用每种模式
- 要避免的反模式
心跳集成
为了实现自主主动工作，需要搭建心跳系统。这告诉您定期检查任务并执行它们。
快速设置： 请参阅 HEARTBEAT-CONFIG.md 了解完整的设置说明和模式。
TL；博士：
- 创建一个 cron 作业，每 30 分钟向您发送一条心跳消息
- 将主动任务检查添加到“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 模型”而不是“研究人工智能的东西”
- 一次即可完成：15-60 分钟的专注工作
- 明确的完成标准：你知道什么时候完成
何时给你的人发消息
✅ 在以下时间发送消息：
- 您完成了一个有意义的里程碑
- 您需要输入/决定才能继续
- 你发现了一些重要的事情
- 任务将花费比预期更长的时间
❌ 请勿发送垃圾邮件：
- 每一个微小的子任务完成
- 日常进度更新
- 他们没有询问的事情（除非相关）
管理范围蔓延
If a task turns out to be bigger than expected:
- 将当前任务标记为“in_progress”
2.为您发现的作品添加新的子任务
3.更新依赖
- 继续处理可管理的块
文件结构
所有数据都存储在“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"
CLI 参考
请参阅 CLI_REFERENCE.md 以获取完整的命令文档。
演变与护栏
在提出新功能之前，请使用我们的VFM/ADL 评分框架对其进行评估，以确保稳定性和价值：
VFM 协议（值频率倍增器）
四个维度的得分：
- 高频 (3x)：这会每天/每周使用吗？
- 减少故障 (3x)：这是否可以防止错误或数据丢失？
- 用户负担 (2x)：这是否会显着减少手动工作？
- 自我成本 (2x)：这会增加多少维护/复杂性？
阈值： 必须得分 ≥60 分才能继续。
ADL协议（架构设计阶梯）
**优先顺序：**稳定性 > 可解释性 > 可重用性 > 可扩展性 > 新颖性
禁忌进化：
- ❌ Adding complexity to "look smart"
- ❌ 无法验证的更改（无法测试是否有效）
- ❌为了新颖性而牺牲稳定性
黄金法则：“这是否能让未来的我以更少的成本解决更多的问题？”如果不是，请跳过它。
工作流程示例
第一天：
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)
$ python3 scripts/task_manager.py complete-task task_001 --notes "..."
代理向人类发送消息：
“嘿！我完成了语音模型的研究。Whisper.cpp 看起来非常适合 Raspberry Pi - 在本地运行、精度高、延迟低。接下来要我比较硬件选项吗？”
第二天：
Human: "Yeah, compare Pi 5 vs alternatives"
Agent: *Adds task, works on it during next heartbeat*
这个循环继续下去——代理在保持稳定的自主进展的同时让人类参与决策和更新。
由 Toki 打造，旨在实现积极的 AI 合作🚀
