openxiangda-skill-kit 2.0.0-alpha.12

package/docs/delivery.md

@@ -0,0 +1,71 @@
+# 构建与交付
+
+## AppPackage
+
+一个包绑定同一提交的前端、后端镜像、配置、生成契约、依赖锁和平台契约范围。构建输出使用内容摘要密封；修改任一部分都会产生新的 AppVersion。
+
+`deploy` 在发起任何网络请求前会再次计算 AppPackage、每个制品和前端包内每个文件的 SHA-256，并校验大小、入口文件、组件 manifest 指向、后端 OCI digest 以及 config/contracts 资源清单。构建完成后被替换、遗漏或来自另一提交的文件会在本地直接失败，不能进入上传阶段；平台收到后还会独立重复校验，客户端校验不能替代服务端信任边界。
+
+## DeploymentRun
+
+```mermaid
+stateDiagram-v2
+  [*] --> Queued
+  Queued --> Validating
+  Validating --> Preparing
+  Preparing --> Deploying
+  Deploying --> Verifying
+  Verifying --> Activating
+  Activating --> Succeeded
+  Validating --> Failed
+  Preparing --> Failed
+  Deploying --> Failed
+  Verifying --> Failed
+  Activating --> Failed
+```
+
+平台持久保存每个检查点、输入摘要、重试分类和关联日志。客户端只创建或查询运行，因此发布不会依赖某个 AI 会话持续在线。
+
+## 标准门禁
+
+1. 本地 AppPackage/制品/组件清单一致性校验；
+2. 平台端契约兼容、摘要与制品完整性复验；
+3. 配置预检及 Secret 准备；
+4. Kubernetes 资源 apply；
+5. liveness/readiness 与平台回调探测；
+6. 前端和配置版本激活；
+7. 审计、通知和可观测关联。
+
+失败默认不切换当前版本。重试复用同一 AppVersion 和幂等键。promotion 复用同一 AppVersion；rollback 是激活历史版本的新 DeploymentRun，不在服务器上现场改文件。
+
+## 版本管理
+
+Changesets 固定组同步发布所有 `openxiangda-*` 包、CLI、MCP 与 skill-kit。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。
+
+`release:publish` 在真正写 registry 前执行不可变版本门禁：未发布版本进入候选集；已经发布的版本则分别解包 registry 工件和当前本地包并逐文件比较。相同内容视为未变包，不重复发布；任何内容差异都必须先用 Changesets 产生新版本；没有新版本时拒绝空发布。发布范围、版本和是否允许写入由机器判定，不由 AI 临场决定。
+
+`pnpm verify:local` 是日常可重复执行的、完全不发包的完整验收入口；`pnpm verify:release` 复用同一门禁。它们只验证原生 2.0 工作区，不运行 1.x 兼容测试。除类型检查、单测、模板、技能和文档门禁外，还会执行发行物黑盒验证：打包所有公开 2.0 包，检查 tarball 内的 `exports`、bin 和依赖协议，在 monorepo 外安装这些 tarball，通过其中的 `create-openxiangda` 创建全新应用，然后执行新应用的生成、检查、单测、真实 Chromium Admin 验收与生产构建。这样 `workspace:*` 链接、未打包的本地文件或只有 jsdom 能通过的交互都不能掩盖坏包。
+
+Playwright 浏览器使用官方缓存目录；`playwright install chromium` 已安装对应版本时是无操作。发包门禁不会额外运行 1.x 测试，也不会为每个包重复浏览器验收，而是在最终独立新应用上只运行一次完整用户路径。
+
+工具仓还会把同批本地包发布到一次性、仅绑定 `127.0.0.1` 的 registry，使用持久独立 reference app 再执行一次安装、契约生成、类型检查、单测、真实 NestJS 身份/Data API 进程验收和生产构建。`pnpm reference:install:from-build` 可在未公开发包时通过同一 registry 协议刷新 reference worktree 的本地依赖，避免 `file:`/`link:` 破坏独立性。
+
+门禁先用 Turbo 完成一次全工作区 check/test/build；后续生成契约检查、tarball 黑盒、技能校验和文档构建复用这批已验证的 `dist`，不会各自再次触发全仓构建。`distribution:smoke`、`skills:check`、`docs:build` 仍保留可独立执行的自包含入口，只有 `verify:local` 内部使用 `:from-build` 阶段命令。
+
+官方工作区使用 pnpm 10 的显式依赖构建策略：只允许经过审核的 `esbuild` 生命周期脚本，并启用 `strictDepBuilds`。未来依赖若新增 install/postinstall 脚本，安装会直接失败，必须先审查并更新策略；发行物黑盒验证同时拒绝任何“已忽略构建脚本”警告，避免开发机缓存掩盖不完整安装。
+
+只运行发行物验证：
+
+```bash
+pnpm distribution:smoke
+```
+
+## 平台契约列车验收
+
+当同一候选版本还修改了 OpenXiangda 2.0 平台接口时，平台服务必须先运行自己的独立门禁：
+
+```bash
+npm run verify:openxiangda-v2
+```
+
+该门禁校验平台 SQL migration、自动发现所有 2.0 测试、运行共享出站 HTTP/存储安全测试并完成平台编译。它与 `pnpm verify:release` 分工明确：前者证明平台实现，后者证明独立 SDK、CLI、技能、模板和真实 tarball 新应用。两边都通过后才可进入人工发布确认；任何一个命令都不会自动提交、发包或部署。

