# 智能化部署 Agent Demo 接口定义说明

## 1. 文档说明

### 1.1 文档目的

本文档用于定义智能化部署 Agent MVP 阶段的 demo 接口,作为前后端开发、联调和本地 Agent 接入的直接输入。

本文档覆盖以下接口范围:

1. Agent 对外任务接口。
2. 云端与本地 Agent 的交互接口。
3. 软件 A 最小能力实现接口。
4. 身份 demo 接口。
5. 审批 demo 接口。

### 1.2 设计目标

1. 先打通完整闭环。
2. 接口语义尽量稳定,便于后续替换为真实系统。
3. 上层编排尽量不感知 demo 与真实系统差异。
4. 所有关键动作可追溯、可审计。

### 1.3 非目标

本文档不覆盖:

1. 前端页面字段细节。
2. 数据库表结构 DDL。
3. 真实软件 A 适配细节。
4. 所有部署场景的扩展字段。

### 1.4 本轮首批 OpenAPI 落地范围

本轮 OpenAPI 草案仅覆盖第一批主链路接口:

1. `POST /api/agent/tasks`
2. `POST /api/agent/tasks/{task_id}/confirm`
3. `GET /api/agent/tasks/{task_id}`

说明:

1. 软件 A 最小能力实现、身份 demo、审批 demo、edge 接口继续保留在本文档中作为后续实现输入。
2. 首批代码骨架只要求先打通以上三条主接口。
3. 后续扩展 OpenAPI 时,优先保持当前对象模型和错误码不变。

---

## 2. 总体约定

## 2.1 协议约定

1. 协议采用 `HTTPS + JSON`。
2. 字符编码采用 `UTF-8`。
3. 时间字段统一采用 `yyyy-MM-dd HH:mm:ss.SSS` 字符串格式,例如 `2026-04-07 18:00:00.123`。
4. 未特殊说明时,所有时间字段默认时区为 `Asia/Shanghai`。
5. 所有写接口建议支持 `request_id` 做幂等控制。

## 2.2 字段命名规范

1. 所有 JSON 字段统一采用 `snake_case`。
2. 主键、关联键、设备键、任务键统一使用 `*_id` 后缀,例如 `task_id`、`approval_id`、`edge_id`。
3. 状态字段统一使用 `*_status` 后缀,例如 `task_status`、`approval_status`。
4. 类型字段统一使用 `*_type` 后缀,例如 `action_type`、`os_type`。
5. 时间点字段统一使用 `*_at` 后缀,例如 `created_at`、`finished_at`、`expire_at`;通用响应时间字段保留 `timestamp`。
6. 毫秒级耗时统一使用 `*_ms` 后缀,例如 `duration_ms`、`latency_ms`、`timeout_ms`。
7. 数量统计统一使用 `*_count` 后缀,例如 `log_error_count`、`total_count`。
8. 集合字段优先使用复数名词,例如 `roles`、`permissions`、`target_nodes`。
9. 布尔字段按语义命名,通用执行结果使用 `success`,权限判断使用 `allowed`,验证结果使用 `*_ok`。
10. 令牌有效期等以秒为单位的持续时间字段统一使用 `*_seconds` 后缀,例如 `expires_in_seconds`。

## 2.3 通用请求头

面向用户调用:

```http
Authorization: Bearer <access_token>
Content-Type: application/json
X-Request-Id: 2f6af6ad-8d98-4f6a-90d4-1ec6a661f701
X-Tenant-Id: tenant-demo
```

面向本地 Agent 调用:

```http
Authorization: Bearer <edge_token>
Content-Type: application/json
X-Request-Id: 4a2e9309-5670-43cf-a88e-7ab5a36190e1
X-Edge-Id: edge-shanghai-001
X-Signature: <signature>
```

## 2.4 通用响应格式

所有接口统一返回如下格式:

```json
{
  "request_id": "2f6af6ad-8d98-4f6a-90d4-1ec6a661f701",
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {},
  "timestamp": "2026-04-08 14:30:00.123"
}
```

字段说明:

