dark/agent_deply
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
agent_deply/doc_scripts/PAM_AUTO_DEPLY_SKILL.md
dark f90bccd0ad 1、增加执行间隔 
2、添加推送进度流程
2026-05-28 16:01:27 +08:00

751 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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脚本`
- `showUsageOnly`: 是否只说明现有脚本用法而不执行
- `userSpecifiedIps`: 用户指定的目标 IP 子集
- `allOrNothing`: 是否要求全有或全无
- `rollbackApproved`: 用户是否已确认回滚
- `osTarget`: 目标脚本入口环境
- `checkpointPath`: 检查点文件路径
- `resumeFromCheckpoint`: 是否按已有检查点断点续试
- `traceFilePath`: 当前部署统一复用的接口跟踪日志文件路径
- `stepIntervalSec`: 全局 action 与 action 之间的执行间隔
- `firstPollDelaySec`: 创建下载任务后，到首次轮询下载进度前的等待间隔
- `perIpStepIntervalSec`: 同一台 IP 内部步骤之间的执行间隔
- `perIpIntervalSec`: 一台 IP 完成后到下一台 IP 开始前的间隔
- `failurePauseSec`: 某步骤失败后进入下一分支前的等待间隔
推荐默认值：
- `stepIntervalSec = 2`
- `firstPollDelaySec = 2`
- `perIpStepIntervalSec = 1`
- `perIpIntervalSec = 3`
- `failurePauseSec = 0`
### 3.3 参数确认要求
在执行任何真实动作前，Agent 必须先输出一份“归一化参数确认单”，至少包含：
- 模式：`MCP` 或 `API脚本`
- 脚本入口：`deploy.sh` 或 `deploy.ps1`
- `HOME_BASE_URL`
- `airportCode`
- `applicationName`
- `moduleName`
- `versionNumber`
- `zipFilePath`
- `actionType`
- `timeOut`
- `logName`
- 用户指定 IP 子集（如有）
确认规则：
- 未确认，不执行任何真实 `action`
- 参数有歧义，先追问，不猜测
- 敏感字段如 `client_secret` 不明文回显，可显示为已提供/未提供
参数确认单建议模板：
```markdown
## 部署参数确认单
- 模式: API脚本
- 脚本入口: deploy.sh
- HOME_BASE_URL: https://pam.home.example.com
- AIRPORT_CODE: HET
- APP_NAME: PAM
- MODULE_NAME: Node
- VERSION_NUMBER: 2.0.5
- ZIP_FILE_PATH: /data/pkg/pam-2.0.5.zip
- ACTION_TYPE: FULL
- TIMEOUT: 120
- LOG_NAME: app.log
- 指定IP: 192.168.1.10, 192.168.1.11
- CLIENT_ID: 已提供
- 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 不执行真实部署，只说明限制和原因。
- `traceFilePath` 与间隔控制参数不写入 `config.txt`，由 Agent 在运行时持有并应用。
## 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`
- `poll-upgrade-progress`
- `start-ip`
- `verify-ip`
- `download-log`
17. 汇总每台 IP 的结果。
18. 若出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作，转入回滚确认分支。
19. 输出最终报告。
主流程补充规则：
1. 一次完整部署中的所有 action 调用，应复用同一个 `traceFilePath`，禁止每个 action 各自新建独立 trace 文件。
2. 全局 action 与下一 action 之间，按 `stepIntervalSec` 等待。
3. `create-download-task` 成功后，到首次 `poll-download-progress` 前，按 `firstPollDelaySec` 等待。
4. 同一台 IP 内部：
- `upgrade-ip -> poll-upgrade-progress`
- `poll-upgrade-progress -> start-ip`
- `start-ip -> verify-ip`
- `verify-ip -> download-log`
之间按 `perIpStepIntervalSec` 等待。
5. 当前一台 IP 处理完成后，到下一台 IP 开始前，按 `perIpIntervalSec` 等待。
6. 若某步骤失败后需要进入提示、确认或分支流程，可按 `failurePauseSec` 等待。
7. 若某个间隔值为 `0`，表示该层级不等待，直接进入下一动作。
### 4.2 主流程中的强制确认点
以下节点必须等待用户确认，不能自动越过：
1. 参数确认单确认前。
2. 出现回滚条件时。
3. 用户指定 IP 与在线 IP 过滤结果不一致，且会影响部署范围时。
4. 用户显式要求修改默认间隔策略时。
### 4.3 面向用户的流程播报要求
真实部署过程中，Agent 必须把部署过程显式展示给用户，至少满足以下要求：
1. 在开始执行任何真实 `action` 前，先输出本次部署阶段列表。
2. 在每个全局步骤开始前，告知用户“当前步骤”和“下一步将做什么”。
3. 在每个全局步骤成功后，告知用户该步骤已完成，并说明关键结果。
4. 在每个全局步骤失败后，立即告知用户失败阶段、失败原因和后续处理。
5. 在逐台 IP 处理时，必须告知当前正在处理哪一台 IP。
6. 在云下载进度轮询阶段，必须持续汇报当前进度，不能静默等待完成。
7. 若执行耗时较长，必须按阶段持续播报，不能等全部结束后一次性汇总。
8. 若进入回滚确认状态，必须明确告诉用户：
- 哪一台 IP 失败
- 失败阶段
- 建议是否回滚
- 是否需要 `stopFirst`
9. 若当前处于 action 间隔等待中，也必须告诉用户等待时长和下一步动作。
建议的阶段播报格式：
```markdown
## 当前部署进度
- 当前阶段: create-version
- 下一步: upload-package
- 当前结果: 成功
- 等待: 2 秒后继续
```
逐 IP 播报格式：
```markdown
## 当前 IP 处理进度
- 目标IP: 192.168.1.10
- 当前阶段: verify-ip
- 当前结果: 进行中
- 下一步: download-log
- 等待: 1 秒后继续
```
云下载进度播报格式：
```markdown
## 云下载进度
- 当前阶段: poll-download-progress
- step: DONE
- msg: success
- rateOfProgress: 100
```
### 4.4 检查点与断点续试
正式部署必须记录步骤检查点，以便后续失败时从断点续试，而不是默认从头重跑。
检查点规则：
1. 从参数确认通过后开始建立检查点。
2. 每个关键步骤成功后，立即更新检查点。
3. 检查点必须落地到文件，不只保存在对话上下文里。
4. 断点续试时，必须先读取检查点，再决定从哪一步继续。
5. 若当前请求参数与检查点中的核心参数不一致，禁止直接续试，必须先让用户确认是否重新开始。
建议的检查点文件：
- `./logs/deploy_checkpoint_<airportCode>_<applicationName>_<moduleName>_<versionNumber>.json`
检查点至少包含以下内容：
- 参数快照：
- `HOME_BASE_URL`
- `AIRPORT_CODE`
- `APP_NAME`
- `MODULE_NAME`
- `VERSION_NUMBER`
- `ZIP_FILE_PATH`
- `ACTION_TYPE`
- `LOG_NAME`
- 当前脚本入口：
- `deploy.sh` 或 `deploy.ps1`
- 已完成的全局步骤列表：
- `get-token`
- `create-version`
- `upload-package`
- `publish-version`
- `get-node-url`
- `get-online-ips`
- `create-download-task`
- `poll-download-progress`
- 关键中间结果：
- `hashCode`
- `nodeUrl`
- 在线 IP 列表
- 过滤后的目标 IP 列表
- 每台 IP 的执行状态：
- `upgrade-ip`
- `poll-upgrade-progress`
- `start`
- `verify`
- `download-log`
- `rollback-status`
- `log-file`
- 最后成功步骤
- 最后失败步骤
- 最后更新时间
断点续试规则：
1. 若 `get-token` 之前失败：
- 直接从 `get-token` 重试
2. 若 `create-version`、`upload-package`、`publish-version` 已成功：
- 默认不重复执行这些步骤
- 除非用户明确要求“重新开始”
3. 若 `create-download-task` 已成功但进度轮询失败：
- 默认从 `poll-download-progress` 继续
- 不重新创建下载任务
4. 若部分 IP 已成功完成：
- 默认跳过成功 IP
- 只继续未完成或失败的 IP
5. 若存在 `PENDING_AGENT_CONFIRMATION(...)`：
- 检查点中必须保留该状态
- 未得到用户确认前，不得自动继续后续动作
6. 若用户要求“从头重新开始”：
- 先明确说明将忽略现有检查点
- 再从第 1 步重新执行
检查点 JSON 建议模板：
```json
{
"mode": "API脚本",
"scriptEntry": "deploy.sh",
"checkpointPath": "./logs/deploy_checkpoint_HET_PAM_Node_2.0.5.json",
"resumeFromCheckpoint": true,
"params": {
"HOME_BASE_URL": "https://pam.home.example.com",
"AIRPORT_CODE": "HET",
"APP_NAME": "PAM",
"MODULE_NAME": "Node",
"VERSION_NUMBER": "2.0.5",
"ZIP_FILE_PATH": "/data/pkg/pam-2.0.5.zip",
"ACTION_TYPE": "FULL",
"LOG_NAME": "app.log"
},
"artifacts": {
"configPath": "./config.txt",
"hashCode": "43858bcf",
"nodeUrl": "https://pam-node.example.com"
},
"onlineIps": [
"192.168.1.10",
"192.168.1.11"
],
"targetIps": [
"192.168.1.10"
],
"completedGlobalSteps": [
"get-token",
"create-version",
"upload-package",
"publish-version",
"get-node-url",
"get-online-ips",
"create-download-task"
],
"ipStates": {
"192.168.1.10": {
"upgrade": "SUCCESS",
"start": "SUCCESS",
"verify": "PENDING",
"download-log": "PENDING",
"rollback-status": "ROLLBACK_NOT_RUN",
"log-file": ""
}
},
"lastSuccessStep": "create-download-task",
"lastFailedStep": "poll-download-progress",
"pendingConfirmation": "",
"updatedAt": "2026-05-21 10:30:00"
}
```
### 4.5 主流程逐步说明
| 步骤 | 目标 | 调用或动作 | 成功判定 | 失败处理 |
| ---- | ----------- | -------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
| 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 ...` | 返回 `RESULT=TASK_CREATED` | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=false)` |
| 16.2 | 轮询单 IP 推送进度 | `poll-upgrade-progress --ip ...` | `STEP=DONE` 或 `FINISH=true` 或 `MSG=success` 且 `RATE_OF_PROGRESS=100` | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=false)` |
| 16.3 | 启动单 IP | `start-ip --ip ...` | action 成功返回 | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=true)` |
| 16.4 | 校验单 IP | `verify-ip --ip ...` | 返回 `SUCCESS=true` | 记录失败，标记 `PENDING_AGENT_CONFIRMATION(stopFirst=true)` |
| 16.5 | 下载日志 | `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. 每个关键步骤成功后都要刷新检查点。
7. 每个关键步骤前后都要向用户播报进度。
8. Action 间隔等待也属于需要播报的执行状态，不能静默等待。
9. 脚本模式下统一输出流程日志：
- `[FLOW][START]`
- `[FLOW][DONE]`
- `[FLOW][FAIL]`
10. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
11. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
12. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。
## 6. 脚本 action 能力
本节仅定义允许调用的入口。除 `action` 入口外，其他脚本运行方式一律不允许用于真实部署。
### 6.1 Shell 入口
```bash
bash ./deploy.sh --config ./config.txt --action <action-name> [--ip 192.168.1.10] [--hash-code xxx] [--stop-first] [--trace-file ./logs/api_trace_xxx.log]
```
### 6.2 PowerShell 入口
```powershell
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action <ActionName> [-Ip 192.168.1.10] [-HashCode xxx] [-RollbackStopFirst]
```
### 6.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 创建推送任务，固定使用 `timeOut=0` | `--ip` / `-Ip` |
| `poll-upgrade-progress` | 轮询指定 IP 的推送进度 | `--ip` / `-Ip` |
| `start-ip` | 启动指定 IP 应用 | `--ip` / `-Ip` |
| `stop-ip` | 停止指定 IP 应用 | `--ip` / `-Ip` |
| `verify-ip` | 校验指定 IP | `--ip` / `-Ip` |
| `download-log` | 下载指定 IP 日志压缩包，返回 zip 文件路径 | `--ip` / `-Ip` |
| `rollback-ip` | 执行指定 IP 回滚 | `--ip` / `-Ip`，可带 `--stop-first` / `-RollbackStopFirst` |
### 6.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 失败，以退出码和错误日志为准
- 若返回 `TRACE_FILE=...`，后续 action 必须继续复用同一个路径
## 7. 分支流程与禁止事项
### 7.1 仅说明现有脚本用法分支
当用户意图不是“真实部署”，而是“查看现有脚本如何使用”时：
1. 只说明现有 `deploy.sh` / `deploy.ps1` / `deploy.bat` 的用途与调用方式。
2. 不执行任何真实 `action`。
3. 不生成、不修改任何脚本文件。
4. 明确告诉用户当前只是说明模式，不会执行真实部署。
### 7.2 参数确认后不执行分支
当用户只想确认参数、检查部署计划，但不执行真实部署时：
1. 读取并归一化参数。
2. 输出参数确认单。
3. 说明预计会调用的 action 顺序。
4. 若存在旧检查点，可同时说明可从哪个断点恢复。
5. 如用户已指定间隔策略，也要一并展示。
6. 不执行任何真实 `action`。
7. 不生成、不修改任何脚本文件。
8. 明确告诉用户当前只是预演流程，不会执行真实部署。
### 7.3 仅查看 Node 与在线 IP 分支
当用户只需要确认目标 Node 和在线工作站，而不是正式部署时：
1. 读取并归一化参数。
2. 输出参数确认单并等待确认。
3. 将参数写入 `config.txt`。
4. 初始化或更新检查点文件。
5. 初始化或指定统一的 `traceFilePath`。
6. 调用：
- `get-token`
- `get-node-url`
- `get-online-ips`
7. 输出 Node 地址、在线 IP 数量和 IP 列表。
8. 若需要间隔等待，也要向用户播报当前等待状态。
9. 不执行：
- `create-version`
- `upload-package`
- `publish-version`
- `create-download-task`
- `upgrade-ip`
### 7.4 手动回滚分支
当部署结果出现 `PENDING_AGENT_CONFIRMATION(...)` 且用户明确同意回滚时：
1. 再次向用户确认目标 IP 和 `stopFirst` 值。
2. 调用 `rollback-ip` action。
3. 如有需要，再调用：
- `verify-ip`
- `download-log`
4. 更新检查点中的 `rollback-status`。
5. 将回滚结果写入最终报告。
6. 在回滚执行前后都要向用户播报进度。
### 7.5 明确禁止的做法
以下做法在本 Skill 中一律禁止：
- 自动生成或修改部署脚本
- 自动生成或修改测试脚本
- 为了方便执行而切换到脚本主流程
- 未确认参数就直接执行真实 action
- 在出现回滚条件时自动执行回滚
- 在已有检查点的情况下，未经判断就从头重跑全部步骤
- 在正式主流程中调用 `download-cloud-to-node`
- 在真实部署过程中长时间静默执行，不向用户播报阶段进度
- 在一轮部署中让不同 action 各自生成不同的 trace 文件
- 擅自忽略用户指定的间隔控制参数
## 8. 失败处理与回滚
### 8.1 全局失败
以下步骤失败时，终止整次部署并报告失败阶段：
- 获取 Token
- 建版
- 上传
- 发布
- 获取 Node
- 获取在线 IP
- 创建云下载任务
- 云下载进度轮询失败或超时
### 8.2 单 IP 失败
单 IP 失败时：
- 必须记录失败阶段和失败原因
- 必须下载该 IP 日志
- 必须刷新该 IP 的检查点状态
- 不得自动执行回滚
### 8.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
```
## 9. 输出要求
最终报告至少包含：
- 本次模式：`MCP` 或 `API脚本`
- 实际入口：`MCP`、`deploy.sh --action ...` 或 `deploy.ps1 -Action ...`
- 机场、应用、模块、版本
- 在线工作站总数、成功数、失败数
- 每个 IP 的状态、失败阶段、失败原因
- 每个 IP 的回滚状态
- 日志压缩包路径
- 检查点文件路径
- Trace 文件路径
- 当前采用的间隔控制参数
- 是否从断点续试
- 若有 trace，则给出 trace 路径
建议结构：
```markdown
## PAM 智能部署报告
- 模式: API脚本
- 入口: deploy.sh --action
- 机场: HET
- 应用: PAM
- 模块: Node
- 版本: 2.0.5
- 总工作站数: 3
- 成功: 2
- 失败: 1
- 间隔控制:
- stepIntervalSec: 2
- firstPollDelaySec: 2
- perIpStepIntervalSec: 1
- perIpIntervalSec: 3
- failurePauseSec: 0
- Trace: ./logs/api_trace_HET_PAM_Node_2.0.5.log
| IP | 状态 | 失败阶段 | 回滚状态 | 日志压缩包 |
| --- | --- | --- | --- | --- |
| 192.168.1.10 | SUCCESS | - | - | logs/deploy_192.168.1.10.zip |
| 192.168.1.11 | SUCCESS | - | - | logs/deploy_192.168.1.11.zip |
| 192.168.1.12 | FAILED | VERIFY | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.zip |
```
更完整的最终报告模板：
```markdown
## PAM 智能部署报告
- 模式: API脚本
- 入口: deploy.sh --action
- 是否断点续试: 是
- 检查点文件: ./logs/deploy_checkpoint_HET_PAM_Node_2.0.5.json
- 机场: HET
- 应用: PAM
- 模块: Node
- 版本: 2.0.5
- 在线工作站总数: 3
- 目标工作站数: 2
- 成功: 1
- 失败: 1
- Trace: ./logs/api_trace_20260521_103000_1234.log
| IP | 状态 | 失败阶段 | 失败原因 | 回滚状态 | 日志 |
| --- | --- | --- | --- | --- | --- |
| 192.168.1.10 | SUCCESS | - | - | - | logs/deploy_192.168.1.10.log |
| 192.168.1.12 | FAILED | VERIFY | Health check failed | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.log |
## 检查点摘要
- 最后成功步骤: create-download-task
- 最后失败步骤: poll-download-progress
- 已完成全局步骤:
- get-token
- create-version
- upload-package
- publish-version
- get-node-url
- get-online-ips
- create-download-task
## 待确认事项
- 是否对 192.168.1.12 执行回滚
```
## 10. Agent 执行建议
1. 只能调用 `action`，不要调用脚本主流程。
2. 不要自动生成、补写、覆盖或修改脚本文件。
3. 在高风险动作前显式说明：
- 会创建版本
- 会上传包
- 会触发升级
- 回滚需要确认
4. 参数未确认前，不触发任何真实部署 action。
5. 用户只要求“生成脚本不执行”时，由于本 Skill 禁止自动生成或修改脚本，应直接说明限制，而不是自动产出脚本文件。
6. 如果 action 输出中出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作并请求确认。
7. 如果存在检查点，优先评估能否从断点续试，而不是默认从头执行。
8. 任何长耗时阶段都要主动播报进度，尤其是：
- `create-download-task`
- `poll-download-progress`
- 多 IP 循环处理
9. 间隔等待由 Agent 编排层负责控制，不要求脚本 action 自己管理 action 之间的等待。
10. 一轮部署中的所有 action，应复用同一个 `traceFilePath`。
Reference in New Issue View Git Blame Copy Permalink