/os-release

name: os-release
description: 发布 AI Team OS 新版本的完整清单——预检、版本七处锁步、中英双语 CHANGELOG、双份 dist 构建、私有术语扫描、commit/tag、双仓推送、建 GitHub Release 条目并核对 latest 徽章、事后核对。当准备发版、补建漏掉的 Release 条目、或核对已发版本的线上状态时使用。

OS Release — 发版清单

为什么有这份清单

机检管得住的部分不用你记，跑一条命令即可。这份清单只管**机检管不住的部分**，以及 **谁按哪个按钮**。

历史上同型漏项两次：**tag 推了、GitHub Release 条目没建**，访客主页的 latest 徽章 因此卡在旧版本两周。所以别把"tag 推完"当成发版完成——第 10 步才是。

执行分工（硬约束：发布流水线必须可中断）

| 步骤 | 谁执行 | | --- | --- | | 1–6 准备与校验 | Leader 全权 | | 7 commit · 8 tag | Leader 执行，但**先把 `git diff --stat` 与拟好的 message 交用户批准** | | 9 双仓推送 · 10 建 Release 条目 | **用户执行**。Leader 只把命令准备好打印出来 | | 11 事后核对 | Leader（只读） |

不要代替用户 push / publish，也不要在未批准前 commit。

---

1. 预检全绿

bash scripts/preflight.sh          # 发版必须跑全量，不要 --fast

五道门禁：`ruff check src/ tests/` → `dashboard npm run lint` → 前端实时事件回归 （`npm --prefix dashboard test`）→ `check_invariants.sh` → `pytest tests/unit/`。 **机检条目数以脚本输出为准**，别在别处写死范围。

preflight 不含、发版仍要跑的两项：`pytest tests/integration/` 全过； `uvx --from build pyproject-build` 产出 .whl 与 .tar.gz 无错（不往系统安装 build； 已有 build 的环境也可用 `python -m build`），再运行 `python3 scripts/check_sdist_contents.py dist/ai_team_os-*.tar.gz` 检查实际归档成员。 它拒绝本地 Python 环境、node_modules 与开发缓存/构建产物，并确认安装、源码、测试及 `plugin/dashboard-dist` 关键分发文件仍在，同时输出压缩字节数与成员数供核对；构建成功或 体积正常均不能代替内容门禁。

失败长这样：每项后面跟 `✗ <门禁名> 失败`，末尾 `✗ 预检未通过 — 修复后再 push`。 退出码非 0。

两处**既定豁免**：

• 未构建 `dashboard/dist` 的环境里 I3 输出 `⚠️ dist 目录缺失（未构建环境可忽略）`

——警告不拦。但发版必须构建（见第 4 步），所以发版时这条不该还是警告。

• I16 在 execpolicy rules 或 Codex 二进制缺席时输出 `⚠️ [I16] Codex execpolicy（...）`

——本期是占位状态，warn 不拦。它转成 ok 的那一天要留意：那意味着这台机器上真的跑了 一次宿主校验，结论才有分量。

**用户生命周期验收**（每次发版都做）：新装一次、从上一个已发布版本更新一次，分别确认 更新后的代码、已安装的适配器、配置与运行中的服务实际生效；写明哪些变化自动生效、哪些 要重启或重新授信、哪些要用户显式启用。开发机上已应用、源码测试通过，都代替不了这一步。

Codex 装机面的严格对账也在这一步：每轮安装（新装、更新）完成后、打 tag 之前，跑

python3 scripts/check_codex_installed_hooks.py   # 验收用的是隔离 Codex 目录时加 --codex-home <该目录>

退出码必须为 0。漂移或仅装侧即退出码 1，先查清是没装上还是装侧被改过，不许带红打 tag。 check_invariants 里的 I28 只警告（用户 2026-10-16 裁定，任务 00a77472：提交前工作区必然 领先于安装），这里是它的严格版。输出 `[WARN] 本机没有 Codex 侧已安装副本` 表示这台机器没装 Codex 适配器，验收记录里要写明「未验 Codex 装机面」，不能当作通过。

