@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/why/references/sources/sentry.md

@@ -0,0 +1,100 @@
+# Sentry Error History
+
+## What this source contains
+
+Sentry is the archive of things that went wrong. For defensive, corrective, or error-handling code, it often holds the direct motivation: the specific exceptions, stack traces, and frequencies that pushed someone to add a check, catch, retry, or fallback.
+
+- **Issues.** Grouped errors with counts, first/last seen timestamps, affected releases, and comments
+- **Events.** Individual error instances within an issue (stack traces, tags, user context)
+- **Releases.** Deployment records with associated issues (useful for "which version fixed this?")
+- **Replays.** Session recordings of user-facing errors (if enabled)
+- **Profiles.** Performance profiling data (less useful for "why", more for "how slow")
+- **Issue comments & assignments.** Sometimes contain engineer notes on root cause
+
+The most valuable thing Sentry provides is **temporal correlation**: "issue X was created 2024-01-02, peaked at 500 events/day, stopped appearing after release v2.14.0 on 2024-01-15, the release that shipped the defensive check."
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Good query components: exception class names the target handles, the function or class name of the target, error message strings the target checks for, the file path of the target.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check:
+   - **First seen.** When did the error start appearing?
+   - **Last seen.** When did it stop? Does it line up with the target's ship date?
+   - **Affected releases.** Which versions saw it? Which was the fix?
+   - **Frequency trajectory.** Did it spike, then get resolved?
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer produces AI root-cause analyses. Useful as a hypothesis generator, but treat them as inference, not authoritative. The actual events and stack traces are the primary evidence. Seer's narrative is secondary.
+
+## What good evidence looks like here
+
+- An issue whose **first seen** is shortly before the target's PR and **last seen** shortly after, suggesting the target addressed this error
+- Stack traces that pass through or land on the target function, showing the exact failure mode being defended against
+- A comment on the issue from the PR author describing the fix
+- The target's PR description or commit message referencing a Sentry issue URL or ID
+- An issue with high event counts that stops after the release containing the target
+
+## Common pitfalls
+
+- **Grouping drift.** Sentry groups errors by fingerprint. Refactors or renames can track the "same" error under a new issue ID. If an issue ends abruptly, the error may have just been regrouped. Check for new issues immediately after.
+- **Release correlation is noisy.** A release contains many commits. An issue stopping at v2.14.0 doesn't prove the target fixed it. Another change in the same release might have. Cross-reference with the target's exact commit.
+- **Silent fixes.** Sometimes the error stops because upstream changed, not because of the defensive code. The correlation suggests the fix. It doesn't prove authorship.
+- **Resolved != fixed.** Issues can be marked "resolved" manually without any code change. Treat `resolved` as a human marker, not evidence that code fixed it.
+- **Seer hallucinations.** Seer can generate confident-sounding explanations that aren't right. Fall back to the actual events, stack traces, and timestamps when making claims.
+- **Sampling.** Some projects sample events aggressively. A low event count may just mean high sampling, not a rare error. If in doubt, note the gap.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/skills/why/references/sources/slack.md

@@ -0,0 +1,54 @@
+# Slack Conversations
+
+## What this source contains
+
+- Real-time discussions of problems and decisions
+- Incident channels where fire-drill decisions were made
+- Design discussion threads where tradeoffs were debated
+- Questions answered by senior engineers that didn't make it into docs
+- Post-merge discussions that explain why something was revisited
+- DMs (usually not searchable, scope accordingly)
+
+Slack is frequently where the *real* decisions got made, especially for smaller changes that didn't warrant a doc. It's also the most ephemeral source. Threads get deleted, channels get archived, and search quality degrades over time.
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+2. **Keyword search for the feature name and key symbols.** Include misspellings and casual phrasings.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+5. **Channel-scoped search.** Narrow to likely channels:
+   - `#eng-*`. Engineering discussions
+   - `#proj-*`. Project channels
+   - `#incident-*` / `#sev-*`. Incident channels
+   - Team-specific channels for the owning team
+   - Design review channels
+6. **Thread traversal.** When you find a relevant message, fetch the whole thread. The decision often lives in the replies.
+
+## What good evidence looks like here
+
+- A thread where tradeoffs were explicitly debated ("I was going to use A but B is better because...")
+- An incident channel message describing the bug the code prevents
+- A question from a reviewer and an authoritative answer from the author or lead
+- A reference to a meeting where a decision was made
+- A message from a product manager or customer-facing engineer explaining a customer ask
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.
+
+## What to return
+
+For each relevant thread:
+- Channel name
+- Permalink or thread ID
+- Participants
+- Date range of the discussion
+- The key quotes (verbatim) with attribution
+- Context: what thread/incident/discussion this was part of

