# 24 domainCheck Node Agent 协议与 Release Hub 设计

如果当前已经进入“把方案真正落地到上线前收口”的阶段，建议配套阅读：

- `docs/25_domainCheck_海外单脑控制面上线收口总表.md`
- `docs/schemas/ops_driver_contract.md`
- `docs/schemas/ops_stack_diagnosis_contract.md`

## 一、Node Agent 为什么是核心

终局架构里，大陆节点不应该再是“需要人工登录的机器”，而应该是：

> 受控执行节点

每个节点通过 `domaincheck-node-agent` 接入海外控制面，承担：

- 注册
- 心跳
- 拉取任务
- 执行任务
- 回传结果
- 回传日志
- 回传诊断包

这样后台按钮和 Codex 都不用再直接碰节点 shell。

补一个很关键的落地约束：

- OpsCenter 顶部的“总检入口”现在应正式优先消费 `GET /api/v1/ops/go-live-summary`
- `GET /api/v1/ops/stack-diagnosis`
  - 保留为更细的可解释总检层
  - 用于继续下钻 `issues / operator_decision / next_actions / recommended_commands`
- CLI 总检脚本也应优先消费同一个 contract
- 海外 Codex 驾驶员后续默认也先看这一份总检结果

也就是说，Node Agent、Release Hub、页面按钮、Codex 驾驶员，不再各自拼一套“当前现场判断”，而是统一先看：

> go-live summary

然后再根据 `stack-diagnosis / overview / release launchpad` 继续下钻。

这里还要再固定一个新口径，避免页面和运维动作继续混用“可联调”和“可发版”：

- `go_live_status`
  - 回答“当前是否已经进入统一收口、联调、复核车道”
  - 允许出现 `attention`
- `publish_status / publish_ready`
  - 回答“当前是否已经满足正式发版门禁”
  - 必须明确区分
    - `blocked`
    - `attention`
    - `ready`

这里再补一条已经收口成代码规则、后续不要再放松的判断：

- 如果目标节点的 Node Agent `delivery_queue` 仍然存在 `dead_letter`
  - 这不是普通 warning
  - 对 `publish_status` 必须按 `blocked` 处理
  - 对 `default_rollout_gate` 也必须按阻断处理
- 如果只是 `retrying`
  - 可以继续保留为 `warning / attention`
  - 但不应该再被当成“完全干净的发布现场”

原因很简单：

- `dead_letter` 说明控制面到节点的执行回执链路已经出现语义失败
- 这时候页面如果还显示“可发布”，就会制造最危险的假阳性
- 所以 `go_live_status` 可以是 `attention`
- 但 `publish_status` 必须更严格，直接阻断正式发版

这里还要补一条已经落成代码的事件语义，后续不要再退回“任务成功就算一切成功”的旧口径：

- 如果 Node Agent 在执行 `jobs/{job_id}/start` 时，开始回执投递失败
  - 允许节点继续本地执行
  - 不允许因为这一次投递失败就直接中断真实任务
- 但控制面必须把这类现场显性化为单独问题，而不是静默吞掉
  - activity stream 中对应 `ops_job` 应升级为 `attention`
  - 保留原始 `job_status`
  - 并暴露
    - `start_delivery_state`
    - `start_delivery_error`
    - `source_focus_ref`
- `ops overview / go-live summary`
  - 也必须把它当成正式关注项
  - 不能只在活动流里可见、但首页总检仍显示“可直接上线”
  - 当前口径应是
    - `go_live_status = attention`
    - `publish_status = attention`
    - 默认下一步指向 `focus_latest_job_events`
- `stack-diagnosis`
  - 也必须把这类现场提升为可操作 issue
  - 默认建议动作应该回到 `focus_latest_job_events`

这里再固定一个动作层约束，避免后面 UI / CLI / Codex 又各自猜入口：

- 如果活动焦点已经明确落到
  - `source_focus_ref.kind = ops_job_event`
  - 或者问题本身就是“开始回执异常”
- 那么默认焦点动作不应继续使用泛化的 `focus_activity_item`
- 而应直接升级为
  - `focus_latest_job_events`

原因是：

- `focus_activity_item` 适合“先进入这条活动对应的详情”
- `focus_latest_job_events` 适合“问题已经明确在 job event 级别”
- 对开始回执异常这类问题，继续停在 activity 级别只会多一跳，降低定位效率

原因也很直接：

- 这类问题不代表节点没执行
- 但代表控制面和节点现场之间已经出现“开始态失联”
- 如果不显性化，页面会以为“任务没问题，只是还没刷新”
- 实际上这是自动化链路一致性已经开始打折的早期信号

也就是说：

- “总检入口”不只告诉你系统是不是在健康收口
- 还必须同时告诉你“现在能不能正式发布”

后续页面、CLI、Codex、按钮动作，都应该优先消费这两个层级，而不是再各自推导一套“看起来差不多能上”的临时判断。

这里再补一个已经落地的收口原则：

- `GET /api/v1/ops/stack-diagnosis` 现在不只返回传统的
  - `issues`
  - `recommended_actions`
  - `next_step`
- 还会正式返回
  - `diagnosis.operator_decision`
  - `diagnosis.next_actions`
  - `diagnosis.recommended_commands`

这三层的定位要固定下来：

- `operator_decision`
  先回答“当前主处理车道是什么”
  例如：`observability / node_handover / release / ops_jobs / steady`
- `next_actions`
  直接给出主动作和复核动作的下一跳命令
- `recommended_commands`
  把节点现场日志、接管、Release Hub、driver-resolve 等常用 drill-down 统一收口成可复用命令集

这样页面顶部“当前主决策”卡、CLI 的 `check_ops_center_stack.sh`、海外 Codex 驾驶员，就都不该再各自重新推导“当前应该先看日志还是先接管还是先看发布门禁”，而是优先共享后端总检 contract。

这里再补一条已经收口成正式操作约束、后续不要再退回去的口径：

- 如果总检已经识别出
  - `runtime_build_schema_stale`
  - `runtime_route_surface_incomplete`
  - `runtime_build_info_unavailable`
- 页面、CLI、Codex 驾驶员的第一反应不应该再是“给我一条 `systemctl restart domaincheck-api`”
- 而应该统一提升为标准恢复入口
  - `runtime-refresh-recover`
  - `go-live-recover`

这两个入口的语义要固定：

- `runtime-refresh-recover`
  - 回答“当前运行中的 API 是否还是旧 schema / 旧路由面”
  - 给出固定恢复链
  - 再输出下一跳复检命令
- `go-live-recover`
  - 把 `runtime-refresh-recover`
  - `stack-diagnosis`
  - `stack-next`
  - `go-live-check`
  - `doctor`
  这条联调收口链直接串起来

也就是说：

- 原子 systemd 重启仍然只是底层执行事实
- 对页面按钮、CLI、Codex 来说，正式入口必须是组合恢复动作
- 这样后续总检摘要、主决策卡、推荐命令集，才不会再次退化成“看见 schema 漂移就手工重启”

再往前一层，现在还应该固定：

- `GET /api/v1/ops/driver-feed`
  - 返回 `go_live_summary`
- `GET /api/v1/ops/driver-feed`
  - 继续返回 `automation_coverage`
- `GET /api/v1/ops/codex-brief`
  - 返回 `go_live_summary`
- `GET /api/v1/ops/codex-brief`
  - 继续返回 `automation_coverage`

也就是说：

- 页面顶部先看 `go-live-summary`
- Codex 驾驶员先看 `codex-brief.go_live_summary`
- CLI 总检先看 `go-live-check`
- 真正需要解释“为什么阻断 / 下一步为什么是这个动作”时，再回退到 `stack-diagnosis`

同时还要固定一条“自动化覆盖率”口径，避免后续页面、CLI、Codex 又各自推导一套“现在已经自动化到什么程度”：

- `driver_feed.automation_coverage`
- `codex_brief.automation_coverage`

至少需要稳定包含：

- `automation_level_counts`
- `recommendation_counts`
- `executor_kind_counts`
- `safe_auto_total`
- `guarded_auto_total`
- `mixed_total`
- `ui_only_total`
- `blocked_total`
- `preview_only_total`
- `backend_handled_total`
- `execution_ready_total`
- `human_dependency_total`
- `launch_status`
- `launch_ready`

其中语义固定为：

- `preview_only_total`
  统计那些已经后端化、但本质仍属于“只读预览 / 聚焦 / 审阅”的动作
- `backend_handled_total`
  统计已经脱离人工页面点击、可以直接走后端 contract 的动作
- `execution_ready_total`
  统计 `auto_execute + confirm_then_execute`
- `human_dependency_total`
  统计 `resolve_first + open_ui + blocked`
- `launch_status`
  作为“自动化层面的收口判断”
  取值固定为 `ready / attention / blocked`
- `launch_ready`
  只回答“从自动化执行角度看，当前是否已经接近无人值守可上线”

这样才是完整的：

- 一份稳定收口摘要
- 一份可解释总检
- 一组可执行下钻命令

---

## 二、当前已经落下的第一版协议骨架

当前后端已经补出这些接口骨架：

- `POST /api/v1/ops/agent/tokens`
- `POST /api/v1/ops/agent/bootstrap-plan`
- `POST /api/v1/ops/agent/register`
- `POST /api/v1/ops/agent/heartbeat`
- `POST /api/v1/ops/agent/pull`
- `POST /api/v1/ops/agent/jobs/{job_id}/start`
- `POST /api/v1/ops/agent/jobs/{job_id}/complete`
- `POST /api/v1/ops/agent/jobs/{job_id}/events`

这几类接口已经足够表达“节点是怎么接控制面的”。

当前仓库里也已经补出第一版 agent 运行骨架：

- `domain-api/app/node_agent.py`
- `domain-api/deploy/systemd/domain-node-agent.service`
- `domain-api/deploy/multi-region/build_node_agent_bootstrap_plan.sh`
- `domain-api/deploy/multi-region/templates/domaincheck-node-agent.env.example`

也就是说，这已经不是纯文档方案，而是开始具备正式执行器入口了。

另外现在控制面已经不只是“签发一枚 token”，而是可以直接生成完整接入方案：

- 后端通过 `POST /api/v1/ops/agent/bootstrap-plan`
- 一次返回：
  - token
  - env 内容
  - 安装命令块
  - 启动检查命令

这一步很关键，因为它把“接管新节点”从零散知识点，收敛成了控制面里的标准对象。

控制面页面现在也已经补上了第一版“可视化接管态”：

- `GET /api/v1/ops/nodes`
  不再只返回“已纳管节点”，也会把“集群可见但未纳管”的节点一起带回来
- `GET /api/v1/ops/nodes/{node_code}/handover`
  可以直接拿到单节点接管详情、阻断项、下一步建议和 bootstrap 默认参数
- `POST /api/v1/ops/nodes/{node_code}/handover/bootstrap-plan`
  可以按节点当前上下文直接生成新的 bootstrap 方案，而不是让页面或脚本自己再拼 `node_region / node_role`
- `GET /api/v1/ops/nodes/{node_code}/onboarding`
  现在除了返回 `onboarding_stage / acceptance / recommended_actions`，还应返回统一的 `recovery_decision`
- `POST /api/v1/ops/nodes/{node_code}/onboarding/recovery/preview`
  应作为 `node-recover` 的正式 preview 入口
- `POST /api/v1/ops/nodes/{node_code}/onboarding/recovery/execute`
  应作为 `node-recover confirm` 的正式 execute 入口
- 节点会被明确区分为：
  - `已接管`
  - `仅运行态在线`
  - `待接入`
  - `心跳过期`
  - `Token 过期 / 已禁用`

这意味着海外控制面第一次真正具备了“先看见，再接管”的统一入口，而不是只有接入完成后才能看见节点。

这里补一个非常关键的收口原则：

- `recovery_decision` 必须由后端统一生成
- 前端、CLI、Codex 驾驶员不再各自重新推导“下一步该 bootstrap 还是该 acceptance”
- 它至少要固定返回：
  - `action`
  - `label`
  - `summary`
  - `command_hint`
  - `window`
  - `stage_code`
  - `acceptance_status_code`

当前口径应固定为：

- 节点仍处于
  - `pending_bootstrap`
  - `runtime_only`
  - `stale`
  - `agent_pending`
  - 以及其他接入中状态
  时，优先收口为 `bootstrap_run`
- 节点真正进入
  - `acceptance_ready`
  - 或 Agent 已在线
  时，才切到 `run_acceptance`

这样 `node-recover`、OpsCenter“自动收口建议”、海外 Codex 驾驶员三边看到的恢复结论才会完全一致。

这里还要补一条很关键的执行约束，避免页面、CLI、Codex 后面又各自补出“双发一次”的隐藏 bug：

- `node-recover`
  - preview 时优先命中 `onboarding/recovery/preview`
  - confirm 时优先命中 `onboarding/recovery/execute`
- 如果控制面已经成功命中正式 `recovery/execute`
  - 就表示后端已经完成“选择动作 + 发起执行”
  - CLI / 页面 / Codex 不允许再额外补跑一次
    - `node-bootstrap-run`
    - 或 `node-acceptance-run`
- 只有在 recovery endpoint 不存在、退回兼容视图时
  - CLI 才可以根据 `recovery_decision / stage_code / acceptance_status_code`
    再本地降级决定下一跳

也就是说，正式协议下：

- 动作选择权在后端 recovery endpoint
- CLI 和页面只是展示恢复结论与执行回执
- 兼容模式下才允许本地推断

这样才能避免后续接管链路出现：

- preview 看的是一套
- execute 走的是另一套
- CLI 还再补跑一次底层动作

一旦出现这种双发结构，节点接管、验收、发布回执都会失真，这在上线期是不能接受的。

接管通过后，控制面也不应该只是停在“状态已通过”这一步，而是要立刻进入正式运维动作：

- 单节点执行标准巡检
- 批量对“真正参与检测节点”发起巡检
- 批量对“在线未参与节点”发起巡检
- 节点定向进入 Release / Rollout

其中“标准巡检”已经统一成固定序列：

- `health.snapshot`
- `logs.collect`
- `diagnostics.collect`

后续无论是 Codex 驾驶员还是后台按钮，都应该优先复用这条标准序列，而不是再回到临时 shell 排障。

在控制面页面上，这些状态不应该只是文字摘要，还应该继续收口成“驾驶建议卡”：

- 如果存在有效执行节点但尚未接管，优先进入接管动作
- 如果存在参与检测节点但现场日志还不可见，优先开启关键日志回传
- 如果存在真正参与检测节点，优先执行标准巡检
- 如果存在在线未参与节点，优先排查接单/待命问题
- 当接管和巡检链路稳定后，再推进 Release / Rollout

这样 Node Agent 协议、Ops Job 模型和页面按钮才会是同一个体系，而不是三套彼此分裂的运维逻辑。

这里的驾驶动作命名也要尽量收敛成通用语义，而不是绑定页面分组：

- `run_standard_inspection`
- `open_worker_logs`
- `open_diagnostics`

这样同一套动作才能在：

- 驾驶建议卡
- 后台按钮
- Codex 自动驾驶
- 后续自动化编排

之间稳定复用。

再进一步，为了避免前端按钮、Codex 驾驶员、临时脚本各自维护一套“多步动作串联逻辑”，控制面里还需要再上一层：

- `ops playbook`

它的职责不是直接执行 shell，而是把一个高层运维意图展开为一组标准 `ops jobs`。

例如：

- `inspection.standard`
  - `health.snapshot`
  - `logs.collect(worker)`
  - `diagnostics.collect`
- `scene.logs.key`
  - `logs.collect(worker, 120)`
- `scene.logs.full`
  - `logs.collect(worker, 300)`
  - `diagnostics.collect(300)`

这样：

- 后端推荐的是 playbook
- 前端按钮点的是 playbook
- Codex 驾驶员调用的也是 playbook
- 真正落库和回执的仍然是 `ops jobs`

