openxiangda-skill-kit 2.0.0-alpha.91 → 2.0.0-alpha.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.91",
+  "version": "2.0.0-alpha.94",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.72"
+    "openxiangda-devkit-core": "2.0.0-alpha.75"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/SKILL.md

@@ -38,10 +38,18 @@ For an AI-native client, start the workspace protocol through the same pinned ex
 pnpm exec openxiangda --mcp-stdio --cwd <workspace>
 ```
 
-Read `openxiangda://workspace/contracts` or call `contract_describe`. When AppSpec is enabled, read `openxiangda://workspace/appspec` or call `appspec_context`; treat it as advisory context, never as deployment authority. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. Never create an application MCP server, Catalog file, preview store or AI authorization path.
+Read `openxiangda://workspace/contracts` or call `contract_describe`. For first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration; never treat the proposal as runtime discovery. When AppSpec is enabled, read `openxiangda://workspace/appspec` or call `appspec_context`; treat it as advisory context, never as deployment authority. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. Never create an application MCP server, Catalog file, preview store or AI authorization path.
 
 The browser uses the current logged-in user's complete application-role union. The platform is authoritative for capabilities, fields, rows and RLS. A declared Perspective is only a read projection over that union: it may narrow pages, rows and readable fields, but never create/update/delete, workflow or custom-action authorization. Omitted Perspective means the complete union. Application code does not replace the authenticated identity, persist a platform token, construct an authorization result or keep a second permission state.
 
+Applications own one explicit typed admin navigation declaration. The compiler
+owns page/route generation, but it never turns every generated resource or
+Workflow into a menu item; the Shell renders only declared navigation and then
+filters it by authorization. Keep page existence, route reachability and menu
+visibility separate. Use resource mutation ownership and per-operation
+generated surface flags, and give only self-contained `standalone` Workflow
+launch pages a menu entry.
+
 Read only the references needed for the current change, except the mandatory discovery and Data/authorization rules above:
 
 - [Discovery](references/discovery.md)

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

@@ -243,6 +243,10 @@ contract:
   and may protect a mutation of another resource;
 - `record-assert` locks one exact record and checks declared field values or
   declared field-to-field comparisons;
+- `databaseNowAssertion('publishAt', 'lte')` compares a declared `datetime`
+  field with the single PostgreSQL transaction time. Do not pass `Date.now()`,
+  an offset, a SQL function or a fallback timestamp; a successful idempotent
+  replay returns the original `evaluatedAt` without re-evaluating the guard;
 - `increment` targets one declared integer field and must have a matching
   same-resource, same-record `record-assert` guard;
 - never send SQL, table names, expressions, old guards without `errorCode`, or

package/skills/openxiangda-v2/references/data-authz.md

@@ -62,6 +62,16 @@ also granted only to the intended roles. They are owned and exported by the
 generated field policy, so do not repeat them in `authz.capabilities`.
 `authz.capabilities` contains only explicit `backend` or `ui` capabilities.
 
+Declare mutation ownership on the same resource with
+`mutationOwner: 'native' | 'action' | 'readonly' | 'workflow'`. Native defaults
+to generated list/detail/create/update/delete. Other owners default to readable
+list/detail only and must use their named action or Workflow boundary for
+mutation. Use `generated: { list, detail, create, update, delete }` to narrow
+the generated page/operation surface. The compiler rejects Native mutation
+pages, AI operations or role grants on a non-Native owner, and rejects
+create/update when no writable business field exists. Do not grant a resource
+create/update/delete capability to make an action-owned record editable.
+
 Declare optional work Perspectives once at the application root. A Perspective
 references existing role codes; the compiler derives its readable capability
 projection, so never hand-author `capabilityCodes` or duplicate row filters:
@@ -99,6 +109,40 @@ generated UI and platform field policies.
 
 Field types are semantic, not PostgreSQL storage aliases. Use the catalog in the generated `AGENTS.md`: for example `text.short`, `number.integer`, `user.single`, `department.multiple`, `resource-ref.single`, `file`, `address` and `subtable`. The compiler alone chooses storage columns and constraints. Reference fields store JSON display values. For `resource-ref.*`, `resourceCode`, `value`, `label`, optional `description` and optional `snapshot` are convenient historical display data only: the target resource remains authoritative, the platform does not create a foreign key or refresh/check the stored JSON, and business actions that need current target state must query it by `resourceCode` plus `value`. A resource source `labelField` must point to `text.short` or `text.long`; a `serial-number` field can be listed in `searchFields`, `descriptionFields` or `snapshotFields`, but it is not a display label. File limits exist only under `file`; `maxCount` owns the single/multiple bound and `maxSizeMb` owns the per-file size bound. There is no `file.multiple` key.
 
