@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,106 @@
+---
+name: portal-app-exchange
+description: '跨应用调用（OAuth Token Exchange）的布线与排错。凡任务涉及让 App A 读 App B 的数据（如 组卷读题库、文件调多模态解析、任务中心读 LMS）、声明 exchangeTargets/交换白名单/consent 共授，或出现 EXCHANGE_NOT_ALLOWED / EXCHANGE_CONSENT_REQUIRED / CONSENT_REQUIRED / SECRET_INVALID / GRANT_NOT_ALLOWED / 跨应用下拉列表莫名为空 等症状时，务必先用本 skill 再动手改代码。Use for wiring or debugging cross-app token exchange: grants, whitelists, consent co-grant, scope intersection, and the classic failure modes (secret drift, missing user consent rows, consent narrowing).'
+---
+
+# portal-app-exchange · 跨应用调用（令牌交换）布线与排错
+
+App A 代表用户调 App B = 拿一个 `aud=B` 的 TDT，走 OAuth Token Exchange，**严格不可提权**。
+权威源是门户仓库 `docs/SSO与App开发指引.md` §11/§15.3/§15.4（2026-07），冲突以门户仓库为准。
+
+> **路径约定（先读这条，能省一次白找）**：本 skill 里出现的 `apps/…` `packages/…` `docs/…`
+> `deploy/…` 这类路径**都在门户仓**。在 App 自己的 repo 里它们**不存在** —— 它们标注的是
+> 「门户侧要做什么」或某段内容的出处，**不是让你去打开的文件**。找不到不是配置错误：
+> 别去创建、别去全局搜、别把它当缺失依赖报出来。本 skill 已自包含，没有 references/。
+> 若你正在门户仓里工作，那这些路径就是可以直接打开的真实文件。
+>
+> ⚠️ 一个例外：`/apps/<key>/`（带前导斜杠）是**线上 URL 路径**——微应用产物的挂载点，
+> 与仓内的 `apps/<key>-app/` 目录无关，别混。
+
+> **本文件读法**：先读「模型一页纸」对齐五件事，再读末尾「红线」避免踩坑；中间章节是按需的——布线时读「布线新链路」，写发起方时读「交换请求 / 发起方实现」，调不通时直接看「排错决策树」。每节都不长，且彼此独立。
+
+## 模型一页纸（动手前先对齐这五件事）
+
+放行 = **同时**满足：
+
+1. A→B 授权关系存在（`app_exchange_grants`）；
+2. B `allowExchange = true`；
+3. A ∈ B 的 `exchangeWhitelist`；
+4. 用户已同意"A 代表我访问 B"（`exchange_consents`，服务端交换不带会话，consent 必须**事先**记录）；
+5. 结果 scope = A 当前 TDT scopes ∩ B 声明 scopes——**发起方 A 的清单必须把 B 命名空间 scope 声明进自己的 `scopes`**（且 B ∈ A 的 `exchangeTargets`），交集为空 = 换到的令牌调 B 全 403。
+
+被调方 B 看到的：`kind:"user"`、有 `user_id`、`azp` = A（出处归因）；B 照常四道闸鉴权、**无需改代码**。
+
+## 交换请求
+
+```
+POST {PORTAL}/oauth/token
+  grant_type    = urn:ietf:params:oauth:grant-type:token-exchange
+  subject_token = <A 的当前入站 TDT>
+  audience      = <B 的 appKey>
+  client_id     = <A 的 appKey>        # 必须等于 subject_token.aud
+  client_secret = <A 的 App Secret>
+→ { access_token: <aud=B 的 TDT>, scope, expires_in }
+```
+
+产物是**用户态** TDT（有 `user_id`），且带 `azp = A`（发起方，B 侧自省可见，用于出处归因）。A 的 `allowedGrants` 须含 `token_exchange`，否则 `GRANT_NOT_ALLOWED`。
+
+## Consent 面
+
+- 用户授权页（门户前端路由）：`/exchange-consent?source=<A>&target=<B>&return=<回跳>`。
+- 配套接口：
+  - `GET /api/me/exchange-consent/:source/:target`（谁在申请 / scope / 是否已授权 / 结构上是否允许）
+  - `POST /api/me/exchange-consents`（记录）
+  - `GET /api/me/exchange-consents`（列出）
+  - `POST /api/me/exchange-consents/:source/:target/revoke`（撤销）
+- **共授**：A 声明了 `exchangeTargets` 时，用户首次进入 A 的 consent 门会一并记录对这些目标的交换同意——正常新用户不需要单独走授权页。
+- **撤销语义**：撤销交换 consent 不回滚已签发的短期 TDT（自然过期），但拦截后续交换——"撤销后还能用几分钟"不是 bug。
+
+## 布线新链路（A 读 B）
+
+完整 4 步：
+
+1. A 的清单：`exchangeTargets` += `B`，`scopes` += 所需 `B 命名空间.*`；
+2. 门户 monorepo：`apps/api/src/db/provisioning.ts` 的 `EXCHANGE_WIRING` 加 `A: [..., "B"]`（生产幂等建 grant + B 开 allowExchange + 白名单）；dev 安装期 `wireExchangeTargets` / 外部 App 的 register-app 同效；
+3. 用户 consent 靠共授覆盖；**布线晚于用户首次 consent** 的存量用户会缺 `exchange_consents` 行——见排错决策树；
+4. B 侧无需改代码——照常四道闸（scope 交集 + azp 归因）。
+
+## 发起方实现要点
+
+参考实现（门户 monorepo）：`apps/files-server/src/lib/exchange.ts`（files→omni-parser）、`apps/library-server`（多目标 → files/exam/lms）。
+
+- 换到的令牌按 **(目标 appKey, user)** 缓存、到期前复用；缓存 key 必须含目标 appKey（曾有"换票缓存串 App"的真实 bug，现象是「有时 403、有时又通」）。
+- 交换失败**优雅降级**为可区分状态（`not_installed` / `unreachable` / `needs_consent`）：别把「目标没装」渲染成传输错误、别把 consent 缺失静默吞成空列表。**交换结果本身就是可用性探测信号**。
+- 想要更多 scope，改**声明**（A 的 scopes/exchangeTargets + 用户再同意），不是在交换请求里多要。
+
+## 排错决策树
+
+| 症状 | 病根 | 处置 |
+| --- | --- | --- |
+| `EXCHANGE_NOT_ALLOWED` | 缺 grant / B 未开 `allowExchange` / A 不在白名单 | 查布线步 1–2；dev 重跑 `register-app` / 重装 |
+| `EXCHANGE_CONSENT_REQUIRED` | 该用户没有 A→B consent 行 | 引导走 `/exchange-consent`；存量用户多半是布线晚于 consent——查 `exchange_consents` 按 `(user, source, target)` 缺行则参照同租户正常用户的行补插 |
+| 跨应用下拉/列表静默为空 | 同上（发起方吞了 consent 错误） | 先查 consent 行，再查 scope 交集 |
+| `SECRET_INVALID` / 「跨应用授权缺失或未开启」但布线在 | **App Secret 漂移**：A 侧 env 的 secret ≠ 门户 `app_secrets` 哈希 | A 侧 secret 求 sha256 与门户 DB 哈希比对；A 的运行环境漏配 `*_APP_SECRET` 是常见形态 |
+| `GRANT_NOT_ALLOWED` | A 的 `allowedGrants` 未含 `token_exchange` | 改 A 清单/注册 |
+| 换到令牌但调 B 全 403 `INSUFFICIENT_SCOPE` | 交集为空：A 未声明 B 命名空间 scope，或 A 入站 TDT 本身没带 | 查 A 清单 scopes + 入站令牌 scopes |
+| 更宽 scope mint 触发 `CONSENT_REQUIRED` | 同意被子集 mint **收窄**过（mint 把本次 scope 记为同意范围） | 先重新走 consent 再宽 mint；日常 mint 别传裁剪 scopes |
+
+## 与服务态直调的边界
+
+`client_credentials`（服务账号签服务态 TDT，无用户上下文）不走本链路——那是"服务调服务"的姿势，consent / 白名单 / 交集都不适用，靠服务账号的 scope 与租户策略收口。判别：请求是否代表**某个用户**？是 → 令牌交换；否 → 服务态直调（见 portal-external-app / portal-backend-app skill）。
+
+**写入时这条判别的实用形式是「这份数据归谁」**（两种姿态在目标 App 里落进不同的容器、有不同的可见性，选错了功能会当场消失）：
+
+| 归属 | 姿态 | 后果 |
+| --- | --- | --- |
+| **归用户**：用户主动存的、他在目标 App 里看得见删得掉、算他的配额 | 令牌交换（用户态） | 落用户自己的容器；令牌带 `azp=A`，目标侧照样有来源归因 |
+| **归 App**：系统产物、用户删不得、随 A 的生命周期消失 | 服务账号（服务态） | 落 A 的应用级容器，默认只有租户管理员可见 |
+
+典型误判：把「用户点一下另存到我的空间」做成服务态——写进去的是 A 的应用容器，用户在目标 App 里根本看不见自己刚存的东西，功能等于没有。
+
+## 红线
+
+- 撤销交换 consent 不回滚已签发的短期 TDT（自然过期），但拦后续交换——"撤销后还能用几分钟"不是 bug。
+- 交换永不扩权：要更多 scope，改**声明**（A 的 scopes/exchangeTargets + 用户再同意），不是在交换请求里多要。
+- 服务态令牌（`client_credentials`）不走本链路——判别标准见上节。**写入时务必先回答「这份数据归谁」**，否则功能会"看上去上线了"但用户根本找不到。
+- **别拿另一个 App 的清单当平台规则**：它只声明了读，往往是它自己的写面不代表用户，而不是平台禁止。规则只有模型一页纸那五条。

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

