@xgent-ai/skills 0.7.5 → 0.7.6

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

@@ -1,6 +1,7 @@
 ---
 name: portal-external-app
 description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖 manifest、注册、鉴权、成员客户端与终端用户身份、/svc 路由、健康检查与一盒联调。'
+when_to_use: "用户会说「把我们服务接进门户」「manifest 怎么填」「/svc 路由不通」时。"
 ---
 
 # portal-external-app · 外部镜像服务类应用接入
@@ -10,6 +11,8 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 
 `/apps/<key>/` 与 `/svc/<key>/` 是线上 URL；本文的 `references/` 和 `scripts/` 相对于本 skill 目录。
 
+品牌图：在开发者应用的 App 概览上传 SVG / PNG / WebP（≤2 MiB），取得门户平台存储的 `/api/assets/app-logo/<listingKey>/<sha256>.<ext>` URL，回填源清单 `logoUrl` 并递增版本。只能引用本 App 这一路径；外链、data URI、`/apps/<key>/` 图、查询串与其他 App key 均拒。`icon` 仍填命名字形，导航不显示品牌图；品牌图原比例原色展示，坏图回退字形。需要已配置的平台自用存储池与显式 `developer:action:branding.manage` + 维护者资格，租户 App 编辑者不能改此字段。
+
 ## 按任务读参考
 
 | 任务 | 读 |
@@ -25,7 +28,7 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 | 用户以 CLI、MCP、个人自动化调用 App，或接入门户多服务用户密钥与服务发现 | [references/cli-user-keys.md](references/cli-user-keys.md)：受审 `cliAccess` 声明、标准绑定与通用目录；不改门户业务代码 |
 | 为外部服务写/审对接契约文档 | [references/contract-doc-template.md](references/contract-doc-template.md) |
 | 有「每租户最多几个 X」的配额诉求（选模型、数值谁配、已用怎么来） | [references/quota-and-seats.md](references/quota-and-seats.md) |
-| 一个配置项该放哪（环境变量 / 平台级或租户级管理页 / 应用内设置 / 用户偏好），`requiredEnvNotes` 与 `adminPages` 怎么写 | [references/config-placement.md](references/config-placement.md) |
+| 一个配置项该放哪（环境变量 / 平台级或租户级管理页 / 应用内设置 / 用户偏好），`requiredEnvNotes`、`adminPages` 与 service `tenantConfig` 怎么写 | [references/config-placement.md](references/config-placement.md) |
 
 ## 先判形态（决定后面走哪条线）
 
@@ -46,7 +49,7 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 3. env 契约表：**镜像实际读取的变量名**（镜像自有前缀与门户契约别名的映射必须写清；有的镜像不读裸 `PORT`）；
 4. **迁移入口**：迁移文件在镜像里、二进制上有一个迁移 argv（见下节）。「迁移脚本留在自己 repo 里」= 不合格；
 5. 运维口径：是否需每租户 bootstrap（需要则 `tenants.id` 必须 = 门户租户 UUID）；**`/health` 必须通过 [健康契约验收](references/health-contract.md)**，按平台同一判据验证正常与依赖故障；信封响应不能只检查 HTTP 200；
-6. **有没有重复造平台已有的能力**：自己存文件 / 自己发通知 / 自己记审计 / 自己排定时任务 / 自己算配额 —— 逐项对照下面两张表，命中就要求改走平台面；
+6. **是否复用平台能力**：文件按下文「文件与对象存储」选择 Files 或平台 `objectStorage`，后者须明确 App 自管的租户隔离、计量与清理；通知、审计、定时任务、配额仍按下面两张表复用平台面；
 7. **租户自助凭证**：这个服务有没有「租户拿自己的程序直接调你」的场景（日志/指标摄取、批量导入、CI 回写）？有就检查那条 scope 在不在 manifest 的 **`scopes`** 里 —— 不在的话租户面开不出凭证，只能退回「找平台管理员代建」（见 [integration-contract.md §3.1](references/integration-contract.md)）；
 8. **配额诉求**：有没有「每租户能建多少」这类上限？有就走平台套餐（见 [references/quota-and-seats.md](references/quota-and-seats.md)），**不接受对方自建**；
    角色本身该由对方在自己的 `app.manifest.json` 里声明 `seatRoles`；`serviceScopes` 里出现 `seats.read` 仍是当场打回的信号，但对方可以在 `privilegedServiceScopes` 里**申请**它（带 reason，进「发布审核」逐条确认批准后授予）；
@@ -71,6 +74,10 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 
 ## 一盒初始化与升级
 
+宿主 skill 与镜像分别更新：先 `npx skills add XGENT-ai/skills` 更新 `portal-dev-setup`，
+从实际安装目录核对 `onebox.sh` 的 SHA-256，再按发布说明的匹配镜像操作。
+`requiredEnv[].generate` 的最低门户提交 / `APP_VERSION`、一盒 tag、公开 skill 提交和脚本摘要
+目前均**未发布**；完整证据状态见 `portal-dev-setup` §6，不能默认当前 `latest` 已支持。
 首次联调用 `portal-dev-setup` 的 `onebox.sh init` → `up`；已有一盒换版本用
 `upgrade [--image <ref>]` → `up`；沿用 latest 先 `pull` 更新缓存，已加载的本地新镜像可离线升级。
 不使用 `init --force` 代替升级。升级保留配置、generated/、backup/、
