openxiangda-skill-kit 2.0.0-alpha.99 → 2.0.1

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

@@ -1,146 +1,50 @@
-# OpenXiangda 2.0 Data and Authorization
+# Data API 与权限
 
-Declare a resource and every field exactly once in `openxiangda.config.ts`.
-Do not write `schemaVersion`, `appCode`, `schema`, `capabilities`, `surface` or
-resource-level `fieldPolicies`; those are compiler projections, not application
-source. Do not create `platform/data` modules.
+授权由四层组成：页面/操作 capability、行谓词、字段 read，以及字段 create/update。前端只消费平台返回的最终访问结果来隐藏按钮、只读输入和剔除 payload；平台每次请求重新执行权威校验。
 
-```ts
-import {
-  currentUserDataPolicy,
-  dataPolicyExpression,
-  defineOpenXiangdaApp,
-  resourceCapabilityCodes,
-  resourceReadPolicy,
-} from 'openxiangda/config';
-
-const APP_CODE = 'visitor-center';
-const reservations = resourceCapabilityCodes(APP_CODE, 'visitor-reservations');
+以下仅以仪器管理应用举例，不是平台默认模型或角色。该示例的行规则是：学校管理员不受行谓词限制；学院管理员按记录 `collegeId` 匹配；仪器管理员按 `instrumentAdminIds` 包含当前用户匹配。不要增加影子范围字段。
 
-const visitorReservations = {
-  code: 'visitor-reservations',
-  name: '访客预约',
-  dataPolicyCode: 'reservation-host',
-  fields: [
-    {
-      code: 'visitorName', type: 'text.short', label: '访客姓名', required: true,
-      indexed: true, list: true, filter: true, searchable: true, sortable: true,
-      section: '访客信息',
-    },
-    {
-      code: 'visitDate', type: 'date', label: '来访日期', required: true,
-      list: true, filter: true, sortable: true, section: '来访安排',
-    },
-    {
-      code: 'hostUserId', type: 'user.single', label: '接待人', required: true,
-      list: true, filter: true,
-    },
-    {
-      code: 'hostDepartmentId', type: 'department.single', label: '接待部门',
-      list: true, filter: true,
-    },
-    {
-      code: 'attachments', type: 'file', label: '附件',
-      file: { maxCount: 5, maxSizeMb: 20, accept: ['image/*', '.pdf'] },
-    },
-    {
-      code: 'internalNote', type: 'text.long', label: '内部备注',
-      access: { read: ['app:visitor-center:internal-note:read'], update: false },
-    },
-  ],
-  list: { defaultPageSize: 20, defaultSort: { field: 'visitDate', order: 'desc' } },
-  form: { layout: 'sections' }, detail: { layout: 'sections' },
-  mobile: { enabled: true },
-};
-```
+`collegeId` 是应用 `colleges` Native Resource 的记录 UUID。学院 scope dimension 通过
+`valueSource.kind=native_resource` 绑定同一资源，选择器只展示平台按当前 membership 与
+create/update 闭包返回的值。人员和部门保存平台目录真实 ID；部门不等于学院，也不能作为
+学院范围的隐式来源。
 
-Put it in `data: { resources: [visitorReservations] }`. Resource CRUD
-capabilities are derived by `resourceCapabilityCodes`; grant the needed values
-to roles. Directory-backed roles also require
-`app:<app-code>:directory:read`. Explicit field `access` capability codes are
-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.
+字段策略支持 `read`、`create`、`update` 和 `mask`。显式空数组拒绝，能力数组采用 all-of。无权更新字段不仅 disabled，还必须从更新 payload 删除。
 