整个模型会更稳定，也更适合后面持续扩机器。

并且这层已经开始真正进入页面主流程：

- OpsCenter 已能列出 playbook
- OpsCenter 已能预览 playbook 展开结果
- “标准巡检”已优先直接调用 `inspection.standard`
- “接管后一键验收”已优先直接调用 `onboarding.acceptance`

也就是说，控制面 UI、Codex 驾驶员、后端编排这三层终于开始共用同一套多步动作模型。

同样，OpsCenter 不应该只会发任务，还要能直接承接执行现场：

- 把 `participating_nodes` 和 `non_participating_nodes` 一起并入运维视图
- 把 `log_sync.enabled / mode / source_nodes / last_line` 一起并入运维视图
- 并允许控制面直接切换远端日志回传模式

这样 Codex 驾驶员和人工按钮都会在同一页看到：

- 谁正在跑
- 谁在线但没跑
- 日志有没有回来
- 要不要临时切到全量回传

并且这层不能只停留在页面按钮，还要提供固定 drill-down 命令：

- `bash domain-api/deploy/multi-region/drive_ops_center.sh scene-node-log <mainland_base_url> <node_code> [limit] [key|full]`
- `bash domain-api/deploy/multi-region/check_node_scene_log.sh <mainland_base_url> <node_code> [limit] [key|full]`

这样海外控制面、CLI 和 Codex 驾驶员在看到“参与检测但缺样本”时，不需要再人工猜下一步看哪台机器，而是直接按节点下钻现场日志。

这里再补一个已经落地的恢复流原则：

- 当 `stack-diagnosis` / `ops overview` 判断为
  - `remote_log_sync_disabled`
  - 或“已有参与节点但现场日志仍不可见”
- CLI、页面按钮、Codex 驾驶员都不应该再只给“去看日志”这种观察型建议
- 而应该优先给出：

> `log-sync-recover`

也就是：

- 先执行 `enable_log_sync_key` 或 `enable_log_sync_full`
- 再自动复核 `execution_scene.log_sync`
- 再自动给出下一跳 drill-down

当前海外单入口已经有这一条组合命令：

```bash
bash domain-api/deploy/multi-region/drive_ops_center.sh log-sync-recover
bash domain-api/deploy/multi-region/drive_ops_center.sh log-sync-recover http://127.0.0.1:8100 full confirm cli/ops
```

它不是“额外的便捷脚本”，而是终局驾驶 contract 的一个关键落地点：

- 页面按钮可直接复用
- Codex 驾驶员可直接复用
- `stack-diagnosis / doctor / stack-next` 也应该优先推荐它

这样“恢复可见性”就不再是人工脑补的一串步骤，而是正式的一跳动作。

Node Agent 接管链路也应采用同样原则：

- 当 `stack-diagnosis` 判断主车道已经进入 `node_handover`
- 或发现 `managed_nodes_agent_pending`
- 不应该只给出零散的
  - `node-handover`
  - `node-bootstrap-plan`
  - `doctor`
- 而应该优先给出一条组合恢复流：

> `agent-gap-recover`

它的目标不是“替代真正的节点落地”，而是把海外控制面需要做的这几步先标准化：

1. 识别首个接管缺口节点
2. 输出该节点当前 handover 状态
3. 生成该节点 bootstrap plan
4. 给出后续检查命令

当前海外单入口已经支持：

```bash
bash domain-api/deploy/multi-region/drive_ops_center.sh agent-gap-check
bash domain-api/deploy/multi-region/drive_ops_center.sh agent-gap-recover
bash domain-api/deploy/multi-region/drive_ops_center.sh agent-gap-export
```

而且这条链路也已经具备版本兼容能力：

- 如果当前控制面 API 还没有节点级 `/handover`
  - 退回 `stack-diagnosis`
- 如果当前控制面 API 还没有节点级 `/handover/bootstrap-plan`
  - 退回通用 `/ops/agent/bootstrap-plan`

这样“节点接管”就不再只是页面里的一个弹窗动作，而是正式进入海外单入口、CLI 总检、Codex 驾驶员都可复用的统一恢复模型。

其中：

- `agent-gap-recover`
  - 负责把首个缺口节点的状态、bootstrap plan、下一跳建议串成一条恢复流
- `agent-gap-export`
  - 负责把首个缺口节点的接管材料直接导出成目录
  - 默认应至少包含：
    - `stack-first-gap-handover`
    - `agent-gap-check`
    - `node-onboarding`
    - `node-bootstrap-plan`
    - `node-bootstrap-preview`
    - `node-acceptance-plan`
    - `manifest.json`

这样海外控制面就不只是“告诉你下一步做什么”，而是可以直接产出一份可执行、可交接、可归档的节点接管包。

另外，`node-bootstrap-plan` 的 condensed summary 还应该主动区分两类情况：

- 仓库代码本身还不支持最新 bootstrap 字段
- 仓库代码已经支持，但运行中的 API 还没重启到最新版本

后一类在联调里非常常见，所以 summary 必须直接给出：

- `repo_capability.supports_install_command_block`
- `repo_capability.runtime_may_need_restart`
- `recommended_commands.restart_api_if_runtime_stale`

这样一眼就能判断，这次缺口到底是“代码没写到位”，还是“代码已经在仓库里，但线上进程还是旧的”。

这个判断还必须继续上提到总检 contract：

- 一旦 `stack-diagnosis` 识别出 `runtime_build_schema_stale`
- 默认 `next_step.action_code`
  - 必须优先收敛为 `api-restart`
- `diagnosis.operator_decision.lane`
  - 必须优先收敛为 `runtime_recovery`

因为这类问题的本质不是“节点还没接管”，而是“控制面 API 还是旧 schema / 旧路由面”。

如果这里不先做 API 重启，而是继续把人带去执行 `bootstrap_run / fix_managed_nodes`

- 只会让真正问题继续被掩盖
- 页面、CLI、Codex 也会一起被带偏

另外，bootstrap 计划和安装脚本都必须兼容多种部署目录布局：

- `${ROOT_DIR}/domainCheck/...`
- `${ROOT_DIR}/domain-api/...`
- `${ROOT_DIR}/deploy/...`

原因很现实：

- 开发仓库里脚本位于 `domain-api/deploy/...`
- 实际上线包可能已经把 API 内容平铺到 `domainCheck/...`

如果 bootstrap 计划只写死其中一种路径，就会在“控制面判定缺口正确，但落地脚本直接找不到 install script”这个位置翻车。

同样，这个 drill-down 也应该进入 `doctor-export`：

- 当 `stack-diagnosis` 已经给出 `node_scene_log` 焦点
- 导出包自动追加 `15_scene_node_log_<node_code>.txt`
- `manifest.json.summary.scene_log_reports` 也同步记录这些节点级现场日志附件

并且这里的焦点来源现在也应该统一成后端总检 contract：

- `diagnosis.issues[*].focus_ref`
- `diagnosis.next_step.focus_ref`
- `diagnosis.operator_decision.next_focus`

只要其中任一层已经明确给出 `node_scene_log`，诊断包就应自动把该节点现场样本带上，而不是再由导出脚本自行重新推导“哪台机器值得看”。

这样海外 Codex、后台自动驾驶和人工交接看到的不是一句“建议去看某台节点”，而是一份已经带着关键现场样本的诊断包。

再往前一步，驾驶建议本身也不应只存在于前端页面，而应成为 ops overview contract 的一部分：

- 后端返回 `driver_recommendations`
- 每条建议附带 `action_code`
- 前端只做动作映射，不再重新计算优先级

继续往下，`driver_recommendations` 也不能只给“同一组 node_codes + 同一份 payload”。

因为真实场景里经常会出现：

- 主动作是 `创建 Rollout`
- 次动作是 `打开点状灰度模板`
- 两个动作对应的目标节点、release_id、预填参数并不相同

所以 contract 还要支持：

- `primary_node_codes`
- `secondary_node_codes`
- `primary_action_payload`
- `secondary_action_payload`

这样海外控制面、Codex 驾驶员、CLI 推荐执行器才能真正做到“同一张建议卡，主次动作各走各的参数”，而不是被迫回退成前端手写分支。

这样未来换成 Codex 自动驾驶或脚本编排时，也能直接复用同一套推荐逻辑。

并且这套 contract 不该只停在“给建议”，而要继续补到“统一执行入口”：

- `POST /api/v1/ops/driver-actions/preview`
- `POST /api/v1/ops/driver-actions/execute`
- 能后端化的动作先统一走这里
- 仍需人工选择、弹窗补参数的动作，再回退到前端交互

其中 `preview` 这层尤其关键，因为它负责把：

- execution chain
- target api / method
- 主次动作 request payload
- runbook resolve 结果

统一冻结成后端 contract。

这样页面、CLI 和海外 Codex 驾驶员都不需要自己重新拼 request preview，也不会再出现“页面自己猜 sequence -> action 映射”的口径漂移。

现在这条链路继续往下已经开始接入：

- `GET /api/v1/ops/playbooks`
- `GET /api/v1/ops/playbook-runs`
- `GET /api/v1/ops/playbook-runs/{run_code}`
- `GET /api/v1/ops/playbook-runs/{run_code}/events`
- `GET /api/v1/ops/activity-stream`
- `POST /api/v1/ops/playbook-runs/{run_code}/rerun`
- `POST /api/v1/ops/playbook-runs/{run_code}/cancel`
- `POST /api/v1/ops/playbooks/preview`
- `POST /api/v1/ops/playbooks/execute`

也就是说，驾驶动作的后端执行入口不再只是“直接发一个动作模板”，而是可以把多步标准动作整体展开。

这样整条链路才是：

- 后端推荐
- 后端标准动作执行
- 前端只做展示和少量交互兜底

再进一步，控制面还要具备“巡检结果收口视图”：

- 一个节点最近的 `health.snapshot`
- 一个节点最近的 `logs.collect`
- 一个节点最近的 `diagnostics.collect`

要能在页面里按节点重新聚合，而不是让操作者自己翻几十条 `ops job` 去拼结果。

这一步很关键，因为它决定了：

- Codex 驾驶员读取的是“节点收口状态”
- 而不是一堆离散任务记录

现在这层也不该继续停留在前端临时聚合，而应该进入正式后端协议：

- `GET /api/v1/ops/overview` 返回 `inspection`
- `GET /api/v1/ops/inspection-overview` 返回独立巡检收口视图
- 页面只负责展示，收口排序、异常优先级、Worker 日志口径都以后端为准

并且这层 contract 不能只停留在“返回一句总结”，还要正式结构化：

- `problem_kind`
- `problem_label`
- `problem_level`
- `recommended_action_code`
- `ui_intent`

这样页面筛选、Codex 自动驾驶、后续策略编排才不需要再从自然语言里反推“这是失败、执行中还是巡检缺口”。

同理，动作模板 contract 也不能继续停留在“只有 text / number / select”：

- `boolean`
- `textarea`
- `text_list`

这三类字段是运维动作真正高频的表达方式：

- `boolean` 用来表达是否自动审批、是否自动回滚、是否切 current
- `textarea` 用来承载 artifact URL、长文本备注、临时参数块
- `text_list` 用来承载服务列表、健康检查 URL 列表、节点列表

否则发布、回滚、批量诊断这些动作永远只能靠前端写死表单，无法真正回收到统一模板层。

尤其 `deploy.release` 这类动作，应该正式进入模板目录，而不是只存在于 rollout 内部：

- `deploy.release.control`
- `deploy.release.worker`
- `deploy.release.custom`

这样单节点灰度验证、点状修复、正式 rollout 之前的预演，才能统一落到同一个 `ops job` 体系里。

模板动作再往前还要补一层正式能力：

- `action template preview`
- `batch policy preview`

也就是在真正创建 `ops jobs` 之前，控制面先基于：

- 目标节点集合
- 当前 execution mode
- 动作 payload
- 集群参与态 / 忙碌态 / control / effective worker 身份

给出统一预检结论：

- `blocked`
- `approval_required`
- `warnings`
- `recommendations`

这样发布、停 Worker、重启 API 这些高风险动作，就不会变成“点了按钮才知道会出事”，而是先看到：

- 哪些节点被阻断
- 哪些节点建议审批
- 哪些只是需要关注

这层能力既服务于页面按钮，也服务于后续的海外 Codex 驾驶员，因为两边都应该调用同一份 policy preview contract，而不是各自写一套风险判断。

在 playbook 这一层，还要继续补一条非常关键的 contract：

- 一次 playbook 执行 = 一次 `playbook run`
- 每个 run 都要有自己的 `run_code`
- 每个子任务都写入统一的 playbook metadata
- 控制面能够把这些子任务重新聚合成：
  - run 总状态
  - step 状态
  - 目标节点集合
  - 最近可追事件的任务入口

这一步的意义是把“多步动作”从前端临时串联，正式升级成可审计、可追溯、可回放的运维对象。

继续补齐 run 级动作之后，控制面就可以直接：

- 对 playbook run 做状态筛选
- 按分组收窄到 onboarding / diagnostics / scene
- 按 run_code、创建来源、目标节点做关键词检索
- 直接查看某轮 run 的 focus summary
- 直接看到 problem steps / active steps

也就是说，控制面针对 playbook run 的 contract 已经不再只是“能聚合”，而是进一步升级成“能定位焦点、能快速追问题”。

再往前一步，playbook run 还必须具备“整轮事件视角”：

- 不是只查某一条 job 的事件
- 而是能把同一 `run_code` 下面所有 job 的事件重新聚合
- 并补齐：
  - `step_key`
  - `step_title`
  - `job_code`
  - `job_status`
  - `target_node_code`

这样海外控制面的详情抽屉才能真正像“远端驾驶舱”，因为它看到的是整轮执行过程，而不是零散子任务的碎片。

现在这层 contract 还要进一步冻结成“前端不再自行翻译”的正式字段：

- `playbook run`
  - `status_label`
  - `summary`
  - `summary_text`
  - `steps_total`
  - `steps_success`
  - `steps_running`
  - `steps_problem`
  - `steps_terminal`
  - `focus_ref`
- `playbook run.steps[]`
  - `status_label`
  - `summary`
  - `summary_text`
  - `target_node_codes`
  - `focus_ref`
- `playbook run events`
  - `level_label`
  - `job_status_label`
  - `summary`
  - `summary_text`
  - `event_key`
  - `occurred_at`
  - `focus_ref`
  - `source_focus_ref`
- `playbook run events.summary`
  - `returned_total`
  - `event_type_counts`
  - `job_status_counts`
  - `filters.limit`

也就是说，从这一步开始：

- 前端不再自己把 `running` 翻译成“收口中”
- 前端不再自己拼“当前焦点摘要”
- 前端也不再把“播放焦点”和“远端执行焦点”混成一个对象

这里还要再补一条非常重要的消费规则：

- `playbook run events.focus_ref`
  - 始终用于定位到本轮 playbook run 的正式落点
- `playbook run events.source_focus_ref`
  - 始终保留远端 Agent / ops job 原始焦点
  - 允许携带：
    - `job_id`
    - `job_code`
    - `event_key`
    - `step_key`
    - 其他执行侧专有定位字段

这样控制面详情抽屉、Codex 驾驶员和后续 CLI 就不会再遇到一个老问题：

- 页面需要跳到“这一轮 playbook 的哪个步骤”
- 但排障又需要知道“远端 Agent 具体卡在了哪条事件”

这两种焦点必须并存，而不能互相覆盖。
- 前端不再自己推断“应该跳到哪一轮 / 哪一步 / 哪条事件”

而是统一消费控制面已经产出的结构化别名字段。

同样，驾驶建议层也开始和 playbook run 正式打通：

- recommendation 不再只推荐“去看哪个节点”
- 而是可以直接推荐“先处理哪轮异常编排”
- 并携带：
  - `run_code`
  - `focus_step_key`
  - `focus_step_title`

这样 recommendation -> playbook run detail -> playbook run events 才形成一条真正闭环的驾驶链路。

