dark/auto_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

设计文档

Browse Source
This commit is contained in:
redbotu 2026-04-08 19:08:56 +08:00
parent 2b4f6dc3e0
commit 482c259f4d
6 changed files with 4730 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

718
智能化部署agent-demo后端项目骨架设计.md.txt Normal file
View File

@ -0,0 +1,718 @@
# 智能化部署 Agent Demo 后端项目骨架设计
## 1. 文档说明
### 1.1 文档目的
本文档用于定义智能化部署 Agent demo 阶段的后端项目骨架,作为研发启动时的直接输入。
本文档重点解决以下问题:
1. demo 后端采用什么形态落地。
2. 项目如何分层和分模块。
3. 哪些模块先实现,哪些模块后实现。
4. 数据如何落库。
5. 如何与软件 A demo、身份 demo、审批 demo、本地 Agent 对接。
### 1.2 适用范围
本文档适用于:
1. 后端研发。
2. 架构设计。
3. 联调排期。
4. demo 落地实施。
### 1.3 设计原则
1. demo 阶段优先打通主链路,不优先拆分微服务。
2. 内部采用清晰模块边界,后续可平滑拆分。
3. Agent 编排、策略治理、任务中心、适配器层必须独立建模。
4. 所有对外系统都通过适配器访问,不允许业务逻辑直接耦合具体 demo 接口。
5. 数据模型、字段命名、时间格式与现有两份文档保持一致。
---
## 2. demo 阶段推荐落地形态
## 2.1 总体建议
demo 阶段建议采用:
**单体后端服务 + 模块化分层 + 外部 demo 适配器 + 独立本地 Agent**
原因:
1. 当前目标是尽快打通闭环,而不是先解决分布式复杂度。
2. 软件 A、审批、身份本身都是 demo 版,先用单体服务更容易联调。
3. 任务编排、审批状态、工具调用、审计日志之间耦合较强,单体更利于快速演进。
4. 后续如果边界稳定,可以将任务中心、审批中心、模型网关逐步拆分。
## 2.2 部署单元建议
demo 阶段建议至少包含 4 个运行单元:
1. `agent-backend`
2. `edge-agent`
3. `postgres`
4. `redis`
可选:
1. `software-a-demo`
2. `identity-demo`
3. `approval-demo`
如果希望进一步压缩工作量,也可以把 `software-a-demo`、`identity-demo`、`approval-demo` 合并进 `agent-backend` 的 mock 模块中。
---
## 3. 技术栈建议
## 3.1 demo 后端推荐技术栈
建议优先采用:
1. Python 3.11+
2. FastAPI
3. Pydantic
4. SQLAlchemy
5. PostgreSQL
6. Redis
7. LangGraph
## 3.2 选择理由
### 3.2.1 为什么推荐 Python
1. LangGraph 生态更直接。
2. demo 阶段实现 Agent 编排更快。
3. 适合快速完成工具适配和状态流转。
4. 本地 Agent 也更容易做跨平台实现。
### 3.2.2 为什么推荐 FastAPI
1. 定义接口快。
2. Pydantic 模型与接口文档天然匹配。
3. 适合 demo 阶段快速落地。
### 3.2.3 为什么保留 PostgreSQL 和 Redis
1. PostgreSQL 用于结构化任务、审批、审计落库。
2. Redis 用于任务队列、幂等键、短期上下文和轮询状态。
## 3.3 如果团队必须走 Java
如果团队明确只能走 Java,也可以替换为:
1. Spring Boot
2. Spring Web
3. JPA / MyBatis
4. PostgreSQL
5. Redis
但 demo 阶段的 Agent 编排效率通常不如 Python 方案。
---
## 4. 项目结构建议
## 4.1 仓库形态建议
建议采用单仓结构:
```text
smart-deploy-agent-demo/
backend/
edge-agent/
docs/
scripts/
deploy/
```
## 4.2 后端目录结构建议
```text
backend/
app/
api/
agent/
edge/
internal/
core/
config.py
logging.py
security.py
exceptions.py
constants.py
domain/
task/
approval/
audit/
edge/
metadata/
schemas/
common.py
task.py
approval.py
edge.py
software_a.py
models/
task.py
tool_call.py
approval.py
audit_log.py
edge_node.py
session_context.py
app_metadata.py
repositories/
task_repository.py
approval_repository.py
audit_repository.py
edge_repository.py
metadata_repository.py
services/
task_service.py
agent_service.py
intent_service.py
risk_service.py
approval_service.py
audit_service.py
edge_service.py
verification_service.py
report_service.py
adapters/
llm/
llm_gateway.py
software_a/
base.py
demo_adapter.py
identity/
base.py
demo_adapter.py
approval/
base.py
demo_adapter.py
edge/
edge_dispatcher.py
workflows/
deploy_workflow.py
query_log_workflow.py
approval_workflow.py
workers/
task_runner.py
task_polling_worker.py
verify_worker.py
db/
base.py
session.py
migrations/
main.py
tests/
api/
services/
workflows/
adapters/
```
---
## 5. 模块职责设计
## 5.1 api 层
职责:
1. 接收 HTTP 请求。
2. 请求参数校验。
3. 调用 service。
4. 输出统一响应格式。
建议按接口边界拆分:
1. `api/agent`
2. `api/edge`
3. `api/internal`
说明:
1. `api/agent` 对应用户侧接口。
2. `api/edge` 对应本地 Agent 侧接口。
3. `api/internal` 对应内部管理、健康检查、mock 控制等接口。
## 5.2 schemas 层
职责:
1. 定义请求响应模型。
2. 与接口文档字段保持一致。
3. 避免 service 层直接处理原始 dict。
## 5.3 models 层
职责:
1. 定义数据库模型。
2. 维护持久化结构。
3. 不承载复杂业务逻辑。
## 5.4 repositories 层
职责:
1. 封装数据库访问。
2. 对 service 层提供统一持久化接口。
3. 隔离 ORM 细节。
## 5.5 services 层
这是后端核心业务层。
职责:
1. 编排任务创建。
2. 调用风险引擎。
3. 调用审批服务。
4. 调用适配器。
5. 维护任务状态机。
6. 汇总结果和生成报告。
## 5.6 adapters 层
职责:
1. 封装软件 A demo 调用。
2. 封装身份 demo 调用。
3. 封装审批 demo 调用。
4. 封装模型网关调用。
5. 封装本地 Agent 调度。
原则:
1. 所有外部系统接入必须先经过 adapter。
2. 上层 service 不直接拼接第三方 URL。
3. adapter 返回统一对象模型,而不是原始第三方响应。
## 5.7 workflows 层
职责:
1. 定义 LangGraph 状态机。
2. 管理任务节点顺序。
3. 将业务 service 组合成可运行工作流。
建议 workflow 按场景拆分:
1. `deploy_workflow`
2. `query_log_workflow`
3. `approval_workflow`
## 5.8 workers 层
职责:
1. 执行异步任务。
2. 轮询软件 A demo 状态。
3. 拉起验证流程。
4. 处理长任务和超时任务。
---
## 6. 建议的核心服务拆分
## 6.1 task_service
职责:
1. 创建任务。
2. 查询任务。
3. 确认任务。
4. 取消任务。
5. 更新任务状态。
## 6.2 agent_service
职责:
1. 驱动整体任务执行。
2. 调用 intent、risk、approval、adapter、report 等服务。
3. 负责主链路协调。
## 6.3 intent_service
职责:
1. 调用模型网关解析自然语言。
2. 生成结构化意图。
3. 标记缺失字段。
## 6.4 risk_service
职责:
1. 基于环境、动作、应用类型计算风险等级。
2. 判断是否需要确认。
3. 判断是否需要审批。
## 6.5 approval_service
职责:
1. 发起审批。
2. 查询审批状态。
3. 同步审批结果到任务。
## 6.6 verification_service
职责:
1. 生成验证步骤。
2. 调度本地 Agent。
3. 汇总验证结果。
## 6.7 report_service
职责:
1. 生成任务详情。
2. 生成任务报告。
3. 生成用户可读摘要。
## 6.8 audit_service
职责:
1. 记录关键行为。
2. 记录工具调用轨迹。
3. 记录审批轨迹。
4. 记录最终结果。
## 6.9 edge_service
职责:
1. 管理边缘节点注册和心跳。
2. 下发待执行步骤。
3. 接收执行结果和异常事件。
---
## 7. 数据库表建议
## 7.1 核心表清单
demo 阶段建议至少建立以下表:
1. `task`
2. `task_step`
3. `tool_call`
4. `approval_request`
5. `approval_decision_log`
6. `audit_log`
7. `edge_node`
8. `edge_task`
9. `session_context`
10. `app_metadata`
## 7.2 task 表建议字段
1. `task_id`
2. `session_id`
3. `tenant_id`
4. `operator_user_id`
5. `operator_user_name`
6. `input_text`
7. `action_type`
8. `app_code`
9. `env`
10. `version`
11. `risk_level`
12. `approval_status`
13. `task_status`
14. `summary`
15. `created_at`
16. `updated_at`
## 7.3 task_step 表建议字段
1. `step_id`
2. `task_id`
3. `step_type`
4. `step_name`
5. `step_status`
6. `executor_type`
7. `target_edge_id`
8. `request_payload`
9. `response_payload`
10. `started_at`
11. `finished_at`
## 7.4 tool_call 表建议字段
1. `tool_call_id`
2. `task_id`
3. `step_id`
4. `tool_name`
5. `request_payload`
6. `response_payload`
7. `success`
8. `duration_ms`
9. `started_at`
10. `finished_at`
## 7.5 approval_request 表建议字段
1. `approval_id`
2. `task_id`
3. `approval_status`
4. `risk_level`
5. `operator_user_id`
6. `approver_user_ids`
7. `reason`
8. `created_at`
9. `updated_at`
## 7.6 audit_log 表建议字段
1. `audit_id`
2. `task_id`
3. `action`
4. `operator_user_id`
5. `target`
6. `result`
7. `detail`
8. `timestamp`
---
## 8. 关键运行链路如何落到代码
## 8.1 创建任务链路
对应模块:
1. `api/agent/tasks.py`
2. `services/task_service.py`
3. `services/intent_service.py`
4. `services/risk_service.py`
5. `repositories/task_repository.py`
执行步骤:
1. 接收自然语言输入。
2. 调用 `intent_service` 生成结构化意图。
3. 调用 `risk_service` 生成风险等级。
4. 保存任务和初始状态。
5. 返回 `task_id` 和下一步动作。
## 8.2 确认任务链路
对应模块:
1. `api/agent/tasks.py`
2. `services/task_service.py`
3. `services/agent_service.py`
4. `services/approval_service.py`
5. `workers/task_runner.py`
执行步骤:
1. 接收确认请求。
2. 检查任务状态。
3. 如需审批则发起审批。
4. 如无需审批则投递异步执行任务。
## 8.3 执行部署链路
对应模块:
1. `workflows/deploy_workflow.py`
2. `services/agent_service.py`
3. `adapters/software_a/demo_adapter.py`
4. `workers/task_polling_worker.py`
5. `services/verification_service.py`
执行步骤:
1. 调用软件 A demo 创建部署任务。
2. 轮询部署状态。
3. 部署成功后生成验证步骤。
4. 下发到本地 Agent。
5. 汇总验证结果。
6. 生成报告。
## 8.4 本地验证链路
对应模块:
1. `api/edge/tasks.py`
2. `services/edge_service.py`
3. `adapters/edge/edge_dispatcher.py`
4. `workers/verify_worker.py`
执行步骤:
1. 本地 Agent 拉取待执行步骤。
2. 执行本地工具。
3. 上报执行结果。
4. 后端归档步骤状态并更新任务状态。
---
## 9. 本地 Agent 骨架建议
## 9.1 本地 Agent 目录建议
```text
edge-agent/
app/
core/
config.py
security.py
logging.py
client/
backend_client.py
executors/
process_executor.py
port_executor.py
http_executor.py
log_executor.py
windows_service_executor.py
linux_service_executor.py
registry/
tool_registry.py
scheduler/
polling_runner.py
main.py
```
## 9.2 本地 Agent 设计原则
1. 仅拉取结构化任务。
2. 不接收自由文本命令。
3. 不开放任意 shell。
4. 工具按操作系统分类适配。
5. 所有执行结果结构化回传。
---
## 10. 配置与环境变量建议
后端建议至少支持以下配置:
1. `APP_ENV`
2. `APP_PORT`
3. `DATABASE_URL`
4. `REDIS_URL`
5. `LLM_BASE_URL`
6. `LLM_API_KEY`
7. `SOFTWARE_A_BASE_URL`
8. `SOFTWARE_A_TIMEOUT_MS`
9. `IDENTITY_BASE_URL`
10. `APPROVAL_BASE_URL`
11. `EDGE_TOKEN_SECRET`
12. `DEFAULT_TIMEZONE`
本地 Agent 建议至少支持:
1. `EDGE_ID`
2. `EDGE_NAME`
3. `BACKEND_BASE_URL`
4. `EDGE_ACCESS_TOKEN`
5. `EDGE_OS_TYPE`
6. `POLL_INTERVAL_MS`
---
## 11. 开发顺序建议
## 11.1 第一批必须完成
1. 通用响应模型。
2. 配置加载。
3. 数据库连接。
4. `task`、`approval_request`、`audit_log` 表。
5. `POST /api/agent/tasks`
6. `POST /api/agent/tasks/{task_id}/confirm`
7. `GET /api/agent/tasks/{task_id}`
## 11.2 第二批完成
1. 软件 A demo adapter。
2. 部署工作流。
3. 审批 demo adapter。
4. 身份 demo adapter。
5. 异步任务执行。
## 11.3 第三批完成
1. edge 心跳。
2. edge 拉取任务。
3. edge 回传结果。
4. 验证结果汇总。
5. 任务报告接口。
## 11.4 第四批完成
1. 审计查询。
2. 应用元数据管理。
3. 错误处理完善。
4. 观测能力补齐。
---
## 12. 测试建议
## 12.1 单元测试
优先覆盖:
1. `intent_service`
2. `risk_service`
3. `task_service`
4. `approval_service`
5. adapter 错误转换
## 12.2 集成测试
优先覆盖:
1. 创建任务 -> 确认任务 -> 执行部署 -> 完成验证
2. 高风险任务 -> 创建审批 -> 审批通过 -> 执行
3. Edge 拉取任务 -> 执行 -> 回传
## 12.3 联调测试
至少覆盖:
1. 软件 A demo 联调。
2. 身份 demo 联调。
3. 审批 demo 联调。
4. 本地 Agent 联调。
---
## 13. 后续拆分方向
当 demo 稳定后,建议按以下边界拆分:
1. `agent-api`:接入与任务接口
2. `agent-orchestrator`:Agent 编排和工作流执行
3. `agent-governance`:审批、权限、风险、审计
4. `agent-edge-gateway`:本地 Agent 接入与调度
但在 demo 阶段,不建议一开始就拆。
---
## 14. 结论
demo 阶段最合适的落地方式不是复杂微服务,而是:
**单体后端服务承接主业务链路,内部按模块清晰分层;本地 Agent 独立运行;软件 A、身份、审批通过 adapter 接入。**
这套骨架的目标不是"一次到位",而是:
1. 尽快打通主链路。
2. 让模块边界稳定下来。
3. 为后续替换真实系统和服务拆分预留空间。