+Numeric bounds belong on the field declaration and are enforced by the
+platform for every write path. They are inclusive, and only valid on
+`number.integer` or `number.decimal`:
+
+```ts
+{ code: 'capacity', type: 'number.integer', label: '容量', required: true, min: 0, max: 10000 }
+```
+
+Cross-field rules belong on the resource, not in a generated form callback.
+Only bounded same-record field comparisons are supported; declare multiple
+invariants when all must hold:
+
+```ts
+{
+  code: 'sessions',
+  name: '场次',
+  fields: [
+    { code: 'startAt', type: 'datetime', label: '开始时间', required: true },
+    { code: 'endAt', type: 'datetime', label: '结束时间', required: true },
+    { code: 'capacity', type: 'number.integer', label: '容量', required: true, min: 0 },
+    { code: 'occupied', type: 'number.integer', label: '已占用', required: true, min: 0 },
+  ],
+  invariants: [
+    { code: 'time-order', expression: { leftField: 'startAt', operator: 'lt', rightField: 'endAt' } },
+    { code: 'capacity-not-exceeded', expression: { leftField: 'capacity', operator: 'gte', rightField: 'occupied' } },
+  ],
+}
+```
+
+`datetime-range` is always a non-empty half-open interval `[start, end)`.
+Adjacent values such as `[10:00, 11:00)` and `[11:00, 12:00)` do not overlap.
+Use the ordinary `overlaps` query operator or a `query-empty` transaction guard;
+never add or subtract milliseconds at the boundary.
+
 Do not author raw schema or storage words as field types. `string`, `text`,
 `integer`, `decimal`, `boolean`, `date`, `datetime`, `uuid`, `json` and `file`
 describe value or storage families only when the platform protocol says so;

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

@@ -28,21 +28,54 @@ union. Never fetch identity for the header, display role codes, add a second
 identity selector, or copy Shell and
 directory-client implementations into application source.
 
-For a custom admin operation page, declare the route in
-`openxiangda.config.ts`, import the generated `appRoutes`, and bind every route
-key to exactly one local React page with `defineAdminContributions` from
-`openxiangda/react`. Pass the result to `OpenXiangdaApplication`. Do not wrap the
-page in another `Shell`: the runtime registers it in the unified router and the
-same Shell owns its menu entry, title, history and direct-URL capability gate.
-Only `navigation: 'menu'` routes enter the menu; hidden routes retain the same
-`capability` or `access.allOf/anyOf`, including ancestor constraints. Never add
-an application-owned layout, router, menu, identity provider or permission
-store. Keep operation pages under `/admin/operations`; parameterized routes are
-hidden so they cannot become unresolved menu links.
+The application owns the editable admin information architecture through the
+typed `defineAdminNavigation`, `adminNavigationGroup`, `adminResourcePage`,
+`adminOperationPage`, `adminWorkflowWorkCenterPage` and
+`adminWorkflowLaunchPage` helpers in `openxiangda/config`. The compiler emits
+all reachable `adminPages`, but the Shell renders only pages explicitly
+referenced by generated `adminNavigation`, then applies current-user access as
+a final filter. Page existence, route reachability and menu visibility are
+separate: detail/new/edit/dynamic/handoff pages never become menu entries by
+discovery, and permission logic cannot create entries. Read
+`openxiangda://workspace/contracts` or call `contract_describe`, then copy
+`data.adminNavigationAuthoring.suggestion.expression` once into
+`frontend.admin.navigation` with the listed `openxiangda/config` imports. The
+proposal is deterministic and editable; the compiler/runtime never invokes it
+or appends newly added resources later.
+
+Declare custom routes in `openxiangda.config.ts`, import the generated
+`appRoutes`, and bind every route key to exactly one local React page with
+`defineApplicationContributions` from `openxiangda/react`. Pass the result to
+`OpenXiangdaApplication`. The runtime registers `surface: 'admin'` routes inside
+the one platform Shell; do not wrap them in another Shell. It renders
+`surface: 'user'` routes without the admin Shell so mobile/user experiences can
+own their page layout without creating another router, identity provider or
+permission store. Only static admin routes explicitly referenced by
+`frontend.admin.navigation` enter the menu. Hidden routes retain the same
+`capability` or `access.allOf/anyOf`, including ancestor constraints. Keep admin
+operation pages under `/admin/operations`; parameterized routes remain
+reachable but cannot be menu references. `defineAdminContributions` remains an
+admin-only helper and intentionally rejects `user` routes.
+
+This is also the whole-application composition contract: pass the resulting
+`contributions` to `OpenXiangdaApplication` and let that component remain the
+only owner of `BrowserRouter`, `RuntimeBoundary`, Refine, generated resource and
+Workflow routes, and the admin Shell. A user page may render an independent PC
+or mobile layout, but it must not add a nested router/Shell or copy generated
+routes. Route parameters continue to come from React Router, and generated
+capability plus ancestor access guards run before the component renders.
+
+To expose the standard application-level todo center, add
+`adminApplicationTodoCenterPage()` to an explicit admin navigation group. The
+compiler generates `/admin/todos`; the same runtime exposes the independent
+mobile `/m/todos` page. The page reads only the authenticated user's
+Notification Hub recipient projection and deep-links to the platform-resolved
+target. Do not query Notification Hub management endpoints or recreate a local
+message state store.
 
 For a small business action on a generated resource page, use the typed
 `resources[resourceCode].toolbar`, `.row` or `.detail` slots accepted by
