Files
admin 4a750785f8 feat(cluster): pending 证明超时回收(默认 900 秒,可配可禁用)
- reconciler:可注入时钟 + 唯一判定 pending_timed_out(saturating_sub 防回拨);超时真调 destroy、释放容量、/report 留带原因失败、本轮不重建(下轮按期望态重试)

- 修真 bug:PendingSession.created_at 曾写 now_secs(),与判定时钟分叉 ⇒ 超时永不触发,单测直接抓到

- ControlPlaneConfig / CLI:--pending-timeout SECS(0=显式禁用),默认值只有 DEFAULT_PENDING_TIMEOUT_SECS 一份常量;help 数字由守卫测试对拍

- 新增 8 个构造用例 + 跨文件判据自测 16 条 / 破坏实验 15 条,并入主门禁第 25 条(分母仍 25)

- 文档:ARCH §1.6/§8、FINDINGS §12、README/INDEX/CLAUDE/真机 README/env 样例/MEMORY 同步;HTML 重新生成并校验

- 诚实边界:未做真机验证、真机 musl 产物未更新、超时后下一轮重试不是永久隔离
2026-11-09 21:22:53 +08:00

233 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 文档索引与当前状态(总入口)
> **本文是 ssw-mpc 文档体系的总索引与当前状态快照(2026-11-08)。**
> 存在的理由:同一件事散在多份文档里,其中不少写的是**当时**的阶段结论
> (「主门禁 18 条」「不宣称能上链」「合约部署未做」),不标注就会被当成现状。
>
> 两条纪律:**① 判定口径只有一份实现**(代码 / 判据脚本),文档只写事实与指针,
> 不复制判据逻辑;**② 历史阶段文档不改写历史**,只加「当时状态 → 当前状态」的锚点。
---
## 0. 三类文档,别混着读
| 类别 | 含义 | 更新纪律 | 代表 |
|---|---|---|---|
| **A 活状态 / 真相源** | 描述当前事实,随代码同步 | 事实变了就改;同一事实只认一处权威 | `README.md` 现状、`ARCHITECTURE_SYSTEM.md`、`FISCO_UPSTREAM_TRUTH.md`、`tools/ci.sh`、本文 |
| **B 专题设计** | 结论稳定、不含进度,讲「为什么不是另一种做法」 | 基本不动;若被推翻只在文首标注 | `ARCHITECTURE.md`、`IR.md`、`ZYNQ.md`、`RAY_*.md` |
| **C 历史阶段快照** | 记录某一轮的决策、取证与当时边界 | **不改写历史正文**,文首加状态对照表 | `INTEGRATION_ANALYSIS.md`、`GAP_PLAN.md`、`REAL_MACHINE_FINDINGS.md` 第 7/9.4 节 |
> 判断口径:文档里出现「本轮 / 本期 / 阶段状态 / 主门禁共 N 条 / 未落地 /
> 不宣称」而没有日期锚点的,一律先按 C 类处理,再去 A 类核对。
---
## 1. 当前状态总览(2026-11-08)
| 领域 | 状态 | 权威入口 / 硬证据 |
|---|---|---|
| 算子与协议基线 | [实证] 零依赖 `mpc-core`、golden 向量、n 方 / PSI / SQL / IR | `README.md`「算子与协议基线」表(2026-10-30,仍适用) |
| TEE 直接调度 | [实证] 框架直出 qemu argv,**不走编排层 / Kata** | `TEE_DIRECT_LAUNCH.md`、`deploy/tee/README.md` |
| 真 TEE 双 guest 密文会话 | [实证] 海光 CSV + AMD SNP 跨物理机,两侧还原 `35.000000` | `deploy/tee/real-machine/tee-pair-attest-e2e.sh`,判据 `TEE_PAIR_OK` |
| 芯片证明链合流 | [实证] **同一次运行**:`attest-collect → attest-post(KBS 验签放行)→ key_source=kbs → 密文会话` | `REAL_MACHINE_FINDINGS.md` 第 10 节,判据 `TEE_ATTEST_GATE_OK`;负向逐条破坏过 |
| ★ 集群端点公布门禁 | [实证] 双节点自报 → 非回环暴露(共享密钥 + `--allow-remote`)→ 真 KBS 芯片验签 → 9p 手牌回传证明包 → hostd 独立判定 → `proven_endpoints()` → `GET /sessions`;判据 `CLUSTER_ENDPOINT_GATE_OK` 20/0,负向零外泄 + 带原因、收尾端点收回 | `deploy/tee/real-machine/cluster-endpoint-gate-e2e.sh`、`REAL_MACHINE_FINDINGS.md` 第 11 节;主门禁第 25 条含端点判据自测 25 项 + 破坏实验 14 项 |
| ★ pending 超时回收 | [离线实证] 证明迟迟不落 ⇒ 真回收实例、释放容量、`/report` 留带原因失败;默认 900 秒可配(`0` = 禁用),判定只有一份且防时钟回拨。**未做真机验证** | `crates/mpc-tee/src/reconciler.rs`、`REAL_MACHINE_FINDINGS.md` 第 12 节;`cargo test` 8 个构造用例 + 主门禁第 25 条跨文件判据 16 项 / 破坏实验 15 项 |
| FISCO 国密链真交易 | [实证] TARS 编码(非 RLP)、`sendTransaction` 4 参、`r‖s‖pub` 128B 签名 | `FISCO_UPSTREAM_TRUTH.md`、`crates/mpc-chain/src/fisco_tx.rs` |
| ★ SM2 签名口径 | [实证] **`e = SM3(ZA‖dataHash)`**,distid `1234567812345678`;**不是**签裸 `dataHash` | `FISCO_UPSTREAM_TRUTH.md` §3.1、`tools/sm2_verify.py`;这是 `10008 InvalidSignature` 的真根因 |
| 智能合约真链部署 / 调用 / 读回 | [实证] `MpcHardRule.sol` 部署 → `recordHardRule` → 读回 → 负向矩阵,**22 项判据全绿** | `tools/selftest-fisco-contract.py`(主门禁第 22 条;零依赖 `--self-test` 每次必跑,真链批缺环境显式 `FISCO_REALNODE_SKIPPED`) |
| 主门禁 | [实证] **25 条**(`tools/ci.sh` 的 `step "N/25"` 是唯一计数) | `tools/ci.sh`;缺环境显式 `*_SKIPPED`,绝不静默通过 |
| FISCO 链节点 + 账本持久化 | [实证] 迁入 wuguirong k8s,`nfs-wuguirong` PVC;历史区块哈希逐个一致,删 Pod 重建后高度不变 | `deploy/k8s/fisco/README.md` |
| MPC 站点 `mpc-demo` | [实证] 已在 k8s(NodePort `30082`),`/tmp` 挂 NFS PVC | `demo/k8s/README.md` |
| ARM 边缘板(Zynq-7015) | [实证] `mpc` 二进制上板:selftest 5/5、两进程会话 `35.000000`、sha256 与本机一致;selftest 单次 **≈4 ms**、峰值 RSS 3.5 MB | `docs/ZYNQ.md` §4 |
| ★ Zynq 真板 OP-TEE | [设计] 产物已能交叉编译;**板端未部署**——当前内核 `CONFIG_TEE is not set`、`BOOT.BIN` 无 EL3 承载 ⇒ 须换启动链 | `docs/ZYNQ.md` §4.3、`build/build_optee_zynq7k.sh` |
| ★ SA 扩展模式 | [实证] **板端 SA 服务端 ↔ OrbStack 外挂 VM 端到端跑通**,判据 26/26;seal/unseal/attest/sign + 会话物料全部可用;**VM 侧拿不到 `K_root`**(site 名骗不出、协议无导出端点、VM 侧无根密钥文件) | `docs/SA_EXTENDED_MODE.md`、`deploy/arm/zynq7015/sa-pair-e2e.sh` |
| ★ 零种子守卫 | [实证] CLI 入口(连网前)+ `Vault::new` 双层拒绝全零主种子;判据 18 条;破坏实验证明非恒绿 | `tools/selftest-seed-guard.py`(主门禁第 24 条) |
| ★ 集群自报判据链 | [实证] **离线自测 11 项 + 破坏实验 13 项全绿**,每条判据都被构造样例逐条破坏过;不依赖真机 / xop 保险库。**真机只读链路已复验** `remote()` 返回值纯度(xop WARN 与 ssh 客户端 Warning 都不进返回值、临时文件无残留),但脚本**完整 e2e 尚未复跑** | `tools/selftest-cluster-selfreport.py`(主门禁第 25 条) |
---
## 2. 权威入口:一件事只认一个地方
| 想干什么 | 去哪 | 别去哪 |
|---|---|---|
| 看当前能力 / 项目门面 | `README.md`「现状」+ 本文 §1 | `GAP_PLAN.md`(2026-10-30 缺口计划) |
| 看系统架构 / 组件怎么摆 / 信任边界 / 端点 | `docs/ARCHITECTURE_SYSTEM.md`(含 `.html` 分享版) | `INTEGRATION_ANALYSIS.md` 正文(决策取证)、`ARCHITECTURE.md`(只讲计算分层) |
| 查 FISCO 上游事实(编码/哈希/签名/回执/端点) | `docs/FISCO_UPSTREAM_TRUTH.md` | 凭 web3 直觉;`INTEGRATION_ANALYSIS.md` 的 11-07 推断 |
| 跑真链验收 | `tools/selftest-fisco-contract.py`(`--self-test` 零依赖) | 自己拼交易;`fisco-realnode-probe.py`(历史契约,未销账) |
| 查门禁条数 / 跑全量闸门 | `tools/ci.sh` | 任何文档里写的数字 |
| 查链端点 / 链配置 | `tools/fisco-realnode/example.chain.json` + `deploy/k8s/fisco/README.md` | `127.0.0.1:20200`(旧本机容器,已停) |
| 复现真机证明门控 | `deploy/tee/real-machine/README.md`(开头「重跑前先看」) | `docs/REAL_MACHINE_FINDINGS.md` 第 7/9 节的「当时边界」 |
| 重跑真机双机 e2e:配置 / 预检 / 症状速查 | `deploy/tee/real-machine/real-machines.env.example` + `preflight-real-machine.sh` + 该 README 速查表 | 逐个脚本 export 参数;去 `/tmp` 翻 60+ 个探索脚本 |
| 核对两台真机 `/opt` 物料是否被换 / 丢失 | `deploy/tee/real-machine/host-materials.sh --verify` + `nodes/host-materials.sha256` | 只看预检「qemu/固件/内核存在」(不比 sha256);把 69MB qemu 拷进仓库 |
| 部署 / 回滚链节点 | `deploy/k8s/fisco/`(含 `migrate-ledger.sh`、`README.md`) | 手动 `docker start fisco-gm`(会与 k8s 链分叉) |
| 看真链实证期的审计轨迹 | `tools/fisco-realnode/README.md` | `/tmp`(会被清) |
| 查两台真机硬事实 / 踩坑 | `docs/REAL_MACHINE_FINDINGS.md`(第 10 节最新) | 记忆或口头结论 |
| 查决策依据(为什么这么设计) | `docs/INTEGRATION_ANALYSIS.md` 决策台账 + `ARCHITECTURE.md` | 把它当进度表 |
| 上 ARM 边缘板 / 真板 OP-TEE | `docs/ZYNQ.md`(板端实证 + 启动链缺口)+ `build/build_optee_zynq7k.sh` | 以为「装个 OP-TEE 包就行」;拿 §1 推算表当实测 |
| ★ 看 SA 扩展模式(安全锚点供能力、算力挂 VM) | `docs/SA_EXTENDED_MODE.md`(形态 / 信任模型 / 协议 / 诚实边界 / PCIe 演进路径) | 把 `platform=none` 当成硬件隔离已成立;以为主种子是秘密 |
| 复现 SA 真机端到端 | `deploy/arm/zynq7015/sa-pair-e2e.sh`(`--prepare-with-fwd` 后跑判据) | 逐条手敲 orbctl;忘了跨网段要 socat 转发 |
**端点速查**:集群内 `fisco-chain.wuguirong.svc.cluster.local:20200`;
集群外 `192.168.1.26|27|29:30100`(RPC)/ `30101`(P2P);
站点 `192.168.1.26|27|29:30082`。
---
## 3. 文档清单(按定位分组)
### A 活状态 / 真相源
| 文档 | 定位 |
|---|---|
| `README.md` | 项目门面:命名沿革、定位、现状(算子基线 + 11-08 增量)、验收命令、目录树 |
| `CLAUDE.md` | 给 AI / 开发者的约束:三条铁律、快速验证、crate 分层、关键设计决策、文档章节 |
| `docs/INDEX.md` | **本文**:总索引 + 当前状态快照 + 更新纪律 |
| `docs/ARCHITECTURE_SYSTEM.md` | **系统架构当前形态**:组件清单 / 双层控制面 / 会话主键 / 端到端数据流 / 部署拓扑 / 平台矩阵(**含 SA 扩展模式 §1.7,第四种形态**)/ 诚实边界;拆解自 `INTEGRATION_ANALYSIS.md`,[实证][桩验][设计][禁用] 区分实证与蓝图 |
| `docs/ARCHITECTURE_SYSTEM.html` + `tools/render-share-html.py` | 上者的**可分享单文件 HTML** 与生成器;HTML 是派生产物勿手改,`--check` 校验与 md 同步 |
| `docs/FISCO_UPSTREAM_TRUTH.md` | 国密链上游逐字节核对的唯一真相源(TARS / ZA / `status==0` / selector) |
| `docs/REAL_MACHINE_FINDINGS.md` | 两台真机实测硬事实;第 10 节是最新合流结论 |
| `tools/ci.sh` | 主门禁(25 条)唯一实现 |
| `tools/selftest-fisco-contract.py` | 真链验收唯一权威脚本(★ **独立于主门禁**:它要连真链,故不在 `ci.sh` 里) |
| `tools/selftest-sa.py` / `tools/selftest-seed-guard.py` | SA 契约(52 条)/ 零种子守卫(18 条)—— 主门禁第 23 / 24 条 |
| `tools/selftest-pending-timeout.py` / `-break.py` | pending 超时回收**跨文件接线**判据(16 条)/ 破坏实验(15 条)—— 主门禁第 25 条;逻辑本身由第 1 条 `cargo test` 真跑 |
### B 专题设计(结论稳定,不含进度)
`docs/ARCHITECTURE.md`(分层 / Ray / TEE 定位)、`docs/IR.md`(轮数规划)、
`docs/N_PARTY.md`(n 方能力矩阵)、`docs/COMPARE_SECRETFLOW.md`(与隐语对照)、
`docs/OPT_PLAN.md`、`docs/ZYNQ.md`(**ARM 边缘板:2026-11-09 已上板实测 + 真板 OP-TEE 启动链缺口**)、`docs/PG.md`,
`docs/SA_EXTENDED_MODE.md`(**SA 扩展模式:板端供能力、算力挂 VM;2026-11-09 真机端到端跑通**)、
`docs/TEE_DIRECT_LAUNCH.md`(AMD/海光直接调度,已加 11-08 状态核对)、
`docs/TEE_OCI_PATH.md`、`docs/OPTEE_VERIF_PLAN.md`(**QEMU 实跑已做:selftest + 第 5 条跨设备 + 第 4 条跨重启**)、
`docs/RAY_CORE.md` / `RAY_CORE_101.md` / `RAY_ARMV7.md`。
### C 历史阶段快照(先看文首状态提示)
| 文档 | 当时状态 | 现在读法 |
|---|---|---|
| `docs/INTEGRATION_ANALYSIS.md` | 2026-11-07 决策定稿,主门禁 18 条 | 决策台账仍生效;文首对照表列出被推进的 7 条结论;**架构骨架已抽到 `ARCHITECTURE_SYSTEM.md`** |
| `docs/GAP_PLAN.md` | 2026-10-30 改名前缺口计划 | 已加归档声明,不据它判断「现在还缺什么」 |
| `docs/REAL_MACHINE_FINDINGS.md` 第 7 / 9.4 节 | 11-07 当时的不宣称项 | 已加状态锚点,指向第 10 节 |
| `docs/TEE_DIRECT_LAUNCH.md` 未交付段 | 11-06 当时 OCI 链路未复跑 | 已加 11-08 核对:仅「OCI 形态」边界继续成立 |
### D 部署与复现
`deploy/k8s/fisco/README.md`(链迁移 SOP / 账本 / 回滚 / 边界)、
`deploy/arm/zynq7015/README.md`(**ARM 边缘板**:板端速查 / `board-selftest.sh` 判据 /
板端三条硬坑 / 真板 OP-TEE 缺口 / 上板产物 sha256)、
`deploy/tee/real-machine/README.md`(真机 e2e;**开头有重跑三步、参数真相源与症状速查表**)、
`deploy/tee/real-machine/real-machines.env.example`(**双机参数唯一集中入口**,脱敏、可 source)、
`deploy/tee/real-machine/preflight-real-machine.sh`(重跑前环境预检,`--self-test` 负向矩阵;
含本机重建条件检查)、
`deploy/tee/real-machine/host-materials.sh` + `nodes/host-materials.sha256`
(**两台真机 `/opt` 不可再生物料的入仓基线**:采集 / 核对 / 判据自测;
`--verify` 比 sha256,`--self-test` 用 6 个构造样例证明非恒绿)、
`deploy/tee/real-machine/nodes/*.node.example` + `fixtures/`(真机路径与真实报告 / 证书链样本)、
`deploy/tee/README.md`、
`deploy/tee/oci/README.md`、`deploy/ray/README.md`、
`demo/README.md`、`demo/k8s/README.md`(站点 + PVC)、
`tools/fisco-realnode/README.md`(复现工具与审计轨迹)、
`examples/12_k8s_two_party/README.md`。
### 非文档(不参与索引)
`.workbuddy/memory/*.md` 是**工作日志**(追加式,只记有跨会话价值的事实);
`.tmp-fisco/` 是临时解包目录;`refs/nax/` 是独立只读参考仓库。
---
## 4. 容易读错的旧结论(对照表)
| 旧文档写过的 | 当前事实 | 权威入口 |
|---|---|---|
| 「主门禁共 18 条 / 20 条 / 22 条」 | **25 条** | `tools/ci.sh` |
| 「`selftest-fisco-contract.py` 不在主门禁里」 | ★ **已回到主门禁第 22 条**(`27cbdc7` 误删过,现已恢复) | `tools/ci.sh`、`tools/fisco-realnode/README.md` |
| 「`flush` 只发规范字节,不是已签名交易」 | `flush --mode signed-tx` 发**完整已签名 FISCO 交易**(TARS + 128B 签名),且走 `Outbox::flush_with` 状态机 | `crates/mpc-cli/src/chain.rs`、`fisco_tx.rs` |
| 「不宣称能上链」「合约部署未做」 | 真链部署 / 调用 / 读回已实证,22/22 全绿 | `selftest-fisco-contract.py` |
| 「签名 = 32B `dataHash` 上直接 SM2,不再二次 SM3」 | `e = SM3(ZA‖dataHash)`,ZA 用 distid 与曲线参数算;`a=p-3` 末字节 `fc` 不许手抄 | `FISCO_UPSTREAM_TRUTH.md` §3.1 |
| 「3.x 是 `eth_` 兼容端点」 | `eth_call` / `eth_getTransactionReceipt` 实测 method-not-found;用自有 `call` / `getTransactionReceipt`(4 参) | 同上、`catalog.rs` 守卫测试 |
| 链在 `127.0.0.1:20200` / 本机 `fisco-gm` | 已迁 k8s `30100`,账本 PVC;本机容器只 stop 未删、**别同时对外服务** | `deploy/k8s/fisco/README.md` |
| 「CSV 的 KBS 链路仍待落地」「证明与会话尚未合流」 | 第 10 节已合流跑通(`key_source=kbs`) | `REAL_MACHINE_FINDINGS.md` 第 10 节 |
| 「站点在 cube 沙箱 / 虚拟机里」 | 站点一直在 k8s(30082);链原是**本机 macOS Docker 容器**,不是虚机 | 本文 §1、`demo/k8s/README.md` |
---
## 5. 诚实边界(仍然不宣称,不许借更新冲掉)
- 软件 OpenSSL 签名器**私钥可导出 ⇒ 密评不可过**;真链能上链 ≠ 生产可用,
生产必须换硬件模组签名器(`SignerPolicy::ProductionModule` 必拒软件签名器)。
- 真实 `bcos-rpc` 的 **TLCP 通道未通**:第 18 条服务端是环回 echo,不是真节点,
`BCOS_RPC_NOT_VERIFIED` 仍成立;`client_tlcp=false` 是当前实证所用配置。
- **`hostd` 执行面仍在 TEE 真机**:要 qemu guest + `/dev/sev`/CSV ioctl,wuguirong
节点无 TEE 设备,且项目铁律禁止编排层;进 k8s 的只是台账 ConfigMap。
- TEE 证明**未上链**、未绑定链上状态位;链上撤销状态位读取后端**未接入**
(声明 chain 即 fail-closed 拒);OPA **不在 guest 内**;decision 未签名未上链。
- OP-TEE **QEMU 实跑已做**(2026-11-09,见 `docs/OPTEE_VERIF_PLAN.md`):
全流程 selftest、第 5 条跨设备解封被拒、第 4 条跨重启 unseal 成功三条**都真跑通了**。
但那是 **QEMU 模拟**:`dna` 是编译期 sha256 种子、HUK 是模拟值 ⇒
**不能**当成真板的设备绑定证据,**不能**替代真板一次性验收。
`CryptoPrecompiled.sm2Verify` 真机对拍未做;
`tools/fisco-realnode-probe.py` 的 4 处 `IMPL_GAPS` 未销账。
- ★ **Zynq-7015 真板 OP-TEE 未部署**:产物能交叉编译(`build/build_optee_zynq7k.sh`),
但板子当前内核 `CONFIG_TEE is not set`、`BOOT.BIN` 里**没有 EL3 承载**
(U-Boot 2018.01 直接 `bootz` 进内核)⇒ 必须换启动链;
板子上跑着 `board-agent` / `easytier-core`(m4gw) 等在役服务,
且**没有第二台板子**可试 ⇒ 部署前必须先做带哈希基线的完整备份 + 回滚路径。
本轮**未改动板子任何文件**。
- 本租户 SA 无 `create secret` 权限;链客户端私钥 `MPC_FISCO_KEY` 保持仓库外,
不进镜像 / ConfigMap / git。
---
## 6. 更新纪律(下次改文档照这个走)
1. **门禁条数只认 `tools/ci.sh`**:脚本里 `step "N/25 ..."` 是唯一计数;文档写死的
数字必须同步,改完用 python 扫全仓 `*.md` 复核(macOS 的 grep 对中文匹配不稳)。
★ 另:**判据脚本在仓库里 ≠ 判据在门禁里** —— 提交 `27cbdc7` 曾删掉
`tools/ci.sh` 里 5 个 step(第 18–22 条),脚本都还在,只是不再被调用 ⇒
门禁**静默削弱**(文件在、判据在、门禁不跑)。改完 `ci.sh` 必须核对:
① `tools/ci.sh` 里的 step 条数与文档条数一致(★ 数 step 时注意**注释里
出现 step 字面样例会被一起数进去** ⇒ 计数永远多 1,2026-11-09 实测踩过);
② 逐条确认被调用的脚本**真的存在**;
③ 头部注释编号与 step 号一一对应。
2. **链端点只认两处**:`tools/fisco-realnode/example.chain.json`(客户端)与
`deploy/k8s/fisco/README.md`(集群);旧 `127.0.0.1:20200` 只能作为历史叙述出现。
3. **上游事实只认 `FISCO_UPSTREAM_TRUTH.md`**:任何「签名口径 / 编码 / 回执字段」
的新结论先在这份文档核对,再改代码与判据;`catalog.rs` 每条 API 签名必须真存在。
4. **判定只有一份实现**:生成端自检 == 审计端判定;文档不得复述判据逻辑当作第二真相源。
5. **历史文档只加锚点**:写「(YYYY-MM-DD 当时)」+ 文首「当时 → 当前」对照表,
**不要把历史改写成就没发生过**,也不要为了好看删掉当时的诚实边界。
6. **每条负向判据都要用构造样例破坏过**,否则恒绿;文档里「已验证」必须有对应脚本与判据名。
7. **新增文档必须回本文登记**(§3 分组),并在 `CLAUDE.md` 文档章节留指针;
部署类脚本 / 证据不得只留在 `/tmp`。
8. 改完做校验:**纯文档改动**至少跑 `python3 tools/selftest-fisco-contract.py --self-test`
+ `bash -n tools/ci.sh` + `git diff --check`(不必跑全量门禁,避免真链判据往链上
写新块 / 部署新合约,那是文档校验不需要的副作用);**涉及代码 / 判据 / 门禁的改动**
才按 `tools/ci.sh` 跑全量 25 条。确认没有把活文档改坏。
9. **★ 帮助文本 / 文档里的参数必须与实现对齐**:2026-11-09 实测踩过两次 ——
改 `mpc tee` 帮助文本时漏掉了 `attest-upload` 的 `--upload-path-file`
(实现里**必填**),以及 SA 客户端的 `--plaintext-hex` / `--blob-hex` /
`--user-data-hex` / `--message-hex` / `--session-id` 全都没写进帮助。
这类漂移**静默**:代码照样编译、门禁照样全绿,只有用户照着帮助敲命令才失败。
已加守卫测试 `tee_usage_flags_are_all_implemented`(正向:帮助里每个 flag
必须有对应解析调用)+ `sa_required_flags_appear_in_usage`(反向:实现里
必填的参数必须在帮助里),两条都做过破坏实验(自指型假绿也修掉了)。
10. **架构结论只改 `docs/ARCHITECTURE_SYSTEM.md`**:新增 / 变更组件、边界、端点先改它,
再跑 `python3 tools/render-share-html.py`(重新生成 `.html`)与 `--check`(校验同步)。
HTML 是**派生产物不许手改**;历史决策文档正文不因架构变更而改写。
文档里写「部署了什么」必须区分 [实证] / [桩验] / [设计] / [禁用],不许把蓝图写成现状。
11. **真机参数只认 `deploy/tee/real-machine/real-machines.env.example`**:换机器 / 换网段
改这一份,不要逐个脚本 export;重跑前先 `preflight-real-machine.sh`(`--self-test`
用构造样例钉死参数判据非恒绿)。`/tmp` 的 60+ 个探索脚本是过程产物,结论已
沉淀进验签器与 `REAL_MACHINE_FINDINGS.md`,**不许整批入库或重跑确认**。
12. **两台真机 `/opt` 物料只认 `nodes/host-materials.sha256` 基线**:远端 `/tmp` 是运行时
目录(每次 e2e 重铺,丢了不用管),`/opt` 的 qemu / 固件 / 内核 / 海光官方验签器 /
GmSSL / CSV 证书链才是不可再生的。重启后先 `--verify`(缺文件 / 被替换 / 被升级
一律 FAIL 并打印 diff),换机或物料升级后 `--collect` 重采并提交。
**清单本身由 git 保护**,不许在仓库外偷改;也不许把 69MB/78MB 二进制搬进仓库。
新增判据必须能用构造样例推翻(`--self-test` 6 条 + 端到端篡改 hash 判红)。
13. **TA 签名密钥分级只有一份实现**:`build/ta-key-tier.sh` 是唯一真相源,
`build_optee.sh` 与 `build_optee_zynq7k.sh` 都 source 它;
`tools/selftest-ta-key-tier.py` 反向守卫「入口里不许有第二份拷贝」。
改密钥规则必须改共享文件并重跑该自检,别在某个入口里私改一份。