@xgent-ai/skills 0.7.5 → 0.7.6

package/skills/xgent-app-release/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: xgent-app-release
 description: '用于从 App 仓库发布或排查 XGENT 门户版本：前端 dist、后端镜像、manifest 或首次接入。通过 release-cli 与发布令牌提交提案，处理 CI、待审及发布后故障。'
+when_to_use: "用户会说「发个版」「提案卡在待审」「发布后出故障」时。"
 ---
 
 # xgent-app-release · App 版本自助发布
@@ -15,7 +16,7 @@ description: '用于从 App 仓库发布或排查 XGENT 门户版本：前端 di
   自动通过并应用清单/产物；后端与网关需分别确认，且每次留档（时间 + diff + 令牌前缀）。
 - **审核档**：其余一切（scopes / ACL 清单 / 依赖 / 跨应用授权 / 服务地址 / 席位 /
   授权文案 scopeLabels / iframe 指向 embedUrl / 部署形态 / 部署前置 env 键清单
-  requiredEnv / 服务账号身份 serviceAccount.clientId / 嵌进门户管理面的管理页 adminPages / 首次接入）都会改变权限面，
+  requiredEnv / 服务账号身份 serviceAccount.clientId / 嵌进门户管理面的管理页 adminPages / service 租户配置 tenantConfig / 首次接入）都会改变权限面，
   ⇒ 提交成功但进入平台管理员的「发布审核」队列，**批准前库里一字不动**。
   被拒绝时 `status` 与 `--wait` 都能看到原因。
 - **`helpEntry`（版头那枚帮助按钮）按【值】分档**，同一个字段两种命运：写 App 内路由
@@ -39,7 +40,7 @@ SERVICE_ONLY scope（如 `seats.read`）写进 `serviceScopes` 都会**提交即
 reason 会原文展示给审批人，写清楚用途能少一轮往返。上报自己的用量指标，先在
 `usageMetrics` 里声明（key 必须以你的 listingKey. 开头；同样治理档）——没声明的
 metricKey 会被上报接口拒收并计入 `rejected`。要声明「部署我需要哪些环境变量」
-用 `requiredEnv`（只交键名），值由平台注入、自动供给或管理员配置 —— 见下面「镜像要环境变量」。
+用 `requiredEnv`（键名与可选生成规格），值由平台注入、自动供给、声明生成或管理员配置 —— 见下面「镜像要环境变量」。
 
 ### 文案字段：哪些支持多语，哪些不支持
 
@@ -156,14 +157,25 @@ MANIFEST_STORE_TOKEN=xrel_…         # 目录那台签给你的发布令牌；
   别把套件令牌当单应用令牌随手分发。成员被移出套件 ⇒ 令牌对它即刻 404；维护者离场 ⇒
   套件令牌连同吊销。
 - **批次**：`POST /api/market/release/bundle/<bundleKey>`（bundle 令牌），一次给全体成员
-  各建一条提案，共享同一批号与同一镜像/版本。JSON 体：`version` / `image` 共享，
-  每成员可选 `dist__<key>`（文件）与 `manifest__<key>`。任一成员的确定性校验不过 ⇒
+  各建一条提案，共享同一批号与同一镜像/版本。字段：`version` / `image` 共享，
+  每成员可选 `dist__<key>`（文件）与 `manifest__<key>`。**带任何 `dist__<key>` 就必须发
+  `multipart/form-data`**（它只认文件字段，JSON 体里塞不进文件）；只有 `version` / `image` /
+  `manifest__<key>` 的纯元数据批次才可以发 JSON。单个包 ≤200 MiB，**整个请求 ≤256 MiB** ——
+  各成员的包加起来也受这一条限制，不能按「成员数 × 200 MiB」估。任一成员的确定性校验不过 ⇒
   整批不落库；成员镜像已漂移而批次没带镜像 ⇒ `BUNDLE_IMAGE_DIVERGED`（带上镜像即可收敛）。
   状态轮询：`GET /api/market/release/bundle/<bundleKey>/status`（每成员一条）。
+- **批次的后端只收敛一次**：门户在提交时冻结本批的预期后端成员；它们**全部生效且无 applyError**
+  后共享后端才按新目标收敛一次。之前清单 / 前端可逐个生效，发布状态显示「后端等待成员 x、y」；
+  有成员被拒 / 撤回 ⇒ 原批不再执行：先撤清其余待审，再提交**新的完整批次**（取代旧批）；
+  `applyError` 按既有重试修好即可。前端先于后端生效，**新前端必须兼容旧后端**。批次回执里每个
+  成员的 `warnings` 会写明「自动档被转待审」的原因（缺键、等生成者等）。
 - **共享后端的 manifest**：成员各自的 `deployDescriptor.image` 的**仓库段可以等于 bundleKey**
-  （治理闸对套件镜像放行）；端口/环境变量以最早加入的成员为准。成员的对外地址不变：
-  各自 `/svc/<成员key>`，容器只是同一个（`<bundleKey>-server`）。共享 ⇒ 故障域合一：
-  容器挂了，全部成员一起不可用，各自的告警各自到。
+  （治理闸对套件镜像放行）。**端口、资源、迁移与健康路径取宿主**（最早加入的有后端成员）；
+  **环境变量由全体后端成员共同提供**——各成员的 SA、交换密钥、库连接、生成密钥都会进同一个容器；
+  **同名表示共享**：同值合并，**异值拒绝**（要么统一取值，要么改用带各自前缀的键）。成员的受管
+  envFile 每行必须是 `KEY=value`，不能写裸 `KEY`。成员的对外地址不变：各自 `/svc/<成员key>`，
+  容器只是同一个（`<bundleKey>-server`）。共享 ⇒ **成员能读到彼此的密钥、故障域合一**：容器挂了，
+  全部成员一起不可用，各自的告警各自到；需要进程级保密的成员继续独立部署。
 - **加不进去的两种真原因**：报 `BUNDLE_BUILTIN_MEMBER` ⇒ 那是仓内内置 App，先出仓再进套件；
   报 `BUNDLE_MEMBER_ALREADY_DEPLOYED` ⇒ 它已有独立容器在跑，先让平台管理员在
   「服务部署」里停止，再加入。
