# TAPD Extension

TAPD 需求与缺陷工作流扩展。提供待办列表、会话关联、需求分析、技术设计、协作评审、Bug 定位，以及设计/开发子需求的创建与同步。

## Commands

| 命令 | 说明 |
| --- | --- |
| `/tapd` | 在居中 Overlay 中打开 TAPD 待办列表，支持需求与 Bug 视图 |
| `/tapd analyze [补充要求]` | 生成 `understanding.md` |
| `/tapd design [补充要求]` | 调研后通过选项式提问确认关键决策，再生成 `design.md` 和结构化开发子需求拆分 |
| `/tapd collaboration [补充要求]` | 生成供产品、后端和前端 Leader 评审的 `collaboration.md` |
| `/tapd preview [understanding\|design\|collaboration]` | 在浏览器批阅当前需求的本地 Markdown 文档并把意见交给 Agent；不带参数时先选择文档，且不需要 TAPD Token |
| `/tapd review [--base origin/dev] [补充要求]` | 选择“仅未提交”或“当前分支全部修改”后，启动只读子代理审核实现与过度设计，并将分级报告返回主 Agent |
| `/tapd sub-task` | 根据 `design.md` 创建或同步设计、开发子需求 |
| `/tapd bug [补充要求]` | 根据当前会话已有缺陷描述启动定位；定位提示显示在对话中，不二次拉取 TAPD；结果只输出原因、带具体代码的因果链与置信度，不写长篇分析报告 |
| `/tapd bug-reject` | 单页 Overlay 拒绝当前 Bug：评价原因多行预览，Enter 进 Overlay 用 Pi Editor 编辑（Enter 确认 / Ctrl+Enter 换行）；解决方法/开发人员同样 Enter 打开 Overlay；FAQ 默认否 |
| `/tapd git-status` | 直接执行 TAPD Git 工作流，并用对话区工具风格卡片显示关联事项、分支、upstream 与工作区状态 |
| `/tapd branch [--base origin/dev]` | 直接获取 TAPD keyword；本地关联分支已存在时切换，否则从指定基础分支创建；结果显示为对话区工具风格卡片 |
| `/tapd commit [--no-push]` | 直接使用 TAPD keyword 生成提交信息，提交并默认推送；结果显示为对话区工具风格卡片 |
| `/tapd mr [--draft] [--target dev] [--no-delete-source-branch]` | 直接创建或更新 GitLab MR 并回写 TAPD；结果显示为对话区工具风格卡片 |

长耗时 TAPD 操作（待办列表冷启动、`Ctrl+Shift+T`、子需求同步、`bug-reject` 拉取与提交、创建关联会话取详情，以及 `git-status`/`branch`/`commit`/`mr`）会在 editor 上方、TASKS 之上显示 `Working...`（含 `Esc 取消`）。Overlay/confirm/select 期间暂时隐藏 Working，Esc 交给对话框。Git 工作流另在对话区保留一张 `running`→终态单卡；Esc 中止会尽量结束 `git`/hooks 进程树并将卡片标为 `cancelled`。`analyze`/`design`/`collaboration`/`review`/`bug` 交给 Agent streaming，不重复挂 Working。

工作流命令支持附加自然语言和 `@文件`：

```text
/tapd design @docs/api.md 重点考虑旧接口兼容
/tapd bug 重点看登录页 @src/login.ts
```

`/tapd bug-reject` 在 Bug 会话中直接打开单页 Overlay（不经 Agent）：状态固定为「已拒绝」；评价原因默认取最近一次定位报告的 `## 原因`，主表多行预览，Enter 打开 Overlay 并嵌入 Pi 官方 `Editor`（Enter 确认、Ctrl+Enter 换行）；解决方法、开发人员同样按 Enter 打开 Overlay 选择/输入；是否需要写 FAQ 默认「否」（←→ 切换）；确认后处理人设为该缺陷的测试人员（`te`），开发人员默认为当前用户；评价原因同时写入「缺陷原因说明」字段，并以流转备注（`bug_remark`）追加评论。确认后按字段中文 label 解析并 `POST /bugs` 回写。

## Shortcuts

- `Ctrl+Shift+T`：打开 TAPD 待办。