package/docs/frontend.md

@@ -0,0 +1,46 @@
+# 前端
+
+`openxiangda-admin` 提供标准 B 端应用外壳：响应式布局、多级菜单、路由、面包屑、固定与可关闭缓存标签、个人中心、权限点、稳定角色会话、标准数据管理页、工作流任务页面和应用自定义操作注册。
+
+## 页面组成
+
+- 菜单与路由使用同一份贡献声明，路由守卫通过批量授权接口一次解析当前页面的 capability；前端按 RoleSession 缓存和去重，服务端仍是最终授权边界。
+- Data API 与 App API 使用类型化客户端，不在组件中拼接平台 URL。
+- 当前角色是显式会话状态。角色选项同时展示业务数据范围，解决同一用户拥有多个同名角色绑定时的歧义。切换角色后重新获取 capability、数据范围与待办，并恢复该角色自己的缓存标签；不会把多个角色权限隐式合并。RoleSession 在到期前自动续期，浏览器从休眠恢复时再次校验；短暂网络故障会保留最后一个可用会话并提供就地重试，不会把整个应用切换成错误页。
+- 缓存标签按应用和角色绑定写入浏览器会话，刷新后恢复仍存在且允许缓存的路由；被移除、禁用缓存或超出数量上限的路由不会复活。业务路由使用独立错误边界，局部渲染错误不会导致整个应用白屏。
+- 标准数据管理模块把搜索字段转换成 Data API filter，并在服务端处理分页、排序、修订冲突和错误展示；搜索区折叠、列显隐、密度、跨页选择和批量业务动作是统一扩展点。分页大小、表格密度、可见列与搜索展开状态按应用/角色绑定/资源保存；异步查询按序列丢弃过期响应，失败时提供就地重试。
+- `department`、`user` 和 `relation` 可直接用于列表搜索与编辑表单。`DepartmentText` / `UserText` 把持久化 ID 批量解析成可读名称，按应用、RoleSession 和类型隔离缓存，解析失败时安全回退到原始 ID。
+- 标准数据编辑表单从 DataResource 生成类型化基础控件，应用只需声明业务标签、枚举选项、帮助信息和少量覆盖；JSON、日期时间和保存错误由框架统一处理。字段读写权限统一来自 DataResource 的 fieldPolicies：不可读字段不会出现在列表、搜索、导出和表单中，只读字段不能提交修改，应用管理员明确 bypass。
+- 标准数据列表默认提供“查看”入口和行详情抽屉。详情抽屉复用 Data API 单记录接口，按字段策略展示业务字段，并以时间线显示当前记录的持久业务审计；操作者名称通过 Directory v2 解析，加载、空状态、失败和重试都有统一交互。
+- `file` 字段使用平台托管附件组件：浏览器按签名计划直传对象存储，完成校验后只把稳定 `DataFileRef` 写入业务记录；查看和下载仍通过 Data API 执行行权限及字段权限。应用不能拼对象存储地址或保存临时签名 URL。
+- 数据导出沿用当前服务端 filter/order 并按权限裁剪字段；CSV 防公式注入并限制最大导出量。导入先本地解析与类型预检，再以最多 100 个操作的受限事务批次提交，每批使用稳定幂等键，支持失败后安全重试。
+- `DashboardPage`、`MetricCard`、`DataCountMetric`、`DataAggregateChart`、`DataDistributionChart`、`DataTrendChart` 和 `DashboardSection` 提供 RoleSession 约束的标准概览页。图表使用服务端受限聚合，ECharts 运行时按需加载；指标查询丢弃过期响应并提供独立错误恢复，不要求每个应用重复搭建卡片、图表与加载状态。
+- `ApplicationOperationsPage` 提供应用管理员运行视图：平台契约、当前身份、后端 readiness/version、不可变 AppVersion 最近部署、事件重试/死信和 `eventId/requestId/traceId` 关联信息集中展示；事件订阅与定时事件可按 revision 暂停/启用，重试或死信可显式创建新投递并保留原记录。各探针独立失败，不会因为一个依赖不可用而把整页变成白屏，诊断快照可一键复制。
+- 生产应用从 `openxiangda-admin/core`、`/data`、`/dashboard`、`/workflow` 子路径导入，并用 `React.lazy` 声明业务路由。官方模板的构建门禁要求首页、数据页和流程页保持独立异步 chunk，同时限制单 chunk 与首屏 JavaScript 预算；新增页面不能重新退化成完整 Admin/Ant Design 一次性加载。
+- 工作流页面按后端返回的 actions、fieldPolicy 和 presentation 渲染按钮与字段。业务记录由 Data API/App API 加载，`edit_required` 在操作前验证，变更以 revision 乐观锁先保存后执行流程命令；Workflow Kernel 不保存业务字段。
+- 个人中心内置长期流程代理。选择代理人后必须再选择其具体应用角色绑定和数据范围，代理始终绑定发起人的当前稳定身份，不合并其他角色权限。
+
+## 自定义操作
+
+自定义操作是应用定义的业务动作，例如“校验预约冲突”“计算费用”“确认到场”。前端通过 `WorkflowActionContribution` 注册协议化表单，执行器调用当前环境的 NestJS App API；后端用 Principal、capability、Data API revision/幂等事务决定最终业务变化。它不是 Workflow Kernel 的隐藏命令，操作后的异步副作用继续通过事件处理。
+
+## 质量门禁
+
+页面测试至少覆盖路由授权、角色切换、服务端拒绝、修订冲突和关键工作流动作。官方模板还用 Playwright 在真实 Chromium 中验收桌面布局、移动端抽屉、权限裁剪导航、搜索/列设置/密度、个人中心、身份切换、数据编辑、缓存标签恢复以及身份初始化失败后的重试恢复。不要把后端规则复制成只能在浏览器生效的判断。
+
+Admin 框架的缓存只保存界面偏好和逻辑路由，不缓存 Token、权限判定或业务数据。页面可以通过 `persistPreferences={false}` 完全关闭列表偏好的读取与写入。
+
+## 发布前本地验收
+
+官方模板的 Vite 开发服务默认装载内存平台 Mock，包含申请人、学院管理员、仪器管理员和应用管理员四种身份，以及长期代理、批量授权、Directory v2、字段权限、Data API 查询/CRUD/单记录详情/审计/受限聚合/托管附件/受限事务、Workflow Kernel 发起与完整审批操作、应用自定义动作、事件订阅/定时器暂停和死信重放。这样新应用无需 provision 或发布即可验证完整 Admin 交互：
+
+```bash
+pnpm dev
+pnpm test:e2e
+```
+
+`pnpm test:e2e` 会自行启动只绑定 `127.0.0.1` 的 Vite + 本地平台 Mock；失败时保留 trace、截图和视频。用例必须通过可访问角色和标签定位交互，不能依赖 Ant Design 私有 DOM 结构。
+
+切换到“应用管理员”后可进入“运行与诊断 → 本地故障实验室”，为匹配的下一次请求注入身份 401、授权 403、修订冲突 409、后端 503 或 3 秒数据延迟；规则默认命中一次并可随时清空，用于验证标准错误、重试和恢复交互。
+
+设置 `OPENXIANGDA_PLATFORM_PROXY=https://platform.example.com` 可改为真实平台；设置 `OPENXIANGDA_LOCAL_MOCK=false` 可关闭 Mock。故障控制端点只存在于 Vite dev server，生产构建不会包含它。本地链接 SDK 的 dist 发生变化时，模板使用整页刷新，避免 React Context 被组件级 HMR 拆成两个实例。