继续往前收一层，recommendation 也不该只看 playbook run，而要继续消费统一 activity stream：

- 如果最近存在失败 / 阻断 / 已取消的 standalone `ops job`
- 或存在 `awaiting_approval`、`halted`、`completed_with_issues` 的 rollout
- recommendation 应直接把这条 activity 提升成驾驶建议
- 并通过统一 `ui_intent` 把前端直接送到：
  - `job_events`
  - `rollout_jobs`

这样 recommendation 才真正具备“先聚焦异常活动，再决定是否补动作”的现场驾驶能力。

再继续往下一层，控制面还需要统一的“最近活动入口”：

- 不只是 playbook run
- 也包括 standalone ops jobs
- 以及 rollout 推进记录

所以活动流 contract 也应该成为正式后端协议：

- `GET /api/v1/ops/activity-stream`
- 每条 activity 带：
  - `kind`
  - `activity_key`
  - `status`
  - `status_label`
  - `occurred_at`
  - `summary`
  - `summary_text`
  - `target_node_codes`
  - `ui_intent`
  - `focus_ref`

其中 `ui_intent` 不是让前端自己猜跳哪，而是由后端直接声明：

- `playbook_run_detail`
- `job_events`
- `rollout_jobs`

这样后端不仅能告诉前端“这里有一条异常活动”，还能直接告诉它“应该落到哪一个处理界面”。

这样海外控制面、后台按钮和 Codex 驾驶员才能共享一套“最近活动 -> 正确落点”的跳转 contract。

并且这层不要再停在“页面展示友好字段”，而要正式成为统一驾驶对象：

- `status_label`
  - 直接给页面、CLI、Codex 看的人类可读状态
- `summary_text`
  - 直接给驾驶建议和摘要面板消费的短摘要
- `target_node_codes`
  - 不让调用方再从自然语言里猜目标节点
- `focus_ref`
  - 让页面、CLI、Codex 都能用同一份定位对象跳到：
    - `playbook run`
    - `ops job`
    - `rollout`
    - `execution scene`

这样后续不管是海外 Codex 驾驶员、CLI 还是后台按钮，都能把 activity 当成正式 contract，而不是“页面 table 的一行数据”。

同样，`activity-stream` 里的 `ops_job` 项也要冻结一条优先级规则：

- 如果 job 本身已经带 `result.summary_text`
  - activity 的 `summary_text` 优先使用它
- 如果 job result 里已经带 `focus_ref`
  - activity 的 `focus_ref` 优先吸收它
- 只有在没有明确执行结果摘要时
  - 才回退到“目标节点 / 发起人 / 执行方式”这类模板化描述

原因很简单：

- 模板摘要适合“任务刚创建”
- 结果摘要才适合“任务已经执行过，且远端已经给出结论”

否则页面上会长期出现这种低信噪比口径：

- `目标节点 xxx / 发起 web-ui / 方式 远端 Agent`

但真正更有价值的应该是：

- `远端 Agent 已回传 120 行 Worker 日志，可直接继续分析`

这一点对海外 Codex 驾驶员尤其关键，因为它读取 activity-feed 时，优先需要的是“执行结论”，而不是“模板元信息”。

这条规则继续往下也要落到 Codex brief：

- `codex-brief.entries`
  - 仍然是可执行主线
- `codex-brief.activity_focus`
  - 则是可观察焦点
- `codex-brief.scene_log_observation`
  - 则是节点级现场日志观察摘要
- 如果当前没有动作主线，但已有观察焦点
  - `codex-brief.focus` 允许回退到首条 `activity_focus`
  - 但推荐行为只能是 `open_ui`
  - 不允许伪装成 `auto_execute`
- 如果当前没有动作主线、也没有合适的 activity focus，但现场日志已经识别出明确目标节点
  - `codex-brief.focus` 允许继续回退到 `scene_log_observation.focus_ref`
  - 这样海外 Codex 会直接落到 `node_scene_log`

这样海外 Codex 在“现场正在变化，但暂时没有标准动作要打”的时候，仍然能稳定给出：

- 先盯哪一条
- 回到哪个正式落点
- 为什么现在是观察优先而不是执行优先

接下来 driver-feed / runbook 这一层也必须正式冻结：

- `driver_feed.entries[*]`
  - `focus_ref`
  - `primary_focus_ref`
  - `secondary_focus_ref`
- `runbook_sequences[*]`
  - `focus_ref`
  - `primary_focus_ref`
  - `secondary_focus_ref`

也就是说：

- driver-feed 不再只返回“动作码 + 按钮文案”
- runbook 也不再只返回“主次动作”
- 而是必须同时告诉页面、CLI、Codex：
  - 这条主线整体应该聚焦哪里
  - 主动作对应哪个正式落点
  - 次动作对应哪个正式落点

这样后端才能真正消灭“前端根据 action_code 猜页面落点”的分叉逻辑。

这一层现在还要继续补一条非常实用的分流规则：

- `driver-feed.entries`
  - 仍然表示“驾驶动作主线”
- `driver-feed.activity_focus`
  - 单独表示“观察与跟踪焦点”
  - 不再把观察项硬塞成一条可执行建议
- `driver-feed.scene_log_observation`
  - 单独表示“当前远端日志回传是否已经形成可下钻的节点级现场日志”

也就是说以后海外控制面和 Codex 同时会拿到两类对象：

- 一类是可以继续 preview / resolve / execute 的动作主线
- 一类是当前值得优先盯住的现场对象
  - 例如：
    - 正在跑的 `ops job`
    - 未收口的 `playbook run`
    - 当前 `execution scene`
    - 远端 `log sync`

这样不会再出现一个老问题：

- 页面把“值得先看”误渲染成“可以直接执行”
- Codex 又把“先看现场”误读成“可以自动发动作”

同样的冻结规则还要继续往下压到驾驶执行链：

- `driver-actions/preview`
  - `focus_ref`
  - `primary_focus_ref`
  - `secondary_focus_ref`
  - `primary.focus_ref`
  - `secondary.focus_ref`
- `driver-actions/resolve`
  - `preview_request.focus_ref`
  - `preview_request.primary_focus_ref`
  - `preview_request.secondary_focus_ref`
  - `gate.focus_ref`
  - 顶层 `focus_ref`
- `codex-actions/resolve`
  - `selected_entry.focus_ref`
  - `preview_request.focus_ref`
  - `gate.focus_ref`
  - 顶层 `focus_ref`

只有这样页面、CLI、海外 Codex 驾驶员在 preview / resolve / execute 三段链路里，才不会重新猜“当前应该回看哪个 release、哪个 rollout、哪个 execution scene”。这也是后续 NodeAgent、ReleaseHub、OpsCenter 可以共享同一份驾驶协议的关键。

进一步说，`activity-stream` 不只是最近事件列表，还应该是正式可筛选的观察面：

- `kind`
- `status`
- `query`

这些过滤条件必须后端支持，而不是只在前端本地过滤。这样未来：

- 海外 Codex 驾驶员
- CLI 检查脚本
- 后台页面

三者都可以复用同一套活动流收口逻辑。

继续升级之后，`driver action` 的协议也不该停在“一个 action_code”：

- 应返回：
  - `handled`
  - `mode`
  - `ui_intent`
- 其中 `ui_intent` 用来表达：
  - 应打开哪个详情页
  - 应聚焦哪一轮 playbook run
  - 应进入哪个发布入口
  - 应打开哪个节点接管入口

这一步的价值很大，因为它意味着：

- recommendation 的解释权回到后端
- 前端变成“执行/跳转承载层”
- 后续如果换成海外 Codex 驾驶员，仍然可以直接复用同一份 intent contract

- 对某一轮编排做统一重跑
- 对某一轮编排做统一取消
- 不需要再由前端把同一批子任务逐条循环处理

这正是“海外控制面统一驾驶，大陆节点被托管执行”的关键基础。

同理，execution scene contract 也不该只是“参与节点数组 + 待命节点数组”，而要继续收成更明确的运行口径：

- `dispatch_active_nodes`
- `recent_only_nodes`
- `standby_nodes`
- `load_syncing_nodes`

以及日志回传本身的正式状态：

- `disabled`
- `waiting_sample`
- `partial_coverage`
- `healthy`
- `full_capture`

并且要直接返回：

- 覆盖了多少参与节点
- 哪些参与节点还没回传样本
- 当前推荐动作文案

这样页面、Codex 驾驶员和后续自动化脚本都能共享同一套“现场观察 -> 判断缺口 -> 执行动作”的协议，而不是各自再做一次前端猜测。

这样未来新增：

- Codex 自动巡检
- 后台按钮巡检
- 节点接管后的首轮验收
- 发布后的批次验收

都能直接复用同一个 inspection contract。

在收口视图之上，还应该继续有“异常节点优先队列”：

- 先处理失败 / 阻断 / 取消
- 再处理仍在执行中的节点
- 再处理尚未形成完整巡检记录的节点

另外标准巡检里的 `logs.collect` 应明确限定为 Worker 日志收口，不应把 Node Agent 的辅助排障日志混成同一类结果。

当前第一版 agent 执行器已经覆盖：

- `service.start`
- `service.stop`
- `service.restart`
- `service.status`
- `health.snapshot`
- `logs.collect`
- `diagnostics.collect`
- `deploy.release`

后续继续增强时，只需要在这条主链路上加能力，不需要重换架构。

---

## 三、Agent 标准执行流程

### 1. 签发 token

控制面给节点签发一枚 agent token。

### 2. 节点注册

节点启动后调用：

- `register`

上报：

- `node_code`
- `region`
- `role`
- `agent_version`
- `capabilities`
- `labels`
- `hostname`
- `ip`

### 3. 节点心跳

节点周期调用：

- `heartbeat`

控制面更新：

- `last_seen_at`
- agent 元数据
- 节点在线状态依据

### 4. 节点拉任务

节点调用：

- `pull`

控制面返回分配给该节点的 `ops job`。

### 5. 节点开工

节点拿到 job 后先调用：

- `jobs/{id}/start`

这一步不是可有可无，而是为了把“任务已派发”和“任务已真实开始执行”区分开。

### 6. 节点完工

执行结束后调用：

- `jobs/{id}/complete`

上报：

- `success / failed / partially_succeeded`
- `stdout`
- `stderr`
- `result json`

### 7. 节点事件流

执行过程中可持续调用：

- `jobs/{id}/events`

把中间事件推回控制面。

---

## 四、为什么要有 Release Hub

因为正式环境不应该继续依赖：

- 节点自己 `git pull`
- 工作区状态不确定
- root/www 用户混跑

正式版必须把“版本”变成平台中的一级对象。

也就是：

> 先有 Release，再有 Deploy

---

## 五、当前已经落下的 Release Hub 骨架

当前后端已经补出：

- `POST /api/v1/ops/releases`
- `GET /api/v1/ops/releases`
- `GET /api/v1/ops/releases/latest`
- `GET /api/v1/ops/releases/{id}`
- `POST /api/v1/ops/releases/{id}/activate`
- `POST /api/v1/ops/releases/{id}/rollouts`
- `GET /api/v1/ops/rollouts/{id}`
- `GET /api/v1/ops/rollouts/{id}/jobs`
- `POST /api/v1/ops/rollouts/{id}/advance`

并落了两类核心对象：

- `ops_releases`
- `ops_release_rollouts`

这意味着后面发布系统可以正式围绕：

- 版本号
- 渠道
- commit sha
- artifact url
- checksum
- 激活版本

来运作。

但是 Release Hub 还不能只回答“有没有版本”，还要回答：

> 现在这版到底能不能发

因此控制面里还需要一个正式门禁对象：

- `release_hub.default_rollout_gate`

它至少要返回：

- 默认 Release
- 默认 Rollout 目标节点
- 门禁状态：
  - `missing_release`
  - `release_not_ready`
  - `artifact_missing`
  - `no_targets`
  - `blocked`
  - `attention`
  - `ready`
- 阻断原因
- 告警原因
- 推荐动作
- `remote_agent_ready_nodes / nodes_total`
- `inspection_healthy_nodes / nodes_total`

这样首页驾驶建议、Release Hub 顶部摘要、Codex 自动驾驶、真正发 Rollout 前的 preview，才能统一读同一份门禁判断。

---

## 六、现在这版 rollout 已经不只是“建记录”

当前 rollout 已经补上三类关键能力：

- 分批推进
- rollout 与 ops job 关联
- 执行结果自动反推 rollout 状态

也就是说，控制面不再是一次性给所有节点平铺发任务，而是可以表达：

- 第一批先发 `1` 台 canary
- 健康后再发后续批次
- 某批失败则暂停
- 人工确认后继续下一批

当前 rollout 状态会根据 job 结果自动进入：

- `planned`
- `running`
- `awaiting_approval`
- `ready_for_next_batch`
- `halted`
- `completed`
- `completed_with_issues`

这已经非常接近正式发布系统的骨架，而不是临时脚本。

---

## 七、终局版发布链路

推荐的正式发布链路：

1. 海外控制面构建 release
2. 写入 `ops_releases`
3. 标记某个 channel 的 active release
4. 后台点击“部署 release”
5. 生成 `ops job`
6. node-agent 拉取任务
7. 下载 artifact
8. 校验 checksum
9. 切换版本
10. 重启服务
11. 健康检查
12. 成功或回滚

当前后端也已经补出：

- Release 对象
- Release 激活
- Rollout 对象
- `release -> rollout -> deploy jobs` 分批生成
- rollout 推进接口
- 节点执行结果回写后自动刷新 rollout 总结

这意味着后续真正接发布包仓库时，只需要把 artifact 构建和分发接入，不需要再重新设计控制面对象模型。

---

## 八、Node Agent 侧的发布保险丝

当前 `deploy.release` 执行链路已经补上：

- 下载 artifact
- checksum 校验
- 解压到 `releases/<version>`
- 切换 `current` 软链
- 重启指定服务
- 执行健康检查
- 健康失败时回滚到旧版本

健康检查目前支持：

- `systemctl is-active`
- HTTP URL 探测

并且 agent 会把关键事件回推控制面，例如：

- `deploy_download_started`
- `deploy_checksum_verified`
- `deploy_current_switched`
- `deploy_health_failed`
- `deploy_rollback_completed`

这套事件流很重要，因为后面后台和 Codex 都是靠这条链路看懂“节点到底做到了哪一步”。

所以事件 contract 也要继续冻结，而不能只返回一行原始 message：

- 每条 job event 至少应带：
  - `event_key`
  - `event_type`
  - `level`
  - `level_label`
  - `summary`
  - `occurred_at`
  - `ui_intent`
- 任务事件接口本身还要有 `summary`：
  - `returned_total`
  - `level_counts`
  - `event_type_counts`
  - `node_counts`
  - `latest_at`

这样海外控制面打开“任务事件流”时，先看到的是结构化执行回放，而不是先读一大串原始日志文本。

---

## 九、为什么这套设计后续最省心

因为它把三件事情分清楚了：

- `release` 是版本对象
- `ops job` 是动作对象
- `node agent` 是执行对象

后面不管节点从 `3` 台增加到 `30` 台，还是 Codex 接管更多动作，这三层都不用推翻。

---

## 十、接管不是终点，要有“验收后直接进入正式运维”的桥

实际落地里最容易断掉的一环，不是 token，也不是 heartbeat，而是：

> 节点明明已经接进来了，但接下来该做什么，操作员还得自己切页面、自己填 node_code、自己判断先巡检还是先发布。

这会把接管成功后的效率重新打回人工模式。

所以控制面里要把 Node Agent 接管链路拆成三段：

### 1. 接入观察

用于回答：

- token 是否有效
- node agent 是否已经 register
- heartbeat 是否稳定
- 当前是 `未纳管 / 待接入 / 已接管 / 心跳过期`

### 2. 标准验收

接管完成后，不应该直接默认“节点已经可用”，而是先跑一轮固定验收动作：

