@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/xgent-app-release/references/embed-csp.mjs

@@ -0,0 +1,126 @@
+// Standalone CSP declaration syntax snapshot; server capability and approval remain separate.
+export const EMBED_CSP_SOURCE_FIELDS = Object.freeze([
+  "connectSrc",
+  "scriptSrc",
+  "styleSrc",
+  "fontSrc",
+  "imgSrc",
+  "mediaSrc"
+]);
+export const EMBED_CSP_PLATFORM_FIELDS = Object.freeze([
+  "scriptSrc",
+  "styleSrc",
+  "fontSrc",
+  "connectSrc"
+]);
+const unsafe = /[\s\u0000-\u001f\u007f-\u009f\\'"`{};*]/u;
+const CONNECT_SCHEME_SOURCES = ["blob:", "data:"];
+function fail(field, reason) {
+  throw new Error(`${field}: ${reason}`);
+}
+function record(value, allowed, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail(field, "expected an object");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null)
+    fail(field, "expected a plain object");
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowed.includes(key))
+      fail(field, "unknown field");
+    if (!("value" in Object.getOwnPropertyDescriptor(value, key)))
+      fail(field, "accessors are not allowed");
+  }
+  return value;
+}
+function origin(value, field, options, allowWebSocket, allowPath = false) {
+  if (typeof value !== "string")
+    fail(field, "expected a string");
+  const source = value.replace(/^ +| +$/g, "");
+  if (!source || unsafe.test(source))
+    fail(field, "empty source or unsafe characters");
+  const parts = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]+)(\/[^?#]*)?$/i.exec(source);
+  if (!parts)
+    fail(field, "expected an explicit origin without query or fragment");
+  if (parts[2].includes("@"))
+    fail(field, "credentials are not allowed");
+  if (!allowPath && parts[3] !== undefined && parts[3] !== "/")
+    fail(field, "paths are not allowed");
+  let url;
+  try {
+    url = new URL(source);
+  } catch {
+    fail(field, "invalid URL");
+  }
+  const secure = url.protocol === "https:" || allowWebSocket && url.protocol === "wss:";
+  const devScheme = url.protocol === "http:" || allowWebSocket && url.protocol === "ws:";
+  const exactLoopback = /^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(parts[2]);
+  if (!secure && !(options.allowDevLoopback === true && devScheme && exactLoopback)) {
+    fail(field, "scheme is not allowed; insecure origins require explicit development loopback");
+  }
+  if (url.username || url.password || url.search || url.hash || url.origin === "null" || unsafe.test(url.origin)) {
+    fail(field, "invalid origin");
+  }
+  return url.origin;
+}
+export function normalizeEmbedCsp(value, options = {}) {
+  if (value === undefined || value === null)
+    return value;
+  const input = record(value, [...EMBED_CSP_SOURCE_FIELDS, "platformSources"], "embedCsp");
+  const result = {};
+  for (const field of EMBED_CSP_SOURCE_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(input, field))
+      continue;
+    const sources = input[field];
+    if (!Array.isArray(sources))
+      fail(`embedCsp.${field}`, "expected an array");
+    const normalized = [];
+    for (const source of sources) {
+      if (field === "connectSrc" && typeof source === "string" && CONNECT_SCHEME_SOURCES.includes(source.replace(/^ +| +$/g, "")))
+        normalized.push(source.replace(/^ +| +$/g, ""));
+      else
+        normalized.push(origin(source, `embedCsp.${field}`, options, field === "connectSrc"));
+    }
+    if (normalized.length)
+      result[field] = [...new Set(normalized)].sort();
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "platformSources")) {
+    const aliases = record(input.platformSources, EMBED_CSP_PLATFORM_FIELDS, "embedCsp.platformSources");
+    const platformSources = {};
+    for (const field of EMBED_CSP_PLATFORM_FIELDS) {
+      if (!Object.prototype.hasOwnProperty.call(aliases, field))
+        continue;
+      const values = aliases[field];
+      if (!Array.isArray(values))
+        fail(`embedCsp.platformSources.${field}`, "expected an array");
+      for (const alias of values) {
+        if (alias !== "jsCdn")
+          fail(`embedCsp.platformSources.${field}`, "expected jsCdn alias");
+      }
+      if (values.length)
+        platformSources[field] = ["jsCdn"];
+    }
+    if (Object.keys(platformSources).length)
+      result.platformSources = platformSources;
+  }
+  return result;
+}
+export function resolveEmbedCsp(csp, jsCdnBase, options = {}) {
+  const normalized = normalizeEmbedCsp(csp, options);
+  const result = {};
+  if (!normalized)
+    return result;
+  for (const field of EMBED_CSP_SOURCE_FIELDS) {
+    if (normalized[field])
+      result[field] = [...normalized[field]];
+  }
+  if (normalized.platformSources) {
+    const cdnOrigin = origin(jsCdnBase, "jsCdnBase", options, false, true);
+    for (const field of EMBED_CSP_PLATFORM_FIELDS) {
+      if (normalized.platformSources[field]?.includes("jsCdn")) {
+        result[field] = [...new Set([...result[field] ?? [], cdnOrigin])].sort();
+      }
+    }
+  }
+  return result;
+}

