openxiangda 2.18.10 → 2.19.0

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.19.0",
   "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.19",
+    "openxiangda-contracts": "2.15.0",
+    "openxiangda-devkit-core": "2.17.0",
     "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.26",
+    "openxiangda-nest": "2.4.4",
+    "openxiangda-skill-kit": "2.2.0",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,32 +132,41 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.18.10",
+    "version": "2.19.0",
     "status": "reviewed",
-    "title": "OpenXiangda 2.18.10：随包技能/文档同步自建中心指南",
-    "summary": "openxiangda-skill-kit 随包技能与文档与源文档再同步：携带「自建待办与消息中心 UI」指南与 2.18.9 标准中心视觉重构说明；无代码行为变化。",
-    "newFeatures": [],
+    "title": "OpenXiangda 2.19.0：平台探针实测修复——编译期拦截三大易错声明与错误透明化",
+    "summary": "来自平台能力探针（platform-capability-probe）全流程实测的修复批：工作流 launch 缺失、快照字段标量投影、数据策略基线角色 unrestricted 三类错误从\"部署后白屏/无限重试/策略静默失效\"提前到编译期拦截；匿名公开策略校验拆分为带指针的独立诊断；发起页防白屏并透出流程命令 lastError；CLI create 支持会话向上继承；同步平台审计列排序与部署 Workflow Head 预检。",
+    "newFeatures": [
+      "编译器新增三项编译期拦截：workflow definition 必须显式声明 launch；unrestrictedRoleCodes 含基线角色（authenticatedUserRoleCode）直接报错（角色并集必命中，策略会静默失效）；option/user/department/resource-ref/cascade 快照字段投影到标量 inputSchema 属性直接报错并给出对象形状与 `<fact>.value` 比较片段。",
+      "匿名公开策略校验拆分为带独立错误码与指针的分组诊断（route 绑定/operations/fields/requiredFields/ownRecordFields 子集/draft 规则/public 投影等），不再聚合为一条无指针报错。",
+      "工作流发起页：definition.launch 渲染期访问改为可选链，缺失时显示可诊断的 404 而不是白屏；提交后轮询透出 process command 的 lastError（不再无提示转圈）。",
+      "平台审计列排序（contracts DATA_SYSTEM_SORT_FIELD_CODES）：列表 defaultSort/sortableFields 支持 created_at/updated_at/created_by/updated_by/id/revision，标准 Admin 列表内置创建/更新时间列可点击排序。",
+      "deploy 构建前只读比对 workflows.activations 与环境 Head：版本回退拒绝部署（DEPLOY_WORKFLOW_ACTIVATION_VERSION_REGRESSION），源码缺失已激活流程告警，防止盲部署停用流程。"
+    ],
     "fixes": [
-      "openxiangda-skill-kit 打包内容与源文档再同步：修复随包技能/文档滞后于「自建待办与消息中心 UI」指南与 2.18.9 标准中心视觉重构说明的问题。"
+      "openxiangda-cli create 在目标目录无登录态时按工作区发现规则向上继承会话（.git 边界停住），不再要求在不存在的目标目录里先登录。",
+      "openxiangda-skill-kit 打包技能/文档同步：声明速查表补数据策略白名单语义与基线角色陷阱、匿名公开字段子集约束、workflow launch 必填、快照对象事实、cascade 数组路径形状；workflow-events 补发起页与事实投影说明。"
     ],
     "affectedUsers": [
-      "通过 skill-kit 安装随包技能与文档的应用开发者与 AI 会话。"
+      "所有 OpenXiangda 2.0 应用开发者与 AI 开发会话；使用数据策略、工作流、匿名公开访问的应用需要关注新的编译期校验。"
     ],
     "upgradeSteps": [
-      "随 2.18.10 列车一起发布；应用无需单独升级，引用 openxiangda 2.18.9 及配套版本即可。"
+      "应用把 openxiangda 精确钉扎到 2.19.0 并重跑 pnpm openxiangda check；此前能通过 check 的声明无需改动，此前靠运行时报错暴露的写法会在编译期给出带修复片段的明确报错。",
+      "工作流 definition 若未声明 launch，会在编译期被拒绝：按报错提示补 `launch: { mode: 'standalone' }` 等声明后重新部署。"
     ],
     "knownLimitations": [
-      "本列车无独立代码变更；功能变更记录见 2.18.9 发布说明，两列车一并发布。"
+      "快照字段投影仅支持对象形状事实，标量投影不支持是契约决定而非缺陷；条件表达式需使用 `<fact>.value` 路径。",
+      "平台侧配套修复（auth 落地路由兼容、不变量 NULL 语义、匿名错误透传、验收票据时效、token TTL）在平台服务端发布列车中交付，本工具链列车不含。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "无平台配合要求。",
+      "platform": "平台服务端需随下一平台列车更新到匹配的 openxiangda-contracts；未更新前 check 的目标平台预检会报校验器版本不一致（fail-closed，属预期）。",
       "v1": "V1 工作区不受影响。"
     },
