@alipay/alipay-aipay 1.1.0 → 1.2.2

package/skill/references/onboarding/modules/scripts/service.sh

@@ -2,14 +2,14 @@
 #=============================================================================
 # 脚本名称: service.sh
 # 功能描述: 服务市场注册 - 查询已有服务 + 创建/修改服务
-# 调用位置: Step 5.2 服务市场注册
+# 调用位置: list 用于 Step 3.1 前置资源查询；save/validate 用于 Step 5.2 服务市场注册
 # 调用前置: 脚本通过 error_handler.sh 间接初始化 DEV_TOOL_NAME；必要时可用 DEV_TOOL_NAME 环境变量覆盖
 # 用法:
 #   service list                                       - 查询已有服务列表
 #   service save  --name <n> --desc <d> --url <u> --pricing <p> --schema <json> [--service-id <id>]
 #   service validate --name <n> --desc <d> --url <u> --pricing <p> --schema <json>
 # 返回值:
-#   list:     输出服务列表表格 + FLOW:CREATE_NEW | FLOW:SELECT
+#   list:     输出服务列表 + FLOW:CREATE_NEW | FLOW:SELECT
 #   save:     输出 ✅/❌ + serviceId（无 FLOW 标记，由 Agent 根据退出码判断）
 #   validate: 输出 ✅/❌ + 校验详情（退出码 0=通过, 1=失败）
 #=============================================================================
@@ -29,9 +29,18 @@ require_command alipay-cli || exit 1
 require_command awk || exit 1
 
 # ─── service list: 查询已有服务 ──────────────────────────────────────────────
