d01c4d3d06
- 新增 MCP client 配置加载，支持 CLI/chat 通过配置文件接入 MCP - 完善 chat 交互命令，支持参数查看、事件查看、checkpoint 列表与加载 - 增加 LLM action 后诊断能力，支持真实 LLM 和本地规则兜底 - 将 chat 人工确认点接入 LangGraph interrupt/checkpointer - 更新 README、流程图、待办文档和打包说明 - 补充相关单元测试
164 lines
5.8 KiB
Markdown
164 lines
5.8 KiB
Markdown
# 当前整体逻辑结构流程图
|
||
|
||
本文描述当前 PAM 部署 Agent 的主要模块、运行路径、人工确认点和断点续跑逻辑。
|
||
|
||
## 模块结构
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
U[用户/上层系统] --> CLI[cli.py 命令行入口]
|
||
U --> CHAT[interactive.py 交互式 chat]
|
||
|
||
CLI --> PARAMS[params_loader.py 读取参数]
|
||
CHAT --> PARAMS
|
||
CLI --> LLMF[llm.factory 构造 LLM client]
|
||
CHAT --> LLMF
|
||
|
||
LLMF --> RULE[RuleBasedLlmClient 规则 fallback]
|
||
LLMF --> REAL[OpenAICompatibleLlmClient 真实 LLM]
|
||
REAL --> PROMPTS[llm.prompts 结构化提示词]
|
||
|
||
CLI --> AGENT[PamDeployAgent]
|
||
CHAT --> AGENT
|
||
CHAT --> LGR[langgraph_runtime.py chat interrupt 运行器]
|
||
PARAMS --> AGENT
|
||
RULE --> AGENT
|
||
REAL --> AGENT
|
||
|
||
LGR --> AGENT
|
||
LGR --> LGCHECK[LangGraph InMemorySaver checkpointer]
|
||
AGENT --> ROUTER[ActionRouter]
|
||
ROUTER --> SCRIPT[ScriptActionRunner]
|
||
ROUTER --> MCP[McpActionRunner]
|
||
ROUTER --> FAKE[FakeActionRunner]
|
||
|
||
SCRIPT --> DEPLOY[doc_scripts/deploy.sh 或 deploy.ps1]
|
||
MCP --> MCPFACTORY[mcp_factory.py 读取 --mcp-config]
|
||
MCPFACTORY --> MCPCLIENT[mcp_client.py: stdio/Session/Function adapter]
|
||
FAKE --> FIXTURE[测试 fixture 或默认 fake 返回值]
|
||
|
||
AGENT --> CHECKPOINT[checkpoint_store.py]
|
||
AGENT --> ACTIONLLM[action 后 LLM/规则诊断]
|
||
AGENT --> REPORT[render_report 部署报告]
|
||
```
|
||
|
||
## analyze/chat 理解和计划链路
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户输入自然语言] --> B[understand_request 识别意图]
|
||
B --> C[validate_intent_result 校验意图]
|
||
C --> D[extract_params 抽取参数和控制信息]
|
||
D --> E[选择执行策略]
|
||
E --> F[generate_plan 生成部署计划]
|
||
F --> G[validate_deploy_plan 校验 action 和危险文本]
|
||
G --> H[输出结构化理解/计划]
|
||
H --> I{用户是否执行}
|
||
I -- 否 --> X[仅预演或继续对话]
|
||
I -- 是 --> J[run / yes 后进入部署执行]
|
||
```
|
||
|
||
## 部署执行主流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[create_state 创建运行状态] --> B[normalize_params 合并默认参数并校验必填项]
|
||
B --> C[write_config 写脚本配置文件]
|
||
C --> D[build_action_backends 生成 action 路由表]
|
||
D --> E[run_deploy_flow]
|
||
|
||
E --> F{是否存在 pending_confirmation}
|
||
F -- 是 --> P[暂停并保存 checkpoint]
|
||
F -- 否 --> G[run_global_flow 全局阶段]
|
||
|
||
G --> G1[get-token]
|
||
G1 --> G2[create-version]
|
||
G2 --> G3[upload-package]
|
||
G3 --> G4[publish-version]
|
||
G4 --> G5[get-node-url]
|
||
G5 --> G6[get-online-ips]
|
||
G6 --> G7[create-download-task]
|
||
G7 --> G8[poll-download-progress]
|
||
G8 --> H[run_ip_flow 逐 IP 阶段]
|
||
|
||
H --> I[resolve_target_ips 计算目标 IP]
|
||
I --> J[upgrade-ip]
|
||
J --> K[poll-upgrade-progress]
|
||
K --> L[start-ip]
|
||
L --> M[verify-ip]
|
||
M --> N[download-log]
|
||
N --> O{还有下一个 IP}
|
||
O -- 是 --> J
|
||
O -- 否 --> R[render_report 输出报告]
|
||
```
|
||
|
||
## action 路由规则
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[action] --> B{execution_strategy}
|
||
B -- fake --> F[fake runner 执行所有 action]
|
||
B -- script_only --> S[脚本执行所有 action]
|
||
B -- hybrid_node_mcp --> C{action 类型}
|
||
C -- PAM_HOME action --> HS[脚本执行]
|
||
C -- PAM_NODE action --> NM[MCP tool 执行]
|
||
```
|
||
|
||
## action 后诊断
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[action 执行完成] --> B{是否开启 analyze-actions}
|
||
B -- 否 --> X[只记录 ACTION_DONE/ACTION_FAIL]
|
||
B -- 是 --> C[整理 ActionResult 和 AgentState 摘要]
|
||
C --> D[敏感字段脱敏并截断长日志]
|
||
D --> E{真实 LLM 是否配置}
|
||
E -- 是 --> F[OpenAICompatibleLlmClient 输出结构化诊断]
|
||
E -- 否 --> G[RuleBasedLlmClient 本地规则诊断]
|
||
F --> H[追加 ACTION_ANALYSIS 事件]
|
||
G --> H
|
||
H --> I[诊断只作建议，不自动继续/回滚/改参数]
|
||
```
|
||
|
||
## 失败、人工确认和续跑
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[逐 IP action 执行] --> B{action 失败或业务校验失败}
|
||
B -- 否 --> C[记录 completed_steps 并保存 checkpoint]
|
||
B -- 是 --> D[记录 ip_state 为 FAILED]
|
||
D --> E[download-log 尽力下载日志]
|
||
E --> F[设置 pending_confirmation=rollback-ip:IP]
|
||
F --> G[保存 checkpoint 并暂停]
|
||
|
||
G --> LG{是否来自 chat}
|
||
LG -- 是 --> LGI[LangGraph interrupt 输出确认请求]
|
||
LGI --> LGRS[approve/reject 通过 Command resume 恢复]
|
||
LGRS --> H{用户决定}
|
||
LG -- 否 --> H{用户决定}
|
||
H -- approve --> I[confirm_pending 执行 rollback-ip]
|
||
I --> J{rollback 是否成功}
|
||
J -- 是 --> K[清空 pending_confirmation]
|
||
J -- 否 --> L[保持 pending_confirmation，等待再次处理]
|
||
H -- reject --> M[标记 REJECTED_BY_OPERATOR 并清空 pending_confirmation]
|
||
|
||
K --> N[resume 续跑]
|
||
M --> N
|
||
N --> O[跳过已完成全局步骤、成功 IP 和单 IP 已完成 action]
|
||
```
|
||
|
||
## checkpoint 续跑语义
|
||
|
||
- `completed_global_steps`：全局阶段已经完成的 action 会跳过。
|
||
- `ip_states[ip].status == SUCCESS`：成功 IP 会跳过。
|
||
- `ip_states[ip].completed_steps`：同一个 IP 已完成的 action 会跳过。
|
||
- `pending_confirmation`：存在待确认事项时，部署流程不继续执行，必须先 `approve` 或 `reject`。
|
||
- chat 会话内的确认点由 `langgraph_runtime.py` 通过 LangGraph interrupt 和 InMemorySaver 托管；命令行一次性 `confirm/resume` 仍读取业务 checkpoint JSON。
|
||
- checkpoint 为了真实续跑会保存完整参数，请放在受控目录中。
|
||
|
||
## 真实外部能力接入点
|
||
|
||
- 真实 LLM：`llm.openai_compatible.OpenAICompatibleLlmClient`，通过 `PAM_LLM_BASE_URL`、`PAM_LLM_API_KEY`、`PAM_LLM_MODEL` 或 CLI 参数配置。
|
||
- 真实 MCP：CLI/chat 可通过 `--mcp-config` 加载 stdio MCP 配置，内部由 `mcp_factory.py` 构造 `McpActionRunner`。
|
||
- 真实脚本：PAM_HOME action 通过 `doc_scripts/deploy.sh` 或 `deploy.ps1` 调用。
|