a11904b7c5
- 为 pam_deploy_graph 生产代码补充中文模块、类、函数/方法文档字符串 - 将原有英文说明和主要英文异常提示改为中文 - 新增当前整体逻辑结构流程图文档，覆盖模块结构、执行链路、action 路由、人工确认和 checkpoint 续跑 - 新增 Linux 自带运行环境打包脚本，使用 PyInstaller 生成解压即用目录和 tar.gz - 新增 Linux 打包说明，包含构建命令、运行方式、依赖说明和包大小评估 - 同步 README，补充流程图、打包方式、产物路径和大小预估 - 更新相关测试断言以匹配中文错误提示
138 lines
4.6 KiB
Markdown
138 lines
4.6 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
|
||
PARAMS --> AGENT
|
||
RULE --> AGENT
|
||
REAL --> AGENT
|
||
|
||
AGENT --> ROUTER[ActionRouter]
|
||
ROUTER --> SCRIPT[ScriptActionRunner]
|
||
ROUTER --> MCP[McpActionRunner]
|
||
ROUTER --> FAKE[FakeActionRunner]
|
||
|
||
SCRIPT --> DEPLOY[doc_scripts/deploy.sh 或 deploy.ps1]
|
||
MCP --> MCPCLIENT[mcp_client.py: Session/Function adapter]
|
||
FAKE --> FIXTURE[测试 fixture 或默认 fake 返回值]
|
||
|
||
AGENT --> CHECKPOINT[checkpoint_store.py]
|
||
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 执行]
|
||
```
|
||
|
||
## 失败、人工确认和续跑
|
||
|
||
```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 --> 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`。
|
||
- checkpoint 为了真实续跑会保存完整参数，请放在受控目录中。
|
||
|
||
## 真实外部能力接入点
|
||
|
||
- 真实 LLM：`llm.openai_compatible.OpenAICompatibleLlmClient`，通过 `PAM_LLM_BASE_URL`、`PAM_LLM_API_KEY`、`PAM_LLM_MODEL` 或 CLI 参数配置。
|
||
- 真实 MCP：外部建立 MCP session 后，用 `SessionMcpToolClient` 包装，再传给 `McpActionRunner`。
|
||
- 真实脚本：PAM_HOME action 通过 `doc_scripts/deploy.sh` 或 `deploy.ps1` 调用。
|