package/skills/xgent-app-release/references/frontend-archive.md

@@ -0,0 +1,67 @@
+# 前端归档与同步验收
+
+适用于带同源前端的应用发布，以及「manifest 已有但前端包缺失」的调查。
+服务型应用没有前端，不要求 dist；有前端的应用不能用「只发 manifest/镜像」代替前端交付。
+
+## 三处存储的区别
+
+| 位置 | 内容 | 能证明什么 |
+| --- | --- | --- |
+| App 仓/CI 的持久制品存储 | 本次实际上传的原始 tgz、SHA-256 与发布记录 | 可以重传完全相同的字节 |
+| 目标门户发布面 | 生效清单、解压后的前端及当前原始归档 | 当前应用的实际交付 |
+| MANIFEST_STORE 的 catalog | 净化后的公开 manifest，没有前端包 | 可以查清单，不能证明可同步 |
+
+跨平台同步源读取主平台的已生效 listing。若 TARGET_XGENT_PLATFORM 与主平台不同，
+向 MANIFEST_STORE 投清单不会把 tgz 发到主平台，也不会让主平台 listing 生效。
+主平台上的发布使用绑定该 App 的 xrel_ 走发布提案；xcat_ 只能读同步源，不能上传前端包。
+
+## 先留存实际上传的包
+
+CLI 的 `--dist dist/` 会生成临时 tgz，命令结束后删除它。预检也只生成临时包。
+二者都不是持久归档。先预检 dist 目录，再显式打包并将文件交给 CLI：
+
+```bash
+set -e
+# LISTING_KEY、VER 已从本次配置与版本确定；不把令牌取出写入发布记录。
+RELEASE_DIR=".xgent-releases/$LISTING_KEY/$VER"
+DIST_ARCHIVE="$RELEASE_DIR/dist.tgz"
+mkdir -p "$RELEASE_DIR"
+if test -e "$DIST_ARCHIVE"; then
+  echo "已有发布包：核对记录后复用，或使用新版本；不要覆盖原归档" >&2
+  exit 1
+fi
+tar czf "$DIST_ARCHIVE" -C dist .
+gzip -t "$DIST_ARCHIVE"
+shasum -a 256 "$DIST_ARCHIVE" > "$DIST_ARCHIVE.sha256"
+bunx @xgent/release-cli publish --version "$VER" --dist "$DIST_ARCHIVE" \
+  --manifest deploy/portal/app.manifest.json
+```
+
+发布后把目标门户、key、version、proposalId、包摘要及提交/审批结果写入项目现有发布记录，
+并核对发布响应的 distDigest 与包摘要一致。pending 时保留包并报告待审，不能报告已生效。
+将 `.xgent-releases/` 加入项目 gitignore；产物不提交源码仓。CI 必须将包、校验文件和发布记录
+上传到项目已有的持久制品存储，记录下载位置；仅留 runner 临时目录不算归档。
+该目录与存储中不放发布令牌或配置文件。
+
+## 可同步性单独验收
+
+主平台的同步源需要部署级 xcat_ 读取权限，App 发布用的 xrel_ 无此权限。
+已有权限时只读检查；没有权限时由平台管理员核验，明确记录未验证，不自行签发令牌或改平台设置。
+
+1. 查询 `GET /api/federation/apps/:key`，要求 Envelope.ok 为 true、data 非 null、
+   syncable 为 true、version 与本次已生效版一致；带前端应用的 distDigest 必须非空且等于上传包摘要。
+   列表 `/api/federation/apps` 不检查归档，不能用列表的 syncable 代替条目检查。
+2. 下载 `GET /api/federation/apps/:key/dist` 的实际 tgz，拒绝 JSON 错误体；复核 SHA-256
+   等于条目 distDigest 与留存包摘要，并验证压缩包完整、根下有 index.html。
+3. 分别记录发布、审批/部署/网关、浏览器主路径、原始包留存、主平台可同步性结果。
+   页面能开或 status 的 digest 正确，都不能代替第 1、2 项。
+
+## 调查 DIST_ARCHIVE_MISSING
+
+先核对当前 distDigest、发布时点、当时门户版本与包留存记录，再检查主平台本地/平台池的当前归档。
+不要把这个错误直接归因于 App 团队漏传 dist：摘要存在通常说明曾上传过，可能是历史服务端删除了包。
+旧版门户发布成功会删除提案归档，控制台直传也未保留原包；升级后的归档保留逻辑不会恢复已删历史包。
+
+若多个 App 同时缺包，整理所有受影响 key、版本、摘要、发布路径与原因，核对归档保留功能的
+上线时间；修正发布/验收流程，不能只修一条后宣称整个流程恢复。
+已有原始包时可以提出同字节重传方案；没有原始包时，解压目录重打包会改变摘要，不能冒称恢复原归档。

