dsh-plugin-todo-scanner

Readme

# dsh-plugin-todo-scanner

> DeepSeek Harness（Cordis 组合）的 TODO 代码扫描插件：递归扫描本地项目目录中的 `TODO / FIXME / HACK / NOTE / XXX / BUG / OPTIMIZE / REVIEW` 标记，生成结构化清单与统计，支持状态管理、Markdown 导出与侧边「TODO 雷达」面板。

- **Host 侧**：注册 8 个工具，供大模型读取/管理扫描结果；本地 HTTP 数据服务供面板取数。
- **Client 侧**（Web）：设置弹窗内的「TODO 雷达」分区卡片（统计 + 类型分布 + 可筛选/排序清单 + 状态操作）。
- 只读扫描，白名单 + 系统目录黑名单双重防护，文件数/大小上限保护；状态仅存内存、按会话隔离、卸载即清空。

## 效果预览

「TODO 雷达」设置分区面板：统计卡片 + 标记类型分布 + 可筛选/排序的清单 + 状态管理操作。

![TODO 雷达面板示例](assets/demo.png)

## 安装

本插件按官方第三方插件分发形态（profile bundle）打包：`package.json` 声明 `dsh.bundle.patch` 指向 [cordis.patch.yml](cordis.patch.yml)，并由 `exports["./cordis.patch.yml"]` 暴露。

```bash
# 已发布为可安装 bundle 时，加入某个 profile：
dsh plugin --profile <name> add dsh-plugin-todo-scanner
```

本地源码调试：在 Harness 的 cordis 配置里引用本文件（或把内容合并进宿主 cordis.yml）：

```yaml
- import: ./dsh-plugin-todo-scanner/cordis.patch.yml
```

面板数据通路默认走**本地 HTTP 轮询**（仅 `127.0.0.1`，端口见配置 `server.port`），因此要求 Client 与 Host 同机；若宿主将 `todo-scanner/state` 事件加入 remotes 转发白名单，也可切换为推送（可选增强，默认关闭）。

## 提供的工具（8 个）

| 工具 | 说明 |
|---|---|
| `todo_scan` | 扫描目录（默认当前会话工作目录）中的代码标记，返回结构化清单与统计 |
| `todo_list` | 当前会话清单，支持类型/状态/文件/关键词筛选与 file/type/line 排序 |
| `todo_get` | 单条条目完整详情（含前后 2 行代码上下文） |
| `todo_update_status` | 更新单条状态（pending / in_progress / done / ignored） |
| `todo_batch_update` | 批量更新状态 |
| `todo_export` | 导出当前清单为 Markdown 任务清单（by_type / by_file） |
| `todo_stats` | 会话扫描统计（总数 / 类型 / 文件 / 语言 / 状态） |
| `todo_clear` | 清空当前会话的扫描结果与状态 |

## 配置

完整配置项见 [cordis.patch.yml](cordis.patch.yml)（扫描范围 / 忽略规则 / 标记类型 / 导出格式 / UI / 面板服务端口），与源码 `Config` schema 一一对应。详见 [docs/api.md](docs/api.md)。

## 本地开发

要求 Node >= 20，包管理器固定为 **npm**（参见 [AGENT.md](AGENT.md) §3，禁止 pnpm/yarn）。

```bash
npm install
npm run typecheck   # tsc --noEmit（Host 侧；Client 类型检查见 typecheck:client）
npm run build       # tsc → lib/
npm run build:client # tsdown 打包 Web 面板 → lib/client.js
npm test            # build + 冒烟回归 + matcher/ignore-rules/safety 单测（node:test）
```

## 文档

- [AGENT.md](AGENT.md) —— 面向维护者/AI Agent 的开发约定与改哪里
- [PRD.md](PRD.md) —— 功能需求与验收口径
- [docs/api.md](docs/api.md) —— 配置、工具与 HTTP 数据接口
- [CHANGELOG.md](CHANGELOG.md) / [LICENSE](LICENSE)

## License

[MIT](LICENSE)