1. `health.snapshot`
2. `service.status(domaincheck-node-agent)`
3. `logs.collect(domaincheck-node-agent)`
4. `service.status(domaincheck-worker)`
5. `logs.collect(domaincheck-worker)`

这轮验收的意义不是“多做几步”，而是把最常见的接管隐患一次性暴露出来：

- 服务虽然启动了，但 register 没成功
- heartbeat 有，但 pull / complete 异常
- worker 在线，但 Redis / DB / proxy 配置不对
- systemd 看似 active，但日志里已经反复报错

### 3. 正式运维入口

如果标准验收通过，控制面不能只显示一个“已通过”标签，而要直接给出两类后续入口：

- `进入巡检模式`
  默认锁定当前节点，直接预填 `diagnostics.collect`
- `进入发布模式`
  默认锁定当前节点，直接预填目标 release 和单节点 rollout

这样节点接管就形成了完整闭环：

> 看见节点 -> 纳管 -> 签发接入方案 -> 接入观察 -> 标准验收 -> 巡检 / 发布

而不是“接进来之后又回到人工记忆和手填”。

当前前端已经按这个思路落了一版：

- 接管弹窗里增加“接管验收结论”
- 可一键跑标准验收
- 验收通过后，直接出现：
  - `进入巡检模式`
  - `进入发布模式`
- 节点会自动锁定为当前接管节点
- 发布会默认带上当前选中的 release，没有 release 时直接提示先创建

并且 OpsCenter 现在不再只是“有按钮”，而是开始把 contract 直接展示到关键弹窗里：

- `生成 Node Agent 接入方案`
  - 明确显示当前使用 `ops_agent_protocol`
  - 展示主入口、schema 文档、发现入口、执行链路
- `创建 Release`
  - 明确显示当前使用 `release_hub_contract`
  - 展示 release 主入口、launchpad、schema 文档、发布链路
- `创建 Rollout`
  - 明确显示当前使用 `release_hub_contract`
  - 展示 rollout 主入口、launchpad、execution_mode、执行链路
- `驾驶建议 / 驾驶主线 / 自动驾驶判断`
  - 可直接打开“驾驶动作契约预览”
  - 展示 `ops_driver_contract`、目标 API、执行链路、request preview
  - `overview / driver-feed` 已下沉到后端 `driver-actions/resolve` / `driver-actions/execute-resolved`
  - `driver-actions/preview` 保留为基础契约预览与兜底入口
  - `codex-focus-preview` / `codex-focus-run` 进一步下沉到后端 `codex-actions/resolve` / `codex-actions/execute`
  - 把“这次点击到底会调用什么”从黑盒按钮变成可审阅对象

命令行侧也开始走同一条 contract 预览链：

- `bash domain-api/deploy/multi-region/drive_ops_center.sh contracts`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-feed`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-focus-preview`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-focus-run`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-preview ...`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-resolve ...`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-run ...`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh runbook-preview ...`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh runbook-run ...`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh codex-focus-preview`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh codex-focus-run`

这样海外主机上即使不打开页面，也能先看到统一 contract，再决定要不要执行。

这里还要再收一条非常重要的约束：

- `codex-focus-preview / codex-focus-run`
  - 不能只认 `codex-brief.entries`
  - 当当前没有动作主线、但存在 `codex-brief.activity_focus` 时
    - 应允许选中观察焦点
    - 并统一收口为 `focus_activity_item`
    - 其 gate 必须落到 `open_ui`
    - 不能伪装成 `auto_execute`

并且这条命令链现在已经补上了真正面向“单脑驾驶”的默认入口：

- `driver-feed`
  - 看当前驾驶主线
- `driver-focus-preview`
  - 默认消费 `driver-feed.top_recommendation`
  - 没传 `entry_key` 时，不再要求人工先抄 `action_code`
  - 如果显式传入的是 `activity_focus.key`
    - 应自动收口为 `focus_activity_item`
    - 只做“进入工作区”的观察焦点，不升级成自动执行
- `driver-focus-run`
  - 先按同一条 focus 生成 `resolve / execute-resolved` 请求
  - 自动兼容：
    - 普通 `driver_action`
    - `runbook_sequence`
    - `secondary`
    - `confirm`

这样后续海外 Codex 驾驶员拿到的就不是“很多离散脚本”，而是一条稳定的动作主线：

1. 看 `driver-feed`
2. 选 `top_recommendation`
3. 先 `preview`
4. 再按门禁 `run`

并且 `codex-focus-run` 已经开始真正落地“驾驶门禁”：

- `safe_auto`
  - 直接执行
- `guarded_auto`
  - 默认不执行，只输出审阅结果
  - 只有显式 `confirm` 才放行
- `resolve_first / open_ui / blocked`
  - 一律不执行，只给出原因和目标入口

现在这层门禁已经不再由 CLI 本地解释，而是由后端统一返回：

- `selected_entry`
- `preview`
- `gate`
- `execution_result`

这样后续海外 Codex 驾驶员就不是“会调接口的脚本”，而是严格受同一份后端 contract 和门禁规则约束。

这样后续不管是人工点击、CLI 脚本调用，还是海外 Codex 驾驶员接管，都不会再出现“页面这样理解、后端那样理解、节点执行又是第三套”的口径漂移。

Release Hub 自己也要走同一套“标准动作对象”思路，而不是继续靠页面里临时拼表单。

当前已经开始往这条线上收：

- `发节点任务` 不再只是一个通用入口，而是正式区分：
  - `deploy.release.control`
  - `deploy.release.worker`
  - `deploy.release.custom`
- 同时命令行侧的 `check_release_hub.sh` 也会直接输出：
  - release 模板摘要
  - 控制面批量预检
  - Worker 批量预检
  - 混合节点预检

这样页面按钮、海外 Codex 驾驶员、CLI 自检脚本三者看到的就是同一套发布口径，而不是三套不同的发布逻辑。

这一步非常关键，因为它把：

- Node Agent 接管
- Ops Job
- Release Hub

第一次真正接成了一条连续工作流。

---

## 十一、正式协议收口原则

为了让后续开发不再反复改口径，这套体系必须先明确 6 条协议原则：

### 1. 前后端与 Codex 共用同一份 contract

同一个动作、同一个节点、同一轮 rollout，必须由后端返回统一结构：

- 页面直接展示
- Codex 直接判断
- CLI 直接检查

不能让三边各自“再推导一次”。

### 2. 所有远控动作都要先变成对象

最终要统一成：

- `release`
- `rollout`
- `ops job`
- `playbook run`
- `activity`

而不是：

- 页面点按钮直接跑 shell
- Codex 临时拼命令
- 节点本地脚本自己决定做什么

### 3. Node Agent 只执行已声明动作

Agent 不应该接受任意 shell 文本，而应该只接受标准动作：

- `service.start`
- `service.stop`
- `service.restart`
- `service.status`
- `health.snapshot`
- `logs.collect`
- `diagnostics.collect`
- `deploy.release`

这样控制面才能做审计、门禁、批量预检和回滚。

### 4. 所有对象都必须能审计

至少都要带：

- `created_at`
- `updated_at`
- `requested_by`
- `target_node_code / target_nodes`
- `status`
- `result`

后面不管是人、后台还是 Codex 都要能回放过程。

### 5. 协议必须支持“逐步增强”

当前已经落下的是第一版骨架，所以协议要区分：

- `当前已实现字段`
- `后续建议补充字段`

这样可以先稳定主链路，再逐步增强，而不是一开始就推翻。

### 6. API 返回必须统一包裹

当前所有接口都已经走：

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

所以后面所有新增接口也应继续遵守：

- `code=0` 表示成功
- `code=1` 表示业务失败
- 具体错误语义继续放进 `message` 和后续建议补的 `detail_code`

---

## 十二、Node Agent HTTP 协议

### 1. 公共约束

#### 请求头

Agent 相关接口统一使用：

- `Content-Type: application/json`
- `X-Domaincheck-Agent-Token: <token>`

其中：

- `tokens`
- `bootstrap-plan`

是控制面主动签发，不要求 agent token。

而以下接口要求带 token：

- `register`
- `heartbeat`
- `pull`
- `jobs/{id}/start`
- `jobs/{id}/complete`
- `jobs/{id}/events`

#### 公共节点载荷

当前代码里的 `_base_payload()` 已经收敛出最小节点信息：

- `node_code`
- `region`
- `role`
- `title`
- `hostname`
- `ip`
- `agent_version`
- `capabilities`
- `labels`
- `metadata.service_names`
- `metadata.delivery_queue`

这意味着后续页面、Codex 和 agent 日志里看到的节点身份，应该都围绕这组字段统一。

其中 `metadata.delivery_queue` 当前已经是正式 contract，而不是预留字段。它至少会带：

- `state`
- `label`
- `reason`
- `pending_count`
- `dead_letter_count`
- `last_flush_at`
- `oldest_pending_at`
- `oldest_dead_letter_at`

也就是说，heartbeat 不只是在汇报“Agent 还在线”，也在汇报：

> 当前本地是否有待补发回执、是否已经出现死信、最近一次补发冲刷是否成功

---

### 2. 签发 Agent Token

`POST /api/v1/ops/agent/tokens`

#### 请求体

```json
{
  "node_code": "mainland-worker-02",
  "issued_by": "web-ui",
  "expires_in_hours": 72,
  "metadata": {
    "source": "ops-center"
  }
}
```

#### 当前返回字段

- `token`
- `token_preview`
- `record_id`
- `node_code`
- `expires_at`
- `created_at`

#### 设计要求

这一步只做“签发”，不做安装、不做纳管、不做启动。

也就是说：

- token 是凭证对象
- bootstrap plan 才是接入方案对象

---

### 3. 生成 Bootstrap Plan

`POST /api/v1/ops/agent/bootstrap-plan`

#### 请求体

```json
{
  "node_code": "mainland-worker-02",
  "node_region": "mainland",
  "node_role": "worker",
  "issued_by": "web-ui",
  "expires_in_hours": 72,
  "control_plane_base_url": "https://ops.example.com",
  "root_dir": "/opt/domaincheck",
  "metadata": {
    "source": "ops-center"
  }
}
```

#### 当前返回字段

当前后端 `build_node_agent_bootstrap_plan()` 已返回：

- token 相关字段
- `control_plane_base_url`
- `bootstrap_plan.node_code`
- `bootstrap_plan.node_region`
- `bootstrap_plan.node_role`
- `bootstrap_plan.root_dir`
- `bootstrap_plan.env_file`
- `bootstrap_plan.service_name`
- `bootstrap_plan.service_file`
- `bootstrap_plan.install_script_path`
- `bootstrap_plan.env_content`
- `bootstrap_plan.command_lines`
- `bootstrap_plan.command_block`
- `bootstrap_plan.health_checks`
- `bootstrap_plan.health_check_block`
- `bootstrap_plan.bootstrap_script_name`
- `bootstrap_plan.bootstrap_script_path`
- `bootstrap_plan.bootstrap_script_content`
- `bootstrap_plan.bootstrap_run_script_block`

#### 正式定位

`bootstrap_plan` 不只是“给一段命令”，它是：

> 控制面签发给目标节点的一份标准接管方案

后续：

- 页面按钮
- Codex 驾驶员
- CLI 辅助脚本

都应该复用这一个对象，不再自己拼接 env 或 shell。

---

### 4. Agent Register

`POST /api/v1/ops/agent/register`

#### 请求体

```json
{
  "node_code": "mainland-worker-02",
  "region": "mainland",
  "role": "worker",
  "title": "mainland-worker-02",
  "hostname": "host-a",
  "ip": "10.0.0.12",
  "agent_version": "0.1.0",
  "capabilities": [
    "service.start",
    "service.stop",
    "service.restart",
    "service.status",
    "health.snapshot",
    "logs.collect",
    "diagnostics.collect",
    "deploy.release"
  ],
  "labels": {},
  "metadata": {
    "service_names": {
      "api": "domaincheck-api",
      "worker": "domaincheck-worker",
      "sync_agent": "domaincheck-sync-agent",
      "node_agent": "domaincheck-node-agent"
    }
  }
}
```

#### 当前返回字段

- `node_code`
- `expires_at`
- `capabilities`

#### 后端当前行为

当前 `agent_register()` 会：

- 校验 token 与 `node_code`
- 调 `_upsert_agent_runtime()`
- 更新 `ops_managed_nodes`

所以 register 的实际语义是：

> 让节点正式进入“已接管候选 / 已纳管”目录

---

### 5. Agent Heartbeat

`POST /api/v1/ops/agent/heartbeat`

#### 请求体

当前与 register 共用同一份最小节点载荷。

#### 当前返回字段

- `node_code`
- `server_time`
- `expires_at`

#### 协议语义

heartbeat 不是简单“在线 ping”，而是：

- 刷新 last seen
- 刷新节点身份与 service_names
- 维持控制面里 Node Agent 在线态
- 同步回执队列现场快照

#### 当前已落地的队列快照字段

当前 heartbeat 已经会通过 `metadata.delivery_queue` 上报：

- `state`
  - `healthy`
  - `retrying`
  - `dead_letter`
- `pending_count`
- `dead_letter_count`
- `last_flush_at`
- `oldest_pending_at`
- `oldest_pending_request_id`
- `oldest_pending_kind`
- `oldest_dead_letter_at`
- `oldest_dead_letter_request_id`
- `oldest_dead_letter_kind`

#### 后续建议补充字段

后续建议 heartbeat 再扩：

- `active_jobs`
- `disk_free_mb`
- `load_average`
- `python_version`

其中 `local_queue_depth` 这一类信息，当前已经由 `delivery_queue` 快照承接，不再是空白能力。

---

### 6. Agent Pull

`POST /api/v1/ops/agent/pull?limit=1`

#### 请求体

```json
{
  "node_code": "mainland-worker-02"
}
```

#### 当前后端行为

当前 `agent_pull_jobs()` 只派发：

- `target_node_code = 当前节点`
- `status = queued`
- `execution_mode = remote-agent`

并在派发时自动改成：

- `ops_jobs.status = dispatching`
- `ops_job_steps.status = dispatching`

然后写入事件：

- `agent_dispatched`

#### 当前返回字段

```json
{
  "jobs": [
    {
      "id": 123,
      "job_code": "ops-xxx",
      "action": "health.snapshot",
      "target_node_code": "mainland-worker-02",
      "status": "dispatching",
      "execution_mode": "remote-agent",
      "payload": {},
      "metadata": {},
      "policy": {},
      "steps": []
    }
  ],
  "count": 1
}
```

#### 正式约束

后续就算扩到批量拉取，也应继续遵守：

- agent 只能拿到属于自己的 job
- agent 不负责选择 job
- 调度权始终在控制面

---

### 7. 标记任务开始

`POST /api/v1/ops/agent/jobs/{job_id}/start`

#### 请求体

```json
{
  "node_code": "mainland-worker-02"
}
```

#### 当前后端行为

当前 `agent_mark_job_started()` 会：

- 把 `ops_jobs.status` 改成 `running`
- 把同 job 的 steps 改成 `running`
- 写入 `agent_started`

#### 设计要求

这一步必须保留，不能省略。

因为：

- `dispatching` 表示控制面已派发
- `running` 表示节点已真实开始执行

这两者对排障非常重要。

---

### 8. 标记任务完成

`POST /api/v1/ops/agent/jobs/{job_id}/complete`

#### 请求体

```json
{
  "node_code": "mainland-worker-02",
  "client_request_id": "complete-ops-123-1",
  "status": "success",
  "stdout": "",
  "stderr": "",
  "result": {
    "summary": "ok"
  },
  "error_message": ""
}
```

#### 当前允许状态

- `success`
- `failed`
- `partially_succeeded`

#### 当前后端行为

`agent_complete_job()` 会：

- 校验 job 属于该节点
- 基于 `client_request_id` 做完成回执幂等
- 更新 `ops_jobs.status`
- 写入 `result_json`
- 回写 `error_message`
- 更新全部 `ops_job_steps`
- 写入 `agent_completed`
- 如果 job 属于 rollout，自动刷新 rollout 汇总

