@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/portal-external-app/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: portal-external-app
+description: '接入「外部镜像服务类应用」——服务端代码不在本 repo、以 Docker 镜像交付的 App（知识库/多模态解析/异步任务网关这类）。凡任务涉及为外部服务写对接契约或 app.manifest.json、register-app/provisioning 注册布线、/svc 路由与健康检查、外部服务的服务账号与 scope、一盒(one-box)本地联调、或评审外部团队的交付物时，务必先用本 skill——即使用户只说"把 XX 服务接进来"。Use when integrating an externally-built docker-delivered service app into the portal: manifest, register-app, provisioning, /svc wiring, one-box debugging, or reviewing an external team''s delivery.'
+---
+
+# portal-external-app · 外部镜像服务类应用接入
+
+外部镜像 App = 服务端在别的 repo（任意语言/栈）、独立镜像交付、**常驻**（不走按需缩零）。鉴权与业务 API 遵循门户运行时契约；**`/health` 支持平铺 JSON 与 Envelope，检测规则与平台运行时一致**。本文件是判断与流程；具体契约按需读 `references/`（可整目录拷到 App repo 独立使用）。
+
+
+`/apps/<key>/` 与 `/svc/<key>/` 是线上 URL；本文的 `references/` 和 `scripts/` 相对于本 skill 目录。
+
+## 按任务读参考
+
+| 任务 | 读 |
+| --- | --- |
+| 实现/评审资源服务器（四道闸、health、env、认证面划界、配置面） | [references/integration-contract.md](references/integration-contract.md) |
+| 实现 `/health`、出仓迁移、发布镜像或健康检查失败（必读） | [references/health-contract.md](references/health-contract.md)：两种正确实现、实际判据、发布前检查命令 |
+| 写 manifest、注册布线、一盒联调、排查 | [references/registration-and-onebox.md](references/registration-and-onebox.md) |
+| 匿名页、后端直出 HTML、公开站点/独立域名、旧链接或 listingKey 迁移 | [references/public-entrypoints.md](references/public-entrypoints.md)：现有 /apps、/svc、Sites 三种通路及各自责任 |
+| 为外部服务写/审对接契约文档 | [references/contract-doc-template.md](references/contract-doc-template.md) |
+| 有「每租户最多几个 X」的配额诉求（选模型、数值谁配、已用怎么来） | [references/quota-and-seats.md](references/quota-and-seats.md) |
+
+## 先判形态（决定后面走哪条线）
+
+- 有用户前端？→ `type:"micro"`（前端 dist 同源托管 `/apps/<key>/`，前端开发见 portal-micro-app skill）；无前端 → **`type:"service"`**（无头：不露卡、不可打开，仅作被调用方，控制台可治理）。
+- 谁调它？→ 自己前端（用户态 TDT）/ 其他 App 后端（令牌交换，见 portal-app-exchange skill）/ 其他服务无用户直调（服务账号 `client_credentials`）。三种来路授权姿势不同（integration-contract.md §3 的表）。
+  - ⚠️ 第三种里，如果调你的是**租户自己的**程序（采集器、脚本、CI），租户管理员可以在门户
+    `/admin/service-accounts` **自助**开凭证，不用找平台管理员代建。**但它只能勾到你 manifest
+    `scopes` 里的 scope** —— 只写在 `serviceScopes` / `privilegedServiceScopes` 里的那条，
+    租户永远勾不到（症状：功能上线了、租户面却没有任何可选项）。判断口径与两条路的差别见
+    [integration-contract.md §3.1](references/integration-contract.md)。
+- 它自带认证体系（API-Key/节点 Token/gRPC）？→ 按 integration-contract.md §6 划界：门户面必走 TDT 四道闸；自有节点面保持原认证但**不得**进 `/svc`（`/svc` 只转发 HTTP :8080）。
+
+## 交付物评审 checklist（收外部团队东西时逐项验）
+
+1. 镜像：监听 8080、网络别名 `<listingKey>-server`、amd64+arm64、**不烘焙 .env**、`docker save` tar + sha256 或私有 registry；
+2. `app.manifest.json`（外部团队 repo 里的单一事实源）；
+3. env 契约表：**镜像实际读取的变量名**（镜像自有前缀与门户契约别名的映射必须写清；有的镜像不读裸 `PORT`）；
+4. **迁移入口**：迁移文件在镜像里、二进制上有一个迁移 argv（见下节）。「迁移脚本留在自己 repo 里」= 不合格；
+5. 运维口径：是否需每租户 bootstrap（需要则 `tenants.id` 必须 = 门户租户 UUID）；**`/health` 必须通过 [健康契约验收](references/health-contract.md)**，按平台同一判据验证正常与依赖故障；信封响应不能只检查 HTTP 200；
+6. **有没有重复造平台已有的能力**：自己存文件 / 自己发通知 / 自己记审计 / 自己排定时任务 / 自己算配额 —— 逐项对照下面两张表，命中就要求改走平台面；
+7. **租户自助凭证**：这个服务有没有「租户拿自己的程序直接调你」的场景（日志/指标摄取、批量导入、CI 回写）？有就检查那条 scope 在不在 manifest 的 **`scopes`** 里 —— 不在的话租户面开不出凭证，只能退回「找平台管理员代建」（见 [integration-contract.md §3.1](references/integration-contract.md)）；
+8. **配额诉求**：有没有「每租户能建多少」这类上限？有就走平台套餐（见 [references/quota-and-seats.md](references/quota-and-seats.md)），**不接受对方自建**；
+   角色本身该由对方在自己的 `app.manifest.json` 里声明 `seatRoles`；`serviceScopes` 里出现 `seats.read` 仍是当场打回的信号，但对方可以在 `privilegedServiceScopes` 里**申请**它（带 reason，进「发布审核」逐条确认批准后授予）；
+9. 对接契约文档：按 [references/contract-doc-template.md](references/contract-doc-template.md) 的结构与精度。**没有这份文档的接入不算完成**——新服务（如任务网关）要先补。
+
+## 资源服务器硬契约（外部实现最常炸的四处）
+
+**Bun / TypeScript 后端不自己实现第 1 条**：直接用 `@xgent/portal-server-sdk` 的 `createPortalAuthenticator`，
+信封解包、主体与凭证类型校验、缓存与故障映射都在里面；其他语言才按下面的契约自己实现。
+`@xgent/*` 从平台私有包仓安装，配法见 `xgent-app-release` skill「第 0 步」；仓里还没有
+`.xgent-registry.env` ⇒ 停下，请开发者先去门户「开发者应用」生成配置文件。**不许 vendor**：
+不把 SDK 的产物或源码拷进仓，不用 `file:` / `link:` / tar 依赖顶替。收外部团队交付时，看到
+`vendor/` 下有 `@xgent/*` 就打回。
+
+1. **自省信封解包**：门户响应必须先检查 `ok === true` 且 `data` 为对象，再校验 `data`；失败信封或缺 data 返回 503，不能回退到顶层。只有合法 `active:false` 才表示凭证失效。TDT 的 exp 必填；无过期长期 key 才可省略 exp。主体/凭证类型矩阵、ACL 范围与缓存预算见 integration-contract.md §3；
+2. **`/health` 按响应形状判定**：HTTP 非 2xx 不通过；2xx 响应顶层有 `ok` 时，必须 `ok === true && data.db === true`；没有顶层 `ok` 时按 2xx 判健康。平铺 `{"service":"my-app","db":"ok"}` 与信封 `{"ok":true,"data":{"db":true}}` 都支持，不按内建/外部 App 区分。平铺依赖故障须用 HTTP 503 表达；不要给字符串状态直接套 `ok(...)`。完整示例与同源检查脚本见 [health-contract.md](references/health-contract.md)。
+3. **门户三变量 all-or-nothing**：自省地址 + SA clientId + secret 全缺→鉴权停用 503；缺一→启动 fail-fast 打印缺失项。
+4. **平台级跨租户闸**：如有跨租户路由，只认服务端自省返回的 `claims.isPlatformAdmin === true`。它由 Portal 按用户实时计算、不在 JWT 里；`role` / `bypass` 只属于当前租户，服务态恒为 `false`，不接受前端自报或 Cookie 转发。
+
+完整契约（四道闸、三种令牌来路、审计、划界）见 [references/integration-contract.md](references/integration-contract.md)。
+
+## 一盒初始化与升级
+
+首次联调用 `portal-dev-setup` 的 `onebox.sh init` → `up`；已有一盒换版本用
+`upgrade [--image <ref>]` → `up`；沿用 latest 先 `pull` 更新缓存，已加载的本地新镜像可离线升级。
+不使用 `init --force` 代替升级。升级保留配置、generated/、backup/、
+端口与卷；`up` 仍重种门户库，不重种 App 自己的库。自带对象存储为 RustFS，保留 `MINIO_*`
+配置与 `minio:9000` 网络别名；控制台路径为 `/rustfs/console/`。存量对象由切换脚本复制、核对后才切换，
+切换后有新写入时不能直接回旧卷，细节见 [registration-and-onebox.md](references/registration-and-onebox.md)。
+
+## 注册布线（细节见 registration-and-onebox.md）
+
+- **dev / 一盒**：`bun run register-app <manifest>`（幂等，生产拒跑）= upsert listing + 直写服务账号 + 写发起方 App Secret + 写 `/svc` 白名单 map。⚠️ `exchangeInitiatorSecret` 的哈希在**首个租户**安装时还没有任何实例可布——先安装 App，**再重跑一次** register-app，否则发起交换 401（之后装的租户会随安装自动补布，见 registration-and-onebox.md §2.2）。日志里 `wired into N …` 的 N 是「**改了**几个实例」，0 也可能是「本来就对」——判据是比哈希，见 registration-and-onebox.md §2.2。
+- ⚠️ **发布 ≠ 租户能看见**：租户市场对 `tenant_listing_grants` 是 fail-closed。**dev 的 `register-app` 会自动授予当时已存在的租户**（非 service 型，输出里有 `租户可用应用:` 一行）；**生产不自动**（提案批准 / 控制台导入都不授予——语义是平台管理员显式勾选）。症状是「控制台显示已上架、租户市场里却根本看不到」——去 平台 › 租户管理 › 租户 › 「可用应用」勾上保存（registration-and-onebox.md §2.1）。
+- **生产（标准路径）**：清单事实源在**对方仓的 `app.manifest.json`**，经
+  **发布提案**到达：平台管理员在 控制台 › 应用市场 › 接入新应用 按 key 签发 `xrel_` 令牌
+  （无行先建 draft 占位），对方 `publish --manifest … --dist … --image …` ⇒ 首次必进
+  「发布审核」队列 ⇒ 批准后更新清单、服务账号与已装租户，后端和网关分别交付。
+  密钥一次性回显给审批人；平台运行配置由管理员维护，App 团队无需修改门户代码。
+  特权服务态 scope 经 manifest 的 `privilegedServiceScopes` 申请、逐项审批后授予；
+  用量指标经 manifest `usageMetrics` 声明（治理档）。批准不等于部署与网关已经生效，
+  交付判据见 [公开入口](references/public-entrypoints.md)。
+- **后续版本**：对方 CI 自助（`xgent-app-release` skill）——无治理变更自动通过，
+  治理变更进「发布审核」等平台批准。
+- **scope 三规则**：平台基础 scope ∪ 自己命名空间（含连字符→下划线变体）∪ 已声明 `exchangeTargets` 的目标命名空间；越界 `VALIDATION_FAILED`。
+- **secret 一致红线**：平台落库的服务账号 secret 与镜像 env 里的必须一致；漂移症状是自省 401 或「跨应用授权缺失」（实为 `SECRET_INVALID`），排查先 sha256 比对两侧。
+
+## 数据库迁移：平台在部署时替你跑
+
+划分决定一切细则：**schema 是平台级的**（随一次部署发生一次），**数据行是租户级的**（随安装发生）。
+所以 DDL 属于部署步骤 —— 不属于容器启动，也不属于逐租户安装。
+
+外部团队声明 `deployDescriptor.migrateArgs`（平台管理员填），控制器在**换容器之前**用
+**同镜像 + 同 env** 跑一次性容器（`--rm`；pm2 / compose / K8s 三个 flavor 都实现了）：
+
+```
+job(deploy|redeploy)
+ ├─ ① migrateArgs 非空 → <entrypoint> <migrateArgs>；失败 ⇒ 任务红 + 旧容器继续服务
+ ├─ ② ensureServiceUp     ← 到这一步才换容器
+ ├─ ③ waitHealthy(180s)   └─ ④ openRoute
+```
+
+**为什么不是「启动时自迁移」**：失败会变成崩溃循环（要 `docker logs` 才知道为什么），
+还要挤 180 秒健康窗口。放在换容器前，失败时旧版仍在服务，且是面板上一个有名字、
+带对方 stderr 的步骤。
+
+**为什么必须在镜像里**：迁移要在**库所在的地方**跑，而跨越边界的产物只有镜像；对方 CI
+连不到（也不该连到）门户的库。且镜像 = 那一版代码，它要求的 schema 与它同源同版本 ——
+分开走就会漂。**门户永远不执行由 App 投递进来的脚本**（宿主机侧的 `migrateScript` 只对
+仓内 built-in 开放，`descriptorToService()` 对 config App 钉死为 `null`）。
+
+要求外部团队做到四条：迁移打进镜像 + 一个迁移 argv（如 `--role migrate`）· `pg_advisory_lock`
+包住 · **失败非零退出**别自愈 · **expand-contract**（迁移跑在换容器前，那一刻旧版本还在服务）。
+
+⚠️ **`migrateArgs` 只有门户部署了对应版本才生效**。反过来的顺序（先填字段、门户没更新）
+会被 jsonb 原样存下、**无人读、不报错** —— 与被删掉的 `migrate`/`provision`/`bootstrap`
+三个死布尔同病。次序固定：门户先部署 → 对方出镜像 → 才填字段。
+
+⚠️ **每租户 bootstrap 目前没有出口**：`bootstrapScript` 对 descriptor App 恒为 `null`，
+门户不会替外部服务建租户行。若对方的表 FK 自己的 `tenants`，接入时必须显式定方案
+（对方开 provisioning 端点 / 首次使用自建 / 门户加钩子），否则症状可能是**静默写 0 行**
+（`INSERT … WHERE EXISTS (SELECT 1 FROM tenants …)` 这种写法不会报错）。
+
+## 改动启动必需 env 的键名，必须发版前知会门户
+
+`descriptor.env` / `envFile` 是**平台管理员治理字段**，manifest 永远带不进值（提交即拒），
+`requiredEnv` 只交键名。**键名集合的变化属治理档**：写进 manifest 的 `requiredEnv` 一变
+（新增/改名/删除），提案就转入「发布审核」，管理员批准前先看到新键名 —— 这是把
+「知会门户」变成流程内动作的那道门。**CR-3 之后它还是一道真闸**：批准前门户拿这张清单比对
+`descriptor.env ∪ envFile` 的键集合（只看键在不在，不读值），缺了就拒绝生效
+（`REQUIRED_ENV_MISSING`，提案留 pending）；审批屏逐键标状态，非密钥可当场填。改名要写成
+`{ key, renamedFrom }` 一条，门户会把旧键在 `descriptor.env` 里的值搬过去（**envFile 里的搬不了**，
+门户不写那个文件，那一条会判「缺」并提示运维改名）。仍有一件它管不到：对方
+**不写进 `requiredEnv`** 的静默改名依旧无门可拦 —— 症状是服务
+换版后 `refusing to start`，而发布方那侧只看到成功。2026-08-19 知识库把 `XGENT_OPENAI_*`
+整族改成 `XGENT_EMBED_*` 就是这么崩了几小时的；只改其中一个 key 更坏 —— 服务起得来，
+但 base URL/model/**dims** 静默回落默认值。所以收交付物时仍要求：改必需 env 必须**同步改
+manifest 的 `requiredEnv`**（改名走 `renamedFrom`），并把「本版新增/改名的必需 env」列进 checklist。发布面本身
+（令牌、tag 不可变、`--wait` / `--wait-review` / `status`）见 `xgent-app-release` skill。
+
+### 值从哪来：三档键名约定（照这张表命名，绝大多数键零手填）
+
+| 档 | 键 | 值从哪来 |
+| --- | --- | --- |
+| **平台注入** | `PORT` · `<PREFIX>_SERVER_PORT` · `PORTAL_INTROSPECT_URL` · `API_BASE_URL` · `PORTAL_BASE_URL` · `<PREFIX>_SA_CLIENT_ID` · `<PREFIX>_SA_CLIENT_SECRET` | 平台换版时自己算并注入，没有人手填 |
+| **自动供给** | 库连接串 · Redis 地址 · 对象存储桶 · Kafka 五键 | 批准时平台按登记的服务代建资源 / 取地址并注入 |
+| **自定** | 其余一切 | 平台管理员手填：非密钥进 `descriptor.env`，密钥进主机 `envFile` |
+
+`<PREFIX>` = `listingKey` 全大写、连字符换下划线。`PORTAL_BASE_URL` 是门户**公开源**（也是调
+别的 App `/svc/<key>` 的基址），`API_BASE_URL` 是内部 portal-api，**不代理 `/svc`**。
+
+**门户内 App 的服务地址由代码派生，不逐个要求平台手填。** 以 Page Builder 为例：
+
+| 原来的地址变量 | 应用代码使用的默认基址 |
+| --- | --- |
+| `LLM_GATEWAY_SERVER_URL` | `${PORTAL_BASE_URL}/svc/llm-gateway` |
+| `FILES_SERVER_URL` | `${PORTAL_BASE_URL}/svc/files` |
+
+接入或审核时核对这几项：
+
+- **清单**：`requiredEnv` 声明 `PORTAL_BASE_URL`，保留其他确实必需的键；上面两个可推导的
+  地址不再列为必填。平台注入的是门户基址，**不会自动注入这两个旧变量**，也不要把派生地址值写进 manifest。
+- **实现与迁移**：代码去掉门户基址末尾的 `/` 后拼接 `/svc/<key>`，再追加具体 API 路径。
+  旧变量可保留为本地调试或特殊部署的可选覆盖项。代码默认值、启动校验、清单与新镜像同步交付，
+  不能只删 `requiredEnv`；平台侧核对已有覆盖值是否保留，并在未设置旧变量时验证实际调用。
+- **权限**：统一入口不替代鉴权。代表用户调用仍需 `exchangeTargets`、目标 scopes 与令牌交换；
+  后台调用仍用获准的服务账号权限，具体姿态见下文「App 型公共服务」。
+
+这条约定针对门户内的 App 服务；第三方 API 等无法从门户基址推导的地址仍按需声明。
+发布操作见 `xgent-app-release` skill「调用门户内的其他 App：从 `PORTAL_BASE_URL` 派生地址」。
+
+**服务怎么绑到键**：键名按约定命名（`<PREFIX>_DATABASE_URL` / `REDIS_CONN_STRING`），再声明要哪条服务 ——
+
+```jsonc
+"requiredServices": [{ "kind": "postgres", "name": "main" }]
+```
+
+⚠️ `requiredServices` 的每一条**只收 `name` / `kind` / `note`**，多一个字段整份清单直接拒收。
+只写 `requiredEnv` 的约定名也认（用该类型的缺省服务）。**键名不按约定来（`ZO_META_POSTGRES_DSN`
+这种上游定死的名字）也能发**，只是平台管理员要在审批屏上逐个点一下「从平台服务取值」，
+每次发版多等一轮。收交付物时把这一条当作可读性问题看：不是错，是白等。
+
+**Kafka**：声明 `requiredServices: [{"kind":"kafka","name":"main"}]`，并在 `requiredEnv` 列出
+`<PREFIX>_KAFKA_BROKERS` / `_KAFKA_USERNAME` / `_KAFKA_PASSWORD` / `_KAFKA_SASL_MECHANISM` /
+`_KAFKA_TOPIC_PREFIX`（每项均带 `<PREFIX>`）。机制固定 `SCRAM-SHA-512`，用户名 `app_<key>`
+把连字符改为下划线；主题、消费组、事务 ID 的前缀 `app.<listingKey>.` **保留连字符**。
+App 显式建主题、副本数 1，不能更改保留期或增加分区；不申请管理员密码。平台是单节点
+at-least-once 消息服务，不是业务记录系统，App 负责重复消费、重连与租户隔离。
+一盒新版 `add` 自动供给相同权限并沿用已有密码，但整份 `compose.env` 仍注入所有容器，
+不提供容器间密钥隔离。完整联调步骤见 [注册布线与一盒](references/registration-and-onebox.md#44-kafka-接入)。
+
+⚠️ 服务账号密钥**不再要求进 envFile**：门户保管并在换版时注入容器，明文只在批准那次一次性
+回显（留给对方本地联调）。收交付物时别再问对方「密钥写进 envFile 了吗」。
+另外，平台级能力（如日志写入）会直接出现在对方的服务令牌里，**不需要在 manifest 里申请**。
+
+## 收交付物时一并核对「跑在哪、要什么服务」两节
+
+manifest 还有两节**同形的审批前置闸**（与 `requiredEnv` 同一挂载点、同一失败语义）：
+
+- `deployRequirements`（`{ region?, size?, gpu?, network? }`）—— 这个 App 的后端需要什么样的
+  机器。批准那一刻按本环境的资源池逐维匹配，不满足就拒绝生效；通过时把落点固定到命中的
+  那台。**需要 `deployDescriptor`**，且只收**名字与档位** —— 网段 / IP / URL 提交即拒。
+- `requiredServices`（`[{ name, kind, note? }]`）—— 运行需要哪些外部服务。批准时比对
+  本环境**已登记**的「已具备服务」（控制台 › 平台设置 › App 清单目录），未登记或缺条目就
+  拒绝生效。登记表描述已有服务；支持自动供给的类型还会按所选档案为 App 建资源与注入约定键。
+
+收交付物时按这两节问三个问题：**它要跑在哪个网络里**（对方写的名字与本环境登记的名字对不
+对得上）、**它连的那些基础服务本环境有没有并且登记了没有**、以及**远端主机上没有门户的
+compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着 `postgres:5432` 时搬到远端
+落点上是连不通的，那正是 `requiredServices` 要把「本环境有什么」摆到审批人眼前的原因。
+
+被拒时对方只会收到一句泛化的「当前环境不满足…，提案已转入待审核队列」（池、网段、机器名
+一个字都不出门户控制台）—— 所以**差在哪要由门户侧的人告诉他们**，别让对方对着一句话猜。
+
+## 无前端服务的租户管理员配置
+
+外部团队实现 `GET/PUT /v1/settings`（TDT 四道闸）；**门户侧要按 App 补三件**（不是零改码）：`<key>-token` 铸造端点 + `<key>-config-api.ts` + `AppForm` 配置 Section——参照 files / llm-gateway，步骤见 portal-backend-app skill。接入新服务时把这三件列入门户侧工作量（omni-parser 至今欠着）。
+
+## 先看平台有没有，别自建一套
+
+外部服务最常见的浪费是把**平台已经有的公共能力**又实现一遍：自己存文件、自己发通知、
+自己记审计、自己排定时任务。除了白干，还会让租户在两个地方看同一件事、让平台的治理面
+（审计/用量/权限）出现盲区。**动手写之前先在这两张表里找。**
+
+### A. 门户基座能力 —— 用你自己的 TDT 直接调 `/api/v1/*`
+
+`PLATFORM_BASE_SCOPES` 里的 scope **任何 App 都能在清单里直接声明**，不需要跨应用授权、
+不需要令牌交换。
+
+| 你想做的 | scope | 端点 |
+| --- | --- | --- |
+| 当前用户是谁 | `userinfo.read` | `GET /api/v1/userinfo` |
+| 选人 / 读通讯录 | `directory.read`（邮箱是 PII，要**另加** `directory.email.read`） | `GET /api/v1/directory/users` |
+| **站内消息 / 通知** | `notification.send`（只发给自己）· `notification.send.others`（发给别的成员） | `POST /api/v1/notifications`；服务态用 `/api/v1/notifications/service` |
+| 收件箱 | `inbox.read` | — |
+| **统一审计** | `audit.write` | `POST /api/v1/audit` |
+| **定时任务** | `scheduler.read` / `scheduler.write` | `/api/v1/scheduler/tasks` |
+| 结构化内容 / CMS | `content.read` / `content.write` | `/api/v1/content/{type}` |
+| **用量计量** | `usage.report`（只收 namespace 前缀 == 你 azp 的 metricKey） | `POST /api/v1/usage/report` |
+| 席位配额 | `seats.read`（SERVICE_ONLY，经 manifest `privilegedServiceScopes` 申请、审批授予，见下节） | `POST /api/v1/seats/quota` |
+| 币种与汇率 | `currency.read` | `GET /api/v1/currency` |
+| 判权限（PID） | — | `POST /api/v1/acl/check` |
+| 用户级设置 | `settings.read` / `settings.write` | `/api/v1/settings/me` |
+| Dashboard 卡片 | `widget.write` | 见 portal-micro-app skill |
+
+### B. App 型公共服务 —— 走 `/svc/<key>` + 令牌交换
+
+这些是**独立 App**，不是基座端点：要在清单里声明 `exchangeTargets`，用交换来的
+`aud=<目标>` 令牌调（机制与排错见 portal-app-exchange skill）。
+
+| 服务 | listingKey | scope 命名空间 |
+| --- | --- | --- |
+| **文件存储**（用户空间 + 应用空间、直传、预览、缩略图） | `files` | `files.read` / `files.write` / `files.share` |
+| 多模态解析（OCR / 文档结构化） | `omni-parser` | `omni_parser.read` / `omni_parser.parse` |
+| 大模型网关（OpenAI 兼容 `/v1`） | `llm-gateway` | `llm_gateway.read` / `llm_gateway.write` |
+
+⚠️ **连字符 listingKey ↔ 下划线 scope**：`omni-parser` 的 scope 是 `omni_parser.*`，
+`llm-gateway` 的是 `llm_gateway.*`。两个命名空间，写混了是 `VALIDATION_FAILED`。
+
+**文件这条尤其别自己来**：字节一律落 files，别自己挂卷、别自己接 S3 —— 否则租户的配额、
+审计、预览、清理全都绕过了平台。落进去用哪种姿态，按**这份字节归谁**二选一：
+
+| 这份字节归谁 | 姿态 | 落在哪 | 用户在文件管理里 |
+| --- | --- | --- | --- |
+| **归 App**：系统产物、用户删不得、随 App 生命周期消失 | 服务账号 `client_credentials`（无用户上下文） | 你自己的**应用空间**（不传 spaceId，懒创建） | 默认只有租户管理员看得到 |
+| **归用户**：用户主动另存、他看得见删得掉、算他的空间 | 令牌交换换出的 `aud=files` **用户态**令牌 | 用户选的**个人/团队空间**（带 spaceId） | 就在他自己的空间里 |
+
+⚠️ **别因为「要写」就默认必须服务态**：用户态持有 `files.write` 完全合法 —— `exchangeTargets`
+背书的是整个命名空间，平台不再按读写另行裁量。凡是「用户在你的界面里点一下、另存到我的
+空间」这类功能**只能**用用户态：服务态写进去的是应用空间，用户在文件管理里根本看不见自己
+刚存的东西。用户态写也不丢归因 —— 交换出的令牌带 `azp=<你的 key>`，files 侧照样落
+`viaApp` 溯源，按来源 App 聚合展示。
+
+### 已经立过的红线（同一条道理，都是「平台有、别自建」）
+
+- **审计**：不自建审计表/页，推 `POST /api/v1/audit`，租户在「设置 › 审计」一处看全。
+- **通讯录**：不做「同步通讯录」到自己库，按需用选人组件挑。
+- **配额/套餐**：见下一节。**计费**：平台级 Credit 服务，同样不自建。
+- **租户级配置**：放门户的 App 配置页（AppForm Section），不是 App 内的设置页。
+- **AI 功能**：终端用户面**不出现模型选择器**，服务端按场景解析模型。
+
+## 有配额需求？用平台的套餐管理，不许自建
+
+**红线：外部服务不自建配额/套餐/计费。** 配额的唯一事实源是平台的套餐矩阵；对方在自己库里存
+一份「本租户上限」，第一次调档就会与门户对不上，而且**没有任何东西会告诉你它们分叉了**。
+
+- 两个模型**二选一**，都只有 **backed listing** 可声明：`seatBased`（计门户成员用不用得了这个
+  App，门户在 TDT 签发时收口，App 侧零代码）/ `seatRoles`（App 自管账号或资源，门户只发数、
+  App 自己在建号路径上收口）。
+- **role 由对方在 `app.manifest.json` 里声明**（不需要门户改代码）；**各套餐的数值进不了
+  manifest**，只有平台管理员在控制台能写 —— 应用侧一条写路径都没有。
+  这是有意的：数值是商务面，改它等于改可售卖档位。
+- 对接面只有一个：`POST /api/v1/seats/quota`（服务态令牌 + `seats.read`）。**`available === null`
+  ⇒ 该租户 unlimited，放行、不要收口** —— 把 null 当 0 是这个契约最容易踩的一处。
+- ⚠️ `seats.read` 是 `SERVICE_ONLY_SCOPES`：对方 manifest 里出现 `serviceScopes: ["seats.read"]`
+  **会被拒收**，评审时这是**当场打回的信号**，不是配置失误。正确路径是
+  `privilegedServiceScopes: [{ "scope": "seats.read", "reason": "…" }]` —— 这是**申请**不是授予：
+  必进「发布审核」，审批人逐条勾选确认后 SA 才拿到（reason 原文展示给审批人）。
+- **配额 ≠ 用量**，别混：配额答「还能不能再建一个」，用量答「这段时间用了多少」，后者走
+  `usageReporter` + `usage.report`。计费方向另有平台级 Credit 服务，同样不自建。
+
+真要落一版（选模型、写 manifest、配数值、上报已用、存量租户、三态处理、判定某个数该不该进
+套餐表）⇒ 读 [references/quota-and-seats.md](references/quota-and-seats.md)。
+
+## 一盒联调与冒烟
+
+外部团队不用克隆本 repo：平台给两个门户镜像 + `deploy/` 目录，对方出 manifest + `compose.env` + 自己的镜像。步骤、冒烟命令与排查速查表见 [references/registration-and-onebox.md](references/registration-and-onebox.md) §4–§6。

package/skills/portal-external-app/references/contract-doc-template.md

@@ -0,0 +1,96 @@
+# 对接契约文档模板（外部服务 → 平台）
+
+> 本模板自包含，可直接在 App 仓库填写。每个外部服务接入前都要按此结构交一份契约文档，且**与已实现代码 1:1 对齐**（理想状态：有回归测试保证路由表与代码同步）。没有这份文档的接入不算完成。
+
+按节填写，方括号处替换：
+
+```markdown
+# `<listingKey>` App — Platform Contract (resource server → portal)
+
+## 1. Listing 元数据
+| 字段 | 值 |
+| --- | --- |
+| listingKey / aud | `<key>`（覆盖变量名如 `<KEY>_AUDIENCE`） |
+| version | `x.y.z` |
+| type | micro / service |
+| scopes | `<key>.read`, `<key>.write`, …（+ `audit.write` 如写审计） |
+| dependencies | 如 `["files"]`（说明是装机拓扑占位还是运行时真调用） |
+| exchangeTargets | 本服务作为交换发起方要读的目标（无则空） |
+| embedUrl | micro 填 `/apps/<key>/`；service 留空 |
+
+（micro 附 navItems JSON。）
+
+## 2. 运行时契约（已实现）
+- 自省端点、Basic 凭证；校验 ok:true 和 data 对象后解析，失败信封不回退；正缓存默认 30 秒/最高 55 秒、调用者隔离、singleflight 与故障 503；
+- kind 与 credential_type 的矩阵、未知类型拒绝；TDT 必填真实 exp，无过期长期 key 可缺省，缓存命中仍判到期；
+- 自省的 `isPlatformAdmin` 是 Portal 按用户实时计算的全局身份，不在 JWT 里；服务态恒为 false；
+- 四道闸各自的失败码（401 INVALID_TOKEN / 403 INSUFFICIENT_SCOPE / FORBIDDEN / INSUFFICIENT_PERMISSION）；
+- 如有跨租户路由：逐条标明 `isPlatformAdmin === true` 服务端闸，说明不用当前 `role` / `bypass` 或前端自报代替；
+- 服务态 TDT 的处理（scope-only；哪些用户拥有的写操作拒绝服务态）；
+- 租户隔离与限流参数。
+
+## 3. 路由 → scope → PID 表（核心，逐条列）
+| Route | method | scope | PID | 额外门 |
+| --- | --- | --- | --- | --- |
+| `/v1/...` | POST | `<key>.read` | `<key>:page:xxx` | |
+| `/v1/...` | POST | `<key>.write` | `<key>:action:xxx` | require admin / require user ctx |
+| `/health` 等 | GET | — | — | public |
+（新增路由的缺省门策略要写明——fail-safe 默认落最严的写门，绝不无门。）
+
+## 4. ACL Manifest JSON（如声明 ACL；纯 scope 鉴权则写明 aclManifest: null）
+（完整 JSON：pages/actions/roleTemplates；DataScope 与 relations 的校验和执行方式，不支持的受限授予必须拒绝，不能扩大为 all。）
+
+## 5. Env 契约（镜像不含 .env）
+| var | required | default/example | 说明 |
+| --- | --- | --- | --- |
+（**列镜像实际读取的变量名**；有门户契约别名的写清映射；端口变量覆盖顺序、是否读裸 PORT；
+门户三变量 all-or-nothing + fail-fast 行为。必填项**同步声明进 manifest 的 `requiredEnv`**
+——键集合一变发布提案会转入人工审核，平台在批准前就看到，且**缺值时批准会被拒绝**；改名写成
+`{ key, renamedFrom }`。不声明的静默改名无门可拦，症状是换版后 refusing to start 而发布侧只看到成功。）
+
+## 6. 平台侧 checklist（对方的工作量）
+（listing/ACL 登记、服务账号创建并回传凭证 —— ⚠️ 只指**你的服务端**那把；租户拿自己的程序
+调你用的那把由租户管理员在 `/admin/service-accounts` 自助开，不是平台工作量，前提是那条 scope
+在 manifest 的 `scopes` 里（integration-contract.md §3.1）、/svc 白名单、交换 grant、
+（micro）dist 托管与 CORS/CSP、（有配置面）<key>-token + config Section。标出阻塞项。）
+
+## 7. 运维命令
+- DB 迁移：**镜像内的迁移 argv**（填进 `deployDescriptor.migrateArgs`）+ 幂等/建议锁/退出码保证；
+- 每租户 bootstrap：需要则给出精确 SQL/命令（tenants.id 必须 = 门户租户 UUID），不需要则明说；
+- 判活/就绪：匿名 GET /health，平铺 JSON 或 Envelope 均可；给出正常与故障响应，并按 health-contract.md 的平台判据说明结果（信封需要 ok:true + data.db:true，非信封依赖故障用 503）；另有 /healthz 时说明它只检查存活；
+- 镜像交付方式（docker save + sha256 / 私有 registry）与架构（amd64+arm64）。
+
+## 6b. 你用了平台的哪些公共能力（逐项声明「用」还是「自建」）
+- 文件存储 / 站内通知 / 统一审计 / 定时任务 / 用量上报 / 结构化内容 / 选人（通讯录）；
+- 任何一项填「自建」都要写明理由 —— 默认答案是用平台的（基座能力走 `/api/v1/*`，
+  文件/解析/大模型这类 App 型服务走 `/svc/<key>` + 令牌交换）。
+
+## 7b. 配额（若有「每租户上限」诉求）
+- 模型：`seatBased`（门户成员席位，门户在 TDT 签发时收口）或 `seatRoles: [...]`（你自管账号，你自己收口）——二选一；
+- 若 seatRoles：列出角色 key，并说明你在哪条建号/建资源路径上调 `POST /api/v1/seats/quota` 收口，
+  以及 `available=null`（unlimited）时放行的处理；
+- 角色 key 由**你在 `app.manifest.json` 里声明**（`"seatRoles": ["service"]`，需 backed listing）；
+  各套餐的数值不进 manifest、由平台管理员在控制台配 —— 在这里**提议**一组（free/pro/ultra），并列出你会上报的 gauge 指标名；
+- **不要**在自己库里存租户上限；`seats.read` **不要**写进 `serviceScopes`（SERVICE_ONLY，会被拒收）——
+  要用 `privilegedServiceScopes: [{ "scope": "seats.read", "reason": "…" }]` **申请**，经「发布审核」逐条确认批准后授予。
+- 机制全貌（三态处理、兜底值、存量租户、已用上报）见 [quota-and-seats.md](quota-and-seats.md)。
+
+## 8. 自测（无 UI 时的 curl 验收）
+（缺/错 token → 401/403；正确 aud+scope → 200 信封。）
+（/health 单独验收：附 scripts/verify-health.ts 对待发布镜像直连及 /svc/<key>/health 的 ready 结果；新增/修改时在隔离环境验证依赖故障的 not-ready，恢复后再验 ready。不得只贴 HTTP 200。）
+
+## 9. 信任边界（如有）
+（自有认证面清单：API-Key/节点 Token/admin 会话/gRPC 端口——哪些绝不从 /svc 暴露；
+MCP/stdio 之类免鉴权面的使用限制；破玻璃通道的启用条件。）
+```
+
+审阅要点（平台方收到契约时逐项验）：
+
+- §3 路由表是否覆盖**全部** `/v1` 业务路由，公开路由是否只有健康/指标；
+- 如有跨租户路由，是否只认自省 `isPlatformAdmin`，并有普通租户 admin 的负控制测试；
+- §5 是否写清镜像实读变量名（对照 compose/K8s 注入排一遍）；
+- §6b 是否有「自建」项而没有理由 —— 自己存文件 / 自己发通知 / 自己记审计是最常见的三处；
+- §7b 若有配额诉求：模型是否二选一说清、role key 是否已在 manifest 的 `seatRoles` 里声明、`seats.read` 是否走了 `privilegedServiceScopes` 申请（写进 `serviceScopes` 是打回信号）、gauge 指标是否已在 manifest `usageMetrics` 里声明、`available=null` 是否按放行处理；
+- §7 两问是否有显式答案：迁移 argv（**必须在镜像里**，不接受「脚本在我们 repo」）、每租户 bootstrap（目前门户无钩子，要显式定方案）；
+- §7/§8 的健康接口是否符合 [health-contract.md](health-contract.md) 的平台判据，并有检查结果；平铺与 Envelope 均可，禁止把合法 ok:true + data.db:true 误判为错误包装；
+- §9 自有认证面是否与 `/svc` 隔离。

package/skills/portal-external-app/references/health-contract.md

@@ -0,0 +1,80 @@
+# App `/health`：与平台一致的判定与发布前检查
+
+**平铺 JSON 与 Envelope 都支持，外部 App 与内建 App 使用相同判据。** 已有健康接口不需要仅为切换包装格式而修改。匿名 `GET /health`，或 `deployDescriptor.healthPath` 指定的路径，应能直接报告服务是否就绪。
+
+## 1. 平台实际怎样判断
+
+按下面的顺序判断，部署控制器、平台信息页、`health:deployed` 巡检及本 skill 的检查脚本保持一致：
+
+1. HTTP 非 **2xx**：不健康。
+2. HTTP 2xx，JSON 对象顶层含 `ok`：仅当 **`ok === true && data.db === true`** 才健康；缺失字段、`false`、字符串 `"ok"` / `"true"` 都不能代替布尔 `true`。
+3. HTTP 2xx，响应没有顶层 `ok`：健康。平台沿用 HTTP 状态判定，不检查平铺字段。
+
+`service`、`redis`、`time` 不参与平台判定；服务名带不带 `-server` 不影响结果。非 JSON / 空响应的 2xx 也沿用第 3 条兼容规则。这是现有检测行为；新接口建议返回有诊断信息的 JSON，不要据此把登录页或无依赖检查的端点当就绪接口。
+
+| HTTP / 响应 | 平台结论 |
+| --- | --- |
+| 200 + `{"service":"wish-list","db":"ok","redis":"ok","time":"…"}` | 健康：平铺响应 |
+| 200 + `{"service":"payhub","db":"ok","redis":"disabled","time":"…"}` | 健康：平铺响应 |
+| 200 + `{"ok":true,"data":{"service":"pagebuilder-server","db":true,"redis":true}}` | 健康：合法 Envelope |
+| 200 + `{"ok":true,"data":{"db":"ok"}}` | 不健康：信封内 db 必须是布尔 true |
+| 200 + `{"ok":true,"db":true}` | 不健康：缺 data.db |
+| 200 + `{"ok":false}` 或 `{"ok":true,"data":{"db":false}}` | 不健康 |
+| 503 + 任意响应 | 不健康：HTTP 优先 |
+| 200 + `{"db":"down"}` | **仍会判健康**：平铺依赖故障应返回 503，不能只改正文 |
+
+必要依赖（包括 Redis）故障时建议统一返回 **503**。特别是 Envelope 的 `data.redis:false` 不会单独让平台判失败，必须通过 HTTP 状态报告必要 Redis 故障。健康响应不要包含密钥、连接串或原始异常。
+
+## 2. 两种正确实现范例（Bun / Elysia）
+
+以下使用 App 已有的 `db` / `sql` / `redis`；只有确实未使用 Redis 时，`redis` 才为 `null`。连接的查询/命令超时应短于平台单次探测的 5 秒（例如 3 秒）。选择一种响应写法即可。
+
+```ts
+app.get('/health', async ({ set }) => {
+  const [dbUp, redisUp] = await Promise.all([
+    db.execute(sql`select 1`).then(() => true, () => false),
+    redis === null
+      ? Promise.resolve(true)
+      : redis.ping().then((reply) => reply === 'PONG', () => false),
+  ]);
+  set.status = dbUp && redisUp ? 200 : 503;
+
+  // 写法 A：平铺。依赖故障由上面的 503 表达。
+  return {
+    service: 'my-app',
+    db: dbUp ? 'ok' : 'down',
+    redis: redis === null ? 'disabled' : redisUp ? 'ok' : 'down',
+    time: new Date().toISOString(),
+  };
+
+  // 写法 B：用下面的 return 替换上面的 return，允许使用等价的 ok({...})。
+  // return { ok: true, data: { service: 'my-app', db: dbUp, redis: redisUp, time: new Date().toISOString() } };
+});
+```
+
+采用 A 时，响应中间件应保留平铺结构；若改为 B，`data.db` 必须同步改为布尔值。不能只给字符串状态套 `ok(...)`，那会得到 `data.db:"ok"`，被平台判失败。
+
+## 3. 发布前检查
+
+本 skill 自带 [scripts/verify-health.ts](../scripts/verify-health.ts)，只依赖 Bun；旁边的 `health-verdict.ts` 与门户运行时同源，导出 skill 时会校验一致性。在 App repo 根目录执行；`SKILL_DIR` 表示本 skill 的 `SKILL.md` 所在目录（本文件的上一级），按实际加载位置填写。URL 和 `HEALTH_APP` 按实际替换：
+
+```bash
+SKILL_DIR="<本 skill 的 SKILL.md 所在目录>"
+HEALTH_APP=my-app
+
+# 待发布镜像的直连路径。
+bun "$SKILL_DIR/scripts/verify-health.ts" http://127.0.0.1:8080/health "$HEALTH_APP"
+
+# 接入一盒后的代理路径。
+bun "$SKILL_DIR/scripts/verify-health.ts" "http://localhost/svc/$HEALTH_APP/health" "$HEALTH_APP"
+```
+
+默认 `ready` 模式，平台会判健康才退出 **0**；失败退出 **1**，参数错误退出 **2**。`listingKey` 仅用于输出标签，不额外校验响应中的 service。脚本的请求、JSON 解析和判定与平台一致，不另加 Content-Type、字段类型或命名规则；因此这是就绪检查，不是 JSON schema 验证器。
+
+新增/修改健康接口时，在隔离测试环境制造依赖故障后执行（不要断开生产共享依赖）：
+
+```bash
+bun "$SKILL_DIR/scripts/verify-health.ts" http://127.0.0.1:8080/health "$HEALTH_APP" not-ready
+```
+
+`not-ready` 要求收到平台会判失败的响应，例如 503 或 `data.db:false`；连接失败仍退出 1，不能替代故障响应的验证。恢复依赖后重跑 `ready`。Docker healthy / `curl -f` 只看 HTTP 时，无法覆盖信封的 db 判据。