@xgent-ai/skills 0.3.0 → 0.5.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

@@ -54,6 +54,10 @@ npx @xgent/release-cli status      # 地址与令牌都不用写在命令里
 | 第一站（真发版） | `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 会提示一句 —— 所以**标准发布命令要带上它**。
 
@@ -80,7 +84,7 @@ npx @xgent/release-cli status      # 地址与令牌都不用写在命令里
 - **一枚令牌只对一个 listing 有效**。拿它去动别的 key 一律 `404`——门户**故意不区分**
   「不属于你」和「那个 App 不存在」，免得令牌变成探测别人 App 是否存在的工具。
 - 可随时吊销、可设过期时间。**每次调用实时查库**，所以吊销后下一次调用就 `401`，没有缓存窗口。
-- 它能**单方面生效**的仍只有自动通过档：`dist` · `version` · `deployDescriptor.image` ·
+- 它能**无需人工批准而应用**的仍只有自动通过档：`dist` · `version` · `deployDescriptor.image` ·
   展示字段 ·「值是 App 内路由 `/…`」的 `helpEntry`（外站 `https://…` 那一形态进审核档）。
   治理变更只能**提议**（随 `manifest` 提交，进平台审核队列，批准前库里一字不动）。
   它也**读不回** `descriptor.env`——响应体里永远没有它，因为那里面是生产密钥。
@@ -90,8 +94,8 @@ npx @xgent/release-cli status      # 地址与令牌都不用写在命令里
 ```
 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 轮询用）
+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  撤回自己【待审】的提案（提交方的权利）
 ```
 
@@ -105,7 +109,7 @@ 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 dist=@dist.tgz \             # 使用持久留存的原始包；只换后端可省，但不代表前端归档已补齐
   -F manifest=@deploy/portal/app.manifest.json   # 可选；清单变更/首次接入时带上
 ```
 
@@ -135,7 +139,7 @@ curl -X POST "$XGENT_PORTAL_URL/api/market/release/<key>" \
 （scopes / aclManifest / dependencies / exchangeTargets / serviceScopes /
 privilegedServiceScopes / usageMetrics / serviceBaseUrl /
 seat* / scopeLabels / embedUrl / embedCsp / type / 部署形态…，以及**任何门户不认识的字段**）
-⇒ 提案 `pending` 等平台审批；只有版本/产物/镜像/展示字段的差异 ⇒ `auto_approved` 当场生效。
+⇒ 提案 `pending` 等平台审批；只有版本/产物/镜像/展示字段的差异 ⇒ `auto_approved` 自动通过并应用清单/产物。
 其中 `privilegedServiceScopes`（平台特权 scope 的申请，如 `seats.read`）是最高一档：
 审批人要**逐条勾选确认**才能批准 —— 每条都带上说清用途的 `reason`，等待会短很多；
 已持有的特权 scope 幂等重放不再进审。
@@ -154,7 +158,7 @@ SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScope
 
 只有三种情况不是 200：`401`（令牌无效/吊销/过期）、`404`（令牌不是为这个 key 签发的），以及真故障。
 
-成功时 `data` 里（先看 `status`：`"applied"` = 已生效；`"pending"` = 等审批，此时只有
+成功时 `data` 里（先看 `status`：`"applied"` = 清单/产物阶段已应用，不代表整条交付已确认；`"pending"` = 等审批，此时只有
 `proposalId` / `kind` / `governance`（待审字段清单）有意义）：
 
 | 字段 | 含义 |
@@ -166,14 +170,13 @@ SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScope
 | `distFiles` | 产物顶层条目数 |
 | `distStores` | 落了哪些存储 |
 | `image` / `imageChanged` / `redeployQueued` | 镜像引用、是否变了、是否排了重部署任务 |
+| `delivery` | 新门户的本提案交付投影；旧门户可能没有该字段，不能据此确认网关 |
 
-## 5. 原子性：坏包碰不到线上那份
-
-一次调用内：解压 → 验根 `index.html` → 落 staging → rename 换上 → **同一次落库** `version` + `distDigest`。
-被拒时 `version` 与 `digest` 都不动，线上产物原封不动。
+## 5. 应用与执行不是一个事务
 
-所以「发布失败了，线上是不是已经半坏了」这个担心不成立——失败就是没发生。
-反过来也意味着：**版本号与产物永远同进同退**，不会出现「产物换了版本号没换」的漂移。
+坏包在解压/staging 校验阶段被拒时不会替换线上产物。之后的清单/产物应用、后端部署与网关加载
+是分阶段执行：后续失败可能发生在清单已经应用之后，须查看 applyError 与 delivery.failureStage。
+不能把任意“发布失败”解释为所有副作用都没发生，也不能把提案 applied 当成完整交付。
 
 ## 6. `--image` / `image`
 
@@ -201,61 +204,59 @@ SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScope
   要多 arch 用 `docker buildx --platform`。
 
 引用一变，门户排一条重部署任务：pm2 侧**先拉后换**（拉不到则旧容器原封不动、任务转 failed），
-K8s 侧滚动更新（旧 Pod 在新 Pod ready 前不下线）。**服务不会因为一次发布断掉。**
+执行失败须回读对应阶段；旧容器一旦已被替换，不能承诺继续提供旧服务。
 
-## 6.1 `--wait` / `--wait-review` / `status`：确认换版真的落地了
+## 6.1 按本次提案查询交付
 
-`publish` 返回 `redeployQueued: true` 只说明**任务排上了**。前端产物是同步的（那一刻已在线上），
-换容器不是——它可能几十秒后才完成，也可能失败（镜像没 push、robot 没权限、tag 打错）。
-不确认这一步，CI 会绿着退出而线上还跑着旧容器。
+新增契约的版本与启用前提见 [公开面与交付确认](public-delivery.md)：这些能力尚待正式发包/上线；
+目标门户须提供 delivery，扩展 CSP 还须 strict 与受控 v2 网关。不得仅按包版本标签猜能力已开。
 
 ```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
