@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,65 @@
+# 构建与打包
+
+发布之前的一切。这里的每一条都对应一种「构建全绿、线上坏掉」的具体死法。
+
+依赖怎么装、包从哪来、构建器怎么配 —— 那是你这个 repo 自己的事，本文不管。
+本文只管**产物要长成什么形状**，因为那是门户会校验、会拒收、会静默画错的部分。
+
+## 1. `base` 必须是 `/apps/<listingKey>/`
+
+生产上产物被同源挂在门户的 `/apps/<key>/` 子路径下（同源是有意的：宿主 iframe 的生产 CSP 是
+`frame-src 'self'`，跨源地址上不了生产）。dev server 却服务在根路径，所以 `base` 是**双态**的：
+
+```ts
+// vite
+export default defineConfig(({ command }) => ({
+  base: command === 'build' ? '/apps/<listingKey>/' : '/',
+  // …
+}));
+```
+
+漏掉 `build` 那一态的症状很有欺骗性：iframe 里页面 200（宿主拿得到 `index.html`），
+但里面每个 `/assets/…` 都打到站点根 → 404 → **白屏，控制台一片红**。
+构建、类型检查、单测全绿——这条只有产物形状检查或人眼看得出来，所以预检脚本第一件事就查它。
+
+非 vite 的构建器同理：webpack 是 `output.publicPath`，Next 静态导出是 `basePath` + `assetPrefix`。
+判据统一：**`index.html` 里所有根绝对路径都要以 `/apps/<key>/` 开头。**
+
+客户端路由也要跟着走子路径（React Router 的 `basename`），否则刷新二级页面会 404。
+
+## 2. 产物形状：tar 根直接是 `index.html`
+
+门户解包后在**根目录**找 `index.html`，找不到就 `VALIDATION_FAILED` 拒收。
+
+```bash
+tar czf dist.tgz -C dist .     # ✅ 根下就是 index.html、assets/…
+tar czf dist.tgz dist          # ❌ 全套在 dist/ 一层下面，拒收
+```
+
+`release-cli` 传目录时已经用第一种形状打好了，只有自己 `curl` 时才需要手打。
+
+其它约束：**≤64MB**（超了先查 source map 与未压缩素材）；空文件会被当成「构建没产出」拒掉，
+而不是当成「只发版本号」——这是有意的，否则一条坏流水线会报成功。
+
+## 3. 不需要 CORS，但可能需要 CSP
+
+前端**从不直连自己的后端**：请求经宿主的 `postMessage` 代理由宿主同源发出。
+所以别去要 CORS 放行——要了也没用。
+
+反过来，如果前端要直连**自己的域名 / 对象存储 / 第三方**，那是浏览器直发的请求，受 per-App CSP 管。
+XHR/fetch 那一类可以由 App manifest 的 `embedCsp.connectSrc` 放行；字体、样式表、图片走的是
+`font-src` / `style-src` / `img-src`，不在这个字段的能力范围内。**manifest 不在自助面里**——
+要放行得找平台管理员，改完下次反代 reload 生效。
+
+所以最省事的做法是**把资源打进产物、不外链**（字体尤其：CDN 字体是这里最常见的外链，
+而它恰好是 `connectSrc` 放行不了的那一类）。预检脚本会把产物里的外链列出来提醒。
+
+## 4. 发之前在真门户里看一眼
+
+| 通路 | 怎么用 | 硬约束 |
+| --- | --- | --- |
+| **本地一盒（devkit 卷挂载）** | 平台侧起一个真门户，把你的 `dist` **绝对路径**挂进去 | 同源，走生产同款 CSP；**无 HMR**，改前端要重新 build |
+| **cross-origin vite dev** | listing 的 `embedUrl` 临时指向 `http://localhost:53xx`，起你仓的 dev server | 仅门户 dev 的 CSP 放行本地端口；**生产 `frame-src 'self'`，此路永远上不了生产** |
+
+第二条最容易留后患：调试时往代码里写死的 `localhost:53xx` 如果跟着产物发上生产，
+CSP 会静默拦掉，症状是「本地好好的，线上那个功能点了没反应」。预检脚本会扫这个。

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

