agent_deply/packaging/README_packaged_agent.md

PAM 部署 Agent 解压即用包

这是打包后的 PAM 部署 Agent 使用说明。该包已包含 Python 运行时和 Python 依赖，目标 Linux 机器解压后即可运行。

目录说明

pam-deploy-agent-linux-x86_64/
  run.sh                 # 推荐入口，带中文帮助
  pam-deploy-agent       # PyInstaller 生成的可执行程序
  doc_scripts/
    deploy.sh            # Linux 脚本 action 入口
    config.txt.example   # 参数配置示例
    PAM_AUTO_DEPLY_SKILL.md
  prompts/
    action_review.txt    # 当前默认 action 审核提示词基线
  mcp_client.example.json
  README.md              # 当前说明
  LICENSE

doc_scripts 只保留运行必需文件，不包含项目设计文档、测试脚本或 Windows 脚本。prompts/action_review.txt 是当前默认 action 审核提示词的落地副本，便于复制后按需修改。

查看帮助

./run.sh --help

查看某个子命令的原始参数：

./run.sh chat --help
./run.sh run-deploy --help

发布包默认会优先使用 prompt_toolkit 增强输入，支持更稳定的退格、历史记录和补全；如果增强输入初始化失败，会自动降级到普通 input()。输出仍会在可用时使用 rich 做更清晰的文本展示。 action 失败或审核阻断后会保存 checkpoint 并暂停；修复外部环境后输入 resume 会从当前 action 重试。回滚不再属于主 workflow 自动分支，需要时在 chat 内输入 rollback [IP] 显式执行。 chat 会在执行前归一化并展示实际写入脚本配置的参数；script_only / hybrid_node_mcp 会先检查 ZIP_FILE_PATH 是否存在，避免脚本运行后才用默认路径失败。执行过程中每个 action 都会输出开始、完成或失败状态；每个 action 完成后还会自动进入一次 LLM/规则审核，并播报审核开始和审核结果；审核输入只包含当前 action 的结构化结果和必要诊断日志，不会把完整运行态 state_summary 交给大模型；只有审核通过才会把 action 记为 completed。create-download-task 支持可选 PARENT_VERSION_NUMBER，非空时会作为云下载接口参数 parentVersionNumber 传入；默认空值不发送，表示继承正在使用的版本规则。 poll-download-progress 和 poll-upgrade-progress 每次只查询一次进度，Agent workflow 会按 POLL_INTERVAL_SEC、DOWNLOAD_POLL_MAX_ATTEMPTS、UPGRADE_POLL_MAX_ATTEMPTS 重复调用，并在每次返回后交给 LLM/规则判断是否完成、向 chat 播报进度。verify-ip 健康检查失败时，Agent workflow 会按 VERIFY_INTERVAL_SEC 重试，最多 VERIFY_MAX_ATTEMPTS 次；默认每 10 秒一次、最多 12 次，仍未通过才暂停。

交互式使用

推荐先用 fake 策略验证流程：

./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json

如果要启用 MCP，先按真实 MCP server 修改 mcp_client.example.json，再使用 hybrid_node_mcp：

./run.sh chat \
  --config doc_scripts/config.txt.example \
  --strategy hybrid_node_mcp \
  --mcp-config mcp_client.example.json \
  --checkpoint runtime/checkpoints/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/demo.json
PAM> rollback
PAM> resume
PAM> exit

一次性命令

只做理解和计划生成，不执行：

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

预演 action 路由：

./run.sh preview --config doc_scripts/config.txt.example --strategy fake

执行 fake 完整部署流程：

./run.sh run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm

执行时把详细 action 审核结果写入 events：

./run.sh run-deploy \
  --config doc_scripts/config.txt.example \
  --strategy fake \
  --checkpoint runtime/checkpoints/demo.json \
  --analyze-actions \
  --confirm

使用 MCP 的完整部署：

./run.sh run-deploy \
  --config doc_scripts/config.txt.example \
  --strategy hybrid_node_mcp \
  --mcp-config mcp_client.example.json \
  --checkpoint runtime/checkpoints/demo.json \
  --confirm

失败后从断点重试：

./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm

需要回滚失败 IP 时显式执行 rollback，未指定 --ip 时会使用当前失败 IP：

./run.sh rollback --checkpoint runtime/checkpoints/demo.json --confirm
./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm

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

./run.sh rollback --checkpoint runtime/checkpoints/demo.json --ip 192.168.1.10 --stop-first --note "人工决定回滚该 IP" --confirm

LLM 配置

不配置 LLM 时会使用本地规则 fallback。真实 LLM 使用 OpenAI-compatible /chat/completions：

export PAM_LLM_BASE_URL="https://your-llm.example.com/v1"
export PAM_LLM_MODEL="your-model-name"

./run.sh analyze --config doc_scripts/config.txt.example --text "请分析这次部署"

如果服务需要鉴权，再补 PAM_LLM_API_KEY；如果不需要鉴权，可以不配置，程序不会发送 Authorization 请求头。

也可以用 CLI 参数：