1. `request_id`:请求唯一标识。
2. `success`:是否成功。
3. `code`:业务错误码。
4. `message`:可读描述。
5. `data`:业务数据。
6. `timestamp`:响应时间。

## 2.5 通用错误码

建议保留以下错误码:

1. `OK`
2. `INVALID_PARAM`
3. `UNAUTHORIZED`
4. `FORBIDDEN`
5. `NOT_FOUND`
6. `CONFLICT`
7. `APPROVAL_REQUIRED`
8. `CONFIRM_REQUIRED`
9. `TOOL_CALL_FAILED`
10. `EDGE_UNAVAILABLE`
11. `SOFTWARE_A_FAILED`
12. `TIMEOUT`
13. `INTERNAL_ERROR`

## 2.6 关键枚举定义

### 2.5.1 风险等级

```json
["LOW", "MEDIUM", "HIGH"]
```

### 2.5.2 任务状态

```json
[
  "CREATED",
  "PENDING_CONFIRM",
  "PENDING_APPROVAL",
  "RUNNING",
  "VERIFYING",
  "SUCCEEDED",
  "FAILED",
  "PARTIAL_SUCCEEDED",
  "CANCELLED"
]
```

### 2.5.3 审批状态

```json
["NOT_REQUIRED", "PENDING", "APPROVED", "REJECTED", "EXPIRED"]
```

### 2.5.4 动作类型

```json
[
  "DEPLOY",
  "PUSH_CONFIG",
  "START_SERVICE",
  "STOP_SERVICE",
  "RESTART_SERVICE",
  "ROLLBACK",
  "QUERY_LOG",
  "HEALTH_CHECK",
  "CALL_THIRD_PARTY_API"
]
```

---

## 3. Agent 对外接口

## 3.1 创建任务

`POST /api/agent/tasks`

说明:

1. 接收用户自然语言输入。
2. 返回任务解析结果。
3. 若缺参或需要确认,不直接执行。

请求示例:

```json
{
  "input_text": "把 order-service 1.2.3 部署到测试环境",
  "channel": "WEB",
  "session_id": "sess-001",
  "tenant_id": "tenant-demo",
  "context": {
    "preferred_env": "test"
  }
}
```

响应示例:

```json
{
  "request_id": "req-001",
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "task_id": "task-20260408-001",
    "parsed_intent": {
      "action_type": "DEPLOY",
      "app_code": "order-service",
      "env": "test",
      "version": "1.2.3"
    },
    "missing_slots": [],
    "risk_level": "MEDIUM",
    "task_status": "PENDING_CONFIRM",
    "next_action": "CONFIRM_TASK"
  },
  "timestamp": "2026-04-08 14:30:00.123"
}
```

## 3.2 确认任务

`POST /api/agent/tasks/{task_id}/confirm`

说明:

1. 用户确认结构化任务。
2. 低中风险任务确认后可进入执行。
3. 高风险任务确认后进入审批。

请求示例:

```json
{
  "confirmed": true,
  "comment": "确认执行"
}
```

响应示例:

```json
{
  "request_id": "req-002",
  "success": true,
  "code": "OK",
  "message": "task confirmed",
  "data": {
    "task_id": "task-20260408-001",
    "task_status": "RUNNING",
    "approval_status": "NOT_REQUIRED"
  },
  "timestamp": "2026-04-08 14:31:00.123"
}
```

## 3.3 查询任务详情

`GET /api/agent/tasks/{task_id}`

响应示例:

```json
{
  "request_id": "req-003",
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "task_id": "task-20260408-001",
    "task_status": "VERIFYING",
    "approval_status": "NOT_REQUIRED",
    "risk_level": "MEDIUM",
    "intent": {
      "action_type": "DEPLOY",
      "app_code": "order-service",
      "env": "test",
      "version": "1.2.3"
    },
    "tool_calls": [
      {
        "tool_name": "deploy_package",
        "success": true
      }
    ],
    "verification_result": {
      "process_ok": true,
      "port_ok": true,
      "http_ok": true,
      "log_error_count": 0
    },
    "summary": "部署成功,自动验证通过"
  },
  "timestamp": "2026-04-08 14:35:00.123"
}
```

