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

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