Skip to content

DSH 插件(五):8 个工具加一个侧边面板 ​

让 Agent “扫一下项目里的 TODO”,听起来是一个工具的事。真做起来会碰到三个问题:

  1. 不设边界,第一个被扫的是 node_modules,清单里一半是依赖包的注释;
  2. 扫完一轮,用户把几条标成“已完成”,再扫一次状态全丢;
  3. 两个会话同时扫不同项目,结果串在一起。

todo-scanner 的 8 个工具和 1 个侧边面板,基本都是围绕这三个问题长出来的。

一、为什么是 8 个工具 ​

一个 todo_scan 不够,因为“扫描”和“管理清单”是两件事。模型需要能重新扫、能按条件查、能改状态、能导出,而不是每次把全量清单塞回上下文。

工具作用
todo_scan扫描并合并结果
todo_list按类型、状态、文件、关键词过滤
todo_get取单条详情
todo_update_status改一条状态
todo_batch_update批量改状态
todo_export导出 Markdown
todo_stats扫描统计
todo_clear清空当前会话清单

工具粒度小,模型可以只取需要的那部分。比如“把 src/auth 下的 FIXME 标成已完成”,先 todo_list 过滤,再 todo_batch_update,不用把 800 条都读一遍。

二、扫描边界:三道闸 ​

第一道:根目录必须被允许 ​

todo_scan 接受 rootPath,但不能什么都扫。规则是:

  • 没传就用会话工作目录;
  • 传了相对路径,按工作目录解析;
  • 配置了 allowedRoots,必须在白名单内;
  • 没配白名单,只允许工作目录及其子目录;
  • 系统目录一律拒绝,包括盘符根、C:\Windows、/etc、/usr。

最后一条在 Windows 上容易写漏。归一化后路径分隔符是 \,如果正则只写 (?:\/|$),C:\Windows\System32 会漏过去。所以系统目录模式统一用 [\\/]。

扫描本身是只读遍历,不执行任何 shell 命令。这降低了“扫描器变成执行器”的风险。

第二道:三层忽略 ​

  1. 目录名:node_modules、dist、.git、vendor 等;
  2. 扩展名:.min.js、.map、图片、字体、压缩包;
  3. 项目根 .gitignore,默认开启。

.gitignore 不是把整个文件当黑名单,而是实现了 git 语义的子集:注释、! 取反、尾 / 限定目录、首 / 锚定、* / ** / ? 通配,以及“最后一条匹配规则生效”。

最后这条最容易被忽略。如果按“任意一条命中就忽略”实现,!important.md 这类取反规则永远不会生效,用户会以为插件没读 .gitignore。

第三道:文件大小与数量上限 ​

单文件默认 1 MB,单次最多 5,000 个文件。超限不是报错,而是跳过并计入统计,同时在结果里给 warnings。这样模型能知道“这次结果不完整”,而不是把截断当成全量。

三、注释识别:纯正则,但不粗糙 ​

扫描器不解析语法树,只看注释符号。六种形式:

形式适用关键排除
//JS / TS / Java / Go / Rust前面不能是 :,避开 https://
#Python / Ruby / Shell / YAML避开 shebang 和 #fff、#field
/* */C 系 / JSDoc支持跨行续读
<!-- -->HTML / XML支持跨行续读
*JSDoc 续行排除 */
--SQL前面必须是行首或空白

标记本身用锚定正则:注释符号之后、可选空白、然后是 TODO|FIXME|...,后面必须是非单词字符。这样 TODOLIST 不会被当成 TODO。

匹配器是纯函数,输入一行文本,输出命中列表。纯函数的好处是测试不需要文件系统:给字符串、断言结果,几十个边界用例几毫秒跑完。

踩坑:块注释跨行

/* TODO: 重构鉴权 */ 单行能处理,但跨行写法:

js
/*
 * TODO: 重构鉴权
 */

第一行只有 /*,标记在第三行。扫描器必须记住“当前处于未闭合块注释”,把后续行当注释内容继续找标记,直到遇到 */。这个状态是逐文件的,不能跨文件复用。

四、重扫之后,状态不能丢 ​

用户把三条标成“已完成”,第二天再扫,不能又变回待办。

做法是给每条 TODO 算一个身份键,跟行号无关:

文件路径 + 标记类型 + 内容

重扫时用身份键去旧清单里找:

  • 找到:保留旧的 id、status、createdAt,只更新行号、代码行和上下文;
  • 没找到:新建,状态 pending。

所以代码整体下移 20 行,已完成状态还在;内容改了,就是一条新 TODO。这个语义比“按行号匹配”稳,也比“按内容哈希匹配整条”宽松。

扫描结果里会返回 added 和 preserved 两个数。用户能直接看出这次是新增多还是保留多。

五、会话隔离与取消 ​

清单按会话存,不按全局存。每个会话有自己的扫描根、清单、统计和审计日志。

会话销毁时,宿主发 session/disposed,插件做三件事:

  1. 中止该会话正在跑的扫描(AbortSignal);
  2. 清掉会话状态;
  3. 关闭对应的资源。

扫描器在遍历目录和逐文件处理时都检查 signal.aborted,超限时也会提前返回。这样用户关掉会话,不会留下一个还在读盘的异步任务。

六、面板:为什么用轮询 ​

面板要显示清单、统计和扫描进度。host 侧已经有一个 todo-scanner/state 事件,但默认没有加入宿主的 remotes 白名单,浏览器端收不到。

所以面板走 HTTP 轮询:

  • 服务只监听 127.0.0.1,端口默认 18766,被占用就 +1,最多试 5 次;
  • 面板每 2 秒拉一次 /todo-scanner/api/state?session=...;
  • 返回的清单最多 1,000 条,避免一次传太多。

轮询不如推送实时,但实现简单、断线自愈、不需要维护连接状态。对一个“看一眼待办”的面板,2 秒延迟完全可以接受。

为什么不直接走 WebSocket

WebSocket 需要连接管理、重连、心跳和鉴权,收益是秒级推送。这个面板的使用频率很低,轮询的复杂度更低。真正需要实时的地方(日志转发)才值得上 WebSocket。

七、边界 ​

正则扫描会有误报:字符串里的 "TODO"、文档里的示例、被注释掉的代码,都可能被收进来。插件提供 ignored 状态让用户手动排除,但不做语义判断。

它也不排优先级。清单能按类型、文件、行号排序,但“哪个 TODO 该先做”需要人判断。这是有意的:扫描器只负责把散落的信息汇总,不替用户做决定。

下一篇离开开发场景,讲两个更靠近“人”的插件:一个决定什么时候弹窗,一个决定什么时候闭嘴。

本文阅读--次|全站访问--次|访客--人