039a3e1bdc
- 新增 PARENT_VERSION_NUMBER 可选配置，默认空值不传 - create-download-task 非空时透传 parentVersionNumber - 支持 LLM/规则从自然语言和 key=value 中抽取继承版本参数 - 将 rollback 接口参数从表单 body 改为 URL query 拼接 - 同步 README、打包说明和 Skill 文档 - 增加 MCP 参数透传、配置写入和 rollback query 调用测试
256 lines
10 KiB
Markdown
256 lines
10 KiB
Markdown
# PAM 部署 Agent 解压即用包
|
||
|
||
这是打包后的 PAM 部署 Agent 使用说明。该包已包含 Python 运行时和 Python 依赖，目标 Linux 机器解压后即可运行。
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
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 审核提示词的落地副本，便于复制后按需修改。
|
||
|
||
## 查看帮助
|
||
|
||
```bash
|
||
./run.sh --help
|
||
```
|
||
|
||
查看某个子命令的原始参数：
|
||
|
||
```bash
|
||
./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 策略验证流程：
|
||
|
||
```bash
|
||
./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`：
|
||
|
||
```bash
|
||
./run.sh chat \
|
||
--config doc_scripts/config.txt.example \
|
||
--strategy hybrid_node_mcp \
|
||
--mcp-config mcp_client.example.json \
|
||
--checkpoint runtime/checkpoints/demo.json
|
||
```
|
||
|
||
进入对话框后可输入：
|
||
|
||
```text
|
||
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> 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
|
||
```
|
||
|
||
## 一次性命令
|
||
|
||
只做理解和计划生成，不执行：
|
||
|
||
```bash
|
||
./run.sh analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境"
|
||
```
|
||
|
||
预演 action 路由：
|
||
|
||
```bash
|
||
./run.sh preview --config doc_scripts/config.txt.example --strategy fake
|
||
```
|
||
|
||
执行 fake 完整部署流程：
|
||
|
||
```bash
|
||
./run.sh run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm
|
||
```
|
||
|
||
执行时把详细 action 审核结果写入 `events`：
|
||
|
||
```bash
|
||
./run.sh run-deploy \
|
||
--config doc_scripts/config.txt.example \
|
||
--strategy fake \
|
||
--checkpoint runtime/checkpoints/demo.json \
|
||
--analyze-actions \
|
||
--confirm
|
||
```
|
||
|
||
使用 MCP 的完整部署：
|
||
|
||
```bash
|
||
./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
|
||
```
|
||
|
||
失败后从断点重试：
|
||
|
||
```bash
|
||
./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm
|
||
```
|
||
|
||
需要回滚失败 IP 时显式执行 rollback，未指定 `--ip` 时会使用当前失败 IP：
|
||
|
||
```bash
|
||
./run.sh rollback --checkpoint runtime/checkpoints/demo.json --confirm
|
||
./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm
|
||
```
|
||
|
||
也可以指定 IP 和停机策略：
|
||
|
||
```bash
|
||
./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`：
|
||
|
||
```bash
|
||
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 参数：
|
||
|
||
```bash
|
||
./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 审核提示词：
|
||
|
||
```bash
|
||
./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：
|
||
|
||
```text
|
||
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 保存、暂停/续跑等关键流程。
|
||
|
||
可通过环境变量调整日志位置和级别：
|
||
|
||
```bash
|
||
export PAM_AGENT_LOG_FILE=logs/pam_deploy_agent.log
|
||
export PAM_AGENT_LOG_LEVEL=INFO
|
||
```
|
||
|
||
日志会递归脱敏 `CLIENT_SECRET`、`MCP_CLIENT_SECRET`、token、Authorization、api_key、password 等字段，并截断长文本。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`。
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `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` 中输入 `你好`、`hello` 这类问候不会触发 LLM/结构化分析；需要分析部署需求时请直接描述部署任务，或显式使用 `analyze <需求>`。
|
||
- 每个 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`。
|