openxiangda-skill-kit 2.0.0-alpha.92 → 2.0.0-alpha.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.92",
+  "version": "2.0.0-alpha.95",
   "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.73"
+    "openxiangda-devkit-core": "2.0.0-alpha.76"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -43,22 +43,51 @@ discovery, and permission logic cannot create entries. Read
 proposal is deterministic and editable; the compiler/runtime never invokes it
 or appends newly added resources later.
 
-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 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. Never add an
-application-owned layout, router, identity provider, permission store or a
-second menu store. Keep operation pages under `/admin/operations`;
-parameterized routes remain reachable but cannot be menu references.
+Generated desktop resource CRUD routes use the compiler-owned
+`/admin/resources/<resourceCode>...` namespace and always render inside the
+platform's one Shell. Their independent mobile admin surface is projected from
+the same generated route catalog under `/m/admin/resources/<resourceCode>...`.
+Generated pages consume that catalog for every list/create/detail/edit/back
+navigation; do not reconstruct root resource paths in application code. Root
+and ordinary `/m/...` paths remain available to explicit user routes. The
+compiler rejects an explicit route whose canonical path shape conflicts with
+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 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

@@ -84,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,7 +3,7 @@
 - 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. Declare the complete editable 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 authorization remains server-owned.
+- 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. Generated resource CRUD routes are compiler-owned under `/admin/resources/<resourceCode>...` and `/m/admin/resources/<resourceCode>...`; never recreate root resource paths, aliases or redirects. Explicit routes that have the same canonical shape as another explicit or generated route fail compilation, even when dynamic parameter names differ. Use only the 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.
@@ -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; 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. 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.
+- 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`; 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.