@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/portal-external-app/references/quota-and-seats.md

@@ -0,0 +1,213 @@
+# 配额与席位（seatBased / seatRoles）
+
+> 有「每租户最多能建几个 X」这类诉求时读本文。提炼自门户仓 `apps/api/src/modules/seats/`、
+> `packages/shared/src/constants.ts`、`apps/api/src/db/provisioning.ts`（门户仓文件，App 自己的
+> repo 里没有；本文件已自包含）。冲突时以门户仓库为准。
+
+## 0. 红线
+
+**外部服务不自建配额/套餐/计费。** 配额的唯一事实源是平台的套餐矩阵。对方在自己库里存一份
+「本租户上限」，第一次调档就会与门户对不上，而且**没有任何东西会告诉你它们分叉了**。
+
+**配额 ≠ 用量**：配额答「还能不能再建一个」，用量答「这段时间用了多少」。后者走 `usageReporter`
++ `usage.report`（指标注册表 = 内置 `USAGE_METRICS` ∪ manifest `usageMetrics` 声明，见 §5）。
+计费方向另有平台级 Credit 服务，同样不自建。
+
+## 1. 先选模型：二选一
+
+两者都是 listing 上的标记，且**仅 backed listing** 可声明 —— end-state 得有 `serviceBaseUrl` 或
+`deployDescriptor`，否则 `createListing`/`updateListing` 直接 `VALIDATION_FAILED`：「只有带独立后端
+(serviceBaseUrl / 部署描述)的应用可声明席位制」（`market/service.ts` 的 `assertSeatBasedEligible`）。
+
+| | 用在哪 | 谁收口 |
+| --- | --- | --- |
+| `seatBased: true` | 计「门户成员」用不用得了这个 App | **门户**。TDT 签发时就拦：无席位 ⇒ `SEAT_REQUIRED`，App 侧零代码 |
+| `seatRoles: ["teacher","student"]` | App **自管账号/资源**（sms 的师生号那类） | **App 自己**。门户只发数，不拦对方的建号请求 |
+
+## 2. 四要素分属四个事实源
+
+「配额」不是一件事。想清楚你要动的是哪一件，再决定找谁：
+
+| 要素 | 谁写 / 写在哪 | 要门户发版吗 |
+| --- | --- | --- |
+| role 存不存在（`seatRoles: ["service"]`） | **对方自己的 `app.manifest.json`**（清单仍在门户仓的 App 才是 `LISTING_DEFS`） | 不用 |
+| 各套餐给几个（生效值） | 平台管理员 → `PUT /api/console/seat-plans` upsert `app_seat_quotas(listing_key, plan, role)` | 不用 |
+| 单租户加购 | 平台管理员 → `PUT /api/console/tenants/:id/seat-addons`（仅 pro/ultra 可加购） | 不用 |
+| role 的三语标签 `SEAT_ROLE_LABELS` | 门户 `packages/shared/src/constants.ts` | **要**（不加则控制台显示裸 role key，`?? role` 兜底不报错） |
+| SA 的 `seats.read` | **对方 manifest `privilegedServiceScopes: [{scope, reason}]` 申请** → 「发布审核」逐条确认批准即授予（`SA_DEFS.serviceScopes` 降为种子/运维兜底，union top-up 不回滚审批授予） | 不用 |
+
+⚠️ **各套餐的数值进不了 manifest，也进不了 `LISTING_DEFS`** —— `AppManifest` 与 `ListingDef`
+都只有 `seatBased` / `seatRoles` 两个字段，没有任何 per-plan 数值字段。应用侧**没有任何写路径**
+（manifest 没这字段 · 发布提案携带的未知字段一律进人工审而非生效 · `seats.read` 只读）。这是有意的：
+数值是商务面，改它等于改可售卖档位、影响所有租户。应用侧能做的是在契约里**提议**一组数。
+
+⚠️ **`seats.read` 是 `SERVICE_ONLY_SCOPES`**（与 `directory.provision` / `lms.taxonomy.manage` 同列）。
+外部团队在 manifest 里自己写 `serviceScopes: ["seats.read"]` **会被拒收** —— 评审交付物
+时看到它是**当场打回的信号**，不是配置失误。要拿它走
+`privilegedServiceScopes: [{ "scope": "seats.read", "reason": "…" }]`：这是**申请**不是授予，
+必进「发布审核」（最高治理档，审批人逐条勾选确认），批准后经 `registerFromManifest`
+落到 SA 的服务态 scope。
+
+## 3. 声明写在 manifest 里（不需要门户改代码）
+
+`seatRoles` / `seatBased` 是 `AppManifest` 的一等字段，`register-app --prod` 与控制台「导入 manifest」
+都经 `manifestToListingInput` → `updateListing` 落到 listing 上：
+
+```jsonc
+{
+  "listingKey": "task-gateway",
+  "deployDescriptor": { "image": "…" },  // 没有它(或 serviceBaseUrl) ⇒ 席位声明会被拒
+  "seatRoles": ["service", "node"]
+}
+```
+
+两条操作面的事实：
+
+- 写进 manifest 后随 `publish --manifest` 提交 —— `seatRoles` 是治理档，提案进「发布审核」
+  等平台批准后生效（`register-app --prod` / 控制台「导入 manifest」是运维兜底路径，同一段
+  `registerFromManifest`）。
+- 出仓四件（knowledge / task-gateway / omni-parser / pagebuilder）已**不在** `LISTING_DEFS`
+  里 —— 清单唯一事实源就是对方仓的 manifest，不存在双事实源问题；**别把定义加回门户**
+  （verify-split「清单零残留」棘轮看守）。
+- 仓内 App 在 `LISTING_DEFS` 加 `seatRoles` **不用 bump version**：它走「代码权威
+  字段」通道，每次部署都对齐，跟版本治理无关。
+
+## 4. 对接面与三态
+
+```
+POST /api/v1/seats/quota    服务态令牌(client_credentials, azp=自己的 listingKey), scope seats.read
+body { roles: ["service","node"] }
+→ { tenantId, plan, listingKey, roles: [{ role, quota, quotaIsDefault, addon, available }] }
+```
+
+在**建号/建资源路径**上查它并拒绝超额，就是 App 侧的全部工作量。按三态分支，**别只看数字**：
+
+| 响应 | 含义 | 建议动作 |
+| --- | --- | --- |
+| `available === null` | 该租户 unlimited | 放行，不收口。**把 null 当 0 是这个契约最容易踩的一处** |
+| `quotaIsDefault: true` | 平台还没配，你拿到的是兜底 | 按兜底值放行 **+ 打告警**，别静默按一个没人定过的数收口 |
+| `quotaIsDefault: false` | 权威值 | 照值收口。**值可能是 0** —— 那是平台明确决定「这档不给」 |
+
+**解析顺序**：`app_seat_quotas` 行 → `SEAT_ROLE_DEFAULTS[role]` → `UNREGISTERED_ROLE_DEFAULTS`
+（各档一律 **1**）。1 的意思是「能跑通、但显然还要配」。
+
+- 兜底**不能取 0**：0 是合法的权威配置值（`putSeatPlans` 接受 0），拿它表示「没配」就再也分不开
+  「没配」与「明确不给」——而 `quotaIsDefault` 存在的全部意义就是分开这两者。
+- `seatBased` 的成员席位走**另一条**兜底 `DEFAULT_PLAN_SEATS` = free 3 / pro 20 / ultra 100，别混。
+- 新 role 落地后**一定要去控制台配一轮真实数值**，别让生产挂着兜底跑。
+
+## 5. 想让控制台显示「已用 / 超额」：得上报 gauge
+
+平台不掌握 `seatRoles` 的占用数（收口在 App 侧），所以「已用」来自 App 自己上报的日快照：
+metricKey 约定 `<listingKey>.<role>-seats.allocated`（`latestRoleAllocated` 读最近一天）。
+sms 先例每个 role 报两条（`allocated` + `available`），两个 role 共 4 条。
+
+⚠️ **硬门**：`ingestUsage` 对**未注册**的 metricKey **拒收该条记录**，且指标的
+`appKey` 必须等于上报者的 azp。漏注册的症状是上报接口返 200 但记录进 `rejected`，
+控制台「已用」恒 0、`overQuota` 恒 false、加购决策没有依据（拒收理由现在会显式指出
+「未注册 —— 请在 usageMetrics 里声明」，不再是无提示的静默失真）。
+指标注册表 = 内置 `USAGE_METRICS` ∪ 各 listing 的 manifest `usageMetrics` 声明：
+**外部 App 在自己 manifest 的 `usageMetrics` 里声明 gauge 条目**
+（`[{ key, kind: "gauge", unit: "count", label: {zh,…} }]`，key 前缀必须=listingKey、
+金额单位 microAmount 不开放；治理档，批准后生效）——不再需要门户发版；
+仓内 App 仍在 `packages/shared/src/usage.ts` 登记。
+
+## 6. 两层快照：谁读哪一层
+
+安装时 `seatBased` / `seatRoles` 会快照进该租户的 `apps` 行。三个面读的表**不同**：
+
+| 面 | 读哪张 |
+| --- | --- |
+| 平台配额矩阵 `getSeatPlans` | `marketplace_listings.seat_roles` |
+| 租户加购 `getTenantAddons` | **`apps.seat_roles`（已装租户快照）** |
+| `POST /api/v1/seats/quota` | **两者都不读** —— roles 来自请求体，只查 plan + 配额表 + 加购表 |
+
+**存量租户不需要人工回刷**，两条路都自带传播：
+
+- `LISTING_DEFS` 路：`syncFromSource` 对 listing 层与已装 `apps` 行**各打一次**
+  `codeAuthoritativePatch`（union 语义），随 `bootstrap:prod` 自动到达。
+- manifest 路：`updateListing` 直接批量 update 所有已装 `apps` 行，`registerFromManifest` 之后
+  还会再跑一次 `syncInstalledAppsFromListing`。
+
+推论：**漏声明不会 fail-closed**。`/api/v1/seats/quota` 不读任何 seatRoles 声明，照样按请求体里的
+role 返回兜底值。真实症状是**控制台配额矩阵与加购面不出这一行** ⇒ 平台配不了、租户加购不了
+⇒ 所有租户静默跑兜底。真正 fail-closed 的是 SA 缺 `seats.read` → 403。
+
+## 7. 三个坑
+
+- **manifest 的 `seatRoles` 是整份覆盖，不是 union**（`updateListing`，改动还会批量传播到所有已装
+  租户的 `apps` 行）。下一版 manifest 少写一个 role ⇒ 那个 role 从所有租户消失。清单字段
+  「只增不减」那条规矩管的是 scopes/dependencies/exchangeTargets，**不覆盖 `seatRoles`**。
+  （走 `LISTING_DEFS` 那条是 union，不会静默删。）
+- **role 名没有格式校验，改名 = 换一个新 role**：旧 `(listing_key, plan, role)` 配额行成孤儿 ——
+  全仓没有任何地方删它们，`getSeatPlans` 只按当前 `seatRoles` 出行，于是孤儿行在控制台不可见
+  却还躺在库里（改回同名会「复活」旧数值），而新 role 悄悄回落兜底。**role 名定下来就别动。**
+- **`SEAT_ROLE_DEFAULTS` 按 role 名索引，不带 App**（`Record<role, Record<plan, number>>`）——
+  全平台共用一个 role 名命名空间，两个 App 都用 `node` 就共享同一份代码兜底。DB 里的权威值
+  倒是按 `(listing_key, plan, role)` 分得开。要放代码兜底就挑个不会撞的名字。
+
+## 8. 判定：这个数该不该进套餐表
+
+**先问一句「你说的是配额还是用量」** —— 两者经常被混为一谈。三个面的命名空间也各不相同：
+
+| 面 | 命名 | 例 |
+| --- | --- | --- |
+| scope | **下划线** | `task_gateway.submit` |
+| 用量指标 `USAGE_METRICS.key` | **连字符** | `task-gateway.tasks.submitted` |
+| 配额 | **不是字符串键** | `(task-gateway, pro, service) → 10` |
+
+配额的键空间是 `app_seat_quotas` 的唯一索引 `(listing_key, plan, role) → seats:int`。namespace 已经
+由 `listingKey` 占掉，你要提供的只是一个**短 role 名**。（所以「entitlements 的 key 怎么命名」是个
+不成立的问题 —— 平台没有 entitlements 这个东西。）
+
+**再问「是不是真要按套餐卖」。** 只是防滥用的安全上限就别进套餐表 —— 进了就等于承诺它是可售卖
+档位，以后想改口径要动所有租户的既有配额。
+
+**最后看它像不像一个「池子」。** `app_seat_quotas` 存的不是参数，是池子：它自带加购
+（`available = quota + addon`）、已占用（gauge）、超额（`overQuota = allocated > available`）三件配套。
+配套不成立的东西塞进去不会报错，只会让控制台显示一行永远「已用 0 / 未超额」、还挂着语义错的
+加购入口的假数据。
+
+⚠️ 别拿「唯一键里没有『每个父对象』这一维」当判据 —— 一个**对所有实例一律生效**的上限就是
+一个整数，`(app, plan, role) → 5` 存得下。只有「A 服务 3 个、B 服务 10 个」那种**真嵌套**配额才卡在
+键的形状上。平台**不**为此新建通用 entitlements 表：真功能要排期，代价是平台从此有两套配额模型。
+
+## 9. 案例：task-gateway 的 `max_services` / `max_nodes_per_service`（2026-08-19）
+
+对方提议拿它们当「entitlements 的 key」问门户怎么映射到套餐表。逐条判定：
+
+- **`max_services`**（每租户最多几个 service）→ **能落**，就是一个 role。按 §2 的事实源表分工：
+  role 由对方 manifest 声明 · 数值平台在控制台配 · gauge 由对方 manifest `usageMetrics` 声明 ·
+  `seats.read` 由对方 manifest `privilegedServiceScopes` 申请（审批授予）· 门户侧只剩
+  `SEAT_ROLE_LABELS` 三语标签一件（可选，不加显示裸 role key）。
+- **`max_nodes_per_service`**（每个 service 最多几个 node，对所有 service 一律生效）→
+  **能落，但配套三件空转**（§8）。按「随不随套餐变」三分：
+  **(a)** 不随套餐变（纯防滥用）→ App 侧产品常量，别进表；
+  **(b)** 随套餐变、卖的是**总容量** → 租户级 `node` 池（`seatRoles: ["service","node"]`），三件配套
+  全部成立，门户看得见真实水位、加购这条商业路径也保住 —— **默认推荐这条**；
+  **(c)** 随套餐变、且确实要卖「节点密度」→ 把这个一律生效的上限当一个 role 落，标签必须说清是
+  「每个服务的上限」而不是总量（否则平台管理员会当成总量配错），接受那行的配套空转。
+
+## 10. 落地清单
+
+**外部 App（manifest 路，除标签外无需门户发版）**
+
+1. manifest 加 `seatRoles: [...]`（治理档）
+2. manifest 加 `usageMetrics` gauge 条目（每 role 两条：`.allocated` / `.available`；治理档）
+3. manifest 加 `privilegedServiceScopes: [{ "scope": "seats.read", "reason": "…" }]`（申请，审批逐条确认后授予）
+4. （可选）门户 `SEAT_ROLE_LABELS` 加三语标签 —— 唯一仍要门户发版的一件；不加则控制台显示裸 role key
+5. 批准部署后，平台管理员在控制台按 `App × role × 套餐` 配一轮真实数值
+
+**仓内 App（LISTING_DEFS 路，随门户发版）**
+
+1. `LISTING_DEFS[<key>]` 加 `seatRoles: [...]`
+2. `SEAT_ROLE_LABELS` 加三语标签；`SEAT_ROLE_DEFAULTS` 加各档默认值（可选；不加则一律兜底 1）
+3. `USAGE_METRICS` 加 gauge 条目（每 role 两条）
+4. `SA_DEFS[<key>].serviceScopes` 加 `seats.read`
+5. 部署后控制台配数值
+
+**App 侧**
+
+1. 建号/建资源路径上调 `POST /api/v1/seats/quota`，按 §4 三态分支
+2. 每日上报 gauge（`allocated` = 当前实际数，`available` = 配额 + 加购；unlimited 不报）
+3. 形状类上限（每个实例最多几个子对象）留作 App 侧常量