package/docs/getting-started.md

@@ -0,0 +1,120 @@
+# 开始开发
+
+## 创建应用
+
+```bash
+openxiangda app create my-app --app-code my-app --name "My App" --install
+cd my-app
+openxiangda skill install
+OPENXIANGDA_TOKEN="$TOKEN" openxiangda auth login --base-url https://platform.example.com
+openxiangda app link --base-url https://platform.example.com
+openxiangda app provision
+openxiangda app info
+```
+
+开发 2.0 工具链本身时，不需要先发布 alpha 包。创建一个独立验收应用并把依赖链接到本地源码：
+
+```bash
+openxiangda app create ../my-local-validation \
+  --app-code my-local-validation \
+  --name "Local Validation" \
+  --local-sdk /absolute/path/to/openxiangda-v2 \
+  --install
+```
+
+带 `--install` 时，创建器先写依赖映射并安装，再执行确定性契约生成；新应用第一次执行 `generate --check` 就应通过。省略 `--install` 时结果会标记 `generationDeferred: true`，需要先运行 `pnpm install`，再运行 `openxiangda generate`。`--local-sdk` 会写入机器相关的 pnpm `link:` overrides，只用于可丢弃的本地验收应用。
+
+应用始终调用工作区本地 `openxiangda-cli`；本地依赖未安装时直接失败，不存在 1.x 回退。`skill install` 会同时安装领域 Skills 与其引用的 2.0 参考文档。
+
+创建结果是普通 pnpm workspace：
+
+```text
+apps/web                 React + Ant Design
+apps/server              NestJS
+packages/domain          业务类型与规则
+packages/contracts       平台生成契约
+openxiangda.config.ts    应用级平台声明
+```
+
+## 日常循环
+
+```bash
+openxiangda dev
+openxiangda generate
+openxiangda check
+openxiangda test
+pnpm dev
+pnpm test:e2e
+```
+
+`generate` 根据配置生成 Data、AuthZ、Event 与 Workflow 类型。`check` 必须是确定性的：同一提交、同一依赖锁、同一配置产生同一结果。
+
+开发 2.0 工具链本身时，每一轮可用一个命令完成发布前同等级的本地验收：
+
+```bash
+pnpm verify:local
+```
+
+它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、Chromium 交互、生产构建、Skill 和文档，不会执行 npm 发布、Git 提交或平台部署。
+
+## OAuth2 应用身份
+
+外部系统或后台任务通过平台托管的 OAuth2 client credentials 获取短期 token，不使用用户 RoleSession。客户端 Secret 只在创建或轮换时返回一次：
+
+```bash
+openxiangda oauth client create --name erp-sync \
+  --environment development \
+  --scope app:invoke \
+  --scope data:read
+openxiangda oauth client list
+openxiangda oauth client rotate <client-id> --grace-period-seconds 600
+openxiangda oauth audit list --limit 100
+```
+
+NestJS App API 使用 `@RequireCapability` 验证服务身份 scope；Workflow 操作仍强制用户 RoleSession，不允许服务身份代替审批人。
+
+应用后端自己的 workload client 由平台托管，不向开发者显示 Secret。查询状态或主动轮换时使用专门命令：
+
+```bash
+openxiangda oauth runtime status --environment development
+openxiangda oauth runtime rotate --environment development \
+  --grace-period-seconds 600 \
+  --idempotency-key runtime-rotation-20260812
+```
+
+`runtime rotate` 先以当前 credential version 做 CAS 暂存，再对该环境当前激活的同一个 AppVersion 创建滚动 DeploymentRun。新 Secret 只在平台内部写入 Kubernetes Secret；新 Pod 就绪后使用新凭据，旧 Pod 在宽限期内仍可换 token。命令重试必须复用同一个幂等键，不重建或篡改应用版本。
+
+## 环境 Secret 与运行维护
+
+`openxiangda.config.ts` 只声明后端需要的 Secret 名称和注入环境变量，值不会进入源码或 AppPackage。可先在本地/测试环境配置，再部署应用：
+
+```bash
+APP_SECRET='development-only-value' \
+  openxiangda secret create dingtalk-client-secret \
+  --environment development \
+  --from-env APP_SECRET
+
+openxiangda event subscription list
+openxiangda event delivery list
+openxiangda workflow provider list --environment development
+```
+
+事件死信通过 `event delivery replay` 显式重放；Workflow Provider 密钥轮换要在下一次成功部署后才激活。
+
+## 构建与发布
+
+应用 CI 先构建并推送后端镜像，再将不可变镜像摘要交给 CLI：
+
+```bash
+openxiangda build --backend-image registry.example.com/apps/my-app@sha256:...
+openxiangda deploy development --backend-image registry.example.com/apps/my-app@sha256:...
+openxiangda status <deployment-id>
+```
+
+CLI 上传应用包并创建 DeploymentRun；部署、重试、健康检查和激活都由平台执行。CLI 退出不影响发布继续进行。
+
+`app provision` 只用于首次创建平台中的稳定 2.0 应用身份，可安全重试，且需要平台管理员身份。日常 CI 使用该应用的发布权限即可，不需要平台管理员。
+
+## AI 入口
+
+AI 先读取 `openxiangda://workspace/context`，再使用 MCP 的 `check_app`、`run_tests`、`build_app` 等结构化工具。会改变环境的工具必须在用户明确授权后调用。