package/skills/xgent-app-release/references/public-delivery.md

@@ -0,0 +1,75 @@
+# 发布后的公开面、CSP 与交付确认
+
+## 版本与启用前提
+
+本节契约由 `@xgent/shared 0.7.0`、`@xgent/release-cli 0.7.0` 起提供，两包已在私有包仓发布。
+装上新版本只代表客户端认识这些字段与交付状态，**不代表目标门户已上线对应能力**：实际使用前回读
+目标门户的能力，并以平台发布公告为准。
+
+严格 CSP 校验默认关闭。平台完成历史来源盘点、兼容检查及受控 v2 网关切换后，才可启用扩展声明。
+只更新 App 的依赖、看到 whoami 成功或通过本地预检，都不代表服务器已启用。未启用时旧门户仍只接受
+connectSrc 兼容契约；不能凭空添加其他指令后宣称生效。预检会按新生产语法检查并提示能力门，不能替平台开启它。
+
+## 入口与权限边界
+
+| 页面 | 正式入口 | 关键责任 |
+| --- | --- | --- |
+| 前端静态/SPA 匿名页 | `/apps/<key>/…` | 正确 base、嵌套路由刷新、匿名页不先强制登录；数据授权仍由 App 验证 |
+| 后端直出 HTML | `/svc/<key>/…` | App 适配 cookie Path、form、fetch、Location、资源与预览；后端自己设置 CSP |
+| 站点/独立域名 | `publicEntrypoints` + Sites | 申请 sites 服务特权，满足平台开关、DNS/TLS/路由和租户权益；独立核对站点修订 |
+
+Sites 需要平台启用、登记入口和 DNS，租户具有 sites.enabled/portal.public_sites，自定义域还需
+portal.custom_site_domains。`sites.read/write` 经 privilegedServiceScopes 申请，不是用户权限。
+publicEntrypoints 只声明站点可绑定的后端前缀，不增加门户根代理。新 App 不得占用 `/v`、`/share`。
+历史根路径和 listingKey 改名均需另行迁移授权；改链接前缀不能代替 cookie、子请求和数据归属迁移。
+
+## 六类来源声明
+
+`embedCsp` 仅扩展本 App 的 `/apps/<key>/` 托管前端策略，不改变门户壳、沙箱或后端公开 HTML 的 CSP。
+完整 manifest 中可申报：
+
+```json
+{
+  "embedCsp": {
+    "connectSrc": ["https://api.example.com", "wss://events.example.com"],
+    "scriptSrc": ["https://components.example.com"],
+    "styleSrc": ["https://styles.example.com"],
+    "fontSrc": ["https://fonts.example.com"],
+    "imgSrc": ["https://images.example.com"],
+    "mediaSrc": ["https://media.example.com"],
+    "platformSources": { "scriptSrc": ["jsCdn"], "styleSrc": ["jsCdn"], "fontSrc": ["jsCdn"], "connectSrc": ["jsCdn"] }
+  }
+}
+```
+
+来源是精确 origin（协议、主机、可选端口），生产只接受 HTTPS；仅 connectSrc 另接受 WSS。
+允许末尾 `/`，不允许路径、query、fragment、凭据、通配符、控制字符、嵌入空白或未知字段。
+唯一例外：connectSrc 可原样申报 `blob:`、`data:`（前端 `fetch()` 本地 blob/data URL 时需要），
+其余字段不接受，`blob:https://…`、`data:,x` 等带内容的写法也不接受。
+不能申报 unsafe-inline、unsafe-eval、self、nonce、hash 等 CSP 关键字，也不能申报其他 scheme 源。
+App 不能修改 frame-ancestors、base-uri、object-src；平台既有兼容基线不是可自行申请的权限。
+开发环回 HTTP/WS 仅在服务端显式开发模式允许，本发布预检按生产规则拒绝。
+
+platformSources 只允许上述四个指令，值只允许 jsCdn，映射到目标门户当前配置的 CDN origin；
+不把某套门户 CDN 域名写死在 App 清单。它不能用于 imgSrc/mediaSrc，也不扩散到其他 App。
+
+省略整个 embedCsp 沿用已批准声明；null 清空额外声明；提供对象是**完整替换**，不是逐指令合并，
+未写指令会撤回，空数组表示该指令无额外来源。来源增删、清空和别名变更均按实际差异进入治理审核；
+排序、重复项及等价 origin 归一化后不制造变更。若省略后没有差异，不会仅因省略而进审。
+
+## 固定提案的四阶段
+
+1. 审批：pending 等人工；提交成功不等于批准。
+2. 清单/产物应用：提案 applied 只说明这一阶段完成，仍检查 applyError。
+3. 后端：只接受本次固定配置目标的实际运行证据；最近任务 succeeded 或别的镜像 ready 不代替它。
+4. 网关：只接受本次目标摘要和修订匹配的回执；纯前端后端为 not_applicable，仍要等待网关。
+
+支持新 delivery 的门户配合新版 CLI：`publish --wait` 等获批后的后端与网关；pending 仍直接退出 0，
+需要等人工决定使用 `--wait-review`。继续追踪用 `status --proposal-id <id> --wait`。
+失败或 superseded 非零退出；unknown 不能当成功，继续等待到预算结束仍未确认则非零退出。
+旧门户没有 delivery 时只按旧后端规则兼容，并明确提示“无法核验网关”；退出 0 也不声称完整交付确认。
+
+网关失败由平台管理员重试网关配置，不必重发清单，也不触发后端重部署。发布令牌没有管理员重试权限。
+API 字段与端点见 [发布 API](publish-api.md)。交付确认仍不是业务可用性的替代：真实验正文、CSP、
+正确/错误口令、过期/撤销、表单/数据源、预览权限、跨租户拒绝和重部署后的访问。HTTP 200 可能是占位页。
+交接只给提案号、版本、时间、脱敏状态和路径形状，不发 token、环境值或内部上游地址。

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