@@ -86,12 +93,14 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
   **发布提案**到达：平台管理员在 控制台 › 应用市场 › 接入新应用 按 key 签发 `xrel_` 令牌
   （无行先建 draft 占位），对方 `publish --manifest … --dist … --image …` ⇒ 首次必进
   「发布审核」队列 ⇒ 批准后更新清单、服务账号与已装租户，后端和网关分别交付。
-  密钥一次性回显给审批人；平台运行配置由管理员维护，App 团队无需修改门户代码。
+  SA / 交换密钥一次性回显给审批人；`requiredEnv[].generate` 声明的独立密钥永不回显。
+  平台运行配置由管理员维护，App 团队无需修改门户代码。
   特权服务态 scope 经 manifest 的 `privilegedServiceScopes` 申请、逐项审批后授予；
   用量指标经 manifest `usageMetrics` 声明（治理档）。批准不等于部署与网关已经生效，
   交付判据见 [公开入口](references/public-entrypoints.md)。
 - **后续版本**：对方 CI 自助（`xgent-app-release` skill）——无治理变更自动通过，
   治理变更进「发布审核」等平台批准。
+- **安装 scope 同步**：外部 listing 自动发布、重试、版本或品牌图同步保留现存安装 scopes，不自动增加新 scope；租户管理员须显式调用 `POST /api/admin/market/listings/:key/update` 取得当前获批 scopes（安装版本已相同也可调用）。新安装取得 listing scopes；门户内置定义同步仍 union。
 - **scope 三规则**：平台基础 scope ∪ 自己命名空间（含连字符→下划线变体）∪ 已声明 `exchangeTargets` 的目标命名空间；越界 `VALIDATION_FAILED`。
 - **secret 一致红线**：平台落库的服务账号 secret 与镜像 env 里的必须一致；漂移症状是自省 401 或「跨应用授权缺失」（实为 `SECRET_INVALID`），排查先 sha256 比对两侧。
 
@@ -139,8 +148,9 @@ job(deploy|redeploy)
 「知会门户」变成流程内动作的那道门。**CR-3 之后它还是一道真闸**：批准前门户拿这张清单比对
 `descriptor.env ∪ envFile` 的键集合（只看键在不在，不读值），缺了就拒绝生效
 （`REQUIRED_ENV_MISSING`，提案留 pending）；审批屏逐键标状态，非密钥可当场填。改名要写成
-`{ key, renamedFrom }` 一条，门户会把旧键在 `descriptor.env` 里的值搬过去（**envFile 里的搬不了**，
-门户不写那个文件，那一条会判「缺」并提示运维改名）。仍有一件它管不到：对方
+`{ key, renamedFrom }` 一条，门户会把旧键在 `descriptor.env` 里的值搬过去。普通条目在
+`envFile` 中的旧名仍判缺；带 `generate` 的条目可沿用可读文件中的旧名，App 必须兼容消费，
+不改文件、不复制值、不生成新主键。旧键已由平台保管时拒绝改名。仍有一件它管不到：对方
 **不写进 `requiredEnv`** 的静默改名依旧无门可拦 —— 症状是服务
 换版后 `refusing to start`，而发布方那侧只看到成功。2026-08-19 知识库把 `XGENT_OPENAI_*`
 整族改成 `XGENT_EMBED_*` 就是这么崩了几小时的；只改其中一个 key 更坏 —— 服务起得来，
@@ -151,13 +161,22 @@ manifest 的 `requiredEnv`**（改名走 `renamedFrom`），并把「本版新
 里写清填什么、不确定时填什么，审批屏会贴在键名旁。放哪一层的完整判断见下文「配置放哪一层」。发布面本身
 （令牌、tag 不可变、`--wait` / `--wait-review` / `status`）见 `xgent-app-release` skill。
 
-### 值从哪来：三档键名约定（照这张表命名，绝大多数键零手填）
+### 值从哪来：键名约定与独立密钥生成
 
 | 档 | 键 | 值从哪来 |
 | --- | --- | --- |
 | **平台注入** | `PORT` · `<PREFIX>_SERVER_PORT` · `PORTAL_INTROSPECT_URL` · `API_BASE_URL` · `PORTAL_BASE_URL` · `<PREFIX>_SA_CLIENT_ID` · `<PREFIX>_SA_CLIENT_SECRET` · `<PREFIX>_APP_SECRET`（声明了 `exchangeTargets` 时） | 平台换版时自己算并注入，没有人手填 |
-| **自动供给** | 库连接串 · Redis 地址 · 对象存储桶 · Kafka 五键 | 批准时平台按登记的服务代建资源 / 取地址并注入 |
-| **自定** | 其余**环境依赖**（第三方地址、第三方密钥…） | 平台管理员手填：非密钥进 `descriptor.env`，密钥进主机 `envFile` |
+| **自动供给** | 库连接串 · Redis 地址 · 对象存储五键（每应用一桶）· Kafka 五键 | 批准时平台按登记的服务代建资源 / 取地址并注入 |
+| **随机生成** | App 独立密钥，声明 `{ key, generate: { bytes: 32, encoding: "base64" } }` | 批准时生成、加密保管；换版复用，值永不回显 |
+| **自定** | 其余**环境依赖**（第三方地址、第三方已有密钥…） | 平台管理员手填：非密钥进 `descriptor.env`，密钥进主机 `envFile` |
+
+`generate` 仅收 `bytes`（16–64 整数）与 `encoding`（标准带填充 `base64` / 小写 `hex`）。
+不可用于平台派生键或服务供给目标。套件共享后端里同名共享键只由一个成员 `generate`，其余成员以
+字符串 `requiredEnv` 消费（先批生成者；两名生成者拒绝）。
+已有主键或匹配保管值保留；规格冲突、来源冲突、不可读 `envFile` 均硬拦，不能填新值绕过。
+`generate` 的增加、撤回、规格变化都需审批；已生成值不覆盖、不提供读取或轮换入口，丢失应恢复备份。
+一盒新版 `add` 在共享的 `<一盒目录>/compose.env` 中首供并稳定复用，同名键共享同一值；主 App 与其他 App
+均可能读到，适用于可信团队调试。生产则按 App、按 brand 隔离，不以一盒结果证明生产隔离。
 
 业务参数不在这张表里：先给代码缺省值；要进清单就配 `requiredEnvNotes`（见上一节末尾与「配置放哪一层」）。
 
