openxiangda-skill-kit 2.0.0-alpha.81 → 2.0.0-alpha.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.81",
+  "version": "2.0.0-alpha.84",
   "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.63"
+    "openxiangda-devkit-core": "2.0.0-alpha.66"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "Use when researching, designing, building, testing, or delivering a complete OpenXiangda 2.0 application.",
-      "sha256": "5545fe41b6afa06ee11eda13eeb372a4baf0ea448224a681d044952db743dd82"
+      "sha256": "ed1f6a68bf3c83402e7d98c64e424b2031091924e008167966d3d265d7ff980e"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -5,7 +5,7 @@ description: Use when researching, designing, building, testing, or delivering a
 
 # OpenXiangda 2.0
 
-Treat requirement discovery, architecture, authorization, development, testing and delivery as one evidence-backed application lifecycle. OpenXiangda 2.0 has no compatibility surface: replace an incorrect alpha contract directly and never add aliases, migration branches, 1.x SDD, Umi, ProComponents, Function CRUD, application RoleSession state or another identity path.
+Treat requirement discovery, architecture, authorization, development, testing and delivery as one evidence-backed application lifecycle. OpenXiangda 2.0 has no compatibility surface: replace an incorrect alpha contract directly and never add aliases, migration branches, 1.x SDD, Umi, ProComponents, Function CRUD, application-owned identity switching or another identity path.
 
 Before a workspace exists, use this Skill's exact npm version:
 
@@ -23,12 +23,13 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 Use this order:
 
 1. Read [Discovery](references/discovery.md), turn the request into actors, scenarios, data, permissions, constraints and acceptance evidence, and identify every unresolved choice.
-2. Read [Architecture](references/architecture.md), assign one owner to each capability and keep ordinary CRUD on platform Data API.
-3. For every resource or permission change, read [Data and authorization](references/data-authz.md) before editing `openxiangda.config.ts`.
-4. Read [Frontend](references/frontend.md) for pages or fields and [Backend actions](references/backend.md) only for a real business action.
-5. When the application explicitly enables standard approval or notifications, read [Workflow and Notification Hub](references/workflow-notification.md). Keep them optional and out of ordinary CRUD.
-6. Run the connected loop with `pnpm openxiangda dev`, then follow [Testing](references/testing.md) and `pnpm openxiangda check`.
-7. Follow [Delivery](references/delivery.md): deploy preproduction first, inspect status/logs, then promote the exact successful version to production.
+2. If the workspace contains `appspec/`, the user asks to maintain requirements, or the task changes observable behavior, read [AppSpec](references/appspec.md) and load `pnpm openxiangda spec context --json`. AppSpec is optional and never a release gate; L0 changes create no record.
+3. Read [Architecture](references/architecture.md), assign one owner to each capability and keep ordinary CRUD on platform Data API.
+4. For every resource or permission change, read [Data and authorization](references/data-authz.md) before editing `openxiangda.config.ts`.
+5. Read [Frontend](references/frontend.md) for pages or fields and [Backend actions](references/backend.md) only for a real business action.
+6. When the application explicitly enables standard approval or notifications, read [Workflow and Notification Hub](references/workflow-notification.md). Keep them optional and out of ordinary CRUD.
+7. Run the connected loop with `pnpm openxiangda dev`, then follow [Testing](references/testing.md) and `pnpm openxiangda check`.
+8. Follow [Delivery](references/delivery.md): deploy preproduction first, inspect status/logs, then promote the exact successful version to production.
 
 For an AI-native client, start the workspace protocol through the same pinned executable:
 
@@ -36,13 +37,14 @@ 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`. 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`. 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. Application code does not select or transmit a RoleSession, persist a platform token, construct an authorization result or keep a second permission state.
+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.
 
 Read only the references needed for the current change, except the mandatory discovery and Data/authorization rules above:
 
 - [Discovery](references/discovery.md)
