openxiangda 2.20.4 → 2.21.1

package/releases/2.8.1.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.8.1",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.8.1：修复审计权限能力引用",
+  "summary": "审计读取策略正确复用已有能力，保留原能力定义，并拒绝缺失引用。",
+  "newFeatures": [],
+  "fixes": [
+    "修复 audit.read 引用已有管理能力时错误报告 catalog owner 冲突的问题。",
+    "本地与平台编译器一致地保留能力原定义；审计策略不再自动补建未声明能力，跨资源引用不依赖资源排序。"
+  ],
+  "affectedUsers": [
+    "使用 audit.read 能力数组控制审计信息的应用开发者。"
+  ],
+  "upgradeSteps": [
+    "平台采用 openxiangda-contracts 2.6.1 后，应用升级到 openxiangda 2.8.1 并重新生成和检查。",
+    "audit.read 引用现有应用能力；独立审计能力须先在 authz.capabilities 声明并按需授予角色。"
+  ],
+  "knownLimitations": [
+    "省略 audit 保留原有读取行为，能力数组保持 all-of 与同一角色成员字段和行授权规则。",
+    "受限应用启用后仍须保留支持 data.audit-read-access 的兼容平台组合。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "openxiangda-contracts 2.6.1 与 data.audit-read-access 1.0.0"
+  },
+  "issues": [],
+  "sha256": "354f1883a5cbd7d5bcf32d94fbabbb4ec362df5abecec99ed78e2d687dff94b7",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.8.1"
+}

package/releases/2.9.0.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.9.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.9.0：声明标准列表导入导出入口",
+  "summary": "应用可按默认或命名视图配置标准列表的导入、导出任务，PC 与移动端使用相同声明。",
+  "newFeatures": [
+    "crud[].list.actions 支持 import 与 export 布尔开关，直接资源声明同样支持。",
+    "关闭导入适用于原生与流程列表；关闭导出同时覆盖 PC 和移动列表。"
+  ],
+  "fixes": [
+    "应用可通过公开配置移除首发范围之外的列表任务，无需修改共享组件或使用 CSS 隐藏。"
+  ],
+  "affectedUsers": [
+    "使用标准 CRUD 默认或命名视图，需要控制导入导出入口的 V2 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "平台采用 openxiangda-contracts 2.7.0，应用采用 openxiangda 2.9.0 后重新生成和检查。",
+    "在目标视图的 list.actions 中将不需要的入口设为 false，再部署测试候选并验证 PC/移动页面。"
+  ],
+  "knownLimitations": [
+    "省略开关保持既有行为；true 不授予权限，也不改变原生、流程或只读写入归属。",
+    "这是页面入口配置，Data API 和敏感字段仍按原有授权规则执行。",
+    "命名视图各自声明开关，不继承默认视图的任务选择；无需新增数据库迁移。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "openxiangda-contracts 2.7.0"
+  },
+  "issues": [],
+  "sha256": "c9d413f52c85a7ca1ee5e113ca72d9284efd303b3a99dc8ba71ae35cf7526783",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.9.0"
+}

package/releases/2.9.1.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.9.1",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.9.1：保留显式查询操作数与路径",
+  "summary": "修复标准客户端将成员包含查询的单值改成数组，导致合法查询返回400的问题。",
+  "newFeatures": [],
+  "fixes": [
+    "has操作保持单个稳定标识；in、between、hasAny、hasAll保留数组全部值，不再复用快捷筛选推断操作数形状。",
+    "显式查询path保持原值路径；单项快照和级联控件选择仍转为稳定查询值。",
+    "列表、批量列表和导出使用相同修正，应用无需修改正确的DataWhere条件。"
+  ],
+  "affectedUsers": [
+    "使用openxiangda/core显式where成员筛选、数组操作或子值路径查询的V2应用。"
+  ],
+  "upgradeSteps": [
+    "将应用的公开openxiangda依赖升级到2.9.1，重新检查并发布测试候选。",
+    "复测参与人归属、数组区间筛选及导出；生产晋级复用验收通过的原测试制品。"
+  ],
+  "knownLimitations": [
+    "快捷filters的既有界面语义不变；字段类型、行权限与查询边界仍由平台Data API验证。",
+    "本补丁不改变业务数据、权限或数据库结构；新增CRUD列表开关仍需平台采用contracts2.7.0。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "openxiangda-contracts 2.7.0"
+  },
+  "issues": [],
+  "sha256": "2cfb20fed9921fc7281f36970f9ba534192fe0eacafb55223e3031587b27f6c7",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.9.1"
+}

