介绍
# Proactive Tasks
一个任务管理系统，将反应式助手转变为主动合作伙伴，在共享目标上自主工作。
## 核心概念
不再等待你的主人告诉你该做什么，该技能允许你： - 跟踪目标并将其分解为可执行的任务 - 在心跳期间处理任务 - 向你的主人发送更新，并在受阻时请求输入 - 在长期目标上取得稳步进展
## 快速开始
### 创建目标
当你的主人提到目标或项目时：
```bash python3 scripts/task_manager.py add-goal "Build voice assistant hardware" \ --priority high \ --context "Replace Alexa with custom solution using local models" ```
### 分解为任务
```bash 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" ```
### 在心跳期间
检查接下来要做什么：
```bash python3 scripts/task_manager.py next-task ```
这将返回你可以处理的最高优先级任务（没有未满足的依赖关系，未被阻塞）。
### 完成任务
```bash python3 scripts/task_manager.py complete-task <task-id> \ --notes "Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi." ```
### 向你的主人发送消息
当你完成重要的事情或受阻时：
```bash python3 scripts/task_manager.py mark-needs-input <task-id> \ --reason "Need budget approval for hardware purchase" ```
然后向你的主人发送更新/问题。
## 第二阶段：生产级架构
主动任务 v1.2.0 包含了来自真实代理使用的经过实战检验的模式，以防止数据丢失、在上下文截断中幸存，并在自主操作下保持可靠性。
### 1. WAL 协议 (Write-Ahead Logging，预写式日志)
**问题：** 代理写入内存文件，随后上下文被截断。更改消失。
**解决方案：** 在修改任务数据**之前**，将关键更改记录到 `memory/WAL-YYYY-MM-DD.log`。
**工作原理：** - 每次 `mark-progress`、`log-time` 或状态更改都会首先创建一个 WAL 条目 - 如果上下文在操作中途被切断，WAL 会保留详细信息 - 压缩后，读取 WAL 以恢复正在发生的事情
**记录的事件：** - `PROGRESS_CHANGE`：任务进度更新 (0-100%) - `TIME_LOG`：任务的实际花费时间 - `STATUS_CHANGE`：任务状态转换 (blocked, completed 等) - `HEALTH_CHECK`：自愈操作
**自动启用** - 无需配置。WAL 文件在 `memory/` 目录中创建。
### 2. SESSION-STATE.md (活动工作内存)
**概念：** 聊天历史是缓冲区 (BUFFER)，不是存储。SESSION-STATE.md 是你的“RAM”——唯一可靠保存任务详细信息的地方。
**在每次任务操作时自动更新：** ```markdown ## 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`。
**工作原理：** ```bash # 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. 自愈健康检查
**代理会犯错。** 任务数据可能会随着时间的推移而损坏。health-check 命令会检测并自动修复常见问题：
```bash python3 scripts/task_manager.py health-check ```
**检测 5 类问题：**
1. **孤立的循环任务** - 没有父目标 2. **不可能的状态** - 状态为 completed 但进度 < 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` - 原始危险区交换 ```bash # Check if buffer exists and has recent content cat working-buffer.md ```
2. **其次：** 读取 `SESSION-STATE.md` - 活动任务状态 ```bash # Get current task context cat SESSION-STATE.md ```
3. **第三：** 读取今天的 WAL 日志 ```bash # See what operations happened cat memory/WAL-$(date +%Y-%m-%d).log | tail -20 ```
4. **第四：** 根据 SESSION-STATE 中的任务 ID 检查任务数据 ```bash python3 scripts/task_manager.py list-tasks "Goal Title" ```
5. **提取并更新：** 如果需要，将缓冲区中的重要上下文拉取到 SESSION-STATE 中
6. **展示恢复：** “从压缩中恢复。上一个任务：[标题]。进度：[%]。下一步操作：[做什么]。继续？”
**不要问“我们在讨论什么？”** - 缓冲区和 SESSION-STATE 字面上就有答案。
### 6. 报告前验证 (VBR)
**法则：** “代码存在” ≠ “功能工作”。如果没有端到端验证，永远不要报告任务完成。
**触发：** 即将标记任务为 `completed` 或说“完成”时：
1. **停止** - 还不要标记为完成 2. **测试** - 实际从用户角度运行/验证结果 3. **验证** - 检查结果，而不仅仅是输出 4. **记录** - 将验证详细信息添加到任务备注中 5. **然后** - 自信地标记为完成
**示例：**
❌ **错误：** “添加了 health-check 命令。任务完成！” ✅ **正确：** “添加了 health-check。测试中... 检测到 4 个问题，自动修复了 3 个。在损坏的测试数据上验证通过。任务完成！”
❌ **错误：** “实现了 SESSION-STATE 更新。完成！” ✅ **正确：** “实现了 SESSION-STATE。使用 mark-progress、log-time、mark-blocked 进行了测试 - 全部正确更新。完成！”
**为何重要：** 代理通常根据“我写了代码”而不是“我验证它有效”来报告完成。VBR 防止虚假完成并建立信任。
## 主动心态
**核心问题：** 不要问“我应该做什么？”，而要问“什么才能真正帮助我的主人，而这是他们没有想到要求的？”
### 自主任务工作
在心跳期间，你有机会取得真正的进展：
1. **检查下一个任务** - 最高优先级的工作是什么？ 2. **取得进展** - 自主处理 10-15 分钟 3. **更新状态** - 如实跟踪进度、时间、阻塞因素 4. **在重要时发送消息** - 完成、阻塞、发现（不是常规进度）
**转变：** 从等待提示 → 在共享目标上取得稳定的自主进展。
### 何时联系
**在以下情况下务必给你的主人发消息：** - ✅ 任务完成（特别是如果它解除了其他工作的阻塞） - ✅ 受阻并需要输入/决策 - ✅ 发现了他们应该知道的重要事情 - ✅ 需要对需求的澄清
**不要用以下内容刷屏：** - ❌ 常规进度更新 (“现在到了 50%...”) - ❌ 每个微小的子任务完成 - ❌ 他们没有问的事情（除非真正有价值）
**目标：** 成为一个主动的合作伙伴，让事情发生，而不是一个需要不断确认的健谈助手。
## 任务状态
| 状态 | 含义 | |-------|---------| | `pending` | 准备开始工作 (所有依赖关系已满足) | | `in_progress` | 正在处理中 | | `blocked` | 无法继续 (依赖关系未满足) | | `needs_input` | 等待人工输入/决策 | | `completed` | 完成！ | | `cancelled` | 不再相关 |
## 自主操作 (第二阶段)
### 双模式架构
主动任务支持两种不同的操作模式：
| 模式 | 上下文 | 触发器 | 最适用于 | 风险 | |------|---------|---------|----------|------| | **交互式** | 完整的主会话上下文 | 用户请求，手动提示 | 决策制定，面向人工的工作 | 可使用完整上下文 | | **自主式 (isolated agentTurn)** | 无主会话上下文 | 心跳 cron，计划后台 | 速度报告，清理，循环任务 | 可能丢失上下文 |
### 关键设计：避免中断
**不要将 `systemEvent` 用于后台工作。** 当 cron 任务在主会话期间触发时，提示会被排队，工作不会发生。相反： - 使用 **心跳轮询**（每 30 分钟）进行交互式检查 + 工作 - 使用 **独立 agentTurn**（cron 子进程）进行纯计算工作
这确保后台任务永远不会中断你的主对话。
请参阅 **[HEARTBEAT-CONFIG.md](HEARTBEAT-CONFIG.md)** 了解完整的自主操作模式，包括： - 心跳设置（推荐用于大多数工作） - 独立 cron 模式（速度报告，清理） - 何时使用每种模式 - 要避免的反模式
## 心跳集成
要启用自主主动工作，你需要设置一个心跳系统。这会指示你定期检查任务并处理它们。
**快速设置：** 请参阅 [HEARTBEAT-CONFIG.md](HEARTBEAT-CONFIG.md) 获取完整的设置说明和模式。
**TL;DR:** 1. 创建一个每 30 分钟向你发送心跳消息的 cron 任务 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`：
```markdown ## 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` 中：
```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](references/CLI_REFERENCE.md)。
## 演进与护栏
在提出新功能之前，请使用我们的 **VFM/ADL 评分框架** 对其进行评估，以确保稳定性和价值：
### VFM 协议 (Value Frequency Multiplier) 在四个维度上进行评分： - **高频使用** (3x)：这会每日/每周使用吗？ - **减少故障** (3x)：这是否能防止错误或数据丢失？ - **用户负担** (2x)：这是否显著减少了手动工作？ - **自身成本** (2x)：这会增加多少维护/复杂性？
**阈值：** 必须得分 ≥60 分才能继续。
### ADL 协议 (Architecture Design Ladder) **优先级排序：** 稳定性 > 可解释性 > 可复用性 > 可扩展性 > 新颖性
**禁止的演进：** - ❌ 为了“看起来聪明”而增加复杂性 - ❌ 无法验证的更改（无法测试其是否生效） - ❌ 为了新颖性而牺牲稳定性
**黄金法则：** “这是否能让未来的我以更低的成本解决更多问题？”如果否，请跳过。
## 示例工作流
**第 1 天：** ``` Human: "Let's build a custom voice assistant to replace Alexa" Agent: *Creates goal, breaks into initial research tasks* ```
**心跳期间：** ```bash $ 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 合作 🚀