#### 正式约束

节点只负责回写：

- 结构化结果
- stdout/stderr
- 失败原因

不负责自己修改 rollout 策略、release 状态或下个批次。

这些都必须仍由控制面决定。

#### 当前已落地的幂等键

当前 `complete` 已支持：

- `client_request_id`

控制面会把它落到：

- `ops_jobs.last_agent_complete_request_id`

因此同一个完成回执即使因为网络抖动被重复补发，也不会再次制造副作用。

---

### 9. 上报中间事件

`POST /api/v1/ops/agent/jobs/{job_id}/events`

#### 请求体

```json
{
  "node_code": "mainland-worker-02",
  "client_event_id": "event-ops-123-checksum-1",
  "step_id": 0,
  "event_type": "deploy_checksum_verified",
  "level": "info",
  "message": "checksum ok",
  "payload": {
    "checksum": "sha256:..."
  }
}
```

#### 当前后端行为

`agent_append_job_event()` 会：

- 校验 token 和 node_code
- 基于 `client_event_id` 做事件幂等
- 追加结构化事件
- 返回 `event_id`

#### 正式要求

中间事件不能只传纯文本，至少还要带：

- `event_type`
- `level`
- `message`
- `payload`

因为后面：

- 页面活动流
- rollout 详情
- playbook run events
- Codex 驾驶员

都依赖结构化事件，而不是只靠日志文本猜。

#### 当前已落地的事件去重约束

当前事件表已经有：

- `ops_job_events.client_event_id`
- `uq_ops_job_events_job_client_event`

所以同一个事件即使被 Agent 重放，也应继续表现为：

- 控制面接收成功
- 不重复制造第二条事件

---

## 十三、Node Agent 状态机

### 1. Token 状态机

- `issued`
- `disabled`
- `expired`

当前代码里 `ops_node_tokens` 已具备：

- `is_enabled`
- `expires_at`
- `last_used_at`

所以 token 生命周期应该正式解释成：

- `issued + enabled + 未过期`：可用
- `issued + disabled`：不可用
- `issued + 已过期`：不可用

---

### 2. 节点接管状态机

页面与控制面应该统一理解为：

- `未纳管`
- `待接入`
- `已接管`
- `仅运行态在线`
- `心跳过期`
- `token 过期 / 已禁用`

建议正式映射为：

- `discovered`
- `pending_bootstrap`
- `agent_online`
- `runtime_only`
- `stale`
- `token_invalid`

前端显示名可以中文化，但后端内部最好固定英文状态码。

---

### 3. Job 状态机

当前主链路已经形成：

- `queued`
- `dispatching`
- `running`
- `success`
- `failed`
- `partially_succeeded`

正式语义应固定为：

- `queued`：已创建，尚未派发
- `dispatching`：控制面已派发给节点，但节点尚未确认开工
- `running`：节点已开始执行
- `success`：完成且成功
- `failed`：完成且失败
- `partially_succeeded`：部分成功，需要人工关注

这套状态机后面不能再随意改名，否则活动流、巡检收口、rollout 汇总都会被打散。

---

## 十四、`ops job` 的 Agent 执行载荷标准

这部分后续建议直接以 [ops_job_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_job_contract.md:1) 为任务对象母本，再由 [ops_agent_protocol.md](/www/wwwroot/getDomain/docs/schemas/ops_agent_protocol.md:1) 继续冻结 Agent 视角下的拉取、开工、完工与事件回执协议。

### 1. Agent 可见 job 最小字段

Agent 从 `pull` 接口拿到 job 时，最少应该依赖这些字段：

- `id`
- `job_code`
- `action`
- `target_node_code`
- `execution_mode`
- `payload`
- `metadata`
- `policy`

其他字段如：

- `requested_by`
- `risk_level`
- `approval_status`
- `rollout_id`

虽然不是最小执行必需，但建议一起保留，便于未来 agent 诊断与本地审计。

### 2. 结构化动作必须优先

当前 agent 已按动作名分发：

- `supports_structured_action(action)`
- `execute_structured_action(...)`
- `execute_release_action(...)`

这条设计必须坚持：

- 先结构化动作
- 再结构化 payload
- 最后才在执行器内部落成本地命令

不能反过来回到“控制面下发整段 shell”。

### 3. `deploy.release` 的 payload 基线

当前 release 执行器已经支持的正式意图至少包括：

- artifact 下载
- checksum 校验
- 解压到 `releases/<version>`
- 切换 `current`
- 重启服务
- 健康检查
- 失败回滚

因此 `deploy.release` 的 payload 应长期固定围绕：

- `release_version`
- `artifact_url`
- `checksum`
- `restart_services`
- `health_check_urls`
- `health_check_timeout_seconds`
- `health_check_retries`
- `health_check_interval_seconds`
- `rollback_on_failure`
- `switch_current`

这套字段已经足够支撑正式 release 部署。

### 4. `logs.collect` 的口径

标准巡检里的 `logs.collect` 应优先解释为：

> 收集目标服务日志，而不是执行任意日志命令

正式建议字段：

- `service_name`
- `lines`
- `include_agent_logs`
- `since_seconds`

并且默认仍要优先收口：

- `domaincheck-worker`
- `domaincheck-node-agent`

而不是允许页面任意填系统命令。

---

## 十五、Release Hub 正式契约

### 1. Release 对象

当前 `ops_releases` 已具备：

- `release_version`
- `channel`
- `commit_sha`
- `status`
- `artifact_url`
- `checksum`
- `notes`
- `metadata`
- `created_by`
- `created_at`
- `activated_at`

现在正式 contract 还需要进一步固定这些别名字段：

- `status_label`
- `summary`
- `summary_text`
- `focus_ref`

正式上应把 Release 理解为：

> 一份不可变版本记录

也就是说：

- release 创建后，不应该允许直接把它重新指向另一份 artifact
- 同一 `release_version` 只对应一份发布物

### 2. Rollout 对象

当前 `ops_release_rollouts` 已具备：

- `release_id`
- `rollout_code`
- `target_selector`
- `target_nodes`
- `policy`
- `status`
- `batch_cursor`
- `batches_total`
- `jobs_total`
- `jobs_created`
- `result_summary`

而 rollout 这一层也不该再只返回“原始推进计数”，还应稳定返回：

- `status_label`
- `target_node_codes`
- `summary`
- `summary_text`
- `focus_ref`

所以 rollout 的正式定义应为：

> 某个 release 在某批目标节点上的一次分批推进计划

### 3. `default_rollout_gate`

这层是 Release Hub 最关键的后端 contract，必须作为正式对象保留。

至少应返回：

- `status`
- `status_label`
- `status_type`
- `summary`
- `summary_text`
- `release`
- `execution_mode`
- `execution_mode_label`
- `target_node_codes`
- `default_target_node_codes`
- `blocking_reasons`
- `warning_reasons`
- `recommendations`
- `operational_readiness.summary`
- `operational_readiness.rows`
- `focus_ref`

#### 推荐状态码

- `missing_release`
- `release_not_ready`
- `artifact_missing`
- `no_targets`
- `blocked`
- `attention`
- `ready`

这组状态码后面必须同时服务：

- 首页驾驶建议
- Release 页面门禁卡
- Rollout 预检
- Codex 自动驾驶

### 4. `release_launchpad`

除了默认门禁外，还应保留更偏“驾驶舱”的发布聚合对象：

- `latest_package`
- `latest_release`
- `worker_rollout_preview`
- `control_rollout_preview`
- `launchpad_status`

其中 `launchpad_status` 至少应回答：

- 当前应该先补什么
- 推荐动作码是什么
- 推荐执行方式是什么
- 是先看 Worker 预案还是先看 Control 预案
- 当前是否还存在接入缺口
- 首个缺口节点是谁
- 这个缺口是
  - `bootstrap_pending`
  - 还是 `acceptance_ready`

并且这层也应该直接给出：

- `summary_text`
- `focus_ref`
- `recommended_target_node_code`
- `recommended_recovery_label`
- `recommended_recovery_summary`
- `onboarding_bootstrap_pending_nodes`
- `onboarding_acceptance_ready_nodes`

其中 `focus_ref` 不该只是“回到 release hub”这么模糊，而应该允许继续携带：

- `section`
- `mode`

这样页面、CLI、Codex 都不需要自己再推断“该跳回 release hub 的哪个区域”。

这里再固定一个已经收口成代码字段的判断口径：

- 如果 `launchpad_status.recommended_action_code` 已经落在
  - `bootstrap_run`
  - `run_acceptance`
- 那么页面、CLI、Codex 不应再只显示笼统的“待补执行面”
- 而应直接把以下字段作为主提示：
  - `recommended_target_node_code`
  - `recommended_recovery_label`
  - `recommended_recovery_summary`
  - `onboarding_bootstrap_pending_nodes`
  - `onboarding_acceptance_ready_nodes`

原因是：

- 真正的阻断并不总是“发布包有问题”
- 很多时候是“发布包已经好了，但节点还没接管完”
- 如果 launchpad 只返回一个大而化之的 `attention`
  前端和 Codex 还得再各自遍历 gap rows 去猜
- 这会重新制造多套判断逻辑

所以现在要把 launchpad 的缺口口径固定成：

- `launchpad_status`
  直接给驾驶层结论
- `gap_rows`
  继续给详情层做下钻

而不是反过来让驾驶层去解析详情层。

当前仓库里这套骨架已经存在，所以后续不要再新造第四套发布摘要模型。

---

## 十六、Rollout 状态机

当前 rollout 状态已经接近正式版，建议固定为：

- `planned`
- `running`
- `awaiting_approval`
- `ready_for_next_batch`
- `halted`
- `completed`
- `completed_with_issues`

### 正式语义

- `planned`：已创建，尚未开始发批次
- `running`：当前批次已发出，正在等待 job 结果
- `awaiting_approval`：下一步推进需要人工确认
- `ready_for_next_batch`：当前批次通过，可进入后续批次
- `halted`：由于失败、阻断或人工暂停而停止
- `completed`：全部批次完成且整体健康
- `completed_with_issues`：全部批次结束，但存在失败或告警

后续不建议再引入新的近义状态名，否则页面和 Codex 会反复适配。

---

## 十七、错误码、幂等与重试规则

### 1. `detail_code` 已经进入 Agent / Ops 主链路

现在统一响应体已经有：

- `code`
- `message`
- `data`

而且 `detail_code` 已经开始进入顶层或 `data` 中，成为控制面和 Agent 都能消费的结构化错误语义。

这层现在的意义不再是“未来建议”，而是：

> 不再靠中文 message 猜失败原因，而是让页面、Codex 和 Node Agent 共用同一份错误码

当前主链路里的错误返回，已经会继续补：

- `detail_code`

例如：

- `agent_token_invalid`
- `agent_token_expired`
- `agent_token_node_mismatch`
- `ops_job_not_owned_by_agent`
- `ops_job_invalid_status_transition`
- `release_checksum_mismatch`
- `release_health_check_failed`

这样页面和 Codex 就不用再从中文 message 里反推错误类型。

### 2. 幂等 contract

当前已经正式落地两条关键幂等线：

- `complete`
  - 使用 `client_request_id`
  - 回写到 `ops_jobs.last_agent_complete_request_id`
- `events`
  - 使用 `client_event_id`
  - 通过 `uq_ops_job_events_job_client_event` 去重

这意味着 Agent 在遇到控制面瞬断、网络抖动或重试补发时，已经具备：

- 回执不重入
- 事件不重复落库

后续仍建议继续保持幂等的动作有：

以下动作应该尽量幂等：

- `register`
- `heartbeat`
- `bootstrap-plan`
- `activate release`
- `rollout preview`

也就是重复请求最多刷新状态，不应制造重复副作用。

### 3. Agent 重试与本地补发规则

建议正式约束，并且当前主链路已经落下一版：

- `register` 失败：指数退避重试
- `heartbeat` 失败：短退避重试，不立即退出
- `pull` 失败：进入轮询退避
- `start/complete/events` 失败：本地保留待补发队列

其中现在已经正式落地的是：

- `complete`
- `events`

这两类回执在失败时会进入 Agent 本地待补发队列，而不是直接丢失。

### 4. 当前已经落地的本地待补发 / 死信队列

当前 `domain-api/app/node_agent.py` 已经具备：

- 本地 `pending` 队列
- 本地 `dead-letter` 队列
- 定时 `_flush_delivery_queue()`
- 对永久性 `detail_code` 的死信分流

也就是说，Agent 当前不是“请求失败就算了”，而是已经形成：

1. 优先即时发送
2. 失败则本地排队
3. 下个 tick 自动重放
4. 如果命中永久性错误，则进入死信

这层能力当前主要覆盖：

- `jobs/{id}/complete`
- `jobs/{id}/events`

### 5. 控制面现在如何看见队列问题

这条链路现在也已经不只存在于 Agent 本地。

当前控制面会把 heartbeat 里的 `metadata.delivery_queue` 收口成：

- 节点行字段
  - `delivery_queue_state`
  - `delivery_queue_label`
  - `delivery_queue_reason`
  - `delivery_queue_pending_count`
  - `delivery_queue_dead_letter_count`
- 节点汇总字段
  - `queue_retrying_nodes`
  - `queue_dead_letter_nodes`
  - `queue_pending_records`
  - `queue_dead_letter_records`

并且驾驶建议已经开始优先提升这类问题：

- 如果存在死信节点，优先建议先处理 Agent 死信
- 如果存在待重试积压，优先建议先观察回执积压

所以这已经不是“隐藏在节点本地目录里的运维细节”，而是正式进入海外控制面的驾驶 contract。

---

## 十八、终局验收标准

当这套体系真正算“上线可用”，至少要满足以下 10 条：

### 1. 新增节点不再需要人工拼命令

控制面能够直接生成：

- token
- env
- bootstrap script
- health check block

### 2. 海外控制面能先看见节点，再决定是否接管

不是只有接入成功后才看见机器。

### 3. 接管完成后可直接跑标准验收

而不是再去手工 systemctl / journalctl。

### 4. 标准巡检统一走 `ops job` / `playbook run`

而不是页面每个按钮都各做一套逻辑。

### 5. 真正参与检测节点和在线未参与节点口径统一

页面、后端、Codex 必须读同一份 execution scene。

### 6. 远端日志回传状态正式结构化

至少统一成：

- `disabled`
- `waiting_sample`
- `partial_coverage`
- `healthy`
- `full_capture`

### 7. 发布必须先有 Release，再有 Rollout

不能回退到节点直接 `git pull`。

### 8. Rollout 必须能分批、暂停、继续、回滚

而不是一次性把所有节点推平。

### 9. 页面按钮和 Codex 都只创建对象，不直接执行 shell

最终：

- 页面创建 `ops job`
- Codex 创建 `ops job` / `playbook run`
- agent 消费 `ops job`

### 10. 海外主机必须成为唯一运维大脑

大陆机器只负责：

- 执行
- 回传
- 承载业务

不再承担“人工登录后做决定”的角色。

---

## 十九、下一步最值得继续补的 6 件事

基于当前仓库状态，接下来最值得继续补的，不再是“把主链路补出来”，而是把已经成型的体系收成真正可长期运维的平台。

### 1. 给死信队列补正式操作面

当前已经有：

- 本地待补发
- 本地死信
- 控制面可见的队列快照

下一步最该补的是：

- 死信详情查看
- 死信重放
- 死信丢弃
- 死信按 `detail_code` 聚类

否则“看见死信”之后，操作者还是得回到节点本地处理。

### 2. 把 action template preview / batch policy preview 正式后端化

在真正创建 `ops jobs` 之前，要让控制面先统一回答：

- 哪些节点被阻断
- 哪些节点需要审批
- 哪些节点只是 warning
- 当前批次策略是否合理