package/releases/2.9.2.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.9.2",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.9.2：查询操作数修正与模板版本联动",
+  "summary": "修复标准客户端将成员包含查询的单值改成数组导致400的问题，并补齐根包和CLI模板的发布版本联动。",
+  "newFeatures": [],
+  "fixes": [
+    "has操作保持单个稳定标识；in、between、hasAny、hasAll保留数组全部值，不再复用快捷筛选推断操作数形状。",
+    "显式查询path保持原值路径；单项快照和级联控件选择仍转为稳定查询值。",
+    "列表、批量列表和导出使用相同修正，应用无需修改正确的DataWhere条件。",
+    "发布版本规划在写入版本前拒绝缺少CLI配套Changeset的根包升级，避免模板变更到不可变包检查阶段才被发现。"
+  ],
+  "affectedUsers": [
+    "使用openxiangda/core显式where成员筛选、数组操作或子值路径查询的V2应用。"
+  ],
+  "upgradeSteps": [
+    "将应用的公开openxiangda依赖升级到2.9.2，重新检查并发布测试候选。",
+    "复测参与人归属、数组区间筛选及导出；生产晋级复用验收通过的原测试制品。"
+  ],
+  "knownLimitations": [
+    "快捷filters的既有界面语义不变；字段类型、行权限与查询边界仍由平台Data API验证。",
+    "本补丁不改变业务数据、权限或数据库结构；新增CRUD列表开关仍需平台采用contracts2.7.0。",
+    "2.9.1仅为被发布门禁拦截的未发布候选；其查询修正随2.9.2正式交付。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "openxiangda-contracts 2.7.0"
+  },
+  "issues": [],
+  "sha256": "9989af7b2e2b9e5eaf81bf19b1307366a35b07522082b384918882f8db05d61c",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.9.2"
+}

package/releases/2.9.3.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.9.3",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.9.3：明确记录用户授权的性能延期",
+  "summary": "修复功能验收完成但用户已延期性能时无法正式晋级的问题，保留原测量并明确区分性能通过与延期。",
+  "newFeatures": [],
+  "fixes": [
+    "AppSpec验收报告支持有授权人、实际时间、来源、证据及后续安排的performanceDeferral。",
+    "延期时保留真实超标测量，返回deferred与overBudget统计，生产阶段明确显示性能未通过。",
+    "没有授权延期时仍要求性能测量达标；延期不豁免功能AC、证据、原测试版本和制品绑定。"
+  ],
+  "affectedUsers": [
+    "已由用户明确延期性能验收、需要按实际范围完成V2功能交付的应用开发者。"
+  ],
+  "upgradeSteps": [
+    "更新项目的openxiangda依赖至2.9.3并刷新项目技能；已有测试制品可以沿用，不因验收工具升级而重建。",
+    "依据实际用户决定填写延期记录，保留成功与失败测量；正式spec verify后提交推送报告，用原TEST运行晋级。"
+  ],
+  "knownLimitations": [
+    "结构验证不证明授权或证据内容真实；不得制造用户确认、提高阈值或仅保留成功样本。",
+    "本次仅修复开发交付记录契约，不修复性能，也不修改平台后端、业务数据或运行时权限。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "沿用openxiangda-contracts 2.7.0，无新增平台能力要求"
+  },
+  "issues": [],
+  "sha256": "aea11cf79206afaae7d6a98eb72506bd71f13752ca6178e459d5395cde4b10a8",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.9.3"
+}

