openxiangda-skill-kit 2.0.0-alpha.31 → 2.0.0-alpha.32

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

@@ -12,7 +12,7 @@ OpenXiangda 2.0 的运行语义采用三层模型：
 2. **环境选择层**：最终的 `app_runtime_environment_heads_v2` 是某个原生环境当前运行哪个 AppVersion/DeploymentRun 的唯一指针。预发和生产可以选择不同修订；晋级仍使用同一个 AppVersion，不重建制品。现有 `app_environment_heads_v2` 的 `environment_id` 外键指向 legacy `app_environments`，只作为 alpha 历史审计事实，不能原地改造成最终 Head。
 3. **环境运行态层**：RoleMembership、manual role、业务范围 grant、RelationshipGrant、RoleSession、Workflow 实例、Event receipt、OAuth client 和 Secret 等可变状态绑定远程环境。生产运行态不能被预发部署覆盖。
 
-2.0 只有一套远程环境身份模型：一个稳定 `tenant + appCode` 下恰好包含 `preproduction`、`production` 两个原生运行环境，每个环境有稳定 UUID 和不可变 route key。同一个 AppVersion 先部署到预发，再原样晋级生产。`local` 是开发机上的运行模式，不注册环境 UUID、不创建远程 Head/OAuth/Secret/RoleSession，也不能作为 deploy/promote 目标。现有 `app_environment_sets/app_environments` 用“不同 appType 分别代表预发和生产”的模型保留给 1.x 发布治理，不再由 2.0 CLI、AppVersion 或 native runtime 使用。
+2.0 只有一套远程环境身份模型：一个稳定 `tenant + appCode` 下恰好包含一个 `preproduction`，并在首次明确晋级时最多创建一个 `production` 原生运行环境；每个已创建环境有稳定 UUID 和不可变 route key。同一个 AppVersion 先部署到预发，再原样晋级生产。`local` 是开发机上的运行模式，不注册环境 UUID、不创建远程 Head/OAuth/Secret/RoleSession，也不能作为 deploy/promote 目标。现有 `app_environment_sets/app_environments` 用“不同 appType 分别代表预发和生产”的模型保留给 1.x 发布治理，不再由 2.0 CLI、AppVersion 或 native runtime 使用。
 
 物理存储和逻辑运行契约必须分开：Data API 的物理表与新增列是应用级、单调扩展的共享基础设施，业务行继续通过 `environment_key` 隔离；当前允许访问哪些字段、capability、字段策略和 data policy，则由请求环境 Head 选择的不可变 config revision 投影决定。contracts revision 用于证明前端、后端与配置引用的是同一组稳定代码，不保存完整字段 schema。
 
