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 # action 级 LangGraph 运行器
  mcp_client.py        # MCP stdio/HTTP/SSE client、鉴权 token 和配置读取
  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 server URL + 鉴权配置示例

当前进度

已完成：

建立 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 处理骨架：升级、轮询、启动、校验、日志下载。
实现 action 失败或审核阻断后暂停并保留当前 action，修复后 resume 会从当前 action 重试。
回滚已从主 workflow 中拆出，改为 chat/CLI 的显式 rollback 命令；旧 confirm 入口仅作为兼容保留。
实现 checkpoint 自动保存和 resume 续跑：全局步骤、成功 IP、单 IP 已完成 action 会跳过。
实现 LLM structured output 骨架：意图识别、参数抽取、部署计划生成。
实现 OpenAI-compatible 真实 LLM client，支持 base_url / model 配置，api_key 可为空。
固化真实 LLM 提示词：意图识别、参数抽取、部署计划生成均要求 JSON structured output。
增加规则 fallback RuleBasedLlmClient，用于本地开发和测试。
增加 LLM 输出 guardrails，禁止计划中出现可执行脚本命令和非法 action。
引入 langgraph 依赖，CLI/chat 执行流程统一通过 action 级 LangGraph runtime 调度。
CLI/chat 执行流程统一通过 action 级 LangGraph runtime 调度；失败暂停状态写入业务 checkpoint，resume 会重新进入图并从断点继续。
引入 MCP client adapter，可包装 SDK session、普通 callable、stdio server、HTTP/SSE server，并提供 JSON client 配置读取。
CLI/chat 支持 --mcp-config 直接加载 MCP server URL、鉴权和可选 tool 覆盖配置。
本地已安装 langgraph 和 mcp，并完成 LangGraph fake 全局流程 smoke。
CLI analyze 输出已做敏感字段脱敏。
增加 chat 常驻式 CLI 对话框，支持自然语言分析、参数设置、执行确认、显式回滚、状态查看、事件查看、checkpoint 选择和续跑。
chat 在开发环境和默认发布包中都会优先启用 rich / prompt_toolkit；如果增强输入初始化失败，会自动降级到普通 input()。
chat 执行前会归一化参数并展示实际写入脚本配置的值；script_only / hybrid_node_mcp 会提前检查 ZIP_FILE_PATH 是否存在。
chat 执行中会播报每个 action 的开始、完成或失败；action 执行失败会停在当前 checkpoint，不再误报 LangGraph 不可用。
每个 action 完成后都会进入一次 LLM/规则审核；只有审核通过才会把 action 记为 completed，如果审核建议停止，流程会暂停并等待用户 resume 重试当前 action。
poll-download-progress 和 poll-upgrade-progress 已改为单次进度查询；workflow 负责按配置重复调用，每次查询结果都会交给 LLM/规则审核判断是否完成，并通过 chat 播报进度。
--analyze-actions 和 llm action-analysis on 改为只控制是否把详细审核结果写入 events，不再控制审核是否执行。
chat 会播报 action 审核开始、审核完成和审核失败，避免黑盒执行。
chat 支持执行中按 Ctrl+C 中断，保存 checkpoint 后再 resume。
chat 支持普通 LLM 对话、日志尾部分析和单 action 执行：ask <问题>、log analyze <路径>、action propose <需求>、action run ...。
chat 普通对话会优先使用 OpenAI-compatible streaming 输出；如果服务端不支持流式，会自动退回普通请求。<think>...</think> 思考内容会被过滤，不展示也不写入运行日志。
chat 支持 set KEY=VALUE 和 load params <路径> 热更新当前运行参数，并同步回写运行中的 config.txt 与 checkpoint。
支持通过 --llm-action-analysis-prompt-file、PAM_LLM_ACTION_ANALYSIS_PROMPT_FILE 或 chat 内 llm config action_analysis_prompt_file=... 自定义 action 审核提示词。
增加统一运行日志，默认写入 logs/pam_deploy_agent.log，覆盖 CLI/chat、LLM 调用、action 路由、脚本/MCP 调用、LangGraph、checkpoint 等关键流程，并按天切分、默认保留 14 个历史日切文件。
chat 支持 llm test [文本]，可用当前 LLM client 做一次轻量调用，确认真实 LLM 或规则 fallback 是否正常加载。
添加基础测试，当前本地结果为 83 passed, 3 skipped。

未完成：

尚未执行真实 PAM_NODE MCP 调用；当前已把 MCP HTTP/SSE/stdio client、鉴权和 tools 自动发现准备好。
尚未执行真实脚本 action 或真实 PAM_NODE MCP 调用。

LLM 配置

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

base_url 和 model 必填；api_key 可为空。如果模型服务不需要鉴权，不配置 PAM_LLM_API_KEY 或不传 --llm-api-key 即可，Agent 不会发送 Authorization 请求头。

$env:PAM_LLM_BASE_URL="https://your-llm.example.com/v1"
$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-model your-model-name

如需自定义 action 审核提示词，可再补充：