2. 版本锁步七处

**I2 机检的五处**（漂移即红，`❌ [I2] 版本号漂移: ...`）：

• `pyproject.toml`
• `src/aiteam/__init__.py`
• `plugin/.claude-plugin/plugin.json`
• `plugin/.claude-plugin/marketplace.json`
• `.claude-plugin/marketplace.json`

**另两处由 I6 第①类硬等式盯**：`README.md` 与 `README.zh-CN.md` 的 announcement 行 （`> ⚡` 开头）必须含 `v<新版本>`，否则 `❌ [I6] README 数字漂移`。

**机检不覆盖、必须人眼看的**：`plugin/.claude-plugin/plugin.json` 里 `description` 文本中的数字（MCP 工具数、生命周期事件数）。v1.11.1 那次人审抓到的唯一实锤就在这里 ——两处数字腐烂了整整一个版本。

README 里的其余数字（工具数/页面数/端点数/测试数）由 I6 对照实测校验，**按实测改， 不要按记忆改**。

3. CHANGELOG 中英双语同步

• 英文 `CHANGELOG.md` 加新版本段，标题格式 `## [x.y.z] - YYYY-MM-DD`。
• 中文 `CHANGELOG.zh-CN.md` **同步全译**。用户 2026-07-30 裁定：中文版维持**镜像

全译契约**——不是摘要，也不退役。

• 段落内容按 `git log` 与设计文档**逐条取证**写成，不照抄计划（计划里没做成的东西

写进 CHANGELOG 就是假账）。

这一步**没有机检**，是本清单里最容易再烂的一环：中文版曾从 1.9.0 起停更 6 个版本 （1.10.0 → 1.11.1），07-30 才回补。写完后自查一遍两个文件的版本段集合是否相同。

4. dashboard 双份 dist 构建一致（I3）

cd dashboard && npm run build && cd ..
rm -rf plugin/dashboard-dist
cp -R dashboard/dist plugin/dashboard-dist

I3 的失败提示就是上面这三步，顺序不能省：**先重建**——机检只比两份产物（JS/CSS 文件名、 index.html 与它引用的资源），判不出哪边新，也判不出两份一样旧， 0914 主 checkout 本地 `dashboard/dist` 反而比跟踪面旧两天，直接拷贝会把新包盖成旧包； **先 `rm -rf` 再 `cp`**——目标目录已存在时 `cp -R` 会在里面套一层 `dist/`，且 bundle 文件名带 hash，旧文件不会被覆盖，会作为过期产物留在分发包里。

失败长这样：`❌ [I3] dashboard/dist 与 plugin/dashboard-dist 不是同一次构建，或 index.html 引用了不存在的资源`， 下面逐行列出不一致的文件名或缺失的资源。

`plugin/dashboard-dist/` 是 marketplace 用户拿到的那份产物——它必须与本批前端源码 **同一个 commit 产出**。

5. 私有术语关键词扫描（四个面）

**词表不写在这里**：把禁用词表写进即将发布的仓库，等于把要防的东西发布出去。执行前用 `memory_search` 拉方向层那条防泄记忆（检索词「私有术语防泄」）取当期词表。

四个面：

PREV=v<上一个版本>
git log --format='%h %B' $PREV..HEAD      # ① 本批全部 commit message
git diff $PREV..HEAD                      # ② 本批触及的全部跟踪文件内容
git diff --name-status $PREV..HEAD        # ③ 本批新增/改名的文件路径本身

④ **即将写下的 release commit message 自身**——写完先扫一遍再提交。这一面最容易漏， 因为它在 git 里还不存在。