`/tapd` 的待办、类型筛选、关联会话、select 和 confirm 页面统一显示在当前 TUI 上方的居中 Overlay 中，与 Subagent 共用单层 Header/viewport/Footer shell（宽度 `92%`、最大高度 `88%`）。`/tapd preview` 和三个文档生成后的自动预览优先打开 localhost 浏览器：默认显示渲染后的 Markdown（含 Mermaid 图），点击内容块可批注对应源行，也可切换源码精确批注；提交后自动发送 follow-up，仅要求 Agent 修改目标文档，取消/关闭不操作。浏览器启动失败时回退原只读 Markdown Overlay（宽度 `90%`、最大高度 `84%`），保留 Mermaid、LaTeX、键盘滚动和 regular wheel。主表在 `<80`、`80–119`、`>=120` 列下依次显示紧凑、普通、完整字段；长待办、会话和路径历史使用围绕当前选择的 viewport，并显示 `start-end/total`。`↑/↓`、`PageUp/PageDown`、`Home/End` 导航；主表的操作提示（导航 · Enter 关联 · `/` 搜索 · Tab 切换 · `i` 迭代 · `t` 类型 · `o` 打开 · Esc/Ctrl+C 退出，窄屏自动缩减）统一显示在 Overlay 最底部 Footer 一行，不重复出现在面板内；会话 picker、select/confirm 对话框的操作提示同样显示在底部 Footer；`i` 键在“当前迭代/所有迭代”待办范围间切换。需求/Bug 和工作项类型使用 `[REQ]`、`[BUG]`、`[DEV]` 等稳定文本标签；主表「设计」列仅出现在需求视图（Bug 视图不显示）；`●` 表示当前项目或关联会话目录中已存在对应的 `design.md`，`○` 表示尚未设计。打开待办时会先扫描会话目录再计算该状态，之后每次重新打开主表时也会重新计算。新建关联会话时，“会话名称”默认使用 TAPD 标题，也可以在创建前编辑；创建后该名称会显示在 `/resume` 会话列表中。选中一个项目路径时，新会话直接在该目录中创建；多选路径时会追加一步工作目录选择；未选路径或所选路径等于当前目录时，行为与原先一致。切到未信任目录时 Pi 会弹出项目信任确认。跨目录创建的会话会写入 `model-manager-new-conversation` 标记 entry，让 model-manager 按新对话规则应用默认模型（普通 `/resume` 不受影响）。

## Story workflow

```text
/tapd analyze → understanding.md → 自动预览
→ /tapd design → 选项确认（如有关键待确认决策）→ design.md → 自动预览
→ /tapd collaboration → collaboration.md → 自动预览
→ /tapd sub-task
```

- 三个文档命令在 Agent 完成且目标文件确实新增或更新后自动打开对应浏览器批阅；提交逐行批注后自动交给 Agent 修订该文件，取消/关闭不触发下一轮。生成失败或文件未变化时不会误开旧内容。之后可随时执行 `/tapd preview` 选择文档，或通过参数直接打开。
- `/tapd design` 会先读取需求理解、检查相关代码，再识别影响范围、架构、兼容性、接口契约或验收标准的关键待确认决策。存在待确认项时，Agent 使用通用的 `ask_user_choice` 一次提交全部当前已知问题；用户用 Tab / Shift+Tab 切换并集中提交答案。每题提供 2～5 个候选方案，可标记一个推荐项，最后固定提供“其他（自定义输入）”；用户取消时停止流程且不创建或覆盖 `design.md`。没有关键待确认项时直接生成设计。
- `/tapd analyze`、`/tapd design`、`/tapd collaboration` 启动时会写入 `chat-mode-ensure-ask-for-docs` 标记，由 chat-mode 在本轮 Agent 启动前切到 Ask（可写项目 `.pi/**`，避免 Plan 只能写 session `plan.md` 导致 `design.md` 落错位置）。prompt 同时禁止调用 `enter_plan_mode`。
- 开发任务拆分来源：`design.md`。
- 设计子需求描述来源：`collaboration.md`。
- 协作文档会包含 Design 方案 Mermaid 图，核对实际代码并列出关键函数或组件签名、出入参及相关接口信息；不再生成独立的“前后端协作点”和“评审与验收”章节。
- 开发子需求描述包含自身开发范围、验收标准和依赖关系。
- 创建或同步子需求时使用 `marked` 将 Markdown 转成 HTML，并写入 Story Open API 唯一支持的 `description` 字段。Mermaid 围栏在 HTML 中显示为代码块，不会渲染成图。
- 每次执行 `/tapd sub-task` 都会先与 TAPD 远端子需求对账：仍存在的计划项会更新描述和基础字段，远端已删除的计划项会清理本地陈旧记录并按原计划重建；远端查询失败时停止操作，避免重复创建。设计中移除的旧项不会自动删除。

