openxiangda 2.0.0-alpha.98 → 2.0.0

package/documentation/upgrading.md

@@ -0,0 +1,39 @@
+# 版本升级与资料刷新
+
+## V1 项目的选型建议
+
+对正在使用 V1 的项目，优先核实 V2 能力覆盖、项目阶段和迁移成本。V2 能力满足、项目仍在测试阶段且代价可控时，建议采用 V2。在 V1 项目中使用统一入口提供的只读迁移评估，获取源码清单，再结合真实数据、在途流程和团队计划评估。命令以统一入口的帮助为准；V2 项目引擎不承担 V1 迁移操作。
+
+确认迁移后，按项目形成 AppSpec 设计、数据与流程映射、验收和回滚方案。尚未完成迁移决策时，原项目继续使用其锁定的 V1 引擎；工具链的同代升级与应用跨代迁移分别处理。
+
+## 升级前核对 {#before}
+
+先运行 `pnpm list openxiangda --depth 0` 核对项目实际安装的根包版本，再运行 `pnpm openxiangda context --json` 核对平台绑定和启用能力。取得目标精确版本和变更说明，核对平台能力要求。应用只直接管理 openxiangda 根包，内部物理包组合由该发行确定。
+
+上下文的 `toolchain.packageName` 标明版本来源，当前 `toolchain.version` 是 `openxiangda-devkit-core` 的物理包版本，不能当作 openxiangda 根包版本。根包与 CLI、Devkit、MCP、contracts 等独立版本化，由根包精确依赖组成同一发行；数字不同不代表版本漂移。
+
+协议版本说明数据格式，能力版本说明某项平台契约，校验实现摘要说明实际执行的规则；不能只比较名称里的数字判断是否配套。旧工具读不懂新协议时升级项目根包及 Skill/MCP；平台缺少新能力时由维护者升级或启用平台能力；规则摘要不同则按发布组合核对两端。诊断无法确定哪端落后时，不应无条件升级平台或反复改业务代码。
+
+共享校验使用 `configuration-compatibility/v2` 描述，包含校验实现摘要。切换到这一契约时，平台和项目工具链需按同一发布说明配套升级。随后每次发布在构建前核对实现摘要；不要反复修改业务代码来处理工具版本不配套。
+
+引导式开发使用 workspace-context/v3 与 AppSpec context/v3。升级后按实际业务补齐总纲与关联变更；空模板不能正式测试发布，生产晋级需要原测试版本的验收计划和实际报告。旧候选缺少计划时建立新的测试候选并验收，不自动补写过去的确认或通过记录。普通 dev/check 仍可用于整理和验证尚未完成的项目。
+
+## 更新项目 {#upgrade}
+
+更新项目的精确根包依赖并安装，提交相应锁文件；不要使用 latest、alpha 或范围版本代替明确版本。运行统一 check，处理实际契约变化，再在测试环境验证后晋级。
+
+执行 `pnpm openxiangda skill install --workspace . --force`，通过新版本根包安装 Skill；已有项目使用项目安装模式时会刷新 AGENTS 的平台管理段，并保留管理段外的自定义说明。没有可识别管理段的旧 AGENTS 不会被整份替换；先审阅工具输出的候选内容，再合并需要的规则。
+
+持续运行的 MCP 进程仍可能加载旧代码，升级后重启该连接并重新读取 workspace_context、资料版本和当前契约。全局 Skill 的版本不代表所有项目版本；进入项目后以项目锁定的 CLI 和随包资料为准。
+
+## 整理旧模板测试 {#tests}
+
+旧模板的测试与源码预算属于项目自有文件，升级包不会静默删除。若新增页面或合理重构触发样例限制，先提交当前源码，检查 `apps/web/test/contracts.test.ts`、`apps/web/scripts/check.mjs` 和 `apps/server/test/smoke.test.ts`：把项目实际业务断言保留，仅移除固定初始页数、样例文件名、普通业务词和总行数限制；Web 的 check 保留 `tsc -p tsconfig.json --noEmit`，后端可用 `tsx --test` 自动发现用例。
+
+旧 `apps/web/e2e/` 中的通用模拟平台夹具及 `*.e2e.html` 不代表本应用验收。确认没有项目用例依赖后，可连同 Vite 中对应的预热入口整理；保留项目自行编写的用例与配置。使用实际业务记录重建验收覆盖，并执行完整 check；不要把整理样例当成修复真实契约、类型或权限错误的方法。
+
+## 失败与回退 {#rollback}
+
+保留失败指针和变更差异。资料缺失或摘要不符时重新安装该精确版本，不能复制其他版本的文档掩盖问题。应用版本回滚、依赖降级和数据/迁移恢复分别处理；降级 npm 包不等于撤回已经发生的业务写入。
+
+平台能力不足时交由平台维护者升级，不通过删除字段、改生成契约或退回 1.x 接口绕过。开发者无需执行工具链 npm 发包或平台数据库迁移。

package/documentation/workflow-events.md

