--- 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`。 - 在任何真实调用前，必须先向用户展示归一化后的参数并得到确认。 - 在真实部署执行过程中，必须持续向用户展示当前阶段、下一步动作和阶段结果，禁止长时间静默执行。 - 回滚不得自动执行；主 workflow 失败后只暂停在当前 action。需要回滚时，必须由用户显式输入 `rollback [IP]` 或直接调用 `rollback-ip` action。 ## 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` | | `pollIntervalSec` | `POLL_INTERVAL_SEC` | 否 | 两次进度查询间隔，默认 `2` 秒 | | `downloadPollMaxAttempts` | `DOWNLOAD_POLL_MAX_ATTEMPTS` | 否 | 云下载进度最大查询次数，默认 `60` | | `upgradePollMaxAttempts` | `UPGRADE_POLL_MAX_ATTEMPTS` | 否 | 单 IP 推送进度最大查询次数，默认 `600` | | `verifyIntervalSec` | `VERIFY_INTERVAL_SEC` | 否 | `verify-ip` 健康检查失败后的重试间隔，默认 `10` 秒 | | `verifyMaxAttempts` | `VERIFY_MAX_ATTEMPTS` | 否 | `verify-ip` 健康检查最大尝试次数，默认 `12` | ### 3.2 运行控制参数 以下参数不一定写入 `config.txt`，但 Skill 需要掌握： - `mode`: `MCP` 或 `API脚本` - `showUsageOnly`: 是否只说明现有脚本用法而不执行 - `userSpecifiedIps`: 用户指定的目标 IP 子集 - `allOrNothing`: 是否要求全有或全无 - `rollbackApproved`: 用户是否已明确要求执行回滚 - `osTarget`: 目标脚本入口环境 - `checkpointPath`: 检查点文件路径 - `resumeFromCheckpoint`: 是否按已有检查点断点续试 - `traceFilePath`: 当前部署统一复用的接口跟踪日志文件路径 - `stepIntervalSec`: 全局 action 与 action 之间的执行间隔 - `perIpStepIntervalSec`: 同一台 IP 内部步骤之间的执行间隔 - `perIpIntervalSec`: 一台 IP 完成后到下一台 IP 开始前的间隔 - `failurePauseSec`: 某步骤失败后进入下一分支前的等待间隔 推荐默认值： - `stepIntervalSec = 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` - `POLL_INTERVAL_SEC` - `DOWNLOAD_POLL_MAX_ATTEMPTS` - `UPGRADE_POLL_MAX_ATTEMPTS` - `VERIFY_INTERVAL_SEC` - `VERIFY_MAX_ATTEMPTS` - 命令行只传 action 级控制参数： - `--action` / `-Action` - `--ip` / `-Ip` - `--hash-code` / `-HashCode` - `--stop-first` / `-RollbackStopFirst` - 不要把整套业务参数直接拼接到命令行。 - `client_secret` 等敏感字段不得通过命令行透传。 - 如果用户明确要求“不落地配置文件”，则本 Skill 不执行真实部署，只说明限制和原因。 - `traceFilePath` 不写入 `config.txt`，由 Agent 在运行时持有并应用。 - 进度查询和健康检查重试参数写入 `config.txt`，由 Agent workflow 和脚本调试流程共同读取。 ## 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` 单次查询进度；每次返回后交给 LLM/规则判断，直到下载完成、失败或达到最大查询次数。 16. 按在线 IP 或过滤后的目标 IP 列表逐台执行： - `upgrade-ip` - 重复调用 `poll-upgrade-progress` 单次查询进度；每次返回后交给 LLM/规则判断，直到推送完成、失败或达到最大查询次数 - `start-ip` - 重复调用 `verify-ip` 健康检查；`SUCCESS=false` 时按 `VERIFY_INTERVAL_SEC` 等待后重试，直到成功或达到 `VERIFY_MAX_ATTEMPTS` - `download-log` 17. 汇总每台 IP 的结果。 18. 若 action 失败、LLM/规则审核要求停止，或出现 legacy `PENDING_AGENT_CONFIRMATION(...)`，暂停在当前 action 并输出建议。 19. 输出最终报告；需要回滚时，等待用户显式执行 `rollback [IP]`。 主流程补充规则： 1. 一次完整部署中的所有 action 调用，应复用同一个 `traceFilePath`，禁止每个 action 各自新建独立 trace 文件。 2. 全局 action 与下一 action 之间，按 `stepIntervalSec` 等待。 3. `create-download-task` 成功后，直接进入 `poll-download-progress`；未完成时按 `POLL_INTERVAL_SEC` 等待后再次查询当前 action。 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`，表示该层级不等待，直接进入下一动作。 8. `poll-download-progress` 和 `poll-upgrade-progress` 的脚本 action 只执行一次进度查询；正式 workflow 的循环、checkpoint、LLM 判断和进度播报由 Agent Runtime 负责。 9. `verify-ip` 失败但未达到 `VERIFY_MAX_ATTEMPTS` 时，不进入 `download-log`，也不把当前 action 记为 completed；正式 workflow 会播报健康检查进度、保存 checkpoint，并按 `VERIFY_INTERVAL_SEC` 重试当前 action。 ### 4.2 主流程中的强制确认点 以下节点必须等待用户确认，不能自动越过： 1. 参数确认单确认前。 2. 执行 `rollback [IP]` 或 `rollback-ip` 前。 3. 用户指定 IP 与在线 IP 过滤结果不一致，且会影响部署范围时。 4. 用户显式要求修改默认间隔策略时。 ### 4.3 面向用户的流程播报要求 真实部署过程中，Agent 必须把部署过程显式展示给用户，至少满足以下要求： 1. 在开始执行任何真实 `action` 前，先输出本次部署阶段列表。 2. 在每个全局步骤开始前，告知用户“当前步骤”和“下一步将做什么”。 3. 在每个全局步骤成功后，告知用户该步骤已完成，并说明关键结果。 4. 在每个全局步骤失败后，立即告知用户失败阶段、失败原因和后续处理。 5. 在逐台 IP 处理时，必须告知当前正在处理哪一台 IP。 6. 在云下载和单 IP 推送进度查询阶段，每次 `poll-*` 返回后都必须汇报当前进度，不能静默等待完成。 7. 在 `verify-ip` 健康检查阶段，每次未通过都必须播报当前检查次数、最大次数和返回信息，不能静默等待应用启动。 8. 若执行耗时较长，必须按阶段持续播报，不能等全部结束后一次性汇总。 9. 若失败后建议回滚，必须明确告诉用户： - 哪一台 IP 失败 - 失败阶段 - 建议是否回滚 - 是否需要 `stopFirst` 10. 若当前处于 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____.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. 若存在失败暂停或 legacy `PENDING_AGENT_CONFIRMATION(...)`： - 检查点中必须保留失败阶段、失败原因和审核建议 - 修复后 `resume` 默认从当前失败 action 重试 - 需要回滚时必须由用户显式执行 `rollback [IP]` 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` | LLM/规则判断 `progress_complete=true`；或 `STEP=DONE` / `MSG=success` 且 `RATE_OF_PROGRESS=100` | 停止并报告 `POLL_DOWNLOAD_PROGRESS` 失败或超时 | | 16.1 | 创建单 IP 推送任务 | `upgrade-ip --ip ...` | 返回 `RESULT=TASK_CREATED` | 暂停在当前 action，修复后 `resume` 重试；需要回滚时显式执行 rollback | | 16.2 | 查询单 IP 推送进度 | 重复调用单次 `poll-upgrade-progress --ip ...` | LLM/规则判断 `progress_complete=true`；或 `STEP=DONE` / `FINISH=true` / `MSG=success` 且 `RATE_OF_PROGRESS=100` | 暂停在当前 action，修复后 `resume` 重试；需要回滚时显式执行 rollback | | 16.3 | 启动单 IP | `start-ip --ip ...` | action 成功返回 | 暂停在当前 action，修复后 `resume` 重试；需要回滚时显式执行 rollback | | 16.4 | 校验单 IP | 重复调用单次 `verify-ip --ip ...` | 返回 `SUCCESS=true` | 按 `VERIFY_INTERVAL_SEC` 重试，达到 `VERIFY_MAX_ATTEMPTS` 后仍失败才暂停在当前 action；需要回滚时显式执行 rollback | | 16.5 | 下载日志 | `download-log --ip ...` | 返回 `LOG_FILE=...` | 记录日志下载失败，但不覆盖原主失败原因 | | 17 | 汇总结果 | 汇总每台 IP 的阶段、失败原因、回滚状态、日志路径 | 报告内容完整 | 若汇总失败，至少保留原始 action 输出 | | 18 | 失败暂停或显式回滚 | 失败后默认停在当前 action；用户输入 `rollback [IP]` 后才执行回滚 | 用户明确要求回滚或修复后 `resume` | 未显式要求回滚时不自动回滚 | | 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. 遇到需要回滚的场景，Agent 只能提示风险和建议；不得自动回滚，必须等待用户显式执行 rollback。 ## 6. 脚本 action 能力 本节仅定义允许调用的入口。除 `action` 入口外，其他脚本运行方式一律不允许用于真实部署。 ### 6.1 Shell 入口 ```bash bash ./deploy.sh --config ./config.txt --action [--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 [-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` | 单次查询下载进度；是否继续查询由 Agent workflow 和 LLM/规则决定 | 无 | | `download-cloud-to-node` | 创建下载任务并轮询至完成，仅调试使用，不得进入正式主流程 | 无 | | `upgrade-ip` | 为指定 IP 创建推送任务，固定使用 `timeOut=0` | `--ip` / `-Ip` | | `poll-upgrade-progress` | 单次查询指定 IP 的推送进度；是否继续查询由 Agent workflow 和 LLM/规则决定 | `--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 显式回滚命令 当用户明确输入 `rollback [IP]` 或直接要求对指定 IP 回滚时： 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 回滚规则 回滚只允许在用户显式要求后执行。 回滚状态包括： - `ROLLBACK_NOT_RUN` - `ROLLBACK_DONE` - `ROLLBACK_FAILED` - `REJECTED_BY_OPERATOR` 默认建议： - 升级失败：建议回滚，`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 - pollIntervalSec: 2 - downloadPollMaxAttempts: 60 - upgradePollMaxAttempts: 600 - 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 | ROLLBACK_NOT_RUN | 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 | ROLLBACK_NOT_RUN | 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 停在 verify-ip；修复后可 resume 重试当前 action - 如确认需要回滚，可执行 rollback 192.168.1.12 ``` ## 10. Agent 执行建议 1. 只能调用 `action`，不要调用脚本主流程。 2. 不要自动生成、补写、覆盖或修改脚本文件。 3. 在高风险动作前显式说明： - 会创建版本 - 会上传包 - 会触发升级 - 回滚需要确认 4. 参数未确认前，不触发任何真实部署 action。 5. 用户只要求“生成脚本不执行”时，由于本 Skill 禁止自动生成或修改脚本，应直接说明限制，而不是自动产出脚本文件。 6. 如果 action 输出中出现 legacy `PENDING_AGENT_CONFIRMATION(...)`，立即暂停当前 workflow，输出建议；需要回滚时等待用户显式执行 rollback。 7. 如果存在检查点，优先评估能否从断点续试，而不是默认从头执行。 8. 任何长耗时阶段都要主动播报进度，尤其是： - `create-download-task` - `poll-download-progress` - 多 IP 循环处理 9. 间隔等待由 Agent 编排层负责控制，不要求脚本 action 自己管理 action 之间的等待。 10. 一轮部署中的所有 action，应复用同一个 `traceFilePath`。