@@ -269,7 +281,8 @@ whoami `200` 而 `/status` `404`，就是这种情况：**令牌没问题，别
   每次都传完整 dist。
 - **tar 根必须直接是 `index.html`。** CLI 传目录会生成临时包并在命令收尾删除；本流程先留存
   完整 `.tgz` 再用 `--dist` 上传该文件，保证留存的是实际上传的字节。套一层 `dist/` 的包会被拒收。
-- **上限 64MB**，且门户只按顶层条目数报数。真超了先查有没有把 source map / 未压缩素材打进去。
+- **单个包 ≤200 MiB**（`dist` / 每个 `dist__<key>` 各算各的），**整个上传请求 ≤256 MiB**（套件批次所有
+  成员的包合计也在内）；门户只按顶层条目数报数。真超了先查有没有把 source map / 未压缩素材打进去。
 - **本机配了代理就用 `@xgent/release-cli` ≥0.6.0。** Node 内置的 `fetch` **不读** `HTTPS_PROXY`
   —— curl / git / npm / docker 全都读，唯独发版这一步不读，于是它绕开本机代理直连门户：跨境
   直连上行实测约 10 KB/s，2MB 产物必然超时，而报出来的是一句没有线索的 `fetch failed`。
@@ -292,14 +305,15 @@ whoami `200` 而 `/status` `404`，就是这种情况：**令牌没问题，别
 
 ## 镜像要环境变量：**键名归你，值归平台**
 
-manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥进你的 git 历史）。唯一的表达
-方式是 **`requiredEnv`（只交键名）**。值从哪来分三档 —— 照这张表命名，绝大多数键**零手填**：
+manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥进你的 git 历史）。使用
+**`requiredEnv` 声明键名与可选的生成规格**。值从哪来按下表区分：
 
 | 档 | 键 | 值从哪来 |
 | --- | --- | --- |
 | **平台注入** | `PORT` · `<PREFIX>_SERVER_PORT` · `PORTAL_INTROSPECT_URL` · `API_BASE_URL` · `PORTAL_BASE_URL` · `<PREFIX>_SA_CLIENT_ID` · `<PREFIX>_SA_CLIENT_SECRET` · `<PREFIX>_APP_SECRET` | 平台换版时自己算并注入，没有人需要动手 |
-| **自动供给** | 库连接串 · Redis 地址 | 批准时平台按登记的服务替你建库 / 取地址并注入（见下面「服务怎么绑到键」） |
-| **自定** | 其余**环境依赖**（第三方服务地址、第三方 API key…）—— **不含上面两档列出的键** | 平台管理员手填：非密钥进控制台的 `deployDescriptor.env`，密钥进宿主机上一个 600 的 `envFile` |
+| **自动供给** | 库连接串 · Redis 地址 · 对象存储五键 | 批准时平台按登记的服务代建资源 / 取地址并注入（见下面「服务怎么绑到键」） |
+| **随机生成** | App 独立密钥，声明 `generate` | 批准时生成、加密保管，后续换版复用，值永不回显 |
+| **自定** | 其余**环境依赖**（第三方服务地址、第三方已有 API key…） | 平台管理员手填：非密钥进控制台的 `deployDescriptor.env`，密钥进宿主机上一个 600 的 `envFile` |
 
 业务参数（超时、阈值、默认文案、功能开关…）**不在这张表里**：先看下面「业务参数」一节。
 
@@ -307,6 +321,43 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
 `PORTAL_BASE_URL` 是**浏览器可达的门户公开地址**，也是你调别的 App `/svc/<key>/…` 的基址；
 `API_BASE_URL` 是内部 portal-api，**不代理 `/svc`** —— 两个别互相顶替。
 
