openxiangda-skill-kit 2.0.0-alpha.20 → 2.0.0-alpha.22

package/docs/architecture/admin-shell-v2.md

@@ -279,6 +279,45 @@ OpenXiangda 2.0 已经具备可运行的 Admin 基础，不应再引入一套新
 
 本轮不增加工作中心搜索。流程名称、业务编号和节点字段的搜索语义必须先由 Kernel 明确可索引字段、权限与最大长度，不能直接复用 Data API 的任意字段筛选，也不能在当前页做客户端搜索。标准页面视觉继续使用既有 `PageHeader -> Tabs -> Table -> Pagination` 层级，默认每页 20 条并显示真实总数。
 
+### 3.14 2026-08-14 标准页面实机复审与头部身份信息分层
+
+本轮再次以候选 tarball 创建的独立应用和真实 Chromium 页面为准，不以静态概念稿替代运行验收。工作台、数据管理、数据表单/详情、流程提交/详情已有完整的中低密度页面族；图片生成仍只保留给确有需要的品牌插图和空态插画。本轮只修复实机证据暴露的框架级问题，不重写已有页面。
+
+| 门禁 | 决定 |
+| --- | --- |
+| 问题与证据 | 桌面截图中角色切换器把角色名与 `college: college-medicine...` 等范围摘要共同放进选中值，长期占用头部宽度；应用名称截断后没有完整文本提示；数据详情直接显示 `available`，流程提交主要显示 `reservation-approval`，流程详情把 `nodeId` 和实例/任务 version 当作产品信息；全栈 Chromium 运行还捕获到 Ant Design 6 `Modal.autoFocusButton` 弃用告警。 |
+| 能力所有权 | 平台继续拥有 RoleSubject、范围摘要和稳定 RoleSession；Admin Shell 只拥有信息层级与呈现。选中值展示稳定角色名，候选下拉第二行保留有界范围摘要用于同名角色消歧。应用拥有状态和流程业务名称，Admin 标准页只提供渲染插槽，不猜测领域文案。 |
+| 稳定不变量 | `subjectKey` 仍是选择与切换的唯一值，角色名和范围说明不得参与身份判断；远端搜索、游标分页、最多 20 项首屏和身份 epoch 失效语义不变。应用名称提示只读，不改变路由或品牌协议。 |
+| 上下游契约 | 不修改平台 wire contract；`RoleOption` 继续包含 `value/label/description`，Select 使用 `label` 渲染当前值并通过 `optionRender` 分层渲染候选。提交页、任务页和实例页新增可选 `workflowName` 作为纯展示字段，`workflowCode` 仍是唯一协议标识；流程详情把 task title/current node 映射为“当前环节”，页头统一状态标签替代并发用 version，侧栏不重复展示同一状态；version 仍留在 Surface/命令协议中。数据详情继续复用应用声明的字段 renderer。脏表单确认迁移到 Ant Design 6 的 `focusable.autoFocusButton`。 |
+| 失败与并发 | 角色搜索失败仍保持当前稳定会话；候选范围只用于展示，即使缺失也不影响切换。角色切换仍经过 DirtyStateRegistry 和平台单活 RoleSession，不新增本地身份状态。 |
+| 安全与资源 | 范围摘要仍由平台有界返回，不在浏览器展开授权明细；下拉宽度保持 360px，超长摘要单行截断并用原生 title 提供完整提示。无新增网络请求、图表依赖或全局 store。 |
+| 回滚边界 | 仅修改 `openxiangda-admin` 的展示、样式与 Ant Design API 用法，无平台、数据库、Data API、Workflow 或 1.x 变化，可随 Admin 包独立回滚。 |
+| 可证伪验收 | Admin check/test、`antd lint`、官方模板 check/test/build，以及独立 tarball 应用桌面/移动 Chromium；头部当前值不再包含范围 ID，下拉仍可见角色范围，数据与流程页面不把已声明映射的枚举、内部流程 code、nodeId 或 version 当主要产品文案，脏表单确认不再产生弃用告警。 |
+
+### 3.15 2026-08-15 标准 Admin 设计基线
+
+本轮按产品界面而非营销页面审视 Admin。设计对象是高校与组织内部的应用管理员、学院管理员、仪器管理员和审批人，目标语言为克制、清晰、可信的桌面 B 端产品。设计参数固定为 `DESIGN_VARIANCE 4 / MOTION_INTENSITY 3 / VISUAL_DENSITY 5`，继续使用 Ant Design 6.4.2，不引入第二套组件运行时。
+
+设计稿：
+
+- [Admin Shell 与工作台](../design/admin-shell-dashboard-v2.png)
+- [数据、表单、详情与流程标准页面](../design/admin-standard-pages-v2.png)
+
+设计评审通过以下决定：
+
+1. Shell 使用浅色三层表面：布局底色、内容容器、浮层。单一钴蓝用于主要动作、选中导航和当前标签；语义色只表达真实状态。
+2. 左侧菜单来自应用静态 route manifest。设计稿中的示例栏目不进入框架默认值，没有声明的页面不占导航空间。
+3. 顶部只承载组织入口、进入用户端、通知和当前稳定角色。角色范围只在切换浮层中用于同名角色消歧。
+4. 标签存在、会话恢复和页面保活继续分别建模。固定首页不可关闭，业务标签按路由声明决定是否恢复或保活。
+5. 工作台指标使用一个连体数据表面和内部间隔，不生成四张同质悬浮卡片。快捷入口、图表和待办按业务重要度形成非对称网格。
+6. 数据管理页固定为页头、搜索、工具栏、表格、分页五层。服务端查询和权限仍由 Data API 负责；列设置、密度和排序只操作声明允许的字段。
+7. 标准编辑表单默认一到两列，窄屏收敛为单列。只有字段短、语义独立且空间充足时才允许三列；主操作位于固定底栏且每个区域只有一个 primary 按钮。
+8. 详情页把业务摘要、附件和关联记录分层，不展示内部 workflow code、nodeId、版本号或权限事实。
+9. 流程详情采用业务字段主区加审批轨迹侧栏。按钮集合完全来自 Kernel 返回的 action surface，标准组件只定义按钮优先级、确认、意见输入和错误恢复，不硬编码业务可用操作。
+10. 所有标准页面必须具备 loading、empty、error、permission denied 和 stale identity 状态；动画限于 0.1-0.3 秒的状态反馈，不增加装饰性动效。
+
+图片稿用于确定布局和视觉语义，不作为像素级实现资源。实现必须优先使用 Ant Design token、算法和组件 API；图片中的示例内容、菜单数量和字段数量不构成框架默认数据。
+
 ## 4. 总体分层
 
 ```mermaid

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

@@ -1,6 +1,6 @@
 # OpenXiangda 2.0 环境配置内核
 
-状态：方案已确认，等待按 Native 实施顺序实现；2026-08-13 已完成 AppVersion、组件修订、环境 Head、DeploymentRun、Kubernetes Runtime、Data API、Authorization、Workflow、Events 与 Secret 激活链路审计
+状态：方案已确认并按 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 后再开放。
 
 ## 1. 决策摘要
 
@@ -28,7 +28,7 @@ OpenXiangda 2.0 的运行语义采用三层模型：
 | AppVersion / alpha Environment Head | AppVersion 已组合 component revision；`app_environment_heads_v2` 同时重复保存组件指针，且 `environment_id` 外键指向 legacy `app_environments` | AppVersion 组合骨架可保留并补数据库不可变约束；alpha Head 不能复用，原生 Head 只保存 AppVersion、DeploymentRun 和 CAS revision，避免两份组件指针漂移 |
 | 两套环境实体 | legacy `app_environments` 要求每个环境绑定不同 appType；Application v2 Head 又在同一 appType 下使用环境 key，且 `environment_id` 可空 | 同一“环境”存在两种主键/晋级模型；2.0 必须引入单一原生 registry，并停止调用 legacy set |
 | Kubernetes Runtime | workload/Service 名包含 AppVersion，候选 readiness 后才在数据库事务中更新 Head；网关读取 Head 对应 DeploymentRun 的 runtime 地址 | 候选不会在 Head 提交前承接应用网关流量；激活失败保留旧流量，但失败候选需要回收 |
-| App API Gateway / Nest Guard | `node-port` 会公开版本化 Service，共享档位没有 NetworkPolicy；网关只附加可伪造的静态 `X-OpenXiangda-Forwarded-By`，Nest 仅校验 Bearer、RoleSession 和 capability | 持有合法用户 token 的调用者可能绕过活动 Head 直连旧版或候选后端；网关超时、请求大小和活动版本策略也可被绕过 |
+| App API Gateway / Nest Guard | 已签发按当前 Head 和具体 HTTP 请求绑定的短期 invocation/assertion，Nest 全局 guard 先离线验签再实时消费调用身份；健康与签名回调使用各自边界 | 路径证明已闭合；下一步由 runtime lease 关闭同进程 Worker/Scheduler 的副作用激活窗口 |
 | 候选运行凭据 | 当前 runtime credential 在候选 readiness 前已经进入可用链路；同一个 Nest 进程可以同时承载 API、Worker 和 Scheduler | 未激活 AppVersion 的启动逻辑、定时任务或 Worker 可能提前访问 Data API 或产生外部副作用，破坏原子晋级 |
 
 问题不是单一权限缓存缺陷，而是“不可变包定义”和“环境活动投影”之间缺少统一边界。授权 A0、Data API D0 和后续 Admin A1 必须建立在同一个环境配置内核上。
@@ -212,7 +212,7 @@ runtime credential 采用 `pending -> active -> retiring -> revoked` 状态并
 4. 单体 Nest 中的 Worker/Scheduler 通过平台长轮询获得短时 runtime lease；lease 绑定当前 Head revision/run，只有活动版本可续租。失去租约后停止领取新任务；已领取任务使用既有 claim lease、幂等键和接管协议，不强杀到一半。
 5. Event/Workflow 投递目标始终从活动 Head 解析，不向 pending/retiring runtime 派发新命令。旧版本只在有界 draining window 处理在途工作，随后撤销凭据并精确回收。
 
-平台对自身通道提供强保证：pending runtime 无 Data API/App API/Workflow scope、不领取任务、不接收事件，也不获得 active-only Secret。应用作者仍可能在第三方库初始化时直接访问外部系统，这不是 Nest 生命周期能单独证明的边界。生产 profile 因此按环境 `side_effect_policy` 默认拒绝候选 egress，只允许 DNS 和平台自检；活动 runtime 才获得声明过的固定 CIDR，域名型目的地通过平台受控 egress proxy 解析、审计和限流。Secret 若仅用于外部连接，在 active runtime 通过短时 runtime identity 按需读取，不以候选 Pod 环境变量提前注入。部署环境不能表达 default-deny/受控 egress 时，preflight 输出 capability failure；只有显式允许 direct-egress 的非生产策略可以继续，生产不能把框架约定冒充隔离保证。
+平台对自身通道提供强保证：pending runtime 无 Data API/App API/Workflow scope、不领取任务、不接收事件，也不获得 active-only Secret。应用作者仍可能在第三方库初始化时直接访问外部系统，这不是 Nest 生命周期能单独证明的边界。2.0 首期信任应用开发者，不建设域名代理、CIDR 审批或通用 egress 策略 DSL；外部系统连接由应用后端正常开发和负责。平台只保证自身发放的业务身份、租约和 Secret 在 Head 激活前不可用，避免把复杂而不完整的网络策略包装成安全保证。
 
 ## 7. 环境激活状态机
 
@@ -258,6 +258,8 @@ runtime credential 采用 `pending -> active -> retiring -> revoked` 状态并
 
 回滚边界：K4 之前可回滚 native-capable 镜像；K4 后只回滚到同样理解 `native-2` schema/route 的修复镜像，不能恢复 alpha 授权语义或重新打开旧 endpoint。若 K4 后验收失败，保持 2.0 maintenance、修复或把 reference app Head 切回 native 历史版本；1.x 始终不进入该栅栏。
 
+多实例门禁由平台进程自动心跳，无需应用开发者参与。每个实例上报 `PLATFORM_RELEASE_VERSION` 和固定 Native capability 集；单实例默认期望数量为 `1`，多实例部署只需把所有实例的 `OPENXIANGDA_PLATFORM_EXPECTED_INSTANCES` 设置为同一个总数。实例必须在短 TTL 内全部存活、release 完全一致且能力无缺失，`switch-native` 才能提交；`status` 同时返回逐实例证据。
+
 ## 10. 可证伪验收
 
 1. 同一应用 preproduction 发布不同角色/字段策略后，production 的 RoleSession、capability explain 和 Data API 响应逐字节不变；local 开发不产生任何远程状态。

package/docs/architecture/implementation-roadmap.md

@@ -1,6 +1,6 @@
 # OpenXiangda 2.0 实施路线图与证据矩阵
 
-状态日期：2026-08-14
+状态日期：2026-08-15
 
 本文只记录可由源码、自动测试、真实 HTTP、新应用黑盒或已发布工件证明的状态。文档存在不等于运行时完成，Mock 通过不等于平台集成完成，npm 已发布也不等于某个应用已经部署。
 
@@ -20,17 +20,17 @@
 | OAuth2 外部应用身份 | Platform Server OAuth2 服务与数据库；Nest SDK 只消费 token | 已交付 | Client Credentials、租户/应用/环境/scope 绑定、一次性 Secret、轮换宽限、撤销、审计、跨环境拒绝、应用 Principal；平台 unit/持久化/真实 HTTP 和 Nest 测试通过 | 后续只按新 scope 或凭据策略单独设计，不与 Admin 用户会话混合 |
 | 平台托管后端运行凭据 | Platform Server credential 状态 + Environment Head/DeploymentRun | 已交付功能基线，E4 激活语义待收敛 | CAS 暂存、同 AppVersion 滚动部署、旧凭据宽限、重试幂等、CLI 不获得明文；真实 HTTP 两轮通过 | 当前候选凭据仍可能在 Head 前进入可用链路。E4 改为 pending→active→retiring→revoked，业务 token/后台 lease 只授予当前 Head 对应 run；配额、告警另做运维主题 |
 | 应用 Secret | Platform Server Secret 版本与审计表 + runtime activation policy | 已交付功能基线，active-only 注入待收敛 | 环境级 AAD、只写值、不可变版本、CAS 幂等、required/optional 部署语义、删除和审计测试 | P0 只校验所需版本存在，不向 pending runtime 提前注入 active-only Secret；E4 通过短时 runtime identity 按需读取并受 egress policy 约束。KMS 替换保持同一协议，不在应用端增加第二套存储 |
-| Data API / App API | Platform Server 物理 schema + 环境 Head 选择的逻辑 config projection；应用后端承载业务逻辑 | 已交付功能基线，环境配置/调用委托待重构 | 用户与服务 Principal、PostgREST RLS、字段/行权限、受限事务批处理、应用网关与真实 NestJS 纵向链路通过；业务行已按环境隔离 | 当前逻辑定义仍被任意环境部署写入应用级活动记录；网关还把调用者原始 bearer 转发给应用且静态 Forwarded-By 可伪造。E2 完成 physical/logical 分离，E4 增加 invocation token + gateway assertion，不能靠 NodePort/NetworkPolicy 充当授权 |
+| Data API / App API | Platform Server 物理 schema + 环境 Head 选择的逻辑 config projection；应用后端承载业务逻辑 | Native 调用委托与请求路径证明已交付；逻辑配置投影继续收敛 | 用户与服务 Principal、PostgREST RLS、字段/行权限、受限事务批处理、最长 60 秒 invocation token、最长 30 秒 Ed25519 assertion、Nest 全局 transport guard 与同构本地平台已通过 | 继续完成 E2 physical/logical 分离和 E4 runtime lease；NodePort/NetworkPolicy 只缩小暴露面，不参与授权正确性 |
 | RBAC + 业务关系权限 | Platform Server 原生 authz revision、环境 state、RoleMembership、RelationshipGrant、RoleSession | A0-N0/N1/N2/C1/C2/P 已实现 | N2 新建环境级 manual role/membership/delegation/relationship、应用级 super-admin grant、Native RoleSession 与不可变 mutation receipt；C2 每请求先以 PostgreSQL 校验 session/state/主体，再使用环境、authz/scope 版本与主体 revision 隔离的 Redis summary；P 以 `scopeSources` 将学院管理员、仪器管理员等业务表映射为环境范围 grant，Data API 同事务置 stale/建任务，Worker 提供 lease/retry/DLQ/replay/receipt/closure，strict 投影失败关闭且恢复扫描不依赖 Redis | 下一步 A0-N3/N4 完成全实例 gate、Native generation switch 与真实 PostgreSQL/PostgREST/K3s 验收；Admin A1 只消费 native kernel |
 | Events/Automation v2 | Platform Server delivery/receipt 状态；Nest handler 承担业务副作用 | 已交付 | CloudEvents 签名、claim lease、重复投递、进程崩溃接管、stale token 隔离、重试/DLQ/replay、双密钥、重启恢复与持久 receipt 真实链路两轮通过；Native 本地层已由 CLI 新建独立应用，在真实 PostgreSQL 上覆盖 503 + Retry-After、确定性 400 死信、幂等重放和成功回执；Timer 使用严格六段 Cron + IANA 时区，调度、事件、outbox 与下一触发点在同一事务提交，并通过同一计划时间并发 claim、重启恢复与 reset 验收 | 外部副作用仍必须使用 event id 做下游幂等；不承诺跨系统 exactly-once；停机期间的 Timer 采用合并补偿而非历史洪峰补发 |
 | Workflow Kernel v2 | Platform Server 持久状态机；Admin 只解释 Surface 协议 | 进行中 | 本地独立应用已在真实 PostgreSQL 验证预览令牌单次消费、实例/任务/参与者链/时间线/回执事务提交、跨重启幂等回放、实例与任务版本 CAS、并发审批唯一成功和 reset 清理；转交与任务代理真实切换 RoleAssignment 待办归属，前/后加签使用有序参与者链，目标身份按角色和数据 scope 校验；长期代理按半开时间窗和不重叠规则解析，在预览与任务创建间 CAS 校验，把规则、有效期、原审批人及代理身份冻结进参与者链，撤销仅影响新任务；浏览器使用独立测试用户覆盖代理待办归属与冻结审计 | 远端 Kernel 与 1.x 双核运行、远端长期代理事务和过期任务管理员重分派仍需继续验收 |
 | Workflow Kernel v2 | Kernel 状态机与平台持久实例；业务字段仍在 Data/App API | 已交付基线 | 同意/拒绝、转交、回退、撤回、加签、代理、两种退回语义、重新提交、长任务委托、Provider 恢复与并发 CAS/lease 真实链路通过 | 可视化编辑器和更多业务协议按独立需求设计；不把业务字段迁入流程库 |
 | 独立 NestJS 后端与应用交付 | 应用 Git/AppPackage；Platform Server DeploymentRun/Environment Head | 已交付功能基线，E4 激活边界待实现 | 不可变包摘要、后端 OCI digest、版本化 Kubernetes workload、readiness、重试/取消/回滚/晋级和资源限制已有证据 | 候选当前可能先取得可用 runtime credential，同进程 Worker/Scheduler 缺活动 Head lease，共享 NodePort 缺强路径证明。E4 以 pending credential、短租约、gateway assertion、failed candidate GC 收敛；仍保持每应用独立容器，不拆成多应用 Node 进程或强制三个 Deployment |
-| 2.0 CLI/MCP/Skills/模板 | 独立 `openxiangda-v2` 仓库与已发布 npm 工件 | 已交付基线 | 16 包 check/test/build、边界扫描、真实 tarball 新应用、持久 reference app、Chromium、Skills、文档全部通过；不调用 1.x | 新能力必须同时更新命令/MCP/Skill/模板消费证据，禁止只写 CLI 命令 |
+| 2.0 CLI/MCP/Skills/模板 | 独立 `openxiangda-v2` 仓库与已发布 npm 工件 | 已交付基线 | 16 包 check/test/build、边界扫描、真实 tarball 新应用、持久 reference app、Chromium、Skills、文档全部通过；2026-08-15 再以 12 个候选 tarball 经临时本地 registry 安装到仓库外参考应用，生成、类型检查、单测、真实 NestJS OAuth2/Native 身份联调与生产构建全部通过；不调用 1.x | 新能力必须同时更新命令/MCP/Skill/模板消费证据，禁止只写 CLI 命令 |
 | 确定性工具链发布 | Changesets 版本提交、冻结工件清单、release receipt | 已交付 | 待消费 Changeset 在构建前 fail-fast；版本只由 Changesets 物化；正式发布只验证一次同一批 tarball；CLI alpha.20 与 skill-kit alpha.19 已按该状态机发布并打 Git tag | 周期性全量审计保留；不得恢复人工选包、手工版本或重复正式门禁 |
 | 环境配置内核 E0-E6 | AppVersion/component revision + native Runtime Environment + minimal Environment Head + 环境运行态 | E1-C0/C1/S0/S1/T0 已完成 | breaking config/contracts v3、平台纯编译器、六领域不可变投影、聚合投影、AppVersion binding、compile receipt、精确 artifact shadow prepare 与真实 PostgreSQL 并发/来源防伪/绑定后不可变已经通过；全新 `openxiangda-v2-native-reference-app` 由候选 tarball 创建并完成 check/test/build，连续构建逐字节一致，config/contract v3 闭包和 artifact/manifest 篡改拒绝已进入发布门禁 | 下一步进入 A0 Native 环境授权；随后实现 Data physical/logical、最小 Head CAS、pending credential、调用委托/网关断言、runtime lease、候选 GC 与 generation cutover。旧 alpha 只留审计历史，不做双读、双写或导入 |
 | 授权内核 A0-N/C/P | 不可变 authz revision + 环境 authz state + native role/scope 表 | 已确认实施；N0/N1/N2/C1/C2/P 完成 | N1/C1 建立不可变定义、两环境 state 与原子版本；N2 建立独立 Native 运行表与局部撤权；C2 建立 DB-authoritative evaluator、request cache、环境/版本 cache namespace、边界 TTL 与 RelationshipGrant 直读；P 升级 `native-2` 配置契约并建立 source definition、projection state/job/receipt/value/closure/effective grant、Data API 与 membership 原子失效、冷启动恢复与 strict gate；89 个 SQL migration 校验、35 个 2.0 migration 真实 PostgreSQL 幂等应用、39 个平台套件 / 263 项测试和工具链全 workspace 测试通过 | 当前推进 N3-N5。alpha membership/grant 不复制、不迁移，禁止给 legacy 表补 environmentKey 或建立长期双读/双写 |
-| Admin Shell v2 完整框架 | 平台 RoleSession 上下文 + Admin Core | 实施中 | A1/A2 Native 身份、UX1、B1.1 结构化 route manifest、B1.2 标准记录页/资源失效、B1.3 流程业务提交适配、B2 有界保活、C 个人中心贡献化、D Data Workbench controller、DirtyStateRegistry/实例释放门禁、标准流程工作中心与 Kernel 服务端分页已落地；标准列表与特殊工作台现共享身份隔离的 DataQuery 状态机，Core-only 构建不含 Workflow 代理；全新改名应用的 Chromium 场景覆盖服务端搜索/排序请求、中文分页、列表到记录、业务保存、脏数据/流程表单放弃确认、完整流程操作、标签恢复、动态详情不恢复、角色切换页面重建和工作中心交互 | 安全退出的 B0-R 平台接入仍待完成；安全轨和产品轨在完整生产验收前汇合 |
+| Admin Shell v2 完整框架 | 平台 RoleSession 上下文 + Admin Core | 实施中 | A1/A2 Native 身份、UX1、B1.1 结构化 route manifest、B1.2 标准记录页/资源失效、B1.3 流程业务提交适配、B2 有界保活、C 个人中心贡献化、D Data Workbench controller、DirtyStateRegistry/实例释放门禁、标准流程工作中心与 Kernel 服务端分页已落地；标准列表与特殊工作台共享身份隔离的 DataQuery 状态机，Core-only 构建不含 Workflow 代理；角色选择器只在选中态展示稳定角色名、在下拉项有界展示 scope，数据与流程页面隐藏协议码并展示业务标签；全新 tarball 应用在显式安全 reset 后以 8 个 Chromium 场景一次穿过 React、本地平台、NestJS 与真实 PostgreSQL | 安全退出的 B0-R 平台接入仍待完成；安全轨和产品轨在完整生产验收前汇合 |
 | Admin A1 RoleSession 上下文 | Native RoleSession bootstrap 是唯一身份资料/role subject/scope 来源 | 已设计待确认 | SubjectProfile 字段白名单、tenant 联合查询、非 active scope=null、capability=`authz.role-session-context`、有界 role subject 分页与切换 CAS 已定义 | A0 native cutover 后实现；A1 自身不再增加身份存储，但不得建立在 alpha 全局 assignment 上；平台先发，工具链后要求 capability |
 | Admin B0-O 租户公共 Origin | Platform Server Origin module + 版本/head/hostname claim registry | 已设计待确认 | 全仓确认多套模糊解析和广泛 URL 调用者；prod-1 证实 HTTPS/HTTP 配置差异、未登记 vhost 别名，且生产 `default_configs` 没有源码宣称的复合唯一约束；稳定租户 UUID、不可变 staged→challenge→verified→active、head revision CAS、hostname claim、事务审计、全局兼容阶段+单租户事实源状态、无长期双写和[逐文件实施蓝图](./tenant-public-origin-implementation-blueprint.md)已定义 | 确认后先做 O0 只读 inventory/digest 与 plan validator；操作者显式决定 migrate/decommission，所有服务实例同版后进入 migrating，再逐租户冻结/验证/切换，单租户失败不阻塞全平台；B0-R 不得绕过该阶段 |
 | Admin B0-C Cookie 安全 | Platform Server `AuthCookieService` + 无状态 policy resolver | 已设计待确认 | 已确认当前 DOMAIN JSON 同时决定 Cookie Domain 且 `secure:false`；共享会话/协议 Cookie 所有权、HTTPS Secure/`__Host-`/host-only、版本化名称、legacy scope manifest、C0/C1/C2 状态机和旧 host retirement 已定义 | B0-O registry 稳定后独立实现；首期不支持跨子域共享；C1 后只能回滚到理解 v2 Cookie 的兼容镜像，不和 Origin 数据迁移、return target 或 OAuth state 混发 |

package/docs/architecture/local-development-v2.md

@@ -62,6 +62,29 @@ Browser
 - PostgreSQL 是默认平台状态存储。开发者不安装 PostgreSQL 服务、客户端、用户或建库脚本；只需 Docker Desktop 或兼容容器运行时。CLI 启动摘要固定的 PostgreSQL 16 镜像，按 canonical workspace 创建独立容器和 volume，自动完成建库、迁移、健康检查与 schema digest 校验，不复用任意同端口数据库。
 - 无容器运行时时，默认命令返回明确诊断；显式 `--ui-only` 才允许使用无持久性的页面模拟器，并在页面持续显示“UI-only，不可作为平台验证”的标识。CI、`openxiangda test` 和发布检查从不接受 UI-only 证据。
 
+### 3.1 2026-08-14 Native App API 用户身份闭环
+
+| 门禁 | 决定 |
+| --- | --- |
+| 问题与证据 | 完整本地会话中，Admin 已使用 `openxiangda.native-role-session/v2`，App API 网关也签发绑定该会话的 60 秒 loopback token；Nest SDK 却继续请求 alpha `/authz/principal`。本地验证器最终又把 token 中的 Native session id 与 `openxiangda.role-session/v2` 比较，导致真实 Chromium 流程保存稳定返回 `401 LOCAL_USER_IDENTITY_INVALID`。 |
+| 能力所有权 | Native RoleSession 服务是 2.0 用户身份的唯一所有者；网关只签发和转发短期调用身份；`openxiangda-nest` 只通过平台 `/native/authz/principal` 与 `/native/authz/explain` 校验并注入 Native Principal/RoleSession，不建立映射或兼容状态。 |
+| 稳定不变量 | 浏览器原始 Authorization 不进入应用；token 必须绑定 app、`runtimeMode=local`、Native RoleSession、60 秒 TTL 和随机 nonce；Nest handler 只收到平台重新验证后的 Native identity。应用身份 OAuth2 仍走独立 `/oauth2/principal`，不允许用无 RoleSession 的服务身份冒充用户。 |
+| 上下游契约 | `openxiangda-nest` 的用户上下文改为 `NativePrincipal + NativeRoleSession`，SDK 用户授权路径固定为 `/native/authz`；本地平台补齐同形 principal 端点；官方 Nest 模板的 controller/service 类型同步改为 Native 类型。2.0 不增加 alpha fallback 或运行时开关。 |
+| 失败与并发 | 缺失、签名错误、过期、错误 app 或 stale Native RoleSession 均在业务 handler 前拒绝。角色切换后旧 token 即使尚未到期也因 session id 不匹配失败；授权 explain 必须再次校验同一 Native session，写操作不自动重放。 |
+| 安全与资源上限 | loopback token 固定 60 秒且只接受 HMAC 等长比较；payload 不携带 allow 结果、业务数据或 Secret。principal/explain 仍受 SDK 5 秒默认超时约束，不增加缓存或后台刷新。 |
+| 回滚边界 | 只发布 `openxiangda-local-platform`、`openxiangda-nest` 和包含新类型消费的创建模板；本地数据 schema、远程 Head、1.x SDK 与旧应用无变化。回滚时三个工件作为同一测试 BOM 恢复。 |
+| 可证伪验收 | 单测断言 Nest 请求 Native 路径并注入 Native schema；本地平台拒绝伪造/错误 session token；全新独立应用在真实 PostgreSQL 下通过 App API 保存、流程预览、发起和后续审批 Chromium 场景。 |
+
+### 3.2 2026-08-14 确定性浏览器验收边界
+
+| 门禁 | 决定 |
+| --- | --- |
+| 问题与证据 | Playwright 复用日常开发会话时，历史修改会污染种子数据断言；若测试配置自行删除数据库，又会绕过 CLI 对工作区、容器和 volume 的所有权校验。先跑 UI-only、再跑完整会话还会重复同一批浏览器成本，却不能增加后端证据。 |
+| 能力所有权 | 日常 `openxiangda dev` 永远保留开发数据；外部 `OPENXIANGDA_E2E_BASE_URL` 只连接现有会话且零清理；发布门禁由打包工具链创建一次性外部应用，并且只能通过 `openxiangda dev reset --data` 建立确定性初始状态。 |
+| 稳定不变量 | 浏览器测试不拥有任意开发者 volume。一次性验收应用完成重置后，Chromium 只运行一次，但路径必须同时穿过 React、独立本地平台、NestJS 与真实 PostgreSQL。UI-only 只服务快速页面回归，不能重复计作完整证据。 |
+| 失败与回滚 | reset、进程就绪或任一浏览器场景失败立即终止门禁并保留诊断；一次性工作区与其有所有权标签的资源是唯一清理边界。回滚只需恢复打包验证器，不改变开发数据和线上环境。 |
+| 可证伪验收 | 被历史修改污染的持久会话不再用于种子套件；全新 tarball 应用在安全 reset 后通过 8 个 Chromium 场景、重启持久化、事务幂等、并发、事件重放、Workflow/Timer 恢复和最终隔离检查。 |
+
 ## 4. 本地身份与状态
 
 - 本地平台为当前工作区生成短期签名材料和 runtime OAuth client，保存在 `.openxiangda/local/`，目录必须被 Git 忽略。原始 OAuth Secret 只注入 NestJS 子进程；Web 子进程和 manifest 只能看到非敏感元数据。

package/docs/backend.md

@@ -16,7 +16,7 @@ src/health         liveness/readiness
 
 ## 身份和接口
 
-平台网关将用户 token 传给应用后端。`openxiangda-nest` 校验 token，并构造包含 tenant、application、user、activeRole、attributes、correlationId 的上下文。面向其他系统的接口同样经平台域名和网关发布，使用 OAuth2 client credentials 获取的短期应用身份与 scope。
+调用者原始 token 只到平台网关，不进入应用容器。网关根据当前 Native Head 换取最长 60 秒的 invocation token，并用最长 30 秒的 Ed25519 assertion 绑定目标应用、环境、AppVersion、DeploymentRun、请求方法、路径、查询和正文摘要。`openxiangda-nest` 的全局 transport guard 在业务控制器前校验 assertion 与运行容器身份，再向平台实时确认 RoleSession/Application Principal；NodePort、cluster DNS 或反向代理直连因缺少 assertion 被拒绝。应用开发者不配置网关密钥，也不手写这段校验。
 
 用户身份必须绑定 RoleSession；应用身份绑定 tenant、app、environment、client、credentialVersion 和 scopes。业务 controller 使用生成的 `appOperations` 和 `@OpenXiangdaOperation()` 同时绑定不可变 operation contract 与 capability；`OpenXiangdaAuthzGuard` 对服务身份要求 `app:invoke` 和完全匹配的 operation capability。`@RequireCapability()` 只保留给官方 SDK 内部与非业务适配层，应用 controller 不应散写 capability 字符串。应用身份可以调用授权的 App API/Data API，但 Workflow 客户端拒绝没有用户 RoleSession 的上下文。
 
@@ -33,6 +33,13 @@ OpenXiangdaModule.forRoot({
   appCode: process.env.OPENXIANGDA_APP_CODE!,
   platformBaseUrl: process.env.OPENXIANGDA_PLATFORM_BASE_URL!,
   environmentKey: process.env.OPENXIANGDA_ENVIRONMENT_KEY!,
+  environmentId: process.env.OPENXIANGDA_ENVIRONMENT_ID!,
+  appVersionId: process.env.OPENXIANGDA_APP_VERSION_ID!,
+  deploymentRunId: process.env.OPENXIANGDA_DEPLOYMENT_RUN_ID!,
+  environmentHeadRevision: Number(
+    process.env.OPENXIANGDA_ENVIRONMENT_HEAD_REVISION!
+  ),
+  backendRevisionId: process.env.OPENXIANGDA_BACKEND_REVISION_ID!,
   version: process.env.OPENXIANGDA_APP_VERSION!,
   oauthClient: {
     clientId: process.env.OPENXIANGDA_OAUTH_CLIENT_ID!,

package/docs/delivery.md

@@ -48,7 +48,7 @@ Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立
 
 发布入口只打包一次，并在 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，并比较候选与上一发布版本；漏升版或待消费 Changeset 会在昂贵测试前直接失败。`pnpm release:publish` 冻结一次候选工件，执行机器生成的增量计划，并在成功后发布同一批 tarball；候选依赖闭包永远完成 check/test/build，每个候选 tarball 都在 monorepo 外安装进全新生成应用并完成 generate/check/test/build。浏览器相关变化提升到真实 Chromium E2E，核心应用 SDK 变化增加持久 reference app，Skill/文档变化增加相应门禁。`pnpm verify:release` 提供相同规则的无发布演练，不能与正式发布组合成必须重复执行的双门禁。未知变化 fail-closed 到完整矩阵；`pnpm verify:release:full` 保留周期性全量审计。
+`pnpm verify:local` 是日常可重复执行的全量验收入口。涉及本地 PostgreSQL 生命周期时，候选 tarball 只在 monorepo 外的新应用中运行一次 Chromium：生命周期门禁先通过受所有权校验的 reset 建立确定性数据库，再让同一浏览器套件同时经过 React、本地平台、NestJS 与 PostgreSQL；不会先跑 UI-only 再重复浏览器工作，也不会清理开发者现有应用的数据。正式候选在版本提交推送后由 `pnpm release:plan` 比较 npm 与本地 tarball，并比较候选与上一发布版本；漏升版或待消费 Changeset 会在昂贵测试前直接失败。`pnpm release:publish` 冻结一次候选工件，执行机器生成的增量计划，并在成功后发布同一批 tarball；候选依赖闭包永远完成 check/test/build，每个候选 tarball 都在 monorepo 外安装进全新生成应用并完成 generate/check/test/build。浏览器相关变化提升到真实 Chromium E2E，核心应用 SDK 变化增加持久 reference app，Skill/文档变化增加相应门禁。`pnpm verify:release` 提供相同规则的无发布演练，不能与正式发布组合成必须重复执行的双门禁。未知变化 fail-closed 到完整矩阵；`pnpm verify:release:full` 保留周期性全量审计。
 
 Playwright 浏览器使用官方缓存目录；`playwright install chromium` 已安装对应版本时是无操作。发包门禁不会额外运行 1.x 测试，也不会为每个包重复浏览器验收，而是在最终独立新应用上只运行一次完整用户路径。
 

package/docs/frontend.md

@@ -38,7 +38,7 @@ Ant Design 6.4.2 是唯一运行时设计系统。ProComponents 作为成熟交
 - `ApplicationOperationsPage` 提供应用管理员运行视图：平台契约、当前身份、后端 readiness/version、不可变 AppVersion 最近部署、事件重试/死信和 `eventId/requestId/traceId` 关联信息集中展示；事件订阅与定时事件可按 revision 暂停/启用，重试或死信可显式创建新投递并保留原记录。各探针独立失败，不会因为一个依赖不可用而把整页变成白屏，诊断快照可一键复制。
 - `ApplicationCredentialsPage` 提供标准的应用管理员安全控制面：外部 OAuth2 Client 生命周期与审计、平台托管后端运行时凭据的分阶段轮换、环境级只写应用 Secret 生命周期与审计、Workflow 审批人 Provider 密钥轮换。浏览器只保存当前表单状态；外部 Client Secret 仅在成功响应后一次性展示，关闭即清除；应用 Secret、运行时凭据和 Provider 密钥永不回显或写入快照、日志与持久化缓存。
 - 生产应用从 `openxiangda-admin/core`、`/data`、`/dashboard`、`/operations`、`/credentials`、`/workflow` 子路径导入，并用 `React.lazy` 声明业务路由。个人中心领域区块通过 `definePersonalCenterSections` 显式装配；Workflow 代理只从 `/workflow/personal-center` 导入。官方模板的构建门禁要求首页、数据页、运维页、凭据页和流程页保持独立异步 chunk，同时限制单 chunk 与首屏 JavaScript 预算，并用 Core-only 构建证明无 Workflow 应用不会携带代理代码。
-- 工作流页面按后端返回的 actions、fieldPolicy 和 presentation 渲染按钮与字段。`WorkflowSubmissionPage` 并列展示业务表单与审批预览，应用只实现 `saveBusiness`：用 Data API 或 NestJS App API 保存后返回 `businessKey + dataRef(revision) + facts`。业务字段、主部门或审批人答案发生变化后，旧 preparation token 立即失效；业务保存与实例发起各自使用稳定幂等键，网络重试不会重复创建。标准流程详情页分离业务字段、流程摘要、当前操作、审批参与者和流转审计。业务记录由 Data API/App API 加载，`edit_required` 在操作前验证，变更以 revision 乐观锁先保存后执行流程命令；Workflow Kernel 不保存业务字段，业务状态的后续投影由 App API 或流程事件消费者负责。
+- 工作流页面按后端返回的 actions、fieldPolicy 和 presentation 渲染按钮与字段。`WorkflowSubmissionPage` 并列展示业务表单与审批预览，应用只实现 `saveBusiness`：用 Data API 或 NestJS App API 保存后返回 `businessKey + dataRef(revision) + facts`。提交页、任务页和实例页用可选 `workflowName` 展示业务名称，稳定 `workflowCode` 仍用于协议请求，不把内部 code 当作主要产品文案。流程详情使用可读的流程名称、当前环节和流程状态；`nodeId` 与实例/任务 version 继续服务于路由、并发和命令协议，不作为普通用户的主要信息。业务字段、主部门或审批人答案发生变化后，旧 preparation token 立即失效；业务保存与实例发起各自使用稳定幂等键，网络重试不会重复创建。标准流程详情页分离业务字段、流程摘要、当前操作、审批参与者和流转审计。业务记录由 Data API/App API 加载，`edit_required` 在操作前验证，变更以 revision 乐观锁先保存后执行流程命令；Workflow Kernel 不保存业务字段，业务状态的后续投影由 App API 或流程事件消费者负责。
 - 流程工作中心使用统一 `PageHeader` 装配发起与刷新操作；应用只用 `workflowLabels` 提供业务流程名称和 `onOpen` 导航。Kernel 返回同一数据库快照中的 `total/limit/offset` 和确定性排序结果；Admin 只把页码转换为 offset。分类、页码或身份切换会使旧请求失效，错误在页面内重试，状态、时间、空态和“处理/查看”入口由 Admin 统一呈现，不做客户端搜索或第二套查询规则。
 - 个人中心 Core 固定展示资料、环境、当前身份、数据范围、刷新和角色切换。领域区块复用路由的 `capability` / `access` 表达式并 fail closed；Workflow 模块可选贡献长期代理，选择代理人后必须再选择其具体应用角色绑定和数据范围。代理始终绑定发起人的当前稳定身份，不合并其他角色权限。
 

package/docs/getting-started.md

@@ -51,6 +51,8 @@ pnpm test:e2e
 
 `openxiangda dev` 是唯一受监督的日常入口：它启动完整 Admin、相互隔离的 React/Vite 与 NestJS 进程、独立 loopback 本地平台，以及工作区隔离的 PostgreSQL。开发者**不需要安装 PostgreSQL**，只需要 Docker Desktop 或兼容容器运行时；CLI 自动下载摘要固定的镜像、创建数据库、选择端口并限制容器资源。关闭前台命令或执行 `openxiangda dev stop` 时只停止进程和容器并保留项目专属 volume，因此数据在重启后仍存在。`openxiangda dev status` 查看当前/上次会话；只有显式执行 `openxiangda dev reset --data` 才会在校验工作区、容器、数据卷和凭据归属后删除本地数据库与凭据。`openxiangda dev --reset` 是“安全重置后立即启动”的快捷形式。工作区内部 `pnpm dev` 只供 CLI 编排，不负责平台进程、数据库、会话锁和清理，不作为公开开发命令。local 不是远程环境，不要求 provision 或远程 OAuth/Secret。`generate` 根据配置生成 Data、AuthZ、Event 与 Workflow 类型。`check` 必须是确定性的：同一提交、同一依赖锁、同一配置产生同一结果。完整本地模型见 [本地开发内核](./architecture/local-development-v2.md)。
 
+默认 `pnpm test:e2e` 会自行启动隔离的 UI-only 快速回归。需要把同一套 Chromium 场景作为完整本地集成证据时，先保持 `openxiangda dev --no-open` 运行，再执行 `OPENXIANGDA_E2E_BASE_URL=http://127.0.0.1:<web-port> pnpm test:e2e`。此时 Playwright 不创建第二个服务器，而是验证浏览器、独立本地平台、NestJS 与项目专属 PostgreSQL 的同一受监督会话；`<web-port>` 以 `openxiangda dev status` 为准。外部会话模式不会隐式重置开发数据，针对确定性种子数据的整套回归只能指向一次性验收应用，或由开发者先明确停止并执行 `openxiangda dev --reset`；不得在测试配置中绕过 CLI 所有权校验直接清理容器或 volume。
+
 完整模式下，浏览器对 App API 的请求先进入本地平台网关：网关验证当前稳定 RoleSession，丢弃浏览器自带的 Authorization，再用仅限 loopback 的短期平台身份转发给 NestJS。CLI 另外创建一个 workspace runtime OAuth client，只把原始 Secret 注入 `dev:server`，供 Worker/Scheduler/后台业务调用 Data API；Vite 进程拿不到该 Secret。数据库连接、OAuth 凭据和其他本地状态位于 Git 忽略的 `.openxiangda/local/state/`，权限为仅当前用户可读写，并且不会进入 AppPackage。
 
 开发 2.0 工具链本身时，每一轮可用一个命令完成发布前同等级的本地验收：