**测试与夹具不是豁免区**。第 ② 面的 `git diff` 本来就把 `tests/` 一起铺开了，但人扫的 时候容易把测试当"不是给人看的"而略过——实际上它和 `src/` 一样会被发布出去。尤其是 **模型型号代号**：测试里为了"像真的"随手写一个型号代号，和写进生产代码没有区别。造 夹具那条链上已有现成形制可抄（`scripts/redact_codex_fixture.py` 把学到的型号统一映射成 `codex-model-<x>`），新写的用例照抄中性占位即可，不必也不该写真代号。

命中即停：树面脱敏后重来。实录（批 9）：一个 agent 把私有设计文档名与内部术语写进 `types.py`、`hook_translator.py`、测试注释和 commit message，靠人工扫描抓获，最终 需要用户授权重写历史才归零。发版扫描是**最后一道闸**，第一道闸在派工 prompt 里。

6. 开发版/分发版同步人审

`src/` 是开发版，`plugin/` 是分发版。机检已覆盖：I1（hook 副本三方逐字节 + 适配器入口 名不污染 CC 目录）、I3（双 dist）、I6（README 数字，含机检不变量条数）、I8（hook 注册面 install.py ↔ hooks.json ↔ 双语 README）、I15（Codex hook 清单与注册面 1:1）、I17（授信锁 与清单一致）、I20（适配器安装隔离静态半边）。

**机检覆盖之外，逐条人眼过**：

• `plugin/.mcp.json` 有没有版本引用
• `install.py` 有没有内嵌版本号
• `plugin/.claude-plugin/plugin.json` 的 `description` 文本里的数字（见第 2 步）
• `plugin/dashboard-dist/` 是否与前端源码同 commit 产出：bundle 里有没有本批新页面的

代码、`index.html` 引用的 bundle 名与 `assets/` 里的实际文件名一致

• 新增了 skill / agent 模板 / commands？`install.py` 走目录遍历（`copy_skills` 等），

加目录不需要改代码，但要确认目录名与 frontmatter 的 `name` 一致

• 用户级 `agents/*.md`（Claude Code 配置目录下，`aiteam paths` 可查）与 `plugin/agents/*.md` 是否同步
• 启动时跑的 backfill / 迁移在新库、老库、迁到一半的库上都幂等（`COLUMNS_TO_ENSURE` 式补列）

6b. Codex 面产物人审

这一批的四条都**不是机检能替的**：机检能证明清单自洽，证明不了这次改动对用户机器意味 着什么。本批 `plugin/harness/codex/` 有任何改动就逐条走一遍。

• **新增/改动的 handler 是不是 takeover**。`kind` 在 `surface.py` 里显式声明：

`observe` 只记录，不做权限判断、不改写输入、不用非零退出码拦人；`takeover` 可以 deny 或改写。把一个 takeover 混进来而不说，等于在用户不知情的情况下改变了他能执行 的动作范围。逐条确认 `kind` 与脚本实际行为一致，Release notes 里点名列出。

• **`hook-trust.lock` 变了就必须写授信提示**，且**按入口分列**：CLI 与 TUI 走 `/hooks`

重新授信，Desktop 走「设置 → 编码 → 钩子」。授信键钉在组序号与 handler 序号上， 所以在中间插一条会让它后面每一条静默失信——用户那边没有任何提示，只是从此不再触发。 漏写这句话的代价不是报错，是一批钩子安静地死掉。

**清单不用自己算**：机检 I17b（`scripts/check_codex_trust_drift.py`）拿 `hook-trust.baseline.lock`（上次发布面 = 用户已授信的那份）对账当前锁，直接打印 「新增待授信」名单，粘进 Release notes 即可；出现「槽位复用」它直接红，那种改动不该 发出去（把改动挪到该事件尾部，或拆两批发）。**发布后推进基线**：

  python3 scripts/check_codex_trust_drift.py --advance   # 再把 released_version 改成本版号

不推进的后果是下一版的对账基准停在旧版本