这样发布、重启、停 Worker 这类高风险动作，才能在创建对象前先收口风险。

### 3. 把接管验收、标准巡检、现场观察彻底收进 playbook run

现在 playbook run 骨架已经有了，而且其中一部分已经开始从“打开弹窗”进入“直接执行正式动作”。下一步要继续把：

- `onboarding.acceptance`
- `inspection.standard`
- `scene.logs.key`
- `scene.logs.full`

都变成真正稳定的编排对象，而不是“部分走编排、部分还停留在前端直触发”。

当前已经落地的直接驾驶动作包括：

- `bootstrap_run`
- `run_acceptance`
- `run_standard_inspection`
- `open_diagnostics`
- `run_scene_logs_key`
- `run_scene_logs_full`

这意味着纳管收口、标准巡检和现场观察都已经开始直接进入正式执行链，而不是先把操作者送去弹窗二次选择。

发布审阅链也应该遵守同样原则：

- `review_smart_rollout_preview`
- `review_control_rollout`
- `fix_rollout_blockers`

这几类动作不应只返回“打开 launchpad 审阅页”的 UI intent，而要同时直接返回结构化 `release_launchpad_review` 结果，让自动驾驶、CLI 和后端任务能直接消费 launchpad 预案。

并且这里的自动化等级也要彻底锁死：

- 这三类动作属于 `safe_auto`
- 它们的职责是“审阅”和“解释”
- 不是“创建发布对象”

所以默认返回应是：

- 结构化 `release_launchpad_review`
- 可选 `ui_intent = release_launchpad_review`
- 但不直接创建 rollout / publish 记录

同理，`focus_release_hub` 也不应继续只是一个纯导航意图：

- 页面侧仍可消费 `ui_intent = focus_release_hub`
- 但后端同时还应返回 `release_hub_preview`
  至少包含：
  - `summary`
  - `launchpad`

这样海外 Codex、CLI、driver-feed 调用方即使不打开页面，也能继续拿这份摘要决定后续是：

- 继续审阅 launchpad
- 进入发布创建
- 还是先回补门禁缺口

`release_package` 也应遵守同样的“先给后端摘要，再保留 UI 入口”原则：

- 页面仍可通过 `ui_intent = open_release_dialog` 进入打包区
- 但动作返回里还应包含 `release_package_preview`
  至少包括：
  - `available`
  - `package_name`
  - `release_version_suggestion`
  - `reason`

这样 Node Agent、Release Hub、海外 Codex 驾驶员三边的判断都能先基于同一份“发布包现场状态”，而不是必须打开页面后才能知道有没有包可发。

同理：

- `open_release_dialog`
  也不应只是纯导航
  应同时返回 `release_dialog_preview`
- `open_rollout_dialog`
  也不应只是纯导航
  应同时返回 `rollout_dialog_preview`

这样就算暂时仍保留页面入口，自动驾驶层也已经可以先读：

- Release 当前摘要
- Launchpad 当前摘要
- 发布包是否存在

而不是必须依赖前端抽屉作为唯一信息入口。

继续往下一层，模板类动作和发布部署模板动作也应该统一走“预览优先”：

- `open_playbook_dialog`
  应返回 `playbook_preview`
- `open_action_template_dialog`
  应返回 `template_preview`
- `open_release_deploy_worker / open_release_deploy_control / open_release_deploy_custom`
  应返回 `release_deploy_preview`

其中 `release_deploy_preview` 至少应包含：

- `template`
- `summary`
- `launchpad`
- `target_node_codes`
- `execution_mode`
- `release_id`

这样自动驾驶层拿到的就不是“去某个弹窗”，而是一份已经够继续判断的执行预案。

再往前，焦点类动作也不应继续只是“跳到某个详情页”：

- `focus_playbook_run`
  应返回 `playbook_run_focus`
- `open_playbook_run_latest_events`
  应返回 `playbook_run_events_preview`
- `focus_latest_job_events`
  应返回 `job_events_preview`
- `focus_activity_item`
  应返回 `activity_focus_preview`

这样 Codex、CLI、OpsCenter 三边在进入具体页面之前，就已经能先读到：

- 当前编排主状态
- 最近事件流
- 当前 job 回执
- 当前 activity 焦点对象

后续“跳到页面”就只是补充查看，而不是唯一信息入口。

这里还要把动作分级口径正式固定下来：

- 只要动作已经满足：
  - 后端可直接执行
  - 不修改现场状态
  - 主要返回 `preview / focus / summary / events`
- 那么它就不应继续归在 `ui_only`
- 而应统一归到 `safe_auto`

当前已经应按这个口径归类的动作包括：

- `handover_first_gap`
- `view_first_gap`
- `open_playbook_dialog`
- `open_action_template_dialog`
- `focus_playbook_run`
- `focus_activity_item`
- `focus_latest_job_events`
- `open_playbook_run_latest_events`
- `open_release_dialog`
- `open_rollout_dialog`
- `open_release_deploy_control`
- `open_release_deploy_worker`
- `open_release_deploy_custom`
- `focus_release_hub`
- `release_package`

也就是说，页面仍然可以消费这些动作的 `ui_intent`，但 Codex / CLI / 自动驾驶网关已经可以把它们当成：

- “可直接执行的只读观察动作”

而不是：

- “必须先打开某个页面才能继续”

而真正进入发布创建层的动作，例如：

- `publish_latest_worker`
- `create_smart_release_rollout_worker`
- `create_smart_release_rollout_control`
- `create_release_rollout_worker`
- `create_release_rollout_control`

则必须继续保持：

- `guarded_auto`
- `confirm_then_execute`
- 正式写入发布与审计链

### 4. 把 Release Artifact 管道做成正式不可变发布链

现在 Release / Rollout 对象已经成型，下一步最关键的是补齐：

- 构建产物打包
- checksum / manifest
- 上传与留存
- channel 激活
- 回滚版本选择

也就是把“版本对象存在”继续推进到“版本供应链完整”。

### 5. 把 SSH Rescue Executor 收成首发接管与紧急救援闭环

终局不是回到 SSH 主运维，但 SSH 仍应有正式位置：

- 首次 bootstrap
- Node Agent 尚未接入时的应急接管
- Agent 故障时的救援执行

这一层应继续做成正式 executor，而不是保留为人工口令。

### 6. 把 Node Agent / ReleaseHub / OpsCenter contract 固化为 schema / OpenAPI

现在最怕的已经不是“没有能力”，而是：

> 页面、后端、Codex、CLI 在继续迭代时发生字段漂移

所以后续上线前，建议正式抽出：

- `schemas/ops_agent_protocol.md`
- `schemas/release_hub_contract.md`
- `schemas/ops_driver_contract.md`
- `schemas/ops_playbook_contract.md`

并且不只要有 schema 文件，还要让控制面直接暴露统一索引：

- `GET /api/v1/ops/contracts`
- `GET /api/v1/ops/contracts/{contract_key}`

前者负责列出整张 contract map，后者负责按 key 钻取单份协议和相关 contract。

控制面前端与海外 CLI 也要统一走这两层入口：

- 页面默认只拉 registry，避免首屏过重
- 当用户点击某个 contract 时，再按 key 拉 detail
- detail 返回里必须带 `related_contract_keys` / `related_contracts`
- 这样排查一条链路时，可以从 `ops_stack_diagnosis_contract` 直接跳到 `ops_driver_contract`、`release_hub_contract`、`ops_agent_protocol`

或者直接写入后端 schema / OpenAPI 注释，让 contract 成为真正受版本控制的对象。

---

## 二十、海外 Codex 驾驶员的正式闭环

如果要把“海外主机单脑控制面”真正做成长期稳定体系，海外 Codex 驾驶员不应该被设计成：

- 远端 shell 执行器
- 看日志后临时拼命令的脚本
- 依赖人工不断复制上下文的助手

它应该是严格跑在统一 contract 上的“驾驶层”。

### 1. 默认入口只看 3 类信号

海外 Codex 驾驶员默认只消费：

1. `driver-feed`
2. `codex-brief`
3. `activity-stream`

分别回答：

- 现在最该处理什么
- 这一步能不能自动执行
- 最近执行后现场发生了什么

也就是说，驾驶员不应该先去翻零散日志，再猜下一步，而是先看控制面已经结构化好的主线。

### 2. 默认执行顺序必须固定

标准顺序应固定成：

1. `driver-feed`
   - 取 `top_recommendation`
2. `driver-focus-preview`
   - 看 contract / gate / request preview
3. `driver-focus-run`
   - 只有后端 gate 允许时才执行
4. `activity-stream`
   - 回看这一步是否真正落地
5. 必要时钻取：
   - `playbook run`
   - `ops job`
   - `release / rollout`

这样驾驶员并不是“直接开车”，而是：

- 先看路标
- 再看交通规则
- 然后再执行

### 3. 驾驶员永远不直接决定 shell

正式规则必须收死：

- 驾驶员不直接 SSH 到节点上拼 shell
- 驾驶员不自己判断某台机器该不该 `git pull`
- 驾驶员不自己决定 systemd 命令如何组合
- 如果控制面已经把首个缺口节点收敛成 `bootstrap_run / run_acceptance`
  - 驾驶员也不能退回成泛化的 `fix_managed_nodes`
  - 而应优先围绕同一个节点继续做预览、执行和回执追踪

驾驶员只做三件事：

1. 选择动作对象
2. 请求后端解析门禁
3. 创建正式执行对象

最终执行必须落到：

- `ops job`
- `playbook run`
- `release / rollout`
- `node agent task`

这样才具备：

- 审计
- 回放
- 回滚
- 风险分级

### 4. 驾驶员必须把“看见问题”和“处理问题”拆开

终局方案里最容易犯的错，就是把：

- 看见节点离线
- 打开日志
- 重启服务
- 改配置
- 再观察

全部写成一段混杂的脚本。

正确方式应该拆成两层：

- 观察层
  - `driver-feed`
  - `activity-stream`
  - `inspection`
  - `release launchpad`
- 执行层
  - `driver-actions/execute-resolved`
  - `ops job`
  - `playbook run`
  - `rollout`

这样后面无论是：

- 人工值班
- 海外 Codex 自动驾驶
- 后台一键按钮

都能共用同一套观察口径与执行口径。

补充一条正式约束：

- `driver-feed`
  - 顶层 payload 需要带 `contract_navigation`
  - 每条 `entries`
  - 每条 `activity_focus`
  都要带 `contract_navigation`
- `activity-stream`
  - 顶层 payload 需要带 `contract_navigation`
  - 每条 `items`
  都要带 `contract_navigation`

这样海外单脑控制面里的卡片、时间线、CLI drilldown、Codex 驾驶员才能共享同一条“协议跳转链”，而不是 UI 有一套、CLI 有一套、排障时再临时翻文档。

### 5. 驾驶员需要一套明确的升级路径

真正上线时，建议把海外 Codex 驾驶员分成 4 档能力，而不是一步到位全自动：

#### L1 观察驾驶

- 只看 `driver-feed / codex-brief / activity-stream`
- 只输出建议，不执行

#### L2 门禁驾驶

- 可以跑 `driver-focus-preview`
- 可以对 `safe_auto` 动作执行 `driver-focus-run`
- 对 `guarded_auto` 只提示确认

这里的典型分界现在应明确到动作名，避免后续接入新驾驶员时再自己猜：

- `safe_auto`
  - `review_smart_rollout_preview`
  - `review_control_rollout`
  - `fix_rollout_blockers`
  - `run_standard_inspection`
  - `run_scene_logs_key`
  - `run_scene_logs_full`
- `guarded_auto`
  - `publish_latest_worker`
  - `create_smart_release_rollout_worker`
  - `create_smart_release_rollout_control`
  - `create_release_rollout_worker`
  - `create_release_rollout_control`

#### L3 编排驾驶

- 可以创建：
  - `playbook run`
  - `ops job`
  - `release / rollout`
- 但仍不直连 shell

#### L4 救援驾驶

- 仅在 Node Agent 失效或接管初期
- 允许走受控 `SSH Rescue Executor`
- 仍然必须把动作写回控制面审计链

这样自动化能力能逐档放开，而不是一开始就把所有权力交给一段脚本。

### 6. 海外主机最终应该成为唯一“决策写入口”

终局不是“海外主机能看到更多日志”，而是：

> 所有决策类动作，都只能从海外控制面写入。

这意味着：

- 大陆节点不再自己 `git pull` 决定版本
- 大陆节点不再靠人工 SSH 决定是否重启
- 大陆节点只负责执行、回传、承载业务

而海外主机负责：

- 产物选择
- 风险判断
- 动作签发
- 回执汇总
- 运行态总览

这才是真正的“单脑控制面”。

### 7. 对你这个项目，最推荐的默认日常路径

如果按最省心、后续最少返工的标准，建议以后日常操作尽量收成下面这条路径：

1. 海外主机打开 OpsCenter
2. 看 `driver-feed.top_recommendation`
3. 先 `driver-focus-preview`
4. 再 `driver-focus-run`
5. 如果动作升级，进入：
   - `inspection`
   - `playbook run`
   - `release hub`
6. 如果执行异常，看：
   - `activity-stream`
   - 死信队列
   - 回执补发状态
7. 只有在 Agent 不可用时，才进入 SSH Rescue

这样后续再新增 1 台大陆机器，不会再变成“重新写一套部署说明”，而只是：

- 新节点 bootstrap
- Node Agent 注册
- 控制面验收
- 进入正式运维

架构不会再被机器数量拖垮。

---

## 二十一、死信队列必须从“可见”升级到“可操作”

当前这套体系已经能看见：

- 哪台节点存在 `dead_letter`
- 有多少条死信
- 最早死信时间是什么

这说明“现场可见性”已经有了。

但如果没有正式操作面，控制面还是会卡在最后一步：

- 看到死信
- 给出建议
- 最后仍然要人工 SSH 去处理

这就违背了“海外单脑控制面”的目标。

所以这层必须继续升级成正式对象：

- 单节点队列总览
- 队列记录列表
- 死信详情
- 单条重放
- 批量重放
- 丢弃
- 主动冲刷

其中第一阶段已落地：

- `GET /api/v1/ops/nodes/{node_code}/delivery-queue`
- `GET /api/v1/ops/nodes/{node_code}/delivery-queue/records`
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/flush`
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/replay`
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/records/{record_id}/replay`
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/records/{record_id}/discard`

当前这组入口明确采用：

- `record_visibility=head_only`

也就是控制面先稳定看到：

- 节点级队列状态
- `pending / dead_letter` 头部记录

而不是假装已经具备远端全量死信列表与直接操作能力。

也就是说现在已经进入“可操作的第一阶段”：

- 控制面能看节点级队列状态
- 控制面能看 `pending / dead_letter` 头部记录
- 控制面能通过正式 `ops job` 触发冲刷 / 重放 / 丢弃
- 但还没有把远端全量记录目录完整投影成控制面对象

并且这第一阶段现在已经不是“后端接口预留”，而是已经形成了三层统一操作面：

- OpsCenter 托管节点表可直接打开“回执队列治理”抽屉
- driver recommendation 遇到 `dead_letter / retrying` 时，会优先落到标准动作模板
- 海外单入口 CLI 已支持直接查看 / 冲刷 / 重放 / 丢弃

也就是说当前这层已经具备明确的人机协作分工：

- 页面负责看现场、做单条处理、做危险动作确认
- driver / Codex 负责把“当前最该处理什么”压成建议
- CLI 负责在海外主机上做统一批处理和交接执行

具体到当前仓库，已经形成下面这些稳定入口：

### 1. 页面入口

- OpsCenter 托管节点表：
  - `队列`
  - `立即冲刷`
  - `重放死信`
  - `单条重放`
  - `单条丢弃`
- 丢弃动作强制要求填写原因
- 当前页面仍明确遵守：
  - `record_visibility=head_only`

也就是页面不会假装自己能枚举远端完整死信目录，而是只围绕“当前可见头部记录”和“节点级摘要”操作。