@@ -0,0 +1,181 @@
+# Workflow 与 Notification Hub 2.0 边界
+
+标准 Workflow 与 Notification Hub 已作为 OpenXiangda 2.0 可选平台模块重新开放。它们不属于默认 CRUD 模板，也不兼容或复用 1.x 工作流、消息中心、模板、卡片、回调、表和 API。
+
+## 标准详情与当前用户入口
+
+普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页；管理员在当前抽屉或页面中切换到普通表单编辑，直接保存并自动留下变更记录，审批结果保持不变。PC 子表在表格内编辑，父表提交时统一校验。
+
+待办中心通过 Workflow 查询 `pending`、`handled`、`created`、`cc` 四种视图；消息中心默认向 Notification Hub 查询 `view=all`，沿用应用声明的渲染扩展。各入口按服务端 `detailNavigation` 打开详情，页面不自行拼接人员范围。
+
+抄送由动态 Surface 提供 `cc` 操作，使用 `user_select` 多选组件收集 1 至 20 位人员。任务 Surface 可以正式包含实例抄送命令；前端按 `operation.execute.href` 和该 Surface 的 token 提交，不另造任务命令或 token。公共事件为 `openxiangda.workflow.instance.cc_added.v2`。
+
+## 能力 owner
+
+- Workflow Kernel v2 唯一拥有定义、实例、任务、参与人、命令、流转、委托、加签和流程审计。
+- Application Events v2 唯一拥有已提交事实的 journal/outbox、顺序、投递和回执。
+- Notification Hub v2 唯一拥有逻辑消息、模板、规则、渠道路由、渲染、发送、更新、关闭、外部绑定、动作收据和消息运维。
+- Data API/App API 唯一拥有业务记录；Workflow 只保存 `dataRef` 和 revision-bound facts，消息只保存允许展示的安全投影。
+- Native Identity/AuthZ v2 唯一拥有当前用户、当前应用角色并集和数据范围；Perspective 只影响读取展示，不改变 Workflow 的发起、任务与操作授权。
+
+Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`，并要求独立的
+正整数 `dataRevision`。definition 的 `inputSchema` 根对象必须显式
+`additionalProperties: false`，未声明的 facts/answers 直接拒绝。Provider
+回调只接受带完整业务/数据/definition/binding/fact digest 的
+`openxiangda.workflow-assignee-request/v2.1`。
+
+## 标准工作流范围
+
+首期只支持 `approval`、`condition`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
+
+复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
+
+所有页面和消息动作必须来自后端 Workflow Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
+Surface 同时签发短期、一次性的 `commandToken`，绑定当前用户/会话、应用环境
+Head、实例/任务版本、允许的命令集合与 CSRF。命令请求只提交
+`commandToken + idempotencyKey + input`；旧的 caller-authored
+`expectedTaskVersion`/`expectedInstanceVersion` 不再是合同。冲突必须刷新 Surface，
+不得自动重放旧意图。
+
+## 事实和消息投影
+
+Workflow 在同一 PostgreSQL 事务中提交状态、fact 和 outbox。每个实例使用严格单调的 `instanceSequence`，每位审批人拥有独立 participant 生命周期。
+
+Native Data 事件的 capture plan 由当前 Head 的 Event、Data、AuthZ revision
+与 resource 四元组共同确定。新增快照字段或扩展 RLS 会形成新的不可变 plan，
+不会与旧 plan 冲突；历史 replay/re-emission 复制原 fact 的数据与 plan digest，
+不会用当前 Head 重新投影历史事实。
+
+每条 Workflow fact v2 都必须携带不可变实例身份信封：`workflowCode`、
+`definitionVersion`、`bindingVersion`、`instanceId`、`generation`、
+`businessKey`、`instanceSequence`、`revision`、`dataRef`、`dataRevision`、
+`actor` 与 `cause`。消费者不得从当前 Workflow Head 反推历史事实版本。
+
+配置中的 `workflows.activations` 是完整 desired set；删除声明即停用新发起，
+不是增量 patch。definition 和 activation 必须一致声明
+`acceptedCommandDeactivationPolicy`：`finish-pinned` 让已接受的 durable process
+command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消尚未启动的命令；
+既有 Workflow instance 始终按固定版本继续。所有审批人 Provider 的 `min/max`
+默认 1/200，最大 200。
+需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
+
+Notification Hub 消费事实：
+
+- `participant.activated` 创建待处理消息；
+- participant 完成、转交、委托、加签、暂停或恢复时更新对应收件人的逻辑消息；
+- instance 完成、拒绝、撤回或终止时更新该实例全部历史消息；
+- 消息回调必须调用 Workflow 命令，等待 Workflow 新事实后再更新卡片。
+
+发送采用至少一次语义，以 `messageKey + recipient + channel` 幂等。RabbitMQ 只负责唤醒，PostgreSQL fact、message projection、outbox 和 receipt 才是恢复事实。
+
+## 详情跳转
+
+消息使用 canonical `navigationTarget`，而不是模板拼接环境 URL。它可以描述平台路由、应用路由或白名单外部地址，由平台按 tenant、environment 和 channel 解析 desktop/mobile/deep link。
+
+详情地址不能携带登录 Token、Cookie 或任何身份替换凭据。点击后必须重新认证，并由 Data/AuthZ/Workflow 执行真实权限校验；当前 Perspective 只能重新应用读取投影。
+
+“跳回业务记录”和“完全接管流程详情”是两个不同合同。标准 Workflow 页需要提供
+“查看业务详情”时，在 subject resource 上声明明确的 route code 对：
+
+```ts
+const purchaseResource = {
+  code: 'purchases',
+  name: '采购申请',
+  detailRouteCode: {
+    desktop: 'purchase-record-detail',
+    mobile: 'purchase-record-detail-mobile',
+  },
+  fields: [/* ... */],
+} satisfies AppDataResourceDeclaration;
+```
+
+两条 route 都必须是已认证的 `surface: 'user'` 页面并要求该资源的 read capability；
+桌面 path 不得进入 `/m`，移动 path 必须以 `/m/` 开头，且各自只能包含一个动态记录参数。
+参数名可以是业务语义名，例如 `:purchaseId` 或 `:applicationId`。编译器把映射写入
+不可变资源 Contract 和生成的 `resourceDefinitions`，平台从同一环境 active Contract
+读取并代入 Workflow Surface 已授权的 recordId。未声明时返回空业务记录目标；已发布
+映射畸形时严格失败。平台和浏览器都不得再按 `resourceCode` 猜路径，也不得用别名补洞。
+
+流程需要完全接管详情页时，在 definition declaration 上声明桌面端与移动端 route code：
+
+```ts
+{
+  version: 1,
+  definition: purchaseApproval,
+  launch: { mode: 'work-center-only' },
+  detailRouteCode: {
+    desktop: 'purchase-detail',
+    mobile: 'purchase-detail-mobile',
+  },
+}
+```
+
+`desktop` 必须引用 `surface: 'admin'` 的 route，`mobile` 必须引用
+`surface: 'user'` 的 route；两个 path 都必须且只能包含
+`:instanceId`。任务入口由平台追加有界 `taskId` query。应用使用
+`defineApplicationContributions(appRoutes, { pages })` 绑定桌面和移动组件，
+页面通过 `openxiangda/core` 的 `loadWorkflowInstanceDetail`、
+`loadWorkflowTaskDetail` 读取修订一致的聚合详情，只渲染 Surface 返回的操作。
+旧 Surface 与 timeline 读取继续供兼容客户端使用。
+
+平台在当前环境 Head 的不可变 Contract Bundle 上统一解析：桌面/移动工作台、
+Notification Hub 的 `workflow.detail` 逻辑目标、钉钉卡片以及其他渠道快照得到
+同一组自定义路径。未声明时保留标准详情；声明存在但 route 缺失、surface 错误或
+path 不合法时严格失败，不退回标准页掩盖合同错误。
+
+标准详情由平台统一渲染，不要求应用复制资源详情页。Workflow Surface 的
+`presentation.businessDetail` 按实例固定的 Data logical revision、资源声明 digest 和
+physical resource 定位结构，但每次读取同一 Native Data record 的当前字段值；发起时
+`requestedRevision` 只用于命令 token/CAS，当前 `sourceRevision` 和当前值始终随重新读取更新，
+禁止把业务字段值改成流程启动快照。字段投影同时应用当前用户策略并统一排除
+`system: true`、平台内部字段与过滤后为空的分组；
+父子表按同一 logical revision 和父记录外键读取，单表最多 200 行。页面同时消费
+`presentation.summary`、服务端 timeline `display.entries` 和 operation descriptors。
+桌面端与移动端拥有独立 DOM；同意/拒绝等决策操作固定在底部主操作区，转交、退回、
+加签等低频操作进入“更多操作”，意见只在点击动作后的确认弹窗或移动端底部抽屉中输入。
+`stale` 只是 revision 元数据，不显示常驻横幅也不预先阻断操作；只有服务端命令 token/CAS
+返回真实 `freshSurface` 冲突时才提示“内容已更新，请刷新后重试”，且绝不自动重放命令。
+同意、拒绝、退回、转交和加签记录并入对应纵向节点；实例撤回/终止是独立终态事件，
+展示操作者、动作、意见和唯一 `primaryDisplayTime`，
+不另设“操作记录”。标准业务页不渲染流程/任务/资源/记录 UUID、事件序列、revision 或失败指针。
+申请人、审批人和操作者显示目录/快照解析名称、可选部门以及真实头像；缺失或加载失败时
+统一使用平台默认头像，不生成姓名首字，也不回退 userId。
+
+PC 标准任务与实例详情的 canonical 路径分别为 `/tasks/:taskId` 和
+`/workflows/:instanceId`，使用独立全屏页面，不进入后台 Shell；不提供旧 admin 路径的
+别名或重定向。移动端继续使用独立的 `/m/tasks/:taskId` 和 `/m/workflows/:instanceId` 页面。
+
+流程详情中的附件、富文本图片和签名不直接复用普通 Data API 文件地址。浏览器调用
+Workflow instance-scoped preview/content 路由，平台在每次文件读取时重新校验当前身份、
+实例参与权限、固定业务记录、资源、字段和 file id；URL 不携带登录态或替代身份。
+
+标准发起页使用独立的 `WorkflowLaunchSurface` 读取当前激活合同：桌面路径为
+`/workflows/:workflowCode/start`，移动路径为
+`/m/workflows/:workflowCode/start`。`standalone`/`hidden-handoff` 缺省使用同一个
+compiler-owned `processOperationCode`、subject declaration 和标准 process commit；平台在一个
+事务中写业务数据和 durable command。action-owned 资源改为声明
+`launch.submission.kind: 'named-operation'`，显式绑定 create/existing 请求来源、响应 subject/
+processCommand 路径和 allowlisted context 预填。标准页调用原 Named Action，由应用服务端保留
+业务校验、幂等与原子提交；缺少/null processCommand 是成功的免审结果，不生成流程。页面只在
+确实返回 command 时把 `commandId` 写入 URL，刷新、跨设备和 worker 恢复都重新读取
+`ProcessCommandSurface`；`awaiting_input` 只回答已生成 requirement，`started` 再进入 pinned
+instance entry。浏览器不再导出 prepare/start 发起协议。
+
+通用应用待办页通过 `frontend.user.applicationTodoCenter: true` 启用，平台同时提供
+`/todos` 和 `/m/todos`。它只投影当前登录用户的 Notification Hub 收件人数据，
+`查看详情` 使用上述统一导航解析；待办页不常驻业务详情，审批命令仍在目标 Workflow
+Surface 上执行。
+
+## 应用声明
+
+应用只在明确启用可选模块时，在 `openxiangda.config.ts` 声明 workflow definition、binding、assignee provider、notification profile、template reference 和安全字段投影。Git 声明是拓扑事实源；平台管理页面只负责版本、激活、预览、诊断和有界运行参数，不建立第二份活动定义。
+
+事件处理器调用 `OpenXiangdaBusinessNotificationService.sendFromEvent()` 时，
+对应订阅还必须声明
+`platformAccess: { notification: { mode: 'business-standard' } }`。编译器将该声明写入
+不可变 Configuration/Contract Bundle，并据此生成精确的 `notification-hub-v2`
+能力闭包；不发送通知的订阅不得声明该依赖，未知 access 或 mode 直接失败。
+
+## 验证
+
+至少验证：完整标准详情投影、父子表边界、流程附件读取、桌面/移动独立渲染、全部标准操作、多人模式、重复/并发命令、stale revision、重启 replay、乱序事件、重复回调、消息终态全量更新、详情跳转、错用户/错租户/过期动作、渠道超时/unknown、死信重放和 1.x 零触碰。

package/launcher-skill/openxiangda/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: openxiangda
+description: Identify OpenXiangda V1 or V2 workspaces and select the matching project tools and AI guidance. Use when working on an OpenXiangda application, creating a new application, checking a tool version, upgrading tools, or assessing a V1 migration.
+---
+
+# OpenXiangda 统一入口
+
+本 Skill 只负责代际识别和分流，分发版本为 `__OPENXIANGDA_VERSION__`。
+
+1. 从任务目录向上定位最近的工作区。`app-workspace.config.ts` 或 V1 `.openxiangda/state.json` 绑定属于 V1；`openxiangda.config.ts` 或 `openxiangda-app.config.ts` 属于 V2。同一目录出现冲突时停止，先解决归属，不能删配置来绕过识别。
+2. 使用 `openxiangda version --json` 核对工作区、实际引擎版本和来源。已声明的项目依赖尚未安装时，按项目锁文件安装；不能用全局引擎代替项目锁定版本。
+3. V1 阅读项目安装的 `$openxiangda-v1` 及其子技能；V2 阅读项目安装的 `$openxiangda-v2`。缺少匹配版本的技能时，在项目中执行 `openxiangda skill install --workspace .`。以该项目版本的文档、MCP 和命令发现结果为准，不把另一代的配置、SDK、登录态和发布命令带入项目。
+4. 空目录创建新应用默认使用 V2。V2 应用先澄清产品、页面、权限与架构，确认 AppSpec 设计基线之后再制定开发计划。
+5. 对已使用 V1 的项目，主动核实 V2 能力是否满足、是否仍在测试阶段，以及迁移成本。如果三项条件满足，优先建议采用 V2，并说明收益、需要重建的部分和验收代价。不能把“识别为 V1”当成必须长期留在 V1 的产品建议；条件未知时先收集证据。实际迁移按项目确认设计、数据/流程映射和回滚方案后实施。
+
+## 升级与说明
+
+- `openxiangda update check` 按项目代际检查稳定更新；离线时可继续使用本地能力。
+- `openxiangda update install --target workspace` 更新本项目同代工具链。升级后检查源码与锁文件差异，并执行项目验证。
+- `openxiangda update install --target launcher` 更新全局统一入口，需要 Node.js 24。此操作不转换已有项目。
+- `openxiangda changelog` 查看实际引擎随包说明；指定版本可查看对应版本资料。
+- `openxiangda migrate assess --to v2` 只读检查 V1 源码并列出迁移待核实项。评估结果不代表数据已迁移，也不授权自动改造旧应用。
+
+原业务授权、环境和部署事实仍由项目及平台的现有契约管理。本入口不会改写角色、登录绑定、业务数据或部署状态。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openxiangda",
-  "version": "2.0.0-alpha.98",
-  "description": "Unified OpenXiangda 2.0 CLI, SDK, React runtime, NestJS integration and AI skill distribution.",
+  "version": "2.0.0",
+  "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -49,18 +49,22 @@
     "bin/",
     "dist/",
     "skills/",
+    "documentation/",
+    "launcher-skill/",
+    "releases/",
     "README.md"
   ],
   "dependencies": {
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.0.0-alpha.172",
-    "openxiangda-contracts": "2.0.0-alpha.86",
-    "openxiangda-devkit-core": "2.0.0-alpha.110",
-    "openxiangda-mcp": "2.0.0-alpha.110",
-    "openxiangda-nest": "2.0.0-alpha.98",
-    "openxiangda-skill-kit": "2.0.0-alpha.135",
+    "openxiangda-cli": "2.0.0",
+    "openxiangda-contracts": "2.0.0",
+    "openxiangda-devkit-core": "2.0.0",
+    "openxiangda-legacy": "npm:openxiangda@1.0.268",
+    "openxiangda-mcp": "2.0.0",
+    "openxiangda-nest": "2.0.0",
+    "openxiangda-skill-kit": "2.0.0",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -112,9 +116,68 @@
     "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=22.12"
+    "node": ">=24"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1377385356/openxiangda.git",
+    "directory": "packages/openxiangda"
+  },
+  "homepage": "https://github.com/1377385356/openxiangda",
+  "bugs": {
+    "url": "https://github.com/1377385356/openxiangda/issues"
+  },
+  "openxiangdaRelease": {
+    "schemaVersion": "openxiangda.release-notes/v1",
+    "version": "2.0.0",
+    "title": "OpenXiangda 2.0 正式版",
+    "status": "reviewed",
+    "summary": "以统一入口使用两代工作区，新应用默认采用 V2。V2 提供从需求设计到 React 应用、平台数据权限和应用交付的完整工具链。",
+    "newFeatures": [
+      "统一入口识别最近的 V1/V2 工作区，优先使用项目已安装的锁定引擎；无本地 V1 引擎的旧工作区使用随入口固定的 V1 维护引擎。",
+      "新应用默认 V2：自然语言澄清产品需求，形成产品、页面、权限和架构设计基线，确认后再制定开发计划。",
+      "V2 提供标准 PC/移动端 CRUD、字段组件、Data API 权限、流程与协作能力；默认本地 React 连接平台测试环境，Nest 后端按需使用。",
+      "提供版本识别、分代更新、随包更新说明和 V1 到 V2 的只读迁移评估。"
+    ],
+    "fixes": [
+      "全局入口切换到 V2 后，旧 V1 工作区仍由 V1 执行，不再因同名命令使用错误代际。",
+      "项目工具链升级与全局入口升级明确分开；V1 维护渠道不再改写 latest。",
+      "两代 Skill 使用独立入口，V1 安装不再覆盖统一入口或清理 V2 Skill。"
+    ],
+    "affectedUsers": [
+      "新建应用的开发者",
+      "需要继续维护 V1 工作区的开发者",
+      "从 V2 alpha 升级的现有用户"
+    ],
+    "compatibility": {
+      "node": ">=24",
+      "workspaceGenerations": [
+        "v1",
+        "v2"
+      ],
+      "v1Policy": "保持现有配置、数据、流程、登录绑定与项目工具链代际；原 V1 CLI 可继续使用其原运行环境。",
+      "platformPolicy": "V2 应用部署前按平台 capabilities 和配置验证器预检；工具版本不能代替平台实际部署版本。",
+      "backendBuild": "Nest 镜像由开发者电脑上的 Docker 构建；普通 React/Nest 连接开发不要求本地平台或数据库。",
+      "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。npm 不允许把 v1/v2 作为标签。"
+    },
+    "upgradeSteps": [
+      "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.0.0。",
+      "进入已有项目运行 openxiangda version --json，核对工作区代际、实际引擎和解析来源。",
+      "运行 openxiangda update check 查看本项目更新；需要升级时执行 openxiangda update install --target workspace。",
+      "检查依赖与锁文件差异，刷新本项目 Skill，并完成项目检查、测试环境和真实角色业务验收后再晋级生产。",
+      "V2 能力满足、项目仍在测试阶段且迁移成本可控时，优先建议 V1 项目采用 V2；先完成项目评估、设计确认和迁移验收。"
+    ],
+    "knownLimitations": [
+      "V1 到 V2 首期仅提供本地源码迁移评估，不读取远端业务数据，也不自动迁移应用。",
+      "源码扫描不会证明远端权限、流程和数据完整性；迁移须按项目制定映射、演练和回滚方案。",
+      "内网或离线环境可读取随包说明；联网检查失败时保留当前工具与项目。",
+      "内部支持 Agent 独立交付和验收，不随此 npm 版本自动部署。"
+    ],
+    "issues": [],
+    "sha256": "a6100370946d253328c924c19f6577bac383c4633e3650d69b7ad378486ae880",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.0.0"
+  },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",
     "build:release": "node ../../scripts/prune-package-dist.mjs && pnpm build",

package/releases/2.0.0.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.0.0",
+  "title": "OpenXiangda 2.0 正式版",
+  "status": "reviewed",
+  "summary": "以统一入口使用两代工作区，新应用默认采用 V2。V2 提供从需求设计到 React 应用、平台数据权限和应用交付的完整工具链。",
+  "newFeatures": [
+    "统一入口识别最近的 V1/V2 工作区，优先使用项目已安装的锁定引擎；无本地 V1 引擎的旧工作区使用随入口固定的 V1 维护引擎。",
+    "新应用默认 V2：自然语言澄清产品需求，形成产品、页面、权限和架构设计基线，确认后再制定开发计划。",
+    "V2 提供标准 PC/移动端 CRUD、字段组件、Data API 权限、流程与协作能力；默认本地 React 连接平台测试环境，Nest 后端按需使用。",
+    "提供版本识别、分代更新、随包更新说明和 V1 到 V2 的只读迁移评估。"
+  ],
+  "fixes": [
+    "全局入口切换到 V2 后，旧 V1 工作区仍由 V1 执行，不再因同名命令使用错误代际。",
+    "项目工具链升级与全局入口升级明确分开；V1 维护渠道不再改写 latest。",
+    "两代 Skill 使用独立入口，V1 安装不再覆盖统一入口或清理 V2 Skill。"
+  ],
+  "affectedUsers": [
+    "新建应用的开发者",
+    "需要继续维护 V1 工作区的开发者",
+    "从 V2 alpha 升级的现有用户"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": [
+      "v1",
+      "v2"
+    ],
+    "v1Policy": "保持现有配置、数据、流程、登录绑定与项目工具链代际；原 V1 CLI 可继续使用其原运行环境。",
+    "platformPolicy": "V2 应用部署前按平台 capabilities 和配置验证器预检；工具版本不能代替平台实际部署版本。",
+    "backendBuild": "Nest 镜像由开发者电脑上的 Docker 构建；普通 React/Nest 连接开发不要求本地平台或数据库。",
+    "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。npm 不允许把 v1/v2 作为标签。"
+  },
+  "upgradeSteps": [
+    "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.0.0。",
+    "进入已有项目运行 openxiangda version --json，核对工作区代际、实际引擎和解析来源。",
+    "运行 openxiangda update check 查看本项目更新；需要升级时执行 openxiangda update install --target workspace。",
+    "检查依赖与锁文件差异，刷新本项目 Skill，并完成项目检查、测试环境和真实角色业务验收后再晋级生产。",
+    "V2 能力满足、项目仍在测试阶段且迁移成本可控时，优先建议 V1 项目采用 V2；先完成项目评估、设计确认和迁移验收。"
+  ],
+  "knownLimitations": [
+    "V1 到 V2 首期仅提供本地源码迁移评估，不读取远端业务数据，也不自动迁移应用。",
+    "源码扫描不会证明远端权限、流程和数据完整性；迁移须按项目制定映射、演练和回滚方案。",
+    "内网或离线环境可读取随包说明；联网检查失败时保留当前工具与项目。",
+    "内部支持 Agent 独立交付和验收，不随此 npm 版本自动部署。"
+  ],
+  "issues": [],
+  "sha256": "a6100370946d253328c924c19f6577bac383c4633e3650d69b7ad378486ae880",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.0.0"
+}

package/skills/manifest.json

@@ -3,8 +3,8 @@
   "skills": [
     {
       "name": "openxiangda-v2",
-      "description": "Use when researching, designing, building, testing, or delivering an OpenXiangda 2.0 application, including anonymous public forms and other no-account external-user pages.",
-      "sha256": "ad7e89a4cfeba1b730cdd9504609872e1355bf5d79101c439cdf7350a4bc9678"
+      "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，再开发、检查和交付应用。维护 1.x 应用时使用对应的 1.x 技能。",
+      "sha256": "03e57d1ed49e993740e9de0e4b24c3a3aa7ffb534604e6cf10e5d583be0edbe6"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -1,71 +1,84 @@
 ---
 name: openxiangda-v2
-description: Use when researching, designing, building, testing, or delivering an OpenXiangda 2.0 application, including anonymous public forms and other no-account external-user pages.
+description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，再开发、检查和交付应用。维护 1.x 应用时使用对应的 1.x 技能。
 ---
 
 # 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-owned identity switching or another identity path.
+## 先理解任务
 
-Before a workspace exists, use this Skill's exact npm version:
+新应用或模糊业务想法先读[对话发现与产品设计](references/product-design.md)，从资料和真实流程主动提出模块建议，逐轮少量提问、复述确认并更新 AppSpec。完整首发的 PRD、旅程、逐页交互、视觉/原型、权限与架构形成权威基线后，才制定实施计划和编写业务实现。用户不知道模块时给出有理由的推荐和代价，不能把整套设计问题丢回用户。
 
-```bash
-pnpm dlx openxiangda@2.0.0-alpha.98 login --base-url <platform>
-pnpm dlx openxiangda@2.0.0-alpha.98 create <directory>
-```
+已有资料沿用；已确认决定持续有效，冲突和新增业务含义再沟通。AI 建议、资料事实、用户确认、否决/延期和阻断问题分别记录。仅分析或原型不自动创建远端应用；既有应用按受影响范围设计，无行为修改不重做全套文档。
+
+遇到已有 V1 项目时，先核实 V2 能力覆盖、项目是否仍在测试阶段和迁移成本；能力满足、仍在测试阶段且代价可控时，优先建议转用 V2。先做只读评估，再按项目确认详细设计、数据/流程映射、测试和回滚；迁移实施前的原项目维护仍使用匹配的 V1 引擎。
 
-Inside an application, use only its locked executable through `pnpm openxiangda`. Never invoke a bare global `openxiangda`, because that executable may belong to stable 1.x. Moving tags such as `latest` and `alpha` are forbidden. To install or refresh this same Skill from the package, run:
+## 定位当前版本
+
+未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.0.0-alpha.98 skill install --force
+pnpm dlx openxiangda@2.0.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.0.0 login --base-url <平台地址>
+pnpm dlx openxiangda@2.0.0 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.0.0 skill install --force
 ```
 