+### 独立密钥：只声明生成规格
+
+```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`）。
+新增、撤回或改变规格都需审批；首供在批准时完成，生产按 App、按 brand 各自生成，
+加密保管并只向所属独立 descriptor 部署注入。重发、重试、重部署与重启复用原值，
+不覆盖存量值；没有读取值或轮换入口，丢失应从备份恢复，不能重生成修复原密文。
+
+有主键沿用主键；descriptor 旧名可以同值搬到新键。可读 `envFile` 只有旧名时，
+`generate` + `renamedFrom` 表示 App 仍能消费旧名，门户原样注入文件、不创建新主键，
+审批屏显示沿用旧名。不要引导运维改文件或手填 NEW。普通无 `generate` 的改名规则不变。
+不可读 envFile、来源冲突、已保管规格冲突均硬拦；旧键已由平台保管时拒绝改名。
+平台派生键和服务自动供给目标不能声明 `generate`。
+
+**套件里的共享生成密钥**：带自己前缀的键各自 `generate`；**同名共享键只由一个成员声明 `generate`**，
+其他成员只在 `requiredEnv` 写字符串键名消费（两名生成者会被拒）。先批生成者——消费者先到时提案
+保持待审、审批屏点名生成者；批次发布自动把生成者排在消费者前面。生成者退出套件前，先让消费者去掉
+对这个键的依赖。
+
+旧门户 / 旧一盒镜像会拒收 `generate`（`VALIDATION_FAILED`），须先升级平台，不能用手填绕过。
+最低门户提交 / `APP_VERSION`、一盒 runtime / proxy tag、公开 skill 提交与脚本 SHA-256
+目前均**未发布**，发布后按完整组合核对。一盒宿主脚本不随镜像更新：先执行
+`npx skills add XGENT-ai/skills` 更新 `portal-dev-setup`，从实际安装目录用
+`shasum -a 256 <脚本路径>` 核对后再 pull / upgrade / up / add，步骤见该 skill §6。
+新版 `add` 把生成值写进共享的 `<一盒目录>/compose.env`，沿用已有主键或旧别名；同名键共享值，
+主 App 和其他 App 均可能读取，限可信团队调试，不能作为生产 App 隔离证据。
+
 ### 业务参数：能不进清单就不进；进了就写 `requiredEnvNotes`
 
 审批你发版的平台管理员只负责**环境**：地址、连接串、密钥、这台机器上的事。你的业务参数他不懂，
@@ -318,7 +369,8 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
    进了 `requiredEnv` 的键批准前**必须有值**（缺了就是 `REQUIRED_ENV_MISSING`），审批人照你这句话填。
 3. **全平台一份、要能随时改、不想换版** ⇒ 这不是环境变量。做成你自己的「平台设置」页，由门户嵌进
    应用市场的编辑页（见 portal-external-app skill「配置放哪一层」）。
-4. **每个租户不同** ⇒ 租户管理员的应用配置页（同上）。
+4. **每个租户不同** ⇒ 有前端的 App 用 `adminPages.tenant` 嵌入自己的配置页；无前端 service 用 `tenantConfig`
+   声明数字、静态选项和开关 schema，由门户渲染动态表单（同上）。
 5. **应用内的业务设置** ⇒ 你应用里的设置页，按 ACL 授权（租户管理员默认可改）。
 
 ```jsonc
@@ -414,7 +466,53 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
   `envKey` 只对 postgres / redis 这类单键服务有效（kafka / 对象存储 / http 不支持）。不绑定的话，
   平台管理员要在审批屏上手选一条服务取值，每次发版多等一轮；预检会对这类键给你一条 warn。
 
-另外：**平台级能力（例如日志写入）会直接出现在你的服务令牌里，不用申请、不用写进 manifest** ——
+### 对象存储：应用池直供 S3 五键
+
+这条路径用于 App 自管的底层对象，后端用 S3 SDK 直连，不经过 Files。需要用户/团队文件空间、
+文件权限、配额、预览或清理时走 Files；两条路径的选型见 `portal-external-app` skill 的
+「文件与对象存储」。**Files 的「应用空间」不等于这里的应用专属 bucket。**
+
+以 `listingKey=wish-list` 为例，下面是合并进现有 manifest 的存储声明片段，其他必需键照常保留：
+
+```jsonc
+"requiredServices": [
+  { "kind": "objectStorage", "name": "main" }
+],
+"requiredEnv": [
+  "WISH_LIST_S3_ENDPOINT",
+  "WISH_LIST_S3_REGION",
+  "WISH_LIST_S3_BUCKET",
+  "WISH_LIST_S3_ACCESS_KEY_ID",
+  "WISH_LIST_S3_SECRET_ACCESS_KEY"
+]
+```
+
+- `main` 换成目标环境已登记的对象存储服务名，用于服务可用性闸；它**不是桶名或池 ID**。
+  首次开通按实际落点 VM 的地域选择应用池，未命中用兜底池；只使用 `role=app`，不回退租户池。
+- 发布提案批准时平台按 `listingKey` 建桶并加密保管整组连接参数，部署时注入。**每应用一个桶，
+  该应用的所有租户共用**；不会为每个租户或安装实例另建桶，也不会自动添加租户目录。
+  App 须自行实现租户隔离、权限、计量和对象清理；它们不自动进入 Files 的配额、计量与退出清理。
+- 五键固定为 `<PREFIX>_S3_ENDPOINT` / `_S3_REGION` / `_S3_BUCKET` / `_S3_ACCESS_KEY_ID` /
+  `_S3_SECRET_ACCESS_KEY`（每项均带 `<PREFIX>`）。`objectStorage` **不支持 `envKey`**，带上即拒；
+  约定名是 `_S3_BUCKET`，镜像若只读 `_S3_BUCKET_NAME` 等其他名字，需在应用配置层适配。
+  只声明该 `requiredServices` 也会整组供给；显式列出五键便于启动校验与交付检查，只交键名、不交值。
+  仅用 `requiredEnv` 的兼容路径以 `<PREFIX>_S3_ACCESS_KEY_ID` 为触发键，仍供给整组；
+  只写 endpoint / region / bucket 不会触发自动供给。
+- **管理员不必逐键取值**：已匹配应用池时，审批页显示「批准时自动供给」，直接批准即可。
+  需要手动选池或提前供给时，在五键任意一行选择 `objectStorage` 应用池并点击「取值」，
+  一次写入全部五键，刷新后整组显示「已取值」。只切换下拉选项、不点「取值」不会保存选择；
+  不要为五个键分别选池。没有可用应用池时先由平台管理员配置，不能拿租户池替代。
+- 注入的是应用池**共用的数据面凭据**，不含管理凭据，也不是 per-App / per-tenant 子凭据；
+  独立桶不等于独立云权限。凭据只留后端，不回显、不写日志、不交给前端。
+- 重发、重试与重部署沿用已登记的桶和存储池；改变落点地域不会自动搬桶或迁移对象。
+  租户卸载也不自动删除这个共用桶。需要迁移、清理或轮换池凭据时由平台与 App 协调。
+
+以上自动供给发生在**发布提案批准链路**。一盒 `onebox.sh add` 的直接注册路径仍须按
+`portal-dev-setup` 配好 RustFS 连接参数和桶名；不能只写这条声明就认为五键已到位。
+
+### 通用环境变量约束
+
+**平台级能力（例如日志写入）会直接出现在你的服务令牌里，不用申请、不用写进 manifest** ——
 拿到令牌就能用，你那侧只管调。
 
 **六条别踩：**
@@ -441,8 +539,8 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
   ```
 
   批准时门户把旧键在 **`descriptor.env`** 里的值搬到新键，审批屏如实显示「将沿用旧键的现有值」。