@@ -0,0 +1,56 @@
+---
+name: portal-backend-app
+description: '在本 monorepo 内新增或修改「独立后端 App」（apps/*-server + apps/*-app 双包模式，如 spms/qbank/lms/llm-gateway/exam/library）。凡任务涉及新建一个后端服务、TDT 自省/四道闸/服务账号、App 的 scope 与 ACL 声明、LISTING_DEFS/seed 布线、给某 *-server 加 API 端点、DB 迁移或字典表、应用配置 tab、部署接线（Caddy/compose/DEPLOYABLE_APP_SERVICES）时，务必先用本 skill——即使用户只说"给 XX 应用加个接口"。Use when creating or extending a standalone-backend app inside this monorepo: gate/introspection, service accounts, listing/seed wiring, migrations, admin config tabs, deploy wiring.'
+---
+
+# portal-backend-app · monorepo 独立后端 App 开发
+
+独立后端 = 自己的进程 + 自己的 DB，消费 Portal 签发的 TDT。本文件是操作序与红线；具体契约按需读 `references/`（为本 skill 提炼的自包含参考；权威源是门户仓库 `docs/`，冲突以门户仓库为准）。本 skill 描述**门户 monorepo 内**的双包模式——服务端在别的 repo 时改用 portal-external-app skill。
+
+## 按任务读参考
+
+| 任务 | 读 |
+| --- | --- |
+| 自省契约 / 四道闸 / 服务账号 / client_credentials / 撤销 | [references/gate-and-tokens.md](references/gate-and-tokens.md) |
+| 注册布线 / scope 目录 / 部署接线 / API 规范 / 用量上报 / 配置 tab | [references/wiring-and-conventions.md](references/wiring-and-conventions.md) |
+
+参考实现：`apps/spms-server/src/lib/gate.ts` + `identity.ts`（各 server 同构的鉴权层）。
+
+## 新建一个后端 App 的全链 checklist
+
+按序做完，每步有既有样板可抄（轻业务抄 `todo-server`、重业务抄 `lms-server`）：
+
+1. **双包**：`apps/<key>-server`（Bun + Elysia，dev 端口取空闲 4xxx）+ `apps/<key>-app`（前端见 portal-micro-app skill）。DB 命名 `xgent-<key>`。
+2. **鉴权层**：整抄 `spms-server/src/lib/gate.ts` + `identity.ts`，改 listingKey/scope 常量。不要手写自省逻辑。
+3. **清单与布线**（位置与规则见 wiring-and-conventions.md §1）：ACL Manifest → `manifests.ts`；listing → `LISTING_DEFS`；服务账号 → `SA_DEFS`；交换 → `EXCHANGE_WIRING`；scope 只能落自己命名空间。
+4. **种子**：App 自己的 seed/bootstrap 写成**非破坏性**独立脚本（`db:seed` 是 portal-only + 破坏性）。
+5. **dev:all**：server+app 挂进根 `package.json` 的 concurrently；绝不叠跑单个 dev 脚本。
+6. **部署接线**一次做全（Caddy 白名单 / compose profile / `DEPLOYABLE_APP_SERVICES` / **Dockerfile COPY 新 workspace** / `build:apps` 串行）——逐项症状见 wiring-and-conventions.md §2，漏一个生产就 404/起不来。
+7. **验证脚本**：`apps/<key>-server/scripts/verify-*.ts` 覆盖 TDT/隔离/ACL/核心业务，挂进 `apps/api/scripts/verify-all.ts`。没有 verify 脚本的功能不算交付。
+
+## 四道闸（每个受保护端点必过）
+
+自省 `POST /api/tokens/introspect`（服务账号 Basic）后：① `(claims.listingKey ?? claims.aud) === 本服务 listingKey`；② 所需 scope ∈ `claims.scopes`；③ 结构性管理操作看 `claims.role === "admin"`；④ 细粒度 `bypass || permissions 命中 PID`（数据范围取最宽）。
+
+如端点是**平台级跨租户**操作，在四道闸之外另加 `claims.isPlatformAdmin === true`：该值是 Portal 按 `user_id` 在每次自省时实时计算的全局身份，不在 JWT 里。`role` / `bypass` 只代表 TDT 当前租户，不能代替这道闸；也不接受前端 header/字段自报。
+
+写错就是全量 401 的硬形状：
+
+- 自省响应走统一信封，**声明在 `data` 里**：`claims = body.data ?? body`；
+- `active:false` 是**成功**的自省（令牌无效），不是传输错误；结果缓存 ≤60s；
+- 服务态 TDT（`kind:"service"`，无 `user_id`）**只按 scope 授权**，勿走 PID 门；
+- `active:true` 的自省结果始终带布尔 `isPlatformAdmin`；服务态恒为 `false`，身份变更传导受下游 ≤60s 缓存上限约束；
+- 租户隔离一律 `claims.tenant_id`，永不信任请求体；限流自建 `(aud, tenant)` 每分钟窗口。
+
+完整字段与服务账号细节见 [references/gate-and-tokens.md](references/gate-and-tokens.md)。
+
+## API 与数据规范（评审必查，细则见 wiring-and-conventions.md §3）
+
+- 业务状态不走 HTTP 状态码：一律 `200 + {ok, data|error}`；数据不存在 = `200 + data:null` 不是 404。
+- 列表端点服务端分页（`Page<T>`）；字典表统一 `sort`（树/兄弟次序保留 `seq`）。
+- 迁移**手写 SQL**（drizzle-kit generate 本仓已知损坏）。
+- 审计写 `POST /api/v1/audit`，不自建审计；租户配置走应用配置 tab 三件套（wiring-and-conventions.md §5）；不做「同步通讯录」；计量走用量上报（wiring-and-conventions.md §4）。
+
+## 验证
+
+改动完成 = 该 server 的 `verify-*.ts` 全绿 + `bun run verify:all` 不回归 + （有 UI 面时）浏览器走通。dev 要点：自省优先服务账号 Basic（`x-resource-key` 仅 `DEV_MOCK_OAUTH=true` 且只认 `FILES_RESOURCE_KEY` 一把）；后端脚本登录用无 2FA 用户（如 `liming`）。

