a11904b7c5
- 为 pam_deploy_graph 生产代码补充中文模块、类、函数/方法文档字符串 - 将原有英文说明和主要英文异常提示改为中文 - 新增当前整体逻辑结构流程图文档，覆盖模块结构、执行链路、action 路由、人工确认和 checkpoint 续跑 - 新增 Linux 自带运行环境打包脚本，使用 PyInstaller 生成解压即用目录和 tar.gz - 新增 Linux 打包说明，包含构建命令、运行方式、依赖说明和包大小评估 - 同步 README，补充流程图、打包方式、产物路径和大小预估 - 更新相关测试断言以匹配中文错误提示
4.6 KiB
4.6 KiB
当前整体逻辑结构流程图
本文描述当前 PAM 部署 Agent 的主要模块、运行路径、人工确认点和断点续跑逻辑。
模块结构
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 理解和计划链路
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 后进入部署执行]
部署执行主流程
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 路由规则
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 执行]
失败、人工确认和续跑
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调用。