openxiangda-skill-kit 2.3.100 → 2.3.104

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.3.100",
+  "version": "2.3.104",
   "description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.59.0"
+    "openxiangda-devkit-core": "2.62.0"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "60a733b398ea69f6b8b8d15f8514d19a448437268706d4ef19ba3b811bcb60a9"
+      "sha256": "e00b24cc4f96f51fb29881ff652bea3db2966428a48bd8b60afb99bf845f621c"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -7,11 +7,11 @@ description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具
 
 ## 应用结构基线（必须遵守）
 
-每个业务应用默认先建立并保留标准管理后台。管理后台是应用骨架，承载资源模型、表单、数据列表、详情/编辑、权限和流程入口；AI 必须先从后台完成数据与契约，再实现用户端体验。默认提供标准 Shell；需要定制后台外观时使用 `ui.admin.shell` 或局部插槽，保留平台后台路由、授权和显式业务菜单。
+有管理任务时选择后台源码模板；PC 用户端、移动用户端和登录外观分别选择布局与风格。先读取 [源码模板与业务场景](references/application-templates.md) 或 template list / MCP template_list，结合已确认业务选择初始化模块。已获开发与创建授权时直接执行，模板选择不增加确认步骤。
 
-Agent 按页面归属优化布局、视觉和交互：后台通过默认 Shell 或 `ui.admin` 扩展复用平台导航事实、字段行为和权限；用户端 PC 与移动端按真实任务分别设计，并通过平台 runtime/Data API 读取后台数据。图片参考不定义交互、权限或验收。不得用图片、单页 HTML、iframe 或独立假后台冒充管理后台，也不得在用户端复制后台权限和导航状态。
+应用拥有外壳与页面源码，可修改、替换或重构。通过 ui.admin.shell 保持唯一后台，通过 resourcePages 贡献替换资源页面，从 openxiangda/resource 组合列表块与控制器。平台继续拥有路由、身份、授权、数据和登录行为；不复制这些权威。既有应用保留 SDK fallback，不强制换模板；没有管理任务的应用可不添加后台。
 
-设计、实现和发布验收必须分别核验管理后台入口、表单、数据列表、流程入口，以及用户端 PC/移动端入口。缺少标准管理后台的应用结构不完整，不能发布。
+分别验证实际使用的后台、表单、列表及用户 PC/移动入口。图片只作为视觉参考，不代表运行或业务验收。
 
 ## 先理解任务
 

package/skills/openxiangda-v2/references/application-templates.md

@@ -0,0 +1,37 @@
+# 源码模板与业务场景
+
+## 选择与创建 {#create}
+
+模板是应用源码的初始化，不是不可编辑的 SDK 页面。后台、PC 用户端、移动用户端和登录外观分别选择布局；公共登录行为继续由 SDK 提供。既有 builtin:application 保持基础空应用。
+
+先运行 `openxiangda template list --json`，或读取 MCP template_list。已确定业务和授权创建时直接初始化，无需为模板选择增加确认。
+
+```bash
+openxiangda create ./visitor-app --base-url <测试平台> --scenario visitor
+openxiangda create ./records-app --base-url <测试平台> --scenario crud --style graphite-blue
+openxiangda create ./visitor-app --base-url <测试平台> --scenario visitor --admin topbar --pc workbench --mobile task-list --login centered
+```
+
+with/without 接受逗号分隔模块。未知场景、布局、风格、模块及缺失依赖在物化前报错。访客默认包含 time-slot、pass-and-checkin、party-directory、my-records；没有应用后端或工作流。移除依赖模块时必须同时移除依赖它的模块。创建到已有工作区只恢复原来源；不能换一套模板覆盖应用源码。
+
+## 源码所有权 {#ownership}
+
+后台外壳位于 apps/web/src/frames/admin/AdminShell.tsx；PC/移动 frame 位于同目录；登录布局位于 apps/web/src/login；样式位于 apps/web/src/theme；后台资源页位于 apps/web/src/admin。开发者可复制、修改、替换、重构，平台不会自动覆盖这些文件。通用模板修复由各应用选择采用。
+
+唯一后台通过 ui.admin.shell 挂载，菜单和路径来自平台已授权模型。保留 SDK 的路由及权限边界。应用页面通过 resourcePages 的 resource/view/list/detail/form contribution 挂载；未声明的页面沿用 SDK fallback。用户端通过 standardUserSurfaces 和普通页面贡献使用同一个应用路由。
+
+## 修改列表 {#resource-list}
+
+从 openxiangda/resource 导入 useResourceListController 和 ResourceListActions、ResourceListQueryBar、ResourceListAdvancedFilter、ResourceListAppliedFilters、ResourceListTable、ResourceListBatchBar、ResourceListOverlays 等块。控制器拥有数据、查询、列偏好、选择和获准动作；页面决定布局。columnRenderers 可替换可读列展示。移动端使用 useMobileResourceListController 与对应块。SDK 默认页使用相同边界。
+
+resourcePages: { visits: { default: { list: VisitListPage } } } 按资源和视图注册。应用组件获得 definition、paths、mode 和 variant；路由先核验生成声明、读取/动作能力，再渲染贡献页。隐藏列不授予权限，新增视觉动作仍由服务器校验。
+
+模板带 check:imports，解析真实 TypeScript 导入并核验包 exports；不允许私有 dist/src 深导入。资源 detail/form 先提供已有块，独立控制器继续扩展。
+
+## 登录与验收 {#login}
+
+登录模板消费 SDK 提供的 methods、state、error、passwordLogin、startSso、startDingTalk。支持账号密码、组织配置的 SSO/钉钉、验证码挑战、恢复身份和错误反馈；不建立第二个登录态，不显示未配置的入口。
+
+访客角色起点：host 可邀请且读取自己创建的记录；front_desk 可进入唯一后台并登记到访，数据范围由平台策略约束。区域及角色为示例，接入实际组织前按业务修改。简单 CRUD 场景提供表单、我的记录和后台数据管理。
+
+验收分别记录本地编译、浏览器、测试平台、实际角色和业务回读。模板初始化和设计图不是已部署业务。先 check，再按已授权环境验证邀请→接待→状态回读，桌面及 390px 均覆盖。参考[页面与标准组件](frontend.md)、[无账号访问](public-access.md)和[校验](testing.md)。

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

