openxiangda-skill-kit 2.0.0-alpha.120 → 2.0.0-alpha.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.120",
+  "version": "2.0.0-alpha.123",
   "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.98"
+    "openxiangda-devkit-core": "2.0.0-alpha.101"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -30,8 +30,7 @@ directory-client implementations into application source.
 
 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
+and `adminOperationPage` 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
@@ -55,6 +54,14 @@ any explicit or platform-generated route, including dynamic routes that differ
 only by parameter name. Do not add aliases, redirects or route-order branches
 for earlier alpha paths.
 
+Declare the application-wide admin boundary at `frontend.admin.access` with
+`allOf` and/or `anyOf` capability arrays. Import generated `adminAccess` and
+pass it to `OpenXiangdaApplication`; the runtime evaluates that same immutable
+expression before `/admin/**`, `/m/admin/**`, the Shell, generated resources or
+admin contribution pages mount. Portal shortcuts may use the exported pure
+`isAdminAccessAllowed` predicate, while Data/App/Workflow APIs remain the
+server-side authority.
+
 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
@@ -134,10 +141,9 @@ 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
+To expose the standard application-level todo center, declare
+`frontend.user.applicationTodoCenter: true`. The compiler generates `/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.
@@ -147,9 +153,8 @@ single desktop/mobile paired catalog for standard Workflow and Todo pages. Each
 entry carries stable route codes, path parameters, access metadata and a
 `requiresAuthentication: true` marker; the top-level digest binds the complete
 catalog. Pass it directly to `OpenXiangdaApplication`. The runtime validates
-pair surfaces, parameter names and shared access metadata before registering
-the Router/Shell, and projects desktop `adminPages` from this same catalog.
-Applications must not recreate standard `/admin/todos`, `/m/todos`, or
+user Surface pairs, parameter names and shared access metadata before registering
+the Router. Applications must not recreate standard `/todos`, `/m/todos`, or
 Workflow paths, add aliases/redirects, or maintain a second route state. The
 compiler/platform preflight is the digest authority; the browser validates the
 digest shape and fails closed on malformed or inconsistent entries.

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

@@ -29,16 +29,53 @@ business/data/version tuple and `factDigest`.
 Every definition declares a launch mode: `standalone` for a self-contained
 generated durable-process 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. `standalone` and `hidden-handoff` receive a compiler-owned
-`processOperationCode` and subject declaration. The browser submits the
-platform standard process commit and persists only `commandId` in the URL; it
-never owns a save callback, facts/dataRef, preparation token, or direct start.
-Custom pages launch only inside a verified Named Action through
+only act on existing tasks. `standalone` exposes the standard user launch
+route, while `hidden-handoff` keeps the same route out of portal navigation;
+the generated browser runtime uses the workflow's localized definition title,
+so applications do not maintain code-to-title maps. `standalone` and
+`hidden-handoff` default to a compiler-owned
+`processOperationCode` and standard process commit. When the subject mutation is
+owned by an App Operation, declare `launch.submission.kind: 'named-operation'`
+instead. The compiler seals its POST path, capability, schemas, input sources,
+result paths and optional context prefill; the standard page invokes that exact
+operation and persists only a returned `commandId`. Missing/null
+`processCommand` is an explicit successful no-approval result. The browser never
+owns a save callback, facts/dataRef, preparation token, or direct start. Custom
+pages launch only inside a verified Named Action through
 `OpenXiangdaBusinessProcessService`.
 
+```ts
+launch: {
+  mode: 'hidden-handoff',
+  submission: {
+    kind: 'named-operation',
+    create: {
+      operationCode: 'reservation.submit',
+      inputs: {
+        idempotencyKey: { source: 'idempotency-key' },
+        applicant: { source: 'current-user-reference' },
+        venue: { source: 'field', fieldCode: 'venue' },
+        startAt: { source: 'field', fieldCode: 'startAt' },
+        purpose: { source: 'field', fieldCode: 'purpose' },
+      },
+      output: {
+        subjectId: 'id',
+        subjectRevision: 'revision',
+        processCommand: 'processCommand',
+      },
+    },
+    context: [{ queryParameter: 'venueId', fieldCode: 'venue' }],
+  },
+}
+```
+
+Every required operation request property must have one input binding. Use
+`field`, `idempotency-key`, `current-user-reference`, `requested-at`, and—for an
+`existing` intent—both `subject-id` and `subject-revision`. Context parameters
+only prefill declared fields; the Named Action still derives identity, validates
+authorization/business invariants and owns idempotency. Its
+`platformAccess.workflow.codes` must include this workflow.
+
 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.
@@ -179,7 +216,7 @@ stable snapshot and use a friendly placeholder instead of exposing userId.
 The standard desktop task and instance pages use `/tasks/:taskId` and
 `/workflows/:instanceId` as standalone full-screen routes outside the admin
 Shell. Historical `/admin/tasks/:taskId` and `/admin/workflows/:instanceId`
-routes only replace-redirect while preserving query/hash. Mobile remains the
+routes have no alias or redirect. Mobile remains the
 independent `/m/tasks/:taskId` and `/m/workflows/:instanceId` surface.
 
 Files, rich-text images and signatures on this page use only the Workflow
@@ -188,17 +225,18 @@ principal, authorized instance, projected resource/record/field and managed
 file id. Never substitute the ordinary Data API file route or put credentials
 in a file URL.
 
-Standard launch entry is also a platform Surface. Desktop uses
-`/admin/workflows/:workflowCode/new` and mobile uses
+Standard launch entry is also a platform user Surface. Desktop uses
+`/workflows/:workflowCode/start` and mobile uses
 `/m/workflows/:workflowCode/start`; both first load
 `loadWorkflowLaunchSurface(workflowCode)`, verify its compiler-owned subject and
-process operation, then use the standard durable process commit.
+submission contract, then use the standard durable process commit or the exact
+sealed Named Action.
 `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
+An application-level inbox is enabled with
+`frontend.user.applicationTodoCenter: true`. 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

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

@@ -42,6 +42,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 canonical `openxiangda.config.ts` declarations and generated clients. `standalone`/`hidden-handoff` use the compiler-owned process operation and Durable Business Process Command; never add a browser save callback or call Workflow prepare/start directly. Custom pages launch only through a verified Named Action using `OpenXiangdaBusinessProcessService`. PC and mobile render the same `ProcessCommandSurface` independently and recover only by `commandId`. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`. Add the current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page.
+- Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through canonical `openxiangda.config.ts` declarations and generated clients. `standalone`/`hidden-handoff` default to the compiler-owned process operation; action-owned submission must instead declare `launch.submission.kind: 'named-operation'` with sealed create/existing input and output bindings so the standard PC/mobile page calls the original Named Action and accepts an explicit no-Workflow result. Never add a browser save callback or call Workflow prepare/start directly. Custom pages launch only through a verified Named Action using `OpenXiangdaBusinessProcessService`. PC and mobile render the same `ProcessCommandSurface` independently and recover only by `commandId`. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`. Add the current-user todo page only with `frontend.user.applicationTodoCenter: true`; never query Notification Hub management APIs from a user page.
 - 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`; 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.