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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/docs/architecture/repository-and-release.md +7 -3
  2. package/docs/delivery.md +4 -4
  3. package/docs/frontend.md +3 -2
  4. package/docs/getting-started.md +9 -0
  5. package/package.json +1 -1
  6. package/skills/openxiangda-v2-delivery/SKILL.md +12 -10
package/docs/architecture/repository-and-release.md CHANGED
@@ -21,8 +21,8 @@
21
21
  ## 测试层级
22
22
 
23
23
  1. 提交与 PR 使用 `pnpm verify:affected`，只运行受影响包及其依赖任务。
24
- 2. 发布候选使用 `pnpm verify:release`，运行全量 2.0 包、官方模板、Skills 和文档构建。
25
- 3. 发布后在全新独立项目执行安装、创建应用、前后端构建和 CLI/Skill 冒烟测试。
24
+ 2. 发布候选先运行 `pnpm release:plan`，由候选 tarball 差异和包依赖图确定门禁；`pnpm verify:release` 执行该计划。
25
+ 3. 每次候选都在全新独立项目安装真实 tarball 并完成 generate/check/test/build；浏览器相关变化再执行完整 Chromium E2E。
26
26
  4. 平台集成测试部署到测试环境；只有平台协议或部署能力变更才需要阻塞核心发布。
27
27
  5. prod-1 只晋级已经验证的相同 npm 版本、AppPackage 和 OCI digest，不重新构建。
28
28
 
@@ -34,7 +34,9 @@
34
34
  reviewed Changesets
35
35
  -> authoritative master commit
36
36
  -> frozen dependency install
37
- -> affected/full 2.0 verification
37
+ -> immutable tarball/version preflight
38
+ -> deterministic affected validation plan
39
+ -> candidate closure + independent tarball verification
38
40
  -> deterministic version commit
39
41
  -> CI npm publish
40
42
  -> independent-project acceptance
@@ -44,6 +46,8 @@ reviewed Changesets
44
46
  发包阶段不允许 AI 决定包、版本、测试范围或发布顺序。AI 可以编写代码和
45
47
  Changeset，但最终范围由 Git diff、workspace 依赖图和机器校验共同确定。
46
48
 
49
+ 增量门禁不是按文件名随意跳测试：计划器读取 npm 当前版本和上一发布版本，解包并比较真实发行物。候选包和依赖闭包永远 check/test/build，候选 tarball 永远安装进全新应用。Admin 或浏览器契约变化触发 Chromium；核心 SDK/后端/Workflow 变化触发 reference app；Skill Kit 变化触发 Skill 与文档；未知包、没有可比较前版或显式 `--full` 一律运行完整矩阵。正式写 registry 前再次确认候选版本仍未被并发发布。
50
+
47
51
  ## OAuth2 外部应用身份
48
52
 
49
53
  2.0 外部应用采用 OAuth2 Client Credentials。平台签发短期 access token，
package/docs/delivery.md CHANGED
@@ -40,17 +40,17 @@ stateDiagram-v2
40
40
 
41
41
  ## 版本管理
42
42
 
43
- Changesets 固定组同步发布所有 `openxiangda-*` 包、CLI、MCP 与 skill-kit。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。
43
+ Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立版本和内部依赖传播。官方模板固定经过同一候选矩阵验证的精确 BOM。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。
44
44
 
45
45
  `release:publish` 在真正写 registry 前执行不可变版本门禁：未发布版本进入候选集；已经发布的版本则分别解包 registry 工件和当前本地包并逐文件比较。相同内容视为未变包，不重复发布；任何内容差异都必须先用 Changesets 产生新版本；没有新版本时拒绝空发布。发布范围、版本和是否允许写入由机器判定，不由 AI 临场决定。
46
46
 
47
- `pnpm verify:local` 是日常可重复执行的、完全不发包的完整验收入口；`pnpm verify:release` 复用同一门禁。它们只验证原生 2.0 工作区，不运行 1.x 兼容测试。除类型检查、单测、模板、技能和文档门禁外，还会执行发行物黑盒验证：打包所有公开 2.0 包，检查 tarball 内的 `exports`、bin 和依赖协议，在 monorepo 外安装这些 tarball，通过其中的 `create-openxiangda` 创建全新应用，然后执行新应用的生成、检查、单测、真实 Chromium Admin 验收与生产构建。这样 `workspace:*` 链接、未打包的本地文件或只有 jsdom 能通过的交互都不能掩盖坏包。
47
+ `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` 保留周期性全量审计。
48
48
 
49
49
  Playwright 浏览器使用官方缓存目录；`playwright install chromium` 已安装对应版本时是无操作。发包门禁不会额外运行 1.x 测试，也不会为每个包重复浏览器验收，而是在最终独立新应用上只运行一次完整用户路径。
50
50
 
