dsh-todo-audit

DeepSeek Harness 的待办注释审计工具箱：scan_todos 扫描源码树里的 TODO/FIXME/HACK 等注释标记并给出明细，todo_report 输出按标签、扩展名、目录、文件的聚合报告。支持多语言注释前缀、标签与扩展名过滤、忽略名单、深度与结果上限。只读、零运行时依赖。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-todo-audit
• npm：https://www.npmjs.com/package/dsh-todo-audit

功能说明

面向"项目里到底还欠多少技术债"这个常见问题，提供"明细定位 → 聚合盘点"两个工具：

scan_todos —— 明细扫描

遍历目录，按注释前缀识别标签，输出「文件 → 行号 → 标签 → 指派人 → 正文」：

扫描：E:\project
标签：TODO, FIXME, HACK, XXX, NOTE, BUG, OPTIMIZE

匹配 5 处，分布在 3 个文件。
按标签：TODO 3，FIXME 1，HACK 1

src/a.js
      1: [TODO] 优化这里
      3: [FIXME](john) 处理边界
      4: [HACK] 临时方案
src/b.py
      1: [TODO] python 待办
docs/c.md
      1: [TODO] 文档补充

已扫描 42 个文件，跳过二进制 2 个

todo_report —— 聚合报告

在同一份扫描结果上做多维度统计，并给出"最久未改动"的待办文件：

目录：E:\project
匹配：5 处 / 3 个文件

按标签：
  TODO              3    60.0%
  FIXME             1    20.0%
  HACK              1    20.0%

按扩展名：
  .js               3
  .py               1
  .md               1

目录 Top 3：
      3  src
      1  docs

文件 Top 3：
      3  src/a.js
      1  src/b.py
      1  docs/c.md

最久未改动（按文件修改时间）：
  2026-08-01    3 处  src/a.js

支持的标签

• 默认关注：TODO、FIXME、HACK、XXX、NOTE、BUG、OPTIMIZE
• 需要时可通过 tags 显式启用：WIP、REVIEW、DEPRECATED、TBD
• 标签大小写不敏感，todo 与 TODO 等价

支持的注释前缀

//、/*、<!--、--、;、%、*（块注释续行）、#、REM （批处理）。

指派人语法

标签后紧跟圆括号即视为指派人：// FIXME(john): 处理边界 → 标签 FIXME、指派人 john、正文 处理边界。

安装

npm install dsh-todo-audit

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: todo-audit
      name: "dsh-todo-audit"

使用说明

scan_todos

| 参数 | 类型 | 说明 | |---|---|---| | path | string | 目录路径，默认当前目录 | | depth | number | 最大下钻层数，默认 6，上限 12 | | ignore | string | 忽略的目录名，逗号分隔，默认 node_modules,.git,dist,build,coverage,out,.next,.cache；传空字符串表示不忽略 | | include | string | 仅扫描这些扩展名，逗号分隔，如 js,ts,py（默认全部） | | tags | string | 只关注这些标签，逗号分隔，默认 TODO,FIXME,HACK,XXX,NOTE,BUG,OPTIMIZE | | max_size | number | 单文件大小上限（KB），默认 1024，上限 20480 | | max_results | number | 最多返回的匹配数，默认 200，上限 2000 | | max_per_file | number | 单文件最多返回的匹配数，默认 50 | | sort | string | 排序：path（默认，按文件/行号）| tag（按标签）| age（按文件修改时间，最旧在前） |

用户：看看 src 目录里还剩多少 TODO

scan_todos(path="src", tags="TODO,FIXME")

用户：只看前端代码，按最旧优先排

scan_todos(path=".", include="ts,tsx,vue", sort="age")

todo_report

| 参数 | 类型 | 说明 | |---|---|---| | path | string | 目录路径，默认当前目录 | | depth | number | 最大下钻层数，默认 6，上限 12 | | ignore | string | 忽略的目录名，逗号分隔，默认同 scan_todos | | include | string | 仅扫描这些扩展名，逗号分隔（默认全部） | | tags | string | 只关注这些标签，逗号分隔，默认同 scan_todos | | top | number | 各榜单展示条数，默认 10，上限 50 |

用户：给我一份这个仓库的待办盘点

todo_report(path=".", top=15)

用户：把 TBD 和 WIP 也算进来看看

todo_report(path=".", tags="TODO,FIXME,TBD,WIP,REVIEW")

典型场景

• 接手陌生代码库：先跑一次 todo_report，用「按目录」榜单快速定位技术债集中的模块。
• 发版前清理：用 scan_todos(tags="FIXME,BUG,HACK") 检查是否有被遗忘的严重标记。
• 代码评审辅助：用 scan_todos(path="src", sort="age") 找出最久未动的待办，优先处理陈年旧账。
• 多语言仓库盘点：用 include 分技术栈统计，或直接用「按扩展名」榜单看分布。
• CI 门禁：把 scan_todos(tags="BUG") 的结果接入流水线，出现新 BUG 标记即提醒。