package/skills/portal-external-app/references/registration-and-onebox.md

@@ -0,0 +1,259 @@
+# 注册布线与一盒（one-box）本地联调
+
+> 提炼自门户仓库 `docs/外部App本地联调指南-one-box.md`、`deploy/app-devkit/README.md`、`docs/SSO与App开发指引.md` §15.3（§4 一盒部分对齐 2026-08 的精简镜像与自建 Harbor）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库为准。
+
+## 1. `app.manifest.json`（单一事实源，放你自己的 repo）
+
+既是交付契约也是注册脚本的输入。字段：
+
+- 身份/展示：`listingKey`（= TDT aud = 服务账号/容器命名基名）、`name`、`version`、`cat`、`tagline`、`desc`、`icon`、`color`
+- 形态：`type`（`micro` 有前端 / `service` 无前端）、`embedUrl`（micro：`/apps/<key>/`）、`embedCsp.connectSrc`、`helpEntry`（micro：版头帮助按钮入口，`"/help"` App 内路由 = 自动档 ／ `"https://…"` 外站文档 = 治理档；不声明就不出按钮）
+- 权限：`scopes` + `scopeLabels`（同意屏逐 scope 的说明文案，支持多语——形状见下）、`aclManifest`（纯 scope 鉴权可 `null`）、`navItems`（micro）
+  - ⚠️ `scopes` 还有第二个用途：它（按租户的安装期快照）就是**租户自助开服务账号**时的可选项池。
+    租户要拿自己的采集器/脚本/CI 直调你，那条 scope 必须在这里；只写在 `serviceScopes` /
+    `privilegedServiceScopes` 里的，租户面**一条也勾不到**（见 integration-contract.md §3.1）。
+    `scopeLabels` 同时是那个勾选列表的正文——不写就只显示裸 scope 串。
+- 关系：`dependencies`、`exchangeTargets`、`serviceBaseUrl`（`/svc/<listingKey>`）
+- 服务态与计量：`usageReporter`（true ⇒ SA 得 `client_credentials` + `usage.report`）、`serviceScopes`（服务态 scope；SERVICE_ONLY **永拒**）、`privilegedServiceScopes`（SERVICE_ONLY 的**申请**：`[{scope, reason}]`，reason 必填，最高治理档、审批逐条确认后授予）、`usageMetrics`（用量指标声明：key 前缀必须=listingKey、金额单位不开放；治理档，批准后 ingest 才认这些 key）
+- 部署/运维：`requiredEnv`（部署所需 env 的**键名**清单，值永远由平台配；元素可写 `{ key, renamedFrom }` 表达改名。键集合一变提案转入「发布审核」，且**批准前门户会比对 `descriptor.env ∪ envFile` 的键集合，缺了拒绝生效**（`REQUIRED_ENV_MISSING`，提案留 pending））、`deployDescriptor`（`image` 归自动档、`hostPort` 归平台不算变更，**其余一切属治理档**）、`deployRequirements`（后端要跑在**什么样的机器**上：`{region?, size?, gpu?, network?}`，只写**名字与档位**，网段/IP/URL 提交即拒；批准时按目标环境**当时**的资源池逐维匹配，不满足则拒绝生效、提案留待审，通过则把首次落点固定住；需要 `deployDescriptor`）、`requiredServices`（运行所需的**外部服务** `[{name, kind, note?, envKey?}]`，身份是 `(kind, name)` 二元组；批准时比对本环境**已登记**的「已具备服务」，未登记或缺条目则拒绝生效 —— 门户**不据此开通**，只核对登记表；`envKey` 只被携带、当前不注入）
+
+⚠️ **`deployDescriptor.hostPort`（宿主机发布口）不归 App 定**：它是部署环境相关的事实——同一份 manifest 会发到一盒与好几套生产门户，各自端口地貌不同，而 App 团队看不见目标机器上谁占了什么。规则三句话：**首次注册**当建议值采纳（撞了自动退让到平台端口池 20000–20999，**不会因此拒掉注册**）；**listing 已存在则一律忽略**（那个口已经写进 Caddy 的 `/svc` map、也是在跑的容器发布出来的口）；发布响应的 `warnings` 会说明实际是哪个口。App 只管 `port`（容器内监听口，约定 8080）。
+**例外**：`extraPorts[].host` **不参与退让**，撞了硬拒——那些是对外契约口（worker 节点连的就是那个数字），静默挪走等于把它们全断掉，且门户侧一条都测不到。
+- dev 专用明文：`serviceAccount{clientId,secret}`（`clientId` 约定 `<key>-server`，且**必须是自己的** —— 服务账号身份归平台，声明已归属另一 App 的 clientId 会进人工审、批准也会在生效时被写入闸拒绝）、`exchangeInitiatorSecret`（本应用作为交换发起方时的 App Secret）
+
+**文案字段的形状**（写错的那一组**不会报错**，所以单列一张表）：
+
+| 字段 | 形状 | 写错的后果 |
+| --- | --- | --- |
+| `tagline` / `desc` / `icon` / `color` / `cat` / `navItems[].label` / `dashboardWidgets[].title` | **纯字符串**（单语） | 给多语对象 ⇒ 门户把它拼成字面量 `"[object Object]"` 存进 text 列，显示在每个租户的应用卡片与详情上 |
+| `name` | 纯字符串 | 给对象不报错，但会被**拍平成 zh-CN**，另外两种语言就此丢掉 |
+| `scopeLabels[<scope>]` | 字符串 **或** `{ "zh-CN": …, "zh-TW": …, "en": … }` | 存 jsonb，同意屏按门户当前语言解析；回退链 当前语言 → `zh-CN` → `en` → 键名，所以 **`zh-CN` 是回退终点，必写** |
+| `aclManifest` 内的 `label` / `name` / `desc` | 同上（字符串或多语对象） | 角色矩阵按请求 locale 解析 |
+| `usageMetrics[].label` | **`{ "zh": …, "en"?: …, "tw"?: … }`** —— 键名与上一行**不是同一套** | 缺 `zh` ⇒ 提交即拒 |
+
+`scopeLabels` 还有两条静默失效：**键不在 `scopes` 里的在写入时被直接丢弃**（同意屏上那条回落成键名，改 scope 名忘了改文案键就中）；
+**平台基础 scope（`userinfo.read` / `audit.write` / `notification.*` …）的文案不归 App 写** —— 那是平台统一维护的措辞，
+各 App 各写一份，同一条权限在不同应用的同意屏上就会说得不一样，比缺文案更糟；发现平台漏了哪条，反馈给平台补。
+
+**scope 三规则**（写时强校验）：一条清单只能声明——
+1. 平台基础 scope（`userinfo.*`/`audit.write`/`notification.*`/`settings.*`/`scheduler.*`/`content.*` 等）；
+2. **自己命名空间**：`<listingKey>.` 前缀及连字符→下划线变体（`omni-parser` → `omni_parser.*`）；
+3. **已声明 `exchangeTargets` 的目标命名空间**（例：omni-parser 声明 `files.read` 但 exchangeTargets 不含 files → 拒；knowledge 声明 `files.read` 且 `exchangeTargets:["files"]` → 放行）。
+
+越界 → `VALIDATION_FAILED`。App 命名空间 scope 随清单入库，**不用改门户代码**。
+
+⚠️ 规则 3 **读写不分**：背书的是整个命名空间，`files.write` 与 `files.read` 同一条待遇，
+没有「写要额外批一次」这回事。别人的 App 只声明了读，那是它自己的业务选择（它的写面不
+代表用户），不是平台对你的限制 —— 照抄别人的清单当规矩用，会把一个本来合法的功能砍掉。
+
+## 2. 注册（dev / 一盒）：`register-app`
+
+```bash
+bun run register-app <你的>.manifest.json    # 幂等；NODE_ENV=production 拒跑
+```
+
+四件事：① 按 listingKey upsert + 发布 listing（复用门户写时校验：scope 命名空间 / ACL 形状 / 依赖无环）；② DB 直写 `token.introspect` 服务账号（secret = manifest 明文；同 secret 不动、不同则轮换）；③ 把 `exchangeInitiatorSecret` 写进**已安装**实例的 App Secret——⚠️ 所以**先在门户安装 App、再重跑一次 register-app**，否则发起交换 401（判定方法见 §2.2，别看日志里那个数字）；④ 往 `caddy-svc-allow` 卷写 `<key>.map` 放行 `/svc/<key>`（免改 Caddyfile、免重启反代）。
+
+### 2.1 第五件事：授予租户（dev 自动 / 生产不自动）
+
+**发布一条 listing 并不会让它出现在任何租户的市场里。** 那道闸 fail-closed 在
+`tenant_listing_grants` 上：列表按授予集过滤、安装前 `assertTenantMayUseListing` 无授予行直接
+`LISTING_NOT_GRANTED`。授予行本来由 `installListing` 在**安装那一刻**写（「安装即授予」，依赖一并
+授予）——这对被依赖方成立，但对**目标 App 自己**是先有鸡还是先有蛋：路由闸先于安装拒绝。
+
+| 路径 | 行为 |
+| --- | --- |
+| **dev / 一盒**：`register-app <manifest>` | **自动授予当时已存在的所有租户**（非 service 型），输出里有一行 `租户可用应用: 新授予 N 个租户` |
+| **生产**：发布提案批准 / 控制台导入 manifest（`mode:"prod"`） | **不自动授予** —— 语义是平台管理员显式勾选，自动授予会绕过治理面 |
+
+⚠️ **判断你手上的一盒镜像有没有这个自动授予**：跑完 `register-app` 看输出里**有没有
+`租户可用应用:` 这一行**。没有 ⇒ 镜像早于这次改动，按下面手动补。
+
+⚠️ **自动授予只覆盖「注册那一刻已存在」的租户**：之后新建的租户不会被补授，要么再跑一次
+`register-app`，要么手动勾。
+
+**手动补授权（生产必走 / 老镜像上必走）**：**平台 › 租户管理 › 选中租户 › 「可用应用」tab**，
+勾上你的 App 再保存（计数会从 `4/5` 变 `5/5`），之后租户市场才出现「安装」。
+
+⚠️ 没授予时的症状极具迷惑性：**平台控制台「清单管理」显示已上架**（还能点「转为草稿 / 下架」，
+看着一切正常），但**租户市场里根本不出现这个 App**——没有报错、没有灰掉的卡片，就是不在列表里。
+别去查发布状态，那不是病根。
+
+⚠️ `service` 型**永不写授予行**（自动与手动都不写）：它在那张表里的勾选语义是**安装 / 卸载**
+（勾上即 `installListing`、取消即卸载），事实源是 `apps.status` 而不是授予表——一个勾选只许一个
+事实源。
+
+### 2.2 `wired into N installed instance(s)` 的 N 是「改了几个」，不是「对了几个」
+
+`wireInitiatorSecret` 对 `secretHash === hash` 的实例直接 `continue` —— **不计数**。所以 **N=0 有两义**：
+① 还没有任何安装实例；② 所有实例本来就已经是对的。register-app 在 N=0 时打印的
+`(none installed yet — install then re-run…)` **只覆盖第 ① 种**，看到它别当成「没写成」。
+
+**判据是比哈希，不是看数字**（三处必须相等）：
+
+```
+sha256(<manifest 的 exchangeInitiatorSecret>)
+  == 门户 app_secrets 里 prefix='sk_<listingKey>' 且 status='active' 那行的 secret_hash
+  == sha256(<你后端 env 的 <PREFIX>_APP_SECRET>)
+```
+
+「先装再重跑」那一步只对**第一个租户**是必要的：`installListing` 现在会把发起方密钥的哈希
+随安装布进新实例（EXCHANGE-SECRET-HOLD：有平台保管值用保管值，dev 没有保管值就从既有实例的
+active 行拷哈希）——但「谁都还没布过」的第一个实例仍然只有 `register-app`（与 seed 的
+provisioning 路径）能写。所以装完第一个租户后的那次重跑仍要跑，**之后每次重跑都显示 0、
+之后装的租户自动布上，那都是正常的**。
+
+## 3. 注册（生产）
+
+生产的清单事实源就是对方仓的 `app.manifest.json`：平台在控制台
+「应用市场 › 接入新应用」按 key 签发 `xrel_` 令牌（无行先建 draft 占位），对方
+`publish --manifest` 提交，平台在「发布审核」批准 = `registerFromManifest` 建全
+（listing 上架 + SA + /svc + 已装租户对齐）。**不要**把外部 App 登记进 `LISTING_DEFS` ——
+门户只保留平台侧事实（`EXCHANGE_WIRING` / Caddy 内联行 / 部署行，及作为**种子**的
+`SA_DEFS` 与 scope 常量 —— 特权 scope 已可经 `privilegedServiceScopes` 申请、审批授予），
+`bootstrap:prod` 对外部 key 只自愈 SA 与部署行。**生产没有 manifest 明文密钥这条路**：
+SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批准时生成、enc:v1 保管、
+换版时注入容器（EXCHANGE-SECRET-HOLD）；明文只回显给审批人一次（供本地联调），轮换走
+控制台（应用清单 ›「轮换交换密钥」/ 服务账号 ›「轮换密钥」），都顺带排换版。要交接一枚
+**既有**的交换密钥（比如和一盒联调对齐），把值写进门户进程的 `<PREFIX>_APP_SECRET` env
+再批准一次即可 —— apply 会把它接管为保管值，两侧从此同源，那行 env 之后可删。
+
+⚠️ **secret 一致红线**：平台落库的服务账号 secret 与你镜像 env 里的必须一致。漂移症状 = 自省 401，或「跨应用授权缺失/未开启」（实为 `SECRET_INVALID`）。排查：对你侧 secret 求 sha256 与门户 DB 存的哈希比对。
+
+## 4. 一盒联调流程
+
+分工：平台交**两个门户镜像** + `deploy/` 目录（含 `app-devkit/` 与 `onebox/`）。你交
+①manifest ②`compose.env`（本机接线：`APP_KEY`=listingKey、`APP_IMAGE`、micro 才需
+`APP_FRONTEND_DIST` **绝对路径**）③你的后端镜像（+ micro 的前端 dist）。
+**不 clone 门户、不改门户代码、不重建门户镜像。**
+
+```
+<registry>/<项目>/one-box:latest   # portal runtime → XGENT_IMAGE       (~310MB)
+<registry>/<项目>/proxy:latest     # caddy proxy    → XGENT_PROXY_IMAGE (~68MB)
+```
+
+⚠️ 三条硬前提，缺一条第 0 步就过不去：① **仓库地址与拉取账号都要问平台团队** —— 仓库不开放
+匿名拉取，得有一个 **puller 账号**（只读凭证，按团队发放），`docker login <registry>` 用的就是它；
+凭证别转发给团队外的人、别写进会提交的文件（`portal-dev-setup` skill 把这两样收在一份
+`.xgent-registry.env` 里，照它配即可）。② **这两个调试镜像有 `latest`**（跟着最新一版走，开新项目
+不用先问 tag）；代价是本地已有同名 `latest` 时 compose **不回仓库查**，换版本前先 `docker pull`。
+要钉住某一版就写 `:v<版本>-<7位sha>`（当前 `v1.1.0-5c1660e`），那种 tag 不可变。③ **一盒只发 `arm64`**（它是给开发机用的调试底座，开发机全是
+Apple Silicon），生产门户走另一条链。无 registry 访问时则要离线 `docker save` tar，`docker load` 即可
+（那条路上镜像的本地 tag 可能叫 `ai-portal-one-box:local` / `xgent-ai-portal-proxy:local`）。
+
+### 4.1 一盒里有什么，以及刻意没有什么
+
+一盒是**调试底座，不是门户**：它按 `deploy/onebox/Dockerfile` 单独构建，只带四个**基础服务 App**——
+`files`（文件管理）· `llm-gateway`（大模型网关）· `git`（Git 服务）· `org`（组织架构）。
+`git` **依赖 `files`**，两者要么一起在 `XGENT_BASE_APPS` 里、要么一起不在。
+
+下面三件「缺失」都是刻意的，**不是环境坏了**，收到这些报错别当配置问题查：
+
+- 其余内置 App（spms/sms/qbank/lms/…）的 workspace **已从镜像里删掉** ⇒
+  `bun --filter @xgent/spms-server …` 直接报 `no packages matched the filter`；
+- 镜像烘死 `XGENT_ONEBOX=1` ⇒ `bootstrap:prod` 与 deploy-controller **启动即拒**并打印原因；
+- 没有 `ffmpeg` 与 `docker CLI`（合计省 552MB）⇒ `PREVIEW_MEDIA_CONVERTER_URL` 必须**留空**
+  （填 `auto` 会让每次转换去 exec 一个不存在的二进制），视频海报/网格缩略图退化成图标，
+  图片/PDF/文本预览不受影响。
+
+### 4.2 起栈之前：躲开本机已占的端口与项目名
+
+一盒**只发布 6 个宿主端口**（reverse-proxy 80/443 → `HTTP_PORT`/`HTTPS_PORT`、postgres 5432 →
+`POSTGRES_PORT`、redis 6379 → `REDIS_PORT`、minio 9000/9001 → `MINIO_PORT`/`MINIO_CONSOLE_PORT`）；
+其余（portal-api 的 3000、各 `<key>-server` 的 8080、你的 app-backend 的 8080）只 `expose`，不占宿主。
+撞了就在 `compose.env` 里改这几个；改的只是发布口，一盒内部一律走 compose 网络的
+`postgres:5432` / `redis:6379` / `minio:9000`。改了 `HTTP_PORT` 之后门户地址随之变化，下文冒烟里的
+`http://localhost/…` 都要跟着改。
+
+⚠️ 两个必改/必不做：
+
+- **`COMPOSE_PROJECT_NAME=xgent-onebox`** —— 模板里写死的是 `xgent`，同机起两套栈时
+  compose 会认为它们是同一个项目：容器名冲突、命名卷被共享，症状是「我起了一盒，结果把另一套的
+  容器停了」。项目名固定 `xgent-onebox`、全机只跑一套一盒：已有在跑的一盒时别再起第二套，
+  把你的 App 接进现有那套（见 portal-dev-setup 文首「一套就够」）。
+- **不要**关掉 `local-infra` 让一盒去连你本地那套 PG —— 库名会撞（`xgent-portal` / `xgent-files` …），
+  而 `db:seed:onebox` 是会往里写的，等于拿一盒的种子污染你的本地开发库。
+
+### 4.3 端到端命令（从 repo 根跑；相对路径解析自第一个 `-f` 文件所在目录）
+
+```bash
+# 0) docker login <registry> && docker pull 上面两个 tag（或 docker load tar）+ 你的镜像
+# 1) env 三层：基础模板 + 一盒增量 + 本套件增量
+#      cp  deploy/compose.env.example                deploy/compose.env
+#      cat deploy/onebox/compose.env.onebox.example  >> deploy/compose.env   # ★ 一盒必需
+#      cat deploy/app-devkit/compose.env.app.example >> deploy/compose.env
+#      填 XGENT_IMAGE / XGENT_PROXY_IMAGE / APP_KEY / APP_IMAGE /(micro)APP_FRONTEND_DIST
+#      + 你后端读的 SA 密钥与 DSN（与 manifest 的 serviceAccount.secret 等值）+ 强随机门户密钥
+# 2) 起基础设施:  --profile local-infra up -d postgres redis minio
+# 3) 门户迁移 + 基线 seed:
+#      run --rm portal-api bun run db:migrate
+#      run --rm portal-api bun run db:seed:onebox     # ★ 不是 db:seed
+# 4) 注册:        run --rm -v "$(pwd)/deploy/app-devkit/manifests:/devkit:ro" \
+#                   portal-api bun run register-app /devkit/<你的>.manifest.json
+# 5) 起门户三件套 + 你的后端（网络别名 <key>-server:8080）:
+#      -f docker-compose.yml \
+#      -f onebox/docker-compose.onebox.yml            # ★ 一盒必须叠这一层
+#      -f app-devkit/docker-compose.app-dev.yml [micro 加 app-frontend.yml]
+#      --profile local-infra --profile app-external up -d reverse-proxy portal-api app-backend
+# 5b) 按需起基础 App 后端（同一个镜像，compose command 选跑哪个）+ 各自库迁移:
+#      --profile app-files --profile app-llm-gateway --profile app-git --profile app-org up -d
+#      run --rm portal-api bun run db:files:migrate   # 同理 db:llm-gateway / db:git / db:org
+#      ⚠️ 这批迁移要跑在 db:seed:onebox 之前 —— 种子会替 deploy-controller 跑各 App 的逐租户基线
+# 6) 你自己的库迁移：跑你镜像的迁移 argv（生产由门户经 migrateArgs 自动跑，这里手动跑同一条）
+#      run --rm --env-file <同一份> <你的镜像> --role migrate
+#    每租户 bootstrap（若你的表 FK 自己的 tenants）：门户目前没有钩子，本地手动建行
+```
+
+⚠️ **第 3 步必须是 `db:seed:onebox`**：`db:seed` 会串起十几个 App 的种子链（qbank/lms/exam/task/…），
+而它们的 workspace 不在一盒镜像里 —— **必失败**。`db:seed:onebox` 只种 `XGENT_APP_CATALOG` 里的四个基础 App。
+
+⚠️ **第 4 步要跑在起反代之前**：注册会往 `caddy-svc-allow` 卷写 `<key>.map`，反代启动时 `import` 才读得到。
+
+⚠️ **依赖 `files` 的 App 别忘了 5b**：`files` 已在镜像里、`/svc/files` 已放行、市场安装会连带补装它，
+但**后端进程不起来**读文件就是 502/401。`FILES_SA_CLIENT_SECRET` 必须与 `db:seed:onebox` 种的 SA secret
+等值，否则自省 401。
+
+细节（含 App 自带基础设施如向量库 sidecar、把后端跑在宿主上保留热重载的 socat 绕法）见交付包内
+`deploy/app-devkit/README.md`。
+
+## 5. 冒烟
+
+打开 `http://localhost/` → 登录页的「本地开发账号」按钮（没有就直接开 `/auth/dev/start`）→ 选 `rockie`（租户 admin + 平台管理员）。
+
+**第 0 步：确认租户已被授予**（否则下面第 1 步无从点起）。新版 `register-app` 在 dev 下会自动授予并
+打印 `租户可用应用: …`；没看到那一行（老镜像）就去 平台 › 租户管理 › 选中租户 › 「可用应用」勾上保存（§2.1）。
+
+⚠️ `db:seed:onebox` 只种两个 dev 账号：`rockie@xgent.ai`（admin）与 `liming@xgent.ai`（普通成员）——
+**用普通成员再走一遍**。ACL member 基线没到位的问题（`defaultForMember` 没种进 member 角色）
+只在非管理员身上才现形，管理员的 `bypass` 会把它整个盖住。
+
+- **micro**：应用市场安装（连带补装依赖）→ 应用中心打开 → iframe 加载 `/apps/<key>/`、`sdk.ready()` 握手 → `sdk.callService("<key>", ...)` 通 → 跨应用读数据首次弹交换授权页 → 切租户看不到上一租户数据。
+- **service**（无 UI 走 curl）：
+
+```bash
+curl http://localhost/svc/<key>/health           # 平铺 {"service":"<key>","db":"ok"} 或信封 {"ok":true,"data":{"db":true}}
+curl -X POST http://localhost/svc/<key>/v1/...   # 缺/错 token → 401/403（四道闸生效）
+# 拿一个 aud=<key> 的 TDT（经交换，或 dev 自助 /api/tokens/authorize → /oauth/token）→ 200 信封
+```
+
+**micro / service 的健康接口都按 [平台健康判据](health-contract.md) 验证**：运行 skill 自带 `scripts/verify-health.ts`，同时检查 HTTP 与信封的 db 判据；首次接入/修改健康接口还要在隔离环境验证必要依赖故障的 `not-ready`。
+
+## 6. 排查速查
+
+| 症状 | 病根 |
+| --- | --- |
+| **租户市场里看不到你的 App**（控制台却显示已上架） | **该租户没被授予**（§2.1）。三种成因：① 一盒镜像早于自动授予那次改动（输出里没有 `租户可用应用:` 行）；② 该租户是注册之后才建的；③ 走的是生产路径（本就不自动）。补法：平台 › 租户管理 › 租户 › 「可用应用」勾上保存。**不是发布状态问题** |
+| 安装报 `LISTING_NOT_GRANTED` | 同上（这是同一道闸的显式报错形态） |
+| `wired into 0 installed instance(s)` | **未必是没写成**：0 = 本次没有改动，含「本来就是对的」。按 §2.2 比哈希判定 |
+| `/svc/<key>` 404 | 白名单 `.map` 没写成，或反代先于 register-app 起（重启反代/重跑注册） |
+| `/svc/<key>` 502 | 后端没起 / 没听 8080 / 网络别名 `<key>-server` 没命中 |
+| `/health` 能访问，但健康检查失败 | HTTP 非 2xx 或信封未满足 `ok:true + data.db:true`；平铺与合法信封都支持，详见 [health-contract.md](health-contract.md)。部署超时还需看启动日志与迁移，不能仅凭包装格式定因 |
+| 有效 TDT 被判 `INVALID_TOKEN` | 先检查自省 ok:true 和 data 对象，再校验 data；失败信封/缺 data 为 503，不能回退到顶层 |
+| register-app 报 scope `VALIDATION_FAILED` | 声明了别人的 scope 但没列进 `exchangeTargets` |
+| 发起交换 401 | `exchangeInitiatorSecret` 未写进已安装实例（先安装再重跑 register-app）或 secret 漂移 |
+| 受门路由 503 | 门户三变量（自省地址/SA id/secret）配置不全 |
+| `db:seed`/`bun --filter @xgent/<别的 App>` 报 `no packages matched the filter` | **刻意的**：一盒只带四个基础 App，其余 workspace 已删。seed 用 `db:seed:onebox`（§4.3） |
+| 读写文件 502 / 401 | `files` 后端没起（`--profile app-files` + `db:files:migrate`）；401 多半是 `FILES_SA_CLIENT_SECRET` 与种子里的 SA secret 不等值 |
+| `git` 连不上本机 Gitea/GitHub | 一盒是 `NODE_ENV=production`，SSRF 守卫默认拒环回与私网 —— 把目标 hostname 显式列进 `GIT_ALLOWED_HOSTS` |
+| 视频海报/网格缩略图不出 | 一盒没装 ffmpeg，`PREVIEW_MEDIA_CONVERTER_URL` 应留空（§4.1）；其余预览不受影响 |
+| 起了一盒把另一套栈的容器停了 | `COMPOSE_PROJECT_NAME` 没改（§4.2） |

