openxiangda-skill-kit 2.0.0-alpha.24 → 2.0.0-alpha.25

package/docs/architecture/environment-configuration-kernel-v2.md

@@ -2,6 +2,8 @@
 
 状态：方案已确认并按 Native 实施顺序推进。2026-08-15 已完成 E4 运行时闭环：应用身份和预发/生产原生环境成对创建、Native DeploymentRun、按 run 隔离的候选 workload、`pending -> active -> retiring -> revoked` 运行凭据、凭据与 Head CAS 同事务激活、旧 token 随 Head 变化立即失效；App Gateway 使用最长 60 秒 invocation token + 最长 30 秒 Ed25519 请求 assertion，官方 NestJS 全局 transport guard 绑定当前 Native Head 与完整 HTTP 请求，本地平台使用同构协议且拒绝重放。单体 Nest 的后台消费由短租约选出一个活动实例，应用 Secret 只允许当前 Head 身份按声明读取，terminal/cancelled/超时候选由精确 GC 回收，`alpha -> native-2` 切换必须通过全平台实例 release/capability 门禁。Native production 仍须完成后续 E5 和真实预发 E2E 后再开放。
 
+生命周期修订：2026-08-16 已确认新应用默认只创建预发环境，正式环境在首次明确发布时惰性创建。本文中“provision 成对创建预发/生产”的既有实现描述由[按需正式环境](./on-demand-production-environment-v2.md)取代；环境隔离、不可变 AppVersion、Head CAS 和预发/正式运行态分离等不变量保持不变。
+
 ## 1. 决策摘要
 
 OpenXiangda 2.0 的运行语义采用三层模型：

package/docs/architecture/on-demand-production-environment-v2.md

