rainskills 0.1.21 → 0.1.22

package/rainbond-app-assistant/scripts/validate_progressive_loading.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+
+"""Validate progressive disclosure for the Rainbond App Assistant skill."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+DEFAULT_SKILL_DIR = Path(__file__).resolve().parents[1]
+APP_INITIAL_STAGE = (
+    "| 初始部署或首次 Rainbond 操作 | 本根入口、"
+    "[own runtime gate](references/runtime-gate.md)、"
+    "[routing](references/routing.md) | 其余全部 |"
+)
+APP_OPERATION_STAGE = (
+    "| operation/context 已建立，需要编排或执行 | "
+    "[workflow rules](references/workflow-rules.md)；仅在核对路线或复盘时读取 "
+    "[operational reference](references/operational-reference.md) | 输出与对象细节 |"
+)
+
+
+def require(condition: bool, message: str, failures: list[str]) -> None:
+    if not condition:
+        failures.append(message)
+
+
+def validate_progressive_loading(skill_dir: Path) -> list[str]:
+    failures: list[str] = []
+    root_path = skill_dir / "SKILL.md"
+    runtime_gate = skill_dir / "references" / "runtime-gate.md"
+    root = root_path.read_text(encoding="utf-8")
+    root_bytes = len(root.encode("utf-8"))
+    root_lines = len(root.splitlines())
+
+    require(root_bytes <= 7_000, f"root is too large: {root_bytes} bytes", failures)
+    require(root_lines <= 150, f"root is too long: {root_lines} lines", failures)
+    require(
+        "所有 reference 必须按需加载；不得一次性加载全部 references，也不得提前读取无关 reference。"
+        in root,
+        "root must explicitly require on-demand reference loading",
+        failures,
+    )
+    require(
+        "任何 Rainbond 查询、环境连接、平台安装或变更前，必须先读取 references/runtime-gate.md。"
+        in root,
+        "root must require its runtime gate before Rainbond access",
+        failures,
+    )
+    require(
+        "当前项目或用户明确给出的源码 Git URL：由本 Skill 接管。" in root,
+        "root must own current projects and explicit source Git URLs",
+        failures,
+    )
+
+    references = {
+        "references/runtime-gate.md": "runtime gate",
+        "references/routing.md": "routing",
+        "references/workflow-rules.md": "workflow rules",
+        "references/operational-reference.md": "operational reference",
+        "references/output-contract.md": "output contract",
+        "references/product-object-model.md": "product object model",
+    }
+    for relative_path, label in references.items():
+        require(relative_path in root, f"root must discover {label}", failures)
+        require((skill_dir / relative_path).is_file(), f"missing {relative_path}", failures)
+
+    require(APP_INITIAL_STAGE in root, "App initial stage mapping is invalid", failures)
+    require(APP_OPERATION_STAGE in root, "App operation/context stage mapping is invalid", failures)
+    if APP_INITIAL_STAGE in root and APP_OPERATION_STAGE in root:
+        require(
+            root.index(APP_INITIAL_STAGE) < root.index(APP_OPERATION_STAGE),
+            "App stage mapping must load the runtime gate before workflow rules",
+            failures,
+        )
+
+    for required in (
+        "首次",
+        "401",
+        "403",
+        "写调用不得自动重放",
+        "确认",
+        "停止",
+    ):
+        require(required in root, f"root is missing required invariant: {required}", failures)
+
+    for forbidden in (
+        "rainskills.skill-runtime-contract.v1",
+        "rainskills.single-runtime-contract.v1",
+        "<!-- rainskills-runtime-gate:start -->",
+        '"runtime_status":',
+        '"input_commands":',
+        "## High-Level Workflow",
+        "fixed launcher",
+        "固定 launcher",
+        "Device Flow",
+        "TTY",
+        "tty: true",
+        "npm root -g",
+        "~/.rainbond",
+        "只读取当前项目内的 manifest",
+        "本地 secrets",
+    ):
+        require(forbidden not in root, f"root embeds staged content: {forbidden}", failures)
+
+    require(runtime_gate.is_file(), "missing references/runtime-gate.md", failures)
+    if runtime_gate.is_file():
+        gate = runtime_gate.read_text(encoding="utf-8")
+        for required in (
+            "rainskills.skill-runtime-contract.v1",
+            "<!-- rainskills-runtime-gate:start -->",
+            "<!-- rainskills-runtime-gate:end -->",
+            "<!-- rainskills-runtime-routing:start -->",
+            "<!-- rainskills-runtime-routing:end -->",
+            "rainskills.single-runtime-contract.v1",
+            "rainskills-tools.js",
+            "固定 launcher",
+            "Device Flow",
+            "tty: true",
+            "npm root -g",
+            "401",
+            "403",
+            "new-application-environment",
+        ):
+            require(required in gate, f"runtime gate is missing: {required}", failures)
+
+    return failures
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--skill-dir", type=Path, default=DEFAULT_SKILL_DIR)
+    args = parser.parse_args()
+    failures = validate_progressive_loading(args.skill_dir.resolve())
+
+    if failures:
+        print("FAIL: progressive loading invalid")
+        for failure in failures:
+            print(f"  - {failure}")
+        return 1
+
+    print("PASS: progressive loading valid")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/rainbond-app-version-assistant/SKILL.md

@@ -17,7 +17,7 @@ description: "Use when a user explicitly asks for an existing Rainbond app versi
 ```json
 {
   "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
+  "package_version": "rainskills@0.1.22",
   "runtime_status": [
     "node",
     "<home>/.rainbond/lib/rainskills/bin/rainskills.js",

package/rainbond-delivery-verifier/SKILL.md

@@ -49,7 +49,7 @@ description: "Use only when the user explicitly asks for final delivery or acces
 ```json
 {
   "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
+  "package_version": "rainskills@0.1.22",
   "runtime_status": [
     "node",
     "<home>/.rainbond/lib/rainskills/bin/rainskills.js",

package/rainbond-env-sync/SKILL.md

@@ -17,7 +17,7 @@ description: "Use when a user explicitly asks to sync non-sensitive preview or p
 ```json
 {
   "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
+  "package_version": "rainskills@0.1.22",
   "runtime_status": [
     "node",
     "<home>/.rainbond/lib/rainskills/bin/rainskills.js",

package/rainbond-fullstack-bootstrap/SKILL.md

@@ -17,7 +17,7 @@ description: "Use only when the user explicitly asks to create the Rainbond app
 ```json
 {
   "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
+  "package_version": "rainskills@0.1.22",
   "runtime_status": [
     "node",
     "<home>/.rainbond/lib/rainskills/bin/rainskills.js",

package/rainbond-fullstack-troubleshooter/SKILL.md

@@ -49,7 +49,7 @@ description: "Use only when the user explicitly asks for a bounded build, runtim
 ```json
 {
   "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
+  "package_version": "rainskills@0.1.22",
   "runtime_status": [
     "node",
     "<home>/.rainbond/lib/rainskills/bin/rainskills.js",

package/rainbond-opensource-app-deploy/SKILL.md

@@ -1,325 +1,54 @@
 ---
 name: rainbond-opensource-app-deploy
-description: "Use when a user wants to deploy an open-source application that is absent from the Rainbond app market from an actual docker-compose file, Helm chart, or container image set, including requests such as 按 docker-compose 部署 XXX or deploy this compose stack on Rainbond. Do not use when the user only names an application such as Harbor without a descriptor; route that request to rainbond-app-assistant. Not for the user's own source or private-image project; use rainbond-app-assistant. Not for an app already available in the market; use rainbond-template-installer."
+description: "Use only when the user actually supplies a third-party Docker Compose file/content, Helm chart/values, or container image-set descriptor. Never use for a bare Git URL, source project/directory/package, named application without a descriptor, private-image project, or confirmed market template; route source and named-only requests to rainbond-app-assistant and market templates to rainbond-template-installer."
 ---
 
 # Rainbond Open-source App Deploy
 
-<!-- rainskills-runtime-gate:start -->
-## 单运行环境 CLI 门禁（最高优先级）
+只处理用户实际提供的第三方 Compose、Helm 或容器镜像集合描述符。核心顺序是：先验证描述符，再加载 Runtime Gate；不得为了确认资格而接触 Rainbond 或外部源码。
 
-本机只允许连接一个 Rainbond 运行环境。当前 Skill 在本会话第一次调用 Rainbond 前，执行固定 launcher 的 `runtime status --json`。返回 `connected` 且 `usable=true` 后，所有查询和变更直接通过本地 `~/.rainbond/bin/rainskills-tools.js` 执行。不得配置或直接调用客户端 MCP，不得执行环境枚举或业务 operation 生命周期命令，也不得生成或传递运行环境 ID、业务 operation ID 或 intent JSON。
+## Phase 0：静态资格判断
 
-没有运行环境时，让用户选择 Rainbond Cloud 或一个已有/新建的私有 Rainbond，并执行对应的 `runtime connect`。连接和重新授权必须进入浏览器 Device Flow，不复用 Shell 中缓存的 JWT；新凭据通过 live probe 后才覆盖唯一运行环境。CLI 返回 401 时，只读调用可在 `runtime reconnect` 成功后重试一次；写调用不得自动重放，必须先查询平台真实状态。403 直接停止，不重新授权。
+只使用用户当前消息中明确提供的输入判断：
 
-`context resolve` 是无状态调用：单一工作空间直接返回上下文，多个候选返回组合选项；用户选择后由当前任务直接携带 team/region 参数，不执行 `context select`，不写本地 operation。所有可变 `call` 仍需先取得 confirmation ID，再以完全相同的输入追加 `--confirm` 执行一次。
+- 实际 Docker Compose 文件/内容、Helm chart/values、容器镜像集合描述符 → 留在本 Skill。
+- 裸 Git URL、源码目录、源码项目、源码包、私有镜像项目，或只给应用名称而没有描述符 → 转到 rainbond-app-assistant。
+- 已确认的 Rainbond 本地/云端市场模板 → 转到 rainbond-template-installer。
 
-```json
-{
-  "schema": "rainskills.single-runtime-contract.v1",
-  "package_version": "rainskills@0.1.21",
-  "runtime_status": [
-    "node",
-    "<home>/.rainbond/lib/rainskills/bin/rainskills.js",
-    "runtime",
-    "status",
-    "--json"
-  ],
-  "runtime_connect": {
-    "saas": [
-      "node",
-      "<home>/.rainbond/lib/rainskills/bin/rainskills.js",
-      "runtime",
-      "connect",
-      "<target>",
-      "--saas"
-    ],
-    "private_existing": [
-      "node",
-      "<home>/.rainbond/lib/rainskills/bin/rainskills.js",
-      "runtime",
-      "connect",
-      "<target>",
-      "--rainbond-url",
-      "<console-origin>"
-    ],
-    "install_private": [
-      "node",
-      "<home>/.rainbond/lib/rainskills/bin/rainskills.js",
-      "runtime",
-      "connect",
-      "<target>",
-      "--install-private",
-      "--location",
-      "<local-or-server>"
-    ],
-    "reconnect": [
-      "node",
-      "<home>/.rainbond/lib/rainskills/bin/rainskills.js",
-      "runtime",
-      "reconnect",
-      "<target>"
-    ]
-  },
-  "input_commands": {
-    "context_resolve": {
-      "argv": [
-        "node",
-        "<home>/.rainbond/bin/rainskills-tools.js",
-        "context",
-        "resolve",
-        "--input",
-        "-",
-        "--skill-id",
-        "rainbond-opensource-app-deploy"
-      ],
-      "stdin": {
-        "required": [
-          "enterprise",
-          "workspace"
-        ]
-      }
-    },
-    "read": {
-      "argv": [
-        "node",
-        "<home>/.rainbond/bin/rainskills-tools.js",
-        "read",
-        "<tool>",
-        "--input",
-        "-",
-        "--skill-id",
-        "rainbond-opensource-app-deploy"
-      ],
-      "stdin_schema_source": "tool-catalog"
-    },
-    "call": {
-      "argv": [
-        "node",
-        "<home>/.rainbond/bin/rainskills-tools.js",
-        "call",
-        "<tool>",
-        "--input",
-        "-",
-        "--skill-id",
-        "rainbond-opensource-app-deploy"
-      ],
-      "stdin_schema_source": "tool-catalog"
-    },
-    "call_confirm": {
-      "argv": [
-        "node",
-        "<home>/.rainbond/bin/rainskills-tools.js",
-        "call",
-        "<tool>",
-        "--input",
-        "-",
-        "--skill-id",
-        "rainbond-opensource-app-deploy",
-        "--confirm",
-        "<confirmation-id>"
-      ],
-      "stdin_schema_source": "same-confirmed-input"
-    }
-  }
-}
-```
-<!-- rainskills-runtime-gate:end -->
+裸 Git URL 不是部署描述符。不得通过 clone、浏览 Git、搜索仓库或读取源码来寻找 Compose/Helm，从而把 App Assistant 的请求改判给本 Skill。描述符是否存在不清楚时，只询问用户是否能提供实际描述符。
 
-受限沙箱（包括 Codex）执行本地状态命令时，必须申请用户级受保护目录访问权限；在 Codex 中使用 `require_escalated`。不得修改 `~/.rainbond` 权限、复制受保护状态到工作区，或因沙箱权限错误建议重装。
+未确认描述符时不得读取 references/runtime-gate.md；也不得加载任何 reference、查询/连接环境、安装平台、调用 Rainbond、克隆或浏览 Git、读取外部文档或做任何变更。
 
-涉及浏览器或设备授权的 `runtime connect`，以及恢复/安装场景中的 `rainskills <target> --self-hosted`，必须在附加交互终端（TTY）中运行；在 Codex 中设置 `tty: true` 并保持进程附着直到授权完成。禁止通过非交互命令要求用户粘贴 JWT；非交互模式只可复用已存在的受保护凭据。
+## 渐进加载
 
-执行优化：同一会话内只检查一次 Node.js（首次使用本地 CLI 前）；仅在 Node.js 或 Rainskills 安装、升级，或 PATH 变更后失效。固定 launcher 和 argv 已在本 Skill 中，禁止读取、搜索或探测 `rainskills.js`，也禁止执行 `npm root -g`。每个新的业务操作仍需要刷新一次环境列表；带已有 `operation_id` 或 `onboarding-id` 的续接复用已绑定的环境 ID，不重复枚举环境。
+不得一次性加载全部 references，只加载当前阶段所需文件：
 
-<!-- rainskills-runtime-routing:start -->
-## 缺少运行环境时
+| 阶段 | 读取 |
+|---|---|
+| Phase 0：描述符未确认 | 不加载 reference；只做上述静态资格判断 |
+| 描述符已确认，首次需要连接或调用 Rainbond | 只读取自己的 [runtime gate](references/runtime-gate.md) |
+| operation/context 已建立，需要建模、部署、排障或交付 | 读取 [deployment workflow](references/deployment-workflow.md) |
+| 新鲜证据命中已知部署故障模式 | 再读取 [failure-mode playbook](references/failure-mode-playbook.md) |
 
-先说：“可以，我会帮你部署未收录到应用市场的开源应用。不过目前还没有可用的应用运行环境。你刚安装的 Rainskills 是 AI 部署助手，它负责分析项目并执行部署；应用实际会运行在 Rainbond 上。Rainbond 是一套应用运行和管理平台，负责容器运行、域名访问、日志和存储等工作，你不需要了解 Kubernetes。”
+正确流程只加载本 Skill 的 Runtime Gate，不得读取 rainbond-app-assistant 或其他相邻 Skill 的 Gate。这里的 operation/context 是当前任务内业务操作与 team/region/app 上下文，不得生成 CLI 业务 operation ID、运行环境 ID 或 intent JSON。
 
-#### 选择运行环境
+## Runtime 与安全边界
 
-请提示“请选择应用要运行的环境：”，并只显示：
+静态确认描述符后，任何 Rainbond 查询、环境连接、平台安装或变更前必须先读取 references/runtime-gate.md；当前 profile 的 transport、鉴权、context、确认与运行时安全契约全部由该 Gate 提供。
 
-1) 云端环境（免费体验）
-2) 本机环境
-3) 独立服务器
-4) 已有 Rainbond
+- 不得绕过 Gate 选择的 transport、context 或授权边界，也不得读取相邻 Skill 的 Gate。
+- 可变调用必须先取得确认 ID，再用完全相同输入确认执行；写调用不得自动重放。
+- 401 只允许只读调用按 Gate 允许的恢复流程重试一次；403 立即停止且不做未授权重试。
+- 不回显 JWT、密钥或凭据，不猜测 component state、内部地址或外部 URL。
 
-选择 1 时执行 `saas` route；选择 2 时执行 `install-private` 并使用 `["--location", "local"]`；选择 3 时执行 `install-private` 并使用 `["--location", "server"]`；选择 4 时执行本地 launcher + `["runtime", "message", "--id", "private-console-origin"]` 后执行 `private-existing`。不得显示“私有环境”或部署位置中间层，不得在运行环境准备完成前继续读取或修改部署描述文件。
-<!-- rainskills-runtime-routing:end -->
+## 执行边界
 
-## 部署类 skill 怎么选
+确认资格并建立 operation/context 后，按 [deployment workflow](references/deployment-workflow.md) 从官方描述符推导完整拓扑、配置组件与依赖、等待终态、检查健康、有限修复并通过真实入口交付门禁。只有证据匹配已知故障时才读取 [failure-mode playbook](references/failure-mode-playbook.md)。
 
-- 应用市场里有的应用 → `rainbond-template-installer`（一键安装商店模板）
-- 市场里没有的开源软件（有 docker-compose、Helm 或镜像）→ `rainbond-opensource-app-deploy`
-- 部署你自己写的项目（源码或私有镜像）→ `rainbond-app-assistant`
+不得把镜像已导入或容器全绿当成交付完成；真实访问地址必须来自 Rainbond，且需要完成应用 UI/core smoke。UI 自动化不可用时停在 needs manual UI validation。
 
-Do not continue with this skill when either neighboring route applies. This skill owns the missing-from-market, upstream-descriptor-driven deployment path only.
+## 确认与停止
 
-## Overview
+低风险且证据充分的 Rainbond 侧动作可在既有授权范围内继续；破坏性、数据变更、范围较广或低置信度动作必须先确认。以下情况停止：缺少/无法确认描述符、确认市场模板、语义无法映射、缺少必需能力或 secret、镜像不可达、集群容量失败、源码/构建缺陷、预算耗尽、需要人工 UI 验证，或任何相邻 Skill 才拥有的请求。
 
-Turn an upstream application's official deployment material into a working Rainbond application. Derive the topology from evidence, create and connect every component, preserve state, then iterate until runtime health, the real external entry, and the application's UI or core flow all pass.
-
-**Core principle:** importing images is not completion. Completion means the topology is evidence-backed and the deployed application works through its real user-facing entry.
-
-Use the protected local Rainskills CLI as the only transport for Rainbond runtime truth. Never call Rainbond MCP directly, start a local Rainskills MCP service, or invent component state, internal addresses, credentials, or external URLs.
-
-## Progress checklist
-
-Track this checklist throughout the run:
-
-```text
-Open-source deployment:
-- [ ] 0. Official topology derived
-- [ ] 1. Components, dependencies, ports, env, and storage modeled
-- [ ] 2. Required upstream documentation obtained
-- [ ] 3. Deployment reached terminal build states
-- [ ] 4. All component health checked
-- [ ] 5. Every blocker converged or stopped within budget
-- [ ] 6. Real entry and UI/core smoke verified
-```
-
-## 0. Derive the official topology
-
-Before any Rainbond write, obtain the upstream project's official `docker-compose.yml`, Compose fragments, Helm chart values/templates, image documentation, and installation guide. Prefer a pinned release or image tag over an unbounded moving tag.
-
-Build one deployment inventory from those sources:
-
-- every required service and its image, tag, command, and role
-- container ports and which single service is the intended user entry
-- required environment variables, secrets that must come from the user, and defaults
-- every provider/consumer relationship from `depends_on` and from host references embedded in env, URLs, DSNs, callbacks, and proxy configuration
-- named volumes, bind mounts, data directories, and volumes shared by multiple services
-- health checks, initialization jobs, profiles, anchors, `env_file` inputs, and config files
-- reverse-proxy routes and same-origin browser requirements
-
-Do not reconstruct a complex suite from model memory when the official descriptor is unavailable. Ask for the descriptor or permission to use a clearly named official alternative before writing runtime state.
-
-If the application is actually available in the Rainbond market, stop and route to `rainbond-template-installer`.
-
-For Helm input, pin the chart version and merge the user's values before deriving the inventory. Render with the upstream-supported `helm template` path when available. Map the rendered intent as follows:
-
-- Deployment or StatefulSet workloads → long-running Rainbond components backed by their declared images
-- Service ports → Rainbond inner/outer ports; Ingress routes → the single external entry and proxy routing
-- persistent volume claims → evidence-backed persistent storage requirements
-- ConfigMaps and non-secret files → `config-file` mounts; Secrets → user-supplied secret inputs that are never printed
-- startup/readiness/liveness probes → `rainbond_manage_component_probe`
-- init containers, Jobs, hooks, privileged host integration, operators, and custom resources → explicit compatibility decisions, not silent omission
-
-If a chart relies on Kubernetes behavior that cannot be represented safely by current Rainbond component capabilities, stop with a semantic-compatibility blocker. Do not claim that reading a chart is equivalent to installing it unchanged.
-
-## 1. Import components and model the deployment
-
-Create or reuse the target Rainbond application, then model the inventory in dependency order.
-
-1. Create every image-backed component with `rainbond_create_component_from_image` and keep initial deployment disabled until its ports, env, dependencies, storage, and config files are ready.
-2. Configure inner ports first. Enable an outer port only on the intended external entry. Add the port with `rainbond_manage_component_ports`, then call `rainbond_manage_component_ports(operation=update_alias)` for that port to set `port_alias` and `k8s_service_name`; do not assume the add call persisted both values.
-3. Create every accepted provider/consumer edge with `rainbond_manage_component_dependency`, including both declared `depends_on` edges and edges implied by URLs, DSNs, callbacks, or proxy upstreams.
-4. Configure provider-side connection variables with `rainbond_manage_component_connection_envs`, then let explicit dependencies inject them. Keep consumer-local env only for names or combined URLs the application itself requires. Ask for missing secrets without displaying or persisting them in reports.
-5. Attach persistent storage to every stateful data directory before deployment. For image-created stateless components, use `rainbond_manage_component_storage` with an explicit `volume_name`, `volume_type=share-file`, and the official `volume_path`. When multiple components must see the same files, mount the same shared writable volume on each required component. Never invent a storage class, host path, or retention guarantee. If the upstream requires local, block, or single-writer stateful semantics that the available component cannot preserve, stop and report the mismatch instead of silently weakening it.
-6. Mount required proxy or application config as `config-file` storage before deploying the component that consumes it.
-7. Preserve health probes through `rainbond_manage_component_probe`. Run one-shot initialization only through an evidence-backed supported path; do not create a long-running component that is expected to exit successfully and then misclassify its restart loop as health.
-
-If any required MCP capability above is unavailable, stop with a capability blocker and name the missing operation. Do not silently emulate it with an unsafe delivery-mode or storage-semantic change.
-
-### Component addressing
-
-Prefer **port alias injection**:
-
-- set the provider port alias to the env prefix expected by the consumer
-- create the explicit dependency edge
-- consume the platform-injected `<PREFIX>_HOST` and `<PREFIX>_PORT`
-- do not copy a Compose service name or hard-code a container-local hostname into Rainbond env
-
-When a hostname must be embedded inside a URL, DSN, callback, or connection string, set a semantic internal domain with `k8s_service_name` and render that verified domain into the value. Use DNS-safe hyphenated names. If deploying another copy in the same namespace, choose unique internal domains and rewrite every matching reference consistently.
-
-Before any env write on a component with dependency-injected or port-alias env, run `rainbond_analyze_env_conflicts`. Do not create a local env that collides with an injected `_HOST` or `_PORT` value.
-
-### Deployment best practices
-
-1. **Explicit dependency edges.** Runtime DNS reachability is not a substitute for a Rainbond dependency. Verify the final accepted edge set is complete.
-2. **Single reverse-proxy entry.** When browser UI and APIs require same-origin path routing, retain the official proxy, mount its routing config, wire every proxy-to-upstream edge, and expose only the proxy externally. Never deploy a stock proxy without its routing config.
-3. **Persistent storage for state.** Databases, uploaded files, generated keys, and other durable state must survive restart. Verify storage is mounted at the official data path and is writable by the running process.
-
-## 2. Acquire documentation on two tracks
-
-Classify each blocker before searching:
-
-- **Configuration-class:** missing required env, wrong provider address, dependency not wired, storage path absent, config file overriding env. Use logs, Rainbond evidence, the deployment inventory, and [references/failure-mode-playbook.md](references/failure-mode-playbook.md) first.
-- **Protocol/framework-class:** the process is healthy but login, encryption, callbacks, cookies, setup, or a framework-specific operation behaves incorrectly. Search the official upstream source, README, issue tracker, or operations guide before changing runtime state.
-
-When clean logs conflict with broken user behavior, treat that as protocol/framework-class. Do not guess a destructive storage or database repair from a browser symptom.
-
-## 3. Deploy and wait for terminal build states
-
-Deploy only after the step 1 readiness gates pass. Use `rainbond_operate_app` for the deployment and `rainbond_wait_for_build_completion` for each returned build event.
-
-- Keep waiting with the same anchored event while the tool reports `running`.
-- Treat the terminal result and its classified reason as evidence.
-- Do not replace the bounded wait with repeated unanchored status polling.
-- A slow image pull is not a failure by elapsed time alone; distinguish active pulling from a terminal image-pull error.
-
-## 4. Check application health
-
-Use `rainbond_get_app_health_overview` as the default whole-application signal. Inspect each abnormal component's blocker, then obtain the minimum supporting pod, event, log, env, dependency, port, and storage evidence needed to explain it.
-
-Continue to step 6 only when every required component is green. If any required component is building, waiting, abnormal, or capacity-blocked, continue to step 5.
-
-## 5. Diagnose, repair, and converge
-
-Read [references/failure-mode-playbook.md](references/failure-mode-playbook.md) when the evidence matches one of its deployment patterns.
-
-Use `rainbond-fullstack-troubleshooter` as the repair engine for existing-component build or runtime blockers. Follow its `RuntimeState` classification, evidence order, config-override gate, connection contract, event anchoring, destructive-action boundary, and attempt budget.
-
-For each blocker:
-
-1. Collect fresh anchored evidence.
-2. Classify the blocker and choose the smallest evidence-backed repair.
-3. Before env changes, run the env-conflict check and inspect mounted config files that may override env.
-4. Announce and apply one known low-risk Rainbond-side repair. Ask before destructive, data-mutating, broad, or low-confidence actions.
-5. Redeploy only the affected scope, wait for its terminal event, then return to step 4.
-
-Budget rules:
-
-- Allow at most one repair attempt for the same blocker signature, then re-verify.
-- If the same signature remains, stop and report the evidence and required human decision.
-- Stop after three distinct repair attempts in one run, or after two consecutive health passes with no material improvement.
-- Stop immediately for a confirmed unreachable upstream image, cluster capacity failure, or source-code/build defect that Rainbond configuration cannot repair.
-- Repeated identical read-only checks without new anchored evidence do not count as progress.
-
-## 6. Pass the delivery gate
-
-Completion requires all of the following:
-
-1. `rainbond_get_app_health_overview` shows every required component green.
-2. Read the real external entry from Rainbond `access_infos`; never fabricate or infer a URL.
-3. If official documentation requires a public base URL, callback URL, trusted proxy, or secure-cookie setting, use that real entry to complete the two-phase public-URL configuration, redeploy once, and read `access_infos` again.
-4. Verify that real entry is reachable through the intended proxy or application component.
-5. Perform an application-specific **UI smoke** or core-flow smoke through the real entry, not only a root-path status check. Examples include loading the setup/login UI, signing in with user-provided test credentials, creating a minimal object, or completing the application's primary read/write flow.
-6. Recheck stateful storage and the explicit dependency set after the smoke test.
-7. When durable application state is part of the acceptance target, perform one controlled restart and verify the smoke-created object or equivalent state is still readable.
-
-If UI automation is unavailable, stop at `needs manual UI validation`; provide the real entry and exact manual steps, but do not call the deployment complete.
-
-Report concisely:
-
-- topology created and external entry component
-- component health and any intentionally omitted optional services
-- explicit dependencies and persistent/shared storage verified
-- real access URL from `access_infos`
-- UI/core smoke performed and result
-- unresolved blocker, if any, plus the exhausted attempt budget
-
-## Common mistakes
-
-- Treating image import or all-green containers as final delivery.
-- Copying Compose service names directly into consumer env.
-- Wiring only `depends_on` while missing env-reference or proxy edges.
-- Exposing web and API separately when the official UI assumes one origin.
-- Deploying a reverse proxy before mounting its routing config.
-- Deploying a database or generated-key directory without persistent storage.
-- Editing env while a mounted config file supplies the effective value.
-- Declaring a slow image pull failed before its event reaches a terminal state.
-- Testing a browser protocol with an incompatible plain HTTP request and misdiagnosing the result.
-- Reporting a guessed URL instead of Rainbond `access_infos`.
+最终只报告真实拓扑、组件健康、依赖/存储验证、来自 access_infos 的访问 URL、实际 smoke 结果，以及唯一未解决 blocker。

package/rainbond-opensource-app-deploy/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Rainbond Open-source App Deploy"
-  short_description: "Deploy open-source compose, Helm, or image apps"
+  short_description: "Only supplied Compose, Helm, or image-set descriptors"
   default_prompt: "Use $rainbond-opensource-app-deploy to deploy an open-source compose stack on Rainbond and verify its UI."