1、完善技能描述

2、修复脚本问题
2026-05-21 15:34:52 +08:00 · 2026-05-21 15:34:52 +08:00 · 76e8f48c2e
commit 76e8f48c2e
parent f2df4df8b9
3 changed files with 286 additions and 43 deletions
--- a/doc_scripts/PAM_AUTO_DEPLY_SKILL.md
+++ b/doc_scripts/PAM_AUTO_DEPLY_SKILL.md
@ -21,6 +21,7 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
 - 禁止使用脚本主流程做部署，包括 `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. 执行模式选择
@ -78,6 +79,8 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
 - `allOrNothing`: 是否要求全有或全无
 - `rollbackApproved`: 用户是否已确认回滚
 - `osTarget`: 目标脚本入口环境
+- `checkpointPath`: 检查点文件路径
+- `resumeFromCheckpoint`: 是否按已有检查点断点续试

 ### 3.3 参数确认要求

@ -102,6 +105,29 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
 - 参数有歧义，先追问，不猜测
 - 敏感字段如 `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`。
@ -171,7 +197,185 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
 2. 出现回滚条件时。
 3. 用户指定 IP 与在线 IP 过滤结果不一致，且会影响部署范围时。

-### 4.3 主流程逐步说明
+### 4.3 面向用户的流程播报要求
+
+真实部署过程中，Agent 必须把部署过程显式展示给用户，至少满足以下要求：
+
+1. 在开始执行任何真实 `action` 前，先输出本次部署阶段列表。
+2. 在每个全局步骤开始前，告知用户“当前步骤”和“下一步将做什么”。
+3. 在每个全局步骤成功后，告知用户该步骤已完成，并说明关键结果。
+4. 在每个全局步骤失败后，立即告知用户失败阶段、失败原因和后续处理。
+5. 在逐台 IP 处理时，必须告知当前正在处理哪一台 IP。
+6. 在云下载进度轮询阶段，必须持续汇报当前进度，不能静默等待完成。
+7. 若执行耗时较长，必须按阶段持续播报，不能等全部结束后一次性汇总。
+8. 若进入回滚确认状态，必须明确告诉用户：
+   - 哪一台 IP 失败
+   - 失败阶段
+   - 建议是否回滚
+   - 是否需要 `stopFirst`
+
+建议的阶段播报格式：
+
+```markdown
+## 当前部署进度
+
+- 当前阶段: create-version
+- 下一步: upload-package
+- 当前结果: 成功
+```
+
+逐 IP 播报格式：
+
+```markdown
+## 当前 IP 处理进度
+
+- 目标IP: 192.168.1.10
+- 当前阶段: verify-ip
+- 当前结果: 进行中
+```
+
+云下载进度播报格式：
+
+```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`
+  - `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 主流程逐步说明

 | 步骤 | 目标 | 调用或动作 | 成功判定 | 失败处理 |
 | --- | --- | --- | --- | --- |
@ -205,13 +409,15 @@ description: 面向 PAM HOME/NODE 的智能部署 Skill。由 Skill 负责理解
 3. 所有关键步骤都要保留原始响应、错误摘要、阶段名。
 4. 单机成功或失败都要下载对应日志。
 5. 执行前必须先完成参数确认。
-6. 脚本模式下统一输出流程日志：
+6. 每个关键步骤成功后都要刷新检查点。
+7. 每个关键步骤前后都要向用户播报进度。
+8. 脚本模式下统一输出流程日志：
   - `[FLOW][START]`
   - `[FLOW][DONE]`
   - `[FLOW][FAIL]`
-7. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
-8. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
-9. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。
+9. 只允许调用脚本 `action` 入口，禁止调用脚本主流程。
+10. 脚本 action 输出以 `key=value` 为主，Agent 应优先读取这些结果行。
+11. 遇到需要回滚的场景，脚本只返回 `PENDING_AGENT_CONFIRMATION(stopFirst=...)`，Agent 必须先确认。

 ## 6. 脚本 action 能力