安全边界

• 只读：两个工具都不写入、不修改、不删除任何文件，仅做遍历与读取；测试含只读性断言。
• 不访问网络：全部逻辑在本地完成，无任何外部请求。
• 符号链接不跟随：遍历时跳过符号链接，避免环状目录导致无限递归。
• 多层上限保护：单次遍历最多 200000 个目录项；depth 上限 12；max_results 上限 2000；max_per_file 上限 2000；max_size 上限 20480 KB。任一上限触发都会在输出中显式提示截断。
• 二进制与超大文件跳过：读取时检测内容中的 NUL 字节判定为二进制并跳过；超过 max_size 的文件直接跳过，二者都会在统计行中报告数量。
• 误报边界：识别要求注释前缀，因此字符串字面量中的普通文本不会误报；但若字符串内容本身形如注释（例如测试用例里写 "// TODO: x"），仍会被计入——这是正则层面的已知取舍，可通过 include 或 ignore 缩小范围规避。
• 不做语法解析：不依赖各语言解析器，纯行级匹配，因此不保证 100% 语义准确。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-file-search | 先用 file-search 定位相关文件，再用 todo-audit 审计其中的待办标记 | | dsh-fs-inspector | 结合 fs-inspector 的目录规模信息，判断待办密度（每千行多少处） | | dsh-folder-tree | 用 folder-tree 输出目录结构，配合 todo-audit 的「按目录」榜单定位热点 | | dsh-table-render | 把 todo_report 的统计结果渲染成对齐表格，便于粘贴进周报 | | dsh-hash-checksum | 对待办文件做哈希快照，比对两次审计之间哪些文件发生了变化 | | dsh-workspace-journal | 把每次审计的汇总数据写入工作区日志，形成技术债趋势记录 | | dsh-code-check | 两者互补：code-check 关注语法与格式，todo-audit 关注遗留标记 |

版本说明

• 0.1.0（2026-09-26）：初始版本。
  • scan_todos：多语言注释标记扫描 + 标签/扩展名/深度/忽略过滤 + 三种排序
  • todo_report：按标签、扩展名、目录、文件的聚合统计 + 最久未改动榜单
  • 11 种标签（7 个默认 + 4 个可选）、9 种注释前缀、指派人解析
  • 二进制与超大文件自动跳过，多层上限保护

RoadMap

v0.2（计划）

• 新增 todo_trend：对比两次审计快照，输出新增/已解决/存量的变化
• 支持 .todoignore 文件，按 glob 规则排除路径
• 支持 --since 语义：只统计指定日期之后修改的文件中的标记
• scan_todos 支持按指派人过滤（assignee=john）

v0.3（展望）

• 接入 Git：用 git log -S 追溯每个标记的引入 commit 与作者
• 输出 SARIF / JUnit XML，便于接入 CI 门禁与代码扫描平台
• 支持从 Markdown 任务列表（- [ ]）中提取未完成项，与注释标记统一盘点
• 增量扫描缓存，大型仓库下只重扫发生变化的文件

FAQ

Q：为什么我写在字符串里的 TODO 没有被统计？ 这是刻意的。识别要求注释前缀（//、#、<!-- 等），以避免把普通文案、测试数据、JSON 字段误判为待办。如果确实需要统计字符串内容，请改用 dsh-file-search 做字面量搜索。

Q：TBD、WIP 这些为什么默认不统计？ 它们在团队中的语义差异较大（有的团队把 TBD 当正文词汇而非标记），默认收窄可以降低噪声。需要时用 tags="TODO,TBD,WIP" 显式启用。

Q：ignore 传空字符串是什么意思？ 表示不启用任何忽略规则，会连 node_modules、.git 一起扫描。测试中正是用它来验证忽略逻辑生效。

Q：max_per_file 和 max_results 有什么区别？ max_per_file 限制单个文件返回多少条（避免某个大文件刷屏），max_results 限制总数（避免整体输出过长）。两者可同时设置，任一触发都会标记截断。

Q：为什么输出说"结果达到上限"？ 说明命中的标记数超过了 max_results。调大该参数（上限 2000）或缩小 path/include 范围即可拿到完整结果。

Q：会不会修改我的文件或自动关闭 TODO？ 不会。本插件只读、只报告，不做任何写入。清理动作请人工完成或使用其他工具。

Q：支持哪些语言的注释？ 不做语言区分，纯按注释前缀匹配，因此 JS/TS/Go/Rust/C/Java/Python/Shell/SQL/HTML/Markdown/批处理等的常见注释都能识别。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-todo-audit
• npm：https://www.npmjs.com/package/dsh-todo-audit

许可证

MIT