## Code review

两种 review 分工明确：

- `/tapd review`：AI 子 Agent 检查需求/设计符合度、隐藏 Bug 和过度设计，返回分级报告并等待确认。
- `/review [uncommitted|branch] [--base origin/dev]`：人在浏览器逐行查看 Git diff；提交批注后自动交给主 Agent 修改，关闭不操作。

两者不会自动串行启动，避免一个命令阻塞两个长流程。

`/tapd review` 会先显示审核范围选择器：

- **仅审核未提交修改**：以 `HEAD` 为比较起点，只审核暂存、未暂存和未跟踪文件，不包含只存在于既有 commit 中的修改。
- **审核当前分支全部修改**：审核指定基础分支的 merge-base 到工作区的全部修改，包括已提交、暂存、未暂存和未跟踪文件；`--base`（默认 `origin/dev`）仅影响此选项。

按 `Esc` 取消选择不会启动 Agent 或 Review 子代理。命令要求当前需求已有非空的 `understanding.md` 和 `design.md`，并使用只开放 `read`、`grep`、`find`、`ls` 的隔离子代理检查代码风格、文件拆分、需求满足度、设计满足度和隐藏 Bug；同时按 ponytail-review 标准检查死代码、重复实现标准库或平台能力、无必要依赖、投机性抽象/配置/扩展点、单调用层、单实现接口及可明显缩短的逻辑，报告给出最小替代方案与预计可减少行数。存在组件改动时，还会检查组件 Props/参数、默认值、事件、状态归属、数据流、组合方式、子结构和拆分边界是否合理及兼容。子代理保持瘦加载，只额外加载 OpenAI 兼容模型发现，因此可直接继承主 Agent 使用的对应自定义模型。

命令会让主 Agent 调用原生 `tapd_review` 工具；执行进度、Review 子代理最近的工具调用和最终报告均显示在对话工具框中。工具卡 summary 与 Subagent Overlay Header 显示 Review 所用模型；该模型支持 reasoning 时再显示思考等级（`provider/id · high`），不支持时省略。思考等级优先用 `tapd.json` 的 `review.thinkingLevel`，未配置时继承主会话。可用 `Ctrl+O` 在运行期间展开全部已记录调用，并在完成后展开完整 Markdown 报告。审核期间按 `Esc` 或 `Ctrl+C` 会通过工具的 AbortSignal 终止子代理。报告使用 `P0 Blocker`、`P1 High`、`P2 Medium`、`P3 Suggestion` 问题等级及 `LOW`、`MEDIUM`、`HIGH`、`BLOCKED` 总体风险等级。工具结果会直接进入主 Agent 上下文，主 Agent 只总结问题，不会自动修改代码。

Review 默认使用持久 RPC 子 Agent，不会自动打开分屏。按 `Alt+A` 可在当前 TUI 上方打开居中的大尺寸只读 Overlay，以主 Agent 相同的消息、Markdown、思考块和工具组件查看最近子 Agent 的过程；Overlay 不提供输入框，支持鼠标滚轮以及 `↑`、`↓`、`PageUp`、`PageDown`、`Home`、`End` 滚动，并使用 `Ctrl+O` 展开或折叠工具输出。按 `Esc` 返回主 Agent且不终止审核。使用 `/subagents` 可以管理指定子 Agent：列表中按 `Enter` 进入实时过程或查看历史详情；completed/exited 历史会从子 Agent session 重建完整消息、思考块和工具时间线，并继续使用主界面组件样式；thinking 可用 `app.thinking.toggle`（默认 `Ctrl+T`）折叠，built-in 工具遵循当前 `/grok-tools` 配置。只有旧记录缺少或损坏 session 时，才回退到最终 Markdown 或 transcript 文本摘要。按 `C` 请求取消，按 `X` 强制终止活跃任务，按 `D` 清理已退出的任务记录。列表默认只显示当前主会话创建的子 Agent，按 `Tab` 可切换到所有会话记录；操作后会刷新列表。首轮审核完成后报告自动返回主 Agent；`keepOpen: true` 时结果同时给出 reusable `subagentId`，相关解释、追查或同一快照内的补充检查可交给 `subagent_followup`。需要独立审查时必须重新调用 `tapd_review` 启动新的 reviewer，不能让产出实现或原结论的同一 Agent 自我审查；代码或需求/设计内容已变化并需要重新采集完整 Git 快照时也必须新建 Review，不要续接旧快照。公共行为由 `~/.pi/agent/ming-core.json` 的 `subagents` 配置；Review 固定使用 managed RPC/manual，`keepOpen: false` 时为一次性。Review 的 Git 上下文会复制进子 Agent 任务目录，避免主工具返回后丢失审核证据。