package/releases/2.9.4.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.9.4",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.9.4：DingTalk OA 工作通知 SDK",
+  "summary": "应用通过平台托管的 Notification Hub 发送文本或 Markdown 钉钉 OA 工作通知，并查询投递结果。",
+  "newFeatures": [
+    "Nest SDK 增加 sendDingTalkWorkNotice 和 getDingTalkWorkNoticeResult。",
+    "工作通知支持按 Native 用户、部门或全员发送，平台负责渠道凭据、Native 标识映射、幂等、投递和审计。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "需要从 OpenXiangda 2.0 应用发送钉钉文本或 Markdown 工作通知的开发者。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": [
+      "v1",
+      "v2"
+    ],
+    "v1Policy": "V1 引擎和已有应用不变。",
+    "platformPolicy": "需要部署包含 Notification Hub DingTalk OA 工作通知接口的匹配平台组合，并配置已启用的 OA 渠道。",
+    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
+  },
+  "upgradeSteps": [
+    "平台先部署匹配的 Notification Hub 服务并确认 DingTalk OA 渠道和 Secret 引用可用。",
+    "将应用的 openxiangda 依赖升级到 2.9.4，更新锁文件并通过标准检查。",
+    "在测试环境验证用户、部门和全员目标的发送回执，再使用同一候选晋级生产。"
+  ],
+  "knownLimitations": [
+    "首版内容类型为 text 和 markdown；钉钉最终接收结果仍以平台投递记录和钉钉响应为准。",
+    "发布包、平台部署和真实业务角色验收分别验证；本版本不自动配置渠道 Secret。"
+  ],
+  "issues": [],
+  "sha256": "6383173f0e6bd4596286e95453fd651d07eb8d91948e829dcd1fe3dfbab1f485",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.9.4"
+}

package/skills/manifest.json