914
智能化部署agent-demo接口定义说明.md.txt Normal file
View File

@ -0,0 +1,914 @@
# 智能化部署 Agent Demo 接口定义说明
## 1. 文档说明
### 1.1 文档目的
本文档用于定义智能化部署 Agent MVP 阶段的 demo 接口,作为前后端开发、联调和本地 Agent 接入的直接输入。
本文档覆盖以下接口范围:
1. Agent 对外任务接口。
2. 云端与本地 Agent 的交互接口。
3. 软件 A demo 接口。
4. 身份 demo 接口。
5. 审批 demo 接口。
### 1.2 设计目标
1. 先打通完整闭环。
2. 接口语义尽量稳定,便于后续替换为真实系统。
3. 上层编排尽量不感知 demo 与真实系统差异。
4. 所有关键动作可追溯、可审计。
### 1.3 非目标
本文档不覆盖:
1. 前端页面字段细节。
2. 数据库表结构 DDL。
3. 真实软件 A 适配细节。
4. 所有部署场景的扩展字段。
---
## 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 Demo 接口
## 5.1 设计说明
软件 A demo 版本用于支撑 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 demo 权限校验。
6. Agent 调用软件 A demo 创建部署任务。
7. Agent 轮询软件 A demo 查询状态。
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、审批 demo 均应封装在适配层后面。
3. 后续替换真实系统时,优先保持上层对象模型不变。
4. 如真实系统能力不足,应在适配层内做降级,而不是修改编排主链路。
---
## 11. 推荐开发顺序
1. 先完成通用响应格式、错误码和枚举定义。
2. 再完成 Agent 对外任务接口。
3. 再完成软件 A demo 接口。
4. 再完成身份 demo 和审批 demo。
5. 最后完成本地 Agent 拉取任务与结果回传接口。
这样可以最短路径打通 MVP 主链路。