+- [AppSpec](references/appspec.md)
 - [Architecture](references/architecture.md)
 - [Workspace agent contract](references/workspace.md)
 - [Backend actions](references/backend.md)

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

@@ -0,0 +1,58 @@
+# AppSpec
+
+AppSpec 是 OpenXiangda 2.0 应用仓库中的可选业务意图层。它帮助 AI 理解“为什么做、应当表现成
+什么、这次改变什么”，但不复制 `openxiangda.config.ts`、编译合同、代码、测试或部署状态，也
+不是发布门禁。
+
+AppSpec 只使用 2.0 的 `appspec/` 与 `openxiangda.appspec/*/v1`。绝不读取、识别、导入或迁移
+1.x 的 `openspec/`、SDD、表单、页面、函数和发布材料。
+
+## 何时读取
+
+- 工作区存在 `appspec/` 时，在分析需求或修改行为前运行 `pnpm openxiangda spec context --json`。
+- 已知变更或能力 ID 时传 selector，例如 `pnpm openxiangda spec context booking-window --json`。
+- AI-native 客户端可读取 `openxiangda://workspace/appspec` 或调用 `appspec_context`。
+- 默认只使用当前应用、相关能力、活跃变更和 ADR；历史变更只在追查原因时人工打开。
+
+## 何时维护
+
+| 风险 | 典型变化 | 最小维护量 |
+| --- | --- | --- |
+| L0 | 重构、格式、无行为变化 | 不创建 ChangeSpec |
+| L1 | 文案、单字段、局部规则 | 一份短 ChangeSpec |
+| L2 | 跨资源、权限、状态变化 | 加正反验收、数据与回滚 |
+| L3 | 身份、迁移、并发、外部副作用 | 加失败/幂等、资源边界和 ADR |
+
+用户没有要求且变更是 L0 时，不要为了“流程完整”创建文档。小应用可以长期只维护 `app.md`。
+
+## 标准操作
+
+```bash
+pnpm openxiangda spec init
+pnpm openxiangda spec add-capability CAP-BOOKING --title "预约管理" --resources bookings
+pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L1 \
+  --capabilities CAP-BOOKING --resources bookings
+pnpm openxiangda spec context booking-window --json
+pnpm openxiangda spec check
+pnpm openxiangda spec close booking-window --summary "已通过真实角色验收"
+```
+
+`spec check` 是用户主动选择的严格检查；普通 `check/dev/deploy` 只给 advisory，不因 AppSpec
+缺失或不完整而失败。
+
+## 写作边界
+
+- `app.md` 记录长期目标、角色、范围、术语和跨能力约束。
+- `capabilities/CAP-*.md` 记录当前有效需求，使用稳定 `REQ-*` 和可证伪 `AC-*`。
+- `changes/active/*.md` 只记录本次 delta、风险、影响范围与验收；关闭前把仍有效的结论合入能力规格。
+- `decisions/ADR-*.md` 只用于架构显著决定，不为普通小改创建。
+- 引用真实 2.0 resource/action code，不抄字段定义和权限矩阵的机器事实。
+- AI 可以创建 `draft`、指出未确认问题和建议更新，不能自行把需求标记为 `confirmed`。
+- 不因 AppSpec 与实现冲突就静默修改其中一方；明确指出冲突，由用户决定业务意图，技术事实以实时
+  编译合同为准。
+
+## 可迁移程度
+
+完整 AppSpec 能显著提高另一个新项目复现业务逻辑的概率，但最终文档本身不等于可执行应用。
+需要接近原应用时，应同时提供 AppSpec、`openxiangda.config.ts`、必要自定义动作、测试和外部接口
+合同；历史 ChangeSpec 不是必需输入。

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

@@ -12,10 +12,18 @@ and do not author an `authorizationJSON` permission mirror. The platform still
 records the initiating user and action code in records, files, events and audit.
 
 `OpenXiangdaDataApiService` deliberately retains ordinary current-user Data
