@alipay/alipay-aipay 1.4.9 → 1.5.0

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

@@ -51,6 +51,15 @@ function loadJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
+function allowedRepliesFor(catalog, message) {
+  if (!message.allowedReplySet) return message.allowedReplies || [];
+  const replies = catalog.interactionReplySets?.[message.allowedReplySet];
+  if (!Array.isArray(replies) || replies.length === 0 || replies.some((reply) => typeof reply !== 'string' || !reply)) {
+    throw new Error(`${message.messageId}: allowedReplySet 无效`);
+  }
+  return replies;
+}
+
 export function loadMccRecords() {
   const records = new Map();
   let primaryCode = '';
@@ -412,7 +421,7 @@ function validateServiceCreateSummary(variantName, variables, normalized) {
 }
 
 function validateIntegrationStart(variantName, variables) {
-  const expectedProducts = { AIPAY: '按量付费', WEBPAY: '网站支付', APPPAY: 'APP 支付' };
+  const expectedProducts = { AIPAY: 'AI 按量付费', WEBPAY: 'AI 网页应用收款', APPPAY: 'AI 移动应用收款' };
   if (expectedProducts[variantName] !== variables.productName) {
     throw new Error('integration.start.confirm variant 与产品不匹配');
   }
@@ -425,12 +434,12 @@ function validateWriteConfirmation(variantName, variables, normalized) {
   const common = ['sessionSummary', 'subjectSummary', 'productName', 'actionTypes'];
   const service = ['serviceId', 'serviceName', 'serviceDescription', 'serviceUrl', 'servicePricing', 'serviceSchema'];
   const definitions = {
-    SERVICE_UPDATE_ONLY: { actions: '服务修改', product: '按量付费', required: ['serviceId', 'serviceName', 'serviceDescription', 'serviceUrl', 'servicePricing', 'serviceSchema'], allowed: [...common, ...service] }
+    SERVICE_UPDATE_ONLY: { actions: '服务修改', product: 'AI 按量付费', required: ['serviceId', 'serviceName', 'serviceDescription', 'serviceUrl', 'servicePricing', 'serviceSchema'], allowed: [...common, ...service] }
   };
   const rule = definitions[variantName];
   if (!rule) throw new Error(`onboarding.write.confirm 不支持 variant ${variantName}`);
   if (variables.actionTypes !== rule.actions) throw new Error('写确认 variant 与 actionTypes 不匹配');
-  if (rule.product && variables.productName !== rule.product) throw new Error('服务写确认只适用于按量付费');
+  if (rule.product && variables.productName !== rule.product) throw new Error('服务写确认只适用于 AI 按量付费');
   for (const name of rule.required) {
     if (!hasValue(variables, name)) throw new Error(`写确认缺少 ${name}`);
   }
@@ -445,23 +454,23 @@ function validateWriteConfirmation(variantName, variables, normalized) {
 }
 
 function productionSpecificLines(productName) {
-  if (productName === '按量付费') {
+  if (productName === 'AI 按量付费') {
     return [
-      '3. 按量付费 `serviceId`：把沙箱 `api_mock_service_id` 替换为真实 `serviceId`，`serviceId` 获取方式是：登录支付宝 AI 付站点（https://aipay.alipay.com/?from=alipay-aipay-skill） → 控制台 → 服务管理 → 复制审核已通过的目标服务 ID。',
-      '4. 按量付费商户标识：`seller_id`/`seller_unique_id` 填收款商户 PID/2088，PID 获取方式是：登录支付宝商家平台（https://b.alipay.com/page/portal/home） → 点击头像 → 复制账户名下方 2088 开头的商家 ID；`seller_app_id` 填生产 `appId`。',
-      '5. 按量付费验收：A2M 不使用 `notify_url`；上线前用生产应用私钥重新签名 402 账单，并验证 `Payment-Proof`、金额/订单/资源一致、`trade_no` 防重复履约和 `alipay.aipay.agent.fulfillment.confirm` 异步回执。'
+      '3. AI 按量付费 `serviceId`：把沙箱 `api_mock_service_id` 替换为真实 `serviceId`，`serviceId` 获取方式是：登录支付宝 AI 付站点（https://aipay.alipay.com/?from=alipay-aipay-skill） → 控制台 → 服务管理 → 复制审核已通过的目标服务 ID。',
+      '4. AI 按量付费商户标识：`seller_id`/`seller_unique_id` 填收款商户 PID/2088，PID 获取方式是：登录支付宝商家平台（https://b.alipay.com/page/portal/home） → 点击头像 → 复制账户名下方 2088 开头的商家 ID；`seller_app_id` 填生产 `appId`。',
+      '5. AI 按量付费验收：A2M 不使用 `notify_url`；上线前用生产应用私钥重新签名 402 账单，并验证 `Payment-Proof`、金额/订单/资源一致、`trade_no` 防重复履约和 `alipay.aipay.agent.fulfillment.confirm` 异步回执。'
     ];
   }
-  if (productName === 'APP 支付') {
+  if (productName === 'AI 移动应用收款') {
     return [
-      '3. APP 支付 `notify_url`：生成生产 `orderStr` 时传入商家已部署的公网 HTTPS `notify_url`；未传不会触发异步通知。',
-      '4. APP 支付验收：`notify_url` 完成验签，校验 `app_id`/`out_trade_no`/`total_amount`/`trade_status`，幂等处理并返回 `success`；支付结果以异步通知或 `alipay.trade.query` 补偿查询为准。客户端 SDK 使用服务端 `orderStr` 调起支付，客户端结果只做展示，不能作为付款成功依据。'
+      '3. AI 移动应用收款 `notify_url`：生成生产 `orderStr` 时传入商家已部署的公网 HTTPS `notify_url`；未传不会触发异步通知。',
+      '4. AI 移动应用收款验收：`notify_url` 完成验签，校验 `app_id`/`out_trade_no`/`total_amount`/`trade_status`，幂等处理并返回 `success`；支付结果以异步通知或 `alipay.trade.query` 补偿查询为准。客户端 SDK 使用服务端 `orderStr` 调起支付，客户端结果只做展示，不能作为付款成功依据。'
     ];
   }
   return [
-    '3. 网站支付 `notify_url`：生产下单时传入商家已部署的公网 HTTPS `notify_url`；该地址是商家后端通知地址，不是支付宝生成的 URL。',
-    '4. 网站支付验收：`notify_url` 完成验签，校验 `app_id`/`out_trade_no`/`total_amount`/`trade_status`，幂等处理并返回 `success`；支付结果以异步通知或 `alipay.trade.query` 补偿查询为准，同步回跳或前台页面不能作为付款成功依据。',
-    '5. 网站支付收款限制：如需解除网站支付的收款限制，请前往 [支付宝商家平台 - 签约管理](https://b.alipay.com/page/ar-center/ar-manage) 补全网站支付信息。'
+    '3. AI 网页应用收款 `notify_url`：生产下单时传入商家已部署的公网 HTTPS `notify_url`；该地址是商家后端通知地址，不是支付宝生成的 URL。',
+    '4. AI 网页应用收款验收：`notify_url` 完成验签，校验 `app_id`/`out_trade_no`/`total_amount`/`trade_status`，幂等处理并返回 `success`；支付结果以异步通知或 `alipay.trade.query` 补偿查询为准，同步回跳或前台页面不能作为付款成功依据。',
+    '5. AI 网页应用收款限制：如需解除 AI 网页应用收款的收款限制，请前往 支付宝商家平台 - 签约管理 补全收款信息：https://b.alipay.com/page/ar-center/ar-manage'
   ];
 }
 
@@ -538,7 +547,7 @@ function validateVariantInputShape(messageId, variantName, variables) {
       return;
     }
     if (Object.prototype.hasOwnProperty.call(variables, 'serviceStatus')) {
-      throw new Error(`onboarding.discovery.summary/${variantName} 禁止传入 serviceStatus 字段；网站支付和 APP 支付的服务市场由模板固定为“无需处理”，请从 JSON 删除 serviceStatus 字段；允许变量：signingStatus、applicationStatus`);
+      throw new Error(`onboarding.discovery.summary/${variantName} 禁止传入 serviceStatus 字段；AI 网页应用收款和 AI 移动应用收款的服务市场由模板固定为“无需处理”，请从 JSON 删除 serviceStatus 字段；允许变量：signingStatus、applicationStatus`);
     }
   }
 }
@@ -573,12 +582,12 @@ const managedEntrypoints = {
     reason: '产品已明确且 MCC 存在多个相似候选时由 runner 绑定本地 MCC 表生成候选事实，禁止手写候选表。'
   },
   'onboarding.discovery.summary': {
-    command: 'node ../normal/scripts/onboarding_message_runner.mjs discovery-summary --product-type <aipay|webpay|apppay>',
-    reason: '运行时只传脚本原始 signStatus/serviceFlow/appFlow，由 runner 映射枚举并处理网站支付/APP 支付禁用 serviceStatus 的变体规则。'
+    command: 'node ../normal/scripts/onboarding_discovery_runner.mjs run --product-type <aipay|webpay|apppay> --sales-code <SALES_CODE>',
+    reason: '该 runner 执行本轮适用查询、校验原始脚本事实、输出唯一 DISCOVERY_RESULT envelope，并在同一次 stdout 生成摘要；禁止单独重放摘要。'
   },
   'materials.category.collect': {
     command: 'node ../normal/scripts/onboarding_message_runner.mjs material-collect --category <signing|service|application> --state <INITIAL|PARTIAL|INVALID|APP_MOBILE_INITIAL> --product-type <aipay|webpay|apppay>',
-    reason: '运行时禁止手写 categoryName/currentStatus/missingFields；runner 会归一化“签约资料”“网站支付签约截图”“mobilePlatform”等常见别名后再调用 renderer。'
+    reason: '运行时禁止手写 categoryName/currentStatus/missingFields；runner 会归一化“签约资料”“AI 网页应用收款签约截图”“mobilePlatform”等常见别名后再调用 renderer。'
   },
   'application.candidates.facts': {
     command: 'node ../normal/scripts/onboarding_message_runner.mjs application-candidates --application-type <WEBAPP|MOBILEAPP>',
@@ -598,7 +607,7 @@ const managedEntrypoints = {
   },
   'process.partial_result': {
     command: 'node ../normal/scripts/onboarding_message_runner.mjs closeout',
-    reason: '产品开通 Step 6 最终收口必须由 runner 统一合并代码开发状态、产品开通分支状态、最近应用分支结果和上线前关键点；禁止 Agent 手写、缩写或删减网站支付收款限制引导。'
+    reason: '产品开通 Step 6 最终收口必须由 runner 统一合并代码开发状态、产品开通分支状态、最近应用分支结果和上线前关键点；禁止 Agent 手写、缩写或删减 AI 网页应用收款限制引导。'
   },
   'auth.page': {
     command: 'bash modules/scripts/auth.sh init --defer-open --scope <scope> --sales-code <code> --mcc-code <code> --product-name <name> --mcc-name <name>，页面 stdout 独立送达后执行 bash modules/scripts/auth.sh open ...',
@@ -607,7 +616,7 @@ const managedEntrypoints = {
   },
   'auth.pending': {
     command: 'bash modules/scripts/auth.sh wait|confirm [--scope <scope> --sales-code <code> --mcc-code <code> --product-name <name> --mcc-name <name>]',
-    reason: '授权待完成状态只能来自 auth.sh 有限轮询耗尽或用户输入 1 后的单次实际查询。',
+    reason: '授权待完成状态只能来自 auth.sh 有限轮询耗尽或登记肯定回复后的单次实际查询。',
     allowedCallers: ['auth.sh']
   },
   'auth.expired': {
@@ -747,9 +756,9 @@ export function getMessageSchema(messageId, variantName = 'DEFAULT') {
     for (const requiredName of ['serviceId', 'serviceName', 'serviceDescription', 'serviceUrl', 'servicePricing', 'serviceSchema']) {
       setVariableRule(inputVariables, requiredName, { required: true });
     }
-    setVariableRule(inputVariables, 'productName', { values: ['按量付费'] });
+    setVariableRule(inputVariables, 'productName', { values: ['AI 按量付费'] });
     setVariableRule(inputVariables, 'actionTypes', { values: ['服务修改'] });
-    variantRules.push('SERVICE_UPDATE_ONLY 只用于按量付费服务修改；签约提交、服务创建、应用创建和应用提审不得进入该确认消息。');
+    variantRules.push('SERVICE_UPDATE_ONLY 只用于 AI 按量付费服务修改；签约提交、服务创建、应用创建和应用提审不得进入该确认消息。');
   }
 
   return {
@@ -759,7 +768,7 @@ export function getMessageSchema(messageId, variantName = 'DEFAULT') {
     owner: message.owner,
     blocking: Boolean(message.blocking),
     replyMode: message.replyMode || 'exact',
-    allowedReplies: message.allowedReplies || [],
+    allowedReplies: allowedRepliesFor(catalog, message),
     inputHintType: message.inputHintType || null,
     postRenderHintType: message.postRenderHintType || null,
     managedEntrypoint: publicManagedEntrypoint(messageId),
@@ -801,11 +810,17 @@ export function validateCatalog() {
   }
 
   for (const message of catalog.messages) {
+    let allowedReplies = [];
+    try {
+      allowedReplies = allowedRepliesFor(catalog, message);
+    } catch (error) {
+      errors.push(error.message);
+    }
     if (messages.has(message.messageId)) errors.push(`重复 messageId: ${message.messageId}`);
     messages.set(message.messageId, message);
     if (!['catalog_owned', 'script_owned'].includes(message.owner)) errors.push(`${message.messageId}: owner 无效`);
-    if (message.blocking && JSON.stringify(message.allowedReplies) === '["1"]' && !['confirm', 'authorizationComplete', 'publicKeyConfirmationComplete', 'complete'].includes(message.inputHintType)) {
-      errors.push(`${message.messageId}: 单一确认消息必须声明合法 inputHintType`);
+    if (message.blocking && allowedReplies.length > 0 && !['confirm', 'authorizationComplete', 'publicKeyConfirmationComplete', 'complete'].includes(message.inputHintType)) {
+      errors.push(`${message.messageId}: 阻塞回复消息必须声明合法 inputHintType`);
     }
     if (message.postRenderHintType !== undefined && message.postRenderHintType !== 'scanReturn') {
       errors.push(`${message.messageId}: postRenderHintType 无效`);
@@ -848,8 +863,8 @@ export function validateCatalog() {
         if (!officialUrls.has(match[0])) errors.push(`${message.messageId}/${variantName}: 静态 URL 未登记 ${match[0]}`);
       }
       if (/<INTERNAL_/i.test(template)) errors.push(`${message.messageId}/${variantName}: 模板包含内部标签`);
-      if (message.blocking && JSON.stringify(message.allowedReplies) === '["1"]' && /(?:回复|输入)\s*`?1`?/.test(template)) {
-        errors.push(`${message.messageId}/${variantName}: 单一确认输入提示必须由 renderer 统一追加`);
+      if (message.blocking && allowedReplies.length > 0 && /(?:回复|输入)\s*`?1`?/.test(template)) {
+        errors.push(`${message.messageId}/${variantName}: 阻塞输入提示必须由 renderer 统一追加`);
       }
     }
   }
@@ -963,10 +978,10 @@ export function renderMessage(messageId, variantName, variables, telemetryContex
   if (messageId === 'integration.checklist.result') {
     const sandboxPending = variables.sandboxConfigState !== 'READY';
     const hasBlockingDefect = variables.blockingDefectState === 'PRESENT';
-    if (variantName === 'AIPAY' && !variables.sandboxResult) throw new Error('按量付费 checklist 缺少沙箱联调结果');
-    if (variantName !== 'AIPAY' && variables.sandboxResult) throw new Error('非按量付费 checklist 禁止传入按量付费沙箱结果');
-    if (variantName === 'WEBPAY' && !variables.webpayExperienceResult) throw new Error('网站支付 checklist 缺少沙箱体验实际结果');
-    if (variantName !== 'WEBPAY' && variables.webpayExperienceResult) throw new Error('非网站支付 checklist 禁止传入网站支付沙箱体验结果');
+    if (variantName === 'AIPAY' && !variables.sandboxResult) throw new Error('AI 按量付费 checklist 缺少沙箱联调结果');
+    if (variantName !== 'AIPAY' && variables.sandboxResult) throw new Error('非 AI 按量付费 checklist 禁止传入 AI 按量付费沙箱结果');
+    if (variantName === 'WEBPAY' && !variables.webpayExperienceResult) throw new Error('AI 网页应用收款 checklist 缺少沙箱体验实际结果');
+    if (variantName !== 'WEBPAY' && variables.webpayExperienceResult) throw new Error('非 AI 网页应用收款 checklist 禁止传入 AI 网页应用收款沙箱体验结果');
     const hasFailedItems = variables.failedItems !== '无';
     const hasManualItems = variables.manualItems !== '无';
     const manualOnly = !hasFailedItems && hasManualItems;
@@ -1002,17 +1017,17 @@ export function renderMessage(messageId, variantName, variables, telemetryContex
     if (sandboxPending && !hasFailedItems) {
       throw new Error('沙箱配置未完成时必须列入未通过或部分通过项');
     }
-    if (sandboxPending && variantName === 'AIPAY' && variables.sandboxResult !== '按量付费沙箱服务端联调未通过') {
-      throw new Error('沙箱配置未完成时按量付费联调不得标记通过');
+    if (sandboxPending && variantName === 'AIPAY' && variables.sandboxResult !== 'AI 按量付费沙箱服务端联调未通过') {
+      throw new Error('沙箱配置未完成时 AI 按量付费联调不得标记通过');
     }
     if (sandboxPending && variantName === 'WEBPAY' && variables.webpayExperienceResult !== '未提供浏览器付款入口或完整操作指引，需先补齐') {
-      throw new Error('沙箱配置未完成时网站支付不得标记已交付付款体验');
+      throw new Error('沙箱配置未完成时 AI 网页应用收款不得标记已交付付款体验');
     }
-    if (variantName === 'AIPAY' && variables.overallResult === '通过' && variables.sandboxResult !== '按量付费沙箱服务端联调通过') {
-      throw new Error('按量付费代码开发通过必须有沙箱服务端联调通过结论');
+    if (variantName === 'AIPAY' && variables.overallResult === '通过' && variables.sandboxResult !== 'AI 按量付费沙箱服务端联调通过') {
+      throw new Error('AI 按量付费代码开发通过必须有沙箱服务端联调通过结论');
     }
     if (variantName === 'WEBPAY' && variables.overallResult === '通过' && variables.webpayExperienceResult === '未提供浏览器付款入口或完整操作指引，需先补齐') {
-      throw new Error('网站支付未交付付款入口时不得标记代码开发通过');
+      throw new Error('AI 网页应用收款未交付付款入口时不得标记代码开发通过');
     }
     if (manualOnly) {
       normalized.failedItems = `人工待验证项未完成：${normalized.manualItems}`;
@@ -1038,6 +1053,16 @@ export function renderMessage(messageId, variantName, variables, telemetryContex
     normalized.paymentPageHint = variables.missingFields.split('、').includes('支付页截图')
       ? definitions.get('paymentPageHint')?.values?.[0] || ''
       : '';
+    normalized.serviceUrlHint = variantName === 'INVALID'
+      && variables.categoryName === '服务资料'
+      && variables.missingFields.split('、').includes('服务地址')
+      ? definitions.get('serviceUrlHint')?.values?.[0] || ''
+      : '';
+    normalized.servicePricingHint = variantName === 'INVALID'
+      && variables.categoryName === '服务资料'
+      && variables.missingFields.split('、').includes('服务单价')
+      ? definitions.get('servicePricingHint')?.values?.[0] || ''
+      : '';
   }
   if (messageId === 'process.partial_result') {
     const statusQueryHintDefinition = definitions.get('statusQueryHint');
@@ -1126,13 +1151,13 @@ export function renderMessage(messageId, variantName, variables, telemetryContex
     } else {
       throw new Error('full_process 进入产品开通收口时只允许已完成、沙箱待配置或人工待验证');
     }
-    if (variables.productName === '按量付费' && variables.serviceResult === '无需处理') {
-      throw new Error('按量付费产品开通不能把服务市场标记为无需处理');
+    if (variables.productName === 'AI 按量付费' && variables.serviceResult === '无需处理') {
+      throw new Error('AI 按量付费产品开通不能把服务市场标记为无需处理');
     }
-    if (variables.productName !== '按量付费' && variables.serviceResult !== '无需处理') {
-      throw new Error('网站支付或 APP 支付的服务市场结果必须为无需处理');
+    if (variables.productName !== 'AI 按量付费' && variables.serviceResult !== '无需处理') {
+      throw new Error('AI 网页应用收款或 AI 移动应用收款的服务市场结果必须为无需处理');
     }
-    const expectedServiceComplete = variables.productName === '按量付费'
+    const expectedServiceComplete = variables.productName === 'AI 按量付费'
       ? ['已复用', '创建成功，状态未取得', '修改成功，状态未取得', '已完成'].includes(variables.serviceResult)
       : variables.serviceResult === '无需处理';
     const productBranchesComplete =
@@ -1161,7 +1186,7 @@ export function renderMessage(messageId, variantName, variables, telemetryContex
   if (messageId === 'process.partial_result' || messageId === 'error.backend' || messageId === 'error.cli') {
     rendered = normalizeProcessPartialResultSpacing(rendered);
   }
-  if (message.blocking && JSON.stringify(message.allowedReplies) === '["1"]') {
+  if (message.blocking && allowedRepliesFor(catalog, message).length > 0) {
     const hintKeys = {
       confirm: 'confirmInputHint',
       authorizationComplete: 'authorizationCompletionInputHint',

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

@@ -35,7 +35,14 @@ const permissionedFlushNetworkErrors = new Set([
   'NETWORK_UNREACHABLE'
 ]);
 const productByVariant = { AIPAY: 'AIPAY', WEBPAY: 'WEBPAY', APPPAY: 'APPPAY' };
-const productByName = { '按量付费': 'AIPAY', '网站支付': 'WEBPAY', 'APP 支付': 'APPPAY' };
+const productByName = {
+  'AI 按量付费': 'AIPAY',
+  'AI 网页应用收款': 'WEBPAY',
+  'AI 移动应用收款': 'APPPAY',
+  按量付费: 'AIPAY',
+  网站支付: 'WEBPAY',
+  'APP 支付': 'APPPAY'
+};
 const productAliases = {
   aipay: 'AIPAY',
   webpay: 'WEBPAY',
@@ -394,9 +401,44 @@ export function emitMetricEvent(event, { env = process.env, stream = process.std
   return true;
 }
 
-export function emitStageMetric(stage, context = {}) {
+export function emitStageMetric(stage, context = {}, env = process.env) {
   try {
-    return emitMetricEvent(stageMetricEvent(stage, context));
+    return emitMetricEvent(stageMetricEvent(stage, context, Date.now(), env), { env });
+  } catch {
+    return false;
+  }
+}
+
+export function emitStageMetricAsync(stage, context = {}, env = process.env) {
+  try {
+    if (!telemetryEnabled(env) || !stageRules.has(stage)) return false;
+    if (normalizeSwitch(env.ALIPAY_AIPAY_TEST_MODE) === '1') {
+      return emitStageMetric(stage, context, env);
+    }
+    const args = [scriptPath(), 'stage', stage, '--timestamp-ms', String(Date.now())];
+    const options = [
+      ['run-id', context.runId || context.run_id],
+      ['root-intent', context.rootIntent || context.root_intent],
+      ['product-type', context.productType || context.product_type],
+      ['product-name', context.productName]
+    ];
+    for (const [name, value] of options) {
+      if (typeof value === 'string' && value) args.push(`--${name}`, value);
+    }
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: 'ignore',
+      env
+    });
+    child.on('error', (error) => {
+      recordLocalTelemetryFailure(
+        safeDimension(error?.code || error?.name || 'TELEMETRY_STAGE_SPAWN_FAILED', 'TELEMETRY_STAGE_SPAWN_FAILED', 80),
+        safeDimension(error?.message || 'failed to start telemetry stage process', 'failed to start telemetry stage process', 240),
+        env
+      );
+    });
+    child.unref();
+    return true;
   } catch {
     return false;
   }
@@ -451,6 +493,13 @@ function contextFromCliArgs(args) {
   };
 }
 
+function timestampFromCliArgs(args) {
+  if (args['timestamp-ms'] === undefined) return Date.now();
+  const value = Number(args['timestamp-ms']);
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error('--timestamp-ms 必须是正整数毫秒时间戳');
+  return value;
+}
+
 function assertCliArgs(args, allowedOptions, positionalCount) {
   for (const name of Object.keys(args)) {
     if (name !== '_' && !allowedOptions.has(name)) throw new Error(`不支持参数 --${name}`);
@@ -1257,8 +1306,8 @@ export async function runTelemetryCli(argv = process.argv) {
       emitTelemetryError(new Error('invalid telemetry arguments'));
       return 0;
     }
-    assertCliArgs(args, new Set(['run-id', 'root-intent', 'product-type', 'product-name']), 1);
-    const event = stageMetricEvent(args._[0], contextFromCliArgs(args));
+    assertCliArgs(args, new Set(['run-id', 'root-intent', 'product-type', 'product-name', 'timestamp-ms']), 1);
+    const event = stageMetricEvent(args._[0], contextFromCliArgs(args), timestampFromCliArgs(args));
     if (event) updateExistingRunStateFromEvent(event);
     emitMetricEvent(event);
     return 0;

package/skill/references/normal/telemetry.md

@@ -0,0 +1,26 @@
+# 遥测维护参考
+
+本文件只供维护、测试和故障排查按需读取；业务运行默认只执行 `runtime-entry.md` 与动作 runner/script 登记的入口。
+
+## 运行契约
+
+- 固定 stage 枚举、Yuyan 字段和低敏维度以 `scripts/telemetry.mjs` 的 `approvedStages`、事件构造器和测试为准。
+- `start-run` 创建或复用 `run_id`；动作 runner/script 使用异步子进程记录 stage。缺少 run、遥测关闭、落盘失败、网络失败和非 2xx 都不得改变业务 stdout、退出语义或 flow 转移。
+- 前台只写用户系统临时目录下带 `alipay-aipay` 标识的私有 outbox，并启动后台补传；collector 返回 HTTP 2xx 后才删除记录。维护/测试进程不复用默认 run state，默认不远端上传。
+- `PLATFORM_ID` 必须等于当前 `run_id`；模型维度只读 `AIPAY_MODEL`，禁止读取用户项目通用 `MODEL` 推断。
+- 遥测内部行统一使用 `ALIPAY_AIPAY_INTERNAL:` 前缀，禁止对客。
+
+## Run 生命周期
+
+- 根入口用 `root_intent + product_type` 判定复用或新建；组合不变时不按经过时长失效，`UNKNOWN` 补全为明确产品仍复用同一 `run_id`。只有明确换产品、切换根意图或已有 run 终态才重建；用户只说“重新开始/重新走流程/作废本轮流程”但组合没有变化时继续复用。
+- 若宿主提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，新建 run 直接使用该项目 ID。当前宿主项目 ID 与已有状态不兼容时静默跳过不兼容事件且不改写 run state。
+- `integration_only` 由 checklist 最终消息终止；`full_process` 的 Integration 收口不终止，和 `onboarding_only` 一样由 Onboarding closeout 终止。
+- 查看当前主键只使用 `current-run-id`，不得为查看而新建 run。业务脚本继续继承 `PLATFORM_ID=<run_id>`；Agent 不手写环境变量前缀或改写 MCP payload。
+
+## 诊断与补传
+
+`node scripts/telemetry.mjs upload-status` 只读取内部诊断状态。网络类失败且 outbox 有积压时，先执行 `node scripts/telemetry.mjs permissioned-flush-needed`；只有内部事实为 `PERMISSIONED_FLUSH_NEEDED=true` 时才申请一次可复用联网权限运行 `node scripts/telemetry.mjs flush-outbox`。同一 Agent 会话只请求一次；已取得权限后可在后续阶段旁路触发同一异步命令。`flush-outbox` 只启动后台补传并立即返回；用户拒绝、后台失败或非 2xx 都保留 outbox 并继续业务。collector HTTP 结果、失败或待重试结果不得作为业务转移或完成条件。
+
+## 修改要求
+
+修改 stage、run 生命周期、outbox 或上传逻辑时，必须覆盖遥测关闭、缺少 run、写盘失败、无网络、非 2xx、并发 claim、终态 run 和 `PLATFORM_ID` 继承测试。不得把实现细节复制回 `runtime-entry.md` 或两个主 flow。