rainskills 0.1.0 → 0.1.2

package/rainbond-app-assistant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rainbond-app-assistant
-description: "Use for any request to deploy, run, deliver, publish, or troubleshoot the current project — regardless of whether the user mentions \"Rainbond\" by name. Triggers on generic intents such as: 帮我把项目跑起来 / 部署这个项目 / 发布上线 / 看看为什么跑不起来 / 帮我交付 / 排查一下 / deploy this project / run this app / check what is blocking it. Prefer this skill when a Rainbond MCP connection is configured in the session. Handles the full lifecycle: project-init, bootstrap, troubleshooting, delivery verification, dev-to-test promotion, and code-layer handoff."
+description: "Use whenever a user asks to deploy, run, deliver, publish, inspect, repair, or troubleshoot the current project, regardless of whether a runtime or MCP connection is configured and whether Rainbond is named. Trigger phrases include: 帮我把当前项目部署到 Rainbond 上 / 帮我把这个项目跑起来 / 帮我看看当前项目卡在哪 / 如果还没初始化就先初始化，然后自动继续到应该停止的位置 / 帮我处理一下这个应用 / deploy this project / run this app / publish this app / troubleshoot this project."
 ---
 
   # Rainbond App Assistant
@@ -55,65 +55,134 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
   - 规则说明、流程说明、人类可读结论：优先中文
   - `### Structured Output` 里的对象名、字段名、enum：保持英文 canonical 形式
 
-  ## Preflight Gate（最高优先级，先于硬规则执行）
+  <!-- rainskills-user-result:start -->
+  ## 用户可见结果协议（最高优先级）
 
-  在读取其它 skill 文件、扫描用户项目、或调用任何业务 MCP 工具之前，必须先验证当前会话能力。
+  普通用户请求部署、排障或交付验证时，内部可以维护结构化结果，但最终用户回复必须简短、中文、只呈现用户能直接使用的信息。若本节与后文 Output Format、示例或评测格式冲突，以本节为准。
 
-  Step 0 — Probe MCP availability：
-  - 调用一个轻量探针，例如 `rainbond_query_enterprises`
-  - 成功：记录 enterprise / team / region 上下文，进入"硬规则"和主线流程
-  - 失败（auth / transport / timeout / not configured）：立即停止，不进入业务流程
+  部署成功时按下面的内容输出；所有名称和地址必须来自本轮真实返回值。某项无法确认时省略该项，不得猜测或推测：
 
-  Preflight 失败时禁止做的事：
-  - 读取其它 reference / SKILL 文件
-  - 扫描用户项目目录、读取 `rainbond.app.json` 或 `.rainbond/local.json`
-  - 在本地生成 `Dockerfile`、`docker-compose.yml`、`manifest`、部署脚本或临时部署文档
-  - 手工编写或猜测 `~/.rainbond/mcp.env`、JWT、API token
-  - 调用任何业务 MCP 工具
+  ```text
+  部署成功。
 
-  Preflight 失败时必须给用户的动作建议，需要先区分场景：
+  - 项目：<用户项目名称>
+  - 运行环境：<本次实际使用的运行环境名称>
+  - 工作空间：<本次实际部署到的 Rainbond 工作空间名称>
+  - 应用：<创建或使用的 Rainbond 应用名称>
+  - 运行环境地址：<Rainbond Console 或应用管理页面地址>
+  - 应用访问地址：<部署完成后真实可访问的应用地址>
+  - 已完成操作：<用一句话概括本轮实际完成的项目识别、应用创建、组件构建、启动和访问验证；只列真实执行过的操作>
+  ```
 
-  - 如果用户机器上已存在 `~/.rainbond/mcp.env` 或 `~/.rainbond/skills/install.sh`，
-    判定为「已装过，多半是 JWT 过期 / 401 / 403」，给出 refresh 指引：
+  部署失败或未完成时只输出：
 
-    ```bash
-    bash <(curl -fsSL https://get.rainbond.com/rainskills/install.sh) refresh
-    # 或：bash ~/.rainbond/skills/install.sh refresh
-    ```
+  ```text
+  部署失败。
 
-    成功后按安装器输出执行客户端恢复动作：Codex / Claude Code 重启，Pi Agent 执行
-    `/reload`；OpenClaw 当前 CLI 使用安装器触发 MCP 热加载，独立 Gateway / Agent 进程需重新加载配置或重启。恢复完成后再让用户重新触发同一指令，
-    本轮不要自动重试同一个 MCP 工具调用。
+  失败原因：<用用户能理解的一句话说明直接原因>
 
-  - 否则视为首次安装，给完整安装命令：
+  解决办法：<确实存在安全、可执行的解决方案时才输出；没有就省略整项>
+  ```
 
