---
name: pam-auto-deply
description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解用户需求、收集并确认参数、选择执行模式、编排主流程、控制回滚确认与最终汇总；由现有 deploy.sh / deploy.ps1 提供 action 能力执行建版、上传、发布、节点发现、云下载、升级、启停、校验、日志下载和手动回滚。禁止自动生成或修改脚本，禁止使用脚本主流程做部署。
---

# PAM_AUTO_DEPLY Skill

## 1. Skill 定位

本 Skill 面向 PAM 软件发布、下载、升级、校验、日志采集和回滚场景。

职责划分如下：

- `Skill` 负责主流程编排。
- `Agent` 负责理解用户意图、补齐参数、按步骤调用脚本 action、控制高风险交互。
- `deploy.sh` / `deploy.ps1` 负责执行具体动作。

默认原则：

- 只允许由 Skill 编排，逐步调用脚本 `action` 入口。
- 禁止使用脚本主流程做部署，包括 `bash ./deploy.sh --config ...` 和 `powershell -File .\deploy.ps1 -ConfigPath ...` 这类整条执行方式。
- 禁止自动生成、重建、覆盖或修改 `deploy.sh`、`deploy.ps1`、`deploy.bat`、`test_deploy.sh`、`test_deploy.ps1`、`test_deploy.bat`。
- 在任何真实调用前，必须先向用户展示归一化后的参数并得到确认。
- 回滚不得自动执行。脚本只能输出 `PENDING_AGENT_CONFIRMATION(...)`，必须由 Agent 先向用户确认。

## 2. 执行模式选择

### 2.1 模式判定

先识别用户期望的入口：

- 用户明确说“用 MCP”“直接在线执行”“不要生成脚本”：使用 `MCP`。
- 用户明确说“用脚本”“离线执行”：使用 `API脚本`。
- 用户只说“帮我部署”，且当前环境存在可用 MCP：优先 `MCP`。
- 用户只说“给我脚本”“生成脚本”“输出 sh / ps1 / bat / config”：直接说明本 Skill 禁止自动生成或修改脚本文件；如需仅提供现有脚本使用方式，可切到 `API脚本` 说明模式，但不执行真实部署。
- 用户只说“不要直接动环境”：优先 `API脚本`，但仅允许说明现有脚本调用方式，不自动产出脚本。

### 2.2 脚本模式优先级

在 `API脚本` 模式下，优先使用真实脚本文件：

- Linux / macOS / Git Bash：`deploy.sh`
- Windows：`deploy.ps1`
- `deploy.bat` 仅作为兼容入口，不作为默认主入口

硬约束：

- 只允许调用当前目录中已经存在的真实脚本文件。
- 禁止根据参考文档自动生成脚本。
- 禁止为适配当前任务而自动修改脚本实现。
- 如果目标脚本文件缺失、损坏或能力不足，必须停止并向用户说明，不得自行补写脚本。

## 3. 输入参数规范

### 3.1 必填业务参数

| 规范字段 | 脚本字段 | 必填 | 说明 |
| --- | --- | --- | --- |
| `HOME_BASE_URL` | `HOME_BASE_URL` | 是 | PAM HOME 基础地址 |
| `client_id` | `CLIENT_ID` | 是 | OAuth 客户端 ID |
| `client_secret` | `CLIENT_SECRET` | 是 | OAuth 客户端密钥 |
| `airportCode` | `AIRPORT_CODE` | 是 | 机场三字码 |
| `applicationName` | `APP_NAME` | 是 | 应用名 |
| `moduleName` | `MODULE_NAME` | 是 | 模块名 |
| `versionNumber` | `VERSION_NUMBER` | 是 | 目标版本号 |
| `zipFilePath` | `ZIP_FILE_PATH` | 是 | 本地软件包路径 |
| `actionType` | `ACTION_TYPE` | 否 | 升级类型，默认 `FULL` |
| `timeOut` | `TIMEOUT` | 否 | 接口级超时参数，默认 `120` |
| `logName` | `LOG_NAME` | 否 | 日志文件名，默认 `app.log` |

### 3.2 运行控制参数