### 2. 驾驶建议入口

当前 `driver_recommendations` 已经升级成：

- `dead_letter`
  - 主动作：直接执行 `replay_delivery_queue`
  - 后端落点：创建 `delivery.queue.replay` 的标准 `ops job batch`
  - 次动作：查看 Worker 日志
- `retrying`
  - 主动作：直接执行 `flush_delivery_queue`
  - 后端落点：创建 `delivery.queue.flush` 的标准 `ops job batch`
  - 次动作：查看 Worker 日志

这一步很关键，因为它意味着控制面不再只是说“这里有死信，你自己想办法”，也不再只是把人送去模板弹窗，而是已经能直接走正式 `ops job` 链路下发队列治理动作。

### 3. 海外单入口 CLI

当前 `drive_ops_center.sh` 也已经补上了这组命令：

- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-status <node_code>`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-records <node_code> [state]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-flush <node_code> [limit] [requested_by]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-replay <node_code> [limit] [requested_by]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-replay-record <node_code> <record_id> [requested_by]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh queue-discard-record <node_code> <record_id> <reason> [requested_by]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh activity-stream [key=value ...]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh activity-preview [activity_key] [requested_by]`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-feed`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-focus-preview`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh driver-focus-run`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh codex-brief`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh codex-focus-preview`
- `bash domain-api/deploy/multi-region/drive_ops_center.sh codex-focus-run`

建议把这组命令视为“海外集中治理 Node Agent 回执队列”的正式入口，而不是临时调试命令。

并且现在这组命令的输出口径也要冻结下来：

- `activity-stream / driver-feed / codex-brief`
  - condensed summary 必须打印顶层 `contract_navigation`
- `activity-preview / driver-focus-preview / codex-focus-preview / stack-next`
  - condensed summary 必须打印 `preview.contract_key / contract_version / contract_primary_endpoint / preview_endpoint / schema_doc_path`
- 所有 `selected_entry`
  - 必须尽可能保留 `contract_navigation`

这样海外 CLI、页面按钮、未来海外 Codex 驾驶员看到的就不是三套不同“解释文本”，而是一套可追踪到协议、接口和 schema 文档的正式输出。

同理，海外单脑控制面导出的交接包也不能只停留在：

- `stack summary`
- `ops plane`
- `participation`

还应该把 contract-aware 驾驶面一起固化进去：

- `contracts registry`
- `driver-feed`
- `activity-stream`
- `codex-brief`
- `stack-next preview`
- `driver-focus preview`
- `activity preview`
- `codex-focus preview`

并且 preview 类报告允许“当前没有焦点但仍导出文件”，文件尾部只记录 `command_exit_code=1`，这样交接人拿到包以后不会误解成“导出中断”，而能明确判断是“现场当时没有可预览入口”。

进一步讲，这个交接包还应该再固定一层机器摘要：

- `manifest.json`

它不是替代原始报告，而是给海外 Codex / 后台自动驾驶 / 未来 OpsCenter UI 二次消费的摘要面。

正式口径应该固定成：

- `meta.json`
  - 负责说明这包是谁、何时、针对哪个 profile / 哪组 API 生成的
- `manifest.json`
  - 负责说明这包里每份报告是否存在、exit code 是多少、哪些 preview 当前可用、现场暴露了哪些 contract key
  - 如果某个 required 报告已经解析出 `http_status` 且不是 `2xx`，也必须记入 `required_failures`
- `*.txt`
  - 保留完整原始现场输出，供人类继续钻取

并且 `doctor-export` 命令自己的 stdout 也应该回传一份缩略版 `summary + decision`，这样海外 Codex 不必先打开文件树，也能先做第一轮分流判断。

进一步往终局落地时，CLI 侧还应该固定一个更适合机器先消费的统一入口：

- `doctor-decision`

正式定位应该是：

- `doctor-export`
  - 负责生成完整交接包
- `doctor-decision`
  - 负责读取 `manifest.json`
  - 如果没有现成 `manifest.json`，就临时生成一份 export
  - 然后只回传 `summary + decision`
  - 并且允许用 `-` 明确关闭 overseas 拓扑探测，避免因为默认海外地址不可达把第一轮分流卡死

这里的 `summary` 不能只做 surface 成败汇总，还要继续固定带出 launchpad 接管口径：

- `launchpad_recommended_target_node_code`
- `launchpad_recommended_recovery_label`
- `launchpad_recommended_recovery_summary`
- `launchpad_onboarding_bootstrap_pending_nodes`
- `launchpad_onboarding_acceptance_ready_nodes`

同时，`decision.evidence` 也要镜像这组字段，确保海外 Codex / 自动驾驶器 / 人工值班
在只消费 `doctor-decision` 的前提下，就能直接判断：

- 当前最该先接哪台节点
- 当前是“还缺 bootstrap”还是“已经 ready，等待 acceptance”
- 是否需要继续下钻 `release-launchpad / driver-feed / codex-brief`

这样海外单脑控制面的“第一跳”就稳定了：

- 海外 Codex 先跑 `doctor-decision`
- 后台自动驾驶按钮先跑 `doctor-decision`
- 人工值班也先看 `doctor-decision`

并且从当前实现口径上，`doctor-decision` 不应再只消费旧的 `next_step_action_code`，而要优先消费：

- `diagnosis.operator_decision`
- `diagnosis.next_actions`
- `diagnosis.recommended_commands`

这意味着如果总检已经明确判定“先看现场日志 / 先打通节点接管 / 先看 Release Hub”，那么 `doctor-export` 产出的 `manifest.json` 与 `doctor-decision` 最终给出的 `recommended_commands` 也必须同步落到同一条主决策，不允许再次退化成泛化建议。

只有当 `decision.status` 显示需要继续钻取时，才去打开整包 `*.txt` 和 `manifest.json` 深挖。

而且 `doctor-export / doctor-decision` 这一层本身也应该固定成“步骤级超时继续导出”：

- 某个 surface 卡住，不允许整包诊断悬死
- required report 失败，要进入 `required_failures`
- required report 失败明细，要进入 `required_failure_details`
- optional preview 不可用，要进入 `optional_unavailable`
- optional preview 不可用明细，要进入 `optional_unavailable_details`
- 海外单脑永远优先拿到一份可判断的 `decision`，而不是拿到一个还在转圈的进程

并且这些明细不能只停留在“文件名失败”：

- `reports[].failure.reason_code`
- `reports[].failure.label`
- `reports[].failure.detail`

至少要能稳定区分：

- `command_timeout`
- `command_failed`
- `http_unreachable`
- `http_error`
- `result_unparsed`

再往前一步，控制面 API 自身也应该暴露正式“运行指纹”：

- `/health`
- `/api/v1/runtime/status`
- `/api/v1/runtime/build-info`

这些接口至少应该稳定给出：

- `build.source`
- `build.package_name`
- `build.generated_at`
- `build.commit_sha`
- `build.commit_ref`
- `build.manifest_path`
- `build.route_surface.surface_complete`
- `build.route_surface.missing_paths`

这样以后看到 `ops/contracts` 返回 404 时，就不用再靠猜：

- 如果 `build` 缺失，说明运行实例还没切到新版本
- 如果 `build` 存在但 `route_surface` 缺路由，说明当前实例加载的仍然不是完整协议面
- 只有 `build` 与 `route_surface` 都完整，才值得继续往 preview / execute 深挖

### 4. 当前阶段的明确边界

当前仍然要刻意坚持下面这几点，避免以后又滑回“假装可控”：

- 不直接 SSH 进节点手改 `pending / dead-letter` 文件
- 不允许页面、CLI、Codex 各自定义不同的 replay / discard 逻辑
- 所有操作都必须落成正式 `ops job`
- 单条 replay / discard 当前只允许针对控制面可见头部记录

这样未来从 `head_only` 升级到“远端全量记录正式投影”时，扩的是可见范围，不是重写整个治理模型

推荐以后直接以 [ops_agent_protocol.md](/www/wwwroot/getDomain/docs/schemas/ops_agent_protocol.md:133) 为母本，把 `delivery_queue` 从 heartbeat 快照扩到控制面操作面。

正式要求应该固定成：

- Agent 只负责补发与执行
- 控制面负责查看、聚类、重放、丢弃
- 页面、CLI、Codex 不允许各自发明不同的死信处理逻辑

---

## 二十二、Playbook Run 必须成为正式一等对象

当前仓库里 `playbook` 已经不只是“预留想法”，而是已经有：

- catalog
- preview
- execute
- run detail
- run events
- rerun
- cancel

这说明骨架已经具备，只差把 contract 冻结清楚。

后续最关键的不是再补更多“脚本型能力”，而是把这几类正式收口：

- `onboarding.bootstrap`
- `onboarding.acceptance`
- `inspection.standard`
- `scene.logs.key`
- `scene.logs.full`
- `scene.diagnostics`

也就是说：

- 接管验收
- 标准巡检
- 现场观察

都应该优先变成 `playbook run`，而不是继续散落在：

- 页面按钮
- Driver Action 临时逻辑
- 手工命令

推荐以后直接以 [ops_playbook_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_playbook_contract.md:1) 为正式母本。

这样后续：

- 页面点“标准巡检”
- CLI 执行“现场观察”
- 海外 Codex 驾驶员决定“先验收还是先抓日志”

最终看到的都是同一类对象：

- 先 `preview`
- 再 `execute`
- 最后围绕 `playbook run / playbook events` 观察

这样控制面才算真正从“按钮集合”进化成“正式编排平台”。

---

## 二十三、单脑控制面最终要固定成 4 张操作面

Node Agent、Release Hub、Driver、Playbook 这些听起来很多，但终局页面不应该把操作者淹没在概念里。

最终应该稳定成 4 张操作面。

其中“现场面 + 队列面”建议以后直接以 [ops_observability_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_observability_contract.md:1) 为正式母本，避免后面又把这层能力重新拆散到页面局部状态里。

### 1. 接管面

负责回答：

- 哪些节点已经纳管
- 哪些节点只是集群可见但未纳管
- 哪些节点 token 过期
- 哪些节点 agent 心跳异常
- 哪些节点已经通过接管验收

这一面主要消费：

- `ops_agent_protocol`
- `managed nodes`
- `bootstrap-plan`
- `onboarding.acceptance`

### 2. 现场面

负责回答：

- 哪些节点正在执行
- 哪些节点在线但未参与
- 哪些节点近窗有吞吐
- 日志回传当前是否关闭 / 关键 / 全量
- 当前应该优先巡检哪台节点

这一面主要消费：

- `overview`
- `inspection`
- `activity-stream`
- `driver_recommendations`
- `playbook runs`

### 3. 队列面

负责回答：

- 哪台节点的回执队列有积压
- 哪台节点有死信
- 头部记录是什么
- 当前应该冲刷、重放，还是丢弃

这一面主要消费：

- `delivery_queue`
- `delivery_queue.records`
- `flush / replay / discard`

这里要持续坚持：

- 当前阶段允许 `head_only`
- 但不允许退回人工 SSH 改文件

### 4. 发布面

负责回答：

- 当前默认 release 是谁
- 默认 gate 是 `blocked / attention / ready`
- 哪些节点可以灰度
- 哪一批 rollout 正在执行
- 哪一轮 rollout 需要审批 / 暂停 / 回滚

这一面主要消费：

- `release_hub_contract`
- `launchpad`
- `default_rollout_gate`
- `rollouts`

这样页面心智模型才会稳定：

- 接管面：先让节点进体系
- 现场面：看现场和巡检
- 队列面：处理回执不一致
- 发布面：推进版本与回滚

这 4 张面板不是 4 套系统，而是：

> 同一套控制面 contract 的 4 个观察窗口

---

## 二十四、新节点从“拿到机器”到“可以发版”必须走标准路径

后续不应该再写“某台机器特殊处理说明”，而要把新节点接入路径固定为下面 8 步。

### 1. 签发接入凭证

控制面生成：

- token
- bootstrap plan
- env 内容
- systemd 文件
- 启动检查命令

这一步之后，页面、CLI、Codex 都只能复用同一份 bootstrap 对象。

### 2. 节点安装 Node Agent

节点完成：

- 安装 agent
- 写入 env
- 启动 systemd

此时节点还只是：

- `agent installed`

还不算已经正式接管成功。

### 3. 节点注册并进入托管目录

节点完成：

- `register`
- `heartbeat`

控制面能看见：

- 节点身份
- capabilities
- service_names
- delivery queue 摘要

这时节点进入：

- `managed candidate`

### 4. 立即跑接管验收

控制面不应等待人工另开命令，而应立刻执行：

- `onboarding.acceptance`

必要时自动追加：

- `inspection.standard`

这样新节点接入不会停留在“能连上就算完成”，而会直接走到：

- 基础服务是否正常
- 日志是否可收口
- 诊断是否可采
- worker / api 拓扑是否正确

### 5. 如果有问题，先走现场面而不是手工 SSH

验收失败后，优先动作应该是：

- 查看 `activity-stream`
- 打开 `playbook run detail`
- 看 `inspection`
- 看 `delivery queue`

只有 Node Agent 已明显不可用，才进入 SSH Rescue。

### 6. 验收通过后进入发布门禁

节点通过验收后，不应马上让它进入发布目标集合，而是先进入：

- release gate readiness

也就是明确判断：

- agent 在线否
- inspection 健康否
- delivery queue 正常否
- 是否允许 remote-agent rollout

### 7. 先进入 Worker / Control 正确角色集合

接入后必须明确：

- 它是 `worker`
- 还是 `control`
- 是否 `effective_worker`
- 是否允许参与 rollout

不能让“纳管成功”和“自动进入发版目标”之间没有门槛。

### 8. 最后才进入 Release / Rollout

到这一步才允许：

- worker canary
- batch rollout
- advance / pause / rollback

这条标准路径的真正意义是：

> 新节点接入不再是一次性脚本，而是正式运维生命周期的开始

---

## 二十五、后续实现时绝不再回退的 10 条边界

为了避免系统越来越大以后又退回人工联调，下面 10 条边界建议直接视为终局铁律。

### 1. 不再把 `git pull` 当正式发布方式

正式发布只认：

- release artifact
- checksum
- rollout

### 2. 不再让节点自己决定版本

节点只能执行：

- 下载
- 校验
- 切换
- 回滚

不能自己挑版本。

### 3. 不再让页面、CLI、Codex 各自拼动作语义

所有动作必须收口到：

- action template
- playbook
- rollout
- delivery queue action

### 4. 不再把 SSH 当日常主链路

SSH 只保留：

- bootstrap
- rescue

### 5. 不再让回执队列治理脱离 `ops job`

无论：

- flush
- replay
- discard

都必须形成正式留痕。

### 5.1 不再让发布兜底路径退回“打开面板”

`release_progression` 现在也应该遵守同一原则：

- 有明确 Launchpad 推荐时，优先走 `publish_latest_worker`
- 已经存在默认 Release、但 Launchpad 还没形成明确推荐时，兜底也要直接走 `create_release_rollout_worker`

也就是说，不能因为“还没形成完整 launchpad 推荐”就退回到“打开 Worker 点状灰度面板”这种 UI 导航式动作。

### 6. 不再让“在线”直接等于“参与检测”

必须明确区分：

- 在线
- 参与执行
- 在线待命
- 近窗有吞吐
- 负载同步中

### 7. 不再让页面自己猜跳转落点

后端必须给：

- `ui_intent`
- `run_code`
- `activity_key`
- `focus_step_key`

### 8. 不再让日志体系只靠全量大文本

必须分层：

- event
- playbook / job log
- runtime log
- diagnostics bundle

### 9. 不再把 root/www 混合工作区当正常运维模型

正式版只允许：

- release build side
- release deploy side

角色分清，而不是在目标节点长期维护一份脏 git 工作区。

### 10. 不再让“设计口径”和“实现口径”分裂

所以现在开始，后续新增能力都建议优先先补到：

- `ops_agent_protocol.md`
- `ops_driver_contract.md`
- `ops_playbook_contract.md`
- `release_hub_contract.md`

再去写页面和执行器。

这样你这套系统才会越来越像：

> 正式控制平台

而不是：

> 一直迭代的一组强力调试脚本

## 二十六、海外单脑控制面的总检入口也要正式化

上面整套设计如果只停留在：

- 有很多 endpoint
- 有很多检查脚本
- 有很多 contract 文档

那后面现场一复杂，还是会退回“先想想这次该跑哪个脚本”。

所以海外单脑控制面还需要一个固定的总检入口：

- `check_ops_center_stack.sh`

它的职责不是替代：

- `check_ops_contracts.sh`
- `check_ops_plane.sh`
- `check_node_agent.sh`
- `check_release_hub.sh`

而是把这四层先按固定顺序收口成一次总览：

1. 先看 API 与 contract registry
2. 再看 `link_snapshot / overview` 当前驾驶主线
3. 再看托管节点、Node Agent、回执队列
4. 最后看 ReleaseHub 与最近 playbook / activity

这样后续海外主机第一次接手现场时，默认起手式就固定为：

```bash
cd /opt/domaincheck/domain-api
bash domain-api/deploy/multi-region/check_ops_center_stack.sh http://127.0.0.1:8100

