@xgent-ai/skills 0.1.0 → 0.4.0

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

@@ -0,0 +1,315 @@
+# 注册布线与一盒（one-box）本地联调
+
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
+
+## 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?}]`，身份是 `(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`
+
+**公开面另有接入契约**：普通匿名页面走 `/apps/<key>/…` 或 `/svc/<key>/…`；
+独立域名用 `publicEntrypoints` + Sites。入口声明不会自动接管门户根路径。
+完整步骤、服务特权申请与 key 迁移见 [public-entrypoints.md](public-entrypoints.md)。
+
+```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` 建全
+（清单、服务账号与已装租户对齐，后端部署和网关交付随后独立核验）。App 团队无需修改门户源码；平台配置由管理员管理。**生产没有 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 **不回仓库查**，沿用 latest 先 `onebox.sh pull` 更新缓存，再 `upgrade` → `up` 同步资产。
+要钉住某一版就写 `: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`）。
+
+已有一盒不要重跑 `init --force` 来升级。使用已安装 `portal-dev-setup` skill 的脚本：
+
+```bash
+S="<portal-dev-setup 的 SKILL.md 所在目录>/scripts/onebox.sh"
+"$S" upgrade --image <registry>/<项目>/one-box:v<版本>-<sha>
+"$S" up
+```
+
+初始化是 `init` → `up`；升级是 `upgrade` → `up`；主动删数据重置才是 `dc down -v` → `init --force` → `up`。
+升级保留 `compose.env`、`generated/`、`backup/`、端口、密钥和卷，只追加变更的镜像/版本行，
+不重生成配置。两个目标镜像都已缓存时支持离线升级；沿用 latest 先 `pull`，再 `upgrade` → `up`。
+`up` 仍重种门户库（租户/用户/清单/安装），不会重种 App 自己的数据库。
+数据库启动前按现有 PG_VERSION 保留大版本和挂载布局；未知/冲突布局拒绝启动，不能用删卷来解决。
+门户升级不执行 PostgreSQL 大版本迁移，后者需要单独备份与维护窗口。
+
+对象存储是 RustFS，原 `MINIO_*` 与 `minio:9000` 地址继续使用。`up`/`add`/建桶都先通过迁移门，
+旧 MinIO 卷复制到新卷并核对后才提交；原卷及 `backup/` 的镜像归档、清单、回退入口保留。
+提交后新卷是权威；有新写入时回退入口会隔离 RustFS 并拒绝切回旧卷，需在副本上人工验证后恢复，
+不能通过删新卷或 `down -v` 处理升级失败。完整恢复步骤见 `portal-dev-setup` §6。
+
+### 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 起栈之前：躲开本机已占的端口与项目名
+
+一盒发布 reverse-proxy 80/443 → `HTTP_PORT`/`HTTPS_PORT`、postgres 5432 →
+`POSTGRES_PORT`、redis 6379 → `REDIS_PORT`、RustFS 9000/9001 → `MINIO_PORT`/`MINIO_CONSOLE_PORT`，
+以及 Kafka HOST → `KAFKA_PORT`（自动避让 9092/19092/29092）、EXTERNAL → `KAFKA_EXTERNAL_PORT`（默认回环 9095，不自动避让）；
+其余（portal-api 的 3000、各 `<key>-server` 的 8080、你的 app-backend 的 8080）只 `expose`，不占宿主。
+撞了就在 `compose.env` 里改这几个；改的只是发布口，一盒内部一律走 compose 网络的
+`postgres:5432` / `redis:6379` / `minio:9000`（RustFS 的兼容别名）。控制台路径为 `/rustfs/console/`。改了 `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 rustfs
+#    存量一盒先按下面的升级路径处理；不要直接起 rustfs。
+# 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`。
+
+### 4.4 Kafka 接入
+
+以 `listingKey: "order-worker"` 为例，清单包含：
+
+```json
+{
+  "requiredServices": [{ "kind": "kafka", "name": "main" }],
+  "requiredEnv": [
+    "ORDER_WORKER_KAFKA_BROKERS", "ORDER_WORKER_KAFKA_USERNAME",
+    "ORDER_WORKER_KAFKA_PASSWORD", "ORDER_WORKER_KAFKA_SASL_MECHANISM",
+    "ORDER_WORKER_KAFKA_TOPIC_PREFIX"
+  ]
+}
+```
+
+用新版 `portal-dev-setup/scripts/onebox.sh add order-worker --manifest ./app.manifest.json --image <镜像>`。
+`add` 会创建 `app_order_worker`，SCRAM-SHA-512 / 8192 次迭代，写入五键；重复执行沿用本地密码。
+容器连接 `kafka:9092`，宿主客户端改用 `127.0.0.1:<KAFKA_PORT>`，机制为 SCRAM-SHA-512、协议为
+SASL_PLAINTEXT。密码写入只显示 `***`；供给失败只告警，检查 Kafka 日志后重跑原命令。
+
+主题、消费组、事务 ID 都以 `app.order-worker.` 开头，保留 listingKey 的连字符。平台关闭自动建主题，
+App 必须显式创建、副本数 1；主题授权 CREATE / DELETE / DESCRIBE / DESCRIBE_CONFIGS / READ / WRITE，
+消费组 READ / DESCRIBE / DELETE，事务 ID WRITE / DESCRIBE，全部 PREFIXED。没有 ALTER / ALTER_CONFIGS：
+不能改保留期或增加分区，保留策略由平台决定。前缀外主题、消费组与事务 ID 不可访问。
+
+Kafka 是单节点、at-least-once，重启会短暂不可用；App 做重连、去重及处理成功后提交 offset，不能把
+Kafka 当权威业务记录系统。权限按 App 隔离，App 自行实现租户数据隔离。SASL_PLAINTEXT 不加密消息，
+外部口保持回环，跨 VM 开放交给运维配置广告地址与限来源安全组。
+
+不要把 `KAFKA_ADMIN_PASSWORD` 写入 App 的 `requiredEnv`。一盒仍将整份 `compose.env` 注入容器，
+只适合可信团队本地联调，不承诺容器间秘密隔离。客户端配置与手工修复命令随 `portal-dev-setup` 的
+`references/kafka.md` 交付，也见门户《平台 Kafka 接入指引》。
+
+## 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);
+}