-  ⚠️ **值在 envFile 里的搬不了**（那是主机上的文件，门户连写都不写它）—— 那种情况审批屏会把这一条
-  判成「缺」，并告诉运维去把那一行改名。仍然只带键名，不带值。
+  ⚠️ **值在 envFile 里的搬不了**（门户不写主机文件）。普通条目仍判缺；带 `generate` 的条目
+  可兼容沿用文件旧名，由 App 消费，不改文件、不复制值、不生成 NEW。旧键已由平台保管则拒绝改名。
   两条写法约束：`renamedFrom` 不能等于 `key`；旧键**不能**同时还留在清单里（那等于说「它既被改掉
   又仍然必需」，提交即拒）。改名生效之后 **`renamedFrom` 留着就行** —— 它是幂等的（新键已有值就不再搬），
   而摘掉它本身是一次清单变更，会平白再进一次人工审。

package/skills/xgent-app-release/references/build-and-package.md

@@ -40,7 +40,8 @@ tar czf dist.tgz dist          # ❌ 全套在 dist/ 一层下面，拒收
 发布流程应按 [前端归档与同步验收](frontend-archive.md) 留存原始 tgz，再用 `--dist <包路径>`
 上传这份文件；重新打包目录不保证 SHA-256 相同，不能替代实际上传包的留存。
 
-其它约束：**≤64MB**（超了先查 source map 与未压缩素材）；空文件会被当成「构建没产出」拒掉，
+其它约束：单个包 **≤200 MiB**，整个上传请求 ≤256 MiB（套件批次多个 `dist__<key>` 合计也算在内；
+超了先查 source map 与未压缩素材）；空文件会被当成「构建没产出」拒掉，
 而不是当成「只发版本号」——这是有意的，否则一条坏流水线会报成功。
 
 ## 3. 不需要 CORS，但可能需要 CSP

package/skills/xgent-app-release/references/publish-api.md

@@ -128,13 +128,18 @@ curl -X POST "$XGENT_PORTAL_URL/api/market/release/<key>" \
 | 字段 | 必填 | 说明 |
 | --- | --- | --- |
 | `version` | （或 manifest.version） | 字母/数字/`. _ + -`，≤64 字符。**每次都要 bump** |
-| `dist` | | multipart 文件，`.tar.gz`，根下 `index.html`，≤64MB。省掉 = 这次不换产物 |
+| `dist` | | multipart 文件，`.tar.gz`，根下 `index.html`，≤200 MiB。省掉 = 这次不换产物 |
 | `image` | | 镜像引用。省掉 = 不换镜像 |
 | `manifest` | | `app.manifest.json` 全文（文件或 JSON 字符串）。省掉 = 只发三件（全自动档） |
 
 **这四个之外的散字段仍然直接拒**（`200 + VALIDATION_FAILED`，拒在写库之前）——
 治理变更只能经 manifest 整份提交，没有「往表单里塞一个 scopes」这条路。
 
+**请求格式与上限**：带文件（`dist`，套件批次的 `dist__<key>`）的请求必须是 `multipart/form-data`，
+产物只认文件字段；不带文件的纯元数据请求（只有 `version` / `image` / `manifest`）也可以发 JSON。
+单个包 ≤200 MiB；**整个请求 ≤256 MiB**，这是门户 HTTP 层的上限，套件批次里各成员的包是合计的，
+不能按「成员数 × 200 MiB」估。
+
 **定级唯一判据：这次提交有没有改变权限面。** manifest 里与当前 listing 相比有治理差异
 （scopes / aclManifest / dependencies / exchangeTargets / serviceScopes /
 privilegedServiceScopes / usageMetrics / serviceBaseUrl /

package/skills/xgent-app-release/references/troubleshooting.md

@@ -19,7 +19,8 @@ catalog 只收 manifest；旧版发布成功后会删归档。有 distDigest 不
 | `404` | 令牌不是为这个 `--key` 签发的（也可能该 listing 不存在——门户**故意**不区分） | 核对 `--key` 与签发时的 key 逐字相同；换一个你确定存在的 key 试同一枚令牌 |
 | `GET …/<key>/status` 返回 `404`，但同一枚令牌 whoami `200` | **这个门户上还没有只读面**（它比发布面晚一版上线），不是令牌的问题 | 见下面「`/status` 报 404 怎么分诊」。别改令牌、别重发 |
 | `200` 但 `ok:false`，说缺根 `index.html` | 打包套了一层 | 用 `tar czf x.tgz -C dist .`，不是 `tar czf x.tgz dist`；或 `--dist` 指错了一层 |