+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
 ```
 
-**两个开关等的是两件事（CLI 0.5.0 起）：**
-
-| 开关 | 等什么 | 提案落成待审时 |
+| 开关 | 等什么 | 新提交为 pending 时 |
 | --- | --- | --- |
-| `--wait [秒]` | 只等**容器换版** | 打印提案号，**退出 0 立即返回** |
-| `--wait-review [秒]` | 先等**人工审批**，批准且换了镜像再等换版 | 轮询到终态；被拒 / 撤回 / 超时 ⇒ 非零退出 |
-
-`--wait` 之所以不再等审批：审批是分钟到小时级的人的动作，而**提案落成的那一刻平台管理员就
-收到了站内 + 邮件通知**，把 runner 挂在上面既烧机器又什么都没保证。
-⚠️ 从 0.4.x 升上来：以前写 `--wait` 指望它等审批的流水线，现在会在提案待审时**直接绿**——
-要保持旧行为，把那一处改成 `--wait-review`。
-
-`--wait` 成功 → 打印实际在跑的镜像引用、零退出；失败或超时 → 打印原因、**非零退出**。
-没换镜像时它直接跳过，不空等。镜像来源不限 `--image`：**manifest 的
-`deployDescriptor.image` 换了镜像同样会等**（`--wait-review` 下则是提案批准后接着等）。
-判据看的是最近一条 `deploy|redeploy` 任务，不掺 `provision-tenant`（那是某个租户的 bootstrap，
-与镜像滚动无关）。
+| `--wait [秒]` | 获批后，本次固定目标的后端 + 网关；默认 1800 秒 | 打印提案号，退出 0；不等待人工 |
+| `--wait-review [秒]` | 人工审批，再等待本次交付；默认 1800 秒 | 等待；拒绝、撤回或超时非零退出 |
+| `status --proposal-id <id> --wait` | 继续查询这一提案，不能偷换成最新任务 | 等本次提案交付或超时 |
 
-门户上没有这个面时，`status` 与 `--wait` 都用不了：产物那半边照旧由 `publish` 的返回体
-（`version` / `distDigest` / `redeployQueued`）交代清楚，容器那半边只能找平台管理员看
-「服务部署」面板。**别用「命令退出码 0」替代这半边的结论。**
+纯前端 backend=not_applicable，仍要等 gateway。failed/superseded 使等待非零退出；unknown 保持
+未确认，超时非零退出。普通 status 只展示；配 --wait 才按交付结果设置退出码。
+旧门户完全没有 delivery 字段时，CLI 明示“无法核验网关”，只兼容原后端规则；即使退出 0，
+也不能声称端到端确认。有字段但为 null/unknown 则缺乏证据，不能冒用旧任务成功。
 
-`status` 返回：
+旧版 status 字段保留 version/distDigest/distUpdatedAt/image/deployment/proposal；指定 proposalId
+只限定新增 delivery，旧 proposal 字段仍可能是最近提案。不要混用两者。新 delivery 的形状：
 
 | 字段 | 含义 |
 | --- | --- |
-| `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` |
+| 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；仅公开脱敏状态 |
 
-这个面是**只读**的，且仍在同一条边界内：同一枚令牌、同样绑死一个 listing、跨 key 一样 404。
-`descriptor.env` 读不回来——**连藏在部署错误文本里的那份也不行**，出口会对它做值级抹除，
-所以错误消息仍然可读（`manifest unknown` 之类留着），只有密钥被换成 `«redacted»`。
+旧目标缺失及无法证明的运行事实为 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 范式
 
@@ -276,10 +277,15 @@ steps:
   - 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
+  # 按 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`。
@@ -291,7 +297,7 @@ steps:
 
 ## 8. 私有包只读令牌（`GET /api/market/release/:key/npm-token`）
 