242
智能化部署agent-当前进度总结.md.txt Normal file
View File

@ -0,0 +1,242 @@
# 智能化部署 Agent 当前进度总结
更新时间:2026-04-08
## 1. 当前总体状态
当前阶段已完成从"需求方案"到"技术架构"再到"接口定义"和"demo 后端骨架"的文档化收敛,整体处于:
**方案已成型、文档体系已建立、技术路线已基本明确、代码尚未开始实现**
当前产出重点仍然是文档设计,不是代码开发。
---
## 2. 已完成的文档产出
当前目录已形成以下核心文档:
1. `智能化部署agent.md`
用于描述项目目标、场景、总体方案、风险、安全和实施路线。
2. `智能化部署agent-技术架构设计说明书.md`
用于描述系统架构、模块分层、数据模型、接口建议、安全设计和实施约束。
3. `智能化部署agent-demo接口定义说明.md`
用于描述 demo 阶段的接口协议、统一响应格式、状态枚举、Agent 接口、软件 A demo 接口、身份 demo 接口、审批 demo 接口。
4. `智能化部署agent-demo后端项目骨架设计.md`
用于描述 demo 后端的推荐技术栈、项目结构、模块职责、数据库表建议、代码落点和开发顺序。
5. `智能化部署agent-技术架构设计说明书.backup-20260408-141109.md`
为技术架构说明书备份文件。
---
## 3. 已完成的主要工作
### 3.1 方案文档已重写
已解决原始文档存在的编码和可读性问题,并重写为结构化方案文档,覆盖:
1. 项目目标。
2. 产品定位。
3. 核心需求拆解。
4. 风险分析。
5. 开源对标。
6. MVP 范围。
7. 实施路线。
### 3.2 技术架构说明书已形成
已形成较完整的技术架构设计说明书,覆盖:
1. 总体架构分层。
2. 核心模块职责。
3. 云端与本地部署架构。
4. 软件 A 集成设计。
5. 数据模型。
6. 接口设计建议。
7. 关键流程设计。
8. 安全设计。
9. 非功能设计。
### 3.3 已确认前提已写入架构文档
以下前提已被整理并写入技术架构设计说明书:
1. MVP 阶段先开发 demo 版软件 A,不直接对接真实软件 A。
2. 软件 A 的操作者透传和权限能力在 demo 阶段由 demo 实现承接。
3. 本地 Agent 部署环境为 Windows 和 Linux 混合环境。
4. 试点应用部署方式统一。
5. 审批系统和身份系统在现网可能已有接口,但当前阶段无法直接接入,需开发 demo 版闭环。
6. 模型接入方式支持自定义 `base_url` 和 `api_key`。
### 3.4 接口文档已形成
demo 接口定义文档已覆盖:
1. Agent 对外任务接口。
2. 云端与本地 Agent 交互接口。
3. 软件 A demo 接口。
4. 身份 demo 接口。
5. 审批 demo 接口。
6. 内部对象结构。
7. 典型时序。
### 3.5 文档规范已统一
已统一以下文档规范:
1. 时间字段格式统一为 `yyyy-MM-dd HH:mm:ss.SSS`
2. 默认时区统一为 `Asia/Shanghai`
3. JSON 字段统一采用 `snake_case`
4. 字段命名规则统一为:
`*_id`、`*_status`、`*_type`、`*_at`、`*_ms`、`*_count`
### 3.6 demo 后端骨架设计已完成
已完成 demo 后端项目骨架设计,明确:
1. 推荐采用单体后端服务 + 模块化分层。
2. 推荐技术栈为 Python + FastAPI + LangGraph。
3. 后端目录结构和模块边界。
4. 核心 service 划分。
5. 数据库表建议。
6. 本地 Agent 骨架建议。
7. 开发顺序建议。
---
## 4. 当前已明确的核心技术结论
### 4.1 架构方向
当前建议的总体方向是:
**软件 A 做执行底座,Agent 做智能编排层,本地 Agent 做受控执行器**
### 4.2 MVP 路线
当前 MVP 路线已经收敛为:
1. 自然语言发起任务。
2. Agent 解析意图并做结构化任务生成。
3. 策略层做风险判断。
4. 调用软件 A demo 执行部署或控制动作。
5. 调用本地 Agent 做验证。
6. 汇总结果,生成报告和审计。
### 4.3 技术选型方向
当前建议方向:
1. 编排框架优先 LangGraph。
2. demo 后端优先 Python + FastAPI。
3. 用户端本地 Agent 采用受控执行模式。
4. 所有外部系统统一通过 adapter 接入。
### 4.4 用户端 Python 运行方式建议
当前讨论结论是:
1. 用户端不应依赖客户现场预装 Python。
2. 本地 Agent 应做成"自带运行时"的便携包。
3. Windows 可采用 embeddable Python 或等价便携运行方式。
4. Linux 可采用自包含运行目录或可执行打包方式。
该结论已明确,但尚未系统性回写到所有设计文档。
### 4.5 数据库选择建议
当前讨论结论是:
1. 正式路线可以采用 PostgreSQL。
2. 如果以 demo 快速落地和减少安装成本为优先,可以先用 SQLite。
3. 后续试点或正式化阶段再切换 PostgreSQL。
该结论属于当前建议,尚未完整回写到骨架设计文档中。
### 4.6 开源和商用许可判断
当前讨论结论是:
1. Python、FastAPI、LangGraph、Pydantic、SQLAlchemy、PostgreSQL 等组件,整体上适合免费使用和商用。
2. Redis 的许可证情况相对复杂,不建议在文档中简单视为"低风险宽松开源"。
3. 如果确实需要 Redis 类组件,后续应评估 Valkey 或在 demo 阶段先不强依赖缓存中间件。
该结论属于当前建议,尚未完整回写到骨架设计文档中。
---
## 5. 当前尚未开始的部分
目前尚未开始以下工作:
1. demo 后端初始化代码。
2. 本地 Agent 初始化代码。
3. 数据库建表脚本。
4. OpenAPI 文档生成。
5. 软件 A demo 服务实现。
6. 身份 demo 服务实现。
7. 审批 demo 服务实现。
8. 验证插件实现。
9. 部署脚本和运行脚本。
10. 测试用例与联调脚本。
---
## 6. 当前存在的待落地事项
虽然整体文档体系已比较完整,但仍有几项内容尚未真正落到可运行层面:
1. 是否正式确认 demo 阶段使用 SQLite 还是 PostgreSQL。
2. 是否正式确认 Redis 在 demo 阶段保留、替换还是去掉。
3. 是否正式确认用户端 Agent 的交付格式:
Windows zip 包、Linux tar.gz 包,或单文件可执行包。
4. 是否继续补数据库 DDL 文档。
5. 是否继续补 OpenAPI 草案。
6. 是否直接开始生成 demo 后端代码骨架。
---
## 7. 建议的下一步
按当前进度,建议后续按以下顺序推进:
### 路线 A:继续补文档后再开发
1. 补数据库 DDL 设计。
2. 补 OpenAPI 草案。
3. 将 SQLite / PostgreSQL、Redis / Valkey、用户端 Python 便携运行方案正式回写到文档。
适合:
1. 先把设计收口到可以评审。
2. 由多人协作开发前需要统一边界。
### 路线 B:直接进入 demo 代码骨架
1. 生成 FastAPI 后端项目初始化代码。
2. 生成核心目录结构和空实现。
3. 先打通 `POST /api/agent/tasks`、确认任务、查询任务三条主接口。
4. 再补软件 A demo adapter、身份 demo adapter、审批 demo adapter。
适合:
1. 尽快进入实现阶段。
2. 通过代码反推细节问题。
当前更推荐:
**先补最小 DDL 和 OpenAPI 草案,然后直接进入 demo 后端代码骨架。**
---
## 8. 当前一句话结论
目前不是"还在想法阶段",而是已经完成了:
**方案文档 -> 技术架构 -> 接口定义 -> 后端骨架**
下一步已经可以从"写文档"切换到"写 demo 代码"。

871
智能化部署agent-技术架构设计说明书.backup-20260408-141109.md.txt Normal file
View File