-| `200` 但 `ok:false`，说超 64MB | source map / 未压缩素材打进产物了 | `du -sh dist`，关掉 sourcemap 再看 |
+| `200` 但 `ok:false`，说「前端产物过大（>200MB）」 | 单个包超 200 MiB：source map / 未压缩素材打进产物了 | `du -sh dist`，关掉 sourcemap 再看 |
+| 上传拿不到 `{ok:…}` 响应体：连接被断开、挂到超时或返回非 200 | 整个请求超过 256 MiB（门户 HTTP 层上限，到不了业务校验）；套件批次最常见，各成员的包是合计的 | 把这次所有 `dist` / `dist__<key>` 与 manifest 的字节加起来看 |
 | `200` 但 `ok:false`，说版本号非法 | 只能字母/数字/`. _ + -`，≤64 字符 | 别把 `v1.2.3 (build 42)` 这种带空格括号的塞进去 |
 | `200` 但 `ok:false`，说属治理字段不接受散字段 | 往表单里直接塞 `scopes=...` / `aclManifest=...` 之类 | 散字段只认 `dist`/`version`/`image`/`manifest`；治理变更写进 `app.manifest.json` 用 `--manifest` 整份提交，进「发布审核」 |
 | `200` 但 `ok:false`，`PROPOSAL_PENDING` | 该 App 已有一条待审提案挡路——待审期间**任何**新提交都拒，纯 dist/version 也一样（放行会「后交先生效」） | 等平台审批，或先撤回：`DELETE …/proposals/<id>`（错误 details 里带在审提案 id） |

package/skills/xgent-app-release/references/verify-preflight.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, openSync, writeSync, closeSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -71,12 +72,31 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
       ["admin page escape", {adminPages:{platform:{route:"//evil.example",label:"x"}}}, false],
       ["admin page no zh-CN", {adminPages:{tenant:{route:"/s",label:{en:"S"}}}}, false],
       ["admin page unknown level", {adminPages:{console:{route:"/s",label:"x"}}}, false],
+      ["tenant config ok", {type:"service",scopes:["demo.read"],tenantConfig:{label:"设置",path:"/v2/policy",scopes:["demo.read"],schema:{type:"object",properties:{limits:{type:"object",properties:{wait:{type:"integer",title:"等待",default:10,unit:"秒",scale:1000},mode:{type:"select",title:"模式",options:[{value:"auto",label:"自动"}]},strict:{type:"boolean",title:"严格",default:false}}}}}}}, true],
+      ["tenant config bad scope", {type:"service",scopes:["demo.read"],tenantConfig:{label:"设置",path:"/v2/policy",scopes:["demo.write"],schema:{type:"object",properties:{wait:{type:"integer",title:"等待"}}}}}, false],
+      ["tenant config escape", {type:"service",scopes:["demo.read"],tenantConfig:{label:"设置",path:"//evil.example",scopes:["demo.read"],schema:{type:"object",properties:{wait:{type:"integer",title:"等待"}}}}}, false],
     ]) {
       writeFileSync(join(root,"app.manifest.json"),JSON.stringify({listingKey:"demo",name:"Demo",version:"1",...extra}));
       const result = spawnSync(process.execPath,[preflight,"--offline","--config","fixture.env","--key","demo","--dist","dist","--version","1","--manifest","app.manifest.json"],{cwd:root,env:{PATH:process.env.PATH},encoding:"utf8",timeout:15000});
       assert.equal(result.status,valid?0:1,label);
       passed++;
     }
+    // 单包上限与门户 MAX_DIST_BYTES 同为 200 MiB：用不可压缩内容逼近边界，199 MiB 放行、201 MiB 拒绝。
+    {
+      const blob = join(root,"dist/blob.bin");
+      const grow = (mib) => { const fd = openSync(blob,"a"); for (let i = 0; i < mib; i++) writeSync(fd,randomBytes(1024*1024)); closeSync(fd); };
+      const run = () => spawnSync(process.execPath,[preflight,"--offline","--config","fixture.env","--key","demo","--dist","dist","--version","1","--manifest","app.manifest.json"],{cwd:root,env:{PATH:process.env.PATH},encoding:"utf8",timeout:120000});
+      writeFileSync(join(root,"app.manifest.json"),JSON.stringify({listingKey:"demo",name:"Demo",version:"1"}));
+      grow(199);
+      assert.equal(run().status,0,"dist 199 MiB");
+      passed++;
+      grow(2);
+      const over = run();
+      assert.equal(over.status,1,"dist 201 MiB");
+      assert.match(over.stdout,/单包 200 MiB 上限/,"dist 201 MiB");
+      passed++;
+      rmSync(blob);
+    }
     assert.deepEqual(normalizeEmbedCsp(cases.find(c=>c[0]==="origin normalization")[1]),{imgSrc:["https://example.com"]});passed++;
     assert.throws(()=>normalizeEmbedCsp(Object.defineProperty({},"scriptSrc",{get(){throw new Error("must-not-run");}})),/accessors/);passed++;
     console.log(`exported preflight: ${passed}/0`);

package/skills/xgent-app-release/scripts/preflight.mjs

@@ -25,7 +25,7 @@ import { spawnSync } from "node:child_process";
 import { loadConfig, parseArgs, pick, warnIfProxyIgnored } from "./registry-config.mjs";
 import { normalizeEmbedCsp } from "../references/embed-csp.mjs";
 
