# 发布手册

发布目标：供 Pi 使用的包 `@yedan1122/brb`。当前候选版本 `0.1.0-beta.3`，许可证 MIT。

当前状态为 PUBLISHED_BETA：`0.1.0-beta.0` 首发，`0.1.0-beta.1` 修文档，`0.1.0-beta.2` 修 README 图片渲染；候选 `0.1.0-beta.3` 加 `pi-package` 关键字（Pi Gallery 发现机制）。各版本均在 npm（dist-tag `beta`）。公开发布证据见 `docs/internal/evidence/RELEASE-20260924-NPM-BETA0.md`（不在包内）。再发布时应升 `0.1.0-beta.N` 并重跑本文门禁。

> 每次发布前都要重新生成发布审计。仓库根目录中已有的 `.tgz` 文件不能证明当前 HEAD 的发布内容。
>
> `files` 白名单包含 `docs/`。`docs/internal/.npmignore` 使用 `*` 排除内部资产。以本次 `npm pack --dry-run` 的文件清单为准。

npm 身份与发布操作由你在自己的终端完成；自动化流程不读取 npm token。

## 发布前检查

```bash
npm test
npm pack --dry-run
```

`npm test` 必须全绿。检查 `npm pack --dry-run` 的输出。Pi extension 所需的 `src/` 和公开包文件必须包含在内。`docs/internal/**` 与 `tmp/**` 必须为零匹配。

## 发布 beta

先确认 npm 身份，再发布 beta。

```bash
npm login && npm whoami
npm publish --access public --tag beta
```

`npm whoami` 应显示 `yedan1122`。发布目标固定为 `@yedan1122/brb`。

## Pi clean-room 验收

发布后，在不引用仓库 checkout 的干净环境里运行：

```text
pi install npm:@yedan1122/brb@beta
pi list
/brb status
/brb doctor
/brb setup
pi update @yedan1122/brb
pi remove @yedan1122/brb
```

验收通过的条件是：包已注册为 extension；`status`、`doctor` 和首次使用引导能够如实反映环境；安装、更新和卸载均可正常使用。真实 ChatGPT 行为需要独立取证。

## Pi Catalog 验证

发布后访问 https://pi.dev/packages/@yedan1122/brb。确认 extension 类型、metadata、README、许可证和安装命令正确。

## 发布门禁

- [ ] clean-room 安装通过。
- [ ] 双语 README、发布文档和 Pi 使用方式一致。
- [ ] SECURITY.md 已完成。
- [ ] npm tarball 人工审计未发现 BUGS、AGENTS、HANDOFF、内部裁决、私有会话 id、真实路径或凭据。
- [ ] 至少一次非开发环境真实安装。
- [ ] beta 不泄漏 credential 或 state。
- [ ] BUGS、内部裁决和开发日志已与公开内容分离。

## 版本节奏

**版本号（SemVer）**

| 阶段 | 版本形式 | 说明 |
| --- | --- | --- |
| beta | `0.1.0-beta.N` | 每发一次 +1；仅修缺陷与文档，不带新功能 |
| 稳定 | `0.1.0` | Beta 反馈与缺陷修正闭环后发布 |
| 之后 | `0.1.x` / `0.2.0` | patch = 修缺陷；minor = 新功能（1.0 前允许破坏性变更，但必须在 CHANGELOG 里写明） |

**已发布的版本号永不重用、永不覆盖。** 需要修正已发布版本时，发下一个 `beta.N`。

**dist-tag 策略**

- `beta` → 最新 beta；beta 期文档统一写 `pi install npm:@yedan1122/brb@beta`。
- `latest` → 推荐安装版。没有稳定版时指向最新 beta；发布 `0.1.0` 后用
  `npm dist-tag add @yedan1122/brb@0.1.0 latest` 指过去，稳定期文档改为不带标签的安装命令。

**一次发布的固定步骤**（顺序执行，每步都有可核对的产物）

1. 改 `package.json` 的 `version`，并同步两个 README 的 `<!-- fact:version=… -->`
   —— 门禁 `DOC-GATE-08` 强制两者与 manifest 一致，写错即红。
2. 写 `CHANGELOG.md` 条目（这次改了什么、为什么不改别的）。
3. 检查公开文档的状态句：不得再出现过期的“未发布/即将发布”陈述
   —— 门禁 `DOC-GATE-04` 负责这条。
4. 跑门禁：`npm test`（全绿）、`npm run test:docs`、`npm pack --dry-run`
   （文件清单里 `docs/internal/**` 与 `tmp/**` 必须零匹配）。
5. commit + push（先提交再发布，已发布产物必须能对应到某个 commit）。
6. 建一个**短期 granular token（勾选 bypass 2FA）**，用环境变量发布，**发布后立即吊销**：

   ```bash
   NPM_CONFIG_//registry.npmjs.org/:_authToken=<TOKEN> npm publish --access public --tag beta
   ```

7. 核验（不重试发布）：`npm view @yedan1122/brb dist-tags`、拉 tarball 检查 README 与文件数、
   在**隔离 home** 里跑一次 `pi install npm:@yedan1122/brb@beta`。
   新版本元数据可能有几分钟延迟；只读核对，不要重发（规则 PUB-5：结果不明不重试）。
8. `git tag vX.Y.Z` + `gh release create`（仅在 npm 侧确认可安装之后）。
9. 把本次发布的实测事实（HTTP 码、dist-tags、clean-room 结果、延迟窗口）写进
   `docs/internal/evidence/RELEASE-<日期>-*.md`。

**1.0.0 前的门槛**：Beta 用户反馈与缺陷修正的闭环必须完成；`docs/internal/BUGS.md` 里
不得留有未处理的产品缺陷。