@xgent-ai/skills 0.3.0 → 0.4.0

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

@@ -5,17 +5,10 @@ description: '接入「外部镜像服务类应用」——服务端代码不在
 
 # portal-external-app · 外部镜像服务类应用接入
 
-外部镜像 App = 服务端在别的 repo（任意语言/栈）、独立镜像交付、**常驻**（不走按需缩零）。鉴权与业务 API 遵循门户运行时契约；**`/health` 支持平铺 JSON 与 Envelope，检测规则与平台运行时一致**。本文件是判断与流程；具体契约按需读 `references/`（为本 skill 提炼的自包含参考，可整目录拷到外部团队 repo；权威源是门户仓库 `docs/`，冲突以门户仓库为准）。
+外部镜像 App = 服务端在别的 repo（任意语言/栈）、独立镜像交付、**常驻**（不走按需缩零）。鉴权与业务 API 遵循门户运行时契约；**`/health` 支持平铺 JSON 与 Envelope，检测规则与平台运行时一致**。本文件是判断与流程；具体契约按需读 `references/`（可整目录拷到 App repo 独立使用）。
 
 
-> **路径约定（先读这条，能省一次白找）**：本 skill 里出现的 `apps/…` `packages/…` `docs/…`
-> `deploy/…` 这类路径**都在门户仓**。在 App 自己的 repo 里它们**不存在** —— 它们标注的是
-> 「门户侧要做什么」或某段内容的出处，**不是让你去打开的文件**。找不到不是配置错误：
-> 别去创建、别去全局搜、别把它当缺失依赖报出来。你需要的一切都在本 skill 的
-> `references/`（自包含）。若你正在门户仓里工作，那这些路径就是可以直接打开的真实文件。
->
-> ⚠️ 一个例外：`/apps/<key>/`（带前导斜杠）是**线上 URL 路径**——微应用产物的挂载点，
-> 与仓内的 `apps/<key>-app/` 目录无关，别混。
+`/apps/<key>/` 与 `/svc/<key>/` 是线上 URL；本文的 `references/` 和 `scripts/` 相对于本 skill 目录。
 
 ## 按任务读参考
 
@@ -24,6 +17,7 @@ description: '接入「外部镜像服务类应用」——服务端代码不在
 | 实现/评审资源服务器（四道闸、health、env、认证面划界、配置面） | [references/integration-contract.md](references/integration-contract.md) |
 | 实现 `/health`、出仓迁移、发布镜像或健康检查失败（必读） | [references/health-contract.md](references/health-contract.md)：两种正确实现、实际判据、发布前检查命令 |
 | 写 manifest、注册布线、一盒联调、排查 | [references/registration-and-onebox.md](references/registration-and-onebox.md) |
+| 匿名页、后端直出 HTML、公开站点/独立域名、旧链接或 listingKey 迁移 | [references/public-entrypoints.md](references/public-entrypoints.md)：现有 /apps、/svc、Sites 三种通路及各自责任 |
 | 为外部服务写/审对接契约文档 | [references/contract-doc-template.md](references/contract-doc-template.md) |
 | 有「每租户最多几个 X」的配额诉求（选模型、数值谁配、已用怎么来） | [references/quota-and-seats.md](references/quota-and-seats.md) |
 
@@ -53,6 +47,13 @@ description: '接入「外部镜像服务类应用」——服务端代码不在
 
 ## 资源服务器硬契约（外部实现最常炸的四处）
 
+**Bun / TypeScript 后端不自己实现第 1 条**：直接用 `@xgent/portal-server-sdk` 的 `createPortalAuthenticator`，
+信封解包、主体与凭证类型校验、缓存与故障映射都在里面；其他语言才按下面的契约自己实现。
+`@xgent/*` 从平台私有包仓安装，配法见 `xgent-app-release` skill「第 0 步」；仓里还没有
+`.xgent-registry.env` ⇒ 停下，请开发者先去门户「开发者应用」生成配置文件。**不许 vendor**：
+不把 SDK 的产物或源码拷进仓，不用 `file:` / `link:` / tar 依赖顶替。收外部团队交付时，看到
+`vendor/` 下有 `@xgent/*` 就打回。
+
 1. **自省信封解包**：门户响应必须先检查 `ok === true` 且 `data` 为对象，再校验 `data`；失败信封或缺 data 返回 503，不能回退到顶层。只有合法 `active:false` 才表示凭证失效。TDT 的 exp 必填；无过期长期 key 才可省略 exp。主体/凭证类型矩阵、ACL 范围与缓存预算见 integration-contract.md §3；
 2. **`/health` 按响应形状判定**：HTTP 非 2xx 不通过；2xx 响应顶层有 `ok` 时，必须 `ok === true && data.db === true`；没有顶层 `ok` 时按 2xx 判健康。平铺 `{"service":"my-app","db":"ok"}` 与信封 `{"ok":true,"data":{"db":true}}` 都支持，不按内建/外部 App 区分。平铺依赖故障须用 HTTP 503 表达；不要给字符串状态直接套 `ok(...)`。完整示例与同源检查脚本见 [health-contract.md](references/health-contract.md)。
 3. **门户三变量 all-or-nothing**：自省地址 + SA clientId + secret 全缺→鉴权停用 503；缺一→启动 fail-fast 打印缺失项。
