agent_deply/docs/current_logic_flow.md

当前整体逻辑结构流程图

本文描述当前 PAM 部署 Agent 的主要模块、运行路径、LLM 审核、失败重试、显式回滚、热更新和断点续跑逻辑。

模块结构

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 理解和计划链路

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[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 --> N[ip_action 节点执行 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 执行]

action 后审核

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 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 开关。
• --analyze-actions 或 llm action-analysis on 只控制是否把详细审核结果写入 events。
• 只有 action 执行成功且审核允许继续时，才会写入 completed_global_steps 或 ip_states[ip].completed_steps。
• 如果审核建议停止或审核本身失败，当前 action 不会计入 completed，resume 会重试当前 action。
• 如果审核本身失败，也会生成“停止继续”的审核结果并暂停流程，避免黑盒继续执行。

进度查询 action 语义

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 继续。

失败、显式回滚和续跑

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]

用户中断与热更新

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 调用。