-    "sha256": "62fba20895d127dc14f81ddac0445eac22957a0e8dadca1556957bb65834869c",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.18.10"
+    "sha256": "89940c302299258200c67215c2ddadbcee505642cc586eda90434541b3f81468",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.19.0"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.19.0.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.19.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.19.0：平台探针实测修复——编译期拦截三大易错声明与错误透明化",
+  "summary": "来自平台能力探针（platform-capability-probe）全流程实测的修复批：工作流 launch 缺失、快照字段标量投影、数据策略基线角色 unrestricted 三类错误从\"部署后白屏/无限重试/策略静默失效\"提前到编译期拦截；匿名公开策略校验拆分为带指针的独立诊断；发起页防白屏并透出流程命令 lastError；CLI create 支持会话向上继承；同步平台审计列排序与部署 Workflow Head 预检。",
+  "newFeatures": [
+    "编译器新增三项编译期拦截：workflow definition 必须显式声明 launch；unrestrictedRoleCodes 含基线角色（authenticatedUserRoleCode）直接报错（角色并集必命中，策略会静默失效）；option/user/department/resource-ref/cascade 快照字段投影到标量 inputSchema 属性直接报错并给出对象形状与 `<fact>.value` 比较片段。",
+    "匿名公开策略校验拆分为带独立错误码与指针的分组诊断（route 绑定/operations/fields/requiredFields/ownRecordFields 子集/draft 规则/public 投影等），不再聚合为一条无指针报错。",
+    "工作流发起页：definition.launch 渲染期访问改为可选链，缺失时显示可诊断的 404 而不是白屏；提交后轮询透出 process command 的 lastError（不再无提示转圈）。",
+    "平台审计列排序（contracts DATA_SYSTEM_SORT_FIELD_CODES）：列表 defaultSort/sortableFields 支持 created_at/updated_at/created_by/updated_by/id/revision，标准 Admin 列表内置创建/更新时间列可点击排序。",
+    "deploy 构建前只读比对 workflows.activations 与环境 Head：版本回退拒绝部署（DEPLOY_WORKFLOW_ACTIVATION_VERSION_REGRESSION），源码缺失已激活流程告警，防止盲部署停用流程。"
+  ],
+  "fixes": [
+    "openxiangda-cli create 在目标目录无登录态时按工作区发现规则向上继承会话（.git 边界停住），不再要求在不存在的目标目录里先登录。",
+    "openxiangda-skill-kit 打包技能/文档同步：声明速查表补数据策略白名单语义与基线角色陷阱、匿名公开字段子集约束、workflow launch 必填、快照对象事实、cascade 数组路径形状；workflow-events 补发起页与事实投影说明。"
+  ],
+  "affectedUsers": [
+    "所有 OpenXiangda 2.0 应用开发者与 AI 开发会话；使用数据策略、工作流、匿名公开访问的应用需要关注新的编译期校验。"
+  ],
+  "upgradeSteps": [
+    "应用把 openxiangda 精确钉扎到 2.19.0 并重跑 pnpm openxiangda check；此前能通过 check 的声明无需改动，此前靠运行时报错暴露的写法会在编译期给出带修复片段的明确报错。",
+    "工作流 definition 若未声明 launch，会在编译期被拒绝：按报错提示补 `launch: { mode: 'standalone' }` 等声明后重新部署。"
+  ],
+  "knownLimitations": [
+    "快照字段投影仅支持对象形状事实，标量投影不支持是契约决定而非缺陷；条件表达式需使用 `<fact>.value` 路径。",
+    "平台侧配套修复（auth 落地路由兼容、不变量 NULL 语义、匿名错误透传、验收票据时效、token TTL）在平台服务端发布列车中交付，本工具链列车不含。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "平台服务端需随下一平台列车更新到匹配的 openxiangda-contracts；未更新前 check 的目标平台预检会报校验器版本不一致（fail-closed，属预期）。",
+    "v1": "V1 工作区不受影响。"
+  },
+  "sha256": "89940c302299258200c67215c2ddadbcee505642cc586eda90434541b3f81468",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.19.0"
+}

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": "80a0a3ab4c92c6f5ee7495bea706f6d976015776a7790a447d43e379ae10e43f"
     }
   ]
 }

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.19.0 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.19.0 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.19.0 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.19.0 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.19.0 skill install --force
+pnpm dlx openxiangda@2.19.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.19.0 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.19.0 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.19.0 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.19.0 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.19.0 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"
-}

package/releases/2.1.1.json

