# PAM 智能部署 LangGraph 重构设计文档 ## 1. 背景 当前 PAM 智能部署能力由三部分组成： - `PAM_AUTO_DEPLY_SKILL.md`：定义 Agent/Skill 的流程约束、参数确认、执行顺序、回滚规则、检查点和输出规范。 - PAM_NODE MCP 工具：面向 Node 在线执行场景，提供可由 Agent 调用的节点侧部署工具能力。 - `deploy.sh` / `deploy.ps1`：提供实际 API 调用能力，已经暴露 action 入口，可按步骤执行建版、上传、发布、节点发现、云下载、升级、启停、校验、日志下载和回滚。 当前接口能力边界： - PAM_HOME 接口不具备 MCP 能力，只能通过现有脚本 action 调用。 - PAM_NODE 接口支持 MCP，可以由 Agent 通过 MCP 工具调用。 现有模式的主要问题是：核心编排规则写在 Skill 文档中，依赖 Agent 按文本约束执行；HOME 脚本 action 与 NODE MCP 工具之间缺少统一动作路由；用户意图理解、参数抽取、缺参追问、异常解释等智能能力没有被显式建模；断点续跑、人工确认、回滚确认、进度事件和最终报告缺少一个可测试、可复用、可持久化的 Agent Runtime。 本设计将这套 Skill + PAM_NODE MCP + Shell/PowerShell 脚本组合重构为 LangGraph Agent。LangGraph 不只是顺序执行器，而是承载“大模型推理 + Skill 规则约束 + 混合工具路由 + 人工确认 + 状态持久化”的智能部署 Agent。 ## 2. 设计目标 1. 将 LangGraph 实现为 PAM 智能部署 Agent，而不是单纯脚本编排器。 2. 支持 `Skill + MCP`：Skill 提供规则、约束和流程策略，PAM_NODE MCP 提供节点侧在线工具能力。 3. 保留现有 `deploy.sh` / `deploy.ps1` action 能力，作为 PAM_HOME 固定执行后端，并作为全脚本离线模式后端。 4. 引入大模型参与意图理解、参数抽取、缺参追问、执行计划生成、失败解释和报告摘要。 5. 对高风险动作使用确定性图节点和人工确认兜底，禁止大模型绕过确认直接部署或回滚。 6. 支持 checkpoint 持久化和断点续跑。 7. 支持部署过程进度流式输出，避免长时间静默执行。 8. 将 PAM_NODE MCP 和 PAM_HOME 脚本 action 输出解析、错误分类、最终报告生成标准化。 9. 为后续服务化、可视化和 Python 原生 API client 迁移预留接口。 ## 3. 非目标 第一阶段不做以下事情： - 不自动生成、覆盖或修改 `deploy.sh`、`deploy.ps1`、`deploy.bat`、测试脚本。 - 不调用脚本主流程做真实部署，只调用 action 入口。 - 不把 `CLIENT_SECRET` 等敏感字段拼接到命令行。 - 不自动执行回滚。 - 不在正式主流程里使用 `download-cloud-to-node`。 - 不一次性重写所有 PAM HTTP API 调用。 - 不让大模型直接执行高风险工具调用；大模型只能生成建议、解释和结构化计划，真实动作由图节点在确认后执行。 ## 4. 总体架构 ```text 用户输入 / CLI / API / Chat | v LangGraph PAM Deploy Agent | |-- Skill Loader | |-- 加载 PAM_AUTO_DEPLY_SKILL.md | |-- 提取硬约束、参数规范、流程策略 | |-- LLM Reasoning Layer | |-- 意图理解 | |-- 参数抽取与缺参追问 | |-- 部署计划生成 | |-- 失败原因解释 | |-- 报告摘要生成 | |-- Deterministic Graph Layer | |-- 人工确认 interrupt | |-- 流程路由 | |-- checkpoint 更新 | |-- 回滚确认 interrupt | |-- 安全策略校验 | |-- Tool Runtime Layer |-- ActionRouter |-- MCPActionRunner |-- ScriptActionRunner |-- OutputParser |-- EventBus | v 工具后端 | |-- PAM_NODE MCP tools |-- deploy.sh --action ... |-- deploy.ps1 -Action ... | v PAM HOME / PAM NODE API ``` 核心原则是：大模型负责理解、规划、解释和生成候选动作；Skill 负责约束大模型和 Agent 的行为边界；LangGraph 确定性节点负责确认、状态和动作路由；PAM_HOME 动作固定走脚本 action；PAM_NODE 动作优先走 MCP，必要时可按用户确认降级到脚本 action。 ### 4.1 Agent 分层 PAM LangGraph Agent 分为四层： 1. `Skill Policy Layer` - 读取并解析 `PAM_AUTO_DEPLY_SKILL.md`。 - 形成系统提示词、工具白名单、确认点、禁止事项和流程约束。 - 对 LLM 输出做规则校验。 2. `LLM Reasoning Layer` - 从自然语言中识别部署意图。 - 抽取业务参数和控制参数。 - 判断是否缺参或存在歧义。 - 生成用户可读的部署计划、风险提示、失败解释和最终摘要。 3. `Deterministic Orchestration Layer` - 用 LangGraph StateGraph 固化主流程。 - 执行人工确认、条件路由、checkpoint、重试和断点续跑。 - 决定何时允许调用工具。 4. `Tool Runtime Layer` - 按 action 粒度路由 HOME/NODE 动作。 - PAM_HOME 脚本 action 后端。 - PAM_NODE MCP 在线工具后端。 - 全脚本离线后端。 - Fake runner 测试后端。 - 统一 action 结果、错误和事件格式。 ### 4.2 大模型介入点 大模型介入但不越权执行： | 阶段 | LLM 作用 | 确定性约束 | | --- | --- | --- | | 意图识别 | 判断是部署、预演、查询、回滚还是用法说明 | 输出必须符合枚举 `intent` | | 执行策略选择 | 结合用户表达判断使用混合执行还是全脚本执行 | HOME 固定脚本，NODE 可选 MCP 或脚本 | | 参数抽取 | 从自然语言、文件片段或对话上下文抽取参数 | 必填参数缺失时不能进入真实 action | | 缺参追问 | 生成简短追问 | 只问缺失或歧义字段 | | 部署计划 | 生成用户可读执行计划和风险提示 | action 顺序由图固定，不由 LLM 任意改 | | 失败解释 | 将 action 错误、HTTP 响应和日志摘要解释给用户 | 原始错误必须保留 | | 回滚建议 | 根据失败阶段建议 `stopFirst` | 回滚必须 interrupt 等用户确认 | | 最终报告 | 生成摘要和后续建议 | 统计数据来自 State，不由 LLM 编造 | 禁止大模型做的事情： - 直接调用真实部署工具。 - 跳过参数确认。 - 跳过 IP 范围确认。 - 自动执行回滚。 - 修改现有脚本文件。 - 编造 action 执行结果。 ### 4.3 Skill + MCP 混合执行方式 `Skill + MCP` 在本项目中的实际含义是“HOME 脚本 action + NODE MCP 工具”的混合执行，而不是全链路 MCP。 ```text PAM_AUTO_DEPLY_SKILL.md | v SkillPolicy | v LangGraph Agent | v ActionRouter | |-- PAM_HOME action -> ScriptActionRunner -> deploy.sh/deploy.ps1 | |-- PAM_NODE action -> MCPActionRunner -> PAM_NODE MCP tools | v PAM HOME / PAM NODE ``` 当用户明确要求“用 MCP”“直接在线执行”“不要生成脚本”，Agent 仍需要说明：PAM_HOME 当前没有 MCP 能力，HOME 阶段会通过现有脚本 action 执行；PAM_NODE 阶段使用 MCP 工具执行。 当 PAM_NODE MCP 不可用、用户明确要求脚本模式、或需要离线执行时，整轮部署可切换为全脚本执行，但必须在真实部署前向用户确认。 执行策略选择规则： 1. 默认策略：`hybrid_node_mcp`，即 HOME 走脚本 action，NODE 走 MCP。 2. 用户明确指定 MCP：使用 `hybrid_node_mcp`；如果 NODE MCP 不可用则停止并说明，不自动改为全脚本。 3. 用户明确指定脚本或离线：使用 `script_only`，所有 action 都走 `deploy.sh` / `deploy.ps1`。 4. 用户只说“帮我部署”：默认 `hybrid_node_mcp`；如果 NODE MCP 不可用，询问是否切换 `script_only`。 5. 用户只要用法或预演：不调用 MCP，也不调用脚本。 6. 高风险动作无论 MCP 还是脚本，都必须先通过参数确认。 标准 action 归属： | action | 接口归属 | 默认执行后端 | | --- | --- | --- | | `get-token` | PAM_HOME | 脚本 action | | `create-version` | PAM_HOME | 脚本 action | | `upload-package` | PAM_HOME | 脚本 action | | `publish-version` | PAM_HOME | 脚本 action | | `get-node-url` | PAM_HOME | 脚本 action | | `get-online-ips` | PAM_NODE | MCP | | `create-download-task` | PAM_NODE | MCP | | `poll-download-progress` | PAM_NODE | MCP | | `upgrade-ip` | PAM_NODE | MCP | | `poll-upgrade-progress` | PAM_NODE | MCP | | `start-ip` | PAM_NODE | MCP | | `stop-ip` | PAM_NODE | MCP | | `verify-ip` | PAM_NODE | MCP | | `download-log` | PAM_NODE | MCP | | `rollback-ip` | PAM_NODE | MCP，且必须人工确认 | ## 5. 推荐目录结构 ```text pam_deploy_graph/ __init__.py agent.py cli.py graph.py state.py constants.py skill_policy.py nodes/ __init__.py skill.py intent.py params.py planning.py confirmation.py backend.py tools.py scripts.py config_writer.py global_actions.py ip_actions.py rollback.py report.py llm/ __init__.py client.py prompts.py structured_outputs.py validators.py runtime/ __init__.py action_router.py tool_registry.py mcp_runner.py script_runner.py fake_runner.py output_parser.py checkpoint_store.py event_bus.py file_lock.py schemas/ __init__.py skill.py params.py plan.py action_result.py checkpoint.py report.py tests/ test_output_parser.py test_skill_policy.py test_llm_structured_outputs.py test_mcp_runner.py test_script_runner.py test_graph_routes.py test_checkpoint_resume.py fixtures/ action_outputs/ ``` 后续服务化时可新增： ```text pam_deploy_api/ app.py routes.py sse.py ``` ## 6. 关键状态模型 LangGraph 的 State 是整个 Agent 的事实来源。建议使用 `TypedDict` 或 Pydantic model。第一版如果需要开发速度，可用 `TypedDict`；如果需要更强校验，使用 Pydantic。 ```python class DeployState(TypedDict, total=False): run_id: str thread_id: str user_input: str messages: list[dict] skill: SkillPolicy skill_version: str skill_source_path: str llm_intent_result: LlmIntentResult llm_param_result: LlmParamResult llm_plan: LlmDeployPlan mode: Literal["MCP", "API脚本"] execution_strategy: Literal["hybrid_node_mcp", "script_only", "fake"] action_backends: dict[str, Literal["mcp", "script", "fake"]] intent: Literal[ "deploy", "show_usage", "preview", "query_node_ips", "rollback" ] show_usage_only: bool params: DeployParams control: ControlParams node_mcp_server_name: str node_mcp_tool_names: dict[str, str] script_entry: Literal["deploy.sh", "deploy.ps1"] script_base_dir: str config_path: str checkpoint_path: str trace_file_path: str confirmation: ConfirmationState completed_global_steps: list[str] token_acquired: bool hash_code: str node_url: str online_ips: list[str] target_ips: list[str] ip_states: dict[str, IpDeployState] last_success_step: str last_failed_step: str pending_confirmation: str errors: list[DeployError] events: list[DeployEvent] final_report: str ``` ### 6.1 SkillPolicy `SkillPolicy` 是从 `PAM_AUTO_DEPLY_SKILL.md` 加载出的规则对象，供 LLM prompt、图路由和工具执行共同使用。 ```python class SkillPolicy(TypedDict): name: str source_path: str allowed_modes: list[str] allowed_actions: list[str] forbidden_actions: list[str] required_confirmations: list[str] required_params: list[str] optional_params: dict[str, object] action_sequence: list[str] ip_action_sequence: list[str] rollback_rules: dict[str, object] output_requirements: dict[str, object] ``` 用途： - 作为 LLM system prompt 的事实来源。 - 作为确定性节点的规则输入。 - 作为工具白名单和执行顺序约束。 - 当 Skill 文档更新时，Agent 不需要散落修改多个节点。 ### 6.2 ActionRoute `ActionRoute` 描述每个标准 action 的接口归属和实际执行后端。 ```python class ActionRoute(TypedDict): action: str api_domain: Literal["PAM_HOME", "PAM_NODE"] backend: Literal["script", "mcp", "fake"] required_inputs: list[str] produces: list[str] ``` 默认路由： - `PAM_HOME` action 固定 `backend=script`。 - `PAM_NODE` action 在 `hybrid_node_mcp` 策略下 `backend=mcp`。 - `PAM_NODE` action 在 `script_only` 策略下 `backend=script`。 ### 6.3 DeployParams ```python class DeployParams(TypedDict): HOME_BASE_URL: str CLIENT_ID: str CLIENT_SECRET: str AIRPORT_CODE: str APP_NAME: str MODULE_NAME: str VERSION_NUMBER: str ZIP_FILE_PATH: str ACTION_TYPE: str TIMEOUT: int LOG_NAME: str ``` 默认值： - `ACTION_TYPE = "FULL"` - `TIMEOUT = 120` - `LOG_NAME = "app.log"` ### 6.4 ControlParams ```python class ControlParams(TypedDict): user_specified_ips: list[str] all_or_nothing: bool rollback_approved: bool os_target: Literal["windows", "linux", "macos", "git-bash"] resume_from_checkpoint: bool step_interval_sec: int first_poll_delay_sec: int per_ip_step_interval_sec: int per_ip_interval_sec: int failure_pause_sec: int ``` 默认值： - `step_interval_sec = 2` - `first_poll_delay_sec = 2` - `per_ip_step_interval_sec = 1` - `per_ip_interval_sec = 3` - `failure_pause_sec = 0` ### 6.5 LLM 结构化输出 LLM 节点必须输出结构化对象，不直接输出可执行命令。 ```python class LlmIntentResult(TypedDict): intent: str mode_preference: Literal["MCP", "API脚本", "未指定"] confidence: float reasons: list[str] needs_clarification: bool clarification_questions: list[str] class LlmParamResult(TypedDict): extracted_params: dict[str, object] extracted_control: dict[str, object] missing_required_params: list[str] ambiguous_fields: list[str] sensitive_fields_present: list[str] class LlmDeployPlan(TypedDict): summary: str risk_notes: list[str] planned_actions: list[str] requires_confirmation: bool ``` 结构化输出必须经过 `validators.py` 校验： - `intent` 必须在枚举内。 - `planned_actions` 必须是 Skill 允许的 action 子集。 - 不允许出现 shell 命令或 PowerShell 命令文本。 - 不允许包含 `CLIENT_SECRET` 明文。 ### 6.6 IpDeployState ```python class IpDeployState(TypedDict, total=False): ip: str status: Literal["PENDING", "RUNNING", "SUCCESS", "FAILED", "SKIPPED"] current_stage: str completed_steps: list[str] failed_stage: str failure_reason: str rollback_status: Literal[ "ROLLBACK_NOT_RUN", "PENDING_AGENT_CONFIRMATION", "ROLLBACK_SUCCESS", "ROLLBACK_FAILED", "ROLLBACK_REQUEST_FAILED", "ROLLBACK_VERIFY_FAILED", "ROLLBACK_SKIPPED" ] rollback_stop_first: bool log_file: str raw_outputs: dict[str, str] ``` ## 7. 工作流主图 ### 7.1 主流程 ```text START -> load_skill_policy -> llm_understand_request -> validate_llm_intent -> llm_extract_params -> validate_and_normalize_params -> llm_generate_plan -> apply_skill_guardrails -> route_by_intent route_by_intent: show_usage -> show_script_usage -> END preview -> render_preview -> END query_node_ips -> confirm_params -> select_execution_strategy -> build_action_routes -> prepare_tool_runtimes -> query_node_ips_flow -> END deploy -> confirm_params -> select_execution_strategy -> build_action_routes -> prepare_tool_runtimes -> deploy_flow rollback -> rollback_entry_flow deploy_flow: init_runtime_files -> maybe_resume_from_checkpoint -> get_token -> create_version -> upload_package -> publish_version -> get_node_url -> get_online_ips -> filter_target_ips -> confirm_target_scope_if_needed -> create_download_task -> wait_first_poll_delay -> poll_download_progress -> deploy_ip_loop -> aggregate_result -> final_report -> END ``` 说明： - `llm_understand_request`、`llm_extract_params`、`llm_generate_plan` 是智能层节点。 - `validate_llm_intent`、`validate_and_normalize_params`、`apply_skill_guardrails` 是确定性安全节点。 - `select_execution_strategy` 根据用户意图、Skill 规则和 PAM_NODE MCP 可用性选择 `hybrid_node_mcp`、`script_only` 或 `fake`。 - `build_action_routes` 生成每个 action 的实际后端；HOME action 固定脚本，NODE action 按策略走 MCP 或脚本。 - `prepare_tool_runtimes` 检查 PAM_NODE MCP 工具、脚本文件和运行时配置。 ### 7.2 单 IP 子流程 ```text deploy_ip: mark_ip_running -> upgrade_ip -> wait_per_ip_step_interval -> poll_upgrade_progress -> wait_per_ip_step_interval -> start_ip -> wait_per_ip_step_interval -> verify_ip -> wait_per_ip_step_interval -> download_log -> mark_ip_success on failure: record_ip_failure -> download_log_best_effort -> mark_pending_rollback -> rollback_confirm_interrupt -> route_rollback_decision ``` 第一版建议逐台顺序执行 IP，不做并发。原因是部署动作本身风险较高，当前 Skill 文档也要求逐台播报。后续如果需要并发，可以在单 IP 子图稳定后引入受控 fan-out，并保留最大并发数和失败策略。 ### 7.3 Agent ReAct 子图边界 本设计不采用开放式 ReAct 循环执行真实部署工具。原因是 PAM 部署包含建版、发布、升级和回滚等高风险动作，不能让模型自由选择下一步真实工具。 允许使用受限 ReAct 子图的场景： - 缺参追问。 - 用户意图澄清。 - 失败原因解释。 - 日志摘要。 - 最终报告文字润色。 不允许使用开放式 ReAct 的场景： - `create-version` - `upload-package` - `publish-version` - `create-download-task` - `upgrade-ip` - `rollback-ip` 这些动作必须由确定性图节点按照 Skill 固定顺序调用。 ## 8. 节点设计 ### 8.1 load_skill_policy 职责： - 读取 `PAM_AUTO_DEPLY_SKILL.md`。 - 解析 Skill frontmatter 和正文中的关键规则。 - 生成 `SkillPolicy`。 - 将 Skill 规则注入 LLM system prompt 和后续图节点。 失败策略： - Skill 文件缺失或解析失败时，Agent 不进入真实部署。 ### 8.2 llm_understand_request 职责： - 调用大模型理解用户自然语言。 - 输出结构化 `LlmIntentResult`。 - 判断用户是否要求 MCP、脚本、预演、查询或回滚。 约束： - LLM 只输出结构化意图，不输出命令。 - 置信度低或存在歧义时，进入澄清分支。 ### 8.3 validate_llm_intent 职责： - 校验 LLM 输出是否符合枚举。 - 按 Skill 规则修正或拒绝不合法意图。 - 例如用户要求“生成脚本”时，转入 `show_usage` 或限制说明分支。 ### 8.4 llm_extract_params 职责： - 从用户输入、对话上下文、上传的参数文件或历史 checkpoint 中抽取业务参数。 - 识别缺失字段和歧义字段。 - 标记 `CLIENT_ID`、`CLIENT_SECRET` 等敏感字段是否已提供。 约束： - 不把 `CLIENT_SECRET` 明文写入普通消息。 - 不猜测必填参数。 ### 8.5 validate_and_normalize_params 职责： - 将 LLM 抽取结果映射为 `DeployParams` 和 `ControlParams`。 - 补齐默认值。 - 校验必填参数。 - 对机场码、版本号、IP 列表、路径格式做基础校验。 硬约束： - 必填参数缺失时，不进入真实 action。 - 参数有歧义时，应中断并要求补充。 ### 8.6 llm_generate_plan 职责： - 基于 Skill 和已归一化参数生成用户可读部署计划。 - 说明执行策略：默认是 HOME 脚本 action + NODE MCP 的混合执行。 - 如果用户要求 MCP，明确提示 HOME 阶段仍会通过脚本 action 执行，因为 PAM_HOME 不具备 MCP 能力。 - 说明高风险动作和确认点。 约束： - 计划中的 action 顺序必须与 Skill 固定流程一致。 - 计划只用于展示和确认，不作为真实执行序列的唯一来源。 ### 8.7 apply_skill_guardrails 职责： - 校验 LLM 输出是否违反 Skill 禁止事项。 - 校验是否试图调用脚本主流程。 - 校验是否试图自动回滚。 - 校验是否试图修改脚本。 失败策略： - 发现违规时终止真实执行并输出限制说明。 ### 8.8 parse_intent 职责： - 判断用户要真实部署、查看用法、预演计划、查询 Node/IP，还是手动回滚。 - 判断用户是否明确要求 `MCP` 或 `API脚本`。 - 如果用户要求生成或修改脚本，直接进入受限说明分支。 输出： - `intent` - `mode` - `show_usage_only` 说明： - 该节点保留为确定性兜底逻辑，用于 LLM 不可用或 structured output 失败时的基础规则识别。 ### 8.9 normalize_params 职责： - 从用户输入、环境变量、配置文件或外部调用参数中收集业务参数。 - 补齐默认值。 - 标记缺失参数。 - 敏感字段不进入普通播报内容。 硬约束： - 必填参数缺失时，不进入真实 action。 - 参数有歧义时，应中断并要求补充。 说明： - 该节点保留为确定性兜底逻辑。 ### 8.10 confirm_params 职责： - 渲染归一化参数确认单。 - 使用 LangGraph interrupt 等待用户确认。 - 未确认前不得调用任何真实 action。 确认单不展示 `CLIENT_SECRET` 明文，只展示“已提供/未提供”。 ### 8.11 select_execution_strategy 职责： - 根据用户偏好、PAM_NODE MCP 可用性、Skill 规则和运行环境选择执行策略。 - 输出 `execution_strategy = hybrid_node_mcp | script_only | fake`。 选择规则： 1. 用户明确指定 MCP：选择 `hybrid_node_mcp`；PAM_NODE MCP 不可用则停止。 2. 用户明确指定脚本或离线：选择 `script_only`。 3. 用户未指定且 PAM_NODE MCP 可用：选择 `hybrid_node_mcp`。 4. 用户未指定且 PAM_NODE MCP 不可用：询问是否切换 `script_only`。 5. 测试环境可显式选择 fake runner。 ### 8.12 build_action_routes 职责： - 根据 `execution_strategy` 生成 `action_backends`。 - HOME action 固定为 `script`。 - NODE action 在 `hybrid_node_mcp` 下为 `mcp`。 - NODE action 在 `script_only` 下为 `script`。 - fake 策略下所有 action 为 `fake`。 输出示例： ```json { "get-token": "script", "create-version": "script", "upload-package": "script", "publish-version": "script", "get-node-url": "script", "get-online-ips": "mcp", "create-download-task": "mcp", "poll-download-progress": "mcp", "upgrade-ip": "mcp", "poll-upgrade-progress": "mcp", "start-ip": "mcp", "verify-ip": "mcp", "download-log": "mcp", "rollback-ip": "mcp" } ``` ### 8.13 prepare_tool_runtimes 职责： - 混合执行下：检查脚本文件、选择脚本入口、写入 HOME 脚本配置，同时检查 PAM_NODE MCP server 和工具映射。 - 全脚本执行下：检查脚本文件、选择脚本入口、写入完整脚本配置。 - fake 模式下：加载 fixture 输出。 ### 8.14 check_scripts 职责： - 检查当前目录下是否存在 `deploy.sh` / `deploy.ps1`。 - 检查目标脚本是否可读。 - 不自动补写脚本。 失败策略： - 缺少脚本时终止流程并输出原因。 ### 8.15 select_script_entry 职责： - Windows 默认选择 `deploy.ps1`。 - Linux / macOS / Git Bash 默认选择 `deploy.sh`。 - `deploy.bat` 只作为兼容包装入口，不作为 LangGraph action runner 默认入口。 ### 8.16 write_config 职责： - 将确认后的业务参数写入 `config.txt` 或本次运行专属配置文件。 - 命令行只传 action 级参数，不传 `CLIENT_SECRET`。 建议： - 默认写入 `./runtime/config_.txt`，避免覆盖人工维护的 `config.txt`。 - 如果必须兼容脚本默认路径，可由 CLI 参数指定 `--config-path ./config.txt`。 说明： - 混合执行下仍需要写配置文件，因为 PAM_HOME action 固定通过脚本执行。 - 全脚本执行下写完整配置文件。 - PAM_NODE MCP 工具不从 `config.txt` 读参数，由 Agent 通过 MCP tool input 传入必要字段。 - `CLIENT_SECRET` 只允许写入受控配置文件或安全凭证通道，不进入命令行和普通日志。 ### 8.17 init_runtime_files 职责： - 创建 `logs/` 或 `runtime/` 目录。 - 生成本次运行的 `checkpoint_path`。 - 生成本次运行的 `trace_file_path`。 - 写入初始业务 checkpoint。 命名建议： ```text logs/deploy_checkpoint____.json logs/api_trace_____.log ``` ### 8.18 action 节点 每个 action 节点只做四件事： 1. 播报即将执行的阶段。 2. 通过 `ActionRouter` 按 action 归属调用 MCP 或脚本 action。 3. 解析 key=value 输出并更新 State。 4. 更新 checkpoint 和进度事件。 全局 action 节点： - `get_token` - `create_version` - `upload_package` - `publish_version` - `get_node_url` - `get_online_ips` - `create_download_task` - `poll_download_progress` 单 IP action 节点： - `upgrade_ip` - `poll_upgrade_progress` - `start_ip` - `verify_ip` - `download_log` - `rollback_ip` ### 8.19 llm_explain_failure 职责： - 在全局失败或单 IP 失败后，基于 `ActionResult`、原始输出、阶段名和 Skill 规则生成用户可读解释。 - 给出下一步建议，例如检查凭证、包路径、Node 连通性、在线 IP 或是否回滚。 约束： - 不能替换原始错误。 - 不能承诺未发生的恢复动作。 - 回滚建议必须进入确认节点。 ### 8.20 final_report 职责： - 汇总模式、脚本入口、机场、应用、模块、版本。 - 汇总在线 IP 数、目标 IP 数、成功数、失败数。 - 汇总每台 IP 的状态、失败阶段、失败原因、回滚状态、日志路径。 - 输出 checkpoint 和 trace 路径。 - 输出是否断点续跑和当前间隔控制参数。 - 调用 LLM 生成简短摘要，但所有统计值必须来自 State。 ## 9. Tool Runtime 设计 ### 9.1 统一 ToolRunner 接口 ```python class ToolRunner: def run( self, action: str, *, params: DeployParams, config_path: str | None = None, script_entry: str | None = None, ip: str | None = None, hash_code: str | None = None, stop_first: bool = False, trace_file_path: str | None = None, timeout_sec: int | None = None, ) -> ActionResult: ... ``` `ActionRouter` 根据 `state.action_backends[action]` 按 action 粒度分发到具体 runner： ```python class ActionRouter: def run_action(self, state: DeployState, action: str, **kwargs) -> ActionResult: backend = state["action_backends"][action] if backend == "mcp": return self.node_mcp_runner.run(action, params=state["params"], **kwargs) if backend == "script": return self.script_runner.run( action, params=state["params"], config_path=state["config_path"], script_entry=state["script_entry"], **kwargs, ) return self.fake_runner.run(action, params=state["params"], **kwargs) ``` ### 9.2 MCPActionRunner MCPActionRunner 只负责 PAM_NODE action。PAM_HOME 当前没有 MCP 能力，HOME action 不进入 MCPActionRunner。 PAM_NODE MCP 工具映射： | 标准 action | MCP tool 建议名 | 说明 | | --- | --- | --- | | `get-online-ips` | `pam_get_online_ips` | 获取在线工作站 | | `create-download-task` | `pam_create_download_task` | 创建云下载任务 | | `poll-download-progress` | `pam_poll_download_progress` | 轮询云下载进度 | | `upgrade-ip` | `pam_upgrade_ip` | 创建单 IP 升级任务 | | `poll-upgrade-progress` | `pam_poll_upgrade_progress` | 轮询单 IP 升级进度 | | `start-ip` | `pam_start_ip` | 启动应用 | | `stop-ip` | `pam_stop_ip` | 停止应用 | | `verify-ip` | `pam_verify_ip` | 校验应用 | | `download-log` | `pam_download_log` | 下载日志 | | `rollback-ip` | `pam_rollback_ip` | 手动回滚 | MCP runner 职责： - 发现 PAM_NODE MCP server 和工具列表。 - 将标准 action 映射为 MCP tool。 - 将 `DeployParams` 转为 tool input。 - 读取 `node_url`、`airportCode`、`applicationName`、`moduleName`、`versionNumber`、目标 IP 等运行时状态。 - 调用工具并统一转为 `ActionResult`。 - 保存工具原始返回。 - 对敏感字段做脱敏。 MCP runner 约束： - 只能调用 Skill 白名单中的 PAM_NODE 工具。 - 不能调用 PAM_HOME action。 - `rollback-ip` 必须在回滚确认后调用。 - 工具返回结果不得由 LLM 改写后写入 State。 - PAM_NODE MCP 不可用时，不能静默切换脚本后端，除非用户确认 `script_only`。 ### 9.3 ScriptActionRunner ScriptActionRunner 有两类职责： 1. 在 `hybrid_node_mcp` 策略下，固定执行 PAM_HOME action： - `get-token` - `create-version` - `upload-package` - `publish-version` - `get-node-url` 2. 在 `script_only` 策略下，执行全部 action，包括 PAM_NODE action。 脚本后端仍然只允许调用 action 入口，不允许调用脚本主流程。 ### 9.4 Shell 命令 ```bash bash ./deploy.sh \ --config ./config.txt \ --action upload-package \ --trace-file ./logs/api_trace_xxx.log ``` 带 IP： ```bash bash ./deploy.sh \ --config ./config.txt \ --action upgrade-ip \ --ip 192.168.1.10 \ --trace-file ./logs/api_trace_xxx.log ``` 发布版本： ```bash bash ./deploy.sh \ --config ./config.txt \ --action publish-version \ --hash-code 43858bcf \ --trace-file ./logs/api_trace_xxx.log ``` 回滚： ```bash bash ./deploy.sh \ --config ./config.txt \ --action rollback-ip \ --ip 192.168.1.10 \ --stop-first \ --trace-file ./logs/api_trace_xxx.log ``` ### 9.5 PowerShell 命令 ```powershell powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action upload-package ``` 带 IP： ```powershell powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action upgrade-ip -Ip 192.168.1.10 ``` 发布版本： ```powershell powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action publish-version -HashCode 43858bcf ``` 回滚： ```powershell powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 192.168.1.10 -RollbackStopFirst ``` ### 9.6 当前能力差异 Shell 侧当前支持 `--trace-file`，可以由 LangGraph 在一轮部署中传入同一个 trace 文件。 PowerShell 侧当前 `deploy.ps1` action 参数未暴露 `-TraceFile`。第一阶段处理策略： - LangGraph 统一保存每个 PowerShell action 的 stdout/stderr 到工作流 trace。 - 业务 checkpoint 中仍记录同一个 `trace_file_path`。 - 如果必须做到 PowerShell 脚本内部 HTTP trace 也复用同一个文件，需要后续单独评估是否修改 `deploy.ps1`，不纳入第一阶段。 ### 9.7 FakeRunner Fake runner 用于图路由、LLM 结构化输出、checkpoint 和报告生成测试。 职责： - 根据 action 返回 fixture。 - 模拟全局失败、单 IP 失败、回滚确认和日志下载失败。 - 不访问真实 PAM 环境。 ## 10. Action 输出解析 `OutputParser` 负责把脚本 stdout 和 MCP tool result 都归一化为 `ActionResult`。 脚本后端优先解析 `key=value` 行。 输入示例： ```text ACTION=upload-package HASH_CODE=43858bcf TRACE_FILE=./logs/api_trace_xxx.log ``` 解析结果： ```python { "ACTION": "upload-package", "HASH_CODE": "43858bcf", "TRACE_FILE": "./logs/api_trace_xxx.log" } ``` 解析规则： 1. 只将形如 `KEY=VALUE` 的行作为结构化结果。 2. `[INFO]`、`[WARN]`、`[FLOW]` 作为日志，不参与主结果判断。 3. 同名 key 多次出现时： - `IP` 保留为列表。 - 其他字段默认以后出现的值覆盖先出现的值。 4. 非零退出码视为 action 失败。 5. stderr、非结构化 stdout 和原始输出必须保存在 `ActionResult.raw_output`。 6. 出现 `PENDING_AGENT_CONFIRMATION(...)` 时，必须转入人工确认分支。 MCP 后端解析规则： 1. MCP tool 如果返回 JSON object，直接映射到 `values`。 2. MCP tool 如果返回文本，先尝试按 JSON 解析，再尝试按 `key=value` 解析。 3. MCP 原始返回必须保存在 `raw_output`。 4. MCP tool error 统一转换为 `ok=false` 和 `error_summary`。 5. 结果字段名归一化为脚本 action 同款字段，例如 `hashCode` 归一为 `HASH_CODE`，`nodeUrl` 归一为 `NODE_URL`。 ### 10.1 ActionResult ```python class ActionResult(TypedDict): action: str backend: Literal["mcp", "script", "fake"] tool_name: str exit_code: int ok: bool values: dict[str, str | list[str]] stdout: str stderr: str raw_output: str error_summary: str ``` ## 11. Checkpoint 设计 需要两层 checkpoint： 1. LangGraph checkpointer：保存图执行位置和完整 State，用于 `interrupt` 恢复和工作流续跑。 2. 业务 checkpoint JSON：兼容现有 Skill 文档，方便人工排查，也方便脱离 LangGraph 查看部署状态。 ### 11.1 业务 checkpoint 文件 路径： ```text ./logs/deploy_checkpoint____.json ``` 内容： ```json { "runId": "20260529_103000_abcd", "mode": "MCP", "executionStrategy": "hybrid_node_mcp", "actionBackends": { "get-token": "script", "create-version": "script", "upload-package": "script", "publish-version": "script", "get-node-url": "script", "get-online-ips": "mcp", "create-download-task": "mcp", "poll-download-progress": "mcp", "upgrade-ip": "mcp", "poll-upgrade-progress": "mcp", "start-ip": "mcp", "verify-ip": "mcp", "download-log": "mcp", "rollback-ip": "mcp" }, "skillVersion": "pam-auto-deply", "scriptEntry": "deploy.ps1", "nodeMcpServerName": "pam-node", "checkpointPath": "./logs/deploy_checkpoint_HET_PAM_Node_2.0.5.json", "resumeFromCheckpoint": true, "params": { "HOME_BASE_URL": "https://pam.home.example.com", "AIRPORT_CODE": "HET", "APP_NAME": "PAM", "MODULE_NAME": "Node", "VERSION_NUMBER": "2.0.5", "ZIP_FILE_PATH": "C:\\path\\to\\pam-2.0.5.zip", "ACTION_TYPE": "FULL", "LOG_NAME": "app.log" }, "artifacts": { "configPath": "./runtime/config_20260529_103000_abcd.txt", "traceFilePath": "./logs/api_trace_HET_PAM_Node_2.0.5_20260529_103000_abcd.log", "hashCode": "43858bcf", "nodeUrl": "https://pam-node.example.com" }, "onlineIps": [ "192.168.1.10", "192.168.1.11" ], "targetIps": [ "192.168.1.10" ], "completedGlobalSteps": [ "get-token", "create-version", "upload-package", "publish-version" ], "ipStates": { "192.168.1.10": { "status": "FAILED", "completedSteps": [ "upgrade-ip", "poll-upgrade-progress", "start-ip" ], "failedStage": "verify-ip", "failureReason": "Health check failed", "rollbackStatus": "PENDING_AGENT_CONFIRMATION", "rollbackStopFirst": true, "logFile": "./logs/deploy_192.168.1.10.zip" } }, "lastSuccessStep": "start-ip", "lastFailedStep": "verify-ip", "pendingConfirmation": "rollback-ip:192.168.1.10", "updatedAt": "2026-05-29 10:30:00" } ``` 敏感字段不写入业务 checkpoint： - `CLIENT_SECRET` - token - Authorization header ### 11.2 断点续跑策略 1. 启动时如果指定 `resume_from_checkpoint=true`，先读取业务 checkpoint。 2. 校验当前核心参数与 checkpoint 参数是否一致。 3. 核心参数不一致时，不直接续跑，必须要求用户确认重新开始或使用旧参数。 4. 已完成的全局步骤默认跳过。 5. `create-download-task` 已成功但 `poll-download-progress` 未完成时，从 `poll-download-progress` 继续。 6. 单 IP 已成功的默认跳过。 7. 单 IP 失败且处于回滚确认状态时，恢复后先进入回滚确认，不继续后续动作。 ## 12. 人工确认设计 使用 LangGraph interrupt 表示需要外部输入的确认点。 ### 12.1 参数确认 触发点： - 真实部署前。 - 查询 Node/IP 前。 - 手动回滚前。 确认内容： - 模式 - 脚本入口 - HOME_BASE_URL - AIRPORT_CODE - APP_NAME - MODULE_NAME - VERSION_NUMBER - ZIP_FILE_PATH - ACTION_TYPE - TIMEOUT - LOG_NAME - 指定 IP - CLIENT_ID 是否已提供 - CLIENT_SECRET 是否已提供 ### 12.2 IP 范围确认 触发点： - 用户指定 IP 和在线 IP 取交集后，部署范围发生变化。 - 过滤结果为空。 - 用户启用 `all_or_nothing=true` 且部分 IP 不在线。 ### 12.3 回滚确认 触发点： - `upgrade-ip` 失败。 - `poll-upgrade-progress` 失败。 - `start-ip` 失败。 - `verify-ip` 失败。 - action 输出 `PENDING_AGENT_CONFIRMATION(...)`。 确认内容： - 目标 IP - 失败阶段 - 失败原因 - 建议是否回滚 - `stopFirst` 建议值 默认建议： - 升级失败：建议回滚，`stopFirst=false` - 启动失败：建议回滚，`stopFirst=true` - 校验失败：建议回滚，`stopFirst=true` ## 13. 进度事件设计 工作流运行中输出结构化事件，供 CLI、日志、SSE 或 WebSocket 使用。 ```python class DeployEvent(TypedDict): run_id: str level: Literal["INFO", "WARN", "ERROR"] type: Literal[ "FLOW_START", "FLOW_DONE", "FLOW_FAIL", "ACTION_START", "ACTION_DONE", "ACTION_FAIL", "WAIT", "IP_START", "IP_DONE", "IP_FAIL", "CONFIRMATION_REQUIRED", "REPORT" ] stage: str ip: str | None message: str next_stage: str | None wait_sec: int | None data: dict created_at: str ``` 事件示例： ```json { "type": "ACTION_DONE", "stage": "upload-package", "message": "软件包上传完成", "data": { "HASH_CODE": "43858bcf" } } ``` 等待事件示例： ```json { "type": "WAIT", "stage": "create-download-task", "message": "等待 2 秒后开始首次下载进度轮询", "next_stage": "poll-download-progress", "wait_sec": 2 } ``` ## 14. 分支流程 ### 14.1 混合智能执行 适用场景： - 用户明确要求“用 MCP”“直接在线执行”“不要生成脚本”。 - 用户只说“帮我部署”，且当前环境存在可用 PAM_NODE MCP 工具。 流程： ```text load_skill_policy -> llm_understand_request -> llm_extract_params -> validate_and_normalize_params -> llm_generate_plan -> confirm_params -> select_execution_strategy(hybrid_node_mcp) -> build_action_routes -> prepare_tool_runtimes -> deploy_flow ``` 行为： - PAM_HOME action 通过 `ScriptActionRunner` 调用 `deploy.sh` / `deploy.ps1` action。 - PAM_NODE action 通过 `MCPActionRunner` 调用 PAM_NODE MCP 工具。 - 需要写配置文件供 HOME 脚本 action 使用，但敏感字段不进入命令行和普通日志。 - 仍然按 Skill 固定 action 顺序执行。 - 仍然写业务 checkpoint 和 trace。 - 仍然要求参数确认、IP 范围确认和回滚确认。 ### 14.2 脚本离线执行 适用场景： - 用户明确要求“用脚本”“离线执行”。 - PAM_NODE MCP 不可用且用户确认切换全脚本后端。 流程： ```text load_skill_policy -> llm_understand_request -> llm_extract_params -> validate_and_normalize_params -> llm_generate_plan -> confirm_params -> select_execution_strategy(script_only) -> build_action_routes -> prepare_tool_runtimes -> deploy_flow ``` 行为： - 只调用 `deploy.sh` / `deploy.ps1` action 入口。 - 不调用脚本主流程。 - `CLIENT_SECRET` 只写入配置文件，不进入命令行。 ### 14.3 只说明脚本用法 适用场景： - 用户要求“给我脚本用法”。 - 用户要求“生成脚本”，但 Skill 禁止生成或修改脚本。 - 用户明确“不直接动环境”。 行为： - 说明现有 `deploy.sh` / `deploy.ps1` action 用法。 - 不写 `config.txt`。 - 不调用 MCP。 - 不调用真实脚本 action。 ### 14.4 预演部署计划 适用场景： - 用户只想确认参数和计划，不执行真实部署。 行为： - LLM 抽取和归一化参数。 - LLM 生成用户可读部署计划。 - 输出确认单。 - 输出预计 action 顺序。 - 输出执行策略：混合执行或全脚本执行。 - 明确 HOME action 和 NODE action 的执行后端。 - 如存在 checkpoint，说明可从哪个步骤恢复。 - 不调用真实 action。 ### 14.5 只查询 Node 和在线 IP 流程： ```text confirm_params -> select_execution_strategy -> build_action_routes -> prepare_tool_runtimes -> get_token -> get_node_url -> get_online_ips -> report_node_ips ``` 禁止执行： - `create-version` - `upload-package` - `publish-version` - `create-download-task` - `upgrade-ip` ### 14.6 手动回滚 流程： ```text rollback_entry -> llm_extract_rollback_target -> confirm_rollback_target -> select_execution_strategy -> build_action_routes -> prepare_tool_runtimes -> rollback_ip -> verify_ip optional -> download_log -> update_checkpoint -> final_report ``` 回滚必须由用户明确确认，不能根据失败状态自动执行。 ## 15. 错误处理策略 ### 15.1 全局失败 以下阶段失败时终止整轮部署： - `get-token` - `create-version` - `upload-package` - `publish-version` - `get-node-url` - `get-online-ips` - `create-download-task` - `poll-download-progress` 处理： - 记录 `last_failed_step`。 - 写 checkpoint。 - 输出失败报告。 - 保留原始 action 输出。 ### 15.2 单 IP 失败 以下阶段失败时只标记当前 IP 失败： - `upgrade-ip` - `poll-upgrade-progress` - `start-ip` - `verify-ip` 处理： - 记录失败阶段和原因。 - 尽力执行 `download-log`。 - 写 checkpoint。 - 转入回滚确认。 - 未确认回滚前，不执行 `rollback-ip`。 ### 15.3 日志下载失败 `download-log` 失败不覆盖原始失败原因。 处理： - 记录日志下载失败。 - 保留主失败阶段。 - 报告中明确日志缺失或下载失败。 ## 16. 安全设计 1. `CLIENT_SECRET` 不进入命令行。 2. `CLIENT_SECRET` 不进入普通日志、进度事件、最终报告。 3. token 不进入最终报告。 4. action 原始输出保存前需要做敏感字段脱敏。 5. `config.txt` 或运行时配置文件权限应尽量限制为当前用户可读写。 6. 回滚必须显式确认。 7. 若用户要求“不落地配置文件”，真实部署流程直接终止并说明原因。 8. 对脚本路径使用白名单，只允许当前工作目录下既有脚本。 9. MCP 工具调用使用白名单，只允许 Skill 中定义的 PAM_NODE 工具。 10. LLM 输出必须经过结构化校验和 Skill guardrails。 11. LLM 不能生成可执行 shell/PowerShell 命令作为真实执行依据。 12. PAM_HOME action 不允许被路由到 MCP。 ## 17. CLI 设计 第一阶段建议先落地 Agent CLI，便于本地验证 Skill、LLM、MCP 和脚本后端。 ### 17.1 部署 ```bash python -m pam_deploy_graph.cli deploy \ --strategy hybrid-node-mcp \ --home-base-url https://pam.home.example.com \ --client-id xxx \ --client-secret "***" \ --airport-code HET \ --app-name PAM \ --module-name Node \ --version-number 2.0.5 \ --zip-file-path C:\path\to\pam-2.0.5.zip \ --target-ip 192.168.1.10 \ --target-ip 192.168.1.11 ``` 脚本后端： ```bash python -m pam_deploy_graph.cli deploy \ --strategy script-only \ --config ./deploy_params.json ``` ### 17.2 预演 ```bash python -m pam_deploy_graph.cli preview --config ./deploy_params.json ``` ### 17.3 对话式 Agent ```bash python -m pam_deploy_graph.cli chat ``` 对话式 Agent 行为： - 使用 LLM 理解用户自然语言。 - 使用 Skill 规则控制工具调用。 - 在真实部署前输出确认单并等待用户确认。 - 支持继续追问缺失参数。 ### 17.4 断点续跑 ```bash python -m pam_deploy_graph.cli resume \ --checkpoint ./logs/deploy_checkpoint_HET_PAM_Node_2.0.5.json ``` ### 17.5 回滚确认恢复 ```bash python -m pam_deploy_graph.cli resume \ --thread-id \ --approve-rollback \ --ip 192.168.1.10 \ --stop-first ``` ## 18. 服务化设计 后续可将 Agent CLI 包装为 FastAPI 服务。 接口建议： ```text POST /agent/chat POST /deploy/preview POST /deploy/start POST /deploy/{run_id}/confirm POST /deploy/{run_id}/rollback/confirm POST /deploy/{run_id}/resume GET /deploy/{run_id} GET /deploy/{run_id}/events GET /deploy/{run_id}/report ``` 事件输出： - CLI：直接打印结构化进度。 - API：通过 SSE 或 WebSocket 输出 `DeployEvent`。 ## 19. 测试策略 ### 19.1 单元测试 覆盖： - `SkillPolicy` 从 Skill 文档提取规则。 - LLM structured output schema 校验。 - LLM 输出违反 Skill guardrails 时会被拒绝。 - `OutputParser` 解析 `key=value`。 - 多个 `IP=` 行解析为列表。 - `PENDING_AGENT_CONFIRMATION(...)` 检测。 - 敏感字段脱敏。 - MCP tool input 构造。 - 脚本 action 命令构造。 - checkpoint JSON 写入和读取。 ### 19.2 图路由测试 覆盖： - `show_usage` 不调用 action。 - `preview` 不调用 action。 - 参数未确认不调用 action。 - PAM_NODE MCP 可用且用户未指定策略时使用 `hybrid_node_mcp`。 - PAM_NODE MCP 不可用时需要用户确认才切 `script_only`。 - HOME action 始终路由到脚本。 - NODE action 在混合策略下路由到 MCP。 - IP 范围变化进入确认。 - 单 IP 失败进入回滚确认。 - 用户拒绝回滚后继续或结束。 ### 19.3 LLM 节点测试 覆盖： - 自然语言中抽取机场、应用、模块、版本和包路径。 - 缺少 `CLIENT_SECRET` 时生成追问。 - 用户说“不要动环境”时进入预演或用法说明。 - 用户说“用 MCP”时 strategy preference 为 `hybrid_node_mcp`，并提示 HOME 仍走脚本 action。 - 用户说“离线脚本执行”时 mode preference 为 API脚本。 - LLM 计划中出现非法 action 时被 guardrails 拒绝。 ### 19.4 MCP runner 测试 覆盖： - PAM_NODE 标准 action 到 MCP tool 的映射。 - PAM_NODE MCP 工具缺失时停止。 - PAM_HOME action 不会进入 MCP runner。 - MCP 返回结构化结果转为 `ActionResult`。 - MCP 原始错误进入 `raw_output`。 - 回滚未确认时不调用 `pam_rollback_ip`。 ### 19.5 Runner 假实现测试 使用 fake runner 模拟脚本输出： - 全部成功。 - 全局失败。 - 上传返回 `HASH_CODE`。 - Node 返回 `NODE_URL`。 - 在线 IP 返回多个 `IP=`。 - 单 IP 校验失败。 - 日志下载失败。 ### 19.6 集成测试 MCP 或脚本真实后端接入后，只做可控环境下的 smoke： - `get-token` - `get-node-url` - `get-online-ips` 完整部署集成测试需要人工指定测试环境和测试包，不默认纳入自动 CI。 ## 20. 实施计划 ### 阶段一：Agent MVP 交付： - `DeployState` - `SkillPolicy` 加载器 - LLM structured output schema - `llm_understand_request` - `llm_extract_params` - `llm_generate_plan` - Skill guardrails - 主图和单 IP 顺序流程 - fake runner - output parser - 参数确认 interrupt - 业务 checkpoint JSON - 最终报告 验收： - 对话式输入能抽取参数并生成部署计划。 - 能跑通 `preview`。 - 能跑通 `query_node_ips`。 - fake runner 能跑通完整部署成功链路。 - fake runner 能验证单 IP 失败和回滚确认。 - LLM 不能绕过参数确认调用 fake runner。 ### 阶段二：混合工具路由接入 交付： - `ActionRouter`。 - PAM_HOME action 到 `ScriptActionRunner` 的固定路由。 - PAM_NODE MCP server/tool discovery。 - `MCPActionRunner`。 - PAM_NODE 标准 action 到 MCP tool 的映射。 - MCP 工具结果统一转 `ActionResult`。 - 混合执行 `query_node_ips` smoke：`get-token/get-node-url` 走脚本，`get-online-ips` 走 MCP。 验收： - 用户指定 MCP 时进入 `hybrid_node_mcp`，HOME 阶段仍走脚本。 - 用户未指定策略且 PAM_NODE MCP 可用时默认混合执行。 - PAM_NODE MCP 不可用时不会静默切全脚本。 - 回滚未确认时不会调用 MCP 回滚工具。 ### 阶段三：全脚本后端完善 交付： - Shell runner 接入全部 `deploy.sh --action`。 - PowerShell runner 接入全部 `deploy.ps1 -Action`。 - 真实 stdout/stderr 收集。 - action 超时控制。 - 统一工作流 trace 文件。 验收： - 在 Windows 上可调用 `deploy.ps1` action。 - 在 Git Bash/Linux 上可调用 `deploy.sh` action。 - 不调用脚本主流程。 ### 阶段四：断点续跑完善 交付： - 从业务 checkpoint 恢复。 - 参数一致性校验。 - 已完成全局步骤跳过。 - 已成功 IP 跳过。 - pending rollback 恢复后继续等待确认。 验收： - 模拟中断后可从指定阶段恢复。 - 参数变化时会要求用户确认。 ### 阶段五：服务化和可视化 交付： - Chat Agent API。 - FastAPI 包装。 - SSE/WebSocket 进度事件。 - 运行记录查询。 - 最终报告接口。 验收： - 前端或调用方可实时看到进度。 - 可通过接口完成确认和恢复。 ### 阶段六：Python 原生 API client 迁移 交付： - 将脚本内部 HTTP 能力逐步迁移为 Python client。 - 保留脚本作为兼容入口。 验收： - Python client 与脚本 action 行为一致。 - 关键接口都有单元测试和契约测试。 ## 21. 风险与待决事项 1. PowerShell 脚本当前未暴露 `-TraceFile`，接口级 trace 复用存在能力差异。 2. HOME action 只能通过脚本 action 执行，脚本内部会重复获取 token。第一阶段接受该开销，后续若 PAM_HOME 支持 MCP 或 Python client 后再优化。 3. `config.txt` 落地包含敏感字段，需要明确文件权限和清理策略。 4. 单 IP 是否允许并发需要谨慎评估，第一版不并发。 5. 真实回滚策略需要业务方确认“失败后是否继续处理后续 IP”的默认行为。 6. PAM_NODE MCP 工具名称、参数 schema 和返回 schema 需要与 MCP server 对齐。 7. LLM 结构化输出需要稳定模型和严格 schema 校验，否则只能作为建议，不能驱动真实工具。 8. Skill 文档如果继续演进，需要建立 SkillPolicy 的解析测试，避免规则变更后 Agent 行为漂移。 9. 混合执行会同时依赖脚本环境和 MCP 环境，需要在启动前做两类运行时检查。 ## 22. 推荐第一版取舍 第一版只做三件事： 1. 用 LangGraph 实现 Agent 骨架：Skill 加载、LLM 结构化理解、确认点、固定流程和 fake runner。 2. 优先接混合工具路由：HOME 脚本 action + NODE MCP，形成符合当前接口能力的智能部署闭环。 3. 再完善全脚本策略作为离线和兜底路径，不重写现有脚本。 这样能先体现智能部署：用户用自然语言发起部署，LLM 负责理解和计划，Skill 负责约束，LangGraph 负责状态和确认，ActionRouter 按 HOME/NODE 归属分发到脚本或 MCP。流程稳定后，再决定是否把脚本能力迁移到 Python 原生实现。