@ -241,7 +447,7 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action <ActionName> [-Ip
 | `get-online-ips` | 获取在线工作站 IP 列表 | 无 |
 | `create-download-task` | 创建云下载任务 | 无 |
 | `poll-download-progress` | 轮询下载进度 | 无 |
-| `download-cloud-to-node` | 创建下载任务并轮询至完成 | 无 |
+| `download-cloud-to-node` | 创建下载任务并轮询至完成，仅调试使用，不得进入正式主流程 | 无 |
 | `upgrade-ip` | 升级指定 IP | `--ip` / `-Ip` |
 | `start-ip` | 启动指定 IP 应用 | `--ip` / `-Ip` |
 | `stop-ip` | 停止指定 IP 应用 | `--ip` / `-Ip` |
@ -275,6 +481,7 @@ Agent 读取时：
 1. 只说明现有 `deploy.sh` / `deploy.ps1` / `deploy.bat` 的用途与调用方式。
 2. 不执行任何真实 `action`。
 3. 不生成、不修改任何脚本文件。
+4. 明确告诉用户当前只是说明模式，不会执行真实部署。

 ### 7.2 参数确认后不执行分支

@ -283,8 +490,10 @@ Agent 读取时：
 1. 读取并归一化参数。
 2. 输出参数确认单。
 3. 说明预计会调用的 action 顺序。
-4. 不执行任何真实 `action`。
-5. 不生成、不修改任何脚本文件。
+4. 若存在旧检查点，可同时说明可从哪个断点恢复。
+5. 不执行任何真实 `action`。
+6. 不生成、不修改任何脚本文件。
+7. 明确告诉用户当前只是预演流程，不会执行真实部署。

 ### 7.3 仅查看 Node 与在线 IP 分支

@ -293,12 +502,13 @@ Agent 读取时：
 1. 读取并归一化参数。
 2. 输出参数确认单并等待确认。
 3. 将参数写入 `config.txt`。
-4. 调用：
+4. 初始化或更新检查点文件。
+5. 调用：
   - `get-token`
   - `get-node-url`
   - `get-online-ips`
-5. 输出 Node 地址、在线 IP 数量和 IP 列表。
-6. 不执行：
+6. 输出 Node 地址、在线 IP 数量和 IP 列表。
+7. 不执行：
   - `create-version`
   - `upload-package`
   - `publish-version`
@ -314,7 +524,9 @@ Agent 读取时：
 3. 如有需要，再调用：
   - `verify-ip`
   - `download-log`
-4. 将回滚结果写入最终报告。
+4. 更新检查点中的 `rollback-status`。
+5. 将回滚结果写入最终报告。
+6. 在回滚执行前后都要向用户播报进度。

 ### 7.5 明确禁止的做法

@ -325,6 +537,9 @@ Agent 读取时：
 - 为了方便执行而切换到脚本主流程
 - 未确认参数就直接执行真实 action
 - 在出现回滚条件时自动执行回滚
+- 在已有检查点的情况下，未经判断就从头重跑全部步骤
+- 在正式主流程中调用 `download-cloud-to-node`
+- 在真实部署过程中长时间静默执行，不向用户播报阶段进度

 ## 8. 失败处理与回滚

@ -347,6 +562,7 @@ Agent 读取时：

 - 必须记录失败阶段和失败原因
 - 必须下载该 IP 日志
+- 必须刷新该 IP 的检查点状态
 - 不得自动执行回滚

 ### 8.3 回滚规则
@ -390,6 +606,8 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
 - 每个 IP 的状态、失败阶段、失败原因
 - 每个 IP 的回滚状态
 - 日志路径
+- 检查点文件路径
+- 是否从断点续试
 - 若有 trace，则给出 trace 路径

 建议结构：
@ -414,6 +632,48 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
 | 192.168.1.12 | FAILED | VERIFY | PENDING_AGENT_CONFIRMATION(stopFirst=true) | logs/deploy_192.168.1.12.log |
 ```

+更完整的最终报告模板：
+
+```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`，不要调用脚本主流程。
@ -426,3 +686,8 @@ powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action rollback-ip -Ip 1
 4. 参数未确认前，不触发任何真实部署 action。
 5. 用户只要求“生成脚本不执行”时，由于本 Skill 禁止自动生成或修改脚本，应直接说明限制，而不是自动产出脚本文件。
 6. 如果 action 输出中出现 `PENDING_AGENT_CONFIRMATION(...)`，立即中止自动后续动作并请求确认。
+7. 如果存在检查点，优先评估能否从断点续试，而不是默认从头执行。
+8. 任何长耗时阶段都要主动播报进度，尤其是：
+   - `create-download-task`
+   - `poll-download-progress`
+   - 多 IP 循环处理
--- a/doc_scripts/deploy.sh
+++ b/doc_scripts/deploy.sh
@ -16,7 +16,6 @@ SUCCESS_COUNT=0
 FAIL_COUNT=0
 RESULTS_FILE=""
 ONLINE_IPS=()
-HAS_JQ=0
 API_TRACE_FILE=""
 API_TRACE_SEQ=0
 TRACE_ANNOUNCED=0
@ -51,8 +50,8 @@ usage() {
 EOF
 }

-log_info() { printf '[INFO] %s\n' "$*"; }
-log_warn() { printf '[WARN] %s\n' "$*"; }
+log_info() { printf '[INFO] %s\n' "$*" >&2; }
+log_warn() { printf '[WARN] %s\n' "$*" >&2; }
 log_error() { printf '[ERROR] %s\n' "$*" >&2; }
 result_line() { printf '%s=%s\n' "$1" "$2"; }

@ -362,12 +361,6 @@ require_tool() {

 ensure_dependencies() {
    require_tool curl
-    if command -v jq >/dev/null 2>&1; then
-        HAS_JQ=1
-    else
-        HAS_JQ=0
-        log_warn "未检测到 jq，将使用 Bash 兼容 JSON 解析。"
-    fi
 }

 ensure_zip_file() {
@ -422,11 +415,6 @@ json_value() {
    local input="$1"
    local query="$2"

-    if (( HAS_JQ == 1 )); then
-        printf '%s' "$input" | jq -r "$query // empty" 2>/dev/null
-        return 0
-    fi
-
    case "$query" in
        '.access_token')
            json_get_string_by_key "$input" "access_token"
@ -449,6 +437,9 @@ json_value() {
        '.rateOfProgress')
            json_get_scalar_by_key "$input" "rateOfProgress"
            ;;
+        '.data.rateOfProgress')
+            json_get_nested_string_by_key "$input" "data" "rateOfProgress"
+            ;;
        '.progress')
            json_get_scalar_by_key "$input" "progress"
            ;;
@ -536,11 +527,6 @@ json_get_nested_string_by_key() {
 json_first_key() {
    local input="$1"

-    if (( HAS_JQ == 1 )); then
-        printf '%s' "$input" | jq -r 'keys[0] // empty' 2>/dev/null
-        return 0
-    fi
-
    local compact
    compact="$(json_compact "$input")"
    printf '%s' "$compact" | sed -nE 's/^[[:space:]]*\{[[:space:]]*"([^"]+)".*/\1/p'
@ -549,11 +535,6 @@ json_first_key() {
 json_array_items() {
    local input="$1"

-    if (( HAS_JQ == 1 )); then
-        printf '%s' "$input" | jq -r '.[]' 2>/dev/null
-        return 0
-    fi
-
    local compact
    compact="$(json_compact "$input")"
    compact="${compact#[}"
--- a/doc_scripts/当前脚本情况总结.md
+++ b/doc_scripts/当前脚本情况总结.md
@ -206,14 +206,11 @@ bash ./test_deploy.sh --config ./config.txt --mode full --max-ips 1
 - 改成更兼容的正则变量写法
 - 改成 here-string 方式读取解析结果

-### 4.4 `jq` 缺失问题
+### 4.4 Shell 原生 JSON 解析

-当前 `deploy.sh` 已做成：
+当前 `deploy.sh` 已完全去除 `jq` 依赖，统一使用 Bash 原生兼容解析。

- 有 `jq`：优先使用 `jq`
- 没有 `jq`：自动降级为 Bash 兼容 JSON 解析
-
-已覆盖的 fallback 解析场景：
+当前已覆盖的解析场景：

 - `access_token`
 - `status`
@ -312,7 +309,7 @@ bash ./test_deploy.sh --config ./config.txt --mode full --max-ips 1

 ## 6. 当前已知限制

-1. Shell 侧虽然支持无 `jq` 运行，但 fallback JSON 解析只针对当前接口结构，不适合复杂 JSON。
+1. Shell 侧已去除 `jq` 依赖，但当前原生 JSON 解析只针对现有接口结构，不适合复杂 JSON。
 2. 回滚测试默认会真实调用回滚接口，会改变测试环境状态；如不希望改变状态，需要显式加 `--skip-rollback`。
 3. `full` 模式会真实创建版本、上传包、发布、升级、启动、回滚，因此它不是只读检查。
 4. PowerShell 与 Shell 两套脚本逻辑大体对齐，但最新的一些 Shell 侧 trace 和兼容修复，后续仍建议同步到 PowerShell 版本。