-    ```bash
-    bash <(curl -fsSL https://get.rainbond.com/rainskills/install.sh)
-    ```
+  只有“解决办法”确实存在并且可执行时才输出该项。默认用户回复不得出现 `Problem Judgment`、`Actions Taken`、`Verification Result`、`Follow-up Advice`、`Structured Output` 等诊断标题；不得展示内部状态码、枚举、对象字段、YAML、JSON、工具调用记录或英文状态表。只有用户明确要求结构化结果，或者自动化/评测明确要求结构化契约时，才允许输出后文的结构化格式。
+  <!-- rainskills-user-result:end -->
+
+  <!-- rainskills-runtime-gate:start -->
+  ## 运行环境门禁（最高优先级）
+
+  ### 多运行环境操作契约
+
+  Node.js 前置检查通过后，每次用户业务请求都创建独立操作，不把项目绑定到任何环境、团队或应用。先执行本地 launcher + `["environment", "list", "--json"]`：用户明确说“运行环境/平台”时按环境名选择；明确说“团队”时表示默认环境中的团队；裸名称同时匹配环境和团队时必须让用户确认。未指定环境时使用全局默认环境；默认环境不可用时停止，禁止自动切换到其他环境。
+
+  生成新的 UUID，并执行本地 launcher + `["operation", "begin", "--operation-id", "<uuid>", "--intent-json", "<intent-json>"]`；用户明确指定已有环境时在 `--intent-json` 前加入 `["--environment-id", "<immutable-environment-id>"]`。保存返回的 `operation_id`，此后每个 Rainbond MCP 工具调用都必须在参数中加入 `rainskills_operation_id`。环境改名或修改全局默认值不能改变已开始操作的目标。同一项目可以在多个环境和团队分别部署，禁止写入或推断项目级默认环境。
+
+  第一步检查 Node.js 是否存在且主版本不低于 18。Node.js 缺失或低于 18 时，只说明“Rainskills 执行组件需要 Node.js 18 或更高版本”并停止：不选择运行环境，不调用 MCP，不猜测替代命令。只有用户或 agent 明确同意后才安装或升级 Node.js，再从同一原始 intent 继续。
+
+  固定 launcher 是 `["npx", "--yes", "rainskills@0.1.2"]`；版本必须与本技能包 `package.json` 一致。把 launcher 与参数拼成 argv 数组直接执行，禁止使用 `rainskills@latest`，禁止拼接或执行 shell 字符串。
+
+  本地 launcher 必须从当前 Skill 所在目录的同级目录定位 `rainbond-platform-installer/scripts/local-runtime.js`，解析为绝对路径后使用 `["node", "<绝对路径>"]` 执行。`environment list`、`operation begin`、`operation complete` 和 `runtime message` 只能使用本地 launcher；本地 launcher 只读取已安装文件和本机受保护状态，不得访问 npm 或其它网络。只有用户选定连接或安装运行环境后，才使用上面的固定 npx launcher。
+
+  <!-- rainskills-runtime-contract:start -->
+  ```json
+  {
+    "schema": "rainskills.skill-runtime-contract.v1",
+    "launcher": ["npx", "--yes", "rainskills@0.1.2"],
+    "local_launcher": ["node", "<installed-skills-root>/rainbond-platform-installer/scripts/local-runtime.js"],
+    "local_argv": {
+      "environment-list": ["node", "<installed-skills-root>/rainbond-platform-installer/scripts/local-runtime.js", "environment", "list", "--json"],
+      "operation-begin": ["node", "<installed-skills-root>/rainbond-platform-installer/scripts/local-runtime.js", "operation", "begin", "--operation-id", "<uuid>", "--intent-json", "<intent-json>"],
+      "operation-complete": ["node", "<installed-skills-root>/rainbond-platform-installer/scripts/local-runtime.js", "operation", "complete", "--operation-id", "<uuid>"],
+      "runtime-message": ["node", "<installed-skills-root>/rainbond-platform-installer/scripts/local-runtime.js", "runtime", "message", "--id", "<message-id>"]
+    },
+    "intents": {
+      "deploy": {"required": [], "optional": ["project_root", "source_kind", "source_url", "service_id"], "enums": {"source_kind": ["local", "git", "image", "package"]}},
+      "create": {"required": [], "optional": ["project_root", "source_kind", "source_url", "service_id"], "enums": {"source_kind": ["local", "git", "image", "package"]}},
+      "query": {"required": ["operation"], "optional": ["team_id", "app_id", "service_id"], "enums": {"operation": ["summary", "components", "events", "logs", "access"]}},
+      "troubleshoot": {"required": ["operation"], "optional": ["team_id", "app_id", "service_id"], "enums": {"operation": ["auto", "build", "runtime", "access"]}},
+      "modify": {"required": ["team_id", "app_id", "operation"], "optional": ["service_id"], "enums": {"operation": ["component-config", "build-source", "ports", "env", "storage", "dependency"]}}
+    },
+    "routes": {
+      "new": ["saas", "private-existing", "install-private"],
+      "existing": ["saas", "private-existing"]
+    },
+    "connect_argv": {
+      "saas": ["npx", "--yes", "rainskills@0.1.2", "runtime", "connect", "<target>", "--saas", "--intent-json", "<intent-json>"],
+      "private-existing": ["npx", "--yes", "rainskills@0.1.2", "runtime", "connect", "<target>", "--rainbond-url", "<rainbond-url>", "--intent-json", "<intent-json>"],
+      "install-private": ["npx", "--yes", "rainskills@0.1.2", "runtime", "connect", "<target>", "--install-private", "--location", "<private-location>", "--intent-json", "<intent-json>"]
+    }
+  }
+  ```
+  <!-- rainskills-runtime-contract:end -->
 
