564 lines
12 KiB
Markdown
564 lines
12 KiB
Markdown
# domainCheck Ops Playbook Contract
|
||
|
||
## 1. 目标
|
||
|
||
这份文档用于冻结 `playbook catalog / preview / run / events` 的正式 contract。
|
||
|
||
这层的定位不是“页面里的一个弹窗”，而是：
|
||
|
||
- 控制面的正式编排对象
|
||
- 海外 Codex 驾驶员可消费的标准作业对象
|
||
- Driver / Runbook / Release / Inspection 之间的统一中间层
|
||
|
||
核心原则：
|
||
|
||
- 一次标准编排 = 一次 `playbook run`
|
||
- 页面、CLI、Codex 必须共用同一份 `playbook` / `playbook run` 结构
|
||
- `playbook run` 只负责创建与聚合正式 `ops job`
|
||
- 不允许前端再把“标准巡检 / 接管验收 / 现场日志”退回成零散按钮逻辑
|
||
|
||
建议与 [ops_job_contract.md](/www/wwwroot/getDomain/docs/schemas/ops_job_contract.md:1) 配套阅读。
|
||
|
||
---
|
||
|
||
## 2. 当前接口面
|
||
|
||
当前已落地的主入口：
|
||
|
||
- `GET /api/v1/ops/playbooks`
|
||
- `POST /api/v1/ops/playbooks/preview`
|
||
- `POST /api/v1/ops/playbooks/execute`
|
||
- `GET /api/v1/ops/playbook-runs`
|
||
- `GET /api/v1/ops/playbook-runs/{run_code}`
|
||
- `GET /api/v1/ops/playbook-runs/{run_code}/events`
|
||
- `POST /api/v1/ops/playbook-runs/{run_code}/rerun`
|
||
- `POST /api/v1/ops/playbook-runs/{run_code}/cancel`
|
||
|
||
并且这层已经被以下入口复用：
|
||
|
||
- `driver action -> open_playbook_dialog`
|
||
- `runbook sequence -> secondary_resolution`
|
||
- `inspection`
|
||
- `activity-stream`
|
||
|
||
所以后续不应再新造第四套“标准作业对象”。
|
||
|
||
---
|
||
|
||
## 3. Playbook Catalog Object
|
||
|
||
来源：
|
||
|
||
- `GET /api/v1/ops/playbooks`
|
||
- `preview / execute` 返回体中的 `playbook`
|
||
|
||
最小字段：
|
||
|
||
```json
|
||
{
|
||
"key": "inspection.standard",
|
||
"group_key": "diagnostics",
|
||
"group_title": "标准巡检",
|
||
"title": "标准巡检",
|
||
"description": "按 健康快照 -> Worker 日志 -> 诊断包 的顺序，对目标节点做一次标准联调巡检。",
|
||
"target_scope": "node-set",
|
||
"default_execution_mode": "remote-agent",
|
||
"default_execution_mode_label": "Node Agent",
|
||
"execution_modes": [
|
||
"remote-agent",
|
||
"ssh"
|
||
],
|
||
"execution_mode_options": [
|
||
{
|
||
"value": "remote-agent",
|
||
"label": "Node Agent",
|
||
"is_default": true
|
||
},
|
||
{
|
||
"value": "ssh",
|
||
"label": "SSH",
|
||
"is_default": false
|
||
}
|
||
],
|
||
"default_auto_approve": true,
|
||
"stop_on_failure": true,
|
||
"steps": [
|
||
{
|
||
"step_key": "health",
|
||
"title": "采集健康快照",
|
||
"template_key": "health.snapshot",
|
||
"payload": {}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
正式约束：
|
||
|
||
- `key`
|
||
- 是 Playbook 的稳定主键
|
||
- `group_key`
|
||
- 用于页面、CLI、Codex 做标准分组，不应用 `title` 猜
|
||
- `execution_modes`
|
||
- 是能力白名单，不是建议文案
|
||
- `stop_on_failure`
|
||
- 是编排级行为，不是某一步骤的临时说明
|
||
|
||
---
|
||
|
||
## 4. Playbook Preview Contract
|
||
|
||
来源：
|
||
|
||
- `POST /api/v1/ops/playbooks/preview`
|
||
|
||
最小请求体：
|
||
|
||
```json
|
||
{
|
||
"playbook_key": "inspection.standard",
|
||
"node_codes": [
|
||
"mainland-worker-01"
|
||
],
|
||
"execution_mode": "remote-agent",
|
||
"auto_approve": true,
|
||
"requested_by": "web-ui"
|
||
}
|
||
```
|
||
|
||
最小返回体：
|
||
|
||
```json
|
||
{
|
||
"playbook": {},
|
||
"requested_by": "web-ui",
|
||
"execution_mode": "remote-agent",
|
||
"execution_mode_label": "Node Agent",
|
||
"auto_approve": true,
|
||
"target_nodes_total": 1,
|
||
"target_node_codes": [
|
||
"mainland-worker-01"
|
||
],
|
||
"step_count": 3,
|
||
"expected_jobs_total": 3,
|
||
"template_keys": [
|
||
"health.snapshot",
|
||
"logs.collect",
|
||
"diagnostics.collect"
|
||
],
|
||
"steps": [
|
||
{
|
||
"order": 1,
|
||
"step_key": "health",
|
||
"title": "采集健康快照",
|
||
"template_key": "health.snapshot",
|
||
"action": "health.snapshot",
|
||
"payload": {},
|
||
"execution_mode": "remote-agent",
|
||
"execution_mode_label": "Node Agent",
|
||
"auto_approve": true,
|
||
"target_nodes_total": 1,
|
||
"expected_jobs": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
预览阶段必须回答：
|
||
|
||
- 最终执行方式是什么
|
||
- 总共会展开多少步
|
||
- 每步会展开成什么模板
|
||
- 总共会生成多少个 `ops job`
|
||
|
||
这样页面、CLI、Codex 才能在执行前看见“这次会做什么”。
|
||
|
||
---
|
||
|
||
## 5. Playbook Run Object
|
||
|
||
来源：
|
||
|
||
- `GET /api/v1/ops/playbook-runs`
|
||
- `GET /api/v1/ops/playbook-runs/{run_code}`
|
||
- `POST /api/v1/ops/playbooks/execute`
|
||
|
||
最小字段：
|
||
|
||
```json
|
||
{
|
||
"run_code": "playbook-20260418-001",
|
||
"playbook_key": "inspection.standard",
|
||
"playbook_title": "标准巡检",
|
||
"group_key": "diagnostics",
|
||
"group_title": "标准巡检",
|
||
"requested_by": "web-ui",
|
||
"execution_mode": "remote-agent",
|
||
"execution_mode_label": "Node Agent",
|
||
"stop_on_failure": true,
|
||
"step_count": 3,
|
||
"expected_jobs_total": 3,
|
||
"target_nodes_total": 1,
|
||
"target_node_codes": [
|
||
"mainland-worker-01"
|
||
],
|
||
"created_at": "2026-04-18 06:30:00",
|
||
"updated_at": "2026-04-18 06:31:10",
|
||
"status": "running",
|
||
"status_label": "收口中",
|
||
"status_counts": {
|
||
"queued": 1,
|
||
"running": 1,
|
||
"success": 1
|
||
},
|
||
"jobs_total": 3,
|
||
"success_jobs_total": 1,
|
||
"terminal_jobs_total": 1,
|
||
"completion_percent": 33.3,
|
||
"steps_total": 3,
|
||
"steps_success": 1,
|
||
"steps_running": 1,
|
||
"steps_problem": 0,
|
||
"steps_terminal": 1,
|
||
"focus_level": "warning",
|
||
"focus_step_key": "worker_logs",
|
||
"focus_step_title": "收集 Worker 日志",
|
||
"focus_summary": "收集 Worker 日志 当前仍在执行，先等待回执或检查对应节点事件流。",
|
||
"summary": "收集 Worker 日志 当前仍在执行，先等待回执或检查对应节点事件流。",
|
||
"summary_text": "收集 Worker 日志 当前仍在执行，先等待回执或检查对应节点事件流。",
|
||
"focus_ref": {
|
||
"kind": "playbook_run",
|
||
"run_code": "playbook-20260418-001",
|
||
"playbook_key": "inspection.standard",
|
||
"group_key": "diagnostics",
|
||
"focus_step_key": "worker_logs",
|
||
"focus_step_title": "收集 Worker 日志",
|
||
"event_key": "",
|
||
"node_code": ""
|
||
},
|
||
"problem_steps": [],
|
||
"active_steps": [],
|
||
"latest_job": {},
|
||
"steps": []
|
||
}
|
||
```
|
||
|
||
正式定义：
|
||
|
||
> `playbook run` 是一轮标准编排在控制面的聚合对象，不是某一条单独任务。
|
||
|
||
也就是说：
|
||
|
||
- `ops job` 是执行颗粒度
|
||
- `playbook run` 是观察、重跑、取消、钻取的编排颗粒度
|
||
|
||
---
|
||
|
||
## 6. Playbook Step Object
|
||
|
||
`playbook run.steps[]` 的最小结构：
|
||
|
||
```json
|
||
{
|
||
"step_key": "worker_logs",
|
||
"title": "收集 Worker 日志",
|
||
"template_key": "logs.collect",
|
||
"order": 2,
|
||
"jobs_total": 1,
|
||
"nodes_total": 1,
|
||
"target_node_codes": [
|
||
"mainland-worker-01"
|
||
],
|
||
"status_counts": {
|
||
"running": 1
|
||
},
|
||
"terminal_jobs_total": 0,
|
||
"success_jobs_total": 0,
|
||
"status": "running",
|
||
"status_label": "收口中",
|
||
"completion_percent": 0.0,
|
||
"summary": "收集 Worker 日志 当前处于执行中，可继续观察该步骤事件。",
|
||
"summary_text": "收集 Worker 日志 当前处于执行中，可继续观察该步骤事件。",
|
||
"focus_ref": {
|
||
"kind": "playbook_run",
|
||
"run_code": "playbook-20260418-001",
|
||
"playbook_key": "inspection.standard",
|
||
"group_key": "diagnostics",
|
||
"focus_step_key": "worker_logs",
|
||
"focus_step_title": "收集 Worker 日志",
|
||
"event_key": "",
|
||
"node_code": ""
|
||
},
|
||
"latest_job": {}
|
||
}
|
||
```
|
||
|
||
推荐 step 状态：
|
||
|
||
- `queued`
|
||
- `running`
|
||
- `success`
|
||
- `attention`
|
||
|
||
规则：
|
||
|
||
- 只要该步骤出现失败、阻断、取消等终态问题，应收口为 `attention`
|
||
- 页面与 Codex 都应优先盯 `problem_steps / active_steps`，而不是自己遍历所有子任务推断
|
||
|
||
---
|
||
|
||
## 7. Playbook Event Stream
|
||
|
||
来源：
|
||
|
||
- `GET /api/v1/ops/playbook-runs/{run_code}/events`
|
||
|
||
最小返回体：
|
||
|
||
```json
|
||
{
|
||
"run_code": "playbook-20260418-001",
|
||
"playbook_run": {},
|
||
"events": [
|
||
{
|
||
"job_id": 123,
|
||
"job_code": "ops-20260418-123",
|
||
"run_code": "playbook-20260418-001",
|
||
"job_status": "running",
|
||
"job_status_label": "收口中",
|
||
"action": "logs.collect",
|
||
"target_node_code": "mainland-worker-01",
|
||
"step_key": "worker_logs",
|
||
"step_title": "收集 Worker 日志",
|
||
"event_type": "job_running",
|
||
"level": "info",
|
||
"level_label": "信息",
|
||
"message": "开始收集 Worker 日志",
|
||
"summary": "开始收集 Worker 日志",
|
||
"summary_text": "开始收集 Worker 日志",
|
||
"payload": {},
|
||
"event_key": "job-event:1001",
|
||
"occurred_at": "2026-04-18 06:31:00",
|
||
"focus_ref": {
|
||
"kind": "playbook_run",
|
||
"run_code": "playbook-20260418-001",
|
||
"playbook_key": "inspection.standard",
|
||
"group_key": "diagnostics",
|
||
"focus_step_key": "worker_logs",
|
||
"focus_step_title": "收集 Worker 日志",
|
||
"event_key": "job-event:1001",
|
||
"node_code": "mainland-worker-01"
|
||
},
|
||
"created_at": "2026-04-18 06:31:00"
|
||
}
|
||
],
|
||
"summary": {
|
||
"total": 1,
|
||
"returned_total": 1,
|
||
"available_step_counts": {
|
||
"worker_logs": 1
|
||
},
|
||
"available_node_counts": {
|
||
"mainland-worker-01": 1
|
||
},
|
||
"level_counts": {
|
||
"info": 1
|
||
},
|
||
"event_type_counts": {
|
||
"job_running": 1
|
||
},
|
||
"job_status_counts": {
|
||
"running": 1
|
||
},
|
||
"latest_at": "2026-04-18 06:31:00",
|
||
"filters": {
|
||
"step_key": "",
|
||
"node_code": "",
|
||
"limit": 80
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
这层必须支持：
|
||
|
||
- 按 `step_key` 过滤
|
||
- 按 `node_code` 过滤
|
||
- 快速看到最近活动时间
|
||
|
||
否则 `playbook run` 只能看总览，不能真正钻取。
|
||
|
||
---
|
||
|
||
## 8. 正式 Playbook Key 语义
|
||
|
||
当前最值得冻结成正式对象的 key：
|
||
|
||
### 8.1 `onboarding.bootstrap`
|
||
|
||
定位：
|
||
|
||
- 生成节点接入工单
|
||
|
||
执行方式：
|
||
|
||
- 仅 `control-plane`
|
||
|
||
正式语义：
|
||
|
||
- 不直接接管节点
|
||
- 只创建标准接入方案对象
|
||
|
||
### 8.2 `onboarding.acceptance`
|
||
|
||
定位：
|
||
|
||
- 新节点接管后标准验收
|
||
|
||
当前标准步骤：
|
||
|
||
1. `health.snapshot`
|
||
2. `service.status(node-agent)`
|
||
3. `logs.collect(node-agent)`
|
||
4. `service.status(worker)`
|
||
5. `logs.collect(worker)`
|
||
|
||
### 8.3 `inspection.standard`
|
||
|
||
定位：
|
||
|
||
- 标准巡检
|
||
|
||
当前标准步骤：
|
||
|
||
1. `health.snapshot`
|
||
2. `logs.collect(worker)`
|
||
3. `diagnostics.collect`
|
||
|
||
正式要求：
|
||
|
||
- 这是 release / rollout 之前最核心的健康观察面
|
||
|
||
### 8.4 `scene.logs.key`
|
||
|
||
定位：
|
||
|
||
- 关键现场日志样本
|
||
|
||
正式要求：
|
||
|
||
- 默认比 `scene.logs.full` 更轻
|
||
- 适合先看现场，再决定是否升级取证
|
||
|
||
### 8.5 `scene.logs.full`
|
||
|
||
定位：
|
||
|
||
- 全量现场取证
|
||
|
||
正式要求：
|
||
|
||
- 应明确比 `scene.logs.key` 更重
|
||
- 默认应同时补诊断包
|
||
|
||
### 8.6 `scene.diagnostics`
|
||
|
||
定位：
|
||
|
||
- 轻量诊断包
|
||
|
||
正式要求：
|
||
|
||
- 适合作为参与节点的常规取证动作
|
||
|
||
---
|
||
|
||
## 9. 执行模式 Contract
|
||
|
||
推荐模式：
|
||
|
||
- `remote-agent`
|
||
- `ssh`
|
||
- `control-plane`
|
||
|
||
正式约束：
|
||
|
||
- `remote-agent`
|
||
- 正式日常运维默认模式
|
||
- `ssh`
|
||
- 仅用于首发接管与应急救援
|
||
- `control-plane`
|
||
- 只适合控制面本地对象生成或极少量控制面动作
|
||
|
||
页面、CLI、Codex 不能自己发明第四种临时模式。
|
||
|
||
---
|
||
|
||
## 10. Playbook Run 状态机
|
||
|
||
推荐状态：
|
||
|
||
- `queued`
|
||
- `running`
|
||
- `success`
|
||
- `attention`
|
||
|
||
含义：
|
||
|
||
- `queued`
|
||
- 子任务刚创建，尚未出现有效执行推进
|
||
- `running`
|
||
- 已有子任务进入 `dispatching / running / awaiting_approval`
|
||
- `success`
|
||
- 全部子任务收口成功
|
||
- `attention`
|
||
- 任一步骤出现失败、阻断、取消或部分成功，需要人工关注
|
||
|
||
正式规则：
|
||
|
||
- 页面上的“标准巡检状态”
|
||
- `activity-stream` 中的 playbook run 摘要
|
||
- Driver / Codex 的推荐动作
|
||
|
||
都必须共用这一套状态语义。
|
||
|
||
---
|
||
|
||
## 11. 与 Driver / Runbook / Release 的关系
|
||
|
||
正式收口规则：
|
||
|
||
- Driver 不直接“模拟巡检”
|
||
- 应优先跳转或创建 `playbook run`
|
||
- Runbook Sequence 不直接展开 shell
|
||
- 应优先收口到 `driver action` 或 `playbook`
|
||
- Release / Rollout 不自己维护另一套巡检摘要
|
||
- 应优先消费 `inspection.standard` 的最近结果
|
||
|
||
也就是说：
|
||
|
||
- `scene` 是现场观察对象
|
||
- `inspection` 是标准健康对象
|
||
- `release / rollout` 是发布对象
|
||
|
||
三者不能再各自维护不同的“日志 / 诊断 / 巡检”定义。
|
||
|
||
---
|
||
|
||
## 12. 正式要求
|
||
|
||
后续继续演进时，必须保持：
|
||
|
||
1. `playbook catalog`
|
||
- 是稳定 contract，而不是页面枚举
|
||
2. `playbook preview`
|
||
- 是执行前的唯一结构化预览面
|
||
3. `playbook run`
|
||
- 是页面、CLI、Codex 共同观察的一轮编排对象
|
||
4. `playbook events`
|
||
- 是整轮编排的钻取视角
|
||
5. 接管验收、标准巡检、现场观察
|
||
- 优先都收进 `playbook`
|
||
|
||
这样这套编排才能成为真正的正式平台能力，而不是一组“看起来像流程”的按钮。
|