package/skills/portal-external-app/scripts/health-verdict.ts

@@ -0,0 +1,22 @@
+// 部署、平台信息页、巡检共用此判据。skill 带同源副本，export-skills.sh 校验逐字一致。
+export type HealthVerdictKind = "healthy" | "degraded" | "unhealthy";
+
+/** 先看 HTTP，再按顶层是否含 ok 分流；不按内建/外部 App 区分。
+ *  信封必须 ok===true 且 data.db===true；非信封沿用任意 2xx 通过的兼容规则。
+ *  service/redis/time 不参与判定，非信封的依赖故障必须由非 2xx 状态表达。 */
+export function healthVerdict(
+  res: { ok: boolean; status: number },
+  body: unknown,
+): { verdict: HealthVerdictKind; detail: string | null } {
+  if (!res.ok) return { verdict: "unhealthy", detail: `http ${res.status}` };
+  const isEnvelope = body !== null && typeof body === "object" && "ok" in (body as object);
+  if (!isEnvelope) return { verdict: "healthy", detail: null };
+  const b = body as { ok?: unknown; data?: { db?: unknown } };
+  if (b.ok !== true) return { verdict: "degraded", detail: "ok=false" };
+  if (b.data?.db === true) return { verdict: "healthy", detail: null };
+  return { verdict: "degraded", detail: b.data?.db === false ? "db=false" : "db=unknown" };
+}
+
+export function isHealthy(v: { verdict: HealthVerdictKind }): boolean {
+  return v.verdict === "healthy";
+}