./run.sh analyze \
  --config doc_scripts/config.txt.example \
  --text "请分析这次部署" \
  --llm-base-url https://your-llm.example.com/v1 \
  --llm-model your-model-name

如需自定义 action 审核提示词：

./run.sh 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

chat 内也可以热加载 LLM：

PAM> llm config base_url=https://your-llm.example.com/v1 api_key=your-api-key model=your-model-name
PAM> llm config action_analysis_prompt_file=prompts/action_review.txt
PAM> llm test 请返回一次连通性测试结果
PAM> llm action-analysis on
PAM> llm fallback

llm test [文本] 会使用当前 LLM client 做一次轻量意图识别调用，并输出 client 类型、intent、strategy 和 confidence，便于确认真实 LLM 或规则 fallback 是否正常加载。

日志

Agent 默认写入运行日志到 logs/pam_deploy_agent.log。日志覆盖 chat/CLI 输入、LLM 请求和响应摘要、action 路由、脚本/MCP 调用、LangGraph 节点、checkpoint 保存、暂停/续跑等关键流程。日志会在本地时间每日 0 点后首次写入时自动切分，历史文件形如 pam_deploy_agent.log.YYYY-MM-DD，默认保留 14 个历史日切文件。

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

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

日志会递归脱敏 CLIENT_SECRET、MCP_CLIENT_SECRET、token、Authorization、api_key、password 等字段，并截断长文本。PAM_AGENT_LOG_RETENTION_DAYS 表示保留的历史日切文件数量，设为 0 时不自动清理历史切分文件。checkpoint 仍会保存完整运行参数，请放在受控目录。

策略说明

• fake：全部使用 fake runner，不访问真实环境。
• script_only：全部 action 走脚本。
• hybrid_node_mcp：PAM_HOME 走脚本，PAM_NODE 走 MCP。

MCP 配置

--mcp-config 指向 MCP client JSON 配置文件。一般只需要配置 MCP server 地址和独立鉴权信息；Agent 会从 MCP server list_tools 自动发现可用 tool，不需要手写所有 action。

MCP token 获取方式与 HOME 一致，默认按 client_credentials POST 到 token 地址；但 MCP 使用独立的 token_url、client_id、client_secret。

{
  "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
}

字段说明：

• transport：支持 streamable_http、sse、stdio。
• server_url：MCP server 地址。
• auth.token_url：MCP token 获取地址。
• auth.client_id / auth.client_secret：MCP 独立账号密码。
• timeout_seconds：单次 tool 调用超时时间。
• action_tools：可选覆盖项。通常不需要配置；只有 server tool 名称不符合 get-online-ips、get_online_ips、pam_get_online_ips 这类约定时才需要。

注意事项

• 执行真实 action 前请确认配置文件中的 HOME_BASE_URL、CLIENT_ID、CLIENT_SECRET、AIRPORT_CODE、APP_NAME、MODULE_NAME、VERSION_NUMBER、ZIP_FILE_PATH。
• PARENT_VERSION_NUMBER 是云下载可选参数；非空时会传给 download-cloud 的 parentVersionNumber，空值不会发送。
• chat 中非内置命令默认交给当前 LLM 做普通对话，不会自动触发部署 workflow；普通对话优先流式展示，<think>...</think> 思考内容会被过滤；需要分析部署需求时请显式使用 analyze <需求>，完整部署仍需 run 并逐步确认。
• ask <问题> 可显式普通对话；log analyze <路径> [问题] [--tail N] [--max-bytes N] 默认只读取日志尾部并脱敏后交给 LLM，日志分析输出同样会过滤 <think> 内容。
• action propose <需求> 只展示 LLM 解析出的单 action 计划；action run <action> [ip=...] [KEY=VALUE...] 和 action run llm <需求> 会在用户输入 yes 后才执行单 action。
• 每个 action 完成后都会自动执行一次 LLM/规则审核；--analyze-actions 和 llm action-analysis on 只控制是否把详细审核结果写入 events。
• action 审核输入不包含完整运行态 state_summary，只包含当前 action 的结构化结果和必要诊断日志。
• poll-download-progress 和 poll-upgrade-progress 是单次进度查询 action，未完成时不会进入下一个 action；最大查询次数和间隔可通过 config.txt 或 chat set 热更新。
• verify-ip 会按 VERIFY_INTERVAL_SEC / VERIFY_MAX_ATTEMPTS 做健康检查重试，默认每 10 秒一次、最多 12 次。
• llm test [文本] 可测试当前 LLM client 是否可用。
• 如果审核建议停止、审核本身失败，或用户在执行中按下 Ctrl+C，流程都会保存 checkpoint 并进入暂停状态；后续可使用 resume 重试当前 action。
• set KEY=VALUE 和 load params <路径> 会热更新当前运行任务的参数，并回写运行中的 config.txt 和 checkpoint。
• checkpoint 会保存完整运行参数，请放在受控目录。
• hybrid_node_mcp、resume、rollback 如果需要执行 MCP action，请同时传入 --mcp-config。