@@ -94,7 +94,7 @@ app_runtime_environment_heads_v2
 ```
 
 - 一个 2.0 app 固定两个长期远程环境；不支持 development 远程环境、任意自定义 key、同 kind 多环境或 key rename。
-- 新应用 provision 事务一次创建 preproduction/production；任一创建失败整笔回滚。部署请求不能隐式补环境，生产环境必须有更严格 side-effect policy 与管理员确认。
+- 新应用 provision 事务只创建 preproduction；首次 promotion 在唯一约束下惰性创建 production。普通部署请求不能隐式补环境，生产环境必须有更严格 side-effect policy 与管理员确认。
 - `environmentId` 进入 OAuth client、Secret、RoleSession、Workflow/Event、DeploymentRun 和授权运行态；对外 DTO 同时返回 id/key/kind，但任何写请求中的 id/key 必须与认证 Principal、app 和 registry 相互匹配。
 - 旧 `app_environment_sets/app_environments` 的跨 appType swap、attach 和 policy 接口不再出现在 openxiangda-v2 CLI/Skill。旧 CLI 和 1.x 应用保持原行为。
 - 原生 Head 不重复保存 frontend/backend/config/contracts revision。AppVersion 是组件组合的唯一事实，`app_version_projection_bindings_v2` 是 AppVersion 到编译后配置闭包的唯一映射；读取方通过它们解析。数据库复合外键必须证明 Head、AppVersion、DeploymentRun 与 environment 属于同一个 tenant/app，不能只靠服务层比较 UUID。

package/docs/architecture/implementation-roadmap.md

@@ -18,6 +18,7 @@
 
 | 能力主题 | 唯一事实来源 | 当前状态 | 已有证据 | 尚缺内容与下一道门 |
 | --- | --- | --- | --- | --- |
+| 按需生产环境与运行启停 | Platform Server Native 环境 registry + Environment Head + DeploymentRun；K3s 只执行平台期望状态 | 已实现待线上验收 | provision 仅创建预发、promotion 惰性创建唯一生产、`runtime_state` CAS、start/stop durable run、停止网关 503、ReplicaFailure 快速诊断、CLI/MCP/Contracts 与能力协商均已实现；平台 targeted 测试、构建、101 条 migration 静态校验和 47 条 Native migration 真实 PostgreSQL 幂等应用通过 | 完成工具链正式发包和 prod-1 migration/image 部署；以全新应用证明初始无 production、预发 stop→0/start→ready、首次 promotion 才出现 production，并停止闲置旧测试环境释放配额 |
 | 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 替换保持同一协议，不在应用端增加第二套存储 |

package/docs/architecture/native-configuration-projection-v2.md

@@ -205,7 +205,7 @@ app_runtime_environments_v2
 
 - key/kind/tenant/app 创建后不可修改；环境不物理删除，只能在满足无活动 Head、runtime、数据和安全状态引用的独立计划中 decommission。
 - native UUID 只由新应用的显式环境创建事务生成；旧 alpha Head/environment UUID 不复用、不映射。
-- 新应用 provision 事务一次创建 preproduction/production；任一创建失败整笔回滚。部署请求不能隐式补环境，local 不进入 registry。
+- 新应用 provision 事务只创建 preproduction；首次 promotion 在唯一约束下惰性创建 production。普通部署请求不能隐式补环境，local 不进入 registry。
 
 ### 5.3 Minimal native Head
 

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

@@ -1,6 +1,6 @@
 # OpenXiangda 2.0 按需正式环境
 
-状态：2026-08-16 已确认，作为 2.0 新应用的目标生命周期。尚未实现。
+状态：2026-08-16 已实现平台与工具链候选，等待正式发包和 prod-1 在线验收。
 
 ## 问题证据
 
@@ -18,8 +18,8 @@
 
 1. `app provision` 幂等创建应用身份、应用最高管理员授权和预发环境，不创建正式环境。
 2. 日常 `deploy` 只向预发部署新的不可变 AppVersion。
-3. 首次 `release production` 选择一个已在预发成功运行的 AppVersion，创建正式环境并把同一个 AppVersion 发布到正式环境。发布过程不重新构建制品。
-4. 后续 `release production` 复用已有正式环境，只更新其环境 Head。
+3. 首次 `promote <preproduction-deployment-id> production` 选择一个已在预发成功运行的 AppVersion，创建正式环境并把同一个 AppVersion 发布到正式环境。发布过程不重新构建制品。
+4. 后续 `promote` 复用已有正式环境，只更新其环境 Head。
 5. 预发和正式工作负载均支持显式启动、停止。停止只把期望运行副本降为零，不删除环境、业务数据、审计、Secret 元数据或历史 DeploymentRun。
 6. 从未正式发布的应用永远没有正式环境、正式 RoleSession、正式 OAuth/Secret 运行态或正式后端 Pod。
 
@@ -39,7 +39,7 @@
 | `app provision` | 创建应用身份和预发环境 |
 | `deploy preproduction` | 构建或提交 AppPackage，并把候选 AppVersion 部署到预发 |
 | `environment start/stop preproduction` | 启停预发工作负载，环境事实保持不变 |
-| `release production` | 首次惰性创建正式环境，或复用已有正式环境，发布预发验证过的同一 AppVersion |
+| `promote <deployment-id> production` | 首次惰性创建正式环境，或复用已有正式环境，发布预发验证过的同一 AppVersion |
 | `environment start/stop production` | 显式启停正式工作负载，不删除正式环境 |
 
 管理端应用列表至少显示“仅预发、预发运行中、预发已停止、正式发布中、已发布、正式发布失败”，并提供与状态匹配的确定性操作。普通用户页面不展示环境 UUID、AppVersion ID、workflow code 或内部错误码；这些信息只进入应用管理员诊断面板。
@@ -77,3 +77,11 @@
 4. 首次发布因资源不足或 readiness 失败时，预发 Head 不变化，正式环境没有活动 Head，也没有残留运行 Pod。
 5. 停止预发后副本数为零，再次启动恢复相同环境和活动版本。
 6. 1.x 发布、流程和自动化回归测试结果不受影响。
+
+## 当前实现
+
+- Platform Server migration 为 Native 环境增加 `runtime_state`，并把 `start`、`stop` 纳入同一 DeploymentRun 状态机和并发唯一约束。
+- provision 默认只创建 `preproduction`；首次 promotion 由平台事务性确保唯一 `production` 环境。
+- K3s 执行器只缩放当前 Head 指向的 Deployment。状态只在目标副本就绪或归零且 Head 未变化后提交；停止后的 App API 返回稳定的 503 错误码。
+- CLI 提供 `environment status/start/stop`；MCP 提供只读环境资源以及 `environment_status`、`start_environment`、`stop_environment` 三个工具。
+- AppPackage 自动要求 `environment.on-demand-production` 与 `environment.runtime-lifecycle`，旧平台会在上传制品前被能力协商拒绝。

package/docs/delivery.md

@@ -38,6 +38,8 @@ stateDiagram-v2
 
 失败默认不切换当前版本。重试复用同一 AppVersion 和幂等键。promotion 复用同一 AppVersion；rollback 是激活历史版本的新 DeploymentRun，不在服务器上现场改文件。
 
+新应用 provision 只创建预发环境。生产环境在首次 promotion 时由平台惰性创建；CLI 和 AI 不预先生成生产 UUID，也不自行补写环境记录。`environment start/stop` 同样创建平台持久化的 DeploymentRun，停止只把当前 Head 的 K3s 工作负载缩容为零并保留环境、数据、配置、密钥元数据与历史。客户端先用 `environment status` 读取权威 revision，并把 revision 纳入默认幂等键；并发操作由平台唯一约束和 Head/环境 CAS 仲裁。
+
 ## 版本管理
 
 Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立版本和内部依赖传播。官方模板固定经过同一候选矩阵验证的精确 BOM。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。

package/docs/getting-started.md

@@ -128,15 +128,18 @@ openxiangda workflow provider list --environment preproduction
 openxiangda build --backend-image registry.example.com/apps/my-app@sha256:...
 openxiangda deploy preproduction --backend-image registry.example.com/apps/my-app@sha256:...
 openxiangda status <deployment-id>
+openxiangda environment status
 ```
 
 CLI 上传应用包并创建 DeploymentRun；部署、重试、健康检查和激活都由平台执行。CLI 退出不影响发布继续进行。生产只晋级预发已验证的同一不可变 AppVersion，不重新构建。
 