@@ -8,7 +8,9 @@
 | `pnpm openxiangda context` | 只读 | 只读查看工作区、版本与平台绑定 |
 | `pnpm openxiangda docs` | 只读 | 按主题和章节读取当前版本中文资料 |
 | `pnpm openxiangda admin` | 远端变更 | 查看管理能力、自助操作契约，或按明确环境执行事件、密钥及通知操作 |
+| `pnpm openxiangda template` | 只读 | 列出场景、模块、布局和风格模板 |
 | `pnpm openxiangda create` | 远端变更 | 创建、绑定并初始化应用 |
+| `pnpm openxiangda workflow` | 远端变更 | 导出流程、导入到源码、规划版本登记、查看状态并显式同步到目标环境 |
 | `pnpm openxiangda source` | 远端变更 | 配置应用源码仓库、查看状态或提交推送 |
 | `pnpm openxiangda dev` | 本地写入 | 连接平台测试数据启动本地 Web，按需启动 Nest |
 | `pnpm openxiangda check` | 本地写入 | 生成契约并在目标平台预检后执行检查、测试和构建 |

package/skills/openxiangda-v2/references/field-components.md

@@ -121,7 +121,16 @@ import { AttachmentFileList } from 'openxiangda/field-kit';
 }
 ```
 
-来源端点接受当前表单绑定值、关键字和游标；页大小由 `source.pageSize` 固定。
+来源端点接受关键字和游标；页大小由 `source.pageSize` 固定。创建表单使用 `operation: 'create'` 和当前绑定值。
+普通编辑表单使用 `operation: 'update', record: { id, expectedRevision }`，只传实际编辑的 `bindings`；平台以已保存记录合并这些编辑，检查行/字段更新权限及记录版本。没有编辑的绑定即使不可读，也由服务端参与查找，不返回它的原值。清空绑定传 `null`；最终提交仍由普通 Data API 验证必填和引用规则。
+
+列表筛选使用 `operation: 'filter'`：只需要宿主资源及字段的读取权限，目标保持当前用户的读取投影和行策略。写入 `source.filters` 不参与筛选，所以历史停用或已不满足写入条件的引用仍可查询；调用中不能携带 `bindings`、`record`、`launch`、`action` 或任务上下文。如需只展示某一类身份，可声明至多 20 个常量条件，例如 `filterWhere: [{ field: 'kind', operator: 'eq', value: 'building' }]`；支持 `eq`/`in`，不接受字段绑定。没有目标资源读取权限时，不会返回候选。
+
+普通生成表单自动传入保存上下文和实际编辑。自定义编辑表单通过 `SurfaceFieldRenderers.referenceBindings` 提供编辑值，`SurfaceFieldControl`/`MobileSurfaceFieldControl` 根据 `recordId` 和 `expectedRevision` 发送同样上下文。直接使用 `ResourceReferenceField` 时提供 `record` 和 `bindingEdits`。不传绑定编辑即使用保存值，不用把不可读字段填进浏览器。
+
+目录筛选通过现有目录检索的 `purpose: 'filter'` 返回可选的历史停用项，并标明停用；普通成员选择仍只接受有效项。范围来源支持 `operation: 'filter'`，使用读取范围授权，包含停用身份；自定义范围筛选控件使用 `renderScopeFilter`，与编辑态 `renderScope` 分开。
+
+含这些引用/目录字段或来源维度的编译包自动要求 `data.field-source-contexts` 版本 `1.0.0`，目标平台先升级后才能交付新包。
 标准流程的具名动作发起表单由 `WorkflowSubmissionPage` 自动传递 `launch: { workflowCode, operationCode }`。
 平台核对当前环境已部署的流程、动作、输入字段映射和当前用户动作权限；不要求额外授予宿主表单 CRUD 权限。
 普通 CRUD 表单不传此绑定，继续检查对应创建/修改权限。自定义选择器可通过 `searchResource` 的同名选项传递

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

@@ -26,11 +26,11 @@
 
 ### 应用骨架优先与视觉页面边界
 
-标准管理后台是每个业务应用的默认开发骨架，必须保留后台 Shell、显式菜单、资源表单、数据列表、详情/编辑、权限和流程入口。开发顺序先完成后台资源与契约，再实现用户端 PC/移动端；不能以用户端首页或设计原型替代后台。
+有管理任务的应用可选择源码后台模板，并在 ui.admin.shell 中挂载唯一外壳。应用拥有后台布局、资源列表和用户页面源码，可自由修改或重构；SDK 保留路由、当前用户权限与数据行为。模板选择是初始化，不增加第二套后台。
 
-Agent 可以在标准后台内部优化布局、视觉和交互，后台通过默认 Shell 或 `ui.admin` 扩展复用平台导航、字段行为和权限。用户端 PC 与移动端按真实旅程分别设计，通过平台 runtime/Data API 使用后台数据。图片参考和原型不拥有业务事实；禁止用图片、单页 HTML、iframe 或自定义假后台替换标准后台，也不能把后台权限、导航状态复制到用户端。
+资源页通过 resourcePages contribution 替换，列表从 openxiangda/resource 导入公共控制器和可组合块。未声明替换的旧应用仍用 SDK 默认页。PC/移动端和登录外观分别选择源码模板；登录共性行为留在 SDK。详见[源码模板与业务场景](application-templates.md)。
 
-发布前分别验证后台入口、表单、数据列表、流程入口和用户端 PC/移动端入口；没有完成后台骨架的应用不得发布。
+按真实任务实现并分别验证后台、表单、数据列表、按需流程及 PC/移动入口。没有管理任务时不强行添加后台；图片和原型只提供视觉参考，不能替代实际路由、授权、业务交互和验收。
 
 | 任务 | 页面与组件起点 |
 | --- | --- |
@@ -359,7 +359,17 @@ typed timeline 和 operation descriptors。业务字段继续使用平台 `Surfa
 PC canonical 路径为 `/tasks/:taskId` 和 `/workflows/:instanceId`，使用独立全屏页面而不进入
 后台 Shell；旧 admin 详情路径不存在。桌面和移动使用独立
 renderer，但共享同一授权与命令生命周期。主决策操作固定在底部，
