161 lines
9.6 KiB
Markdown
161 lines
9.6 KiB
Markdown
---
|
||
name: pam-smart-deploy
|
||
description: 基于 PAM HOME/NODE 流程执行软件发布、下载、升级、回滚、健康检查和日志采集。用于用户要求按机场、版本、软件包部署 PAM 应用，并需要根据用户输入在 MCP 直连部署和 API 脚本部署（config.txt + deploy.sh / deploy.ps1 / deploy.bat）之间切换时。
|
||
---
|
||
|
||
# PAM智能部署 Skill
|
||
|
||
按用户意图在 `MCP` 与 `API脚本` 两种模式之间选择，并完成以下闭环：HOME 端建版与发布、NODE 端下载、在线工作站动态发现、逐台升级、启动、健康检测、日志下载、失败回滚、结果汇总。
|
||
|
||
## 模式选择
|
||
|
||
1. 先识别用户期望的执行入口。
|
||
- 用户明确说“用 MCP”“直接执行”“在线部署”“不要生成脚本”：使用 `MCP`。
|
||
- 用户明确说“用脚本”“生成脚本”“输出 sh / ps1 / bat / config”“离线执行”“批量复用”：使用 `API脚本`。
|
||
- 用户只说“帮我部署”，且当前环境存在可用的 PAM MCP：默认 `MCP`。
|
||
- 用户只说“给我部署脚本”或“不要直接动环境”：默认 `API脚本`，且默认只生成文件不执行。
|
||
2. 在两种模式都可行但用户意图不清时，只追问一个问题：`这次要直接通过 MCP 执行，还是生成/运行 API 脚本？`
|
||
3. 在开始执行前，明确告知本次采用的模式。
|
||
4. 用户已经明确指定模式后，不要静默切换。若当前模式不可用，先说明原因，再请求切换到另一种模式。
|
||
|
||
## 输入参数
|
||
|
||
先收集并标准化以下参数。脚本模式下，优先写入 `config.txt`。
|
||
|
||
| 规范字段 | 脚本字段 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `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` |
|
||
|
||
## 通用执行原则
|
||
|
||
1. 始终通过接口动态获取在线工作站 IP，不要要求用户手填 `TARGET_IPS`。
|
||
2. 用户若指定单个或部分 IP，先调用在线 IP 接口，再对返回列表做过滤，不要跳过在线性校验。
|
||
3. 任一步骤失败时，保留该步骤的原始响应、错误摘要和当前阶段名称。
|
||
4. `TOKEN` 失效时，自动重取一次并重试当前步骤一次。
|
||
5. 无论单机部署成功或失败，都下载对应日志。
|
||
6. 在线工作站列表为空时，终止部署并明确报告“无在线工作站匹配该模块”。
|
||
7. 用户要求“只生成脚本”“先给我文件”“不要执行”时，不要触发真实部署。
|
||
8. Windows 脚本模式默认优先 `deploy.ps1`，不要默认使用 `deploy.bat`。
|
||
9. 当前目录如果只有文档而没有真实脚本文件，先根据参考实现落地脚本，再决定是否执行。
|
||
10. `download-cloud` 只负责触发云下载任务；后续必须异步调用进度接口并持续展示状态/进度，直到成功、失败或超时。
|
||
11. 脚本模式下，每个关键方法执行前后都输出统一流程日志，至少包含 `[FLOW][START]`、`[FLOW][DONE]`、`[FLOW][FAIL]`。
|
||
12. 当检测到需要回滚时，脚本只标记 `PENDING_AGENT_CONFIRMATION(...)`，不得自动执行回滚；必须由 Agent 先向用户确认，再走手动回滚入口或直接调用回滚接口。
|
||
|
||
## 统一部署流程
|
||
|
||
两种模式都遵循同一业务顺序，差异只在“通过 MCP 直接执行”还是“通过脚本封装执行”。
|
||
|
||
| 阶段 | 操作 | 关键接口 |
|
||
| --- | --- | --- |
|
||
| 1 | 获取 Token | `POST {HOME_BASE_URL}/oauth/token` |
|
||
| 2.1 | 新建版本记录 | `POST {HOME_BASE_URL}/api/version/upgrade` |
|
||
| 2.2 | 上传软件包 | `POST {HOME_BASE_URL}/api/version/upgrade/upload` |
|
||
| 2.3 | 发布版本 | `PUT {HOME_BASE_URL}/api/version/upgrade/profile?...` |
|
||
| 3.1 | 获取 Node 地址 | `GET {HOME_BASE_URL}/api/mcp/airport/target-node?airportCode={airportCode}` |
|
||
| 3.2 | 获取在线工作站 IP | `GET {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/ips?...` |
|
||
| 3.3 | 下载软件包到 Node | `GET {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/download-cloud?...&timeOut=0` |
|
||
| 3.3b | 异步轮询并展示下载进度 | `GET {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/download-cloud/progress?...&versionNumber={versionNumber}` |
|
||
| 4.1 | 对每个 IP 执行升级 | `POST {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade?airportCode=...&targetIp=...` |
|
||
| 4.2 | 启动应用 | `POST {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/start-stop?airportCode=...&targetIp=...&runStart=true` |
|
||
| 4.3 | 健康检测 | `GET {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/verify?...` |
|
||
| 4.4 | 下载日志 | `GET {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/log-download?...` |
|
||
| 4.x | 失败回滚 | `POST {HOME_BASE_URL}/node-proxy/{airportCode}/api/mcp/version/upgrade/rollback` |
|
||
|
||
调用 NODE 侧接口时，始终携带：
|
||
|
||
- `Authorization: Bearer {TOKEN}`
|
||
- `Target-Node: {NODE_URL}`
|
||
- `airport-code: {airportCode}`，仅在下载到 NODE 等需要时携带
|
||
|
||
`download-cloud/progress` 响应优先读取以下字段：
|
||
|
||
- `msg`
|
||
- `step`
|
||
- `rateOfProgress`
|
||
|
||
当 `msg=success`、`step=DONE`、`rateOfProgress=100` 时，判定云下载完成；其中 `rateOfProgress` 就是下载进度值，应持续展示。
|
||
|
||
接口参数约定补充：
|
||
|
||
- `POST /api/mcp/version/upgrade` 的业务参数直接拼到 `?query`，不要放在 body 表单里。
|
||
- `POST /api/mcp/version/upgrade/start-stop` 的业务参数直接拼到 `?query`，不要放在 body 表单里。
|
||
- 启停接口参数名统一使用 `runStart`，不要再用 `runstart`。
|
||
- `download-cloud` 创建任务接口固定传 `timeOut=0`，表示任务创建成功后立即返回，再通过进度接口异步轮询，不要等待长超时。
|
||
|
||
## MCP 模式
|
||
|
||
1. 直接调用 PAM MCP 提供的能力完成上述流程，不生成本地脚本文件。
|
||
2. 若 MCP 暴露的是高层工具，确保其实际覆盖以下关键环节：建版、上传、发布、取 Node、取在线 IP、下载到 Node、逐台升级、启动、校验、日志下载、回滚。
|
||
3. 若 MCP 暴露的是通用 HTTP/REST 能力，则按“统一部署流程”中的接口顺序执行。
|
||
4. 在 `MCP` 模式下，仍然要输出逐台 IP 的结果，不要只给出整体成功或失败。
|
||
5. 用户若额外要求“顺手生成脚本留档”，可在部署完成后再生成脚本产物，但不要把脚本生成作为 MCP 主路径的前置步骤。
|
||
|
||
## API脚本模式
|
||
|
||
仅在脚本模式下读取并使用 `PAM智能部署 Shell & Bat 脚本实现.md.md` 作为参考实现。
|
||
|
||
1. 先把规范字段映射为脚本字段，并写入 `config.txt`。
|
||
2. 根据操作系统选择脚本入口。
|
||
- Linux / Mac：使用 `deploy.sh`。
|
||
- Windows：优先使用 `deploy.ps1`。
|
||
- `deploy.bat` 只在用户明确要求 Batch，或必须兼容旧入口，且确认特殊字符风险可接受时才使用。
|
||
3. Agent 优先通过脚本的 `action` 入口逐步调用能力方法，由 Skill 负责主流程编排；只有在用户明确要求“一键整条执行”时，才直接运行脚本主流程。
|
||
4. 若当前目录只有文档而没有真实脚本文件，先从参考实现中落地实际脚本文件，再执行。
|
||
5. 若用户要求“只生成脚本不执行”，完成以下产物后即可结束：
|
||
- `config.txt`
|
||
- `deploy.sh` 或 `deploy.ps1`
|
||
- 如用户明确要求，再额外提供 `deploy.bat`
|
||
6. 执行脚本后，读取脚本输出和 `./logs/` 目录内容，整理成最终报告。
|
||
|
||
## 失败处理与回滚
|
||
|
||
1. `Step 2` 或 `Step 3` 失败时，终止整个部署，并指出失败阶段。
|
||
2. `Step 4.1` 升级失败时，记录该 IP 失败原因，并把回滚状态标记为 `PENDING_AGENT_CONFIRMATION(stopFirst=false)`；Agent 需要先向用户确认是否回滚，再决定是否调用 `rollback`。
|
||
3. `Step 4.3` 健康检测失败时，记录失败原因，并把回滚状态标记为 `PENDING_AGENT_CONFIRMATION(stopFirst=true)`；若用户确认回滚，再执行以下顺序：
|
||
- 调用 `start-stop` 停止应用，`runStart=false`
|
||
- 调用 `rollback`
|
||
- 再次执行健康检测
|
||
- 下载回滚阶段日志
|
||
4. 最终报告必须写清楚回滚是“未执行”“待 Agent 确认”还是“已执行及结果”，不能只记录“已尝试回滚”。
|
||
|
||
## 输出要求
|
||
|
||
最终输出至少包含：
|
||
|
||
- 本次模式：`MCP` 或 `API脚本`
|
||
- 机场、应用、模块、版本
|
||
- 在线工作站总数、成功数、失败数
|
||
- 每个 IP 的状态、失败阶段、失败原因、回滚结果或 `PENDING_AGENT_CONFIRMATION(...)` 状态、日志位置或日志摘要
|
||
- 如果是脚本模式：实际生成或执行的文件名
|
||
|
||
可按以下结构输出：
|
||
|
||
```markdown
|
||
## PAM 智能部署报告
|
||
|
||
- 模式: MCP
|
||
- 机场: 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 | Health Check | Rollback Failed | logs/deploy_192.168.1.12.log |
|
||
```
|