-`app provision` 只用于首次创建平台中的稳定 2.0 应用身份，并在同一事务中补齐稳定的 `preproduction`、`production` 原生环境；命令可安全重试，且需要平台管理员身份。日常 CI 使用该应用的发布权限即可，不需要平台管理员。
+`app provision` 只用于首次创建平台中的稳定 2.0 应用身份和默认 `preproduction` 环境；命令可安全重试，且需要平台管理员身份。首次执行 `openxiangda promote <preproduction-deployment-id> production` 时，平台才惰性创建唯一的 `production` 环境并发布相同 AppVersion。
+
+测试应用不使用时可执行 `openxiangda environment stop preproduction` 把当前工作负载缩容为零；环境、业务数据、Secret 元数据、Head 和发布历史都会保留。需要继续测试时执行 `openxiangda environment start preproduction`。正式环境使用相同命令，但不会由平台自动停止。
 
 ## AI 入口
 
-AI 先读取 `openxiangda://workspace/context`，再使用 MCP 的 `check_app`、`run_tests`、`build_app` 等结构化工具。会改变环境的工具必须在用户明确授权后调用。
+AI 先读取 `openxiangda://workspace/context` 和 `openxiangda://environments`，再使用 MCP 的 `check_app`、`run_tests`、`build_app` 等结构化工具。`start_environment`、`stop_environment` 等会改变环境的工具必须在用户明确授权后调用。
 CI 或非交互环境不写用户会话文件，必须成对提供短期凭据：
 
 ```bash

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 应用业务角色 |
@@ -58,6 +58,9 @@
 | `build` | write-local | 构建并密封一个 AppPackage |
 | `deploy` | deploy | 创建平台持久执行的 DeploymentRun |
 | `promote` | deploy | 以同一 AppVersion 晋级目标环境 |
+| `environment status` | read | 查询应用环境、运行状态和活动版本 |
+| `environment start` | deploy | 从活动版本启动应用环境 |
+| `environment stop` | deploy | 停止应用环境并保留数据与配置 |
 | `status` | read | 查询 DeploymentRun 状态 |
 | `logs` | read | 查询部署检查点和关联日志 |
 | `retry` | deploy | 重试可恢复的 DeploymentRun |

package/docs/reference/mcp.md

@@ -8,6 +8,7 @@
 - `openxiangda://workspace/contracts`
 - `openxiangda://platform/capabilities`
 - `openxiangda://deployments/latest`
