openxiangda-skill-kit 2.0.0-alpha.13 → 2.0.0-alpha.14

package/docs/architecture/repository-and-release.md

@@ -21,8 +21,8 @@
 ## 测试层级
 
 1. 提交与 PR 使用 `pnpm verify:affected`，只运行受影响包及其依赖任务。
-2. 发布候选使用 `pnpm verify:release`，运行全量 2.0 包、官方模板、Skills 和文档构建。
-3. 发布后在全新独立项目执行安装、创建应用、前后端构建和 CLI/Skill 冒烟测试。
+2. 发布候选先运行 `pnpm release:plan`，由候选 tarball 差异和包依赖图确定门禁；`pnpm verify:release` 执行该计划。
+3. 每次候选都在全新独立项目安装真实 tarball 并完成 generate/check/test/build；浏览器相关变化再执行完整 Chromium E2E。
 4. 平台集成测试部署到测试环境；只有平台协议或部署能力变更才需要阻塞核心发布。
 5. prod-1 只晋级已经验证的相同 npm 版本、AppPackage 和 OCI digest，不重新构建。
 
@@ -34,7 +34,9 @@
 reviewed Changesets
   -> authoritative master commit
   -> frozen dependency install
-  -> affected/full 2.0 verification
+  -> immutable tarball/version preflight
+  -> deterministic affected validation plan
+  -> candidate closure + independent tarball verification
   -> deterministic version commit
   -> CI npm publish
   -> independent-project acceptance
@@ -44,6 +46,8 @@ reviewed Changesets
 发包阶段不允许 AI 决定包、版本、测试范围或发布顺序。AI 可以编写代码和
 Changeset，但最终范围由 Git diff、workspace 依赖图和机器校验共同确定。
 
+增量门禁不是按文件名随意跳测试：计划器读取 npm 当前版本和上一发布版本，解包并比较真实发行物。候选包和依赖闭包永远 check/test/build，候选 tarball 永远安装进全新应用。Admin 或浏览器契约变化触发 Chromium；核心 SDK/后端/Workflow 变化触发 reference app；Skill Kit 变化触发 Skill 与文档；未知包、没有可比较前版或显式 `--full` 一律运行完整矩阵。正式写 registry 前再次确认候选版本仍未被并发发布。
+
 ## OAuth2 外部应用身份
 
 2.0 外部应用采用 OAuth2 Client Credentials。平台签发短期 access token，

package/docs/delivery.md

@@ -40,17 +40,17 @@ stateDiagram-v2
 
 ## 版本管理
 
-Changesets 固定组同步发布所有 `openxiangda-*` 包、CLI、MCP 与 skill-kit。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。
+Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立版本和内部依赖传播。官方模板固定经过同一候选矩阵验证的精确 BOM。文档参考从命令和 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 能通过的交互都不能掩盖坏包。
+`pnpm verify:local` 是日常可重复执行的全量验收入口。正式候选先由 `pnpm release:plan` 比较 npm 与本地 tarball，并比较候选与上一发布版本；漏升版会在昂贵测试前直接失败。`pnpm verify:release` 执行机器生成的增量计划：候选依赖闭包永远完成 check/test/build，每个候选 tarball 都在 monorepo 外安装进全新生成应用并完成 generate/check/test/build；浏览器相关变化提升到真实 Chromium E2E，核心应用 SDK 变化增加持久 reference app，Skill/文档变化增加相应门禁。未知变化 fail-closed 到完整矩阵。`pnpm verify:release:full` 保留周期性全量审计。
 
 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:` 破坏独立性。
+当计划要求 reference app 时，工具仓只把本次候选包发布到一次性、仅绑定 `127.0.0.1` 的 registry；未变化的依赖继续从 npm 代理取得。持久独立 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` 阶段命令。
+增量门禁先用 Turbo 完成候选包及其依赖闭包的 check/test/build；全量模式完成整个 workspace。后续生成契约、tarball 黑盒、技能校验和文档构建复用已验证的 `dist`。`distribution:smoke`、`skills:check`、`docs:build` 仍保留可独立执行的自包含入口。
 
 官方工作区使用 pnpm 10 的显式依赖构建策略：只允许经过审核的 `esbuild` 生命周期脚本，并启用 `strictDepBuilds`。未来依赖若新增 install/postinstall 脚本，安装会直接失败，必须先审查并更新策略；发行物黑盒验证同时拒绝任何“已忽略构建脚本”警告，避免开发机缓存掩盖不完整安装。
 

package/docs/getting-started.md

@@ -57,6 +57,15 @@ pnpm verify:local
 
 它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、Chromium 交互、生产构建、Skill 和文档，不会执行 npm 发布、Git 提交或平台部署。
 
+准备发包时先查看机器生成的影响计划：
+
+```bash
+pnpm release:plan
+pnpm verify:release
+```
+
+`release:plan` 会在运行昂贵测试前完成 npm 不可变性检查并比较候选包与上一发布版本的真实 tarball。`verify:release` 至少执行候选依赖闭包的 check/test/build 和全新应用 tarball 安装；只有 Admin/浏览器契约、核心应用 SDK、模板、Skills 或文档实际变化时才增加对应 Chromium、reference app、Skill 或 VitePress 门禁。无法分类的新包或变化自动升级为全量验证。周期审计使用 `pnpm verify:release:full`。
+
 ## OAuth2 应用身份
 
 外部系统或后台任务通过平台托管的 OAuth2 client credentials 获取短期 token，不使用用户 RoleSession。客户端 Secret 只在创建或轮换时返回一次：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.13",
+  "version": "2.0.0-alpha.14",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -37,16 +37,18 @@ command itself. A failed deployment must leave the currently active key intact.
 ## Toolchain release
 
 When changing or publishing OpenXiangda 2.0 itself, run
-`pnpm verify:release`. The gate is native to the independent 2.0 repository and
-must not invoke 1.x compatibility suites. It packs every public package,
-validates published `exports`, bin targets and dependency protocols, installs
-the tarballs outside the monorepo, creates a new application from the packed
-creator, and runs that application's generate/check/test/build lifecycle.
-The packed application's lifecycle also installs the pinned Playwright Chromium
-and runs its Admin browser acceptance exactly once before the production build.
-The release pipeline builds/checks/tests the workspace once, then uses the
-`:from-build` distribution, skill and docs stages so those gates reuse verified
-artifacts instead of rebuilding the entire workspace.
+`pnpm release:plan` before `pnpm verify:release`. The gate is native to the
+independent 2.0 repository and must not invoke 1.x compatibility suites. The
+plan compares current npm tarballs before expensive tests, rejects changed
+published versions, compares candidates with their nearest earlier release and
+maps actual artifact differences to deterministic gates. Candidate dependency
+closures always check/test/build; every candidate tarball is installed outside
+the monorepo into a newly generated application. Admin/browser changes require
+Chromium, core application SDK changes require the independent reference app,
+and Skill Kit changes require Skills/docs. Unknown or first-release packages
+fail closed to the full matrix. Run `pnpm verify:release:full` for the periodic
+complete audit. The final publish command repeats version availability before
+writing npm, so concurrent publication cannot invalidate the reviewed plan.
 `pnpm distribution:smoke` runs only this packed-distribution verification.
 Keep `strictDepBuilds: true` in the official workspace and template. Permit only
 reviewed dependency lifecycle scripts (`esbuild` today); never suppress the