## 3.4 查询任务报告

`GET /api/agent/tasks/{task_id}/report`

说明:

返回完整执行报告,适合前端展示和审计导出。

响应 `data` 建议包含:

1. `task_basic`
2. `intent_snapshot`
3. `approval_trace`
4. `tool_trace`
5. `verification_trace`
6. `result_summary`
7. `audit_trace`

## 3.5 取消任务

`POST /api/agent/tasks/{task_id}/cancel`

说明:

1. 仅允许取消未完成任务。
2. 已经进入软件 A 执行阶段时,需要根据执行状态判断是否支持取消。

---

## 4. 云端与本地 Agent 交互接口

## 4.1 Edge 心跳

`POST /api/agent/edge/heartbeat`

请求示例:

```json
{
  "edge_id": "edge-shanghai-001",
  "hostname": "customer-host-01",
  "os_type": "WINDOWS",
  "agent_version": "0.1.0",
  "capabilities": [
    "check_process",
    "check_port",
    "http_health_check",
    "grep_log",
    "service_control_windows"
  ]
}
```

## 4.2 Edge 拉取任务

`POST /api/agent/edge/tasks/pull`

请求示例:

```json
{
  "edge_id": "edge-shanghai-001",
  "max_tasks": 5
}
```

响应示例:

```json
{
  "request_id": "req-101",
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "tasks": [
      {
        "task_id": "task-20260408-001",
        "step_id": "step-verify-01",
        "tool_name": "http_health_check",
        "params": {
          "url": "http://10.0.0.12:8080/actuator/health",
          "timeout_ms": 3000
        },
        "expire_at": "2026-04-08 14:40:00.123"
      }
    ]
  },
  "timestamp": "2026-04-08 14:35:10.123"
}
```

## 4.3 Edge 回传执行结果

`POST /api/agent/edge/tasks/report`

请求示例:

```json
{
  "edge_id": "edge-shanghai-001",
  "task_id": "task-20260408-001",
  "step_id": "step-verify-01",
  "tool_name": "http_health_check",
  "success": true,
  "code": "OK",
  "message": "200 OK",
  "data": {
    "status_code": 200,
    "latency_ms": 45
  },
  "evidence": {
    "response_body": "{\"status\":\"UP\"}"
  },
  "started_at": "2026-04-08 14:35:11.123",
  "finished_at": "2026-04-08 14:35:11.456"
}
```

## 4.4 Edge 上报异常

`POST /api/agent/edge/events`

说明:

用于上报:

1. 本地 Agent 异常。
2. 工具不可用。
3. 证书异常。
4. 系统资源异常。

---

## 5. 软件 A 最小能力实现接口

## 5.1 设计说明

软件 A 最小能力实现用于支撑 MVP 闭环,其接口语义需尽量贴近未来真实软件 A 的标准能力。

建议 base path:

`/api/demo/software-a`

## 5.2 创建部署任务

`POST /api/demo/software-a/deploy-tasks`

请求示例:

```json
{
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "tenant_id": "tenant-demo",
  "app_code": "order-service",
  "env": "test",
  "version": "1.2.3",
  "target_nodes": [
    "10.0.0.12",
    "10.0.0.13"
  ],
  "deploy_options": {
    "graceful": true
  }
}
```

响应示例:

```json
{
  "request_id": "req-sa-001",
  "success": true,
  "code": "OK",
  "message": "deploy task created",
  "data": {
    "software_a_task_id": "sa-task-001",
    "task_status": "RUNNING"
  },
  "timestamp": "2026-04-08 14:32:00.123"
}
```

## 5.3 查询部署任务状态

`GET /api/demo/software-a/deploy-tasks/{software_a_task_id}`

响应 `data` 建议包含:

1. `software_a_task_id`
2. `task_status`
3. `progress_percent`
4. `app_code`
5. `env`
6. `version`
7. `target_nodes`
8. `started_at`
9. `finished_at`
10. `error_detail`