@@ -60,6 +61,15 @@ description: '接入「外部镜像服务类应用」——服务端代码不在
 
 完整契约（四道闸、三种令牌来路、审计、划界）见 [references/integration-contract.md](references/integration-contract.md)。
 
+## 一盒初始化与升级
+
+首次联调用 `portal-dev-setup` 的 `onebox.sh init` → `up`；已有一盒换版本用
+`upgrade [--image <ref>]` → `up`；沿用 latest 先 `pull` 更新缓存，已加载的本地新镜像可离线升级。
+不使用 `init --force` 代替升级。升级保留配置、generated/、backup/、
+端口与卷；`up` 仍重种门户库，不重种 App 自己的库。自带对象存储为 RustFS，保留 `MINIO_*`
+配置与 `minio:9000` 网络别名；控制台路径为 `/rustfs/console/`。存量对象由切换脚本复制、核对后才切换，
+切换后有新写入时不能直接回旧卷，细节见 [registration-and-onebox.md](references/registration-and-onebox.md)。
+
 ## 注册布线（细节见 registration-and-onebox.md）
 
 - **dev / 一盒**：`bun run register-app <manifest>`（幂等，生产拒跑）= upsert listing + 直写服务账号 + 写发起方 App Secret + 写 `/svc` 白名单 map。⚠️ `exchangeInitiatorSecret` 的哈希在**首个租户**安装时还没有任何实例可布——先安装 App，**再重跑一次** register-app，否则发起交换 401（之后装的租户会随安装自动补布，见 registration-and-onebox.md §2.2）。日志里 `wired into N …` 的 N 是「**改了**几个实例」，0 也可能是「本来就对」——判据是比哈希，见 registration-and-onebox.md §2.2。
