dark/auto_agent

Fork 0

redbotu 62186e7994 feat: scaffold demo backend and task workflow

2026-04-08 21:42:43 +08:00

17 KiB

Raw Blame History

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

1. 文档说明

1.1 文档目的

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

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

Agent 对外任务接口。
云端与本地 Agent 的交互接口。
软件 A demo 接口。
身份 demo 接口。
审批 demo 接口。

1.2 设计目标

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

1.3 非目标

本文档不覆盖:

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

1.4 本轮首批 OpenAPI 落地范围

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

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

说明:

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

2. 总体约定

2.1 协议约定

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

2.2 字段命名规范

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

2.3 通用请求头

面向用户调用:

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

面向本地 Agent 调用:

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 通用响应格式

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

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

字段说明:

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

2.5 通用错误码

建议保留以下错误码:

OK
INVALID_PARAM
UNAUTHORIZED
FORBIDDEN
NOT_FOUND
CONFLICT
APPROVAL_REQUIRED
CONFIRM_REQUIRED
TOOL_CALL_FAILED
EDGE_UNAVAILABLE
SOFTWARE_A_FAILED
TIMEOUT
INTERNAL_ERROR

2.6 关键枚举定义

2.5.1 风险等级

["LOW", "MEDIUM", "HIGH"]

2.5.2 任务状态

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

2.5.3 审批状态

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

2.5.4 动作类型

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

说明:

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

请求示例:

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

响应示例:

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

说明:

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

请求示例:

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

响应示例:

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

响应示例:

{
  "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 建议包含:

task_basic
intent_snapshot
approval_trace
tool_trace
verification_trace
result_summary
audit_trace

3.5 取消任务

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

说明:

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

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

4.1 Edge 心跳

POST /api/agent/edge/heartbeat

请求示例:

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

请求示例:

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

响应示例:

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

请求示例:

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

说明:

用于上报:

本地 Agent 异常。
工具不可用。
证书异常。
系统资源异常。

5. 软件 A Demo 接口

5.1 设计说明

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

建议 base path:

/api/demo/software-a

5.2 创建部署任务

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

请求示例:

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

响应示例:

{
  "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 建议包含:

software_a_task_id
task_status
progress_percent
app_code
env
version
target_nodes
started_at
finished_at
error_detail

5.4 推送配置

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

请求示例:

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

统一请求示例:

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

请求示例:

{
  "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 建议包含:

total_count
entries
summary

entries 单条建议字段:

timestamp
level
host
message

5.7 查询指标

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

请求示例:

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

请求示例:

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

响应示例:

{
  "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 阶段闭环,不要求完全模拟现网身份系统,但必须支持:

登录。
用户信息查询。
角色信息查询。
基础权限集合返回。

建议 base path:

/api/demo/identity

6.2 登录

POST /api/demo/identity/login

请求示例:

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

响应示例:

{
  "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 建议包含:

user_id
roles
permissions
allowed_envs
allowed_apps

6.5 验证 Token

POST /api/demo/identity/token/introspect

7. 审批 Demo 接口

7.1 设计说明

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

创建审批单。
查询审批单。
通过或驳回审批。
审批记录留痕。

建议 base path:

/api/demo/approval

7.2 创建审批单

POST /api/demo/approval/requests

请求示例:

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

响应示例:

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

请求示例:

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

decision 可选值:

["APPROVED", "REJECTED"]

7.5 查询待审批列表

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

8. 建议的内部对象结构

8.1 Task 对象

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

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

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

9. 典型时序

9.1 部署时序

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

9.2 高风险审批时序

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

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

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

11. 推荐开发顺序

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

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

17 KiB Raw Blame History

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

1. 文档说明

1.1 文档目的

1.2 设计目标

1.3 非目标

1.4 本轮首批 OpenAPI 落地范围

2. 总体约定

2.1 协议约定

2.2 字段命名规范

2.3 通用请求头

2.4 通用响应格式

2.5 通用错误码

2.6 关键枚举定义

2.5.1 风险等级

2.5.2 任务状态

2.5.3 审批状态

2.5.4 动作类型

3. Agent 对外接口

3.1 创建任务

3.2 确认任务

3.3 查询任务详情

3.4 查询任务报告

3.5 取消任务

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

4.1 Edge 心跳

4.2 Edge 拉取任务

4.3 Edge 回传执行结果

4.4 Edge 上报异常

5. 软件 A Demo 接口

5.1 设计说明

5.2 创建部署任务

5.3 查询部署任务状态

5.4 推送配置

5.5 服务控制

5.5.1 启动服务

5.5.2 停止服务

5.5.3 重启服务

5.6 查询日志

5.7 查询指标

5.8 查询应用拓扑

5.9 权限校验

6. 身份 Demo 接口

6.1 设计说明

6.2 登录

6.3 获取当前用户信息

6.4 查询用户权限

6.5 验证 Token

7. 审批 Demo 接口

7.1 设计说明

7.2 创建审批单

7.3 查询审批单

7.4 审批决策

7.5 查询待审批列表

8. 建议的内部对象结构

8.1 Task 对象

8.2 ToolCall 对象

8.3 Approval 对象

9. 典型时序

9.1 部署时序

9.2 高风险审批时序

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

11. 推荐开发顺序

17 KiB

Raw Blame History