agent_deply/README.md

opagent

PAM Deploy Agent

本仓库正在把原有 PAM_AUTO_DEPLY_SKILL.md + deploy.sh / deploy.ps1 的组合，重构为一个 LangGraph-style 的 PAM 智能部署 Agent。

当前已加入 pam_deploy_graph Python 包，用于先落地 Agent Runtime 的核心骨架：

• PAM_HOME action 固定通过 deploy.sh / deploy.ps1 调用。
• PAM_NODE action 可通过 MCP runner 调用。
• 默认执行策略为 hybrid_node_mcp，即 HOME 脚本 action + NODE MCP。
• 离线策略为 script_only，全部 action 走脚本 action。
• langgraph 已作为正式依赖引入；核心 Agent、runner、router 和 parser 也可独立测试。

当前代码骨架

pam_deploy_graph/
  agent.py             # Agent runtime，参数归一化、预演、fake 全局流程
  action_router.py     # 按 action 路由到脚本、MCP 或 fake runner
  script_runner.py     # deploy.sh / deploy.ps1 action 调用封装
  mcp_runner.py        # PAM_NODE MCP runner 协议与 action -> tool 映射
  fake_runner.py       # 测试用 runner，不访问真实环境
  output_parser.py     # 解析 key=value、MCP JSON、待确认回滚标记
  skill_policy.py      # 从 PAM_AUTO_DEPLY_SKILL.md 加载 Skill 策略
  config_writer.py     # 生成脚本 action 所需 config 文件
  checkpoint_store.py  # 业务 checkpoint JSON 读写
  params_loader.py     # 读取 JSON 或 config.txt 风格参数文件
  llm/                 # LLM structured output 接口、真实 HTTP client、提示词、规则 fallback 和 guardrails
  graph.py             # LangGraph StateGraph 集成入口
  langgraph_runtime.py # chat 人工确认点的 LangGraph interrupt 运行器
  mcp_client.py        # MCP session/callable adapter 与 client 配置读取
  interactive.py       # 常驻式 CLI 对话框，会话命令、确认和续跑
  cli.py               # CLI 入口

tests/
  test_action_router.py
  test_output_parser.py
  test_params_loader.py
  test_script_runner.py
  test_skill_policy.py
  test_interactive_cli.py

docs/
  current_logic_flow.md      # 当前整体逻辑结构流程图
  todo.md                    # chat 优化和 LLM action 后分析待办

packaging/
  build_linux_self_contained.sh  # Linux 解压即用包构建脚本
  README_linux_package.md        # Linux 打包说明和包大小评估
  mcp_client.example.json        # MCP stdio 配置示例

当前进度

已完成：