-`@xgent/{release-cli,shared,portal-sdk,portal-ui}` 都在私有包仓上 —— **包括发版用的 CLI 本身**，
+`@xgent/{release-cli,shared,portal-sdk,portal-server-sdk,portal-ui}` 都在私有包仓上 —— **包括发版用的 CLI 本身**，
 所以这一步是整条发布链的前置，不只是装依赖。**你不需要云账号**：拿同一枚 `xrel_`
 向门户换一枚 ≤12 h 的只读令牌，门户持那把云凭据。
 

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

@@ -1,8 +1,16 @@
 # 排查速查
 
+**跨平台同步报 DIST_ARCHIVE_MISSING，尤其多个应用都缺包**：按
+[前端归档与同步验收](frontend-archive.md) 核对发布时点、服务端保留逻辑与实际上传包的留存。
+catalog 只收 manifest；旧版发布成功后会删归档。有 distDigest 不代表原始包仍在。
+
 先分清事故落在哪一层——**发不出去** / **发出去了但页面坏** / **发出去了但线上没变**。
 三层的成因不重叠，混着猜会很久。
 
+**已审批、后端 ready，仍打不开公开页或画布**：还要核验网关与业务层，见
+[public-delivery.md](public-delivery.md)。标准 /svc 可以承载正式公开 HTML，但 App 必须
+适配所有外部路径；publicEntrypoints 不创建门户根级路由；connectSrc 不放行脚本/字体。
+
 ## A. 发不出去（命令报错）
 
 | 症状 | 多半原因 | 怎么确认 |