-authorization. Do not use it to implement a declared business action. The
+authorization and automatically inherits the request Perspective for reads.
+Its writes still authorize against the complete role union. Do not use it to
+implement a declared business action. The
 business facade also rejects routes without immutable `OpenXiangdaOperation`
 metadata, so a controller cannot silently gain trusted Data access.
 
+If a custom controller bypasses the standard Data API and reads Nest-owned SQL,
+an external service or another datastore, inject `@CurrentPerspective()` and
+apply the declared role-based read projection explicitly. Perspective is not a
+credential and must never change mutation authorization. Prefer moving ordinary
+reads back to `OpenXiangdaDataApiService`, where the platform owns the contract.
+
 Do not duplicate resource persistence in controllers. Keep actions bounded and side-effect behavior explicit. Run `pnpm openxiangda dev` for the connected loop and `pnpm openxiangda check` before delivery.
 
 Keep the generated `apps/server/src/main.ts` on

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

@@ -60,6 +60,36 @@ 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 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:
+
+```ts
+export default defineOpenXiangdaApp({
+  // ...identity, authz and data...
+  perspectives: [
+    {
+      code: 'reception-desk',
+      name: '接待人员视角',
+      roleCodes: ['reception_staff'],
+      default: true,
+    },
+    {
+      code: 'visitor-admin',
+      name: '访客管理员视角',
+      roleCodes: ['visitor_admin'],
+    },
+  ],
+});
+```
+
+The runtime offers only Perspectives whose `roleCodes` intersect the current
+user's actual application-role union. Selecting one sends
+`X-OpenXiangda-Perspective` on standard reads. Native Data intersects the
+normal authorized role union with that Perspective before capability, field,
+row-policy and RLS evaluation. Omit the header for the complete union. Never
+use Perspective to guard writes, workflows or custom actions.
+
 `required: true` owns both storage nullability and form validation. A field
 without `access` inherits the resource read/create/update capability. Each
 access array is all-of; `false` is explicit deny. The same arrays drive the

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

@@ -7,4 +7,25 @@ CSV/XLS/XLSX preview import, export, filters, column settings and density. Keep
 imports at 100 rows per transaction, use exact declared labels or field codes,
 and leave attachment values to the platform managed-file component.
 
-Read the current user, complete application-role union and capabilities from the platform runtime authorization endpoint. There is no role switcher and the browser does not send a RoleSession header. Use capabilities and field access only to present or disable UI; strip unauthorized fields from create and update payloads and never treat a disabled input as server authorization. Verify with `pnpm openxiangda check`.
+Declare searchable and filterable fields on the resource and let the standard
+CRUD renderer compose the search area. Keyword search spans the declared
+searchable fields; the first two filters remain inline and additional filters
+open in the platform's large modal. The renderer also preserves declaration
+order for form fields and removes authorization/debug explanations from the
+business UI. Do not create application-owned search toolbars, field ordering
+maps, permission tips or per-resource CRUD pages for these standard behaviors.
+
+Read the current user, complete application-role union and capabilities from the platform runtime authorization endpoint. The standard Shell owns the optional Perspective selector. Use `hasReadCapability` for navigation, list/detail visibility and readable fields; continue to use `hasCapability` for create/update/delete, workflows and custom actions. The standard client sends the selected Perspective automatically, and the server repeats the projection for rows, fields and RLS. Never implement resource-specific frontend filters for it. Strip unauthorized fields from create and update payloads and never treat a disabled input as server authorization. Verify with `pnpm openxiangda check`.
+
+Use the standard `Shell` unchanged. It owns the authenticated user's display
+name, account identifier, safe avatar upload, localized application-role names,
+theme controls, Perspective selection and navigation scroll restoration. It
+also owns directory field requests under the current logged-in user's role
+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.
+
+Generated contracts intentionally emit each resource Surface once in
+`resourceSurfaces`; `resourceDefinitions[code].surface` references that shared
+object. Import the generated runtime definitions normally. Do not serialize,
+inline or duplicate Surface literals in application code.

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

