core: Skill for Claude Code

Publish to npm

1. 集中预检与版本处理

• 集中检查 Git 状态、server 版本、npm whoami、registry dist-tags 和目标版本是否已存在，记录发布前的 latest。若上一次发布记录为「registry 可见性待确认」，先查清那次的版本是否已落库，再决定本次版本号，避免撞号。
• 用户明确要求“新 beta”时，递增当前 beta 系列的序号，并与 registry 核对；不再询问 patch/minor/major。新系列或升级范围不明确时才询问。明确版本号优先；转正式版去掉 prerelease 后缀。
• 更新 packages/server/package.json 的版本。发布前必须提交版本变更并保持源码工作区干净；需要 Git 提交授权时在此一次询问，已有明确授权则不重复问。
• 记录构建所用的提交 SHA。不要假设 npm 会自动写入 gitHead，来源追溯使用提交 SHA、安装包 integrity 和验证记录。

2. 按变更选择验证等级

比较上一次完整冒烟通过的提交与本次提交，不能只检查未提交 diff，也不能把 npm beta 标签自动视为验证基线。基线来自可信的发版任务记录或 CI 结果，包含提交、验证环境和结果；找不到基线、基线不适用或影响不明时走完整验证。

等级	条件	必做验证
快速 beta	仅 UI/业务逻辑调整，生产依赖与安装链路未变，有适用的完整验证基线	构建、包内容检查、相关回归测试；可省略全新全局安装
完整验证	生产依赖/相关锁文件、打包脚本、postinstall、Prisma、原生模块、Pi/ACP 或 CLI 启动链路变化；或无可信基线	快速检查 + 最终 tarball 的隔离全局安装冒烟
正式版	非 prerelease 发布	完整验证 + macOS、Windows、Linux 安装和 CLI 启动验证

• 比较 package.json 时忽略纯 version 变化；锁文件改动无法确认仅影响开发依赖时按完整验证处理。
• 快速验证不等价于新机器安装验证，不能在后续发布中充当完整基线；定期完整验证或用户要求完整检查时不得走快速模式。
• cloudflared 的真实首次下载检查仅在相关依赖/下载逻辑变化、正式版或定期完整检查时执行，不随每个 beta 重复联网下载。

3. 构建、打包一次并复用

从仓库根目录执行：

pnpm build:publish
npm pack ./packages/server/publish --json --pack-destination ./packages/server/publish > ./packages/server/publish/pack-result.json

从 pack-result.json 读取 filename、version、integrity 和 files，后续检查、安装、发布和交付均复用这一个 tarball。不要额外运行 npm pack --dry-run，不要从目录再次发布，也不要为了交付重新打包。已有有效 tarball 时，安装/发布网络失败不触发重新打包；产物内容修改后则必须重新构建、打包和验证。

构建前置条件：build-publish.mjs 要求 packages/server/prebuilds/linux-x64 与 linux-arm64 下都有进程域 supervisor agent-tower-scope（Linux 用户靠它避免整机进程表采样）。脚本会自动尝试构建，依次使用 zig cc（brew install zig，可交叉编译两种架构）、宿主 cc、Docker（alpine）。没有任何工具链时构建失败；面向单一已知主机的 beta 可用 AGENT_TOWER_SCOPE_HELPER_TARGETS=linux-x64 缩小要求；只有明确接受 Linux 退回兼容后端时才设置 AGENT_TOWER_ALLOW_MISSING_SCOPE_HELPER=1，两种情况都要在汇报中说明。

包内容检查保留以下不变量：

• CLI/MCP 入口、前端和 Prisma schema 齐全，版本正确，不夹带 .env、数据库或发布机运行数据。
• prebuilds/linux-x64/agent-tower-scope 与 prebuilds/linux-arm64/agent-tower-scope 存在且可执行（--probe 输出 "subreaper":true）。
• bundled @prisma/client 移除 generate/postinstall 和可选 prisma peer；普通 dependency 的 Prisma CLI 与 Client 精确同版本，由根 postinstall 唯一生成本机 Client。包内不含 node_modules/prisma 或预生成的 node_modules/.prisma。
• Pi 的完整运行时依赖树和 node-pty 多平台 prebuilds 齐全；cloudflared 仅包含无 postinstall 的 JS wrapper，不含 node_modules/cloudflared/bin。