diff --git a/doc_scripts/PAM_AUTO_DEPLY_SKILL.md b/doc_scripts/PAM_AUTO_DEPLY_SKILL.md index f21ce11..9b5d5d6 100644 --- a/doc_scripts/PAM_AUTO_DEPLY_SKILL.md +++ b/doc_scripts/PAM_AUTO_DEPLY_SKILL.md @@ -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 [-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,17 +540,19 @@ Agent 读取时： 2. 输出参数确认单并等待确认。 3. 将参数写入 `config.txt`。 4. 初始化或更新检查点文件。 -5. 调用： +5. 初始化或指定统一的 `traceFilePath`。 +6. 调用： - `get-token` - `get-node-url` - `get-online-ips` -6. 输出 Node 地址、在线 IP 数量和 IP 列表。 -7. 不执行： - - `create-version` - - `upload-package` - - `publish-version` - - `create-download-task` - - `upgrade-ip` +7. 输出 Node 地址、在线 IP 数量和 IP 列表。 +8. 若需要间隔等待，也要向用户播报当前等待状态。 +9. 不执行： + - `create-version` + - `upload-package` + - `publish-version` + - `create-download-task` + - `upgrade-ip` ### 7.4 手动回滚分支 @@ -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`。 diff --git a/doc_scripts/PAM智能部署 Shell & Bat 脚本实现.md.md b/doc_scripts/PAM智能部署 Shell & Bat 脚本实现.md.md index 0f7e077..9812731 100644 --- a/doc_scripts/PAM智能部署 Shell & Bat 脚本实现.md.md +++ b/doc_scripts/PAM智能部署 Shell & Bat 脚本实现.md.md @@ -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 默认) diff --git a/doc_scripts/deploy.ps1 b/doc_scripts/deploy.ps1 index d44432f..4af07cf 100644 --- a/doc_scripts/deploy.ps1 +++ b/doc_scripts/deploy.ps1 @@ -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 diff --git a/doc_scripts/deploy.sh b/doc_scripts/deploy.sh index 721b680..e175a3e 100644 --- a/doc_scripts/deploy.sh +++ b/doc_scripts/deploy.sh @@ -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 [--ip ] [--hash-code ] [--stop-first] + ./deploy.sh [--config /path/to/config.txt] --action [--ip ] [--hash-code ] [--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}" - { - printf 'PAM API TRACE LOG\n' - printf 'Started: %s\n' "$(timestamp_now)" - printf 'ScriptDir: %s\n' "$SCRIPT_DIR" - printf '\n' - } > "$API_TRACE_FILE" + 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 diff --git a/doc_scripts/当前脚本情况总结.md b/doc_scripts/当前脚本情况总结.md index 41007d2..e572bf8 100644 --- a/doc_scripts/当前脚本情况总结.md +++ b/doc_scripts/当前脚本情况总结.md @@ -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` diff --git a/智能化部署agent-dify_langraph.md b/智能化部署agent-dify_langraph.md deleted file mode 100644 index a4a4493..0000000 --- a/智能化部署agent-dify_langraph.md +++ /dev/null @@ -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[编排与治理层
（两阶段实现不同）] - direction LR - B1[第一阶段: Dify 工作流编排] - B2[第二阶段: LangGraph 状态机编排] - end - - subgraph C[MCP 工具适配层
（两阶段共用）] - C1[软件 A MCP 服务器
封装部署、配置、监控 API] - C2[本地验证 MCP 服务器
封装进程、端口、日志检查工具] - C3[第三方接口 MCP 服务器
封装 CMDB、工单、通知等 API] - end - - subgraph D[执行与观测层] - D1[软件 A 引擎] - D2[本地执行沙箱
（容器/虚拟机/物理机）] - 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工具
deploy_package] - - Deploy --> Poll[轮询任务状态节点
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 到生产级系统的平滑演进。