@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,273 @@
+---
+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/`（为本 skill 提炼的自包含参考，可整目录拷到外部团队 repo；权威源是门户仓库 `docs/`，冲突以门户仓库为准）。
+
+
+> **路径约定（先读这条，能省一次白找）**：本 skill 里出现的 `apps/…` `packages/…` `docs/…`
+> `deploy/…` 这类路径**都在门户仓**。在 App 自己的 repo 里它们**不存在** —— 它们标注的是
+> 「门户侧要做什么」或某段内容的出处，**不是让你去打开的文件**。找不到不是配置错误：
+> 别去创建、别去全局搜、别把它当缺失依赖报出来。你需要的一切都在本 skill 的
+> `references/`（自包含）。若你正在门户仓里工作，那这些路径就是可以直接打开的真实文件。
+>
+> ⚠️ 一个例外：`/apps/<key>/`（带前导斜杠）是**线上 URL 路径**——微应用产物的挂载点，
+> 与仓内的 `apps/<key>-app/` 目录无关，别混。
+
+## 按任务读参考
+
+| 任务 | 读 |
+| --- | --- |
+| 实现/评审资源服务器（四道闸、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) |
+| 为外部服务写/审对接契约文档 | [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) 的结构与精度。**没有这份文档的接入不算完成**——新服务（如任务网关）要先补。
+
+## 资源服务器硬契约（外部实现最常炸的四处）
+
+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)。
+
+## 注册布线（细节见 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 …` ⇒ 首次必进
+  「发布审核」队列 ⇒ 批准 = `registerFromManifest` 一次建全（listing 上架 + SA + /svc +
+  已装租户对齐），SA secret 明文一次性回显给审批人。**不要**再把外部 App 登记进
+  `LISTING_DEFS` —— 那会成为把对方清单静默改回去的第二事实源（verify-split「清单零残留」
+  棘轮看守）。门户保留的平台侧事实只有：部署行、Caddyfile 内联行、`EXCHANGE_WIRING`，
+  以及作为**种子**的 `SA_DEFS` 与内置 scope 常量 / `USAGE_METRICS` ——「审批而非发版」后，
+  特权服务态 scope 经对方 manifest 的 `privilegedServiceScopes` 申请、审批即授予（SA_DEFS
+  不再是唯一授予点，union top-up 也不会回滚审批授予）；用量指标经 manifest `usageMetrics`
+  声明（治理档）；控制台应用配置的 scope 校验运行时按 listing 声明放行（不卡编译期枚举）。
+- **后续版本**：对方 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 地址 | 批准时平台按登记的服务代建库 / 取地址并注入 |
+| **自定** | 其余一切 | 平台管理员手填：非密钥进 `descriptor.env`，密钥进主机 `envFile` |
+
+`<PREFIX>` = `listingKey` 全大写、连字符换下划线。`PORTAL_BASE_URL` 是门户**公开源**（也是调
+别的 App `/svc/<key>` 的基址），`API_BASE_URL` 是内部 portal-api，**不代理 `/svc`**。
+
+**服务怎么绑到键**：键名按约定命名（`<PREFIX>_DATABASE_URL` / `REDIS_CONN_STRING`），再声明要哪条服务 ——
+
+```jsonc
+"requiredServices": [{ "kind": "postgres", "name": "main" }]
+```
+
+⚠️ `requiredServices` 的每一条**只收 `name` / `kind` / `note`**，多一个字段整份清单直接拒收。
+只写 `requiredEnv` 的约定名也认（用该类型的缺省服务）。**键名不按约定来（`ZO_META_POSTGRES_DSN`
+这种上游定死的名字）也能发**，只是平台管理员要在审批屏上逐个点一下「从平台服务取值」，
+每次发版多等一轮。收交付物时把这一条当作可读性问题看：不是错，是白等。
+
+⚠️ 服务账号密钥**不再要求进 envFile**：门户保管并在换版时注入容器，明文只在批准那次一次性
+回显（留给对方本地联调）。收交付物时别再问对方「密钥写进 envFile 了吗」。
+另外，平台级能力（如日志写入）会直接出现在对方的服务令牌里，**不需要在 manifest 里申请**。
+
+## 收交付物时一并核对「跑在哪、要什么服务」两节
+
+manifest 还有两节**同形的审批前置闸**（与 `requiredEnv` 同一挂载点、同一失败语义）：
+
+- `deployRequirements`（`{ region?, size?, gpu?, network? }`）—— 这个 App 的后端需要什么样的
+  机器。批准那一刻按本环境的资源池逐维匹配，不满足就拒绝生效；通过时把落点固定到命中的
+  那台。**需要 `deployDescriptor`**，且只收**名字与档位** —— 网段 / IP / URL 提交即拒。
+- `requiredServices`（`[{ name, kind, note?, envKey? }]`）—— 运行需要哪些外部服务。批准时比对
+  本环境**已登记**的「已具备服务」（控制台 › 平台设置 › 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，也进不了 `LISTING_DEFS`**，只有平台管理员在控制台能写 —— 应用侧一条写路径都没有。
+  这是有意的：数值是商务面，改它等于改可售卖档位。
+- 对接面只有一个：`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 @@
+# 对接契约文档模板（外部服务 → 平台）
+
+> 泛化自已交付的知识库契约（`docs/knowledge-app-contract.md`，**门户仓文件，App 自己的 repo 里没有**；本模板已自包含，不必去找）。每个外部服务接入前都要按此结构交一份契约文档，且**与已实现代码 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 判据。

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

@@ -0,0 +1,130 @@
+# 外部镜像服务类应用 · 集成契约
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §7/§15 与已接入案例（知识库 / omni-parser，2026-08）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库为准。
+
+## 1. 形态与分界
+
+外部镜像 App = 服务端在自己的 repo（任意语言/栈）、独立 Docker 镜像交付。鉴权、统一 :8080 与 `/svc/<key>` 路由遵循门户契约；**`/health` 支持平铺 JSON 与 Envelope，使用平台同一判据**。注册与部署方式如下：
+
+| | 内建 App | 外部镜像 App |
+| --- | --- | --- |
+| 镜像 | 全部长在同一 runtime 镜像 | 独立镜像（`docker save` tar / 私有 registry，不发公共 dockerhub） |
+| 部署 | deploy-controller 按需拉起/缩零 | **常驻**（controller 不编排外部镜像）：独立 Deployment / compose profile，无状态可多副本 |
+| 注册 | seed / bootstrap 内建 | `app.manifest.json` + register-app（dev）/ provisioning 登记（生产） |
+
+**App 类型**：有用户前端 → `micro`（前端 dist 由平台同源托管到 `/apps/<key>/`）；无前端 → **`service`**（headless：应用市场/应用中心不露卡、不可打开，仅作被调用方；平台控制台清单管理仍可治理，可作依赖被补装）。
+
+## 2. 交付物（外部团队 → 平台）
+
+1. **后端镜像**：容器内监听 **8080**（可由 env 覆盖，编排统一注 8080）；服务名/网络别名 **`<listingKey>-server`**（通用反代规则按此 DNS 命中）；多架构 **amd64 + arm64**（生产集群 amd64）；**不烘焙 `.env`/密钥**。⚠️ 只需要认这一个**容器口**；发布到宿主机的哪个口（`deployDescriptor.hostPort`）归平台按环境分配，别在镜像或 manifest 里把它当常量依赖（详见 registration-and-onebox.md）。
+2. **`app.manifest.json`**（见 registration-and-onebox.md）。
+3. **env 契约表**：逐个列镜像**实际读取**的变量名。⚠️ 镜像内部若用自有前缀（知识库读 `XGENT_PG_DSN`，门户契约别名 `KNOWLEDGE_DATABASE_URL`；且**不读裸 `PORT`**），必须写清映射，编排按镜像认的名字注入。
+4. **运维口径**（没有默认答案，必须显式声明）：
+   - **迁移 argv**：迁移文件**必须在镜像里**，二进制上给一个迁移入口（如 `--role migrate`），
+     由 `deployDescriptor.migrateArgs` 在**换容器前**以一次性容器执行。
+     要求：幂等 · `pg_advisory_lock` 包住 · 失败非零退出 · expand-contract 前向兼容。
+     ~~外部命令（`scripts/migrate.sh up` 式）~~ 已作废 —— 脚本留在对方 repo 里门户拿不到，
+     对方 CI 也连不到门户的库；「启动自迁」同样不再推荐（失败变崩溃循环 + 挤健康窗口）；
+   - 是否需**每租户 bootstrap**：业务表 FK 自己的 `tenants` 表就需要——首次写入前 `INSERT INTO tenants (id, slug) VALUES ('<门户租户UUID>','<slug>') ON CONFLICT DO NOTHING`，`id` **必须等于门户租户 UUID**（自铸 uuid 会在首写触发外键冲突）；`tenant_id` 只是普通列则无需；
+   - `/health` 判活口径（§4）。
+5. **对接契约文档**：按 contract-doc-template.md 的结构写（路由→scope→PID 表、env、运维命令、信任边界）。
+
+## 3. 运行时鉴权（四道闸）
+
+每个受保护请求：取 `Authorization: Bearer <TDT 或端点已接纳的长期凭证>` → 调门户自省并校验声明 → 四道闸。Bun/TypeScript 使用公共服务端 SDK；其他语言实现下述相同契约。
+
+```
+POST {PORTAL_INTROSPECT_URL}            # 如 http://portal-api:3000/api/tokens/introspect
+  Authorization: Basic base64(<saClientId>:<saSecret>)
+  body: { "token": "<Bearer 凭证>" }
+→ 200 { "ok": true, "data": {
+    "active", "kind": "user"|"service", "principal_id", "credential_type", "credential_id", "aud", "listingKey", "azp",
+    "tenant_id", "user_id", "scopes": [], "role", "isPlatformAdmin", "bypass", "groups",
+    "permissions": [{ "pid", "scope", "relations"? }]|null, "aclStamp", "exp"? } }
+```
+
+1. **身份**：端点显式允许 user/service；用户态检查 `(claims.listingKey ?? claims.aud) === 你的 listingKey`，否则 401 `INVALID_TOKEN`。服务态 aud 是来源 SA clientId、azp 是来源 App，按端点用途校验，不能把来源当目标；
+2. **scope** ∈ `claims.scopes`，否则 403 `INSUFFICIENT_SCOPE`；
+3. 用户结构性管理操作看 `claims.role === "admin"`；服务身份不能携带用户角色进入此闸；
+4. 用户细粒度操作校验 PID，并执行命中授予的 `scope`（own/team/all）与 `relations`。字段必须保留、校验并在业务查询中收口；不支持受限范围时拒绝该授予，不能升级成 all。纯服务端点按 scope、来源及业务绑定授权。
+
+如端点是**平台级跨租户**读/写，在上述四道闸外另加 `claims.isPlatformAdmin === true`。该值由 Portal 在每次自省时按 `user_id` 检查其是否为平台租户 active admin，与当前 `tenant_id` / `role` / `bypass` 独立；它是自省派生信息，**不在 TDT JWT claims 里**。不能用当前租户 admin、平台租户 ID 比较或前端头推导全局身份。
+
+硬形状（外部实现最常炸的四处）：
+
+- **信封与故障**：门户响应先检查 `ok === true` 且 `data` 为对象，再校验声明；`ok:false`、缺/null data、坏 JSON、非法声明、自省 HTTP 401/403/5xx 或超时均返回资源端 503。不能从失败信封回退到顶层；合法 `active:false` 或真实到期才是 401。若实现兼容裸声明，只能在根本不存在 ok 字段时走独立完整校验分支。
+- **主体与凭证类型**：service 允许 tdt/service_access_key，user 允许 tdt/user_access_key；未知类型、互串类型返回 503。缺省 kind 仅兼容完整合法用户声明，不能推断服务身份。principal_id 是主体 UUID，user 时须与 user_id 一致；service 无 user_id/role/groups/permissions，bypass/isPlatformAdmin 为 false。用户长期 key 只在明确迁移的机器入口启用，并逐请求核验 credentialId 对应的本地业务绑定；普通 REST 默认只接纳 tdt/service_access_key。
+- **到期与缓存**：TDT 的 exp 必须存在且非 null；无过期长期 key 可省略（兼容旧 null）。exp 是非负安全整数 Unix 秒；0 为已到期，负数/非数值为 503。正缓存默认 30 秒、最高 55 秒，从自省请求开始计时，加门户配置最多 5 秒总撤权预算 60 秒；受真实 exp 截断，命中仍检查 exp，不滑动续期或伪造到期。键隔离完整自省地址、调用者配置及 bearer 哈希；同上下文并发合并，不缓存 inactive/故障，缓存依赖故障时直查门户，门户也故障则 503。
+- **全局身份字段**：`active:true` 始终带布尔 `isPlatformAdmin`，服务态恒为 `false`。虽然 Portal 在自省时实时计算，下游缓存会让身份变更最多延后 60s 生效；更敏感的操作应缩短缓存或直查。
+- **门户三变量 all-or-nothing**：自省地址 + SA clientId + SA secret **全缺** → 门户鉴权停用、受门路由 503；**缺一不全** → 启动 fail-fast 打印缺失变量。避免半配置静默放行。
+- **租户隔离**按 `claims.tenant_id`（永不信任请求体）；限流自建 `(aud, tenant)` 每分钟窗口（参考默认 600/min）。
+
+**三种令牌来路 × 授权姿势**：
+
+| 来路 | kind | user_id | 授权依据 |
+| --- | --- | --- | --- |
+| 自己前端（宿主注入 / callService） | user | 有 | scope + PID/ACL |
+| 其他 App 令牌交换（如 files→omni-parser） | user | 有 | 同上；scope=发起方 TDT ∩ 你声明的 scopes；`azp`=发起方（出处归因） |
+| 服务账号 client_credentials（服务直调） | service | **无** | **只按 scope**（permissions 空、bypass=false、isPlatformAdmin=false，勿走 PID 门；用户拥有的写操作应拒绝） |
+
+### 3.1 服务账号从哪来：平台代建 vs 租户自助
+
+有**两条**路会产出打给你的 `client_credentials` 凭证，两条铸出来的令牌形状一样（`kind:"service"`、
+`user_id:null`、`azp` = 某个 listingKey、`tenant_id` 钉死），你的闸**一个字都不用改**。区别只在谁建、
+建给谁：
+
+| | 平台代建（`SA_DEFS` / manifest `serviceScopes`） | 租户自助（租户管理员，控制台路径 `/admin/service-accounts`） |
+| --- | --- | --- |
+| 建的人 | 平台管理员 / 你的 manifest 声明 | **租户自己的管理员**，不经平台 |
+| 典型用途 | 你的服务端调门户（files/notification/audit/seats…） | 该租户的采集器、脚本、CI **调你** |
+| 租户范围 | 由平台决定（可 `all`） | **恒 allowlist=[他自己那一个租户]**，请求体里出现别的租户 id 直接 `VALIDATION_FAILED` |
+| `azp` | manifest 里的 `serviceScopes.ownerAppKey` | = 租户选的那个已装 App 的 listingKey（**用户填不了、也不用填**） |
+| 可选 scope | `serviceScopes` / `privilegedServiceScopes`（可含 SERVICE_ONLY，走审批） | **只有 `scopes`（用户态那份清单）里、属于你自己命名空间的那些**；平台基础 scope 与 SERVICE_ONLY 一律不可选 |
+
+**⚠️ 对你的唯一要求，就在最后一行**：租户自助的 scope 池取的是**该租户安装你时那份 `apps.scopes`
+快照**（= manifest 的 `scopes`），不是 `serviceScopes`。所以——
+
+> 一条只写在 `serviceScopes` / `privilegedServiceScopes` 里的 scope，**租户自助永远勾不到**。
+> 想让租户自己开凭证来调你的某条路（典型：日志/指标摄取），那条 scope 必须出现在 manifest 的
+> **`scopes`** 里。
+
+这不矛盾：`scopes` 是「这个 App 在这个租户能做的事」的清单，用户态与租户自助的服务态都从它派生；
+`serviceScopes` 是「**你的服务端**代表自己去调**别人**」的那一份，不属于租户可自助的范围。
+
+其余几条租户自助的行为，都是你已经在依赖的机制，列出来是为了让你知道不必另做：
+
+- **卸载即失效**：`ownerAppKey` 的装机门跑在**签发时刻**，租户把你卸了之后新令牌立刻
+  `APP_NOT_INSTALLED`；同时门户会连坐停用该租户自助建的、绑在你身上的那些服务账号，把**已签出**
+  的令牌一并断掉（服务态令牌只认 SA 版本号，不停用会一直活到 TTL 到期）。**停用**是可逆动作，
+  不连坐 —— 签发门以 `APP_DISABLED` 挡住新令牌，敞口只有已签出那批的剩余 TTL。
+- **scope 收窄即时生效**：租户在应用配置里把你的某条 scope 去掉之后，那些自助钥匙**下一次
+  签发**就不再带它（不需要租户去改凭证、也不需要你做任何事）。所以你侧永远以令牌里实际带的
+  scope 为准，别缓存「这把 clientId 有哪些 scope」。
+- **密钥只显示一次**，可轮换/吊销；轮换即刻作废在途令牌。
+- **审计**落在该租户自己的审计日志里（创建/轮换/吊销/删除/每一次签发）。
+- 每租户有个数上限（默认 10）。
+
+## 4. 健康检查
+
+- **实现、出仓或发布镜像前必读 [health-contract.md](health-contract.md)**：有完整正确实现、错误示例与可执行验收命令。
+- `GET /health`（匿名就绪接口）支持平铺 `{"service":"my-app","db":"ok","redis":"disabled"}` 与信封 `{"ok":true,"data":{"db":true}}`。HTTP 非 2xx 不通过；2xx 顶层含 `ok` 时必须 `ok === true && data.db === true`；否则按 HTTP 状态判健康，不校验平铺字段。必要依赖故障建议返回 503，尤其平铺响应不能仅把 db 改为 `"down"` 仍返回 200。
+- 可另设 `GET /healthz`（存活，`{"status":"ok"}`），不能用它代替就绪检查。发布前用 skill 的同源脚本验证；Envelope 的 `data.db` 必须是布尔 true，不能混用平铺示例的字符串。
+
+## 5. 响应信封与审计
+
+- **业务接口**响应统一 `{ ok, data | error }`，业务失败 HTTP 仍 200；4xx/5xx 只留传输/认证/路由层（401 缺/坏令牌、403 scope/权限、429 限流）。**`/health` 的形状与故障状态按 §4 实现；允许信封，也允许保留平铺响应，不应被中间件意外改成 `data.db:"ok"`。**
+- 审计：不自建审计页，关键操作用当次用户 TDT `POST {API_BASE_URL}/api/v1/audit`（需声明 `audit.write` scope），best-effort。
+
+## 6. 自有认证面与 Portal 认证面的划界
+
+服务自带认证体系（API-Key、节点 Token、自有 admin 会话、gRPC 端口等）时：
+
+- 凡经 `/svc/<key>` 暴露给门户侧的 HTTP 面，一律 TDT 四道闸——不得让门户侧调用方复用你的自有认证。
+- 自有节点/外部客户端面保持原认证，但**不得**从 `/svc` 暴露；`/svc` 只转发 HTTP :8080，gRPC 等额外端口在网关契约之外，需单独规划暴露并写进交付契约。
+- 平台/其他 App 调你：有用户上下文走令牌交换、无用户上下文走服务账号 client_credentials（scope 落你的命名空间）——不是给平台发你体系内的 API-Key。吊销、审计、租户策略都收口在门户。
+- 若有 MCP/stdio 之类**免鉴权信任面**：只限本地可信进程，发货镜像不得暴露（知识库的 `--role mcp` 规则）。
+
+## 7. 无前端服务的租户管理员配置
+
+- 外部团队实现 `GET/PUT /v1/settings`（四道闸；读/写门槛按 scope），存租户级覆盖，运行时 `内置默认 → 租户覆盖 → 单次请求参数` 叠加。
+- 门户侧需按 App 补三件（平台方工作量，不是零改码）：`<key>-token` admin-TDT 铸造端点 + 前端 config-api + 应用配置页 Section。浏览器直连你的 `/svc/<key>/v1/settings`，门户不经手敏感配置。