-    安装脚本会配置 MCP server、保存 JWT，并验证当前客户端的 RainSkills 专用 MCP 地址可用。
-    配置完成后重新触发同一指令即可。
+  `deploy`/`create` 含 `service_id` 时属于 existing，否则属于 new；`query`、`troubleshoot`、`modify` 始终属于 existing。意图不明确时先澄清，不执行 connect。target 只允许 `codex`、`claude`、`all`。连接前校验 intent，只执行其 scope 在契约中允许的完整 argv。只消费 schema 为 `rainskills.next-action.v1` 且完成字段校验后的 `argv` 数组。
 
-  例外：用户在同一会话里已经成功用过任意 `rainbond_*` 工具，则视为 preflight 已通过，不必每轮重探。
+  连接或平台安装完成后，用固定 `onboarding-id` 执行 launcher + `["intent", "resume", "--onboarding-id", "<同一 onboarding-id>"]`，恢复原始 intent 和 `resume_step`，不得重新猜测动作。
 
-  ## Installation Intent（高优先级）
+  业务 MCP 返回 401 时，先执行 launcher + `["runtime", "record-failure", "--onboarding-id", "<同一 onboarding-id>", "--step", "<当前固定步骤>", "--reason", "credential-expired"]`，再仅一次执行 launcher + `["runtime", "reconnect", "--onboarding-id", "<同一 onboarding-id>"]`，然后 resume 并只重试该步骤；第二次 401 立即停止。403 时执行 launcher + `["runtime", "record-failure", "--onboarding-id", "<同一 onboarding-id>", "--step", "<当前固定步骤>", "--reason", "permission-denied"]` 后停止，不得 reconnect、重新授权或自动重试，只说明缺少的权限。
+  <!-- rainskills-runtime-gate:end -->
 
-  当用户的请求本身是"帮我把 rainskills / Rainbond MCP 装上"或等价表达（含 `github.com/goodrain/rainskills` URL）时，**禁止**走以下旁路：
+  <!-- rainskills-runtime-routing:start -->
+  ## 缺少运行环境时
 
-  - 手工 `git clone` 后只复制部分 `rainbond-*` Skill
-  - 手工编写 `~/.rainbond/mcp.env`、JWT、登录回调
-  - 手工修改任一客户端配置来注册 MCP server
+  先确认 intent 属于 new scope 还是 existing scope；确认前不展示环境选项。
 
-  必须给用户一行可直接复制的命令，由仓库内 `install.sh` 接管交互式登录、JWT 获取、MCP 注册和验证：
+  ### 意图不明确
 
-  ```bash
-  bash <(curl -fsSL https://raw.githubusercontent.com/goodrain/rainskills/main/install.sh)
-  ```
+  用户请求没有明确指向新应用或已有应用时，只问：“这是要部署新应用还是管理已有应用？”确认前不连接运行环境，也不展示任何环境选项。
+
+  ### 新应用
+
+  用户明确要部署新应用后，先执行本地 launcher + `["runtime", "message", "--id", "new-application-environment"]`。收到 `[RAINSKILLS_USER_MESSAGE_BEGIN:<id>]` 与对应 END marker 后，只原样输出两者之间的正文，不输出 marker，不得总结、改写、调整项目符号或追加其它说明。下方文案仅用于核对，不得由 agent 自行生成：
+
+  > 可以，我会帮你完成应用识别、构建、部署和访问验证。
+  >
+  > 不过目前还没有可用的应用运行环境。
+  >
+  > 你刚安装的 Rainskills 是负责“部署”的 AI 助手，它会分析项目并执行部署流程；Rainbond 负责为应用提供稳定运行环境。
+  >
+  此时只保存用户已经明确提供的 intent 字段。`deploy`/`create` 可以只保存 `type`；不得为了构造 runtime intent 提前补参数，平台安装完成前不得询问应用来源，包括本地项目路径、Git 仓库 URL、镜像地址或安装包路径。运行环境连接并通过验收后，恢复到 `project-analysis`，再识别当前项目或询问缺失的应用来源。
 
