dark/agent_deply
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
agent_deply/doc_scripts/PAM智能部署 Agent Skill 文档.md.md
dark 143cd76c6a 1、新增action给agent使用 
2、新增SKILL描述
2026-05-20 16:58:01 +08:00

9.6 KiB
Raw Blame History

name, description
name description
pam-smart-deploy 基于 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(...) 状态、日志位置或日志摘要
  • 如果是脚本模式：实际生成或执行的文件名

可按以下结构输出：

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