openxiangda 2.34.0 → 2.34.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.34.0",
+  "version": "2.34.2",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,13 +64,13 @@
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.6.14",
+    "openxiangda-cli": "2.6.16",
     "openxiangda-contracts": "2.34.0",
     "openxiangda-devkit-core": "2.35.0",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
     "openxiangda-mcp": "2.0.62",
     "openxiangda-nest": "2.11.0",
-    "openxiangda-skill-kit": "2.3.37",
+    "openxiangda-skill-kit": "2.3.39",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -136,41 +136,39 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.34.0",
+    "version": "2.34.2",
     "status": "reviewed",
-    "title": "OpenXiangda 2.34.0：持久排队业务计划与结果恢复",
-    "summary": "新增由平台持久受理并自动处理的业务命令，支持关闭页面后继续执行与本人跨设备恢复。",
+    "title": "OpenXiangda 2.34.2：受管读取繁忙恢复与原申请观察期限",
+    "summary": "为受管只读查询提供有界退避，并使持久申请观察遵守原始三十分钟期限，真实依赖和权限故障立即显露。",
     "newFeatures": [
-      "新增 durable 受管命令、独立能力门禁、有界参数及生成的 backend-plan handler 清单。",
-      "openxiangda/nest 提供受执行证明约束的只读计划 handler，平台负责最终原子提交。",
-      "openxiangda/react 与 mobile 提供 useDurableCommand，支持显式提交、原键恢复、本人结果和退避轮询。"
+      "受管详情、本人申请、命令结果和配额查询默认最多恢复120秒、12次请求，可通过budgetMs或AbortSignal收窄。"
     ],
     "fixes": [
-      "严格区分内置 permit 配额所有权与应用 durable 计划，普通业务模型无需迁移到命令独占所有权。",
-      "执行上下文拒绝普通 SDK 写入、事务、通知和 OAuth，读取响应验证标准记录结构。"
+      "读取恢复冻结原参数及身份，遵循服务端Retry-After，只重试明确的容量繁忙；写请求保持单次发送。",
+      "已受理申请以原首次提交时间观察，跨设备使用原acceptedAt；刷新不会延长期限，超期后保留原编号用于显式查询。",
+      "持久结果轮询不再吞掉真实网络、依赖和权限故障。"
     ],
     "affectedUsers": [
-      "构建活动报名、预约、抢票及其他需要持久排队事务的 V2 应用开发者。"
+      "使用受管读取和持久排队能力的活动报名、预约及抢票应用开发者。"
     ],
     "upgradeSteps": [
-      "升级 openxiangda 到 2.34.0，重新安装依赖并生成应用契约。",
-      "先部署支持 data.managed-concurrency.durable@1.0.0 的平台，再声明 durable 命令、handler manifest 和前端恢复流程。",
-      "在隔离测试数据上验证关闭浏览器、原请求恢复、取消后重报和业务原子结果，再分级测量实际容量。"
+      "将应用openxiangda精确依赖升级到2.34.2，刷新同版本资料后检查并部署测试环境。",
+      "验证繁忙恢复、故障提示、原键跨设备恢复及三十分钟期限；在目标硬件测量完整混合负载。"
     ],
     "knownLimitations": [
-      "应用只返回受声明约束的事务计划，不能在 handler 内发送通知或调用普通写入接口。",
-      "受理成功不等于业务成功；队列位置为近似投影，不能推导精确等待时间或服务器容量。",
-      "旧 permit 模式保留，未升级平台会拒绝 durable 包；回滚前须停止新受理并核对已有请求。"
+      "读取恢复仅覆盖明确只读方法；普通Data API和写入没有新增自动重试。",
+      "默认受理恢复预算仍为120秒，accepted观察最长三十分钟；客户端预算不承诺服务端完成时间。",
+      "自动观察停止后可能存在迟到结果，应查询原申请；容量仍需目标环境实测。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "durable 必须具备 data.managed-concurrency.durable@1.0.0，旧 permit 契约继续支持。",
-      "v1": "V1 引擎与业务不变。"
+      "platform": "沿用data.managed-concurrency.durable@1.0.0，兼容已知API_BUSY/RESULT_BUSY的旧503；新入口预算429需匹配平台版本。",
+      "v1": "V1引擎及业务不变。"
     },