-  如果用户当前会话所在仓库就是 `rainbond-skills` 本身，可建议 `./install.sh`。
-  如果用户明确要求非默认仓库位置，告诉他用环境变量 `RAINBOND_SKILLS_HOME=<path>` 前置。
+  #### 选择运行环境
 
-  说明给用户：脚本会安装全部独立 Skill、引导浏览器登录、写 `~/.rainbond/mcp.env`、为 Codex / Claude Code / OpenClaw / Pi Agent 配置对应 MCP，并验证专用地址。不需要 AI 手工配置其中任何一步。
+  请提示“请选择应用要运行的环境：”，并只显示：
+
+  1) 云端环境（免费体验）
+  2) 私有环境（去对接）
+
+  用户选择私有环境后，立即执行本地 launcher + `["runtime", "message", "--id", "private-deployment-location"]`，并按同一消息协议原样输出块内正文：
+
+  请选择部署位置：
+
+  1、部署到本机
+  2、部署到独立服务器
+  3、部署到已有 Rainbond
+
+  选择 1 时执行 `install-private` route，并在完整 argv 中使用 `["--location", "local"]`；选择 2 时执行 `install-private` route，并使用 `["--location", "server"]`；选择 3 时执行本地 launcher + `["runtime", "message", "--id", "private-console-origin"]`，收到地址后执行 `private-existing`。不得显示额外的接入方式中间步骤，不得在平台安装器中重复询问部署位置，也不得在环境准备完成前询问应用来源。
+
+  ### 已有应用
+
+  用户明确要查询、排障、修改或验证已有应用时，使用与动作匹配的第一句话，只提供 `Rainbond Cloud` 或承载目标应用的`已有私有 Rainbond`。选择已有私有 Rainbond 时执行本地 launcher + `["runtime", "message", "--id", "private-console-origin"]` 并原样输出。已有应用不得安装新平台，也不得进入 install-private。
+  <!-- rainskills-runtime-routing:end -->
 
   ## 硬规则
 
@@ -127,6 +196,7 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
      - 多个 team 且无 manifest 提示 → 停下来询问用户，**禁止**静默选 `default` / 第一个 / 任意已有 team。
      - app 选择同上逻辑：manifest 指定且可解析 → 直接用；无提示且多候选 → 询问。
      - 任何自动选择的结果都必须在最终报告里以"已选 X（理由：来自 manifest / 单一可选）"形式告知，邀请用户覆盖。
+     - 每个 Rainbond MCP 工具边界都要把十进制字符串 `app_id` 规范化为正整数；非数字 ID 必须拒绝。
   3. 单入口主线一旦触发：
      `project-init -> bootstrap -> troubleshooter -> delivery-verifier -> version-assistant -> testing-app delivery-verifier`
      应按 gate 自动继续，不要在中途停成“下一步建议”。
@@ -175,6 +245,7 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
 16. 如果用户要求调整源码构建参数，优先走 `rainbond_manage_component_envs(operation=replace_build_envs, build_env_dict=...)`。
     不要把语言构建参数塞进 `build_info`。
 17. 如果源码检测同时命中 Dockerfile 和语言构建，按 `rainbond-fullstack-bootstrap` 的 Build Mode Selection 优先级链解决：manifest `source.build.strategy` 优先 → 启发式按 Dockerfile 分类 + 意图信号判断（"语言 buildpack 能否产生等价运行时行为"，原则驱动而非固定清单）→ 真正模糊时才问一次并建议用户写回 manifest。决策必须双轨可审计：prose 输出"Build mode for `<name>`: `<picked>` (`<source>` — `<reason>`; to override: `<hint>`)"逐组件展示，且 bootstrap 的结构化输出 `deployment_plan.workflow.build_strategy_decisions[<name>]` 同步记录（仅给有 dual detection 的组件填）。`dockerfile` 决策映射到 `rainbond_create_component_from_source` 的 `prefer_dockerfile_when_detected = true`。详见 `rainbond-fullstack-bootstrap/references/source-build-parameter-guide.md § Build Mode Selection`。
+    - **恢复例外按状态决定**：`checking` / `checked` / 未完成组件可以通过 `rainbond_get_component_check_result(prefer_dockerfile_when_detected=true)` 在原拓扑中取得 Dockerfile 证据，禁止删除。只有 `create_status=complete` 的 CNB 组件不存在通用原地切换能力时，才允许在已保存 topology and configuration snapshot、已向用户展示该完成状态并获得 explicit user confirmation 后删除并重建；任一证据缺失时只读停止。
 18. 当前 MCP 不支持显式 `dockerfile_path` 时，不要在顶层编排里承诺该能力。
 19. 对 reverse-proxy full-stack 项目，不要只因为根路径 URL 存在就把它当作最终交付成功或 Fast Path 的可信 URL；同 host 的 backend 路径（通常是 `/api`）必须也一致可用，或明确停在 blocker。
 20. **组件依赖与连接变量管理**（合并自原 20-23 四条）：多组件拓扑里，provider/consumer 关系必须用显式依赖 + provider 侧连接变量管理，不要让 consumer 端硬编码或重复声明。