@@ -232,13 +251,15 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 收交付物时逐项问「这个配置是哪一类」，完整判断表见 [references/config-placement.md](references/config-placement.md)。要点：
 
 - **环境依赖**进 `requiredEnv`；**业务参数**先给代码缺省值，确需覆盖才进清单并配 `requiredEnvNotes`——审批人只懂环境。
-- **全平台一份、要随时改** ⇒ 平台级管理页 `adminPages.platform`；**每租户不同** ⇒ 租户级管理页 `adminPages.tenant`。
-  页面由 App 自己做，门户嵌进应用市场编辑页 / 租户应用配置，**门户零改码**（治理档，需审批）。
+- **全平台一份、要随时改** ⇒ 平台级管理页 `adminPages.platform`；**每租户不同** ⇒ 有前端的 App 用 `adminPages.tenant`，
+  无前端的 service 用 `tenantConfig` 声明受限 schema。门户分别嵌入 App 页面或渲染动态表单，**都零业务改码**（治理档，需审批）。
 - **应用内业务设置** ⇒ 应用内设置页 + `aclManifest` 授权；**用户偏好** ⇒ App 自己按用户存。
 
-**无前端的服务型 App** 没有页面可嵌：它的租户管理员配置仍要**门户按 App 补三件**（不是零改码）——
-`<key>-token` 铸造端点 + `<key>-config-api.ts` + `AppForm` 配置 Section，参照 files / llm-gateway，
-步骤见 portal-backend-app skill；接入时把这三件列入门户侧工作量。有前端的 App 一律走 `adminPages`。
+**无前端的服务型 App**：普通数字、静态选项和开关配置在 manifest 写 `tenantConfig: { label, path, scopes, schema }`。
+门户通用签票 + 动态表单复用 App 的 GET/PUT policy 接口，不再按 App 增加 token 端点、config-api 或 Section。
+配置 GET 返回 `{ policy, effective }`，保存时 Portal 重新 GET 最新 policy、只合并编辑字段后整份 PUT；App 仍负责最终校验。
+复杂动态选项和跨字段交互可保留存量手写页，新 micro App 一律走 `adminPages`。完整契约见 references/config-placement.md；
+其中「OmniParser：六项 `foreground` 后端接入清单」给出逐字段默认值、DTO 示例和后端验收项，供 OmniParser 直接按单实现。
 
 ## 先看平台有没有，别自建一套
 
@@ -288,8 +309,24 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 ⚠️ **连字符 listingKey ↔ 下划线 scope**：`omni-parser` 的 scope 是 `omni_parser.*`，
 `llm-gateway` 的是 `llm_gateway.*`。两个命名空间，写混了是 `VALIDATION_FAILED`。
 
-**文件这条尤其别自己来**：字节一律落 files，别自己挂卷、别自己接 S3 —— 否则租户的配额、
-审计、预览、清理全都绕过了平台。落进去用哪种姿态，按**这份字节归谁**二选一：
+### 文件与对象存储：两条接入路径
+
+| | Files 文件服务 | `objectStorage` 基础设施 |
+| --- | --- | --- |
+| 接入 | 调 `/svc/files`，使用获准的用户态或服务态令牌 | 清单声明 `requiredServices: [{"kind":"objectStorage","name":"main"}]`，后端用 S3 SDK 直连；`main` 换成目标环境已登记的服务名 |
+| 桶与租户 | 托管模式使用租户池 `role=tenant`：多租户共用 bucket，默认按 `t/<tenantId>/` 前缀隔离 | 使用应用池 `role=app`：按 `listingKey` 每应用一个 bucket，该应用所有租户共用；租户安装时不另建桶 |
+| 隔离与治理 | Files 按租户、空间与权限收口，提供文件配额、计量、预览和清理能力 | 平台不自动加租户前缀；App 自行校验租户、组织对象 key，并负责权限、计量和生命周期；不自动纳入 Files 治理 |
+| 适用 | 用户/团队文件、需要平台文件治理的应用文件 | 自带 S3 存储引擎、索引快照或缓存等由 App 自管的底层对象 |
+
+**Files 的「应用空间」是某个租户内的逻辑空间，不是应用专属 bucket。** 租户在 Files 中自配的
+bucket 与凭据优先于托管池；存储位置由 Files 解析，调用 App 不取得租户池的 S3 凭据。
+
+应用池当前注入的是**池级共用的数据面凭据**，不发 per-App / per-tenant 子凭据；每应用独立桶
+不代表云侧已做跨 App 权限隔离。声明与五项 S3 环境变量见 `xgent-app-release` skill 的
+「对象存储：应用池直供 S3 五键」。五键按整组供给，不需要管理员逐键取值。
+
+应受平台文件治理的字节走 Files；App 自管底层对象可使用平台 `objectStorage`。以下用户态、
+服务态与空间选择**仅适用于 Files**，按**这份字节归谁**选择：
 
 | 这份字节归谁 | 姿态 | 落在哪 | 用户在文件管理里 |
 | --- | --- | --- | --- |
