openxiangda-skill-kit 2.0.18 → 2.0.20

package/dist/bin.js

@@ -23,7 +23,7 @@ else {
     const skillsRoot = resolve(process.cwd(), rootArgument || defaultSkillsRoot);
     const metadataFile = optionValue('--distribution-commands');
     const metadata = metadataFile ? JSON.parse(await readFile(resolve(metadataFile), 'utf8')) : null;
-    if (metadata && (metadata.schemaVersion !== 'openxiangda.distribution-commands/v1' || !Array.isArray(metadata.commands) || metadata.commands.some((command) => typeof command !== 'string' || !/^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)+$/.test(command))))
+    if (metadata && (metadata.schemaVersion !== 'openxiangda.distribution-commands/v1' || !Array.isArray(metadata.commands) || metadata.commands.some((command) => typeof command !== 'string' || !/^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*$/.test(command))))
         throw new Error('DISTRIBUTION_COMMAND_METADATA_INVALID');
     const issues = await validateSkills(skillsRoot, { distributionCommandIds: metadata?.commands });
     if (issues.length) {

package/package.json

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

package/skills/openxiangda-v2/SKILL.md

@@ -18,8 +18,8 @@ description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --base-url <平台地址>
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --cwd <应用目录> --base-url <平台地址>
 pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ create <应用目录> --base-url <同一平台地址>
 pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 ```
@@ -56,6 +56,8 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 
 ## 引导开发并持续记录
 
+先选择页面归属：管理后台默认只面向 PC，普通管理/录入复用标准 CRUD 与 Shell，自定义报表和工具使用 admin React 页面及显式菜单；不因“自定义”就复制导航或改成 user 页面，也不为后台自动补移动适配。独立用户页与手机用户任务按实际需求设计，模板 `/home` 仅是占位。报表等专业交互主动检查已有依赖、评估成熟组件和开源库，图表优先评估 ECharts，记录选型理由及加载/销毁边界；细节见[前端](references/frontend.md)。交付需验证平台实际点击入口、根路径、后台菜单和登录返回，不能只验收直达业务链接。
+
 每轮先读取当前 AppSpec 总纲、设计索引、相关能力、活动变更与契约，按稳定 ID 恢复已知事实、候选建议和未决项。设计文件相互引用而不重复定义规则；角色、权限、页面或入口范围改变时，同步受影响 PRD、旅程、交互、架构和 AC。具体工作法按需读取[产品设计](references/product-design.md)。
 
 总纲维护领域与模型关系、PC/移动任务页面、页面/操作/行/字段权限、多角色组合和容量预算。新增功能先评估影响，普通 CRUD、流程、消息等复用平台能力。明确数据量、分页/索引、请求次数、并发/批量和延迟目标，避免无界全量读取、逐行请求与无限重试。
@@ -90,4 +92,4 @@ pnpm exec openxiangda --mcp-stdio --cwd <workspace>
 
 失败保留错误码、指针与原候选。结果不确定先查平台，不生成新的随机幂等键掩盖原运行；仅执行平台允许的恢复。升级项目后刷新资料并重启旧 MCP 连接。
 
-指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。
+指定站点授权可用 `auth status --cwd <应用目录> --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。

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

@@ -20,7 +20,9 @@
 ## 选择平台能力 {#capabilities}
 
 - 普通数据管理：通过 `defineDataModel`、`defineApplicationModule` 和显式 CRUD 视图声明；模型不自动生成菜单或写权限。
-- PC/移动页面：先复用平台组件和标准页面，再使用受支持的页面、插槽与导航扩展。详见[前端](frontend.md)。
+- 管理后台默认仅 PC：先复用平台 Shell、标准 CRUD 和字段；自定义报表/工具使用 admin 页面与显式导航，不为后台自动创建移动副本。详见[页面归属](frontend.md#surface-selection)。
+- 用户页面按实际旅程选择独立 PC/移动布局，手机端只覆盖已确认的用户任务。
+- 图表等专业交互先检查已有依赖，再评估成熟组件或开源库；报表优先评估 ECharts，记录选型理由和加载/销毁边界。详见[组件选型](frontend.md#component-selection)。
 - 无平台账号的外部表单：使用[匿名公开访问](public-access.md)，不用普通 RBAC 角色冒充匿名主体。
 - 标准审批、待办与通知：按需声明平台能力，见[工作流](workflow-events.md)。
 - 真实事务或外部集成：使用[按需后端](backend.md)，不为每张表重写 CRUD 控制器。

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

@@ -12,6 +12,33 @@
 
 不维护 Umi/Pro 双栈，也不在新模板中依赖已退休的前端框架包或旧身份 Provider。
 
+## 先选页面归属，再写布局 {#surface-selection}
+
+管理后台默认只面向 **PC 操作**。数据管理、后台录入和管理报表优先使用平台标准 Shell；无需为后台创建移动页面、响应式手机布局或移动验收任务。
+
+| 任务 | 页面与组件起点 |
+| --- | --- |
+| 简单管理列表、表单、详情 | 显式标准 CRUD，使用平台字段与默认外观 |
+| 后台自定义报表、批量工具、跨模型操作 | `surface: 'admin'` 的 React 页面，路径 `/admin/operations/...`，通过 `adminOperationPage` 加入菜单 |
+| 独立门户、申请或用户任务 | 按实际旅程选择 `surface: 'user'`，拥有独立布局 |
+| 确有手机使用需求的用户任务 | 独立移动 user 页面，使用 `openxiangda/mobile` 和 Field Kit |
+
+“自定义页面”可以直接放在标准后台内。应用只编写内容，runtime 自动套用唯一 Shell；不要因为要画图表就复制顶栏、侧栏、Router 或改成 user 页面。模板 `/home` 是独立用户页占位，不能不经页面选型就当作业务默认入口。
+
+后台菜单的分组、名称、顺序、图标由 `frontend.admin.navigation` 配置；标准视图控制字段与操作，工具栏/行/详情有动作插槽，自定义 React 内容通过 contributions 接入。当前没有整套后台 Shell 的替换接口。用户需要独立产品布局时选择 user surface，普通后台报表无需更换外壳。
+
+应用根路径由生成的 `routeManifest.rootEntry` 分流；`/admin` 根据当前用户可访问的显式菜单选择后台首页。交付时分别核验平台应用列表入口、根路径、后台入口和业务深链接。无后台菜单不能解释为缺少模型；没有管理后台的用户应用也不需要为了消除空状态伪造 CRUD 页面。
+
+## 按场景选择成熟组件与开源库 {#component-selection}
+
+实现专业交互前先检查项目已有依赖，再选择合适的成熟组件或开源库，不默认手写替代品，也不把所有推荐库预装进模板。
+
+- 普通业务字段优先 Field Kit，后台通用控件使用 Ant Design；记录数等单值指标可使用标准统计组件。
+- 分类、趋势、分布等报表图表优先评估 **ECharts**。按需要引入图表、组件和渲染器，图表页面按需加载，容器变化时 resize，卸载时 dispose；用同一筛选条件的服务端聚合结果绘图，不以当前分页数据冒充总体。
+- 编辑器、日历、复杂拖拽等专业功能先评估现有组件和成熟库，平台能力仍唯一拥有数据与权限。选型考虑当前 React/构建兼容性、维护情况、许可证、所需交互、包体积与可访问性。
+
+在页面设计或实现说明中写清选用组件、理由与必要边界。已有需求内的技术选型由开发者完成，无需让用户逐个指定依赖。ECharts 的按需导入方式见[官方说明](https://echarts.apache.org/handbook/en/basics/import/)；后台无需为图表增加手机适配，用户移动图表只按已确认需求处理。
+
 ## 数据和权限
 
 `modules/` 中的业务模型由编译器派生 DataResource 契约，`openxiangda.config.ts` 声明页面

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

@@ -4,7 +4,62 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
 
 ## 准备 {#prerequisites}
 
-准备平台地址、具有应用开发权限的账号、Node.js 24 和 pnpm 10.15.1。向平台维护者取得已验证的 OpenXiangda 2.0 精确版本，并核对平台能力是否支持。`openxiangda@latest` 可能属于 1.x；不能用它选择 2.0。
+准备平台地址、具有应用开发权限的账号、Node.js 24 和 pnpm 10.15.1。`openxiangda@latest` 与 `openxiangda@stable-v2` 指向 V2 稳定版，`openxiangda@legacy-v1` 指向 V1 维护版。安装后核对实际精确版本和目标平台能力；项目依赖与锁文件决定应用使用的工具链。
+
+<a id="upgrade"></a>
+
+## CLI、Skill、MCP 安装与升级 {#upgrade}
+
+全局统一入口适合新用户和原 V1 用户安装；Node.js 需要 24 或更高版本：
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda version --json
+```
+
+`openxiangda` 根包已经依赖配套 CLI、MCP 和 Skill 资料，无需逐个全局安装 `openxiangda-cli`、`openxiangda-mcp` 或 `openxiangda-skill-kit`。全局入口根据当前目录识别代际，进入已有项目时优先使用该项目锁定的引擎；更新全局入口不升级项目依赖。
+
+### 原 V1 用户
+
+建议评估升级到 OpenXiangda 2.0。新应用优先使用 V2；已有应用先核实能力覆盖、迁移成本及数据、在途流程、权限的验收与回滚方案。在已安装新版全局入口后，进入原项目运行：
+
+```bash
+openxiangda version --json
+openxiangda migrate assess --to v2 --json
+```
+
+这里使用全局 `openxiangda`，不要用会优先调用旧项目 V1 CLI 的 `pnpm exec openxiangda` 或 `npx openxiangda` 来执行迁移评估。评估只读取本地源码指针，不读取远端数据、不自动转换应用。原项目仍按 V1 维护；同代更新通过 `legacy-v1` 获取维护版，不把 V2 包直接替换进 V1 项目。
+
+### 更新入口与项目
+
+```bash
+# 更新全局统一入口
+openxiangda update check --target launcher --json
+openxiangda update install --target launcher
+
+# 在项目目录，更新本项目同代依赖与锁文件
+openxiangda update check --target workspace --json
+openxiangda update install --target workspace
+openxiangda version --json
+```
+
+更新完成后审查依赖、锁文件差异并运行项目检查与业务验收。统一入口不会后台自动升级工具或转换项目。V1 独立 CLI 的 `update install` 会尝试刷新 V1 Skill（可用 `--no-skills` 跳过）；统一入口的更新完成后按下面命令显式刷新 Skill。
+
+### 安装或刷新 Skill
+
+在项目目录刷新匹配该项目版本的技能，并更新 V2 项目的 AGENTS 平台区块：
+
+```bash
+openxiangda skill install --workspace . --force
+```
+
+安装到用户级 Codex 或其他 AI 工具可用 `skill install --agent codex|claude|qoder|dual --force`（实际执行时选一个值），或 `--destination <Skill根目录>`。在 V1 项目内会安装 V1 技能与统一入口技能；要先安装 V2 用户级技能，使用 `openxiangda skill install --cwd <不属于任何应用的空目录> --force`。支持协作的自动准备与 `--skip-support` 见下文。
+
+创建 V2 应用会准备匹配版本的项目指引。后续更新依赖后再次刷新技能；不要把不同代际或旧版本的技能正文复制进新项目。
+
+### 接入及更新 MCP
+
+MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置一次。使用[项目路径配置示例](mcp.md#连接项目)，由客户端启动项目锁定版本的 `openxiangda --mcp-stdio`。CLI 更新不会自动修改客户端配置，也不会重启已有 MCP 进程；项目依赖升级后在客户端重启 MCP，然后读取 `workspace_context` 核对版本。长期开发进程使用 CLI 终端管理。
 
 ## 安装与创建 {#create}
 
@@ -13,7 +68,7 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
 ```bash
 pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --base-url https://platform.example.com
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --cwd my-app --base-url https://platform.example.com
 pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
@@ -160,3 +215,11 @@ pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
 先调用 `workspace_context`，再按任务读取 `docs_read` 和当前契约。配置示例与工具参数见[MCP 参考](mcp.md)。登录、创建和长期 dev 进程继续由 CLI/终端管理。
 
 指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。
+
+## 工作区登录态
+
+平台授权保存到所选工作区的 `.openxiangda/session.json`，CLI、MCP、刷新与退出共用该文件。不再读取或迁移旧全局会话；升级后需在每个项目重新登录。已有项目可在根目录或子目录运行 `openxiangda login --base-url <platform>`；`login --cwd <directory>` 和 `auth --cwd <directory>` 明确选定工作区。嵌套应用不会继承父应用会话。
+
+创建应用前先执行 `openxiangda login --cwd my-app --base-url <platform>`，再执行 `openxiangda create my-app --base-url <platform>`。仅含受管登录文件的目录允许初始化，凭据会保留并自动加入 Git 忽略规则。
+
+本地文件优先；仅在文件缺失时使用成对的 `OPENXIANGDA_BASE_URL` 与 `OPENXIANGDA_TOKEN` CI 环境凭据。损坏、过期或平台不符的文件不会触发其他身份回退。请勿提交或打包登录文件。钉钉支持由 DWS 管理自己的授权，不与平台会话混用。

package/skills/openxiangda-v2/references/interaction-patterns.md

@@ -4,6 +4,8 @@
 
 ## 标准管理页面 {#admin}
 
+管理后台默认仅 PC，不要求手机适配或移动验收。自定义报表和工具也优先放进同一后台 Shell，通过声明增加菜单；图表选型见[成熟组件与开源库](frontend.md#component-selection)。只有实际用户端需求才采用下文的独立 PC 或移动模式。
+
 适用于管理员维护独立业务对象。显式选择 CRUD 视图，沿用 Field Kit、Ant Design 与组件默认外观。页面优先呈现标题、主要新建入口、常用筛选、列表与行操作；复杂筛选按需展开。列按办理任务选择，记录默认排序、分页上限、空值/长文显示与操作条件。辅助模型无需独立导航。
 
 列表进入详情再返回时明确关键词、筛选、页码、选择范围与位置是否保留；批量操作说明当前页/已选记录范围，确认内容包含实际对象及影响。新建和编辑复用字段规则，失败定位到字段并保留其他输入。删除只在业务明确需要时提供，由服务端权限和业务约束最终裁定。

package/skills/openxiangda-v2/references/product-design.md

@@ -64,6 +64,8 @@ AppSpec 是唯一设计记录位置。`app.md` 是总纲与目录，详细规则
 
 页面必须记录初始加载、刷新、首次空数据、筛选无结果、错误、无权限、提交中、成功、明确失败、结果未知及并发冲突的适用性。公共状态可引用共用设计，逐页写差异；不适用时写具体理由。详细逐页检查与标准方案见[交互模式](interaction-patterns.md)。
 
+管理后台默认只在 PC 操作，页面规格写明“后台仅 PC，移动不适用”即可，不为材料完整度扩出手机后台。只有用户端有明确手机任务时才设计对应移动页面。页面设计同时选择标准 CRUD、后台自定义页或独立 user 页；报表等专业交互应主动评估成熟组件与开源库，按[前端选型](frontend.md#component-selection)记录选择与理由。
+
 ## AppSpec 材料模板 {#templates}
 
 应用资料放在 `product/`（来源与 PRD）、`experience/`（旅程和逐页规格）、`design/`（视觉、权限和架构）、`reviews/`（评审）下。它们都是 `appspec/` 内单层 Markdown；不要使用嵌套页面目录。只为实际需要的材料建文件，不复制一批“已确认”示例。

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

@@ -28,7 +28,9 @@ CI、离线开发或尚未发布的候选包使用 `pnpm openxiangda check --loc
 
 Web 默认保留开发服务回环访问检查。按需 Nest 使用 `tsx --test` 发现项目中的业务测试；没有用例时只有零项测试，不能当成业务已验收。浏览器目录 `apps/web/e2e/` 起初只有编写说明，添加本应用的 `*.spec.ts` 后运行 `pnpm test:e2e`；真实角色验收绑定 AppSpec 和指定测试版本。
 
-修改资源时验证声明、PC/移动字段语义及受影响的新增、详情、修改、删除、筛选、导出和版本冲突。用允许角色验证成功，用禁止角色验证页面、操作、行和字段边界；存储值及审计应符合声明。平台内部的数据库和性能回归由平台维护者负责，应用不重复搭建平台数据库测试。
+修改资源时验证声明、实际交付端的字段语义及受影响的新增、详情、修改、删除、筛选、导出和版本冲突。管理后台默认仅 PC，不要求移动后台验收；只有已确认的用户移动页面需要验证移动交互。用允许角色验证成功，用禁止角色验证页面、操作、行和字段边界；存储值及审计应符合声明。平台内部的数据库和性能回归由平台维护者负责，应用不重复搭建平台数据库测试。
+
+应用入口或导航变更必须从平台应用列表实际点击进入，再验证应用根路径、登录返回和刷新后的深链接。使用后台的应用检查 `/admin` 进入首个有权菜单、自定义页只出现一个 Shell、菜单切换与未保存保护、无权限拒绝；纯用户应用验证其声明首页，不强制增加后台。直达开发者给出的 `/home` 或报表链接通过，不能替代平台实际入口验收。
 
 只改文案时验证受影响页面。复杂事务、并发和值转换使用聚焦测试。浏览器验收实际操作并检查错误，不能用模拟响应或空页面加载代替真实角色验收。
 

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

@@ -2,6 +2,62 @@
 
 标准 Workflow 与 Notification Hub 已作为 OpenXiangda 2.0 可选平台模块重新开放。它们不属于默认 CRUD 模板，也不兼容或复用 1.x 工作流、消息中心、模板、卡片、回调、表和 API。
 
+## 数据事件捕获与历史
+
+默认保存全部数据增删改事件。没有完整事件审计或历史回放要求的资源，可在
+`events.capturePolicies` 声明 `{ resourceCode: 'items', mode: 'subscribed' }`。
+共享编译器据发布版本中的订阅声明生成固定计划，仅捕获需要的操作事件；没有
+`resourceCodes` 限制的订阅覆盖全部资源，暂时禁用的订阅仍计入需求。该策略需要
+平台 `events.capture-policy` 能力，不能只升级本地 SDK。
+
+未声明策略或使用 `mode: 'all'` 保持原行为。`subscribed` 不提供完整变更事件
+历史，回放只针对实际保存的事实；改回 `all` 只恢复今后的捕获。需要完整事件
+审计或未来任意历史回放时保留 `all`。数据库审计字段与事件历史是不同的契约。
+
+必要事件仍与数据同事务提交；没有必要事件时不写事件事实、outbox 或唤醒投递。
+权限、记录修订约束、文件引用、日期触发和流程命令继续生效，自定义 `emitEvent`
+也不受该策略影响。策略通过正常应用版本发布、测试和生产晋级生效。
+
+## 平台原生数据自动化
+
+只涉及平台表单数据增删改的自动化，可以直接声明 `execution`，无需应用 Nest
+服务和事件 HTTP 接收器。需要平台 `events.native-data-actions` 1.0.0 能力。
+例如已声明 `items`、`copies` 模型及相应字段后：
+
+```ts
+events: {
+  capturePolicies: [
+    { resourceCode: 'items', mode: 'subscribed' },
+    { resourceCode: 'copies', mode: 'subscribed' },
+  ],
+  subscriptions: [{
+    code: 'copy-item',
+    eventTypes: ['openxiangda.data.record.created.v2'],
+    filter: { resourceCodes: ['items'] },
+    execution: {
+      kind: 'native-data', version: 1,
+      operations: [{
+        operation: 'create', resourceCode: 'copies',
+        data: {
+          name: { source: 'event', path: 'data.projection.name' },
+          sourceId: { source: 'event', path: 'data.recordId' },
+        },
+      }],
+    },
+  }],
+},
+```
+
+编译器自动收集必需的事件字段并固定目标资源摘要。动作效果与执行结果同事务
+提交，重复消息和人工重放使用同一个效果标记。更新、删除还必须映射 `id` 和
+`expectedRevision`，冲突不会覆盖新数据。常量使用 `{ source: 'literal', value }`。
+首版支持数据事件、明确的源资源、最多 16 个操作、每次最多 32 个映射字段和
+64 KiB 输入，不执行脚本、SQL、HTTP 或应用代码。目标模型发生不兼容变化时停止
+旧动作并报告错误；关闭并排空此类动作后才能回退到不支持该能力的平台镜像。
+
+外部 Webhook 和自定义代码仍使用已有签名、回执、重试及接收端幂等协议，按至少
+一次投递处理。轻量操作历史仍通过已有审计 API 查询，不依赖是否订阅了事件。
+
 ## 标准详情与当前用户入口
 
 普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页；管理员在当前抽屉或页面中切换到普通表单编辑，直接保存并自动留下变更记录，审批结果保持不变。PC 子表在表格内编辑，父表提交时统一校验。