openxiangda 2.20.4 → 2.21.1

package/bin/distribution/launcher.js

@@ -11,8 +11,7 @@ export async function launch(packageRoot, args = process.argv.slice(2)) {
     await distributionCommand({ manifest, packageRoot }, args);
     return;
   }
-  // OpenDesign owns every native flag, including --cwd after design cli.
-  const explicitCwd = args[0] === 'design' ? null : flagValue(args, '--cwd');
+  const explicitCwd = flagValue(args, '--cwd');
   const authorization = args[0] === 'login' || args[0] === 'auth';
   const workspace = discoverWorkspace(explicitCwd || (args[0] === 'skill' ? flagValue(args, '--workspace') : null) || process.cwd(), {
     allowMissing: authorization,

package/documentation/AGENTS.md

@@ -8,8 +8,8 @@
 - 模型、页面、导航和权限由应用声明一次；编译器生成契约。业务代码不改生成结果、不创建 platform/data、不复制平台 Router、字段组件、客户端或权限状态。
 - 当前用户、角色并集、数据授权和部署状态归平台；应用不保存凭据或授权快照。普通 CRUD 走 Data API，真实业务动作才按需启用 Nest。想写后端接口时先按 docs development 的"判定是否真的需要 Nest 后端"逐行核对：列表/表单/详情/删除用 `createNativeResourceClient`，幂等、时间窗、状态前置用平台事务与守卫，聚合用服务端聚合；check 会拒绝未绑定已声明 operation 的应用 controller 路由。
 - 标准业务字段使用 `openxiangda/field-kit`；PC 补充控件使用 antd，移动使用有作用域的 `openxiangda/mobile` 和 MobileSurface，不引入上游全局重置。
-- 界面开发默认按 docs design-workflow 使用原版 OpenDesign 桌面和 design cli先设计整体视觉、可运行原型并实际走查，再实现。设备由真实任务决定；复用 Shell 导航事实、标准字段行为，通过 ui 和局部样式应用设计，不复制权限或导航状态。原型和 tokens 以 AppSpec assets 固定。模板 /home 不替代页面选型。
-- 应用默认先建立并保留标准管理后台：后台 Shell、显式菜单、资源表单、数据列表、详情/编辑、权限和流程入口是应用骨架。OpenDesign 可优化后台外观但不能替换后台；用户端 PC 与移动端可分别使用 OpenDesign 的完整视觉和交互，通过 runtime/Data API 读取后台数据。禁止用单页 HTML、iframe 或独立假后台替代后台，发布前分别验收后台与用户端入口。
+- 界面开发默认按 docs design-workflow 由当前 Agent 完成视觉、真实页面实现和浏览器修正；需要新视觉方向时可用 Image 2.5 等当前图片能力生成少量参考。图片不定义交互、权限或验收。设备由真实任务决定；复用 Shell 导航事实、标准字段行为，通过 ui 和局部样式应用设计，不复制权限或导航状态。采用的参考图、tokens 和必要原型以 AppSpec assets 固定。模板 /home 不替代页面选型。
+- 应用默认先建立并保留标准管理后台：后台 Shell、显式菜单、资源表单、数据列表、详情/编辑、权限和流程入口是应用骨架。Agent 可优化后台外观但不能替换后台；用户端 PC 与移动端按真实任务分别设计，通过 runtime/Data API 读取后台数据。禁止用图片、单页 HTML、iframe 或独立假后台替代后台，发布前分别验收后台与用户端入口。
 - 图表等专业交互先检查现有依赖并评估成熟组件/开源库，报表优先评估 ECharts，按需加载并释放实例；平台数据、权限与聚合仍通过官方能力。详见 docs frontend。
 - 入口与导航验收从平台应用列表开始，检查应用根路径、后台首个有权菜单、登录返回及刷新深链接；不能只验证开发者给出的业务链接。
 - 无账号表单或外部公开数据读取都读取 `docs public-access`：使用 `frontend.publicAccess` 和专用客户端；提交策略声明 `create` 时必须启用 `draft`，只读公开目录使用 `public.list`/`public.read` 与 `publicRecordFields`，附件/图片/富文本按平台托管 URL 读取，子表必须声明 `publicSubtableFields`，不创建 guest 角色、不传 draft id、不调用普通 Data API。标准审批、通知和后端均按需启用。

package/documentation/appspec.md

@@ -36,11 +36,18 @@ appspec/
 ```bash
 pnpm openxiangda spec init
 pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L2
+pnpm openxiangda spec add-capability CAP-REPAIR-REQUEST --title "报修申请能力" --resources repair-requests
 pnpm openxiangda spec context booking-window --json
 pnpm openxiangda spec check
 ```
 
-已有工作区优先用 `spec new` 生成本地记录。访谈尚未创建应用时，可在 `appspec/changes/active/<变更ID>.md` 手工建草稿：front matter 使用 `schema: openxiangda.appspec/change/v1`、与文件名一致的 `id`、`title`、`status: draft`、`currentSpec: pending`、适用的 `risk`，以及 `documents: [实际评审ID]`。不必为整理设计先创建远端应用。
+已有工作区优先用 `spec new` 生成本地记录。跨变更复用的能力规格用
+`spec add-capability <CAP-*> --title <名称>` 单独建立（可带 `--resources`/`--actions`
+逗号分隔引用），排他创建 `appspec/capabilities/` 下的规格文件，绝不覆盖同名文件；
+ChangeSpec 通过 `capabilities` 引用这些 CAP-* 规格。访谈尚未创建应用时，可在
+`appspec/changes/active/<变更ID>.md` 手工建草稿：front matter 使用
+`schema: openxiangda.appspec/change/v1`、与文件名一致的 `id`、`title`、`status: draft`、
+`currentSpec: pending`、适用的 `risk`，以及 `documents: [实际评审ID]`。不必为整理设计先创建远端应用。
 
 | 阶段或风险 | ChangeSpec 必需正文 |
 | --- | --- |

package/documentation/backend.md

@@ -189,6 +189,44 @@ await businessData.transaction({
 分派已接受后撤销角色，不会自动撤销历史分派；后续处理动作必须重新验证当前权限，
 由管理员重新分派。此规则应写入 AppSpec，并实测撤销先发生和分派先发生两种顺序。
 
+## AI 能力目录与 MCP Facade {#ai-catalog}
+
+编译器为每个应用生成不可变的 AI 能力目录：资源的标准 CRUD 面（query/get/create/update/delete，
+按 `generated` 与 `mutationOwner` 实际开放的操作）自动成为 `generatedCrud` 能力；`backend.operations[]`
+中带 `ai` 声明的操作成为 `customAction` 能力。目录摘要（`aiCatalogDigest`）随当前声明生成并进入契约；
+平台 `GET .../native/ai/catalog` 按当前用户角色与字段权限裁剪后返回。为操作声明 `ai` 即把它加入目录：
+
+```ts
+operations: [{
+  code: 'dispatch-repair', method: 'POST', path: '/dispatch', capability: dispatchCapability,
+  ai: {
+    name: '受理派单', description: '把报修单派给指定技师并写入派工记录',
+    risk: 'write', resources: ['repair-requests'],
+    sideEffects: ['更新报修单状态为处理中', '写入一条派工记录'],
+  },
+}],
+```
+
+`ai` 的规则：`name` 与 `description` 必填；`risk` 取 `read | write | destructive | external`，
+`read` 等价于 `method: 'GET'`，DELETE 方法只能是 `destructive` 或 `external`；`resources`
+引用 1–16 个已声明资源；`sideEffects` 最多 20 条——只读必须为零，写操作至少一条具体副作用；
+`concurrency` 可选 `none | revision`，`timeoutMs` 限 100–30000。
+
+宿主（平台 AI 网关）用该目录装配 MCP Facade，应用不自己实现协议：
+
+- **单应用 Facade**（`createApplicationAiMcpServer`）：每个能力一个工具，只读能力直接以
+  `capability.code` 命名执行；写能力命名为 `capability.code + '.preview'`，只生成预览不落库；
+  存在写能力时额外提供 `openxiangda.ai.confirm`（入参 `previewId`），在用户明确确认预览摘要后
+  由宿主重新校验身份、权限、版本和幂等性再执行。目录本体通过资源 `openxiangda://ai/catalog`
+  读取。
+- **平台聚合 Facade**（`createAggregatedAiMcpServer`）：跨应用统一工具面
+  `apps.search`、`resources.describe`、`records.query`、`records.get`、`records.create`、
+  `records.update`、`records.delete`、`actions.invoke`、`mutations.confirm`；聚合器只把工具
+  路由到所属应用的执行器，不合并权限、不产生第二个数据或授权边界。
+
+这套 Facade 服务平台侧 AI 入口，与应用工作区开发用的 MCP（见[MCP 参考](./reference/mcp.md)）
+是两组互不重叠的工具。
+
 ## 启动与依赖注入 {#bootstrap}
 
 ```ts

package/documentation/data-authz.md

@@ -29,6 +29,41 @@ pnpm openxiangda check
 
 角色成员、维度授权和平台管理员由平台管理面维护，不属于应用开发 CLI。
 
+### 授权来源声明
+
+应用可以在 `authz` 中声明四类授权来源，让平台从业务数据投影出维度授权、应用角色成员和
+行级关系授权；投影事实由平台物化并按当前配置重算，应用不维护第二份权限状态。各声明的
+`userIdField` 等字段路径支持 `field`、`field.value` 和 `field.snapshot.<子字段>` 投影形式。
+
+- `scopeDimensions`：`{ code, name, resourceCode?, valueType?: 'string'|'uuid',
+  hierarchyMode?: 'flat'|'self_parent', valueSource?: { kind: 'native_resource',
+  resourceCode, labelField, enabledField? } }`。定义数据范围的取值域；`valueSource` 把
+  Native 资源绑定取值来源，选择器只展示平台按当前 membership 与 create/update 闭包返回的
+  值；`self_parent` 表示取值记录通过父引用形成层级。
+- `scopeSources`：`{ code, name, resourceCode, subject, grants, operationField?,
+  enabledField?, effectiveFromField?, effectiveToField?, failureMode }`。从业务资源行投影
+  维度授权：`subject` 为 `{ type: 'user', userIdField }` 或
+  `{ type: 'role_membership', userIdField, roleCode }`，`grants: [{ dimensionCode,
+  valueField, parentValueField? }]` 把行字段值授为对应维度；生效窗口和启用开关由字段控制；
+  `failureMode: 'strict'` 投影失败即判定失败，`'last_known_good'` 在源数据暂不可读时沿用
+  最近一次成功投影。
+- `roleMembershipSources`：`{ code, name, resourceCode, userIdField, roleCode,
+  enabledField?, effectiveFromField?, effectiveToField?, failureMode: 'strict' }`。从业务
+  数据行授予应用角色，例如"成员表"一行代表某人拥有某角色。
+- `relationshipGrantSources`：`{ code, name, resourceCode, subject, relationCode,
+  targetResourceCode, resourceIdField, operations, enabledField?, effectiveFromField?,
+  effectiveToField?, failureMode: 'strict' }`。通过业务关系授予目标资源上指定操作
+  （1–20 个）的行级授权，例如"订单负责人可更新该订单"。
+
+`authorizationTransitions: [{ fromAuthzDigest, removeRoleCodes?,
+removeCapabilityCodes?, reason }]` 记录授权合同的关键收缩：从 `fromAuthzDigest`
+（64 位十六进制）标识的授权版本移除角色或能力时，必须逐条声明并给出原因，平台在两个授权
+修订之间核对覆盖情况后才放行发布；它不用于新增授权。
+
+`authz.capabilities` 的完整形状是 `{ code, kind: 'backend' | 'ui', name, description? }`；
+`kind: 'ui'` 声明页面级能力，`kind: 'backend'` 声明后端操作能力并配合
+[按需后端](./backend.md)的 `platformAccess` 使用。
+
 自定义 PC/移动页面需要维护当前应用角色时，使用
 `openxiangda/core` 的 `loadRoleManagementCatalog`、
 `listRoleMemberships`、`searchRoleManagementUsers`、成员 mutation 与

package/documentation/declarations-cheatsheet.md

@@ -41,6 +41,10 @@
 | workflow definition 必须显式 `launch`（编译器强制） | `definitions: [{ version: 1, definition, launch: { mode: 'standalone' } }]` |
 | option/user/department/resource-ref/cascade 字段投影进工作流事实是 { label, value } 对象，不能声明为标量；条件比较用 `<fact>.value` | `inputSchema.properties.urgency = { type: 'object', ... }` + `path: 'urgency.value'` |
 | `cascade.*` 的写入/比较值形状是**数组路径** | `category: [{ label: '办公设备', value: 'office' }]` |
+| 行级策略按**角色并集取最宽**：多角色身份的可见行 = 各角色可见行的并集；基线角色与限制性规则并存时，限制会被宽松规则覆盖（平台语义，不是缺陷） | 给某角色做行级收窄前，先确认其角色并集里没有更宽的 unrestricted 角色 |
+| `matchMode: 'AND'` 且多条规则面向**不同角色**时，非目标角色规则恒 false → 全拒（编译器会警告） | 多角色白名单用 `matchMode: 'OR'`；单条规则用 AND/OR 等价 |
+| `created_by`/`updated_by` 审计列支持 `current_user` 行规则（"只看自己创建"）；运行时 WITH CHECK 正向匹配依赖平台版本，使用前在目标平台实测确认 | `{ subject: 'current_user', field: 'created_by', roleCodes: ['app-user'] }` |
+| 匿名策略 `requiredFields` 比模型必填更严格时编译器**警告**：标准控件不为这些字段生成必填校验，空值提交会被服务端 `REQUIRED_FIELD_MISSING` 拒绝 | 在模型字段上声明 `required: true`，使模型必填与策略对齐 |
 | 平台保留能力（如 `app:<app>:directory:read`）**不能**在 `capabilities` 里重复声明，直接在角色中引用即可 | `const directoryRead = \`app:\${APP_CODE}:directory:read\`` → `roles: [{ code: 'admin', capabilities: [directoryRead] }]` |
 | 资源 CRUD 能力码用 `resourceCapabilityCodes(appCode, resourceCode)` 生成 | `const crud = resourceCapabilityCodes(APP_CODE, 'repair-requests')` → `capabilities: [crud.read, crud.create]` |
 | `authenticatedUserRoleCode` 是平台登录用户的基线角色 | `authz: { authenticatedUserRoleCode: 'app-user', ... }` |
@@ -190,11 +194,13 @@ export default defineOpenXiangdaApp({
       { code: 'app-user', name: '应用用户', capabilities: [requestCrud.read, requestCrud.create] },
       { code: 'admin', name: '管理员', capabilities: [requestCrud.read, requestCrud.create, requestCrud.update, requestCrud.delete] },
     ],
-    scopeDimensions: [], scopeSources: [], dataPolicies: [], authorizationTransitions: [],
+    scopeDimensions: [], scopeSources: [], roleMembershipSources: [], relationshipGrantSources: [], dataPolicies: [], authorizationTransitions: [],
   },
 });
 ```
 
+授权来源声明的字段路径（`userIdField` 等）支持 `field` / `field.value` / `field.snapshot.<子字段>` 三种投影形式；`roleMembershipSources`/`relationshipGrantSources` 只允许 `failureMode: 'strict'`，`scopeSources` 额外允许 `last_known_good`。`authorizationTransitions` 只记录移除（`removeRoleCodes`/`removeCapabilityCodes`）并要求 `fromAuthzDigest` 匹配原授权摘要；新增授权不需要 transition。
+
 `request-items` 不出现在 `crud` 里：子表行随 `requests` 表单的 `subtable` 字段写入（在 `requests.fields` 里补 `{ code: 'items', type: 'subtable', subtable: { resourceCode: 'request-items', foreignKey: 'requestId', orderField: 'sortOrder', maxRows: 20 } }`）。
 
 ## 图片上传的像素上限

package/documentation/design-workflow.md

@@ -1,119 +1,135 @@
-# OpenDesign 设计、原型与实现
+# Agent 原生视觉设计与实现
 
-有界面影响的新应用、页面或改版，默认由 **OpenXiangda 2.0 的 AI 工作流调用原版 OpenDesign CLI、Skill 和 MCP** 完成设计、原型、预览和修正，再在同一工作区交接到享搭实现业务。OpenDesign 客户端是可选预览器，不是用户必须操作的开发入口。享搭只提供安装发现、原生 CLI 透传和 Agent 接入边界；项目、模板、设计系统、插件、导出及更新都由 OpenDesign 管理。纯后端、文字校正等按影响沿用已有设计。
+有界面影响的新应用、页面或改版，由当前 AI Agent 在同一个 OpenXiangda 工作区内完成
+视觉方向、真实页面实现、浏览器走查和修正。按需使用用户指定或当前可用的图片生成能力
+（例如 Image 2.5）输出少量设计参考；不安装或调用独立设计运行时，也不在图片与实现之间
+建立第二个项目状态。纯后端或无视觉影响的文字修正沿用已有设计。
 
-## 原版安装与完整 CLI {#native}
+图片只回答构图、层次、色彩、材质和氛围等视觉问题。AppSpec 继续定义用户、任务、页面、
+字段、权限、状态和验收；真实 React 页面才是最终界面事实。静态图不能证明加载、失败、
+拒绝、校验、提交、未保存输入、键盘、响应式或业务权限已经实现。
 
-从[官方发行页](https://github.com/nexu-io/open-design/releases/latest)安装原版运行时或 CLI。AI 工作流优先通过绝对路径 `OPENXIANGDA_OPENDESIGN_CLI`（也支持 `OD_BIN` 与 `OD_NODE_BIN`）调用原生 CLI；macOS 桌面自动发现 `/Applications/Open Design.app` 或 `~/Applications/Open Design.app` 仅用于可选预览。不要要求用户打开客户端，也不搜索 PATH 中的 `od`，避免调用操作系统的同名命令。当前桌面自动发现已在官方 macOS arm64 0.22.2 验证；其他平台使用显式入口，不声称已完成桌面验证。
+## 先固定设计输入 {#inputs}
 
-```bash
-pnpm openxiangda design open
-pnpm openxiangda design status --json
-pnpm openxiangda design cli --help
-pnpm openxiangda design cli project list
-pnpm openxiangda design cli templates list
-pnpm openxiangda design cli design-systems list
-pnpm openxiangda design cli tools directions --json
-pnpm openxiangda design cli plugin --help
-pnpm openxiangda design cli mcp
-```
-
-`cli` 后面的参数、标准输入、输出、JSON、错误码和取消交给原版；享搭不维护上游命令白名单。查看每条原生命令的 `--help` 再执行当前需要的操作。原版 MCP 可直接接到支持 stdio 的 Agent，启动命令为 `openxiangda design cli mcp`；它与享搭平台 MCP 分别拥有设计项目和平台契约，不合并权限。
-
-AI 通过 CLI/MCP 工作时使用原生 `OD_DAEMON_URL` 或原版自动发现的本地运行时；不需要先执行 `design open`。桌面版 sidecar 只在用户主动预览时使用。原版桌面文件导入等操作可能要求桌面授权上下文；AI 应保留原版错误并停止该步骤，不伪造 token 或改数据库。享搭不会在 npm 安装时下载桌面应用、自动修改 Agent 凭据或开启云付费功能。
+开始界面工作前，从当前 AppSpec、平台契约和用户材料形成一个短设计输入，至少明确：
 
-AI Agent 通过原版 CLI/MCP 使用设计能力；模型和登录由原版及所选提供商管理。用户需要人工查看时才打开客户端。需要原版图像、视频、音频或云服务时按原版配置相应提供商。原生功能按其实际依赖可用，不把所有功能都描述为无需配置。
+- 目标用户、主任务、页面归属以及 PC/移动设备范围；
+- 必须保留的平台 Shell、导航、字段协议、权限和数据来源；
+- 页面信息层次、关键操作，以及空、加载、失败、拒绝、校验、提交中和成功状态；
+- 用户提供的品牌、参考图和素材授权；没有品牌事实时标记为 Agent 推断；
+- 目标视口、可访问性、内容长度、数据量和性能边界；
+- 本轮可以改变、必须保留和明确不做的内容。
 
-## 随包离线参考 {#resources}
+已有有效设计继续沿用。只有视觉方向存在真实取舍时才比较候选；已经确认的意图不重复
+提问。不得凭空补充 KPI、品牌故事、业务统计、角色能力或示例数据来源。
 
-通过 `pnpm openxiangda docs <主题> --section <章节>` 或 MCP `docs_read` 的 topic/section 读取。Skill references 与这些正文同源；以当前项目安装版本为准。以下是携带完整正文的精选方法及依赖，作为离线参考。原版运行时提供完整且可能更新的资源；不要把这张精选表当作原版能力边界。
+## 图片参考 {#image-reference}
 
-| 工作 | opendesign-methods 章节 | 同时读取 design-craft 章节 |
-| --- | --- | --- |
-| 从任务、参考到整体视觉方向 | reference-design-contract、reference-design-contract-2（附属 checklist） | typography、color、anti-ai-slop |
-| 生成可运行页面和交互 | frontend-design | typography、color、anti-ai-slop；有状态 UI 再读 state-coverage、accessibility-baseline |
-| 浏览器走查、修正已有原型及实现 | impeccable-design-polish | typography、color、anti-ai-slop、animation-discipline、accessibility-baseline |
-| 信息层次、密集工作台、表单 | 按当前阶段选择上述方法 | typography-hierarchy、laws-of-ux、form-validation，按实际问题选读 |
+图片生成是可选步骤。需要建立新视觉方向、比较布局或统一多页面风格时，可用 Image 2.5
+等当前 Agent 图片能力生成一至三个关键视图；普通 CRUD、小范围样式修正或已有明确设计时
+直接实现。生成提示应包含真实页面类型、主要内容、设备、密度、组件约束和不应出现的元素，
+不得包含生产秘密、真实个人数据或未经授权的品牌和人物素材。
 
-原文来源、上游提交、适配版本和能力摘要见[原文方法](./opendesign-methods.md)；每个 Craft 都保留完整正文，见[设计 Craft](./design-craft.md)。引用它们时记录实际读取的章节，不能只读本页摘要就宣称用了完整方法。
+只保留实际采用的参考图，并记录实际模型、日期、提示摘要、目标视口和采用/拒绝理由。
+不要逐像素照抄图片中的伪文字、虚构控件或不可能交互。Agent 应从参考图提取可实现的布局、
+排版、颜色、间距和组件关系，再对照真实内容与平台组件修正。图片生成失败、不可用或结果
+不合格时，记录事实并使用现有设计约束、成熟组件和浏览器迭代继续开发，不伪造产物。
 
-## 享搭适配规则 {#adapter}
+## 页面归属与平台边界 {#adapter}
 
-按用户任务、业务材料和实际设备选择整体方向，包括导航形态、布局、层次、密度、字体、色彩、间距、组件与交互状态。已有“标准后台必须默认外观”“后台一律不设计移动”等审美和设备约定不再是限制。设备适用性由真实任务决定；不要机械增加没有用户任务的页面。
+应用结构先于视觉：标准管理后台是默认骨架，必须保留平台 Shell、后台路由、显式菜单、
+资源表单、数据列表、详情/编辑、权限和流程入口。Agent 可以在这些边界内优化布局、视觉和
+交互，但不能用设计图、独立原型、单页 HTML 或 iframe 替代后台。
 
-应用结构先于视觉改版：标准管理后台是默认骨架，必须保留平台 Shell、后台路由、显式菜单、资源表单、数据列表、权限和流程入口。OpenDesign 对后台只做布局、视觉和交互优化，不能用独立原型、单页 HTML 或 iframe 替换后台。用户端 PC 与移动端按真实旅程分别设计，可以完整采用 OpenDesign 的视觉与交互，但通过平台 runtime/Data API 连接后台数据，并保持与后台分离的权限和导航状态。设计交接时分别标记后台、用户端 PC、用户端移动端的页面归属和验收入口。
+用户端 PC 与移动端按真实旅程分别实现，通过平台 runtime/Data API 使用后台数据，并与
+后台保持独立的导航状态。Shell 的路由、当前用户、授权菜单和拒绝事实仍来自平台，不在
+用户端复制。先复用 PC/移动 Field Kit 的输入、校验、上传、只读和权限行为；替换外观或
+专业控件时，证明字段值、未保存输入、拒绝和恢复行为仍正确。
 
-先复用 PC/移动 Field Kit 的输入、校验、上传、只读和权限行为。组件外观、布局及专业控件可据设计优化；换组件时证明字段值、未保存输入、拒绝和恢复行为仍正确。Shell 的路由、当前用户、授权菜单事实继续来自平台；`ui` 提供视觉参数，局部 CSS 可以编排布局，结构扩展应走平台支持的组件接口，不能复制导航状态。
+普通管理与录入保持工作型界面的扫描效率和信息密度。专业交互先评估项目已有依赖与成熟
+组件，图表优先评估 ECharts。营销式大标题、装饰性卡片堆叠、无任务依据的插画、纯氛围
+背景和重复导航不能因为参考图中出现就进入业务应用。
 
-上游模板的桌面/手机预览框、固定侧栏、虚构指标、限定图表库和示例品牌仅服务其示例。原文中的字体/颜色数量、渐变等规则用于评审设计理由，不能压过实际品牌、中文阅读或已确认任务。借鉴参考的可描述特征，不复制品牌素材或凭空声称业务事实。
+## 从参考到真实实现 {#loop}
 
-离线快照中的目录入口不被冒充为完整实现；原版中实际可用的插件、技能及资源通过原生命令和界面发现。遵循原版工作流，不把享搭自己的审美限制强加给它。执行插件、连接器和分享等功能仍需要与用户当前任务相符的授权。
+1. 读取设计输入和相关契约，确定本轮页面、状态、视口与验收动作。
+2. 需要时生成并筛选图片参考，提取可实现的视觉规则；不需要时直接沿用现有设计系统。
+3. 在 `tokens.css` 或应用现有 token 源中定义实际采用的数值，派生 AntD theme 与移动 CSS
+   变量；不要在图片说明、组件和全局偏好中维护多份数值事实。
+4. 直接使用真实 React、平台 Shell、Field Kit 和受支持组件实现页面。原型只有在能降低
+   高风险交互的不确定性时创建，且不得成为另一套长期业务代码。
+5. 在目标尺寸打开真实页面，操作完整关键任务；检查布局、滚动、弹层、键盘、长文本、
+   空、加载、失败、拒绝、校验、提交、恢复和离开保护。浏览器控制台错误必须处理。
+6. 获取实际截图与交互发现，修正代码并重复检查。截图用于比较视觉，不替代操作断言。
+7. 连接平台后，从真实入口按实际角色验证后台与用户端、允许与拒绝路径；只有业务证据
+   通过后才进入部署。组件样例、本地数组和图片参考不能冒充远端业务验收。
 
-## 从设计到真实页面 {#loop}
+现有交互模式作为任务检查依据，见[交互模式](./interaction-patterns.md)；它们允许按当前设计
+改进，不是固定页面皮肤。
 
-1. 从当前 AppSpec 和实际界面识别主任务、目标用户、设备、约束与已有证据。新方向给出有理由的推荐；实际有取舍时最多比较两个方向，已确认意图不重复问。
-2. AI 通过原版 CLI/MCP 创建或复用项目、选择模板/设计系统，提供任务与必要参考；工作目录由当前 OpenXiangda 工作区确定。使用原版工作流形成设计方向，保留上游的项目和资源结构；用户可选打开客户端查看。
-3. 通过原版 Agent、项目和预览做可运行原型，关键任务能从入口走到完成。标明示例数据；覆盖适用的空、加载、失败、拒绝、校验、提交中和成功状态。真实业务请求尚未接入时明确说明。
-4. 使用原版预览、lint、导出和修正能力；在目标尺寸实际打开、点击和键盘操作。证据记录实际 URL/文件、尺寸、操作与发现，没有浏览器证据就写未验证。不能用 AI 评分或勾选表代替画面和操作结果。
-5. 依据已有授权和实际答复记录确认范围，固定设计文档和 assets 摘要。工具检查只证明资料与资源一致，不代表审美通过。
-6. 消费同一设计包接入真实组件、平台数据和权限。对照原型检查布局、字段、弹层、未保存输入、拒绝/返回、键盘与移动任务。验收证据关联本次真实实现；原型成功不能冒充业务验收。
+## AppSpec 设计资源 {#artifacts}
 
-现有交互模式作为任务检查依据，见[交互模式](./interaction-patterns.md)；它们允许按设计改进，不是固定页面皮肤。
-
-## 原版产物交接到 AppSpec {#artifacts}
-
-OpenDesign 项目保留自己的设计文件、清单和数值 token。交接时用原版文件/导出功能复制本轮实际采用的文件及依赖到以下目录，记录原版版本、项目 ID 和导出来源；不要求为了享搭改写上游 manifest 或重复制作原型。大型媒体和完整上游工作目录留在原项目，AppSpec 引用本轮可审阅、自包含的产物。
+只固定本轮实际采用、可审阅且自包含的资源。目录可以按任务裁剪：
 
 ```text
-appspec/design/visual.md              # AppSpec 索引与受影响范围
-appspec/design/system/manifest.json   # 能力来源和应用使用的精确版本
-appspec/design/system/DESIGN.md       # 视觉语义、设计取舍与实现交接
-appspec/design/system/tokens.css      # 数值 token 的唯一可编辑来源
-appspec/design/prototypes/<task>/     # 完整、自包含的原型和依赖
+appspec/design/visual.md                 # 范围、来源、取舍与受影响页面
+appspec/design/references/<task>/        # 实际采用的图片参考及来源说明
+appspec/design/system/DESIGN.md          # 视觉语义与实现交接
+appspec/design/system/tokens.css         # 数值 token 的唯一可编辑来源
+appspec/design/prototypes/<task>/        # 仅在必要时保留的可运行交互原型
 ```
 
-原版已有设计系统清单优先原样保留。没有清单时可以使用下面的享搭来源索引，业务规则引用 AppSpec ID；它是可选交接记录，不是 OpenDesign 要求的格式：
+图片来源可以用工具无关的清单记录；字段只描述实际事实，不要求特定模型或提供商：
 
 ```json
 {
   "schema": "openxiangda.design-system/v1",
-  "capability": { "runtime": "OpenDesign", "version": "实际使用的原版版本", "projectId": "原版项目 ID" },
-  "methods": ["reference-design-contract", "frontend-design", "impeccable-design-polish"],
-  "runtimeVersion": "项目锁定的 openxiangda 精确版本",
+  "sources": [
+    {
+      "kind": "generated-image",
+      "model": "Image 2.5",
+      "path": "../references/request/desktop.png",
+      "viewport": "1440x1024",
+      "promptSummary": "内部事项办理台，紧凑主从布局"
+    }
+  ],
   "tokens": "tokens.css",
-  "design": "DESIGN.md"
+  "design": "DESIGN.md",
+  "status": "reviewed-reference"
 }
 ```
 
-运行时代码按构建步骤从 tokens.css 派生 AntD theme 与移动 CSS 变量，不另写数值表或全局偏好存储。标准应用用 `OpenXiangdaApplication` 的 `ui`；独立组件预览用 `OpenXiangdaUiProvider` 的同名参数。例：
+没有图片参考时省略 `sources` 和 `references`，不要创建占位文件。历史设计包已有其他来源
+字段时仍可读取，不要求为了新流程重写。业务规则引用 AppSpec ID，图片清单不复制权限、
+字段或页面协议。
+
+运行时代码从 `tokens.css` 派生 AntD theme 与移动 CSS 变量。标准应用使用
+`OpenXiangdaApplication` 的 `ui`，独立组件预览使用 `OpenXiangdaUiProvider` 的同名参数：
 
 ```tsx
 const ui = { theme: derivedAntdTheme, className: 'project-design' };
 <OpenXiangdaApplication {...applicationProps} ui={ui} />
 ```
 
-`.project-design` 下的样式只覆盖本应用。移动端使用可继承的 `--oxa-mobile-*` 输入，例如 `--oxa-mobile-color-primary: var(--accent)`；名称对应上游 `--adm-*`，可以放在应用根或 MobileSurface 上。嵌套字段会继承这些设计输入，未配置时保留组件默认值。直接在父级改 --adm-* 会被字段基础样式重新声明，应使用 --oxa-mobile-*。平台 Provider 将 PC 下拉、对话框、消息与通知留在当前应用作用域；移动封装沿用原有本地弹层。使用上下文反馈 API，避免 AntD 静态 API 脱离应用上下文。不要通过 theme 变化给整个应用换 key。若显式设置 AntD cssVar.key，使用与页面 className 不同的名字，避免把根容器布局施加到每个控件上。
+`.project-design` 下的样式只覆盖本应用。移动端使用可继承的 `--oxa-mobile-*` 输入；平台
+Provider 让 PC 下拉、对话框、消息与通知留在当前应用作用域。使用上下文反馈 API，避免
+AntD 静态 API 脱离作用域；不要通过 theme 变化给整个应用换 key，以免清空正在编辑的值。
 
-自定义任务表单可以从 `openxiangda/field-kit` 复用 `ResourceFormContent` 和 `ResourceFormDrawer`，传入受支持的字段定义、当前值、错误与提交回调；Drawer 可用 `title` 表达任务名称。它们只负责呈现，加载、保存和授权仍归现有业务所有者。不要为了改变外观重写字段值协议。
-
-维护仓库包含[可运行事项工作台样例](https://github.com/1377385356/openxiangda/tree/master/scripts/fixtures/design-workbench)，演示同一设计包、PC/移动字段、错误恢复与主题作用域。它是示例，具体设计未获得用户确认，也不代表生产数据或业务验收。复制时固定所用工具版本并更换为实际平台契约。浏览器检查还覆盖 reduced-motion：保留组件所需的动画完成事件，不能简单用全局 animation:none 让弹层停在初始隐藏态。
-
-在 `visual.md` 的 front matter 加入实际资源引用（路径从工作区根开始）：
+在 `visual.md` 的 front matter 中引用实际资源：
 
 ```yaml
 assets:
+  - appspec/design/references/request
   - appspec/design/system
-  - appspec/design/prototypes/request
 ```
 
-目录引用包含所有后代文件；新增、修改、删除任何依赖都会改变评审摘要，嵌套 DESIGN.md 是资源而非第二份 AppSpec 文档。原型自包含，外部参考链接不等于被固定的资源。只引用实际受评任务目录，避免无关原型让局部评审失效。原型使用的本地依赖要一起放在引用目录内；不能依赖临时缓存或目录外文件。
-
-引用拒绝越界、符号链接、空目录和超预算。每次检查最多 128 文件、单文件 2 MiB、总计 8 MiB、16 层目录。大媒体用可控的小型评审产物与来源说明；不要靠删资产声明绕过检查。资源只做摘要，`spec context` 不执行原型。修改后重新检查实际变化和受影响确认，不能只改摘要让旧确认复活。生产晋级核对测试提交中的相同资源。既有纯文字设计仍可读取，采用新原型时补全 assets。
-
-## 上游更新与项目升级 {#updates}
-
-原版运行时使用官方更新器或官方发行版升级；CLI 每次从当前安装读取入口和版本。进行中的设计在 AppSpec 记录实际版本与导出摘要。不要把 npm 包里的离线资料版本当成原版安装版本。下面的每日检查只维护随包离线资料，不替代原版更新器。
+目录引用包含所有后代文件；新增、修改或删除依赖都会改变评审摘要。引用拒绝越界、符号
+链接、空目录和超预算；每次检查最多 128 文件、单文件 2 MiB、总计 8 MiB、16 层目录。
+参考图应压缩为足以评审的尺寸，大型媒体放在受控来源并记录摘要，不靠删除 assets 声明
+绕过检查。`spec context` 只读取资源字节，不执行原型或图片内容。
 
-维护仓库的日常检查比较当前上游提交、选中文件和新增候选方法/模板，输出更新报告；它不改已安装能力或应用设计。固定原文的 hash、craft.requires、本地 checklist/许可和生成专题在仓库检查中一起核对，缺项明确失败。候选更新须评审真实差异，补充依赖与来源，更新适配后用可运行样例验证，再走 Changeset/主线/正式发布流程。
+## 完成标准 {#acceptance}
 
-项目只消费验证过的精确工具版本。升级时按[版本升级](./upgrading.md)刷新 Skill 与 AGENTS，查看设计能力差异；进行中的已确认设计继续使用冻结版本，需要升级时重新评审受影响部分。网络失败或候选不合格保留原版本并报告原因。不要每次生成都临时下载上游 main。
+视觉完成至少同时具备：当前 AppSpec 设计范围、真实实现、目标视口截图、关键交互断言、
+无不可解释的浏览器错误，以及适用的真实角色允许/拒绝证据。图片模型的输出、Agent 自评、
+结构检查或组件样例只能是过程证据，不能单独宣称设计或业务验收通过。

package/documentation/development.md

@@ -20,7 +20,7 @@
 ## 选择平台能力 {#capabilities}
 
 - 普通数据管理：通过 `defineDataModel`、`defineApplicationModule` 和显式 CRUD 视图声明；模型不自动生成菜单或写权限。
-- 界面工作先按[OpenDesign 工作流](./design-workflow.md)形成具体设计；设备范围按真实任务选择。复用平台导航和字段行为，自定义报表/工具使用 admin 页面与显式导航。详见[页面归属](./frontend.md#surface-selection)。
+- 界面工作先按[Agent 原生设计工作流](./design-workflow.md)形成具体视觉并直接实现真实页面；设备范围按真实任务选择。复用平台导航和字段行为，自定义报表/工具使用 admin 页面与显式导航。详见[页面归属](./frontend.md#surface-selection)。
 - 用户页面按实际旅程选择独立 PC/移动布局，手机端只覆盖已确认的用户任务。
 - 图表等专业交互先检查已有依赖，再评估成熟组件或开源库；报表优先评估 ECharts，记录选型理由和加载/销毁边界。详见[组件选型](./frontend.md#component-selection)。
 - 无平台账号的外部表单：使用[匿名公开访问](./public-access.md)，不用普通 RBAC 角色冒充匿名主体。
@@ -38,8 +38,8 @@
 | 列表、筛选、排序、分页接口 | `createNativeResourceClient` 的 `list`，服务端条件树与分页 | [前端数据访问](./frontend.md#data-access) |
 | 新增 / 编辑 / 删除接口 | 标准 CRUD 页面，或同一客户端的 `create` / `update` / `remove`（`expectedRevision` 乐观锁） | [前端数据访问](./frontend.md#data-access) |
 | 提交防重、幂等重试 | `transactNativeData` / 事务请求自带 `idempotencyKey` 幂等回执 | [前端数据访问](./frontend.md#data-access)、[按需后端](./backend.md#business-action) |
-| 时间窗、状态前置、指定人角色校验 | 平台事务守卫：`operation-time`、`record-assert`、`record-exists`、`role-member` | [按需后端](./backend.md#business-action) |
-| 统计报表数据 | Data API 服务端聚合 `batchAggregateNativeResources`（单个指标也用它），前端不拉全量求和 | [前端](./frontend.md#component-selection) |
+| 时间窗、状态前置、指定人角色校验 | 平台事务守卫：`operation-time`、`record-assert`、`record-exists`、`record-match`、`role-member`、`databaseNowAssertion` | [按需后端](./backend.md#business-action) |
+| 统计报表数据 | Data API 服务端聚合 `batchAggregateNativeResources`（单个指标也用它），前端不拉全量求和 | [前端](./frontend.md#data-access) |
 | 导入 / 导出 | 标准 CRUD 的 `import` / `export` 动作声明 | [业务模块](./application-foundation.md) |
 | 跨模型原子写、外部 API、硬件或第三方推送 | Nest 具名 operation + 平台事务，必要时事务内 `emitEvent` | [按需后端](./backend.md) |
 

package/documentation/frontend.md

@@ -14,13 +14,13 @@
 
 ## 先选页面归属，再写布局 {#surface-selection}
 
-管理后台的设备范围按实际办理任务确定。数据管理、录入和报表复用平台 Shell 的路由与菜单事实，视觉依据[OpenDesign 工作流](./design-workflow.md)设计；存在手机办理任务时同步设计与验证。
+管理后台的设备范围按实际办理任务确定。数据管理、录入和报表复用平台 Shell 的路由与菜单事实，视觉依据[Agent 原生设计工作流](./design-workflow.md)实现并在浏览器修正；存在手机办理任务时同步设计与验证。
 
-### 应用骨架优先与 OpenDesign 页面边界
+### 应用骨架优先与视觉页面边界
 
 标准管理后台是每个业务应用的默认开发骨架，必须保留后台 Shell、显式菜单、资源表单、数据列表、详情/编辑、权限和流程入口。开发顺序先完成后台资源与契约，再实现用户端 PC/移动端；不能以用户端首页或设计原型替代后台。
 
-OpenDesign 可以在标准后台内部优化布局、视觉和交互，但后台仍复用平台 Shell、导航、字段行为和权限。用户端 PC 与移动端可以分别采用 OpenDesign 的完整视觉和交互，通过平台 runtime/Data API 使用后台数据。禁止用单页 HTML、iframe 或自定义假后台替换标准后台，也不能把后台权限、导航状态复制到用户端。
+Agent 可以在标准后台内部优化布局、视觉和交互，但后台仍复用平台 Shell、导航、字段行为和权限。用户端 PC 与移动端按真实旅程分别设计，通过平台 runtime/Data API 使用后台数据。图片参考和原型不拥有业务事实；禁止用图片、单页 HTML、iframe 或自定义假后台替换标准后台，也不能把后台权限、导航状态复制到用户端。
 
 发布前分别验证后台入口、表单、数据列表、流程入口和用户端 PC/移动端入口；没有完成后台骨架的应用不得发布。
 
@@ -365,7 +365,14 @@ renderer，但共享同一授权与命令生命周期。主决策操作固定在
 
 资源用 `mutationOwner: 'native' | 'action' | 'readonly' | 'workflow'` 声明 mutation owner，
 并可用 `generated.list/detail/create/update/delete` 精确选择标准 surface。非 Native owner
-不能生成或向应用角色授予 Native mutation；零可写业务字段不能开放 create/update。
+不能生成或向应用角色授予 Native mutation；零可写业务字段不能开放 create/update。运行时直接对
+非 Native owner 资源调用 Data API create/update/delete 会被平台以 409
+`OPENXIANGDA_NATIVE_DATA_CAPABILITY_MISSING` 拒绝——这不是权限配置错误，而是 mutation owner
+契约：`readonly` 资源只能读，`action` 资源的写入走 named operation，`workflow` 资源由流程命令推进。
+`workflow` 资源的数据修正不绕过流程：平台为应用超级管理员提供专门的 correction 入口（记录的
+correction-surface/corrections），保留审批快照；非 workflow 资源走该入口返回 409
+`WORKFLOW_OWNER_REQUIRED`，修正失败错误码为 `OPENXIANGDA_WORKFLOW_CORRECTION_<reason>` 族。
+排查这两类错误先核对资源的 `mutationOwner` 声明和期望的写入通道，不要试图用扩角色绕过。
 Workflow definition 用 `launch.mode` 声明 `standalone`、`custom-page`、`hidden-handoff` 或
 `work-center-only`；只有 `standalone` 可进入菜单，`hidden-handoff` 保留同一标准 PC/移动路由
 但不进菜单。缺省 submission 使用 compiler 生成的标准 process operation。action-owned 资源

package/documentation/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.20.4 skill install --force
-pnpm dlx openxiangda@2.20.4 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.20.4 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.20.4 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.21.1 skill install --force
+pnpm dlx openxiangda@2.21.1 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.21.1 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.21.1 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -79,7 +79,7 @@ pnpm openxiangda dev
 
 将两处示例平台地址替换为同一个目标地址。`create` 先核对目标与当前登录平台，再创建本地目录、安装依赖并初始化远端应用；新应用不会自动沿用文件中最后登录的站点。CI 使用原有成对的 `OPENXIANGDA_BASE_URL` 和 `OPENXIANGDA_TOKEN` 时，可以由该显式地址指定目标。
 
-初始化中断后重试同一命令；已有目录会核对原平台绑定，不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台，不修改 link 文件绕过检查，也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
+初始化中断后重试同一命令；已有目录会核对原平台绑定，不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台；确需把工作区切换到其他站点时，使用 `openxiangda link rebind --base-url <新平台>` 显式换绑（见[跨站点与换绑](#cross-site)），不手改 link 文件绕过检查，也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
 
 进入项目后使用 `pnpm openxiangda`，由项目依赖和锁文件决定版本。查看使用资料运行 `pnpm openxiangda docs`；查看单一主题运行 `pnpm openxiangda docs frontend`。安装到其他 AI 工具时使用 `skill install --destination <Skill根目录>`。
 
@@ -145,6 +145,7 @@ pnpm openxiangda source push -m "完成本轮应用开发"
 | --- | --- |
 | 新应用 | 正常执行 `create`，平台启用后自动建仓、配置凭据和首次推送 |
 | 已有项目首次交接给另一个 AI | 先读 `context --json` 和 `source status`，沿用项目绑定与版本 |
+| 交接给另一位开发者 | 平台管理员先把对方加为该应用的应用管理员；对方执行 `source clone <仓库URL> <新目录> --base-url <平台>`，克隆后在同目录 `login --base-url <平台>` 继续开发 |
 | 换电脑或初始化中断 | 在应用目录执行 `pnpm openxiangda source setup`；已有提交及未提交修改会保留 |
 | 从个人远端迁入 | 明确迁入后运行 `source setup --import`，原远端保留为 `external-source` |
 | 本轮修改完成 | 检查差异后运行 `source push -m "AppSpec: <本轮变更ID> 变更说明"`；多个任务共享目录时先精确提交本轮文件，再不带 `-m` 推送 |
@@ -173,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.20.4 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.20.4 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.20.4 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.21.1 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.21.1 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.21.1 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回
@@ -200,6 +201,32 @@ pnpm dlx openxiangda@2.20.4 source clone <仓库URL> <新目录> --base-url <平
 使用 CLI 时无需自行调用凭据 API；支持工具不得记录其响应或另建身份体系。
 未登记的外部仓库先在原工作区执行 `source setup --import`，再使用平台返回的仓库 URL。
 
+## 跨站点与平台换绑 {#cross-site}
+
+源码仓库、应用与数据都归属各自站点：A 站点的平台只认 A 站点登记的仓库绑定，
+发布校验要求当前工作区 `origin` 与该站点绑定仓库一致。站点之间流动的是代码（git），
+应用的数据库数据、发布历史与环境配置不会自动迁移。
+
+```bash
+openxiangda link                       # 查看当前绑定、登录态匹配与 origin 归属
+openxiangda link rebind --base-url https://platform-b.example.com   # 显式换绑
+```
+
+一个工作区同一时间只绑定一个平台；换绑只改写 `.openxiangda/link.json`
+（清空旧站点环境列表），不修改 git remote、不迁移登录凭据，也不在远端产生变更。
+换绑后必须重新登录，`create` 会在新平台幂等初始化同 code 应用。
+
+| 场景 | 执行方式 |
+| --- | --- |
+| 在 A 开发、也要发布到 B | 在 B 站点创建同 code 应用并由其管理员启用源码；`source clone <B仓库URL> <B目录> --base-url <B平台>` 得到第二个检出；同步代码用 `git remote add external-source <A仓库URL>` 后 fetch/merge，再 `source push`；在 B 目录执行 `deploy` |
+| 后续发布永久切换到 B | 在原目录依次执行 `link rebind --base-url <B平台>` → `login --base-url <B平台>` → `create <目录> --base-url <B平台>`（幂等初始化）→ `source status` 核对 origin；如报告 `APPLICATION_SOURCE_ORIGIN_CONFLICT`，用 `source setup --import` 把 origin 切到 B 仓库（原 origin 保留为 `external-source`） |
+| 换绑后想回退 | `link rebind --base-url <原平台>` 即恢复；link.json 随仓库提交时也可用 git 还原该文件 |
+| 换绑对象不是同一应用 | 拒绝执行（`OPENXIANGDA_LINK_APP_CODE_CONFLICT`）；请在对应应用的目录操作 |
+
+换绑命令对地址做与 `login` 相同的归一化校验；地址拼错时失败会在下一步登录或
+幂等初始化处暴露，随时可以再次 rebind 修正。详细决策记录见仓库
+`docs/architecture-decisions/workspace-platform-rebind.md`。
+
 ## 检查与交付 {#delivery}
 
 只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。
@@ -220,8 +247,13 @@ pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
 
 ## 工作区登录态
 
-平台授权保存到所选工作区的 `.openxiangda/session.json`，CLI、MCP、刷新与退出共用该文件。不再读取或迁移旧全局会话；升级后需在每个项目重新登录。已有项目可在根目录或子目录运行 `openxiangda login --base-url <platform>`；`login --cwd <directory>` 和 `auth --cwd <directory>` 明确选定工作区。嵌套应用不会继承父应用会话。
+平台授权保存到所选工作区的 `.openxiangda/session.json`，CLI、MCP、刷新与退出共用该文件。不再读取或迁移旧全局会话；升级后需在每个项目重新登录。已有项目可在根目录或子目录运行 `openxiangda login --base-url <platform>`；`login --cwd <directory>` 和 `auth status --cwd <directory>` 明确选定工作区。首次 `create` 目标目录尚无会话时，按工作区发现规则向上继承父目录会话，并在 `.git` 仓库边界停止，不跨仓借用账号。
 
 创建应用前先执行 `openxiangda login --cwd my-app --base-url <platform>`，再执行 `openxiangda create my-app --base-url <platform>`。仅含受管登录文件的目录允许初始化，凭据会保留并自动加入 Git 忽略规则。
 
 本地文件优先；仅在文件缺失时使用成对的 `OPENXIANGDA_BASE_URL` 与 `OPENXIANGDA_TOKEN` CI 环境凭据。损坏、过期或平台不符的文件不会触发其他身份回退。请勿提交或打包登录文件。钉钉支持由 DWS 管理自己的授权，不与平台会话混用。
+
+查看当前绑定与登录态匹配情况运行 `openxiangda link`；登录地址与绑定平台不一致时
+`login` 会拒绝执行（`OPENXIANGDA_PLATFORM_SESSION_MISMATCH`），防止凭据跨平台发送。
+需要切换站点时先运行 `openxiangda link rebind --base-url <新平台>`，再登录，见
+[跨站点与平台换绑](#cross-site)。