# dsh-plugin-todo-scanner API

插件对外接口汇总：**配置**、**Host 工具**、**HTTP 数据服务**、**客户端事件**。

> 行为口径的权威来源是 [PRD.md](../PRD.md) 与源码；本文档随实现更新。数据结构（`TodoItem` / `ScanStats` / `SessionState` 等）见 [src/types.ts](../src/types.ts)。

## 1. 配置（cordis 插件 config）

默认值已内联在 [cordis.patch.yml](../cordis.patch.yml)（挂载点可整体覆盖），与源码 `Config` schema（[src/config.ts](../src/config.ts)）一一对应：

| 段 | 项 | 说明 | 默认 |
|---|---|---|---|
| `enable` | 插件总开关 | 关闭时加载但不工作 | `true` |
| `scan` | `allowedRoots` | 允许扫描的根目录白名单（绝对路径）；空 = 仅各会话工作目录 | `[]` |
| | `ignoreDirs` | 忽略目录名（node_modules / 构建产物 / VCS / IDE） | 内置清单 |
| | `ignoreExtensions` | 忽略扩展名 / 后缀（.min.js / .map / 图片 / 压缩包等） | 内置清单 |
| | `useGitignore` | 是否应用项目根 `.gitignore`（git 语义子集） | `true` |
| | `maxFileSize` | 单文件最大扫描字节数，超出跳过并计入 skipped | 1 MB |
| | `maxFiles` | 单次扫描最大文件数，超出停止收集 | 5000 |
| `markers` | `types` | 识别哪些标记类型 | TODO/FIXME/HACK/NOTE/XXX/BUG/OPTIMIZE/REVIEW |
| | `caseSensitive` | 标记匹配是否大小写敏感 | `false` |
| `export` | `defaultFormat` | `todo_export` 默认分组：`by_type` / `by_file` | `by_type` |
| `ui` | `showIgnored` | 面板是否显示已忽略项 | `false` |
| `server` | `enable` | 是否启动面板数据服务 | `true` |
| | `port` | 监听端口；被占用自动 +1（最多 5 次） | `18766` |

## 2. Host 工具（8 个）

经 `ctx.tools` 注册（`defineTool`），返回 JSON Schema 校验后的结构化值；模型侧见各工具 `description`。

- **todo_scan** `{ rootPath?, types? }` → 扫描结果：`ok / error / items[] / stats / summary / scanRoot / truncated / cancelled / warnings / added / preserved`
- **todo_list** `{ filter?{type,status,filePath,keyword}, sortBy?('file'|'type'|'line'), includeIgnored? }` → `TodoItem[]`
- **todo_get** `{ id }` → `TodoItem`（不存在则抛错）
- **todo_update_status** `{ id, status }` → `{ success, item?, error? }`；变更写审计
- **todo_batch_update** `{ ids[], status }` → `{ success, updatedCount, missing[] }`
- **todo_export** `{ format?, includeDone? }` → `{ content }`（Markdown）
- **todo_stats** `{}` → `{ scanned, scanRoot, lastScanTime, stats }`
- **todo_clear** `{}` → `{ success, removedCount }`

工具执行要求绑定会话（`exec.agent`），状态按会话隔离。

## 3. HTTP 数据服务（面板取数，仅 127.0.0.1）

基础路径 `/todo-scanner`；所有响应为 JSON（除导出返回原始文本）。未列端点一律 `404`。

| 方法与路径 | 说明 |
|---|---|
| `GET /todo-scanner/` | 简易状态页（浏览器调试） |
| `GET /todo-scanner/health` | 健康检查（含端口/版本） |
| `GET /todo-scanner/api/sessions` | 会话摘要列表（面板会话选择器） |
| `GET /todo-scanner/api/state?session=` | 会话完整状态：清单 + 统计 + 进度 + 配置（清单截断上限 1000 条） |
| `POST /todo-scanner/api/scan` | 触发异步扫描 `{ session?, rootPath?, types? }` |
| `POST /todo-scanner/api/update-status` | 更新单条状态 `{ session?, id, status }` |
| `POST /todo-scanner/api/batch-update` | 批量更新状态 `{ session?, ids, status }` |
| `POST /todo-scanner/api/mark-all-done` | 全部标记已完成 `{ session? }` |
| `GET /todo-scanner/api/export?session=&format=&includeDone=` | 导出 Markdown |
| `POST /todo-scanner/api/clear` | 清空清单 `{ session? }` |
| `GET /todo-scanner/api/audit?session=` | 审计日志（最近 20 条） |

`session` 省略时解析为最近活跃会话；无任何扫描记录时多数操作返回 `error: '尚无会话扫描记录'`。端口被占用时自动尝试 `+1`（最多 5 次），实际端口见 `/health`。

## 4. 事件与生命周期

- **`todo-scanner/state`**（Host emit）：`{ session: string | null, changedAt }` —— 扫描开始/进度/完成、状态变更、清空时触发；供宿主加入 remotes 白名单后向面板推送（默认未启用，面板走轮询）。
- **`session/disposed`**（Host 监听）：会话销毁时取消该会话进行中的扫描并清理状态。
- **卸载**：取消全部扫描 → 关闭 HTTP 服务 → 清空全部会话状态，零残留。