agent_deply/docs/current_logic_flow.md

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

本文描述当前 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
    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 执行完成] --> 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{是否来自 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]
```

## checkpoint 续跑语义

- `completed_global_steps`：全局阶段已经完成的 action 会跳过。
- `ip_states[ip].status == SUCCESS`：成功 IP 会跳过。
- `ip_states[ip].completed_steps`：同一个 IP 已完成的 action 会跳过。
- `pending_confirmation`：存在待确认事项时，部署流程不继续执行，必须先 `approve` 或 `reject`。
- 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` 或 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` 调用。