agent_deply/docs/current_logic_flow.md

# 当前整体逻辑结构流程图

本文描述当前 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/interrupt]
    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{是否存在 pending_confirmation}
    F -- 是 --> P[confirm interrupt 节点]
    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 --> H[prepare_ip 节点选择下一个 IP action]

    H --> I[resolve_target_ips 计算目标 IP]
    I --> J[ip_action 节点执行 upgrade-ip]
    J --> K[ip_action 节点执行 poll-upgrade-progress]
    K --> L[ip_action 节点执行 start-ip]
    L --> M[ip_action 节点执行 verify-ip]
    M --> N[ip_action 节点执行 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 执行完成] --> C[整理 ActionResult 和 AgentState 摘要]
    C --> D[敏感字段脱敏并截断长日志]
    D --> E{真实 LLM 是否配置}
    E -- 是 --> F[OpenAICompatibleLlmClient 输出结构化审核]
    E -- 否 --> G[RuleBasedLlmClient 本地规则审核]
    F --> H{should_continue}
    G --> H
    H -- true --> I[继续后续 action]
    H -- false --> J[暂停流程并写入 review_context]
    J --> K[chat/CLI 播报审核建议并等待 resume]
    F --> L{是否开启 analyze-actions}
    G --> L
    L -- 是 --> M[追加 ACTION_ANALYSIS 事件]
    L -- 否 --> N[不写详细事件，仅播报审核过程]
```

说明：

- 每个 action 完成后都会进入一次审核，不再依赖 `--analyze-actions` 开关。
- `--analyze-actions` 或 `llm action-analysis on` 只控制是否把详细审核结果写入 `events`。
- 如果审核本身失败，也会生成“停止继续”的审核结果并暂停流程，避免黑盒继续执行。

## 失败、人工确认和续跑

```mermaid
flowchart TD
    A[逐 IP action 执行] --> B{action 失败或业务校验失败}
    B -- 否 --> C[记录 completed_steps 并保存 checkpoint]
    C --> C1{LLM 审核是否允许继续}
    C1 -- 是 --> C2[继续后续 action]
    C1 -- 否 --> G[保存 checkpoint 并暂停]
    B -- 是 --> D[记录 ip_state 为 FAILED]
    D --> E[download-log 尽力下载日志]
    E --> F[设置 pending_confirmation=rollback-ip:IP]
    F --> G[保存 checkpoint 并暂停]

    G --> LG{是否来自 CLI/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]
```

## 用户中断与热更新

```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 会跳过。
- `ip_states[ip].status == SUCCESS`：成功 IP 会跳过。
- `ip_states[ip].completed_steps`：同一个 IP 已完成的 action 会跳过。
- `pending_confirmation`：存在待确认事项时，部署流程不继续执行，必须先 `approve` 或 `reject`。
- `paused` / `pause_reason`：流程可能因 LLM 审核阻断、用户中断、回滚失败等原因暂停；`resume` 会先清理暂停标记，再继续执行。
- `review_context`：保存最近一次暂停时的审核建议、失败原因、IP 和阶段，供 chat/CLI 输出给用户。
- CLI/chat 的运行调度由 `langgraph_runtime.py` 通过 action 级 LangGraph 节点执行；chat 和 CLI confirm 的确认点使用 LangGraph interrupt 和 InMemorySaver。
- 跨进程续跑仍读取业务 checkpoint JSON；LangGraph checkpointer 负责单进程图恢复和 interrupt resume。
- 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` 调用。