package/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,135 @@
+# Synthesizer Prompt Template
+
+Build the synthesizer's prompt from this template. Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from multiple investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that honestly communicates what the evidence supports and what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow the framework in `references/epistemics.md`. Read it in full before writing the output. The key rules:
+
+1. Every claim sits in one of these tiers: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier determines what section the claim goes in and how it's phrased.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Gaps in the evidence must be documented. Don't fill them with plausible-sounding guesses.
+6. If the user's question embedded a hypothesis, treat it as a candidate, not a conclusion. Check the evidence independently.
+
+## Instructions
+
+1. **Read all investigator findings.** They gathered raw evidence, not conclusions. You weigh it.
+2. **Reconcile overlapping findings.** Multiple investigators may have cited the same PR, ticket, or doc. Merge into a single, authoritative reference.
+3. **Identify contradictions.** If two items of evidence disagree, don't pick one. Surface both.
+4. **Calibrate confidence.** For each claim, identify the evidence and the tier. State Direct claims plainly with a citation. Hedge Inferred claims and explain the inference. Mark Speculative claims explicitly. Put claims with no evidence in the gaps section.
+5. **Verify citations by spot-checking.** You can read the codebase and call MCP tools to verify citations. Do not write files, commit, or modify external state. If you're uncertain a cited item exists or says what's claimed, check it. Don't propagate errors.
+6. **Don't overreach.** The user will act on your output. Better to leave an open question open than to fill it with a confident-sounding guess.
+
+## Output Format
+
+Write the output for the user. Use this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences so the answer is anchored.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a reader who lands here cold.
+
+### What We Found
+
+**Claims with direct evidence**, one per bullet. Quote or paraphrase the source and cite precisely. Format each finding like:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+Use `[Direct]` for single-source, explicit evidence. Use `[Supported]` when multiple indirect items converge on a conclusion.
+
+### What We Can Reasonably Infer
+
+**Claims that aren't explicitly stated anywhere but are well-supported by indirect evidence.** Make the inference chain visible: "Given A and B, it's likely that C." Use hedged language ("appears to", "likely", "suggests", "is consistent with"). Format:
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+If there's nothing to infer, skip this section.
+
+### Competing Hypotheses
+
+**If the evidence fits multiple stories, present them.** Don't force a winner when the record doesn't support one. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+**Explicit gaps.** Things the user asked that the evidence didn't answer. Sources searched that came up empty. Sources that weren't searchable at all, such as a missing real-time team chat MCP.
+
+Be specific. "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold" is useful. "We don't know why" is not. Include:
+
+- Specific questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable (and why)
+- People who would likely know but who you can't ask
+
+### Sources Consulted
+
+Bulleted list of what was actually searched, so the user can judge coverage and redirect. Format:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences summarizing your overall confidence. E.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Before finalizing, review your output against this checklist:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move the claim to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface any contradictions you noticed, or did you quietly pick one?
+4. Does the "What We Don't Know" section exist and name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. If the user embedded a hypothesis in their question, did you check it against the evidence rather than rubber-stamping it?
+6. Did you cite any code as evidence for its own intent? Remove those. Code is mechanics, not motivation.
+7. Is the overall tone calibrated? A confident-sounding answer with weak evidence is the exact failure mode this skill exists to prevent.
+
+If any item fails, revise before returning.
+
+## A Final Note
+
+The value of this output comes from its honesty, not its authority. A reader who takes your answer to the original author, an engineering lead, or a product manager should be well-positioned to ask the right follow-up questions. Be clear about what's known, what's inferred, and what's missing. Don't optimize for looking decisive. Optimize for being useful.

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

@@ -1,6 +1,6 @@
 ---
 name: xgent-app-release
