4250a7b221
调整了 agent.py 和 LLM client 协议/实现。 现在只传当前 action 的结构化结果和必要诊断日志，避免历史运行态影响判断。 提示词和文档也已同步说明。 verify-ip 增加健康检查重试 默认 VERIFY_INTERVAL_SEC=10、VERIFY_MAX_ATTEMPTS=12，约 2 分钟。 verify-ip 未通过但未达到最大次数时，会播报进度、保存 checkpoint，并继续从当前 verify-ip 重试，不会进入 download-log。 参数已加入 config.txt.example、脚本配置读取、README、打包 README、Skill 文档和流程图。
253 lines
11 KiB
Markdown
253 lines
11 KiB
Markdown
# 当前整体逻辑结构流程图
|
||
|
||
本文描述当前 PAM 部署 Agent 的主要模块、运行路径、LLM 审核、失败重试、显式回滚、热更新和断点续跑逻辑。
|
||
|
||
## 模块结构
|
||
|
||
```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
|
||
CLI --> LGR[langgraph_runtime.py action 级 LangGraph runtime]
|
||
CHAT --> LGR
|
||
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/HTTP/SSE adapter + token auth]
|
||
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[LangGraph entry 节点]
|
||
|
||
E --> F{是否已暂停}
|
||
F -- 是 --> R[render_report 输出报告]
|
||
F -- 否 --> G[global_action 节点循环]
|
||
|
||
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 --> G9{LLM/规则判断下载完成}
|
||
G9 -- 未完成且正常 --> G8
|
||
G9 -- 已完成 --> H[prepare_ip 节点选择下一个 IP action]
|
||
G9 -- 异常或超时 --> R
|
||
|
||
H --> I[resolve_target_ips 计算目标 IP]
|
||
I --> J[ip_action 节点执行 upgrade-ip]
|
||
J --> K[ip_action 节点执行 poll-upgrade-progress 单次查询]
|
||
K --> K1{LLM/规则判断推送完成}
|
||
K1 -- 未完成且正常 --> K
|
||
K1 -- 已完成 --> L[ip_action 节点执行 start-ip]
|
||
K1 -- 异常或超时 --> R
|
||
L --> M[ip_action 节点执行 verify-ip]
|
||
M --> M1{健康检查通过或达到最大次数}
|
||
M1 -- 未通过且未超时 --> M
|
||
M1 -- 已通过 --> N[ip_action 节点执行 download-log]
|
||
M1 -- 仍未通过且超时 --> R
|
||
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 执行完成] --> C[整理当前 ActionResult]
|
||
C --> D[敏感字段脱敏；仅在异常时附带必要诊断日志]
|
||
D --> E{真实 LLM 是否配置}
|
||
E -- 是 --> F[OpenAICompatibleLlmClient 输出结构化审核]
|
||
E -- 否 --> G[RuleBasedLlmClient 本地规则审核]
|
||
F --> H{should_continue}
|
||
G --> H
|
||
H -- true --> I[标记 action completed 并继续后续 action]
|
||
H -- false --> J[不写 completed，暂停流程并写入 review_context]
|
||
J --> K[chat/CLI 播报审核建议并等待 resume]
|
||
F --> L{是否开启 analyze-actions}
|
||
G --> L
|
||
L -- 是 --> M[追加 ACTION_ANALYSIS 事件]
|
||
L -- 否 --> N[不写详细事件，仅播报审核过程]
|
||
```
|
||
|
||
说明：
|
||
|
||
- 每个 action 完成后都会进入一次审核，不再依赖 `--analyze-actions` 开关。
|
||
- 审核输入只包含当前 action 的结构化结果和必要诊断日志，不再传入完整运行态 `state_summary`，避免历史状态干扰大模型判断。
|
||
- `--analyze-actions` 或 `llm action-analysis on` 只控制是否把详细审核结果写入 `events`。
|
||
- 只有 action 执行成功且审核允许继续时，才会写入 `completed_global_steps` 或 `ip_states[ip].completed_steps`。
|
||
- 如果审核建议停止或审核本身失败，当前 action 不会计入 completed，`resume` 会重试当前 action。
|
||
- 如果审核本身失败，也会生成“停止继续”的审核结果并暂停流程，避免黑盒继续执行。
|
||
|
||
## verify-ip 健康检查重试
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[执行 verify-ip] --> B[LLM/规则审核单次返回]
|
||
B --> C{SUCCESS 是否为 true}
|
||
C -- 是 --> D[清理重试计数，标记 verify-ip completed]
|
||
C -- 否 --> E{是否达到 VERIFY_MAX_ATTEMPTS}
|
||
E -- 否 --> F[播报 ACTION_PROGRESS 并保存 checkpoint]
|
||
F --> G[等待 VERIFY_INTERVAL_SEC]
|
||
G --> A
|
||
E -- 是 --> H[暂停在 verify-ip，写入 review_context]
|
||
```
|
||
|
||
说明：
|
||
|
||
- `verify-ip` 用于应用启动后的健康检查，失败时默认每 `10` 秒重试一次，最多 `12` 次，约两分钟。
|
||
- 重试参数来自 `VERIFY_INTERVAL_SEC` 和 `VERIFY_MAX_ATTEMPTS`，支持通过 `config.txt`、chat `set` 或 `load params` 热更新。
|
||
- 未达到最大次数时不会把 `verify-ip` 写入 completed，也不会进入 `download-log`；中断或失败后 `resume` 仍从 `verify-ip` 继续。
|
||
|
||
## 进度查询 action 语义
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[poll-download-progress / poll-upgrade-progress] --> B[执行一次进度查询]
|
||
B --> C[ActionResult 返回结构化进度字段]
|
||
C --> D[LLM/规则审核 progress_complete]
|
||
D --> E{是否完成}
|
||
E -- 是 --> F[写入 completed，进入下一个 action]
|
||
E -- 否但正常 --> G[追加 ACTION_PROGRESS，保存 checkpoint]
|
||
G --> H[按 POLL_INTERVAL_SEC 等待]
|
||
H --> A
|
||
E -- 异常 --> I[暂停在当前 progress action]
|
||
G --> J{达到最大查询次数}
|
||
J -- 是 --> I
|
||
J -- 否 --> H
|
||
```
|
||
|
||
- `poll-download-progress` 和 `poll-upgrade-progress` 不再在脚本内部长时间循环；脚本/MCP/fake 每次只返回一次进度查询结果。
|
||
- LLM/规则通过 `progress_complete` 判断进度是否完成。未完成但正常时，`should_continue=true`、`progress_complete=false`，workflow 会保留当前 action 并再次查询。
|
||
- 查询间隔由 `POLL_INTERVAL_SEC` 控制，下载最大次数由 `DOWNLOAD_POLL_MAX_ATTEMPTS` 控制，单 IP 推送最大次数由 `UPGRADE_POLL_MAX_ATTEMPTS` 控制。
|
||
- 每次进度查询都会播报 `ACTION_PROGRESS` 并保存 checkpoint；中断或失败后 `resume` 会从同一个 progress action 继续。
|
||
|
||
## 失败、显式回滚和续跑
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[逐 IP action 执行] --> B{action 失败或业务校验失败}
|
||
B -- 否 --> C{LLM 审核是否允许继续}
|
||
C -- 是 --> C1[记录 completed_steps 并保存 checkpoint]
|
||
C1 --> C2[继续后续 action]
|
||
C -- 否 --> G[不记录 completed_steps，保存 checkpoint 并暂停]
|
||
B -- 是 --> D[记录 ip_state 为 FAILED]
|
||
D --> F[保存 failed_stage 和 failure_reason]
|
||
F --> G[保存 checkpoint 并暂停]
|
||
|
||
G --> H{用户决定}
|
||
H -- 修复后继续 --> I[resume 清理 paused]
|
||
I --> J[next_ip_action 返回 failed_stage]
|
||
J --> K[重试当前 action]
|
||
H -- 需要回滚 --> L[rollback IP 显式执行 rollback-ip]
|
||
L --> M{rollback 是否成功}
|
||
M -- 是 --> N[标记 ROLLBACK_DONE]
|
||
M -- 否 --> O[暂停为 rollback_failed]
|
||
N --> P[resume 续跑]
|
||
P --> Q[跳过已完成全局步骤、成功 IP、已回滚 IP 和单 IP 已完成 action]
|
||
```
|
||
|
||
## 用户中断与热更新
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[chat 执行中] --> B{用户是否按 Ctrl+C}
|
||
B -- 是 --> C[pause_state 标记 paused=user_interrupted]
|
||
C --> D[保存 checkpoint]
|
||
D --> E[chat 播报可 resume]
|
||
B -- 否 --> F[继续执行]
|
||
|
||
G[用户输入 set KEY=VALUE] --> H[normalize_params]
|
||
I[用户输入 load params <路径>] --> J[读取参数文件]
|
||
J --> H
|
||
H --> K[update_state_params]
|
||
K --> L[回写 state.params]
|
||
L --> M[回写运行中的 config.txt]
|
||
M --> N[保存 checkpoint]
|
||
```
|
||
|
||
## checkpoint 续跑语义
|
||
|
||
- `completed_global_steps`：全局阶段已经完成的 action 会跳过。
|
||
- `completed_global_steps` 只记录“执行成功且审核通过”的全局 action；审核阻断时不会提前写入，`resume` 会重试该 action。
|
||
- `ip_states[ip].status == SUCCESS`：成功 IP 会跳过。
|
||
- `ip_states[ip].rollback_status == ROLLBACK_DONE`：已显式回滚的失败 IP 会跳过，继续后续目标。
|
||
- `ip_states[ip].failed_stage`：失败 IP 未回滚时，`resume` 会从该 action 重试。
|
||
- `ip_states[ip].completed_steps`：同一个 IP 已完成且审核通过的 action 会跳过；审核阻断时不会提前写入，`resume` 会重试当前 action。
|
||
- `pending_confirmation`：仅保留为旧 checkpoint/旧 confirm 入口的兼容字段，新失败流程不再自动设置。
|
||
- `paused` / `pause_reason`：流程可能因 action 失败、LLM 审核阻断、用户中断、回滚失败等原因暂停；`resume` 会先清理暂停标记，再继续执行。
|
||
- `review_context`：保存最近一次暂停时的审核建议、失败原因、IP 和阶段，供 chat/CLI 输出给用户。
|
||
- CLI/chat 的运行调度由 `langgraph_runtime.py` 通过 action 级 LangGraph 节点执行；失败暂停和续跑依赖业务 checkpoint JSON。
|
||
- 跨进程续跑读取业务 checkpoint JSON；LangGraph checkpointer 负责单进程图状态保存。
|
||
- checkpoint 为了真实续跑会保存完整参数，请放在受控目录中。
|
||
|
||
## 真实外部能力接入点
|
||
|
||
- 真实 LLM：`llm.openai_compatible.OpenAICompatibleLlmClient`，通过 `PAM_LLM_BASE_URL`、`PAM_LLM_API_KEY`、`PAM_LLM_MODEL`、`PAM_LLM_ACTION_ANALYSIS_PROMPT_FILE` 或 CLI 参数配置。
|
||
- 真实 MCP：CLI/chat 可通过 `--mcp-config` 加载 streamable_http、sse 或 stdio MCP 配置，HTTP/SSE 支持独立 token 鉴权，并通过 `list_tools` 自动发现 server tools。
|
||
- 真实脚本：PAM_HOME action 通过 `doc_scripts/deploy.sh` 或 `deploy.ps1` 调用。
|