@@ -0,0 +1,79 @@
+# OpenXiangda 2.0 按需正式环境
+
+状态：2026-08-16 已确认，作为 2.0 新应用的目标生命周期。尚未实现。
+
+## 问题证据
+
+当前 `app provision` 会同时创建预发和正式环境，参考应用部署后也容易同时保留两套后端工作负载。大多数 2.0 应用长期处于开发或试验阶段，不会正式投入使用。提前创建正式环境、运行凭据、环境状态和 Kubernetes 工作负载没有业务价值，还会增加资源占用、运维噪音和发布失败面。
+
+## 能力归属
+
+- 应用身份、环境注册、DeploymentRun、环境 Head 和运行期启停状态由平台控制面唯一拥有。
+- Git 仓库和 AppPackage 只拥有源码、声明与不可变 AppVersion，不保存环境是否已创建或正在运行的事实。
+- CLI、MCP、AI 和 Admin 管理端只是控制面客户端，不自行推导或补写正式环境。
+
+## 决策
+
+一个 2.0 逻辑应用默认只创建稳定的 `preproduction` 环境。`production` 是可选的长期环境，仅在开发者首次执行明确的“发布正式版”操作时惰性创建。
+
+1. `app provision` 幂等创建应用身份、应用最高管理员授权和预发环境，不创建正式环境。
+2. 日常 `deploy` 只向预发部署新的不可变 AppVersion。
+3. 首次 `release production` 选择一个已在预发成功运行的 AppVersion，创建正式环境并把同一个 AppVersion 发布到正式环境。发布过程不重新构建制品。
+4. 后续 `release production` 复用已有正式环境，只更新其环境 Head。
+5. 预发和正式工作负载均支持显式启动、停止。停止只把期望运行副本降为零，不删除环境、业务数据、审计、Secret 元数据或历史 DeploymentRun。
+6. 从未正式发布的应用永远没有正式环境、正式 RoleSession、正式 OAuth/Secret 运行态或正式后端 Pod。
+
+## 稳定不变量
+
+- 一个应用始终恰好有一个预发环境，最多有一个正式环境；环境 key 创建后不可改。
+- 同一个 AppVersion 从预发发布到正式，前端、后端镜像、配置和数据契约摘要保持完全一致。
+- 预发与正式的业务数据、角色成员、范围授权、OAuth 客户端、Secret 值、Workflow 实例和 Event receipt 相互独立。
+- 首次正式发布不复制预发业务数据。需要初始化数据时使用应用明确声明、可审计且可重试的 seed/import 操作。
+- 环境不存在、环境已停止和环境发布失败是三种不同状态，网关和管理端必须返回可区分的结果。
+- 1.x 应用、流程、自动化和既有发布模型不读取也不写入该生命周期。
+
+## 控制面契约
+
+| 操作 | 结果 |
+|---|---|
+| `app provision` | 创建应用身份和预发环境 |
+| `deploy preproduction` | 构建或提交 AppPackage，并把候选 AppVersion 部署到预发 |
+| `environment start/stop preproduction` | 启停预发工作负载，环境事实保持不变 |
+| `release production` | 首次惰性创建正式环境，或复用已有正式环境，发布预发验证过的同一 AppVersion |
+| `environment start/stop production` | 显式启停正式工作负载，不删除正式环境 |
+
+管理端应用列表至少显示“仅预发、预发运行中、预发已停止、正式发布中、已发布、正式发布失败”，并提供与状态匹配的确定性操作。普通用户页面不展示环境 UUID、AppVersion ID、workflow code 或内部错误码；这些信息只进入应用管理员诊断面板。
+
+## 失败与并发
+
+- 首次正式发布使用稳定 operation/idempotency key，并以 `tenant + app + production` 唯一约束防止双击或并发会话创建两个正式环境。
+- 发布先验证源 DeploymentRun、AppVersion 摘要、平台 capability、必需 Secret 和集群资源，再创建 Kubernetes 工作负载。
+- 数据库注册与 Kubernetes 就绪不能伪装成一个跨系统事务。正式环境先进入 `provisioning`，只有候选工作负载通过 readiness 后，才在一个数据库事务中激活环境 Head 和发布成功状态。
+- 候选失败时不产生正式活动 Head，不影响预发，也不覆盖既有正式版本。首次失败可以保留同一个正式环境身份和失败记录，重试继续使用该身份。
+- 资源不足必须在创建 Pod 前返回明确的 CPU、内存或配额诊断，不能停留在无提示的 Pending。
+
+## 资源边界
+
+| 应用状态 | 默认运行后端数 |
+|---|---:|
+| 预发已停止且从未发布 | 0 |
+| 正在预发验证 | 1 |
+| 已发布且预发已停止 | 1 |
+| 正式运行并同时进行预发验证 | 临时 2 |
+
+平台可以为长期未访问的预发应用提供自动停止策略，但不能自动删除环境或业务数据。正式环境不做自动停止，除非开发者明确配置。
+
+## 回滚边界
+
+- 该变化只调整 2.0 新应用的环境创建时机和控制面命令语义，不删除已经存在的正式环境。
+- 已有双环境 2.0 测试应用可以继续运行，后续通过显式清理任务停止或删除无用的正式工作负载。
+- 实现阶段必须采用可独立回滚的数据库和 API 变更；回滚时允许恢复“provision 同时创建两环境”的旧行为，但不得删除惰性创建后产生的正式环境事实。
+
+## 可证伪验收
+
+1. 新应用执行 `app provision` 后，数据库和控制面查询只返回预发环境，Kubernetes 中没有正式 Deployment 或 Pod。
+2. 预发部署成功后首次执行 `release production`，平台创建唯一正式环境，并发布与预发完全相同摘要的 AppVersion。
+3. 并发执行两次首次正式发布，只能产生一个正式环境和一个活动 Head；另一个请求幂等复用或返回稳定冲突。
+4. 首次发布因资源不足或 readiness 失败时，预发 Head 不变化，正式环境没有活动 Head，也没有残留运行 Pod。
+5. 停止预发后副本数为零，再次启动恢复相同环境和活动版本。
+6. 1.x 发布、流程和自动化回归测试结果不受影响。

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