package/skills/portal-logging/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: portal-logging
+description: '把一个 App 的日志/遥测接进门户的「日志与监控」服务：采集器布线（容器 stdout / 文件 tail / 应用内直打）、写入身份（服务账号换令牌 或 长期访问密钥）、`observability.ingest` scope、`/svc/observability/v1/ingest/…` 写入面、`app_你的key_流名` 的流命名与跨 App 统一的日志字段口径。凡任务涉及「让我的服务的日志能在日志与监控里看到」「接采集器 / fluent-bit / docker 日志驱动」「日志写入 401 / 403 / scope 为空」「写进去了但界面查不到 / stream not found」「一次报错被拆成几十条 / 分不出哪条是错误」时，务必先用本 skill 再动手——即使用户只说「把日志接上」。Use when wiring an app''s logs or telemetry into the portal observability service: collector setup, ingest credentials and scope, stream naming, log field conventions, and the classic failures (empty scope, 403 on write, 401 on query, records that never show up).'
+---
+
+# portal-logging · 把 App 的日志接进「日志与监控」
+
+一条链路四段，**两种身份**：
+
+```
+你的进程  →  采集器  →  POST /svc/observability/v1/ingest/<stream>  →  在「日志与监控」App 里看
+（产生）     （搬运）    ↑ 服务身份（机器的钥匙）                        ↑ 用户身份（人的票）
+```
+
+两种身份不能互换，这是整条链路最常见的困惑来源：**采集器只能写、不能查；人只能查、不能写**。拿服务密钥去查会得到 401，那不是配置错。
+
+> **路径约定**：本 skill 里的 `apps/…` `deploy/…` `docs/…` 都在**门户仓**。在你自己的 App repo 里它们不存在——它们标注的是「门户侧的事实在哪」，不是让你去打开的文件。你需要的一切在本 skill 的 `references/` 与 `scripts/`（自包含，路径相对于本 `SKILL.md` 所在目录）。运行脚本前，在 App repo 根目录按实际加载位置设置 `SKILL_DIR="<本 SKILL.md 所在目录>"`。
+
+## 按任务读
+
+| 任务 | 读 |
+| --- | --- |
+| 配采集器（容器 stdout / 文件 tail / 应用内直打），含多行合并与级别判定 | [references/collectors.md](references/collectors.md) |
+| 端点、凭据、请求/响应形状、查询 API、错误码矩阵、计量 | [references/contract.md](references/contract.md) |
+| 只想先打通一条，验证链路是活的 | `"$SKILL_DIR/scripts/smoke-ingest.sh"`（改环境变量直接跑） |
+
+## 0. 先判断：你要接的真的是「日志」吗
+
+日志流是**给人排障看的时间序列文本**。下面这些各有专用面，塞进日志流会同时失去两边的能力：
+
+- **审计**（谁在什么时候改了什么，要可追溯、不可篡改、要留存）→ 门户审计面（`audit.write`），不是日志。
+- **用量/计费**（要精确、要对账）→ 平台计量面。日志会被采样、会过期。
+- **给用户看的消息**（提醒、待办、通知）→ 门户通知域。
+- **指标与链路**（数值时间序列 / trace）→ 同一个服务的 OTLP 入口，形状与日志不同，见 contract.md。
+
+判据：这条记录**丢了会不会有人要赔钱或说不清责任**。会 → 不是日志。
+
+## 1. 三个前提（不成立时，每一步都会以「看起来成功」的方式失败）
+
+1. **平台把「日志与监控」登记为平台基础服务应用，且默认授予里含 `observability.ingest`。**
+   这是平台管理员在门户控制台做的一次登记。没有它：你换令牌拿到 HTTP 200、`scope` 字段却是**空的**，直到第一次写入才 403。——第一天接日志的团队九成栽在这里，先查它。
+2. **你的 App 在目标租户已安装且可用。** 令牌里的 `azp` 绑着你的 App key，签发时会检查「这个租户装没装你」。没装 ⇒ `APP_NOT_INSTALLED`。语义是对的：你没在这个租户里跑，就不该有这个租户的日志。
+3. **你有自己的服务账号凭据。** 平台部署你的服务时注入 `<PREFIX>_SA_CLIENT_ID` / `<PREFIX>_SA_CLIENT_SECRET`（`<PREFIX>` = 你的 appKey 大写、`-` 换 `_`），另有 `API_BASE_URL`（门户内部源，换令牌用）与 `PORTAL_BASE_URL`（门户公开源，`/svc/...` 用）。
+   与门户同仓的后端没有「平台注入」这一步，同名的键在部署环境的 env 文件里——**键名与用法完全一样**，下文不再分叉。
+
+**不要为日志新建一套密钥**，也**不要**把 `observability.ingest` 写进自己 manifest 的 `serviceScopes`：那是别人命名空间的 scope，写进去反而要求你把对方列进依赖；这条 scope 由平台在**签发那一刻**并进来，manifest 一个字都不用改。
+
+## 2. 选写入身份
+
+| | 短期服务态令牌 | 长期访问密钥（`xsak_` 开头） |
+| --- | --- | --- |
+| 怎么拿 | `POST {API_BASE_URL}/api/tokens/service`，HTTP Basic = `client_id:secret`，body `grant_type=client_credentials` + `tenant_id` + `scope` | 门户控制台 › 服务账号 › 访问密钥（平台管理员签；租户自助建的服务账号同理） |
+| 有效期 | 分钟级，要缓存 + 到期前续 | 可无期限 |
+| 谁用 | **你的应用代码**自己打点 | **采集器进程**（fluent-bit 这类不会自己换令牌的） |
+| 代价 | 每次要一次 HTTP | 明文长期存在盘上，泄漏面大 ⇒ 只给 `observability.ingest` 这一条 scope，别多给 |
+
+拿短期令牌时把它缓存到 `expires_in - 10s`，别每条日志换一次令牌——那是把日志量乘进了门户的负载。
+
+## 3. 写入
+
+```
+POST {PORTAL_BASE_URL}/svc/observability/v1/ingest/<stream>
+Authorization: Bearer <服务令牌 或 xsak_…>
+Content-Type: application/json
+
+[ {…记录1…}, {…记录2…} ]      ← 一次一批，别一条一个请求
+```
+
+**成功判据要看两层**：HTTP 200 **且** 响应体 `code:200` 且 `status[]` 里 `failed:0`。只看 HTTP 状态码会把「收下了但没落库」当成功——这正是「写入一直 200、界面永远查不到」的来源。
+
+⚠️ **采集器代发（形态 A/B）时你根本看不到这个响应**：采集器只在自己的日志里留一行 `HTTP status=200`，`failed>0` 那种「收下了没落库」它不会告诉你，401/403 也只是按重试上限丢掉——**采集器不报错 ≠ 接通了**。所以这两种形态的验收落在 §8 冒烟那一条 curl（那里你拿得到响应体）加上界面真的搜到；排障时再临时打开采集器的响应打印（见 collectors.md）。
+
+**流名**：你写 `<stream>`，实际落在 `app_<你的 appKey>_<stream>`——前缀由令牌里的 `azp` 决定，你写不进别人的命名空间，也**别在 `<stream>` 里再重复一遍自己的 key**（会得到 `app_foo_foo_console`）。一个 App 按用途分流即可：`console`（进程标准输出）、`access`、`job`。
+
+## 4. 字段口径（跨 App 一致，界面和排障才有共同语言）
+
+| 字段 | 必要性 | 说明 |
+| --- | --- | --- |
+| `message` | 必备 | 正文，一条一行 |
+| `level` | 强烈建议 | `info` / `warn` / `error`；**产生方给的最准**，采集器只能猜 |
+| `service` | 强烈建议 | 进程/子服务名，一个 App 有多个进程时靠它分 |
+| `host` | 建议 | 实例/主机名，多副本时靠它分 |
+| `fd` | 采集器填 | `stdout` / `stderr` |
+
+**时间**：落库的时间轴是**到达时间**，日志自带的时间只是一个普通字段。要让时间轴等于事件时间，就在记录里带上 `_timestamp`（微秒 epoch），并**先用一条冒烟记录验证**这个版本认不认——别假设。
+
+**级别**：如果你的日志是文本行、由采集器搬运，采集器只能靠 `stderr` 和关键词猜，而 `console.warn` 一类在多数运行时也走 stderr ⇒ 例行 warn 会整批被判成 error。解法是**产生方把级别写进正文**（例如正文尾部的 JSON 里 `"lvl":"error"`），采集器优先取它。判定次序与可直接抄的实现见 collectors.md。
+
+**永远不要写进日志**：令牌 / 密钥 / 密码、完整 query string（授权码与令牌常在里面）、用户个人信息与租户业务正文、大 blob。排障要的是**能定位的 ID**，不是内容本身——日志会被转发、留存、被平台管理员看到。
+
+## 5. 选采集形态
+
+| 形态 | 适合 | 代价 |
+| --- | --- | --- |
+| A 容器 stdout → 日志驱动 → 采集器 | 容器化交付、应用零改动 | 多一个采集器进程 |
+| B 采集器 tail 日志文件 | 进程管理器把 stdout 写成文件的部署 | 要处理轮转 |
+| C 应用内直接批量 POST | 想要结构化字段与精确级别、日志量小 | 自己管批量/重试/背压 |
+
+共性的四条（三种形态都适用，任一漏掉都会在生产上现形）：**批量发**、**异步发**（不许在请求热路径上同步等远端）、**失败丢弃而不是无限重试**（日志不值得拖垮主流程）、**多行合并**（一个栈是一条记录，不是四十条）。
+
+⚠️ 多行合并按 tag/流分缓冲。**多个日志源共用一个 tag 时，A 源的栈会把 B 源随后那行吸进同一条记录**——每个源（每个文件 / 每个容器 × stdout|stderr）一个 tag。
+
+配置照抄 [references/collectors.md](references/collectors.md)。
+
+## 6. 查
+
+正常路径是人打开「日志与监控」App 查（需要 `observability.read`，由租户管理员同意授权）。程序化查询要**用户身份的令牌**，服务密钥打查询面是 `401`——先确认你是不是拿错了钥匙，再怀疑数据没进去。
+
+## 7. 排错矩阵
+
+| 症状 | 多半是 | 动作 |
+| --- | --- | --- |
+| 换令牌 200，但响应里 `scope` 是空的 | 平台没登记基础服务应用 / 默认授予里没有 ingest | 找平台管理员登记，§1.1 |
+| 写入 `403` | 身份类型不对（拿用户票写）或 scope 里没有 ingest | 用服务身份；查签出来的 scope |
+| 写入 `401` | 凭证缺失 / 伪造 / 已撤销 / 已过期 | 重签；轮换过的旧密钥立刻失效 |
+| 换令牌报 `APP_NOT_INSTALLED` | 你的 App 没装在这个租户 | 这是设计，不是 bug；换租户或先装 |
+| 写入 200，但查不到 | ① 只看了 HTTP 没看 `status[]`；② 流名前缀猜错（是 `app_<key>_<stream>`）；③ 时间范围——时间轴是**到达时间** | 按序查这三条 |
+| 查询报 `stream not found` | 这个流一条都没写进去过 | 回到上一行 |
+| 查询 401、但写入 200 | 拿服务密钥查 | 换用户身份 |
+| 只看到零星几条 | 时间范围太窄；或你的进程本来就几乎不打日志 | 先确认源头有没有行 |
+| 一次报错被拆成几十条 | 采集器没配多行合并 | collectors.md |
+| 一条记录里混了两个进程的行 | 多个源共用一个 tag | 每源一个 tag |
+| 界面里只有别的 App 的流 | 你的令牌 `azp` 不是你以为的那个 | 自省一下令牌 |
+
+## 8. 冒烟验收（接完逐条走一遍，都过才算接上）
+
+1. 换出来的令牌 `scope` **确实含** `observability.ingest`（不是空）。
+2. 写一条带标记的记录，响应 HTTP 200 且 `status[]` 里 `failed:0`。
+3. 在「日志与监控」App 里按这个标记**搜到了**它，流名是 `app_<你的 key>_<stream>`。
+4. 故意打一个多行栈，界面里它是**一条**记录。
+5. 打一条 error 和一条 info，界面里级别**分得开**。
+6. 把采集器停掉再起来，不重放历史、也不丢新行。
+
+## 别做的事
+
+- 别为日志自建一套网关/存储/密钥体系——这条链路已经存在，重造的那份不会有人运维。
+- 别把审计、用量、通知塞进日志流（§0）。
+- 别在生产刷 debug 级别：写入是**计量项**（按字节），也会把有用的行淹掉。
+- 别把别的 App 的日志代写进自己的流：`azp` 决定前缀，代写要么被拒，要么污染自己的命名空间。