todo

name	todo
description	上下文快照 + 批次处理：add 时自动保存会话上下文到 checkpoint 文件，resolve 时读取 checkpoint 无缝续接

上下文快照 + 批次调度。add 时自动冻结当前会话状态，resolve 时解冻上下文并执行任务。

核心理念

todo.md 是任务入口，cp-{timestamp}.md 是上下文快照。add 时存快照、写死路径；resolve 时读路径、还原上下文、执行任务。

存储位置

.agent-tasks/ 目录是 AI 智能体专用的待办存储，可被 Claude Code、Codex、Gemini CLI 等所有 agent 识别和读写。

语义映射（新增）

为减少口头指令歧义，以下自然语言应映射为固定行为：

1. 用户说“全局待办任务 / 全局 Todo / global todo”：
   • 强制等价于 --global
   • 固定操作文件：~/.agent-tasks/todo.md
   • 忽略当前是否位于 git 仓库
2. 用户说“项目待办任务 / 当前项目待办”：
   • 强制使用项目级路径 {git-root}/.agent-tasks/todo.md
   • 若当前不在 git 仓库，提示无法使用项目级并建议改用全局
3. 用户只说”待办任务 / todo”未指定范围：
   • 按路径解析规则处理（在 git 项目内时需询问用户选择项目级还是全局）

双层结构

层级	路径	用途
全局	~/.agent-tasks/	跨项目待办，所有环境共享
项目级	{git-root}/.agent-tasks/	项目相关待办，跟随项目走

路径解析规则

1. 检测当前目录是否在 git 仓库内（向上查找 .git/）
2. 若命中“全局待办任务”语义 → 强制使用全局 ~/.agent-tasks/
3. 若命中“项目待办任务”语义 → 强制使用 {git-root}/.agent-tasks/
4. 在 git 项目内（且未命中强制语义）→ 通过 AskUserQuestion 询问用户选择项目级还是全局（仅 add 和 resolve 时询问，list 默认项目级）
5. 不在 git 项目内 → 使用全局 ~/.agent-tasks/
6. --global 标志 → 强制使用全局路径，忽略项目

目录结构

.agent-tasks/
├── todo.md              # 任务入口
├── cp-20260429-143000.md  # 上下文快照（checkpoint）
├── cp-20260429-153000.md
└── todo-1.md            # 批次文件（resolve 时生成）

初始化

首次使用时，如果 .agent-tasks/ 目录不存在，自动创建并生成 todo.md 模板。

三个命令

list

仅列出当前待办，绝不创建 checkpoint、绝不执行任务、绝不触发任何调研或实现动作。

执行步骤：

1. 解析存储路径（项目级 or 全局，遵循“语义映射”优先）
2. 若 todo.md 不存在，仅初始化模板文件
3. 输出 Todo/Ideas 条目清单
4. 结束，不做任何额外操作

add <内容>

添加一条待办，同时自动生成 checkpoint 文件。

执行步骤：

1. 解析存储路径（项目级 or 全局，遵循”语义映射”优先）。若在 git 项目内且未命中强制语义，必须通过 AskUserQuestion 询问用户选择项目级还是全局
2. 确保 .agent-tasks/ 目录存在（不存在则创建）
3. 生成 checkpoint 文件 {storage}/cp-{YYYYMMDD-HHmmss}.md
4. 将当前会话上下文写入 checkpoint：
   • 当前任务（在做什么）
   • 进度（做到哪了）
   • 关键决策（为什么选 A 不选 B）
   • 下一步（具体操作）
   • 正在编辑的文件（工作集）
5. 在 {storage}/todo.md 添加条目，写死 checkpoint 路径：

- [ ] 完成用户认证模块 @context:cp-20260427-143000.md
  已写完 3 个 case，还差错误处理分支

• --idea → 写入 💡 Ideas 分区（不生成 checkpoint）
• --global → 强制写入全局 ~/.agent-tasks/
• 默认 → 写入 📋 Todo 分区（自动生成 checkpoint）

注意：checkpoint 是 add 那一刻的会话快照，不是 todo 条目本身。条目可以写续行补充细节。

resolve

提取条目到批次文件，使用 Multi Teams 并行处理：每个条目分配一个 teammate，各自带着 checkpoint 上下文独立执行。

执行步骤：