@@ -19,6 +19,15 @@ For each changed resource, verify the real chain:
 5. stored values and audit records match the declared shape;
 6. PostgreSQL/RLS remains authoritative, including current-user and multi-role-union cases.
 
+For platform generator changes, add a representative multi-resource fixture
+(currently nineteen standard resources), assert each Surface literal is emitted
+only once, then run the unchanged Web dist budget gate. A budget failure is a
+generator/runtime regression to fix; never raise the application budget or copy
+generated contracts into a smaller application-local format. Browser acceptance
+must also cover the large more-filters modal, declaration-order forms, hidden
+developer-only authorization copy, real account/role labels, avatar update and
+left-menu scroll preservation across route changes.
+
 Mock and unit tests are useful but do not close remote acceptance. When real
 identity acceptance is needed, create a short-lived local plan and run:
 

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

@@ -8,7 +8,7 @@ Use these optional modules only when the application has a real standard approva
 - Workflow Kernel v2 owns definitions, instances, tasks, participants, commands, transitions and audit facts.
 - Application Events v2 owns durable facts and delivery.
 - Notification Hub v2 owns templates, rules, logical messages, channel delivery, callbacks and message operations.
-- Native Identity/AuthZ v2 owns the current user and the union of that user's current application roles. Never select, transmit or persist a RoleSession.
+- Native Identity/AuthZ v2 owns the current user and the union of that user's current application roles. Perspective is read-only and never changes workflow participation or action authorization.
 - Never import, query, migrate or call 1.x workflow/message code, tables, APIs, queues, templates or callbacks.
 
 ## Workflow declaration
@@ -46,7 +46,7 @@ Template variables must be declared by JSON Schema and stay within the field pol
 
 ## Detail navigation
 
-Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlisted `EXTERNAL_URL`, stable route code, path/query parameters and an authenticated access requirement. Do not place environment domains, bearer tokens, cookies, RoleSession identifiers or secrets in template strings.
+Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlisted `EXTERNAL_URL`, stable route code, path/query parameters and an authenticated access requirement. Do not place environment domains, bearer tokens, cookies, identity-switching credentials or secrets in template strings.
 
 The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
 

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

@@ -1,6 +1,7 @@
 # OpenXiangda 2.0 Application Agent Contract
 
 - 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 `pnpm openxiangda spec context --json`; use no ChangeSpec for L0 work, one short ChangeSpec for L1, and add permission/rollback/concurrency detail only for L2/L3. AppSpec is advisory, never a release gate, and AI must not self-confirm a draft. 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.
 - 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.
 - 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`.
@@ -8,7 +9,7 @@
 - Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
 - Every interactive business action binds `@OpenXiangdaOperation(operation)` and injects `OpenXiangdaBusinessDataApiService` or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data access only to its exact application/environment while audit retains the initiating user. Do not author `authorizationJSON` or reapply the user's resource, row and field permissions inside the action.
 - A NestJS backend declares only `enabled`, `isolation: 'shared' | 'dedicated'` and `resourceProfile: 'light' | 'standard'`. Never put raw Kubernetes resources, replicas, ports or environment maps in application metadata; the platform owns capacity and scaling.
-- Use the current logged-in user and the union of that user's application roles. The generated client uses same-origin cookies and does not transmit a RoleSession header. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
+- Use the current logged-in user and the union of that user's application roles. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
 - Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
 - Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
 - Declare every custom operation capability in `authz.capabilities` with `kind: 'backend'`, then reference that same code from the operation and its allowed roles. Generated resource CRUD capabilities do not go in this catalog.
@@ -19,4 +20,4 @@
 - 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.
 - 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`, and require its `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not a ninth CLI command. 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`; 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.