@alipay/alipay-aipay 1.6.8-beta3 → 1.6.8-beta5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alipay/alipay-aipay",
-  "version": "1.6.8-beta3",
+  "version": "1.6.8-beta5",
   "description": "支付宝 AI 付接入 Skill 安装包 - 优先安装 Agent Skill，并在 macOS/Linux 后台准备用户级 CLI 工具",
   "type": "module",
   "bin": {

package/skill/VERSION

@@ -1 +1 @@
-1.6.8-beta3
+1.6.8-beta5

package/skill/references/normal/scripts/onboarding_message_runner.mjs

@@ -315,6 +315,7 @@ function dynamicMccRecordsFromCatalog(rawCatalog) {
     throw new Error('mcc-catalog-json 必须是非空数组');
   }
   const records = new Map();
+  const refs = new Set();
   for (const item of catalog) {
     if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error('mcc-catalog-json 项必须是对象');
     const code = String(item.mccCode || item.code || '').toUpperCase();
@@ -325,6 +326,10 @@ function dynamicMccRecordsFromCatalog(rawCatalog) {
     if (typeof item.needSpecialQual !== 'boolean') throw new Error(`动态 MCC ${code} 缺少布尔型 needSpecialQual`);
     if (!Array.isArray(item.qualificationGroups)) throw new Error(`动态 MCC ${code} 的 qualificationGroups 必须是数组`);
     if (records.has(code)) throw new Error(`动态 MCC 重复：${code}`);
+    const ref = item.mccRef == null ? '' : String(item.mccRef);
+    if (ref && !/^mcc-\d+$/u.test(ref)) throw new Error(`动态 MCC ${code} 的 mccRef 非法`);
+    if (ref && refs.has(ref)) throw new Error(`动态 MCC 目录引用重复：${ref}`);
+    if (ref) refs.add(ref);
     const needSpecialQual = item.needSpecialQual;
     const qualificationGroups = item.qualificationGroups;
     records.set(code, {
@@ -334,6 +339,7 @@ function dynamicMccRecordsFromCatalog(rawCatalog) {
       needSpecialQual,
       qualificationGroups,
       qualification: mccQualificationSummary({ needSpecialQual, qualificationGroups }),
+      ref: ref || undefined,
       dynamic: true
     });
   }
@@ -352,9 +358,20 @@ function sortedMccRecords(records) {
   return [...records.values()].sort((left, right) => left.code.localeCompare(right.code));
 }
 
+function mccAgentRefEntries(records) {
+  const refs = new Map();
+  sortedMccRecords(records).forEach((record, index) => {
+    const ref = record.ref || `mcc-${index + 1}`;
+    if (refs.has(ref)) throw new Error(`动态 MCC 目录引用重复：${ref}`);
+    refs.set(ref, record.code);
+  });
+  return refs;
+}
+
 function mccCatalogForAgent(records) {
-  return sortedMccRecords(records).map((record, index) => ({
-    ref: `mcc-${index + 1}`,
+  const refsByCode = new Map([...mccAgentRefEntries(records)].map(([ref, code]) => [code, ref]));
+  return sortedMccRecords(records).map((record) => ({
+    ref: refsByCode.get(record.code),
     mccName: record.name,
     mccDescription: record.applicableBusinesses
   }));
@@ -362,7 +379,7 @@ function mccCatalogForAgent(records) {
 
 function parseAgentCandidateRefs(args, records) {
   const raw = optional(args, 'agent-candidate-refs-json');
-  if (raw === undefined) return { provided: false, codes: [] };
+  if (raw === undefined) return { codes: [] };
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -372,7 +389,7 @@ function parseAgentCandidateRefs(args, records) {
   if (!Array.isArray(parsed) || parsed.length > 8 || parsed.some((ref) => typeof ref !== 'string')) {
     throw new Error('agent-candidate-refs-json 必须是最多 8 项的 JSON 字符串数组');
   }
-  const refs = new Map(sortedMccRecords(records).map((record, index) => [`mcc-${index + 1}`, record.code]));
+  const refs = mccAgentRefEntries(records);
   const codes = [];
   for (const ref of parsed) {
     if (!refs.has(ref) || codes.includes(refs.get(ref))) {
@@ -380,7 +397,7 @@ function parseAgentCandidateRefs(args, records) {
     }
     codes.push(refs.get(ref));
   }
-  return { provided: true, codes };
+  return { codes };
 }
 
 function mccTableSummary(records) {

package/skill/references/onboarding/modules/product-sign.md

@@ -13,7 +13,7 @@
 
 `queryMcc`、签约查询和签约提交使用 `{"request":{...},"ctx":{}}`；`batchQueryMcc` 使用 `{"request":{"mccCodes":[...]}}`。完整 payload 只在脚本中维护；Agent 不从本模块自行构造 MCP 调用。
 
-`queryMcc` 成功树按同一 run、产品短时缓存，并逐项提供二级 MCC 编码、名称、描述和布尔型 `needSpecialQual`；任一必需字段缺失、为空或类型异常均失败关闭，不从其他字段回退。非精确编码时，Agent 应先理解用户原话，并在行业俗称或场景表达与目录用词可能不同时于首次调用一并提供有原话依据的行业概念或同义表达；本地词面结果为 `NONE`、候选冲突或低置信时，runner 可发出一次目录复核 marker，携带同一次 `queryMcc` 返回的当前产品 MCC 名称、描述和稳定引用；Agent 只返回该 marker 中的目录引用，runner 映射并校验为当前动态目录中的候选，不接受自由提交 MCC code。目录复核不新增 MCP/网络调用，语义扩充仍按 flow 最多完成两次。候选确定后，仅把其中 `needSpecialQual=true` 的编码集中交给一次 `batchQueryMcc` 获取特殊资质项；没有此类候选时不调用。多候选的完整树事实和资格详情按 run、产品、原查询、规范化语义词和选择回执缓存，用户选择时携带同一语义词且有效命中则两种 MCC 方法都不重调。缓存默认 1800 秒、无有效 run 不落盘；过期、损坏、符号链接、跨 run、语义词变化或事实哈希不一致时忽略并从完整当前产品目录重查，不修补缓存事实，不做产品级全量预取。
+`queryMcc` 成功树按同一 run、产品短时缓存，并逐项提供二级 MCC 编码、名称、描述和布尔型 `needSpecialQual`；任一必需字段缺失、为空或类型异常均失败关闭，不从其他字段回退。非精确编码时，Agent 应先理解用户原话，并在行业俗称或场景表达与目录用词可能不同时于首次调用一并提供有原话依据的行业概念或同义表达；本地词面结果为 `NONE`、候选冲突或低置信时，runner 可发出一次目录复核 marker，携带同一次 `queryMcc` 返回的当前产品 MCC 名称、描述和稳定引用；Agent 只返回该 marker 中的目录引用，runner 映射并校验为当前动态目录中的候选，不接受自由提交 MCC code。稳定引用由完整动态目录生成，并随候选裁剪和资格详情合并原样携带；最终方案 runner 不得按缩减后的候选数组重新编号。目录复核不新增 MCP/网络调用，语义扩充仍按 flow 最多完成两次。候选确定后，仅把其中 `needSpecialQual=true` 的编码集中交给一次 `batchQueryMcc` 获取特殊资质项；没有此类候选时不调用。多候选的完整树事实和资格详情按 run、产品、原查询、规范化语义词和选择回执缓存，用户选择时携带同一语义词且有效命中则两种 MCC 方法都不重调。缓存默认 1800 秒、无有效 run 不落盘；过期、损坏、符号链接、跨 run、语义词变化或事实哈希不一致时忽略并从完整当前产品目录重查，不修补缓存事实，不做产品级全量预取。
 
 ## 签约状态
 

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

@@ -323,6 +323,92 @@ mcc_semantic_retry_file() {
     "$(mcc_cache_component "$sales_code")"
 }
 
+mcc_agent_review_file() {
+  local product_type="$1" sales_code="$2" root scope
+  root="$(mcc_cache_root)" || return 1
+  scope="$(mcc_cache_scope_id)" || return 1
+  if [ -e "$root" ] && { [ ! -d "$root" ] || [ -L "$root" ]; }; then
+    return 1
+  fi
+  mkdir -p "$root" 2>/dev/null || return 1
+  chmod 700 "$root" 2>/dev/null || true
+  printf '%s/%s.%s.%s.agent-reviews.json' \
+    "$root" \
+    "$(mcc_cache_component "$scope")" \
+    "$(mcc_cache_component "$product_type")" \
+    "$(mcc_cache_component "$sales_code")"
+}
+
+mcc_agent_review_issued() {
+  local product_type="$1" sales_code="$2" input_id="$3" file
+  file="$(mcc_agent_review_file "$product_type" "$sales_code")" || return 1
+  [ -f "$file" ] && [ ! -L "$file" ] || return 1
+  jq -e \
+    --arg inputId "$input_id" \
+    '.schemaVersion == 1
+      and ((.entries // null) | type == "array")
+      and all(.entries[];
+        type == "object"
+        and ((.query // null) | type == "string")
+        and ((.inputId // null) | type == "string")
+      )
+      and any(.entries[]; .inputId == $inputId)' \
+    "$file" >/dev/null 2>&1
+}
+
+mark_mcc_agent_review_issued() {
+  local product_type="$1" sales_code="$2" query="$3" input_id="$4"
+  local file dir lock tmp
+  file="$(mcc_agent_review_file "$product_type" "$sales_code")" || return 1
+  dir="${file%/*}"
+  lock="${file}.lock"
+  if ! mkdir "$lock" 2>/dev/null; then
+    return 1
+  fi
+  if [ -e "$file" ] && { [ ! -f "$file" ] || [ -L "$file" ]; }; then
+    rmdir "$lock" 2>/dev/null || true
+    return 1
+  fi
+  tmp="$(mktemp "$dir/.mcc-agent-reviews.XXXXXX" 2>/dev/null)" || {
+    rmdir "$lock" 2>/dev/null || true
+    return 1
+  }
+  chmod 600 "$tmp" 2>/dev/null || true
+  if [ -f "$file" ]; then
+    if ! jq -ce \
+      --arg query "$query" \
+      --arg inputId "$input_id" '
+        if .schemaVersion != 1 or ((.entries // null) | type != "array") then
+          error("invalid MCC agent review state")
+        elif any(.entries[]; .query == $query and .inputId == $inputId) then
+          .
+        else
+          .entries += [{query: $query, inputId: $inputId}]
+        end
+      ' "$file" >"$tmp" 2>/dev/null; then
+      rm -f "$tmp" 2>/dev/null || true
+      rmdir "$lock" 2>/dev/null || true
+      return 1
+    fi
+  else
+    if ! jq -cn \
+      --arg query "$query" \
+      --arg inputId "$input_id" \
+      '{schemaVersion: 1, entries: [{query: $query, inputId: $inputId}]}' \
+      >"$tmp" 2>/dev/null; then
+      rm -f "$tmp" 2>/dev/null || true
+      rmdir "$lock" 2>/dev/null || true
+      return 1
+    fi
+  fi
+  if ! mv "$tmp" "$file" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null || true
+    rmdir "$lock" 2>/dev/null || true
+    return 1
+  fi
+  rmdir "$lock" 2>/dev/null || true
+}
+
 claim_mcc_semantic_retry() {
   local product_type="$1" sales_code="$2" query="$3" input_id="$4" semantic_terms_json="$5"
   local file dir lock entry original_query retry_count next_retry_count now tmp lock_acquired=false
@@ -588,7 +674,10 @@ mcc_rows_from_tree() {
     elif (($rows | map(.fullCode) | unique | length) != ($rows | length)) then
       error("queryMcc returned duplicate selectable mcc")
     else
-      $rows
+      ($rows
+        | sort_by(.fullCode)
+        | to_entries
+        | map(.value + {mccRef: ("mcc-" + ((.key + 1) | tostring))}))
     end
   ' 2>/dev/null
 }
@@ -596,16 +685,17 @@ mcc_rows_from_tree() {
 normalize_mcc_tree_catalog() {
   local rows_json="$1"
   jq -cn --argjson rows "$rows_json" '
-    [
-      $rows[] |
-      {
+    ($rows |
+      map({
         mccCode: .fullCode,
         mccName: .treeName,
         mccDescription: .treeDescription,
         needSpecialQual: .treeNeedSpecialQual,
         qualificationGroups: []
-      }
-    ]
+      }) |
+      sort_by(.mccCode) |
+      to_entries |
+      map(.value + {mccRef: ("mcc-" + ((.key + 1) | tostring))}))
   ' 2>/dev/null
 }
 
@@ -654,6 +744,15 @@ query_mcc_detail_chunk() {
   printf '%s' "$business"
 }
 
+mcc_match_error_kind() {
+  case "$1" in
+    *agent-candidate-refs-json*) printf 'INVALID_AGENT_CANDIDATE_REFS' ;;
+    *semantic-terms-json*) printf 'INVALID_SEMANTIC_TERMS' ;;
+    *mcc-catalog-json*) printf 'INVALID_DYNAMIC_CATALOG' ;;
+    *) printf 'MATCHER_RUNTIME_ERROR' ;;
+  esac
+}
+
 normalize_mcc_catalog() {
   local rows_json="$1" details_json="$2"
   jq -cn --argjson rows "$rows_json" --argjson details "$details_json" '
@@ -683,6 +782,7 @@ normalize_mcc_catalog() {
             mccName: $row.treeName,
             mccDescription: $row.treeDescription,
             needSpecialQual: $row.treeNeedSpecialQual,
+            mccRef: $row.mccRef,
             qualificationGroups: (if $row.treeNeedSpecialQual then
               (($detail.qualificationGroups // []) | map({
                 qualifications: ((.qualifications // []) | map({
@@ -713,6 +813,7 @@ normalize_mcc_catalog() {
 
 run_mcc_match_codes() {
   local query="$1" product_type="$2" root_intent="$3" catalog="$4" semantic_terms_json="$5" agent_candidate_refs_json="${6:-}" runner_out runner_err runner_rc line resolution=""
+  local runner_error error_kind
   runner_out=$(mktemp "${TMPDIR:-/tmp}/mcc_match_out.XXXXXX") || { echo "❌ 创建临时文件失败"; exit 1; }
   runner_err=$(mktemp "${TMPDIR:-/tmp}/mcc_match_err.XXXXXX") || { rm -f "$runner_out"; echo "❌ 创建临时文件失败"; exit 1; }
   local node_args=(
@@ -729,7 +830,16 @@ run_mcc_match_codes() {
   "${NODE_BINARY:-node}" "${node_args[@]}" >"$runner_out" 2>"$runner_err"
   runner_rc=$?
   if [ "$runner_rc" -ne 0 ] || [ -s "$runner_out" ]; then
+    runner_error="$(sed -n 's/^ONBOARDING_MESSAGE_ERROR://p' "$runner_err" | sed -n '1p')"
+    error_kind="$(mcc_match_error_kind "$runner_error")"
+    if [ "$error_kind" = "INVALID_AGENT_CANDIDATE_REFS" ] && [ -n "$agent_candidate_refs_json" ]; then
+      rm -f "$runner_out" "$runner_err"
+      emit_control "MCC_AGENT_CANDIDATE_REFS_IGNORED=INVALID"
+      run_mcc_match_codes "$query" "$product_type" "$root_intent" "$catalog" "$semantic_terms_json"
+      return $?
+    fi
     rm -f "$runner_out" "$runner_err"
+    emit_control "MCC_MATCH_ERROR=$error_kind"
     mcc_query_failed
   fi
   while IFS= read -r line; do
@@ -754,7 +864,7 @@ validate_mcc_selection_cache() {
 }
 
 run_resolve_plan() {
-  local query="" product_type="" root_intent="" semantic_terms_json='[]' agent_candidate_refs_json="" select_value="" selection_receipt="" input_id="" sales_code tree rows tree_catalog resolution match_type semantic_status full_codes candidate_rows qualification_rows details catalog selection_cache="" used_selection_cache=false stale_selection=false resolved_semantic_terms='[]' retry_input_id="" retry_rc=0 next_retry_count=0 retry_reason="" retry_payload="" agent_review_required="false" agent_review_payload=""
+  local query="" product_type="" root_intent="" semantic_terms_json='[]' agent_candidate_refs_json="" select_value="" selection_receipt="" input_id="" sales_code tree rows tree_catalog resolution match_type semantic_status full_codes candidate_rows qualification_rows details catalog selection_cache="" used_selection_cache=false stale_selection=false resolved_semantic_terms='[]' retry_rc=0 next_retry_count=0 retry_reason="" retry_payload="" agent_review_required="false" agent_review_payload=""
   shift
   while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -840,20 +950,25 @@ run_resolve_plan() {
     semantic_status=$(printf '%s' "$resolution" | jq -r '.semanticStatus // ""' 2>/dev/null) || mcc_query_failed
     resolved_semantic_terms=$(printf '%s' "$resolution" | jq -c '.semanticTerms // []' 2>/dev/null) || mcc_query_failed
     agent_review_required=$(printf '%s' "$resolution" | jq -r '.agentReview.required // false' 2>/dev/null) || mcc_query_failed
+    if [ -n "$input_id" ] && [ -n "$agent_candidate_refs_json" ]; then
+      mark_mcc_agent_review_issued "$product_type" "$sales_code" "$query" "$input_id" || true
+    fi
     if [ "$agent_review_required" = "true" ] && [ -z "$agent_candidate_refs_json" ] && [ -n "$input_id" ]; then
       agent_review_payload=$(printf '%s' "$resolution" | jq -c '.agentReview' 2>/dev/null) || mcc_query_failed
-      emit_control "MCC_QUERY_RESULT=SUCCESS"
-      emit_control "MCC_RESOLUTION=$(printf '%s' "$resolution" | jq -c 'del(.agentReview)' 2>/dev/null)"
-      emit_control "MCC_AGENT_REVIEW_REQUIRED=$agent_review_payload"
-      return 0
+      if ! mcc_agent_review_issued "$product_type" "$sales_code" "$input_id"; then
+        mark_mcc_agent_review_issued "$product_type" "$sales_code" "$query" "$input_id" || true
+        emit_control "MCC_QUERY_RESULT=SUCCESS"
+        emit_control "MCC_RESOLUTION=$(printf '%s' "$resolution" | jq -c 'del(.agentReview)' 2>/dev/null)"
+        emit_control "MCC_AGENT_REVIEW_REQUIRED=$agent_review_payload"
+        return 0
+      fi
     fi
     if [ "$match_type" = "NONE" ] \
       && [ "$semantic_status" != "DYNAMIC_CATALOG_CODE_NOT_FOUND" ] \
       && [ "$semantic_status" != "DYNAMIC_CATALOG_CODE_AMBIGUOUS" ]; then
       if [ -n "$input_id" ]; then
-        retry_input_id="$input_id"
         next_retry_count="$(claim_mcc_semantic_retry \
-          "$product_type" "$sales_code" "$query" "$retry_input_id" "$resolved_semantic_terms" 2>/dev/null)"
+          "$product_type" "$sales_code" "$query" "$input_id" "$resolved_semantic_terms" 2>/dev/null)"
         retry_rc=$?
       else
         # A retry without a message identity cannot be bound to one user input.
@@ -884,7 +999,7 @@ run_resolve_plan() {
     else
       full_codes=$(printf '%s' "$resolution" | jq -c '.mergedCandidateCodes // []' 2>/dev/null) || mcc_query_failed
     fi
-    if [ -z "${catalog:-}" ]; then
+  if [ -z "${catalog:-}" ]; then
       if ! printf '%s' "$full_codes" | jq -e 'type == "array" and length > 0' >/dev/null 2>&1; then
         catalog="$tree_catalog"
       else
@@ -904,6 +1019,15 @@ run_resolve_plan() {
       fi
     fi
   fi
+  if [ -n "$agent_candidate_refs_json" ] && ! printf '%s' "$catalog" | jq -e \
+    --argjson refs "$agent_candidate_refs_json" '
+      ([.[] | .mccRef?] | map(select(type == "string"))) as $available |
+      ($refs | type == "array" and all(.[]; . as $ref | $available | index($ref) != null))
+    ' >/dev/null 2>&1; then
+    # An invalid Agent review may have already fallen back to local matches.
+    # Do not pass that invalid reference into the reduced final catalog.
+    agent_candidate_refs_json=""
+  fi
   node_args=(
     "$ONBOARDING_RUNNER" mcc-resolve-plan
     --query "$query"
@@ -955,7 +1079,7 @@ case "${1:-}" in
     run_resolve_plan "$@"
     ;;
   *)
-    echo "用法: bash mcc.sh resolve-plan --query <经营描述|MCC编码> --product-type <aipay|webpay|apppay> --root-intent <onboarding_only|full_process> [--semantic-terms-json <JSON数组>] [--select <MCC编码> --selection-receipt <receipt>] [--input-id <USER_INPUT_ID>]"
+    echo "用法: bash mcc.sh resolve-plan --query <经营描述|MCC编码> --product-type <aipay|webpay|apppay> --root-intent <onboarding_only|full_process> [--semantic-terms-json <JSON数组>] [--agent-candidate-refs-json <JSON数组>] [--select <MCC编码> --selection-receipt <receipt>] [--input-id <USER_INPUT_ID>]"
     exit 1
     ;;
 esac