-`defineAdminContributions`. Declare a stable action code, label and
+`defineApplicationContributions`. Declare a stable action code, label and
 capability/access expression. The render context contains only the current
 resource, already-authorized record or selection, and a bounded `refresh()`;
 it does not own CRUD, revisions, fields or authorization. Invoke a guarded Nest

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

@@ -19,6 +19,20 @@ Use these optional modules only when the application has a real standard approva
 
 Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Keep business data in Data API/App API and pass an immutable `dataRef`, business revision and bounded facts into prepare/start.
 
+Every definition declares a launch mode: `standalone` for a self-contained
+generated save-and-start page, `custom-page` for an application operation page,
+`hidden-handoff` for a non-menu handoff route, or `work-center-only` when users
+only act on existing tasks. Only `standalone` may be referenced by
+`adminWorkflowLaunchPage`; the generated browser runtime uses the workflow's
+localized definition title, so applications do not maintain code-to-title
+maps. A standalone page receives all durable business context through its
+typed save handler and URL/search contract; it must never depend on transient
+router location state. Work center, task and instance pages remain reachable
+without becoming launch menu entries. Bind the generated metadata with
+`defineWorkflowLaunchContributions(workflowDefinitions, handlers)`; handlers
+only persist the durable business revision, while generated code keeps title
+and launch mode authoritative.
+
 Use an assignee Provider only when resolution depends on application data. The Provider returns stable Native user/role subjects and never makes the final task authorization decision.
 
 The standard operations are approve, reject, return, resubmit, transfer, delegate, add-sign, withdraw, admin reassign, admin terminate and reminder. Render only operations returned by the task/instance Surface. A template or application action cannot add a Workflow command that is absent from the Surface.
@@ -70,6 +84,70 @@ Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlis
 
 The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
 
