1. 这个超能力到底是什么Superpowers 的核心定位先说结论Superpowers 是 VS Code 扩展市场里一个专注于TODO待办事项管理的开源插件。它的核心功能是把你散落在代码注释里的 TODO、FIXME、HACK、BUG 等标记集中抓取并展示在一个独立的侧边栏面板中还附带优先级分组、进度视图、评论串联等功能。我第一次在 Hacker News 上看到这个项目时第一反应是这不就是另一个 Todo Tree 吗。但实际装上用了两周之后我发现它的设计思路和主流 TODO 插件有本质区别。Todo Tree 的核心逻辑是扫描匹配它把注释里的 TODO 全部列出来以文本列表形式呈现你能看到每一条出现在哪个文件哪一行而 Superpowers 的核心逻辑是项目管理它把 TODO 视为一个个需要被排序、跟踪、验收的任务单元通过优先级分组和处理状态来驱动你的日常工作流。换句话说Todo Tree 是一张任务清单Superpowers 是一个轻量级的任务看板。对于需要在多个项目、多类任务之间切换的开发者来说这种任务管理视角比文本扫描视角实用得多。适合谁用这个问题我实际操作下来觉得有三类人收益最大个人项目维护者一个人维护多个仓库经常在不同仓库里修修补补需要一个全局视角把握所有任务的轻重缓急。前端/全栈开发者代码里往往同时存在待实现功能待修复样式 bug待优化性能等多种标记Superpowers 的优先级分组能帮你一眼定位该先处理哪一类。团队协作场景中的代码审查者Superpowers 可以把评论和 TODO 关联起来相当于在代码里维护一个极简的协作讨论区审查者可以直接在 TODO 上挂反馈。我目前的工作流里Superpowers 主要用于两个场景一是快速理解陌生仓库里遗留的未完成事项二是把自己开发中的 TODO 按紧急程度排序避免全是 TODO 等于没有 TODO。2. 安装、界面布局与核心概念2.1 两分钟完成安装并验证安装非常简单VS Code 扩展市场里直接搜索 Superpowers发布者署名是 SvenAppel点击 Install 即可。我建议安装后顺手做一件事打开命令面板CtrlShiftP输入 Reload Window重载一下窗口确保插件激活。安装完成后你会在左侧活动栏看到一个新的拳头图标Superpowers 的 Logo 就是一只发光拳头。点击后Superpowers 面板就会打开。首次打开时如果你当前项目里还没有任何 TODO 标记面板会显示一条空状态提示——还没有 TODO开始添加吧之类。这里有个细节Superpowers 默认只扫描/src、/lib、/app等几个常见源码目录而不是扫描整个项目根目录。如果你的代码放在projects/、packages/这类自定义目录下可能扫不到。此时需要打开设置项手动添加目录白名单。我稍后在配置部分详细讲。安装验证方法很简单在任意 JS/TS/Python 文件里写一行// TODO: 测试一下 Superpowers侧边栏应该立刻出现这条记录。如果你用的是 Todo Tree 或别的同类插件两者面板可以同时存在互不冲突但同名高亮可能有覆盖问题建议实际使用时二选一开启。2.2 界面布局四个核心区域Superpowers 面板可以拆成四个区域来理解搜索/筛选栏位于面板顶部支持按文本内容模糊搜索也支持按优先级过滤。这个搜索是即时的快捷键是面板内的输入框聚焦后直接打字没有额外快捷键。任务列表区核心区域展示所有捕获到的 TODO。每一行展示任务文本、优先级标记如高优、中优、低优、关联文件路径。行内右侧有操作按钮可以快速标记已完成或正在处理。进度指示区在面板底部或顶部展示当前项目里总任务数、已完成数、完成百分比。这是个很直观的健康度指标。评论/详情区点击某个任务后右侧或底部展开详情显示任务所在文件的完整上下文、关联评论列表以及一个文本输入框可以直接输入 Markdown 格式的评论。这四个区域布局紧凑信息密度比较高刚上手可能会觉得有点挤。习惯之后你会发现它其实是一个极简版 Jira但完全在编辑器内部工作不需要切窗口不需要加载网页零延迟响应。2.3 三个核心概念优先级、状态、评论Superpowers 的管理能力建立在三个基础概念上全部通过注释语法来定义优先级Priority决定任务在列表中的排序权重。有 high 和 low 两个显式等级加上不标任何优先级时的 normal普通等级一共三档。语法是在 TODO 后面用[priority: high]之类的标签声明。状态Status标记任务当前处于什么阶段。支持in_progress进行中、done已完成、unfinished未完成等状态。同样通过注释标签声明。评论Comments允许你在 TODO 代码位置附近添加多条评论形成小型讨论串。适合记录某任务的前因后果、做法思路、验收意见。这三个概念组合起来就能支撑一个非常完整的工作流创建一个 TODO 时标注优先级开始处理时标记为in_progress过程中通过评论记录进展完成时标记为done。整个生命周期都在代码注释里完成不跳出编辑器所有信息跟着代码仓库走团队成员拉取代码后也能看到完整上下文。3. 适用场景与方案选型为什么我不直接用 Todo Tree3.1 场景一快速评估陌生项目的工作量接手一个不熟悉的老项目时我最想知道的不是架构文档而是这个仓库里还有多少没干完的活。用 Todo Tree 能看到一个长长的列表但那个列表没有优先级排序没有完成状态看完之后你的内心os通常是哦有 200 个 TODO然后呢。Superpowers 不一样它在扫描后直接把任务按优先级分好了组红色高优组是阻塞性任务或者上线前必须处理的黄色普通组是一般待办绿色低优组是优化项/备选项。配合完成进度百分比你能非常直观地判断出这个仓库的成熟度如果 80% 的任务都已完成说明项目接近可交付状态如果 90% 都是进行中或高优先级说明这个项目还在快速迭代期接手时要预留大量时间处理遗留事项。这个信息在做技术方案评估、工时预估时非常有用比对着 README 猜半天靠谱得多。3.2 场景二对比 Todo Tree 的关键差异我确实认真对比过 Todo Tree 和 Superpowers大概列了个差异表对比维度SuperpowersTodo Tree核心定位任务管理看板文本扫描清单优先级分组内置三档优先级标签依赖正则匹配无显式优先级任务状态可标记进行中/已完成无状态管理评论系统内置 Markdown 评论功能无界面复杂度较高信息密度大简单直接学习成本需掌握标签语法零学习成本独有特性按目录/文件全局视角、进度统计自定义标记类型更灵活单从记录待办这个动作来看Todo Tree 确实更简单装完就用。但如果你需要知道哪些任务卡住了哪些快完成了Superpowers 的价值就体现出来了。Todo Tree 的列表永远是静态的你无法在清单里表达这件事我已经做了一半Superpowers 可以做这件事。还有一个细节差异值得提Todo Tree 默认会扫描node_modules等第三方依赖目录默认排除 pattern 需要手动配而 Superpowers 初始只扫描明确定义的源码目录范围。这意味着用 Superpowers 梳理出的任务列表通常更干净几乎不会有第三方库里的噪声干扰比如不会把某个包内部注释里的 FIXME 混进你的任务列表。3.3 场景三配合 GitHub 工作流的日常使用我做个人项目时习惯配合 GitHub 的 issue 和 PR 流程使用 Superpowers。逻辑非常顺写代码时发现问题不想打断思路直接在代码里写// TODO: 修复 xx 边界条件标注高优做完一个功能块在提交信息里带上相关的 TODO 编号代码和任务天然关联提 PR 时Superpowers 里done的任务就是本次 PR 的完成清单未完成的in_progress则是下一轮迭代的入口。由于所有任务信息都在代码文件里PR 的 diff 天然包含了任务演进的完整轨迹。团队成员 review 代码时能看到某处注释从todo变为done的提交记录——这比在 PR 描述里手写本次改动如下更有说服力因为任务上下文就在代码旁边。4. 核心语法与配置指南从标签语法到工作流4.1 TODO 标记的标准语法与项目结构Superpowers 默认识别的标记类型基本覆盖了主流代码注释习惯TODO、FIXME、HACK、BUG、IDEA、NOTE、REVIEW。每种标记可以用不同颜色高亮显示方便在代码里扫视时一眼区分类型。我测试过它在 JavaScript、TypeScript、Python、Java、Go、Rust、C/C 等主流语言里的表现都能正常识别行注释和块注释中的标记。对于 Vue 单文件组件.vue、Svelte.svelte、甚至 Markdown 文件里的!-- TODO --也能正确捕获。标准语法长这样// TODO: 重构这段逻辑抽出公共函数 // FIXME: 组件卸载时有内存泄漏风险 // BUG: 移动端布局在 iOS 14 以下错乱 // HACK: 临时方案等后端接口稳定后移除 // IDEA: 未来可考虑用 Web Worker 优化计算 // NOTE: 这个魔数 86400 代表一天的秒数 // REVIEW: 确认这段代码是否符合团队规范4.2 优先级与状态的标签语法规则这里是最容易踩坑的部分我需要重点讲清楚语法细节。优先级标签是放在任务文本末尾的格式是方括号包络、priority 为键、值与键之间用冒号冒号隔开// TODO: 修复表格组件排序功能 [priority: high] // TODO: 补充表单校验逻辑 [priority: low] // FIXME: 首屏白屏时间过长需要做性能优化 [priority: high]不写[priority: xx]标签的任务自动归为普通优先级normal排在 high 之后、low 之前。状态标签语法同理// TODO: 实现用户注册接口 [status: in_progress] // TODO: 接入支付回调 [status: done]这里有个细节状态标签和优先级标签可以在同一条 TODO 里共存顺序任意。比如// TODO: 重构鉴权中间件 [priority: high] [status: done]多个标签之间用空格分隔即可。还要注意一旦你给某条 TODO 加了[status: done]标签它就默认从主任务列表的未完成任务分区中消失会被自动归入已完成分区。如果你没有开启显示已完成任务选项它甚至不显示在主面板里。初次使用的人很容易产生我写的 TODO 怎么丢了的困惑实际只是被归入已完成状态了。解决办法是在面板筛选栏里选择All包含已完成任务。4.3 完整的任务生命周期示例拿一个真实的例子演示一下完整流程假设我要给博客项目增加一个搜索功能第一步创建任务标注优先级// TODO: 给博客增加全文搜索功能 [priority: high] // 搜索范围文章标题、正文、标签 // 方案暂定用 lunr.js 做客户端索引后续如数据量增大再考虑服务端搜索这里我在标准 TODO 行下面追加了两行辅助注释Superpowers 会把这些后续行识别为任务的备注/描述仅当它们紧邻 TODO 行且没有其他代码行间隔时才生效。所以想要写描述文本时要紧跟 TODO 行换行写。第二步开始处理标记状态// TODO: 给博客增加全文搜索功能 [priority: high] [status: in_progress]面板里这一行会显示为进行中状态高优先级排序仍然排在最前面进度百分比也会相应变化。第三步完成标记 done// TODO: 给博客增加全文搜索功能 [priority: high] [status: done]这一步完成后如果开了隐藏已完成任务这行注释就在面板里消失了但代码里的注释依然完整保留。我的习惯是保留这些done注释理由有两个一是它们在代码库中留下了演进痕迹二是万一功能回退或需要修复这些注释能快速告诉你当初的实现意图。4.4 关键配置项逐一说明Superpowers 的设置在 VS Code 设置界面搜索 Superpowers 就能看到全部分组我用过的核心项如下{ // 指定需要扫描哪些子目录注意这里的路径相对于项目根目录 superpowers.foldersToScan: [src, lib, components, utils], // 排除的目录/文件避免扫描构建产物 superpowers.excludeFolders: [dist, build, node_modules, .next], // 是否默认隐藏已完成任务对于个人整理习惯来说设为 false 更直观 superpowers.showCompletedIssues: false, // 是否开启编辑器内的行内装饰注释颜色高亮等 superpowers.editorLineHighlights: true }foldersToScan是大多数人必须改的一项。默认值里没有src以外的常见目录如果你用的是 monorepo 结构比如packages/web/src路径可能根本不生效。这时要写相对路径比如packages/web/src这样。改完配置文件后面板不会自动刷新需要手动点击一下面板顶部的刷新按钮或者重载窗口。showCompletedIssues我建议个人项目设成false因为完成任务太多时反而干扰视线但到了项目收尾或 code review 阶段可以临时设成true或直接切到 All 筛选快速过一遍所有遗留事项。还有一个不太起眼但很实用的设置自动补全标签的快捷键——CtrlShiftP打开命令面板输入 Superpowers: Add TODO with Priority它会自动在当前光标位置生成一条带标准模板的 TODO 注释省去手写[priority: xx]的麻烦也避免标签格式写错导致不生效的问题。4.5 给新手的入门建议如果你刚开始尝试这种任务即代码的工作方式建议先做几件事找一个自己有感情线的小项目比如自己维护的博客主题或一个练手的工具脚本把里面所有TODO加上合理的优先级标签不必强行加状态标签开着侧边栏正常工作两天观察自己看到高优任务时的下意识反应——如果你看完立刻就想动手处理说明这种方式对你有用如果你完全没感觉那说明它跟你的工作流不匹配不必强上。不要一上来就追求把任务状态管理体系堆满。我见过不少同事把一条// TODO: 修 bug写成了带四个标签、三条评论的半页注释结果代码可读性严重下降。在代码注释里维护任务本质是给后来的读者包括几周后的自己降低理解成本而不是制造信息负担。保持简洁永远是第一原则。5. 常见问题与排查技巧实录5.1 插件不显示任何任务这是最常遇到的问题。先从三个方向排查确认标记文本是否完全匹配Superpowers 默认只识别大写的TODO和FIXME等如果你写的是Todo或todo全小写它不会识别。早期版本甚至对TODO:后面的空格和冒号有严格要求。检查一下你的注释是否用了规范格式。确认文件路径是否在扫描范围内检查foldersToScan配置把你的源码目录填进去。如果是 monorepo确认没有把路径写错层级。确认插件是否真的激活了点击侧边栏 Superpowers 图标看面板是不是空白状态而非报错状态。如果面板完全加载不出来多半是扩展本身与现代 VS Code 版本存在兼容问题去扩展页面更新一下或用兼容模式运行。还有一种隐蔽情况本地多个版本 VS Code 共存旧版本的全局状态污染导致插件读取到了旧的且空白的缓存数据。清一下~/.config/Code/User/workspaceStorageLinux/Mac 路径Windows 在%APPDATA%\Code\User\workspaceStorage下的对应缓存目录基本上就能解决。5.2 标签语法正确但任务未分组有读者反馈[priority: high]写了但面板里没按高优显示我排查后发现他的写法是// TODO: 修复问题 [priority high]注意等于号是不被识别的必须用冒号:分隔且priority全小写high全小写。如果是[Priority: High]这种大小写混写同样失败。标签体系是大小写敏感的请严格按[priority: high]这个模板来写。5.3 高亮颜色与编辑器主题冲突Superpowers 会对注释中的关键标签加颜色高亮但如果你用的主题对注释文本颜色做了强覆盖比如某些高对比度主题高亮可能会失效看起来跟普通注释没两样。解决办法是在设置里调整superpowers.editorLineHighlights的色值或者干脆把行内高亮关掉靠侧边栏面板来追踪任务。Figma 设计工具里有一个很有意思的插件叫 Figma Chat它让你在画板元素上直接添加评论进行讨论避免在设计稿和即时通讯之间来回切换。Superpowers 的思路跟它相似让你在代码画布上进行上下文讨论。5.4 TODO 被吞掉已完成任务不显示这个现象我前面提过但值得单列一条给任务加上[status: done]后默认情况下它会从主列表消失。如果你找不到了不是被吞了是被已完成筛选过滤了。在面板顶部的筛选器里找到 Completed 相关选项勾选显示已完成任务即可。如果你的真实需求其实是删掉这条 TODO 记录那标记done并不是删除。想要从列表里彻底移除直接把注释从代码里删掉就行——Superpowers 是实时监听代码文件的注释没了任务自然消失。5.5 多仓库开发场景的心得我同时开了三个仓库一个工作项目、两个开源项目的时候发现直接切仓库看 Superpowers 面板会出现信息残留——上一次仓库的任务还挂在面板里当前仓库的反而没刷新。解决方法是每次切仓库后手动点一下刷新按钮面板顶部的循环箭头图标。这个按钮是监听目录切换事件的但某些远程开发或特殊工作区模式下事件可能不触发手动刷新最可靠。在 monorepo 或 workspace 场景下我建议把foldersToScan指向到具体包目录而不要指向 workspace 根否则扫描范围过大面板列表会非常长反而失去聚焦待办的意义。视觉上比较舒服的上限大概是单个项目 30~50 条任务超过这个量就该考虑拆分任务或清理陈旧标记了。6. 进阶技巧把 Superpowers 用出真正超能力的野路子6.1 给团队做一次注释任务规范Superpowers 的语法其实非常简单但为了让团队所有成员在同一个仓库里互不干扰又信息互通可以定几条规范提交代码前凡是带[status: in_progress]的 TODO必须带上一条评论说明卡在什么地方新开任务默认给[priority: normal]只有明确阻塞开发或必须在近期上线前完成的任务才给[priority: high]。优先级太泛滥高优列表就跟普通列表没区别了done状态的注释保留三个版本周期后再清理方便回溯演进过程。这种规范不需要上什么协作工具写进仓库里的 CONTRIBUTING.md 即可配合 VS Code 的 workspace 配置.vscode/settings.json统一团队成员的foldersToScan、showCompletedIssues设置协作体验会搞得非常顺畅。6.2 双插件协作Superpowers 任务管理工具Superpowers 本身不提供同步到 Jira/Trello这类外部集成能力但可以做一个轻量桥接在 Superpowers 里以[priority: high]标记一个重要任务旁边的评论里写明Jira 编号 #1234。然后靠CtrlShiftP→ Superpowers: Copy Link 之类的命令复制该任务的行链接贴进 Jira ticket 里。这样两边都能互相跳转虽然没有一键同步那么优雅但已经能解决开发者在代码和项目管理工具间来回切换的主要痛点。如果你真的想做成半自动同步可以写一个简短的 Node.js 脚本用 VS Code 的扩展 API 读取某个目录下的 Superpowers 数据文件解析出任务清单然后通过 git commit hook 做检查本地有未处理的高优 TODO 时不允许合入主干分支。思路非常简单但实际效果非常强——相当于把任务纪律下沉到了代码提交环节。6.3 用它做学习计划和日常待办它不是只能管理代码任务本质上就是一套任意文本文件里的可标注待办系统。我尝试过在notes/目录下面用 Markdown 文件维护每日学习计划# 2024-06-13 学习计划 - [ ] 学习 Rust 所有权机制 [priority: high] [status: in_progress] - [ ] Rust 生命周期章节配套练习 [priority: low] - [ ] 整理昨天的 Rust 知识点笔记 [status: done]由于我在foldersToScan里加了notes目录这些学习任务也能直接出现在 Superpowers 面板里。它的 markdown 语法兼容性不错但我测试过更复杂的任务列表嵌套时偶尔会丢失缩进层级所以学习笔记里我尽量保持扁平列表结构不嵌套二级三级列表。实测下来非常香——我的编辑器变成了一个统一的今日工作学习仪表盘代码里的开发任务和笔记里的学习任务都在同一个侧边栏里优先级一目了然。看整体的任务完成比例成就感直接拉满。6.4 规则当死的人当活的最后必须说一点反方意见Superpowers 这套任务标签化管理的方法不是对所有项目、所有开发者都适用。代码里应不应该写 TODO 是有争议的有人觉得上下文需要靠代码表达有人坚持TODO 全部进 issue tracker代码注释只保留思路性说明。我个人的取舍标准是长期开源项目里尽量少留[priority: low]的 TODO因为这种任务很可能永远没人做注释却一直在那边误导读者。低优任务更合适的归宿是 GitHub issue 的 backlog不要堆在代码里当数字遗产。我的做法是以周为粒度每周五花 15 分钟把这一周的 TODO 过一遍done的保留、low的迁到 issue、已无价值的直接删除注释。这个习惯帮我维护的项目干净了很多。7. 在实际项目里的典型使用案例复盘我在一个中小型开源项目里一个 Markdown 博客工具主代码量约八千行 TypeScript实际用 Superpowers 管理了两个迭代周期。第一个迭代开始时我在foldersToScan里添加了[src, test]然后把仓库里所有历史遗留的 TODO 都扫了出来。一共有 47 个任务其中高优 7 个、普通 24 个、低优 16 个。绝大多数是早期开发留的临时注释。我按优先级处理第一周把所有高优任务全部清理干净其中 5 个真的需要改代码2 个属于当时留错了直接删注释。处理高优任务时我习惯用[status: in_progress]标记这样面板里显示正在处理中周末复盘时能清楚地看出哪些任务已经动过手、哪些只是开了个头。第二迭代开始之前我专门要求自己新 TODO 必须写优先级标签。两周下来新增了 31 个任务全部带标签。因为标签可以帮助后续 backlog 梳理。到迭代末高优清零普通完成 12 个低优剩余 14 个。这 14 个低优任务我逐条审视后删掉 6 个内容过时或意义不大剩余 8 条转为 GitHub issue代码注释里不再保留。整个过程代码改动量不多但项目的任务视角清爽了很多。涉及并行任务的场景也值得一提我曾经同时在三个分支上开发一个加新功能、一个修容器化部署 bug、一个重构核心类。没有 Superpowers 时切分支后我经常想不起来当前分支进行到一半的事项用了之后每个 TODO 上的in_progress状态就是每个分支的现场记录切回来扫一眼面板就知道该从哪继续确实省了不少捡起上下文的时间。我还在一次代码 review 中发现了一个特别好的用法reviewer 直接在代码里加评论 TODO标注[priority: medium]Superpowers 里普通优先级在排序中等显示在列表中间并写明修改意见完事之后在评论里 作者。作者下次打开面板时一眼就能看到代码里还有 2 条 review 意见待处理。这个流程比在聊天工具里翻记录靠谱多了因为所有信息都和代码文件绑定永远不会丢。评论里其实不需要 也能实现因为评论本身就挂在对应的 TODO 上面。我个人的实际操作体会是Superpowers 这套体系的真正价值在于让待办事项跟着代码库走而不是脱离代码单独存在。所有你看过的代码总有一部分是实现完的、一部分是有心无力的、一部分是卡住不知道该怎么办的。给这些状态一个显式的标签和位置比把它们默默留在注释里发霉要健康得多。它不会替你做决策也不会神奇地把项目变好但它会帮你把不知道从哪里下手的焦虑变成一条条可以被勾掉的进度。我踩过的最大的坑就是刚从 Todo Tree 切换过来时反复在任务消失了和格式错了之间打转但一旦把标签语法和面板筛选逻辑搞清楚它就成了我编辑器里最有存在感的一个侧边栏。如果你也刚好需要给散落在代码里的待办建立秩序建议装一个试一周把工作流的对比体会写下来再决定留不留。