-低频操作统一进入“更多操作”；意见输入延迟到动作确认层，页面不常驻空白意见表单。
+低频操作进入“更多”；意见输入延迟到动作确认层，页面不常驻空白意见表单。
+审批内容与本节点补填先于审批进度，附件独立展示，资料变更收进进度卡底部，默认折叠并在展开后加载，不使用内容 Tabs。
+PC 使用摘要页头、内容主栏与审批进度/参与人侧栏；移动端使用居中流程名称、纵向字段列表和底部单行操作栏。当前会签计数只读取当前任务的真实参与人，历史节点不推测审批模式。
+宽度足够时桌面右侧显示进度栏；窄屏按同一阅读顺序堆叠。移动端显示邻近三个节点，并可查看全部进度。
+
+审批详情不展示私有草稿入口。服务端提供的“保存”位于“更多”，仅保存当前填写的申请数据，不推进审批流程。`uiSchema.presentation: direct` 的操作直接复用同一提交控制器，保留权限、字段校验、数据修订与原请求恢复边界。
+操作顺序消费服务端可选的 `prominence`（正整数越小越突出，`null` 表示更多）和 `consequence`，
+不由应用猜测权限或重写命令。手机最多两项主操作与更多入口保持单行，桌面最多三项主操作；
+配套服务端将同意/重新提交、退回、拒绝申请依次排列，保存进入更多。
+旧服务端缺少这些元数据时沿用其 `placement`/`emphasis`。表单、上传、原请求恢复、
+权限撤回和写入成功后刷新失败仍由同一 SDK controller 处理。
 页面只显示非系统业务字段与节点内操作，不展示 UUID、revision、事件序列或技术信息区；
 `stale` 不产生常驻提示，真实命令冲突才显示刷新提示。
 应用只有在业务交互确实不能由标准页表达时才声明成对的 custom detail route。

