openxiangda 2.35.3 → 2.44.0

package/documentation/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.35.3 skill install --force
-pnpm dlx openxiangda@2.35.3 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.35.3 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.35.3 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.44.0 skill install --force
+pnpm dlx openxiangda@2.44.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.44.0 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.44.0 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.35.3 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.35.3 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.35.3 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.44.0 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.44.0 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.44.0 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/documentation/managed-concurrency-frontend.md

@@ -224,17 +224,22 @@ export function ClaimAction({ offerId }: { offerId: string }) {
 
 ```tsx
 const client = useMemo(() => createManagedConcurrencyClient(), []);
-const command = useDurableCommand({client,command:'registration-enroll',resourceKey:activityId,acceptanceRecoveryMs:30*60*1000});
+const command = useDurableCommand({client,command:'registration-enroll',resourceKey:activityId,
+  acceptanceRecoveryMs:30*60*1000,discoveryRecoveryMs: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秒；可用 acceptanceRecoveryMs 明确配置120000至1800000毫秒，更长预算最多120次，遵守更长的 Retry-After。预算从首次明确提交计时，刷新或 resume() 不重置；旧版意图没有时间时从首次明确恢复计时，无法证明更早的提交时间。尚无 receipt 时只能提示“正在确认受理”，不能承诺可关闭页面。用完预算保留原意图，停止自动入队，refresh() 仍可只读核对迟到结果；这不是报名失败。该预算只控制受理恢复，不是后端最终完成时限承诺。如果刷新时原请求尚未被平台受理，挂载只查询，明确点击 resume() 才重新启动有界受理重试。
+hook 从 `openxiangda/react` 和 `openxiangda/mobile` 导出。state、initialized、isObserving、acceptanceConfirmed、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() 不重置；旧版意图没有时间时从首次明确恢复计时，无法证明更早的提交时间。尚无已核对归属的受理回执时 acceptanceConfirmed 为 false，只能提示“正在确认受理”，不能承诺可关闭页面。为 true 仅证明此原申请曾持久受理，不代表已成功，也不能替代服务端证明。用完预算保留原意图，停止自动入队，refresh() 仍可只读核对迟到结果；这不是报名失败。该预算只控制受理恢复，不是后端最终完成时限承诺。如果刷新时原请求尚未被平台受理，挂载只查询，明确点击 resume() 才重新启动有界受理重试。
 
-已受理申请的自动观察最多持续到首次明确提交后的 30 分钟，默认受理恢复仍为 120 秒，两者分别计算。每次结果读取同时受单次 120 秒和原提交剩余时间限制；刷新和 resume 不重新获得观察时间。跨设备没有本地首次时间时，用原回执 acceptedAt 计算观察窗口，不能以页面挂载时间重新计时。达到窗口后保留原意图，状态为 recovering、isObserving 为 false，提示稍后核对；明确 refresh 仍可查询迟到终态，但不重新启动已经到期的自动观察，也不自动提交。
+初查/refresh 的 discoveryRecoveryMs 默认仍是 120000 毫秒，应用可以显式配置 1 至 1800000 毫秒。上面的 30 分钟是热点应用的主动选择，不会扩大其他应用默认值。一轮发现的原键 result 和必要的 mine 共用固定、单调计时的读取截止；有尚未到期的原申请时还取原提交剩余窗口的较小值。每次底层只读调用在剩余预算大于 120 秒时最多 120 次请求，其他情况最多 12 次，遵守服务端退避与随机抖动。同一控制器的重复 refresh 共用当前任务，stop 后再次挂载可以开始新读取，旧代次的迟到应答不能覆盖新状态。这项预算不续期、不写入，也不为首个提交额外添加等待。
+
+已受理申请的自动观察最多持续到首次明确提交后的 30 分钟，默认受理恢复仍为 120 秒，两者分别计算。自动观察的每次结果读取同时受单次 120 秒和原提交剩余时间限制；刷新和 resume 不重新获得观察时间。跨设备没有本地首次时间时，用原回执 acceptedAt 计算观察窗口，不能以页面挂载时间重新计时。达到窗口后保留原意图，状态为 recovering、isObserving 为 false，提示稍后核对；明确 refresh 仍可用有界初查预算查询迟到终态，但不重新启动已经到期的自动观察，也不自动提交。
 
 正常待处理结果每次至少间隔 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 只显示「已登记，处理中」。
+refresh 有本地原键时先薄查询原 key；找到已受理非终态后不再 mine。没有本地意图或原申请已有终态时，mine 优先恢复新的进行中周期，避免本地历史 succeeded 遮蔽另一个设备的新申请。原键明确 404 后保留一次本人列表兜底；未确认的本地意图只能采用同原键回执。列表中只有别的活跃周期时显示 recovering / CONCURRENCY_ORIGINAL_REQUEST_REQUIRED，并保留原 key/input；没有匹配时显示 CONCURRENCY_ACCEPTANCE_UNCONFIRMED，提供「核对原申请」和「恢复原申请」动作。不能把无匹配解释为业务失败，也不丢弃可能迟到受理的原意图。已知读取繁忙耗尽显示 recovering，真实依赖、网络、权限或未知 400 显示 error；两种状态均保留原键、输入和已受理回执，读取失败不自动提交。
+
+不要在 mount 发现历史 succeeded 时自动跳成功页或永久禁用提交。它可能已经被管理员取消，需结合当前业务记录展示。只有用户明确再次点击 submit，且原请求已有终态，SDK 才创建新的 requestKey；活跃请求或未知应答始终恢复原 key。平台明确返回未受理的参数错误（400 + CONCURRENCY_INPUT_INVALID 等约定错误）时，SDK 才清除被拒输入，允许修正后再提交；未知 400、409、429、5xx 和网络错误仍保留原意图。成功提示以 receipt.state==='succeeded' 和 receipt.result 为准，accepted/executing 只显示「已登记，处理中」。
 
 permit 的 ManagedCommandGate 仍只用于 admitted 短确认，不用于 durable。durable 不能套任意前端 onSubmit 冒充后台事务，真正业务必须由已声明的 backend-plan handler 返回受管计划。

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.35.3",
+  "version": "2.44.0",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "f32771aac73fa5cbe2ef41f30f997abb723d18fb48b1fa6418553a7632da073b"
+      "sha256": "5a0fd1357652426798651f3a947308abb2a47d391a4c523a4f9739c564ce4d0d"
     },
     {
       "id": "product-design",
@@ -60,7 +60,7 @@
       "id": "frontend",
       "title": "页面与标准组件扩展",
       "file": "frontend.md",
-      "sha256": "d2e313a5bfffc9aea46e4f9936ae79908588c2a4727824e2b211b886baa1f392"
+      "sha256": "9fdc5f950356843dca2dcfad3c0f5ff0d44b5158bd79cbd0f14ae99a48a543cf"
     },
     {
       "id": "field-components",
@@ -84,7 +84,7 @@
       "id": "workflow-events",
       "title": "审批、事件与通知",
       "file": "workflow-events.md",
-      "sha256": "4dcb4b24aeb1f94f2d8c8261b41b0a602c365eeb68fc89592274397dbb9915e1"
+      "sha256": "712024dc7f01a645c458aa98bc53b3ca817909356ca9255c2ab857698f4d66ef"
     },
     {
       "id": "backend",
@@ -114,13 +114,13 @@
       "id": "managed-concurrency-frontend",
       "title": "并发能力的前端接入",
       "file": "managed-concurrency-frontend.md",
-      "sha256": "0adcbada38bbe2c5775d92f5ca00a232ead076058c6833ebcd9cf9cb798eb0f5"
+      "sha256": "0e6c4aa63ae82f7ce8c19c1dea061688c6507cebe93733be715b27fab71afa2e"
     },
     {
       "id": "administration",
       "title": "应用管理与有效配置",
       "file": "administration.md",
-      "sha256": "b023843d340e6664aca09009b2a6d195ce5fc0a92de4c075c2a9db54e99f3b17"
+      "sha256": "a5e17ced019746f314bf9a2005b023786308204233565b96ddf3db2150de2216"
     },
     {
       "id": "testing",

package/documentation/workflow-events.md

@@ -153,13 +153,55 @@ Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`，并要求
 
 ## 标准工作流范围
 
-首期只支持 `approval`、`condition`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
+标准节点支持 `approval`、`condition`、`cc`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
 
 除命令集之外，平台为实例管理员提供两个维护动作：`admin_jump`（把处于运行或退回状态的实例跳转到指定节点）与 `admin_delete`（删除实例，可选同时删除表单数据、是否触发自动化）。两者走平台管理端点的预览/执行两步流程并要求同源浏览器请求，不属于应用声明的工作流命令，也不占用 `commandToken` 命令合同。
 
 复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
 
 所有页面和消息动作必须来自后端 Workflow Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
+
+### 自动抄送 {#automatic-cc}
+
+在固定拓扑中声明 `cc` 节点，进入时解析接收人、保存抄送事实，然后继续 `next`。
+完整声明例子见 `examples/workflow-administration/automatic-cc.ts`：
+
+```ts
+copy: {
+  id: 'copy', kind: 'cc', title: '抄送办理负责人',
+  binding: 'readers', next: 'approved', emptyPolicy: 'block',
+  administration: { assigneeProviders: ['app_role', 'fixed_users'] },
+},
+```
+
+接收 binding 支持 `fixed_users`、`initiator`、`input_users`、`form_field_users`、
+`app_role`、`app_role_in_scope`、`previous_node_actor`。仅使用事务内原生来源，
+不支持 `application_provider` 或需要申请人交互的 `initiator_select`。名单按用户去重，
+每次进入最多 20 人；`min/max` 默认 1/20，非空名单仍必须符合声明的下限。
+角色查询超过 200 条有效成员行时明确拒绝，不能使用截断后的名单。
+范围角色要求对应范围的 `cc` 授权（或未限制操作、`*`），仅 `approve` 不满足。
+抄送不套用审批代理。
+
+`emptyPolicy: 'block'` 在真实空名单时回滚触发动作，补齐人员后可重试原申请或任务；
+`'skip'` 记录无人跳过并继续。未知角色、失效账号、非法输入和超限均属于错误，
+不会被 skip 吞掉。通知默认开启；`notify: false` 仍保存抄送审计、事件和实例阅读关系，
+Notification Hub 不生成该次抄送消息。渠道失败通过原 Hub 恢复，不回滚流程。
+
+进入记录、系统抄送日志及事件在同一事务提交。原命令重放不重复抄送；退回等导致实际
+再次进入时产生新轮次，可采用新的兼容节点配置，过去名单和配置保持冻结。时间线显示
+“流程自动抄送”，不会把系统动作记为发起人的人工操作。
+
+接收人可以使用既有抄送列表及实例详情，不获得审批权、后台权限或通用业务数据读取权。
+标准流程详情由服务器按页面代码声明的固定详情字段投影读取；需要排除敏感字段时，
+在 `crud.detail` 和 `subject.factProjection` 中明确选择允许字段，不能仅在浏览器隐藏。
+通用 Data API 继续核验当前数据授权，流程节点不提供字段权限配置。
+
+含 cc 的包自动声明 `workflow.automatic-cc@1.0.0`，平台正式迁移后自动提供该能力，
+没有额外开关。管理员仅可修改名称、说明及代码显式开放的接收来源，
+`next/emptyPolicy/notify` 保持代码所有；配置 SDK 见[应用管理](./administration.md#node-administration)。
+
+### 工作流命令
+
 Surface 同时签发短期、一次性的 `commandToken`，绑定当前用户/会话、应用环境
 Head、实例/任务版本、允许的命令集合与 CSRF。命令请求只提交
 `commandToken + idempotencyKey + input`；旧的 caller-authored
@@ -242,8 +284,8 @@ Native Data 事件的 capture plan 由当前 Head 的 Event、Data、AuthZ revis
 不是增量 patch。definition 和 activation 必须一致声明
 `acceptedCommandDeactivationPolicy`：`finish-pinned` 让已接受的 durable process
 command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消尚未启动的命令；
-既有 Workflow instance 始终按固定版本继续。所有审批人 Provider 的 `min/max`
-默认 1/200，最大 200。
+既有 Workflow instance 始终按固定版本继续。审批人 Provider 的 `min/max`
+默认 1/200，最大 200；自动抄送默认 1/20，最大 20。
 需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
 
 平台按 desired set 直接覆盖环境 Head，不做版本比较。因此 `openxiangda deploy`
@@ -402,3 +444,171 @@ readability: {
 说明的执行位置只能是 submission、某节点的 node_input 或 completion。它是对已有逻辑的注释，不会自动执行计算或产生新流程节点。没有实际计算步骤时，不应写成“系统已计算总金额”。条件的变量必须存在于输入 Schema；对旧未标注定义，读取投影会明确给出未知来源诊断。
 
 可选 `source: { path, symbol?, digest }` 只返回源码位置和 SHA256，不返回源码内容。path 指向工作区 apps/packages/platform 下的代码文件，digest 为 `sha256:<原始文件字节摘要>`。工作区加载时核对文件存在、无符号链接、大小和摘要；源码变化后以 WORKFLOW_LOGIC_DESCRIPTION_STALE 阻止封装，开发者应核实说明并更新引用。32 个文件、单文件 2MiB、总量 8MiB 为上限。元数据不能验证任意 TypeScript 的业务含义，业务说明及验收仍由开发者维护。
+
+## 持久业务步骤
+
+必须收到业务计算或外部操作结果后才继续的流程，用固定 `action` 节点。平台自动
+提供 `workflow.durable-business-step@1.0.0`；应用包含动作时自动声明能力需求并
+按需引导标准 Nest 后端，普通无动作应用保持原合同。字段显隐/编辑/必填继续由
+页面代码负责；动作版本、Schema、条件和连线只由开发者发布。
+
+```ts
+const amountSchema = { type: 'object', additionalProperties: false,
+  required: ['amountCents'], properties: { amountCents: { type: 'integer', minimum: 0 } } };
+// 放入已声明流程的 nodes；amount-route 必须是同一固定定义中的真实目标。
+const calculate = {
+  id: 'calculate', kind: 'action', title: '核算金额', next: 'amount-route',
+  handler: { code: 'calculate-v1', version: 1, mode: 'pure' },
+  inputSchema: amountSchema, outputSchema: amountSchema,
+  inputs: { amountCents: { source: 'fact', path: 'amountCents' } },
+};
+// 放入 events.subscriptions；应用 backend.enabled=true，消费 generated manifest。
+const subscription = {
+  code: 'calculate-v1', eventTypes: ['openxiangda.workflow.step.requested.v2'],
+  filter: { workflowStep: { handlerCode: 'calculate-v1' } },
+  payload: { includeChanges: false, fields: [] },
+};
+```
+
+成功输出写入 `steps.calculate.amountCents`。后续条件或动作只能读取每条路径上
+已经完成的生产者；前向/自引用、非法路径和输入类型不兼容会拒绝编译。步骤后
+需要 HTTP provider 或发起人选人的组合暂不支持，先在动作中产生有 Schema 的
+人员数据，再使用原生人员字段/角色分派。示例见
+`examples/workflow-administration/business-step.ts`。
+
+Nest 使用 `@OpenXiangdaEventHandler(generatedContract)` 注册实现，`handle` 返回
+`{ output, receipt? }`；上下文 `workflowStep` 包含验证过的固定请求，
+`idempotencyKey` 是稳定 executionId。不得通过返回值任意指定下一节点或调用
+Workflow 跳转。使用标准 `PlatformOpenXiangdaEventReceiptStore`；内存 receipt
+不能完成业务步骤。
+
+`pure` 用于无外部效果的计算；`reconciled-effect` 必须实现 `reconcile(event,
+context)`：成功返回 `{ status:'succeeded', result:{output,receipt?} }`，确定未执行
+返回 `{status:'not-executed'}`，无法确定返回 `{status:'unknown'}`。每次尝试先
+核对原执行键，未知结果需要人工核对后重放原事件。增加v2时保留v1合同及代码；
+旧具名版本合同不可变，缺失实现明确失败，不自动改用最新版本。
+
+输入输出各16KiB、回执2KiB，最多32映射、200节点；Schema闭合且有界，无远端
+引用或正则执行。平台先持久保存合法结果，再尝试流转；下游缺人等失败保留
+`result_ready`，恢复仅推进，不再次执行处理器。自动恢复最多5次，每批20；
+outbox容量等事务故障会回滚，处理器按原键核对后重交，不承诺跨服务绝对一次。
+撤回后的未领取步骤拒绝执行，已开始的外部操作仍需原键核对。
+
+管理员在标准实例管理页或 `WorkflowBusinessStepRecoveryPanel` 查看并继续受阻
+步骤；公开客户端为 `loadWorkflowBusinessStepRecovery`、
+`previewWorkflowBusinessStepRecovery`、`executeWorkflowBusinessStepRecovery`。
+复用原管理权限/token/CAS/CSRF/审计，提交失败保留相同token/input/idempotencyKey。
+组件通过 `onDraftStateChange` 报告 dirty/busy/unknown；宿主将其接入已有导航保护，
+提交中或结果未知时保留组件和实例。未知结果只允许显式重试原恢复请求；首次明确
+的4xx拒绝可保留原因并重新预览。宿主刷新失败不改变已经确认的提交结果。
+等待处理器的失败从原事件管理受控重放，保留原执行键。普通详情只显示安全状态
+摘要；原输入、输出和外部回执不放入普通时间线。
+
+## 代码任务页面与补填 {#task-page-submit}
+
+需要办理人补填时，在定义的 `taskPages` 声明命名页面，审批节点以
+`taskPageCode` 引用。页面字段顺序、`readonly`、`required`、`visibleWhen` 和
+`requiredWhen` 属于应用代码；流程管理员不能覆盖页面字段、条件或连线。
+字段类型和编码来自同一个 Native 模型。例子见
+`examples/workflow-administration/task-page.ts`。
+
+页面表达式只读取本页 `values.*`，平台以合并后的业务值强制显隐和必填。
+最多16页、每页64字段、单次值64KiB，表达式8层/64节点。
+系统、流水号和隐藏字段不可作为补填入口。根附件、图片复用平台托管文件；
+签名、子表和富文本仍需后续任务页面支持，不将它们降为任意 JSON。
+
+标准 PC/手机任务页和 `WorkflowTaskOperationsPanel` 自动显示当前参与人的
+`surface.taskForm`。`save_form` 表示“提交补填，继续办理”，不是私有草稿。
+approve/resubmit 携带 `form: { expectedRevision, values }` 时，Native 业务更新、
+事实刷新、任务决定和下游流转同事务提交。reject/return/transfer 等操作不得
+夹带表单。审批人仅获得当前任务对应的单记录/页面字段入口，不获得通用 CRUD。
+
+相同幂等键不同输入拒绝；结果未知时保留原 token/input/key。共享组件锁定
+编辑，只重试原请求或调用 `loadWorkflowTaskCommandReceipt(taskId, key, tokenDigest)`
+查询本人原回执。重载只保存定位信息和 SHA256 token 摘要，不保存凭据或表单。
+`not_observed` 仍然未知；只有平台锁住确切凭证、确认数据库时间已过期且未使用
+的 `expired_unconsumed` 才能解除等待，供用户核对资料后重新确认。
+组件复用宿主的 `OpenXiangdaApplication` 导航保护；成功后刷新失败不变成提交失败。
+
+嵌入自定义详情时，可用 `renderLayout={({ content, actions, surface }) => ...}` 将补填表单和
+恢复提示放在可滚动正文，将操作按钮放在底栏。两部分始终使用同一个任务面板，
+不要分别创建两个面板或复制其表单、请求和回执状态。`surface` 是面板当前实际展示的
+资料，自定义详情用它显示刷新后的字段；加载或无可用资料时为空。标准详情已采用该布局。
+
+多人补填与管理纠错使用 Native 记录 CAS，冲突保留输入。首次请求的明确拒绝会只读刷新，
+修订变化时对照最新已保存值和本人输入，核对前锁住字段与操作；可选择保留输入或采用最新值。
+拒绝后的读取失败明确提示本次未提交，锁住旧操作，恢复读取后再核对；未知结果仍只能恢复原请求。
+补填刷新固定事实投影；
+修改已计算步骤的输入时清除当前失效输出及依赖输出。仅退回 replay 且所有前向
+审批路径确定重经生产者时允许；resume_current 或后置补填跳过重算会返回
+`WORKFLOW_TASK_FORM_RECOMPUTATION_REQUIRED` 并回滚，历史结果与签名保持。
+自动能力为 `workflow.task-page-submit@1.0.0`，平台初始化无需额外开关。
+
+### 任务私有草稿
+
+标准PC/手机任务页和嵌入面板提供“保存私有草稿”“我的草稿”。暂存仅本人可见，
+不会更新业务资料、事实、待办或推进任务；可以保存尚未完成必填的标量输入。
+页面的显隐/只读规则和Native类型仍强制，管理员没有字段覆盖或读取他人草稿的入口。
+
+自定义页面从 `openxiangda/core` 或 `openxiangda/react` 调用
+`loadWorkflowTaskDrafts(taskId)`、`saveWorkflowTaskDraft(taskId, input)` 和
+`removeWorkflowTaskDraft(taskId, { id, expectedRevision })`。
+保存输入为 `{ id, expectedRevision, recordRevision, values }`：首写前固定UUID及
+`expectedRevision: 0`；recordRevision来自当前taskForm.expectedRevision。
+身份、环境、业务记录和固定页面由平台派生，不传actor/resource/page作为授权。
+可编译例子见 `examples/workflow-administration/task-draft.ts`。
+
+最多20份/90天与同用户、应用、环境、资源的其他表单草稿共享，单份最多64字段/64KiB。
+字段支持根附件、图片，暂不包含签名、富文本或子表。读到不兼容草稿时只返回安全标识与诊断，
+不静默丢弃或泄露旧值。失去任务、角色或代理资格后不能继续读/用。
+
+读取不会自动覆盖输入；采用前确认，业务基线变化先核对并再次保存。相同输入暂存成功后
+可安全离开，后续新编辑恢复导航保护；浏览器持久存储不保存字段值。
+结果未知保留原id/CAS/values，仅核对同id或重试原保存；同一次最后保存确认不新增修订，
+其他CAS冲突保留输入。新id必须是用户明确另存，不能用自动另存掩盖未知结果。
+
+正式 `form: { expectedRevision, values, draft: { id, expectedRevision } }` 可以包含暂存之后的新编辑。
+平台锁住本人草稿及业务基线，再沿原save_form/approve/resubmit命令同事务更新业务并消费，
+失败全部回滚。原成功命令重试先返回唯一Workflow回执，不因草稿已消费重复写入。
+任务真正关闭才过期未消费草稿，all/sequence任务仍可办理时保留其他人的有效草稿。
+能力 `workflow.task-private-drafts@1.0.0` 自动提供，无额外配置开关。
+
+### 任务附件与图片
+
+当前任务的可编辑 `file/image` 字段自动接入标准 PC/手机上传、缩略图、预览和下载。
+当前处理资格不授通用资源 CRUD；平台从固定任务派生记录、页面、身份和环境，
+上传时还核验**已保存业务资料对应的页面状态**。局部修改才显示附件字段时，
+先“保存补填”使字段生效，再上传；组件说明此边界，不自动提交业务值。
+
+自定义页面可从 `openxiangda/core` 或 `openxiangda/react` 调用：
+
+```ts
+const input = { id: crypto.randomUUID(), fieldCode: 'evidence',
+  fileName: file.name, fileSize: file.size, contentType: file.type };
+const plan = await initiateWorkflowTaskFileUpload(taskId, input);
+// pending 才按 plan.uploadMethod/uploadUrl/headers 上传原 File；ready 直接采用 plan.file。
+const readyFile = await completeWorkflowTaskFileUpload(taskId, input.id);
+// 结果未知时：loadWorkflowTaskFileUploadPlan(taskId, input.id)，或重试同 ID/规格。
+```
+
+上传 ID 必须在第一次请求前固定。标准组件一次处理一个文件；上传中或结果未知时
+保留原 File、ID、规格和当前输入，锁住新任务动作与草稿写入，提供“核对原上传”
+和“重试原上传”。ready 结果不再 PUT；完成响应丢失后只恢复原完成结果。
+文件字节、签名地址与表单值不进入浏览器持久存储。离开未完成上传时需先确认结果。
+
+预览字段组件传入 `workflowFileBinding: { taskId, resourceCode, recordId, fieldCode }`；
+正式实例详情使用原 `instanceId` binding。同一 binding 只提供一种范围。
+仅本人当前任务可读私有暂存文件，其他处理人和管理员没有私有读取特权。
+当前根业务记录已经引用的文件可按该任务页面规则读取；隐藏、资格失效或任务关闭后拒绝。
+通用 Native 完成、删除和未绑定文件读取不能绕过此范围。
+
+附件完成后仍只是当前输入；私有草稿延长文件保留至该草稿到期，业务绑定再移除引用
+仍尊重该保留期。原 save_form/approve/resubmit 验证真实文件状态、字段、范围与元数据，
+同事务提交业务引用、事实、任务决定和草稿消费；失败全回滚。完成上传时平台复制为
+独占正式对象，旧上传地址不能再修改正式字节。
+
+单文件不超过字段限制与100MiB；每账号/应用/环境最多100个尚未业务绑定的任务文件，
+声明大小合计200MiB。此大小是上传容量预算，staging/正式对象与缩略图另有存储开销。
+复用既有 Native 文件引用 worker 和 GC；流式正式复制限时10秒。
+需要服务端正式 SQL `AddWorkflowTaskManagedFilesV2` 和自动能力
+`workflow.task-managed-files@1.0.0`，初始化无需新增开关。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.35.3",
+  "version": "2.44.0",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -66,13 +66,13 @@
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
     "elkjs": "0.12.0",
-    "openxiangda-cli": "2.6.21",
-    "openxiangda-contracts": "2.35.0",
-    "openxiangda-devkit-core": "2.36.0",
+    "openxiangda-cli": "2.6.37",
+    "openxiangda-contracts": "2.43.0",
+    "openxiangda-devkit-core": "2.41.2",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.63",
-    "openxiangda-nest": "2.11.1",
-    "openxiangda-skill-kit": "2.3.41",
+    "openxiangda-mcp": "2.0.73",
+    "openxiangda-nest": "2.13.3",
+    "openxiangda-skill-kit": "2.3.52",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -138,49 +138,39 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.35.3",
+    "version": "2.44.0",
     "status": "reviewed",
-    "title": "OpenXiangda 2.35.3：运行时繁忙恢复与可读流程图",
-    "summary": "应用进入时可有界等待平台明确的繁忙响应，同身份刷新保留页面和原申请；流程图使用与不可变执行定义同源的投影展示说明、变量来源与实例路径。",
+    "title": "OpenXiangda 2.44.0：当前任务的托管附件与图片",
+    "summary": "代码任务页面支持根附件与图片，普通审批人通过固定任务上传和预览，草稿保留和正式流程提交复用平台文件生命周期。",
     "newFeatures": [
-      "现有运行时 current 读取在明确的入口繁忙时按服务端提示和抖动退避，最长等待五分钟、最多一百二十次读取，并支持离页取消。",
-      "公开 WorkflowReadability、validateWorkflowReadability、projectWorkflowGraph 及共享 WorkflowDiagram，展示流程说明、条件优先级、变量来源和持久执行决定对应的路径，支持搜索、键盘及窄屏节点列表。",
-      "流程图使用懒加载 React Flow 与 ELK 正交布局，支持直角连线、平移缩放、节点定位、分支条件标签和缩略导航。",
-      "审批节点可显式声明管理员可调整的模式、人员来源和按钮上限；编译器复用有界校验，SDK 提供配置读取、CAS 更新和幂等回执，任务冻结有效配置。"
+      "任务文件 SDK 支持固定 ID 的原计划与完成恢复，标准 PC/手机上传及预览自动接入。",
+      "编译器按可编辑任务文件申请 workflow.task-managed-files 自动能力，无额外默认关闭开关。"
     ],
     "fixes": [
-      "启动、焦点和可见性检查合并挂起身份读取；同身份刷新保留已验证页面和草稿，临时服务故障可重新检查，真实身份、环境、权限作用域变化或拒绝使旧受管客户端失效。",
-      "退出通知优先于仍在加载的身份请求，旧响应和取消回调不会恢复旧身份或覆盖登录入口。验证 current 成功后仅清除当前路径的入口等待截止。",
-      "安全只读传输故障最多三次总尝试；权限投影等待保留原十秒限制，普通应用请求和写入不会因本次修改自动重放。",
-      "管理员流程节点配置使用平台已有的 admin controller，修正上下文、配置读取和保存地址，保留环境、CAS、幂等操作标识与权限拒绝。",
-      "管理员流程节点配置保留平台返回的具体冲突错误码，页面可准确提示配置修订和幂等冲突。",
-      "StrictMode 同一提交的清理、重挂载接管原 current owner，避免重复初始化读取；观察取消立即生效，无人接管时释放共享请求，安装身份必须仍有活跃观察者，原读取预算与退出优先级保留。",
-      "标准任务和实例详情按应用声明返回对应设备的用户流程中心，避免普通申请人被带入管理后台；独立详情组件可显式指定返回路径，抽屉关闭和页面授权保持原行为。"
+      "上传结果未知时保留原文件与请求并锁住新流程动作和草稿写入；ready 结果不再次 PUT。",
+      "任务表单和本人草稿比较使用任务文件范围，避免依赖通用 CRUD 预览资格。"
     ],
     "affectedUsers": [
-      "使用 V2 运行时及持久排队能力的活动报名、预约、抢票应用开发者。",
-      "需要展示不可变流程定义、说明及实例执行路径，或启用有界审批节点配置的平台维护者和应用开发者。"
+      "声明 file/image 任务补填页面的 V2 应用开发者、办理人和平台维护者。"
     ],
     "upgradeSteps": [
-      "将应用 openxiangda 精确升级到 2.35.3；平台流程图消费者将 openxiangda-contracts 精确升级到 2.35.0，同批工具链使用 openxiangda-devkit-core 2.36.0 和 openxiangda-cli 2.6.21，更新锁文件。",
-      "统一验证运行时繁忙恢复、同身份刷新、退出与真实身份切换，以及流程图说明与持久执行路径后发布同一冻结候选；启用管理员节点配置时确认平台支持 workflow.node-administration。",
-      "在目标服务器另外测量完整页面进入、提交、自然结果查询及最终处理时间；客户端恢复测试不作为硬件并发容量证据。"
+      "消费同批本地 SDK/contracts 与匹配平台 Server，应用迁移 AddWorkflowTaskManagedFilesV2，刷新资料并重启。",
+      "局部修改才显示附件字段时先保存补填，再上传；自定义页面固定上传 UUID，并保留原请求处理未知结果。"
     ],
     "knownLimitations": [
-      "运行时繁忙恢复只用于现有 current 读取；未知 429、权限或版本拒绝和非繁忙依赖失败不扩展等待，初始化成功不表示业务请求已经受理。",
-      "本次发布保留持久申请的原请求键、观察截止和自然轮询策略；队列的受理、执行和最终结果仍由平台负责。",
-      "流程图说明不改变不可变执行定义及持久实例决定，不补造不存在的执行边，也不改变流程授权。",
-      "管理员节点配置只调整应用明确开放的边界，字段行为继续由应用页面与代码维护；未声明该能力的应用不启用新的配置入口。"
+      "本轮交付根 file/image，签名、富文本和 owned 子表仍按后续任务页面切片验证。",
+      "上传资格依据已保存资料的页面状态；管理员不能配置字段权限。",
+      "本轮是本地迁移实验，npm 发布与学校生产迁移分别另行执行。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "入口繁忙恢复需要平台提供 CONCURRENCY_BOOTSTRAP_BUSY 或 CONCURRENCY_API_BUSY 契约；可读流程图需要匹配的只读平台接口，管理员节点配置需要 workflow.node-administration 能力。持久排队沿用 data.managed-concurrency.durable@1.0.0。",
-      "v1": "V1 分发引擎及业务不变。"
+      "platform": "workflow.task-managed-files@1.0.0 与 AddWorkflowTaskManagedFilesV2",
+      "v1": "1.x 引擎独立，本轮不改变其上传入口。"
     },
-    "sha256": "31ce7268d3e443bf8fd5d26f0be82be6b1a24ff22f25d0735c7abf4a83fe92dd",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.35.3"
+    "sha256": "b4d4027b81772f5c63ef0638b7ffa9c73374799a398bd17c8828ed126410e4da",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.44.0"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.43.0.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.43.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.43.0：持久命令的有界发现与原申请恢复",
+  "summary": "热点应用可显式延长只读发现预算，刷新合并并优先核对原键；未知受理保留原申请与输入，避免误报排队成功。",
+  "newFeatures": [
+    "DurableCommandOptions 与 useDurableCommand 新增 discoveryRecoveryMs，默认 120 秒，可显式配置最长 30 分钟；每次发现共享固定截止。",
+    "DurableCommandSnapshot 新增 acceptanceConfirmed，供界面区分已确认受理与仍需核对的原申请。"
+  ],
+  "fixes": [
+    "已确认非终态优先读取原键，原键 404 保留受控本人列表兜底；未确认原意图不会被其他周期覆盖。",
+    "重复刷新合并，停止后重新挂载可重新只读发现；回执同时核对原键、operationId 和作用域。",
+    "CLI 内置模板与同批 SDK 精确版本同步，中文接入资料随 skill-kit 发布。"
+  ],
+  "affectedUsers": [
+    "使用持久命令排队提交、原申请恢复的 V2 页面开发者及应用用户。"
+  ],
+  "upgradeSteps": [
+    "安装同批正式 openxiangda 包，刷新技能资料并重启应用；按应用需求显式配置 discoveryRecoveryMs。",
+    "排队文案以 acceptanceConfirmed 为准，未知受理提供显式恢复原申请操作，不在挂载时重放提交。",
+    "本轮能力不要求新服务端契约或 SQL；使用此前新增的工作流能力时仍需对应平台正式迁移与服务端版本。"
+  ],
+  "knownLimitations": [
+    "延长只读发现预算不会延长原首次提交的受理或观察窗口，也不会自动补单。",
+    "单元与发行门禁不证明实际服务器容量；入口、受理和本人结果须在目标环境独立测量。",
+    "浏览器尚未取得受理回执时，离页不能保证原申请已经进入后台队列。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "现有 managed concurrency durable command 契约；新增恢复选项为可选。",
+    "v1": "V1 引擎保持独立，本轮无行为变更。"
+  },
+  "sha256": "456c5671abc109c2cadc82bd22ae82adb2756293b63ee79aad941fc3450138d3",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.43.0"
+}

package/releases/2.44.0.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.44.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.44.0：当前任务的托管附件与图片",
+  "summary": "代码任务页面支持根附件与图片，普通审批人通过固定任务上传和预览，草稿保留和正式流程提交复用平台文件生命周期。",
+  "newFeatures": [
+    "任务文件 SDK 支持固定 ID 的原计划与完成恢复，标准 PC/手机上传及预览自动接入。",
+    "编译器按可编辑任务文件申请 workflow.task-managed-files 自动能力，无额外默认关闭开关。"
+  ],
+  "fixes": [
+    "上传结果未知时保留原文件与请求并锁住新流程动作和草稿写入；ready 结果不再次 PUT。",
+    "任务表单和本人草稿比较使用任务文件范围，避免依赖通用 CRUD 预览资格。"
+  ],
+  "affectedUsers": [
+    "声明 file/image 任务补填页面的 V2 应用开发者、办理人和平台维护者。"
+  ],
+  "upgradeSteps": [
+    "消费同批本地 SDK/contracts 与匹配平台 Server，应用迁移 AddWorkflowTaskManagedFilesV2，刷新资料并重启。",
+    "局部修改才显示附件字段时先保存补填，再上传；自定义页面固定上传 UUID，并保留原请求处理未知结果。"
+  ],
+  "knownLimitations": [
+    "本轮交付根 file/image，签名、富文本和 owned 子表仍按后续任务页面切片验证。",
+    "上传资格依据已保存资料的页面状态；管理员不能配置字段权限。",
+    "本轮是本地迁移实验，npm 发布与学校生产迁移分别另行执行。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "workflow.task-managed-files@1.0.0 与 AddWorkflowTaskManagedFilesV2",
+    "v1": "1.x 引擎独立，本轮不改变其上传入口。"
+  },
+  "sha256": "b4d4027b81772f5c63ef0638b7ffa9c73374799a398bd17c8828ed126410e4da",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.44.0"
+}

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": "e70281f337585990895c4f75765c55b759167506656749d865fc749b6c2419ac"
+      "sha256": "9350d7e567e877208b86929f0eeedade792f9750989ca08055061092c980ec37"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

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