package/skills/portal-backend-app/references/gate-and-tokens.md

@@ -0,0 +1,93 @@
+# 自省、四道闸与服务账号（资源服务器契约）
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §7/§9/§12（2026-08），响应形状对照 `apps/api/src/modules/token/index.ts` 实现核实。冲突时以门户仓库为准。
+
+## 1. 令牌自省（introspection）
+
+你的服务**不验 JWT 签名**（HS256 密钥只在 Portal），把 bearer TDT 发给自省端点换已解析声明：
+
+```
+POST {PORTAL}/api/tokens/introspect
+  Authorization: Basic base64(<saClientId>:<saSecret>)   # 服务账号凭证
+  body: { "token": "<待验证的 TDT>" }
+→ 200 { "ok": true, "data": {
+    "active": true, "kind": "user"|"service",
+    "aud": "<安装态 appKey>", "listingKey": "<稳定身份>", "azp": "<代表行事的来源App>"|null,
+    "tenant_id": "...", "user_id": "..."|null, "scopes": [...], "role": "admin"|"user"|null,
+    "isPlatformAdmin": true,
+    "bypass": false, "groups": [...]|null, "permissions": [{ "pid", "scope" }]|null,
+    "aclStamp": "..."|null, "exp": 1730003600
+  } }
+```
+
+硬规则：
+- **信封解包**：声明在 `data` 里，必须 `claims = body.data ?? body`。裸读顶层 `active` 会把一切有效 TDT 误判 401（真实事故）。
+- 无效/已撤销 TDT 也是**成功**的自省，只是 `active:false`——不要当传输错误。
+- `active:true` 始终返回布尔 `isPlatformAdmin`：Portal 每次自省都按 `user_id` 实时检查其是否为**平台租户的 active admin**，与当前 `tenant_id` / `role` / `bypass` 独立；服务态恒为 `false`。该字段是**自省派生信息，不在 TDT JWT claims 里**。
+- 结果缓存到 `exp` 前（上限 60s）；因此吊销和平台管理员身份变更可能有秒级延迟。
+- dev 通道 `x-resource-key` 仅 `DEV_MOCK_OAUTH=true` 时生效且只认门户侧 `FILES_RESOURCE_KEY` 一把；生产一律拒绝，必须走 Basic。
+
+## 2. 四道闸（每个受保护端点）
+
+1. **身份**：`(claims.listingKey ?? claims.aud) === 你的 listingKey`。按 **listingKey**（稳定身份）鉴权而非裸 aud——aud 是安装态 appKey。不匹配 → 401 `INVALID_TOKEN`。
+2. **scope**：所需 scope ∈ `claims.scopes` → 否则 403 `INSUFFICIENT_SCOPE`。
+3. **结构性管理操作**：`claims.role === "admin"`（角色来自 Portal 成员关系，非 TDT claim）→ 否则 403。
+4. **细粒度 ACL**：`claims.bypass || permissions 命中目标 PID`；数据范围取命中授予里**最宽**的（`own`<`team`<`all`）做行级过滤 → 否则 403 `INSUFFICIENT_PERMISSION`。
+
+外加两条恒规则：**租户隔离**一律按 `claims.tenant_id` 收口（永不信任请求体）；**限流**自建 `(aud, tenant)` 每分钟固定窗口。
+
+**平台级跨租户端点另加一道全局闸**：只认服务端自省的 `claims.isPlatformAdmin === true`。不能用 `role === "admin"` / `bypass` 代替（它们只表示 TDT 当前租户），也不能靠 `tenant_id === PLATFORM_TENANT_ID` 推导（平台管理员切到普通租户后仍有全局身份）。拒绝浏览器转发的 Cookie、`X-Is-Platform-Admin` 或 body 字段。
+
+`can(claims, pid)` 实现：`bypass || permissions.some(p => pidMatches(p.pid, pid))`；PID 通配 `app:*` ⊃ `app:page:*` ⊃ `app:page:x.*` ⊃ 精确。批量检查可用 `POST /api/v1/acl/check { token, pids[] }`（同服务账号鉴权）。
+
+## 3. 服务态令牌的授权姿势
+
+`kind:"service"`（client_credentials 签发）**无 `user_id`、整体绕过用户 ACL**：自省返回 `permissions` 空、`bypass=false`、`isPlatformAdmin=false`。对服务态调用**只按 scope 授权**，勿走 PID 门；涉及"用户拥有"的写操作应拒绝服务态。
+
+三种令牌来路对照：
+
+| 来路 | kind | user_id | 授权依据 |
+| --- | --- | --- | --- |
+| 自己前端（宿主注入 / callService） | user | 有 | scope + PID/ACL |
+| 其他 App 令牌交换 | user | 有 | 同上；scope 是交集；`azp`=发起方（出处归因） |
+| 服务账号 client_credentials | service | 无 | 只按 scope |
+
+## 4. 服务账号（M2M）
+
+平台管理员在控制台创建（`/api/console/service-accounts`），`clientId:secret` 走 HTTP Basic。能力：
+
+| capability | 含义 |
+| --- | --- |
+| `token.introspect` | 可调自省/批量检查——独立后端必需 |
+| `client_credentials` | 可自助签发服务态 TDT（受租户策略约束） |
+
+租户访问策略（针对 client_credentials）：`tenantAccess="all"`（任意租户，高风险）或 `"allowlist"`（仅名单内，否则 `TENANT_NOT_ALLOWED`）。新增该能力必须显式选策略，否则 `VALIDATION_FAILED`。
+
+签发服务态 TDT：
+
+```
+POST /api/tokens/service
+  Authorization: Basic base64(<clientId>:<secret>)
+  body: { "grant_type": "client_credentials", "tenant_id": "...", "scope?": "a b c" }
+→ 200 { access_token, token_type:"Bearer", expires_in, scope }
+```
+
+签发 scope = 请求 ∩ 服务账号 scopes（绝不扩张，SA 未授权时**不报错只返空 scope**——调用方必须检查返回的 scope 再用）。
+
+## 5. 宿主代理与管理直连
+
+- `sdk.callService` 只是转发便利层：你的后端仍必须完整四道闸，不要只因请求来自 Portal web 源就信任。
+- **管理控制面直连**（应用配置 tab 用）：门户为管理员铸短时 admin-TDT（`GET /api/admin/apps/:appKey/<svc>-token`，assertAdmin + signTdt，aud=appKey、按需 scope、600s），浏览器直连你的后端读写配置，Portal 不经手敏感配置。参照 files-token / llm-gateway-token。
+
+## 6. TDT 撤销（四把钥匙）
+
+网关每次校验比对四个版本维度，任一 bump 旧令牌立即失效：
+
+| 维度 | 触发 | 影响面 |
+| --- | --- | --- |
+| jti 黑名单 | `POST /oauth/revoke` | 单个 TDT |
+| app version | 应用停用/卸载、Secret 轮换/吊销 | 该应用全部 TDT |
+| user version | 管理员停用/移除用户 | 该用户全部应用 TDT |
+| (user,app) version | 用户撤销该应用授权 | 该用户对该应用的 TDT |
+
+你的自省缓存 ≤60s，所以吊销传导有秒级延迟——安全敏感操作可缩短缓存或直查。

