TODO 看板
收集项目中的 TODO / FIXME / NOTE 注释,在 VS Code / Trae CN 侧边面板中分组展示、筛选、搜索、跳转与标记完成。
功能
- 活动栏独立面板,按
TODO / FIXME / NOTE 分组,分组标题带条数
- 条目显示注释正文,右侧显示
文件路径:行号,点击直接跳转到代码行
- 每条前有复选框,可标记完成 / 取消完成
- 工具栏支持:刷新、按类型筛选(多选)、按完成状态筛选(全部 / 未完成 / 已完成)、关键词搜索、清除所有完成标记
- 面板顶部显示统计:
共 N 条 · 已完成 M 条;没有结果时显示"未找到 TODO / FIXME / NOTE 注释"
- 修改
todoBoard.* 配置后自动重新扫描
支持的注释格式
匹配 行首注释(允许前置空白),以下 5 种写法均可识别:
| 注释写法 |
典型语言 |
示例 |
// # -- ; % 行注释 |
JS / TS / Python / Shell / SQL / Lua |
// TODO: 补充参数校验 |
/* ... */、/** ... */ 单行块注释 |
C / CSS / JS |
/* FIXME: 重构 */ |
<!-- ... --> |
HTML / XML / Vue 模板 |
<!-- NOTE: 临时方案 --> |
* TODO 多行块注释内部 |
JSDoc / JavaDoc |
* TODO: 补全文档 |
{ TODO } |
模板语法 |
{ FIXME: 待优化 } |
规则说明:
- 不区分大小写:
TODO、todo、Todo 都能被识别,展示时统一转为大写
- 类型后的冒号可有可无:
// TODO xxx 与 // TODO: xxx 等价
- 类型与后续单词之间必须是词边界,
TODOs、TODOList 这类不会命中
- 一行最多命中一条注释
字符串占位值(默认开启)
todoBoard.matchValues 默认为 true,形如「字段值就是待办标记」的写法会被收集,条目标题显示字段名:
"test": "todo",
test = 'TODO',
const status = 'TODO';
会刻意避开以下容易误报的场景:
if (status === 'TODO') {} // 比较运算,不命中
case 'TODO': // switch 分支,不命中
type Status = 'TODO' | 'FIXME' // 联合类型,不命中
const list = ['TODO'] // 数组元素,不命中
已知限制
- 只匹配行首注释。行尾注释(如
const a = 1; // TODO: xxx)不会被收集
- 字符串占位值只支持键值对/赋值形式(
key: "TODO"、key = 'TODO'、带 const/let 等修饰符的声明),数组元素与函数返回值不在此列
- 不会自动监听文件变化。新增或修改注释后,需点击面板工具栏的刷新按钮
- 完成状态保存在工作区状态中(不是写回代码文件),条目唯一标识为
相对路径#L行号。因此在被标记的注释上方增删代码导致行号变化后,完成标记会失效
安装
扩展需 VS Code ^1.85.0(Trae CN 当前版本满足要求)。
方式一:本地调试(F5)
在项目根目录用 VS Code / Trae CN 打开本仓库,按 F5,会启动一个扩展开发宿主窗口,左侧活动栏出现 TODO 看板图标。
依赖仓库内的调试配置:
.vscode/launch.json:type 为 extensionHost,--extensionDevelopmentPath 指向当前工作区
.vscode/tasks.json:启动前自动执行 pnpm run compile
方式二:打包 VSIX 后安装
node scripts/package.js
脚本会先编译 TypeScript,再生成 todo-board-<版本>.vsix(零依赖,不依赖 vsce)。
安装时注意:code --install-extension 只会装到 VS Code 目录(~/.vscode/extensions),Trae CN 读取的是自己的目录(~/.trae-cn/extensions),两者不共用。
- VS Code:
Ctrl+Shift+P → Extensions: Install from VSIX... → 选择生成的 .vsix
- Trae CN:同样菜单操作,或使用下面的方式三
方式三:一键编译并安装(推荐给 Trae CN)
node scripts/install-trae.js
脚本会编译 TypeScript,并把扩展分别复制到:
| 目标 |
目录 |
| Trae CN |
%USERPROFILE%\.trae-cn\extensions\<publisher>.<name>-<version> |
| Trae |
%USERPROFILE%\.trae\extensions\...(不存在则跳过) |
| VS Code |
%USERPROFILE%\.vscode\extensions\... |
安装完成后需完全退出并重启 IDE(仅 Reload Window 不够),图标才会出现。
使用
- 打开任意项目文件夹(扩展是全局安装的,所有项目通用)
- 点击左侧活动栏的 TODO 看板 图标
- 面板自动扫描当前工作区并分组展示
工具栏按钮说明:
| 按钮 |
作用 |
| 刷新 |
重新扫描工作区 |
| 筛选注释类型 |
多选 TODO / FIXME / NOTE |
| 筛选完成状态 |
全部 / 未完成 / 已完成 |
| 关键词搜索 |
匹配注释正文、文件路径、原始行,输入留空则清除筛选 |
| 清除所有完成标记 |
一次性清空该工作区的完成记录 |
条目上的操作:勾选复选框切换完成状态;点击条目跳转到对应代码行。
配置
在被扫描的项目根目录创建 .vscode/settings.json(也可以写在用户设置里全局生效):
{
// 要扫描的文件(glob,默认全部)
"todoBoard.include": [
"src/**/*.ts",
"src/**/*.tsx",
"src/**/*.vue"
],
// 扫描时排除的路径。注意:显式设置会整体覆盖默认值,需把要保留的默认项一起写上
"todoBoard.exclude": [
"**/node_modules/**",
"**/.git/**",
"**/dist/**",
"**/build/**",
"**/out/**",
"**/coverage/**",
"**/*.min.js",
"**/package-lock.json",
"**/pnpm-lock.yaml",
"**/yarn.lock",
"**/.next/**",
"**/test/**"
],
// 要收集的注释类型(枚举值必须大写)
"todoBoard.types": ["TODO", "FIXME"],
// 是否把字符串占位值("key": "todo")也识别为待办(默认开启)
"todoBoard.matchValues": true
}
| 配置项 |
类型 |
默认值 |
todoBoard.include |
string[] |
["**/*"] |
todoBoard.exclude |
string[] |
["**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**", "**/*.min.js", "**/package-lock.json", "**/pnpm-lock.yaml", "**/yarn.lock"] |
todoBoard.types |
("TODO" \| "FIXME" \| "NOTE")[] |
["TODO", "FIXME", "NOTE"] |
todoBoard.matchValues |
boolean |
true |
注意:todoBoard.types 的取值会被转换为大写后与配置比对,必须写大写,否则对应类型不会显示。
开发
pnpm install # 安装依赖
pnpm run compile # 编译 TypeScript 到 out/
pnpm run watch # 监听编译
node scripts/package.js # 打包 VSIX
node scripts/install-trae.js # 编译并安装到本地 IDE 扩展目录
源码结构:
| 文件 |
职责 |
src/extension.ts |
扩展入口,创建树视图、注册命令、监听配置变更 |
src/scanner.ts |
扫描工作区文件,正则匹配注释并解析出待办条目 |
src/todoProvider.ts |
树数据提供者:分组、筛选、搜索、完成标记持久化 |
src/todoItem.ts |
数据模型与类型定义 |
源码改动后,package.js 与 install-trae.js 都会先自动编译,无需手动执行 pnpm run compile。
License
MIT