## 5.4 推送配置

`POST /api/demo/software-a/config/push`

请求示例:

```json
{
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "app_code": "order-service",
  "env": "test",
  "config_template": "default-v1",
  "config_version": "20260408-01",
  "target_nodes": [
    "10.0.0.12"
  ]
}
```

## 5.5 服务控制

### 5.5.1 启动服务

`POST /api/demo/software-a/services/start`

### 5.5.2 停止服务

`POST /api/demo/software-a/services/stop`

### 5.5.3 重启服务

`POST /api/demo/software-a/services/restart`

统一请求示例:

```json
{
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "app_code": "order-service",
  "env": "test",
  "target_nodes": [
    "10.0.0.12"
  ]
}
```

## 5.6 查询日志

`POST /api/demo/software-a/logs/search`

请求示例:

```json
{
  "app_code": "order-service",
  "env": "test",
  "time_range": {
    "start_at": "2026-04-08 14:20:00.123",
    "end_at": "2026-04-08 14:30:00.123"
  },
  "keywords": [
    "ERROR",
    "Exception"
  ],
  "limit": 100
}
```

响应 `data` 建议包含:

1. `total_count`
2. `entries`
3. `summary`

`entries` 单条建议字段:

1. `timestamp`
2. `level`
3. `host`
4. `message`

## 5.7 查询指标

`POST /api/demo/software-a/metrics/query`

请求示例:

```json
{
  "app_code": "order-service",
  "env": "test",
  "metric_names": [
    "cpu_usage",
    "memory_usage",
    "http_5xx_count"
  ],
  "time_range": {
    "start_at": "2026-04-08 14:20:00.123",
    "end_at": "2026-04-08 14:30:00.123"
  }
}
```

## 5.8 查询应用拓扑

`GET /api/demo/software-a/apps/{app_code}/topology?env=test`

## 5.9 权限校验

`POST /api/demo/software-a/permissions/check`

请求示例:

```json
{
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "action_type": "DEPLOY",
  "app_code": "order-service",
  "env": "test"
}
```

响应示例:

```json
{
  "request_id": "req-sa-009",
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "allowed": true,
    "reason": ""
  },
  "timestamp": "2026-04-08 14:31:00.123"
}
```

---

## 6. 身份 Demo 接口

## 6.1 设计说明

身份 demo 用于 MVP 阶段闭环,不要求完全模拟现网身份系统,但必须支持:

1. 登录。
2. 用户信息查询。
3. 角色信息查询。
4. 基础权限集合返回。

建议 base path:

`/api/demo/identity`

## 6.2 登录

`POST /api/demo/identity/login`

请求示例:

```json
{
  "username": "alice",
  "password": "demo-password"
}
```

响应示例:

```json
{
  "request_id": "req-id-001",
  "success": true,
  "code": "OK",
  "message": "login success",
  "data": {
    "access_token": "demo-token-alice",
    "expires_in_seconds": 7200,
    "user": {
      "user_id": "u1001",
      "user_name": "alice",
      "display_name": "Alice",
      "roles": [
        "DEPLOY_OPERATOR"
      ],
      "tenant_id": "tenant-demo"
    }
  },
  "timestamp": "2026-04-08 14:00:00.123"
}
```

## 6.3 获取当前用户信息

`GET /api/demo/identity/me`

## 6.4 查询用户权限

`GET /api/demo/identity/users/{user_id}/permissions`

响应 `data` 建议包含:

1. `user_id`
2. `roles`
3. `permissions`
4. `allowed_envs`
5. `allowed_apps`

## 6.5 验证 Token

`POST /api/demo/identity/token/introspect`

---

## 7. 审批 Demo 接口

## 7.1 设计说明

审批 demo 用于高风险动作闭环,至少支持:

1. 创建审批单。
2. 查询审批单。
3. 通过或驳回审批。
4. 审批记录留痕。

建议 base path:

`/api/demo/approval`

## 7.2 创建审批单

`POST /api/demo/approval/requests`

请求示例:

```json
{
  "task_id": "task-20260408-888",
  "risk_level": "HIGH",
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "action_type": "RESTART_SERVICE",
  "target": {
    "app_code": "user-service",
    "env": "prod"
  },
  "reason": "生产故障恢复",
  "approvers": [
    "u2001"
  ]
}
```

响应示例:

```json
{
  "request_id": "req-ap-001",
  "success": true,
  "code": "OK",
  "message": "approval created",
  "data": {
    "approval_id": "ap-20260408-001",
    "approval_status": "PENDING"
  },
  "timestamp": "2026-04-08 14:40:00.123"
}
```

## 7.3 查询审批单

`GET /api/demo/approval/requests/{approval_id}`

## 7.4 审批决策

`POST /api/demo/approval/requests/{approval_id}/decision`

请求示例:

```json
{
  "decision": "APPROVED",
  "comment": "同意执行",
  "operator": {
    "user_id": "u2001",
    "user_name": "bob"
  }
}
```

`decision` 可选值:

```json
["APPROVED", "REJECTED"]
```

## 7.5 查询待审批列表

`GET /api/demo/approval/requests?approval_status=PENDING&approver_user_id=u2001`

---

## 8. 建议的内部对象结构

## 8.1 Task 对象

```json
{
  "task_id": "task-20260408-001",
  "session_id": "sess-001",
  "tenant_id": "tenant-demo",
  "operator": {
    "user_id": "u1001",
    "user_name": "alice"
  },
  "action_type": "DEPLOY",
  "app_code": "order-service",
  "env": "test",
  "version": "1.2.3",
  "target_nodes": [
    "10.0.0.12"
  ],
  "risk_level": "MEDIUM",
  "approval_status": "NOT_REQUIRED",
  "task_status": "RUNNING"
}
```

## 8.2 ToolCall 对象

```json
{
  "tool_call_id": "tool-call-001",
  "task_id": "task-20260408-001",
  "tool_name": "deploy_package",
  "request_payload": {},
  "response_payload": {},
  "success": true,
  "duration_ms": 1200,
  "started_at": "2026-04-08 14:31:00.123",
  "finished_at": "2026-04-08 14:31:01.456"
}
```

## 8.3 Approval 对象

```json
{
  "approval_id": "ap-20260408-001",
  "task_id": "task-20260408-888",
  "approval_status": "PENDING",
  "approvers": [
    "u2001"
  ],
  "decision_logs": []
}
```

---

## 9. 典型时序

## 9.1 部署时序

1. 用户调用 `POST /api/agent/tasks` 发起自然语言请求。
2. Agent 完成解析并返回 `task_id` 和结构化结果。
3. 用户调用确认接口。
4. Agent 调用身份 demo 获取操作者信息和权限。
5. Agent 调用软件 A 最小能力实现权限校验。
6. Agent 调用软件 A 最小能力实现创建部署任务。
7. Agent 轮询软件 A 最小能力实现查询状态。
8. Agent 调用 Edge 接口执行本地验证。
9. Agent 汇总结果,更新任务状态并生成报告。

## 9.2 高风险审批时序

1. 用户发起高风险任务。
2. Agent 判定需要审批。
3. Agent 调用审批 demo 创建审批单。
4. 审批人完成审批。
5. Agent 检查审批结果。
6. 审批通过后进入执行。

---

## 10. demo 与正式系统的替换原则

1. Agent 上层只依赖统一语义接口,不直接依赖 demo 接口字段差异。
2. 软件 A 最小能力实现、身份 demo、审批 demo 均应封装在适配层后面。
3. 后续替换真实系统时,优先保持上层对象模型不变。
4. 如真实系统能力不足,应在适配层内做降级,而不是修改编排主链路。

---

## 11. 推荐开发顺序

1. 先完成通用响应格式、错误码和枚举定义。
2. 再完成 Agent 对外任务接口。
3. 再完成软件 A 最小能力实现接口。
4. 再完成身份 demo 和审批 demo。
5. 最后完成本地 Agent 拉取任务与结果回传接口。

这样可以最短路径打通 MVP 主链路。