-const MAX_BYTES = 64 * 1024 * 1024; // 门户侧上限，超了直接 VALIDATION_FAILED
+const MAX_BYTES = 200 * 1024 * 1024; // 门户单包上限（MAX_DIST_BYTES），超了直接 VALIDATION_FAILED；整个请求另有 256 MiB 上限
 const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/; // 与门户逐字一致
 const KEY_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 
@@ -133,8 +133,8 @@ if (distStat?.isDirectory()) {
       const size = statSync(out).size;
       const mb = (size / 1024 / 1024).toFixed(1);
       const entries = readdirSync(dist).length;
-      if (size > MAX_BYTES) err(`打包后 ${mb}MB，超过门户 64MB 上限 —— 先查 source map / 未压缩素材是不是打进来了`);
-      else ok(`打包 ${mb}MB · ${entries} 个顶层条目`);
+      if (size > MAX_BYTES) err(`打包后 ${mb} MiB，超过门户单包 200 MiB 上限 —— 先查 source map / 未压缩素材是不是打进来了`);
+      else ok(`打包 ${mb} MiB · ${entries} 个顶层条目`);
     }
   } finally {
     rmSync(temp, { recursive: true, force: true });
@@ -345,6 +345,45 @@ if (!manifestPath) {
             err(`manifest.adminPages.${level}.label 必须是非空字符串，或带 "zh-CN" 的多语对象`);
         }
     }
