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

1、删除无效文档

Browse Source 
2、补充执行间隔
3、修正日志下载格式
This commit is contained in:
dark 2026-05-27 10:12:24 +08:00
parent 76e8f48c2e
commit 7b53d02e0e
6 changed files with 140 additions and 407 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
doc_scripts/PAM_AUTO_DEPLY_SKILL.md
View File

@ -81,6 +81,20 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
- `osTarget`: 目标脚本入口环境
- `checkpointPath`: 检查点文件路径
- `resumeFromCheckpoint`: 是否按已有检查点断点续试
- `traceFilePath`: 当前部署统一复用的接口跟踪日志文件路径
- `stepIntervalSec`: 全局 action 与 action 之间的执行间隔
- `firstPollDelaySec`: 创建下载任务后，到首次轮询下载进度前的等待间隔
- `perIpStepIntervalSec`: 同一台 IP 内部步骤之间的执行间隔
- `perIpIntervalSec`: 一台 IP 完成后到下一台 IP 开始前的间隔
- `failurePauseSec`: 某步骤失败后进入下一分支前的等待间隔
推荐默认值：
- `stepIntervalSec = 2`
- `firstPollDelaySec = 2`
- `perIpStepIntervalSec = 1`
- `perIpIntervalSec = 3`
- `failurePauseSec = 0`
### 3.3 参数确认要求
@ -154,6 +168,7 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
- 不要把整套业务参数直接拼接到命令行。
- `client_secret` 等敏感字段不得通过命令行透传。
- 如果用户明确要求“不落地配置文件”，则本 Skill 不执行真实部署，只说明限制和原因。
- `traceFilePath` 与间隔控制参数不写入 `config.txt`，由 Agent 在运行时持有并应用。
## 4. 主流程（硬约束）
@ -189,6 +204,20 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
18. 若出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作，转入回滚确认分支。
19. 输出最终报告。
主流程补充规则：
1. 一次完整部署中的所有 action 调用，应复用同一个 `traceFilePath`，禁止每个 action 各自新建独立 trace 文件。
2. 全局 action 与下一 action 之间，按 `stepIntervalSec` 等待。
3. `create-download-task` 成功后，到首次 `poll-download-progress` 前，按 `firstPollDelaySec` 等待。
4. 同一台 IP 内部：
- `upgrade-ip -> start-ip`
- `start-ip -> verify-ip`
- `verify-ip -> download-log`
之间按 `perIpStepIntervalSec` 等待。
5. 当前一台 IP 处理完成后，到下一台 IP 开始前，按 `perIpIntervalSec` 等待。
6. 若某步骤失败后需要进入提示、确认或分支流程，可按 `failurePauseSec` 等待。
7. 若某个间隔值为 `0`，表示该层级不等待，直接进入下一动作。
### 4.2 主流程中的强制确认点
以下节点必须等待用户确认，不能自动越过：
@ -196,6 +225,7 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
1. 参数确认单确认前。
2. 出现回滚条件时。
3. 用户指定 IP 与在线 IP 过滤结果不一致，且会影响部署范围时。
4. 用户显式要求修改默认间隔策略时。
### 4.3 面向用户的流程播报要求
@ -213,6 +243,7 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
- 失败阶段
- 建议是否回滚
- 是否需要 `stopFirst`
9. 若当前处于 action 间隔等待中，也必须告诉用户等待时长和下一步动作。
建议的阶段播报格式：
@ -222,6 +253,7 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
- 当前阶段: create-version
- 下一步: upload-package
- 当前结果: 成功
- 等待: 2 秒后继续
```
逐 IP 播报格式：
@ -232,6 +264,8 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
- 目标IP: 192.168.1.10
- 当前阶段: verify-ip
- 当前结果: 进行中
- 下一步: download-log
- 等待: 1 秒后继续
```
云下载进度播报格式：
@ -411,13 +445,14 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
5. 执行前必须先完成参数确认。
6. 每个关键步骤成功后都要刷新检查点。
7. 每个关键步骤前后都要向用户播报进度。
8. 脚本模式下统一输出流程日志：
8. Action 间隔等待也属于需要播报的执行状态，不能静默等待。
9. 脚本模式下统一输出流程日志：
- `[FLOW][START]`
- `[FLOW][DONE]`
- `[FLOW][FAIL]`
9. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
10. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
11. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。
10. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
11. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
12. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。
## 6. 脚本 action 能力
@ -452,7 +487,7 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action <ActionName> [-Ip
| `start-ip` | 启动指定 IP 应用 | `--ip` / `-Ip` |
| `stop-ip` | 停止指定 IP 应用 | `--ip` / `-Ip` |
| `verify-ip` | 校验指定 IP | `--ip` / `-Ip` |
| `download-log` | 下载指定 IP 日志 | `--ip` / `-Ip` |
| `download-log` | 下载指定 IP 日志压缩包，返回 zip 文件路径 | `--ip` / `-Ip` |
| `rollback-ip` | 执行指定 IP 回滚 | `--ip` / `-Ip`，可带 `--stop-first` / `-RollbackStopFirst` |
### 6.4 action 输出约定
@ -471,6 +506,7 @@ Agent 读取时：
- 优先解析 `key=value`
- 将 `[INFO]`、`[WARN]`、`[FLOW]` 视为辅助日志
- 若 action 失败，以退出码和错误日志为准
- 若返回 `TRACE_FILE=...`，后续 action 必须继续复用同一个路径
## 7. 分支流程与禁止事项
@ -491,9 +527,10 @@ Agent 读取时：
2. 输出参数确认单。
3. 说明预计会调用的 action 顺序。
4. 若存在旧检查点，可同时说明可从哪个断点恢复。
5. 不执行任何真实 `action`。
6. 不生成、不修改任何脚本文件。
7. 明确告诉用户当前只是预演流程，不会执行真实部署。
5. 如用户已指定间隔策略，也要一并展示。
6. 不执行任何真实 `action`。
7. 不生成、不修改任何脚本文件。
8. 明确告诉用户当前只是预演流程，不会执行真实部署。
### 7.3 仅查看 Node 与在线 IP 分支
@ -503,12 +540,14 @@ Agent 读取时：
2. 输出参数确认单并等待确认。
3. 将参数写入 `config.txt`。
4. 初始化或更新检查点文件。
5. 调用：
5. 初始化或指定统一的 `traceFilePath`。
6. 调用：
- `get-token`
- `get-node-url`
- `get-online-ips`
6. 输出 Node 地址、在线 IP 数量和 IP 列表。
7. 不执行：
7. 输出 Node 地址、在线 IP 数量和 IP 列表。
8. 若需要间隔等待，也要向用户播报当前等待状态。
9. 不执行：
- `create-version`
- `upload-package`
- `publish-version`
@ -540,6 +579,8 @@ Agent 读取时：
- 在已有检查点的情况下，未经判断就从头重跑全部步骤
- 在正式主流程中调用 `download-cloud-to-node`
- 在真实部署过程中长时间静默执行，不向用户播报阶段进度
- 在一轮部署中让不同 action 各自生成不同的 trace 文件
- 擅自忽略用户指定的间隔控制参数
## 8. 失败处理与回滚
@ -605,8 +646,10 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
- 在线工作站总数、成功数、失败数
- 每个 IP 的状态、失败阶段、失败原因
- 每个 IP 的回滚状态
- 日志路径
- 日志压缩包路径
- 检查点文件路径
- Trace 文件路径
- 当前采用的间隔控制参数
- 是否从断点续试
- 若有 trace，则给出 trace 路径
@ -624,12 +667,19 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
- 总工作站数: 3
- 成功: 2
- 失败: 1
- 间隔控制:
- stepIntervalSec: 2
- firstPollDelaySec: 2
- perIpStepIntervalSec: 1
- perIpIntervalSec: 3
- failurePauseSec: 0
- Trace: ./logs/api_trace_HET_PAM_Node_2.0.5.log
| IP | 状态 | 失败阶段 | 回滚状态 | 日志 |
| IP | 状态 | 失败阶段 | 回滚状态 | 日志压缩包 |
| --- | --- | --- | --- | --- |
| 192.168.1.10 | SUCCESS | - | - | logs/deploy_192.168.1.10.log |
| 192.168.1.11 | SUCCESS | - | - | logs/deploy_192.168.1.11.log |
| 192.168.1.12 | FAILED | VERIFY | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.log |
| 192.168.1.10 | SUCCESS | - | - | logs/deploy_192.168.1.10.zip |
| 192.168.1.11 | SUCCESS | - | - | logs/deploy_192.168.1.11.zip |
| 192.168.1.12 | FAILED | VERIFY | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.zip |
```
更完整的最终报告模板：
@ -691,3 +741,5 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
- `create-download-task`
- `poll-download-progress`
- 多 IP 循环处理
9. 间隔等待由 Agent 编排层负责控制，不要求脚本 action 自己管理 action 之间的等待。
10. 一轮部署中的所有 action，应复用同一个 `traceFilePath`。

3
doc_scripts/PAM智能部署 Shell & Bat 脚本实现.md.md
View File

@ -33,6 +33,7 @@
9. 正式部署脚本不会自动执行回滚；发现需要回滚时，只输出 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，由 Agent 先和用户确认，再调用手动回滚入口。
10. `POST /api/mcp/version/upgrade` 和 `POST /api/mcp/version/upgrade/start-stop` 的业务参数都直接放在 URL query 中，不再使用 body 表单；启停接口参数名使用 `runStart`；`download-cloud` 固定传 `timeOut=0` 创建任务。
11. 脚本同时提供主流程入口与 `action` 入口；建议 Agent 优先调用 `action` 入口，由 Skill 负责主流程编排。
12. 当前目录中的真实 `deploy.sh` 已去除 `jq` 依赖，统一使用 Bash 原生兼容 JSON 解析；若本文中的历史代码块仍出现 `jq`，以真实脚本文件为准。
## 0.1 当前实现边界
@ -762,8 +763,6 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action UpgradeIp -Ip 192
* `curl`: 通常预装
* `jq`: JSON 解析工具
2. **Windows**:
* `PowerShell`: 必须使用 PowerShell 5.0+ (Windows 10 默认)

10
doc_scripts/deploy.ps1
View File

@ -700,7 +700,7 @@ function Download-DeployLog {
$null = New-Item -ItemType Directory -Path $logsDir
}
$logFile = Join-Path $logsDir ("deploy_{0}.log" -f $Ip)
$logFile = Join-Path $logsDir ("deploy_{0}.zip" -f $Ip)
$errorFile = Join-Path $logsDir ("error_{0}.log" -f $Ip)
$query = Join-RequestPairs ([ordered]@{
applicationName = $Config.APP_NAME
@ -716,9 +716,13 @@ function Download-DeployLog {
} -OutFile $logFile)
if ((Get-Item -LiteralPath $logFile).Length -gt 0) {
Get-Content -LiteralPath $logFile -Tail 5 | Set-Content -LiteralPath "$logFile.summary"
@(
'Archive format: zip'
("Saved path: {0}" -f $logFile)
("Size: {0} bytes" -f (Get-Item -LiteralPath $logFile).Length)
) | Set-Content -LiteralPath "$logFile.summary"
} else {
'Log content empty or no data' | Set-Content -LiteralPath "$logFile.summary"
'Zip archive empty or no data' | Set-Content -LiteralPath "$logFile.summary"
}
} catch {
Get-ErrorBody $_ | Set-Content -LiteralPath $errorFile

54
doc_scripts/deploy.sh
View File

@ -33,7 +33,7 @@ usage() {
用法:
./deploy.sh [--config /path/to/config.txt]
./deploy.sh [--config /path/to/config.txt] --rollback-ip 192.168.1.10 [--rollback-stop-first]
./deploy.sh [--config /path/to/config.txt] --action <name> [--ip <target-ip>] [--hash-code <hash>] [--stop-first]
./deploy.sh [--config /path/to/config.txt] --action <name> [--ip <target-ip>] [--hash-code <hash>] [--stop-first] [--trace-file /path/to/api_trace.log]
配置项:
HOME_BASE_URL
@ -152,6 +152,21 @@ timestamp_now() {
ensure_trace_file() {
if [[ -n "$API_TRACE_FILE" ]]; then
local trace_dir
trace_dir="$(dirname "$API_TRACE_FILE")"
mkdir -p "$trace_dir"
if [[ ! -f "$API_TRACE_FILE" ]]; then
{
printf 'PAM API TRACE LOG\n'
printf 'Started: %s\n' "$(timestamp_now)"
printf 'ScriptDir: %s\n' "$SCRIPT_DIR"
printf '\n'
} > "$API_TRACE_FILE"
fi
if (( TRACE_ANNOUNCED == 0 )); then
log_info "接口跟踪日志: $API_TRACE_FILE"
TRACE_ANNOUNCED=1
fi
return 0
fi
@ -159,15 +174,17 @@ ensure_trace_file() {
local trace_name
mkdir -p "$trace_dir"
trace_name="api_trace_$(date '+%Y%m%d_%H%M%S')_$$.log"
trace_name="api_trace_$(safe_trace_name_part "$AIRPORT_CODE")_$(safe_trace_name_part "$APP_NAME")_$(safe_trace_name_part "$MODULE_NAME")_$(safe_trace_name_part "$VERSION_NUMBER").log"
API_TRACE_FILE="${trace_dir}/${trace_name}"
if [[ ! -f "$API_TRACE_FILE" ]]; then
{
printf 'PAM API TRACE LOG\n'
printf 'Started: %s\n' "$(timestamp_now)"
printf 'ScriptDir: %s\n' "$SCRIPT_DIR"
printf '\n'
} > "$API_TRACE_FILE"
fi
if (( TRACE_ANNOUNCED == 0 )); then
log_info "接口跟踪日志: $API_TRACE_FILE"
@ -378,6 +395,15 @@ sanitize_field() {
printf '%s' "$value"
}
safe_trace_name_part() {
local value="$1"
value="${value//\\/_}"
value="${value//\//_}"
value="${value// /_}"
value="${value//:/_}"
printf '%s' "$value"
}
require_ip_arg() {
local ip="$1"
[[ -n "$ip" ]] && return 0
@ -912,7 +938,7 @@ verify_ip() {
download_log() {
local ip="$1"
local logs_dir="${SCRIPT_DIR}/logs"
local log_file="${logs_dir}/deploy_${ip}.log"
local log_file="${logs_dir}/deploy_${ip}.zip"
local err_file="${logs_dir}/error_${ip}.log"
local request_id
local trace_url="${HOME_BASE_URL}/node-proxy/${AIRPORT_CODE}/api/mcp/version/upgrade/log-download?applicationName=${APP_NAME}&moduleName=${MODULE_NAME}&airportCode=${AIRPORT_CODE}&targetIp=${ip}&logName=${LOG_NAME}"
@ -933,9 +959,13 @@ download_log() {
-w '%{http_code}' > "${err_file}.code" 2>"$err_file"; then
http_code="$(cat "${err_file}.code" 2>/dev/null)"
if [[ -s "$log_file" ]]; then
tail -n 5 "$log_file" > "${log_file}.summary" 2>/dev/null || true
{
printf 'Archive format: zip\n'
printf 'Saved path: %s\n' "$log_file"
printf 'Size: %s bytes\n' "$(wc -c < "$log_file" | tr -d ' ')"
} > "${log_file}.summary"
else
printf 'Log content empty or no data\n' > "${log_file}.summary"
printf 'Zip archive empty or no data\n' > "${log_file}.summary"
fi
else
curl_exit=$?
@ -1027,11 +1057,13 @@ run_action() {
local ip="$3"
local hash_code="$4"
local stop_first="$5"
local trace_file="$6"
local response=""
local log_file=""
local rollback_result=""
ACTIVE_CONFIG_PATH="$config_path"
API_TRACE_FILE="$trace_file"
init_runtime
load_config "$config_path"
ensure_dependencies
@ -1164,6 +1196,10 @@ run_action() {
return 1
;;
esac
if [[ -n "$API_TRACE_FILE" ]]; then
result_line "TRACE_FILE" "$API_TRACE_FILE"
fi
}
add_result() {
@ -1284,6 +1320,7 @@ main() {
local action_ip=""
local action_hash_code=""
local action_stop_first="false"
local action_trace_file=""
local manual_rollback_ip=""
local manual_rollback_stop_first="false"
@ -1314,6 +1351,11 @@ main() {
action_hash_code="$2"
shift 2
;;
--trace-file)
[[ $# -lt 2 ]] && { log_error "--trace-file 缺少路径"; exit 1; }
action_trace_file="$2"
shift 2
;;
--stop-first)
action_stop_first="true"
manual_rollback_stop_first="true"
@ -1338,7 +1380,7 @@ main() {
ACTIVE_CONFIG_PATH="$config_path"
if [[ -n "$action" ]]; then
run_action "$config_path" "$action" "$action_ip" "$action_hash_code" "$action_stop_first"
run_action "$config_path" "$action" "$action_ip" "$action_hash_code" "$action_stop_first" "$action_trace_file"
return
fi

6
doc_scripts/当前脚本情况总结.md
View File

@ -52,6 +52,8 @@
- `/api/mcp/version/upgrade` 使用 query 参数，不再使用 body 表单。
- `/api/mcp/version/upgrade/start-stop` 使用 query 参数，不再使用 body 表单，且参数名使用 `runStart`。
- `download-cloud` 固定传 `timeOut=0`，仅用于创建下载任务；后续进度通过 `download-cloud/progress` 异步查询。
- Shell 侧 action 调用现在支持复用统一的 trace 文件，不再要求每次 action 各自生成单独的 trace 日志。
- `log-download` 下载结果按 zip 压缩包保存，不再按纯文本日志处理。
### 2.2 测试脚本
@ -286,7 +288,9 @@ bash ./test_deploy.sh --config ./config.txt --mode full --max-ips 1
日志特点：
- 位置：`logs/api_trace_YYYYMMDD_HHMMSS_PID.log`
- 位置：
- 默认会按机场/应用/模块/版本复用稳定文件名
- 也可由 Agent 显式传入统一 trace 文件路径
- 自动记录每个请求
- 自动生成请求编号，如 `REQ-0001`

368
智能化部署agent-dify_langraph.md
View File

@ -1,368 +0,0 @@
# 智能化部署 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 到生产级系统的平滑演进。