@@ -314,7 +351,7 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 - **审计**：不自建审计表/页，推 `POST /api/v1/audit`，租户在「设置 › 审计」一处看全。
 - **通讯录**：不做「同步通讯录」到自己库，按需用选人组件挑。
 - **配额/套餐**：见下一节。**计费**：平台级 Credit 服务，同样不自建。
-- **租户级配置**：放门户的 App 配置页（AppForm Section），不是 App 内的设置页。
+- **租户级配置**：micro 用 `adminPages.tenant`，service 普通配置用 `tenantConfig`；都在租户 › 应用管理 › 配置，不再按 App 手写 AppForm Section。
 - **AI 功能**：终端用户面**不出现模型选择器**，服务端按场景解析模型。
 
 ## 有配额需求？用平台的套餐管理，不许自建
@@ -346,3 +383,5 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 ## 一盒联调与冒烟
 
 外部团队不用克隆本 repo：平台给两个门户镜像 + `deploy/` 目录，对方出 manifest + `compose.env` + 自己的镜像。步骤、冒烟命令与排查速查表见 [references/registration-and-onebox.md](references/registration-and-onebox.md) §4–§6。
+
+本地调试的 PostgreSQL、Redis、RustFS（S3）、Kafka 必须复用共享 `xgent-onebox`，不另起独立实例，也不连接 portal 仓自己的独立开发环境。宿主热重载与容器的接线边界见该参考 §4、§4.2 与 §4.4。

package/skills/portal-external-app/references/config-placement.md

@@ -11,7 +11,7 @@
 | **环境依赖**：地址、连接串、证书、第三方密钥；全平台一份 | 清单 `requiredEnv`（键名，值归平台）。连接类键用约定名或 `requiredServices[].envKey` 绑定，平台自动供给 | 平台管理员 | 要 |
 | **业务参数**：超时、阈值、默认文案、开关；全平台一份、部署后不变 | **先在代码里给缺省值，不进清单**。确实要部署时可覆盖，才进 `requiredEnv`，并且**必须**在 `requiredEnvNotes` 里写清填什么 | 平台管理员（照你的说明填） | 要 |
 | **全平台一份、要随时改、不换版** | **平台级管理页**：你自己的页面，清单 `adminPages.platform` 声明，门户嵌进 控制台 › 应用市场 › 编辑你的应用 | 平台管理员 | 不要 |
-| **每个租户不同** | **租户级管理页**：清单 `adminPages.tenant` 声明，门户嵌进 租户 › 应用管理 › 配置 | 租户管理员 | 不要 |
+| **每个租户不同** | micro：清单 `adminPages.tenant` 嵌入 App 页面；service：清单 `tenantConfig` 声明受限 schema，门户渲染动态表单。都进 租户 › 应用管理 › 配置 | 租户管理员 | 不要 |
 | **应用内的业务设置**：模板、字典、流程规则… | 你应用里的设置页，用 `aclManifest` 声明权限（不给 `defaultForMember` ⇒ 默认只有租户管理员能进） | 被授权的角色 | 不要 |
 | **每个用户的偏好** | 你自己的库，按 `userId` 存 | 用户本人 | 不要 |
 | **每租户的密钥**（租户自己的第三方 API key） | 租户级管理页里录入，你的后端加密存库，**只写不回显** | 租户管理员 | 不要 |
@@ -42,6 +42,112 @@
 
 - 说明会原样给审批人看：**别写任何值或密钥**。
 