@@ -0,0 +1,315 @@
+# 发布面：令牌、端点、字段、CI
+
+## 0. 五项输入全部放同一份本地配置文件
+
+| 输入 | 键名 | 说明 |
+| --- | --- | --- |
+| `listingKey` | `LISTING_KEY` | 一个 repo 一个 App，从头到尾不变。每条命令手打一次纯噪音，还容易打成另一个 App —— 那会直接 404 |
+| 目标门户地址 | `TARGET_XGENT_PLATFORM` | 本次发版打哪一台（旧名 `XGENT_PORTAL_URL` 仍认）。`--portal` 可覆盖 |
+| 目标门户的发布令牌 | `XGENT_RELEASE_TOKEN` | `xrel_…`，按 App 绑定。`--token` 可覆盖 |
+| 清单目录地址 | `MANIFEST_STORE` | 可选。不配 ⇒ 不投目录（整步跳过，不报错也不提示） |
+| 目录的发布令牌 | `MANIFEST_STORE_TOKEN` | 可选。不配 ⇒ 回落 `XGENT_RELEASE_TOKEN`（两个地址是同一台时那就是对的那把） |
+
+配置文件按顺序取第一个存在的：`--config <path>` / `$XGENT_REGISTRY_CONFIG` /
+`./.xgent-registry.env` / `${XDG_CONFIG_HOME:-~/.config}/xgent/registry.env` / `~/.xgent-registry.env`。
+格式是 `KEY=value`；同一份文件也放你镜像推送那侧要的键（`REGISTRY` / `PULLER_AUTH`）。
+同名环境变量优先，命令行参数又优先于环境变量 —— **CI 里注入环境变量即可覆盖**。
+
+前两个位置是**显式指定**的：指到一个不存在的文件会直接报错，不会悄悄回退到别的候选——
+回退意味着你可能在读另一个 App 的身份，而命令照样成功，只是发错了地方。
+
+### 令牌为什么放这里（这条推翻了旧规则）
+
+旧规则「密钥别落盘、走 `--token` 或 env」是按**人手敲命令**的模型写的：env 短暂、文件长存。
+今天发版几乎都是**经 skill 让 agent 驱动 CLI**：强制走 `--token`，agent 必须先把令牌**取出来**
+才能传进去 —— 于是它进 agent 上下文、进对话记录、进工具调用日志，还出现在命令行里（同机
+其它进程 `ps` 可见）。**那比落盘更不安全，而且泄露面不可撤销**（记录已经写出去了）。
+让 CLI 自己读文件，令牌就**从不经过 agent**。这个文件本来就是凭证文件（`PULLER_AUTH` 一直在里面）。
+
+护栏没有删，换成了真正管用的两条 —— CLI 每次运行都替你查，**只 warn 不阻断**：
+
+| 检查 | 触发 | 修法 |
+| --- | --- | --- |
+| 文件权限 | mode 允许同组 / 其他人读 | `chmod 600 .xgent-registry.env` |
+| 有没有被忽略 | `git check-ignore` 判定它**未被忽略**（这才是真会泄露的场景） | `echo '.xgent-registry.env' >> .gitignore` |
+
+（做成硬失败只会逼人把令牌搬回命令行 —— 那正是要消灭的那件事。）
+
+```bash
+# .xgent-registry.env（chmod 600，且必须 .gitignore）
+LISTING_KEY=my-app
+TARGET_XGENT_PLATFORM=https://portal.example.com
+XGENT_RELEASE_TOKEN=xrel_…
+MANIFEST_STORE=https://catalog.example.com
+MANIFEST_STORE_TOKEN=xrel_…
+```
+```bash
+npx @xgent/release-cli status      # 地址与令牌都不用写在命令里
+```
+
+## 0a. 一次 publish 打两个端点
+
+| 站 | 端点 | 失败语义 |
+| --- | --- | --- |
+| 第一站（真发版） | `POST <TARGET_XGENT_PLATFORM>/api/market/release/<key>` | **必成**：失败 ⇒ 整体非零退出，且**不投目录** |
+| 第二站（投目录） | `PUT <MANIFEST_STORE>/api/market/catalog/<key>` | **best-effort**：连不上 / 非 2xx / `ok:false` 都只 warn，退出码不变 |
+
+两个地址相同时**照常两次调用** —— 它们是不同端点，不会互撞。
+没带 `--manifest` 就不投（没有清单可投），CLI 会提示一句 —— 所以**标准发布命令要带上它**。
+
+第二站送的是这次发版**生效后**的那一份清单，即原始字节**再套上 `--version` / `--image`
+的覆盖**。这不是「改了内容」，恰恰是为了两站说同一句话：第一站的服务端本来就取
+`body.version ?? manifest.version` 与 `body.image ?? manifest.deployDescriptor.image`，
+批准时还会把这两个值嫁接回 manifest 才落 listing。原样投原始字节的结果是：目标门户
+已经是 `$VER` / 新镜像，目录还停在清单里写的旧值，而 `onebox.sh add` 正是照
+`deployDescriptor.image` 拉镜像 —— 别人起出来的是旧容器，且没有任何信号。
+
+一个刻意的例外：目标门户回 `PROPOSAL_PENDING`（你上一版还在待审队列里）时，
+**目录照投**。那是目标门户的**队列状态**，不是「这份清单是什么」的结论；不投的话，
+目标门户与目录是同一台时，一条待审提案会把目录永久冻在提交它的那一版。
+那次 `publish` 的退出码仍是非 0 —— 发版确实没成。
+
+目录里那份是**净化过的公开副本**：`serviceAccount` 只留 `clientId`，`exchangeInitiatorSecret`
+与 `deployDescriptor` 的 `env` / `envFile` / `hostPort` 一律剔除（密钥与单部署事实不跨部署共享）。
+它是**只读投影**：不参与任何门户的治理判定、不回写任何 listing、不触发任何部署。
+唯一的消费者是开发环境 —— 别人 `onebox.sh add <key> --from <目录地址>` 时从这里拉清单。
+
+## 1. 发布令牌 `xrel_…` 的语义
+
+- 平台管理员在 **控制台 › 应用清单 › 编辑清单 › 发布令牌** 签发，**明文只显示一次** → 直接进 CI secret。
+- **一枚令牌只对一个 listing 有效**。拿它去动别的 key 一律 `404`——门户**故意不区分**
+  「不属于你」和「那个 App 不存在」，免得令牌变成探测别人 App 是否存在的工具。
+- 可随时吊销、可设过期时间。**每次调用实时查库**，所以吊销后下一次调用就 `401`，没有缓存窗口。
+- 它能**单方面生效**的仍只有自动通过档：`dist` · `version` · `deployDescriptor.image` ·
+  展示字段 ·「值是 App 内路由 `/…`」的 `helpEntry`（外站 `https://…` 那一形态进审核档）。
+  治理变更只能**提议**（随 `manifest` 提交，进平台审核队列，批准前库里一字不动）。
+  它也**读不回** `descriptor.env`——响应体里永远没有它，因为那里面是生产密钥。
+
+## 2. 端点
+
+```
+POST   /api/market/release/:key                发布（落成一条发布提案）
+GET    /api/market/release/:key                whoami（校验令牌，只返回持有者本就知道的东西）
+GET    /api/market/release/:key/status         只读：版本 / 产物 digest / 部署状态 / 最近一条提案
+GET    /api/market/release/:key/proposals/:id  只读：单条提案状态（--wait 轮询用）
+DELETE /api/market/release/:key/proposals/:id  撤回自己【待审】的提案（提交方的权利）
+```
+
+认证只有一件事：`Authorization: Bearer xrel_…`。没有 cookie、没有 session、没有 CSRF 面。
+
+`curl` 兜底（`@xgent/release-cli` 取不到时用这个，能力完全等价）：
+
+```bash
+tar czf dist.tgz -C dist .        # 根下就是 index.html
+curl -X POST "$XGENT_PORTAL_URL/api/market/release/<key>" \
+  -H "authorization: Bearer $XGENT_RELEASE_TOKEN" \
+  -F version=1.4.2 \
+  -F image=<key>:1.4.2 \          # 可选；没有后端的纯前端 App 省掉
+  -F dist=@dist.tgz \             # 只 bump 版本/换镜像时可省掉
+  -F manifest=@deploy/portal/app.manifest.json   # 可选；清单变更/首次接入时带上
+```
+
+> `deploy/portal/app.manifest.json` 是【你自己 App 仓】的惯例路径，不是门户仓文件 ——
+> 你的 manifest 只存在于你自己的 repo，按你实际存放的位置传即可。
+
+`whoami` 就是同一路径的 `GET`，带同一个 header。
+
+**前两条是发布面的底线，第三条不是**：只读面比发布面晚一版上线，老门户上打它得到
+`404 NOT_FOUND / 路由不存在`——与「令牌不是这个 key 的」**响应体完全相同**（门户故意不区分，
+免得令牌能用来探测别人的 App 是否存在）。分诊只有一条路：同一枚令牌先打 whoami，
+`200` 就说明是门户没有这个面。见 `troubleshooting.md`。
+
+## 3. 字段：四个 multipart 字段 + 定级
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `version` | （或 manifest.version） | 字母/数字/`. _ + -`，≤64 字符。**每次都要 bump** |
+| `dist` | | multipart 文件，`.tar.gz`，根下 `index.html`，≤64MB。省掉 = 这次不换产物 |
+| `image` | | 镜像引用。省掉 = 不换镜像 |
+| `manifest` | | `app.manifest.json` 全文（文件或 JSON 字符串）。省掉 = 只发三件（全自动档） |
+
+**这四个之外的散字段仍然直接拒**（`200 + VALIDATION_FAILED`，拒在写库之前）——
+治理变更只能经 manifest 整份提交，没有「往表单里塞一个 scopes」这条路。
+
+**定级唯一判据：这次提交有没有改变权限面。** manifest 里与当前 listing 相比有治理差异
+（scopes / aclManifest / dependencies / exchangeTargets / serviceScopes /
+privilegedServiceScopes / usageMetrics / serviceBaseUrl /
+seat* / scopeLabels / embedUrl / embedCsp / type / 部署形态…，以及**任何门户不认识的字段**）
+⇒ 提案 `pending` 等平台审批；只有版本/产物/镜像/展示字段的差异 ⇒ `auto_approved` 当场生效。
+其中 `privilegedServiceScopes`（平台特权 scope 的申请，如 `seats.read`）是最高一档：
+审批人要**逐条勾选确认**才能批准 —— 每条都带上说清用途的 `reason`，等待会短很多；
+已持有的特权 scope 幂等重放不再进审。
+**提交即拒**（连提案都不落）的只有四类：manifest 携带密钥值（SA secret / descriptor.env）、
+SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScopes`）、形状非法
+（含 `usageMetrics` 的 key 不在你的 listingKey 命名空间、或声明金额单位），
+以及**该 App 已有一条待审提案**（`PROPOSAL_PENDING`——
+待审期间连纯 dist/version 的自动档也拒，否则「后交先生效」，批准旧提案时会把后发的版本滚回去）。
+另注意 `serviceAccount.clientId` 归属也算权限面：声明一个已归属别的 App 的 clientId ⇒
+`pending`，且批准也会在生效时被拒 —— clientId 用自己的。
+
+## 4. 响应怎么读
+
+**业务失败是 `200 + { ok:false, error }`**（门户全局约定：HTTP 状态码只表达传输/路由层）。
+所以只看 HTTP 状态码会把「产物形状不对」读成成功。判据固定是 `body.ok`。
+
+只有三种情况不是 200：`401`（令牌无效/吊销/过期）、`404`（令牌不是为这个 key 签发的），以及真故障。
+
+成功时 `data` 里（先看 `status`：`"applied"` = 已生效；`"pending"` = 等审批，此时只有
+`proposalId` / `kind` / `governance`（待审字段清单）有意义）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `proposalId` / `status` / `kind` | 本次提案：id · applied/pending · register(首次)/update |
+| `governance` | pending 时的待审字段清单 |
+| `version` | 落库后的版本号 |
+| `distDigest` | 本次产物的 sha256（`null` = 这次没换产物）。**控制台上「线上跑的是哪一版」靠它** |
+| `distFiles` | 产物顶层条目数 |
+| `distStores` | 落了哪些存储 |
+| `image` / `imageChanged` / `redeployQueued` | 镜像引用、是否变了、是否排了重部署任务 |
+
+## 5. 原子性：坏包碰不到线上那份
+
+一次调用内：解压 → 验根 `index.html` → 落 staging → rename 换上 → **同一次落库** `version` + `distDigest`。
+被拒时 `version` 与 `digest` 都不动，线上产物原封不动。
+
+所以「发布失败了，线上是不是已经半坏了」这个担心不成立——失败就是没发生。
+反过来也意味着：**版本号与产物永远同进同退**，不会出现「产物换了版本号没换」的漂移。
+
+## 6. `--image` / `image`
+
+给有后端的 App 用。三条硬约定：
+
+1. **`<name>` 就是你的 App key**，不是 `<key>-server`。写错了拼出来的仓库根本不存在，
+   而这件事只有在真正 `docker pull` 的那一刻才会暴露（往往是切换窗口里）。
+2. **只写相对名**（`<key>:<tag>`），仓库前缀由门户在部署时拼。把前缀写死进来，换仓库就得改你的仓。
+   判据与门户一致：含 `/` 且首段含 `.` 或 `:` 或等于 `localhost` 才算完整引用——
+   所以 `my-app:1.4.2` 是相对名，`hub.example.com/x/y:1` 不是。
+3. **tag 不可变，新版本 = 新 tag。** 同 tag 覆盖推送在门户侧看不出变化（引用没变），不会触发换版。
+
+前提：该 App 已由平台管理员配了 `deployDescriptor`。没有的话这一项直接被拒——
+「给一个没有部署描述的 App 加镜像」等于决定它从此是个被部署的后端，那是治理动作不是发布动作。
+
+镜像本身先 `docker push` 到平台 registry。**推送那一步不在本 skill 的范围内**，它有自己的流程与预检
+（跨境链路、架构、tag 不可变、保留策略），照那边的规矩来。这里只提三条会直接影响发布结果的：
+
+- **仓库域名不写死。** 它是内部信息，由各仓的本地配置提供（形如 gitignore 掉的 `.xgent-registry.env`，
+  CI 里用同名环境变量注入）。所以你的 `--image` 只写相对名，域名从头到尾不该出现在你的发布脚本里。
+- **robot 密钥的权限是项目级**，不是「只能推你那一个 repository」——密钥泄露等于同项目下所有 App
+  的 repository 都能被推拉。别放公共 runner。能推别人的不等于可以推。
+- **只发单 arch 的话必须是 amd64**（两条生产链路都是 amd64）；Apple Silicon 上直接 build 出来是 arm64，
+  **推得上去、拉得下来、容器起不来**（`exec format error`），看着像仓库坏了其实不是。
+  要多 arch 用 `docker buildx --platform`。
+
+引用一变，门户排一条重部署任务：pm2 侧**先拉后换**（拉不到则旧容器原封不动、任务转 failed），
+K8s 侧滚动更新（旧 Pod 在新 Pod ready 前不下线）。**服务不会因为一次发布断掉。**
+
+## 6.1 `--wait` / `--wait-review` / `status`：确认换版真的落地了
+
+`publish` 返回 `redeployQueued: true` 只说明**任务排上了**。前端产物是同步的（那一刻已在线上），
+换容器不是——它可能几十秒后才完成，也可能失败（镜像没 push、robot 没权限、tag 打错）。
+不确认这一步，CI 会绿着退出而线上还跑着旧容器。
+
+```bash
+# 发布并等到换版结束（默认 1800s，可写 --wait 600）
+npx @xgent/release-cli publish --key $KEY --version $VER --dist dist/ --image $KEY:$VER --wait
+
+# 必须卡在人工审批上的流水线，再加一个开关（默认 1800s）
+npx @xgent/release-cli publish --key $KEY --manifest app.manifest.json --wait-review
+
+# 或任何时候单查
+npx @xgent/release-cli status --key $KEY
+```
+
+**两个开关等的是两件事（CLI 0.5.0 起）：**
+
+| 开关 | 等什么 | 提案落成待审时 |
+| --- | --- | --- |
+| `--wait [秒]` | 只等**容器换版** | 打印提案号，**退出 0 立即返回** |
+| `--wait-review [秒]` | 先等**人工审批**，批准且换了镜像再等换版 | 轮询到终态；被拒 / 撤回 / 超时 ⇒ 非零退出 |
+
+`--wait` 之所以不再等审批：审批是分钟到小时级的人的动作，而**提案落成的那一刻平台管理员就
+收到了站内 + 邮件通知**，把 runner 挂在上面既烧机器又什么都没保证。
+⚠️ 从 0.4.x 升上来：以前写 `--wait` 指望它等审批的流水线，现在会在提案待审时**直接绿**——
+要保持旧行为，把那一处改成 `--wait-review`。
+
+`--wait` 成功 → 打印实际在跑的镜像引用、零退出；失败或超时 → 打印原因、**非零退出**。
+没换镜像时它直接跳过，不空等。镜像来源不限 `--image`：**manifest 的
+`deployDescriptor.image` 换了镜像同样会等**（`--wait-review` 下则是提案批准后接着等）。
+判据看的是最近一条 `deploy|redeploy` 任务，不掺 `provision-tenant`（那是某个租户的 bootstrap，
+与镜像滚动无关）。
+
+门户上没有这个面时，`status` 与 `--wait` 都用不了：产物那半边照旧由 `publish` 的返回体
+（`version` / `distDigest` / `redeployQueued`）交代清楚，容器那半边只能找平台管理员看
+「服务部署」面板。**别用「命令退出码 0」替代这半边的结论。**
+
+`status` 返回：
+
+| 字段 | 含义 |
+| --- | --- |
+| `version` / `distDigest` / `distUpdatedAt` | 线上现在是哪一版、哪一份产物 |
+| `image` | 你**声明**的相对引用（不是解析后的完整引用） |
+| `deployment` | `null` = 纯前端 App，没有后端可等 |
+| `deployment.status` | `not_deployed` / `deploying` / `ready` / `failed` |
+| `deployment.deployedImageRef` | **实际**在跑的完整引用（含仓库前缀）——「为什么还是旧版」靠它自查。CLI 默认只打印末段（域名是内部信息，没必要每次构建都刷进 CI 日志），**只在与声明值对不上时**才展开完整引用——那正是需要看清来源的场合，同名 tag 也可能来自另一个仓库 |
+| `deployment.lastJob` | 最近一条部署任务的 `action` / `status` / `error` / `finishedAt` |
+
+这个面是**只读**的，且仍在同一条边界内：同一枚令牌、同样绑死一个 listing、跨 key 一样 404。
+`descriptor.env` 读不回来——**连藏在部署错误文本里的那份也不行**，出口会对它做值级抹除，
+所以错误消息仍然可读（`manifest unknown` 之类留着），只有密钥被换成 `«redacted»`。
+
+## 7. CI 范式
+
+`listingKey` 从仓里的配置文件来，所以 CI 里不用重复它。先在 CI 中准备好本 skill，将 `SKILL_DIR` 设为它的 `SKILL.md` 所在目录；以下步骤在 App repo 根目录执行。
+
+```yaml
+env:
+  SKILL_DIR: "<本 skill 的 SKILL.md 所在目录>"
+  # 仓里那份 .xgent-registry.env 通常不进 CI —— 在这里注入即可（环境变量优先于文件）。
+  TARGET_XGENT_PLATFORM: https://portal.example.com
+  XGENT_RELEASE_TOKEN: ${{ secrets.XGENT_RELEASE_TOKEN }}
+  MANIFEST_STORE: https://catalog.example.com          # 可选：顺带投一份到清单目录
+  MANIFEST_STORE_TOKEN: ${{ secrets.MANIFEST_STORE_TOKEN }}
+
+steps:
+  # ⓪ 必须在最前：@xgent/release-cli 自己就在私有包仓上，.npmrc 没配的话 ① 取不到包。
+  - run: eval "$(node "$SKILL_DIR/scripts/npm-token.mjs")"   # 换私有包只读令牌
+  - run: npx @xgent/release-cli whoami                  # ① 先验令牌，别等构建完才发现过期
+  - run: <你自己的依赖安装与构建>                        # ② base=/apps/<key>/
+  - run: node "$SKILL_DIR/scripts/preflight.mjs" --dist dist --version $VER
+  - run: npx @xgent/release-cli publish --version $VER --dist dist/ --image <key>:$VER --wait
+          --manifest deploy/portal/app.manifest.json   # ← 不带它目录永远是空的
+```
+
+`--wait` 是让这条流水线**诚实**的那一步：没有它，换版失败时任务照样绿。
+它**不会**把流水线卡在人工审批上——改了权限面的那次发版会打印提案号后退出 0，平台管理员
+已被通知；真要门禁到审批，把 `--wait` 换成 `--wait-review`。
+
+版本号从哪来：用 git tag 或 `package.json` 的 version 都行，关键是**每次发布都不同**。
+把它固定成 `latest` 之类的常量，等于放弃「线上跑的是哪一版」这个能力。
+
+`--dry-run` 只打印将要发送的内容、不发请求，改 CI 脚本时先跑它。
+
+## 8. 私有包只读令牌（`GET /api/market/release/:key/npm-token`）
+
+`@xgent/{release-cli,shared,portal-sdk,portal-ui}` 都在私有包仓上 —— **包括发版用的 CLI 本身**，
+所以这一步是整条发布链的前置，不只是装依赖。**你不需要云账号**：拿同一枚 `xrel_`
+向门户换一枚 ≤12 h 的只读令牌，门户持那把云凭据。
+
+```
+GET <TARGET_XGENT_PLATFORM>/api/market/release/<key>/npm-token
+Authorization: Bearer xrel_…
+→ 200 { ok: true, data: { registry, scopes: ["@xgent"], token, expiresAt } }
+```
+
+| 情况 | 响应 | 你该做什么 |
+| --- | --- | --- |
+| 没令牌 / 令牌失效 | `401` | 重新拿一枚发布令牌 |
+| 令牌绑的是别的 App | `404` | 核对 `LISTING_KEY` |
+| 打太频繁 | `429` | CI 里只换一次，把结果传下去 |
+| 平台没配私有包仓库 | `200` + `NPM_REGISTRY_NOT_CONFIGURED` | **平台侧**的事，贴给管理员 |
+| 平台的仓库凭据被拒 | `200` + `NPM_REGISTRY_UNAUTHORIZED` | 同上，你这边不用改 |
+| 仓库暂时不可达 | `200` + `NPM_REGISTRY_UNAVAILABLE` | 重试一次 |
+
+- 令牌是**域级只读**的：能装 `@xgent/*`（`release-cli` 也在内），不能发布、不能删。
+- 不缓存到文件：它 12 h 就过期，CI 每次跑现换即可（门户侧自带缓存，不会每次都打云上）。
+- 客户端脚本 `scripts/npm-token.mjs`（`--raw` / `--npmrc` / `--check`）把这些都封好了。

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

@@ -0,0 +1,108 @@
+# 排查速查
+
+先分清事故落在哪一层——**发不出去** / **发出去了但页面坏** / **发出去了但线上没变**。
+三层的成因不重叠，混着猜会很久。
+
+## 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） |
+| 缺少应用标识 | 没传 `--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` 看最近一条任务：`failed` 就是拉不到镜像（没 push / robot 没权限 / tag 打错）。**先拉后换**，所以旧容器还在跑、服务没断 |
+| `status` 显示任务还在 `queued`/`running` | 就是还没轮到/还没跑完。发布时加 `--wait` 就不用手动盯 |
+| 提案一直 `pending`，`--wait` 却早早退出 0 | **这是 0.5.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 / 单测全都发现不了，靠读代码找它们非常慢。

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

@@ -0,0 +1,94 @@
+#!/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-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);
+};
+
+if (!key) die("缺少 LISTING_KEY", "在 .xgent-registry.env 里写 LISTING_KEY=<你的应用标识>，或用 --key 传");
+if (!portal) die("缺少门户地址", "在 .xgent-registry.env 里写 TARGET_XGENT_PLATFORM=<门户地址>，或用 --portal 传");
+if (!token) die("缺少发布令牌", "在 .xgent-registry.env 里写 XGENT_RELEASE_TOKEN=xrel_…（就是发版用的那枚）");
+
+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}'`);
+}