-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:
-
-```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'],
-    },
-  ],
-});
+```bash
+pnpm openxiangda check
 ```
 
-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.
+角色成员、维度授权和平台管理员由平台管理面维护，不属于应用开发 CLI。
 
-`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
-generated UI and platform field policies.
+自定义 PC/移动页面需要维护当前应用角色时，使用
+`openxiangda/core` 的 `loadRoleManagementCatalog`、
+`listRoleMemberships`、`searchRoleManagementUsers`、成员 mutation 与
+role-management-grant mutation。应用/平台超级管理员可以把全部角色或明确的
+目标角色集合委托给一个业务角色；普通业务管理者只有同时具备
+`management.delegate` 时，才能把自己已有的目标角色和动作子集继续委托。
+平台按当前用户角色并集重算，接口不接受 actor、tenant、active role 或
+impersonation token。mutation 必须携带 UUID `operationId`、`reason`，更新/撤销还必须
+携带最新 `expectedRevision`；409 后重新加载，不能猜 revision。使用前读取当前角色管理目录，详见[管理入口](administration.md)。
 
-For `uuid` fields, omission never generates a value. Only the resource system
-field `id` is platform-generated. An omitted optional UUID remains `null`; a
-required UUID must be supplied explicitly and cannot rely on an implicit
-database default.
+匿名外部访问不属于 RBAC 角色或 current-user 行策略。公开表单、续填、附件、重复校验和同一
+浏览器的本人记录访问只通过[`frontend.publicAccess` 专用合同](public-access.md)开放；平台继续在
+专用端点和 PostgreSQL/RLS 中强制匿名主体、字段、策略及提交回执边界。
 
-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.
-
-Generated list, detail, audit and preview surfaces render the stored canonical
-`label` snapshots for `option.*`, `user.*`, `department.*` and
-`resource-ref.*`, including multiple arrays and the first linked list column.
-Do not add application formatters, directory re-queries or browser-side joins
-for these standard fields.
-
-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:
+数值边界直接声明在字段上，`min`/`max` 为闭区间，并且只允许用于
+`number.integer` 和 `number.decimal`。跨字段约束声明在资源的
+`invariants` 中；每条约束只能比较同一记录的两个已声明字段，最多 20 条，
+由平台在 create/update/increment 的最终候选记录上统一执行。
 
 ```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 },
+    { code: 'startAt', type: 'datetime', label: '开始', required: true },
+    { code: 'endAt', type: 'datetime', label: '结束', required: true },
+    { code: 'capacity', type: 'number.integer', label: '容量', min: 0 },
+    { code: 'occupied', type: 'number.integer', label: '已占用', min: 0 },
   ],
   invariants: [
     { code: 'time-order', expression: { leftField: 'startAt', operator: 'lt', rightField: 'endAt' } },
@@ -149,122 +53,10 @@ invariants when all must hold:
 }
 ```
 