+## Service 动态配置（`tenantConfig`）
+
+无前端 service 的普通租户配置不再向平台申请手写页面。在 manifest 声明一个 Tab、同源 GET/PUT 路径、所需 scopes 和受限 schema：
+
+```jsonc
+"tenantConfig": {
+  "label": { "zh-CN": "解析预算", "en": "Parsing budget" },
+  "path": "/v2/policy",
+  "scopes": ["omni_parser.read", "omni_parser.govern"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "foreground": {
+        "type": "object",
+        "title": { "zh-CN": "前程预算", "en": "Foreground budget" },
+        "properties": {
+          "wall_time_ms": {
+            "type": "integer", "title": { "zh-CN": "最多等待", "en": "Wait limit" },
+            "default": 10, "unit": { "zh-CN": "秒", "en": "s" }, "scale": 1000
+          },
+          "mode": {
+            "type": "select", "title": "模式", "default": "auto",
+            "options": [{ "value": "auto", "label": "自动" }, { "value": "fast", "label": "快速" }]
+          },
+          "strict": { "type": "boolean", "title": "严格模式", "default": false }
+        }
+      }
+    }
+  }
+}
+```
+
+- 支持 `integer` / `number`、`select` 静态 options、`boolean` 和 object 嵌套分组；标签、说明与单位支持多语。
+  `scale` 表示「界面值 × scale = wire 值」，例如秒→1000 毫秒、MiB→1048576 字节；integer 缩放后必须是安全整数。
+- 配置 GET 返回 `{ "policy": {…}, "effective": {…} }`。Portal 展示 effective 与继承/覆盖状态；保存前重新 GET 最新
+  policy，只合并本次编辑或清除的 schema 路径，再整份 PUT，保留未展示字段。PUT 接收合并后的完整 policy 并返回同一形状。
+- 字段缺省时 effective 必须已有应用默认值；旧后端没有返回 schema 所需 effective 字段时，Portal 显示版本不支持并禁止写入。
+  App 必须在每次读写时重新校验租户管理员和 scopes，不能只信 Portal 签票或浏览器校验。
+- 无 `protocol` 的 schema 声明只支持 `type:"service"`，scopes 必须已在 listing `scopes` 中。字段新增、修改和撤回都是治理档；
+  批准后按 listing 现值对所有租户生效，不进安装快照。首版不支持动态选项、远程 `$ref`、脚本或密钥录入。
+
+### 既有 revision/CAS 设置（`skills-settings-v1`）
+
+已有 Skills 设置线协议的 micro/service 可复用 `tenantConfig`，无需新增门户 key 分支。新 micro App 的默认接入仍是 `adminPages.tenant`；此协议只适配既有的设置格式。
+
+```jsonc
+"tenantConfig": {
+  "protocol": "skills-settings-v1",
+  "label": { "zh-CN": "Skills 设置", "en": "Skills settings", "zh-TW": "Skills 設定" },
+  "path": "/v1/settings",
+  "scopes": ["my-app.read", "my-app.admin"]
+}
+```
+
+- `path` 固定为 `/v1/settings`；不带 `schema` 或其他字段。必须恰含同一自有命名空间的 read/admin，命名空间为 listingKey 或其连字符转下划线形态；两项须在 manifest 自身 `scopes` 中显式声明。重复、混合命名空间、依赖或平台权限均拒绝。
+- GET/PUT 沿用 Skills 的 revision/CAS 合同；不会转换为上节的 policy/effective。PUT 使用 `expectedRevision` 和最小 patch，冲突读回再处理；丢响应后先 GET 确认，不自动重放 PUT。存储、业务校验、审计及严格自省仍由 App 负责。
+- 通用 `GET /api/admin/apps/:appKey/tenant-config-token` 必须由当前管理员会话携带 `expectedUserId` / `expectedTenantId`，返回 `{ token, expiresIn: 600, serviceBase }`。本安装 appKey/contentOwner/来源 listingKey 必须一致，且安装仍有两项 scope；只支持 canonical `/svc/<listingKey>`（可带单尾斜杠，返回归一地址）。App 请求只带 Bearer、不带 Portal cookie。
+- 旧 `skills-token` 入口仅对本协议适配为 `skillsBase` 响应，同样现读获批声明，无旧 key 兜底。声明省略保留、null 撤回、完整对象替换，均沿既有治理；null 立即停止新票，已出票沿现有 JTI/资格撤销及最长 600 秒边界，不承诺声明撤回本身即时吊销全部旧票。
+- 批准声明不补安装 scope、角色 grant 或 consent。全部外部 listing 的自动版本/品牌同步均保留安装 scopes；新增权限须租户管理员显式调用 `POST /api/admin/market/listings/:key/update`（版本已相同也可调用）。新安装取当前获批 scopes，内置定义同步仍 union。
+- 旧 null 不自动恢复；平台有权者须在支持新协议的 API 上明确治理恢复。先升级 Portal API，再提交并批准 bump 后的正式清单，最后升级宿主前端；声明样例不是已批准事实。
+- `@xgent/shared` 联合类型从 0.11.0 起提供（实际可安装状态以门户发布回执为准）：先用 `isSkillsSettingsConfig` 分派，再访问旧 `AppTenantConfig.schema`。所有 DTO 消费方均须加守卫。
+
+### OmniParser：六项 `foreground` 后端接入清单
+
+OmniParser 的 manifest 已按上面的 `tenantConfig` 形状声明。后端要实现的是**现有 `/v2/policy` 的增量契约**，不要另建配置 API，也不要把 `foreground_limits`（单次请求字段）写成 policy 字段。
+
+| `policy.foreground` / `effective.foreground` 键 | wire 类型与单位 | 无覆盖时的应用默认 | Portal 展示 |
+| --- | --- | --- | --- |
+| `wall_time_ms` | 整数毫秒 | `10000` | 10 秒（`scale=1000`） |
+| `max_input_bytes` | 整数字节 | `16777216` | 16 MiB（`scale=1048576`） |
+| `max_result_bytes` | 整数字节 | `4194304` | 4 MiB（`scale=1048576`） |
+| `max_nodes` | 整数项 | `100000` | 100000 个节点 |
+| `max_container_depth` | 整数层 | `8` | 8 层 |
+| `max_embedded_items` | 整数项 | `10000` | 10000 个资源项 |
+
+DTO 规则：
+
+- `policy.foreground` 是**可选、可部分覆盖**的对象；缺整个对象或缺某一键都表示继承。已有 policy 的其他键必须原样保留。
+- `effective.foreground` 必须**始终包含全部六键**，值是应用默认、租户覆盖和平台安全界共同决定的当前有效值；不能只回显 raw 覆盖值。它不包含单次请求 `foreground_limits` 的临时收紧。
+- 例如，raw 只覆盖等待时间时，GET 仍返回完整 effective：
+
+  ```json
+  {
+    "policy": { "foreground": { "wall_time_ms": 12000 } },
+    "effective": {
+      "foreground": {
+        "wall_time_ms": 12000,
+        "max_input_bytes": 16777216,
+        "max_result_bytes": 4194304,
+        "max_nodes": 100000,
+        "max_container_depth": 8,
+        "max_embedded_items": 10000
+      }
+    }
+  }
+  ```
+
+后端行为与验收：
+
+1. 沿用现有租户管理员 + `omni_parser.read` / `omni_parser.govern` 双闸和租户隔离，不新增 scope。每次读写都重新判权，不能信任浏览器或 Portal 的预检。
+2. PUT 接受合并后的完整 policy，校验六键的类型和实际安全范围；非法或超界时**整份拒绝、原 policy 不变**。成功 PUT 后返回与 GET 同形的最新 `{ policy, effective }`。
+3. 清除某个 raw 覆盖键后，该键在 effective 中回到继承值；编辑一个键不得重置其他覆盖键，也不得改变已有 Jobs 的冻结策略、预算或 fragment topology。
+4. `budget: EnhancementBudget` 继续独立表示模型调用/费用预算，不能用 `foreground` 替代。实际 Probe / Inspect / FastParse 必须把应用默认、租户 policy、请求 `foreground_limits` 和平台硬界按既定规则取交集；**只把六键加入 DTO 而不接入实际执行路径不算完成**。
+5. 旧后端没有 `effective.foreground` 时，Portal 会显示「当前服务版本不支持」且不会 PUT。不要为了制造“支持”假象而在旧版本补一个空对象或静态默认值，然后让实际执行绕开这些限制。
+6. 至少验证：完整/部分 raw 的 GET、六键逐一保存与刷新读回、清除覆盖、非法值原样拒绝、未编辑旧键保留、普通成员/无 govern/跨租户拒绝，以及真实执行确实遵守六项限制。
+
 ## 管理页嵌入（`adminPages`）
 
 门户不为你写配置界面。你在自己的前端里做好页面，在清单里声明它的路由，门户把它嵌进管理面：
