agent-insight 发布指南（团队维护者版）
本文给被授权的维护者，说明如何把
agent-insight打包并发布到 npm。 默认流程：先--dry-run打包 → 本机验证 → 再发布同一个 tarball（npm publish不可逆，验证别跳过）。
0. TL;DR（已配好 token 的老手）
默认是「先验证、再发布」三步（详见 §4）：
# 1) 构建 + 打包，但不发布 → 产出 agent-insight-<版本>.tgz
node scripts/publish-npm.js --version 0.1.0-beta --dry-run
# 2) 本机装这个 tarball 冒烟验证（必做）：起服务 → 首页 200/307 → 关服务
# 3) 验证通过后，发布「刚测过的同一个 tarball」
npm publish ./agent-insight-0.1.0-beta.tgz --tag latest --registry https://registry.npmjs.org/
嫌麻烦也可以一把梭：
node scripts/publish-npm.js --version 0.1.0-beta --tag latest（脚本自动 build+pack 再发）。但这样跳过了本机验证、且发的不是你测过的那个产物，仅建议小改动 / 很有把握时用。
1. 谁能发布
发布权限由 npm 的「包 owner 列表」控制（agent-insight 是不带 scope 的包）。
- 现有 owner 把你加进来：
npm owner add <你的npm用户名> agent-insight - 查看当前 owner：
npm owner ls agent-insight - 移除：
npm owner rm <用户名> agent-insight
注意：不带 scope 的包，所有 owner 权限平等，任何 owner 都能加/踢别人。仅限可信团队。
2. 新维护者一次性配置（4 步）
- 被加成 owner（让现有 owner 执行
npm owner add <你> agent-insight） - 注册 npm 账号（如果还没有）：https://www.npmjs.com/signup
- 生成 Automation token（会绕过 2FA，适合脚本发布）：
npmjs.com → 右上头像 → Access Tokens → Generate New Token → Classic Token → 选 Automation → Generate → 复制（
npm_开头） - 写进你的
~/.npmrc（绝不要提交到仓库）：echo "//registry.npmjs.org/:_authToken=npm_你的token" >> ~/.npmrcnpm whoami --registry https://registry.npmjs.org/ # 打印你的用户名即 OK
这行 token 是「针对 npmjs.org 官方源的认证」，不会影响你默认的国内镜像（平时装包照样快）。
3. 发布命令与参数
node scripts/publish-npm.js [options]
| 参数 | 说明 |
|---|---|
--version <版本> |
指定确切版本，如 0.1.0-beta、1.0.0 |
--type patch|minor|major |
自动递增版本（与 --version 二选一） |
--prerelease alpha|beta|rc |
配合 --type 加预发布后缀 |
--tag <tag> |
npm dist-tag，默认 latest |
--dry-run |
只打包不发布（强烈建议先跑） |
版本号约定
- 我们的版本号带
-beta后缀（如0.1.0-beta），但仍发到latest，因为它就是对外的当前版本。 - ✅ 正确：
--version 0.1.0-beta --tag latest - ⚠️ 迭代时往上加版本号（npm 版本不可变，不能覆盖）：
0.1.0-beta → 0.1.1-beta → 0.2.0-beta ... - 如果只是内部灰度、不想动
latest，才用--tag beta（用户需npx agent-insight@beta才能拿到）。
4. 标准发布流程（构建 → 验证 → 发布 → 复验）
npm publish基本不可逆（72 小时后自己删不掉），所以本机验证是必经步骤，不是可选项。
第 1 步：构建 + 打包（不发布）
先清掉旧的 Next.js 构建产物，避免 npm pack 把上一次的 .next/standalone 打进包里：
rm -rf .next
node scripts/publish-npm.js --version 0.1.0-beta --dry-run
完整 npm ci + build + 组装裁剪 standalone + npm pack，产出 agent-insight-<版本>.tgz，不上传。
第 2 步：本机验证（必做）
包内容自查：
ls -lh agent-insight-*.tgz # 体积正常约 30~35MB
tar -tzf agent-insight-*.tgz | grep -c 'standalone/exclude/' # 应为 0
tar -tzf agent-insight-*.tgz | grep -c 'standalone/data/' # 应为 0
tar -tzf agent-insight-*.tgz | grep -c 'standalone/skills/agent-debug-diagnosis/SKILL.md' # 应为 1
装这个 tarball 跑一遍冒烟测试：
mkdir -p /tmp/ai-verify && cd /tmp/ai-verify && npm init -y
npm install /绝对路径/agent-insight-<版本>.tgz # 触发 postinstall（prisma/sharp 自愈）
npx agent-insight start --port 3000 # 起服务
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/ # 期望 200 或 307
npx agent-insight stop --port 3000 # 关服务
cd - && rm -rf /tmp/ai-verify
最小通过标准（全绿才发布）：
- [ ]（跨平台发布时）在另一个 OS（mac / linux / windows）重复装一遍验证
第 3 步：发布「你刚测过的同一个 tarball」（推荐）
npm publish ./agent-insight-<版本>.tgz --tag latest --registry https://registry.npmjs.org/
直接发第 1 步产出、第 2 步验证过的那个文件——「测的」和「发的」零偏差，不会重新 build 出另一个产物。
备选：
node scripts/publish-npm.js --version <版本> --tag latest也能发，但它会重新 build 一遍，发出去的不是你刚测的那个 tarball（构建虽确定，严格说不是同一产物）。
第 4 步：发布后线上复验
npm view agent-insight version dist-tags --registry https://registry.npmjs.org/
npx agent-insight@<版本> start # 从 npm 真实拉取再跑一遍
6. 常见报错排查
| 现象 | 原因 / 解决 |
|---|---|
❌ Not authenticated to the npm registry |
没配 token。按 §2 配 Automation token 到 ~/.npmrc（脚本会在 build 前就提示，不会白等） |
npm ci 报 ENOTEMPTY: rmdir ...node_modules |
npm 清理旧依赖偶发问题。先 rm -rf node_modules 再重跑脚本 |
You cannot publish over the previously published versions |
该版本号已发过，npm 版本不可变。改用更高版本号 |
| 发布卡在国内镜像 / 403 | 脚本已钉死 --registry https://registry.npmjs.org/，无需改全局；若仍异常，确认 ~/.npmrc 没把 registry 覆盖成只读镜像 |
预发布版本发不上 latest |
npm 拒绝把预发布版静默发到 latest。脚本已自动显式带 --tag；手动发 tarball 也要带全：npm publish ./agent-insight-<版本>.tgz --tag latest --registry https://registry.npmjs.org/ |
| 想撤销刚发的版本 | 72 小时内可删：npm unpublish agent-insight@<版本> --registry https://registry.npmjs.org/；超 72h 自己删不了（联系 npm support）。迭代请 bump 版本号，别靠删 |
7. 关于包内容（背景知识）
- 采用 Next.js standalone 模式打包，包内含运行时所需依赖，体积约 30~35MB。
- 本地/临时目录不会进包：
exclude/（本地临时文件）、data/（用户数据/数据库）、tests/、skillbench/等由prepack钩子自动剔除——无论谁、用什么方式打包都生效，所以不同人打出的包大小一致。 - 跨平台：包默认带打包机平台的原生二进制（sharp、Prisma 引擎），用户
npm install时由postinstall按其自身平台自愈（需联网）。因此 mac/linux/windows 打的包都能在各平台安装运行。
8. 用户侧使用（供 README/对外文档参考）
# 安装并一键部署（装包 + 起服务 + 建 Key + 配 opencode/Claude 遥测 + 加 skill）
npx agent-insight install
# 或者分步
npm install agent-insight
npx agent-insight start # http://localhost:3000
npx agent-insight stop
npx agent-insight status
agent-insight install的一键流程需要包已发布到latest；前提是用户机器有 Node 20+，要测 opencode 上报还需用户已装并配置好 opencode。