@@ -23,7 +23,7 @@
 1. 提交与 PR 使用 `pnpm verify:affected`，只运行受影响包及其依赖任务。
 2. 已评审 Changesets 先由 `pnpm release:version` 在干净且已同步远端的 `master` 上物化；人工只审核生成的版本、内部依赖与模板 BOM，不手改版本。版本 diff 必须提交并推送后才成为候选源码事实。
 3. 发布候选运行 `pnpm release:plan`，由真实候选 tarball 差异和包依赖图确定门禁；待消费 Changesets 未物化时在任何构建前失败。
-4. `pnpm release:publish` 从干净的远端 `master` 生成一次带摘要的候选工件清单；候选安装、reference 验证和 npm publish 复用相同 tarball，禁止重新打包，并且只执行一次正式验证。`pnpm verify:release` 只用于需要提前获得无发布验收证据的演练，不是正式发布前必须重复执行的步骤。
+4. `pnpm release:publish` 从干净的远端 `master` 生成一次带摘要的候选工件清单；候选安装、reference 验证和 npm publish 复用相同 tarball，禁止重新打包，并且只执行一次正式验证。公开 registry 确认收到相同 tarball 后，发布命令会从公开包自动同步 reference 仓库锁文件并执行 frozen install；锁文件不再从发布前的临时 registry 生成。`pnpm verify:release` 只用于需要提前获得无发布验收证据的演练，不是正式发布前必须重复执行的步骤。
    从源码创建候选 tarball 前，制品入口按候选包及其 workspace 依赖统一执行一次 Turbo 增量构建；不能直接打包工作区里可能过期的 `dist`。如果输入已经是带摘要的 release artifact manifest，则跳过构建并只消费冻结制品。
 5. 每次候选都在全新独立项目安装真实 tarball 并完成 generate/check/test/build；浏览器相关变化再执行完整 Chromium E2E。
 6. 平台集成测试部署到测试环境；只有平台协议或部署能力变更才需要阻塞核心发布。
@@ -43,6 +43,7 @@ reviewed Changesets
   -> deterministic affected validation plan
   -> candidate closure + independent tarball verification
   -> npm publish of the exact validated tarballs