-description: '把一个 App 的新版本发布到 XGENT.ai Portal —— 在 App 自己的 repo 里用 xrel_ 发布令牌一条命令提交「前端产物 dist / bump 版本 / 换镜像 / 整份 app.manifest 清单」，落成发布提案：无治理变更自动生效，改权限面的进平台「发布审核」等批准；不登录门户控制台、不找门户运维代传。凡任务涉及发版/发布前端或后端镜像/上传产物/提交或修改 app.manifest.json/首次把 App 接入门户/release-cli/xrel_ 令牌/POST /api/market/release/、配 vite base、在 CI 里写发布步骤、或出现「`npx @xgent/release-cli` 取不到 / E404（它在私有包仓上）」「发布 401 / 404」「发布 200 但 ok:false」「PROPOSAL_PENDING / 一直 pending 等审」「/apps/<key>/ 白屏或资源 404」「发上去了但线上没变 / 容器没换版」这类症状时，务必先用本 skill 再动手——即使用户只说「发个版」。Use whenever publishing or debugging an XGENT portal app release from the app''s own repo — frontend dist, backend image, or manifest/governance changes via release proposals: release tokens, packaging, version bumps, CI wiring, pending approvals, or a blank/404 /apps/<key>/ page after a publish.'
+description: '把一个 App 的新版本发布到 XGENT.ai Portal —— 在 App 自己的 repo 里用 xrel_ 发布令牌一条命令提交「前端产物 dist / bump 版本 / 换镜像 / 整份 app.manifest 清单」，落成发布提案：无治理变更自动通过并应用，改权限面的进平台「发布审核」等批准；不登录门户控制台、不找门户运维代传。凡任务涉及发版/发布前端或后端镜像/上传产物/提交或修改 app.manifest.json/首次把 App 接入门户/release-cli/xrel_ 令牌/POST /api/market/release/、配 vite base、在 CI 里写发布步骤、或出现「`npx @xgent/release-cli` 取不到 / E404（它在私有包仓上）」「发布 401 / 404」「发布 200 但 ok:false」「PROPOSAL_PENDING / 一直 pending 等审」「/apps/listingKey/ 白屏或资源 404」「发上去了但线上没变 / 容器没换版」这类症状时，务必先用本 skill 再动手——即使用户只说「发个版」。Use whenever publishing or debugging an XGENT portal app release from the app''s own repo — frontend dist, backend image, or manifest/governance changes via release proposals: release tokens, packaging, version bumps, CI wiring, pending approvals, or a blank/404 /apps/listingKey/ page after a publish.'
 ---
 
 # xgent-app-release · App 版本自助发布
@@ -12,7 +12,7 @@ description: '把一个 App 的新版本发布到 XGENT.ai Portal —— 在 App
 
 - **自动通过档**：`dist`（前端产物）· `version` · `deployDescriptor.image` · 展示字段
   （name / tagline / desc / icon / color / cat / navItems / dashboardWidgets）——
-  提交即生效，与从前一字不差，且每次留档（时间 + diff + 令牌前缀）。
+  自动通过并应用清单/产物；后端与网关需分别确认，且每次留档（时间 + diff + 令牌前缀）。
 - **审核档**：其余一切（scopes / ACL 清单 / 依赖 / 跨应用授权 / 服务地址 / 席位 /
   授权文案 scopeLabels / iframe 指向 embedUrl / 部署形态 / 部署前置 env 键清单
   requiredEnv / 服务账号身份 serviceAccount.clientId / 首次接入）都会改变权限面，
@@ -29,7 +29,7 @@ description: '把一个 App 的新版本发布到 XGENT.ai Portal —— 在 App
 
 **它就是你 App 清单的唯一事实源**，而且**直接参与发版**：
 `publish --manifest deploy/portal/app.manifest.json` 把它随提案交上去 ——
-无治理变更的自动生效，有治理变更的等平台批准。门户代码里不再保留你清单的副本，
+无治理变更的自动通过并应用，有治理变更的等平台批准。门户代码里不再保留你清单的副本，
 「改了 manifest 却被门户下次部署改回去」的静默漂移已经从机制上消灭。
 
 manifest **绝不携带密钥值**：`serviceAccount.secret`、`deployDescriptor.env` 有值、
@@ -39,7 +39,7 @@ SERVICE_ONLY scope（如 `seats.read`）写进 `serviceScopes` 都会**提交即
 reason 会原文展示给审批人，写清楚用途能少一轮往返。上报自己的用量指标，先在
 `usageMetrics` 里声明（key 必须以你的 listingKey. 开头；同样治理档）——没声明的
 metricKey 会被上报接口拒收并计入 `rejected`。要声明「部署我需要哪些环境变量」
-用 `requiredEnv`（只交键名），值永远由平台管理员在控制台填 —— 见下面「镜像要环境变量」。
+用 `requiredEnv`（只交键名），值由平台注入、自动供给或管理员配置 —— 见下面「镜像要环境变量」。
 
 ### 文案字段：哪些支持多语，哪些不支持
 
@@ -79,10 +79,14 @@ metricKey 会被上报接口拒收并计入 `rejected`。要声明「部署我
 
 ## 先备齐三样，缺一样就发不出去
 