python -m pam_deploy_graph.cli analyze \
  --config doc_scripts/config.txt.example \
  --text "请分析这次部署" \
  --llm-base-url https://your-llm.example.com/v1 \
  --llm-model your-model-name \
  --llm-action-analysis-prompt-file prompts/action_review.txt

仓库内已提供 prompts/action_review.txt 作为“当前默认 action 审核提示词”的落地副本，后续自定义时可以先复制它再改，便于和内置默认行为对照。

真实 LLM 调用位置在 pam_deploy_graph/llm/openai_compatible.py，提示词在 pam_deploy_graph/llm/prompts.py。发送给 LLM 的 base_params 会脱敏，CLIENT_SECRET 不会进入 prompt；本地生成计划后仍会执行 guardrails 校验。chat 普通对话优先使用 /chat/completions streaming；服务端不支持时会自动退回非流式请求。普通对话和日志分析会过滤 <think>...</think>、未闭合 <think> 及内部思考内容。

chat 内可以用当前 client 做一次轻量测试，确认真实 LLM 或规则 fallback 是否正常加载：

PAM> llm test 请返回一次连通性测试结果

如果服务需要鉴权，再补充：

export PAM_LLM_API_KEY="your-api-key"

MCP Client 配置

CLI/chat 已支持通过 --mcp-config 直接加载 MCP 配置。常用场景只需要配置 MCP server_url 和独立鉴权信息；Agent 会连接 MCP server，调用 list_tools 自动发现 server 暴露的 tools，再按 action 名自动匹配。

MCP 鉴权 token 获取方式与 HOME 一致，默认按 client_credentials POST 到 /oauth/token 风格接口；但 MCP 使用独立的 token_url、client_id、client_secret，不会复用 HOME 的账号密码。

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": "streamable_http",
  "server_url": "https://pam-node-mcp.example.com/mcp",
  "auth": {
    "token_url": "https://pam-node-auth.example.com/oauth/token",
    "client_id": "mcp_client_id",
    "client_secret": "mcp_client_secret",
    "grant_type": "client_credentials"
  },
  "timeout_seconds": 60,
  "sse_read_timeout_seconds": 300,
  "headers": {}
}

字段说明：

transport：支持 streamable_http、sse、stdio。一般远端 MCP server 用 streamable_http 或 sse。
server_url：MCP server 地址，例如 /mcp 或 /sse endpoint。
auth.token_url：MCP 鉴权 token 地址，和 HOME 获取 token 的表单方式一致，但地址和账号密码独立。
auth.client_id / auth.client_secret：MCP 独立账号密码。
headers：除鉴权外需要额外带给 MCP server 的静态请求头。
action_tools：通常不用配置。只有 server 暴露的 tool 名称不符合 get-online-ips、get_online_ips、pam_get_online_ips 这类约定时，才用它覆盖 action -> tool，例如 { "get-online-ips": "custom_list_ips" }。

如果是本地 stdio MCP server，也仍然支持：

{
  "transport": "stdio",
  "command": "/opt/pam-node-mcp/server",
  "args": ["--stdio"],
  "cwd": "/opt/pam-node-mcp",
  "env": {
    "PAM_NODE_ENV": "prod"
  }
}

使用方式

开发项目迁移到新环境后，推荐先安装完整开发依赖：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[mcp,chat,test]"
pytest -q

Windows PowerShell 激活虚拟环境使用：

.\.venv\Scripts\Activate.ps1

基础要求：Python 3.11+。如果要执行 Linux 脚本 action，运行环境还需要 bash 和 curl；如果要构建 Linux 解压即用包，请在 Linux x86_64 构建机上执行打包脚本。

整体逻辑结构流程图：

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> load params runtime/override.txt
PAM> run
即将执行真实 action；确认执行请输入 yes: yes
开始执行 action: get-token [backend=fake]
开始分析 action 结果: get-token [backend=fake]
完成 action: get-token [backend=fake]
PAM> status
PAM> params
PAM> events 5
PAM> ask 这个 agent 能做什么
PAM> log analyze logs/pam_deploy_agent.log 请帮我看最近异常 --tail 400
PAM> action propose 请单独执行 verify-ip 192.168.1.10
PAM> action run verify-ip ip=192.168.1.10
PAM> action run llm 请单独执行 get-online-ips
PAM> llm test
PAM> llm action-analysis on
PAM> llm config action_analysis_prompt_file=prompts/action_review.txt
PAM> mcp config mcp_client.example.json
PAM> list checkpoints
PAM> load checkpoint runtime/checkpoints/chat-demo.json
PAM> rollback
PAM> resume
PAM> exit