51
- 工具仓还会把同批本地包发布到一次性、仅绑定 `127.0.0.1` 的 registry，使用持久独立 reference app 再执行一次安装、契约生成、类型检查、单测、真实 NestJS 身份/Data API 进程验收和生产构建。`pnpm reference:install:from-build` 可在未公开发包时通过同一 registry 协议刷新 reference worktree 的本地依赖，避免 `file:`/`link:` 破坏独立性。
51
+ 当计划要求 reference app 时，工具仓只把本次候选包发布到一次性、仅绑定 `127.0.0.1` 的 registry；未变化的依赖继续从 npm 代理取得。持久独立 reference app 再执行安装、契约生成、类型检查、单测、真实 NestJS 身份/Data API 进程验收和生产构建。`pnpm reference:install:from-build` 可在未公开发包时通过同一 registry 协议刷新 reference worktree 的本地依赖，避免 `file:`/`link:` 破坏独立性。
52
52
 
53
- 门禁先用 Turbo 完成一次全工作区 check/test/build；后续生成契约检查、tarball 黑盒、技能校验和文档构建复用这批已验证的 `dist`，不会各自再次触发全仓构建。`distribution:smoke`、`skills:check`、`docs:build` 仍保留可独立执行的自包含入口，只有 `verify:local` 内部使用 `:from-build` 阶段命令。
53
+ 增量门禁先用 Turbo 完成候选包及其依赖闭包的 check/test/build；全量模式完成整个 workspace。后续生成契约、tarball 黑盒、技能校验和文档构建复用已验证的 `dist`。`distribution:smoke`、`skills:check`、`docs:build` 仍保留可独立执行的自包含入口。
54
54
 
55
55
  官方工作区使用 pnpm 10 的显式依赖构建策略：只允许经过审核的 `esbuild` 生命周期脚本，并启用 `strictDepBuilds`。未来依赖若新增 install/postinstall 脚本，安装会直接失败，必须先审查并更新策略；发行物黑盒验证同时拒绝任何“已忽略构建脚本”警告，避免开发机缓存掩盖不完整安装。
56
56
 
package/docs/frontend.md CHANGED
@@ -16,7 +16,8 @@
16
16
  - 数据导出沿用当前服务端 filter/order 并按权限裁剪字段；CSV 防公式注入并限制最大导出量。导入先本地解析与类型预检，再以最多 100 个操作的受限事务批次提交，每批使用稳定幂等键，支持失败后安全重试。
17
17
  - `DashboardPage`、`MetricCard`、`DataCountMetric`、`DataAggregateChart`、`DataDistributionChart`、`DataTrendChart` 和 `DashboardSection` 提供 RoleSession 约束的标准概览页。图表使用服务端受限聚合，ECharts 运行时按需加载；指标查询丢弃过期响应并提供独立错误恢复，不要求每个应用重复搭建卡片、图表与加载状态。
18
18
  - `ApplicationOperationsPage` 提供应用管理员运行视图：平台契约、当前身份、后端 readiness/version、不可变 AppVersion 最近部署、事件重试/死信和 `eventId/requestId/traceId` 关联信息集中展示；事件订阅与定时事件可按 revision 暂停/启用，重试或死信可显式创建新投递并保留原记录。各探针独立失败，不会因为一个依赖不可用而把整页变成白屏，诊断快照可一键复制。
19
- - 生产应用从 `openxiangda-admin/core`、`/data`、`/dashboard`、`/workflow` 子路径导入，并用 `React.lazy` 声明业务路由。官方模板的构建门禁要求首页、数据页和流程页保持独立异步 chunk，同时限制单 chunk 与首屏 JavaScript 预算；新增页面不能重新退化成完整 Admin/Ant Design 一次性加载。
19
+ - `ApplicationCredentialsPage` 提供标准的应用管理员安全控制面：外部 OAuth2 Client 生命周期与审计、平台托管后端运行时凭据的分阶段轮换、环境级只写应用 Secret 生命周期与审计、Workflow 审批人 Provider 密钥轮换。浏览器只保存当前表单状态；外部 Client Secret 仅在成功响应后一次性展示，关闭即清除；应用 Secret、运行时凭据和 Provider 密钥永不回显或写入快照、日志与持久化缓存。
20
+ - 生产应用从 `openxiangda-admin/core`、`/data`、`/dashboard`、`/operations`、`/credentials`、`/workflow` 子路径导入，并用 `React.lazy` 声明业务路由。官方模板的构建门禁要求首页、数据页、运维页、凭据页和流程页保持独立异步 chunk，同时限制单 chunk 与首屏 JavaScript 预算；新增页面不能重新退化成完整 Admin/Ant Design 一次性加载。
20
21
  - 工作流页面按后端返回的 actions、fieldPolicy 和 presentation 渲染按钮与字段。业务记录由 Data API/App API 加载，`edit_required` 在操作前验证，变更以 revision 乐观锁先保存后执行流程命令；Workflow Kernel 不保存业务字段。