@@ -195,13 +266,16 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
 24. 不要自动拉起本地 Docker Desktop/OrbStack、执行本地 Docker build/push、或推送临时镜像作为兜底；这属于 delivery-mode 策略切换，必须先得到用户明确确认。
 25. 每次运行内部仍必须形成 `AppAssistantResult` 结果对象，但默认用户答复不一定暴露 YAML。
     当 `source_app_delivery` 的 runtime healthy、没有 blocker、控制台部署位置和公网访问地址都已确定，且 delivery 已 `delivered` 或只剩浏览器人工确认时，默认使用简洁中文交付报告，不追加 `### Structured Output`。
-26. 只有在自动化/评测/调试明确要求结构化结果、用户明确要求 YAML/JSON、结果仍在构建或异常、存在 blocker/handoff/身份歧义、或进入 dev-to-test promotion 时，才把 `AppAssistantResult` 渲染为最终 fenced `yaml`。仅因当前 agent 无法打开公网地址而需要用户确认，不是暴露 YAML 的理由。
+26. 只有在自动化/评测明确要求结构化契约，或用户明确要求 YAML、JSON、调试详情、内部状态对象时，才把 `AppAssistantResult` 渲染为最终 fenced `yaml`。部署失败、仍在构建、存在 blocker/handoff/身份歧义或进入 dev-to-test promotion 都不是默认暴露 YAML 的理由。
 27. 如果本次使用了 Git、镜像仓库或其他传输代理，必须在默认交付报告的处理记录或注意事项中说明；在结构化模式下也必须写入 `actions_performed[].details`。
     代理事实属于执行记录，不是强制暴露 YAML 的理由。
 28. `rbd-*` 组件（rbd-gateway、rbd-api、rbd-worker、rbd-chaos、rbd-db、rbd-mq、rbd-monitor、rbd-node 等）是 Rainbond 平台自身的基础设施组件，不是用户应用组件。
     - 可以用 `rainbond_query_region_rbd_components` 查询并展示它们的状态
     - 不能通过 MCP 对它们执行重启、部署、修改等写操作；当前 MCP 工具集不支持此类操作
-    - 如果用户要求操作这些组件，明确告知：需要通过 Kubernetes 命令（如 `kubectl rollout restart deployment/<name> -n rbd-system`）或 Rainbond 集群管理控制台进行，超出本技能的操作范围，不要假装可以执行
+     - 如果用户要求操作这些组件，明确告知：需要通过 Kubernetes 命令（如 `kubectl rollout restart deployment/<name> -n rbd-system`）或 Rainbond 集群管理控制台进行，超出本技能的操作范围，不要假装可以执行
+28a. 写操作失败或结果异常时，先调用 `rainbond_get_operation_failure_context`，按其 `classified_reason` 决定停下、只读核实或低风险修复；`unknown` 回退既有证据链，禁止盲目重放写操作。
+    `event_log_tail` 只作为敏感诊断证据使用，绝不能复制、引用或向用户展示其原文；输出只能使用 `classified_reason`、非敏感摘要和已脱敏字段。
+28b. 运行态或交付健康检查先调用 `rainbond_get_app_health_overview`；仅 `abnormal` 或 `unknown` 组件再读取 component summary、日志、事件或存储明细。
 29. **仅给 bare Git URL 时默认 root + 空 `subdirectories`**：当用户给的只是一个 Git URL（无本地 manifest、无明确子目录提示），默认 `subdirectories=""`（仓库根）进入 source 检测，让后端判断这个仓库结构。**不要**先问用户"根目录还是子目录"。
     - 单项目仓库（一个 buildable root）→ 后端检测通过，正常 build
     - 多组件 / 多 example 仓库 → 后端返回 `multiple services detected` 或等价歧义信号 → 按 Iron Law 10 停下问用户选哪个子目录
@@ -900,13 +974,9 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
   Use this mode when any of the following is true:
   - the user asks for structured output, YAML, JSON, debug details, or machine-readable output
   - an eval, wrapper, or automation flow explicitly needs deterministic structured schema validation
-  - any concise delivery report condition above is not met
-  - the app is building, unhealthy, blocked, identity-ambiguous, or requires handoff
-  - `promotion_result` is non-null or the user requested dev-to-test promotion
-  - there is any unresolved blocker or handoff
   - another skill or wrapper will consume the result as input
 
-  Building, unhealthy, blocked, ambiguous, handoff, and incomplete promotion states should keep the detailed human-readable sections and evidence below. Do not make non-success output terse merely because successful output is concise.
+  普通对话中的 building、unhealthy、blocked、ambiguous、handoff 和 incomplete promotion 结果仍使用“用户可见结果协议”，不得因为内部状态复杂就暴露结构化报告。
 
   In structured contract mode:
   - the human-readable sections below are the narrative view over `AppAssistantResult`
