基础文档
This commit is contained in:
2521690
parent
440b779d95
commit
064f9adaab
368
智能化部署agent-dify_langraph.md
Normal file
368
智能化部署agent-dify_langraph.md
Normal file
@ -0,0 +1,368 @@
|
||||
|
||||
|
||||
# 智能化部署 Agent 方案建议（分阶段实施版）
|
||||
|
||||
## 1. 项目目标
|
||||
|
||||
目标建设一套面向软件部署与运维验证的智能化 Agent，支持云端与本地协同，通过自然语言对话完成：
|
||||
|
||||
1. 软件部署，优先支持 Java 应用。
|
||||
2. 部署后日志验证、进程/端口/接口/健康检查。
|
||||
3. 调用现有软件 A 完成部署包推送、配置推送、监控与告警。
|
||||
4. 调用第三方系统接口，完成联调验证、状态查询、数据校验。
|
||||
5. 具备安全控制、风险分级、审批确认、审计留痕能力。
|
||||
6. 尽快形成 MVP，逐步扩展至更多环境与应用类型。
|
||||
|
||||
一句话定位：
|
||||
|
||||
> **不是“让大模型自由操作机器”，而是“让大模型理解意图，通过 MCP 协议驱动受控工具完成标准化部署与验证”。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目定位与分阶段策略
|
||||
|
||||
### 2.1 整体定位
|
||||
|
||||
本项目定位为：
|
||||
|
||||
**软件 A 之上的智能编排与受控执行层，通过 MCP 协议统一集成各类工具，分两阶段完成能力演进。**
|
||||
|
||||
- **第一阶段（Demo 验证期）**：基于 Dify 平台快速搭建原型，验证自然语言交互、工具集成、部署验证的可行性，同时积累 Agent 应用的设计与运维经验。
|
||||
- **第二阶段（企业级建设期）**：基于 LangGraph 框架进行深度定制开发，构建可编程、强治理、高可控的生产级智能部署系统。
|
||||
|
||||
### 2.2 边界定义
|
||||
|
||||
Agent 负责：
|
||||
|
||||
- 理解用户意图，生成标准化任务。
|
||||
- 通过 MCP 工具调用软件 A、本地验证工具、第三方接口。
|
||||
- 汇总证据并输出结构化结论。
|
||||
- 执行高风险动作的审批与审计。
|
||||
|
||||
Agent 不负责：
|
||||
|
||||
- 自由执行任意 Shell 命令。
|
||||
- 无边界访问本地资源。
|
||||
- 绕过审批自动执行生产环境高危操作。
|
||||
- 以模型主观判断替代工具返回的结构化证据。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心需求拆解
|
||||
|
||||
与之前方案一致，核心需求包括：
|
||||
|
||||
- **对话式部署**：意图识别、参数提取、多轮澄清、执行前确认、结果总结。
|
||||
- **部署后验证**：日志关键字检查、进程/端口/HTTP 健康检查、第三方接口联调验证、监控指标核验。
|
||||
- **第三方工具与接口调用**：软件 A、CMDB、监控平台、工单系统、通知系统。
|
||||
- **云端与本地协同**：云端负责推理与编排，本地负责执行验证动作。
|
||||
- **安全治理**：身份认证、RBAC、高危动作审批、全链路审计、最小权限、凭据脱敏。
|
||||
|
||||
---
|
||||
|
||||
## 4. 总体架构（统一 MCP 工具层）
|
||||
|
||||
无论第一阶段还是第二阶段，工具层均采用 **MCP 协议** 进行标准化封装。架构上仅在编排层与治理层采用不同实现。
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph A[交互接入层]
|
||||
A1[Web 控制台]
|
||||
A2[企业 IM 机器人]
|
||||
A3[OpenAPI]
|
||||
end
|
||||
|
||||
subgraph B[编排与治理层<br>（两阶段实现不同）]
|
||||
direction LR
|
||||
B1[第一阶段: Dify 工作流编排]
|
||||
B2[第二阶段: LangGraph 状态机编排]
|
||||
end
|
||||
|
||||
subgraph C[MCP 工具适配层<br>（两阶段共用）]
|
||||
C1[软件 A MCP 服务器<br>封装部署、配置、监控 API]
|
||||
C2[本地验证 MCP 服务器<br>封装进程、端口、日志检查工具]
|
||||
C3[第三方接口 MCP 服务器<br>封装 CMDB、工单、通知等 API]
|
||||
end
|
||||
|
||||
subgraph D[执行与观测层]
|
||||
D1[软件 A 引擎]
|
||||
D2[本地执行沙箱<br>（容器/虚拟机/物理机）]
|
||||
D3[日志 / 指标 / 链路采集]
|
||||
end
|
||||
|
||||
A --> B
|
||||
B --> C
|
||||
C --> D
|
||||
```
|
||||
|
||||
**关键点**：
|
||||
|
||||
- MCP 工具层是两阶段**共用资产**，第一阶段开发的 MCP 服务器可直接复用于第二阶段。
|
||||
- 编排与治理层在第一阶段采用 Dify 快速搭建，在第二阶段用 LangGraph 重构以实现深度定制。
|
||||
|
||||
---
|
||||
|
||||
## 5. 第一阶段：基于 Dify 的 Demo 验证
|
||||
|
||||
### 5.1 目标
|
||||
|
||||
- 在 **2-4 周**内完成一个可演示的智能部署助手。
|
||||
- 验证自然语言交互、MCP 工具调用、部署与验证闭环。
|
||||
- 让团队熟悉 Agent 的交互模式、工具设计、安全边界。
|
||||
- 为第二阶段积累业务需求和工具资产。
|
||||
|
||||
### 5.2 技术选型
|
||||
|
||||
| 组件 | 选型 | 说明 |
|
||||
|:-------------- |:----------------------- |:-------------------------------- |
|
||||
| **Agent 编排平台** | Dify | 开箱即用的可视化工作流，支持对话型应用 |
|
||||
| **工具集成协议** | MCP | Dify 已原生支持 MCP 客户端，可接入外部 MCP 服务器 |
|
||||
| **LLM** | 云端 API（如 DeepSeek、通义千问） | 快速接入，无需自建模型 |
|
||||
| **部署方式** | Docker Compose 单机部署 | 低运维成本，适合 Demo 验证 |
|
||||
|
||||
### 5.3 Dify 中的工作流设计
|
||||
|
||||
以“部署 Java 应用到测试环境”为例，在 Dify 中可构建如下工作流：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start([用户输入]) --> Intent{意图识别节点}
|
||||
|
||||
Intent -->|部署意图| Extract[参数提取节点]
|
||||
Intent -->|其他意图| Other[其他处理分支]
|
||||
|
||||
Extract --> Check{参数是否完整？}
|
||||
Check -->|否| Clarify[反问澄清节点]
|
||||
Clarify --> Start
|
||||
|
||||
Check -->|是| Confirm[执行前确认节点]
|
||||
Confirm -->|用户取消| Cancel([流程终止])
|
||||
Confirm -->|用户确认| Deploy[调用软件A MCP工具<br>deploy_package]
|
||||
|
||||
Deploy --> Poll[轮询任务状态节点<br>get_deploy_status]
|
||||
Poll -->|进行中| Poll
|
||||
Poll -->|成功| Verify[调用本地验证 MCP 工具]
|
||||
Poll -->|失败| Fail[记录失败信息]
|
||||
|
||||
Verify --> V1[check_process]
|
||||
Verify --> V2[check_port]
|
||||
Verify --> V3[http_health_check]
|
||||
Verify --> V4[grep_log]
|
||||
|
||||
V1 & V2 & V3 & V4 --> Summary[LLM 汇总结果节点]
|
||||
Fail --> Summary
|
||||
|
||||
Summary --> Response([返回用户])
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Dify 工作流实现要点**：
|
||||
|
||||
- 使用 **知识库** 存储应用元数据（应用名、环境、部署方式等），辅助意图识别。
|
||||
- 通过 **HTTP 请求节点** 调用软件 A 的 API（若未封装 MCP）或直接配置 **MCP 工具节点**。
|
||||
- 利用 **条件分支** 实现参数校验与多轮对话。
|
||||
- 使用 **LLM 节点** 对工具返回的原始数据进行总结，生成用户友好的报告。
|
||||
|
||||
### 5.4 第一阶段交付物
|
||||
|
||||
1. 一个运行在测试环境的 Dify 实例。
|
||||
2. 2-3 个 MCP 服务器：
|
||||
- 软件 A MCP 服务器（至少包含 `deploy_package`、`get_deploy_status`）。
|
||||
- 本地验证 MCP 服务器（至少包含 `check_process`、`check_port`、`grep_log`）。
|
||||
3. 一个 Dify 工作流，实现“部署 → 验证 → 报告”闭环。
|
||||
4. 针对 1-2 个 Java 应用的试点验证报告。
|
||||
|
||||
### 5.5 第一阶段的局限性（需在第二阶段解决）
|
||||
|
||||
- **编排能力受限**：Dify 工作流适合线性流程，难以实现复杂的动态分支、循环、错误恢复。
|
||||
- **治理深度不足**：细粒度权限、全链路审计、自定义审批流需要额外开发或依赖商业版。
|
||||
- **状态管理较弱**：跨会话的上下文保持和长时间运行任务的跟踪能力有限。
|
||||
- **代码化程度低**：工作流配置难以进行版本控制和自动化测试。
|
||||
|
||||
---
|
||||
|
||||
## 6. 第二阶段：基于 LangGraph 的企业级建设
|
||||
|
||||
### 6.1 目标
|
||||
|
||||
- 在第一阶段验证的基础上，用 **LangGraph** 重构核心编排逻辑。
|
||||
- 构建一个**可编程、高可控、强审计**的生产级智能部署系统。
|
||||
- 实现深度的安全治理、复杂流程编排、完全的可观测性。
|
||||
|
||||
### 6.2 技术选型
|
||||
|
||||
| 组件 | 选型 | 说明 |
|
||||
|:-------------- |:------------------------- |:------------------------------- |
|
||||
| **Agent 编排框架** | LangGraph | 基于状态机的 Agent 编排，适合复杂、多步骤、可中断的流程 |
|
||||
| **工具集成协议** | MCP | 复用第一阶段开发的 MCP 服务器 |
|
||||
| **LLM** | 可切换云端 API 或私有化模型 | 根据数据安全要求灵活部署 |
|
||||
| **状态持久化** | PostgreSQL / Redis | LangGraph 内置支持 checkpoint 持久化 |
|
||||
| **可观测性** | LangSmith / OpenTelemetry | 全链路追踪与调试 |
|
||||
| **部署方式** | 容器化（Docker / K8s 可选） | 不强制 K8s，可独立部署于虚拟机 |
|
||||
|
||||
### 6.3 LangGraph 状态机设计
|
||||
|
||||
LangGraph 的核心是 **StateGraph**，可以将部署流程建模为一系列节点和边，并支持条件分支、循环、人工介入。
|
||||
|
||||
**简化的部署状态图**：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 理解意图
|
||||
理解意图 --> 参数校验
|
||||
参数校验 --> 澄清参数: 参数缺失
|
||||
澄清参数 --> 理解意图
|
||||
参数校验 --> 风险评估
|
||||
风险评估 --> 人工审批: 高风险动作
|
||||
人工审批 --> 执行部署: 审批通过
|
||||
人工审批 --> [*]: 审批拒绝
|
||||
风险评估 --> 执行部署: 低风险动作
|
||||
执行部署 --> 等待完成
|
||||
等待完成 --> 部署验证
|
||||
部署验证 --> 生成报告
|
||||
生成报告 --> [*]
|
||||
```
|
||||
|
||||
**LangGraph 实现关键点**：
|
||||
|
||||
- **Checkpointer**：将每个步骤的状态持久化，支持暂停、恢复、重试。
|
||||
- **Human-in-the-Loop**：通过 `interrupt` 机制在审批节点暂停，等待人工确认。
|
||||
- **工具节点**：封装对 MCP 服务器的调用，统一处理错误和重试。
|
||||
- **审计日志**：每个状态转换都可记录，形成完整的审计轨迹。
|
||||
|
||||
### 6.4 安全治理增强
|
||||
|
||||
在第二阶段，LangGraph 允许我们实现比 Dify 更深入的治理能力：
|
||||
|
||||
| 能力 | 实现方式 |
|
||||
|:---------- |:------------------------------------------ |
|
||||
| **细粒度权限** | 在工具调用前，通过中间件校验用户角色与操作权限 |
|
||||
| **动态审批流** | 根据环境、动作、应用敏感度动态决定是否需要审批及审批人 |
|
||||
| **全链路审计** | 利用 LangSmith 或自建 OpenTelemetry 收集每个节点的输入输出 |
|
||||
| **敏感信息脱敏** | 在进入 LLM 上下文前，对日志、配置等数据进行规则脱敏 |
|
||||
| **沙箱执行** | MCP 服务器以受限用户运行，仅开放白名单工具 |
|
||||
|
||||
### 6.5 第二阶段交付物
|
||||
|
||||
1. 基于 LangGraph 的智能部署 Agent 核心代码库。
|
||||
2. 可独立部署的容器镜像（不依赖 K8s）。
|
||||
3. 完整的权限与审批策略配置模块。
|
||||
4. 集成 LangSmith 或自建的可观测性仪表盘。
|
||||
5. 生产环境就绪的部署与运维文档。
|
||||
|
||||
---
|
||||
|
||||
## 7. 软件 A 与本地验证工具的 MCP 化
|
||||
|
||||
无论第一阶段还是第二阶段，工具层均采用 MCP 协议标准化封装，确保资产可复用。
|
||||
|
||||
### 7.1 软件 A MCP 服务器
|
||||
|
||||
封装软件 A 的核心能力为 MCP 工具，示例工具清单：
|
||||
|
||||
| 工具名 | 描述 |
|
||||
|:---------------------------- |:-------- |
|
||||
| `deploy_package` | 下发部署包 |
|
||||
| `push_config` | 推送配置文件 |
|
||||
| `start/stop/restart_service` | 服务生命周期管理 |
|
||||
| `get_deploy_status` | 查询任务状态 |
|
||||
| `get_app_logs` | 获取应用日志 |
|
||||
| `get_metrics` | 查询监控指标 |
|
||||
|
||||
### 7.2 本地验证 MCP 服务器
|
||||
|
||||
部署在目标主机或可访问目标主机的容器中，提供验证工具：
|
||||
|
||||
| 工具名 | 描述 |
|
||||
|:------------------- |:----------- |
|
||||
| `check_process` | 检查进程是否存在 |
|
||||
| `check_port` | 检查端口监听状态 |
|
||||
| `http_health_check` | HTTP 健康检查 |
|
||||
| `grep_log` | 在日志中搜索关键字 |
|
||||
| `tail_log_summary` | 获取最近日志摘要 |
|
||||
| `jvm_status` | 获取 JVM 运行信息 |
|
||||
|
||||
### 7.3 MCP 服务器实现与部署
|
||||
|
||||
- 使用 Python MCP SDK 快速开发。
|
||||
- 打包为 Docker 镜像，可在任意支持容器运行时的环境（Docker/containerd）执行。
|
||||
- 对于非容器化环境，也可作为普通 Python 进程运行。
|
||||
|
||||
---
|
||||
|
||||
## 8. 实施路线图（分阶段详细）
|
||||
|
||||
### 8.1 第一阶段：Demo 验证期（4-6 周）
|
||||
|
||||
| 周次 | 任务 | 产出 |
|
||||
|:------- |:-------------------------------- |:----------------- |
|
||||
| 第 1 周 | 部署 Dify 实例；梳理软件 A API 与试点应用元数据 | 可访问的 Dify 平台；接口清单 |
|
||||
| 第 2 周 | 开发软件 A MCP 服务器（最小集）和本地验证 MCP 服务器 | 两个可工作的 MCP 服务器 |
|
||||
| 第 3 周 | 在 Dify 中搭建部署工作流，进行对话测试 | 可演示的部署助手原型 |
|
||||
| 第 4 周 | 接入 1-2 个试点 Java 应用，收集反馈，优化工作流 | 试点报告；改进清单 |
|
||||
| 第 5-6 周 | 总结第一阶段经验，整理第二阶段需求 | 第二阶段设计文档 |
|
||||
|
||||
### 8.2 第二阶段：企业级建设期（8-12 周）
|
||||
|
||||
| 阶段 | 任务 | 产出 |
|
||||
|:---------- |:-------------------------------------- |:--------------- |
|
||||
| **架构设计** | 设计 LangGraph 状态机；定义审计、权限、审批接口 | 详细设计文档 |
|
||||
| **核心开发** | 实现 LangGraph Agent 核心逻辑；集成第一阶段 MCP 服务器 | 可运行的 Agent 核心代码 |
|
||||
| **治理模块** | 开发权限校验中间件、审批流模块、审计日志模块 | 治理组件库 |
|
||||
| **可观测性集成** | 接入 LangSmith 或 OpenTelemetry | 全链路追踪仪表盘 |
|
||||
| **容器化部署** | 编写 Dockerfile 与部署脚本；支持独立部署 | 容器镜像与部署文档 |
|
||||
| **试点迁移** | 将第一阶段试点应用迁移至 LangGraph 版本 | 生产试点报告 |
|
||||
| **生产扩展** | 逐步开放更多应用与生产环境，完善审批策略 | 生产级智能部署系统 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险分析与应对
|
||||
|
||||
| 风险 | 第一阶段应对 | 第二阶段应对 |
|
||||
|:----------- |:-------------------------- |:----------------------- |
|
||||
| **自然语言误解** | 在 Dify 工作流中增加参数回显确认节点 | LangGraph 状态机内置确认与中断机制 |
|
||||
| **模型幻觉** | LLM 仅用于总结，判断基于工具返回的结构化数据 | 同左，且工具返回增加校验逻辑 |
|
||||
| **工具调用失败** | Dify 工作流支持错误分支与重试 | LangGraph 支持可编程的错误恢复与降级 |
|
||||
| **敏感信息泄露** | MCP 服务器内部脱敏，Dify 日志配置脱敏 | 中间件层统一脱敏，审计日志过滤 |
|
||||
| **两阶段过渡成本** | 提前设计好 MCP 工具接口，确保第二阶段可直接复用 | 重构仅限于编排层，工具层无需改动 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 成功标准
|
||||
|
||||
### 第一阶段 MVP 成功标准
|
||||
|
||||
- Dify 工作流可稳定完成测试环境的部署与验证。
|
||||
- 至少 1 个 Java 应用可通过自然语言完成完整流程。
|
||||
- 团队对 Agent 能力边界、工具设计、安全要点形成共识。
|
||||
|
||||
### 第二阶段企业级成功标准
|
||||
|
||||
- LangGraph Agent 在生产环境稳定运行，支持至少 5 个应用。
|
||||
- 高危操作均有审批留痕，审计日志可追溯至每次工具调用。
|
||||
- 部署验证平均耗时较人工降低 50% 以上。
|
||||
- 系统具备水平扩展能力，可接入更多应用类型与第三方系统。
|
||||
|
||||
---
|
||||
|
||||
## 11. 开源项目参考
|
||||
|
||||
| 项目 | 阶段 | 用途 |
|
||||
|:------------------ |:-------- |:-------------- |
|
||||
| **Dify** | 第一阶段 | 可视化 Agent 编排平台 |
|
||||
| **LangGraph** | 第二阶段 | 代码化状态机编排框架 |
|
||||
| **MCP Python SDK** | 两阶段共用 | 开发 MCP 服务器 |
|
||||
| **OpenTelemetry** | 第二阶段 | 可观测性数据采集 |
|
||||
| **LangSmith** | 第二阶段（可选） | 调试与追踪 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 下一步行动建议
|
||||
|
||||
1. **立即启动**：部署 Dify 实例，搭建演示环境。
|
||||
2. **同步进行**：梳理软件 A 的 API 文档，选定第一个试点 Java 应用。
|
||||
3. **并行开发**：开始编写软件 A MCP 服务器的第一个版本（仅包含 `deploy_package` 和 `get_deploy_status`）。
|
||||
4. **设计评审**：基于第一阶段的经验，逐步细化第二阶段的 LangGraph 状态机设计。
|
||||
|
||||
这份文档明确了两个阶段的目标、技术选型、交付物和过渡策略，同时保持了 MCP 工具层的资产复用性，确保从 Demo 到生产级系统的平滑演进。
|
||||
Loading…
x
Reference in New Issue
Block a user