# 如果只想看最终收口，不展开全量原始 JSON
bash domain-api/deploy/multi-region/check_ops_center_stack.sh http://127.0.0.1:8100 summary
```

它本质上回答的是 5 个问题：

- 当前控制面跑的是哪一版 contract
- 当前最该处理的 driver recommendation 是什么
- 当前有哪些节点已经被正式接管、哪些还没进入稳定执行面
- 当前回执队列有没有死信或待补发积压
- 当前 ReleaseHub 是 ready / attention / blocked 哪一种

而在正式实现上，这份总检结果不应该只停留在“把几段 JSON 拼起来”，而是要直接形成一层可被人和程序共用的诊断输出：

- `diagnosis.surface_status`
  说明总检表面层是不是完整联通
- `diagnosis.automation_status`
  说明海外单脑自动化执行面是不是已经真正可接管
- `diagnosis.stack_status`
  作为总检最终结论
- `diagnosis.issues`
  作为问题清单
- `diagnosis.next_step`
  作为默认下一步动作
- `diagnosis.quick_commands`
  作为现场立刻可复制执行的命令集合

这样一来，总检结果就不只是“读给人看”的说明书，而是后续：

- 海外 Codex 驾驶
- 后台按钮自动诊断
- 交接包导出
- 标准作业入口编排

都可以直接消费的正式 contract。

对应的正式入口也应该固定为：

- `GET /api/v1/ops/stack-diagnosis`

CLI 总检脚本只是它的终端包装层，而不应该继续长期承担“总检规则真正定义者”的角色。

进一步说，CLI 默认动作入口也应该固定下来：

- `bash domain-api/deploy/multi-region/drive_ops_center.sh stack-next`

它不再要求海外操作人先从总检结果里人工抄：

- `action_code`
- `focus_ref`
- `recommended command`

而是直接消费：

- `diagnosis.next_step`

然后统一进入：

- `driver-actions/resolve`
- `driver-actions/execute-resolved`

这一步很重要，因为它把“总检”和“下一步执行”正式接成一条链：

- 页面顶部总检入口
- 海外 CLI 单入口
- 后续海外 Codex 驾驶员

都不再自己猜“下一步该做什么”，而是统一信任一份正式 contract。

如果现场执行 `stack-next` 时拿到的是：

- `404 Not Found`

那也不要把它理解成“设计不成立”，而应理解为：

- 运行中的控制面 API 版本还没升级到包含 `/api/v1/ops/stack-diagnosis`
- 或代码已同步，但 `domaincheck-api` 尚未重启

也就是说，后续现场排障里，`404` 属于：

- 部署版本未对齐问题

而不是：

- 总检 contract 本身设计错误

这一步很关键，因为它把“海外主机的第一反应”也变成正式 contract 的一部分，而不是继续依赖人工记忆。

也就是说，未来不管是：

- 人工运维
- 海外 Codex 驾驶员
- 后台按钮触发自动诊断

都应该优先先看这份总检结果，再决定下一步钻取哪一层。

只有这样，这套体系才真正具备：

> 单入口观察，分层下钻，协议不漂移

## 二十七、终局实现顺序不能再乱

为了避免后面继续一边联调、一边改口径，这套体系后续实现顺序必须固定。

建议严格按下面 6 段推进：

### 1. 先冻结 contract，再扩页面和执行器

优先冻结的母本应固定为：

- [ops_stack_diagnosis_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_stack_diagnosis_contract.md:1)
- [ops_driver_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_driver_contract.md:1)
- [ops_job_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_job_contract.md:1)
- [ops_agent_protocol.md](/www/wwwroot/getDomain/docs/schemas/ops_agent_protocol.md:1)
- [release_hub_contract.md](/www/wwwroot/getDomain/docs/schemas/release_hub_contract.md:1)
- [ops_observability_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_observability_contract.md:1)

只有这些 contract 先稳住，页面按钮、CLI、Codex、Node Agent 才能围绕同一套结构化对象工作。

### 2. 再固定控制面的统一执行链

控制面日常动作主链必须固定为：

1. `stack-diagnosis`
2. `driver-actions/resolve`
3. `driver-actions/execute-resolved`
4. `ops job`
5. `Node Agent / rollout executor`
6. `event / complete / activity`

也就是说：

- 页面不直接执行壳命令
- CLI 不直接拼最终执行接口
- Codex 不直接猜动作 target api

所有高层动作都先下沉为统一 resolve / execute-resolved contract。

### 3. 再把 Node Agent 执行面补齐

Node Agent 侧必须先补齐：

- `register`
- `heartbeat`
- `pull`
- `jobs/{job_id}/start`
- `jobs/{job_id}/complete`
- `jobs/{job_id}/events`
- 本地待补发 / 死信队列

直到这条链稳定之前，不应把“节点能 SSH 上去”误判成“执行面已经正式接管”。

### 4. 再把 Release Hub 收成正式发布面

Release Hub 后续必须坚持：

- 包只认 artifact
- 发布只认 rollout gate
- 批次推进只认正式 rollout / ops job
- 节点不允许直接 `git pull`

这样后续：

- worker canary
- controller rollout
- 失败回滚
- 灰度暂停

才会继续沿用同一个正式模型，而不是变回“发布时再单独写一套命令”。

### 5. 最后才是 SSH Rescue

SSH 不应再作为日常主链路，只保留给下面几类场景：

- Node Agent 尚未接管
- Node Agent 失联
- 运行环境损坏到 agent 无法自救
- release 切换半途损坏，需要紧急修复目录或 systemd

而且即使走 SSH，也要继续满足：

- 创建正式 `ops job`
- 留下执行人、节点、动作来源
- 回写控制面审计链

### 6. 页面和 Codex 只能做“消费者”，不能做第二大脑

终局架构里：

- 页面负责展示和触发
- CLI 负责终端入口
- Codex 负责智能判断和编排

但三者都不能再自己定义：

- 新状态机
- 新动作对象
- 新门禁口径
- 新下一步推断逻辑

否则“海外单脑控制面”就又会退化成三套脑子。

## 二十八、上线前必须通过的收口验收

如果以后要说“这套系统已经进入正式长期可维护状态”，至少应通过下面 10 条验收。

### 1. 总检入口必须真实可用

下面命令必须能在海外控制面直接打通：

```bash
cd /opt/domaincheck/domain-api
bash domain-api/deploy/multi-region/check_ops_center_stack.sh http://127.0.0.1:8100 summary
```

而且结果里必须能给出：

- `diagnosis.stack_status`
- `diagnosis.issues`
- `diagnosis.next_step`

### 2. 默认下一步必须可以直接消费

下面命令必须成立：

```bash
bash domain-api/deploy/multi-region/drive_ops_center.sh stack-next http://127.0.0.1:8100
```

也就是说，现场不应再需要人工从总检结果里抄：

- `action_code`
- `focus_ref`
- `command`

### 3. 所有标准动作都必须落为正式对象

后续任何标准动作都必须能落成：

- `driver action`
- `ops job`
- 或 `playbook run`

不允许再出现“后台按钮一按，后端直接去某台机器执行一个临时命令，但控制面里没有正式记录”。

### 4. Node Agent 接管和 runtime 心跳必须明确区分

控制面必须能够直接区分：

- `已接管`
- `仅运行态在线`
- `待接入`
- `心跳过期`
- `失联`

绝不能再用“API 能看到节点在线”代替“Node Agent 已正式接管”。

### 5. 回执队列必须能治理，不只是能看见

必须能在页面或海外单入口完成：

- `queue-status`
- `queue-records`
- `queue-flush`
- `queue-replay`
- `queue-discard-record`

否则后续只要出现一次跨地域回执积压，就又会退回到手工删文件。

### 6. 远端日志回传必须可开关

多机联调时，海外控制面必须能够：

- 默认关闭，避免长期噪声
- 调试时打开，拿到远端关键或全量日志
- 调试结束后关闭

否则后续每新增一台大陆机器，都会重新回到“复制日志给 Codex 看”的低效模式。

### 7. Release Hub 必须可执行 canary 到 rollout

至少要能稳定完成：

- 选默认版本
- 看 rollout gate
- 发 worker canary
- 看结果
- 继续批次
- 异常暂停 / 回滚

### 8. 节点发布必须只认 artifact，不认 git pull

一旦进入正式执行链，节点侧必须坚持：

- 不 `git pull`
- 不直接以运行目录为发布源
- 不允许 controller / worker 各自拉不同本地临时代码

### 9. 救援必须是正式例外，不是常态

如果某类动作每次都需要：

- SSH 上机
- 手工重启
- 手工改 env
- 手工粘日志

那说明它还没有进入正式执行面，不能算收口完成。

### 10. 页面、CLI、Codex 三端口径必须一致

同一条动作在三端看到的：

- 状态
- 下一步
- 风险说明
- focus_ref
- target_api

必须一致。

只有这样，后面你才不会再遇到：

- 页面说能做
- CLI 说不能做
- Codex 又判断成第三种情况

## 二十九、后续绝不能回退的 8 种反模式

后续无论现场多急，都不建议再回到下面这些模式。

### 1. 新增页面按钮，直接在后端执行 shell

这是最容易把平台重新打回“脚本集合”的退路。

正确做法应始终是：

- 先 resolve
- 再 execute-resolved
- 最终落成 `ops job`

### 2. 页面、CLI、Codex 各自拼 request payload

一旦三端自己拼：

- `action_code`
- `target_api`
- `focus_ref`
- `execution chain`

后面就一定会再次口径漂移。

### 3. 用 runtime 心跳冒充正式接管

“节点在线”不等于：

- Node Agent 已接管
- 可以标准发布
- 可以标准巡检
- 可以标准回执

这两者必须永远分开。

### 4. 把发布流程重新做成节点本地更新

正式发布链绝不应回退到：

- `git pull`
- 覆盖运行目录
- 临时复制文件

正确做法只能是：

- 构建 artifact
- 生成 rollout
- 由执行面标准接收和切换

### 5. 把 SSH 当成默认执行器

SSH 只能是：

- bootstrap
- rescue
- 临时过渡

而不能成为：

- 日常发布
- 日常巡检
- 日常日志拉取
- 日常服务控制

的默认方式。

### 6. 故障时重新回到“复制日志给 Codex”

终局目标是：

- 海外控制面统一拿日志
- Codex 直接消费控制面 contract

而不是每次故障又退回：

- 现场机器跑命令
- 人工复制粘贴
- 再让 Codex 二次解释

### 7. 新增机器时再写一份特殊部署说明

以后新增大陆 controller / worker，不应再写：

- “这台机器例外”
- “这台机器单独执行某个手工命令”
- “这台机器按另一套说明”

而应继续只走：

- bootstrap plan
- Node Agent 接管
- onboarding acceptance
- 标准巡检 / rollout

### 8. 因为赶时间，就跳过正式审计链

只要动作会改变远端节点现场，就必须有：

- 发起人
- 动作来源
- 目标节点
- 执行结果
- 回执事件

否则后续节点一多，你就再也无法回答：

- 是谁改的
- 为什么改
- 哪次改坏了
- 哪台节点没跟上

这 8 条如果长期守住，后面这套系统才不会越做越散，而会越来越像真正的：

> 海外单脑控制平台

## 三十、这一轮继续冻结的 4 组关键字段

这轮设计继续往前收口时，有 4 组字段必须正式冻结，否则后面最容易再次出现“页面一套、后端一套、Codex 一套”的漂移。

### 1. Execution Scene 的参与态字段必须固定

现在“节点在线”和“节点真正参与检测”已经被证明不能混为一谈。

所以后续 `execution_scene` 里每个节点都应该优先稳定返回：

- `participation_state`
- `participation_label`
- `participation_reason`

推荐值直接固定成：

- `dispatch_active`
- `recent_only`
- `standby`
- `load_syncing`

这样页面“参与检测节点”、CLI 摘要、海外 Codex 驾驶员才能直接区分：

- 在线但未参与
- 正在领任务 / 正在执行
- 近窗刚参与但当前已收口
- 控制面和现场仍在同步

这层后续建议直接以 [ops_observability_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_observability_contract.md:1) 为观察面母本。

### 2. 远端日志回传必须从“有无样本”升级成“覆盖到哪些节点”

远端检测日志回传后续不能再只回答：

- 开了没
- 有样本没

这还不够支撑多机现场。

正式 contract 还要继续稳定返回：

- `source_node_summaries`
- `covered_participating_node_summaries`
- `missing_participating_node_summaries`

也就是说，控制面要能直接回答：

- 哪些参与节点已经有样本
- 哪些参与节点还没有样本
- 每台已覆盖节点当前拿到了多少关键行 / 全量行
- 最近一条样本来自谁

这样后面你不需要再自己翻日志去判断“到底是哪台机器没回传”，页面和 Codex 都能直接聚焦缺口节点。

### 3. Node Agent 拉到的任务包裹必须固定

Node Agent 后续不能只拿到：

- `action`
- `payload`

然后自己去猜这是不是 rollout、是不是巡检、是不是日志采样。

正式 Agent Job Envelope 应继续带上：

- `job_type`
- `step_key`
- `step_title`
- `policy`
- `release_context`
- `focus_ref`

这样同一个 Agent 才能稳定承接：

- 标准巡检
- Worker 日志
- 诊断收集
- Release 部署
- Rollout 回滚

这层后续建议直接以 [ops_agent_protocol.md](/www/wwwroot/getDomain/docs/schemas/ops_agent_protocol.md:1) 为执行面母本。

### 4. Release Hub 不能只显示版本，还必须冻结 manifest / readiness / preview

Release Hub 如果只停在：

- latest release
- rollout list

那本质上还是“看版本页面”，不是正式发布控制面。

接下来必须固定的 3 个发布对象是：

- `artifact manifest`
- `operational_readiness.rows`
- `rollout preview`

它们分别回答：

- 这个包到底会改哪些服务、怎么验、怎么回滚
- 哪台节点为什么能发 / 不能发
- 真正发 rollout 之前预计会分几批、风险在哪

这层后续建议直接以 [release_hub_contract.md](/www/wwwroot/getDomain/docs/schemas/release_hub_contract.md:1) 为发布面母本。

这 4 组字段一旦收死，后面再往下做页面、后端、CLI、Codex 自动驾驶时，就不会再反复经历：

- 先做一个能跑的版本
- 现场一复杂就发现字段不够
- 再回头改 contract
- 然后前后端一起返工

后续真正高效的节奏应该变成：

1. 先定 contract
2. 再做后端聚合
3. 再做页面展示
4. 最后接 Codex 自动驾驶

只有这样，Node Agent、Release Hub、OpsCenter 才会越来越像一个统一系统，而不是三块并排长大的模块。