-    "sha256": "929abb0ea8cdbb32e38c39131540cd64a248c4e1a68dbde9ff187f35438f8da0",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.34.0"
+    "sha256": "93594d8cc407bef730868e32737ba3e78ca5df955e2d33bc0bb3f6eec8f1d1f9",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.34.2"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.34.1.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.34.1",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.34.1：持久申请受理恢复预算",
+  "summary": "支持配置最长30分钟的自动受理恢复，并保留首次明确提交时间和原申请编号。",
+  "newFeatures": [
+    "useDurableCommand 可用 acceptanceRecoveryMs 配置120秒至30分钟的受理恢复预算。"
+  ],
+  "fixes": [
+    "刷新及恢复原申请不再重新计算受理重试预算；截止后保留查询和迟到结果恢复能力。"
+  ],
+  "affectedUsers": [
+    "需要较长排队等待的活动报名、预约和抢票应用开发者。"
+  ],
+  "upgradeSteps": [
+    "升级 openxiangda 到2.34.1，在需要长时间恢复的业务明确配置 acceptanceRecoveryMs。",
+    "验证原键恢复、截止后查询、未知应答及目标环境的完整排队容量。"
+  ],
+  "knownLimitations": [
+    "默认受理恢复预算仍为120秒；配置值是客户端自动入队预算，不是服务端最终完成承诺。",
+    "旧意图没有首次时间时，只能从首次明确恢复计时，无法证明历史发起时间。",
+    "受理成功不等于报名成功；实际容量需使用独立用户在目标环境验证。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "沿用 data.managed-concurrency.durable@1.0.0；不改变平台事实和permit协议。",
+    "v1": "V1引擎及业务不变。"
+  },
+  "sha256": "f7297f5c779f079b48aa95ef594c9b4d7c373207467e1410aacfda57ca361451",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.34.1"
+}

package/releases/2.34.2.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.34.2",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.34.2：受管读取繁忙恢复与原申请观察期限",
+  "summary": "为受管只读查询提供有界退避，并使持久申请观察遵守原始三十分钟期限，真实依赖和权限故障立即显露。",
+  "newFeatures": [
+    "受管详情、本人申请、命令结果和配额查询默认最多恢复120秒、12次请求，可通过budgetMs或AbortSignal收窄。"
+  ],
+  "fixes": [
+    "读取恢复冻结原参数及身份，遵循服务端Retry-After，只重试明确的容量繁忙；写请求保持单次发送。",
+    "已受理申请以原首次提交时间观察，跨设备使用原acceptedAt；刷新不会延长期限，超期后保留原编号用于显式查询。",
+    "持久结果轮询不再吞掉真实网络、依赖和权限故障。"
+  ],
+  "affectedUsers": [
+    "使用受管读取和持久排队能力的活动报名、预约及抢票应用开发者。"
+  ],
+  "upgradeSteps": [
+    "将应用openxiangda精确依赖升级到2.34.2，刷新同版本资料后检查并部署测试环境。",
+    "验证繁忙恢复、故障提示、原键跨设备恢复及三十分钟期限；在目标硬件测量完整混合负载。"
+  ],
+  "knownLimitations": [
+    "读取恢复仅覆盖明确只读方法；普通Data API和写入没有新增自动重试。",
+    "默认受理恢复预算仍为120秒，accepted观察最长三十分钟；客户端预算不承诺服务端完成时间。",
+    "自动观察停止后可能存在迟到结果，应查询原申请；容量仍需目标环境实测。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "沿用data.managed-concurrency.durable@1.0.0，兼容已知API_BUSY/RESULT_BUSY的旧503；新入口预算429需匹配平台版本。",
+    "v1": "V1引擎及业务不变。"
+  },
+  "sha256": "93594d8cc407bef730868e32737ba3e78ca5df955e2d33bc0bb3f6eec8f1d1f9",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.34.2"
+}

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "9df75c0d1a91f5729dbcca42c5b04f99cc3efc5f6d453ea02dbf571bb6c1f4a7"
+      "sha256": "e6140e8e642539ee51ab51ec9018e7caa751db2a9c931f783891110b987c1615"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.34.0 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.34.0 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.34.0 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.34.0 skill install --force
+pnpm dlx openxiangda@2.34.2 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.34.2 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.34.2 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.34.2 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。

package/skills/openxiangda-v2/references/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.34.0 skill install --force
-pnpm dlx openxiangda@2.34.0 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.34.0 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.34.0 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.34.2 skill install --force
+pnpm dlx openxiangda@2.34.2 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.34.2 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.34.2 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.34.0 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.34.0 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.34.0 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.34.2 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.34.2 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.34.2 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/skills/openxiangda-v2/references/managed-concurrency-frontend.md