21
22
  - 个人中心内置长期流程代理。选择代理人后必须再选择其具体应用角色绑定和数据范围，代理始终绑定发起人的当前稳定身份，不合并其他角色权限。
22
23
 
@@ -32,7 +33,7 @@ Admin 框架的缓存只保存界面偏好和逻辑路由，不缓存 Token、
32
33
 
33
34
  ## 发布前本地验收
34
35
 
35
- 官方模板的 Vite 开发服务默认装载内存平台 Mock，包含申请人、学院管理员、仪器管理员和应用管理员四种身份，以及长期代理、批量授权、Directory v2、字段权限、Data API 查询/CRUD/单记录详情/审计/受限聚合/托管附件/受限事务、Workflow Kernel 发起与完整审批操作、应用自定义动作、事件订阅/定时器暂停和死信重放。这样新应用无需 provision 或发布即可验证完整 Admin 交互：
36
+ 官方模板的 Vite 开发服务默认装载内存平台 Mock，包含申请人、学院管理员、仪器管理员和应用管理员四种身份，以及长期代理、批量授权、Directory v2、字段权限、Data API 查询/CRUD/单记录详情/审计/受限聚合/托管附件/受限事务、Workflow Kernel 发起与完整审批操作、应用自定义动作、事件订阅/定时器暂停和死信重放、OAuth2 Client 与只写 Secret 的完整本地验收。这样新应用无需 provision 或发布即可验证完整 Admin 交互：
36
37
 
37
38
  ```bash
38
39
  pnpm dev
package/docs/getting-started.md CHANGED
@@ -57,6 +57,15 @@ pnpm verify:local
57
57
 
58
58
  它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、Chromium 交互、生产构建、Skill 和文档，不会执行 npm 发布、Git 提交或平台部署。
59
59
 
60
+ 准备发包时先查看机器生成的影响计划：
61
+
62
+ ```bash
63
+ pnpm release:plan
64
+ pnpm verify:release
65
+ ```
66
+
67
+ `release:plan` 会在运行昂贵测试前完成 npm 不可变性检查并比较候选包与上一发布版本的真实 tarball。`verify:release` 至少执行候选依赖闭包的 check/test/build 和全新应用 tarball 安装；只有 Admin/浏览器契约、核心应用 SDK、模板、Skills 或文档实际变化时才增加对应 Chromium、reference app、Skill 或 VitePress 门禁。无法分类的新包或变化自动升级为全量验证。周期审计使用 `pnpm verify:release:full`。
68
+
60
69
  ## OAuth2 应用身份
61
70
 
62
71
  外部系统或后台任务通过平台托管的 OAuth2 client credentials 获取短期 token，不使用用户 RoleSession。客户端 Secret 只在创建或轮换时返回一次：
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openxiangda-skill-kit",
3
- "version": "2.0.0-alpha.12",
3
+ "version": "2.0.0-alpha.14",
4
4
  "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
package/skills/openxiangda-v2-delivery/SKILL.md CHANGED
@@ -37,16 +37,18 @@ command itself. A failed deployment must leave the currently active key intact.
37
37
  ## Toolchain release
38
38
 
39
39
  When changing or publishing OpenXiangda 2.0 itself, run
40
- `pnpm verify:release`. The gate is native to the independent 2.0 repository and
41
- must not invoke 1.x compatibility suites. It packs every public package,
42
- validates published `exports`, bin targets and dependency protocols, installs
43
- the tarballs outside the monorepo, creates a new application from the packed
44
- creator, and runs that application's generate/check/test/build lifecycle.
45
- The packed application's lifecycle also installs the pinned Playwright Chromium
46
- and runs its Admin browser acceptance exactly once before the production build.
47
- The release pipeline builds/checks/tests the workspace once, then uses the
48
- `:from-build` distribution, skill and docs stages so those gates reuse verified
49
- artifacts instead of rebuilding the entire workspace.
40
+ `pnpm release:plan` before `pnpm verify:release`. The gate is native to the
41
+ independent 2.0 repository and must not invoke 1.x compatibility suites. The
42
+ plan compares current npm tarballs before expensive tests, rejects changed
43
+ published versions, compares candidates with their nearest earlier release and
44
+ maps actual artifact differences to deterministic gates. Candidate dependency
45
+ closures always check/test/build; every candidate tarball is installed outside
46
+ the monorepo into a newly generated application. Admin/browser changes require
47
+ Chromium, core application SDK changes require the independent reference app,
48
+ and Skill Kit changes require Skills/docs. Unknown or first-release packages
49
+ fail closed to the full matrix. Run `pnpm verify:release:full` for the periodic
50
+ complete audit. The final publish command repeats version availability before
51
+ writing npm, so concurrent publication cannot invalidate the reviewed plan.
50
52
  `pnpm distribution:smoke` runs only this packed-distribution verification.
51
53
  Keep `strictDepBuilds: true` in the official workspace and template. Permit only
52
54
  reviewed dependency lifecycle scripts (`esbuild` today); never suppress the