@@ -0,0 +1,321 @@
+# 发布面：令牌、端点、字段、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，**没有 dist 文件**。跨平台同步使用主平台已生效 listing 与原始包，
+不是 catalog。主平台归档留存、目标门户与主平台不同时的交付边界，以及同步验收见
+[前端归档与同步验收](frontend-archive.md)。不要把投目录成功报告成「前端包已归档/可同步」。
+
+两个地址相同时**照常两次调用** —— 它们是不同端点，不会互撞。
+没带 `--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?proposalId=<id>  只读：兼容状态 + 指定提案 delivery；省略 id 默认最新
+GET    /api/market/release/:key/proposals/:id  只读：单条提案状态 + delivery（--wait-review 审批轮询用）
+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 \             # 使用持久留存的原始包；只换后端可省，但不代表前端归档已补齐
+  -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` | 镜像引用、是否变了、是否排了重部署任务 |
+| `delivery` | 新门户的本提案交付投影；旧门户可能没有该字段，不能据此确认网关 |
+
+## 5. 应用与执行不是一个事务
+
+坏包在解压/staging 校验阶段被拒时不会替换线上产物。之后的清单/产物应用、后端部署与网关加载
+是分阶段执行：后续失败可能发生在清单已经应用之后，须查看 applyError 与 delivery.failureStage。
+不能把任意“发布失败”解释为所有副作用都没发生，也不能把提案 applied 当成完整交付。
+
+## 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），
+执行失败须回读对应阶段；旧容器一旦已被替换，不能承诺继续提供旧服务。
+
+## 6.1 按本次提案查询交付
+
+新增契约的版本与启用前提见 [公开面与交付确认](public-delivery.md)：这些能力尚待正式发包/上线；
+目标门户须提供 delivery，扩展 CSP 还须 strict 与受控 v2 网关。不得仅按包版本标签猜能力已开。
+
+```bash
+npx @xgent/release-cli publish --version "$VER" --dist dist/ --manifest app.manifest.json --wait
+npx @xgent/release-cli publish --manifest app.manifest.json --wait-review
+npx @xgent/release-cli status --proposal-id <id> --wait
+```
+
+| 开关 | 等什么 | 新提交为 pending 时 |
+| --- | --- | --- |
+| `--wait [秒]` | 获批后，本次固定目标的后端 + 网关；默认 1800 秒 | 打印提案号，退出 0；不等待人工 |
+| `--wait-review [秒]` | 人工审批，再等待本次交付；默认 1800 秒 | 等待；拒绝、撤回或超时非零退出 |
+| `status --proposal-id <id> --wait` | 继续查询这一提案，不能偷换成最新任务 | 等本次提案交付或超时 |
+
+纯前端 backend=not_applicable，仍要等 gateway。failed/superseded 使等待非零退出；unknown 保持
+未确认，超时非零退出。普通 status 只展示；配 --wait 才按交付结果设置退出码。
+旧门户完全没有 delivery 字段时，CLI 明示“无法核验网关”，只兼容原后端规则；即使退出 0，
+也不能声称端到端确认。有字段但为 null/unknown 则缺乏证据，不能冒用旧任务成功。
+
+旧版 status 字段保留 version/distDigest/distUpdatedAt/image/deployment/proposal；指定 proposalId
+只限定新增 delivery，旧 proposal 字段仍可能是最近提案。不要混用两者。新 delivery 的形状：
+
+| 字段 | 含义 |
+| --- | --- |
+| proposalId / approval | 被查询提案及其审批状态 |
+| state | pending / applied / failed / unknown / superseded |
+| target | null 或固定目标摘要：manifestDigest、distDigest、deploymentConfigDigest、gatewayDigest、gatewayRevision |
+| backend | state= pending / ready / failed / unknown / not_applicable；jobId 与脱敏 error |
+| gateway | state= pending / applied / failed / unknown / not_applicable；desiredRevision、appliedRevision 与脱敏 error |
+| failureStage / error | approval / application / backend / gateway，或 null；仅公开脱敏状态 |
+
+旧目标缺失及无法证明的运行事实为 unknown；后续目标取代本次为 superseded，哪怕摘要后来回到
+相同值也不能借旧修订冒认。只有本次实际后端目标和匹配网关回执齐备才 applied。
+最近一条 succeeded job 或 deployment.ready 不能替代上述判据。
+
+维护者查询仍用绑定此 App 的 release token：跨 key 不可读，指定别的 App 的 proposalId 也无数据。
+新交付状态不返回环境值、内部 upstream 或原始执行日志。可交接提案号、摘要和脱敏失败阶段。
+
+平台管理员另有控制台 session 接口：
+
+```
+GET  /api/console/releases/:id/delivery
+POST /api/console/releases/:id/retry-gateway
+Body: { "expectedTargetDigest": "<当前提案的 gatewayDigest>" }
+```
+
+Envelope.data 为同一 delivery DTO；重试必须目标仍有效，旧目标冲突拒绝。重试仅协调网关，
+不重放清单，不触发后端重部署。发布令牌不能调用该管理接口；非平台租户无权使用。
+
+## 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
+  # 按 frontend-archive.md 生成 DIST_ARCHIVE、校验文件；使用 CI 的跨步骤变量机制传递包路径。
+  - run: bunx @xgent/release-cli publish --version "$VER" --dist "$DIST_ARCHIVE" --image <key>:$VER --wait
+          --manifest deploy/portal/app.manifest.json   # ← 不带它目录永远是空的
+  # 无论发布成功、待审或失败，都将原始包、校验文件及发布记录存到项目的持久制品存储。
+```
+
+涉及跨平台同步的交付还需按 [前端归档与同步验收](frontend-archive.md) 检查主平台条目与下载摘要；
+`--wait` 等部署/网关，不核验当前归档可下载。
+
+`--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-server-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`）把这些都封好了。