@@ -73,4 +179,4 @@
 ## 已有的门户手写配置页
 
 文件管理、大模型网关、知识库等早期应用的租户配置页是门户代码里按应用手写的（签票端点 + 配置 API +
-配置区块）。那是过渡做法：**新应用一律用 `adminPages`**，不要再向平台申请这类按应用写的门户代码。
+配置区块）。那是过渡做法：新 micro App 用 `adminPages`，新 service 的普通配置用 `tenantConfig`；不要再向平台申请这类按应用写的门户代码。

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

@@ -18,7 +18,7 @@
   声明本 App 的身份空间范围；不创建托管 profile/client、不授额度，也不是成员的 publicClient。
   顾客/学生认证与生命周期按 [终端用户接入](end-users.md) 配置；endusers.* 等服务权限经特权审批申请。
 - 服务态与计量：`usageReporter`（true ⇒ SA 得 `client_credentials` + `usage.report`）、`serviceScopes`（服务态 scope；SERVICE_ONLY **永拒**）、`privilegedServiceScopes`（SERVICE_ONLY 的**申请**：`[{scope, reason}]`，reason 必填，最高治理档、审批逐条确认后授予）、`usageMetrics`（用量指标声明：key 前缀必须=listingKey、金额单位不开放；治理档，批准后 ingest 才认这些 key）
-- 部署/运维：`requiredEnvNotes`（`{ 键名: 说明 }`，给 `requiredEnv` 里需要解释的键写一句给审批人看的话，≤200 字；纯展示、自动档）、`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`）
+- 部署/运维：`requiredEnvNotes`（`{ 键名: 说明 }`，给 `requiredEnv` 里需要解释的键写一句给审批人看的话，≤200 字；纯展示、自动档）、`requiredEnv`（部署所需 env 的**键名**清单，值永远由平台配；元素可写 `{ key, renamedFrom }` 表达改名，或加 `generate` 声明独立密钥规格，见 §3.1。键名、改名或生成规格一变提案转入「发布审核」，且**批准前门户会核对实际来源，缺键拒绝生效**（`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 节点连的就是那个数字），静默挪走等于把它们全断掉，且门户侧一条都测不到。
@@ -126,6 +126,32 @@ SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批
 
 ⚠️ **secret 一致红线**：平台落库的服务账号 secret 与你镜像 env 里的必须一致。漂移症状 = 自省 401，或「跨应用授权缺失/未开启」（实为 `SECRET_INVALID`）。排查：对你侧 secret 求 sha256 与门户 DB 存的哈希比对。
 
+### 3.1 声明由平台生成的独立密钥
+
+```jsonc
+"requiredEnv": [
+  {
+    "key": "WORKER_DATA_KEY",
+    "renamedFrom": "WORKER_LEGACY_DATA_KEY",
+    "generate": { "bytes": 32, "encoding": "base64" }
+  }
+],
+"requiredEnvNotes": { "WORKER_DATA_KEY": "保护应用持久化数据；应用兼容消费旧键名" }
+```
+
+`generate` 只收 `bytes`（16–64 整数）与 `encoding`（标准带填充 `base64` / 小写 `hex`），
+不含密钥值。声明或规格变化进发布审核；首供在批准时完成，值加密保管且永不回显，后续
+发布、重试与部署复用。已有 descriptor 主键或可读 envFile 主键保留，匹配的保管行也保留；
+descriptor 旧名按同值改名。带 `generate` + `renamedFrom` 时，可读 envFile 只有旧名也可满足：
+保持文件原样、原名注入，App 继续消费旧名，不复制到新键、不生成新主键。
+不带 `generate` 的旧名条目仍走原缺键规则。
+
+按 App、按 brand 各自生成。平台派生键、服务自动供给目标不得再声明 `generate`。套件共享后端里
+同名共享键只由一个成员声明 `generate`，其余成员以字符串 `requiredEnv` 消费（先批生成者，两名生成者
+拒绝；生成者退出前先解除消费者依赖），成员受管 envFile 必须显式 `KEY=value`。envFile 不可读、来源冲突或保管规格不一致
+都硬拦；旧键已由平台保管时不能用 `renamedFrom` 改名，须保留原键。没有读取值或轮换入口；
+保管行丢失须恢复备份，不能用重生成修复原密文。
+
 ## 4. 一盒联调流程
 
 分工：平台交**两个门户镜像** + `deploy/` 目录（含 `app-devkit/` 与 `onebox/`）。你交
@@ -133,6 +159,11 @@ SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批
 `APP_FRONTEND_DIST` **绝对路径**）③你的后端镜像（+ micro 的前端 dist）。
 **不 clone 门户、不改门户代码、不重建门户镜像。**
 
+**本地调试的基础设施边界**：PostgreSQL、Redis、RustFS（S3）、Kafka 一律使用共享 `xgent-onebox`，
+不要在 App repo 另起独立实例，也不要连接 portal 仓自己的独立开发环境（那套只服务门户仓自身开发）。
+无论后端跑在容器还是宿主热重载进程都遵守：容器用一盒网络地址，宿主用 §4.2 的发布端口；Kafka 的
+宿主地址与 App 用户见 §4.4。
+
 ```
 <registry>/<项目>/one-box:latest   # portal runtime → XGENT_IMAGE       (~310MB)
 <registry>/<项目>/proxy:latest     # caddy proxy    → XGENT_PROXY_IMAGE (~68MB)
