todo · diff
git:20260428.5b13843 to git:20260430.2c74f1b
115 added, 37 removed. Audit A to A.
---
name: todo
description: "上下文快照 + 批次处理：add 时自动保存会话上下文到 checkpoint 文件，resolve 时读取 checkpoint 无缝续接"
- argument-hint: '[add|resolve] [内容]'
+ argument-hint: '[list|add|resolve] [内容]'
---
<role>上下文快照 + 批次调度。add 时自动冻结当前会话状态，resolve 时解冻上下文并执行任务。</role>
## 核心理念
`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. 生成 checkpoint 文件 `cp-{YYYYMMDD-HHmmss}.md`（项目根目录）
- 2. 将当前会话上下文写入 checkpoint：
+ 1. 解析存储路径（项目级 or 全局，遵循”语义映射”优先）。若在 git 项目内且未命中强制语义，**必须通过 AskUserQuestion 询问用户**选择项目级还是全局
+ 2. 确保 `.agent-tasks/` 目录存在（不存在则创建）
+ 3. 生成 checkpoint 文件 `{storage}/cp-{YYYYMMDD-HHmmss}.md`
+ 4. 将当前会话上下文写入 checkpoint：
- 当前任务（在做什么）
- 进度（做到哪了）
- 关键决策（为什么选 A 不选 B）
- 下一步（具体操作）
- 正在编辑的文件（工作集）
- 3. 在 `todo.md` 添加条目，**写死 checkpoint 路径**：
+ 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. 读取 `todo.md`，展示所有待处理条目
- 2. 用户确认要处理的条目
- 3. 扫描已有 `todo-N.md`，取最大 N+1
- 4. 将选中条目提取到 `todo-{N}.md`（带 `@context` 路径）
- 5. 清空 `todo.md`（保留模板结构），用户可继续新增条目
- 6. **创建团队**：`TeamCreate` 创建 `todo-resolve-{N}` 团队
- 7. **创建任务**：为每个条目调用 `TaskCreate`，描述中包含 checkpoint 路径和续行上下文
- 8. **并行派发 teammates**：每个条目 spawn 一个 `general-purpose` 类型 teammate（带 `team_name` 和 `name`，如 `todo-task-1`）：
- - teammate 读取自己的 `cp-xxx.md` 还原上下文
+ 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 汇报结果
- 9. **主会话监控**：通过 `TaskList` 跟踪进度，接收 teammate 消息
- 10. **全部完成后**：
- - 标记 `todo-{N}.md` 中已完成条目
- - 清理对应的 `cp-xxx.md` 文件
+ 10. **主会话监控**：通过 `TaskList` 跟踪进度，接收 teammate 消息
+ 11. **全部完成后**：
+ - 标记 `{storage}/todo-{N}.md` 中已完成条目
+ - 清理对应的 `{storage}/cp-xxx.md` 文件
- `SendMessage` shutdown 所有 teammates
- `TeamDelete` 清理团队资源
**teammate prompt 模板**：
```
你是一个独立执行任务的 agent。请完成以下工作：
- 1. 读取 checkpoint 文件还原上下文：{cp-xxx.md 路径}
+ 1. 读取 checkpoint 文件还原上下文：{storage}/cp-xxx.md
2. 根据 checkpoint 中的「下一步」和「正在编辑的文件」，继续完成任务
3. 任务完成后，通过 SendMessage 向 team lead 汇报：
- 完成了什么
- 修改了哪些文件
- 是否有问题需要 team lead 处理
4. 通过 TaskUpdate 将任务标记为 completed
- **Checkpoint 文件**: {cp-xxx.md 完整路径}
+ **Checkpoint 文件**: {storage 的完整绝对路径}/cp-xxx.md
**任务描述**: {todo 条目内容 + 续行上下文}
```
## todo.md 文件格式
```markdown
# TODO
最后更新: YYYY-MM-DD
## 📋 Todo
- [ ] 任务描述 @context:cp-20260427-143000.md
续行补充上下文
## 💡 Ideas
- [ ] 想法描述
```
## todo-N.md 批次文件格式
```markdown
---
source: todo.md
created: "2026-04-27"
status: pending
---
## 📋 Todo
- [ ] 任务描述 @context:cp-20260427-143000.md
续行补充上下文
## 💡 Ideas
- [ ] 想法描述
```
## cp-xxx.md checkpoint 格式
```markdown
---
type: checkpoint
created: "2026-04-27T14:30:00"
---
## 当前任务
一句话描述在做什么
## 进度
- 已完成的事项
- 正在进行的事项
## 关键决策
- 为什么选 A 不选 B
## 下一步
1. 具体操作
2. 具体操作
## 正在编辑的文件
- path/to/file1
- path/to/file2
```
## resolve 流程图
```
- 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
+ .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 文件路径必须在项目目录内
+ 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`。