package/skills/openxiangda-v2/references/getting-started.md

@@ -79,6 +79,8 @@ pnpm openxiangda dev
 
 将两处示例平台地址替换为同一个目标地址。`create` 先核对目标与当前登录平台，再创建本地目录、安装依赖并初始化远端应用；新应用不会自动沿用文件中最后登录的站点。CI 使用原有成对的 `OPENXIANGDA_BASE_URL` 和 `OPENXIANGDA_TOKEN` 时，可以由该显式地址指定目标。
 
+已有明确业务时可加 `--scenario visitor` 或 `--scenario crud`，使用 `template list --json` 查看四类布局、风格和模块。模板复制为应用源码，可独立修改；详见[源码模板与业务场景](application-templates.md)。
+
 初始化中断后重试同一命令；已有目录会核对原平台绑定，不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台；确需把工作区切换到其他站点时，使用 `openxiangda link rebind --base-url <新平台>` 显式换绑（见[跨站点与换绑](#cross-site)），不手改 link 文件绕过检查，也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
 
 进入项目后使用 `pnpm openxiangda`，由项目依赖和锁文件决定版本。查看使用资料运行 `pnpm openxiangda docs`；查看单一主题运行 `pnpm openxiangda docs frontend`。安装到其他 AI 工具时使用 `skill install --destination <Skill根目录>`。

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

@@ -59,6 +59,25 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
 }
 ```
 
+## template_list
+
+发现源码模板。列出业务场景、模块依赖、四类源码外壳和主题；创建使用 CLI，不执行远端操作。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
 ## workspace_context
 
 查看工作区。首先读取当前项目、工具链版本和绑定，不运行构建或创建远端对象。
@@ -1356,6 +1375,225 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
 }
 ```
 
+## workflow_sync
+
+同步流程到目标环境。按目标流程修订号显式同步，默认同时更新在途和新申请；复用发布及版本适用规则。保留指定人员边界。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "workflowCode": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "fromEnvironment": {
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "toEnvironment": {
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "expectedSourceHeadRevision": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "expectedTargetHeadRevision": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "operationId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000
+    },
+    "scope": {
+      "type": "string",
+      "enum": [
+        "running_and_new",
+        "new_only"
+      ]
+    },
+    "acknowledgeExceptions": {
+      "type": "boolean"
+    },
+    "copyHandlingDefaults": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "workflowCode",
+    "fromEnvironment",
+    "toEnvironment",
+    "expectedSourceHeadRevision",
+    "expectedTargetHeadRevision",
+    "operationId",
+    "reason"
+  ],
+  "additionalProperties": false
+}
+```
+
+## workflow_export
+
+导出流程到工作区。只读导出环境中的规范定义、绑定和办理设置摘要；不包含运行记录或环境内部标识。
+
+- 只读：否
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "workflowCode": {
+      "type": "string",
+      "minLength": 1
+    },
+    "out": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "workflowCode",
+    "out"
+  ],
+  "additionalProperties": false
+}
+```
+
+## workflow_import
+
+把流程导入源码。验证代码能力和摘要后修改工作区显式流程声明，保留人员配置边界。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "minLength": 1
+    },
+    "adoptHandlingDefaults": {
+      "default": false,
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "additionalProperties": false
+}
+```
+
+## workflow_plan_registration
+
+规划流程版本登记。服务器只读查询已有摘要和下一版本数字；write 只写源码版本数字，不写环境观察。
+
+- 只读：否
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "write": {
+      "default": false,
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## workflow_status
+
+查看流程源码同步状态。比较源声明、导入基线和环境摘要，显示待导回源码、待部署或冲突及未启用版本数量。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "workflowCode": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "additionalProperties": false
+}
+```
+
 ## workflow_node_configurations
 
 查看流程有效参数。修改已部署流程前，读取管理员维护的节点配置。已有任务和后续节点进入使用各自适用版本。

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