+涉及匿名公开页、CDN 画布、CSP 阻断、改 App key 或“批准且 ready 但不可用”时，
+先读 [references/public-delivery.md](references/public-delivery.md)。现有标准入口是
+`/apps/<key>/…`、`/svc/<key>/…` 或 Sites；审核、部署、网关与业务验收分别核对。
+
 | 你需要 | 从哪来 | 放在哪 |
 | --- | --- | --- |
 | `listingKey` | 平台给的 App 标识，小写字母/数字/连字符。它同时是 `/svc/<key>`、`/apps/<key>/`、scope 命名空间、令牌的 aud —— **四位一体，永不改** | `LISTING_KEY=…` |
-| 发布令牌 `xrel_…` | 平台管理员在 控制台 › 应用市场 › 接入新应用（或 应用清单 › 发布令牌）签发，**明文只显示一次** | `XGENT_RELEASE_TOKEN=xrel_…` |
+| 发布令牌 `xrel_…` | 门户「开发者应用」› 你的应用 › 凭证 › **生成配置文件**（连同 listingKey、门户地址一次写好），**明文只显示一次**。开发者应用里还没有这个应用 ⇒ 先「申请建立应用」，平台管理员批准后才能生成 | `XGENT_RELEASE_TOKEN=xrel_…` |
 | 目标门户地址 | 问平台要 | `TARGET_XGENT_PLATFORM=…`（旧名 `XGENT_PORTAL_URL` 仍认） |
 
 **五项全部写进同一份本地配置文件 `.xgent-registry.env`**（另两项见下面「顺带投一份到清单目录」），
@@ -118,6 +122,9 @@ MANIFEST_STORE_TOKEN=xrel_…         # 目录那台签给你的发布令牌；
 - 目录**只是一份只读投影**：它不下发、不部署、不编排任何东西，也不参与任何门户的治理判定。
   它唯一的消费者是**开发环境** —— 别人起一盒时 `onebox.sh add <key>` 从这里拉你的清单，
   不再依赖「那版一盒镜像里预置了哪几份样例」。
+- **投递 manifest 不会上传前端包。** 跨平台同步读取主平台已生效的 listing 与原始归档
+  （`/api/federation/apps/:key` 与 `/dist`）。投目录成功、发布 applied、页面能打开，
+  都不能单独证明可同步。带前端的应用按 [前端归档与同步验收](references/frontend-archive.md) 留存、上传并核验。
 - 目录里那份是**净化过的**：`serviceAccount` 只留 `clientId`，`exchangeInitiatorSecret` 与
   `deployDescriptor` 的 `env` / `envFile` / `hostPort` 一律剔除（密钥与单部署事实不跨部署共享）。
 - **目标门户那边卡在待审不影响投目录**：`PROPOSAL_PENDING` 是目标门户的队列状态，
@@ -126,10 +133,44 @@ MANIFEST_STORE_TOKEN=xrel_…         # 目录那台签给你的发布令牌；
 
 ## 第 0 步：配私有包仓（**`@xgent/release-cli` 自己也在上面**，不需要任何云账号）
 
-`@xgent/release-cli` 与 `@xgent/shared` / `@xgent/portal-sdk` / `@xgent/portal-ui` 发在**同一个
-私有包仓**上，公共 npm 上一个都没有。所以这一步**不只是装依赖**：`.npmrc` 没配 `@xgent:registry`，
-下面第 1 步的 `npx @xgent/release-cli whoami` 就是第一条撞墙的命令
+`@xgent/release-cli` 与 `@xgent/shared` / `@xgent/portal-sdk` / `@xgent/portal-server-sdk` /
+`@xgent/portal-ui` 发在**同一个私有包仓**上，公共 npm 上一个都没有。所以这一步**不只是装依赖**：
+`.npmrc` 没配 `@xgent:registry`，下面第 1 步的 `npx @xgent/release-cli whoami` 就是第一条撞墙的命令
 （`E404 Not Found - GET https://registry.npmjs.org/@xgent%2frelease-cli`）。
