openxiangda-skill-kit 2.3.20 → 2.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.3.20",
+  "version": "2.3.22",
   "description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.26.0"
+    "openxiangda-devkit-core": "2.28.0"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/references/decimal-reservations.md

@@ -105,7 +105,51 @@ workflow command/instance/subject revision 和台账验证，SDK自动继承已
 普通应用凭据或自填事件头不构成授权。精确同键、同payload重放返回原完整事务结果；
 旧轮次不能释放重提后的新占用。重放仍受当前权限、有效事件租约和父记录可读性约束。
 
-首批只覆盖主子额度和三个真实审批结果。作废/终止释放 committed 必须另有受管
-真实业务动作；状态枚举不代表已实现该能力，签后金额变更仍拒绝。锁等待最多2秒、
+作废/终止释放 committed 必须另有受管真实业务动作；状态枚举不代表已实现该能力，
+签后金额变更仍拒绝。锁等待最多2秒、
 单条SQL最多5秒，较严格的已有约束优先；retryable 409
 `OPENXIANGDA_NATIVE_DECIMAL_CONTENTION` 不允许换键掩盖未知结果。
+
+## 提交金额后的正常生命周期
+
+需要在 committed 后继续签订、履行等状态操作时，在模型上声明
+`decimalReservationLifecycle`。它复用同资源 reserve 动作的状态与关系字段，
+不新增接口或余额；未声明时继续原有严格保护。以下状态均须已在状态字段选项中声明：
+
+```ts
+decimalReservationLifecycle: {
+  parentTransitions: [
+    { from: 'active', to: 'closed' },
+    { from: 'closed', to: 'active' },
+  ],
+  childTransitions: [
+    { from: 'signing', to: 'fulfilled' },
+    { from: 'fulfilled', to: 'signing' },
+  ],
+  fulfilledChildStatuses: ['fulfilled'],
+  lockedParentStatuses: ['closed'],
+}
+```
+
+之后用既有 Data API update 或 transaction，带原记录的 expectedRevision。
+当前用户或已授权后台主体仍须具备原资源、字段和数据范围权限。金额、币种、主子关系、
+parent/root 仍受保护，声明状态边不授予写权限。普通子状态更新必须属于当前 committed
+周期；reserved/released 继续走真实受管审批或重新提交，不能绕过审批。
+
+父记录进入 locked 状态时，所有当前占用都必须已 committed 且子状态在 fulfilled 集合；
+存在 reserved、缺失子记录、金额/关系不一致或未履行子记录时返回
+`OPENXIANGDA_NATIVE_DECIMAL_PARENT_UNFULFILLED_CHILDREN`。released 历史周期已退出义务。
+终止、作废不会自动算作履行或释放金额，需按真实业务含义选择声明。
+父记录 locked 后拒绝新预留和把子记录改回未履行状态，返回
+`OPENXIANGDA_NATIVE_DECIMAL_PARENT_LOCKED`；如需解锁，必须有明确的父状态边和原更新权限。
+
+每类最多 64 条不重复、非自身状态边，两个状态集合各 1–16 项。状态和映射不符、缺少
+reserve 声明、锁定状态仍可新预留，在本地检查即拒绝并指向声明位置。
+显式启用才要求 `data.decimal-reservation-lifecycle@1.0.0`；目标环境须先升级并具备该能力。
+状态规则改变在激活新版本前会核对现有关闭父记录，冲突返回
+`OPENXIANGDA_NATIVE_DECIMAL_LIFECYCLE_ACTIVATION_CONFLICT`，保留原版本和数据；不会自动改历史状态。
+移除声明将恢复严格保护。回滚到不支持本能力的服务器前，应先停用依赖此声明的入口。
+Connected Dev 会保留已激活规则。新增或改变规则时，先通过 `check` 并发布到测试环境，
+使历史一致性校验完成后再连接开发；若仅改本地覆盖层，会返回
+`OPENXIANGDA_CONNECTED_DEV_OVERLAY_DECIMAL_LIFECYCLE_ACTIVATION_REQUIRED` 和声明指针。
+这样不会出现本地规则被接受却在写入时悄悄忽略的情况。

package/skills/openxiangda-v2/references/delivery.md

@@ -48,6 +48,17 @@ pnpm openxiangda logs <deployment-id> --json
 
 平台启用镜像上传后，`deploy` 在本机用 Docker Buildx 导出 OCI 镜像，再使用当前平台登录态分片上传。开发者只需应用部署权限，无需登录平台管理员的镜像仓库或取得推送凭据。已完成的镜像层按摘要复用，中断后重新执行同一条部署命令可恢复上传；平台核验镜像完整性后才进入应用发布。尚未升级的旧平台保留其原镜像构建合同；新平台已声明上传能力但未启用时，命令会明确报告平台配置缺失。
 
+上传失败后，本机保留原 OCI 制品，错误的 `details` 包含候选 ID、原 digest、失效时间及脱敏原因码。
+恢复网络或登录后，在原工作区执行同一条 `pnpm openxiangda deploy`：相同构建输入、账号、平台、
+应用和环境会校验原制品并从平台保存的偏移继续；即使 Docker 暂时不可用也能恢复已经构建的镜像。
+完成响应丢失时同样查询原摘要的 ready 回执。源码（包括未提交文件）、权限主体或目标变化会创建新候选，
+不会冒充原上传。上传鉴权仍在平台执行；本地缓存不授予部署权限。
+
+缓存保留最多 24 小时、8 个候选、总预算 8 GiB；空间不足时仅回收未被使用的旧候选。
+仅当平台单镜像上限不超过 8 GiB 时启用本地恢复，较大的平台配额保留原上传路径，不降低平台允许的镜像大小。
+缓存和登录凭据分开，位于本机用户私有目录。过期或已经回收的候选需重新构建；已有 DeploymentRun
+的未知结果仍查询原运行，镜像上传恢复不会重新发起已提交的部署。
+
 生成的不可变 AppVersion 绑定前端、可选后端、配置契约和制品摘要。默认提交后持续跟踪同一运行，直到平台成功、失败或取消，最多观察 15 分钟。`--no-wait` 只提交，适用于已有状态跟踪器的自动化；此时返回运行 ID 不代表部署完成。
 
 构建、上传及平台执行都会显示当前阶段和耗时，长步骤每 10 秒反馈一次。平台的准备、部署、切换和健康检查状态来自原运行。观察超时或连接中断不会取消部署或重建候选，使用下面的命令继续跟踪：
@@ -58,7 +69,8 @@ pnpm openxiangda status <deployment-id> --watch
 
 网络响应不确定时先查询原运行，不凭本地输出创建重复部署。平台部署成功后，仍需执行真实角色的业务验收。
 
-重复发布直接使用当前源码重新构建。pnpm、Docker 和平台可以自行提供构建缓存，Devkit 不维护另一套工作区摘要或候选状态。提交响应不确定时使用原 DeploymentRun 的 status/logs 和 recovery 继续处理。
+新的发布使用当前源码构建；尚未完成的同输入镜像上传可复用上述短期原制品缓存。
+该缓存不保存部署状态，平台仍唯一拥有 DeploymentRun。提交响应不确定时使用原 DeploymentRun 的 status/logs 和 recovery 继续处理。
 
 ## 测试环境验收