package/docs/index.md

@@ -0,0 +1,23 @@
+---
+layout: home
+hero:
+  name: OpenXiangda 2.0
+  text: 把平台应用当作真正的软件工程
+  tagline: 标准 React 前端、NestJS 后端、统一 Data API、上下文权限、Workflow Kernel v2、事件订阅与应用级交付
+  actions:
+    - theme: brand
+      text: 开始开发
+      link: /getting-started
+    - theme: alt
+      text: 阅读架构
+      link: /concepts
+features:
+  - title: 一个应用，一个版本
+    details: 前端、后端、配置契约和生成类型共同构成不可变 AppVersion。
+  - title: 平台托管后端
+    details: 每应用独立容器，共享 Kubernetes 集群资源，由平台完成部署与身份注入。
+  - title: AI 可用但不依赖 AI 发布
+    details: CLI、MCP 和 Skills 共用确定性服务；平台持久化执行部署，不让会话承担状态机。
+---
+
+OpenXiangda 2.0 保留平台统一数据与治理能力，同时把应用开发恢复成成熟的前后端工程。本工具链只面向 2.0 应用；旧应用由独立的 1.x 产品线维护。

package/docs/llms.txt

@@ -0,0 +1,12 @@
+# OpenXiangda 2.0 documentation
+
+- /getting-started.md: standard workspace and development loop
+- /concepts.md: application, platform, data, runtime, and version boundaries
+- /frontend.md: React admin shell, role session, CRUD, workflow UI
+- /backend.md: NestJS modules, identity, Data API, health, secrets
+- /data-authz.md: RBAC plus contextual data and field authorization
+- /workflow-events.md: Workflow Kernel v2, providers, actions, durable events
+- /delivery.md: immutable AppPackage and platform-owned DeploymentRun
+- /architecture/repository-and-release.md: standalone 2.0 repository and release boundaries
+- /reference/cli.md: generated CLI commands
+- /reference/mcp.md: generated MCP resources and tools