@@ -59,7 +61,7 @@ pnpm test:e2e
 pnpm verify:local
 ```
 
-它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、Chromium 交互、生产构建、Skill 和文档；还会用真实 PostgreSQL 验证工作区隔离、资源限制、重启持久化、事务幂等回放和显式重置。它不会执行 npm 发布、Git 提交或平台部署。
+它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、生产构建、Skill 和文档；Chromium 只运行一次，并在该临时应用经过显式安全重置后的完整受监督会话中同时验证 React、独立本地平台、NestJS 与真实 PostgreSQL。相同生命周期还验证工作区隔离、资源限制、重启持久化、事务幂等回放和显式重置。它不会执行 npm 发布、Git 提交或平台部署。
 
 准备发包时，先从干净且已同步远端的 `master` 物化已经评审的 Changesets，
 检查生成的包版本、内部依赖与模板 BOM，提交并推送该版本提交，然后查看机器生成的影响计划：
@@ -129,7 +131,7 @@ openxiangda status <deployment-id>
 
 CLI 上传应用包并创建 DeploymentRun；部署、重试、健康检查和激活都由平台执行。CLI 退出不影响发布继续进行。生产只晋级预发已验证的同一不可变 AppVersion，不重新构建。
 
-`app provision` 只用于首次创建平台中的稳定 2.0 应用身份，可安全重试，且需要平台管理员身份。日常 CI 使用该应用的发布权限即可，不需要平台管理员。
+`app provision` 只用于首次创建平台中的稳定 2.0 应用身份，并在同一事务中补齐稳定的 `preproduction`、`production` 原生环境；命令可安全重试，且需要平台管理员身份。日常 CI 使用该应用的发布权限即可，不需要平台管理员。
 
 ## AI 入口
 

package/docs/reference/cli.md

@@ -9,7 +9,7 @@
 | `auth logout` | write-local | 删除当前登录会话 |
 | `app create` | write-local | 从官方模板创建 2.0 应用 |
 | `app link` | write-local | 绑定平台地址和应用环境 |
-| `app provision` | deploy | 在平台幂等创建 2.0 应用身份 |
+| `app provision` | deploy | 在平台幂等创建 2.0 应用身份和预发/生产环境 |
 | `app info` | read | 读取应用工作区上下文 |
 | `authz membership list` | read | 查询 Native 应用角色成员 |
 | `authz membership grant` | deploy | 授予 Native 应用业务角色 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.22",
   "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.17"
+    "openxiangda-devkit-core": "2.0.0-alpha.19"
   },
   "devDependencies": {
     "tsx": "4.23.12",