@xgent-ai/skills 0.1.0 → 0.4.0

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

@@ -0,0 +1,124 @@
+# 排查速查
+
+**跨平台同步报 DIST_ARCHIVE_MISSING，尤其多个应用都缺包**：按
+[前端归档与同步验收](frontend-archive.md) 核对发布时点、服务端保留逻辑与实际上传包的留存。
+catalog 只收 manifest；旧版发布成功后会删归档。有 distDigest 不代表原始包仍在。
+
+先分清事故落在哪一层——**发不出去** / **发出去了但页面坏** / **发出去了但线上没变**。
+三层的成因不重叠，混着猜会很久。
+
+**已审批、后端 ready，仍打不开公开页或画布**：还要核验网关与业务层，见
+[public-delivery.md](public-delivery.md)。标准 /svc 可以承载正式公开 HTML，但 App 必须
+适配所有外部路径；publicEntrypoints 不创建门户根级路由；connectSrc 不放行脚本/字体。
+
+## A. 发不出去（命令报错）
+
+| 症状 | 多半原因 | 怎么确认 |
+| --- | --- | --- |
+| `401` | 令牌无效 / 已吊销 / 已过期；或压根没带 `Authorization: Bearer xrel_…` | `whoami`。门户每次调用实时查库，所以「昨天还能发」不构成反证 |
+| `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`，说版本号非法 | 只能字母/数字/`. _ + -`，≤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） |
+| `200` 但 `ok:false`，说没有部署描述 | 带了 `--image`，但该 App 还没被平台管理员配 `deployDescriptor` | 纯前端 App 本来就不该带 `--image`，去掉即可；真是新后端就在 manifest 里声明 `deployDescriptor` 随提案提交审核 |
+| `npx @xgent/release-cli` 取不到（`E404 … registry.npmjs.org/@xgent%2frelease-cli`） | **CLI 自己就在私有包仓上**，而这个 repo 的 `.npmrc` 没配 `@xgent:registry` —— 公共 npm 上当然没有 | `npm config get @xgent:registry`，是 `undefined` 就 `node "$SKILL_DIR/scripts/npm-token.mjs" --npmrc >> .npmrc` 再重试（SKILL.md 第 0 步）。**只有**换令牌这步本身报 `NPM_REGISTRY_NOT_CONFIGURED`（平台侧没配）才用 `curl` 兜底，能力完全等价（见 `publish-api.md` §2） |
+| App 代码 `bun install` / `npm install` 装 `@xgent/*` 报 E404 / 401，或私有仓上没有要的那一版 | E404 指向 `registry.npmjs.org` ⇒ `.npmrc` 没配；401 ⇒ 只读令牌过期（≤12 h）；版本不存在 ⇒ 那一版还没发布 | 前两种回 SKILL.md 第 0 步（没有 `.xgent-registry.env` 就停下，请开发者去「开发者应用」生成配置文件）；版本不存在就停下找平台团队发布。**任何一种都不许 vendor**：不拷产物或源码进仓、不用 `file:` / `link:` / tar 依赖 |
+| 缺少应用标识 | 没传 `--key`，配置文件里也没有 `LISTING_KEY` | 二选一，见 `publish-api.md` §0 |
+| 缺少发布令牌 / 令牌形状不对 | 没设 `XGENT_RELEASE_TOKEN`、也没传 `--token`；或把别的令牌拿来了 | 令牌以 `xrel_` 开头。**别写进配置文件**——CLI 会告警并忽略 |
+| 卡几分钟后 `fetch failed` / 上传超时，产物只有一两 MB | **本机配了代理，而 Node 内置 `fetch` 不读它**——直连跨境上行实测约 10 KB/s | 环境里有 `HTTPS_PROXY` / `HTTP_PROXY` 就是它。升到 `@xgent/release-cli` ≥0.6.0（检测到代理会带 `NODE_USE_ENV_PROXY=1` 重启自身）；Node 既不是 ≥22.21 也不是 ≥24 时按 `publish-api.md` §2 用 curl 兜底 |
+| `门户网关返回 502`（或任何 ≥500） | **传输层故障，不是内容被拒**——反代/网关把连接切了，门户那边没留下任何痕迹（无提案行、无审计、产物未动） | 看 CLI 打出的已传字节与实测速率：速率低得离谱就是上面那条代理问题；速率正常则是门户侧的事，带上时间点找平台管理员 |
+| `tar 不可用` | 构建镜像太精简 | 装 tar，或自己打好包用 `--dist dist.tgz` 传现成的 |
+
+### `/status` 报 404 怎么分诊
+
+两种 404 的响应体**一字不差**（都是 `{"ok":false,"error":{"code":"NOT_FOUND","message":"路由不存在"}}`）——
+门户是**故意**让「令牌不属于你」和「这条路由不存在」长得一样的，免得令牌变成探测别人 App
+是否存在的工具。所以**别对着 404 的文案猜**，用同一枚令牌先打一次 whoami：
+
+```bash
+H="authorization: Bearer $XGENT_RELEASE_TOKEN"
+curl -s -o /dev/null -w 'whoami %{http_code}\n' -H "$H" "$XGENT_PORTAL_URL/api/market/release/<key>"
+curl -s -o /dev/null -w 'status %{http_code}\n' -H "$H" "$XGENT_PORTAL_URL/api/market/release/<key>/status"
+```
+
+| whoami | `/status` | 结论 |
+| --- | --- | --- |
+| `200` | `404` | 这个门户**没有**只读面（版本旧）。令牌没问题，发布照发 |
+| `404` | `404` | 令牌不是这个 key 签发的，或该 listing 不存在 |
+| `401` | `401` | 令牌本身无效 / 已吊销 / 已过期 |
+
+**没有只读面时怎么验收**：`publish` 的返回体本身就带 `version` / `distDigest` / `distFiles` /
+`imageChanged` / `redeployQueued`——「产物落的是哪一份」这半边一点不缺，照常报告。缺的只有
+「容器到底换没换」，那半边只能找平台管理员看「服务部署」面板，或直接压你自己 App 的健康检查。
+`--wait` / `--wait-review` 同理会失效（它们就是在轮询这个面），**别把它当成保险还照绿放行**。
+
+## B. 发出去了，但页面坏
+
+| 症状 | 多半原因 |
+| --- | --- |
+| **iframe 白屏，控制台一片 404** | `base` 没设成 `/apps/<key>/` —— **最常见的一种**。资源请求打到了站点根 |
+| 首页能开，**刷新二级页面就 404** | 客户端路由的 basename 没跟着走子路径 |
+| 某个功能点了没反应，本地却正常 | 产物里残留 `localhost:53xx`，或直连了未在 `embedCsp.connectSrc` 里声明的外部源 —— 生产 CSP 静默拦掉。看浏览器控制台的 CSP 报错 |
+| 页面在，但调后端全失败 | 不是 CORS（前端从不直连后端，请求走宿主 postMessage 代理）。查 SDK 握手、`callService` 的 key、以及该 App 在这个租户里装没装 |
+| `/apps/<key>/` 打不开但发布明明成功 | 产物存储侧的事，自己这边查不了 —— 带上本次的 `distDigest` 找平台管理员 |
+| 发布成功但看到的是旧页面 | 浏览器/CDN 缓存。硬刷新；仍旧则对比控制台上的 `distDigest` 与本次返回值 |
+
+**B 类问题里最值钱的一句话**：`✓ 已发布` 只证明产物落库了，不证明页面能用。
+所以流程的最后一步是在浏览器里真打开一次——这一步没做就别报「发布完成」。
+
+## C. 发出去了，但线上没变
+
+**先跑 `npx @xgent/release-cli status --key <key>`**——C 类的几乎每一条它都能直接回答：
+线上是哪一版、实际在跑哪个镜像、最近一条部署任务成没成、失败原因是什么。
+
+这个面较新，**门户上没有它时会 `404`**（先按 A 类那条分诊，别当成发布失败）。那种情况下
+下面整张表都只能拿去问平台管理员——你手上只剩 `publish` 的返回体和浏览器。
+
+| 症状 | 多半原因 |
+| --- | --- |
+| 换了 `--image`，容器还是旧的 | 用 `status --proposal-id <id>` 看本次 delivery.backend 与失败阶段；可能是镜像、迁移或健康失败。旧容器已被替换时不保证旧服务仍可用 |
+| `status` 显示任务还在 `queued`/`running` | 就是还没轮到/还没跑完。发布时加 `--wait` 就不用手动盯 |
+| 提案一直 `pending`，`--wait` 却早早退出 0 | **仍保留提交与审批分离语义**：`--wait` 等获批后的本次交付。要卡在审批上用 `--wait-review`；平台管理员在提案落成时已收到通知，不必催 |
+| 审批屏说某个库 / Redis 的键「缺」 | 这个键不叫约定名（`<PREFIX>_DATABASE_URL` / `REDIS_CONN_STRING`），平台自动供给不到 ⇒ 只能人工点一下「从平台服务取值」。改成约定名后下次就零手填（预检会提前 warn 这一条） |
+| 同一个 tag 重推了，门户没反应 | tag 不可变是硬约定：引用没变**根本不排任务**（`status` 里看不到新任务就是这个）。新版本必须新 tag；真要按原样重建只能找平台管理员点面板的「重新部署」 |
+| 版本号发上去了，过一阵又变回旧值 | 该 key 是**门户仓内 App**（清单定义在门户代码里），version 随门户部署被等值对齐回定义值——仓内 App 不走自助发版面。外部 App 的清单事实源在你仓，不存在这个症状；真遇到就是有人在门户控制台手改过，找平台管理员对账 |
+| 发布成功、版本也对，但应用市场/租户侧看不到这个 App | listing 被平台**下架**（delisted）。发布刻意不改上下架状态——上下架归平台，找平台管理员重新上架 |
+| 带 `--manifest` 提交，返回 `ok:true`，但线上一字没变 | 这次提交里有**治理变更** ⇒ 落成待审提案，批准前库里一字不动（`status` 的最近一条提案是 `pending`）。最容易被忽略的一个触发源是 `helpEntry` 写成了外站文档 `https://…`——外链是审核档，改成 App 内路由 `"/help"` 才是自动档 |
+| 控制台上 `version` 与产物对不上 | 正常情况下不可能——两者同一次落库。若真发生，说明有人从别的路径改过 version，带 `distDigest` 去对账 |
+
+## D. 发上去也跑起来了，但跨应用调用 401
+
+症状：你的 App 去 `POST /oauth/token` 换票，门户回 `SECRET_INVALID`；或者界面上只写着
+**「跨应用授权缺失或未开启」**——那句话说的是授权，而最常见的真因不是授权。
+
+| 症状 | 多半原因 | 怎么确认 |
+| --- | --- | --- |
+| `SECRET_INVALID` | `<PREFIX>_APP_SECRET` 两边漂了：容器里跑的是**手填**的那一份，门户布出去的是**平台保管**的那一份的哈希 | 问平台管理员：该 App 的 `deployDescriptor.env` 或 `envFile` 里是不是手填了这个键。有就删掉它——删掉之后指纹变化会自动排一次换版，平台保管的那份就注进去了 |
+| `EXCHANGE_NOT_ALLOWED` | 清单里没声明要调的那个目标 App | 在 `app.manifest.json` 的 `exchangeTargets` 里补上目标 key，随 `--manifest` 提交（这是治理档，要等人工审批） |
+| 闸说缺 `<PREFIX>_APP_SECRET`，提案一直批不了 | 你在 `requiredEnv` 里写了这个键，却没声明 `exchangeTargets` | 平台不会为一个不做跨应用调用的 App 生成这枚密钥。补 `exchangeTargets`，或把这个键从 `requiredEnv` 去掉。**别让平台管理员手填一个值来让闸放行**——那正好制造上面第一行那个故障 |
+
+这枚密钥的完整口径见 SKILL.md「`<PREFIX>_APP_SECRET`：跨应用交换的发起方密钥」。一句话：
+**键名归你，值归平台，明文只在批准那一刻给审批人看一次。**
+
+## 一条通用的分诊起手式
+
+在 App repo 根目录执行；`SKILL_DIR` 表示本 skill 的 `SKILL.md` 所在目录（本文件的上一级）。
+
+```bash
+node "$SKILL_DIR/scripts/preflight.mjs" --key <key> --dist dist --version <v>   # 发之前
+npx @xgent/release-cli status --key <key>                                  # 发之后
+```
+
+前者一次性覆盖 A 类的绝大多数与 B 类的头两条，后者覆盖 C 类（`status` 在这个门户上不存在
+就跳过它，不要为了让它绿而改令牌或改 key）。**先跑它再猜**——
+这些成因的共同点是 `tsc` / lint / 单测全都发现不了，靠读代码找它们非常慢。
+
+## 新交付状态与旧门户
+
+新版本与能力前提见 [公开面与交付确认](public-delivery.md)。纯前端也须等网关。
+`delivery.state=unknown` 表示证据不足，不能报成功；superseded 表示本次目标已被取代，查询后续提案。
+网关失败请平台管理员重试网关配置，不必重提清单或更换镜像。旧门户无 delivery 会明确提示无法核验网关。
+CSP 扩展语法通过但服务器拒绝新指令时，先确认 strict 与 v2 是否由平台受控启用，不能自行放宽策略。

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

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { normalizeEmbedCsp } from "./embed-csp.mjs";
+
+export const cases = [
+  ["omitted", undefined, true], ["clear", null, true], ["empty", {}, true],
+  ["all directives", Object.fromEntries(["connectSrc","scriptSrc","styleSrc","fontSrc","imgSrc","mediaSrc"].map(k=>[k,["https://cdn.example.com"]])), true],
+  ["websocket connect", {connectSrc:["wss://events.example.com"]}, true],
+  ["local schemes connect", {connectSrc:["blob:","data:"]}, true],
+  ["local scheme with payload", {connectSrc:["data:,x"]}, false],
+  ["alias", {platformSources:{scriptSrc:["jsCdn"],styleSrc:["jsCdn"],fontSrc:["jsCdn"],connectSrc:["jsCdn"]}}, true],
+  ["origin normalization", {imgSrc:[" https://EXAMPLE.com:443/ ","https://example.com"]}, true],
+  ["empty arrays", {scriptSrc:[],platformSources:{scriptSrc:[]}}, true],
+  ["unknown field", {frameAncestors:["https://example.com"]}, false],
+  ["unknown alias", {platformSources:{scriptSrc:["other"]}}, false],
+  ["unsupported alias directive", {platformSources:{imgSrc:["jsCdn"]}}, false],
+  ["wrong collection", {scriptSrc:"https://example.com"}, false],
+  ["wrong source", {scriptSrc:[null]}, false],
+  ...["https://*.example.com","https://example.com/script.js","https://example.com?x=1","https://example.com#x",
+    "https://user:private@localhost","unsafe-inline","'unsafe-eval'","data:","blob:","http://example.com",
+    "http://localhost:8080","wss://example.com","https:example.com","https://example.com\n","https://example.com;"].map((value,i)=>[`invalid origin ${i}`,{scriptSrc:[value]},false]),
+];
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = mkdtempSync(join(tmpdir(),"release-preflight-fixture-"));
+  const preflight = resolve(dirname(fileURLToPath(import.meta.url)),"../scripts/preflight.mjs");
+  let passed = 0;
+  try {
+    mkdirSync(join(root,"dist"));
+    writeFileSync(join(root,"dist/index.html"),'<script src="/apps/demo/main.js"></script>');
+    writeFileSync(join(root,"dist/main.js"),'console.log("fixture")');
+    writeFileSync(join(root,"fixture.env"),"LISTING_KEY=demo\n");
+    for (const [label,value,valid] of cases) {
+      const manifest = {listingKey:"demo",name:"Demo",version:"1",...(value===undefined?{}:{embedCsp:value})};
+      writeFileSync(join(root,"app.manifest.json"),JSON.stringify(manifest));
+      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);
+      if (value!==undefined) assert.match(result.stdout,/能力门未核验/,label);
+      assert.ok(!result.stdout.includes("private@localhost"),"不回显非法来源中的凭据");
+      passed++;
+    }
+    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`);
+  } finally { rmSync(root,{recursive:true,force:true}); }
+}

package/skills/xgent-app-release/scripts/npm-token.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * xgent-app-release · 换一枚私有包只读令牌
+ *
+ *   node npm-token.mjs            # 打印 export XGENT_NPM_AUTH_TOKEN='…'（可 eval）
+ *   node npm-token.mjs --raw      # 只打印令牌本体（管道用）
+ *   node npm-token.mjs --npmrc    # 打印可直接追加进 .npmrc 的三行
+ *   node npm-token.mjs --check    # 只体检：能不能换到、还剩多久，不打印令牌
+ *
+ * `@xgent/{release-cli,shared,portal-sdk,portal-server-sdk,portal-ui}` 都装在私有仓上 —— **发版用的 CLI 本身也在**，
+ * 所以 `.npmrc` 没配好时 `npx @xgent/release-cli` 第一条就 E404。你**不需要**任何云账号或 CLI：
+ * 用已有的发布令牌（`XGENT_RELEASE_TOKEN`，就是发版那枚）向门户换一枚 ≤12 h 的
+ * **只读**令牌即可。门户持那把云凭据，轮换时你这边零改动。
+ *
+ * 取值优先级：命令行参数 > 环境变量 > 本地配置文件（`.xgent-registry.env` 等）。
+ * 令牌**只走 stdout**，不落盘、不进日志；诊断信息一律走 stderr，所以
+ * `eval "$(node npm-token.mjs)"` 与 `node npm-token.mjs --raw > /dev/null` 都是安全的。
+ *
+ * 零依赖，纯 Node ≥18（fetch 内置）。可以整个文件拷进任何 App 仓。
+ * 退出码：换到 → 0；配置缺失/被拒/不可达 → 1。
+ */
+import { loadConfig, parseArgs, resolveRelease, warnIfProxyIgnored } from "./registry-config.mjs";
+
+const args = parseArgs(process.argv.slice(2), ["raw", "npmrc", "check", "help"]);
+if (args.help) {
+  console.error("用法: node npm-token.mjs [--raw|--npmrc|--check] [--key <listingKey>] [--portal <url>] [--config <path>]");
+  process.exit(0);
+}
+
+const cfg = loadConfig(args.config);
+const { key, portal, token } = resolveRelease(args, cfg);
+
+const die = (msg, ...hints) => {
+  console.error(`✗ ${msg}`);
+  for (const h of hints) console.error(`  → ${h}`);
+  process.exit(1);
+};
+
+// 三样都缺 = 压根没有配置文件：指向唯一的来源，别让人（或 agent）去找别的办法装包。
+const GET_CONFIG = "去门户「开发者应用」› 你的应用 › 凭证 › 生成配置文件，把 .xgent-registry.env 放到仓根后重跑";
+const NO_APP_YET = "开发者应用里还没有这个应用 ⇒ 先「申请建立应用」，平台管理员批准后才能生成";
+const NO_VENDOR = "拿到之前停下：不要把 @xgent/* 拷进 vendor/ 或改用 file:/tar 依赖";
+if (!key && !portal && !token) die("没找到 .xgent-registry.env（也没有对应的环境变量）", GET_CONFIG, NO_APP_YET, NO_VENDOR);
+if (!key) die("缺少 LISTING_KEY", "在 .xgent-registry.env 里写 LISTING_KEY=<你的应用标识>，或用 --key 传");
+if (!portal) die("缺少门户地址", "在 .xgent-registry.env 里写 TARGET_XGENT_PLATFORM=<门户地址>，或用 --portal 传");
+if (!token) die("缺少发布令牌", GET_CONFIG, NO_APP_YET, NO_VENDOR);
+
+warnIfProxyIgnored();
+
+const url = `${portal}/api/market/release/${encodeURIComponent(key)}/npm-token`;
+let res;
+try {
+  res = await fetch(url, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+    signal: AbortSignal.timeout(30_000),
+  });
+} catch (e) {
+  die(`连不上门户：${e?.message ?? e}`, `确认 ${portal} 可达（公司网络 / VPN）`, "稍后重试；这条链路超时不代表令牌有问题");
+}
+
+if (res.status === 401) die("发布令牌无效或已失效（401）", "去门户「开发者应用」› 你的应用 › 凭证 重新生成配置文件");
+if (res.status === 404) die(`门户上没有 ${key} 这个应用，或令牌绑的是别的应用（404）`, "核对 LISTING_KEY 与令牌是否同一个应用");
+if (res.status === 429) die("触发限流（429）", "稍等一分钟再试；CI 里别在每个 job 都换一次，换一次传下去");
+
+const body = await res.json().catch(() => null);
+if (!res.ok || !body) die(`门户返回 ${res.status}`, "把这一行贴给平台管理员");
+
+if (body.ok === false) {
+  const code = body.error?.code ?? "UNKNOWN";
+  const msg = body.error?.message ?? "";
+  if (code === "NPM_REGISTRY_NOT_CONFIGURED")
+    die("门户还没配置私有包仓库凭据", "让平台管理员去「控制台 › 平台设置 › 私有包仓库」填一次", "这不是你这边的问题，无需改任何配置");
+  if (code === "NPM_REGISTRY_UNAUTHORIZED")
+    die("门户持有的仓库凭据被拒了", "让平台管理员检查「私有包仓库」设置里的凭据是否过期", "这不是你这边的问题");
+  if (code === "NPM_REGISTRY_UNAVAILABLE")
+    die("私有包仓库暂时不可达", "过几分钟重试", "CI 里给这一步加一次重试即可");
+  die(`${code}${msg ? `：${msg}` : ""}`);
+}
+
+const { registry, scopes, token: authToken, expiresAt } = body.data ?? {};
+if (!authToken || !registry) die("门户返回的内容不完整", "把这一行贴给平台管理员");
+
+const mins = Math.max(0, Math.round((Date.parse(expiresAt) - Date.now()) / 60000));
+console.error(`✓ 已换到只读令牌，有效期约 ${Math.floor(mins / 60)} 小时 ${mins % 60} 分（至 ${expiresAt}）`);
+
+if (args.check) process.exit(0);
+
+if (args.raw) {
+  console.log(authToken);
+} else if (args.npmrc) {
+  // registry 形如 https://<host>/npm/<repo>/ —— .npmrc 的 //<host>/<path>:_authToken 要去掉协议。
+  const bare = registry.replace(/^https?:/, "");
+  for (const s of scopes ?? ["@xgent"]) console.log(`${s}:registry=${registry}`);
+  console.log(`${bare}:_authToken=${authToken}`);
+  console.log(`${bare}:always-auth=true`);
+} else {
+  console.log(`export XGENT_NPM_AUTH_TOKEN='${authToken}'`);
+  console.log(`export XGENT_NPM_REGISTRY='${registry}'`);
+}

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

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * xgent-app-release · 发布预检
+ *
+ *   node preflight.mjs --dist dist [--version 1.4.2] [--key <listingKey>]
+ *                      [--manifest deploy/portal/app.manifest.json]
+ *                      [--portal https://portal.example.com] [--config path] [--offline]
+ *
+ * `--manifest` 缺省时按常见路径自己找；找到就一并检查文案字段形状。
+ *
+ * `--key` 缺省时从本地配置文件的 LISTING_KEY 读（与 release-cli 同一份）。
+ *
+ * 挡的是同一类事故：构建成功、命令返回 ✓、线上却白屏或发不出去。这些成因
+ * tsc / lint / 单测一条都发现不了，因为它们全都发生在「产物形状」与「凭证」上。
+ *
+ * 零依赖，纯 Node ≥18（fetch 内置）。可以整个文件拷进任何 App 仓。
+ * 退出码：有 ✗ → 1，否则 0（! 只是提醒，不拦）。
+ */
+import { readFileSync, statSync, readdirSync, rmSync, mkdtempSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { tmpdir, homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+// 本地配置文件的读取只有一份实现（同目录 registry-config.mjs，npm-token.mjs 也用它）：
+// 抄成两份的下场是换个字段名只改了一处，另一个脚本悄悄退回默认值。
+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 VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/; // 与门户逐字一致
+const KEY_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+const errs = [];
+const warns = [];
+const oks = [];
+const err = (m) => errs.push(m);
+const warn = (m) => warns.push(m);
+const ok = (m) => oks.push(m);
+
+const args = parseArgs(process.argv.slice(2), ["offline"]);
+const cfg = loadConfig(args.config);
+const key = String(pick(args.key, process.env.LISTING_KEY, cfg.LISTING_KEY));
+const dist = args.dist ?? "dist";
+const version = args.version ?? "";
+// TARGET_XGENT_PLATFORM 是新名字，XGENT_PORTAL_URL 保留兼容（同一件事）。
+const portal = String(pick(args.portal, process.env.TARGET_XGENT_PLATFORM, process.env.XGENT_PORTAL_URL, cfg.TARGET_XGENT_PLATFORM, cfg.XGENT_PORTAL_URL)).replace(/\/+$/, "");
+const token = String(pick(process.env.XGENT_RELEASE_TOKEN, cfg.XGENT_RELEASE_TOKEN)).trim();
+
+if (!key) {
+  console.error("用法: node preflight.mjs [--key <listingKey>] --dist dist [--version v] [--manifest path] [--portal url] [--config path] [--offline]");
+  console.error("      缺 --key 时从本地配置文件的 LISTING_KEY 读（./.xgent-registry.env 等）");
+  process.exit(1);
+}
+if (!KEY_RE.test(key)) err(`--key "${key}" 形状不合法：只能小写字母/数字/连字符，且不能以连字符开头或结尾`);
+
+/* ── 1. 产物目录与根 index.html ─────────────────────────────────────────
+   门户解包后就找根目录的 index.html；找不到直接拒收。最常见的成因不是构建
+   坏了，而是把仓库根 / 上一层目录当成了 --dist。 */
+let distStat = null;
+try {
+  distStat = statSync(dist);
+} catch {
+  err(`产物目录不存在：${dist}（是不是还没构建，或路径写错了？）`);
+}
+if (distStat && !distStat.isDirectory()) err(`${dist} 不是目录`);
+
+let html = null;
+if (distStat?.isDirectory()) {
+  try {
+    html = readFileSync(join(dist, "index.html"), "utf8");
+    ok(`根目录有 index.html`);
+  } catch {
+    // 帮一把：如果它躺在下一层，几乎肯定是 --dist 指错了一层
+    let hint = "";
+    try {
+      const sub = readdirSync(dist, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .find((d) => {
+          try { statSync(join(dist, d.name, "index.html")); return true; } catch { return false; }
+        });
+      if (sub) hint = ` —— 但 ${join(dist, sub.name)}/index.html 在，--dist 应该指那一层`;
+    } catch {}
+    err(`产物根目录没有 index.html${hint}`);
+  }
+}
+
+/* ── 2. base 前缀（翻车率第一名）──────────────────────────────────────
+   产物在生产被挂到 /apps/<key>/ 下。base 少了，页面本身能 200（宿主 iframe
+   拿得到 index.html），但里面每个 /assets/… 请求都打到站点根 → 404 → 白屏。
+   构建、类型检查、单测全绿，只有人眼在浏览器里看得出来。 */
+if (html) {
+  const base = `/apps/${key}/`;
+  const refs = [...html.matchAll(/(?:src|href)\s*=\s*["']([^"']+)["']/gi)].map((m) => m[1]);
+  const rooted = refs.filter((r) => r.startsWith("/"));
+  const bad = rooted.filter((r) => !r.startsWith(base));
+  const good = rooted.filter((r) => r.startsWith(base));
+  const relative = refs.filter((r) => !/^([a-z]+:)?\/\//i.test(r) && !r.startsWith("/") && !r.startsWith("#") && !r.startsWith("data:"));
+  const external = refs.filter((r) => /^https?:\/\//i.test(r));
+
+  if (bad.length) {
+    err(
+      `index.html 里有 ${bad.length} 个绝对路径没走 base ${base}：${bad.slice(0, 3).join(" ")}${bad.length > 3 ? " …" : ""}\n` +
+        `      → 构建时 base 没设对。vite: base: command === 'build' ? '${base}' : '/'`,
+    );
+  } else if (good.length) {
+    ok(`资源路径都带 base ${base}（${good.length} 处）`);
+  } else if (relative.length) {
+    warn(
+      `index.html 用的是相对路径（${relative.slice(0, 3).join(" ")}）而不是 ${base}。` +
+        `资源本身能加载，但客户端路由进到嵌套路径后相对基准会变，容易在二级页面上炸。建议显式设 base。`,
+    );
+  } else {
+    warn(`index.html 里没解析到任何 src/href —— 确认这是构建产物而不是模板？`);
+  }
+  if (external.length) {
+    warn(
+      `index.html 直连了外部地址：${external.slice(0, 3).join(" ")}${external.length > 3 ? " …" : ""}\n` +
+        `      → 生产受 per-App CSP 管。XHR/fetch 可通过 publish --manifest 申报 embedCsp.connectSrc，治理审核批准后再验实际响应头；` +
+        `script/style/font/img/media 需各自来源声明；扩展指令要求目标门户已启用严格 CSP 与 v2 网关，预检无法确认启用状态。`,
+    );
+  }
+}
+
+/* ── 3. 打包形状与体积 ────────────────────────────────────────────────
+   顺带验证 tar 可用：release-cli 用的就是这条命令，它跑不了发布也跑不了。 */
+if (distStat?.isDirectory()) {
+  const temp = mkdtempSync(join(tmpdir(), "xgent-preflight-"));
+  try {
+    const out = join(temp, "dist.tgz");
+    const r = spawnSync("tar", ["czf", out, "-C", dist, "."], { stdio: ["ignore", "ignore", "pipe"] });
+    if (r.status !== 0) {
+      err(`tar 打包失败（release-cli 用的是同一条命令）：${String(r.stderr).slice(0, 200)}`);
+    } else {
+      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} 个顶层条目`);
+    }
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+/* ── 4. dev 残留 ─────────────────────────────────────────────────────
+   cross-origin vite dev 那条联调通路会让人往代码里写 localhost:53xx。留在
+   产物里的话，生产 CSP 直接拦掉，症状是「本地好好的，线上功能静默不动」。 */
+if (distStat?.isDirectory()) {
+  const hits = [];
+  const scan = (dir, depth = 0) => {
+    if (depth > 4 || hits.length >= 5) return;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) scan(p, depth + 1);
+      else if ([".js", ".mjs", ".css", ".html", ".json"].includes(extname(e.name))) {
+        let s;
+        try {
+          if (statSync(p).size > 8 * 1024 * 1024) continue;
+          s = readFileSync(p, "utf8");
+        } catch { continue; }
+        if (/https?:\/\/(localhost|127\.0\.0\.1):\d+/.test(s)) hits.push(p);
+        if (hits.length >= 5) return;
+      }
+    }
+  };
+  scan(dist);
+  if (hits.length) warn(`产物里有 localhost 地址：${hits.join(" ")} —— 生产 CSP 会拦掉，确认是死代码还是真会被调用`);
+}
+
+/* ── 5. 版本号形状 ───────────────────────────────────────────────────── */
+if (version) {
+  if (!VERSION_RE.test(version)) err(`--version "${version}" 门户会拒：只能字母/数字/. _ + -，且 ≤64 字符`);
+  else ok(`版本号 ${version} 形状合法（记得它必须比线上那版新 —— 同号重发会让「线上是哪一版」说不清）`);
+} else {
+  warn(`没传 --version：发布时它是必填项，且每次都要 bump（哪怕只换产物）`);
+}
+
+/* ── 6. 令牌 ─────────────────────────────────────────────────────────
+   放最后但最值得做：令牌过期/吊销/发给了别的 key，只有真调一次才现形。 */
+if (!token) {
+  warn(`找不到发布令牌 —— 在 .xgent-registry.env 里写 XGENT_RELEASE_TOKEN=xrel_…（平台管理员在控制台签发，明文只显示一次）`);
+} else if (!token.startsWith("xrel_")) {
+  err(`XGENT_RELEASE_TOKEN 形状不对：应以 xrel_ 开头（拿成别的令牌了？）`);
+} else if (args.offline) {
+  ok(`令牌形状正确（--offline，未联网校验）`);
+} else if (!portal) {
+  warn(`没有门户地址（--portal / TARGET_XGENT_PLATFORM），跳过令牌联网校验`);
+} else {
+  warnIfProxyIgnored();
+  const url = `${portal}/api/market/release/${encodeURIComponent(key)}`;
+  try {
+    const res = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+    if (res.status === 401) err(`令牌无效 / 已吊销 / 已过期（门户每次调用实时查库，吊销即刻生效）`);
+    else if (res.status === 404) err(`令牌不是为 ${key} 签发的（也可能该 listing 不存在 —— 门户故意不区分这两种）`);
+    else {
+      const body = await res.json().catch(() => null);
+      const d = body?.data;
+      if (!d) warn(`令牌校验返回了预期外的响应（HTTP ${res.status}）—— 确认 --portal 指的是门户而不是别的服务`);
+      else {
+        ok(`令牌有效 · ${d.key} · 前缀 ${d.prefix}… · ${d.expiresAt ? `${d.expiresAt} 过期` : "不过期"}`);
+        if (d.expiresAt) {
+          const days = (new Date(d.expiresAt) - new Date()) / 86400000;
+          if (days < 7) warn(`令牌还有 ${days.toFixed(1)} 天过期 —— 提前找平台管理员续，别卡在发布当天`);
+        }
+      }
+    }
+  } catch (e) {
+    warn(`令牌联网校验失败（${e?.message ?? e}）—— 网络不通就用 --offline 跳过，但发布时还是会验`);
+  }
+}
+
+/* ── 7. manifest 文案字段形状 ─────────────────────────────────────────
+   门户把 manifest 的文案分两处存：展示字段进 text 列（只存一种语言），
+   `scopeLabels` 与 `aclManifest` 里的 label 进 jsonb（支持按门户语言解析的多语对象）。
+   两组的形状要求【不一样】，而写错的那一组【不会报错】：给 `tagline` 一个
+   `{"zh-CN":…,"en":…}` 对象，会被拼成字面量 `[object Object]` 存进去，然后出现在
+   每个租户的应用卡片和详情上。构建、发布、审批，整条链路没有任何一处会提示你。 */
+const MANIFEST_GUESSES = [
+  "deploy/portal/app.manifest.json", "portal-app/app.manifest.json",
+  "deploy/app.manifest.json", "app.manifest.json",
+];
+const manifestPath = args.manifest ?? MANIFEST_GUESSES.find((p) => { try { return statSync(p).isFile(); } catch { return false; } });
+if (!manifestPath) {
+  warn(`没找到 app.manifest.json（试过 ${MANIFEST_GUESSES.join(" ")}）—— 用 --manifest <path> 指给我，文案字段形状就没人查了`);
+} else {
+  let mf = null;
+  try {
+    mf = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    err(`${manifestPath} 不是合法 JSON：${e?.message ?? e}`);
+  }
+  if (mf && typeof mf === "object") {
+    if (Object.hasOwn(mf, "embedCsp")) {
+      try {
+        normalizeEmbedCsp(mf.embedCsp);
+        ok("manifest.embedCsp 通过生产严格语法检查（不代表已获批或已加载）");
+      } catch (e) {
+        err(`manifest.embedCsp 不符合严格声明语法：${e.message}`);
+      }
+      warn("能力门未核验：strict 默认关闭；扩展 CSP 需平台确认已发布兼容版本并受控启用 strict 与 v2 网关。whoami 成功不证明此能力已启用。");
+      warn("embedCsp 省略沿用；null 清空；完整对象替换原声明，未写指令会撤回。来源增删均需治理审核。");
+    }
+    const isObj = (v) => v !== null && typeof v === "object";
+    const shown = (v) => JSON.stringify(v)?.slice(0, 60) ?? String(v);
+
+    /* ① text 列 = 单语纯字符串。`name` 是唯一被容忍的：门户会把对象拍平成 zh-CN 存下去
+       （不报错，但另外两种语言就此丢了）。其余给对象一律变成 "[object Object]"。 */
+    if (isObj(mf.name)) {
+      warn(
+        `manifest.name 是对象（${shown(mf.name)}）—— 门户会把它拍平成 zh-CN 一种语言存下去。` +
+          `应用名不支持多语，写纯字符串，别指望三语生效。`,
+      );
+    } else if (mf.name !== undefined && typeof mf.name !== "string") {
+      err(`manifest.name 必须是字符串`);
+    }
+    for (const f of ["tagline", "desc", "icon", "color", "cat", "version", "embedUrl", "serviceBaseUrl", "helpEntry"]) {
+      const v = mf[f];
+      if (v === undefined || v === null || typeof v === "string") continue;
+      err(
+        `manifest.${f} 必须是字符串，现在是${Array.isArray(v) ? "数组" : typeof v}（${shown(v)}）。` +
+          (isObj(v) ? `\n      → 这个字段不支持多语：给对象会被存成字面量 "[object Object]"，直接显示给每个租户。多语只有 scopeLabels 和 aclManifest 里的 label 支持。` : ""),
+      );
+    }
+    for (const [i, n] of (Array.isArray(mf.navItems) ? mf.navItems : []).entries())
+      if (n && typeof n.label !== "string")
+        err(`manifest.navItems[${i}].label 必须是字符串（导航项标题不支持多语；现在是${shown(n.label)}）`);
+    for (const [i, w] of (Array.isArray(mf.dashboardWidgets) ? mf.dashboardWidgets : []).entries())
+      for (const f of ["title", "subtitle", "description"])
+        if (w && w[f] !== undefined && typeof w[f] !== "string")
+          err(`manifest.dashboardWidgets[${i}].${f} 必须是字符串（Widget 文案不支持多语）`);
+
+    /* ② scopeLabels = 同意屏正文，jsonb，**支持**多语对象。这里查的是三种「配了不生效」：
+       键不在 scopes 里（写入时被静默丢弃）、多语对象缺 zh-CN（回退终点）、
+       替平台基础 scope 写文案（那是平台的措辞，各 App 各写一份只会互相打架）。 */
+    const declared = new Set(Array.isArray(mf.scopes) ? mf.scopes : []);
+    const ns = [key, key.replace(/-/g, "_")];
+    const labels = isObj(mf.scopeLabels) ? mf.scopeLabels : {};
+    const LOCALES = ["zh-CN", "zh-TW", "en"];
+    let labelOk = 0;
+    for (const [s, v] of Object.entries(labels)) {
+      if (Array.isArray(mf.scopes) && !declared.has(s)) {
+        err(
+          `manifest.scopeLabels 有一条 "${s}"，但它不在 manifest.scopes 里 —— 门户写入时会把它【静默丢弃】，` +
+            `同意屏上那条 scope 回落成键名。要么补进 scopes，要么删掉这条文案。`,
+        );
+        continue;
+      }
+      if (!ns.some((p) => s === p || s.startsWith(`${p}.`))) {
+        warn(
+          `manifest.scopeLabels 替 "${s}" 写了文案，但它不在你的命名空间（${key}.）里 —— ` +
+            `平台基础 scope 的说明归平台统一维护：各 App 各写一份，同一条权限在不同应用的同意屏上措辞就不一致了。` +
+            `缺文案找平台补，别在自己清单里补。`,
+        );
+      }
+      if (typeof v === "string") { labelOk++; continue; }
+      if (!isObj(v) || Array.isArray(v)) { err(`manifest.scopeLabels["${s}"] 只能是字符串或 { "zh-CN": …, "zh-TW": …, "en": … } 对象`); continue; }
+      if (typeof v["zh-CN"] !== "string" || !v["zh-CN"].trim())
+        err(`manifest.scopeLabels["${s}"] 缺 "zh-CN" —— 它是回退终点，缺了在没有对应语言时会退到别的语言甚至键名`);
+      const extra = Object.keys(v).filter((k) => !LOCALES.includes(k));
+      if (extra.length) warn(`manifest.scopeLabels["${s}"] 里的 ${extra.join("/")} 门户界面用不到（只认 ${LOCALES.join(" / ")}）`);
+      if (typeof v["zh-CN"] === "string") labelOk++;
+    }
+    const appScopes = [...declared].filter((s) => ns.some((p) => s === p || s.startsWith(`${p}.`)));
+    const noLabel = appScopes.filter((s) => !(s in labels));
+    if (noLabel.length)
+      warn(
+        `你自己命名空间的 scope 有 ${noLabel.length} 条没写 scopeLabels：${noLabel.slice(0, 4).join(" ")}${noLabel.length > 4 ? " …" : ""}` +
+          `\n      → 门户对 App 命名空间的 scope 没有内建文案，同意屏上会直接显示键名。用户看到 "${noLabel[0]}" 是不会点同意的。`,
+      );
+    if (labelOk) ok(`scopeLabels ${labelOk} 条形状合法`);
+
+    /* ③ usageMetrics[].label 是【第三种】形状：键名是 zh/en/tw，不是 zh-CN/zh-TW。
+       写成 zh-CN 会被门户判成缺 label.zh，提交即拒（连提案都不落）。 */
+    for (const [i, u] of (Array.isArray(mf.usageMetrics) ? mf.usageMetrics : []).entries()) {
+      const l = u?.label;
+      if (!isObj(l) || typeof l.zh !== "string" || !l.zh.trim())
+        err(
+          `manifest.usageMetrics[${i}].label 必须是 { "zh": "…" }（en / tw 可选，缺省回退 zh）——` +
+            `注意这里的键是 zh / en / tw，不是 scopeLabels 那套 zh-CN / zh-TW / en。写错门户提交即拒。`,
+        );
+    }
+    /* ④ 像库 / Redis 连接串、却不按约定命名的键：平台自动供给不到它，落到审批屏就是
+       「平台管理员多点一下」。**只 warn 不阻断** —— 键名归 App，这里只是告诉你便宜的写法。 */
+    const PREFIX = key ? key.toUpperCase().replace(/-/g, "_") : null;
+    const CONVENTIONAL = new Set([PREFIX ? `${PREFIX}_DATABASE_URL` : "", "REDIS_CONN_STRING"].filter(Boolean));
+    const envKeys = (Array.isArray(mf.requiredEnv) ? mf.requiredEnv : [])
+      .map((e) => (typeof e === "string" ? e : typeof e?.key === "string" ? e.key : null))
+      .filter(Boolean);
+    const unbound = envKeys.filter((k) => /(DATABASE_URL|_DSN|POSTGRES|REDIS)/.test(k) && !CONVENTIONAL.has(k));
+    if (unbound.length)
+      warn(
+        `这几个键看着是库 / Redis 连接串，但平台自动供给不到它们：${unbound.slice(0, 4).join(" ")}${unbound.length > 4 ? " …" : ""}` +
+          `\n      → 改用约定名就零手填：${PREFIX ? `${PREFIX}_DATABASE_URL` : "<PREFIX>_DATABASE_URL"} / REDIS_CONN_STRING，` +
+          `并在 requiredServices 里声明要哪条服务（只写 name / kind / note，多一个字段整份清单会被拒收）。` +
+          `\n      不改也能发 —— 只是平台管理员要在审批屏上逐个点「从平台服务取值」，多等一轮。`,
+      );
+
+    if (!errs.some((m) => m.startsWith(`manifest.`) || m.startsWith(`${manifestPath} `)))
+      ok(`${manifestPath} 文案字段形状合法`);
+  }
+}
+
+/* ── 报告 ───────────────────────────────────────────────────────────── */
+for (const m of oks) console.log(`✓ ${m}`);
+for (const m of warns) console.log(`! ${m}`);
+for (const m of errs) console.log(`✗ ${m}`);
+console.log(
+  errs.length
+    ? `\n预检未通过：${errs.length} 项必须先修。修完重跑，别硬发 —— 门户拒收时不改任何状态，但白屏类问题它拦不住。`
+    : `\n预检通过${warns.length ? `（${warns.length} 条提醒，自行判断）` : ""}。可以 publish 了。`,
+);
+process.exit(errs.length ? 1 : 0);