+To replace the standard Workflow detail page everywhere, declare both route
+codes on the Workflow definition declaration. The desktop route must be an
+`admin` route, the mobile route must be a `user` route, and both paths contain
+exactly `:instanceId`:
+
+```ts
+frontend: {
+  root: 'apps/web',
+  routes: [
+    {
+      code: 'purchase-detail',
+      path: '/admin/operations/purchases/:instanceId',
+      label: '采购审批详情',
+      surface: 'admin',
+    },
+    {
+      code: 'purchase-detail-mobile',
+      path: '/m/purchases/:instanceId',
+      label: '移动采购审批详情',
+      surface: 'user',
+    },
+  ],
+},
+workflows: {
+  definitions: [{
+    version: 1,
+    definition: purchaseApproval,
+    launch: { mode: 'work-center-only' },
+    detailRouteCode: {
+      desktop: 'purchase-detail',
+      mobile: 'purchase-detail-mobile',
+    },
+  }],
+  bindings: [],
+  activations: [],
+},
+```
+
+Bind the generated routes with `defineApplicationContributions`. Inside the
+page, read `instanceId` from React Router and optional `taskId` from the query.
+Use `loadWorkflowInstanceSurface`, `loadWorkflowTaskSurface` and
+`loadWorkflowTimeline` from `openxiangda/core`; render only operations returned
+by the Surface. The platform resolves the same declaration for desktop/mobile
+work centers, Notification Hub logical messages, DingTalk cards and other
+channel snapshots. Omitting `detailRouteCode` keeps the standard pages. A
+declared but missing or incompatible route fails closed rather than falling
+back silently.
+
+Standard launch entry is also a platform Surface. Desktop uses
+`/admin/workflows/:workflowCode/new` and mobile uses
+`/m/workflows/:workflowCode/start`; both first load
+`loadWorkflowLaunchSurface(workflowCode)`, then use the same durable
+`saveBusinessRevision -> prepareWorkflowStart -> startWorkflow` protocol.
+`custom-page` and `work-center-only` declarations do not expose the standard
+launch Surface. After start, navigate through the device's standard instance
+entry so the current `detailRouteCode` contract can redirect consistently.
+
+An application-level inbox is enabled in explicit admin navigation with
+`adminApplicationTodoCenterPage()`. It projects Notification Hub messages and
+per-recipient interaction for the current logged-in user only; it is not the
+Notification Hub management console. Use its `去处理` navigation to enter the
+authorized Workflow or application page, and keep approve/reject/transfer
+commands on the destination Surface.
+
 ## Interactive channel actions
 
 Channel callbacks enter the Notification Action Gateway. The gateway verifies tenant, environment, recipient identity, task/participant, Surface revision, operation, nonce, signature and expiry before calling Workflow.

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

@@ -3,8 +3,8 @@
 - Use only the workspace-pinned CLI: `pnpm openxiangda <command>`. Never invoke a bare global `openxiangda` inside a 2.0 task.
 - `appspec/` is the optional OpenXiangda 2.0 business-intent layer. Before changing observable behavior, read the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID; use no ChangeSpec for L0 work, one short ChangeSpec for L1, and add permission/rollback/concurrency detail only for L2/L3. Before close, the user—not AI—confirms `currentSpec=merged` or `not-applicable`. AppSpec is advisory and never a release gate. Never read, import or migrate 1.x `openspec/` or SDD.
 - Use Vite, React Router, Refine Core and Ant Design. Do not add Umi, ProComponents or another admin shell.
-- Keep generated admin routes and custom actions inside the platform Shell. Bind generated `appRoutes` to local operation pages with `defineAdminContributions`, and use only its typed `toolbar`, `row` and `detail` resource slots. Do not create another router, menu, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API authorization remains server-owned.
-- Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case.
+- Bind every generated `appRoutes` entry to its local page with `defineApplicationContributions`; desktop `admin` routes stay inside the platform Shell, while `user` routes render without an admin Shell for independent mobile/user experiences. Use only its typed `toolbar`, `row` and `detail` resource slots for generated resource actions. Declare the complete editable admin menu with `defineAdminNavigation` and its page/group helpers; the Shell renders only generated `adminNavigation` references and permissions only filter them. Do not create another router, menu store, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API and Workflow authorization remain server-owned.
+- Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional `mutationOwner`, generated/list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case. Use `native` for direct Data API mutations, `action`, `readonly` or `workflow` for non-Native ownership; never grant or generate Native mutation for a non-Native owner.
 - Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.
 - Ordinary list/get/create/update/delete, filters, export and batch operations use the platform Native Data API. Do not create Function CRUD or NestJS wrappers.
 - Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
@@ -20,6 +20,6 @@
 - `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
 - Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
 - Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
-- Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through the canonical `openxiangda.config.ts` declarations and generated clients; never copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
+- Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through the canonical `openxiangda.config.ts` declarations and generated clients; declare each Workflow launch as `standalone`, `custom-page`, `hidden-handoff` or `work-center-only`, put only self-contained standalone launch pages in navigation, and bind durable save handlers with `defineWorkflowLaunchContributions` without repeating generated titles. Desktop and mobile standard launch pages load the same canonical Workflow launch Surface. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`; Work Center, the application todo center and notification channels consume the platform-resolved paths, while every Surface and command remains server-authorized. Add the standard current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page. Never depend on temporary router location state or copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
 - Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.
-- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; when AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.
+- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; for first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration. Never treat the proposal as runtime discovery. When AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.