agent_deply/packaging/README_packaged_agent.md

# 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
```

发布包默认使用普通文本输入，避免 PyInstaller 环境下 `prompt_toolkit` 兼容性问题；输出仍会在可用时使用 `rich` 做更清晰的文本展示。
chat 内的失败回滚确认由 LangGraph interrupt 托管；执行停在确认点后，输入 `approve` 或 `reject [原因]` 会恢复同一个图线程继续处理。
chat 会在执行前归一化并展示实际写入脚本配置的参数；`script_only` / `hybrid_node_mcp` 会先检查 `ZIP_FILE_PATH` 是否存在，避免脚本运行后才用默认路径失败。执行过程中每个 action 都会输出开始、完成或失败状态；每个 action 完成后还会自动进入一次 LLM/规则审核，并播报审核开始和审核结果。

## 交互式使用

推荐先用 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 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> approve
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 confirm --checkpoint runtime/checkpoints/demo.json --decision approve --confirm
```

`confirm` 会通过 LangGraph interrupt resume 处理确认，并在确认后继续执行后续图节点；进程中断或需要再次续跑时，再使用 `resume`。

拒绝回滚：

```bash
./run.sh confirm --checkpoint runtime/checkpoints/demo.json --decision reject --note "人工决定暂不回滚" --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 action-analysis on
PAM> llm fallback
```

## 策略说明

- `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`。
- `chat` 中输入 `你好`、`hello` 这类问候不会触发 LLM/结构化分析；需要分析部署需求时请直接描述部署任务，或显式使用 `analyze <需求>`。
- 每个 action 完成后都会自动执行一次 LLM/规则审核；`--analyze-actions` 和 `llm action-analysis on` 只控制是否把详细审核结果写入 `events`。
- 如果审核建议停止、审核本身失败，或用户在执行中按下 `Ctrl+C`，流程都会保存 checkpoint 并进入暂停状态；后续可使用 `resume` 继续。
- `set KEY=VALUE` 和 `load params <路径>` 会热更新当前运行任务的参数，并回写运行中的 `config.txt` 和 checkpoint。
- `checkpoint` 会保存完整运行参数，请放在受控目录。
- `hybrid_node_mcp`、`resume`、`confirm` 如果需要执行 MCP action，请同时传入 `--mcp-config`。