+**App 代码第一次要装 `@xgent/*`（还没到发版）也走这一步**，不必等到发版。
+
+**没有发布令牌就停下，别绕。** 仓里没有 `.xgent-registry.env`、或里面没有 `XGENT_RELEASE_TOKEN`
+⇒ 停止安装，请开发者先去门户「开发者应用」› 你的应用 › 凭证 › **生成配置文件**，把下载的
+`.xgent-registry.env` 放到仓根（`chmod 600`，加进 `.gitignore`）再继续。开发者应用里还没有这个
+应用 ⇒ 先「申请建立应用」，平台管理员批准后才能生成；打开开发者应用提示没有开发者权限 ⇒ 请租户
+管理员在「用户管理」里发「开发者」角色。
+
+### 套件（bundle）：一枚令牌发一组应用
+
+一组 App 由同一支团队交付、**后端跑在同一个镜像里**时，门户里把它编成「套件」：
+开发者应用 › 我的套件 › 新建，把成员应用加进去（成员必须是 descriptor 型出仓 App、
+没有独立部署在跑、镜像与其它成员一致）。
+
+- **令牌**：套件详情 › 凭证 签的 `xrel_` 对**任一成员**都有效 —— 单发照旧走
+  `POST /api/market/release/<成员key>`（CLI 零改动）；凭证页会列明这枚令牌能发哪几个应用，
+  别把套件令牌当单应用令牌随手分发。成员被移出套件 ⇒ 令牌对它即刻 404；维护者离场 ⇒
+  套件令牌连同吊销。
+- **批次**：`POST /api/market/release/bundle/<bundleKey>`（bundle 令牌），一次给全体成员
+  各建一条提案，共享同一批号与同一镜像/版本。JSON 体：`version` / `image` 共享，
+  每成员可选 `dist__<key>`（文件）与 `manifest__<key>`。任一成员的确定性校验不过 ⇒
+  整批不落库；成员镜像已漂移而批次没带镜像 ⇒ `BUNDLE_IMAGE_DIVERGED`（带上镜像即可收敛）。
+  状态轮询：`GET /api/market/release/bundle/<bundleKey>/status`（每成员一条）。
+- **共享后端的 manifest**：成员各自的 `deployDescriptor.image` 的**仓库段可以等于 bundleKey**
+  （治理闸对套件镜像放行）；端口/环境变量以最早加入的成员为准。成员的对外地址不变：
+  各自 `/svc/<成员key>`，容器只是同一个（`<bundleKey>-server`）。共享 ⇒ 故障域合一：
+  容器挂了，全部成员一起不可用，各自的告警各自到。
+- **加不进去的两种真原因**：报 `BUNDLE_BUILTIN_MEMBER` ⇒ 那是仓内内置 App，先出仓再进套件；
+  报 `BUNDLE_MEMBER_ALREADY_DEPLOYED` ⇒ 它已有独立容器在跑，先让平台管理员在
+  「服务部署」里停止，再加入。
+
+**不许 vendor。** 装不上时不要把 `@xgent/*` 的产物或源码拷进仓（`vendor/` 目录、`file:` / `link:`
+依赖、向人要 tar 包、手抄一份 SDK），也不要自己重写 SDK 已有的能力。私有仓上没有你要的版本
+⇒ 停下，请平台团队发布那一版。本地快照不会随平台的修复更新，会和门户协议悄悄漂开。
 
 **动手发版之前先查一眼配没配**（`npm config get` 会把 `./.npmrc`、`~/.npmrc` 整条链解析完）：
 
@@ -189,21 +230,25 @@ VER=1.4.2      # 地址、令牌、listingKey 都在 .xgent-registry.env 里，
    平铺与 Envelope 都支持：非 2xx 不通过；2xx 顶层有 `ok` 时必须 `ok === true && data.db === true`；
    没有顶层 `ok` 时按 2xx 判健康。检查脚本与平台同源，不另加包装或字段命名限制。
 4. **发布。**
+   带前端的应用先按 [前端归档与同步验收](references/frontend-archive.md) 生成并持久留存
+   `DIST_ARCHIVE`（根下直接是 index.html 的 `.tgz`）与 SHA-256；下面上传的必须就是这份文件。
+   只发后端/治理变更可省略 dist，但不能据此声称前端归档已补齐；服务型应用不要求前端包。
    ```bash
-   npx @xgent/release-cli publish --version $VER --dist dist/ \
+   bunx @xgent/release-cli publish --version "$VER" --dist "$DIST_ARCHIVE" \
      --manifest deploy/portal/app.manifest.json
-   # 有后端、这次还换了镜像时，加 --image <key>:$VER --wait
+   # 获批后等待本次后端与网关：加 --wait；换镜像另加 --image <key>:$VER
    ```
    **每次都带 `--manifest`**：内容没变的重复提交是自动档（不会多一次人工审），而
    ①它是清单目录唯一的输入 —— 不带就等于目录永远是空的；②`requiredEnv` 这类
    「不落 listing」的声明只有随清单提交才能刷新基线。
-   → 验收：打印 `✓ <key> 已发布 <version>` + 产物 digest。**失败时线上那份原封不动**
-   （门户先落 staging、验根 `index.html`、再 swap；被拒时 `version` 与 `digest` 都不动）。
+   → 验收：本次产物 digest 与留存包的 SHA-256 一致，并记录 proposalId。坏包在 staging 校验失败时不会替换线上产物；应用后的部署或网关失败须按阶段检查，不能概括为“什么都没发生”。
    有治理变更时打印的是「提案已提交」+ 提案号，**同样退出 0 并立即返回** —— 平台管理员
    在那一刻就收到了通知，流水线没有理由挂在那里等人（见下面「等审批」）。
 5. **线上看一眼。** `npx @xgent/release-cli status` 确认版本与 digest 就是本次这一份；
    然后浏览器打开门户 → 应用中心 → 你的 App，走通主路径。**`status` 报 404 不等于发布失败**
    （见下），第 4 步的返回体已经给了版本与 digest，浏览器那一眼照走不误。