@@ -1260,6 +1330,10 @@ description: "Use for any request to deploy, run, deliver, publish, or troublesh
   - the opening fence must be exactly ````yaml` immediately after the heading
   - the closing fence must be the last non-whitespace line of the whole reply
 
+  ## On-demand references
+
+  根据当前阶段按需加载 [workflow rules](references/workflow-rules.md)、[operational reference](references/operational-reference.md)、[output contract](references/output-contract.md) 或 [product object model](references/product-object-model.md)。
+
   ## Common Mistakes
 
   - running bootstrap when the topology already exists

package/rainbond-app-assistant/evals/01-linked-topology-missing.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: orders-app
-      app_id: app-201
+      app_id: 201
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-201/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/201/overview
   environment:
     name: preview
     source: local_preference
@@ -46,7 +46,7 @@ AppAssistantResult:
   actions_performed:
     - skill: inspection-only
       status: completed
-      details: Resolved the linked source app identity and current project intent from local binding plus current MCP truth.
+      details: Resolved the linked source app identity and current project intent from local binding plus current platform truth.
     - skill: rainbond-fullstack-bootstrap
       status: pending
       details: Selected as the next safe step because the linked source app still has no established topology.

package/rainbond-app-assistant/evals/02-linked-topology-building.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: inventory-app
-      app_id: app-202
+      app_id: 202
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-202/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/202/overview
   environment:
     name: preview
     source: local_preference
@@ -46,7 +46,7 @@ AppAssistantResult:
   actions_performed:
     - skill: inspection-only
       status: completed
-      details: Resolved the linked source app state from current MCP truth without changing the source-backed path.
+      details: Resolved the linked source app state from current platform truth without changing the source-backed path.
     - skill: rainbond-fullstack-troubleshooter
       status: pending
       details: Selected because topology exists but source-backed components are still converging.

package/rainbond-app-assistant/evals/03-runtime-healthy-delivery-unknown.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: billing-app
-      app_id: app-203
+      app_id: 203
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-203/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/203/overview
   environment:
     name: preview
     source: explicit
@@ -46,7 +46,7 @@ AppAssistantResult:
   actions_performed:
     - skill: inspection-only
       status: completed
-      details: Confirmed runtime convergence for the linked source app from current MCP truth.
+      details: Confirmed runtime convergence for the linked source app from current platform truth.
     - skill: rainbond-delivery-verifier
       status: pending
       details: Selected because runtime is healthy but delivery acceptance is still unknown.

package/rainbond-app-assistant/evals/04-delivered-stop-without-promotion.expected.yaml

@@ -7,7 +7,7 @@ assert:
     - preview
     - 部署位置
     - 访问地址
-    - https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-204/overview
+    - https://run.rainbond.com/#/team/demo-team/region/cn/apps/204/overview
     - https://demo-team-cn.rainbond.me/payments-app
     - 200 OK
   prose_not_contains:

package/rainbond-app-assistant/evals/04-delivered-stop-without-promotion.response.md

@@ -5,7 +5,7 @@
 应用：`payments-app`
 环境：`preview`
 
-- 部署位置：[打开 Rainbond 应用](https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-204/overview)
+- 部署位置：[打开 Rainbond 应用](https://run.rainbond.com/#/team/demo-team/region/cn/apps/204/overview)
 - 访问地址：[打开应用](https://demo-team-cn.rainbond.me/payments-app)
 
 ### 运行状态

package/rainbond-app-assistant/evals/05-delivered-explicit-dev-to-test.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: orders-app
-      app_id: app-205
+      app_id: 205
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-205/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/205/overview
   environment:
     name: preview
     source: explicit
@@ -57,7 +57,7 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: orders-app-test
-      app_id: app-test-205
+      app_id: 205
     testing_delivery_state:
       status: delivered
       preferred_access_url: https://demo-team-cn.rainbond.me/orders-app-test

package/rainbond-app-assistant/evals/06-manual-validation-stop.expected.yaml

@@ -3,7 +3,7 @@ assert:
   equal:
     AppAssistantResult.request_intent: dev_to_test_promotion
     AppAssistantResult.orchestration_state: linked-and-needs-manual-url-validation
-    AppAssistantResult.project.deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-206/overview
+    AppAssistantResult.project.deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/206/overview
     AppAssistantResult.delivery_state.status: delivered-but-needs-manual-validation
     AppAssistantResult.delivery_state.verification_mode: inferred
     AppAssistantResult.delivery_state.verifier_next_action: manual_url_validation

package/rainbond-app-assistant/evals/06-manual-validation-stop.response.md

@@ -1,5 +1,5 @@
 ### Project State
-The project is `linked-and-needs-manual-url-validation` for the `preview` environment with team `demo-team`, region `cn`, app `manual-check-app`, and app_id `app-206`.
+The project is `linked-and-needs-manual-url-validation` for the `preview` environment with team `demo-team`, region `cn`, app `manual-check-app`, and app_id `206`.
 
 ### Actions Performed
 This run resolved the linked source app state and completed `rainbond-delivery-verifier`. The user asked for the dev-to-test mainline, but the source app only reached manual URL validation, so promotion was not entered.
@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: manual-check-app
-      app_id: app-206
+      app_id: 206
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-206/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/206/overview
   environment:
     name: preview
     source: explicit

package/rainbond-app-assistant/evals/07-cluster-capacity-blocked.response.md

@@ -2,7 +2,7 @@
 The project is `linked-and-cluster-capacity-blocked` for the `preview` environment with team `demo-team`, region `cn`, app `ops-dashboard`, and app_id `app-207`.
 
 ### Actions Performed
-This run resolved the linked source app state and current MCP/runtime evidence. `rainbond-fullstack-troubleshooter` was not entered because the dominant blocker is active cluster capacity shortage.
+This run resolved the linked source app state and current platform evidence. `rainbond-fullstack-troubleshooter` was not entered because the dominant blocker is active cluster capacity shortage.
 
 ### Current Health
 db status running, api/service status running, frontend-access status capacity-blocked, overall status capacity_blocked.
@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: ops-dashboard
-      app_id: app-207
+      app_id: 207
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-207/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/207/overview
   environment:
     name: preview
     source: local_preference
@@ -46,7 +46,7 @@ AppAssistantResult:
   actions_performed:
     - skill: inspection-only
       status: completed
-      details: Confirmed the linked source app identity and active capacity blocker from current MCP truth.
+      details: Confirmed the linked source app identity and active capacity blocker from current platform truth.
     - skill: rainbond-fullstack-troubleshooter
       status: skipped
       details: Deferred because active cluster capacity shortage must be fixed before bounded runtime repair can continue.

package/rainbond-app-assistant/evals/08-code-build-handoff-stop.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: frontend-console
-      app_id: app-208
+      app_id: 208
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-208/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/208/overview
   environment:
     name: preview
     source: local_preference

package/rainbond-app-assistant/evals/09-source-backed-failure-no-fallback.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: catalog-app
-      app_id: app-209
+      app_id: 209
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-209/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/209/overview
   environment:
     name: preview
     source: local_preference

package/rainbond-app-assistant/evals/10-identity-ambiguous-stop.response.md

@@ -1,5 +1,5 @@
 ### Project State
-The project is `linked-and-identity-ambiguous` for the `preview` environment. Current local binding and current MCP evidence still leave multiple safe team/app targets, so no single app identity can be emitted yet.
+The project is `linked-and-identity-ambiguous` for the `preview` environment. Current local binding and current platform evidence still leave multiple safe team/app targets, so no single app identity can be emitted yet.
 
 ### Actions Performed
 This run only performed context resolution. No lower-level bootstrap, troubleshooter, delivery-verifier, or version flow was executed because the team/app identity is still ambiguous.
@@ -8,7 +8,7 @@ This run only performed context resolution. No lower-level bootstrap, troublesho
 No canonical runtime_state or delivery_state can be emitted yet because the team/app identity is still ambiguous.
 
 ### Blocking Issue
-Multiple safe team/app targets remain after reading local binding and current MCP evidence.
+Multiple safe team/app targets remain after reading local binding and current platform evidence.
 
 ### Next Step
 stop and ask the user to choose the team/app identity
@@ -41,6 +41,6 @@ AppAssistantResult:
   actions_performed:
     - skill: inspection-only
       status: completed
-      details: Local binding and current MCP evidence still leave multiple safe team/app targets.
+      details: Local binding and current platform evidence still leave multiple safe team/app targets.
   next_action: stop and ask the user to choose the team/app identity
 ```

