# 自动发布闸门实现说明

## 当前状态

自动发布闸门采用 fail-closed 设计。机器目录从 `production-release-guardian.md` 加载并校验 187 个连续、唯一场景编号；执行器不能把没有实现、没有执行或没有证据的场景视为成功。

已经实现：

- `release-gate/catalog.mjs`：187 场景机器目录和永远不可豁免清单。
- `release-gate/safety.mjs`：拒绝生产 IP、`*.tkmind.cn`、生产路径和生产关联环境变量。
- `release-gate/artifact.mjs`：runtime 排序目录树 SHA256、依赖闭包和持久数据扫描。
- `release-gate/runner.mjs`：suite 执行、日志归档和失败关闭。
- `release-gate/report.mjs`：`report.json`、Markdown、JUnit、环境指纹及四小时有效期。
- `release-gate/regression-corpus.mjs`：脱敏生产回归 fixture 和 active manifest 校验。
- `scripts/verify-release-gate-report.mjs`：校验完整 `main` SHA、artifact SHA、187 项状态和合法豁免。
- `scripts/release-portal-runtime-prod.sh`：任何 103 连接或上传之前强制验证 Gate report。

当前已经有自动判定证据的场景如下。这里的“覆盖”必须同时满足
`release-gate/coverage.mjs` 中逐场景的业务断言；仅仅执行过一个通用测试文件不能计入。

| 场景组 | 已自动判定 | 总数 | 已覆盖编号 |
|---|---:|---:|---|
| REL | 11 | 11 | REL-01 至 REL-11 |
| AUTH | 8 | 8 | AUTH-01 至 AUTH-08 |
| CHAT | 15 | 15 | CHAT-01 至 CHAT-15 |
| MEM | 16 | 16 | MEM-01 至 MEM-16 |
| FILE | 8 | 8 | FILE-01 至 FILE-08 |
| IMGPG | 8 | 8 | IMGPG-01 至 IMGPG-08 |
| XLS | 12 | 12 | XLS-01 至 XLS-12 |
| PAGE | 13 | 13 | PAGE-01 至 PAGE-13 |
| DATA | 13 | 13 | DATA-01 至 DATA-13 |
| SEARCH | 8 | 8 | SEARCH-01 至 SEARCH-08 |
| AGENT | 11 | 11 | AGENT-01 至 AGENT-11 |
| SCHED | 5 | 5 | SCHED-01 至 SCHED-05 |
| WX | 13 | 13 | WX-01 至 WX-13 |
| BILL | 7 | 7 | BILL-01 至 BILL-07 |
| MS | 9 | 9 | MS-01 至 MS-09 |
| PLAZA | 5 | 5 | PLAZA-01 至 PLAZA-05 |
| CFG | 8 | 8 | CFG-01 至 CFG-08 |
| UI | 8 | 8 | UI-01 至 UI-08 |
| COMP | 9 | 9 | COMP-01 至 COMP-09 |
| **合计** | **187** | **187** | 184 个 suite 映射，加 REL-01/REL-02/REL-04 三项直接检查 |

`REL-03` 会比较候选和两次干净重建的排序目录树 SHA256；`REL-06`、`REL-07`
分别执行生产配置冷启动和脱敏旧库升级，并断言运行前后 artifact 哈希不变；`REL-11`
在无网络 Linux ARM64 容器中实际加载 Portal、WeChat、worker 和每个 MCP 模块。

全部 187 项都已有自动判定路径，未执行的 mode 仍保持 `unknown`。UI-01 至 UI-08
在隔离本地 Portal、390×844 移动视口和公开页 fixture 上运行；COMP-09 由独立执行器
要求 active 脱敏回归 manifest 并逐条回放。没有 manifest 时 COMP-09 明确 `failed`，
不会因“没有用例”而通过。`REL-02` 只在候选等于 `origin/main` 且 CI 注入
`MEMIND_RELEASE_CI_STATUS=success` 时通过。

2026-07-26 本地补齐验证中，历史完整报告为 180/187 通过；`REL-01` 因当前仍在功能
分支且工作区不干净而失败。PAGE-01/02 与 DATA-01/02/03/04 的隔离栈现在使用后台
直连 LLM（`custom_deepseek` / `deepseek-v4-pro`），关闭 relay bootstrap，并将代码/技能
根与隔离数据根分离，避免技能目录为空导致普通用户丢失 `static_publish` 工具。页面发布
约束也明确要求 `sandbox-fs__write_file/edit_file` 命名空间，避免模型误调用不存在的裸工具。
修复后的真实 Agent 回归仍需在最新 runtime 上完成全 6 项终态断言；在此之前不能伪装成通过，
也不能标记为合法 `not_applicable`。生产发布继续禁止。

