openxiangda-skill-kit 2.3.18 → 2.3.20

package/package.json

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

package/skills/manifest.json

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

package/skills/openxiangda-v2/SKILL.md

@@ -71,6 +71,7 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 | 外部无账号表单、续填、上传、本人记录 | [匿名公开访问](references/public-access.md) |
 | 审批、待办、消息或事件 | [工作流与通知](references/workflow-events.md) |
 | 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
+| 主子额度、审批占用释放、撤回修订重提 | [精确金额占用](references/decimal-reservations.md) |
 | 管理成员或查看有效流程参数 | [应用管理](references/administration.md) |
 | 检查、部署、生产发布与故障恢复 | [验收](references/testing.md)、[交付](references/delivery.md) |
 | 需求记录与版本升级 | [全流程记录](references/appspec.md)、[升级](references/upgrading.md) |

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

@@ -321,3 +321,5 @@ if (output.status === 'pending') {
 ```
 
 这些方法适用于当前用户、具名业务动作和应用服务身份，沿用各自权限；业务记录绑定仍需正式数据事务。输出目前支持 OSS/MinIO，受字段上限与100MiB硬上限约束，上传凭据五分钟后过期，完成须在额外十分钟内进行。过期错误应由调用者建立新的处理意图，不能无限重试相同过期计划。下载最长五分钟，签发后到期前为短期委托，不能即时撤回。不要在日志、持久草稿或业务数据中保存签名地址、POST policy 或签名字段。
+
+主子记录共享精确金额额度、撤回修订和审批释放，请使用[精确金额占用](decimal-reservations.md)的受管提交及终态事务。

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

@@ -15,7 +15,7 @@
 | `pnpm openxiangda accept` | 远端变更 | 按计划准备可选的真实预发验收身份 |
 | `pnpm openxiangda deploy` | 远端变更 | 部署测试环境或显式复用测试版本部署生产 |
 | `pnpm openxiangda status` | 只读 | 查询最近或指定部署状态 |
-| `pnpm openxiangda logs` | 只读 | 查询最近或指定部署日志 |
+| `pnpm openxiangda logs` | 只读 | 查询部署日志或应用原操作事实 |
 | `pnpm openxiangda cancel` | 远端变更 | 幂等取消尚未提交激活的部署 |
 | `pnpm openxiangda retry` | 远端变更 | 显式重试可恢复的失败部署 |
 | `pnpm openxiangda start` | 远端变更 | 从当前不可变版本启动应用环境 |

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

@@ -0,0 +1,111 @@
+# 主子记录精确金额占用
+
+需要跨多条子记录共享主记录额度时，使用平台 `data.decimal-reservations` 1.1.0，
+金额字段声明 `number.decimal`、`precision: 18`、`scale: 2`、`exactDecimal: true`。
+JSON 金额使用字符串。平台在父记录锁内用 PostgreSQL NUMERIC 校验占用；应用不做
+浮点求和、不维护另一个余额字段。此能力需要匹配 SDK、平台镜像和迁移；包安装成功
+不表示目标环境已就绪，先检查平台能力和正式部署回执。
+
+## 声明与首次提交
+
+提交的 Named Action 在 `platformAccess.decimalReservation` 声明 `mode: 'reserve'`、
+资源、amount/currency/relation/parent/root/status 六个字段、主子关系取值和允许状态，
+并用 `platformAccess.workflow.codes` 声明实际审批。当前用户仍需资源与字段读写权限。
+首次使用会冻结环境内该资源的映射；已有未入账子记录时拒绝启用，不自动补账。
+
+在 `OpenXiangdaBusinessProcessService.commit` 顶层增加：
+
+```ts
+const decimalReservation = {
+  parentId,
+  expectedParentRevision: parent.revision,
+  childOperationKey: 'child',
+  reservationKey: submission.reservationKey,
+  amount: '123.45',
+  currencyCode: 'CNY',
+};
+```
+
+`childOperationKey` 同 `workflow.subject.fromOperation`，选中唯一一条该资源的
+create 或 update。平台原子完成子记录、占额、审批命令和可选本人草稿消费。
+审批通过将 reserved 改为 committed，继续占额；驳回或撤回释放一次。
+
+## 撤回后修订并重提
+
+released 子记录仍不能通过普通 CRUD 或 `BusinessData.transaction` 修改金额、
+状态、父/root/关系等保护字段。界面把修订保存到本人 FormDraft，重提时一次提交：
+
+```ts
+await businessProcess.commit({
+  idempotencyKey: submission.idempotencyKey,
+  data: {
+    operations: [{
+      key: 'child', kind: 'update', resourceCode: 'contracts',
+      id: child.id, expectedRevision: child.revision,
+      data: {
+        title: draft.title,
+        amount: '123.45',
+        status: { value: 'approving' },
+      },
+    }],
+  },
+  formDraft: {
+    resourceCode: 'contracts', id: draft.id,
+    expectedRevision: draft.revision, mode: 'update', recordId: child.id,
+  },
+  decimalReservation,
+  workflow: { workflowCode: 'contract-approval', subject: { fromOperation: 'child' } },
+});
+```
+
+每次新的提交意图使用新的 reservationKey 和提交键；网络结果未知时保留原键及原
+payload查询/重试，不能用新键重做旧请求。更新保留父/root/关系，失败会整体回滚，
+本人草稿仍可恢复，正式金额与审批命令不会半完成。普通主记录继续原来的无额度路径。
+
+## 真实审批事件终态
+
+在真实审批消费者的 `platformAccess` 增加以下声明；其中状态取值由应用自己的
+资源选项决定。审批必须声明同一 subject 资源，且存在该资源的 reserve 动作映射。
+
+```ts
+platformAccess: {
+  decimalReservation: {
+    resourceCode: 'contracts', workflowCode: 'contract-approval',
+    outcomes: [
+      { eventType: 'openxiangda.workflow.instance.completed.v2', mode: 'commit', eligibleChildStatuses: ['signing'] },
+      { eventType: 'openxiangda.workflow.instance.rejected.v2', mode: 'release', eligibleChildStatuses: ['rejected'] },
+      { eventType: 'openxiangda.workflow.instance.withdrawn.v2', mode: 'release', eligibleChildStatuses: ['draft'] },
+    ],
+  },
+}
+```
+
+每个 eventType 也必须列在订阅的 eventTypes 中。不得使用自造应用事件或
+native-data execution 订阅获得此权限。事件 handler 中用已有的
+`OpenXiangdaApplicationDataApiService`，将终态附加到原事务：
+
+```ts
+import { idempotentTransaction } from 'openxiangda/nest';
+
+await applicationData.transaction(idempotentTransaction(
+  context.idempotencyKey,
+  [childStatusUpdate, auditCreate],
+  [],
+  { decimalReservation: {
+    reservationKey: originalSubmission.reservationKey,
+    transitionKey: context.idempotencyKey,
+    childOperationIndex: 0,
+  } },
+));
+```
+
+选中的 childStatusUpdate 必须是该资源唯一 update，保留正常 expectedRevision。
+模式和金额不能放进终态请求；平台从真实 leased delivery、原始及当前不可变订阅、
+workflow command/instance/subject revision 和台账验证，SDK自动继承已验签事件上下文。
+普通应用凭据或自填事件头不构成授权。精确同键、同payload重放返回原完整事务结果；
+旧轮次不能释放重提后的新占用。重放仍受当前权限、有效事件租约和父记录可读性约束。
+
+首批只覆盖主子额度和三个真实审批结果。作废/终止释放 committed 必须另有受管
+真实业务动作；状态枚举不代表已实现该能力，签后金额变更仍拒绝。锁等待最多2秒、
+单条SQL最多5秒，较严格的已有约束优先；retryable 409
+`OPENXIANGDA_NATIVE_DECIMAL_CONTENTION` 不允许换键掩盖未知结果。

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

@@ -2,6 +2,30 @@
 
 应用开发者从工作区执行 `pnpm openxiangda`。平台负责应用版本、运行状态和恢复决定。工具链自身的 npm 发布由平台维护者负责，应用项目无需复制发包脚本或平台验证矩阵。
 
+## 按原操作自助诊断
+
+保留原 requestId、commandId、DeploymentRun ID 或 fileId；应用管理员可在已有
+登录工作区查询，不需要服务器账号。目标平台需提供 `application.scoped-diagnostics@1`。
+
+```bash
+pnpm openxiangda logs --request-id <原请求ID> --json
+pnpm openxiangda logs --command-id <原命令UUID> --json
+pnpm openxiangda logs --file-id <受管文件UUID> --environment test --json
+pnpm openxiangda logs --deployment-run-id <原RunUUID> --environment production --json
+```
+
+requestId 默认最近一小时，结果会显示实际 from/to；跨日排查可传一对 UTC ISO
+时间 `--from` / `--to`（最多 24 小时）。其余定位器按原 ID 查，不接受时间窗口。
+默认环境是 test；production 必须显式选择。结果包含实际站点、应用、环境、观测时间、
+持久状态和是否截断，只投影允许的元数据，不返回业务正文、文件名或密钥。
+
+`observed` 仅表示查到事实，仍需看每条状态；`not_observed` 不表示原写入没有发生；
+`unavailable` 表示本次诊断暂不可用。三者都不会重放原操作。保留原 ID、输入和幂等键，
+按返回的下一步查询原回执，不创建新运行代替未知结果。文件存在不等于当前用户可下载。
+
+原有 `pnpm openxiangda logs [deploymentId]` 保持部署日志行为。MCP 的
+`application_diagnostics` 使用同一范围和状态约定；requestId 的 from/to 必须明确提供。
+
 ## 测试部署
 
 源码托管仍可通过 `pnpm openxiangda source push` 提交和推送，但不是测试发布的前置步骤。

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

@@ -561,6 +561,59 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
 }
 ```
 
+## application_diagnostics
+
+查询应用原操作事实。在当前应用和明确环境内只读查询 requestId、commandId、deploymentRunId 或 fileId。requestId 必须传成对 UTC from/to，最多 24 小时；其余类型不传窗口。未观测到不表示未执行，禁止据此换键重放。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "requestId",
+        "commandId",
+        "deploymentRunId",
+        "fileId"
+      ]
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "from": {
+      "type": "string"
+    },
+    "to": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "id"
+  ],
+  "additionalProperties": false
+}
+```
+
 ## cancel_deployment
 
 取消未激活部署。仅在用户授权且平台 recovery.cancelAllowed 为真时取消；激活后的运行不能取消。