package/skills/portal-backend-app/references/wiring-and-conventions.md

@@ -0,0 +1,71 @@
+# 注册布线、部署接线与平台规范（monorepo 后端 App）
+
+> 提炼自门户仓库 `docs/SSO与App开发指引.md` §3/§4/§7.5/附录 A、`docs/用量统计服务接入指引.md`、CLAUDE.md 及历史事故（2026-07）。冲突时以门户仓库为准。
+
+## 1. 注册链（单一事实源在代码）
+
+```
+①代码注册表                    ②市场清单                  ③安装快照         ④运行时
+acl/manifests.ts + LISTING_DEFS ─seed─► marketplace_listings ─install─► apps 行 ─► SDK init.acl / introspection
+```
+
+| 声明什么 | 写在哪 |
+| --- | --- |
+| ACL Manifest | `apps/api/src/modules/acl/manifests.ts`（按 listingKey 集中定义） |
+| listing（scopes/navItems/exchangeTargets/serviceBaseUrl/依赖…） | `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS` |
+| 服务账号 | 同文件 `SA_DEFS`；约定 `clientId = <key>-server`，capability `token.introspect` |
+| 跨应用交换 | 同文件 `EXCHANGE_WIRING`（`{ 发起方: [目标...] }`） |
+| 内容类型（如用内容服务） | `apps/api/src/modules/content/schemas.ts`，owner=listingKey |
+
+升级 Manifest = 改 `manifests.ts` 的 version+内容 → 重新 seed/发布清单 → 租户同步更新。`db:seed` 是 portal-only + **破坏性**（重生成 UUID、会话失效）；App 自己的种子写成独立**非破坏性**脚本。
+
+**scope 命名空间**（写时校验 `market/service.ts::validateScopes`）：一条清单只能声明 平台基础 scope ∪ 自己命名空间（`<listingKey>.` 前缀，连字符 key 接受下划线变体如 `llm_gateway.*`）∪ 已声明 `exchangeTargets` 的目标命名空间。App 命名空间 scope 随清单入库，**无需**改 `packages/shared/src/scopes.ts`；配 `scopeLabels` 三语文案。
+
+平台基础 scope 速查：`userinfo.read`、`directory.read`（+`directory.email.read` 含邮箱）、`notification.send`（+`.others` 跨用户）、`inbox.read`、`settings.read/write`、`widget.write`、`audit.write`、`scheduler.read/write`、`content.read/write`。
+
+## 2. 部署接线 checklist（新建 App 漏一项生产就出事）
+
+| 接线 | 位置 | 漏掉的症状 |
+| --- | --- | --- |
+| `/svc/<key>` 白名单 | `deploy/caddy/Caddyfile` | 生产 404（网关白名单 map 收口，未注册=路由不可达） |
+| **Caddy 全局配置两条不可逆** | 两份 Caddyfile 的 `admin localhost:2019` 不许改回 `admin off`；`ProcessDriver.reloadRouting` 必须是 `systemctl reload`（不是 `restart`），且与 `deploy.sh` 的 sudoers 授权**逐字一致** | 关 admin ⇒ 三个 flavor 的热重载全部**静默**失效（只剩一行 warn）；改回 restart ⇒ 请求处理器拆掉自己正在应答的那条连接，调用方在数据已落库之后拿到 GOAWAY + 无响应体（2026-08-19 事故）。门是 `verify-caddy-dynamic` |
+| compose profile | `deploy/docker-compose.yml` 加 `app-<key>`（同 runtime 镜像 + `command: bun --filter @xgent/<key>-server`） | 容器起不来 |
+| 按需部署注册表 | `apps/api/src/modules/deploy/registry.ts` 的 `DEPLOYABLE_APP_SERVICES` | 生产卡「服务正在部署」门 |
+| **Dockerfile COPY 新 workspace** | 根 `Dockerfile` | 本地全绿、镜像构建才炸（真实事故） |
+| 前端构建 | `build:apps` 保持**串行**（并行 OOM） | CI/构建机 OOM |
+| dev:all | 根 `package.json` concurrently 挂 server+app | 本地起不齐 |
+
+容器/生产统一监听 8080（本地 dev 各用自己的 4xxx）；反代通用规则 `/svc/<key>/* → <key>-server:8080`。宿主运行时按 listing `serviceBaseUrl` 解析服务地址（无烘焙注册表），新增后端无需重建门户前端。
+
+## 3. API 与数据规范（评审必查）
+
+- **HTTP 状态码只反映传输/路由层**：业务成功/失败一律 `200 + {ok, data|error}`；不用 201/204；数据不存在 = `200 + data:null` 不是 404；4xx/5xx 只留参数结构错/未登录/未授权/真故障。
+- **列表服务端分页**：复用 `Page<T>` 契约与现有 helpers（所有 admin/console 列表页同款）。
+- **字典表**（租户级可维护枚举/分类）：排序列固定 `sort integer NOT NULL DEFAULT 0`，查询 `orderBy(asc(sort), asc(name))`，创建 `sort: body.sort ?? 0`、更新 `if (body.sort !== undefined)`。**例外**：树/兄弟次序（章节树、子母题）保留 `seq`，语义是序号不是字典排序。
+- **迁移手写**：`drizzle-kit generate` 在本仓已知损坏——迁移 SQL 手写进 server 的 migrations 目录。
+- **审计**：不自建审计表/页，`POST /api/v1/audit`（scope `audit.write`，用当次用户 TDT），best-effort 不阻断业务。
+- **不做「同步通讯录」**：成员一律 `@xgent/portal-ui` 的 `UserPicker` curated 按需挑选。
+
+## 4. 用量上报（如需计量/计费）
+
+心智模型：**日桶（UTC 日切）+ 桶内绝对值幂等覆写**。上报的是整桶重算的绝对值不是增量（重试/补报天然幂等）；唯一键 `(tenantId, metricKey, day, dimsKey)`。
+
+1. **登记指标**：`packages/shared/src/usage.ts` 的 `USAGE_METRICS`（key 前缀必须=你的 listingKey；kind 选对：counter=流量求和 / gauge=水位取峰值，选错聚合口径灾难；dims 白名单防高基数——别放 userId/requestId）。这是**仓内 App** 的路径；manifest 注册的外部 App 改在自己 manifest 的 `usageMetrics` 里声明（治理档，见 portal-external-app skill），运行时注册表 = 内置 ∪ listing 声明。
+2. **服务账号三件套**：capabilities += `client_credentials`、scopes += `usage.report`、`ownerAppKey` = listingKey（`SA_DEFS` 加 `usageReporter: { ownerAppKey }`，`ensureServiceAccount` 幂等补齐）。`metricKey` 前缀必须等于令牌 `azp`——别的 SA 报你的指标整批拒收。
+3. **上报**：按租户铸服务态令牌（**检查返回 scope 含 `usage.report`**——SA 未授权时不报错只返空 scope，应视为可重试失败；`APP_NOT_INSTALLED`/`APP_DISABLED`/`TENANT_NOT_ALLOWED` 才是该租户永久跳过）→ `POST /api/v1/usage/report { records:[{tenantId, metricKey, day, dims?, value}] }`，单批 ≤500、all-or-nothing、`rejected` 非空响亮 log。
+4. 参考实现：counter+水位线 `apps/llm-gateway-server/src/lib/usage-report.ts`；gauge+快照 files。
+
+## 5. 应用配置 tab（租户级配置三件套）
+
+不在微应用里自建「设置」页；配置收口平台应用配置页：
+
+1. server 暴露 `GET/PUT /api/v1/settings`（四道闸，写操作落 ACL action）；
+2. `apps/api/src/modules/apps/index.ts` 加 `GET /api/admin/apps/:appKey/<key>-token`（assertAdmin，signTdt 铸 aud=appKey、按需 scope 的 600s admin-TDT，无 consent 门）；
+3. `apps/web/src/lib/<key>-config-api.ts` + `AppForm.tsx` 按 `form.scopes.includes("<key>.…")` 条件挂 Section（参照 `showStorage`/`showGateway`），浏览器直连你的后端。
+
+## 6. 本地 dev 要点
+
+- 一把起齐 `bun run dev:all`；绝不叠跑单个 dev 脚本（Vite 端口自增会抢相邻 App 端口，iframe 加载错应用）。重起先清干净旧监听。
+- 非生产下部署门自动视作 ready，本地不会卡「服务正在部署」。
+- 种子账号均 `@xgent.ai`：`rockie`（晨光 admin + 平台管理员）、`liming`（晨光 user/星网 admin，**无 2FA，脚本登录用它**）、`chenjing`（admin，开了 2FA）。
+- 验证脚本放 `apps/<key>-server/scripts/verify-*.ts` 并挂进 `apps/api/scripts/verify-all.ts`；交付标准 = 本服务 verify 全绿 + `bun run verify:all` 不回归。