+   交付包含跨平台同步时，还须核验主平台条目和 `/dist` 的真实字节；没有读取权限时明示
+   「前端已发布，主平台归档/可同步性未验证」，不能把发布或投目录成功当作同步验收通过。
 
 `@xgent/release-cli` 不在公共 npm 上，**它就在第 0 步那个私有包仓里**。取不到包时先分诊，
 别急着换工具：`npm config get @xgent:registry` 是 `undefined` ⇒ 回第 0 步配 `.npmrc`，一条命令就好。
@@ -222,8 +267,8 @@ whoami `200` 而 `/status` `404`，就是这种情况：**令牌没问题，别
   version 归你所有（清单事实源在你仓里）；`--version` 可省略，省略时取 manifest.version。
 - **发布是替换，不是合并。** 上一版的文件不会留着。所以「只补传一个改了的文件」这种操作不存在，
   每次都传完整 dist。
-- **tar 根必须直接是 `index.html`。** `release-cli` 传目录时已经用 `tar czf … -C dist .` 打好；
-  只有自己 `curl` 时才需要自己打，`tar czf x.tgz dist` 那种套一层 `dist/` 的包会被拒收。
+- **tar 根必须直接是 `index.html`。** CLI 传目录会生成临时包并在命令收尾删除；本流程先留存
+  完整 `.tgz` 再用 `--dist` 上传该文件，保证留存的是实际上传的字节。套一层 `dist/` 的包会被拒收。
 - **上限 64MB**，且门户只按顶层条目数报数。真超了先查有没有把 source map / 未压缩素材打进去。
 - **本机配了代理就用 `@xgent/release-cli` ≥0.6.0。** Node 内置的 `fetch` **不读** `HTTPS_PROXY`
   —— curl / git / npm / docker 全都读，唯独发版这一步不读，于是它绕开本机代理直连门户：跨境
@@ -235,15 +280,15 @@ whoami `200` 而 `/status` `404`，就是这种情况：**令牌没问题，别
 ## 顺带换镜像（有后端的 App）
 
 同一次 `publish` 可以带 `--image <name>:<tag>`：镜像引用一变，门户自动排一条重部署任务，
-生产两条链路（pm2 / K8s）都会滚到新版本。三个易错点：**① `<name>` 就是你的 App key，不是
+当前支持的部署驱动异步执行，实际完成状态需回读。三个易错点：**① `<name>` 就是你的 App key，不是
 `<key>-server`；② 只写相对名，仓库前缀由门户拼；③ tag 不可变——同 tag 覆盖推送门户看不出变化，
 不会触发换版。** 该 App 必须已由平台管理员配了 `deployDescriptor`，否则这一项直接 `VALIDATION_FAILED`。
 
-**换镜像时加 `--wait`。** 产物是同步的（打印成功时已在线上），换容器不是——门户只排了任务，
-容器过一会儿才换、而且可能失败。不加 `--wait`，CI 会在这之前就退出码 0，把「发布成功」
-和「新版本在跑」画上等号。细节见 [references/publish-api.md](references/publish-api.md)。
-`--wait` 轮询的就是上面那个只读面：**门户上没有它时这一步失效**，「容器换没换」只能人工确认，
-如实说明，不要因为流水线绿了就报「新版本已在跑」。
+**需要确认交付时加 `--wait`，纯前端也一样。** 支持新 delivery 的门户按本次 proposalId 固定目标，
+等待后端与网关回执；待审不会自动等待，需加 `--wait-review`。unknown 不能当成功，superseded 表示
+已被后续目标取代。旧门户无 delivery 时会明确提示无法核验网关，不能把兼容退出 0 当完整确认。
+版本与 strict/v2 启用前提见 [公开面与交付确认](references/public-delivery.md)，API 见
+[发布 API](references/publish-api.md)。上述新增能力尚待正式发布与受控启用。
 
 ## 镜像要环境变量：**键名归你，值归平台**
 
@@ -260,6 +305,30 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
 `PORTAL_BASE_URL` 是**浏览器可达的门户公开地址**，也是你调别的 App `/svc/<key>/…` 的基址；
 `API_BASE_URL` 是内部 portal-api，**不代理 `/svc`** —— 两个别互相顶替。
 