## Session links

TAPD 会话关联保存在 Pi session 自身的 custom entry（`tapd-session-link`）中，不再维护 `tapd-links.json`。每个 TAPD 会话保存 `workspaceId / itemId / kind / itemName / title / projectPaths / understandingFile / subtaskPlan / subtasks` 快照；子任务计划与结果每次更新都会追加新快照，恢复会话时读取最后一条。`/tree` 导航不影响会话关联。

事项 → 历史会话列表由 `SessionManager.listAll()` + 有界并发扫描会话 custom entries 构建内存目录（`sessions/catalog.ts`），首次打开关联会话 picker 时扫描并在进程内缓存；创建或删除会话后失效重建。大量会话时 picker 会显示扫描进度，单个损坏 JSONL 跳过，不阻断待办列表。

旧版 `~/.pi/agent/tapd-links.json` 的关联已在迁移时写入各会话 custom entry，迁移完成后原文件归档为带时间戳的 `.migrated.bak`；迁移逻辑已移除，不再读取或维护该文件。

在关联会话列表按 `Ctrl+D` 删除会话时，直接删除（优先 trash）session 文件；关联信息随会话文件消失，无需额外清理。`tapd-project-paths.json`（项目路径输入历史）继续保留。

文档默认位于：

```text
.pi/docs/story-{storyId}/
```

## Configuration

配置文件：`~/.pi/agent/tapd.json`

```json
{
  "token": "TAPD 个人令牌",
  "baseUrl": "可选的 TAPD API Base URL",
  "review": {
    "model": "可选；例如 lumilegend/gpt-5.6-sol；默认继承主 Agent 当前模型",
    "thinkingLevel": "可选；off、minimal、low、medium、high、xhigh 或 max；默认继承主会话",
    "presentation": "兼容保留；Review 固定使用 manual RPC，以接入子 Agent 状态栏、Overlay 和 /subagents"
  },
  "rootCause": {
    "model": "可选；例如 cursor/composer-2.5；默认继承主 Agent 当前模型",
    "thinkingLevel": "可选；off、minimal、low、medium、high、xhigh 或 max；默认继承主会话"
  },
  "gitlab": {
    "token": "可选；也可使用 GITLAB_PERSONAL_ACCESS_TOKEN",
    "baseUrl": "可选；默认从 origin 推导 https://host/api/v4"
  }
}
```

TAPD Open API 索引见 [`../../docs/tapd-api.md`](../../docs/tapd-api.md)。

## Git workflow

- `git-status`、`branch`、`commit`、`mr` 由 slash command handler 直接执行，不经过模型，也不会插入工具触发提示词。执行一开始在对话区插入一张 `running` 工具卡片，并显示 `Working... · Esc 取消`；结束时不追加第二张展示卡，仅通过同 `runId` 重绘为终态。运行中按 Esc 会 abort 并尽量结束 `git`/`npm` hooks 进程树（Windows 使用 `taskkill /T`）。展示卡正文过长会截断，完整日志在隐藏 context 消息中。
- 目标 `bug/{short_id}` 或 `feature/{short_id}` 已在本地存在时直接切换（已在目标分支则保持不变）；否则默认从 `origin/dev` 创建，并使用 `--no-track`。
- 工作区有未提交改动时，创建分支前会打开迁移方式选择器（标题显示当前分支、目标分支与基础分支）：
  - **stash 后迁移（推荐）**：`git stash push --include-untracked` 保存全部改动（含未跟踪文件）→ 从 `--base` 创建目标分支 → `git stash pop` 恢复；
  - **WIP commit 后迁移**：`git add --all` 并以 `chore: WIP before creating {目标分支}` 自动提交（正常执行 Git hooks，不自动 `--no-verify`）→ 从 `--base` 创建目标分支 → `git cherry-pick` 该 WIP commit；WIP commit 会保留在原分支；
  - **从当前 HEAD 创建**：直接以当前 HEAD 创建目标分支并保留未提交改动，**不再基于 `--base` 指定的基础分支**；
  - **取消**（Esc）：不执行 stash、commit 或分支创建，工作区保持不变。
