# Agent Todos

对标 Cursor `TodoWrite` 的任务清单扩展。复杂任务先拆分，完整进度显示在输入框上方，不做侧边栏。

## 行为

1. Agent 在多步骤任务中应先调用 `agent_todo_write` 拆分任务。
2. 成功后，editor **上方**出现完整 Todos 列表；footer 显示 `📋 completed/active`（分母不含 `cancelled`）。若同时有 TAPD Git 的 `Working...` 指示条，TASKS 会 restack 到其下方，保证 Working 始终在最上方。
3. 后续用 `merge: true` 按 `id` 更新状态；面板与 footer 即时刷新。
4. `in_progress` 必须对应当前实际工作；只有目标结果已达成并验证后才能标记 `completed`。若后续证据表明该步骤仍需处理，必须先重新打开为 `in_progress`，并将原当前步骤退回 `pending`，再继续操作。
5. 每次工具结果会向模型重申当前执行焦点；此外，每次 LLM 调用前都会临时注入当前 `in_progress` 与下一条 `pending`，避免长工具链中遗忘切换阶段。
6. 每轮焦点提醒只进入当次模型上下文，不写入会话，不使用时间或工具次数阈值，也不强制制造事后的状态转换。
7. 完成任务后可运行 `/todos` 手动隐藏面板；再次运行可手动显示。
8. 已隐藏时，后续新增 `pending` / `in_progress` todo 会自动重新打开面板。
9. 状态保存在 `agent_todo_write` 的 tool result details 中，跟随会话分支（resume / fork）。

## Tool

### `agent_todo_write`

工具名使用 `agent_todo_write`，与其它扩展常见的 `todo_write` 区分。

```ts
agent_todo_write({
  merge: boolean,
  todos: Array<{
    id: string;
    content: string;
    status: "pending" | "in_progress" | "completed" | "cancelled";
    subagentId?: string; // 可选：关联 spawn_subagent 返回的 subagentId
  }>;
})
```

| 规则 | 说明 |
| --- | --- |
| `merge: false` | 整表替换；`todos: []` 清空；恰好 1 条会被拒绝 |
| `merge: true` | 按 `id` 合并；可只传变更项 |
| `in_progress` | 合并后全表最多 1 条，且必须与当前正在执行的工作一致 |
| `completed` | 仅表示目标结果已达成并验证；后续发现仍需补做时先重新打开，不允许清单停在下一阶段继续补做上一阶段 |
| `subagentId` | 关联子 Agent：该子 Agent（后台任务或 live managed 子进程）成功完成时，pending / in_progress 条目自动置为 completed 并刷新面板；失败或取消不改状态。自动写回以 `agent-todos-subagent-sync` 会话条目持久化，参与 `/reload` 与历史重建 |

## UI

- Widget 在 editor 上方，采用与工具时间线一致的低噪声样式：
  - 标题行：`TASKS` + 完成进度与 active / pending / cancelled 计数
  - Unicode 进度条（`━` / `─`）
  - 状态：`○` pending · `●` in_progress · `✓` completed · `✗` cancelled
  - 完成和取消项降低亮度，不依赖删除线或 emoji 宽度
- 超过 16 条时底部显示 `… n more`
- `/todos`：手动隐藏或显示面板；隐藏不清除 todo 状态
- 隐藏后新增未完成 todo 时，面板自动显示
- Footer：`📋 2/5` 或全部完成时 `✅ 5/5`（面板隐藏后仍保留）
- print / json 模式跳过 UI，工具仍可用

状态标记使用单列终端字符，不依赖图片或 emoji；在 Windows Terminal、tmux、SSH 和 CJK 字体环境中更容易保持对齐。

日常查看不依赖命令；仅在需要手动隐藏或恢复面板时使用 `/todos`。

## 与其它扩展

| 扩展 | 关系 |
| --- | --- |
| 官方示例 `todo` | 工具名不同，可并存；优先用本扩展 |
| plan-mode / pi-codex-goal / TAPD | 正交，可同时安装 |

## Modules

| 文件 | 职责 |
| --- | --- |
| `index.ts` | 注册 tool、prompt、会话事件 |
| `model.ts` | 校验、merge、计数、格式化 |
| `store.ts` | 内存状态与分支重建 |
| `ui.ts` | widget / footer |
| `render.ts` | 工具行渲染 |
| `prompt.ts` | 工具名常量、基础规则与每轮 Todo focus reminder |