-fetch_service_list() {
+fetch_service_page() {
+  local OFFSET="$1"
+  local LIMIT="$2"
+  local REQUEST_JSON RESULT BUSINESS BUSINESS_CODE BUSINESS_MESSAGE
+
+  REQUEST_JSON=$(jq -n \
+    --argjson limit "$LIMIT" \
+    --argjson offset "$OFFSET" \
+    '{request:{limit:$limit,offset:$offset}}')
+
   RESULT=$(export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call a2a-pay-service.discoverBazaarServicesForMcp \
-    -d '{"request":{"serviceStatus":"ACTIVE"}}' \
+    -d "$REQUEST_JSON" \
     --json 2>/dev/null)
 
   if ! handle_error "$RESULT"; then
@@ -39,9 +48,116 @@ fetch_service_list() {
   fi
 
   BUSINESS=$(unwrap_mcp "$RESULT")
-  SERVICE_LIST=$(echo "$BUSINESS" | jq -c '.resultObj.serviceList // []' 2>/dev/null)
-  if [ -z "$SERVICE_LIST" ] || ! echo "$SERVICE_LIST" | jq -e 'type == "array"' >/dev/null 2>&1; then
-    echo "❌ 服务列表返回结构异常，无法解析 serviceList"
+
+  BUSINESS_CODE=$(echo "$BUSINESS" | jq -r 'if has("code") then (.code | tostring) else "" end' 2>/dev/null)
+  if [ -n "$BUSINESS_CODE" ] && [ "$BUSINESS_CODE" != "10000" ]; then
+    BUSINESS_MESSAGE=$(echo "$BUSINESS" | jq -r '
+      .subMsg // .data.subMsg // .msg // .data.msg // "未知错误"
+    ' 2>/dev/null)
+    echo "❌ 查询服务列表失败: ${BUSINESS_CODE} / ${BUSINESS_MESSAGE}"
+    return 1
+  fi
+
+  PAGE_FORMAT=$(echo "$BUSINESS" | jq -r '
+    if ((.code | tostring) == "10000") and
+       ((.data | type) == "object") and
+       ((.data.items | type) == "array") and
+       ((.data.pagination | type) == "object") and
+       ((.data.pagination.total | type) == "number") and
+       (.data.pagination.total >= 0) and
+       ((.data.pagination.total | floor) == .data.pagination.total) and
+       ((.data.pagination.offset | type) == "number") and
+       (.data.pagination.offset >= 0) and
+       ((.data.pagination.offset | floor) == .data.pagination.offset) then
+      "current"
+    elif (.success == true) and
+         ((.resultObj | type) == "object") and
+         ((.resultObj.serviceList | type) == "array") then
+      "legacy"
+    else
+      "invalid"
+    end
+  ' 2>/dev/null)
+
+  case "$PAGE_FORMAT" in
+    current)
+      PAGE_ITEMS=$(echo "$BUSINESS" | jq -c '.data.items')
+      PAGE_TOTAL=$(echo "$BUSINESS" | jq -r '.data.pagination.total')
+      PAGE_OFFSET=$(echo "$BUSINESS" | jq -r '.data.pagination.offset')
+      ;;
+    legacy)
+      PAGE_ITEMS=$(echo "$BUSINESS" | jq -c '.resultObj.serviceList')
+      PAGE_TOTAL=$(echo "$PAGE_ITEMS" | jq 'length')
+      PAGE_OFFSET=0
+      ;;
+    *)
+      echo "❌ 服务列表返回结构异常，无法解析 data.items 或兼容的 resultObj.serviceList"
+      return 1
+      ;;
+  esac
+
+  if [ -z "$PAGE_ITEMS" ] || ! echo "$PAGE_ITEMS" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    echo "❌ 服务列表返回结构异常，列表字段不是数组"
+    return 1
+  fi
+}
+
+fetch_service_list() {
+  local LIMIT=20
+  local OFFSET=0
+  local EXPECTED_TOTAL=""
+  local PAGE_COUNT
+
+  SERVICE_LIST='[]'
+
+  while true; do
+    if ! fetch_service_page "$OFFSET" "$LIMIT"; then
+      return 1
+    fi
+
+    if [ "$PAGE_FORMAT" = "legacy" ]; then
+      SERVICE_LIST="$PAGE_ITEMS"
+      break
+    fi
+
+    if [ "$PAGE_OFFSET" -ne "$OFFSET" ]; then
+      echo "❌ 服务列表分页返回异常：期望 offset=${OFFSET}，实际 offset=${PAGE_OFFSET}"
+      return 1
+    fi
+
+    if [ -z "$EXPECTED_TOTAL" ]; then
+      EXPECTED_TOTAL="$PAGE_TOTAL"
+    elif [ "$PAGE_TOTAL" -ne "$EXPECTED_TOTAL" ]; then
+      echo "❌ 服务列表分页返回异常：分页过程中 total 发生变化"
+      return 1
+    fi
+
+    SERVICE_LIST=$(jq -cn \
+      --argjson existing "$SERVICE_LIST" \
+      --argjson page "$PAGE_ITEMS" \
+      '$existing + $page')
+    SERVICE_COUNT=$(echo "$SERVICE_LIST" | jq 'length')
+
+    if [ "$SERVICE_COUNT" -gt "$EXPECTED_TOTAL" ]; then
+      echo "❌ 服务列表分页返回异常：已返回数量超过 total"
+      return 1
+    fi
+    if [ "$SERVICE_COUNT" -eq "$EXPECTED_TOTAL" ]; then
+      break
+    fi
+
+    PAGE_COUNT=$(echo "$PAGE_ITEMS" | jq 'length')
+    if [ "$PAGE_COUNT" -eq 0 ]; then
+      echo "❌ 服务列表分页返回异常：尚有未返回数据但当前页为空"
+      return 1
+    fi
+    OFFSET="$SERVICE_COUNT"
+  done
+
+  if ! echo "$SERVICE_LIST" | jq -e '
+    all(.[]; ((.serviceId | type) == "string") and (.serviceId | length > 0))
+  ' >/dev/null 2>&1; then
+    echo "❌ 服务列表返回结构异常：存在缺少 serviceId 的候选服务"
     return 1
   fi
 
@@ -54,14 +170,13 @@ service_list() {
   fi
 
   if [ "$SERVICE_COUNT" -eq 0 ] || [ "$SERVICE_LIST" = "[]" ] || [ -z "$SERVICE_LIST" ]; then
-    echo "📋 暂无服务上架，需要创建新服务"
+    echo "📋 暂无已有服务；记录新建候选分支，等待 Step 4 统一决策"
     echo "FLOW:CREATE_NEW"
   else
-    # 输出服务列表
     echo "📋 发现您已有以下服务："
     echo ""
-    echo "| 序号 | 服务ID | 服务名称 | 描述 | 价格 | 状态 | 服务地址 |"
-    echo "|------|--------|----------|------|------|------|----------|"
+    echo "| 序号 | 服务ID | 服务名称 | 描述 | 价格 | 实际状态 | 服务地址 |"
+    echo "|------|--------|----------|------|------|----------|----------|"
 
     for i in $(seq 0 $((SERVICE_COUNT-1))); do
       SERVICE=$(echo "$SERVICE_LIST" | jq ".[$i]")
@@ -69,11 +184,11 @@ service_list() {
       SERVICE_NAME=$(echo "$SERVICE" | jq -r '.serviceName // "未知"')
       SERVICE_DESC=$(echo "$SERVICE" | jq -r '.serviceDesc // "无描述"')
       PRICING=$(echo "$SERVICE" | jq -r '.pricing // "未知"')
-      SERVICE_STATUS=$(echo "$SERVICE" | jq -r '.status // "未知"')
+      SERVICE_STATUS=$(echo "$SERVICE" | jq -r '.serviceStatus // .status // "未知"')
       RESOURCE_URL=$(echo "$SERVICE" | jq -r '.resourceUrl // "未知"')
 
       case "$SERVICE_STATUS" in
-        "ONLINE") STATUS_CN="已上架" ;;
+        "ACTIVE") STATUS_CN="已上线" ;;
         "PENDING") STATUS_CN="审核中" ;;
         "REJECTED") STATUS_CN="审核拒绝" ;;
         *) STATUS_CN="$SERVICE_STATUS" ;;