@@ -1,48 +0,0 @@
-{
-  "schemaVersion": "openxiangda.release-notes/v1",
-  "version": "2.1.1",
-  "title": "OpenXiangda 应用源码托管",
-  "status": "reviewed",
-  "summary": "私有化平台通过共享 Forgejo 管理应用源码。创建应用时自动初始化私有仓库并推送代码，应用管理员自动获得仓库管理权限，开发者使用长期 Git 凭据。",
-  "newFeatures": [
-    "既有 PLATFORM_ADMIN 自动获得共享 Git 服务全部已有和新建仓库的管理权限。",
-    "source resolve/clone 支持仅凭平台与仓库 URL、使用当前登录态读取源码，不安装或执行应用脚本。",
-    "新增 source status、source setup 和 source push 命令，支持初始化恢复和已有工作区接入。",
-    "创建应用后自动提交并推送初始源码，通过系统凭据管理器保存个人 Git 凭据。",
-    "配套平台支持首次部署前浏览源码及最近提交，并核验部署关联的提交已经推送。"
-  ],
-  "fixes": [
-    "应用源码可直接保留在平台托管仓库中，减少对开发者个人 Git 服务的依赖。",
-    "显式导入保留原 origin 为 external-source，初始化重试保留已有未提交修改，冲突推送不覆盖远端提交。"
-  ],
-  "affectedUsers": [
-    "使用 OpenXiangda 2.0 创建应用或接入平台源码仓库的开发者。",
-    "维护内部私有化平台和应用管理员权限的平台管理员。"
-  ],
-  "compatibility": {
-    "node": ">=24",
-    "workspaceGenerations": [
-      "v1",
-      "v2"
-    ],
-    "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
-    "platformPolicy": "自动源码托管需要匹配的平台后端、管理前端和网关，并配置 OPENXIANGDA_SOURCE_*；未启用的站点保持原创建行为。",
-    "gitCredential": "支持 macOS Keychain、Windows Git Credential Manager，以及 Linux 已安装的 Git Credential Manager 或 libsecret。",
-    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
-  },
-  "upgradeSteps": [
-    "平台管理员配置共享 Forgejo、源码入口和专用凭据派生密钥，部署匹配的平台版本；长期保留密钥及 Git 数据。",
-    "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.1.1。",
-    "更新 V2 工作区工具链；新应用自动接入，已有应用运行 openxiangda source setup --import 接入。",
-    "完成修改后运行 openxiangda source push -m 描述，再按现有检查和部署流程交付。"
-  ],
-  "knownLimitations": [
-    "当前仅同步应用管理员新增授权，不同步撤销或删除。",
-    "导入推送当前分支，不自动迁移全部历史分支、标签及 LFS 对象。",
-    "制品仍在本地构建；提交存在性核验不构成服务端构建证明。",
-    "新源码功能不依赖 Studio；Studio 旧代码移除属于独立后续工作。"
-  ],
-  "issues": [],
-  "sha256": "f7341eb21e1489c684ee03eed31568063dfad01bfe345f914552bd51b7357f84",
-  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.1.1"
-}

package/releases/2.10.0.json

@@ -1,42 +0,0 @@
-{
-  "schemaVersion": "openxiangda.release-notes/v1",
-  "version": "2.10.0",
-  "status": "reviewed",
-  "title": "OpenXiangda 2.10.0：通知已读回执基础能力",
-  "summary": "浏览器与 Nest SDK 增加通知投递详情、已读回执缓存和单次刷新接口，应用通过平台消息与投递标识使用钉钉已读查询。",
-  "newFeatures": [
-    "浏览器与 Nest SDK 同步提供 getNotificationMessage、getDingTalkCardReadReceipt 和 refreshDingTalkCardReadReceipt，并公开对应类型。",
-    "配套平台保存卡片查询标识，持久化单投递查询任务，区分已读、未读、未知、不可查询和查询失败。",
-    "配套平台通用化钉钉卡片发送、查询及总预算，并按资源配置准备和投递并发。"
-  ],
-  "fixes": [
-    "配套平台将钉钉 HTTP 403 QpsLimitForApi 识别为可退避重试的限流响应，保留创建请求结果未知时的既有处理边界。"
-  ],
-  "affectedUsers": [
-    "需要查询钉钉卡片已读状态或使用平台通知 SDK 的 OpenXiangda 2.0 应用开发者。"
-  ],
-  "compatibility": {
-    "node": ">=24",
-    "workspaceGenerations": [
-      "v1",
-      "v2"
-    ],
-    "v1Policy": "V1 引擎和已有应用不变。",
-    "platformPolicy": "已读接口需要匹配的平台后端、通知回执追加迁移，以及通知读取和内容读取权限。",
-    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
-  },
-  "upgradeSteps": [
-    "先部署匹配的平台后端及追加迁移，按实际钉钉额度配置统一的发送、查询和总预算。",
-    "将应用精确依赖升级到 openxiangda 2.10.0，更新锁文件，并通过标准检查。",
-    "使用平台消息 ID 和投递 ID 查询缓存或请求一次刷新；应用负责选择消息、分组和后续业务轮询。",
-    "在测试环境验证实际投递和已读回执，再使用同一应用候选晋级生产。"
-  ],
-  "knownLimitations": [
-    "一次上游查询针对一个 processQueryKey 下最多 20 名收件人；本版本不提供跨消息批量查询或自动全量轮询。",
-    "历史投递没有保存查询标识时返回不可查询，不能推断为未读；查询遵循钉钉提供方的 24 小时窗口。",
-    "包发布、平台部署与真实消息验收分别记录；本版本不会自动补发历史失败或未知通知。"
-  ],
-  "issues": [],
-  "sha256": "a1be367ab9c5de6b66ec8dd02724af71611183d99ddb9dae861e6253c58875df",
-  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.10.0"
-}