@ -0,0 +1,871 @@
# 智能化部署 Agent 技术架构设计说明书
## 1. 文档说明
### 1.1 文档目的
本文档用于在《智能化部署 Agent 方案建议》基础上,进一步细化系统技术架构设计,作为后续研发、联调、评审、实施和试点落地的依据。
本文档重点回答以下问题:
1. 系统由哪些模块组成。
2. 云端与本地分别承担什么职责。
3. 软件 A 如何被接入和封装。
4. Agent 如何安全地调用部署、验证、日志、监控和第三方接口能力。
5. 高危动作如何被拦截、确认、审批和审计。
6. MVP 阶段应实现哪些能力,哪些能力暂缓。
### 1.2 适用范围
本文档适用于:
1. 研发架构设计。
2. 软件 A 集成设计。
3. 本地 Agent 设计。
4. 安全评审。
5. MVP 实施和试点。
### 1.3 设计原则
1. 复用软件 A,避免重复建设部署底座。
2. 所有执行必须受控,禁止模型直接自由执行命令。
3. 先覆盖标准场景,再扩展复杂场景。
4. 结论以工具证据为准,不以模型主观推断为准。
5. 安全、审批、审计与功能同级建设。
---
## 2. 建设目标
## 2.1 业务目标
建设一套支持自然语言交互的智能部署与验证 Agent,面向软件交付、实施和运维场景,完成以下工作:
1. 触发标准化软件部署,优先支持 Java 应用。
2. 调用软件 A 完成部署包推送、配置推送、任务执行和状态查询。
3. 执行日志检查、进程检查、端口检查、健康检查、第三方接口联调验证。
4. 输出标准化执行报告和结果结论。
5. 在生产等高风险场景下实现权限、审批、确认和审计。
## 2.2 技术目标
1. 建立统一的 Agent 编排层。
2. 建立统一的工具适配层。
3. 建立云端编排与本地执行分离架构。
4. 建立统一的任务模型、工具结果模型和审计模型。
5. 建立面向高风险动作的安全控制机制。
## 2.3 MVP 目标
MVP 目标是打通一条完整闭环:
> 用户自然语言输入 -> Agent 识别任务 -> 策略校验 -> 调用软件 A -> 本地验证 -> 结果汇总 -> 审计留痕
---
## 3. 总体架构设计
## 3.1 架构概览
系统采用"云端智能编排 + 本地受控执行 + 软件 A 作为执行底座"的总体架构。
### 3.1.1 云端核心职责
1. 用户接入与身份认证。
2. 大模型推理与任务理解。
3. 任务编排与状态流转。
4. 风险识别与策略决策。
5. 审批、审计和结果归档。
### 3.1.2 本地核心职责
1. 执行云端下发的结构化任务。
2. 调用软件 A 本地可达能力。
3. 调用本地验证工具。
4. 回传结构化结果和执行证据。
### 3.1.3 软件 A 的职责
1. 作为部署和配置下发的主执行引擎。
2. 提供部署任务状态查询能力。
3. 提供日志、监控、配置等基础运维数据能力。
## 3.2 架构分层
系统分为六层:
### 第一层:接入层
负责:
1. Web 控制台。
2. 企业 IM 机器人。
3. OpenAPI 接口。
### 第二层:会话与任务层
负责:
1. 会话管理。
2. 用户上下文管理。
3. 原始输入记录。
4. 任务创建与任务状态管理。
### 第三层:Agent 编排层
负责:
1. 意图识别。
2. 参数抽取。
3. 缺参澄清。
4. 任务规划。
5. 工具路由。
6. 结果总结。
### 第四层:策略治理层
负责:
1. 身份与权限校验。
2. 风险分级。
3. 二次确认。
4. 审批流。
5. 幂等控制。
6. 执行限流。
7. 审计日志。
### 第五层:工具适配层
负责:
1. 软件 A 适配器。
2. 本地验证适配器。
3. 第三方接口适配器。
### 第六层:执行与观测层
负责:
1. 云端任务调度。
2. 本地 Agent 执行器。
3. 日志、指标、Trace、审计采集。
---
## 4. 核心模块设计
## 4.1 接入层
### 4.1.1 Web 控制台
建议提供以下能力:
1. 对话输入。
2. 任务执行确认。
3. 审批处理。
4. 执行报告展示。
5. 审计查询。
### 4.1.2 企业 IM 机器人
适合:
1. 快速发起查询类任务。
2. 快速发起测试/预发部署任务。
3. 审批通知和结果通知。
### 4.1.3 OpenAPI
用于:
1. 第三方系统发起标准任务。
2. 自动化平台对接。
3. 审批和工单系统集成。
## 4.2 会话与任务层
### 4.2.1 会话管理
职责:
1. 维护用户会话上下文。
2. 关联最近任务。
3. 支持多轮澄清。
### 4.2.2 任务管理
任务状态建议至少包括:
1. `CREATED`
2. `PENDING_CONFIRM`
3. `PENDING_APPROVAL`
4. `RUNNING`
5. `VERIFYING`
6. `SUCCEEDED`
7. `FAILED`
8. `PARTIAL_SUCCEEDED`
9. `CANCELLED`
### 4.2.3 上下文约束
会话层不应将全部历史数据无边界提供给模型,建议:
1. 只传最近相关任务。
2. 对日志和工具结果做摘要。
3. 通过结构化上下文替代长文本拼接。
## 4.3 Agent 编排层
建议采用状态机方式实现,优先选择 LangGraph 类框架。
### 4.3.1 编排节点建议
建议包含以下节点:
1. `intent_parse`
2. `slot_extract`
3. `task_normalize`
4. `risk_evaluate`
5. `confirm_required`
6. `approval_required`
7. `tool_dispatch`
8. `verify_dispatch`
9. `result_summarize`
10. `audit_persist`
### 4.3.2 编排输入
输入至少包括:
1. 用户信息。
2. 原始文本。
3. 会话上下文。
4. 环境信息。
5. 应用元数据。
6. 风险规则。
### 4.3.3 编排输出
输出至少包括:
1. 标准化动作类型。
2. 结构化参数。
3. 风险等级。
4. 任务执行计划。
5. 工具调用列表。
6. 最终结论。
## 4.4 策略治理层
策略治理层必须在模型之外独立实现。
### 4.4.1 权限控制
建议同时支持:
1. RBAC:按角色授权。
2. ABAC:按环境、应用、租户、动作类型做属性控制。
### 4.4.2 风险分级
建议按以下维度综合计算:
1. 环境级别。
2. 动作类型。
3. 是否影响生产流量。
4. 是否涉及配置变更。
5. 是否涉及回滚或停机。
### 4.4.3 审批流
审批流建议支持:
1. 单人审批。
2. 多级审批。
3. 超时失效。
4. 审批驳回。
5. 审批记录审计。
### 4.4.4 幂等与并发控制
建议实现:
1. 任务唯一请求 ID。
2. 同一应用同一环境互斥执行。
3. 防止重复部署。
4. 防止同一审批结果重复使用。
## 4.5 工具适配层
### 4.5.1 设计目标
工具适配层的目标是将不同系统封装成统一可调用能力,避免编排层直接依赖外部系统差异。
### 4.5.2 统一工具协议
建议每个工具遵循统一协议:
输入:
1. `tool_name`
2. `request_id`
3. `operator`
4. `target`
5. `params`
输出:
1. `success`
2. `code`
3. `message`
4. `data`
5. `evidence`
6. `retryable`
7. `duration_ms`
8. `timestamp`
### 4.5.3 软件 A 适配器
建议封装以下能力:
1. `deploy_package`
2. `push_config`
3. `start_service`
4. `stop_service`
5. `restart_service`
6. `rollback_service`
7. `query_deploy_task`
8. `query_logs`
9. `query_alerts`
10. `query_metrics`
### 4.5.4 本地验证适配器
建议封装:
1. `check_process`
2. `check_port`
3. `http_health_check`
4. `tcp_probe`
5. `grep_log`
6. `jvm_status`
7. `disk_space_check`
### 4.5.5 第三方接口适配器
建议封装:
1. `invoke_http_api`
2. `query_cmdb`
3. `query_config_center`
4. `create_ticket`
5. `send_notification`
## 4.6 本地 Agent 执行器
### 4.6.1 核心职责
1. 校验任务签名。
2. 鉴权与策略匹配。
3. 执行工具调用。
4. 采集执行证据。
5. 回传执行结果。
### 4.6.2 执行约束
1. 不提供自由 Shell 能力。
2. 仅允许调用白名单工具。
3. 每个工具独立参数校验。
4. 每个工具有超时控制。
5. 每次执行都写审计日志。
---
## 5. 云端与本地部署架构
## 5.1 部署拓扑
建议部署为两部分:
### 云端服务
1. API 网关。
2. Agent 编排服务。
3. 策略引擎服务。
4. 审批与审计服务。
5. 元数据服务。
6. 任务中心。
7. 模型网关。
### 本地服务
1. 本地 Agent。
2. 本地工具插件。
3. 本地缓存与任务队列。
4. 本地审计日志模块。
## 5.2 通信模式
建议采用"云端下发结构化任务,本地回传结构化结果"的方式,避免传输自由文本命令。
通信要求:
1. 双向 TLS。
2. 设备身份认证。
3. 请求签名。
4. 任务过期时间。
5. 重放保护。
## 5.3 弱网与离线处理
建议支持:
1. 本地任务重试。
2. 网络恢复后结果补传。
3. 审批未完成任务不得离线执行。
4. 高风险任务必须在线校验策略。
---
## 6. 软件 A 集成设计
## 6.1 集成方式
优先级建议如下:
1. 首选 API / SDK 集成。
2. 其次通过网关封装内部接口。
3. 不建议通过页面自动化方式集成。
## 6.2 软件 A 接口能力清单
建议与软件 A 对接时确认以下能力:
1. 部署任务创建。
2. 配置推送。
3. 应用启停。
4. 回滚能力。
5. 任务状态查询。
6. 日志查询。
7. 告警查询。
8. 指标查询。
9. 应用拓扑查询。
10. 权限透传或操作者记录。
## 6.3 软件 A 适配器设计要求
1. 对外暴露统一语义接口。
2. 屏蔽软件 A 错误码差异。
3. 将软件 A 错误转换为统一错误模型。
4. 保留软件 A 原始任务 ID 以便追溯。
## 6.4 失败处理设计
需要区分:
1. 调用失败。
2. 任务创建成功但执行失败。
3. 软件 A 返回成功但验证失败。
4. 查询超时或状态不确定。
---
## 7. 数据模型设计
## 7.1 应用元数据模型
建议字段:
1. `app_code`
2. `app_name`
3. `env`
4. `deploy_type`
5. `package_type`
6. `service_start_mode`
7. `health_check_url`
8. `log_paths`
9. `listen_ports`
10. `dependencies`
11. `config_templates`
12. `rollback_policy`
13. `owner`
14. `risk_level`
## 7.2 任务模型
建议字段:
1. `task_id`
2. `session_id`
3. `tenant_id`
4. `operator`
5. `intent_type`
6. `action_type`
7. `app_code`
8. `env`
9. `version`
10. `target_nodes`
11. `risk_level`
12. `approval_status`
13. `task_status`
14. `plan_snapshot`
15. `result_summary`
16. `created_at`
17. `updated_at`
## 7.3 工具调用模型
建议字段:
1. `tool_call_id`
2. `task_id`
3. `tool_name`
4. `request_payload`
5. `response_payload`
6. `success`
7. `duration_ms`
8. `started_at`
9. `finished_at`
## 7.4 审计模型
建议字段:
1. `audit_id`
2. `task_id`
3. `operator`
4. `action`
5. `target`
6. `risk_level`
7. `approval_trace`
8. `tool_trace`
9. `result`
10. `timestamp`
---
## 8. 接口设计建议
## 8.1 对话任务接口
### 8.1.1 创建任务
`POST /api/agent/tasks`
请求示例字段:
1. `input_text`
2. `channel`
3. `session_id`
4. `tenant_id`
返回字段:
1. `task_id`
2. `parsed_intent`
3. `missing_slots`
4. `risk_level`
5. `next_action`
### 8.1.2 查询任务状态
`GET /api/agent/tasks/{task_id}`
返回字段:
1. `task_status`
2. `approval_status`
3. `tool_calls`
4. `verification_result`
5. `summary`
## 8.2 审批接口
### 8.2.1 提交审批
`POST /api/agent/approvals`
### 8.2.2 审批通过/驳回
`POST /api/agent/approvals/{approval_id}/decision`
## 8.3 本地 Agent 回调接口
### 8.3.1 拉取任务
`POST /api/agent/edge/tasks/pull`
### 8.3.2 回传结果
`POST /api/agent/edge/tasks/report`
## 8.4 软件 A 适配器内部接口
建议内部抽象接口:
1. `createDeployTask`
2. `queryDeployTask`
3. `pushConfig`
4. `restartService`
5. `queryLogs`
6. `queryMetrics`
---
## 9. 关键流程设计
## 9.1 部署流程
1. 用户输入部署请求。
2. Agent 解析意图并抽取参数。
3. 若缺参则澄清。
4. 风险引擎计算风险等级。
5. 若需确认或审批,则进入等待状态。
6. 调用软件 A 创建部署任务。
7. 查询部署状态直到完成或超时。
8. 调用本地验证工具执行校验。
9. 汇总证据并输出结论。
10. 写入审计。
## 9.2 日志查询流程
1. 用户输入日志查询请求。
2. Agent 识别应用、环境、时间范围和关键字。
3. 调用软件 A 或本地日志工具查询。
4. 进行摘要和异常聚合。
5. 输出结果。
## 9.3 第三方接口联调验证流程
1. 用户输入联调验证请求。
2. Agent 路由到第三方接口工具。
3. 获取响应码、响应体、耗时。
4. 必要时结合日志和监控交叉验证。
5. 输出验证结论。
## 9.4 生产环境高危操作流程
1. 判定为高风险操作。
2. 执行权限校验。
3. 执行二次确认。
4. 发起审批。
5. 审批通过后再执行。
6. 执行完成后自动验证。
7. 写入完整审计链路。
---
## 10. 安全设计
## 10.1 身份认证
建议:
1. 用户通过统一身份认证系统接入。
2. 本地 Agent 使用设备证书认证。
3. 内部服务间使用服务身份认证。
## 10.2 权限控制
按以下维度控制:
1. 用户角色。
2. 租户。
3. 应用。
4. 环境。
5. 动作类型。
## 10.3 敏感数据保护
1. Token、密钥、密码不进入模型上下文。
2. 日志和配置默认脱敏。
3. 用户展示层默认隐藏敏感字段。
## 10.4 Prompt Injection 防护
1. 所有日志、接口响应、配置文本视为不可信数据。
2. 不允许外部文本影响系统策略与审批逻辑。
3. 模型只能建议,不直接突破策略层。
## 10.5 本地执行安全
1. 工具白名单。
2. 参数白名单和格式校验。
3. 最小系统权限运行。
4. 限制出站访问范围。
5. 每个工具独立超时和资源限制。
## 10.6 审计要求
必须审计:
1. 原始输入。
2. 解析结果。
3. 风险结果。
4. 审批结果。
5. 工具调用。
6. 验证结果。
7. 最终结论。
---
## 11. 非功能设计
## 11.1 可用性
1. 核心服务支持水平扩展。
2. 任务执行状态可恢复。
3. 外部系统短时失败可重试。
## 11.2 稳定性
1. 每类工具单独超时控制。
2. 异常分类处理。
3. 长任务支持轮询与中断。
## 11.3 可观测性
建议采集:
1. 接口日志。
2. 工具调用日志。
3. 任务状态流转日志。
4. Trace。
5. 指标监控。
## 11.4 可扩展性
1. 工具插件化。
2. 应用元数据可配置化。
3. 策略规则可扩展。
4. 支持后续增加更多部署类型和中间件类型。
---
## 12. 技术选型建议
## 12.1 编排框架
推荐:
1. LangGraph 作为核心编排框架。
理由:
1. 更适合状态机和受控执行流程。
2. 更适合插入确认、审批和人工干预。
3. 更适合长期维护和审计追溯。
## 12.2 快速原型方案
如果需要快速演示,可选:
1. Dify 作为前台工作流和对话原型。
但长期建议迁移回代码化编排。
## 12.3 执行引擎
推荐:
1. 软件 A 作为主执行引擎。
2. AWX 或 Rundeck 作为补充能力,不作为主底座。
## 12.4 模型接入
建议采用模型网关方式,屏蔽底层模型差异,并统一处理:
1. Prompt 模板。
2. 模型选择。
3. 调用审计。
4. 敏感信息过滤。
---
## 13. MVP 范围与边界
## 13.1 MVP 纳入范围
1. Java 应用标准部署。
2. 配置推送。
3. 服务启停/重启。
4. 日志查询。
5. 进程/端口/HTTP 健康检查。
6. 审批和二次确认。
7. 审计留痕。
## 13.2 MVP 暂不纳入
1. 任意命令执行。
2. 复杂自治型多 Agent。
3. 自动根因分析闭环。
4. 无人审批的生产自动处置。
5. 全类型应用和全中间件覆盖。
---
## 14. 实施建议
## 14.1 第一阶段:接口与元数据梳理
输出:
1. 软件 A 接口清单。
2. 试点应用元数据模板。
3. 风险规则表。
4. 工具协议定义。
## 14.2 第二阶段:核心链路开发
输出:
1. 对话任务接口。
2. 编排服务。
3. 软件 A 适配器。
4. 本地 Agent 基础执行器。
5. 基础验证插件。
## 14.3 第三阶段:治理能力补齐
输出:
1. 审批接入。
2. 审计中心。
3. 任务中心。
4. 权限模型。
## 14.4 第四阶段:试点与优化
输出:
1. 试点应用上线。
2. 指标统计。
3. 问题闭环与优化清单。
---
## 15. 风险与待确认项
以下内容需要尽快确认,否则会影响架构落地:
1. 软件 A 当前是否有稳定 API/SDK。
2. 软件 A 是否支持操作者透传和权限控制。
3. 本地 Agent 部署环境是 Windows、Linux 还是混合。
4. 试点应用的部署方式是否统一。
5. 审批系统和身份系统是否已有标准接口。
6. 模型是否允许使用云端服务,还是必须私有化。
---
## 16. 结论
推荐将本项目建设为"受控执行型部署 Agent 平台",以软件 A 为执行底座,以 LangGraph 为编排核心,以本地 Agent 为边缘执行节点,以策略治理层保障高危动作安全。
从工程落地看,最关键的不是模型能力本身,而是以下四点:
1. 软件 A 能否提供稳定可调用接口。
2. 应用元数据是否完整。
3. 本地执行是否足够受控。
4. 审批、权限、审计是否能真正闭环。
如果以上四点落实,本项目具备较强的 MVP 落地可行性。