@@ -84,9 +199,9 @@ service_list() {
 
     echo ""
     echo "请选择："
-    echo "  • 输入序号（1-$SERVICE_COUNT）复用对应服务"
+    echo "  • 输入序号 (1-${SERVICE_COUNT}) 复用对应服务"
     echo "  • 输入\"新建\"创建新服务"
-    echo "  • 输入\"修改\"修改已有服务"
+    echo "  • 输入\"修改 + serviceId\"修改已有服务"
     echo "FLOW:SELECT"
   fi
 }
@@ -102,12 +217,24 @@ service_save() {
 
   while [[ $# -gt 0 ]]; do
     case $1 in
-      --service-id)    SERVICE_ID="$2"; shift 2 ;;
-      --name)          SERVICE_NAME="$2"; shift 2 ;;
-      --desc)          SERVICE_DESC="$2"; shift 2 ;;
-      --url)           RESOURCE_URL="$2"; shift 2 ;;
-      --pricing)       PRICING="$2"; shift 2 ;;
-      --schema)        SCHEMA_URL="$2"; shift 2 ;;
+      --service-id)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SERVICE_ID="$2"; shift 2 ;;
+      --name)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SERVICE_NAME="$2"; shift 2 ;;
+      --desc)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SERVICE_DESC="$2"; shift 2 ;;
+      --url)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        RESOURCE_URL="$2"; shift 2 ;;
+      --pricing)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        PRICING="$2"; shift 2 ;;
+      --schema)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SCHEMA_URL="$2"; shift 2 ;;
       *) echo "❌ 未知参数: $1"; exit 1 ;;
     esac
   done