-`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;
-their authored counterparts are the semantic catalog entries above (some names
-such as `date`, `datetime`, `uuid`, `json` and `file` intentionally coincide).
-In particular, `number` is not a field type: choose `number.integer` or
-`number.decimal`.
-
-Current-user row access has one spelling only:
-
-```ts
-currentUserDataPolicy({
-  code: 'reservation-host',
-  name: '接待人员仅查看本人预约',
-  resourceCode: 'visitor-reservations',
-  field: 'hostUserId',
-  roleCodes: ['reception_staff'],
-  unrestrictedRoleCodes: ['visitor_admin'],
-})
-```
-
-Put that value in `authz.dataPolicies`, declare both roles, and set the
-resource `dataPolicyCode` to the same code. Do not invent `current_user: true`,
-lowercase match modes, a dotted value path, or policy-level `roleCodes`. The
-compiler and platform know that `user.*` fields compare their stable `value`;
-`field` remains the declared field root code.
-
-For portal visibility windows, use the typed SDK expression and keep it a
-server-enforced read policy:
-
-```ts
-resourceReadPolicy({
-  code: 'published-articles',
-  name: '仅查看当前已发布内容',
-  resourceCode: 'articles',
-  matchMode: 'AND',
-  rules: [{ dimensionCode: 'organization', field: 'organizationId' }],
-  expression: dataPolicyExpression.allOf(
-    dataPolicyExpression.constant({
-      field: 'status', operator: 'eq', value: 'PUBLISHED',
-    }),
-    dataPolicyExpression.databaseNow({
-      field: 'publishAt', operator: 'lte',
-    }),
-    dataPolicyExpression.anyOf(
-      dataPolicyExpression.null({ field: 'expireAt', operator: 'is_null' }),
-      dataPolicyExpression.databaseNow({ field: 'expireAt', operator: 'gt' }),
-    ),
-  ),
-})
-```
-
-`db_now` is platform-owned PostgreSQL statement time and only accepts a
-`datetime` field. Missing/null values match only `is_null`; they do not match
-negative constants or time comparisons. The same bounded expression can
-combine `currentUser`, `dimension`, `relation`, `constant`, `null`, and
-`databaseNow` leaves under `allOf`/`anyOf`. Never duplicate this expression in
-a page `where` filter and call it authorization: UI filters are optional
-display state and cannot weaken or replace Native RLS.
-
-`readExpression` is always added on top of the base `matchMode`/`rules`; those
-base rules continue to restrict create/update/delete. If writes truly need no
-row scope beyond capability checks, say so explicitly with
-`writeBoundary: 'capability_only'` instead of `matchMode`/`rules`. Never use an
-empty base implicitly: `check` rejects it so an AI cannot accidentally remove
-write authorization while adding a portal read window.
-
-When a business membership resource is the durable source of a package role or
-RelationshipGrant, declare the projection instead of calling authorization
-management endpoints from application code:
-
-```ts
-authz: {
-  // ...capabilities, roles and policies...
-  roleMembershipSources: [{
-    code: 'venue-managers',
-    name: '场馆管理员角色成员',
-    resourceCode: 'venue-manager-relations',
-    userIdField: 'manager.value',
-    roleCode: 'venue_admin',
-    enabledField: 'enabled',
-    failureMode: 'strict',
-  }],
-  relationshipGrantSources: [{
-    code: 'venue-member-grants',
-    name: '场馆成员关系授权',
-    resourceCode: 'venue-manager-relations',
-    subject: { type: 'user', userIdField: 'manager.value' },
-    relationCode: 'member',
-    targetResourceCode: 'venues',
-    resourceIdField: 'venue.value',
-    operations: ['read', 'update'],
-    enabledField: 'enabled',
-    failureMode: 'strict',
-  }],
-}
-```
-
-The user path must be `user.single.value`; the target path is `id` only when the
-source resource is also the target resource, or a `resource-ref.single.value`
-that points at the declared target resource.
-Operations are a bounded constant list. Create/update/delete the relationship
-resource through the standard Data API; the platform converges and revokes only
-the facts owned by that source. Projection failure is always strict because a
-last-known-good grant could defeat revocation.
+`date-range` 与 `datetime-range` 必须显式声明 `rangeBoundary`，取值为 closed 或 half-open。选择半开区间 `[start, end)` 时相邻时间段不冲突；闭区间端点相接可能重叠。
 
-Use the SDK projection health call after deployment. A platform operator with
-the existing authorization-management capability may run rebuild for historical
-rows or recover a dead-letter job. Rebuild/recovery are idempotent and accept an
-`operationId`; they never accept a user token, user id override or impersonation
-input. Do not write `sourceCode`, canonical membership rows or relationship
-grant rows yourself.
+业务 uuid 字段与系统 id 不同：可选业务 UUID 省略时为空，必填字段需调用方提供合法值，平台不会替业务 UUID 自动生成默认值。
 
-Run `pnpm openxiangda check` after every declaration or permission change.
+业务分派需要目标人员具有指定角色时，使用[事务中的角色条件](backend.md#role-member)，
+由平台在写入事务中核对当前有效成员。候选查询、页面隐藏、应用管理员身份和历史
+角色列表都不能替代这一规则，也不应在应用中复制一份权限状态。

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

@@ -1,42 +1,112 @@
-# OpenXiangda 2.0 Delivery
-
-Run `pnpm openxiangda check --json`; it defaults to the test target, compiles
-the complete configuration and contract bundles, and asks the target
-platform's advertised `configurationCompatibility` endpoint to run the same
-Native compiler validation used during deployment preparation. This read-only
-preflight happens before workspace checks, tests, builds, Buildx or uploads.
-Use `--environment production` only when explicitly checking that target. A
-failure preserves `pointer`, client contract/schema versions, platform
-version/capability and the required/supported application-contract tuples.
-The capability also publishes the existing 4 MiB configuration, 8 MiB
-contract and 10 MiB total request bounds so oversized input fails before the
-transport layer.
-Never remove generated fields, reduce versions, raise limits, add app-code
-exceptions or introduce 1.x compatibility to make it pass. The platform
-revalidates authoritatively during deployment preparation.
-
-After compatibility succeeds, check owns static checks, tests and production
-builds but deliberately does not seal an AppPackage. Its
-`data.sealedArtifact` object and `.openxiangda/build/seal-status.json` make that
-state explicit even when an older `app-package.json` remains on disk. Deploy to
-test with the returned `openxiangda deploy` next command. Deploy owns the
-official application Dockerfile and platform-provided repository target,
-builds and pushes the Nest image, then writes a `sealed` status tied to the new
-immutable package digest. Never ask the developer for an image tag, digest,
-registry password, Docker configuration, or another public build command. If
-Docker, Buildx, repository configuration, or registry login is missing,
-preserve the stable machine error and retry with the same
-`pnpm openxiangda deploy` command after fixing that prerequisite.
-
-`pnpm openxiangda accept --plan <file>` is an optional manual preproduction
-test helper. It prepares expiring real identities but does not deploy, seal,
-promote or satisfy any release gate. Use it only when the requested acceptance
-needs real role membership and browser login.
-
-Use `pnpm openxiangda status` and `pnpm openxiangda logs` without an ID for the most recent run, or pass an explicit run ID.
-
-For the AI-native MCP entrypoint, `build_app` and `deployment_plan` are explicitly unsealed previews. After the user authorizes deployment, call `deploy_app` without any image coordinate; it owns the same automatic Buildx, push, digest and sealing path as the CLI.
-
-Applications with Native Data Resources automatically require `data.native-golden-crud`. If deployment returns `OPENXIANGDA_REQUIRED_CAPABILITY_UNAVAILABLE`, preserve the remediation to upgrade the platform and retry the same deploy command. Never remove the requirement, edit the AppPackage, construct a second identity path, or create Function-based CRUD.
-
-After a successful test run, deploy the exact same version with `pnpm openxiangda deploy --environment production --from <test-deployment-id>`. Roll back with `pnpm openxiangda rollback --environment production --to <app-version-id>`. The platform owns durable deployment state.
+# 部署、生产晋级与恢复
+
+应用开发者从工作区执行 `pnpm openxiangda`。平台负责应用版本、运行状态和恢复决定。工具链自身的 npm 发布由平台维护者负责，应用项目无需复制发包脚本或平台验证矩阵。
+
+## 测试部署
+
+发布前，先将本轮源码、生成契约及必要记录合入并推送仓库的远端默认主分支，然后从干净且同步的主分支工作区发布。工具从 origin 的远端 HEAD 识别主分支，不把任务分支的 upstream 当作主线。未提交、未推送、未合并或落后主线的问题会在构建和上传前返回；工具不会自动合并分支或覆盖其他会话的改动。
+
+开发开始时先同步主线并读取项目现状，开发完成包括提交、推送与主线整合。每个工作区保持一个写者；需要并行时使用独立目录并明确各任务范围。日常 dev/check 仍可验证未提交源码。没有 Git 远端的项目应先建立并绑定仓库再发布。
+
+准备部署时直接执行 deploy，它已经包含兼容性预检、生成、检查、测试和构建。只想检查代码时使用 [check](testing.md)，无需在 deploy 前重复运行全套检查。
+
+测试发布还会核对 [AppSpec](appspec.md) 的需求依据、架构、权限、性能预算和验收计划。缺失时给出具体记录位置，先补实际设计；首次测试部署不要求预先完成线上业务验收。
+
+```bash
+pnpm openxiangda deploy --dry-run --json
+pnpm openxiangda deploy
+pnpm openxiangda status --json
+pnpm openxiangda logs <deployment-id> --json
+```
+
+默认目标为 `test`，平台内部标识为 `preproduction`。只读预览不生成构建产物、不上传制品、不提交 DeploymentRun；因此预览成功不能证明代码已通过检查。正式检查使用本地完整校验，再通过目标平台的 `configurationCompatibility` 核对同源规则、密钥、已有物理模型和登录提供方等只读条件；失败时停止后续步骤。只有启用了自定义 Nest 后端的应用才需要构建后端镜像及对应 Docker 环境。
+
+平台启用镜像上传后，`deploy` 在本机用 Docker Buildx 导出 OCI 镜像，再使用当前平台登录态分片上传。开发者只需应用部署权限，无需登录平台管理员的镜像仓库或取得推送凭据。已完成的镜像层按摘要复用，中断后重新执行同一条部署命令可恢复上传；平台核验镜像完整性后才进入应用发布。尚未升级的旧平台保留其原镜像构建合同；新平台已声明上传能力但未启用时，命令会明确报告平台配置缺失。
+
+生成的不可变 AppVersion 绑定前端、可选后端、配置契约和制品摘要。默认提交后持续跟踪同一运行，直到平台成功、失败或取消，最多观察 15 分钟。`--no-wait` 只提交，适用于已有状态跟踪器的自动化；此时返回运行 ID 不代表部署完成。
+
+构建、上传及平台执行都会显示当前阶段和耗时，长步骤每 10 秒反馈一次。平台的准备、部署、切换和健康检查状态来自原运行。观察超时或连接中断不会取消部署或重建候选，使用下面的命令继续跟踪：
+
+```bash
+pnpm openxiangda status <deployment-id> --watch
+```
+
+网络响应不确定时先查询原运行，不凭本地输出创建重复部署。平台部署成功后，仍需执行真实角色的业务验收。
+
+相同源码候选重试时，工具会重新核对本地验证证据、封存清单和制品字节，复用仍有效的构建结果及后端镜像；已上传内容按摘要查询并复用。只有环境条件改变时不需要重建源码制品。输出损坏、输入变化或缓存缺失时自动回到正式检查和构建。缓存位于 `.openxiangda/build/`，不是新的部署状态源；提交响应不确定时使用原候选和幂等键，已有失败运行按其 recovery 恢复。
+
+## 测试环境验收
+
+至少记录应用版本、目标环境、真实角色、复现数据、预期和实际结果。按改动范围检查页面、权限、业务规则和失败路径；详见[校验与验收](testing.md)。
+
+| 证据 | 能说明什么 |
+| --- | --- |
+| 本地 check 成功 | 本次声明兼容，检查、测试和构建通过 |
+| 包密封完成 | 存在可识别的不可变候选版本 |
+| DeploymentRun 成功 | 平台完成该版本的部署流程 |
+| 真实角色的页面与业务操作通过 | 对应场景在目标环境可用 |
+| 生产晋级成功并回读 | 生产使用指定测试版本；仍需核对实际入口与关键业务 |
+
+构建成功、提交成功和真实业务验收是不同证据，报告时分别给出实际状态。
+
+## 生产晋级
+
+生产必须复用已成功部署到测试环境的同一版本，不能从当前源码直接重建：
+
+先按真实操作保存 `appspec/verification/<测试运行ID>.json` 并提交、推送到主线。晋级会从测试源码提交读取原验收计划，核对报告的运行 ID、包摘要、AC 场景与性能证据；主线后来的需求不改变已测范围。
+
+该版本的源码提交必须仍包含在权威远端主分支中。主分支后来有新提交，不会改变本次晋级的制品。若任务分支采用 squash/rebase 合并，应在最终主线提交上重新冻结并验证测试候选，不能继续晋级合并前的提交。
+
+```bash
+pnpm openxiangda deploy --environment production --from <test-deployment-id> --dry-run --json
+pnpm openxiangda deploy --environment production --from <test-deployment-id>
+pnpm openxiangda status --json
+```
+
+预览会精确读取指定测试运行的封存配置并核对生产密钥、模型和登录条件，返回源运行、版本与摘要。主线后来变化或版本较旧，不会使预检改用当前源码或最近版本列表。测试运行失败、版本缺失或条件不符时直接失败。平台在真正晋级时再次权威校验。生产参数不接受测试环境的 `environmentId` 或 `idempotencyKey`。已有生产发布授权时可继续执行；授权不明确时先准备版本、预览及验收证据，再确认具体发布对象。
+
+## 失败、重试与回滚
+
+`logs` 返回首个失败 `rootFailure`、最近失败 `latestFailure`、候选状态、尝试账本与 `recovery`。无失败时对应字段为 null。按平台给出的 `recovery.nextCommand` 处理；只在 `recovery.cancelAllowed` 为真时取消。已激活的运行不能用 cancel 撤销。
+
+```bash
+pnpm openxiangda retry <deployment-id>
+pnpm openxiangda cancel <deployment-id>
+pnpm openxiangda rollback --to <app-version-id>
+```
+
+环境版本回滚不保证撤销数据库业务写入；数据修复需要单独计划与验证。暂停与恢复默认作用于测试环境；生产必须显式选择：
+
+```bash
+pnpm openxiangda stop
+pnpm openxiangda start
+pnpm openxiangda stop --environment production
+```
+
+stop 保留数据与配置，start 从当前不可变版本恢复。不要把暂停、取消、回滚当作同一种操作。
+
+## 自动化与错误定位
+
+CLI 的 `--json` 输出单个 `openxiangda.cli-result/v2` 对象；失败包含 code、message、retryable、remediation、nextCommand，以及适用的 pointer/details。自动化依据 code 和结构化字段决策，不解析中文描述。
+
+`check`、`deploy` 和持续状态观察的结果带 `data.execution`，包含本次操作 ID、总耗时及各阶段状态和耗时。阶段进度写到 stderr，保持 `--json` 的 stdout 可解析；`--json-events` 则通过 `command.status` 返回同源结构化进度。MCP 客户端提供 `progressToken` 时收到标准进度通知；不订阅通知仍能从最终结果读取阶段摘要。MCP `deploy_app.wait` 默认 true，`deployment_status.watch` 可继续观察原运行。
+
+兼容性错误会列出当前工具链与目标平台的版本、能力和契约要求。按定位修复声明或升级目标平台，不删除真实业务要求、改写摘要或绕过权限来让预检通过。应用所需能力由规范化声明派生，应用不能手写一份能力列表冒充平台支持。
+
+`OPENXIANGDA_CONFIGURATION_VALIDATOR_MISMATCH` 表示工具链与平台的校验实现不配套，应按发布说明升级对应版本；它会在构建、镜像推送和制品上传前出现。模型类型不能原地替换时，按提示设计新字段及数据转换；必需密钥缺失时配置目标环境后继续，不修改源码伪装问题已解决。
+
+MCP 的 check_app、deployment_plan、deploy_app 使用与 CLI 相同的环境与生产晋级参数规则。完整参数以[CLI](cli.md)与[MCP](mcp.md)为准。
+
+## 构建前运行配额
+
+`deploy --dry-run`（MCP `deployment_plan`）会只读查询目标 TEST 的运行配额，输出 `runtimeCapacity` 的核验时间、所需增量、各配额剩余量和缺口。`sufficient: false` 表示当前不足；`null` 表示无需新增或未核验，必须结合 `basis` 与 `capacity.checked` 阅读。专用命名空间未检查不能当成资源充足。
+
+正式 deploy 在检查脚本和镜像构建前预检；平台缺少配套能力或无法核验时明确停止。配额快照不预留资源，实际执行再次检查。已有可验证密封候选会携带摘要和幂等键，平台识别 `existing-run` 时返回原运行，不把它当作新副本；观察或恢复原运行使用 status/retry。不要为绕过配额创建新包或切换目标环境。
+
+## TEST 单副本维护替换
+
+平台配额只允许一个后端副本时，可显式选择维护替换。它会停止当前 TEST 后端，期间应用不可用；成功后激活新版本，失败时由原 DeploymentRun 恢复旧后端。恢复尚未完成时继续占用原运行，status/logs 显示恢复阶段与首个失败，不允许用新部署或取消跳过恢复。
+
+先运行 `openxiangda deploy --environment test --strategy maintenance-replace --dry-run --json` 查看前驱版本、Head revision 和停止后的容量估算，再使用相同参数去掉 `--dry-run` 提交。计划不预留资源。只有已存在、身份匹配的单副本 TEST 后端才可使用；前端应用、新应用和 production 不支持。默认仍为 rolling，不会因配额不足自动停止实例。
+
+策略属于部署幂等请求。默认维护幂等键含策略，显式幂等键不能在不同策略之间复用。已有运行通过 status/retry 恢复；持续恢复中的运行保持 preparing/maintenance-recovery-required，平台会重试恢复，恢复失败时保留原运行与错误。

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

@@ -0,0 +1,32 @@
+# 需求与开发流程
+
+先确认用户要完成的任务，再选择数据模型、页面和权限。使用项目锁定的 `pnpm openxiangda`，读取 `context --json` 与相关专题。现有项目的代码和实时契约优先于其他项目的样例。
+
+## 新应用先完成设计基线
+
+从模糊想法开始时，按[对话发现与产品设计](product-design.md)分析已有资料、提出可解释的模块建议，用少量自然语言问题持续沟通确认。完整首发范围的 PRD、旅程、页面交互、原型、权限和架构设计齐备后，再制定实施计划和编写业务实现。用户已给出完整材料时先核对矛盾和遗漏，不重复访谈；已有确认持续有效。
+
+## 根据任务决定工作量 {#risk}
+
+| 变化 | 需要明确的内容 | 验证 |
+| --- | --- | --- |
+| 格式、无行为重构 | 保留现有行为，无需创建需求记录 | 受影响静态检查和现有测试 |
+| 文案、字段展示、局部规则 | 业务含义、影响页面和预期结果 | 对应数据和交互 |
+| 跨模型、权限、状态变化 | 用户角色、正反场景、数据和恢复边界 | 真实角色、API 和浏览器 |
+| 身份、迁移、并发、外部副作用 | 所有者、失败与幂等、资源边界、回滚和架构决定 | 所涉及契约的专项验证 |
+
+技术命名、可逆布局等在已有要求内决定。新的业务含义、权限扩大或尚未授权的外部操作需要用户决定；已经明确授权的范围不重复询问。用户只要求分析时，不自动创建应用或发布。
+
+## 选择平台能力 {#capabilities}
+
+- 普通数据管理：通过 `defineDataModel`、`defineApplicationModule` 和显式 CRUD 视图声明；模型不自动生成菜单或写权限。
+- PC/移动页面：先复用平台组件和标准页面，再使用受支持的页面、插槽与导航扩展。详见[前端](frontend.md)。
+- 无平台账号的外部表单：使用[匿名公开访问](public-access.md)，不用普通 RBAC 角色冒充匿名主体。
+- 标准审批、待办与通知：按需声明平台能力，见[工作流](workflow-events.md)。
+- 真实事务或外部集成：使用[按需后端](backend.md)，不为每张表重写 CRUD 控制器。
+
+## 实施与交接 {#iteration}
+
+开发使用 `pnpm openxiangda dev`，过程中运行必要的聚焦测试。交接前按[检查与验收](testing.md)验证；授权发布后按[交付](delivery.md)部署。失败保留错误码、位置和原始候选，依据平台恢复指令继续。
+
+[AppSpec](appspec.md)保存业务意图、设计与交付记录，不复制字段 Schema、生成契约和部署状态。新应用维护具体设计和评审，复杂度随业务展开；既有小变更沿用有效设计，仅修订受影响记录，无行为变化可引用已有记录。每轮先读取当前规则、澄清业务、评估架构、权限和性能，随后实施与验证，发布后更新当前规格及交接。测试部署前需要设计和验收计划，生产晋级前需要绑定测试运行及包摘要的实际验收报告。