+- `openxiangda://environments`
 - `openxiangda://docs/index`
 
 ## Tools
@@ -20,6 +21,9 @@
 - `fire_local_timer`
 - `build_app`
 - `deployment_plan`
+- `environment_status`
+- `start_environment`
+- `stop_environment`
 - `deploy_app`
 - `deployment_status`
 - `deployment_logs`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.31",
+  "version": "2.0.0-alpha.32",
   "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.24"
+    "openxiangda-devkit-core": "2.0.0-alpha.25"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -11,6 +11,7 @@ Deliver the whole application as one immutable version. The client submits inten
 
 1. Run `openxiangda doctor` and confirm client/platform contract compatibility.
 2. For a first deployment only, confirm an authorized platform administrator has run `openxiangda app provision`.
+   Provisioning creates only `preproduction`; do not assume `production` exists.
 3. Run `openxiangda generate --check`, `openxiangda check`, and `openxiangda test`.
 4. Build and push the backend image; use an immutable digest reference.
 5. Run `openxiangda build --backend-image <immutable-image>` and retain the returned package digest.
@@ -28,6 +29,9 @@ Deliver the whole application as one immutable version. The client submits inten
 - Use `openxiangda retry` only for retryable failed runs.
 - Use `openxiangda cancel <deploymentId>` to stop an obsolete or blocked run before submitting a replacement package.
 - Use `openxiangda promote` to move the exact same application version between environments.
+- Use `openxiangda environment status` as the authoritative environment inventory.
+- Use `openxiangda environment stop <environment>` to scale an idle environment to zero without deleting data, configuration, the active Head, or history. Use `start` to restore that same Head.
+- Production is created only by the first explicitly authorized promotion. Never create or infer it from workspace configuration.
 - Use `openxiangda rollback` to create a new run that activates a known historical version.
 
 Do not rebuild during promotion or rollback. Do not expose injected secrets in logs, manifests returned to clients, or package metadata.