• 建立 Python 工程骨架和 pyproject.toml。
• 实现 hybrid_node_mcp 路由规则：PAM_HOME 走脚本 action，PAM_NODE 走 MCP。
• 实现 script_only 路由规则：所有 action 走脚本 action。
• 实现脚本 action 命令构造，避免调用脚本主流程。
• 实现 MCP runner 抽象和 PAM_NODE action 到 MCP tool 的默认映射。
• 实现脚本/MCP/fake action 结果统一为 ActionResult。
• 实现 config.txt.example 风格和 JSON 风格参数读取。
• 实现 fake 全局流程和完整部署流程，便于不触碰真实环境地验证 Agent 路由。
• 实现逐 IP 处理骨架：升级、轮询、启动、校验、日志下载。
• 实现单 IP 失败后的待回滚确认状态，不自动执行回滚。
• 实现人工确认入口：confirm --decision approve|reject 只处理待确认回滚。
• 实现 checkpoint 自动保存和 resume 续跑：全局步骤、成功 IP、单 IP 已完成 action 会跳过。
• 实现 LLM structured output 骨架：意图识别、参数抽取、部署计划生成。
• 实现 OpenAI-compatible 真实 LLM client，支持 base_url / api_key / model 配置。
• 固化真实 LLM 提示词：意图识别、参数抽取、部署计划生成均要求 JSON structured output。
• 增加规则 fallback RuleBasedLlmClient，用于本地开发和测试。
• 增加 LLM 输出 guardrails，禁止计划中出现可执行脚本命令和非法 action。
• 引入 langgraph 依赖，并提供 build_langgraph() 图工厂。
• chat 人工确认点已接入 LangGraph interrupt/checkpointer：run 到待回滚确认时暂停，approve/reject 通过 Command(resume=...) 恢复。
• 引入 MCP client adapter，可包装 SDK session 或普通 callable，并提供 JSON client 配置读取。
• CLI/chat 支持 --mcp-config 直接加载 stdio MCP 配置并构造 MCP runner。
• 本地已安装 langgraph 和 mcp，并完成 LangGraph fake 全局流程 smoke。
• CLI analyze 输出已做敏感字段脱敏。
• 增加 chat 常驻式 CLI 对话框，支持自然语言分析、参数设置、执行确认、回滚确认、状态查看、事件查看、checkpoint 选择和续跑。
• chat 可选启用 rich / prompt_toolkit，支持更清晰输出、命令补全和输入历史。
• 增加 action 后 LLM/规则诊断，可通过 --analyze-actions 或 llm action-analysis on 显式开启。
• 添加基础测试，当前本地结果为 37 passed, 1 skipped。

未完成：

• 尚未接入真实 MCP session；当前已把 client adapter、tool 映射和配置格式准备好。
• 尚未执行真实脚本 action 或真实 PAM_NODE MCP 调用。

LLM 配置

默认不配置 LLM 时，analyze 使用本地规则 fallback。配置真实 LLM 后，会走 OpenAI-compatible /chat/completions：

$env:PAM_LLM_BASE_URL="https://your-llm.example.com/v1"
$env:PAM_LLM_API_KEY="your-api-key"
$env:PAM_LLM_MODEL="your-model-name"

python -m pam_deploy_graph.cli analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境"

也可以直接用 CLI 参数覆盖环境变量：

python -m pam_deploy_graph.cli analyze \
  --config doc_scripts/config.txt.example \
  --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境" \
  --llm-base-url https://your-llm.example.com/v1 \
  --llm-api-key your-api-key \
  --llm-model your-model-name

真实 LLM 调用位置在 pam_deploy_graph/llm/openai_compatible.py，提示词在 pam_deploy_graph/llm/prompts.py。发送给 LLM 的 base_params 会脱敏，CLIENT_SECRET 不会进入 prompt；本地生成计划后仍会执行 guardrails 校验。

MCP Client 配置

CLI/chat 已支持通过 --mcp-config 直接加载 MCP 配置。当前内置支持 stdio transport；配置文件里提供 MCP server 启动命令后，Agent 会在调用 PAM_NODE action 时创建 MCP stdio session。

CLI 示例：

python -m pam_deploy_graph.cli chat \
  --config doc_scripts/config.txt.example \
  --strategy hybrid_node_mcp \
  --mcp-config mcp_client.json \
  --checkpoint runtime/checkpoints/demo.json

代码内嵌方式：

from pam_deploy_graph.agent import PamDeployAgent
from pam_deploy_graph.mcp_factory import build_mcp_runner_from_config

runner = build_mcp_runner_from_config("mcp_client.json")
agent = PamDeployAgent(mcp_runner=runner)

mcp_client.json 示例：

{
  "server_name": "pam-node-prod",
  "transport": "stdio",
  "command": "/opt/pam-node-mcp/server",
  "args": ["--stdio"],
  "cwd": "/opt/pam-node-mcp",
  "env": {
    "PAM_NODE_ENV": "prod"
  },
  "timeout_seconds": 60,
  "tool_names": {
    "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",
    "poll-upgrade-progress": "pam_poll_upgrade_progress",
    "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"
  }
}

