agent_deply/doc_scripts/PAM_AUTO_DEPLY_SKILL.md

name, description

name	description
pam-auto-deply	面向 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
parentVersionNumber	PARENT_VERSION_NUMBER	否	云下载时指定继承哪个版本的规则；默认空值不传，继承正在使用的版本规则
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
• parentVersionNumber（可选；空值表示不传）
• 用户指定 IP 子集（如有）

确认规则：

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

参数确认单建议模板：

## 部署参数确认单

- 模式: 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
- PARENT_VERSION_NUMBER: -
- 指定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
  • PARENT_VERSION_NUMBER
  • 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 在运行时持有并应用。
• PARENT_VERSION_NUMBER 写入 config.txt 但默认可为空；只有非空时，create-download-task 才把它作为云下载接口参数 parentVersionNumber 发送。
• 进度查询和健康检查重试参数写入 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；如 PARENT_VERSION_NUMBER 非空，则云下载接口携带 parentVersionNumber，否则不传该参数。
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. PARENT_VERSION_NUMBER 只影响 create-download-task / download-cloud，不得透传到推送、启动、校验或日志下载 action。
5. 同一台 IP 内部：
   • upgrade-ip -> poll-upgrade-progress
   • poll-upgrade-progress -> start-ip
   • start-ip -> verify-ip
   • verify-ip -> download-log 之间按 perIpStepIntervalSec 等待。
6. 当前一台 IP 处理完成后，到下一台 IP 开始前，按 perIpIntervalSec 等待。
7. 若某步骤失败后需要进入提示、确认或分支流程，可按 failurePauseSec 等待。
8. 若某个间隔值为 0，表示该层级不等待，直接进入下一动作。
9. poll-download-progress 和 poll-upgrade-progress 的脚本 action 只执行一次进度查询；正式 workflow 的循环、checkpoint、LLM 判断和进度播报由 Agent Runtime 负责。
10. 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 间隔等待中，也必须告诉用户等待时长和下一步动作。

建议的阶段播报格式：

## 当前部署进度

- 当前阶段: create-version
- 下一步: upload-package
- 当前结果: 成功
- 等待: 2 秒后继续

逐 IP 播报格式：

## 当前 IP 处理进度

- 目标IP: 192.168.1.10
- 当前阶段: verify-ip
- 当前结果: 进行中
- 下一步: download-log
- 等待: 1 秒后继续

云下载进度播报格式：

## 云下载进度

- 当前阶段: 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. 若存在失败暂停或 legacy PENDING_AGENT_CONFIRMATION(...)：
   • 检查点中必须保留失败阶段、失败原因和审核建议
   • 修复后 resume 默认从当前失败 action 重试
   • 需要回滚时必须由用户显式执行 rollback [IP]
6. 若用户要求“从头重新开始”：
   • 先明确说明将忽略现有检查点
   • 再从第 1 步重新执行

检查点 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 ./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 -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	单次查询下载进度；是否继续查询由 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 回滚；接口参数使用 URL query，不使用表单 body	--ip / -Ip，可带 --stop-first / -RollbackStopFirst

6.4 action 输出约定

典型返回为：

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 ./deploy.sh --config ./config.txt --action rollback-ip --ip 192.168.1.10 --stop-first

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 路径

建议结构：

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

更完整的最终报告模板：

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