package/docs/reference/cli.md

@@ -0,0 +1,51 @@
+# CLI Reference
+
+> Generated from `DEVKIT_COMMANDS`. Do not edit manually.
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `auth login` | write-local | 保存 2.0 平台登录会话 |
+| `auth status` | read | 查看当前登录会话 |
+| `auth logout` | write-local | 删除当前登录会话 |
+| `app create` | write-local | 从官方模板创建 2.0 应用 |
+| `app link` | write-local | 绑定平台地址和应用环境 |
+| `app provision` | deploy | 在平台幂等创建 2.0 应用身份 |
+| `app info` | read | 读取应用工作区上下文 |
+| `oauth client list` | read | 查询应用 OAuth2 客户端 |
+| `oauth client create` | deploy | 创建环境绑定的 OAuth2 客户端 |
+| `oauth client update` | deploy | 更新 OAuth2 客户端 |
+| `oauth client rotate` | deploy | 双密钥轮换 OAuth2 客户端 |
+| `oauth client revoke` | deploy | 吊销 OAuth2 客户端 |
+| `oauth runtime status` | read | 查询平台托管运行凭据状态 |
+| `oauth runtime rotate` | deploy | 暂存运行凭据并创建同版本滚动部署 |
+| `oauth audit list` | read | 查询 OAuth2 审计事件 |
+| `secret list` | read | 查询环境隔离的应用 Secret 元数据 |
+| `secret create` | deploy | 从本机安全来源创建应用 Secret |
+| `secret update` | deploy | 更新应用 Secret 元数据和状态 |
+| `secret rotate` | deploy | 追加不可变版本并轮换应用 Secret |
+| `secret delete` | deploy | 删除未被当前配置引用的应用 Secret |
+| `secret audit list` | read | 查询应用 Secret 审计事件 |
+| `event subscription list` | read | 查询应用事件订阅 |
+| `event subscription status` | deploy | 暂停或恢复事件订阅 |
+| `event subscription rotate-secret` | deploy | 暂存下一版本事件签名密钥并随下次部署激活 |
+| `event delivery list` | read | 查询事件投递与死信 |
+| `event delivery replay` | deploy | 幂等回放历史事件投递 |
+| `event timer list` | read | 查询定时事件 |
+| `event timer status` | deploy | 暂停或恢复定时事件 |
+| `workflow provider list` | read | 查询 Workflow Assignee Provider |
+| `workflow provider rotate` | deploy | 轮换 Workflow Provider 签名密钥 |
+| `skill install` | write-local | 安装 OpenXiangda 2.0 AI Skills |
+| `skill validate` | read | 验证 OpenXiangda 2.0 AI Skills |
+| `dev` | write-local | 启动标准前后端开发进程 |
+| `generate` | write-local | 生成 Data/App/Workflow/Event 类型契约 |
+| `check` | read | 确定性检查完整应用 |
+| `test` | read | 运行应用测试 |
+| `build` | write-local | 构建并密封一个 AppPackage |
+| `deploy` | deploy | 创建平台持久执行的 DeploymentRun |
+| `promote` | deploy | 以同一 AppVersion 晋级目标环境 |
+| `status` | read | 查询 DeploymentRun 状态 |
+| `logs` | read | 查询部署检查点和关联日志 |
+| `retry` | deploy | 重试可恢复的 DeploymentRun |
+| `cancel` | deploy | 幂等取消 DeploymentRun |
+| `rollback` | deploy | 以历史 AppVersion 创建回滚部署 |
+| `doctor` | read | 诊断本地工具链和平台兼容性 |

package/docs/reference/mcp.md

@@ -0,0 +1,26 @@
+# MCP Reference
+
+> Generated from the MCP server registry. Do not edit manually.
+
+## Resources
+
+- `openxiangda://workspace/context`
+- `openxiangda://workspace/contracts`
+- `openxiangda://platform/capabilities`
+- `openxiangda://deployments/latest`
+- `openxiangda://docs/index`
+
+## Tools
+
+- `workspace_context`
+- `contract_describe`
+- `generate_contracts`
+- `check_app`
+- `run_tests`
+- `build_app`
+- `deployment_plan`
+- `deploy_app`
+- `deployment_status`
+- `deployment_logs`
+- `retry_deployment`
+- `rollback_app`

package/docs/workflow-events.md