@@ -162,26 +289,59 @@ service_save() {
     exit 1
   fi
 
-  # 解包 MCP 信封后解析业务字段
+  # 解包 MCP 信封后按当前协议解析，并兼容旧 success/resultObj 协议。
   BUSINESS=$(unwrap_mcp "$RESULT")
-  SUCCESS=$(echo "$BUSINESS" | jq -r '.success // false')
-
-  if [ "$SUCCESS" = "true" ]; then
-    OPERATION="上架"
+  SAVE_FORMAT=$(echo "$BUSINESS" | jq -r '
+    if ((.code | tostring) == "10000") and
+       ((.data | type) == "object") and
+       (.data.success == true) then
+      "current"
+    elif (.success == true) and
+         ((.resultObj | type) == "object") then
+      "legacy"
+    else
+      "invalid"
+    end
+  ' 2>/dev/null)
+
+  if [ "$SAVE_FORMAT" = "current" ] || [ "$SAVE_FORMAT" = "legacy" ]; then
+    OPERATION="创建"
     if [ -n "$SERVICE_ID" ]; then
       OPERATION="修改"
     fi
-    # 使用 --arg 安全拼接回退值
-    NEW_SERVICE_ID=$(echo "$BUSINESS" | jq -r --arg fallback "${SERVICE_ID}" '.resultObj.serviceId // $fallback')
+
+    if [ "$SAVE_FORMAT" = "current" ]; then
+      NEW_SERVICE_ID=$(echo "$BUSINESS" | jq -r --arg fallback "${SERVICE_ID}" '
+        (.data.serviceId | select(type == "string" and length > 0)) // $fallback
+      ')
+    else
+      NEW_SERVICE_ID=$(echo "$BUSINESS" | jq -r --arg fallback "${SERVICE_ID}" '
+        (.resultObj.serviceId | select(type == "string" and length > 0)) // $fallback
+      ')
+    fi
+
+    if [ -z "$NEW_SERVICE_ID" ]; then
+      echo "❌ 服务创建返回成功，但未解析到 serviceId，禁止继续后续流程"
+      exit 1
+    fi
     echo "✅ 服务${OPERATION}成功"
     echo "📋 服务ID: $NEW_SERVICE_ID"
   else
-    ERROR_MSG=$(echo "$BUSINESS" | jq -r '.error.message // .errorMessage // "未知错误"')
-    OPERATION="上架"
+    OPERATION="创建"
     if [ -n "$SERVICE_ID" ]; then
       OPERATION="修改"
     fi
-    echo "❌ 服务${OPERATION}失败: $ERROR_MSG"
+
+    BUSINESS_CODE=$(echo "$BUSINESS" | jq -r 'if has("code") then (.code | tostring) else "" end' 2>/dev/null)
+    if [ -n "$BUSINESS_CODE" ] && [ "$BUSINESS_CODE" != "10000" ]; then
+      ERROR_MSG=$(echo "$BUSINESS" | jq -r '
+        .data.subMsg // .data.msg // .subMsg // .msg //
+        .error.message // .errorMessage // "未知错误"
+      ' 2>/dev/null)
+      echo "❌ 服务${OPERATION}失败: ${BUSINESS_CODE} / ${ERROR_MSG:-未知错误}"
+    else
+      echo "❌ 服务${OPERATION}返回结构异常，无法确认操作结果"
+    fi
     exit 1
   fi
 }
@@ -196,11 +356,21 @@ service_validate() {
 
   while [[ $# -gt 0 ]]; do
     case $1 in
-      --name)    SERVICE_NAME="$2"; shift 2 ;;
-      --desc)    SERVICE_DESC="$2"; shift 2 ;;
-      --url)     RESOURCE_URL="$2"; shift 2 ;;
-      --pricing) PRICING="$2"; shift 2 ;;
-      --schema)  SCHEMA_URL="$2"; shift 2 ;;
+      --name)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SERVICE_NAME="$2"; shift 2 ;;
+      --desc)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SERVICE_DESC="$2"; shift 2 ;;
+      --url)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        RESOURCE_URL="$2"; shift 2 ;;
+      --pricing)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        PRICING="$2"; shift 2 ;;
+      --schema)
+        [ $# -ge 2 ] || { echo "❌ 缺少参数值: $1"; exit 1; }
+        SCHEMA_URL="$2"; shift 2 ;;
       *) echo "❌ 未知参数: $1"; exit 1 ;;
     esac
   done
