openxiangda 2.18.10 → 2.20.1

package/documentation/delivery.md

@@ -102,7 +102,7 @@ MCP 的 check_app、deployment_plan、deploy_app 使用与 CLI 相同的环境
 
 ## 构建前运行配额
 
-`deploy --dry-run`（MCP `deployment_plan`）会只读查询目标 TEST 的运行配额，输出 `runtimeCapacity` 的核验时间、所需增量、各配额剩余量和缺口。`sufficient: false` 表示当前不足；`null` 表示无需新增或未核验，必须结合 `basis` 与 `capacity.checked` 阅读。专用命名空间未检查不能当成资源充足。
+`deploy --dry-run`（MCP `deployment_plan`）会只读查询目标 TEST 的运行配额，输出 `runtimeCapacity` 的核验时间、所需增量、各配额剩余量和缺口。`sufficient: false` 表示当前不足；`null` 表示无需新增或未核验，必须结合 `basis` 与 `capacity.checked` 阅读。专用命名空间未检查不能当成资源充足。同一预检还会比对源码 `workflows.activations` 与环境 Head，输出 `workflowActivation` 诊断：版本回退（error，拒绝部署）、源码缺失已激活流程（warning，本次部署会停用）、目录不可读（error，拒绝盲部署），详见 [Workflow 事件](./workflow-events.md)。
 
 正式 deploy 在检查脚本和镜像构建前预检；平台缺少配套能力或无法核验时明确停止。配额快照不预留资源，实际执行再次检查。已有可验证密封候选会携带摘要和幂等键，平台识别 `existing-run` 时返回原运行，不把它当作新副本；观察或恢复原运行使用 status/retry。不要为绕过配额创建新包或切换目标环境。
 

package/documentation/frontend.md

@@ -90,12 +90,13 @@ import { resourceSurfaces } from '@app/contracts';
 
 const records = createNativeResourceClient('records', resourceSurfaces.records);
 
-// 服务端过滤、排序、分页；字段必须已声明，未声明字段直接报错
+// 服务端过滤、排序、分页；where 字段必须已声明；排序字段用已声明字段或
+// 平台审计列（created_at/updated_at/created_by/updated_by/id/revision）
 const page = await records.list({
   page: 1,
   pageSize: 20,
   where: { field: 'enabled', operator: 'eq', value: true },
-  sort: { field: 'createdAt', order: 'desc' },
+  sort: { field: 'created_at', order: 'desc' },
 });
 
 const record = await records.get(id);