@@ -3,8 +3,8 @@
   "skills": [
     {
       "name": "openxiangda-v2",
-      "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由 AI 在工作区内调用 OpenDesign 原版 CLI/Skill/MCP 形成整体视觉与可运行原型，再开发、检查和交付应用。OpenDesign 客户端只作为可选预览器；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "01cad9ea9d2ffff598fc6f213a180dfea95b790e577df6ba6b131d87d0076434"
+      "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
+      "sha256": "da8d59598a9fbd9217f7df8e730e9dafa32716144676b29d669c8022bef4070b"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openxiangda-v2
-description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由 AI 在工作区内调用 OpenDesign 原版 CLI/Skill/MCP 形成整体视觉与可运行原型，再开发、检查和交付应用。OpenDesign 客户端只作为可选预览器；维护 1.x 应用时使用对应的 1.x 技能。
+description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。
 ---
 
 # OpenXiangda 2.0
@@ -9,7 +9,7 @@ description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具
 
 每个业务应用默认先建立并保留标准管理后台。管理后台是应用骨架，承载资源模型、表单、数据列表、详情/编辑、权限和流程入口；AI 必须先从后台完成数据与契约，再实现用户端体验。不得因为制作用户端首页而删除、隐藏或替换后台 Shell、后台路由或显式菜单。
 
-OpenDesign 按页面归属使用：后台页面可以用 OpenDesign 优化布局、视觉和交互，但必须复用平台后台 Shell、导航、字段行为和权限；用户端 PC 与移动端可以分别使用 OpenDesign 的完整视觉和交互，并通过平台 runtime/Data API 读取后台数据。不得用单页 HTML、iframe 或独立假后台冒充管理后台，也不得在用户端复制后台权限和导航状态。
+Agent 按页面归属优化布局、视觉和交互：后台必须复用平台 Shell、导航、字段行为和权限；用户端 PC 与移动端按真实任务分别设计，并通过平台 runtime/Data API 读取后台数据。图片参考不定义交互、权限或验收。不得用图片、单页 HTML、iframe 或独立假后台冒充管理后台，也不得在用户端复制后台权限和导航状态。
 
 设计、实现和发布验收必须分别核验管理后台入口、表单、数据列表、流程入口，以及用户端 PC/移动端入口。缺少标准管理后台的应用结构不完整，不能发布。
 
@@ -21,29 +21,29 @@ OpenDesign 按页面归属使用：后台页面可以用 OpenDesign 优化布局
 
 遇到已有 V1 项目时，先核实 V2 能力覆盖、项目是否仍在测试阶段和迁移成本；能力满足、仍在测试阶段且代价可控时，优先建议转用 V2。先做只读评估，再按项目确认详细设计、数据/流程映射、测试和回滚；迁移实施前的原项目维护仍使用匹配的 V1 引擎。
 
-有界面影响的开发和改版默认读[OpenDesign 工作流](references/design-workflow.md)，由 AI 在当前 OpenXiangda 工作区读取相关 Skill，并通过 `openxiangda design cli` 或原版 stdio MCP 自动完成设计方向、原型、lint、修正和产物交接；不要求用户打开或操作 OpenDesign 客户端。客户端只用于用户主动查看或人工预览。随包方法仅作离线参考，保留字段与权限行为，旧默认皮肤或设备偏好可按任务重新设计。设计与原型资源使用 AppSpec assets 固定；不把结构检查或示例数据当成实际验收。
+有界面影响的开发和改版默认读[Agent 原生设计工作流](references/design-workflow.md)，由当前 AI 在同一个 OpenXiangda 工作区确定视觉方向、直接实现真实页面并在浏览器修正。需要建立新方向时，按需使用用户指定或当前可用的图片生成能力（例如 Image 2.5）形成少量参考；图片不可用或质量不足时直接使用设计约束、成熟组件和浏览器迭代继续开发。保留字段与权限行为，旧默认皮肤或设备偏好可按任务重新设计。实际采用的参考图、token 和必要原型使用 AppSpec assets 固定；不把图片、结构检查或示例数据当成实际验收。
 
 ## AI 自动设计与开发
 
-AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作区内执行以下闭环，不把设计任务转交给用户操作客户端：
+AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作区内执行以下闭环，不建立第二个设计项目或把实现转交给用户：
 
-1. 读取本 Skill、`references/design-workflow.md` 和任务相关的 OpenDesign Skill；从当前 AppSpec、平台契约和用户材料确定页面、角色、设备与验收目标。
-2. 用 `openxiangda design cli` 查询原版方向、模板、设计系统和插件；需要持续会话时启动 `openxiangda design cli mcp`，把原版设计工具接入当前 AI Agent。所有 CLI 参数、JSON、标准输入输出和取消都由原版处理。
-3. 在任务工作区创建或复用原版项目，向原版 Agent 提交任务上下文，生成可运行原型；AI 自己读取文件、运行 lint/预览检查并按结果修正。
-4. 将本轮实际采用的设计文件、token、原型和来源版本复制或导出到 `appspec/design`，然后继续生成 OpenXiangda 页面、字段和业务实现。设计产物与应用源码属于同一变更链，不要求用户在客户端中搬运文件。
-5. 运行本项目的 check、浏览器和真实角色验收；只有实际证据通过后才进入部署流程。原型、示例数据或客户端截图不能替代业务验收。
+1. 读取本 Skill 和 `references/design-workflow.md`，从当前 AppSpec、平台契约和用户材料确定页面、角色、设备、状态与验收目标。
+2. 已有设计足够时直接沿用；需要新视觉方向时，用 Image 2.5 等当前图片能力生成一至三个关键视图，筛选后只固定实际采用的参考。图片中不得包含秘密、真实个人数据或未授权素材。
+3. 从参考和产品约束提取布局、排版、颜色、间距与组件关系，直接使用真实 React、平台 Shell、Field Kit 和受支持组件实现；不逐像素照抄伪文字、虚构控件或图片中的错误交互。
+4. 在目标视口打开真实页面，操作空、加载、失败、拒绝、校验、提交、恢复、未保存输入、键盘与响应式路径，依据截图和交互发现修正代码。图片和 Agent 自评不能替代浏览器断言。
+5. 将本轮实际采用的参考图、设计说明、token 和必要原型记录到 `appspec/design`，运行本项目的 check、浏览器和真实角色验收；只有实际证据通过后才进入部署流程。
 
-如果原版 CLI 或 MCP 不可用，保留真实错误并停止依赖原版的设计步骤；可以继续不依赖设计运行时的只读分析，但不能伪造设计产物或把离线参考当成原版执行结果。
+图片能力不可用、失败或结果不合格时，记录事实并继续直接实现和浏览器迭代；不能伪造设计产物或通过结果。静态图不拥有应用结构、交互、权限、数据或验收事实。
 
 ## 定位当前版本
 
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.20.4 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.20.4 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.20.4 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.20.4 skill install --force
+pnpm dlx openxiangda@2.21.1 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.21.1 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.21.1 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.21.1 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
@@ -61,7 +61,7 @@ pnpm dlx openxiangda@2.20.4 skill install --force
 | 安装、登录、创建、连接开发 | [开始开发](references/getting-started.md) |
 | 源码仓库、换电脑、旧项目导入、提交推送与重试 | [应用源码](references/getting-started.md#应用源码)；先用 `source status` 读取实际绑定 |
 | 模糊想法、模块发现、PRD、权限与架构设计 | [产品设计](references/product-design.md)、[交互模式](references/interaction-patterns.md) |
-| 界面设计、改版、原型和视觉修正 | 先读[设计工作流](references/design-workflow.md)，使用 `openxiangda design open` 和 `design cli` 调用原版；[离线方法](references/opendesign-methods.md)与[设计 Craft](references/design-craft.md)仅作补充 |
+| 界面设计、改版、原型和视觉修正 | 先读[Agent 原生设计工作流](references/design-workflow.md)，按需用 Image 2.5 等当前图片能力生成参考，直接实现真实页面并完成浏览器闭环 |
 | 理解需求与选择能力 | [开发流程](references/development.md)、[架构](references/concepts.md) |
 | 写 openxiangda.config.ts 声明、避免首轮校验返工 | [声明速查](references/declarations-cheatsheet.md)；先扫规则表再动手 |
 | 模型、CRUD、字段与移动表单 | [业务模块](references/application-foundation.md)、[字段](references/field-components.md) |

package/skills/openxiangda-v2/references/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/skills/openxiangda-v2/references/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 参考](mcp.md)）
+是两组互不重叠的工具。
+
 ## 启动与依赖注入 {#bootstrap}
 
 ```ts

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

@@ -7,7 +7,6 @@
 | `pnpm openxiangda auth` | 只读 | 只读核验指定平台授权，不登录或刷新会话 |
 | `pnpm openxiangda context` | 只读 | 只读查看工作区、版本与平台绑定 |
 | `pnpm openxiangda docs` | 只读 | 按主题和章节读取当前版本中文资料 |
-| `pnpm openxiangda design` | 远端变更 | 打开 OpenDesign 原版并透传完整原生 CLI；写入范围由原生命令决定 |
 | `pnpm openxiangda admin` | 只读 | 只读查看应用管理能力和流程节点运行配置 |
 | `pnpm openxiangda create` | 远端变更 | 创建、绑定并初始化应用 |
 | `pnpm openxiangda source` | 远端变更 | 配置应用源码仓库、查看状态或提交推送 |
@@ -23,7 +22,10 @@
 | `pnpm openxiangda stop` | 远端变更 | 将应用环境缩容为零并保留数据 |
 | `pnpm openxiangda rollback` | 远端变更 | 回滚测试或生产环境 |
 | `pnpm openxiangda login` | 本地写入 | 通过平台浏览器授权登录 |
+| `pnpm openxiangda link` | 本地写入 | 查看平台绑定或显式换绑到其他站点 |
 | `pnpm openxiangda skill` | 本地写入 | 安装当前版本的 AI Skill |
 | `pnpm openxiangda spec` | 本地写入 | 维护需求、设计、变更与业务验收记录 |
 
 只验证时运行 check；部署测试环境时直接运行 deploy，它已包含检查、测试和构建。生产使用 deploy --environment production --from <测试运行ID>；加 --dry-run 只读预览。登录、创建和长期 dev 进程由 CLI 管理。
+
+上表为项目工作区的 Devkit 命令。统一入口在转发给引擎之前还自带 `version`、`update check|install`、`changelog`、`migrate assess` 和 `support status|bootstrap|login|join`，分别用于版本诊断、工具链升级、变更日志、V1 项目迁移评估和支持通道授权；它们不属于 Devkit 注册表，用法与示例见「开始开发」主题（getting-started）。

package/skills/openxiangda-v2/references/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/skills/openxiangda-v2/references/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 } }`）。
 
 ## 图片上传的像素上限