如果不传 tool_names，McpActionRunner 会使用上面的默认 action -> tool 映射。

使用方式

整体逻辑结构流程图：

docs/current_logic_flow.md

Linux 解压即用打包：

bash packaging/build_linux_self_contained.sh

构建产物会输出到：

dist/linux_self_contained/pam-deploy-agent-linux-x86_64/
dist/linux_self_contained/pam-deploy-agent-linux-x86_64.tar.gz

发布包内的 doc_scripts 只包含运行必需文件：deploy.sh、config.txt.example、PAM_AUTO_DEPLY_SKILL.md。发布包内的 README.md 使用 packaging/README_packaged_agent.md，只介绍打包后 Agent 的使用方式；同时会带上 mcp_client.example.json 作为 MCP 配置示例。

目标机器解压后运行：

tar -xzf pam-deploy-agent-linux-x86_64.tar.gz
cd pam-deploy-agent-linux-x86_64
./run.sh --help
./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json

包大小以构建脚本末尾打印的 du 结果为准。按当前依赖估算：默认包含 MCP 依赖时压缩包约 60-110 MB、解压后约 160-300 MB；使用 PACKAGE_EXTRAS= 构建最小包时压缩包约 45-75 MB、解压后约 120-200 MB。

交互式对话框：

python -m pam_deploy_graph.cli chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/chat-demo.json

启动后可输入自然语言需求或会话命令：

PAM> 请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境
PAM> preview
PAM> set VERSION_NUMBER=2.0.6
PAM> run
即将执行真实 action；确认执行请输入 yes: yes
PAM> status
PAM> params
PAM> events 5
PAM> llm action-analysis on
PAM> mcp config mcp_client.example.json
PAM> list checkpoints
PAM> load checkpoint runtime/checkpoints/chat-demo.json
PAM> approve
PAM> resume
PAM> exit

chat 默认仍要求在会话内显式输入 run，并确认参数、目标 IP 范围和最终执行后才会执行 action；如果某个 IP 失败，会通过 LangGraph interrupt 暂停并提示输入 approve 或 reject [原因]，确认后恢复同一个图线程继续执行。chat 也支持 --llm-base-url / --llm-api-key / --llm-model、--mcp-config 和 --analyze-actions。

预演：

python -m pam_deploy_graph.cli preview --config doc_scripts/config.txt.example --strategy fake

fake 全局流程验证：

python -m pam_deploy_graph.cli run-global --config doc_scripts/config.txt.example --strategy fake --confirm

fake 完整部署流程验证：

python -m pam_deploy_graph.cli run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm

如果某个 IP 失败并进入待回滚确认，先查看输出中的 confirmation，再人工决定：

python -m pam_deploy_graph.cli confirm --checkpoint runtime/checkpoints/demo.json --decision approve --confirm
python -m pam_deploy_graph.cli resume --checkpoint runtime/checkpoints/demo.json --confirm

拒绝回滚：

python -m pam_deploy_graph.cli confirm --checkpoint runtime/checkpoints/demo.json --decision reject --note "人工决定暂不回滚" --confirm

checkpoint 用于断点续跑，会保存完整运行状态和参数。为了支持真实续跑，Agent 写入 checkpoint 时不会脱敏参数；请把 checkpoint 放在受控目录中。如果不传 --checkpoint，流程仍可运行，但不能跨进程 resume。

结构化理解和计划生成：

python -m pam_deploy_graph.cli analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境"

测试：

pytest -q

下一步建议

1. 接入真实 PAM_NODE MCP session，并用 SessionMcpToolClient 包装。
2. 在测试环境中做 smoke：HOME 脚本 get-token/get-node-url + NODE MCP get-online-ips。
3. 在测试环境验证真实脚本 action 的失败、回滚确认和续跑链路。
4. 继续细化参数确认、IP 范围确认的交互式 UI 或上层编排。