发布

推送 v* tag 会触发 .github/workflows/publish.yml，它会发布 npm 包并创建对应的 GitHub Release。

VS Code 扩展（hover-dev）是分发形态。它通过 pnpm --filter hover-dev package（→ 一个 .vsix）完成构建、引擎暂存与打包，然后发布到 VS Code Marketplace（发布者 hyperyond）——本地的 .vsix 用于开发测试的旁加载。它不属于下面的 npm tag 推送工作流。

每次发布交付什么（npm）

@hover-dev/mcp（编写交付面）和 @hover-dev/core（它所依托的引擎）在 v* tag 上锁步发布。（旧的打包器插件包与探测包已被移除；此前发布的版本作为历史产物仍留在 registry 上。）所有带作用域的包都归于 @hover-dev npm org（public access）。

切出一次发布

1. 把所有要发布的 PR 合入 main。main 必须始终可运行——上面的每个提交都应让 pnpm typecheck + pnpm test 保持完好。

2. 确认本地 pnpm build 干净，且相关的手动端到端通过。

3. 用带注解的消息打 tag（该消息会成为 GitHub Release 正文的开头部分）：

   git tag -a v0.16.0 -m "v0.16.0 — Claude Code hooks
   
   - hover-hook: SessionStart / UserPromptSubmit / Stop wiring
   - Cloud heal-queue context injected into the session preface
   - …"
   git push --tags
   

4. tag 推送触发工作流。它会：

   • 在 CI 中重新安装依赖。
   • 从 tag 解析出版本号（v0.7.0 → 0.7.0）。
   • 通过 npm version --no-git-tag-version 就地改写每个可发布的 package.json。
   • 运行 pnpm typecheck + pnpm test 作为发布关卡。
   • 构建每个包。
   • 用 --access public 把每个包发布到 npm。
   • 打包相同的 tarball 并附加到一个 GitHub Release。

如果工作流失败

对所有已经拉取过的人来说，tag 是不可变的。不要重新打 tag——而是重新触发：

gh workflow run publish.yml --ref v0.7.0 -f version=0.7.0

--ref 会检出该 tag 所对应的提交（而不是移动中的默认分支 HEAD）。工作流正是为这种情况设置了 workflow_dispatch 输入。手动重跑时不会重新创建 Release（工作流的 if: startsWith(github.ref, 'refs/tags/') 关卡会跳过它）；如果原本在 Release 步骤之前就失败了，用 gh release create 手动创建。

版本策略

1.0 之前我们采用主题式 patch：v0.6.x = 语音模式，v0.7.x = 安全测试，v0.8.x = 源码归因（Vue/Svelte/Astro），v0.9.x = 挂件插件 UI 协议，v0.10.x = 多标签页 + agent 扩展（cursor-agent/aider/gemini-cli/qwen-code），v0.11.x = spec 韧性（重录 + 会话保存），v0.12.x = 安全 spec 录制，v0.13.x = 录制/回放一致性（可见性前奏 + 录制初始 page.goto + 可选 reload）。严格的 SemVer 从 v1.0.0 开始生效。参见路线图。

权限

工作流用到：

• NPM_TOKEN —— 对 @hover-dev/* 具备读+写权限的细粒度自动化 token。设在仓库 secrets 中。
• GITHUB_TOKEN —— 自动注入，由 softprops/action-gh-release 用于创建 Release。

绝不使用 --no-verify，绝不改动 git config，绝不向 main 强推。钩子必须保持绿色。