Proactive Tasks

核心用法

Proactive Tasks 是一套面向 AI 代理的主动式任务管理系统，通过 CLI 工具与心跳机制实现「目标拆解 → 自主执行 → 状态同步 → 人机协同」的闭环。

典型工作流：
1. 用 add-goal 创建长期目标，附加优先级与背景上下文
2. 用 add-task 拆解为可 15-60 分钟完成的子任务，设置依赖关系
3. 心跳触发时执行 next-task 获取当前最高优先级可执行任务
4. 自主工作 10-15 分钟后，用 mark-progress、complete-task 或 mark-needs-input 更新状态
5. 关键节点（完成、阻塞、重大发现）主动推送消息给人类

生产级可靠性机制（v1.2.0）：

• WAL 协议：关键操作先写日志再改数据，防上下文截断丢数据
• SESSION-STATE.md：作为"RAM"实时保存当前任务状态，截断后秒级恢复
• Working Buffer：60%-100% 上下文危险区自动追加操作记录
• Health Check：自检修复 5 类常见数据异常（孤儿任务、状态冲突等）
• VBR 原则：标记完成前必须端到端验证，杜绝"代码写了=功能好了"的幻觉

显著优点

• 真正自主：心跳驱动无需人工催办，适合长周期项目持续推进
• 抗上下文截断：多层恢复机制确保会话重启后无缝衔接
• 防幻觉设计：VBR 强制验证、WAL 持久化、health-check 自修复三位一体
• 人机边界清晰：明确区分"自主执行"与"需要人类决策"的触发条件
• 轻量可嵌入：纯 CLI + JSON 存储，无外部依赖，易于集成到现有工作流

局限与风险

• 依赖心跳配置：若未正确设置 cron/heartbeat，退化为被动工具
• 无内置并发控制：多代理同时操作同一任务可能产生竞态（需外部协调）
• 时间估算偏乐观：actual_time 与 estimate 偏差需人工复核
• 消息策略需调教：默认"不 spam"原则下，新手代理可能过于保守或过于活跃

适合人群

• 需要 AI 长期自主跟进复杂项目的深度用户
• 对"上下文截断丢进度"有痛点的 Claude/Claude Code 用户
• 愿意配置心跳 cron 的技术型用户（非开箱即用）
• 追求"代理即伙伴"而非"代理即工具"的理念采纳者

常规风险

| 风险场景 | 缓解措施 |

|---------|---------|

| 上下文截断导致状态丢失 | WAL + SESSION-STATE + Buffer 三层恢复 |

| 代理误报任务完成 | VBR 强制端到端验证 |

| 数据文件损坏 | health-check 自动修复 4/5 类问题 |

| 心跳 spam 干扰人类 | HEARTBEAT.md 明确"HEARTBEAT_OK 静默"规则 |

| 目标漂移/范围蔓延 | 强制子任务拆解 + 依赖管理 |

核心功能

proactive-tasks 是一套面向 Claude 等 AI Agent 的生产级任务管理系统，核心目标是将 AI 从「等待指令」转变为「主动推进」。系统允许 Agent 独立管理目标与任务、在心跳周期内自主工作、并在上下文截断后可靠恢复。

显著优点

1. 双模式自主架构

• Interactive 模式：用户对话期间，Agent 可即时创建目标、拆解任务
• Autonomous 模式：通过心跳机制（每 30 分钟），Agent 自动检查待办任务并执行 10-15 分钟工作，完成后主动汇报进展或阻塞

2. 生产级可靠性设计（Phase 2）

• WAL 预写日志：关键操作先记日志再改数据，防上下文截断导致数据丢失
• SESSION-STATE.md：作为 Agent 的「工作内存」，保留当前任务状态，便于断点续传
• Working Buffer：在上下文使用率 60%-100% 的「危险区」自动追加操作记录
• Self-Healing 健康检查：自动检测并修复 5 类常见数据异常
• VBR 验证原则：任务完成前必须端到端验证，杜绝「代码写了=功能好了」的虚假完成

3. 零依赖本地运行
仅使用 Python 标准库（json、pathlib、datetime 等），无网络请求、无第三方包，供应链攻击面为零。

潜在局限

• T3 来源级别：由个人开发者（Toki/ImrKhn03）维护，长期维护可持续性需关注
• 单文件 JSON 存储：tasks.json 为单一数据源，虽有 WAL 保护但无自动备份机制
• Claude 生态专用：SESSION-STATE.md、HEARTBEAT.md 等机制深度绑定 Claude 的上下文管理模型
• 任务复杂度上限：适合 15-60 分钟粒度的原子任务，超大型项目需人工拆分策略

适合人群

• 希望 AI Agent 长期自主推进项目 的开发者/研究者
• 需要 异步协作模式 的场景（如夜间执行数据分析、定时生成报告）
• 对 上下文可靠性 有强要求的长时间运行任务

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 上下文截断 | 长会话中历史记录被压缩 | WAL + SESSION-STATE + Buffer 三层保护 |

| 数据损坏 | JSON 文件意外损坏 | 健康检查自动修复 + 建议手动备份 |

| 过度自主 | Agent 执行未授权操作 | HEARTBEAT.md 人工审核机制 + 阻塞时主动询问 |

| 来源可信度 | 个人项目维护风险 | 代码开源可审计，建议 fork 后自行维护 |

安全认证

CLS-Certify 扫描评级 S 级（95 分）：无危险函数、无网络请求、无第三方依赖、隐私合规通过。唯一警告为 T3 来源级别，属可接受风险。