+### 调用门户内的其他 App：从 `PORTAL_BASE_URL` 派生地址
+
+门户已通过 `/svc/<key>` 统一代理 App 服务。调用这些服务时，在应用代码里用平台注入的
+`PORTAL_BASE_URL` 拼接服务路径；不要求管理员逐个提供目标服务的主机名、容器名或端口。
+以 Page Builder 调用 LLM 网关和文件服务为例：
+
+| 原来的地址变量 | 应用代码使用的默认基址 |
+| --- | --- |
+| `LLM_GATEWAY_SERVER_URL` | `${PORTAL_BASE_URL}/svc/llm-gateway` |
+| `FILES_SERVER_URL` | `${PORTAL_BASE_URL}/svc/files` |
+
+- **manifest**：这两个地址能推导，就不再列入 `requiredEnv`；改为声明 `PORTAL_BASE_URL`，
+  并保留其他确实必需的键。平台会注入门户地址，**不会自动注入这两个旧变量**。
+- **代码**：去掉门户基址末尾的 `/` 后拼接路径，再追加具体 API 路径（例如 LLM 的
+  `/v1/chat/completions`）。如保留旧变量用于本地调试或特殊部署，把它们作为可选覆盖项，
+  未设置时使用上表默认值。不要将 `${PORTAL_BASE_URL}/…` 当成值写进发布 manifest。
+- **迁移**：代码的默认值与启动校验、manifest、包含新代码的新镜像要同步交付；只删
+  `requiredEnv` 不会让仍强制读取旧变量的镜像自动兼容。已有覆盖值仍会优先使用，需由平台侧
+  核对是否保留。发布前在未设置这两个旧变量时，验证经 `/svc` 的实际调用。
+- **鉴权**：统一入口只解决路由。代表用户调用仍需声明 `exchangeTargets` 与目标 scopes，
+  换取目标 App 的令牌；后台服务调用仍用获准的服务账号权限。不要直接转发本 App 的用户令牌。
+
+这是**门户内 App 服务地址**的约定；第三方 API 等无法从门户基址推导的地址，仍按实际需要声明。
+
 ### `<PREFIX>_APP_SECRET`：跨应用交换的发起方密钥（归平台，线上永不手填）
 
 只要你的清单声明了 `exchangeTargets`（你要去调别的 App），平台就在**批准那一刻**生成这枚密钥、
@@ -344,10 +413,9 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
   两条写法约束：`renamedFrom` 不能等于 `key`；旧键**不能**同时还留在清单里（那等于说「它既被改掉
   又仍然必需」，提交即拒）。改名生效之后 **`renamedFrom` 留着就行** —— 它是幂等的（新键已有值就不再搬），
   而摘掉它本身是一次清单变更，会平白再进一次人工审。
-- **平台填完值会自动换容器；envFile 改内容不会。** 换版触发器的判据是 descriptor 的**配置指纹**
-  （镜像 / 端口 / env），平台管理员在控制台填进 `env` 就会自动排一条重部署任务。唯一的例外是
-  **改 envFile 的内容**（文件在主机上，门户看不见那次改动）—— 那种情况面板那一行会显示「待重建」，
-  由平台管理员点「重新部署」。
+- **重部署看配置指纹，不只看 image。** 新执行链把实际消费的 envFile 字节、平台注入与落点纳入指纹，
+  控制器协调最新目标；Compose 使用其实际消费的全局 env 文件。旧部署可能仍需管理员显式重部署。
+  显式 redeploy 用于强制重建；同 tag 覆盖镜像仍不是可追踪的发版方式。实际运行事实与网关回执要分别核对。
 - **`deployRequirements` / `requiredServices` 也是治理档，而且是【闸】。** 前者说「我的后端要跑在
   什么样的机器上」（地域 / 规格档位下限 / 要不要 GPU / 必须同时属于哪些**命名**网络），后者说
   「我运行需要哪些外部服务」（`(kind, name)` 二元组）。批准那一刻门户按目标环境**当时**的资源池与
@@ -380,16 +448,16 @@ manifest 里带**值**的 `deployDescriptor.env` 提交即拒（防生产密钥
 2. 你第一次 `publish --manifest deploy/portal/app.manifest.json --dist dist/ --image <ref>` ⇒
    **必然进审核队列**（首次提交携带全部治理字段，无论内容）。
 3. 平台批准 ⇒ listing 建成上架 + 服务账号建出（client secret 明文一次性回显给审批人，