@@ -147,14 +178,24 @@ SA 密钥与交换发起方密钥（`<PREFIX>_APP_SECRET`）都由平台在批
 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 的脚本：
+镜像升级不会更新宿主脚本。先从公开渠道更新 `portal-dev-setup`，核对实际安装的脚本摘要，
+再更新匹配镜像；已有一盒不要重跑 `init --force` 来升级：
 
 ```bash
+npx skills add XGENT-ai/skills
 S="<portal-dev-setup 的 SKILL.md 所在目录>/scripts/onebox.sh"
+shasum -a 256 "$S"
+"$S" pull
 "$S" upgrade --image <registry>/<项目>/one-box:v<版本>-<sha>
 "$S" up
+"$S" add <listingKey> --manifest app.manifest.json
 ```
 
+`generate` 的最低组合目前**未发布**：首个支持的门户提交 / `APP_VERSION`、一盒 runtime / proxy
+不可变 tag、`XGENT-ai/skills` 公开提交及 `onebox.sh` SHA-256 均待正式发布后填齐。
+按发布说明逐项核对，不能从现有样例 tag 或 `latest` 推断支持。新脚本配旧镜像时，
+`register-app` 拒收未知字段，`add` 按「注册失败」中止；只更新镜像不会补齐旧宿主脚本的生成能力。
+
 初始化是 `init` → `up`；升级是 `upgrade` → `up`；主动删数据重置才是 `dc down -v` → `init --force` → `up`。
 升级保留 `compose.env`、`generated/`、`backup/`、端口、密钥和卷，只追加变更的镜像/版本行，
 不重生成配置。两个目标镜像都已缓存时支持离线升级；沿用 latest 先 `pull`，再 `upgrade` → `up`。
@@ -162,6 +203,13 @@ S="<portal-dev-setup 的 SKILL.md 所在目录>/scripts/onebox.sh"
 数据库启动前按现有 PG_VERSION 保留大版本和挂载布局；未知/冲突布局拒绝启动，不能用删卷来解决。
 门户升级不执行 PostgreSQL 大版本迁移，后者需要单独备份与维护窗口。
 
+新版 `add` 在 SA / App Secret 后按 §3.1 生成独立密钥，非空主键保留，旧别名有值则沿用旧名，
+缺键检查也显示兼容满足。它写入共享 `compose.env`，主调试 App 和其他 App 均可能读到；
+同名键共享同一值，只适用于可信团队，不承诺生产的 App / brand 隔离。
+`init` / `up` / `add` / `upgrade` 用 `<一盒目录>/.onebox-env.lock/` 保护写入，并发调用先退出再重试。
+异常中断留下锁时核对 `owner` 记录的 PID 与进程启动时间，确认原进程已结束后才手工清理；
+脚本只释放自己的锁，不自动抢锁或重生成。
+
 对象存储是 RustFS，原 `MINIO_*` 与 `minio:9000` 地址继续使用。`up`/`add`/建桶都先通过迁移门，
 旧 MinIO 卷复制到新卷并核对后才提交；原卷及 `backup/` 的镜像归档、清单、回退入口保留。
 提交后新卷是权威；有新写入时回退入口会隔离 RustFS 并拒绝切回旧卷，需在副本上人工验证后恢复，
@@ -318,3 +366,9 @@ curl -X POST http://localhost/svc/<key>/v1/...   # 缺/错 token → 401/403（
 | `git` 连不上本机 Gitea/GitHub | 一盒是 `NODE_ENV=production`，SSRF 守卫默认拒环回与私网 —— 把目标 hostname 显式列进 `GIT_ALLOWED_HOSTS` |
 | 视频海报/网格缩略图不出 | 一盒没装 ffmpeg，`PREVIEW_MEDIA_CONVERTER_URL` 应留空（§4.1）；其余预览不受影响 |
 | 起了一盒把另一套栈的容器停了 | `COMPOSE_PROJECT_NAME` 没改（§4.2） |