@@ -234,7 +404,8 @@ service_validate() {
     exit 1
   fi
 
-  # 5. 请求示例：有效 JSON（改用 jq 代替 python3，与脚本其他部分保持一致）
+  # 5. schemaUrl 在本流程中承载序列化后的 JSON 请求示例，不是 URL。
+  # CLI 接收原始 JSON；save 分支通过 jq --arg 将其安全写入字符串字段。
   if [ -z "$SCHEMA_URL" ] || ! echo "$SCHEMA_URL" | jq . >/dev/null 2>&1; then
     echo "❌ 请提供有效的 JSON 格式请求示例"
     exit 1

package/skill/references/onboarding/modules/scripts/upload_screenshots.sh

@@ -2,7 +2,7 @@
 #=============================================================================
 # 脚本名称: upload_screenshots.sh
 # 功能描述: 并行上传截图文件并解析可用于签约的图片引用值
-# 调用位置: Step 4 资料采集
+# 调用位置: Step 4 一次性资料与资源决策
 # 调用前置: 脚本通过 error_handler.sh 间接初始化 DEV_TOOL_NAME；需传入3个文件路径
 # 用法: bash upload_screenshots.sh "$HOME_IMG" "$SHOP_IMG" "$PAY_IMG"
 # 返回值: 输出上传结果和图片引用值

package/skill/references/onboarding/modules/service-registration.md

@@ -1,7 +1,7 @@
 # 服务市场注册模块
 
 > 本文档定义按量付费产品的服务市场上架流程。**仅按量付费产品需要服务市场注册**。
-> 被引用文档：`SKILL.md` → Step 5 入驻推进 - 服务注册部分
+> 被引用文档：`onboarding/flow.md` → Step 3.1 服务查询 + Step 5.2 服务注册
 > 本文档位于 `references/onboarding/modules/`，文中的 `scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/onboarding/modules/scripts/...`。
 
 ---
@@ -32,11 +32,11 @@
 │    └─ 调用 discoverBazaarServicesForMcp                             │
 │                                                                     │
 │  Step 2: 判断服务列表                                                │
-│    ├─ serviceList 为空 → 进入 Step 3 交互式收集服务信息               │
-│    └─ serviceList 不为空 → 进入 Step 3 让用户选择操作                 │
+│    ├─ data.items 为空 → 进入 Step 3 收集服务信息                       │
+│    └─ data.items 不为空 → 展示完整分页结果后进入 Step 3 决策           │
 │                                                                     │
 │  Step 3: 用户决策                                                    │
-│    ├─ 选择序号（复用已有服务）→ 跳过创建，完成                        │
+│    ├─ 选择序号复用已有服务 → 跳过创建，完成                            │
 │    ├─ 选择"新建" → ⚠️ 检查服务数量，若 ≥ 20 则禁止创建                │
 │    │                 若 < 20，收集 5 项服务信息，进入 Step 4           │
 │    └─ 选择"修改" → 输入服务ID，收集所有服务信息，进入 Step 4          │
@@ -72,7 +72,7 @@
 
 ## Step 2: 根据查询结果执行不同分支
 
-### 场景 A：serviceList 为空（无已有服务）
+### 场景 A：服务列表为空（无已有服务）
 
 **此时必须进入 Step 3 收集服务信息并创建新服务。**
 
@@ -80,24 +80,24 @@
 >
 > ⚠️ 注意：服务数量上限为 20 个，`service.sh save` 在创建前会校验。
 
-### 场景 B：serviceList 不为空（有已有服务）
+### 场景 B：服务列表不为空（有已有服务）
 
-**此时必须让用户选择是复用已有服务还是创建新服务。**
+**此时必须按接口返回结果展示服务及其实际状态，让用户选择复用、创建或修改。Skill 不额外按状态过滤复用候选。**
 
 **输出格式：**
 
 ```markdown
 📋 发现您已有以下服务：
 
-| 序号 | 服务ID | 服务名称 | 描述 | 价格 | 状态 | 服务地址 |
-|------|--------|----------|------|------|------|----------|
-| 1 | SVC001 | 天气查询 | 提供全球天气查询 | 0.01元/次 | 已上架 | https://api.example.com/weather |
+| 序号 | 服务ID | 服务名称 | 描述 | 价格 | 实际状态 | 服务地址 |
+|------|--------|----------|------|------|----------|----------|
+| 1 | SVC001 | 天气查询 | 提供全球天气查询 | 0.01元/次 | 已上线 | https://api.example.com/weather |
 | 2 | SVC002 | AI助手 | 智能对话服务 | 0.05元/次 | 审核中 | https://api.example.com/ai |
 
 请选择：
   • 输入序号（1/2）复用对应服务
   • 输入"新建"创建新服务
-  • 输入"修改"修改已有服务
+  • 输入"修改 + serviceId"修改已有服务
 ```
 
 > 📎 表格渲染由 `scripts/service.sh list` 自动完成，无需手动拼接。Agent 直接展示脚本输出即可。
@@ -110,19 +110,21 @@ Agent 根据用户输入执行对应分支：
 |----------|----------|
 | 数字序号（1-$SERVICE_COUNT） | 复用对应服务 → 跳过创建，直接进入应用发布 |
 | "新建" | 进入 Step 3 收集服务信息 → `bash scripts/service.sh save`（创建前自动校验数量 < 20） |
-| "修改" | 引导用户输入服务ID → 进入 Step 3 收集**所有**字段 → `bash scripts/service.sh save --service-id <id>` |
+| "修改 + serviceId" | 使用表格中展示的 serviceId → 进入 Step 3 收集**所有**字段 → `bash scripts/service.sh save --service-id <id>` |
 
 > ⚠️ 服务数量上限 20 个，由 `service.sh save` 在创建前自动校验。
 
+用户选择修改时可使用列表中展示的 `serviceId`。展示和记录接口返回的实际状态，不自行增加状态过滤、可用性结论或审核规则。
+
 ---
 
 ## Step 3: 收集服务信息（创建或修改服务时执行）
 
 **⚠️ 在以下情况需执行此步骤：**
 ```
-✅ serviceList 为空（无已有服务）→ 创建新服务
+✅ 服务列表为空（无已有服务）→ 创建新服务
 ✅ 用户选择"新建" → 创建新服务
-✅ 用户选择"修改" → 修改已有服务（需先输入服务ID）
+✅ 用户选择"修改" → 修改已有服务（提供表格中的 serviceId）
 ```
 
 **⚠️ 修改服务特别注意：**
@@ -141,11 +143,15 @@ Agent 根据用户输入执行对应分支：
 2. 服务描述（1-500 字符）：简要描述服务功能
 3. 服务地址（URL）：服务的 API 地址
 4. 服务单价（元，最低 0.01）：用户每次调用的费用
-5. 请求示例（JSON）：API 请求参数示例
+5. 请求示例（JSON）：API 请求参数示例，提交时作为 `schemaUrl` 字符串传入
 
-请依次提供以上信息。
+请在一条回复中一次性提供以上全部信息。修改服务时请同时提供表格中的 serviceId，不再单独增加一轮询问。
 ```
 
+只补问缺失或校验失败的字段。已经通过校验的字段必须保留，不要求用户重新提交；修改服务仍必须最终获得全部五项字段，禁止只提交局部字段。
+
+Agent 在当前任务中记录操作选择、serviceId 和五项服务资料。用户更正字段时只覆盖并重新校验该字段，其他未变化且已校验通过的字段继续复用；操作类型变化时清除不再适用的 serviceId 或创建资料。只补问缺失或校验失败字段，本模块的 `scripts/service.sh validate` 继续作为业务格式校验唯一来源。
+
 ### 入参校验规则
 
 | 字段 | 说明 | 验证规则 | 错误提示 |
@@ -154,7 +160,9 @@ Agent 根据用户输入执行对应分支：
 | `serviceDesc` | 服务描述 | 长度 1-500 字符 | 服务描述长度需在 1-500 字符之间 |
 | `resourceUrl` | 服务地址 | 有效的 URL 格式（以 http:// 或 https:// 开头） | 请提供有效的 URL 地址 |
 | `pricing` | 服务单价 | 必须 >= 0.01 元 | 服务单价最低为 0.01 元 |
-| `schemaUrl` | 请求示例 | 有效的 JSON 格式 | 请提供有效的 JSON 格式请求示例 |
+| `schemaUrl` | 请求示例 | 有效的 JSON 格式；提交时序列化为字符串 | 请提供有效的 JSON 格式请求示例 |
+
+> `schemaUrl` 是 MCP 入参字段名，本流程中承载的是序列化后的 JSON 请求示例，不是 URL。用户提供原始 JSON，例如 `{}`；`scripts/service.sh` 校验 JSON 后将其作为字符串写入 `request.schemaUrl`。禁止因为字段名含 `Url` 而要求用户提供网页地址。
 
 ### 校验脚本
 
@@ -186,20 +194,22 @@ bash scripts/service.sh validate   --name "$SERVICE_NAME"   --desc "$SERVICE_DES
 ### 成功输出格式
 
 ```markdown
-✅ 服务上架成功
+✅ 服务创建成功
 
 | 项目 | 信息 |
 |------|------|
+| 服务ID | API_xxx |
 | 服务名称 | 天气查询 |
 | 服务描述 | 提供全球天气查询服务 |
 | 服务地址 | https://api.example.com/weather |
 | 服务单价 | 0.01 元/次 |
-| 状态 | 审核中 |
 ```
 
+`saveBazaarServiceForMcp` 的当前成功响应不包含服务状态。不得根据创建或修改成功推断为“审核中”“已上线”或其他状态。只有后续 `scripts/service.sh list` 只读查询成功并按 `serviceId` 匹配到该服务时，才能记录和展示实际状态；查询失败或尚未返回该服务时，将状态保留为“未取得”，不得因此重复执行 `save`。
+
 ### 按量付费集成产物
 
-服务创建、修改或复用成功后，必须记录并向用户说明以下字段：
+服务创建、修改或复用成功后，必须记录并向用户说明以下已取得字段：
 
 | 字段 | 用途 |
 |------|------|
@@ -207,7 +217,7 @@ bash scripts/service.sh validate   --name "$SERVICE_NAME"   --desc "$SERVICE_DES
 | 服务名称 | 用于核对收银台展示和用户识别 |
 | 服务地址 `resourceUrl` | 应与实际提供 402 服务的资源地址一致 |
 | 服务单价 `pricing` | 应与 `Payment-Needed.protocol.amount` 的业务定价保持一致 |
-| 服务状态 | 判断是否可用于正式上架和后续排查 |
+| 服务状态 | 仅在只读查询实际取得时记录，用于正式上线判断和后续排查 |
 
 如果服务注册成功但未解析到 `serviceId`，不要继续宣称按量付费入驻完成；应提示用户重新查询服务列表或根据服务名称定位服务。
 
@@ -230,9 +240,17 @@ bash scripts/service.sh validate   --name "$SERVICE_NAME"   --desc "$SERVICE_DES
 
 | 查询方式 | 参数 | 说明 |
 |----------|------|------|
-| 查询已上线服务列表 | `{"request":{"serviceStatus":"ACTIVE"}}` | 返回所有已上架的服务列表 |
+| 查询服务列表 | `{"request":{"limit":20,"offset":0}}` | 返回接口可见的服务列表；脚本按 `pagination.total` 自动翻页并完整展示实际状态，不按状态过滤候选 |
 | 根据 serviceId 查询详情 | `{"request":{"keyword":"API_xxx"}}` | 返回指定服务的详细信息 |
 
+**查询返回处理：**
+
+- MCP 信封先通过共享 `unwrap_mcp` 解包 `content[0].text`。
+- 当前成功协议以 `code="10000"` 判断，服务数组读取 `data.items`，分页读取 `data.pagination.limit/offset/total`。
+- 当前服务状态字段读取 `serviceStatus`，兼容旧响应中的 `status`；`ACTIVE` 表示已上线，其他未定义映射的状态值原样展示，不推断业务含义。
+- 脚本兼容旧成功协议中的 `success=true` 与 `resultObj.serviceList`，但不得用旧结构覆盖或猜测当前字段。
+- 只有明确取得成功响应中的空数组，才能判定没有已有服务；业务失败、字段缺失、分页不完整或候选缺少 `serviceId` 均必须阻断，禁止输出 `FLOW:CREATE_NEW` 或 `FLOW:SELECT`。
+
 **⚠️ saveBazaarServiceForMcp 创建/修改服务参数说明：**
 
 | 场景 | 必传参数 | 说明 |
@@ -240,12 +258,35 @@ bash scripts/service.sh validate   --name "$SERVICE_NAME"   --desc "$SERVICE_DES
 | 创建新服务 | serviceName, serviceDesc, resourceUrl, pricing, schemaUrl | 无需传入 serviceId |
 | 修改已有服务 | **serviceId**, serviceName, serviceDesc, resourceUrl, pricing, schemaUrl | **必须传入 serviceId + 所有资料信息** |
 
+**写入返回处理：**
+
+- MCP 信封先通过共享 `unwrap_mcp` 解包 `content[0].text`。
+- 当前成功协议必须同时满足 `code="10000"` 和 `data.success=true`，服务 ID 读取 `data.serviceId`。
+- 脚本兼容旧成功协议中的 `success=true` 和 `resultObj.serviceId`；不得混用两套协议中的成功条件与服务 ID 路径。
+- 创建成功但未解析到 `serviceId` 时必须阻断后续流程；修改成功未返回新 ID 时，继续使用本次请求中已经确认的原 `serviceId`。
+- 业务失败优先展示 `data.subMsg` / `data.msg`，再读取顶层错误字段；响应结构不符合当前或兼容协议时不得宣称成功。
+- 当前保存成功响应不包含服务状态；不得从 `success=true` 推断审核或上线状态。
+
+其中 `schemaUrl` 按本模块约定传入序列化后的 JSON 请求示例。例如空请求示例的实际入参为：
+
+```json
+{
+  "request": {
+    "serviceName": "服务名称",
+    "serviceDesc": "服务描述",
+    "resourceUrl": "https://your-domain.com/callback",
+    "pricing": "0.6",
+    "schemaUrl": "{}"
+  }
+}
+```
+
 ### 正确调用示例
 
 > 📎 所有 MCP 调用均有对应脚本：
 
 ```bash
-# ✅ 查询已上线服务列表 → scripts/service.sh list
+# ✅ 查询服务列表 → scripts/service.sh list
 # ✅ 创建新服务 → scripts/service.sh save --name <name> --desc <desc> --url <url> --pricing <pricing> --schema <json>
 # ✅ 修改已有服务 → scripts/service.sh save --service-id <id> --name <name> --desc <desc> --url <url> --pricing <pricing> --schema <json>
 ```
@@ -270,12 +311,14 @@ export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call a2a-pay-service.saveBaza
 
 ## 服务状态说明
 
+当前列表响应优先读取 `serviceStatus`，旧响应兼容读取 `status`。下表以外的实际状态值必须原样展示；没有已验证依据时不得自行翻译、归类或推断是否可用。
+
 | 状态 | 说明 | 处理方式 |
 |------|------|----------|
-| `DRAFT` | 草稿 | 可继续编辑或提交审核 |
-| `PENDING` | 审核中 | 等待审核结果，服务暂不可用 |
-| `ONLINE` | 已上架 | 服务可被调用，可直接复用 |
-| `REJECTED` | 审核拒绝 | 引导用户联系客服或重新提交 |
+| `DRAFT` | 草稿 | 展示接口返回的实际状态，由用户决定后续操作 |
+| `PENDING` | 审核中 | 展示接口返回的实际状态，由用户决定后续操作 |
+| `ACTIVE` | 已上线 | 展示接口返回的实际状态，由用户决定后续操作 |
+| `REJECTED` | 审核拒绝 | 展示接口返回的实际状态，由用户决定后续操作 |
 
 ---
 
@@ -283,8 +326,8 @@ export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call a2a-pay-service.saveBaza
 
 ```
 ❌ 禁止：未查询已有服务直接创建新服务
-❌ 禁止：在 Step 4 资料采集阶段收集 按量付费 的服务信息（服务信息在服务市场模块交互式收集）
-❌ 禁止：serviceList 不为空时直接创建新服务（必须让用户选择）
+❌ 禁止：未在 Step 3.1 成功查询已有服务就要求用户决定新建/修改或提供服务资料
+❌ 禁止：服务列表不为空时直接创建新服务（必须让用户选择）
 ❌ 禁止：用户选择复用已有服务后仍创建新服务
 ❌ 禁止：跳过服务信息校验直接提交
 ❌ 禁止：使用虚拟或自行推断的 MCP 方法