VSCode安装Stepsize插件 团队开发必备VSCode追踪技术债

装完Stepsize插件就万事大吉了？别急着下结论。这件事儿，必须开门见山地说清楚：它必须和团队的GitHub仓库、PR流程，甚至.stepsize/config.json配置深度联动，否则充其量只能算个个人TODO列表，根本谈不上什么技术债协同追踪。

Stepsize 安装后为什么右键没出现“Add Technical Debt”选项？

一个相当常见的翻车场景是：插件明明已经启用，但编辑器里却死活找不到任何Stepsize相关的菜单或命令。这背后的原因其实很简单——要么没登录Stepsize账户，要么当前工作区压根没关联上有效项目。

• 安装完成后，必须点击状态栏右下角的Stepsize图标，用GitHub账号登录（注意，不支持邮箱直登）
• 登录后，还需要手动选择一个已连接的GitHub仓库——系统会从你有权限的私有或公开仓库中，列出可绑定的项目
• 如果列表为空，不妨检查一下GitHub Token权限，看是否包含了repo和read:org（Stepsize官方文档明确要求这两项）
• 另外，确认VSCode当前打开的是该仓库的根目录，而不是某个子文件夹，否则插件无法识别上下文

如何让团队成员看到同一处技术债标记？

Stepsize的技术债条目默认只存本地，要共享就必须显式提交到Git，并且依赖.stepsize/目录下的元数据文件。这不是自动行为，需要手动操作。

• 添加技术债后，VSCode会在当前文件同级生成.stepsize/annotations/xxx.json文件，内容包含位置、描述、严重等级等信息
• 这个文件必须被git add并提交——否则队友拉代码后，完全看不到你标的内容
• 建议在.gitignore中排除.stepsize/cache/，但保留.stepsize/annotations/和.stepsize/config.json
• 配置文件里可以设置"defaultSeverity": "medium"等统一规则，避免每个人各自定义，导致筛选混乱

在 PR 中自动关联技术债卡片要满足哪些条件？

Stepsize的PR自动检测功能其实挺容易失效的。关键不在插件本身，而在于GitHub webhook和仓库设置。

• 必须在Stepsize Web控制台中为该仓库开启Enable pull request detection
• GitHub那边，需要确认仓库的Settings > Webhooks里存在Stepsize的有效endpoint（通常会自动配置，但有时会被防火墙拦截）
• PR描述中必须包含@stepsize或明确引用TD-123这类卡片ID，光写“待重构”这种纯文字，是触发不了的
• 如果PR已经合入，但技术债没有自动关闭，需要手动在Stepsize Web页面上点击Resolve——它不会根据代码是否合并来更新状态

最容易被忽略的一点是：Stepsize本身不分析代码语义，它只记录你打标的位置和描述。所谓“追踪技术债”，实际上靠的是人对位置的共识，加上提交的持久化，以及PR场景下的显式引用。如果没有这三层绑定，它和随手写的// TODO: refactor this，本质上没什么区别。