auto_agent/智能化部署agent-技术架构设计说明书.md.txt

# 智能化部署 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 落地可行性。