+  -> published reference lock synchronization + frozen install
   -> independent-project acceptance
   -> immutable promotion
 ```

package/docs/design/admin/README.md

@@ -0,0 +1,122 @@
+# OpenXiangda 2.0 Admin 设计基线
+
+## 设计判断
+
+OpenXiangda 2.0 Admin 面向应用开发者、应用管理员和业务角色用户。界面采用冷静、干净、中低密度的企业级产品语言，组件与交互基于 Ant Design 6，并吸收 ProComponents 的数据管理页面模式。
+
+设计参数：
+
+- `DESIGN_VARIANCE: 4`
+- `MOTION_INTENSITY: 2`
+- `VISUAL_DENSITY: 5`
+- 单一强调色：`#1677ff`
+- 输入框与按钮圆角：8px
+- 主内容容器圆角：12px
+- 页面间距：24px
+- 表格常规行高：约 48px
+
+## 设计稿
+
+### 应用壳与工作台
+
+![应用壳与工作台](./workbench-v1.png)
+
+评审结论：
+
+- 保留侧栏、顶栏、身份切换、缓存标签栏和三列洞察区的层级。
+- 指标区降低图标装饰，数字必须来自真实接口。
+- 快捷入口采用紧凑操作带或非等宽布局，避免三张装饰性等宽卡片。
+- 待办列表不使用无语义状态点。
+- 不实现设计稿中的伪监控数字。应用模板只能展示真实可获取的数据。
+
+### 标准数据管理页
+
+![标准数据管理页](./data-management-v1.png)
+
+评审结论：
+
+- 页面由紧凑标题区、搜索区、表格工具区、数据表格和分页组成。
+- 搜索字段使用上方标签，不使用占位符代替标签。
+- 批量操作只在已选择数据时出现。
+- 导入、导出、密度、列设置和刷新归入统一工具区。
+- 空、加载、错误是互斥运行状态，设计稿底部三态条仅用于评审说明。
+- 侧栏完全由应用路由清单生成，不采用设计稿自行扩展的菜单。
+
+### 流程详情与审批任务页
+
+![流程详情与审批任务页](./workflow-detail-v1.png)
+
+评审结论：
+
+- 业务字段始终放在申请信息区，由 Data API 或 App API 保存。
+- 流程状态、当前节点和审批记录放在审批进度区。
+- 同意、拒绝、转交、回退、加签和应用自定义操作都由后端协议返回。
+- 操作确认抽屉只在执行前展示动作、下一处理人、字段变化和审批意见。
+- 不显示 BPMN 画布、引擎内部节点或低代码配置细节。
+- 侧栏完全由应用路由清单生成。
+
+## 应用壳基线
+
+- 桌面侧栏宽度 232px，折叠宽度 68px。
+- 顶栏高度 56px，标题使用当前路由名称。
+- 稳定角色切换器必须始终可见，并明确显示当前角色与数据范围。
+- 缓存标签栏支持刷新、关闭当前、关闭其他和关闭全部。
+- 页面存在未保存内容时，导航、关闭标签、切换身份和退出都进入统一的脏状态确认流程。
+- 移动端使用抽屉导航，内容区域单列排列。
+
+## 标准页面协议
+
+### 数据管理页
+
+- 必需能力：搜索、排序、分页、列配置、密度切换、刷新。
+- 可选能力：创建、编辑、详情、删除、批量操作、导入、导出。
+- 权限决定能力是否出现，不在前端复制数据权限规则。
+- 列配置和表格密度按应用、身份、资源持久化。
+- 请求失败保留现有查询条件，并提供就地重试。
+
+### 表单提交页
+
+- 标题区包含返回、页面标题和简短说明。
+- 表单正文使用最大宽度约束，字段标签位于控件上方。
+- 主操作为保存或提交，取消为次操作。
+- 字段错误就地展示，服务器错误保留已填写内容。
+- 页面离开、标签关闭、身份切换时接入统一脏状态管理。
+
+### 表单详情页
+
+- 标题区包含业务标题、状态、关键元数据和允许的操作。
+- 字段信息按业务分组显示，不把所有字段堆进一个大表格。
+- 文件、长文本和子表拥有独立展示区。
+- 编辑入口由能力和字段策略共同决定。
+
+### 流程提交页
+
+- 业务字段表单和流程预览分区展示。
+- 提交前解析主部门、角色身份、审批人和条件分支。
+- 预览结果由后端返回，前端不自行模拟审批人解析。
+- 提交失败保留业务字段和准备阶段答案。
+
+### 流程详情页
+
+- 业务数据与流程状态分离。
+- 审批流只展示条件分支、审批节点、处理人、状态、时间和意见。
+- 当前允许操作完全由 Workflow Surface 协议返回。
+- 应用自定义操作与标准操作共享确认、幂等、审计和结果刷新机制。
+
+### 工作台
+
+- 指标、图表和待办必须来自真实 Data API、App API 或 Workflow API。
+- 快捷入口由应用声明，不在框架写死业务菜单。
+- 页面提供加载、空和错误状态。
+- 图表延迟加载，避免进入应用时加载全部 ECharts 代码。
+
+## 实现预检
+
+- 页面只使用一个主题和一个强调色。
+- 不使用渐变、玻璃效果、紫色光晕和装饰性状态点。
+- 卡片只用于表达层级，不给每个内容块套卡片。
+- 所有按钮文本在桌面端保持单行。
+- 表单标签、占位符、帮助文本和错误文本满足可读性要求。
+- 空、加载、错误、无权限和成功状态都可独立验证。
+- 所有 Admin 页面在 1440px、1024px 和移动端宽度下通过布局验证。
+- 所有新增 Ant Design API 在编码前通过本地 `antd` CLI 按 6.4.2 版本核对。

package/package.json

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