以下参数不一定写入 `config.txt`，但 Skill 需要掌握：

- `mode`: `MCP` 或 `API脚本`
- `generateOnly`: 是否只生成文件不执行
- `userSpecifiedIps`: 用户指定的目标 IP 子集
- `allOrNothing`: 是否要求全有或全无
- `rollbackApproved`: 用户是否已确认回滚
- `osTarget`: 目标脚本入口环境

### 3.3 参数确认要求

在执行任何真实动作前，Agent 必须先输出一份“归一化参数确认单”，至少包含：

- 模式：`MCP` 或 `API脚本`
- 脚本入口：`deploy.sh` 或 `deploy.ps1`
- `HOME_BASE_URL`
- `airportCode`
- `applicationName`
- `moduleName`
- `versionNumber`
- `zipFilePath`
- `actionType`
- `timeOut`
- `logName`
- 用户指定 IP 子集（如有）

确认规则：

- 未确认，不执行任何真实 `action`
- 参数有歧义，先追问，不猜测
- 敏感字段如 `client_secret` 不明文回显，可显示为已提供/未提供

### 3.4 参数落地规则

参数确认完成后，Agent 应先将业务参数写入 `config.txt`，再调用脚本 `action`。

规则如下：

- `config.txt` 承载稳定业务参数：
  - `HOME_BASE_URL`
  - `CLIENT_ID`
  - `CLIENT_SECRET`
  - `AIRPORT_CODE`
  - `APP_NAME`
  - `MODULE_NAME`
  - `VERSION_NUMBER`
  - `ZIP_FILE_PATH`
  - `ACTION_TYPE`
  - `TIMEOUT`
  - `LOG_NAME`
- 命令行只传 action 级控制参数：
  - `--action` / `-Action`
  - `--ip` / `-Ip`
  - `--hash-code` / `-HashCode`
  - `--stop-first` / `-RollbackStopFirst`
- 不要把整套业务参数直接拼接到命令行。
- `client_secret` 等敏感字段不得通过命令行透传。
- 如果用户明确要求“不落地配置文件”，则本 Skill 不执行真实部署，只说明限制和原因。

## 4. 主流程（硬约束）

### 4.1 正式部署主流程

在 `API脚本` 模式下，真实部署必须严格按以下顺序执行：

1. 读取用户输入并识别本次意图是否为真实部署。
2. 归一化业务参数与控制参数。
3. 输出参数确认单，并等待用户确认。
4. 检查现有脚本文件是否存在且可用：
   - `deploy.sh`
   - `deploy.ps1`
5. 选择脚本入口：
   - Linux / macOS / Git Bash 用 `deploy.sh`
   - Windows 用 `deploy.ps1`
6. 将确认后的业务参数写入 `config.txt`。
7. 调用 `get-token`。
8. 调用 `create-version`。
9. 调用 `upload-package`。
10. 调用 `publish-version`。
11. 调用 `get-node-url`。
12. 调用 `get-online-ips`。
13. 若用户指定了目标 IP，则基于在线 IP 列表做过滤。
14. 调用 `create-download-task`。
15. 调用 `poll-download-progress`，直到下载完成、失败或超时。
16. 按在线 IP 或过滤后的目标 IP 列表逐台执行：
   - `upgrade-ip`
   - `start-ip`
   - `verify-ip`
   - `download-log`
17. 汇总每台 IP 的结果。
18. 若出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作，转入回滚确认分支。
19. 输出最终报告。

### 4.2 主流程中的强制确认点

以下节点必须等待用户确认，不能自动越过：

1. 参数确认单确认前。
2. 出现回滚条件时。
3. 用户指定 IP 与在线 IP 过滤结果不一致，且会影响部署范围时。

### 4.3 主流程逐步说明

