getDomain/docs/24_domainCheck_NodeAgent协议与ReleaseHub设计.md

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 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 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 返回必须统一包裹

当前所有接口都已经走：

{
  "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

请求体

{
  "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

请求体

{
  "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

请求体

{
  "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

请求体

{
  "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

当前返回字段

{
  "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

请求体

{
  "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

请求体

{
  "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

请求体

{
  "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 为任务对象母本，再由 ops_agent_protocol.md 继续冻结 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 为母本，把 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 为正式母本。

这样后续：

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

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

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

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

---

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

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

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

其中“现场面 + 队列面”建议以后直接以 ops_observability_contract.md 为正式母本，避免后面又把这层能力重新拆散到页面局部状态里。

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

这样后续海外主机第一次接手现场时，默认起手式就固定为：

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
• ops_driver_contract.md
• ops_job_contract.md
• ops_agent_protocol.md
• release_hub_contract.md
• ops_observability_contract.md

只有这些 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. 总检入口必须真实可用

下面命令必须能在海外控制面直接打通：

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 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 为观察面母本。

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 为执行面母本。

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 为发布面母本。

这 4 组字段一旦收死，后面再往下做页面、后端、CLI、Codex 自动驾驶时，就不会再反复经历：

• 先做一个能跑的版本
• 现场一复杂就发现字段不够
• 再回头改 contract
• 然后前后端一起返工

后续真正高效的节奏应该变成：

1. 先定 contract
2. 再做后端聚合
3. 再做页面展示
4. 最后接 Codex 自动驾驶

只有这样，Node Agent、Release Hub、OpsCenter 才会越来越像一个统一系统，而不是三块并排长大的模块。