package/documentation/getting-started.md

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

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.18.10",
+  "version": "2.20.1",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "dda539622d18a90beea7885bfe2651cc42f94cc16764e485622ffd0489f508e3"
+      "sha256": "089b3eadff09a1ffd55afdcdb4045fa3c8d6d72ed038ffba8b48cdcacf3669ec"
     },
     {
       "id": "product-design",
@@ -48,13 +48,13 @@
       "id": "declarations-cheatsheet",
       "title": "声明速查：一次写对 config",
       "file": "declarations-cheatsheet.md",
-      "sha256": "5b4327eeead055b9d1f46a4122c6c2ac7052ca86e9ca2d586c8ce1b3df4d2bd2"
+      "sha256": "b7943a245f2a40599c90adc72cbc42280c65e22513b3df7cac6c1adaa8e6c48c"
     },
     {
       "id": "application-foundation",
       "title": "业务模型与标准 CRUD",
       "file": "application-foundation.md",
-      "sha256": "dd28e08c6ebbcb2651a216649182c8c46b1ab62a2853a4cece9f041f5da2cd15"
+      "sha256": "7a315a0a5db5c2c60ccfaf2fdf9da903167821e8c5214bfae14e9674d894b68e"
     },
     {
       "id": "appspec",
@@ -72,7 +72,7 @@
       "id": "frontend",
       "title": "页面与标准组件扩展",
       "file": "frontend.md",
-      "sha256": "cc94258be41427af5c5caed29810e548cb1727f2564e849d4bb64b868c70e3e9"
+      "sha256": "e668ddfd81a8308e1f750e4d79d34eac316ba97e2d28ba27a72c166565ea5949"
     },
     {
       "id": "field-components",
@@ -96,13 +96,13 @@
       "id": "workflow-events",
       "title": "审批、事件与通知",
       "file": "workflow-events.md",
-      "sha256": "9d25f32e7758888b2d051519bb3f260c1202a5908120d788ed1c997d358e1bdd"
+      "sha256": "9d78faf470638c33d4bf8b0f7b7540c9adb10e0661d4ec790779c304fc9a7bb6"
     },
     {
       "id": "backend",
       "title": "按需后端与业务动作",
       "file": "backend.md",
-      "sha256": "75c8f9b83c37afe53b57d0283fa814a5153aa7d72a85efb2a1d9c4a9c1844e6a"
+      "sha256": "323d585d3069e0eb7f649eb2c5d0bf0f7344266ce446f539e872b4ec7bc0fbd9"
     },
     {
       "id": "administration",
@@ -120,7 +120,7 @@
       "id": "delivery",
       "title": "部署、生产晋级与恢复",
       "file": "delivery.md",
-      "sha256": "32f07cfe6b946975bb3795e6ca3a01370e4d6bcc89f1b52b8df19085438e92c2"
+      "sha256": "69c94361f2c7e1038bb50be9875b34337d8138a923e1913d3f8ee3d5dfb2a57d"
     },
     {
       "id": "upgrading",

package/documentation/workflow-events.md

@@ -202,6 +202,15 @@ command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消
 默认 1/200，最大 200。
 需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
 
+平台按 desired set 直接覆盖环境 Head，不做版本比较。因此 `openxiangda deploy`
+与 `deploy --dry-run` 会在构建前只读比对源码激活声明与环境 Head：
+源码 `definitionVersion` 低于当前已激活版本时以
+`DEPLOY_WORKFLOW_ACTIVATION_VERSION_REGRESSION` 拒绝部署——把高版本定义与激活
+声明合入源码后再发，版本号与 digest 必须与已注册版本一致（同版本不同内容会被
+平台以 `WORKFLOW_V2_DEFINITION_VERSION_IMMUTABLE` 拒绝）；Head 已激活而源码
+缺声明的流程给出 `DEPLOY_WORKFLOW_ACTIVATION_ABSENT` 警告（本次部署会停用它）；
+目录查询不可用时以 `WORKFLOW_HEAD_PREFLIGHT_UNAVAILABLE` 拒绝盲部署。
+
 Notification Hub 消费事实：
 
 - `participant.activated` 创建待处理消息；
@@ -294,7 +303,12 @@ Workflow instance-scoped preview/content 路由，平台在每次文件读取时
 
 标准发起页使用独立的 `WorkflowLaunchSurface` 读取当前激活合同：桌面路径为
 `/workflows/:workflowCode/start`，移动路径为
-`/m/workflows/:workflowCode/start`。`standalone`/`hidden-handoff` 缺省使用同一个
+`/m/workflows/:workflowCode/start`。definition 必须显式声明
+`launch: { mode: 'standalone' | 'hidden-handoff' | ... }`，缺失会被编译器拒绝；
+factProjection 把 option/user/department/resource-ref/cascade 字段投影为
+`{ label, value }` 对象，对应 inputSchema 属性必须声明为 `type: 'object'`
+（multiple 类字段为 array + object items），条件表达式用 `path: '<fact>.value'`
+比较；声明成标量会在运行时 INPUT_SCHEMA_MISMATCH 并无限重试，编译器现已拦截。`standalone`/`hidden-handoff` 缺省使用同一个
 compiler-owned `processOperationCode`、subject declaration 和标准 process commit；平台在一个
 事务中写业务数据和 durable command。action-owned 资源改为声明
 `launch.submission.kind: 'named-operation'`，显式绑定 create/existing 请求来源、响应 subject/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.18.10",
+  "version": "2.20.1",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,13 +60,13 @@
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.4.18",
-    "openxiangda-contracts": "2.14.1",
-    "openxiangda-devkit-core": "2.16.0",
+    "openxiangda-cli": "2.4.21",
+    "openxiangda-contracts": "2.16.0",
+    "openxiangda-devkit-core": "2.18.1",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.25",
-    "openxiangda-nest": "2.4.3",
-    "openxiangda-skill-kit": "2.1.12",
+    "openxiangda-mcp": "2.0.28",
+    "openxiangda-nest": "2.4.5",
+    "openxiangda-skill-kit": "2.3.1",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,32 +132,33 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.18.10",
+    "version": "2.20.1",
     "status": "reviewed",
-    "title": "OpenXiangda 2.18.10：随包技能/文档同步自建中心指南",
-    "summary": "openxiangda-skill-kit 随包技能与文档与源文档再同步：携带「自建待办与消息中心 UI」指南与 2.18.9 标准中心视觉重构说明；无代码行为变化。",
-    "newFeatures": [],
-    "fixes": [
-      "openxiangda-skill-kit 打包内容与源文档再同步：修复随包技能/文档滞后于「自建待办与消息中心 UI」指南与 2.18.9 标准中心视觉重构说明的问题。"
+    "title": "OpenXiangda 2.20.1：contracts 资源级审计列排序修复",
+    "summary": "openxiangda-contracts 修复资源级 surface list defaultSort 对平台审计列（created_at/updated_at 等）的 fail-closed 误拒：与命名视图 defaultSort、Data API order 的系统列规则对齐。devkit 与 openxiangda 2.20.0 已含的行为不变。",
+    "newFeatures": [
+      "资源级 surface list defaultSort 支持平台审计列（created_at/updated_at/created_by/updated_by/id/revision），不再按未知字段 fail-closed；补回归测试。"
     ],
+    "fixes": [],
     "affectedUsers": [
-      "通过 skill-kit 安装随包技能与文档的应用开发者与 AI 会话。"
+      "所有使用数据策略、行级权限、匿名公开访问的 OpenXiangda 2.0 应用开发者与 AI 开发会话。"
     ],
     "upgradeSteps": [
-      "随 2.18.10 列车一起发布；应用无需单独升级，引用 openxiangda 2.18.9 及配套版本即可。"
+      "应用把 openxiangda 精确钉扎到 2.20.0 并重跑 pnpm openxiangda check；出现新告警/报错时按提示调整策略声明。",
+      "使用 created_by 行规则需平台服务端配套版本；升级前请确认平台列车已包含该修复。"
     ],
     "knownLimitations": [
-      "本列车无独立代码变更；功能变更记录见 2.18.9 发布说明，两列车一并发布。"
+      "created_by 行规则的运行时 WITH CHECK 正向匹配修复仍随平台列车交付。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "无平台配合要求。",
+      "platform": "无强制平台配合要求；created_by 行规则的运行时生效需平台列车跟进。",
       "v1": "V1 工作区不受影响。"
     },
-    "sha256": "62fba20895d127dc14f81ddac0445eac22957a0e8dadca1556957bb65834869c",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.18.10"
+    "sha256": "043a0bdb2615be80b4efff4a9f2e58107965e261e9294050a1decee22a6b7e6c",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.20.1"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.20.1.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.20.1",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.20.1：contracts 资源级审计列排序修复",
+  "summary": "openxiangda-contracts 修复资源级 surface list defaultSort 对平台审计列（created_at/updated_at 等）的 fail-closed 误拒：与命名视图 defaultSort、Data API order 的系统列规则对齐。devkit 与 openxiangda 2.20.0 已含的行为不变。",
+  "newFeatures": [
+    "资源级 surface list defaultSort 支持平台审计列（created_at/updated_at/created_by/updated_by/id/revision），不再按未知字段 fail-closed；补回归测试。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "所有使用数据策略、行级权限、匿名公开访问的 OpenXiangda 2.0 应用开发者与 AI 开发会话。"
+  ],
+  "upgradeSteps": [
+    "应用把 openxiangda 精确钉扎到 2.20.0 并重跑 pnpm openxiangda check；出现新告警/报错时按提示调整策略声明。",
+    "使用 created_by 行规则需平台服务端配套版本；升级前请确认平台列车已包含该修复。"
+  ],
+  "knownLimitations": [
+    "created_by 行规则的运行时 WITH CHECK 正向匹配修复仍随平台列车交付。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "无强制平台配合要求；created_by 行规则的运行时生效需平台列车跟进。",
+    "v1": "V1 工作区不受影响。"
+  },
+  "sha256": "043a0bdb2615be80b4efff4a9f2e58107965e261e9294050a1decee22a6b7e6c",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.20.1"
+}

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由 AI 在工作区内调用 OpenDesign 原版 CLI/Skill/MCP 形成整体视觉与可运行原型，再开发、检查和交付应用。OpenDesign 客户端只作为可选预览器；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "ef986e71335449e705a7a05867403e4781077f4da19f546491f9cd35841702cf"
+      "sha256": "007592d8f9143efa946717dd72f9bfbfb8200bc43027be6908631dbe472eff3e"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

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

package/skills/openxiangda-v2/references/application-foundation.md

@@ -194,7 +194,13 @@ crud: [{
 }]
 ```
 
-引用未声明字段按编译错误处理；低层 `data.resources[].fields[].sortable` 语义不变。
+排序字段可以是已声明字段，也可以是平台审计列（`created_at` / `updated_at` /
+`created_by` / `updated_by` / `id` / `revision`）——它们由平台维护、所有记录必有值，
+不需要也无法在模型 `fields` 中声明。"按真实创建时间倒序"直接写
+`defaultSort: { field: 'created_at', order: 'desc' }`，标准 Admin 列表的内置
+"创建时间/更新时间"列同样可点击排序；不要为排序复制一份业务时间字段。
+引用其他未声明字段仍按编译错误处理；低层 `data.resources[].fields[].sortable`
+语义不变。`filterFields` / `searchableFields` 仍只接受已声明字段。
 
 ## 资源详情路由声明 {#detail-route-code}
 

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

@@ -109,6 +109,34 @@ try {
 ```
 
 事务守卫的 `errorCode` 必须匹配 `^OPENXIANGDA_[A-Z0-9_]{1,96}$`，例如 `OPENXIANGDA_REPAIR_REQUEST_NOT_PENDING`。
+
+## 在同一事务中引用前序 create 生成的 id {#transaction-references}
+
+一个事务内"先建主记录、再建引用它的子记录"不需要预先分配 id，也不需要两段式
+暂存。后续 create/update 的 `data` 字段值可以直接写
+`{ operationIndex, field: 'id' }` 引用本事务中**之前的 create** 生成的主键，
+平台在提交前解析替换：
+
+```ts
+await businessData.transaction({
+  schemaVersion: 'openxiangda.data-transaction-request/v2',
+  idempotencyKey: input.idempotencyKey,
+  operations: [
+    { operation: 'create', resourceCode: 'clubs', data: { name: input.name } },
+    { operation: 'create', resourceCode: 'club-memberships',
+      data: { clubId: { operationIndex: 0, field: 'id' }, userId: input.ownerId, role: 'owner' } },
+    { operation: 'create', resourceCode: 'club-memberships',
+      data: { clubId: { operationIndex: 0, field: 'id' }, userId: input.memberId, role: 'member' } },
+  ],
+});
+```
+
+引用约束：引用对象只含 `operationIndex`（0..99 的整数）与 `field: 'id'` 两个键；
+只能指向索引更小的 create 操作；引用不得嵌套在数组或对象里。违反形状报
+`OPENXIANGDA_NATIVE_DATA_TRANSACTION_REFERENCE_INVALID`，嵌套报
+`..._NESTED`，目标不可解析报 `..._UNRESOLVED`。任一操作失败时整个事务回滚，
+不会留下无成员的 club。
+
 ## 业务动作与普通查询 {#business-action}
 
 `OpenXiangdaDataApiService` 按当前用户的普通资源、行和字段权限执行。具名业务动作使用 `OpenXiangdaBusinessDataApiService`：入口先检查该动作 capability，平台在精确应用和环境内以受信任后端执行，并保留发起人与动作审计。业务动作不能接受任意模型/字段/用户 ID 后不做业务校验；应用负责该动作的输入约束和业务不变量。

package/skills/openxiangda-v2/references/declarations-cheatsheet.md

@@ -14,6 +14,7 @@
 | Workflow 详情接管的资源路由用模型级 `detailRouteCode` 表达（desktop/mobile 各引用一条 user surface 路由） | `defineDataModel({ code: 'x', detailRouteCode: { desktop: 'x-detail', mobile: 'x-detail-mobile' }, ... })` |
 | 迁移工具/验收脚本需要看模块投影结果时，用公共出口的 `materializeApplicationModules`，不要引用 devkit 的 dist 文件路径 | `import { defineApplicationModule, materializeApplicationModules } from 'openxiangda/config';` → `const { resources } = materializeApplicationModules([module])` |
 | system 字段（服务端赋值）可以进入查询与分组类选择（filterFields/searchableFields/sortableFields/defaultSort/sections.fields），不可进入展示与可写选择（list/form/detail.fields） | `filterFields: ['campaignId']`（system 外键筛选合法）；hidden 字段任何选择都拒绝 |
+| 平台审计列（created_at/updated_at/created_by/updated_by/id/revision）可直接作 `defaultSort`/`sortableFields`，无需声明；不可进入 filterFields/searchableFields/展示/可写选择 | `defaultSort: { field: 'created_at', order: 'desc' }`（按真实创建时间倒序，勿复制业务时间字段） |
 
 ## 字段声明
 
@@ -25,7 +26,7 @@
 | `audit.read` 可写 `true`（绑定本资源读能力）或能力数组 | `audit: { read: true }` |
 | `resource-ref.*` 必须带 `source` 来源协议 | `{ type: 'resource-ref.single', source: { kind: 'resource', resourceCode: 'repair-requests', labelField: 'title', searchFields: ['title'], pageSize: 20, loadMode: 'search' } }` |
 | `labelField` 必须指向目标资源的 `text.short` / `text.long` 字段 | 不要用流水号/选项字段当 label |
-| 列表可排序列用视图级 `sortableFields` 表达（`defaultSort.field` 隐式可排序） | `list: { sortableFields: ['capacity'], defaultSort: { field: 'name', order: 'asc' } }` |
+| 列表可排序列用视图级 `sortableFields` 表达（`defaultSort.field` 隐式可排序）；平台审计列（如 `created_at`）同样合法 | `list: { sortableFields: ['capacity'], defaultSort: { field: 'name', order: 'asc' } }`；`defaultSort: { field: 'created_at', order: 'desc' }` |
 | 每个字段都必须带中文/业务 `label`（含子表外键与排序字段） | `{ code: 'requestId', type: 'uuid', label: '所属申请', required: true }` |
 | 子表 `subtable` 的外键是子资源的 **uuid** 字段，排序字段是**可写 number.integer** | 子资源：`{ code: 'requestId', type: 'uuid', required: true }` + `{ code: 'sortOrder', type: 'number.integer', required: true }`；父表：`subtable: { resourceCode: 'repair-items', foreignKey: 'requestId', orderField: 'sortOrder', maxRows: 20 }` |
 | 图片/附件的 `file` 限定数量与大小 | `file: { maxCount: 3, maxSizeMb: 10, accept: ['image/png', 'image/jpeg'] }` |
@@ -34,6 +35,12 @@
 
 | 规则 | 正确片段 |
 | --- | --- |
+| 数据策略是**白名单**语义：规则 `roleCodes` 之外的角色若不在 `unrestrictedRoleCodes` 中会被 RLS 全拒（报错只有 FIELD_ROW_FORBIDDEN） | `unrestrictedRoleCodes: ['admin']` 必须列出所有"不受限"角色 |
+| 基线角色（`authenticatedUserRoleCode`）进 `unrestrictedRoleCodes` = 策略对所有人失效（角色并集必含基线角色），编译器直接报错 | 把基线角色移出 unrestrictedRoleCodes，为其单独声明 rules |
+| 匿名公开策略的 `ownRecordFields` 必须是 `fields` 的子集；`create` 必须配套 `draft`；`requiredFields` ⊆ `fields` | 先定 fields，再从中选 required/own |
+| workflow definition 必须显式 `launch`（编译器强制） | `definitions: [{ version: 1, definition, launch: { mode: 'standalone' } }]` |
+| option/user/department/resource-ref/cascade 字段投影进工作流事实是 { label, value } 对象，不能声明为标量；条件比较用 `<fact>.value` | `inputSchema.properties.urgency = { type: 'object', ... }` + `path: 'urgency.value'` |
+| `cascade.*` 的写入/比较值形状是**数组路径** | `category: [{ label: '办公设备', value: 'office' }]` |
 | 平台保留能力（如 `app:<app>:directory:read`）**不能**在 `capabilities` 里重复声明，直接在角色中引用即可 | `const directoryRead = \`app:\${APP_CODE}:directory:read\`` → `roles: [{ code: 'admin', capabilities: [directoryRead] }]` |
 | 资源 CRUD 能力码用 `resourceCapabilityCodes(appCode, resourceCode)` 生成 | `const crud = resourceCapabilityCodes(APP_CODE, 'repair-requests')` → `capabilities: [crud.read, crud.create]` |
 | `authenticatedUserRoleCode` 是平台登录用户的基线角色 | `authz: { authenticatedUserRoleCode: 'app-user', ... }` |

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

@@ -102,7 +102,7 @@ MCP 的 check_app、deployment_plan、deploy_app 使用与 CLI 相同的环境
 
 ## 构建前运行配额
 
-`deploy --dry-run`（MCP `deployment_plan`）会只读查询目标 TEST 的运行配额，输出 `runtimeCapacity` 的核验时间、所需增量、各配额剩余量和缺口。`sufficient: false` 表示当前不足；`null` 表示无需新增或未核验，必须结合 `basis` 与 `capacity.checked` 阅读。专用命名空间未检查不能当成资源充足。
+`deploy --dry-run`（MCP `deployment_plan`）会只读查询目标 TEST 的运行配额，输出 `runtimeCapacity` 的核验时间、所需增量、各配额剩余量和缺口。`sufficient: false` 表示当前不足；`null` 表示无需新增或未核验，必须结合 `basis` 与 `capacity.checked` 阅读。专用命名空间未检查不能当成资源充足。同一预检还会比对源码 `workflows.activations` 与环境 Head，输出 `workflowActivation` 诊断：版本回退（error，拒绝部署）、源码缺失已激活流程（warning，本次部署会停用）、目录不可读（error，拒绝盲部署），详见 [Workflow 事件](workflow-events.md)。
 
 正式 deploy 在检查脚本和镜像构建前预检；平台缺少配套能力或无法核验时明确停止。配额快照不预留资源，实际执行再次检查。已有可验证密封候选会携带摘要和幂等键，平台识别 `existing-run` 时返回原运行，不把它当作新副本；观察或恢复原运行使用 status/retry。不要为绕过配额创建新包或切换目标环境。
 

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

@@ -90,12 +90,13 @@ import { resourceSurfaces } from '@app/contracts';
 
 const records = createNativeResourceClient('records', resourceSurfaces.records);
 
-// 服务端过滤、排序、分页；字段必须已声明，未声明字段直接报错
+// 服务端过滤、排序、分页；where 字段必须已声明；排序字段用已声明字段或
+// 平台审计列（created_at/updated_at/created_by/updated_by/id/revision）
 const page = await records.list({
   page: 1,
   pageSize: 20,
   where: { field: 'enabled', operator: 'eq', value: true },
-  sort: { field: 'createdAt', order: 'desc' },
+  sort: { field: 'created_at', order: 'desc' },
 });
 
 const record = await records.get(id);

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

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

package/skills/openxiangda-v2/references/workflow-events.md

@@ -202,6 +202,15 @@ command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消
 默认 1/200，最大 200。
 需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
 
+平台按 desired set 直接覆盖环境 Head，不做版本比较。因此 `openxiangda deploy`
+与 `deploy --dry-run` 会在构建前只读比对源码激活声明与环境 Head：
+源码 `definitionVersion` 低于当前已激活版本时以
+`DEPLOY_WORKFLOW_ACTIVATION_VERSION_REGRESSION` 拒绝部署——把高版本定义与激活
+声明合入源码后再发，版本号与 digest 必须与已注册版本一致（同版本不同内容会被
+平台以 `WORKFLOW_V2_DEFINITION_VERSION_IMMUTABLE` 拒绝）；Head 已激活而源码
+缺声明的流程给出 `DEPLOY_WORKFLOW_ACTIVATION_ABSENT` 警告（本次部署会停用它）；
+目录查询不可用时以 `WORKFLOW_HEAD_PREFLIGHT_UNAVAILABLE` 拒绝盲部署。
+
 Notification Hub 消费事实：
 
 - `participant.activated` 创建待处理消息；
@@ -294,7 +303,12 @@ Workflow instance-scoped preview/content 路由，平台在每次文件读取时
 
 标准发起页使用独立的 `WorkflowLaunchSurface` 读取当前激活合同：桌面路径为
 `/workflows/:workflowCode/start`，移动路径为
-`/m/workflows/:workflowCode/start`。`standalone`/`hidden-handoff` 缺省使用同一个
+`/m/workflows/:workflowCode/start`。definition 必须显式声明
+`launch: { mode: 'standalone' | 'hidden-handoff' | ... }`，缺失会被编译器拒绝；
+factProjection 把 option/user/department/resource-ref/cascade 字段投影为
+`{ label, value }` 对象，对应 inputSchema 属性必须声明为 `type: 'object'`
+（multiple 类字段为 array + object items），条件表达式用 `path: '<fact>.value'`
+比较；声明成标量会在运行时 INPUT_SCHEMA_MISMATCH 并无限重试，编译器现已拦截。`standalone`/`hidden-handoff` 缺省使用同一个
 compiler-owned `processOperationCode`、subject declaration 和标准 process commit；平台在一个
 事务中写业务数据和 durable command。action-owned 资源改为声明
 `launch.submission.kind: 'named-operation'`，显式绑定 create/existing 请求来源、响应 subject/

package/releases/2.0.0.json

@@ -1,50 +0,0 @@
-{
-  "schemaVersion": "openxiangda.release-notes/v1",
-  "version": "2.0.0",
-  "title": "OpenXiangda 2.0 正式版",
-  "status": "reviewed",
-  "summary": "以统一入口使用两代工作区，新应用默认采用 V2。V2 提供从需求设计到 React 应用、平台数据权限和应用交付的完整工具链。",
-  "newFeatures": [
-    "统一入口识别最近的 V1/V2 工作区，优先使用项目已安装的锁定引擎；无本地 V1 引擎的旧工作区使用随入口固定的 V1 维护引擎。",
-    "新应用默认 V2：自然语言澄清产品需求，形成产品、页面、权限和架构设计基线，确认后再制定开发计划。",
-    "V2 提供标准 PC/移动端 CRUD、字段组件、Data API 权限、流程与协作能力；默认本地 React 连接平台测试环境，Nest 后端按需使用。",
-    "提供版本识别、分代更新、随包更新说明和 V1 到 V2 的只读迁移评估。"
-  ],
-  "fixes": [
-    "全局入口切换到 V2 后，旧 V1 工作区仍由 V1 执行，不再因同名命令使用错误代际。",
-    "项目工具链升级与全局入口升级明确分开；V1 维护渠道不再改写 latest。",
-    "两代 Skill 使用独立入口，V1 安装不再覆盖统一入口或清理 V2 Skill。"
-  ],
-  "affectedUsers": [
-    "新建应用的开发者",
-    "需要继续维护 V1 工作区的开发者",
-    "从 V2 alpha 升级的现有用户"
-  ],
-  "compatibility": {
-    "node": ">=24",
-    "workspaceGenerations": [
-      "v1",
-      "v2"
-    ],
-    "v1Policy": "保持现有配置、数据、流程、登录绑定与项目工具链代际；原 V1 CLI 可继续使用其原运行环境。",
-    "platformPolicy": "V2 应用部署前按平台 capabilities 和配置验证器预检；工具版本不能代替平台实际部署版本。",
-    "backendBuild": "Nest 镜像由开发者电脑上的 Docker 构建；普通 React/Nest 连接开发不要求本地平台或数据库。",
-    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。npm 不允许把 v1/v2 作为标签。"
-  },
-  "upgradeSteps": [
-    "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.0.0。",
-    "进入已有项目运行 openxiangda version --json，核对工作区代际、实际引擎和解析来源。",
-    "运行 openxiangda update check 查看本项目更新；需要升级时执行 openxiangda update install --target workspace。",
-    "检查依赖与锁文件差异，刷新本项目 Skill，并完成项目检查、测试环境和真实角色业务验收后再晋级生产。",
-    "V2 能力满足、项目仍在测试阶段且迁移成本可控时，优先建议 V1 项目采用 V2；先完成项目评估、设计确认和迁移验收。"
-  ],
-  "knownLimitations": [
-    "V1 到 V2 首期仅提供本地源码迁移评估，不读取远端业务数据，也不自动迁移应用。",
-    "源码扫描不会证明远端权限、流程和数据完整性；迁移须按项目制定映射、演练和回滚方案。",
-    "内网或离线环境可读取随包说明；联网检查失败时保留当前工具与项目。",
-    "内部支持 Agent 独立交付和验收，不随此 npm 版本自动部署。"
-  ],
-  "issues": [],
-  "sha256": "a6100370946d253328c924c19f6577bac383c4633e3650d69b7ad378486ae880",
-  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.0.0"
-}

package/releases/2.0.1.json

@@ -1,39 +0,0 @@
-{
-  "schemaVersion": "openxiangda.release-notes/v1",
-  "version": "2.0.1",
-  "title": "OpenXiangda pnpm 工作区识别修复",
-  "status": "reviewed",
-  "summary": "修复独立安装的统一入口进入 pnpm 工作区时无法找到项目 CLI 的问题，继续严格使用该项目锁定的同代引擎。",
-  "newFeatures": [
-    "本次为 2.0.0 的修复发布，没有新增应用能力。"
-  ],
-  "fixes": [
-    "从 pnpm 符号链接指向的真实包目录解析 openxiangda-cli，避免 WORKSPACE_ENGINE_DEPENDENCY_MISSING。"
-  ],
-  "affectedUsers": [
-    "使用全局或独立安装的统一入口维护 pnpm 工作区的开发者。"
-  ],
-  "compatibility": {
-    "node": ">=24",
-    "workspaceGenerations": [
-      "v1",
-      "v2"
-    ],
-    "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
-    "platformPolicy": "没有新增平台能力要求，部署仍执行目标平台预检。",
-    "backendBuild": "Nest 镜像继续由开发者电脑上的 Docker 构建。",
-    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
-  },
-  "upgradeSteps": [
-    "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.0.1。",
-    "在项目及其子目录运行 openxiangda version --json，核对工作区代际、项目引擎版本和解析来源。",
-    "需要更新 V2 项目依赖时运行 openxiangda update install --target workspace，检查锁文件并完成项目验收。"
-  ],
-  "knownLimitations": [
-    "独立入口更新不会自动升级项目锁定的工具链，也不会迁移 V1 应用。",
-    "已发布的 2.0.0 保持不可变；本修复不代表平台部署或业务验收已完成。"
-  ],
-  "issues": [],
-  "sha256": "6bba13f70a956b58412da587fc9d7b50dd279fea809eae2461dd3515321a83dd",
-  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.0.1"
-}

package/releases/2.1.0.json

@@ -1,44 +0,0 @@
-{
-  "schemaVersion": "openxiangda.release-notes/v1",
-  "version": "2.1.0",
-  "title": "OpenXiangda 平台托管应用镜像上传",
-  "status": "reviewed",
-  "summary": "应用 Nest 后端在本机构建为 OCI 镜像后，通过平台登录态分片上传。平台负责应用归属校验、镜像存储和运行时拉取，开发者无需取得平台维护者个人镜像仓库的推送权限。",
-  "newFeatures": [
-    "发现并优先使用平台 backendImageUpload 能力，导出 linux/amd64 OCI 镜像并上传有界分片。",
-    "上传前校验本地镜像大小和摘要，复用已完成的镜像回执，并恢复分片传输中断。"
-  ],
-  "fixes": [
-    "启用平台上传后，应用部署不再依赖开发者对平台维护者镜像仓库的推送权限。",
-    "Docker classic image store 不支持 OCI 导出时，返回明确的 builder 配置指引。"
-  ],
-  "affectedUsers": [
-    "声明可选 Nest 后端并通过 CLI 或 MCP 部署的 OpenXiangda 2.0 应用开发者。",
-    "维护共享应用运行时及平台镜像存储的平台管理员。"
-  ],
-  "compatibility": {
-    "node": ">=24",
-    "workspaceGenerations": [
-      "v1",
-      "v2"
-    ],
-    "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
-    "platformPolicy": "平台托管上传需要匹配的后端、Registry 和网关发布，并启用 backendImageUpload；旧平台继续使用既有构建合同。",
-    "backendBuild": "可选 Nest 后端仍在开发者电脑上使用 Docker Buildx 构建，需要支持 OCI exporter 的 builder。",
-    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
-  },
-  "upgradeSteps": [
-    "平台管理员先按部署运行手册准备镜像存储与凭据，再部署匹配的后端和网关。",
-    "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.1.0。",
-    "更新 V2 项目锁定的工具链并刷新项目资料，核对平台上传能力后运行项目的 openxiangda deploy。"
-  ],
-  "knownLimitations": [
-    "当前仅支持 linux/amd64 单平台 OCI 镜像；默认单镜像上限为 1Gi，由平台配置控制。",
-    "已声明但未启用的平台上传能力会阻止部署，避免回退到个人镜像仓库推送。",
-    "镜像保留与垃圾回收由平台运维单独管理；现有版本仍可能需要历史镜像进行部署或回滚。",
-    "托管镜像开始使用后，后端回滚必须保留 Registry、持久卷、凭据和网关读取路由。"
-  ],
-  "issues": [],
-  "sha256": "d7f6a21ddc37b3d2439350bf17f5f4575192168944dc33efb15460f7d1854aff",
-  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.1.0"
-}