1. 解析存储路径（项目级 or 全局，遵循”语义映射”优先）。若在 git 项目内且未命中强制语义，通过 AskUserQuestion 询问用户选择项目级还是全局
2. 读取 {storage}/todo.md，展示所有待处理条目
3. 用户确认要处理的条目
4. 扫描已有 {storage}/todo-N.md，取最大 N+1
5. 将选中条目提取到 {storage}/todo-{N}.md（带 @context 路径）
6. 清空 {storage}/todo.md（保留模板结构），用户可继续新增条目
7. 创建团队：TeamCreate 创建 todo-resolve-{N} 团队
8. 创建任务：为每个条目调用 TaskCreate，描述中包含 checkpoint 完整路径和续行上下文
9. 并行派发 teammates：每个条目 spawn 一个 general-purpose 类型 teammate（带 team_name 和 name，如 todo-task-1）：
   • teammate 读取自己的 {storage}/cp-xxx.md 还原上下文
   • teammate 独立执行任务
   • 完成后 TaskUpdate 标记已完成，通过 SendMessage 向 team lead 汇报结果
10. 主会话监控：通过 TaskList 跟踪进度，接收 teammate 消息
11. 全部完成后：
    • 标记 {storage}/todo-{N}.md 中已完成条目
    • 清理对应的 {storage}/cp-xxx.md 文件
    • SendMessage shutdown 所有 teammates
    • TeamDelete 清理团队资源

teammate prompt 模板：

你是一个独立执行任务的 agent。请完成以下工作：

1. 读取 checkpoint 文件还原上下文：{storage}/cp-xxx.md
2. 根据 checkpoint 中的「下一步」和「正在编辑的文件」，继续完成任务
3. 任务完成后，通过 SendMessage 向 team lead 汇报：
   - 完成了什么
   - 修改了哪些文件
   - 是否有问题需要 team lead 处理
4. 通过 TaskUpdate 将任务标记为 completed

**Checkpoint 文件**: {storage 的完整绝对路径}/cp-xxx.md
**任务描述**: {todo 条目内容 + 续行上下文}

todo.md 文件格式

# TODO

最后更新: YYYY-MM-DD

## 📋 Todo
- [ ] 任务描述 @context:cp-20260427-143000.md
  续行补充上下文

## 💡 Ideas
- [ ] 想法描述

todo-N.md 批次文件格式

---
source: todo.md
created: "2026-04-27"
status: pending
---

## 📋 Todo
- [ ] 任务描述 @context:cp-20260427-143000.md
  续行补充上下文

## 💡 Ideas
- [ ] 想法描述

cp-xxx.md checkpoint 格式

---
type: checkpoint
created: "2026-04-27T14:30:00"
---

## 当前任务
一句话描述在做什么

## 进度
- 已完成的事项
- 正在进行的事项

## 关键决策
- 为什么选 A 不选 B

## 下一步
1. 具体操作
2. 具体操作

## 正在编辑的文件
- path/to/file1
- path/to/file2

resolve 流程图

.agent-tasks/
├── todo.md                    cp-xxx.md (多个)
│     │                              │
│     └──── resolve ─────────────────┤
│             │                      │
│             ▼                      ▼
│        todo-1.md  ←──── 提取 @context 路径
│             │
│             ▼
│        TeamCreate("todo-resolve-1")
│             │
│             ├─→ TaskCreate(条目1) ──→ teammate-1 读 cp-A → 执行 → 完成
│             ├─→ TaskCreate(条目2) ──→ teammate-2 读 cp-B → 执行 → 完成
│             └─→ TaskCreate(条目3) ──→ teammate-3 读 cp-C → 执行 → 完成
│             │
│             ▼
│        全部完成 → 清理 cp-xxx.md + shutdown teammates + TeamDelete

安全规则

1. resolve 前必须经用户确认
2. checkpoint 文件路径必须在 .agent-tasks/ 目录内
3. 清理 checkpoint 前确认任务已完成
4. 所有 teammates 完成后必须 shutdown 并 TeamDelete，避免资源残留
5. 单个 teammate 失败不影响其他 teammate，team lead 负责收集失败结果并报告
6. .agent-tasks/ 应加入 .gitignore，避免待办数据进入版本控制（除非团队有意共享）
7. 当用户只要求 list 或“添加待办”时，禁止执行待办内容本身；仅允许文件级增删改查
8. 未收到用户明确授权前，禁止调研系统、禁止创建守护进程、禁止落地自动化脚本

推荐触发词（新增）

建议优先使用下列短语，模型更容易稳定命中正确路径：

• 列表查询：全局待办、看下全局待办、列出全局待办任务
• 添加任务：加到全局待办：<内容>、全局待办新增：<内容>
• 完成批次：处理全局待办、resolve 全局待办
• 项目范围：当前项目待办、这个仓库的待办

其中“全局待办任务”是最高优先级别名，默认指向 ~/.agent-tasks/todo.md。