817 lines
17 KiB
Markdown
817 lines
17 KiB
Markdown
# domainCheck Ops Agent Protocol
|
||
|
||
## 1. 目标
|
||
|
||
这份文档用于冻结 `Node Agent <-> Overseas Control Plane` 的正式 contract。
|
||
|
||
适用范围：
|
||
|
||
- `POST /api/v1/ops/agent/tokens`
|
||
- `POST /api/v1/ops/agent/bootstrap-plan`
|
||
- `GET /api/v1/ops/nodes/{node_code}/handover`
|
||
- `POST /api/v1/ops/nodes/{node_code}/handover/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 只执行声明过的结构化动作
|
||
- 控制面负责调度、门禁、编排和审计
|
||
- 所有回执都必须可重放、可去重、可死信化
|
||
|
||
---
|
||
|
||
## 2. 公共响应包裹
|
||
|
||
所有接口统一返回：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"detail_code": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
约束：
|
||
|
||
- `code=0` 表示成功
|
||
- `code=1` 表示业务失败
|
||
- `detail_code` 用于结构化错误语义
|
||
- `message` 只承担可读说明，不承担机器判断主逻辑
|
||
|
||
常见 `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`
|
||
|
||
---
|
||
|
||
## 3. 认证与请求头
|
||
|
||
Agent 相关接口统一使用：
|
||
|
||
- `Content-Type: application/json`
|
||
- `X-Domaincheck-Agent-Token: <token>`
|
||
|
||
其中：
|
||
|
||
- `tokens`
|
||
- `bootstrap-plan`
|
||
|
||
不要求 Agent Token。
|
||
|
||
其余接口都要求 Token。
|
||
|
||
---
|
||
|
||
## 4. 公共节点载荷
|
||
|
||
`register` 与 `heartbeat` 当前共享 `_base_payload()`。
|
||
|
||
最小字段：
|
||
|
||
```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"
|
||
},
|
||
"delivery_queue": {
|
||
"state": "healthy",
|
||
"label": "正常",
|
||
"reason": "当前没有待重试回执，也没有死信记录。",
|
||
"pending_count": 0,
|
||
"dead_letter_count": 0,
|
||
"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": ""
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `service_names` 是控制面识别节点服务拓扑的最小入口
|
||
- `delivery_queue` 是控制面识别 Agent 回执现场的最小入口
|
||
|
||
---
|
||
|
||
## 5. Bootstrap Contract
|
||
|
||
### 5.1 Issue 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`
|
||
|
||
### 5.2 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"
|
||
}
|
||
}
|
||
```
|
||
|
||
返回体关键字段：
|
||
|
||
- 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 逻辑
|
||
|
||
---
|
||
|
||
## 6. Runtime Contract
|
||
|
||
### 6.1 Register
|
||
|
||
`POST /api/v1/ops/agent/register`
|
||
|
||
语义：
|
||
|
||
- 校验 Token 与 `node_code`
|
||
- Upsert Agent 运行态
|
||
- 将节点推入托管目录候选态
|
||
|
||
最小成功返回字段：
|
||
|
||
- `node_code`
|
||
- `expires_at`
|
||
- `capabilities`
|
||
|
||
### 6.2 Heartbeat
|
||
|
||
`POST /api/v1/ops/agent/heartbeat`
|
||
|
||
语义：
|
||
|
||
- 刷新 `last_seen_at`
|
||
- 刷新节点身份、服务名和队列快照
|
||
- 维持控制面中的 Agent 在线态
|
||
|
||
最小成功返回字段：
|
||
|
||
- `node_code`
|
||
- `server_time`
|
||
- `expires_at`
|
||
|
||
### 6.3 Pull
|
||
|
||
`POST /api/v1/ops/agent/pull?limit=1`
|
||
|
||
请求体最小字段：
|
||
|
||
```json
|
||
{
|
||
"node_code": "mainland-worker-02"
|
||
}
|
||
```
|
||
|
||
返回体关键字段：
|
||
|
||
```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 只能拿到属于自己的任务
|
||
- Agent 不负责选择任务
|
||
- 调度权始终在控制面
|
||
|
||
### 6.3.1 Agent Job Envelope
|
||
|
||
为了避免 Agent 再从自然语言动作名里“猜执行上下文”，`pull.data.jobs[]` 当前已经按统一任务包裹返回。
|
||
|
||
当前 `pull.data` 顶层也会额外带：
|
||
|
||
- `protocol_version`
|
||
- `envelope_type`
|
||
- `node_code`
|
||
- `limit`
|
||
- `count`
|
||
|
||
推荐最小结构：
|
||
|
||
```json
|
||
{
|
||
"protocol_version": "ops-agent/v1",
|
||
"envelope_type": "agent_job",
|
||
"id": 123,
|
||
"job_id": 123,
|
||
"job_code": "ops-20260418-001",
|
||
"job_type": "ops_action",
|
||
"action": "logs.collect",
|
||
"target_node_code": "mainland-worker-02",
|
||
"status": "dispatching",
|
||
"execution_mode": "remote-agent",
|
||
"step_key": "worker_logs",
|
||
"step_title": "收集 Worker 日志",
|
||
"job_ref": {
|
||
"job_id": 123,
|
||
"job_code": "ops-20260418-001",
|
||
"action": "logs.collect",
|
||
"target_node_code": "mainland-worker-02"
|
||
},
|
||
"step_ref": {
|
||
"step_id": 456,
|
||
"step_key": "worker_logs",
|
||
"step_title": "收集 Worker 日志"
|
||
},
|
||
"payload": {
|
||
"service_name": "domaincheck-worker",
|
||
"lines": 120,
|
||
"include_agent_logs": false
|
||
},
|
||
"policy": {
|
||
"timeout_seconds": 120,
|
||
"stop_on_failure": true,
|
||
"auto_approve": true
|
||
},
|
||
"metadata": {
|
||
"requested_by": "playbook:inspection.standard",
|
||
"source": "ops-center"
|
||
},
|
||
"release_context": {
|
||
"release_id": 0,
|
||
"release_version": "",
|
||
"rollout_id": 0,
|
||
"rollout_code": ""
|
||
},
|
||
"focus_ref": {
|
||
"kind": "ops_job",
|
||
"job_id": 123,
|
||
"job_code": "ops-20260418-001",
|
||
"action": "logs.collect",
|
||
"target_node_code": "mainland-worker-02"
|
||
}
|
||
}
|
||
```
|
||
|
||
正式要求：
|
||
|
||
- Agent 必须优先消费：
|
||
- `action`
|
||
- `payload`
|
||
- `policy`
|
||
- Agent 不应通过：
|
||
- `step_title`
|
||
- `summary`
|
||
- `notes`
|
||
去反推真实执行参数
|
||
- 与发布相关的任务应通过：
|
||
- `release_context`
|
||
传递 release / rollout 关联，而不是让 Agent 自己查询“当前版本”
|
||
|
||
这层的意义是：
|
||
|
||
- `ops job`
|
||
- 仍是正式执行颗粒度
|
||
- `Agent Job Envelope`
|
||
- 是 Node Agent 拿到的稳定执行视图
|
||
|
||
这样同一套 Agent 才能同时承接：
|
||
|
||
- 标准巡检
|
||
- 日志收集
|
||
- 诊断采样
|
||
- Release 部署
|
||
- Rollout 回滚
|
||
|
||
### 6.4 Start
|
||
|
||
`POST /api/v1/ops/agent/jobs/{job_id}/start`
|
||
|
||
请求体最小字段：
|
||
|
||
```json
|
||
{
|
||
"node_code": "mainland-worker-02"
|
||
}
|
||
```
|
||
|
||
语义：
|
||
|
||
- `dispatching` 表示已派发
|
||
- `running` 表示节点已真实开工
|
||
|
||
### 6.5 Complete
|
||
|
||
`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`
|
||
|
||
幂等约束：
|
||
|
||
- 使用 `client_request_id`
|
||
- 控制面写入 `ops_jobs.last_agent_complete_request_id`
|
||
- 同一完成回执可安全重放，不应再次制造副作用
|
||
|
||
推荐补充字段：
|
||
|
||
- `duration_ms`
|
||
- `result.summary_text`
|
||
- `result.focus_ref`
|
||
|
||
当前成功返回里也会额外带：
|
||
|
||
- `completion_summary.job_id`
|
||
- `completion_summary.job_code`
|
||
- `completion_summary.status`
|
||
- `completion_summary.status_label`
|
||
- `completion_summary.result_summary_text`
|
||
- `completion_summary.focus_ref`
|
||
- `completion_summary.deduplicated`
|
||
|
||
这样控制面在不展开 stdout/stderr 的情况下，也能直接把：
|
||
|
||
- 任务收口摘要
|
||
- 后续跳转落点
|
||
|
||
并入 activity / inspection / rollout 观察面。
|
||
|
||
### 6.6 Events
|
||
|
||
`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:..."
|
||
}
|
||
}
|
||
```
|
||
|
||
去重约束：
|
||
|
||
- 使用 `client_event_id`
|
||
- 控制面通过唯一索引去重
|
||
- 同一事件可安全重放，不应重复落库
|
||
|
||
推荐补充字段：
|
||
|
||
- `occurred_at`
|
||
- `summary_text`
|
||
- `focus_ref`
|
||
|
||
当前成功返回里也会额外带：
|
||
|
||
- `event`
|
||
- 即标准化后的事件对象
|
||
- 内含 `event_key / summary_text / occurred_at / focus_ref`
|
||
|
||
这样事件流就不再只是“原始日志点”，而能直接成为：
|
||
|
||
- playbook run events
|
||
- rollout events
|
||
- activity-stream
|
||
|
||
共同消费的现场片段。
|
||
|
||
---
|
||
|
||
## 7. Agent 本地补发队列
|
||
|
||
当前主链路已经正式具备：
|
||
|
||
- `pending` 队列
|
||
- `dead-letter` 队列
|
||
- 定时 `_flush_delivery_queue()`
|
||
- 永久性错误转死信
|
||
|
||
当前重点覆盖：
|
||
|
||
- `jobs/{id}/complete`
|
||
- `jobs/{id}/events`
|
||
|
||
队列状态：
|
||
|
||
- `healthy`
|
||
- `retrying`
|
||
- `dead_letter`
|
||
|
||
语义：
|
||
|
||
- `healthy`：无积压，无死信
|
||
- `retrying`：存在待补发回执，Agent 会继续自动重放
|
||
- `dead_letter`：存在永久失败记录，需人工介入
|
||
|
||
控制面消费方式：
|
||
|
||
- 节点维度：
|
||
- `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`
|
||
|
||
### 7.1 当前控制面已可见的最小现场
|
||
|
||
当前至少已经可以通过：
|
||
|
||
- `GET /api/v1/ops/nodes`
|
||
|
||
看到每台托管节点的队列现场：
|
||
|
||
```json
|
||
{
|
||
"node_code": "mainland-worker-02",
|
||
"delivery_queue_state": "dead_letter",
|
||
"delivery_queue_label": "死信 2",
|
||
"delivery_queue_reason": "当前存在 2 条死信记录，建议优先查看节点日志或诊断编排。",
|
||
"delivery_queue_pending_count": 0,
|
||
"delivery_queue_dead_letter_count": 2,
|
||
"delivery_queue_last_flush_at": "2026-04-18 06:10:00",
|
||
"delivery_queue_oldest_pending_at": "",
|
||
"delivery_queue_oldest_pending_request_id": "",
|
||
"delivery_queue_oldest_pending_kind": "",
|
||
"delivery_queue_oldest_dead_letter_at": "2026-04-18 05:59:00",
|
||
"delivery_queue_oldest_dead_letter_request_id": "complete-ops-123-1",
|
||
"delivery_queue_oldest_dead_letter_kind": "job_complete"
|
||
}
|
||
```
|
||
|
||
这已经足够让：
|
||
|
||
- 页面显示“节点存在死信”
|
||
- `overview / driver-feed / codex-brief` 产出驾驶建议
|
||
- CLI 快速判断现场是不是要先走日志或诊断
|
||
|
||
但这还不够支撑正式运维，因为它只能“看见死信”，还不能“处理死信”。
|
||
|
||
### 7.2 Delivery Queue Record 正式对象
|
||
|
||
后续控制面不应再把死信理解成一个纯计数器，而要把每条待补发 / 死信记录升级成正式对象。
|
||
|
||
推荐最小结构：
|
||
|
||
```json
|
||
{
|
||
"record_id": "dq-mainland-worker-02-20260418-001",
|
||
"node_code": "mainland-worker-02",
|
||
"state": "dead_letter",
|
||
"request_kind": "job_complete",
|
||
"client_request_id": "complete-ops-123-1",
|
||
"job_id": 123,
|
||
"job_code": "ops-20260418-001",
|
||
"target_api": "/api/v1/ops/agent/jobs/123/complete",
|
||
"detail_code": "ops_job_invalid_status_transition",
|
||
"error_message": "当前任务状态不允许 complete",
|
||
"attempt_count": 6,
|
||
"first_queued_at": "2026-04-18 05:58:00",
|
||
"last_attempt_at": "2026-04-18 05:59:00",
|
||
"next_retry_at": "",
|
||
"payload_preview": {
|
||
"status": "success"
|
||
},
|
||
"response_preview": {
|
||
"code": 1,
|
||
"detail_code": "ops_job_invalid_status_transition"
|
||
}
|
||
}
|
||
```
|
||
|
||
正式约束：
|
||
|
||
- `record_id`
|
||
- 是控制面侧唯一主键
|
||
- `client_request_id`
|
||
- 是 Agent 幂等键
|
||
- `detail_code`
|
||
- 是死信聚类主键，不能只靠 `message`
|
||
- `payload_preview / response_preview`
|
||
- 用于页面和 Codex 快速判断，不必默认展开完整原始报文
|
||
|
||
推荐状态：
|
||
|
||
- `pending`
|
||
- `retrying`
|
||
- `dead_letter`
|
||
- `replayed`
|
||
- `discarded`
|
||
|
||
### 7.3 死信操作面正式入口
|
||
|
||
为了让“看见死信”之后不用回节点本地处理，推荐把操作面固定成下面这组接口。
|
||
|
||
当前已落地的第一阶段能力：
|
||
|
||
- `GET /api/v1/ops/nodes/{node_code}/delivery-queue`
|
||
- `GET /api/v1/ops/nodes/{node_code}/delivery-queue/records`
|
||
|
||
当前控制面返回的记录可见性为：
|
||
|
||
- `record_visibility=head_only`
|
||
|
||
也就是：
|
||
|
||
- 当前已经能稳定查看节点级队列总览
|
||
- 也能看到 `pending / dead_letter` 的头部记录摘要
|
||
- 但还没有把节点本地全量 `pending/*.json / dead-letter/*.json` 正式同步到控制面
|
||
|
||
所以这两条 GET 入口现在属于“正式只读观察面”，而不是完整操作面。
|
||
|
||
#### a. 单节点队列总览
|
||
|
||
- `GET /api/v1/ops/nodes/{node_code}/delivery-queue`
|
||
|
||
最小返回体：
|
||
|
||
```json
|
||
{
|
||
"node_code": "mainland-worker-02",
|
||
"summary": {
|
||
"state": "dead_letter",
|
||
"pending_count": 0,
|
||
"dead_letter_count": 2,
|
||
"last_flush_at": "2026-04-18 06:10:00"
|
||
},
|
||
"oldest_pending_record": {},
|
||
"oldest_dead_letter_record": {}
|
||
}
|
||
```
|
||
|
||
#### b. 队列记录列表
|
||
|
||
- `GET /api/v1/ops/nodes/{node_code}/delivery-queue/records`
|
||
|
||
推荐筛选参数：
|
||
|
||
- `state=pending|retrying|dead_letter|replayed|discarded`
|
||
- `request_kind=job_complete|job_event`
|
||
- `detail_code=...`
|
||
- `group_by=detail_code|request_kind|target_api`
|
||
- `limit=50`
|
||
|
||
当带 `group_by` 时，返回值应优先给出聚类摘要，而不是只返回平铺明细。
|
||
|
||
#### c. 单条死信重放
|
||
|
||
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/records/{record_id}/replay`
|
||
|
||
当前已落地，但要明确当前阶段约束：
|
||
|
||
- 控制面仍然是 `record_visibility=head_only`
|
||
- 所以单条动作目前只允许针对“当前可见头部记录”
|
||
- 真正的执行不是控制面直接改远端文件，而是创建正式 `ops job`
|
||
- 由目标节点 `Node Agent` 执行 `delivery.queue.replay`
|
||
|
||
最小请求体：
|
||
|
||
```json
|
||
{
|
||
"requested_by": "web-ui",
|
||
"reason": "确认任务状态已修复，重放这条 complete 回执"
|
||
}
|
||
```
|
||
|
||
#### d. 批量重放
|
||
|
||
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/replay`
|
||
|
||
当前已落地为正式操作面。
|
||
|
||
推荐请求体：
|
||
|
||
```json
|
||
{
|
||
"requested_by": "codex",
|
||
"selector": {
|
||
"state": "dead_letter",
|
||
"detail_code": "ops_job_invalid_status_transition"
|
||
},
|
||
"limit": 20
|
||
}
|
||
```
|
||
|
||
#### e. 丢弃死信
|
||
|
||
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/records/{record_id}/discard`
|
||
|
||
当前已落地，但与单条重放一样，仍然只允许针对当前可见头部死信记录发起单条动作。
|
||
|
||
最小请求体：
|
||
|
||
```json
|
||
{
|
||
"discarded_by": "web-ui",
|
||
"reason": "确认这条回执不再需要补发"
|
||
}
|
||
```
|
||
|
||
#### f. 主动冲刷队列
|
||
|
||
- `POST /api/v1/ops/nodes/{node_code}/delivery-queue/flush`
|
||
|
||
当前已落地为正式操作面，执行方式同样是：
|
||
|
||
- 控制面创建 `ops job`
|
||
- 目标节点 `Node Agent` 执行 `delivery.queue.flush`
|
||
|
||
语义：
|
||
|
||
- 不是“强行成功”
|
||
- 而是立即触发一次 Agent 补发冲刷
|
||
- 结果仍然回到 `pending / retrying / dead_letter / replayed`
|
||
|
||
### 7.4 为什么必须做成正式操作面
|
||
|
||
这层不是为了让页面多一个按钮，而是为了保证：
|
||
|
||
- 页面可以处理死信
|
||
- CLI 可以处理死信
|
||
- 海外 Codex 驾驶员可以处理死信
|
||
|
||
三者都不需要绕回：
|
||
|
||
- 手工 SSH 登录节点
|
||
- 手工删本地文件
|
||
- 手工重放某条 HTTP 请求
|
||
|
||
正式规则应该固定成：
|
||
|
||
- “死信查看” 走控制面对象
|
||
- “死信重放 / 丢弃 / 冲刷” 走控制面对象
|
||
- Agent 只负责执行，不负责决定如何处理死信
|
||
|
||
---
|
||
|
||
## 8. Job Status Enum
|
||
|
||
当前 Agent 主链路约束：
|
||
|
||
- `queued`
|
||
- `dispatching`
|
||
- `running`
|
||
- `success`
|
||
- `failed`
|
||
- `partially_succeeded`
|
||
|
||
语义：
|
||
|
||
- `queued`：任务已创建，尚未派发
|
||
- `dispatching`：控制面已派发，但节点尚未确认开工
|
||
- `running`：节点已真实执行
|
||
- `success`：成功完成
|
||
- `failed`：失败完成
|
||
- `partially_succeeded`：部分成功，需关注
|
||
|
||
---
|
||
|
||
## 9. 实现边界
|
||
|
||
Agent 只执行已声明动作：
|
||
|
||
- `service.start`
|
||
- `service.stop`
|
||
- `service.restart`
|
||
- `service.status`
|
||
- `health.snapshot`
|
||
- `logs.collect`
|
||
- `diagnostics.collect`
|
||
- `deploy.release`
|
||
|
||
不允许控制面长期依赖任意 shell 下发。
|
||
|
||
`shell executor` 只能作为受限兜底能力存在，并必须挂审批与审计。
|