-   平台经外部渠道交给你）+ 产物与镜像同一次生效。
+   平台经外部渠道交给你）；清单/产物应用、后端和网关分阶段完成，不承诺同一时刻切换。
 4. 之后的日常发版与老 App 完全相同 —— 首次与后续是同一条代码路径，没有第二套流程。
 
 ## 等审批（pending 之后会发生什么）
 
 - `publish` 返回 pending 时**退出码 0 并立即返回**（提交成功不是失败），打印提案 id 与待审字段清单。
   **提案落成的那一刻，平台管理员就收到了站内 + 邮件通知**，不必另行催办。
-- **`--wait` 只等容器换版，不等人工审批。** 审批是分钟到小时级的人的动作，把 runner 挂在上面
+- **`--wait` 等获批后的本次后端与网关，不等人工审批。** 审批是分钟到小时级的人的动作，把 runner 挂在上面
   既烧机器又什么都没保证。真要把「审批通过且生效」纳入 CI 门禁，用 **`--wait-review [秒]`**
-  （默认 1800s）：它轮询到 `applied` / `rejected` / `withdrawn`，批准且换了镜像 ⇒ 继续等容器换版；
+  （默认 1800s）：它轮询到 `applied` / `rejected` / `withdrawn`，批准 ⇒ 继续等本次后端与网关，纯前端同样等网关；
   **被拒绝 ⇒ 打印平台填的原因并非零退出**（CI 该红就红）；超时 ⇒「仍在等审批」+ 非零退出。
   ⚠️ 从旧版升上来：以前写 `--wait` 指望它等审批的流水线，现在会在提案待审时**直接绿**。
 - 同一 App 同时只允许一条待审提案，且待审期间**任何新提交都被拒**（纯 dist/version 的
@@ -434,5 +502,6 @@ App 声明过的某个 `requiredEnv` 键在部署环境里还没有值，这次
 | 令牌语义、端点原始形状、字段白名单、返回体、`curl` 兜底、CI 范式 | [references/publish-api.md](references/publish-api.md) |
 | 症状 → 原因速查（发布报错 / 线上白屏 / 发了没换版） | [references/troubleshooting.md](references/troubleshooting.md) |
 
-报告结果时如实说清：发了哪个 key、哪个版本、digest 是多少、有没有在浏览器里实际打开过。
+报告结果时如实说清：发了哪个 key、哪个版本、proposalId、digest、原始包持久留存位置、
+有没有在浏览器里实际打开过；涉及同步时另报主平台归档是否已验证。
 「命令返回 ✓」只证明产物落库了，不证明页面能用——第 5 步没做就说没做。

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

@@ -36,7 +36,9 @@ tar czf dist.tgz -C dist .     # ✅ 根下就是 index.html、assets/…
 tar czf dist.tgz dist          # ❌ 全套在 dist/ 一层下面，拒收
 ```
 
-`release-cli` 传目录时已经用第一种形状打好了，只有自己 `curl` 时才需要手打。
+`release-cli` 传目录时会用第一种形状生成临时包，并在命令结束后删除。
+发布流程应按 [前端归档与同步验收](frontend-archive.md) 留存原始 tgz，再用 `--dist <包路径>`
+上传这份文件；重新打包目录不保证 SHA-256 相同，不能替代实际上传包的留存。
 
 其它约束：**≤64MB**（超了先查 source map 与未压缩素材）；空文件会被当成「构建没产出」拒掉，
 而不是当成「只发版本号」——这是有意的，否则一条坏流水线会报成功。
@@ -48,8 +50,11 @@ tar czf dist.tgz dist          # ❌ 全套在 dist/ 一层下面，拒收
 
 反过来，如果前端要直连**自己的域名 / 对象存储 / 第三方**，那是浏览器直发的请求，受 per-App CSP 管。
 XHR/fetch 那一类可以由 App manifest 的 `embedCsp.connectSrc` 放行；字体、样式表、图片走的是
-`font-src` / `style-src` / `img-src`，不在这个字段的能力范围内。**manifest 不在自助面里**——
-要放行得找平台管理员，改完下次反代 reload 生效。
+`font-src` / `style-src` / `img-src`，不在这个字段的能力范围内。
+**manifest 支持自助提交**：用 `publish --manifest` 申报 connectSrc，变化进入治理审核，
+批准后由平台同步反代；申报不等于已经生效，仍须验证实际响应头。
+需要 script/style/font 等扩展时向平台提出具体能力需求，不把它们塞进 connectSrc。
+公开入口与交付验收见 [public-delivery.md](public-delivery.md)。
 
 所以最省事的做法是**把资源打进产物、不外链**（字体尤其：CDN 字体是这里最常见的外链，
 而它恰好是 `connectSrc` 放行不了的那一类）。预检脚本会把产物里的外链列出来提醒。