openxiangda-skill-kit 2.0.0-alpha.16 → 2.0.0-alpha.18

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

@@ -22,9 +22,10 @@
 
 1. 提交与 PR 使用 `pnpm verify:affected`，只运行受影响包及其依赖任务。
 2. 发布候选先运行 `pnpm release:plan`，由候选 tarball 差异和包依赖图确定门禁；`pnpm verify:release` 执行该计划。
-3. 每次候选都在全新独立项目安装真实 tarball 并完成 generate/check/test/build；浏览器相关变化再执行完整 Chromium E2E。
-4. 平台集成测试部署到测试环境；只有平台协议或部署能力变更才需要阻塞核心发布。
-5. prod-1 只晋级已经验证的相同 npm 版本、AppPackage 和 OCI digest，不重新构建。
+3. `pnpm release:publish` 从干净的远端 `master` 生成一次带摘要的候选工件清单；候选安装、reference 验证和 npm publish 复用相同 tarball，禁止重新打包。
+4. 每次候选都在全新独立项目安装真实 tarball 并完成 generate/check/test/build；浏览器相关变化再执行完整 Chromium E2E。
+5. 平台集成测试部署到测试环境；只有平台协议或部署能力变更才需要阻塞核心发布。
+6. prod-1 只晋级已经验证的相同 npm 版本、AppPackage 和 OCI digest，不重新构建。
 
 任何层级都不得调用 1.x 测试套件。
 

package/docs/backend.md

@@ -20,6 +20,8 @@ src/health         liveness/readiness
 
 用户身份必须绑定 RoleSession；应用身份绑定 tenant、app、environment、client、credentialVersion 和 scopes。`OpenXiangdaAuthzGuard` 默认要求服务身份至少具有 `app:invoke`，声明 `@RequireCapability()` 时还要求 token 中包含完全匹配的 capability。应用身份可以调用授权的 App API/Data API，但 Workflow 客户端拒绝没有用户 RoleSession 的上下文。
 
+Application 2.0 的运行环境只有 `development`、`preproduction`、`production` 三条固定通道，`environmentKey` 是 Principal、RoleSession、事件、Workflow、App API 和运行容器共同使用的稳定身份键，并与通道名一致。`environmentId` 仅表示平台旧环境表中的可选 UUID 关联，不能传入应用运行时或用于授权判断。需要同类多环境时必须升级发布契约，不能把 UUID 或任意字符串临时当成 `environmentKey`。
+
 Worker、Scheduler 或事件消费者没有浏览器请求上下文时，注入 `OpenXiangdaApplicationDataApiService`。每个已部署后端的应用环境都有一个平台托管的 workload OAuth2 client；平台自动创建或复用客户端，并通过 Kubernetes Secret 注入 `OPENXIANGDA_OAUTH_CLIENT_ID`、`OPENXIANGDA_OAUTH_CLIENT_SECRET` 和 `OPENXIANGDA_OAUTH_SCOPES`，这些保留变量不写入 `backend.secrets`。本地开发时可以在未提交的 `.env` 中显式提供测试客户端凭据。
 
 运行凭据的状态只包含 clientId、当前版本、hint、宽限期和待激活轮换元数据，不返回 Secret。`openxiangda oauth runtime rotate --environment <key> --idempotency-key <key>` 使用当前版本 CAS 暂存新凭据，并自动对当前激活 AppVersion 创建一次同版本滚动部署；部署准备阶段才把待激活凭据提升为当前凭据。旧 Pod 使用的上一版本在指定宽限期内仍可换 token，因此轮换不依赖同时重启全部副本。失败或重复请求不会生成第二份凭据，运维重试必须复用幂等键。
@@ -30,7 +32,7 @@ SDK 会合并并发换 token、在到期前刷新，并在平台返回 401 时
 OpenXiangdaModule.forRoot({
   appCode: process.env.OPENXIANGDA_APP_CODE!,
   platformBaseUrl: process.env.OPENXIANGDA_PLATFORM_BASE_URL!,
-  environmentId: process.env.OPENXIANGDA_ENVIRONMENT_ID!,
+  environmentKey: process.env.OPENXIANGDA_ENVIRONMENT_KEY!,
   version: process.env.OPENXIANGDA_APP_VERSION!,
   oauthClient: {
     clientId: process.env.OPENXIANGDA_OAUTH_CLIENT_ID!,

package/docs/delivery.md

@@ -44,6 +44,8 @@ Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立
 
 `release:publish` 在真正写 registry 前执行不可变版本门禁：未发布版本进入候选集；已经发布的版本则分别解包 registry 工件和当前本地包并逐文件比较。相同内容视为未变包，不重复发布；任何内容差异都必须先用 Changesets 产生新版本；没有新版本时拒绝空发布。发布范围、版本和是否允许写入由机器判定，不由 AI 临场决定。
 
+发布入口只打包一次，并在 Git 私有目录写入绑定源码 `HEAD`、registry、包版本、字节数、SHA-256 与 npm SHA-512 integrity 的工件清单。全新应用、独立 reference app 与正式 npm publish 必须消费同一批 `.tgz`；任何字节或清单变化都会在写 registry 前失败。部分发布中断后可以从 receipt 继续：已经发布且 integrity 一致的包被跳过，不一致则停止。npm 在逐包写入时可能先推进预发布 tag；receipt 只接受这一个可恢复中间态，并在所有包确认后统一收敛最终 dist-tag 和 Git tag。
+
 `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 测试，也不会为每个包重复浏览器验收，而是在最终独立新应用上只运行一次完整用户路径。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.16",
+  "version": "2.0.0-alpha.18",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.14"
+    "openxiangda-devkit-core": "2.0.0-alpha.16"
   },
   "devDependencies": {
     "tsx": "4.23.12",