948
智能化部署agent-技术架构设计说明书.md.txt Normal file
View File

@ -0,0 +1,948 @@
# 智能化部署 Agent 技术架构设计说明书
## 1. 文档说明
### 1.1 文档目的
本文档用于在《智能化部署 Agent 方案建议》基础上,进一步细化系统技术架构设计,作为后续研发、联调、评审、实施和试点落地的依据。
本文档重点回答以下问题:
1. 系统由哪些模块组成。
2. 云端与本地分别承担什么职责。
3. 软件 A 如何被接入和封装。
4. Agent 如何安全地调用部署、验证、日志、监控和第三方接口能力。
5. 高危动作如何被拦截、确认、审批和审计。
6. MVP 阶段应实现哪些能力,哪些能力暂缓。
### 1.2 适用范围
本文档适用于:
1. 研发架构设计。
2. 软件 A 集成设计。
3. 本地 Agent 设计。
4. 安全评审。
5. MVP 实施和试点。
### 1.3 设计原则
1. 复用软件 A,避免重复建设部署底座。
2. 所有执行必须受控,禁止模型直接自由执行命令。
3. 先覆盖标准场景,再扩展复杂场景。
4. 结论以工具证据为准,不以模型主观推断为准。
5. 安全、审批、审计与功能同级建设。
---
## 2. 建设目标
## 2.1 业务目标
建设一套支持自然语言交互的智能部署与验证 Agent,面向软件交付、实施和运维场景,完成以下工作:
1. 触发标准化软件部署,优先支持 Java 应用。
2. 调用软件 A 完成部署包推送、配置推送、任务执行和状态查询。
3. 执行日志检查、进程检查、端口检查、健康检查、第三方接口联调验证。
4. 输出标准化执行报告和结果结论。
5. 在生产等高风险场景下实现权限、审批、确认和审计。
## 2.2 技术目标
1. 建立统一的 Agent 编排层。
2. 建立统一的工具适配层。
3. 建立云端编排与本地执行分离架构。
4. 建立统一的任务模型、工具结果模型和审计模型。
5. 建立面向高风险动作的安全控制机制。
## 2.3 MVP 目标
MVP 目标是打通一条完整闭环:
> 用户自然语言输入 -> Agent 识别任务 -> 策略校验 -> 调用软件 A -> 本地验证 -> 结果汇总 -> 审计留痕
---
## 3. 总体架构设计
## 3.1 架构概览
系统采用"云端智能编排 + 本地受控执行 + 软件 A 作为执行底座"的总体架构。
### 3.1.1 云端核心职责
1. 用户接入与身份认证。
2. 大模型推理与任务理解。
3. 任务编排与状态流转。
4. 风险识别与策略决策。
5. 审批、审计和结果归档。
### 3.1.2 本地核心职责
1. 执行云端下发的结构化任务。
2. 调用软件 A 本地可达能力。
3. 调用本地验证工具。
4. 回传结构化结果和执行证据。
### 3.1.3 软件 A 的职责
1. 作为部署和配置下发的主执行引擎。
2. 提供部署任务状态查询能力。
3. 提供日志、监控、配置等基础运维数据能力。
## 3.2 架构分层
系统分为六层:
### 第一层:接入层
负责:
1. Web 控制台。
2. 企业 IM 机器人。
3. OpenAPI 接口。
### 第二层:会话与任务层
负责:
1. 会话管理。
2. 用户上下文管理。
3. 原始输入记录。
4. 任务创建与任务状态管理。
### 第三层:Agent 编排层
负责:
1. 意图识别。
2. 参数抽取。
3. 缺参澄清。
4. 任务规划。
5. 工具路由。
6. 结果总结。
### 第四层:策略治理层
负责:
1. 身份与权限校验。
2. 风险分级。
3. 二次确认。
4. 审批流。
5. 幂等控制。
6. 执行限流。
7. 审计日志。
### 第五层:工具适配层
负责:
1. 软件 A 适配器。
2. 本地验证适配器。
3. 第三方接口适配器。
### 第六层:执行与观测层
负责:
1. 云端任务调度。
2. 本地 Agent 执行器。
3. 日志、指标、Trace、审计采集。
---
## 4. 核心模块设计
## 4.1 接入层
### 4.1.1 Web 控制台
建议提供以下能力:
1. 对话输入。
2. 任务执行确认。
3. 审批处理。
4. 执行报告展示。
5. 审计查询。
### 4.1.2 企业 IM 机器人
适合:
1. 快速发起查询类任务。
2. 快速发起测试/预发部署任务。
3. 审批通知和结果通知。
### 4.1.3 OpenAPI
用于:
1. 第三方系统发起标准任务。
2. 自动化平台对接。
3. 审批和工单系统集成。
## 4.2 会话与任务层
### 4.2.1 会话管理
职责:
1. 维护用户会话上下文。
2. 关联最近任务。
3. 支持多轮澄清。
### 4.2.2 任务管理
任务状态建议至少包括:
1. `CREATED`
2. `PENDING_CONFIRM`
3. `PENDING_APPROVAL`
4. `RUNNING`
5. `VERIFYING`
6. `SUCCEEDED`
7. `FAILED`
8. `PARTIAL_SUCCEEDED`
9. `CANCELLED`
### 4.2.3 上下文约束
会话层不应将全部历史数据无边界提供给模型,建议:
1. 只传最近相关任务。
2. 对日志和工具结果做摘要。
3. 通过结构化上下文替代长文本拼接。
## 4.3 Agent 编排层
建议采用状态机方式实现,优先选择 LangGraph 类框架。
### 4.3.1 编排节点建议
建议包含以下节点:
1. `intent_parse`
2. `slot_extract`
3. `task_normalize`
4. `risk_evaluate`
5. `confirm_required`
6. `approval_required`
7. `tool_dispatch`
8. `verify_dispatch`
9. `result_summarize`
10. `audit_persist`
### 4.3.2 编排输入
输入至少包括:
1. 用户信息。
2. 原始文本。
3. 会话上下文。
4. 环境信息。
5. 应用元数据。
6. 风险规则。
### 4.3.3 编排输出
输出至少包括:
1. 标准化动作类型。
2. 结构化参数。
3. 风险等级。
4. 任务执行计划。
5. 工具调用列表。
6. 最终结论。
## 4.4 策略治理层
策略治理层必须在模型之外独立实现。
### 4.4.1 权限控制
建议同时支持:
1. RBAC:按角色授权。
2. ABAC:按环境、应用、租户、动作类型做属性控制。
### 4.4.2 风险分级
建议按以下维度综合计算:
1. 环境级别。
2. 动作类型。
3. 是否影响生产流量。
4. 是否涉及配置变更。
5. 是否涉及回滚或停机。
### 4.4.3 审批流
审批流建议支持:
1. 单人审批。
2. 多级审批。
3. 超时失效。
4. 审批驳回。
5. 审批记录审计。
### 4.4.4 幂等与并发控制
建议实现:
1. 任务唯一请求 ID。
2. 同一应用同一环境互斥执行。
3. 防止重复部署。
4. 防止同一审批结果重复使用。
## 4.5 工具适配层
### 4.5.1 设计目标
工具适配层的目标是将不同系统封装成统一可调用能力,避免编排层直接依赖外部系统差异。
### 4.5.2 统一工具协议
建议每个工具遵循统一协议:
输入:
1. `tool_name`
2. `request_id`
3. `operator`
4. `target`
5. `params`
输出:
1. `success`
2. `code`
3. `message`
4. `data`
5. `evidence`
6. `retryable`
7. `duration_ms`
8. `timestamp`
### 4.5.3 软件 A 适配器
建议封装以下能力:
1. `deploy_package`
2. `push_config`
3. `start_service`
4. `stop_service`
5. `restart_service`
6. `rollback_service`
7. `query_deploy_task`
8. `query_logs`
9. `query_alerts`
10. `query_metrics`
### 4.5.4 本地验证适配器
建议封装:
1. `check_process`
2. `check_port`
3. `http_health_check`
4. `tcp_probe`
5. `grep_log`
6. `jvm_status`
7. `disk_space_check`
### 4.5.5 第三方接口适配器
建议封装:
1. `invoke_http_api`
2. `query_cmdb`
3. `query_config_center`
4. `create_ticket`
5. `send_notification`
## 4.6 本地 Agent 执行器
### 4.6.1 核心职责
1. 校验任务签名。
2. 鉴权与策略匹配。
3. 执行工具调用。
4. 采集执行证据。
5. 回传执行结果。
### 4.6.2 执行约束
1. 不提供自由 Shell 能力。
2. 仅允许调用白名单工具。
3. 每个工具独立参数校验。
4. 每个工具有超时控制。
5. 每次执行都写审计日志。
---
## 5. 云端与本地部署架构
## 5.1 部署拓扑
建议部署为两部分:
### 云端服务
1. API 网关。
2. Agent 编排服务。
3. 策略引擎服务。
4. 审批与审计服务。
5. 元数据服务。
6. 任务中心。
7. 模型网关。
### 本地服务
1. 本地 Agent。
2. 本地工具插件。
3. 本地缓存与任务队列。
4. 本地审计日志模块。
### 5.1.1 本地部署环境约束
本地 Agent 部署环境确认为混合环境,需同时支持 Windows 和 Linux,并根据用户现场环境选择部署方式。
因此架构上需满足:
1. 本地 Agent 核心能力跨平台一致。
2. 工具插件按操作系统实现适配层。
3. 进程检查、端口检查、日志采集、服务控制等能力需区分 Windows 与 Linux 实现。
4. 打包、安装、升级和日志路径配置需支持双平台差异。
## 5.2 通信模式
建议采用"云端下发结构化任务,本地回传结构化结果"的方式,避免传输自由文本命令。
通信要求:
1. 双向 TLS。
2. 设备身份认证。
3. 请求签名。
4. 任务过期时间。
5. 重放保护。
## 5.3 弱网与离线处理
建议支持:
1. 本地任务重试。
2. 网络恢复后结果补传。
3. 审批未完成任务不得离线执行。
4. 高风险任务必须在线校验策略。
---
## 6. 软件 A 集成设计
## 6.1 集成方式
优先级建议如下:
1. 首选 API / SDK 集成。
2. 其次通过网关封装内部接口。
3. 不建议通过页面自动化方式集成。
当前确认前提如下:
1. MVP 阶段不直接对接真实软件 A。
2. 需要先开发一个满足当前需求的 demo 版软件 A 接口层或模拟服务。
3. 后续对接真实软件 A 时,预计仍需做接口适配或能力改造。
## 6.2 软件 A 接口能力清单
建议与软件 A 对接时确认以下能力:
1. 部署任务创建。
2. 配置推送。
3. 应用启停。
4. 回滚能力。
5. 任务状态查询。
6. 日志查询。
7. 告警查询。
8. 指标查询。
9. 应用拓扑查询。
10. 权限透传或操作者记录。
基于当前已知前提,MVP 阶段建议 demo 版软件 A 至少提供以下能力:
1. 部署任务创建与任务状态查询。
2. 配置推送。
3. 服务启停与重启。
4. 基础日志查询。
5. 操作者标识透传。
6. 基础权限控制或最小可用权限校验。
## 6.3 软件 A 适配器设计要求
1. 对外暴露统一语义接口。
2. 屏蔽软件 A 错误码差异。
3. 将软件 A 错误转换为统一错误模型。
4. 保留软件 A 原始任务 ID 以便追溯。
5. 适配器接口需同时兼容 demo 版软件 A 和后续真实软件 A。
6. 适配器内部应预留能力探测和版本兼容机制,避免后续接入真实软件 A 时推翻上层编排逻辑。
## 6.4 失败处理设计
需要区分:
1. 调用失败。
2. 任务创建成功但执行失败。
3. 软件 A 返回成功但验证失败。
4. 查询超时或状态不确定。
对于 MVP 阶段,还需要额外区分:
1. demo 版软件 A 能力未实现。
2. demo 版接口与未来真实软件 A 语义不一致。
3. 真实软件 A 接入后因接口缺口需要降级处理。
---
## 7. 数据模型设计
本说明书中的时间字段,例如 `created_at`、`updated_at`、`started_at`、`finished_at`、`timestamp`,统一采用 `yyyy-MM-dd HH:mm:ss.SSS` 字符串格式,默认时区为 `Asia/Shanghai`。
字段命名建议统一遵循以下规范:
1. JSON 字段统一采用 `snake_case`。
2. 主键和关联键统一使用 `*_id`。
3. 状态字段统一使用 `*_status`。
4. 类型字段统一使用 `*_type`。
5. 时间点字段统一使用 `*_at`,通用响应时间可使用 `timestamp`。
6. 毫秒级耗时统一使用 `*_ms`。
7. 数量统计统一使用 `*_count`。
8. 集合字段优先使用复数名词。
## 7.1 应用元数据模型
建议字段:
1. `app_code`
2. `app_name`
3. `env`
4. `deploy_type`
5. `package_type`
6. `service_start_mode`
7. `health_check_url`
8. `log_paths`
9. `listen_ports`
10. `dependencies`
11. `config_templates`
12. `rollback_policy`
13. `owner`
14. `risk_level`
## 7.2 任务模型
建议字段:
1. `task_id`
2. `session_id`
3. `tenant_id`
4. `operator`
5. `intent_type`
6. `action_type`
7. `app_code`
8. `env`
9. `version`
10. `target_nodes`
11. `risk_level`
12. `approval_status`
13. `task_status`
14. `plan_snapshot`
15. `result_summary`
16. `created_at`
17. `updated_at`
## 7.3 工具调用模型
建议字段:
1. `tool_call_id`
2. `task_id`
3. `tool_name`
4. `request_payload`
5. `response_payload`
6. `success`
7. `duration_ms`
8. `started_at`
9. `finished_at`
## 7.4 审计模型
建议字段:
1. `audit_id`
2. `task_id`
3. `operator`
4. `action`
5. `target`
6. `risk_level`
7. `approval_trace`
8. `tool_trace`
9. `result`
10. `timestamp`
---
## 8. 接口设计建议
## 8.1 对话任务接口
### 8.1.1 创建任务
`POST /api/agent/tasks`
请求示例字段:
1. `input_text`
2. `channel`
3. `session_id`
4. `tenant_id`
返回字段:
1. `task_id`
2. `parsed_intent`
3. `missing_slots`
4. `risk_level`
5. `next_action`
### 8.1.2 查询任务状态
`GET /api/agent/tasks/{task_id}`
返回字段:
1. `task_status`
2. `approval_status`
3. `tool_calls`
4. `verification_result`
5. `summary`
## 8.2 审批接口
### 8.2.1 提交审批
`POST /api/agent/approvals`
### 8.2.2 审批通过/驳回
`POST /api/agent/approvals/{approval_id}/decision`
## 8.3 本地 Agent 回调接口
### 8.3.1 拉取任务
`POST /api/agent/edge/tasks/pull`
### 8.3.2 回传结果
`POST /api/agent/edge/tasks/report`
## 8.4 软件 A 适配器内部接口
建议内部抽象接口:
1. `create_deploy_task`
2. `query_deploy_task`
3. `push_config`
4. `restart_service`
5. `query_logs`
6. `query_metrics`
---
## 9. 关键流程设计
## 9.1 部署流程
1. 用户输入部署请求。
2. Agent 解析意图并抽取参数。
3. 若缺参则澄清。
4. 风险引擎计算风险等级。
5. 若需确认或审批,则进入等待状态。
6. 调用软件 A 创建部署任务。
7. 查询部署状态直到完成或超时。
8. 调用本地验证工具执行校验。
9. 汇总证据并输出结论。
10. 写入审计。
## 9.2 日志查询流程
1. 用户输入日志查询请求。
2. Agent 识别应用、环境、时间范围和关键字。
3. 调用软件 A 或本地日志工具查询。
4. 进行摘要和异常聚合。
5. 输出结果。
## 9.3 第三方接口联调验证流程
1. 用户输入联调验证请求。
2. Agent 路由到第三方接口工具。
3. 获取响应码、响应体、耗时。
4. 必要时结合日志和监控交叉验证。
5. 输出验证结论。
## 9.4 生产环境高危操作流程
1. 判定为高风险操作。
2. 执行权限校验。
3. 执行二次确认。
4. 发起审批。
5. 审批通过后再执行。
6. 执行完成后自动验证。
7. 写入完整审计链路。
---
## 10. 安全设计
## 10.1 身份认证
建议:
1. 用户通过统一身份认证系统接入。
2. 本地 Agent 使用设备证书认证。
3. 内部服务间使用服务身份认证。
当前确认前提如下:
1. 现网可能已有身份系统标准接口,但当前阶段无法直接接入。
2. MVP 阶段需开发 demo 版身份能力,用于完成登录、用户识别、角色识别和基础鉴权闭环。
## 10.2 权限控制
按以下维度控制:
1. 用户角色。
2. 租户。
3. 应用。
4. 环境。
5. 动作类型。
当前确认前提如下:
1. 现网审批系统可能已有标准接口,但当前阶段无法直接接入。
2. MVP 阶段需提供 demo 版审批能力,至少支持提交审批、审批通过、审批驳回和审批记录。
## 10.3 敏感数据保护
1. Token、密钥、密码不进入模型上下文。
2. 日志和配置默认脱敏。
3. 用户展示层默认隐藏敏感字段。
## 10.4 Prompt Injection 防护
1. 所有日志、接口响应、配置文本视为不可信数据。
2. 不允许外部文本影响系统策略与审批逻辑。
3. 模型只能建议,不直接突破策略层。
## 10.5 本地执行安全
1. 工具白名单。
2. 参数白名单和格式校验。
3. 最小系统权限运行。
4. 限制出站访问范围。
5. 每个工具独立超时和资源限制。
## 10.6 审计要求
必须审计:
1. 原始输入。
2. 解析结果。
3. 风险结果。
4. 审批结果。
5. 工具调用。
6. 验证结果。
7. 最终结论。
---
## 11. 非功能设计
## 11.1 可用性
1. 核心服务支持水平扩展。
2. 任务执行状态可恢复。
3. 外部系统短时失败可重试。
## 11.2 稳定性
1. 每类工具单独超时控制。
2. 异常分类处理。
3. 长任务支持轮询与中断。
## 11.3 可观测性
建议采集:
1. 接口日志。
2. 工具调用日志。
3. 任务状态流转日志。
4. Trace。
5. 指标监控。
## 11.4 可扩展性
1. 工具插件化。
2. 应用元数据可配置化。
3. 策略规则可扩展。
4. 支持后续增加更多部署类型和中间件类型。
---
## 12. 技术选型建议
## 12.1 编排框架
推荐:
1. LangGraph 作为核心编排框架。
理由:
1. 更适合状态机和受控执行流程。
2. 更适合插入确认、审批和人工干预。
3. 更适合长期维护和审计追溯。
## 12.2 快速原型方案
如果需要快速演示,可选:
1. Dify 作为前台工作流和对话原型。
但长期建议迁移回代码化编排。
## 12.3 执行引擎
推荐:
1. 软件 A 作为主执行引擎。
2. AWX 或 Rundeck 作为补充能力,不作为主底座。
落地约束:
1. MVP 阶段由 demo 版软件 A 承担主执行引擎角色。
2. 正式阶段再对接真实软件 A,并通过适配层完成平滑切换。
## 12.4 模型接入
建议采用模型网关方式,屏蔽底层模型差异,并统一处理:
1. Prompt 模板。
2. 模型选择。
3. 调用审计。
4. 敏感信息过滤。
模型接入前提已确认如下:
1. 模型接入方式支持自定义 `base_url` 和 `api_key`。
2. 因此架构上不强制限定为公有云模型或私有化模型。
3. 模型网关需支持多模型源配置、动态切换和按租户配置接入参数。
4. 模型网关需支持最小化敏感信息透传和调用审计。
---
## 13. MVP 范围与边界
## 13.1 MVP 纳入范围
1. Java 应用标准部署。
2. 配置推送。
3. 服务启停/重启。
4. 日志查询。
5. 进程/端口/HTTP 健康检查。
6. 审批和二次确认。
7. 审计留痕。
## 13.2 MVP 暂不纳入
1. 任意命令执行。
2. 复杂自治型多 Agent。
3. 自动根因分析闭环。
4. 无人审批的生产自动处置。
5. 全类型应用和全中间件覆盖。
---
## 14. 实施建议
## 14.1 第一阶段:接口与元数据梳理
输出:
1. 软件 A 接口清单。
2. 试点应用元数据模板。
3. 风险规则表。
4. 工具协议定义。
## 14.2 第二阶段:核心链路开发
输出:
1. 对话任务接口。
2. 编排服务。
3. 软件 A 适配器。
4. 本地 Agent 基础执行器。
5. 基础验证插件。
## 14.3 第三阶段:治理能力补齐
输出:
1. 审批接入。
2. 审计中心。
3. 任务中心。
4. 权限模型。
## 14.4 第四阶段:试点与优化
输出:
1. 试点应用上线。
2. 指标统计。
3. 问题闭环与优化清单。
---
## 15. 已确认前提与实施约束
以下前提已确认,可作为后续研发与实施的固定输入:
1. 当前不直接对接真实软件 A,MVP 阶段需开发 demo 版软件 A;后续对接真实软件 A 时可能仍需开发改造。
2. 软件 A 的操作者透传和权限控制在 MVP 阶段由 demo 版能力承接,正式对接真实软件 A 时再评估透传和鉴权改造方案。
3. 本地 Agent 部署环境为 Windows 和 Linux 混合环境,需按用户现场环境适配。
4. 试点应用部署方式统一,这有利于先沉淀标准任务模型、标准验证模型和标准回滚策略。
5. 审批系统和身份系统理论上有标准接口,但当前阶段无法直接提供,MVP 阶段需开发 demo 版能力闭环。
6. 模型接入采用自定义 `base_url` 和 `api_key` 的方式,因此模型网关必须支持灵活配置,不预设单一模型厂商。
基于以上前提,对实施的直接影响如下:
1. MVP 应优先验证编排层、策略层、本地执行器和统一工具协议,不以真实外部系统对接完成度作为第一阶段阻塞项。
2. 软件 A、审批系统、身份系统均需采用"适配层 + demo 实现 + 后续真实替换"的分层设计。
3. 本地工具体系必须从一开始就考虑跨平台实现,避免后续从单平台重构。
4. 试点应用部署方式统一,可优先围绕单一部署范式建设模板化能力。
5. 模型网关需在配置、审计、安全过滤层面先抽象清楚,避免后续因模型源变化重构上层调用链路。
---
## 16. 结论
推荐将本项目建设为"受控执行型部署 Agent 平台",以软件 A 为执行底座,以 LangGraph 为编排核心,以本地 Agent 为边缘执行节点,以策略治理层保障高危动作安全。
从工程落地看,最关键的不是模型能力本身,而是以下四点:
1. 软件 A 能否提供稳定可调用接口。
2. 应用元数据是否完整。
3. 本地执行是否足够受控。
4. 审批、权限、审计是否能真正闭环。
如果以上四点落实,本项目具备较强的 MVP 落地可行性。

1037
智能化部署agent.md.txt Normal file
View File

File diff suppressed because it is too large Load Diff