- 迁移失败不会强制回滚或丢弃改动：stash 成功但创建分支失败时改动保留在 stash，提示 stash ref 与 `git stash apply` 恢复命令；stash pop 冲突时停留在目标分支的冲突工作区，stash 条目未被删除时仍可在 `git stash list` 找到；cherry-pick 冲突时停留在标准 cherry-pick 冲突状态，提示 `git cherry-pick --continue` / `--abort`；WIP commit 成功但创建分支失败时 commit 保留在原分支，提示 commit hash。
- 无交互界面（print/json 等）且工作区有未提交改动时直接报错，不会默认选择会改写 Git 状态的方案。
- Bug 提交为 `fix: {KEYWORD}`；需求/任务提交为 `feat: {KEYWORD}`。KEYWORD 原样保留。
- `commit` 或 `mr` 遇到当前分支没有 upstream 时，会自动使用 `git push -u origin HEAD` 首次推送并建立跟踪关系。
- 提交默认使用当前操作系统 PATH 中的 `git`。仅当运行于 WSL，且 Git hook 因 Windows CRLF shebang 报出 `sh\\r: No such file or directory` 时，才自动改用 Windows `git.exe` 重试；重试成功后将仓库记录在 `~/.pi/agent/tapd-git-runtime.json`，该仓库后续在 WSL 中提交时直接使用 Windows Git。原生 Windows、Linux 和 macOS 环境始终使用各自 PATH 中的 `git`。可用 `TAPD_WINDOWS_GIT_PATH` 指定 WSL 可执行的 `git.exe` 完整路径。
- `git commit` / pre-commit（如 `npm run precommit`）运行期间可按 Esc 取消；hooks 失败后会在同一张 Git 卡片上临时展示截断摘要，并打开选择器：`› 使用 --no-verify 跳过 hooks 后重试` 或 `取消`。选择跳过会重新暂存并以 `--no-verify` 提交，成功后终态卡不再保留该摘要；取消时摘要仍留在取消结果中。取消、Esc 中止或放弃提交预览时卡片为 `cancelled`（不是 `completed`）。无交互界面时直接报错，不默认跳过 hooks。
- MR 会扫描 `merge-base..HEAD` 的全部提交，不只处理第一条 TAPD 关联。
- `/tapd mr --draft` 会创建或更新 Draft MR。当前关联项是功能需求时，功能需求本身和测试需求保持原状态，但其下所有处理人为当前 Token 用户的直属开发子需求会更新为“开发完成”；直接关联开发子需求时也照常更新为“开发完成”。这些实际流转的开发子需求会将完成工时同步为各自的有效预估工时。TAPD 任务和 Bug 不流转，Bug 也不会触发根因分析。后续执行不带 `--draft` 的 `/tapd mr` 会把同一开放 MR 更新为 Ready：当前用户负责的功能需求仅更新状态；存在其他处理人的未完成直属开发或测试需求时更新为“实现中”，否则更新为“开发完成”。当前用户负责的开发子需求更新为“开发完成”，测试需求更新为“已通过”；其他处理人的需求不流转。
- Bug 默认标签为 `二组`、`迭代bug(每日发布)`，状态更新为 `已解决`，负责人为 `沈瑞昀`。
- 需求/任务默认标签为 `二组`、`迭代任务(随迭代发布)`。Ready MR 中，关联项是开发子需求或 TAPD 任务时更新为 `开发完成`；关联项是测试需求时，仅在处理人为当前 Token 用户时更新为 `已通过`；关联项是顶层功能需求时，仅更新当前用户负责的功能需求本身及其直属开发、测试需求。功能需求只更新状态：存在其他处理人的未完成直属开发或测试需求时更新为 `实现中`，否则更新为 `开发完成`；开发子需求更新为 `开发完成`，测试需求更新为 `已通过`。每个实际流转的 TAPD 任务、开发子需求和测试需求都会将完成工时同步为自身的有效预估工时；首次批量更新后会回读完成工时，仅在 TAPD 状态流转覆盖工时值时单独补写并再次校验。预估工时缺失、为零或无效时只更新状态，不写完成工时，也不阻断 MR。其他处理人的需求不会被修改，所有更新均不修改负责人。
- 纯需求/任务的 `/tapd mr` 保持一次执行完成，不触发根因填写。
- 含 Bug 的 Ready `/tapd mr` 在同一次执行中完成：只读子 Agent 根据 TAPD 描述、会话定位结论和当前修复 diff，用 `git blame` / `log` / `show` **自行定位引入 commit**，并预填【根因分析（RCA）】、【影响范围】、【修复方案说明】与【引入commit】（不提供候选列表或已确认 hash，无超时）。子 Agent 模型优先用 `tapd.json` 的 `rootCause.model`（例如 `cursor/composer-2.5`），未配置时继承主会话；思考等级同样优先 `rootCause.thinkingLevel`，未配置时继承主会话。lean 子进程以 `--no-extensions` 启动，会加载本 toolkit 的 `openai-compat-models`，模型为 `cursor/*` 时还会加载已启用的 `npm:@rahularya01/pi-cursor`。总结开始后自动打开与 `/subagents` 相同的只读过程 Overlay；该内部根因 Agent 固定 `keepOpen: false`，完成后 Overlay 自动关闭且不暴露 reusable handle。按 `Esc` 取消本次总结并回退为空模板，不取消整次 MR。此期间 slash 命令不可用，进度看 Overlay。打开编辑器确认或修改：【根因分析（RCA）】、【影响范围】、【修复方案说明】必填；可改引入 commit，可填未能定位。子 Agent 会从 TAPD「根因大类」级联候选中选一行「大类 / 子项」；选不出或对不上候选时，在 MR 预览确认前弹出大类、子类选择器，项目有该字段时必须选出一项。确认后创建或更新 MR 并回写 TAPD。流转时按中文 label 写入修复方案说明、根因分析（RCA）、影响范围、根因大类（`大类/子项`），以及当前 Token 用户为「开发人员」；项目没有对应字段时跳过该项且不阻断 MR。流转备注含【根因分析（RCA）】、【影响范围】、【修复方案说明】、【引入commit】、【commit信息】。子 Agent 失败、被取消或当前会话没有模型时回退为空模板（【引入commit】为未能定位），不阻断 MR，也不要求二次执行 `/tapd mr`。再次执行 Ready `/tapd mr` 会再次 POST 更新这些字段。
- 若仓库 `.pi/tapd-root-cause/{bugId}.json` 已有与当前 `HEAD` 匹配的草稿，会直接复用并跳过填写；TAPD 流转成功后自动删除该草稿。未能定位引入 commit 时使用 TAPD 真实候选值 `其他(历史缺陷)`。
- 引入 commit 经验证后，会拉取远端 tags，优先取直接指向 commit 的第一个 tag，否则取第一个包含该 commit 的 tag。
- 合入版本从 TAPD `/bugs/get_fields_info` 的“合入版本”候选值中选择。普通版本精确匹配；`.0` 等存在多个迭代候选时，根据引入 commit 中 TAPD keyword 关联事项的迭代唯一匹配；关联事项没有迭代时会列出候选值让用户手动选择。
- tag 在候选值中完全不存在时，按规则选择候选值中的 `其他(历史缺陷)`；若该选项也不存在则不修改合入版本。
- 除首次推送建立 upstream 跟踪关系外，工作流不会修改 git config，也不会 hard reset、clean、force switch 或 force-push；stash、WIP commit 与 cherry-pick 仅在用户明确选择后执行。