chat 默认把非内置命令交给当前 LLM 做普通对话，不会自动触发部署 workflow；普通对话优先流式展示，<think>...</think> 思考内容会被过滤。需要结构化分析部署需求时请显式使用 analyze <需求>，完整部署仍要求输入 run，并确认参数、目标 IP 范围和最终执行后才会执行 action。log analyze <路径> [问题] [--tail N] [--max-bytes N] 默认只读取日志尾部并脱敏后交给 LLM；action propose <需求> 只让 LLM 解析单 action 计划，不执行；action run <action> [ip=...] [KEY=VALUE...] 或 action run llm <需求> 会展示 action、backend、ip、风险和参数，用户输入 yes 后才会复用现有 ActionRouter 执行单 action。每个 workflow action 和单 action 完成后都会自动进入一次 LLM/规则审核，并播报审核开始/结束；审核输入只包含当前 action 的结构化结果和必要诊断日志，不会把完整运行态 state_summary 交给大模型，避免跨步骤状态干扰判断；只有 workflow 审核通过才会把 action 记为 completed；如果审核建议停止或审核本身失败，流程会暂停并输出建议，等待用户决定是否 resume 重试当前 action。create-download-task 支持可选 PARENT_VERSION_NUMBER，非空时会在云下载接口中传入 parentVersionNumber，用于指定继承哪个版本的规则；默认空值不传，沿用正在使用的版本规则。poll-download-progress 和 poll-upgrade-progress 每次只查询一次进度，workflow 会按 POLL_INTERVAL_SEC、DOWNLOAD_POLL_MAX_ATTEMPTS、UPGRADE_POLL_MAX_ATTEMPTS 重复调用，并在每次返回后让 LLM/规则判断是否完成、播报进度；未完成时不会跳到下一个 action。verify-ip 用于应用启动后的健康检查，失败时 workflow 会按 VERIFY_INTERVAL_SEC 重试，最多 VERIFY_MAX_ATTEMPTS 次；默认约每 10 秒一次、最多 12 次，仍未通过才暂停。逐 IP action 失败时也会暂停，修复外部环境后输入 resume 会从当前 action 重试；如果确实需要回滚，使用 rollback [IP] 显式执行。llm test [文本] 可测试当前 LLM client 是否可用。--analyze-actions 仅控制详细审核结果是否写入 events。执行中可按 Ctrl+C 中断，chat 会保存当前 checkpoint 并把流程标记为 user_interrupted。set KEY=VALUE 和 load params <路径> 会把更新同步到当前运行 state、config.txt 和 checkpoint。chat 也支持 --llm-base-url / --llm-api-key / --llm-model / --llm-action-analysis-prompt-file、--mcp-config 和 --analyze-actions。

云下载相关参数：

PARENT_VERSION_NUMBER：可选，创建云下载任务时映射为接口参数 parentVersionNumber；默认空值不发送，表示继承正在使用的版本规则。

重试和进度查询相关参数：

POLL_INTERVAL_SEC：两次进度查询之间的等待秒数，默认 2。
DOWNLOAD_POLL_MAX_ATTEMPTS：云下载进度最大查询次数，默认 60。
UPGRADE_POLL_MAX_ATTEMPTS：单 IP 推送进度最大查询次数，默认 600。
VERIFY_INTERVAL_SEC：verify-ip 健康检查失败后的重试间隔秒数，默认 10。
VERIFY_MAX_ATTEMPTS：verify-ip 健康检查最大尝试次数，默认 12。

日志

Agent 默认写入运行日志到 logs/pam_deploy_agent.log。日志覆盖 CLI/chat 输入、LLM 请求和响应摘要、action 路由、脚本/MCP 调用、LangGraph 节点、checkpoint 保存、暂停/续跑等关键流程。日志会在本地时间每日 0 点后首次写入时自动切分，历史文件形如 pam_deploy_agent.log.YYYY-MM-DD，默认保留 14 个历史日切文件。日志会递归脱敏 CLIENT_SECRET、MCP_CLIENT_SECRET、token、Authorization、api_key、password 等字段，并截断长文本；chat 普通对话和日志分析的 <think> 内容会先过滤，不记录原始思考过程。

可通过环境变量调整日志位置、级别和保留策略：

export PAM_AGENT_LOG_FILE=logs/pam_deploy_agent.log
export PAM_AGENT_LOG_LEVEL=INFO
export PAM_AGENT_LOG_RETENTION_DAYS=14

调试 LLM 或 MCP 调用时可临时把 PAM_AGENT_LOG_LEVEL 设为 DEBUG。PAM_AGENT_LOG_RETENTION_DAYS 表示保留的历史日切文件数量，设为 0 时不自动清理历史切分文件；仍建议把日志目录放在受控位置。

预演：

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

如果 action 失败或审核阻断，流程会保存 checkpoint 并暂停；修复外部环境后可直接续跑，Agent 会从当前 action 重试：

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

如果需要回滚失败 IP，请显式执行 rollback。未传 --ip 时会使用当前失败 IP；执行完成后再用 resume 继续主流程。

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

也可以指定 IP 和停机策略：

python -m pam_deploy_graph.cli rollback --checkpoint runtime/checkpoints/demo.json --ip 192.168.1.10 --stop-first --note "人工决定回滚该 IP" --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

下一步建议

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

README.md Unescape Escape

opagent

PAM Deploy Agent

当前代码骨架

当前进度

LLM 配置

MCP Client 配置

使用方式

日志

下一步建议

README.md