-Use this order:
+创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
+
+进入既有项目后使用项目锁定的 `pnpm openxiangda`，先读 `context --json`。全局 Skill 的版本不代表项目版本；资料以项目 `docs` 或 MCP docs_read 返回的版本为准。不要调用可能属于 1.x 的裸全局命令，也不用 latest/alpha 替代精确版本。
+
+## 按任务选择资料
+
+只读当前任务相关专题。以下参考由中文使用文档生成，与 CLI/MCP 正文同源：
+
+| 任务 | 参考 |
+| --- | --- |
+| 安装、登录、创建、连接开发 | [开始开发](references/getting-started.md) |
+| 模糊想法、模块发现、PRD、权限与架构设计 | [产品设计](references/product-design.md)、[交互模式](references/interaction-patterns.md) |
+| 理解需求与选择能力 | [开发流程](references/development.md)、[架构](references/concepts.md) |
+| 模型、CRUD、字段与移动表单 | [业务模块](references/application-foundation.md)、[字段](references/field-components.md) |
+| 图片压缩、缩略图、附件和缓存 | [图片与附件读取](references/field-components.md#图片缩略图和附件读取)：卡片优先缩略图，原图按需，使用平台权限与缓存规则 |
+| 页面、标准组件与扩展 | [前端](references/frontend.md) |
+| 角色、行和字段权限 | [数据与权限](references/data-authz.md) |
+| 外部无账号表单、续填、上传、本人记录 | [匿名公开访问](references/public-access.md) |
+| 审批、待办、消息或事件 | [工作流与通知](references/workflow-events.md) |
+| 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
+| 管理成员或查看有效流程参数 | [应用管理](references/administration.md) |
+| 检查、部署、生产发布与故障恢复 | [验收](references/testing.md)、[交付](references/delivery.md) |
+| 需求记录与版本升级 | [全流程记录](references/appspec.md)、[升级](references/upgrading.md) |
+| 选择 CLI/MCP 操作 | [命令](references/cli.md)、[MCP](references/mcp.md) |
+
+用户仅要求分析时不自动创建或发布。无行为变化不创建需求/架构记录；按实际风险决定验证深度。技术细节在已有要求内处理，新的业务含义、权限扩大或未授权外部变更才需要用户决定，已有明确授权不重复请求。
+
+## 引导开发并持续记录
 
-1. Read [Commands](references/commands.md) when selecting a CLI operation. It is generated from the executable registry. `create` owns application binding and initialization, while `check`, `deploy` and `status` expose the current workspace and deployment facts.
-2. Read [Discovery](references/discovery.md), turn the request into actors, scenarios, data, permissions, constraints and acceptance evidence, and identify every unresolved choice.
-3. If the workspace contains `appspec/`, the user asks to maintain requirements, or the task changes observable behavior, read [AppSpec](references/appspec.md), load the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID. AppSpec is optional and never a release gate; L0 changes create no record.
-4. Read [Architecture](references/architecture.md), assign one owner to each capability and keep ordinary CRUD on platform Data API.
-5. For every resource or permission change, read [Data and authorization](references/data-authz.md) before editing `openxiangda.config.ts`.
-   When a custom authenticated page lets business users maintain application-role memberships or delegate that maintenance authority, also read [Frontend](references/frontend.md). Use the current-user role-management browser SDK documented there; never add actor selection, an application-owned grant table, or a proxy authorization service.
-6. If the request mentions external users without platform accounts, anonymous or guest access, a public form/page, resumable submission, duplicate checks, public uploads, or letting a visitor read their own submissions, read [Anonymous public access](references/public-access.md). Use the declared platform contract; do not invent a guest role, public Native Data API, fingerprint identity or application-owned token.
-7. Read [Frontend](references/frontend.md) for pages or fields and [Backend actions](references/backend.md) only for a real business action.
-   When the request customizes the application Todo center or the common PC/mobile frame around standard user pages, use only `standardUserSurfaces` from that reference. The platform must keep ownership of the Router, `RuntimeBoundary`, current user, Notification Hub and Workflow controllers.
-8. When the application explicitly enables standard approval, application events or notifications, read [Workflow, Events and Notification Hub](references/workflow-events.md). Keep them optional and out of ordinary CRUD.
-9. Run the connected loop with `pnpm openxiangda dev`, then follow [Testing](references/testing.md) and `pnpm openxiangda check`; check performs the target platform's read-only Native compatibility preflight before application checks or builds.
-10. Follow [Delivery](references/delivery.md): deploy preproduction first, inspect status/logs, then promote the exact successful version to production.
+每轮先读取当前 AppSpec 总纲、设计索引、相关能力、活动变更与契约，按稳定 ID 恢复已知事实、候选建议和未决项。设计文件相互引用而不重复定义规则；角色、权限、页面或入口范围改变时，同步受影响 PRD、旅程、交互、架构和 AC。具体工作法按需读取[产品设计](references/product-design.md)。
 
-For an AI-native client, start the workspace protocol through the same pinned executable:
+总纲维护领域与模型关系、PC/移动任务页面、页面/操作/行/字段权限、多角色组合和容量预算。新增功能先评估影响，普通 CRUD、流程、消息等复用平台能力。明确数据量、分页/索引、请求次数、并发/批量和延迟目标，避免无界全量读取、逐行请求与无限重试。
+
+新应用和改变业务含义的工作，先以实际用户答复和设计内容摘要形成评审，确认 readyForImplementation 后再写实施任务；纯文案和无行为调整引用已有有效基线，不新建评审或重复确认。不能只改摘要或虚构确认让检查通过；工具结构检查不证明体验合格。本轮 ChangeSpec 关联评审、需求依据、方案、任务、源码、AC 场景和验收证据；多个变更时用提交说明 `AppSpec: <ID>` 指明本次交付。测试发布前完成设计和计划，部署后按实际角色、拒绝路径和性能样本验收。生产使用绑定测试运行及包摘要的 `appspec/verification/<运行ID>.json`。更新当前规则后归档，保留未覆盖项、失败原因、发布指针和交接。不可编造需求确认或通过结果；参见 [AppSpec](references/appspec.md)。
+
+## 使用当前事实
+
+MCP 从项目锁定的 CLI 启动：
 
 ```bash
 pnpm exec openxiangda --mcp-stdio --cwd <workspace>
 ```
 
-Read `openxiangda://workspace/contracts` or call `contract_describe`. For first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration; never treat the proposal as runtime discovery. 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.
-
-Authenticated browser routes use the current logged-in user's complete application-role union. An application that serves every logged-in platform user may declare one existing package role through `authz.authenticatedUserRoleCode`; the platform materializes that role on first access and unions it with manual and business-projected roles. Do not fake the role in React, use a membership resource for a universal audience, or confuse the baseline access role with business membership. The only no-account exception is an exact static user route declared through `frontend.publicAccess`; it uses a platform-issued HttpOnly browser credential and dedicated `createAnonymousPublicClient` operations. It is not an application role, login session or general Data API identity. For both paths the platform remains authoritative for capabilities, fields, rows and RLS. A declared Perspective is only a read projection over the authenticated 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 either identity, persist a platform token, construct an authorization result or keep a second permission state.
-
-Applications own one explicit typed admin navigation declaration. The compiler
-owns page/route generation, but it never turns every generated resource or
-Workflow into a menu item; the Shell renders only declared navigation and then
-filters it by authorization. Keep page existence, route reachability and menu
-visibility separate. Use resource mutation ownership and per-operation
-generated surface flags, and give only self-contained `standalone` Workflow
-launch pages a menu entry.
-
-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)
-- [Commands](references/commands.md)
-- [Architecture](references/architecture.md)
-- [Workspace agent contract](references/workspace.md)
-- [Backend actions](references/backend.md)
-- [Data and authorization](references/data-authz.md)
-- [Anonymous public access](references/public-access.md)
-- [Frontend](references/frontend.md)
-- [Workflow, Events and Notification Hub](references/workflow-events.md)
-- [Testing](references/testing.md)
-- [Delivery](references/delivery.md)
-
-Workflow and Notification Hub are optional 2.0 modules outside the CRUD golden path. Never add their packages, routes, declarations or runtime workers to an application that does not enable them.
+先读取 workspace_context，再按需调用 docs_read、contract_describe、administration_context 或 workflow_node_configurations。docs_read 不传 topic 时返回目录，使用其中的 id 读取正文；主题 ID 与本 Skill 参考文件名一致，例如命令专题为 cli。`openxiangda://workspace/contracts` 提供契约索引；按 selector 读取正文，aiCatalogDigest 随当前声明生成。字段、角色、管理员运行参数和部署状态都取自当前结果，不把示例值当成平台默认值。
+
+平台拥有身份、授权、业务数据、环境和部署状态。应用只声明自己的模型、页面和规则；普通 CRUD 走 Data API，标准审批和通知按需声明，真实业务动作才启用 Nest。编译器生成契约，应用不改生成输出、不维护第二份权限或能力目录。菜单建议只供初次复制到应用声明，不是运行时自动发现。
+
+匿名访问使用 frontend.publicAccess、createAnonymousPublicClient 与平台浏览器凭证，不建立 guest 角色或公开普通 Data API。角色并集来自当前用户，Perspective 只收窄读取。
+
+## 完成与失败
+
+开发开始先同步绑定仓库的远端默认主分支。开发完成包括源码、生成契约与必要记录的提交、推送和主线整合；发布从干净且同步的主分支冻结候选。任务分支已推送不代表进入主线。同一工作区保持一个写者，不覆盖其他会话未提交内容。日常 dev/check 可验证未提交源码。
+
+只验证时运行 check/check_app；授权部署时直接 deploy/deploy_app，它已经包含检查并默认跟踪平台完成，长步骤持续反馈阶段和耗时。生产显式复用成功测试运行。观察中断用 status <运行ID> --watch 或 deployment_status.watch 继续查询原运行。登录、创建及长期 dev 使用 CLI/终端，分别记录本地验证、部署激活和真实业务验收。
+
+失败保留错误码、指针与原候选。结果不确定先查平台，不生成新的随机幂等键掩盖原运行；仅执行平台允许的恢复。升级项目后刷新资料并重启旧 MCP 连接。
+
+指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。