## Modules

| 目录/文件 | 职责 |
| --- | --- |
| `index.ts` / `types.ts` / `lean-extensions.ts` | 扩展组装入口、跨领域共享类型，以及 lean 子 Agent 的 OpenAI-compat / `pi-cursor` provider 路径 |
| `core/` | 配置、HTTP 客户端、基础 TAPD API |
| `sessions/` | TAPD 会话 custom entry 状态、事项→会话目录（catalog）、按目标目录创建/切换会话（`spawn.ts`）、项目路径历史与会话文件删除 |
| `documents/` | analyze、design、collaboration、Bug 定位与 `/tapd bug-reject` 拒绝流转，以及 Design 关键决策提问工具 |
| `subtasks/` | 子需求解析、确认计划、TAPD 同步（`api-sync.ts`）与 append-only 状态更新（`state.ts`） |
| `todo/` | 待办编排与 Overlay；`tree-list.ts`、`table-view.ts`、`session-picker*.ts` 分别负责树表、响应式主表和会话/路径 viewport |
| `review/` | 需求实现审核上下文、只读子代理、进度和报告渲染 |
| `working.ts` | TAPD 侧 `withTapdWorking`；底层实现见 `extensions/shared/tui/working-cancel.ts` |
| `git/` | Git 仓库、TAPD keyword、GitLab MR、状态回写和根因备注；`commands.ts` 单卡、`commit-workflow.ts` 提交推送、`root-cause-*.ts` 根因证据与总结子 Agent、`bug-fields.ts` 缺陷字段信息 |