@@ -1212,3 +1212,36 @@ subject update和来源guards提交实际改变的派生字段；普通补填仍
 不改变字段授权、审批参数或流程版本；不提供该选项的应用保持既有行为。
 
 `commandHandlers.resubmit` 仅绑定固定 correction 节点的业务重校验。普通 `return_review` 任务继续由 Kernel 标准 `resubmit` 办理：Surface 不返回 correction operationCode，审批人不需要起草提交 capability。无需增加 `taskKinds` 字段、改动已有定义版本或重建在途实例；直接对普通退回任务调用 correction 业务动作仍被拒绝。
+
+## 画布、源码与测试环境同步
+
+管理员可以在画布修改节点和条件并直接发布。发布默认更新在途申请与新申请，当前已经进入的任务继续保留其人员、操作按钮、页面与字段权限；后续流转使用新版本。只让新申请生效、保留个别在途申请属于显式例外。
+
+应用源码与画布共同引用同一份不可变定义和绑定登记。画布修改后，后续仅改页面或后端的应用部署会保留兼容的画布版本。两边都改了流程而基线不一致时，部署返回 `WORKFLOW_SOURCE_DIVERGED`，需要先把正式环境流程导回源码：
+
+```sh
+pnpm openxiangda workflow export request-review --environment production --out platform/workflows/request-review.bundle.json
+pnpm openxiangda workflow import platform/workflows/request-review.bundle.json --to source
+pnpm openxiangda workflow plan-registration --environment test --write
+pnpm openxiangda workflow status --environment test
+```
+
+`export` 包含规范定义、绑定、任务页面与代码步骤契约、办理设置摘要；不含申请、待办、审批日志、密钥或环境内部标识。源码本来声明的固定用户标识会保留；管理员实际指定人员的覆盖只导出数量。`import` 只改 `openxiangda.config.ts` 中显式的 `workflows` 声明及 `platform/workflows/<code>.lock.json`，保留其他代码。新增或变化的代码步骤、页面契约需要先由开发者补齐；缺少这些契约的导入会在写文件前拒绝。
+
+可加 `--adopt-handling-defaults` 把办理模式与按钮开关、文案作为源码默认值。它保留原有必需动作，不把管理员指定人员复制成源码默认值。导入的摘要基线写在源码 activation 的 `sourceBase`；来源环境与修订号只保留在审计锁文件，不进入密封应用制品。锁文件与导出的规范文档可能包含合法源码用户引用，应按项目访问权限管理。
+
+`plan-registration` 是服务器只读查询，返回相同内容已有的版本号或下一整数；`--write` 只把数字写入本机源码。最终准备仍检查编号冲突、内容冲突和跳号。准备成功但后续部署失败的版本保留为未启用的不可变登记，相同制品可复用这些数字；不会删除或重排。`status` 显示 `in_sync`、`behind`、`ahead`、`diverged`、`not_active` 和未启用登记数量。它没有远端写入。首次导入之前，状态比较使用目标环境当前应用版本的源码声明作为基线；跨环境导入的来源修订不会冒充目标环境基线。
+
+如果只希望把正式环境的流程规则同步到已有测试环境，可先读取两边的 `status`，记录实际流程 Head 修订号，再显式执行同步：
+
+```sh
+pnpm openxiangda workflow sync request-review --from production --to test \
+  --expected-source-head 14 --expected-target-head 3 \
+  --operation-id workflow-sync-20261012-01 --reason '同步正式环境流程到测试'
+```
+
+示例修订号必须替换成实际读取值。源和目标必须属于同一应用且均有已启用流程。同步检查目标现有页面、代码步骤、角色与固定人员引用，复用源版本，并通过正常发布与在途适用规则生效。默认同时更新在途和新申请；`--new-only` 只更新新申请。存在不兼容在途申请时，在确认预览结果后加 `--acknowledge-exceptions`，这些申请继续保留原版本。
+
+`--copy-handling-defaults` 可复制办理模式、按钮和角色覆盖；两边的指定人员覆盖都保持环境所有。源环境不被修改。同步后的目标画布草稿若基线已经过时，需要重读或合并，不能覆盖新的 Head。请求不确定时，保留相同操作标识、两个修订号和完整参数重试；不要换标识重做。CLI 与 MCP 共用这些权限、校验、幂等和发布入口。
+
+部署前记录目标流程修订号，激活前再次核对。期间若有人发布了画布，激活返回 `WORKFLOW_SOURCE_HEAD_CHANGED`，应用 Head 与流程 Head 在同一事务回滚；已准备的不可变登记保留。同步成功、源码检查成功、包发布与真实审批验收分别核对。