package/skills/openxiangda-v2/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "OpenXiangda 2.0"
-  short_description: "Build internal and anonymous public OpenXiangda 2.0 apps"
-  default_prompt: "Use $openxiangda-v2 to build and validate this OpenXiangda 2.0 application."
+  short_description: "开发、校验与交付 OpenXiangda 2.0 应用"
+  default_prompt: "使用 $openxiangda-v2 按当前项目版本开发和验证应用。"

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

@@ -0,0 +1,27 @@
+# 应用管理与有效配置
+
+平台的应用管理控制台维护应用成员、角色授权和流程运行参数。应用自身声明的 `/admin` 业务菜单展示业务页面，两者职责不同。可见入口和可执行操作以当前用户与目标环境返回结果为准。
+
+## 发现当前入口 {#context}
+
+```bash
+pnpm openxiangda admin context --environment test --json
+```
+
+MCP 对应 `administration_context`。先检查返回的管理能力与入口，再进入平台标准管理页面。普通开发者不因拥有源码就自动获得成员管理或流程配置权限；拒绝时联系有权管理员，不伪造用户、租户或权限头。
+
+## 查看流程节点配置 {#workflow}
+
+```bash
+pnpm openxiangda admin workflow <workflowCode> --environment test --json
+```
+
+MCP 对应 `workflow_node_configurations`。workflowCode 来自当前应用声明。管理员运行配置可能已经覆盖开发默认值；不要只看本地文件推断线上处理人。已创建任务保留其冻结配置，后续节点进入采用适用的新运行配置，具体版本以接口返回为准。
+
+生产读取必须显式指定 production。两个命令均为只读发现，成员/角色和流程参数修改通过已授权的标准管理入口执行。
+
+## 业务页面中的角色管理 {#role-management}
+
+确有业务需要时，使用 `openxiangda/core` 的角色管理 SDK。目录提供可管理角色、动作与授权范围；业务角色只能维护管理员已委托的范围。进一步委托要求 management.delegate，并受已有目标角色及动作子集限制。
+
+成员和委托修改带 UUID operationId、原因，更新/撤销带最新 expectedRevision；冲突后重新读取。应用不另建授权表、选择 actor 或自行保存权限快照。SDK 和当前用户数据边界见[权限](data-authz.md)。