@@ -67,14 +77,11 @@ description: '接入「外部镜像服务类应用」——服务端代码不在
 - **生产（标准路径）**：清单事实源在**对方仓的 `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 声明放行（不卡编译期枚举）。
+  「发布审核」队列 ⇒ 批准后更新清单、服务账号与已装租户，后端和网关分别交付。
+  密钥一次性回显给审批人；平台运行配置由管理员维护，App 团队无需修改门户代码。
+  特权服务态 scope 经 manifest 的 `privilegedServiceScopes` 申请、逐项审批后授予；
+  用量指标经 manifest `usageMetrics` 声明（治理档）。批准不等于部署与网关已经生效，
+  交付判据见 [公开入口](references/public-entrypoints.md)。
 - **后续版本**：对方 CI 自助（`xgent-app-release` skill）——无治理变更自动通过，
   治理变更进「发布审核」等平台批准。
 - **scope 三规则**：平台基础 scope ∪ 自己命名空间（含连字符→下划线变体）∪ 已声明 `exchangeTargets` 的目标命名空间；越界 `VALIDATION_FAILED`。
@@ -138,12 +145,32 @@ manifest 的 `requiredEnv`**（改名走 `renamedFrom`），并把「本版新
 | 档 | 键 | 值从哪来 |
 | --- | --- | --- |
 | **平台注入** | `PORT` · `<PREFIX>_SERVER_PORT` · `PORTAL_INTROSPECT_URL` · `API_BASE_URL` · `PORTAL_BASE_URL` · `<PREFIX>_SA_CLIENT_ID` · `<PREFIX>_SA_CLIENT_SECRET` | 平台换版时自己算并注入，没有人手填 |
-| **自动供给** | 库连接串 · Redis 地址 | 批准时平台按登记的服务代建库 / 取地址并注入 |
+| **自动供给** | 库连接串 · Redis 地址 · 对象存储桶 · Kafka 五键 | 批准时平台按登记的服务代建资源 / 取地址并注入 |
 | **自定** | 其余一切 | 平台管理员手填：非密钥进 `descriptor.env`，密钥进主机 `envFile` |
 
 `<PREFIX>` = `listingKey` 全大写、连字符换下划线。`PORTAL_BASE_URL` 是门户**公开源**（也是调
 别的 App `/svc/<key>` 的基址），`API_BASE_URL` 是内部 portal-api，**不代理 `/svc`**。
 
+**门户内 App 的服务地址由代码派生，不逐个要求平台手填。** 以 Page Builder 为例：
+
+| 原来的地址变量 | 应用代码使用的默认基址 |
+| --- | --- |
+| `LLM_GATEWAY_SERVER_URL` | `${PORTAL_BASE_URL}/svc/llm-gateway` |
+| `FILES_SERVER_URL` | `${PORTAL_BASE_URL}/svc/files` |
+
+接入或审核时核对这几项：
+
+- **清单**：`requiredEnv` 声明 `PORTAL_BASE_URL`，保留其他确实必需的键；上面两个可推导的
+  地址不再列为必填。平台注入的是门户基址，**不会自动注入这两个旧变量**，也不要把派生地址值写进 manifest。
+- **实现与迁移**：代码去掉门户基址末尾的 `/` 后拼接 `/svc/<key>`，再追加具体 API 路径。
+  旧变量可保留为本地调试或特殊部署的可选覆盖项。代码默认值、启动校验、清单与新镜像同步交付，
+  不能只删 `requiredEnv`；平台侧核对已有覆盖值是否保留，并在未设置旧变量时验证实际调用。
+- **权限**：统一入口不替代鉴权。代表用户调用仍需 `exchangeTargets`、目标 scopes 与令牌交换；
+  后台调用仍用获准的服务账号权限，具体姿态见下文「App 型公共服务」。
+
+这条约定针对门户内的 App 服务；第三方 API 等无法从门户基址推导的地址仍按需声明。
+发布操作见 `xgent-app-release` skill「调用门户内的其他 App：从 `PORTAL_BASE_URL` 派生地址」。
+
 **服务怎么绑到键**：键名按约定命名（`<PREFIX>_DATABASE_URL` / `REDIS_CONN_STRING`），再声明要哪条服务 ——
 
 ```jsonc
@@ -155,6 +182,15 @@ manifest 的 `requiredEnv`**（改名走 `renamedFrom`），并把「本版新
 这种上游定死的名字）也能发**，只是平台管理员要在审批屏上逐个点一下「从平台服务取值」，
 每次发版多等一轮。收交付物时把这一条当作可读性问题看：不是错，是白等。
 