## 本地命令

先运行框架单元测试：

```bash
npm run test:release-gate:unit
```

构建候选 runtime 后运行完整闸门：

```bash
npm run build:portal-runtime
npm run test:release-gate:all -- --artifact .runtime/portal
```

完整报告路径：

```text
.release-gate/<full-main-sha>/report.json
```

单层执行结果存放在：

```text
.release-gate/<full-main-sha>/partials/<mode>/
```

只验证已有完整报告与当前 artifact：

```bash
npm run verify:release-gate-report -- --artifact .runtime/portal
```

### 耗时控制

完整覆盖不等于 187 条都等待在线 Agent 串行执行：

- 业务规则、权限、账务、记忆、文件和交付契约优先做成确定性 fixture/replay，随
  `deterministic` 模式并行执行。
- Gate 执行器默认同时运行 4 个独立 suite，可通过
  `--suite-concurrency` 或 `RELEASE_GATE_SUITE_CONCURRENCY` 在 1～16 之间调整；
  每个 suite 仍写独立日志并单独判定。
- 必须验证真实 Agent 的场景按不同 session 并行；Page Data 场景默认并发 4，
  单个 Agent 步骤上限 300 秒、子进程总上限 360 秒。超时直接失败，不允许无限等待。
- 可用 `RELEASE_GATE_SCENARIO_CONCURRENCY`、
  `RELEASE_GATE_SCENARIO_TIMEOUT_MS` 和
  `RELEASE_GATE_SCENARIO_PROCESS_TIMEOUT_MS` 在 CI 资源范围内收紧预算，不得用它们
  放宽为无限超时。
- 完整闸门只为干净 `main` 的精确 commit + artifact 生成一次四小时有效报告；
  发布脚本复用并校验这份报告，不重复跑慢场景。commit、artifact 或环境指纹变化后
  证据立即失效并重新执行。
- 本地开发先跑相关确定性 suite；只有形成发布候选时才聚合全部 187 项。任何未执行、
  超时或缺证据项仍保持 `unknown/failed` 并阻断发布。

报告出现以下任意状态都会返回非零：

- `failed`
- `skipped`
- `blocked`
- `unknown`
- `cleanup_failed`
- 缺少场景
- 非法 `not_applicable`
- commit、branch 或 artifact SHA 不匹配
- 报告超过四小时

## 增加自动化场景

1. 先在 `release-gate/` 或现有模块中实现确定性测试。
2. 在 `release-gate/coverage.mjs` 新增 suite，明确列出唯一场景 ID 和可执行命令。
3. 一个场景只有在守门员列出的所有强制参数 case 都有断言时，才能映射为 `passed`。
4. 为 suite 失败、超时和日志路径增加框架测试。
5. 运行 `npm run test:release-gate:unit` 和对应 mode，确认失败时不会被吞掉。
6. 更新本文的覆盖表。

禁止把大型通用测试命令直接映射到大量场景并据此宣称覆盖；每个映射必须能指出真实业务断言。

## 生产失败回归 fixture

active manifest 约定位置：

```text
scenarios/production-regressions/manifests/active.json
```

每个 active fixture 必须位于 approved bucket，具有：

- `PRC-<GROUP>-NNN` ID。
- 一个或多个 guardian scenario ID。
- 合成意图、规范化失败签名和可执行 replay 命令。
- 不可反查用户的证据摘要和审计批次 ID。
- `contains_personal_data=false`。
- 隐私审核人和时间。

当前 active manifest 已包含 `PRC-REL-001`，用于回放 runtime worker 的 18036 端口冲突
回归。原始聊天、用户身份、附件和生产资源地址不得进入仓库或 Gate report。

## 发布脚本保护

生产脚本执行顺序固定为：

1. 检查干净、完整且不落后远端的 `main`。
2. 运行既有本地 verify。
3. 构建并检查 `.runtime/portal`。
4. 验证与当前 commit 和 runtime tree SHA256 完全一致的完整 Gate report。
5. Gate report 通过后才允许执行 103 只读预检。
6. 再次请求本次发布的明确人工确认。
7. 确认后才允许上传和切换。

`--skip-tests`、范围绕过变量和公开页问题绕过变量均被硬拒绝。