@@ -0,0 +1,63 @@
+# 工作流与事件
+
+## Workflow Kernel v2
+
+Workflow Kernel v2 专注审批语义：版本化定义、条件分支、审批任务、同意、拒绝、转交、回退、代理、加签、审批人解析、提交预览、主部门选择、字段策略、允许操作与审计。
+
+业务字段始终由 Data API 或 App API 保存。流程内核仅保存定义、实例、节点、任务、动作、参与者快照、字段策略和关联业务记录 ID。
+
+标准任务页使用实例的 DataRef 加载业务记录，并按节点 `fieldPolicy` 控制字段。`edit` 与 `edit_required` 的变化在流程命令前先写入 Data API，使用记录 revision 防止覆盖他人修改；采用 App API 存储的应用注入等价 loader/saver。流程命令失败不会把业务数据偷偷写进 Kernel。
+
+任务级操作包含同意、拒绝、退回、重新提交、转交、任务代理和前/后加签；实例级操作包含发起人撤回和应用管理员终止。一个正在审批的任务 Surface 可以同时返回任务级与实例级操作，例如应用管理员在任务仍活动时仍能终止实例。Admin 执行器按操作类型选择任务或实例命令，不以“当前页面有没有任务”猜测请求目标；撤回和终止也不会被当前审批节点的必填业务字段误拦截。
+
+长期代理绑定委托人的当前 RoleAssignment，以及代理人的明确 RoleAssignment。平台提供代理目标身份查询，页面同时展示角色和 scope grant；多角色用户不会因为只选择了人员而获得错误的数据范围。任务级转交/代理仍由当次 Surface 的操作协议控制。
+
+## Provider 与自定义操作
+
+审批节点只保留简单声明。需要读取应用数据的审批人解析、动作可用性或业务校验，由应用后端实现 provider 契约。自定义操作由前端 contribution 声明表单和展示，执行器调用 NestJS App API；后端按 Principal/capability 执行 Data API 或外部系统逻辑并使用幂等键。自定义操作不扩展 Kernel 状态机，异步副作用交给事件。
+
+## 前端协议
+
+任务详情返回：
+
+- 当前定义与任务修订；
+- `operations`（含输入 JSON Schema、UI Schema、执行目标、可见/可用状态与刷新范围）；
+- fieldPolicy；
+- presentation；
+- assignee/代理/加签上下文；
+- 提交所需 concurrency token。
+
+前端按协议展示，不需要复制内核状态机。协议允许扩展展示元数据，但内核始终校验动作是否合法。
+
+## 事件层
+
+表单数据增删改查、流程状态变化和定时器统一产生类型化事件。订阅目标是应用后端接口。平台负责签名、持久投递、重试、死信、暂停与重放；应用负责验签、幂等和业务处理。
+
+事件首先与业务变更写入同一事务的 outbox，再由 Worker 领取带租约的投递任务。网络失败、408、409、425、429 和 5xx 才进入指数退避；确定性 4xx 直接进入死信，`Retry-After` 优先于本地退避。人工重放要求幂等键，相同键只产生同一条投递：
+
+```bash
+openxiangda event subscription list
+openxiangda event delivery list --limit 100
+openxiangda event delivery replay <delivery-id> \
+  --idempotency-key incident-20260812-replay-1
+```
+
+应用管理员也可在标准“运行与诊断”页面暂停/启用事件订阅和定时事件，并对重试或死信执行重放。重放创建新 delivery，原记录保持不变，便于审计与关联排障。
+
+Nest SDK 默认使用平台托管的持久化 receipt store：它复用当前事件订阅密钥，对 `claim / complete / release` 命令做 HMAC 签名，并把消费状态保存在平台数据库，因此 Pod 重启、滚动部署或多副本运行都不会退化为进程内去重，也不要求应用自建数据库。只有显式注入 `InMemoryOpenXiangdaEventReceiptStore` 时才使用本地进程内实现。
+
+处理器完成后才提交 receipt，异常会释放 claim 以便平台重试。仍在租约内处理的重复投递返回可重试错误；只有状态已经是 `succeeded` 的事件才返回成功重复。对于“外部副作用成功、回执提交前进程崩溃”的固有窗口，处理器仍应把 `event.id` 作为 Data API 受限事务的 `idempotencyKey`，或使用下游系统自己的幂等键；receipt 提供的是可靠的消费领取与完成记录，不虚构跨系统 exactly-once。
+
+## Provider 密钥轮换
+
+Provider 轮换采用部署驱动的双阶段协议。`workflow provider rotate` 只暂存下一版本；下次 Deployment 给新 Pod 同时注入当前密钥和 `_NEXT` 密钥，新 Pod 可验证两者。readiness 成功后平台原子提升下一版本；失败部署继续使用旧版本，不影响现网。API 和 CLI 从不返回轮换后的明文。
+
+```bash
+openxiangda workflow provider list --environment production
+openxiangda workflow provider rotate special-lab-reviewers \
+  --environment production \
+  --revision 3 \
+  --idempotency-key rotate-special-lab-20260812
+openxiangda deploy production \
+  --backend-image registry.example.com/apps/my-app@sha256:...
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "openxiangda-skill-kit",
+  "version": "2.0.0-alpha.12",
+  "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "openxiangda-skill-kit": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "docs/",
+    "README.md"
+  ],
+  "dependencies": {
+    "openxiangda-devkit-core": "2.0.0-alpha.12"
+  },
+  "devDependencies": {
+    "tsx": "4.23.12",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  }
+}

package/skills/manifest.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "skills": [
+    {
+      "name": "openxiangda-v2",
+      "description": "Build, inspect, validate, and deliver a complete OpenXiangda 2.0 application workspace. Use when a task spans the React frontend, NestJS backend, Data API, authorization, workflow, events, or whole-application delivery.",
+      "sha256": "ac22f47182c7e101b66d96e50dac7db238c7deb09904cdc53f389b1a533954a1"
+    },
+    {
+      "name": "openxiangda-v2-architecture",
+      "description": "Design OpenXiangda 2.0 application boundaries and typed contracts. Use when creating an app, decomposing frontend and backend responsibilities, or changing Data, AuthZ, workflow, event, or deployment declarations.",
+      "sha256": "02768b17e048c623a13b9a99e5cedc72c9081eaa71b346c3d9db3ca66c95bf5e"
+    },
+    {
+      "name": "openxiangda-v2-backend",
+      "description": "Build the standard OpenXiangda 2.0 NestJS application backend. Use when implementing App APIs, Data API transactions, identity-aware business services, event consumers, health checks, or external integration endpoints.",
+      "sha256": "c107b1aa914130de821fa9f7b157274d568371c8e4410e5d5d3f03e80f2fb24d"
+    },
+    {
+      "name": "openxiangda-v2-data-authz",
+      "description": "Design OpenXiangda 2.0 Data API and contextual authorization contracts. Use for RBAC, active-role behavior, department or record attributes, application-admin bypass, field policies, and restricted transactions.",
+      "sha256": "5c4a2d4465ea92efcfb64cdcef6b6f80232ea0413bba6c77e7ccb70f9b33e29e"
+    },
+    {
+      "name": "openxiangda-v2-delivery",
+      "description": "Validate, build, deploy, observe, promote, retry, and roll back an OpenXiangda 2.0 application. Use when preparing an immutable AppPackage or changing a platform-managed environment.",
+      "sha256": "66e1df9664a10d66ca2a2f6552c84ac13fc68cfbb8424ef4369bda07b5f9dcdd"
+    },
+    {
+      "name": "openxiangda-v2-frontend",
+      "description": "Build OpenXiangda 2.0 React and Ant Design admin experiences. Use when implementing menus, routes, CRUD pages, role switching, workflow task pages, or application-defined action components.",
+      "sha256": "788b8f32b6cffcbc9c8686d064f570472ae107f3da4f8c5b797ceb0e6b84fe8c"
+    },
+    {
+      "name": "openxiangda-v2-workflow-events",
+      "description": "Implement OpenXiangda Workflow Kernel v2 and durable application events. Use for approval definitions, assignee providers, task actions, delegation, add-sign, previews, data-change events, workflow events, or timers.",
+      "sha256": "ad662800fc0285004e957681f714c157667cba2163c913bdbc519f2762ea9012"
+    }
+  ]
+}

package/skills/openxiangda-v2/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: openxiangda-v2
+description: Build, inspect, validate, and deliver a complete OpenXiangda 2.0 application workspace. Use when a task spans the React frontend, NestJS backend, Data API, authorization, workflow, events, or whole-application delivery.
+---
+
+# OpenXiangda 2.0
+
+Treat the repository as one typed application product. Work through package contracts and deterministic commands; do not mutate platform resources one at a time.
+
+## Start Here
+
+1. Run `openxiangda app info` and inspect the returned workspace and platform contract versions.
+2. Read `openxiangda.config.ts`, then identify which domain skill applies:
+   - architecture: `$openxiangda-v2-architecture`
+   - frontend: `$openxiangda-v2-frontend`
+   - backend: `$openxiangda-v2-backend`
+   - data and authorization: `$openxiangda-v2-data-authz`
+   - workflow and events: `$openxiangda-v2-workflow-events`
+   - delivery: `$openxiangda-v2-delivery`
+3. Keep generated contracts current with `openxiangda generate`.
+4. Before delivery, run `openxiangda check` and `openxiangda test`.
+
+For a new repository, link it to the target platform and let an authorized platform administrator run `openxiangda app provision` once. The command is idempotent and provisions only a native 2.0 application identity.
+
+## Boundaries
+
+- Put browser code in `apps/web`, server code in `apps/server`, shared domain types in `packages/domain`, and generated declarations in `packages/contracts`.
+- Persist business records only through Data API or an App API implemented by the application backend.
+- Treat the active role and context attributes as explicit request state.
+- Use durable event consumers for side effects and idempotency keys for retries.
+- Build one immutable application package; the platform owns deployment execution, health gates, promotion, and rollback.
+- Reject any workspace that does not declare the native 2.0 application configuration.
+
+## Delivery Gate
+
+Use `openxiangda build --backend-image <immutable-image>` only after checks pass. Use `openxiangda deploy`, `openxiangda status`, and `openxiangda logs` only when the user has authorized the environment change.
+
+Read [Getting Started](../../docs/getting-started.md) for the complete development loop.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenXiangda 2.0"
+  short_description: "Build and deliver typed OpenXiangda 2.0 applications"
+  default_prompt: "Use $openxiangda-v2 to build and validate this OpenXiangda 2.0 application."

package/skills/openxiangda-v2-architecture/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: openxiangda-v2-architecture
+description: Design OpenXiangda 2.0 application boundaries and typed contracts. Use when creating an app, decomposing frontend and backend responsibilities, or changing Data, AuthZ, workflow, event, or deployment declarations.
+---
+
+# OpenXiangda 2.0 Architecture
+
+Design one independently versioned application with a standard React frontend and NestJS backend.
+
+## Design Sequence
+
+1. Inspect the workspace with `openxiangda app info`.
+2. Define business aggregates and invariants in `packages/domain`.
+3. Declare Data API resources, capabilities, policies, workflow definitions, event subscriptions, and timers in `openxiangda.config.ts`.
+4. Keep synchronous user interactions in App APIs; move retryable side effects to event consumers.
+5. Use a workflow provider when assignee resolution or a workflow action depends on application data.
+6. Generate types with `openxiangda generate`, then run `openxiangda check`.
+
+## Required Decisions
+
+- Name every resource, capability, event type, workflow, and provider with a stable application-scoped code.
+- Separate business data from workflow runtime state.
+- Define the authorization context needed for each operation, including active role and data attributes.
+- Define idempotency and concurrency behavior before implementing writes.
+- Define health, readiness, and rollback expectations as part of the application contract.
+
+Do not design environment-specific code paths. Environment values and secrets are injected by the platform at deployment time.
+
+Read [Concepts](../../docs/concepts.md) before introducing a new platform-facing contract.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenXiangda 2.0 Architecture"
+  short_description: "Design typed OpenXiangda 2.0 application boundaries"
+  default_prompt: "Use $openxiangda-v2-architecture to design this OpenXiangda 2.0 application."

package/skills/openxiangda-v2-backend/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: openxiangda-v2-backend
+description: Build the standard OpenXiangda 2.0 NestJS application backend. Use when implementing App APIs, Data API transactions, identity-aware business services, event consumers, health checks, or external integration endpoints.
+---
+
+# OpenXiangda 2.0 Backend
+
+Build a normal NestJS service in `apps/server`. The platform deploys one container per application and injects identity, platform endpoints, environment configuration, and secrets.
+
+## Request Path
+
+1. Use the platform guard to verify the user token and construct typed request context.
+2. Authorize the capability and contextual data policy before accessing records.
+3. Keep invariants in domain services, not controllers.
+4. Use Data API for persistence and its restricted transaction endpoint for atomic batches.
+5. Require revision or idempotency keys for retryable writes.
+6. Return stable application contracts and structured errors.
+7. Use single-record reads for details, bounded aggregate queries for reports,
+   and the durable business-audit endpoint for history. All remain scoped to
+   the request RoleSession.
+8. For attachments, initiate a platform-managed upload, upload to the signed
+   plan, complete verification, and persist only the returned `DataFileRef`.
+
+## Runtime Path
+
+- Expose liveness and readiness endpoints.
+- Consume platform events with signature verification and durable idempotency.
+- Keep outbound integrations behind adapters with timeouts and correlation IDs.
+- Declare external credentials in `backend.secrets`; create values with
+  `openxiangda secret create` and rotate them with
+  `openxiangda secret rotate`, using `--from-env` or `--from-file`.
+- Read secrets only from injected environment references; never place values in
+  source, command arguments, application packages, logs, or browser responses.
+- Treat `OPENXIANGDA_OAUTH_CLIENT_*` as platform-reserved workload identity.
+  Inspect it with `openxiangda oauth runtime status --environment <key>` and
+  rotate it with `openxiangda oauth runtime rotate --environment <key>
+  --idempotency-key <stable-key>`. The platform stages by credential-version
+  CAS and rolls the same active AppVersion; no Secret is returned to the CLI.
+
+Use `openxiangda dev` for local orchestration. Run `openxiangda check`, `openxiangda test`, and `openxiangda build --backend-image <immutable-image>` before deployment.
+
+Read [Backend](../../docs/backend.md) for the standard module layout.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenXiangda 2.0 Backend"
+  short_description: "Build standard NestJS application backend services"
+  default_prompt: "Use $openxiangda-v2-backend to implement this OpenXiangda 2.0 backend."