+**Kafka**：声明 `requiredServices: [{"kind":"kafka","name":"main"}]`，并在 `requiredEnv` 列出
+`<PREFIX>_KAFKA_BROKERS` / `_KAFKA_USERNAME` / `_KAFKA_PASSWORD` / `_KAFKA_SASL_MECHANISM` /
+`_KAFKA_TOPIC_PREFIX`（每项均带 `<PREFIX>`）。机制固定 `SCRAM-SHA-512`，用户名 `app_<key>`
+把连字符改为下划线；主题、消费组、事务 ID 的前缀 `app.<listingKey>.` **保留连字符**。
+App 显式建主题、副本数 1，不能更改保留期或增加分区；不申请管理员密码。平台是单节点
+at-least-once 消息服务，不是业务记录系统，App 负责重复消费、重连与租户隔离。
+一盒新版 `add` 自动供给相同权限并沿用已有密码，但整份 `compose.env` 仍注入所有容器，
+不提供容器间密钥隔离。完整联调步骤见 [注册布线与一盒](references/registration-and-onebox.md#44-kafka-接入)。
+
 ⚠️ 服务账号密钥**不再要求进 envFile**：门户保管并在换版时注入容器，明文只在批准那次一次性
 回显（留给对方本地联调）。收交付物时别再问对方「密钥写进 envFile 了吗」。
 另外，平台级能力（如日志写入）会直接出现在对方的服务令牌里，**不需要在 manifest 里申请**。
@@ -166,9 +202,9 @@ manifest 还有两节**同形的审批前置闸**（与 `requiredEnv` 同一挂
 - `deployRequirements`（`{ region?, size?, gpu?, network? }`）—— 这个 App 的后端需要什么样的
   机器。批准那一刻按本环境的资源池逐维匹配，不满足就拒绝生效；通过时把落点固定到命中的
   那台。**需要 `deployDescriptor`**，且只收**名字与档位** —— 网段 / IP / URL 提交即拒。
-- `requiredServices`（`[{ name, kind, note?, envKey? }]`）—— 运行需要哪些外部服务。批准时比对
+- `requiredServices`（`[{ name, kind, note? }]`）—— 运行需要哪些外部服务。批准时比对
   本环境**已登记**的「已具备服务」（控制台 › 平台设置 › App 清单目录），未登记或缺条目就
-  拒绝生效。门户**不据此开通**任何服务，只核对登记表。
+  拒绝生效。登记表描述已有服务；支持自动供给的类型还会按所选档案为 App 建资源与注入约定键。
 
 收交付物时按这两节问三个问题：**它要跑在哪个网络里**（对方写的名字与本环境登记的名字对不
 对得上）、**它连的那些基础服务本环境有没有并且登记了没有**、以及**远端主机上没有门户的
@@ -254,7 +290,7 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
   App，门户在 TDT 签发时收口，App 侧零代码）/ `seatRoles`（App 自管账号或资源，门户只发数、
   App 自己在建号路径上收口）。
 - **role 由对方在 `app.manifest.json` 里声明**（不需要门户改代码）；**各套餐的数值进不了
-  manifest，也进不了 `LISTING_DEFS`**，只有平台管理员在控制台能写 —— 应用侧一条写路径都没有。
+  manifest**，只有平台管理员在控制台能写 —— 应用侧一条写路径都没有。
   这是有意的：数值是商务面，改它等于改可售卖档位。
 - 对接面只有一个：`POST /api/v1/seats/quota`（服务态令牌 + `seats.read`）。**`available === null`
   ⇒ 该租户 unlimited，放行、不要收口** —— 把 null 当 0 是这个契约最容易踩的一处。

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

@@ -1,6 +1,6 @@
 # 对接契约文档模板（外部服务 → 平台）
 
-> 泛化自已交付的知识库契约（`docs/knowledge-app-contract.md`，**门户仓文件，App 自己的 repo 里没有**；本模板已自包含，不必去找）。每个外部服务接入前都要按此结构交一份契约文档，且**与已实现代码 1:1 对齐**（理想状态：有回归测试保证路由表与代码同步）。没有这份文档的接入不算完成。
+> 本模板自包含，可直接在 App 仓库填写。每个外部服务接入前都要按此结构交一份契约文档，且**与已实现代码 1:1 对齐**（理想状态：有回归测试保证路由表与代码同步）。没有这份文档的接入不算完成。
 
 按节填写，方括号处替换：
 

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

@@ -1,6 +1,6 @@
 # 外部镜像服务类应用 · 集成契约
 
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §7/§15 与已接入案例（知识库 / omni-parser，2026-08）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库为准。
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 
 ## 1. 形态与分界
 
@@ -9,8 +9,8 @@
 | | 内建 App | 外部镜像 App |
 | --- | --- | --- |
 | 镜像 | 全部长在同一 runtime 镜像 | 独立镜像（`docker save` tar / 私有 registry，不发公共 dockerhub） |
-| 部署 | deploy-controller 按需拉起/缩零 | **常驻**（controller 不编排外部镜像）：独立 Deployment / compose profile，无状态可多副本 |
-| 注册 | seed / bootstrap 内建 | `app.manifest.json` + register-app（dev）/ provisioning 登记（生产） |
+| 部署 | deploy-controller 按需拉起/缩零 | 由平台按部署描述交付；支持的部署驱动和副本能力须与管理员确认 |
+| 注册 | seed / bootstrap 内建 | `app.manifest.json` + register-app（本地一盒）/ 发布提案审批（生产） |
 
 **App 类型**：有用户前端 → `micro`（前端 dist 由平台同源托管到 `/apps/<key>/`）；无前端 → **`service`**（headless：应用市场/应用中心不露卡、不可打开，仅作被调用方；平台控制台清单管理仍可治理，可作依赖被补装）。
 
@@ -31,7 +31,7 @@
 
 ## 3. 运行时鉴权（四道闸）
 
-每个受保护请求：取 `Authorization: Bearer <TDT 或端点已接纳的长期凭证>` → 调门户自省并校验声明 → 四道闸。Bun/TypeScript 使用公共服务端 SDK；其他语言实现下述相同契约。
+每个受保护请求：取 `Authorization: Bearer <TDT 或端点已接纳的长期凭证>` → 调门户自省并校验声明 → 四道闸。Bun/TypeScript 使用服务端 SDK `@xgent/portal-server-sdk`（`createPortalAuthenticator`，从平台私有包仓安装，不 vendor）；其他语言实现下述相同契约。
 
 ```
 POST {PORTAL_INTROSPECT_URL}            # 如 http://portal-api:3000/api/tokens/introspect

package/skills/portal-external-app/references/public-entrypoints.md

@@ -0,0 +1,100 @@
+# 公开页面、站点与应用身份迁移
+
+本文说明当前接入方式；能力是否已部署到目标门户，要用实际接口和浏览器确认。发布审核通过与后端健康都不能代替公开页面验收。
+
+## 1. 先选入口
+
+| 需求 | 入口 | 前提 |
+| --- | --- | --- |
+| 匿名 SPA、分享页面 | `/apps/<listingKey>/…` | 匿名页不先强制 SDK 登录；读取的数据仍需业务授权 |
+| 后端直接返回 HTML、公开回调 | `/svc/<listingKey>/…` | 平台去掉服务前缀；App 自己区分匿名与受保护路由，公开服务应常驻 |
+| 租户站点、独立域名 | `publicEntrypoints` + Sites 服务 | 入口声明、服务特权、平台站点配置、租户权益及路由就绪 |
+
+前两条已经是正式接入方式，不需要为了每个新 App 请求门户增加根级路径。
+`publicEntrypoints` 是**站点可以绑定的后端入口目录**，不是“在门户根路径新增一条代理”。
+仅声明它，不会让门户根级 `/v`、`/share` 等路径指向你的服务。
+历史根路径属于兼容契约，需要与平台约定数据迁移和切换，不可自行复用或覆盖。
+
+## 2. 后端直出页必须认识外部路径
+
+例如外部 `/svc/demo/v/abc` 转到后端 `/v/abc`。后端路由可以继续用 `/v`，
+但发给浏览器的 URL 必须包含外部 base：公开链接、表单 action、fetch、资源引用、
+重定向 Location、口令 cookie 的 Path，以及受保护预览的票据交接。
+
+将这些地址集中从可信的 public base 配置生成；不要只修改“复制链接”字段。
+不要信任任意请求自报的 Host 或转发前缀生成外部地址。不同入口的 cookie 名/Path 应避免冲突。
+仅换前缀会破坏既有 App 时，应先发布完整路径适配版本，再切换正式链接。
+
+后端 HTML 自己设置 CSP；`embedCsp` 是前端 `/apps/<key>/` 托管策略，不会替代后端公开页的策略。
+匿名可达不等于数据公开：token、口令、过期、撤销、租户边界、数据源与提交配额仍由 App 验证。
+
+## 3. 复用已有 Sites 能力
+
+清单片段（合并到自己完整 manifest；特权 reason 写实际用途）：
+
+```json
+{
+  "publicEntrypoints": [{ "key": "pages", "pathPrefix": "/public" }],
+  "privilegedServiceScopes": [
+    { "scope": "sites.read", "reason": "查询本应用在本租户的站点和域名就绪状态" },
+    { "scope": "sites.write", "reason": "为本应用在本租户创建公开站点并管理域名" }
+  ]
+}
+```
+
+同时在既有 `deployDescriptor` 中设置 `alwaysOn: true`。入口最多 8 条；key 小写字母开头，
+只含小写字母、数字、连字符，最长 40；pathPrefix 是后端站内绝对路径，不能是 URL，
+不能有 query、fragment、点段、空段或控制字符。末尾斜杠会归一化。
+省略 publicEntrypoints 保留既有登记；`[]` 弃用所有入口，会影响引用它们的站点。
+
+申报走发布提案治理审核。`sites.read/write` 是服务专用权限，写进
+`privilegedServiceScopes` 申请并由管理员批准，不能放入用户 `scopes` 或普通 `serviceScopes`。
+
+平台须打开 `PUBLIC_SITES_ENABLED`，配置站点 baseDomain/入口 DNS，租户具有
+`sites.enabled`、`portal.public_sites`，绑定自定义域时还需 `portal.custom_site_domains`。
+没有这些前提，应向平台明确反馈缺哪一项，不能仅因声明批准就发链接。
+
+后端以自己的服务账号，逐租户换取 `client_credentials` 服务票，调用：
+
+1. `POST /api/v1/sites { siteKey, entrypointKey, name? }`，同租户、App、siteKey 幂等。
+   响应 Envelope 的 `data.site` 含站点事实；平台地址由返回的 code 与平台配置派生，不硬编码域名。
+2. 需要自定义域名时 `POST /api/v1/sites/:id/domains { domain, operationKey }`，
+   按返回挑战配置 TXT 和入口 DNS，再 `POST /api/v1/sites/:id/domains/:domainId/check`。
+3. 四项 ownership/dns/tls/routing 全过才把该域名视为 ready。
+   `GET /api/v1/sites/:id` 回读站点修订，路由 appliedRevision 到达目标 revision 才算送达。
+4. 暂停用 `POST /api/v1/sites/:id/suspend`；域名释放和归档按响应的修订做并发检查，
+   不靠删 manifest 字段假装已经清理完。
+
+租户与应用从服务票推导，不能用请求体指定其他租户。
+站点请求按 pathPrefix 重写并保留 query；App 必须适配站点外部 URL。
+边缘路由头用于选站而非登录凭证；站点路径会剥除门户 `xg_sess`，
+受保护预览需自己的票据交接，不能依赖门户会话 cookie 跨到独立域名。
+
+## 4. 改 listingKey 是身份迁移
+
+改显示名不需要换 key。确需换 key 时，它是新的 aud、服务身份、安装身份和资源所有者，
+不能只重发同一镜像或复制业务数据库。迁移必须覆盖旧公开链接、页面版本、口令/撤销/过期、
+文件应用空间与授权、内容 schema、加密字段及新旧写入归属。
+
+在双方确认迁移和回滚前保留旧数据库、服务和路由。不能用 HTTP 404、HTTP 200 或 HTML
+标题猜 token 属于哪个服务；“不存在”可能返回 200 占位页。切回路由也不会自动搬回新产生的数据。
+
+## 5. 验收与交接
+
+至少检验：正式匿名页真实正文；有效/口令/过期/撤销；GET 与 POST 子请求；cookie/Location；
+有权与错误/过期预览；跨租户拒绝；重部署后地址仍可用。HTTP 200 和 `/health` 通过都不够。
+
+反馈平台时交提案号、镜像/版本、失败路径形状、时间、脱敏错误与浏览器 CSP 指令；
+不贴链接 token、口令、服务密钥。区分缺少接入说明、平台能力不足与 App 路径适配问题。
+
+## 6. 扩展 CSP 与交付能力门
+
+开发版本已实现 embedCsp 六类精确来源（connectSrc/scriptSrc/styleSrc/fontSrc/imgSrc/mediaSrc），
+以及 platformSources 在 script/style/font/connect 四类中的 jsCdn 别名。它只作用于 /apps 托管前端，
+不能替代本后端 HTML 的 CSP。生产来源须 HTTPS（connect 另可 WSS），不可通配、带路径/凭据或
+unsafe-inline/unsafe-eval 等关键字；增删均需治理审核。省略沿用、null 清空，对象完整替换。
+
+这些能力尚待正式发布与目标门户受控启用，strict 缺省关闭，不能从已有包版本或 whoami 推断已开启。
+支持 delivery 的门户按 proposalId 分别确认审批、清单/产物、实际后端及网关；纯前端也等网关。
+unknown 不能报成功，superseded 查询后续提案；旧门户无 delivery 时 CLI 明示无法核验网关。
+网关失败由平台管理员单独重试，不必重发镜像。Sites 权限与站点修订仍按本文独立核验。

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

@@ -1,8 +1,6 @@
 # 配额与席位（seatBased / seatRoles）
 
-> 有「每租户最多能建几个 X」这类诉求时读本文。提炼自门户仓 `apps/api/src/modules/seats/`、
-> `packages/shared/src/constants.ts`、`apps/api/src/db/provisioning.ts`（门户仓文件，App 自己的
-> repo 里没有；本文件已自包含）。冲突时以门户仓库为准。
+> 有「每租户最多能建几个 X」这类诉求时读本文。App 声明角色和用量指标，平台管理员维护套餐数值；不需要访问门户源码。
 
 ## 0. 红线
 
@@ -17,12 +15,12 @@
 
 两者都是 listing 上的标记，且**仅 backed listing** 可声明 —— end-state 得有 `serviceBaseUrl` 或
 `deployDescriptor`，否则 `createListing`/`updateListing` 直接 `VALIDATION_FAILED`：「只有带独立后端
-(serviceBaseUrl / 部署描述)的应用可声明席位制」（`market/service.ts` 的 `assertSeatBasedEligible`）。
+(serviceBaseUrl / 部署描述)的应用可声明席位制」。
 
 | | 用在哪 | 谁收口 |
 | --- | --- | --- |
 | `seatBased: true` | 计「门户成员」用不用得了这个 App | **门户**。TDT 签发时就拦：无席位 ⇒ `SEAT_REQUIRED`，App 侧零代码 |
-| `seatRoles: ["teacher","student"]` | App **自管账号/资源**（sms 的师生号那类） | **App 自己**。门户只发数，不拦对方的建号请求 |
+| `seatRoles: ["teacher","student"]` | App **自管账号/资源**（学校管理 `lms-school` 的师生号那类） | **App 自己**。门户只发数，不拦对方的建号请求 |
 
 ## 2. 四要素分属四个事实源
 
@@ -30,14 +28,13 @@
 
 | 要素 | 谁写 / 写在哪 | 要门户发版吗 |
 | --- | --- | --- |
-| role 存不存在（`seatRoles: ["service"]`） | **对方自己的 `app.manifest.json`**（清单仍在门户仓的 App 才是 `LISTING_DEFS`） | 不用 |
+| role 存不存在（`seatRoles: ["service"]`） | **对方自己的 `app.manifest.json`** | 不用 |
 | 各套餐给几个（生效值） | 平台管理员 → `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 不回滚审批授予） | 不用 |
+| role 的三语标签 `SEAT_ROLE_LABELS` | 平台维护的本地化标签（联系管理员） | **要**（不加则控制台显示裸 role key，`?? role` 兜底不报错） |
+| SA 的 `seats.read` | **对方 manifest `privilegedServiceScopes: [{scope, reason}]` 申请** → 「发布审核」逐条确认批准即授予 | 不用 |
 
-⚠️ **各套餐的数值进不了 manifest，也进不了 `LISTING_DEFS`** —— `AppManifest` 与 `ListingDef`
-都只有 `seatBased` / `seatRoles` 两个字段，没有任何 per-plan 数值字段。应用侧**没有任何写路径**
+⚠️ **各套餐的数值进不了 manifest** —— App 清单只有 `seatBased` / `seatRoles` 两个字段，没有任何 per-plan 数值字段。应用侧**没有任何写路径**
 （manifest 没这字段 · 发布提案携带的未知字段一律进人工审而非生效 · `seats.read` 只读）。这是有意的：
 数值是商务面，改它等于改可售卖档位、影响所有租户。应用侧能做的是在契约里**提议**一组数。
 
@@ -66,11 +63,7 @@
 - 写进 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**：它走「代码权威
-  字段」通道，每次部署都对齐，跟版本治理无关。
+- App 自己仓库的 manifest 是开发者声明的事实源；修改后提交新提案，并核对已安装租户的同步结果。
 
 ## 4. 对接面与三态
 
@@ -100,7 +93,7 @@ body { roles: ["service","node"] }
 
 平台不掌握 `seatRoles` 的占用数（收口在 App 侧），所以「已用」来自 App 自己上报的日快照：
 metricKey 约定 `<listingKey>.<role>-seats.allocated`（`latestRoleAllocated` 读最近一天）。
-sms 先例每个 role 报两条（`allocated` + `available`），两个 role 共 4 条。
+学校管理（`lms-school`）先例每个 role 报两条（`allocated` + `available`），两个 role 共 4 条。
 
 ⚠️ **硬门**：`ingestUsage` 对**未注册**的 metricKey **拒收该条记录**，且指标的
 `appKey` 必须等于上报者的 azp。漏注册的症状是上报接口返 200 但记录进 `rejected`，
@@ -110,7 +103,7 @@ sms 先例每个 role 报两条（`allocated` + `available`），两个 role 共
 **外部 App 在自己 manifest 的 `usageMetrics` 里声明 gauge 条目**
 （`[{ key, kind: "gauge", unit: "count", label: {zh,…} }]`，key 前缀必须=listingKey、
 金额单位 microAmount 不开放；治理档，批准后生效）——不再需要门户发版；
-仓内 App 仍在 `packages/shared/src/usage.ts` 登记。
+平台内建指标由平台维护，外部 App 无需修改平台代码。
 
 ## 6. 两层快照：谁读哪一层
 
@@ -122,12 +115,7 @@ sms 先例每个 role 报两条（`allocated` + `available`），两个 role 共
 | 租户加购 `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`。
+**已批准的 manifest 变更会同步到已安装租户。** 发布后核对控制台配额矩阵与租户加购面；异常交平台管理员处理，不直接修改平台数据库。
 
 推论：**漏声明不会 fail-closed**。`/api/v1/seats/quota` 不读任何 seatRoles 声明，照样按请求体里的
 role 返回兜底值。真实症状是**控制台配额矩阵与加购面不出这一行** ⇒ 平台配不了、租户加购不了
@@ -138,7 +126,6 @@ role 返回兜底值。真实症状是**控制台配额矩阵与加购面不出
 - **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 名定下来就别动。**
@@ -198,13 +185,7 @@ role 返回兜底值。真实症状是**控制台配额矩阵与加购面不出
 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 团队不能用发布令牌修改这些配置。
 
 **App 侧**
 

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

@@ -1,6 +1,6 @@
 # 注册布线与一盒（one-box）本地联调
 
-> 提炼自门户仓库 `docs/外部App本地联调指南-one-box.md`、`deploy/app-devkit/README.md`、`docs/SSO与App开发指引.md` §15.3（§4 一盒部分对齐 2026-08 的精简镜像与自建 Harbor）（门户仓文件，App 自己的 repo 里没有；本文件已自包含，不必去找）。冲突时以门户仓库为准。
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 
 ## 1. `app.manifest.json`（单一事实源，放你自己的 repo）
 
@@ -15,7 +15,7 @@
     `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` 只被携带、当前不注入）
+- 部署/运维：`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 节点连的就是那个数字），静默挪走等于把它们全断掉，且门户侧一条都测不到。
@@ -48,6 +48,10 @@
 
 ## 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 拒跑
 ```
@@ -108,10 +112,7 @@ provisioning 路径）能写。所以装完第一个租户后的那次重跑仍
 生产的清单事实源就是对方仓的 `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 明文密钥这条路**：
+（清单、服务账号与已装租户对齐，后端部署和网关交付随后独立核验）。App 团队无需修改门户源码；平台配置由管理员管理。**生产没有 manifest 明文密钥这条路**：
 SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批准时生成、enc:v1 保管、
 换版时注入容器（EXCHANGE-SECRET-HOLD）；明文只回显给审批人一次（供本地联调），轮换走
 控制台（应用清单 ›「轮换交换密钥」/ 服务账号 ›「轮换密钥」），都顺带排换版。要交接一枚
@@ -136,11 +137,31 @@ SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批
 匿名拉取，得有一个 **puller 账号**（只读凭证，按团队发放），`docker login <registry>` 用的就是它；
 凭证别转发给团队外的人、别写进会提交的文件（`portal-dev-setup` skill 把这两样收在一份
 `.xgent-registry.env` 里，照它配即可）。② **这两个调试镜像有 `latest`**（跟着最新一版走，开新项目
-不用先问 tag）；代价是本地已有同名 `latest` 时 compose **不回仓库查**，换版本前先 `docker pull`。
+不用先问 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**——
@@ -158,11 +179,12 @@ Apple Silicon），生产门户走另一条链。无 registry 访问时则要离
 
 ### 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`）；
+一盒发布 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`。改了 `HTTP_PORT` 之后门户地址随之变化，下文冒烟里的
+`postgres:5432` / `redis:6379` / `minio:9000`（RustFS 的兼容别名）。控制台路径为 `/rustfs/console/`。改了 `HTTP_PORT` 之后门户地址随之变化，下文冒烟里的
 `http://localhost/…` 都要跟着改。
 
 ⚠️ 两个必改/必不做：
@@ -184,7 +206,8 @@ Apple Silicon），生产门户走另一条链。无 registry 访问时则要离
 #      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
+# 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
@@ -216,6 +239,39 @@ Apple Silicon），生产门户走另一条链。无 registry 访问时则要离
 细节（含 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 + 平台管理员）。