Stepsize插件需登录GitHub账户、绑定仓库并提交.stepsize/annotations/文件才能实现技术债协同追踪，否则仅是本地TODO；PR中需含@stepsize或卡片ID才触发自动关联。
Stepsize 插件不能只装完就完事——它必须和团队的 GitHub 仓库、PR 流程、甚至 .stepsize/config.json 配置联动，否则只会变成个人 TODO 列表，起不到技术债协同追踪作用。
Stepsize 安装后为什么右键没出现“Add Technical Debt”选项？
常见错误现象是插件已启用，但编辑器里找不到任何 Stepsize 相关菜单或命令。根本原因通常是：未登录 Stepsize 账户，或当前工作区未关联有效项目。
- 安装插件后必须点击状态栏右下角的
Stepsize图标，用 GitHub 登录（不支持邮箱直登） - 登录后需手动选择一个已连接的 GitHub 仓库——它会从你有权限的私有/公开 repo 中列出可绑定项目
- 如果列表为空，请检查 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 没本质区别。