+    /* ③d tenantConfig：service 的受限动态配置 schema。门户提交面会做完整校验，这里先挡住常见形状错误。 */
+    if (mf.tenantConfig !== undefined && mf.tenantConfig !== null) {
+      const tc = mf.tenantConfig;
+      const textOk = (value) => typeof value === "string" ? !!value.trim() : isObj(value) && typeof value["zh-CN"] === "string" && !!value["zh-CN"].trim();
+      if (!isObj(tc) || Array.isArray(tc)) err(`manifest.tenantConfig 必须是 { label, path, scopes, schema }`);
+      else {
+        if (mf.type !== "service") err(`manifest.tenantConfig 只能由 type=service 声明`);
+        if (!textOk(tc.label)) err(`manifest.tenantConfig.label 必须是非空字符串或带 zh-CN 的多语对象`);
+        if (typeof tc.path !== "string" || !tc.path.startsWith("/") || tc.path.startsWith("//") || /[?#]/.test(tc.path) || /(^|\/)\.\.(\/|$)/.test(tc.path))
+          err(`manifest.tenantConfig.path 必须是不带 query / fragment 的同源绝对路径`);
+        if (!Array.isArray(tc.scopes) || !tc.scopes.length || tc.scopes.some((scope) => typeof scope !== "string" || !scope.trim()))
+          err(`manifest.tenantConfig.scopes 必须是非空字符串数组`);
+        else if (Array.isArray(mf.scopes)) for (const scope of tc.scopes) if (!mf.scopes.includes(scope)) err(`manifest.tenantConfig.scopes 的「${scope}」未声明在 listing scopes 中`);
+        const walk = (node, where, depth) => {
+          if (!isObj(node) || Array.isArray(node)) { err(`${where} 必须是对象`); return; }
+          if (depth > 4) { err(`${where} 嵌套超过 4 层`); return; }
+          if (node.type === "object") {
+            if (!isObj(node.properties) || Array.isArray(node.properties) || !Object.keys(node.properties).length) { err(`${where}.properties 必须是非空对象`); return; }
+            for (const [key, child] of Object.entries(node.properties)) {
+              if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key) || ["__proto__", "prototype", "constructor"].includes(key)) err(`${where}.properties 的键「${key}」非法`);
+              walk(child, `${where}.properties.${key}`, depth + 1);
+            }
+            return;
+          }
+          if (!["integer", "number", "select", "boolean"].includes(node.type)) { err(`${where}.type 只支持 integer / number / select / boolean / object`); return; }
+          if (!textOk(node.title)) err(`${where}.title 必须是非空字符串或带 zh-CN 的多语对象`);
+          if (node.description !== undefined && !textOk(node.description)) err(`${where}.description 形状非法`);
+          if (["integer", "number"].includes(node.type)) {
+            for (const field of ["default", "scale", "minimum", "maximum"]) if (node[field] !== undefined && (typeof node[field] !== "number" || !Number.isFinite(node[field]))) err(`${where}.${field} 必须是有限数字`);
+            if (node.scale !== undefined && node.scale <= 0) err(`${where}.scale 必须是正数`);
+            if (node.unit !== undefined && !textOk(node.unit)) err(`${where}.unit 形状非法`);
+          } else if (node.type === "select") {
+            if (!Array.isArray(node.options) || !node.options.length) err(`${where}.options 不能为空`);
+            else for (const option of node.options) if (!isObj(option) || typeof option.value !== "string" || !option.value.trim() || !textOk(option.label)) err(`${where}.options 每项必须是 { value, label }`);
+          } else if (node.default !== undefined && typeof node.default !== "boolean") err(`${where}.default 必须是布尔值`);
+        };
+        walk(tc.schema, "manifest.tenantConfig.schema", 0);
+      }
+    }
     /* ③b requiredEnvNotes：只能给 requiredEnv 里的键写说明，非空、≤200 字（与门户同口径）。 */
     if (mf.requiredEnvNotes !== undefined) {
       const declaredEnv = new Set((Array.isArray(mf.requiredEnv) ? mf.requiredEnv : [])

package/skills/xgent-image-push/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: xgent-image-push
 description: 用于 App 发版时构建、推送镜像到私有 Harbor，配置 CI 推送或排查 docker push 失败。仓库地址从本地配置读取；推送前检查链路、架构、tag 与保留策略。
+when_to_use: "用户会说「推个镜像」「docker push 被拒」「镜像架构不对」时。"
 ---
 
 # 推镜像到私有仓库

package/skills/xgent-init/SKILL.md

@@ -3,6 +3,7 @@ name: xgent-init
 metadata:
   internal: true
 description: 用于在 XGENT 出仓 App 仓库初始化或补齐 AGENTS.md、PRODUCT.md、DESIGN.md；已有文件不覆盖。保留 Portal 产品边界与设计规范。
+when_to_use: "用户会说「初始化这个 XGENT 仓库」「补上 PRODUCT.md 和 DESIGN.md」时。"
 ---
 
 # xgent-init · 出仓 App 的 Agent、产品与设计上下文

package/docs/claude-context-goal-guard.md

@@ -1,124 +0,0 @@
-# Claude Code goal 上下文收尾提醒
-
-当前会话的 `/goal` 仍 active，且本地估算上下文使用率**严格超过阈值**（默认 70%，可配置）时，本 hook 提醒 agent 收尾：停止开始新的实质任务，按任务已有约定更新进度并交接。回合结束时由 Stop hook 结束回合，Claude Code 原生把 goal 置为「Goal paused」，再由你自己新开对话（或 `/clear`）接续。恰好等于阈值不触发。hook 只读当前会话记录，不写任何文件，也不清除、转移或恢复 goal。
-
-## 兼容范围与限制
-
-- 已验证：Claude Code **2.1.288** 交互式 CLI、macOS arm64、Node v25.2.1（安装器要求 Node ≥ 18）。完整验收见 [M1 记录](plan/claude-context-goal-guard.records/M1.md)、[M2 记录](plan/claude-context-goal-guard.records/M2.md)、[M3 记录](plan/claude-context-goal-guard.records/M3.md)、[M4 记录](plan/claude-context-goal-guard.records/M4.md)。新版本不自动视为兼容。
-- 未验证：`claude -p` 非交互模式、桌面应用、Remote Control、云端会话。
-- 只保护主会话；子 agent 内的事件直接跳过。
-- 上下文窗口：hook 输入和会话记录都不含窗口大小，脚本只认下表中验证过的模型。其他模型，或设置了 `CLAUDE_CODE_DISABLE_1M_CONTEXT`、`DISABLE_COMPACT`、`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 任一变量时，报告「检测不可用」，不触发。
-
-| 模型 id（会话记录中的 `message.model`） | 窗口 |
-| --- | --- |
-| `claude-opus-5-5` | 1,000,000（是否选 `[1m]` 相同） |
-| `claude-sonnet-5-5` | 1,000,000（是否选 `[1m]` 相同） |
-| `claude-haiku-4-5-20251001` | 200,000 |
-
-窗口还会因账号与服务端能力而不同，上表只在验证时用的 Claude Max 账号上核对过。启用前用 statusLine 自查：statusLine 命令的 stdin JSON 里 `model.id` 和 `context_window.context_window_size` 应与上表一致，不一致时不要启用。
-
-### 用量口径
-
-```text
-used    = input_tokens + cache_creation_input_tokens + cache_read_input_tokens   # 取最新主链 assistant 记录；有 iterations 时取最后一项
-trigger = used * 100 > window * threshold     # threshold 默认 70，见「阈值配置」
-```
-
-与 statusLine 的 `used_percentage` 同口径，不计 output。会话记录异步写入，可能落后一条消息。自动压缩后，出现新统计前不判定。
-
-Claude Code 界面右下角的「NN% context used」按扣除输出预留后的有效窗口计算，读数比本 guard 高。例如 Haiku 4.5 实测 155,100 token 时，界面显示 86%（≈ 155,100 / 180,000），guard 计为 78%。
-
-## 安装
-
-### 使用 install
-
-```sh
-# 默认不安装 guard；从本仓库源码显式安装
-# 发布到 npm 后可用 npx @xgent-ai/skills install --claude-context-goal-guard
-node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard
-```
-
-交互和非交互安装均默认跳过 guard，不再询问。仅在显式传入 `--claude-context-goal-guard` 或 `--claude-context-goal-guard-threshold=N` 时安装；`--no-claude-context-goal-guard` 显式跳过并保留已有 guard，不能与安装参数同时使用。这个选项与 `--providers`、`--no-phoenix-ui`（旧 `--no-impeccable` 为弃用别名）、`--xgent-init` 及 Codex guard 的选项互不影响。
-
-安装器会：
-
-1. 复制脚本到目标项目 `.claude/hooks/context-goal-guard.js`；
-2. 把 `PostToolBatch` 与 `Stop` 两个 handler 合并进个人的 `.claude/settings.local.json`（不进共享的 `settings.json`），command 为 `node "$CLAUDE_PROJECT_DIR/.claude/hooks/context-goal-guard.js"`，超时 5 秒；
-3. 保留其他事件、handler、matcher 和顶层字段，重复安装只更新 guard。非法 JSON 默认报错，`--force` 先备份为 `.bak` 再覆盖；合法 JSON 但结构不认识时报错，需要手动修复。
-
-### 阈值配置
-
-阈值写在 handler 命令末尾：`--threshold N`，N 为 1–99 的整数百分比；不带参数时为 70。与 Codex 版（默认 65）各自独立。
-
-```sh
-# 安装时指定（同时表示安装，不再询问）
-node bin/xgent-skills.js install /absolute/path/to/project --claude-context-goal-guard-threshold=75
-```
-
-安装器总是把阈值明确写进两个 handler 的 command，在 `/hooks` 里看得到。之后重装时不给这个 flag，就沿用已装的值。也可以直接改 `.claude/settings.local.json` 里两条 command 末尾的数字，两条要一致。参数无效时（如 `0`、`100`、`6.5`）guard 不猜测数值，按「检测不可用」处理。
-
-阈值不宜太高：收尾本身还要消耗上下文，而 Claude Code 在接近有效窗口上限时会自动压缩（见上面的界面读数说明）。建议不超过 75%。
-
-### 手动部署
-
-```sh
-mkdir -p "/absolute/path/to/project/.claude/hooks"
-cp hooks/claude/context-goal-guard.js "/absolute/path/to/project/.claude/hooks/context-goal-guard.js"
-```
-
-把 [设置示例](../hooks/claude/settings.example.json) 里的两组 handler（默认 `--threshold 70`，按需修改）**追加**到目标项目 `.claude/settings.local.json` 已有的 `PostToolBatch`、`Stop` 数组，不要用示例覆盖整个文件。Claude Code 的 hook 运行环境里必须能找到 `node`。
-
-## 信任与生效确认
-
-1. 运行 `claude --version`，确认是上面验证过的版本。
-2. 从目标项目启动 Claude Code，信任该工作区。工作区未被信任时，设置里的 hook 和 `/goal` 都不可用。
-3. 输入 `/hooks`，确认 `PostToolBatch` 和 `Stop` 下各有一条 `[Local] node "$CLAUDE_PROJECT_DIR/.claude/hooks/context-g…`，其他 hooks 仍在。
-4. 先用测试 goal 走一遍：越过阈值后应看到提醒，回合结束后出现「Goal paused · a hook ended the turn」。
-
-## goal 条件怎么写
-
-guard 不管进度写到哪里，提醒只要求 agent 按任务**已有约定**更新进度。最好让 goal 条件指向一份带进度区的计划，例如：
-
-```text
-/goal 按 docs/plan/xxx.md 开发：全部里程碑完成并回写进度
-```
-
-没有计划文件时，agent 会在最终回复里给出交接摘要，不会新建文件。
-
-## 触发后会看到什么
-
-1. 越线后的每个工具批次，agent 都会收到同一条收尾提醒：停止新工作，把手上的工作处理到可交接，更新进度，停止后台任务，写明「因上下文收尾而暂停，工作未完成」。
-2. agent 第一次结束回合时，guard 可能先请求补做收尾。界面上显示为「Stop hook error: 上下文估算使用率 NN% …」，这是正常的继续请求，不是故障。
-3. 下一次结束回合时，guard 结束回合，界面显示 guard 的说明和「Goal paused · a hook ended the turn · send a message to continue」。goal 评估器会照常判定「未达成」，但不会再自动续跑。
-
-提醒没有强制力。在 goal 的自动续轮里越线时，agent 可能只收到一次提醒、甚至一次都没收到就被暂停。交接不完整时，在原会话发一句「按上下文收尾提醒补交接」，回合结束后会再次暂停。
-
-## 接续
-
-在同一项目目录新开对话，或在原会话输入 `/clear`。告诉 agent 计划路径（或粘贴交接摘要），再重新设置 `/goal`。新对话和 `/clear` 后都**不继承** goal：不重新设置，guard 就不会触发。
-
-原会话的 goal 只是暂停：在原会话里发任何消息都会恢复 goal，guard 随即再次收口；`claude --resume` 也会恢复 goal（不会自动运行）。不再需要时，在原会话 `/goal clear`。
-
-### 后台任务
-
-暂停时如果还有后台命令或子 agent 在跑，它们完成时的通知（以及 goal 的 idle check-in）会唤醒会话。guard 会先请求一次收尾，在请求里列出仍在运行的任务，再结束回合；进度不会前进，但每次唤醒多花两次简短的模型调用。这种被唤醒后再结束的回合，界面可能显示「Goal not yet met… continuing」，状态栏仍是「/goal active」，没有「Goal paused」提示；实测此后约 7 分钟内没有自动回合。
-
-## 停用
-
-从 `.claude/settings.local.json` 删除 command 含 `context-goal-guard.js` 的两个 handler，保留其他 hooks，再删除 `.claude/hooks/context-goal-guard.js`。实测会话运行中修改后，`/hooks` 数秒内就不再列出它们；保险起见仍建议重启会话。已暂停的 goal 不受影响。
-
-不要用 `disableAllHooks`：它会连 `/goal` 一起禁用。
-
-## 排查
-
-guard 只在 **Stop** 时显示告警，不会在每个工具批次刷屏。告警格式为「context goal guard 检测不可用：<原因>」：
-
-| 原因 | 处理 |
-| --- | --- |
-| 模型 `X` 的上下文窗口未经验证 | 换用上表中的模型，或停用 guard；补表需要先在同环境核对 statusLine 的窗口 |
-| 设置了改变上下文窗口的环境变量 `X` | 取消该变量，或停用 guard |
-| 无法读取会话记录 / hook 输入缺少会话记录路径 | 核对 Claude Code 版本；持续出现时停用 guard |
-| 用量统计格式未知 | Claude Code 的会话记录格式变了，停用 guard 并等待重新验证 |
-| 阈值参数无效 | 把两条 command 末尾改为 `--threshold` 加 1–99 的整数，或重新运行安装器 |
-
-检测不可用时，guard 不提醒、不结束回合，也不显示 0%。