openxiangda-skill-kit 2.0.18 → 2.0.19

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.19",
   "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.7.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
 ```
@@ -90,4 +90,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/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/workflow-events.md

@@ -2,6 +2,22 @@
 
 标准 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`
+也不受该策略影响。策略通过正常应用版本发布、测试和生产晋级生效。
+
 ## 标准详情与当前用户入口
 
 普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页；管理员在当前抽屉或页面中切换到普通表单编辑，直接保存并自动留下变更记录，审批结果保持不变。PC 子表在表格内编辑，父表提交时统一校验。