Todo

Todo

Todo 是自然语言适配层。任务数据保存在 .agent-tasks/tasks/*.md，确定性读写全部交给本 Skill 自带的 Node CLI。

第一性原则：状态服务于用户的时间主权

Todo 的目标不是让任务机械地穿过一组状态，而是帮助用户从持续盯守、重复确认和不可预期的等待中释放出来，同时保留对成本、进度和启动时机的掌控。

执行任何状态变更前，先以终为始地确认：

1. 用户最终想获得的结果和工作状态是什么，而不只是当前说出的流程动作。
2. 当前状态能为用户减少什么负担，提供什么新的确定性。
3. 接下来是否存在昂贵的时间、注意力、额度或外部副作用；用户是否已经看见并接受。
4. 是否存在更便宜、更快、同样能推进最终目标的路径。
5. 当前动作是在推进用户的终局，还是只是在完成 Skill 自己的流程。

决策优先级固定为：

用户终局 → 时间与注意力 → 成本与风险透明 → 用户掌控点 → 最小流程 → 工具

流程、状态和工具都只是手段。一旦它们与用户希望“减少等待、释放注意力、把控整体进度”的核心诉求冲突，必须调整手段，不能以“已经严格执行流程”为完成依据。

硬约束

1. 禁止直接编辑任务文件、YAML、index.md 或归档目录。
2. 新增、修改、查询、移动、归档和正文更新都必须调用 CLI。
3. 未明确指定范围时始终使用全局 ~/.agent-tasks/，即使当前位于 Git 仓库。
4. 只有用户明确说“当前项目”或提供项目路径时才使用项目级目录。
5. 用户只要求记录、查看或修改任务时，不得执行任务本身。
6. list 只查询，不调研、不实现、不创建额外上下文文件。
7. index.md 是生成视图，tasks/*.md 是唯一数据源。

CLI 调用

Skill 内调用：

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" <command> [options]

如果宿主没有注入 CLAUDE_SKILL_DIR，使用当前 SKILL.md 所在目录的绝对路径。不要假设系统已经存在全局 todo 命令。

人工安装全局命令、依赖检查和 Web 启动方法见 references/setup-guide.md。

作用域

明确项目无法解析时报告错误，不静默写入全局。

意图映射

新增任务

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" add "<标题>" \
  --status idea \
  --json

添加当前项目任务时追加 --current-project。添加指定项目任务时追加 --project <git-root>。

创建后向用户返回：

• task_id
• 标题和状态
• 实际文件路径

查询任务

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" list
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" list --status canDurable
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" show <TSK-ID>
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" stats --format yaml

修改 YAML

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" set <TSK-ID> \
  --project-name "<项目名>" \
  --workspace "<路径>"

Reference 使用逗号分隔：

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" set <TSK-ID> \
  --references "references/设计.md,OBA-w8s3k7p2"

修改 Markdown 章节

Skill 更新上下文时使用标准输入，避免 shell 引号破坏正文：

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" section set <TSK-ID> "目标"
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" section append <TSK-ID> "关键决定"
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" section show <TSK-ID> "当前进度"

将正文通过标准输入传入。set 替换指定二级章节，append 保留旧内容后追加；两者不得影响其他章节。

修改状态

常规状态流：

idea → shaping → canDurable → doing → done
                            ↘ waitingHuman ↗

waitingHuman 是例外分支，不是每个阶段后的默认步骤。状态可以按真实进展前后调整，不强制线性迁移。

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" status <TSK-ID> shaping

进入 canDurable 必须记录判断依据：

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" status <TSK-ID> canDurable \
  --basis human-confirmed

合法依据：

• poc-passed
• human-confirmed
• ai-assessed

durable_basis 是任务的长程能力标记，不是临时状态附属字段。任务从 canDurable 进入 doing、waitingHuman 或 done 时必须保留；只有退回 idea / shaping 才自动移除。

Durable 准备与执行授权

状态服务于用户安排时间，不能由 Agent 把“准备好”擅自解释成“立刻开工”：

硬约束：

1. 进入 canDurable 后默认停止。 不得紧接着自动改为 doing，也不得开始实现、POC 或浏览器回归。
2. 执行必须单独获得授权。 用户提供账号、凭据、生产环境权限或技术方案，只解决执行条件，不等于授权立即启动。
3. 进入 canDurable 前给出执行预估。 在任务正文记录 ## Durable 执行预估，至少包含预计耗时范围、主要阶段、最大不确定性和可能需要人工处理的最终节点。
4. 状态反馈必须说清是否已启动。 例如：“已进入 canDurable，尚未执行；预计无人值守运行 8–12 小时。”

Durable 判断

canDurable 表示任务已经适合用户离线、夜间或不值守时持续执行。判断重点不是“文档写得是否足够多”，而是：

1. 最终目标和范围已经稳定。
2. 用户最终要回归的产物类型、入口和验收动作已经提前约定。
3. Agent 具备独立完成任务所需的环境、能力和权限。
4. 普通实现选择存在安全默认值，失败时存在重试或回退路径。
5. 当前没有已知的高风险授权、关键凭据或产品方向选择阻塞执行。

满足以上条件即可进入 canDurable：

1. 用户已认可最终验收契约：使用 human-confirmed。
2. 可执行 POC 已证明关键路径：使用 poc-passed。
3. 用户不在场，但最终产物、权限和回退路径都明确：使用 ai-assessed。
4. 只有缺失信息会明显改变最终结果或导致任务根本无法启动时，才保持 shaping。

POC 只用于消除真正影响长程执行的技术不确定性，不得把“邀请用户参与 POC”变成 Durable 的固定前置步骤。

POC 时间成本与确认门

POC 是 shaping 内的可选验证活动，不是进入 Durable 的默认动作。POC 可能消耗大量时间、调用额度并产生真实环境副作用，因此不得由 Agent 自行启动。

启动 POC 前必须先向用户展示一份简短确认信息：

1. 为什么需要：它要消除哪一个阻止进入 canDurable 的关键不确定性。
2. 预计耗时：给出区间，并标明主要耗时来自哪里。
3. 验证边界：本次会做什么、明确不做什么，以及停止条件。
4. 环境与副作用：是否登录真实账号、创建数据、发送消息、占用远端设备或修改外部状态。
5. 替代路径：说明跳过 POC 后能否用 human-confirmed 或 ai-assessed 进入 canDurable，以及可靠性差异。

随后必须得到用户对本次 POC 的明确确认，例如“开始 POC”或“按这个时间预算执行”。以下内容都不构成 POC 授权：

• 用户只说希望任务进入 Durable；
• 用户提供了凭据或生产账号；
• 用户同意最终目标或验收标准；
• Agent 判断 POC 更稳妥。

POC 执行规则：

1. 未确认时保持 shaping，只完善任务上下文，不执行 POC。
2. 选择能消除关键不确定性的最小闭环，先使用便宜、只读、可逆的证据。
3. 到达预估上限、验证范围扩大或出现新的外部副作用时，停止并重新给出预估，不能静默延长。
4. POC 通过后可以使用 poc-passed 进入 canDurable，但仍然停止；只有用户另行要求启动，才进入 doing。
5. 在任务正文使用 ## POC 计划 和 ## POC 结果 记录预算、停止条件与结论，避免后续 Agent 重复昂贵验证。

无人值守执行与人工等待阈值

硬约束

1. 中间文档不设人工门。 需求文档、研究报告、设计稿说明、决策矩阵、阶段总结、日志和其他辅助材料完成后，保存为 Reference 并继续执行。
2. 阶段结束不等于暂停。 只要下一阶段仍在既定目标、权限和验收契约内，保持 doing 并自动继续。
3. 普通问题不等待。 可逆实现选择、低风险分歧、依赖故障、测试失败和工具切换由 Agent 诊断、记录、重试或采用安全替代方案。
4. 文档类任务默认自动完成。 若用户明确要求的最终产物就是文档，完成结构、链接、事实与格式检查后直接 done，提供可点击文件；除非用户明确要求逐段审阅，否则不进入 waitingHuman。
5. 不得为了流程完整而制造人工检查点。 “请确认继续下一阶段”“请阅读长报告后验收”不属于有效阻塞。

只有以下情况可以进入 waitingHuman

1. 全部实现与自动验证已经完成，最终产物必须由人体验才能判断，而且已提供可直接回归的入口。
2. 继续执行需要用户授予新的高风险权限、提供缺失凭据，或选择会明显改变最终产品结果的方向。
3. 已耗尽安全的诊断、重试和替代路径，外部状态不变化就无法继续。

如果只是希望用户“有空看看”，不进入 waitingHuman；保持 doing 继续工作，或在自动完成后设为 done。

最终验收契约

Durable 任务在开始前应在正文记录 ## 最终验收，至少说明：

• 最终产物是什么；
• 用户从哪里进入；
• 用户需要执行的最短回归动作；
• Agent 会先完成哪些自动验证；
• 哪些情况才算失败。

按产物类型选择回归入口：

• 网页/应用：部署可点击 URL；无法部署时提供一条启动命令、固定本地 URL 和 3–5 步回归路径。
• E2E：保存真实点击步骤、自动化结果、录屏视频和视频报告；用户主要看视频回归，不要求重跑整套过程。
• Skill：提供可直接复制的触发提示词、预期行为和最小测试输入；用户通过实际调用 Skill 验收。
• CLI/API：提供可复制命令或请求、预期输出和机器可读测试结果。
• 文档/研究：提供可点击最终文件和自动检查结果，任务直接完成，不把阅读长文设为等待门。

完整模板和例子见 references/durable-acceptance.md。

执行记录

Durable 执行期间在任务正文持续维护 ## 执行记录，只记录可复用的工作证据，不暴露隐藏推理：

1. 使用了哪些 Skills/工具，以及它们承担什么工作。
2. 关键决策、假设和选择理由。
3. 遇到的问题、诊断证据、重试与解决办法。
4. 自动测试、构建、浏览器回归、录屏等验证结果。
5. 下次可以怎样减少调用、并行处理、复用缓存或提前发现失败。

记录的目的，是让后续 Agent 能恢复任务并审计效率；它不能成为要求用户阅读的中间验收物。

移动、归档与检查

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" move <TSK-ID> \
  --to-current-project

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" delete <TSK-ID> --yes
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" index
node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" doctor

delete 实际移动到 archive/，不永久删除。

Web 看板

当用户要求打开或启动 Todo 看板时：

node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" web

项目级看板显式追加作用域参数。Web 只监听 127.0.0.1，与 CLI 读取同一份 Markdown 数据。

渐进式资料

• 需要完整命令参数时读 references/commands.md。
• 需要任务 YAML、正文和目录格式时读 references/file-format.md。
• 需要安装、依赖或 Web 启动排查时读 references/setup-guide.md。
• 需要产品范围和验收条件时读 references/poc-spec.md。
• 需要判断人工等待阈值或设计最终回归入口时读 references/durable-acceptance.md。

错误处理

1. CLI 返回非零退出码时报告真实错误，不绕过 CLI 直接改文件。
2. Task ID 必须是 TSK-xxxxxxxx；标题不能代替 ID。
3. canDurable 缺少合法依据时不得强行写入。
4. doctor 报告非法 YAML、重复 ID、文件名不一致或 Reference 失效时，先修复数据再继续。
5. 旧格式只通过 migrate 尽力转换；迁移失败不阻塞新系统使用。
6. waitingHuman 不得用于中间文档验收或例行阶段确认；不满足人工等待阈值时改回 doing 或 done。