| 步骤 | 目标 | 调用或动作 | 成功判定 | 失败处理 |
| --- | --- | --- | --- | --- |
| 1 | 识别意图 | 判断是否为真实部署 | 意图明确为真实部署 | 若不是，转入分支流程，不执行真实部署 |
| 2 | 归一化参数 | 整理用户输入、补齐默认值 | 参数结构完整 | 参数不清时先追问，不猜测 |
| 3 | 参数确认 | 输出参数确认单 | 用户明确确认 | 未确认前停止 |
| 4 | 检查脚本 | 检查 `deploy.sh` / `deploy.ps1` 是否存在且可用 | 至少存在一个与当前 OS 对应的脚本入口 | 缺失或不可用时停止并说明 |
| 5 | 选择入口 | 根据 OS 选择 `deploy.sh` 或 `deploy.ps1` | 入口唯一且明确 | 入口不明确时停止 |
| 6 | 落地配置 | 将稳定业务参数写入 `config.txt` | `config.txt` 已生成且内容与确认单一致 | 写入失败则停止 |
| 7 | 获取 Token | `get-token` | 返回 `TOKEN=...` 且非空 | 停止并报告 `TOKEN` 阶段失败 |
| 8 | 创建版本 | `create-version` | 返回 `RESULT=OK` | 停止并报告 `CREATE_VERSION` 失败 |
| 9 | 上传软件包 | `upload-package` | 返回 `HASH_CODE=...` 且非空 | 停止并报告 `UPLOAD_PACKAGE` 失败 |
| 10 | 发布版本 | `publish-version --hash-code ...` | 返回 `RESULT=OK` | 停止并报告 `PUBLISH_VERSION` 失败 |
| 11 | 获取 Node | `get-node-url` | 返回 `NODE_URL=...` 且非空 | 停止并报告 `GET_NODE_URL` 失败 |
| 12 | 获取在线 IP | `get-online-ips` | 返回 `COUNT>0` 且有 `IP=...` 行 | 停止并报告 `GET_ONLINE_IPS` 失败 |
| 13 | 过滤目标 IP | 按用户指定 IP 与在线 IP 交集过滤 | 过滤结果明确 | 过滤后为空时停止；范围变化需确认 |
| 14 | 创建云下载任务 | `create-download-task` | 返回 `RESULT=TASK_CREATED` | 停止并报告 `CREATE_DOWNLOAD_TASK` 失败 |
| 15 | 轮询下载进度 | `poll-download-progress` | `STEP=DONE` 或 `MSG=success` 且 `RATE_OF_PROGRESS=100` | 停止并报告 `POLL_DOWNLOAD_PROGRESS` 失败或超时 |
| 16.1 | 升级单 IP | `upgrade-ip --ip ...` | 返回 `SUCCESS=true` | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=false)` |
| 16.2 | 启动单 IP | `start-ip --ip ...` | action 成功返回 | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=true)` |
| 16.3 | 校验单 IP | `verify-ip --ip ...` | 返回 `SUCCESS=true` | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=true)` |
| 16.4 | 下载日志 | `download-log --ip ...` | 返回 `LOG_FILE=...` | 记录日志下载失败，但不覆盖原主失败原因 |
| 17 | 汇总结果 | 汇总每台 IP 的阶段、失败原因、回滚状态、日志路径 | 报告内容完整 | 若汇总失败，至少保留原始 action 输出 |
| 18 | 回滚确认分支 | 发现 `PENDING_AGENT_CONFIRMATION(...)` 时进入回滚确认 | 用户明确是否回滚 | 未确认时停止，不自动回滚 |
| 19 | 最终报告 | 输出最终报告 | 报告包含模式、入口、阶段结果、日志、回滚状态 | 不省略失败细节 |

## 5. 通用执行原则

1. 始终通过接口动态获取在线工作站 IP，不要求用户手填 `TARGET_IPS`。
2. 用户若指定部分 IP，必须先查在线 IP，再做过滤。
3. 所有关键步骤都要保留原始响应、错误摘要、阶段名。
4. 单机成功或失败都要下载对应日志。
5. 执行前必须先完成参数确认。
6. 脚本模式下统一输出流程日志：
   - `[FLOW][START]`
   - `[FLOW][DONE]`
   - `[FLOW][FAIL]`
7. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
8. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
9. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。

## 6. 接口约定

### 6.1 基础约定

- Node 侧路径统一使用 `node-proxy`
- Node 侧接口始终携带：
  - `Authorization: Bearer {TOKEN}`
  - `Target-Node: {NODE_URL}`
- `airport-code: {airportCode}` 仅在下载到 Node 等需要时携带

### 6.2 云下载接口

- 创建任务接口：
  - `GET /api/mcp/version/upgrade/download-cloud`
  - 固定传 `timeOut=0`
  - 含义是“任务创建成功立即返回”，不要等待长超时
- 进度接口：
  - `GET /api/mcp/version/upgrade/download-cloud/progress?...&versionNumber={versionNumber}`
  - 完成判定优先看：
    - `msg`
    - `step`
    - `rateOfProgress`
  - 当 `msg=success`、`step=DONE`、`rateOfProgress=100` 时，判定下载完成

### 6.3 升级与启停接口

- `POST /api/mcp/version/upgrade`
  - 参数直接拼到 URL query
  - 不使用 body 表单
- `POST /api/mcp/version/upgrade/start-stop`
  - 参数直接拼到 URL query
  - 不使用 body 表单
  - 参数名统一使用 `runStart`

## 7. 脚本 action 能力

本节仅定义允许调用的入口。除 `action` 入口外，其他脚本运行方式一律不允许用于真实部署。

### 7.1 Shell 入口

```bash
bash ./deploy.sh --config ./config.txt --action <action-name> [--ip 192.168.1.10] [--hash-code xxx] [--stop-first]
```

### 7.2 PowerShell 入口

```powershell
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action <ActionName> [-Ip 192.168.1.10] [-HashCode xxx] [-RollbackStopFirst]
```

### 7.3 可用 action

| action | 用途 | 额外参数 |
| --- | --- | --- |
| `get-token` | 获取访问令牌 | 无 |
| `create-version` | 新建版本记录 | 无 |
| `upload-package` | 上传软件包 | 无 |
| `publish-version` | 发布版本 | `--hash-code` / `-HashCode` |
| `get-node-url` | 获取目标 Node 地址 | 无 |
| `get-online-ips` | 获取在线工作站 IP 列表 | 无 |
| `create-download-task` | 创建云下载任务 | 无 |
| `poll-download-progress` | 轮询下载进度 | 无 |
| `download-cloud-to-node` | 创建下载任务并轮询至完成 | 无 |
| `upgrade-ip` | 升级指定 IP | `--ip` / `-Ip` |
| `start-ip` | 启动指定 IP 应用 | `--ip` / `-Ip` |
| `stop-ip` | 停止指定 IP 应用 | `--ip` / `-Ip` |
| `verify-ip` | 校验指定 IP | `--ip` / `-Ip` |
| `download-log` | 下载指定 IP 日志 | `--ip` / `-Ip` |
| `rollback-ip` | 执行指定 IP 回滚 | `--ip` / `-Ip`，可带 `--stop-first` / `-RollbackStopFirst` |

### 7.4 action 输出约定

典型返回为：

```text
ACTION=get-online-ips
COUNT=2
IP=192.168.1.10
IP=192.168.1.11
```

Agent 读取时：

- 优先解析 `key=value`
- 将 `[INFO]`、`[WARN]`、`[FLOW]` 视为辅助日志
- 若 action 失败，以退出码和错误日志为准

## 8. 分支流程与禁止事项

### 8.1 仅说明现有脚本用法分支

当用户意图不是“真实部署”，而是“查看现有脚本如何使用”时：

1. 只说明现有 `deploy.sh` / `deploy.ps1` / `deploy.bat` 的用途与调用方式。
2. 不执行任何真实 `action`。
3. 不生成、不修改任何脚本文件。

### 8.2 参数确认后不执行分支

当用户只想确认参数、检查部署计划，但不执行真实部署时：

1. 读取并归一化参数。
2. 输出参数确认单。
3. 说明预计会调用的 action 顺序。
4. 不执行任何真实 `action`。
5. 不生成、不修改任何脚本文件。

### 8.3 仅查看 Node 与在线 IP 分支

当用户只需要确认目标 Node 和在线工作站，而不是正式部署时：

1. 读取并归一化参数。
2. 输出参数确认单并等待确认。
3. 将参数写入 `config.txt`。
4. 调用：
   - `get-token`
   - `get-node-url`
   - `get-online-ips`
5. 输出 Node 地址、在线 IP 数量和 IP 列表。
6. 不执行：
   - `create-version`
   - `upload-package`
   - `publish-version`
   - `create-download-task`
   - `upgrade-ip`

### 8.4 手动回滚分支

当部署结果出现 `PENDING_AGENT_CONFIRMATION(...)` 且用户明确同意回滚时：

1. 再次向用户确认目标 IP 和 `stopFirst` 值。
2. 调用 `rollback-ip` action。
3. 如有需要，再调用：
   - `verify-ip`
   - `download-log`
4. 将回滚结果写入最终报告。

### 8.5 明确禁止的做法

以下做法在本 Skill 中一律禁止：

- 自动生成或修改部署脚本
- 自动生成或修改测试脚本
- 为了方便执行而切换到脚本主流程
- 未确认参数就直接执行真实 action
- 在出现回滚条件时自动执行回滚

## 9. 失败处理与回滚

### 9.1 全局失败

以下步骤失败时，终止整次部署并报告失败阶段：

- 获取 Token
- 建版
- 上传
- 发布
- 获取 Node
- 获取在线 IP
- 创建云下载任务
- 云下载进度轮询失败或超时

### 9.2 单 IP 失败

单 IP 失败时：

- 必须记录失败阶段和失败原因
- 必须下载该 IP 日志
- 不得自动执行回滚

### 9.3 回滚规则

回滚只允许在 Agent 与用户确认后执行。

回滚状态有三类：

- `ROLLBACK_NOT_RUN`
- `PENDING_AGENT_CONFIRMATION(stopFirst=true|false)`
- 真正执行后的结果：
  - `ROLLBACK_SUCCESS`
  - `ROLLBACK_FAILED`
  - `ROLLBACK_REQUEST_FAILED`
  - `ROLLBACK_VERIFY_FAILED`

推荐确认逻辑：

- 升级失败：建议回滚，`stopFirst=false`
- 启动失败：建议回滚，`stopFirst=true`
- 校验失败：建议回滚，`stopFirst=true`

手动回滚命令示例：

```bash
bash ./deploy.sh --config ./config.txt --action rollback-ip --ip 192.168.1.10 --stop-first
```

```powershell
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 192.168.1.10 -RollbackStopFirst
```

## 10. 输出要求

最终报告至少包含：

- 本次模式：`MCP` 或 `API脚本`
- 实际入口：`MCP`、`deploy.sh --action ...` 或 `deploy.ps1 -Action ...`
- 机场、应用、模块、版本
- 在线工作站总数、成功数、失败数
- 每个 IP 的状态、失败阶段、失败原因
- 每个 IP 的回滚状态
- 日志路径
- 若有 trace，则给出 trace 路径

建议结构：

```markdown
## PAM 智能部署报告

- 模式: API脚本
- 入口: deploy.sh --action
- 机场: HET
- 应用: PAM
- 模块: Node
- 版本: 2.0.5
- 总工作站数: 3
- 成功: 2
- 失败: 1

| IP | 状态 | 失败阶段 | 回滚状态 | 日志 |
| --- | --- | --- | --- | --- |
| 192.168.1.10 | SUCCESS | - | - | logs/deploy_192.168.1.10.log |
| 192.168.1.11 | SUCCESS | - | - | logs/deploy_192.168.1.11.log |
| 192.168.1.12 | FAILED | VERIFY | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.log |
```

## 11. Agent 执行建议

1. 只能调用 `action`，不要调用脚本主流程。
2. 不要自动生成、补写、覆盖或修改脚本文件。
3. 在高风险动作前显式说明：
   - 会创建版本
   - 会上传包
   - 会触发升级
   - 回滚需要确认
4. 参数未确认前，不触发任何真实部署 action。
5. 用户只要求“生成脚本不执行”时，由于本 Skill 禁止自动生成或修改脚本，应直接说明限制，而不是自动产出脚本文件。
6. 如果 action 输出中出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作并请求确认。