Release

Tellux 发版助手

把当前 dev 分支上的改动打包成一个新版本，发布到 npm + GitHub Release。

• 准备（助手可跑）：actions/release.js — check / bump / changelog / commit / annotated tag
• publish（必须用户本机手动）：pnpm publish — npm 需浏览器跳转或密钥验证，助手禁止代跑
• 收尾（用户 publish 成功后助手再跑）：actions/release-finish.js — push tag + GitHub Release

本 skill 负责前置准备（撰写发版摘要）+ 编排 + 兜底。

何时使用

用户要做以下任何一件事时启用：

• "发版"、"发布新版本"、"release 一下"、"publish tellux"、"cut a release"
• 升 patch / minor / major 版本号

补建历史版本的 Release 见文末「补建历史 Release」，不走下面的主流程。

前置条件（先全部满足，否则停下告诉用户）

1. 分支与工作区：在 dev 分支，且 git status 干净。release.js 开头会校验，不干净直接退出。若有未提交改动，让用户先 commit 或 stash——不要替用户提交无关改动。
2. 包管理器：必须 pnpm。npm pack/npm publish 会因 pnpm 符号链接 node_modules 触发 arborist 崩溃（Cannot read properties of null），打包发布都必须走 pnpm。
3. gh CLI：已 gh auth login 且 gh repo set-default cyanfish-x/tellux。收尾建 GitHub Release 依赖它；缺失只会告警，不影响 npm 发布与 tag 推送，但 Release 要后补。
4. npm registry：本机默认 registry 可能是 npmmirror；publish 必须显式指定 https://registry.npmjs.org/。

主流程

1. 确认版本类型

patch / minor / major。可从 commit 推断建议（有 feat: → minor；只有 fix:/refactor: → patch；有 !: 破坏性 → major），但发版不可逆，必须向用户确认后再继续。

2. 撰写发版摘要（hybrid 模式核心）

generate-changelog.js 会从 commit 自动生成 ### Added/Changed/Fixed 清单，但缺重点。发版前先在 CHANGELOG.md 的 ## [Unreleased] 下写一段摘要，发版时它会成为版本段开头，GitHub Release 点进去先看到摘要。

起草：

git describe --tags --abbrev=0                    # 上一版本 tag，如 v0.1.8
git log v0.1.8..HEAD --pretty=format:"%h %s"      # 该 tag 到 HEAD 的 commit（含 merge，勿只过滤 feat/fix）

基于这些 commit 归纳 3-5 条主题级亮点（不是逐条罗列），写入 ## [Unreleased] 下。格式硬性要求：

• 散文或 - bullet 均可，不要用 ### 标题（会被 generate-changelog.js 误判为「全手写」而不追加自动清单）。
• 突出用户视角的主题（如「高性能 HISM 渲染」「统一拾取与高亮」），不复述实现细节。
• 可用 **粗体** 标主题词便于扫读。
• 扫 commit 时不要只看 feat:/fix:：merge: 或无前缀的合入说明也可能是大特性（例如 HISM），漏掉会严重失真。

参考写法：

## [Unreleased]

本版本重点：

- **高性能 HISM 渲染**：合入 HISM 实例化渲染能力，并支持单实例后处理描边高亮。
- **统一拾取与高亮**：收敛为 `pick` / `pickAll` API，落地统一高亮能力。

3. 提交摘要（让工作区回到干净）

把上一步起草的摘要展示给用户确认后：

git add CHANGELOG.md
git commit -m "docs(changelog): 补充发版摘要"

必须先提交摘要，否则 release.js 的干净工作区校验会失败。

4. 执行发版准备（到 tag 为止）

node actions/release.js <type>     # patch | minor | major

release.js 依次：pnpm release:check → 升版本号 → 生成 changelog（保留上一步摘要并追加自动分类清单）→ commit + annotated tag，然后退出并打印手动 publish 命令。

中途若 release:check 失败（类型/构建/打包），修完重跑。

此时不要代跑 pnpm publish / git push / GitHub Release。

5. 用户手动 publish（硬性规则）

助手禁止执行 pnpm publish / npm publish。原因：npm 账号发布需要浏览器跳转或密钥验证，非交互环境无法完成。

向用户给出确切命令并等待其确认「已发布」或「继续」：

pnpm publish --no-git-checks --registry https://registry.npmjs.org/

说明：

• 必须加 --registry https://registry.npmjs.org/（避免打到 npmmirror）。
• --no-git-checks：tag/commit 尚未 push，需跳过 pnpm 对未推送 commit 的拦截。
• 用户在本机终端跑，以便弹出浏览器完成验证。

6. 收尾（用户 publish 成功之后）

确认 npm 已有新版本后再执行：

node actions/release-finish.js <新版本>   # git push --follow-tags + GitHub Release

或等价拆开：

git push --follow-tags
node actions/github-release.js <新版本>

若 GitHub Release 失败（gh 没装/没登录），npm 包与 tag 推送仍可成功，按告警补：

gh auth login && gh repo set-default cyanfish-x/tellux
node actions/github-release.js <新版本>

7. 确认

npm view tellux version --registry https://registry.npmjs.org/   # 应为新版本号
gh release view v<新版本>                                         # 确认 notes 带摘要

半途恢复（准备已完成、publish 或收尾未做）

若本地已有 chore(release): 发布 vX.Y.Z 与 vX.Y.Z tag，不要重跑 release.js（会再次升版本）。按缺口补：

1. 用户尚未 publish → 只让用户跑第 5 步命令。
2. npm 已发布、尚未 push/Release → 直接跑第 6 步 release-finish.js。

补建历史 Release

为已存在 tag 的旧版本补建 GitHub Release（不重发 npm）：

git push origin v<版本>                            # 先确保 tag 在远端
node actions/github-release.js <版本> --no-latest  # --no-latest 避免抢占最新版 Latest 徽章

notes 取自 CHANGELOG 对应版本段；已有 Release 则更新，可反复重跑。给已有版本补摘要：直接编辑 CHANGELOG 该版本段顶部加摘要，再跑一次 node actions/github-release.js <版本> 更新 notes。

关键坑点

• publish 必须用户本机手动跑，助手禁止代跑（浏览器 / 密钥验证）。
• 必须 pnpm，不能用 npm（arborist 崩溃）。
• publish 必须 --registry https://registry.npmjs.org/，否则可能打到 npmmirror 并鉴权失败。
• 必须 annotated tag：release.js 用 git tag -a；轻量 tag 不会被 git push --follow-tags 推送（历史上的 v0.1.4/5/6/8 曾因此漏推）。
• pnpm publish --no-git-checks：发版在 push 之前，需跳过 pnpm 对未推送 commit 的拦截。
• commit message 遵守 Conventional Commits（feat:/fix:/refactor: 等）：generate-changelog.js 按此归类，不规范的会被跳过而不进 changelog；写「版本重点」摘要时仍要阅读 merge / 无前缀 commit，避免漏掉大特性。