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。
• 在任何真实调用前，必须先向用户展示归一化后的参数并得到确认。
• 回滚不得自动执行。脚本只能输出 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 ./deploy.sh --config ./config.txt --action <action-name> [--ip 192.168.1.10] [--hash-code xxx] [--stop-first]

7.2 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 输出约定

典型返回为：

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 ./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

10. 输出要求

最终报告至少包含：

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

建议结构：

## 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(...)，立即中止自动后续动作并请求确认。