@@ -49,6 +49,24 @@ export async function readOffer(
 
 将读取接入应用已有的异步查询状态：初次加载显示局部骨架，空数组显示无可展示内容，失败提供局部重试。组件卸载或资源变化时中止旧请求，迟到响应不能覆盖新资源。同页多个观察者可复用应用已有查询层，查询键包含 `client.scope`、读取 code 和规范化参数，身份变化时清除旧主体视图；当前没有内置的 `useManagedRead` hook。
 
+### 只读预算繁忙恢复
+
+`read`、`mine`、`result`、`allocation` 共用有界恢复：单次调用默认含 HTTP 和等待的总预算 120 秒，最多 12 次总请求。只重试 HTTP 429 的 `CONCURRENCY_API_BUSY`、`CONCURRENCY_RESULT_BUSY`、`CONCURRENCY_RATE_LIMITED`、`CONCURRENCY_SOURCE_BUSY`；兼容旧平台的 HTTP 503 仅限前两个已知预算错误。明确 `retryable: false`、未知 429、权限拒绝、Redis/数据库/授权依赖失败和网络失败直接返回，不用繁忙重试掩盖。
+
+第一次失败后的基础等待为 2 秒，之后指数增加到最多 30 秒；取其与有效服务端提示的较大值，再加 0% 至 25% 随机抖动。提示优先使用合法 `Retry-After`（秒或 HTTP 日期），缺失时使用 `data.retryAfterMs`。若等待达到剩余预算，不提前查询，直接返回最后一次繁忙错误；12 次用完也保留最后繁忙响应。正在进行的请求超过总预算则中止并返回 `CONCURRENCY_READ_RECOVERY_EXHAUSTED`，不以之前的繁忙响应掩盖悬挂请求。
+
+可以传入更短的剩余预算，不能扩展单次 120 秒上限：
+
+```ts
+// budgetMs 含本次请求和所有预算繁忙退避；服务端事实仍为最终依据。
+const receipt = await client.result({ operationId }, signal, {
+  budgetMs: Math.max(0, originalDeadline - Date.now()),
+});
+const offer = await client.read<Offer>('offer', { id: offerId }, signal, { budgetMs: 30_000 });
+```
+
+每次调用在第一次请求前冻结完整参数、环境、主体及权限视角；后续修改表单不会改变重试内容。身份或视角变化时停止旧调用并返回 `CONCURRENCY_IDENTITY_CHANGED`。`AbortSignal` 可以中止请求和等待；组件卸载应中止旧读取。`enqueue`、`accept`、`cancel` 等写方法不使用这层自动重试，持久申请的原键受理恢复由下述控制器单独管理。普通 Data API 也不自动获得此策略。
+
 `freshness: 'stale'` 表示返回的是允许使用的旧内容，并不证明后台刷新已经成功。保留内容并提示“当前展示最近一次可用信息”；按新鲜期和有界退避刷新，超过 `staleUntil` 后不能继续无限展示。手动刷新仍调用同一命名读取，不绕回普通 CRUD。
 
 详情与余量使用不同读取声明。页面倒计时本地显示，不能每秒重查活动；资格、开放时间和扣减仍由服务端决定。缓存余量不保证获票；允许补量或释放的业务，也不能因旧余量为零永久阻止新的有效申请。等待期间不要重复读取详情或表单。
@@ -190,7 +208,7 @@ export function ClaimAction({ offerId }: { offerId: string }) {
 | 关闭状态区后返回 | 继续查看原操作，不宣称已取消 |
 | 取消与受理/成功同时发生 | 显示服务端原结果；错误时保留待核实状态 |
 | 身份切换、存储被禁用 | 不串用旧主体资料，不静默丢弃恢复能力 |
-| 网络或依赖异常 | 退避观察，保留原键，不绕回数据库或快速换键重提 |
+| 网络或依赖异常 | 显示故障并保留原键；恢复后查询原结果，不绕回数据库或快速换键重提 |
 | 许可到期、预占到期 | 分别核实准入与分配，互不冒充 |
 | 键盘、屏幕阅读器、窄屏 | 状态可读，焦点可控，关闭与取消语义清楚 |
 
@@ -201,14 +219,16 @@ export function ClaimAction({ offerId }: { offerId: string }) {
 
 ```tsx
 const client = useMemo(() => createManagedConcurrencyClient(), []);
-const command = useDurableCommand({client,command:'registration-enroll',resourceKey:activityId});
+const command = useDurableCommand({client,command:'registration-enroll',resourceKey:activityId,acceptanceRecoveryMs:30*60*1000});
 // 仅真实点击提交；不是 useEffect 或页面 mount 回调。
 const submit = () => command.submit({activity:activityId,channel:channelId,agreed:true,phone});
 ```
 
-hook 从 `openxiangda/react` 和 `openxiangda/mobile` 导出。state、initialized、isObserving、requestKey、receipt、errorCode 用于统一状态区；submit(input)、resume()、refresh()、stop() 分别为明确提交、用冻结 input 重试原请求、恢复查询和停止观察。挂载只查本地原 key 或服务端 mine，不自动 enqueue。未知应答保留原 key 与 input；用户恢复后先查原结果，不能换 key 重试。浏览器存储失败在提交前明确失败。未知应答后的恢复按钮调用 resume()，不传当前可能已经修改的表单。snapshot.input 可恢复本地冻结表单；跨设备只有回执时不展示推测的原输入。一次明确 submit/resume 期间，429、暂时5xx或网络错误会按原 key/input 自动退避恢复，先查原结果再重试 enqueue，最多6次、最长120秒，遵守更长的 Retry-After；尚无 receipt 时只能提示“正在确认受理”，不能承诺可关闭页面。用完预算保留原意图，明确点击 resume() 继续。如果刷新时原请求尚未被平台受理，挂载只查询，明确点击 resume() 才重新启动有界受理重试。
+hook 从 `openxiangda/react` 和 `openxiangda/mobile` 导出。state、initialized、isObserving、requestKey、receipt、errorCode 用于统一状态区；submit(input)、resume()、refresh()、stop() 分别为明确提交、用冻结 input 重试原请求、恢复查询和停止观察。挂载只查本地原 key 或服务端 mine，不自动 enqueue。未知应答保留原 key 与 input；用户恢复后先查原结果，不能换 key 重试。浏览器存储失败在提交前明确失败。未知应答后的恢复按钮调用 resume()，不传当前可能已经修改的表单。snapshot.input 可恢复本地冻结表单；跨设备只有回执时不展示推测的原输入。一次明确 submit/resume 期间，429、暂时5xx或网络错误会按原 key/input 自动退避恢复，先查原结果再重试 enqueue，默认最多6次、最长120秒；可用 acceptanceRecoveryMs 明确配置120000至1800000毫秒，更长预算最多120次，遵守更长的 Retry-After。预算从首次明确提交计时，刷新或 resume() 不重置；旧版意图没有时间时从首次明确恢复计时，无法证明更早的提交时间。尚无 receipt 时只能提示“正在确认受理”，不能承诺可关闭页面。用完预算保留原意图，停止自动入队，refresh() 仍可只读核对迟到结果；这不是报名失败。该预算只控制受理恢复，不是后端最终完成时限承诺。如果刷新时原请求尚未被平台受理，挂载只查询，明确点击 resume() 才重新启动有界受理重试。
+
+已受理申请的自动观察最多持续到首次明确提交后的 30 分钟，默认受理恢复仍为 120 秒，两者分别计算。每次结果读取同时受单次 120 秒和原提交剩余时间限制；刷新和 resume 不重新获得观察时间。跨设备没有本地首次时间时，用原回执 acceptedAt 计算观察窗口，不能以页面挂载时间重新计时。达到窗口后保留原意图，状态为 recovering、isObserving 为 false，提示稍后核对；明确 refresh 仍可查询迟到终态，但不重新启动已经到期的自动观察，也不自动提交。
 
-默认每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动；暂时失败指数退避，终态停止。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
+正常待处理结果每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙时，外层可在原观察窗口内指数退避继续；权限、依赖、网络故障或悬挂请求超过读取预算时立即停止自动观察，显示 error 并保留原回执和请求键。终态停止。受理恢复中核对原结果同样只允许已知预算繁忙继续，读取依赖失败不能被外层重试隐藏。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
 
 refresh 会优先恢复 mine 返回的新进行中周期，避免本地历史 succeeded 遮蔽另一个设备的新申请。不要在 mount 发现历史 succeeded 时自动跳成功页或永久禁用提交。它可能已经被管理员取消，需结合当前业务记录展示。只有用户明确再次点击 submit，且原请求已有终态，SDK 才创建新的 requestKey；活跃请求或未知应答始终恢复原 key。平台明确返回未受理的参数错误（400 + CONCURRENCY_INPUT_INVALID 等约定错误）时，SDK 才清除被拒输入，允许修正后再提交；未知 400、409、429、5xx 和网络错误仍保留原意图。成功提示以 receipt.state==='succeeded' 和 receipt.result 为准，accepted/executing 只显示「已登记，处理中」。