装完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，本质上没什么区别。