+
+## 品牌图（logoUrl）
+
+开发者应用概览提供上传与地址复制。接口 `POST /api/v1/developer/apps/:key/logo` 以开发者用户 TDT 和原始图片字节请求；服务端验证当前租户、显式开发者页面/品牌动作 PID、维护者关系、字节格式与 2 MiB 上限。成功 `{ok:true,data:{url}}`，同时写 listing 并同步存量安装；同字节 URL 幂等。平台存储未配置返回 `STORAGE_NOT_CONFIGURED`，不可回退为 data URI。
+
+将 URL 填入源 `app.manifest.json` 的 `logoUrl` 并递增版本。字段省略沿用，`null` 清空；只支持 `/api/assets/app-logo/<本 listingKey>/<64位小写sha256>.(svg|png|webp)`。展示字段按自动档发布，存量安装与新装一致，保留租户自定义名称。品牌显示在市场、应用中心、启动器、宿主版头与授权屏；左侧导航保持 `icon` 命名字形。跨部署清单目录会剔除这个单部署资产地址，目标门户须重新上传品牌图并回填 URL。需要包含门户提交 `1590f2e3` 的运行件（本期一盒 tag `wise-pdf-p1-1590f2e3-20261019`）。

package/skills/portal-logging/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: portal-logging
 description: '用于将 App 日志或遥测接入 XGENT 门户「日志与监控」，或排查写入、查询异常。覆盖采集器、写入凭据与 scope、流命名、日志字段及多行合并。'
+when_to_use: "用户会说「日志进不了门户」「门户里查不到日志」「日志被拆成很多行」时。"
 ---
 
 # portal-logging · 把 App 的日志接进「日志与监控」

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

@@ -1,6 +1,7 @@
 ---
 name: portal-micro-app
 description: '用于开发、修改或排查 XGENT Portal 的 iframe 微应用前端。覆盖页面、导航、Widget、portal-sdk 握手、令牌、consent、主题与路由等 UI 问题。'
+when_to_use: "用户会说「微应用里拿不到当前用户」「iframe 和门户通信不通」「门户主题不生效」时。"
 ---
 
 # portal-micro-app · 嵌入式微应用（iframe + SDK）开发
@@ -49,7 +50,7 @@ skill 的「第 0 步」。仓里还没有 `.xgent-registry.env` ⇒ 停下，
 - **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。浏览器验收时检查版头与 App 内容没有重复标题。
 - **帮助页入口 `helpEntry`**：清单里声明一个可空字符串，版头工具条最右侧（全屏与刷新的**左边**）就多一枚帮助按钮；不声明就不出按钮。两种形态：`"/help"` = App 内路由（宿主置 `?r=`，不离开门户，**自动档**）、`"https://docs.example.com"` = 外站文档（新标签 + `noopener`，**走治理审核**，因为门户版头等于替这个域名背书）。`/…` 与 crumb `route` 同一条规则；外站必须 https（`http://` 连回环也拒）、无 fragment。它是**安装期快照**，改了要 bump 自己的 `version`；**租户不可覆盖**（想指向自家知识库去知识库 App 建条目）。门户不托管、不渲染、不翻译帮助正文。
 - **低频入口放版头、不占侧栏**：帮助中心 / 接入指引这类低频页别长期占着侧栏一个位置 —— 用 `helpEntry` 挂到版头，并把这一级显式推进面包屑。
-- 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；未保存更改 `sdk.setDirty(true)` 让宿主拦离开。
+- 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；未保存更改 `sdk.setDirty(true)` 让宿主拦 Shell 离开、刷新/关闭，以及跨宿主 pathname 的前进后退；取消保留原 iframe。同 App 只改 `?r=` 不拦。历史守卫需要包含 Wise PDF 平台增量（2026-10）的门户运行件；SDK 0.5.7 的注释更新本身不启用旧宿主。App 内部应使用内存路由 + routeSync，不在 iframe 内 pushState。
 - **iframe 高度二选一**：满高型（编辑器、聊天、带底部输入栏）**不调** `sdk.resize`，外壳 `height: 100dvh`（或 `100%`）+ 内部滚动——软键盘缩小可见区时宿主让 iframe 一起变矮、在 iframe 内触发 `resize`，App 在 `resize` 里把插入点 / 焦点输入框滚回视图，且 iOS 上输入控件计算字号 ≥16px（更小时 Safari 聚焦即放大，宿主不让位）；内容高度型调 `sdk.resize(scrollHeight)`，由宿主滚动区滚动，**调过一次就不再复位为满高、也不再为键盘让位**。没有键盘高度事件，也不需要。详见 [SDK 参考「iframe 高度」](references/sdk-reference.md#iframe-高度满高型与内容高度型软键盘)。
 
 ## Consent 硬规则

package/skills/portal-micro-app/references/sdk-reference.md

@@ -102,7 +102,9 @@ sdk.setBreadcrumbs([                         // 页面层级 → 宿主版头面
   { label: "需求池", route: "/requirements" },
   { label: "FR-12 登录页改造" },             // 末级不带 route（它就是当前页）
 ]);                                          // 首页推 []；整条 trail 全量覆盖
-sdk.setDirty(true);                          // 未保存更改 → 宿主拦截离开
+sdk.setDirty(true);                          // 拦 Shell 离开、刷新/关闭、跨 pathname 的前进后退
+                                             // 同 App ?r= 不拦；取消保留原 iframe
+                                             // 需要含门户提交 1590f2e3 的运行件；仅升级 SDK 不启用旧宿主
 sdk.requestFullscreen(true);
 
 // 订阅宿主事件