@@ -17,6 +25,7 @@
 | `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 兜底 |
@@ -70,9 +79,9 @@ curl -s -o /dev/null -w 'status %{http_code}\n' -H "$H" "$XGENT_PORTAL_URL/api/m
 
 | 症状 | 多半原因 |
 | --- | --- |
-| 换了 `--image`，容器还是旧的 | `status` 看最近一条任务：`failed` 就是拉不到镜像（没 push / robot 没权限 / tag 打错）。**先拉后换**，所以旧容器还在跑、服务没断 |
+| 换了 `--image`，容器还是旧的 | 用 `status --proposal-id <id>` 看本次 delivery.backend 与失败阶段；可能是镜像、迁移或健康失败。旧容器已被替换时不保证旧服务仍可用 |
 | `status` 显示任务还在 `queued`/`running` | 就是还没轮到/还没跑完。发布时加 `--wait` 就不用手动盯 |
-| 提案一直 `pending`，`--wait` 却早早退出 0 | **这是 0.5.0 的既定行为**：`--wait` 只等换版。要卡在审批上用 `--wait-review`；平台管理员在提案落成时已收到通知，不必催 |
+| 提案一直 `pending`，`--wait` 却早早退出 0 | **仍保留提交与审批分离语义**：`--wait` 等获批后的本次交付。要卡在审批上用 `--wait-review`；平台管理员在提案落成时已收到通知，不必催 |
 | 审批屏说某个库 / Redis 的键「缺」 | 这个键不叫约定名（`<PREFIX>_DATABASE_URL` / `REDIS_CONN_STRING`），平台自动供给不到 ⇒ 只能人工点一下「从平台服务取值」。改成约定名后下次就零手填（预检会提前 warn 这一条） |
 | 同一个 tag 重推了，门户没反应 | tag 不可变是硬约定：引用没变**根本不排任务**（`status` 里看不到新任务就是这个）。新版本必须新 tag；真要按原样重建只能找平台管理员点面板的「重新部署」 |
 | 版本号发上去了，过一阵又变回旧值 | 该 key 是**门户仓内 App**（清单定义在门户代码里），version 随门户部署被等值对齐回定义值——仓内 App 不走自助发版面。外部 App 的清单事实源在你仓，不存在这个症状；真遇到就是有人在门户控制台手改过，找平台管理员对账 |
@@ -106,3 +115,10 @@ 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

@@ -7,7 +7,7 @@
  *   node npm-token.mjs --npmrc    # 打印可直接追加进 .npmrc 的三行
  *   node npm-token.mjs --check    # 只体检：能不能换到、还剩多久，不打印令牌
  *
- * `@xgent/{release-cli,shared,portal-sdk,portal-ui}` 都装在私有仓上 —— **发版用的 CLI 本身也在**，
+ * `@xgent/{release-cli,shared,portal-sdk,portal-server-sdk,portal-ui}` 都装在私有仓上 —— **发版用的 CLI 本身也在**，
  * 所以 `.npmrc` 没配好时 `npx @xgent/release-cli` 第一条就 E404。你**不需要**任何云账号或 CLI：
  * 用已有的发布令牌（`XGENT_RELEASE_TOKEN`，就是发版那枚）向门户换一枚 ≤12 h 的
  * **只读**令牌即可。门户持那把云凭据，轮换时你这边零改动。
@@ -36,9 +36,14 @@ const die = (msg, ...hints) => {
   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("缺少发布令牌", "在 .xgent-registry.env 里写 XGENT_RELEASE_TOKEN=xrel_…（就是发版用的那枚）");
+if (!token) die("缺少发布令牌", GET_CONFIG, NO_APP_YET, NO_VENDOR);
 
 warnIfProxyIgnored();
 
@@ -53,7 +58,7 @@ try {
   die(`连不上门户：${e?.message ?? e}`, `确认 ${portal} 可达（公司网络 / VPN）`, "稍后重试；这条链路超时不代表令牌有问题");
 }
 
-if (res.status === 401) die("发布令牌无效或已失效（401）", "去门户「应用详情 › 凭证」重新生成一枚，或让平台管理员补发");
+if (res.status === 401) die("发布令牌无效或已失效（401）", "去门户「开发者应用」› 你的应用 › 凭证 重新生成配置文件");
 if (res.status === 404) die(`门户上没有 ${key} 这个应用，或令牌绑的是别的应用（404）`, "核对 LISTING_KEY 与令牌是否同一个应用");
 if (res.status === 429) die("触发限流（429）", "稍等一分钟再试；CI 里别在每个 job 都换一次，换一次传下去");