package/skills/portal-external-app/scripts/verify-health.ts

@@ -0,0 +1,27 @@
+// 独立运行，无需门户源码或凭证；判据与平台运行时同源。
+// bun verify-health.ts <health-url> <listingKey> [ready|not-ready]
+import { healthVerdict, isHealthy } from "./health-verdict";
+
+const args = Bun.argv.slice(2);
+const [url, listingKey, expected = "ready"] = args;
+if (args.length < 2 || args.length > 3 || !url || !listingKey || !["ready", "not-ready"].includes(expected)) {
+  console.error("用法：bun verify-health.ts <health-url> <listingKey> [ready|not-ready]");
+  process.exit(2);
+}
+
+try {
+  // 与 deploy-controller / health:deployed 相同：5 秒超时，JSON 解析失败按 null 判定。
+  const res = await fetch(url, { signal: AbortSignal.timeout(5000) })
+    .catch(() => { throw new Error("健康接口无法连接或探测超时"); });
+  const body = await res.json().catch(() => null);
+  const verdict = healthVerdict(res, body);
+  const up = isHealthy(verdict);
+  if (up !== (expected === "ready"))
+    throw new Error(`期望 ${expected}，实际 ${verdict.verdict}${verdict.detail ? ` (${verdict.detail})` : ""}`);
+  console.log(`[health-contract] PASS ${listingKey}: ${verdict.verdict}, HTTP ${res.status}`);
+} catch (error) {
+  // not-ready 只验证收到了明确的失败响应；连接失败不算故障分支已正确实现。
+  // 不打印服务响应体，它可能错误地包含连接串或其他秘密。
+  console.error(`[health-contract] FAIL: ${error instanceof Error ? error.message : "探测失败"}`);
+  process.exit(1);
+}