package/rainbond-app-assistant/evals/12-complex-suite-needs-descriptor-stop.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: registry-app
-      app_id: app-301
+      app_id: 301
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-301/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/301/overview
   environment:
     name: preview
     source: default

package/rainbond-app-assistant/evals/13-explicit-git-url-locks-source.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: catalog-app
-      app_id: app-302
+      app_id: 302
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-302/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/302/overview
   environment:
     name: preview
     source: local_preference

package/rainbond-app-assistant/evals/14-strategy-switch-cleans-residue.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: catalog-app
-      app_id: app-303
+      app_id: 303
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-303/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/303/overview
   environment:
     name: preview
     source: local_preference

package/rainbond-app-assistant/evals/15-turn-discipline-reuse-alias.response.md

@@ -21,10 +21,10 @@ AppAssistantResult:
       team_name: demo-team
       region_name: cn
       app_name: catalog-app
-      app_id: app-304
+      app_id: 304
     linked: true
     selected_environment: preview
-    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/app-304/overview
+    deployment_location_url: https://run.rainbond.com/#/team/demo-team/region/cn/apps/304/overview
   environment:
     name: preview
     source: local_preference

package/rainbond-app-assistant/references/operational-reference.md

@@ -0,0 +1,77 @@
+# App Assistant operational reference
+
+Load this reference only when checking a proposed route or reviewing a completed run.
+
+  ## Common Mistakes
+
+  - running bootstrap when the topology already exists
+  - running bootstrap for a template-install intent
+  - running troubleshooter before confirming the project is linked
+  - assuming env sync is mandatory for every run
+  - treating env files as runtime truth
+  - exposing a large YAML block for an eligible successful source delivery, including browser-confirmation-only delivery, when the user did not ask for structured/debug output
+  - reporting team/region/app identity as a substitute for the clickable Rainbond deployment location
+  - using the public service URL as the Rainbond deployment location, or constructing the public service URL from naming conventions
+  - stripping useful diagnostic evidence from building, blocked, unhealthy, ambiguous, handoff, or incomplete promotion states
+  - omitting the required `### Structured Output` section in structured contract mode
+  - replacing the required five human-readable sections with freeform narrative in structured contract mode
+  - treating a project as unlinked only because `.rainbond/local.json.metadata.status` is stale even though the platform confirms the same app in the current run
+  - omitting `Actions Performed` detail when the run only did inspection/classification and intentionally skipped downstream skills
+  - echoing raw platform labels such as `closed` instead of normalizing component status to the canonical vocabulary
+  - stopping after bootstrap even when bootstrap explicitly recommends troubleshooting
+  - skipping template version resolution before installation
+  - treating source build convergence as a finished healthy topology
+  - continuing application repair when scheduling is blocked by cluster capacity
+  - stopping at “running” without verifying delivery state or reporting access URL
+  - declaring the app healthy when only db/api are healthy but frontend access is still broken
+  - continuing platform-level repairs when the issue is clearly in code or reverse proxy configuration
+  - auto-entering version flow when delivery is only `delivered-but-needs-manual-validation`
+  - replacing the source-app meaning of `project` with the created testing app instead of recording testing identity under `promotion_result`
+  - recursively treating the created testing app as a brand-new source app in the same run
+  - silently degrading a source-backed component into an image-backed component after a source creation error
+  - silently rewriting the source branch or ref after a source creation error
+  - inventing `delivery_state.partially-delivered` before `rainbond-delivery-verifier` has actually run
+  - routing a control-plane or platform backend failure into `code_build_handoff`
+  - copying a frontend-only component state into `api_status`
+  - stopping the top-level app-assistant run at successful init even though the user asked for deploy or dev-to-test continuation
+  - silently selecting one team when multiple accessible teams existed and the user had not chosen one
+  - searching outside the current project directory for `rainbond.app.json` or `.rainbond/local.json`
+  - continuing into local code edits, local tests, commit, push, or automatic retry after reaching `code_build_handoff_needed`
+  - automatically switching from source-backed bootstrap to local package because source detection found multiple services
+  - starting local Docker/OrbStack, building locally, or pushing temporary images after a source/package/image path fails without explicit user confirmation
+  - spending 20-30 minutes repeatedly trying the same path instead of stopping at the attempt budget
+  - routing a clear source build failure straight to runtime logs without checking component events and build logs first
+  - using `build_info` as the default container for source build parameters
+  - promising `dockerfile_path` or defaulting to Dockerfile mode without explicit user intent
+
+  ## Quick Reference
+
+  Decision summary:
+  - no link -> link first
+  - no link -> `rainbond-project-init`
+  - template install intent -> `rainbond-template-installer`
+  - no topology -> bootstrap
+  - source build still converging -> troubleshooter
+  - explicit build failure question -> troubleshooter with `events -> build logs -> runtime logs`
+  - external artifact unreachable -> stop and request reachable mirror/egress or explicit strategy change
+  - cluster capacity blocked -> stop and fix platform capacity first
+  - topology exists but unhealthy -> troubleshoot
+  - runtime appears converged -> delivery verifier
+  - strict delivered plus explicit dev-to-test intent -> create snapshot and testing app
+  - delivered-but-needs-manual-validation -> stop for manual URL validation before promotion; use concise success output for source-only delivery when all concise-mode conditions are met
+  - runtime fixed but browser path broken -> code/build handoff
+  - healthy -> stop
+
+  Trust model:
+  - local files provide context
+  - the locked Rainbond transport provides runtime truth
+
+  Default orchestration:
+  1. resolve context
+  2. determine whether the run is source-only or dev-to-test mainline
+  3. classify state
+  4. choose lower-level skill
+  5. continue until the current strict gate says stop
+  6. if strict delivered and promotion was requested, snapshot and create testing app
+  7. verify the testing app once
+  8. report one next step