@xgent-ai/skills 0.3.0 → 0.5.0

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

@@ -23,6 +23,7 @@ import { spawnSync } from "node:child_process";
 // 本地配置文件的读取只有一份实现（同目录 registry-config.mjs，npm-token.mjs 也用它）：
 // 抄成两份的下场是换个字段名只改了一处，另一个脚本悄悄退回默认值。
 import { loadConfig, parseArgs, pick, warnIfProxyIgnored } from "./registry-config.mjs";
+import { normalizeEmbedCsp } from "../references/embed-csp.mjs";
 
 const MAX_BYTES = 64 * 1024 * 1024; // 门户侧上限，超了直接 VALIDATION_FAILED
 const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/; // 与门户逐字一致
@@ -113,8 +114,8 @@ if (html) {
   if (external.length) {
     warn(
       `index.html 直连了外部地址：${external.slice(0, 3).join(" ")}${external.length > 3 ? " …" : ""}\n` +
-        `      → 生产受 per-App CSP 管，自助面改不了它。XHR/fetch 那类可由 manifest 的 embedCsp.connectSrc 放行；` +
-        `字体/样式/图片走的是 font-src / style-src / img-src，能不能放行要问平台管理员。最稳的做法是把资源打进产物、不外链。`,
+        `      → 生产受 per-App CSP 管。XHR/fetch 可通过 publish --manifest 申报 embedCsp.connectSrc，治理审核批准后再验实际响应头；` +
+        `script/style/font/img/media 需各自来源声明；扩展指令要求目标门户已启用严格 CSP 与 v2 网关，预检无法确认启用状态。`,
     );
   }
 }
@@ -228,6 +229,16 @@ if (!manifestPath) {
     err(`${manifestPath} 不是合法 JSON：${e?.message ?? e}`);
   }
   if (mf && typeof mf === "object") {
+    if (Object.hasOwn(mf, "embedCsp")) {
+      try {
+        normalizeEmbedCsp(mf.embedCsp);
+        ok("manifest.embedCsp 通过生产严格语法检查（不代表已获批或已加载）");
+      } catch (e) {
+        err(`manifest.embedCsp 不符合严格声明语法：${e.message}`);
+      }
+      warn("能力门未核验：strict 默认关闭；扩展 CSP 需平台确认已发布兼容版本并受控启用 strict 与 v2 网关。whoami 成功不证明此能力已启用。");
+      warn("embedCsp 省略沿用；null 清空；完整对象替换原声明，未写指令会撤回。来源增删均需治理审核。");
+    }
     const isObj = (v) => v !== null && typeof v === "object";
     const shown = (v) => JSON.stringify(v)?.slice(0, 60) ?? String(v);
 

package/skills/xgent-init/SKILL.md

@@ -1,96 +1,37 @@
 ---
 name: xgent-init
-description: 在一个 XGENT.ai Portal 出仓 App 自己的仓库里生成配套的 CLAUDE.md / PRODUCT.md / DESIGN.md（并镜像出 AGENTS.md）—— 读 app.manifest.json 与代码事实、一次性把缺的问清楚、按模板填出可直接用的三份文档，不留任何待填占位，已存在的文件不覆盖。凡任务是「初始化/接入一个新的出仓 App 仓库」「给这个 App 仓补上 CLAUDE.md / AGENTS.md / PRODUCT.md / DESIGN.md」「补一份 impeccable 能读的设计文档」，或用户刚拿到一个空的/只有代码没有规范的 App 仓时使用；门户 monorepo 内的 App、非 XGENT 项目不用本 skill。Use in an external XGENT portal app's own repo to scaffold its CLAUDE.md / PRODUCT.md / DESIGN.md (AGENTS.md is written as a mirror of CLAUDE.md) from the app manifest and repo facts — one round of questions, no leftover placeholders, never overwrites existing files.
+metadata:
+  internal: true
+description: 在 XGENT.ai Portal 出仓 App 自己的仓库里补齐 AGENTS.md / PRODUCT.md / DESIGN.md，保留 Portal 产品边界和设计规范，支持不同 coding agent。用户要求初始化出仓 App 规范、补齐产品或设计上下文时使用；读清单与代码事实，一轮问清缺的信息，已有文件不覆盖。install 本身只直接创建 AGENTS.md。
 ---
 
-# xgent-init · 出仓 App 仓库的三份文档 + AGENTS.md 镜像
+# xgent-init · 出仓 App 的 Agent、产品与设计上下文
 
-**用在 App 自己的 repo 里**（门户代码不在你手上，也不需要在）。产出：
+用在 App 自己的 repo 里。产出：
 
-| 文件 | 谁读它 | `service` 型（无前端） |
+| 文件 | 内容 | `service` 型（无前端） |
 | --- | --- | --- |
-| `CLAUDE.md` | 每次开工的 agent（Claude Code） | 生成，删掉前端五节 |
-| `AGENTS.md` | 读 `AGENTS.md` 的 agent（Codex / Cursor / pi） | 生成，`CLAUDE.md` 的镜像 |
-| `PRODUCT.md` | `impeccable` skill 每条子命令开工前 | 生成 |
-| `DESIGN.md` | `impeccable` skill、任何 UI 工作 | **不生成** |
+| `AGENTS.md` | 通用编码准则、onebox 联调、前端浏览器验收 | 生成，前端约定按适用条件执行 |
+| `PRODUCT.md` | 产品上下文与 Portal 已提供的能力边界 | 生成 |
+| `DESIGN.md` | Portal 色彩、字体、组件、主题与 iframe 设计规范 | 不新生成，已有文件保留 |
 
-`AGENTS.md` 不是独立文档：正文与 `CLAUDE.md` 逐字相同，只有第 1 行标题不同。改任一份都要同步另一份，`check-docs.mjs` 会核对。
+`AGENTS.md` 是独立的通用规范，直接使用 [references/external-app-AGENTS.template.md](references/external-app-AGENTS.template.md)，没有需要填写的 App 身份或启动命令占位，不生成或镜像 `CLAUDE.md`。
 
-模板在 `references/`，槽位规则在 [references/fill-guide.md](references/fill-guide.md)，结构检查在 `scripts/check-docs.mjs`。
-**平台契约不在本 skill 里**：口径以目标仓已装的 `portal-external-app` / `portal-micro-app` / `xgent-app-release` / `xgent-image-push` / `portal-dev-setup` / `portal-app-exchange` 为准，模板正文已经引用它们，不要在这里或生成的文件里复述一遍。
+`PRODUCT.md` 与 `DESIGN.md` 分别使用 [references/external-app-PRODUCT.template.md](references/external-app-PRODUCT.template.md) 和 [references/external-app-DESIGN.template.md](references/external-app-DESIGN.template.md)。填槽位前读 [references/fill-guide.md](references/fill-guide.md)，保留模板里的 Portal 产品边界与设计规范，不替换成通用设计建议。
 
-## 红线
+`install` 保留 hooks / impeccable 安装，可选步骤直接创建仓根 `AGENTS.md`，不安装本 skill，也不生成产品和设计文档。需要补齐这些文档时显式安装并使用本 skill；非交互 install 用 `--xgent-init` 创建 AGENTS.md，`--force` 也不覆盖已有文件。
 
-1. **不编造。** 用户、指标、竞品、启动命令、端口 —— 从 manifest 或仓库里读不出来的，只能问，不能猜。
-2. **不覆盖。** 已存在的文件一律跳过。只有用户明确要求更新时才动，且只改指定小节。
-3. **不留占位。** 生成完的文件里不能有 `[方括号]` 槽位、`<!-- 填写指引 -->`、`<APP_KEY>` 这类令牌，也不能有「请根据实际情况补充」这种话。
-4. **不引门户仓路径。** 目标仓访问不到 `apps/…` `packages/…` `docs/…`，要指路就指 skill 名。
-5. **只问一轮。** 把所有缺的合成一次问完，别来回打断。
-6. **脚本不绿不算完成。**
+## 约束
 
-## 流程
-
-### 1. 前置判定
-
-目标仓有 `app.manifest.json`（根目录，或 `deploy/portal/` `portal-app/` `deploy/` 下），或用户明确说这是一个出仓 App → 继续。
-在门户 monorepo 里 → 停下，指向 `portal-micro-app`；这份 skill 只服务代码不在门户仓的 App。
-
-### 2. 存在性检查
-
-逐份看 `CLAUDE.md` / `AGENTS.md` / `PRODUCT.md` / `DESIGN.md`。
-
-- 该有的都有（`micro` 四份 / `service` 三份）→ **报告「已齐，未写任何文件」并停止**。
-- 部分存在 → 只补缺的那几份，已存在的原样不动。
-- `CLAUDE.md` 与 `AGENTS.md` 只有一份、或两份正文不一致 → 以用户认可的那份为准补齐／对齐另一份；动手前先把要写的内容贴出来确认（红线 2：不覆盖已存在的文件）。
-- 用户明确要求更新某份已存在的文件 → 只改他指名的小节：先把改动后的小节全文贴出来，确认了再写，不整份重写。**改的是 `CLAUDE.md` 或 `AGENTS.md` 时，同一处改动要同步到另一份。**
-
-### 3. 事实采集
-
-按这个顺序，**不许跳级**：
-
-1. **`app.manifest.json`** —— `listingKey`、`name`、`type`、`color`、`tagline`、`desc`、`navItems`、`helpEntry`、`scopes`、`aclManifest`。
-   `name` 两种形状都接受：对象取 `zh-CN`，字符串直接用。
-2. **仓库信号** —— `package.json` 的 scripts 与依赖、`compose*.y*ml`、`Dockerfile`、README、目录结构与路由 / 页面 / 组件命名。
-3. **仍然缺的** —— 进第 4 步问。
-
-边读边填一张「槽位 → 候选值 → 来源」表（槽位清单见 fill-guide.md §1–§2）。`type` 决定 DESIGN.md 生不生成、CLAUDE.md 怎么裁剪。
-
-### 4. 一次批量追问
-
-把仍为空且推不出来的槽位合成**一轮**问题，通常 3–6 个：分条编号、每条给一个默认建议，让用户可以整体回「都按建议」。
-用户跳过的槽位按 fill-guide.md §5 的「删法」处理 —— **删掉那段，不要留空位，也不要编一个**。
+- 不编造用户、指标、竞品、身份色或项目事实。仓库读不到的必要信息合成一轮追问；可选信息缺失就删对应段落，不留占位。
+- 已有文件一律跳过。用户明确要求更新时，只修改指定内容。
+- 平台步骤以 `portal-external-app` / `portal-micro-app` / `portal-dev-setup` / `portal-app-exchange` / `xgent-app-release` / `xgent-image-push` 为准，不引用目标仓访问不到的门户源码路径。
 
-### 5. 渲染
-
-以 `references/` 里的模板为骨架，逐槽位填：
-
-- 替换 `<APP_KEY>` / `<APP_NAME>` / `<PREFIX>`（PREFIX = key 大写、`-` 换 `_`，不用问）与 `type: [micro|service]`。
-- 删掉全部 `<!-- 填写指引 -->` 注释，以及 `## Design Context` 里那条讲链接路径的注释。
-- 按 fill-guide.md §5 裁剪可选小节；保留的小节要把标题里的括号条件去掉。
-- `service` 型：删 CLAUDE.md 的「前端 UI 开发」及其后四个前端小节，并把 `## Design Context` 收敛成只指向 PRODUCT.md（不再提 DESIGN.md、impeccable、浏览器验证）。
-- DESIGN.md frontmatter 的 `name` / `description` 用双引号，值里的 `"` 与 `\` 要转义；`app-identity` 用 manifest 的 `color`，hover / dark 按 fill-guide.md §3 推导并在 frontmatter 上方留一行 YAML 注释说明是推导值。
-- **不要动** `Page<T>`、`{colors.x}` 引用、PRODUCT 的七个标题、DESIGN 的六个标题。
-
-### 6. 写入
-
-只写本次缺的文件。`CLAUDE.md` 与 `AGENTS.md` 成对写：同一份正文，只把第 1 行的 `# CLAUDE.md` 换成 `# AGENTS.md`。
-
-### 7. 校验
-
-```bash
-node <本 skill 目录>/scripts/check-docs.mjs <目标仓根>
-```
-
-有 `✗` 就改了重跑，直到退出 0。`!` 是提醒，自己判断要不要处理。
-环境里没有 Node → 照着 fill-guide.md §0 与 §7 逐条人工过一遍，并在报告里写明「未用脚本校验」。
-
-### 8. 报告
-
-一张表列出每个槽位的值与来源（manifest / 仓库信号 / 用户回答 / 模型建议），外加：
-
-- 生成了哪几份文件、跳过了哪几份；
-- 删掉了哪些可选段落（让用户知道少了什么，而不是以为漏了）；
-- `app-identity-hover` / `-dark` 的推导值，一句「可按需调整」；
-- 一句提示：这三份文件的结构是给 `impeccable` 读的，装了 impeccable 的话建议让它读一次确认。
+## 流程
 
-标为「模型建议」的行是给用户纠正用的 —— 用户改口后走第 2 步的小节级更新，不要重跑整个流程。
+1. **判定目标与检查文件。** 确定出仓 App 仓根，读取 `app.manifest.json`（根目录或 `deploy/portal/`、`portal-app/`、`deploy/` 下）；用户明确说明是出仓 App 而缺清单时，追问必要事实。门户 monorepo 内的 App 使用 `portal-micro-app`。检查 AGENTS.md / PRODUCT.md / DESIGN.md，只补缺的；都齐了就报告并停止。
+2. **采集产品与设计事实。** 从 manifest 的 name、type、color、tagline、desc、navItems、scopes、aclManifest，以及 README、页面、路由与组件中收集槽位候选和来源。name 为对象时取 zh-CN，为字符串时直接使用。type 决定是否生成 DESIGN.md。
+3. **一轮追问。** 把仍缺的必要槽位一次问完。用户跳过的可选项按 fill-guide 删除；未确定的必需身份色或产品事实不得猜填。
+4. **渲染。** AGENTS.md 原样复制通用模板。PRODUCT / DESIGN 按指南填槽位并删除填写指引；保留 PRODUCT 的七个二级标题、DESIGN 的六个二级标题与 YAML frontmatter。身份色使用 manifest 的 color，hover / dark 推导值注明来源。保留 `Page<T>` 与 `{colors.app-identity}` 等类型和 token 引用。service 型不新生成 DESIGN.md，PRODUCT 中的设计文档指引改为仅在有前端时适用。
+5. **写入并校验。** 只创建缺的文件，不触碰已有文档；运行 `node <本 skill 目录>/scripts/check-docs.mjs <目标仓根>`。修复本次生成文件的错误后重跑；已有文件的问题仅报告，不自行覆盖。没有 Node 时按指南人工检查并说明未用脚本校验。
+6. **报告。** 列出创建与跳过的文件、槽位值和来源、删除的可选段落，以及身份色推导值。说明尚未完成的校验或缺失信息。

package/skills/xgent-init/references/external-app-AGENTS.template.md

@@ -0,0 +1,149 @@
+# AGENTS.md
+
+行为准则，用来减少常见的 LLM 编码错误。与项目自身的规范合并使用。
+
+**取舍**：这些准则偏向审慎而非速度。琐碎任务自行判断。
+
+## 1. Think Before Coding
+
+**不要假设。不要藏起困惑。把取舍摆出来。**
+
+动手之前：
+- 明确说出你的假设。不确定就问。
+- 有多种解释时全部列出来——不要默默选一个。
+- 有更简单的做法就说出来。该反驳时反驳。
+- 有不清楚的地方就停下。指出困惑在哪。问。
+
+## 2. Simplicity First
+
+**用最少的代码解决问题。不做预留。**
+
+- 不做没被要求的功能。
+- 不为一次性代码造抽象。
+- 不加没被要求的「灵活性」「可配置性」。
+- 不为不可能发生的场景写错误处理。
+- 写了 200 行而它可以是 50 行，就重写。
+
+自问：「资深工程师会不会觉得这写复杂了？」会，就简化。
+
+## 3. Surgical Changes
+
+**只碰必须碰的。只清理自己造成的混乱。**
+
+改既有代码时：
+- 不「顺手改进」相邻代码、注释、格式。
+- 不重构没坏的东西。
+- 匹配既有风格，哪怕你会用别的写法。
+- 发现无关的死代码就说出来——不要删。
+
+自己的改动造成孤儿时：
+- 删掉**因你的改动**而不再被使用的 import / 变量 / 函数。
+- 不删既有的死代码，除非被要求。
+
+检验标准：每一行改动都能直接追溯到用户的诉求。
+
+## 4. Goal-Driven Execution
+
+**定义成功标准。循环到可验证为止。**
+
+把任务转成可验证的目标：
+- 「加校验」→「为非法输入写测试，然后让它们通过」
+- 「修 bug」→「写一个能复现它的测试，然后让它通过」
+- 「重构 X」→「保证重构前后测试都过」
+
+多步任务先说一句计划：
+```
+1. [步骤] → 验证：[检查点]
+2. [步骤] → 验证：[检查点]
+```
+
+## 5. Evidence & Quotation
+
+**凡引用必见原文。没读到的不写。**
+
+- 引用任何文件的措辞、编号、数值、状态、命令或日期前，先亲眼读到那段原文；不凭上下文推断补写，不把「大概如此」写成事实。
+- 工具回显被截断（长文件只给首尾）时，中段是**未知**：要引用就先按行范围或搜索结果回读定位，再引。
+- 正式产物（CR、计划、运维手册、commit message、给用户的事实陈述）里每一处「据 X 说 Y」，X（文件与段落）与 Y（内容）都要能当场指出。
+- 发现引用与原文不符：全仓搜出同一错误的所有副本一并修正，并向负责人说明，不留两处互相矛盾的版本。
+
+---
+
+## Project Conventions
+
+本文件适用于支持项目指令的 coding agent。开工先读本仓 README、包管理与工具链配置、相关开发计划；已有 PRODUCT.md / DESIGN.md 时一并读取。命令、端口、服务名、数据库名和 App 身份以本仓配置为准，不套用其他项目的值。
+
+### 本地开发
+
+- 用本仓已有的启动、检查、测试与构建入口，遵循现有包管理器、锁文件和工具链配置；有统一启动入口时优先使用它。
+- **缺服务、缺容器就停下来问，不要擅自装。** 未获授权时不下载镜像、不另起基础设施容器；先确认已有环境和依赖，再说明缺什么、请用户协助。
+- 共享数据库上的测试只使用明确的测试库。会 TRUNCATE / reset 的测试先核对目标库；共享状态的用例按项目约定串行执行，不清理其他项目或用户的数据。
+- `@xgent/*` 依赖从平台私有 registry 安装，配置以本仓 registry 与 CI 为准。401/404 先查凭证有效性与版本是否已发布；不通过复制源码或 file/link 依赖绕过。
+- 未经用户明确要求，不升级依赖 Major。
+
+### Portal App 接入
+
+本节与下方 onebox、Portal 前端及发布约定只适用于 XGENT.ai Portal App。清单事实源是本仓的 `app.manifest.json`；`listingKey`、App 名称和 `type` 从清单读取，不在本文件维护另一份副本。
+
+- `listingKey` 同时决定令牌 audience、安装态 appKey、服务路由和 scope 命名空间，改 key 等于换 App，不作为普通重命名处理。
+- 修改清单要同步更新 `version`。安装期字段是租户快照，改清单不等于已安装租户已经更新；验证时同时检查新安装与已有安装的行为。
+- 身份来自门户真实自省，解开响应信封后再读 claims；后端校验 audience、tenant、scope、角色和 ACL，自省失败必须拒绝放行。查询按 claims 的租户收口，不信前端自报的身份或租户。
+- 接入、清单与 API 契约查 `portal-external-app`；SDK、iframe、导航和版头查 `portal-micro-app`；跨应用授权查 `portal-app-exchange`。这些 skill 是平台口径的事实源；缺少相关 skill 时说明缺失，不猜平台步骤或引用目标仓访问不到的门户源码路径。
+
+### 本地联调：一盒（onebox / one-box）
+
+**本地起前端不等于门户联调通过。** iframe 握手、TDT、consent 和服务反代要接真实 onebox。初始化、注册、启动、体检和排错先读 `portal-dev-setup`，按该 skill 的脚本与当前配置执行，不 clone 门户、不改门户代码、不自行重建门户镜像。
+
+- **一台机器复用一盒**：先检查已有栈，其他 App 接到同一套联调底座；已有 onebox 时不再初始化第二套。镜像仓库、凭证、端口和目录从现有配置读取，缺凭证请用户找开发团队，不猜值。
+- **一盒仅供开发**：mock OAuth、开发服务账号和明文开发密钥不用于生产，不提交凭证到 git。
+- **先核对镜像版本与架构**：文档和运行行为不符时先查当前镜像；门户 onebox 镜像与自己的 App 镜像可能属于不同 registry 项目，不混用。App 镜像架构与运行平台必须匹配。
+- **核对 App 数据库与迁移**：onebox 不会自动创建每个出仓 App 的库。按本仓配置核对所需库；创建或迁移前确认目标。onebox 没有部署控制器，换成带新迁移的 App 镜像后，须按本仓迁移入口显式执行，健康检查绿不代表 schema 已更新。
+- **注册先于反代启动**：注册后先确认演示租户市场里出现 App 卡片，再检查安装、授权、宿主入口和服务路由。404/502 先跑 onebox doctor 与 skill 排查表，核对注册、反代与后端状态。
+- **dev 注册不等于已装租户同步**：导航、helpEntry 等安装期快照变更后，要通过租户管理员的市场更新入口同步，再验收宿主上的显示与行为。
+- **把首次同意屏算进走查**：「授权并打开」是正常步骤。onebox 的部署任务可能停在 `deploying`，因为没有部署控制器；是否可用以实际宿主链路为准。
+- 有本仓 onebox 冒烟入口时运行它，随后从宿主进入验证实际功能。
+
+### 前端 UI 开发与验收（有前端时）
+
+涉及页面、组件、布局、交互或视觉的改动，走完设计与浏览器验收两步：
+
+- **设计阶段用 impeccable**：先读已有产品与设计上下文，覆盖视觉层级、信息架构、间距对齐、配色、动效、可访问性以及空状态和错误状态。当前环境没有该 skill 时说明缺失并提示安装，不声称已经使用。
+- **验收使用当前 Agent 可用的真实浏览器通道**：Chrome extension、`kimi-webbridge` 或 Playwright 均可，按实际可用能力选择，不绑定某一种 Agent。
+- **Portal App 必须从宿主进入**：从已有宿主入口打开 App，走通主路径与关键边界；首次接入时还要覆盖市场卡片、安装与授权。确认浏览器显示的是最新产物；standalone 页面或直接打开 dev server 只能作为补充。
+- 检查本次改动涉及的导航、面包屑、关键操作与保存结果、空 / 错状态、权限边界；涉及响应式、主题或语言时检查相应状态。查看 console 与失败请求，保留实际步骤、结果及必要截图作为验收证据。
+- **类型检查、lint、单测和 build 不能替代浏览器验收**；只看 diff 不算完成。环境跑不起来时先按现有配置排查；仍受阻则明确写「未在浏览器中验证」、说明原因与需要的协助，不声称 UI 已验收通过。
+
+### Portal 前端约定（micro App）
+
+- 版头的应用图标、应用名与 tagline 归门户；App 内只显示运行期上下文，不重复绘制应用身份。脱离门户的 standalone 壳按需保留。
+- 页面层级由视图驱动的 effect 调用 `sdk.setBreadcrumbs` 全量上报，首页传空数组，label 用当前语言解析。内部路由调用 `sdk.routeSync`，同时订阅 `sdk.onRoute` 处理宿主切页。
+- 自己的后端通过 `sdk.callService` 调用，App key 来自清单。令牌交给 `sdk.getToken()` 管理，不自行存入 localStorage，不随意裁剪 scopes。
+- `sdk.acl.can(pid)` 用于按钮显示，后端仍须校验权限；不能用管理员走查代替普通成员的权限验收。
+- 跨源沙箱 iframe 不使用 `window.alert` / `confirm` / `prompt`，改用 DOM 模态框。
+- 下拉框复用项目 Select 原语；使用原生 `<select>` 时关闭原生箭头（`appearance-none`）并自绘 chevron，验证文字、箭头与主题的实际显示。
+- App 图标要契合用途，并确认门户注册表支持该名称；不依赖静默回退来掩盖配置错误。
+
+### API: HTTP status code 只反映传输/路由层，不反映业务状态
+
+- 404 = endpoint 不存在（路由层）；「数据不存在」用 200 + 业务字段（如 `data: null`）。
+- 业务成功统一 200，含新建/更新/删除/覆写，不用 201/204。
+- 业务失败（校验不过 / 状态非法 / 资源冲突）也走 200 + 响应体错误结构。4xx/5xx 只留给参数不正确、未登录、未授权、真传输/服务层故障。
+
+### 性能：热路径上不许 N+1，读多写少的事实必须缓存
+
+「表小 / 量不大 / 上限只有 1 000」都不是不优化的理由——tsc、lint、verify 对 N+1 全绿，只有压测和生产 p95 看得出来。请求路径与 worker 热路径一律适用，算法上能提高的就要提高，不能偷懒：
+
+- **循环里逐条 `await` 查询 = N+1，禁止**。同一批 id 一条 SQL `inArray` 取回，再在内存里映射；Redis 同理用 `mget`。反例（已修）：typed 通知入口逐个 `isActiveMember` 校验 1 000 个 userIds = 1 000 次串行往返；Router 每收件人每 push 渠道各查一次端点 = 200 人 400 条查询。
+- **一批写入用多行 INSERT + `RETURNING`**，按业务键（不是数组下标）把返回行映射回输入；`onConflictDoNothing` 只返回真插入的行，冲突那部分要再查一次。超过 1 000 行分块（PG 单语句 65 535 个参数）。范本：`modules/notifications/router.ts` 的 `writeRecipientBatch`。
+- **读多写少的配置/字典必须有进程内短 TTL 缓存**。管理员改完要即时生效的（事件定义、策略、模板、lane 开关、渠道连接）加显式 `invalidateXxxCache()` 在写侧调用；纯展示快照（App 名/图标/颜色）30 s TTL 就是契约，不要求写侧失效——写点散在十几处且 worker 是别的进程，失效调用本来就到不了。同一次请求 / 同一批处理里同一事实只查一次（先整批取到手再进循环）。
+- **不许缓存的**：发送/扣费/授权前的「当下资格」重查（成员是否 active、App 是否仍安装、端点归属）——它们存在的意义就是新鲜；一条带索引的点查即可。
+- **热路径上的聚合（`count(*)` / `min()`）不许每次现算**：`/health` 与背压这类每秒会被打的入口共用一份短 TTL 缓存（`modules/notifications/ops.ts` 的 `laneStatsCached()`）。
+- **事务里不做外部调用，持连接只覆盖写入**；渲染、解密、供应商调用都在事务外。
+- **改了热路径要给前后数字**：`apps/api` 有 `notification:loadtest` 这类参数化压测，改完跑一遍把 recipients/s 或 p95 写进提交说明；没有压测的路径至少 `EXPLAIN` 一次。
+
+### 完成标准与发布
+
+- 执行与改动相关的本仓检查、测试和构建入口，报告实际执行结果与未验证项。
+- Portal 后端改动验证无 token 的 401、缺 scope 的 403、租户隔离和经宿主服务路由访问的健康检查；权限改动覆盖普通成员，不只用管理员账号。
+- 有前端改动时完成上述真实浏览器验收，报告入口、主路径、关键边界和结果；阻塞项明确列出。
+- 发布时使用 `xgent-app-release`，镜像交付使用 `xgent-image-push`。发布前验证 release-cli 身份；换镜像带 `--wait`，以新版本实际运行作为成功依据。
+- 发布清单不携带密钥值，镜像 tag 不可变；迁移打进镜像、持锁、失败非零退出，并兼容仍在运行的旧版本。onebox 手动迁移与生产控制器迁移分别验证。

package/skills/xgent-init/references/fill-guide.md

@@ -1,9 +1,6 @@
-# 槽位填写指南
+# 产品与设计槽位填写指南
 
-三份模板在 `references/` 下：`external-app-CLAUDE.template.md` · `external-app-PRODUCT.template.md` · `external-app-DESIGN.template.md`。
-它们 95% 的文字是平台口径，**逐字照抄**；只有下面列出的槽位需要你填。行号是模板当前行号，改模板后以内容定位为准。
-
-`AGENTS.md` 没有模板：它是渲染完的 `CLAUDE.md` 的镜像，只把第 1 行标题换成 `# AGENTS.md`，正文逐字相同。
+AGENTS.md 使用通用模板原样创建，不填项目槽位，也不与 CLAUDE.md 镜像。以下指南用于 `external-app-PRODUCT.template.md` 和 `external-app-DESIGN.template.md`；只填产品与设计槽位，保留 Portal 规范。
 
 ## 0. 三条硬约束（改坏了 impeccable 就解析不出来）
 
@@ -11,22 +8,17 @@
 - **DESIGN.md**：YAML frontmatter 必须从**文件第 1 行**开始（前面多一个空行就整块解析不出来），正文**恰好六段**，名字与顺序照抄 —— `1. Overview` / `2. Colors` / `3. Typography` / `4. Elevation` / `5. Components` / `6. Do's and Don'ts`。不要加 Layout / Motion / Responsive 这类第七段，把内容折进六段里。
 - **平台口径的事实源是目标仓里已装的 skill**，不是这三份文件：`portal-external-app`（接入契约 · `app.manifest.json` · `/svc` 与健康检查）· `portal-micro-app`（SDK 握手 / 版头 / consent / iframe 坑）· `xgent-app-release`（发布提案 · 产物打包 · 排错）· `xgent-image-push`（镜像构建与推送）· `portal-dev-setup`（一盒本地联调）· `portal-app-exchange`（跨应用调用）。**门户仓的文档目标仓访问不到，别在生成的文件里引它的路径。**
 
-## 1. 令牌替换（全文）
-
-| 令牌 | 值 | 来源 |
-| --- | --- | --- |
-| `<APP_KEY>` | listingKey，如 `omni-parser` | manifest `listingKey` → 追问。必须过 `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$` |
-| `<APP_NAME>` | App 中文名 | manifest `name`（对象则取 `zh-CN`，字符串直接用）→ 追问 |
-| `<PREFIX>` | key 大写、`-` 换 `_`，如 `OMNI_PARSER` | 由 `<APP_KEY>` 派生，**不问** |
-| `type: [micro\|service]` | `type: micro` 或 `type: service` | manifest `type` → 追问 |
+## 1. 项目事实
 
-`<APP_KEY>` 在 CLAUDE 模板里出现十余处（含 `xgent-<APP_KEY>`、`<APP_KEY>_SERVER_PORT`、`/svc/<APP_KEY>`），逐个替换，别漏。
+- App 中文名从 manifest `name` 读取：对象取 `zh-CN`，字符串直接使用。
+- manifest `type` 决定是否新生成 DESIGN.md：micro 生成，service 不生成。
+- 身份色取 manifest `color`，缺失时追问；不要使用模板占位色。
+- PRODUCT / DESIGN 的其他事实从 README、路由、页面、组件与用户回答采集，记录来源。AGENTS 不再包含需要替换的 key、PREFIX 或 type 槽位。
 
 ## 2. 段落级槽位
 
 | # | 位置 | 要写什么 | 来源优先级 | 追问问法 | 约束 |
 | --- | --- | --- | --- | --- | --- |
-| S4 | CLAUDE `### 本地开发` | 起本仓的命令、端口、依赖的基础设施容器、测试与 verify 入口、最容易踩的启动坑 | `package.json` scripts / `compose*.y*ml` / `Dockerfile` / README → 追问 | 「一把起齐本仓的命令是什么？依赖哪些容器？测试怎么跑？」 | 写「一把起齐」的那条命令；坑要具体，不写「注意配置环境变量」 |
 | S5 | PRODUCT `## Users` 第 1 条 | 普通成员在做什么工作、一屏之内的首要任务、使用频次 | manifest `tagline` / `desc` / `navItems` + 路由/页面命名 → 追问 | 「普通成员进来主要做什么？多久来一次？」 | 一句话，具体动词；不写「提升效率」 |
 | S6 | PRODUCT `## Users` 第 2 条 | 只有租户管理员能做的结构性操作 | `aclManifest` 的 PID、admin 路由 → 追问 | 「哪些操作只有租户管理员能做？」 | 列具体动作（建/删业务对象、改租户级设置） |
 | S7 | PRODUCT `## Product Purpose` 首段 | 解决什么问题、为什么值得单独存在、什么算成功 | manifest `desc` + README → 追问 | 「这个 App 解决什么问题？什么算成功？」 | 一段话；具体名词动词，**禁用**「赋能 / 一站式 / 全流程」 |
@@ -35,7 +27,7 @@
 | S10 | PRODUCT `## Anti-references` 末段 | 具体的反面参照（某竞品、某旧版本）及**具体哪一点**不要 | 追问 | 「有没有明确不想像的产品或旧版本？」 | 用户说没有 → **整段删掉**，保留上面继承的六条 |
 | S11 | PRODUCT `## Design Principles` 第 3、4 条 | 两条领域设计原则 | 由 S5–S8 推导 | 可不问 | 是战略判断（「先给答案再给表格」），不是视觉规则（「用 8px 圆角」——那属于 DESIGN.md）。推不出就删到只剩平台那两条 |
 | S12 | PRODUCT `## Accessibility & Inclusion` 末条 | 本 App 特有的可访问性约束 | 由 UI 形态推断（长表格 / 拖拽 / 图表） | 可不问 | 无特有约束 → **删掉该行** |
-| S13 | DESIGN frontmatter `name` / `description`，与 `# Design System: …` 标题 | App 中文名；一句话说清这块工作区是什么、给谁用 | S2 + `tagline` / S7 | — | 三处名字一致；frontmatter 是 YAML，值里的 `"` 与 `\` 必须转义 |
+| S13 | DESIGN frontmatter `name` / `description`，与 `# Design System: …` 标题 | App 中文名；一句话说清这块工作区是什么、给谁用 | manifest `name` + `tagline` / S7 | — | 三处名字一致；frontmatter 是 YAML，值里的 `"` 与 `\` 必须转义 |
 | S14 | DESIGN frontmatter `colors.app-identity` / `-hover` / `-dark` | 三个色值 | `app-identity` = manifest `color`（**硬约束**，见 §3）；hover / dark 推导 | 无 manifest：「身份色是多少（#RRGGBB）？」 | 见 §3 |
 | S15 | DESIGN `## 1. Overview` 的 Creative North Star | 一句话北极星 | 由 S7 提炼 | 可不问 | 一句话，带画面感（例：「像一张随时可核对的账」） |
 | S16 | DESIGN `## 1. Overview` 第一段 | 这块工作区的性格：密集数据面还是引导式流程、用户一屏之内在找什么 | 由 S5 与 UI 形态推断 | 可不问 | 其后两段（「你画的是内容区」「主题不是你的选择」）**原样保留** |
@@ -60,19 +52,15 @@ DESIGN `## 2. Colors` 的 A / B 表格是**给用户的选择题**，不是背
 
 | 位置 | 留的条件 | 删法 |
 | --- | --- | --- |
-| CLAUDE `### 前端 UI 开发` 与 `### 前端：版头归门户` 及其后三节（`下拉框` / `字典表` / `App 图标`） | `type: micro` | `service` 型：五节整删。保留时去掉两个标题里的 `micro` / `service` 条件说明 |
-| CLAUDE `### 字典表统一带 sort + name_i18n` | 本 App 有租户级可维护的枚举 / 分类表 | 没有就整节删；保留时去掉标题里的括号条件 |
-| CLAUDE `## Design Context` 整节 | `type: micro` | `service` 型：删掉 DESIGN.md 那行，并把开头那句改写成不提 impeccable、不提前端 UI 的说法（例：「本仓有一份产品上下文文档：」），只留 PRODUCT.md 那行 |
 | PRODUCT `## Users` 第 4 条业务角色 | 本 App 有自己的业务角色（老师/学生、审核人/提交人…） | 有就补一条，并写明它是「门户角色 + ACL PID 的组合」还是「你自己表里的一列」——后者要说明如何与租户隔离共存 |
 | PRODUCT `## Anti-references` 末段 · `## Design Principles` 3–4 条 · `## Accessibility` 末条 · DESIGN `### [Signature Component]` | 见 §2 的 S10 / S11 / S12 / S17 | 无内容就整段删，**不要留空槽位** |
 
-## 6. 六处填写指引注释与两处元注释
+## 6. 填写指引与身份色说明
 
-模板里 `<!-- 填写指引：… -->` 共六处（PRODUCT 三处、DESIGN 两处、CLAUDE `## Design Context` 一处），**填完即删**。CLAUDE `## Design Context` 里那条讲链接路径的注释也删 —— 三份文件同在仓根，链接就是模板里写的样子。
+PRODUCT / DESIGN 中的 `<!-- 填写指引：… -->` 注释填完即删。DESIGN 中讲模板色值是占位值的说明，改为实际身份色及其用途；主按钮 A / B 选择写清理由。AGENTS 没有填写指引，不做项目槽位替换。
 
 ## 7. 不要动的东西（防过度替换）
 
 - DESIGN `## 5. Components` 里的 `Page<T>` 是平台分页契约的类型名，不是槽位。
 - DESIGN frontmatter `components.*` 里的 `{colors.app-identity}` / `{rounded.md}` 等花括号引用是 token 引用语法，保持原样。
-- CLAUDE 里的 `[object Object]`（讲多语对象被拼成字面量的那处）、`[]`（`setBreadcrumbs` 首页推空数组）、`[步骤]` / `[检查点]`（Goal-Driven Execution 的示例）都是正文，不是槽位。
 - DESIGN frontmatter 的全部色值、字体、圆角、间距、组件尺寸是门户 token 的权威副本，**一个字不改也是对的**；除身份色三条外不要调。

package/skills/xgent-init/scripts/check-docs.mjs

@@ -13,7 +13,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
-const KEY_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/; // 与门户逐字一致
 const CJK_RE = /[\u3000-\u303F\u4E00-\u9FFF\uFF00-\uFFEF]/; // 中日韩标点与汉字
 
 const errs = [];
@@ -46,14 +45,13 @@ const h2 = (src) =>
     .filter((l) => l.startsWith("## "))
     .map((l) => l.slice(3).trim());
 
-/* ── 0. 三份文件（AGENTS.md 是 CLAUDE.md 的镜像，见 §5） ──────────── */
+/* ── 0. AGENTS.md / PRODUCT.md / DESIGN.md ──────────── */
 
-const claude = read("CLAUDE.md");
 const product = read("PRODUCT.md");
 const design = read("DESIGN.md");
 const agents = read("AGENTS.md");
 
-if (!claude) err("CLAUDE.md 不存在");
+if (!agents) err("AGENTS.md 不存在");
 if (!product) err("PRODUCT.md 不存在");
 
 let manifest = null;
@@ -74,7 +72,7 @@ for (const p of MANIFEST_GUESSES) {
   }
   break;
 }
-if (!manifest) warn(`没找到 app.manifest.json（试过 ${MANIFEST_GUESSES.join(" ")}）—— key / type / 身份色无法交叉核对`);
+if (!manifest) warn(`没找到 app.manifest.json（试过 ${MANIFEST_GUESSES.join(" ")}）—— type / 身份色无法交叉核对`);
 
 /* ── 1. 残留占位（三份文件通查） ─────────────────────────────────
    R-5：生成完就能直接用，不留任何「还要手工编辑」的痕迹。 */
@@ -91,10 +89,10 @@ const RESIDUE = [
   ["本 App 有租户级可维护的枚举/分类表时", "小节标题里的模板条件没去掉"],
 ];
 
-/** CLAUDE.md 正文本来就有的两个方括号（Goal-Driven Execution 的示例）。 */
+/** AGENTS.md 正文本来就有的两个方括号（Goal-Driven Execution 的示例）。 */
 const BRACKET_OK = new Set(["步骤", "检查点"]);
 
-for (const [name, src] of [["CLAUDE.md", claude], ["PRODUCT.md", product], ["DESIGN.md", design]]) {
+for (const [name, src] of [["AGENTS.md", agents], ["PRODUCT.md", product], ["DESIGN.md", design]]) {
   if (!src) continue;
   for (const [token, why] of RESIDUE) {
     if (src.includes(token)) err(`${name} 残留 ${JSON.stringify(token)}：${why}`);
@@ -105,7 +103,7 @@ for (const [name, src] of [["CLAUDE.md", claude], ["PRODUCT.md", product], ["DES
     if (next === "(" || next === "[") continue;
     const inner = m[1].trim();
     if (!CJK_RE.test(inner)) continue;
-    if (name === "CLAUDE.md" && BRACKET_OK.has(inner)) continue;
+    if (name === "AGENTS.md" && BRACKET_OK.has(inner)) continue;
     err(`${name} 残留占位 ${JSON.stringify(m[0].slice(0, 40))}：方括号槽位没填`);
   }
   // C-6：门户仓的文档目标仓访问不到，别在生成的文件里引它的路径。
@@ -151,73 +149,19 @@ if (product) {
   }
 }
 
-/* ── 3. CLAUDE.md：key / type / PREFIX / 按形态裁剪 ─────────────── */
+/* ── 3. AGENTS.md：独立通用规范，形态从 manifest 读取 ─────────── */
 
-const MICRO_SECTIONS = ["### 前端 UI 开发：", "### 前端：版头归门户", "### 下拉框：", "### App 图标："];
-const UI_WORKFLOW_MARKERS = [
-  "npx impeccable install",
-  "mcp__claude-in-chrome__*",
-  "kimi-webbridge",
-  "playwright",
-  "未在浏览器中验证",
-];
-const DICT_SECTION = "### 字典表统一带"; // micro 型也可按需删，只在 service 型断言不存在
-
-let type = null;
-let key = null;
-
-if (claude) {
-  const t = claude.match(/type:\s*(micro|service)\b/);
-  if (!t) err("CLAUDE.md 找不到 `type: micro` 或 `type: service`（Project Conventions 首句里的形态声明）");
-  else {
-    type = t[1];
-    ok(`CLAUDE.md type = ${type}`);
-  }
-
-  const line = claude.split("\n").find((l) => l.includes("本仓交付的是"));
-  const k = line?.match(/`([^`]+)`/);
-  if (!k) err("CLAUDE.md 找不到 Project Conventions 首句（`本仓交付的是 … App：\\`<key>\\`…`），无法核对 key");
-  else if (!KEY_RE.test(k[1])) err(`CLAUDE.md 里的 key \`${k[1]}\` 不合法，必须匹配 ${KEY_RE}`);
-  else {
-    key = k[1];
-    ok(`CLAUDE.md key = ${key}`);
-  }
-
-  if (key) {
-    const expect = key.toUpperCase().replace(/-/g, "_");
-    const sa = claude.match(/([A-Z0-9_]+)_SA_CLIENT_SECRET/);
-    if (!sa) err("CLAUDE.md 找不到 `<PREFIX>_SA_CLIENT_SECRET`（服务账号密钥那条）");
-    else if (sa[1] !== expect) err(`CLAUDE.md 的 ${sa[1]}_SA_CLIENT_SECRET 与 key \`${key}\` 不一致，应为 ${expect}_SA_CLIENT_SECRET（key 大写、连字符换下划线）`);
-    else ok(`CLAUDE.md PREFIX = ${expect}`);
-  }
-
-  if (type === "service") {
-    for (const s of [...MICRO_SECTIONS, DICT_SECTION]) {
-      if (claude.includes(s)) err(`CLAUDE.md 是 service 型（无前端），应删掉 \`${s}…\` 这一节`);
-    }
-    for (const s of ["DESIGN.md", "impeccable"]) {
-      if (claude.includes(s)) err(`CLAUDE.md 是 service 型，## Design Context 里不该再提 ${s}`);
-    }
-  } else if (type === "micro") {
-    for (const s of MICRO_SECTIONS) {
-      if (!claude.includes(s)) err(`CLAUDE.md 是 micro 型，缺 \`${s}…\` 这一节`);
-    }
-    for (const marker of UI_WORKFLOW_MARKERS) {
-      if (!claude.includes(marker)) err(`CLAUDE.md 是 micro 型，前端 UI 两步法缺少 \`${marker}\``);
-    }
-  }
-
-  if (key && manifest?.listingKey && manifest.listingKey !== key) {
-    err(`CLAUDE.md 的 key \`${key}\` 与 manifest.listingKey \`${manifest.listingKey}\` 不一致`);
-  }
-  if (type && manifest?.type && manifest.type !== type) {
-    err(`CLAUDE.md 的 type \`${type}\` 与 manifest.type \`${manifest.type}\` 不一致`);
-  }
+if (agents) {
+  const head = agents.split("\n")[0];
+  if (head !== "# AGENTS.md") err(`AGENTS.md 第 1 行应是 \`# AGENTS.md\`，实际：${JSON.stringify(head.slice(0, 40))}`);
+  else ok("AGENTS.md 标题正确");
 }
 
+const type = manifest?.type;
+
 /* ── 4. DESIGN.md：存在性随形态；frontmatter + 六段 ─────────────── */
 
-if (type === "service" && design) err("service 型（无前端）不需要 DESIGN.md，请删掉");
+if (type === "service" && design) warn("service 型（无前端）不新生成 DESIGN.md；已有文档保留");
 if (type === "micro" && !design) err("micro 型缺 DESIGN.md");
 
 const DESIGN_H2 = ["1. Overview", "2. Colors", "3. Typography", "4. Elevation", "5. Components", "6. Do's and Don'ts"];
@@ -279,22 +223,6 @@ if (design) {
   }
 }
 
-/* ── 5. AGENTS.md：CLAUDE.md 的镜像 ───────────────────────────────
-   读 AGENTS.md 的工具（Codex / Cursor / pi）也要看到同一套约定；两份不同步
-   就是同一个仓里摆着两处互相矛盾的规范。 */
-
-if (!agents) {
-  err("AGENTS.md 不存在 —— 它必须是 CLAUDE.md 的镜像（除第 1 行标题外逐字相同）");
-} else if (claude) {
-  const head = agents.split("\n")[0];
-  if (head !== "# AGENTS.md") {
-    err(`AGENTS.md 第 1 行应是 \`# AGENTS.md\`，实际：${JSON.stringify(head.slice(0, 40))}`);
-  }
-  const body = (src) => src.split("\n").slice(1).join("\n");
-  if (body(agents) === body(claude)) ok("AGENTS.md 与 CLAUDE.md 除首行外逐字一致");
-  else err("AGENTS.md 与 CLAUDE.md 正文不一致 —— 两份是同一套约定的镜像，只有第 1 行标题该不同；改一份就同步另一份");
-}
-
 /* ── 输出 ───────────────────────────────────────────────────────── */
 
 for (const m of oks) console.log(`  ✓ ${m}`);

package/vendor/impeccable/VERSION.json

@@ -1,28 +1,22 @@
 {
   "source": "https://github.com/pbakaus/impeccable",
   "license": "Apache-2.0",
-  "skillVersion": "4.3.1",
-  "engineVersion": "0.1.5",
+  "skillVersion": "4.5.0",
+  "engineVersion": "0.1.11",
   "bundle": {
-    "url": "https://github.com/pbakaus/impeccable/releases/download/skill-v4.3.1/universal.zip",
+    "url": "https://github.com/pbakaus/impeccable/releases/download/skill-v4.5.0/universal.zip",
     "keyId": "release-2026-09",
-    "sha256": "1deea4cdfb1608df6d9e08ef359629e7cc866a22ab7c2195a835627b887f190b",
-    "size": 15625571
+    "sha256": "a6877c158ec90c63560728553d2e737081afa8a79b86c507fa8d15a81fffd475",
+    "size": 16157124
   },
   "engines": {
     "darwin-arm64": {
       "asset": "impeccable-darwin-arm64",
-      "sha256": "0d48b6e16aa97664fdbe607d5da9ae320e389a1843e0ff1328f8c2530530320d",
-      "size": 12762240,
-      "url": "https://download.xgent.ai/vendor/impeccable/engine/v0.1.5/darwin-arm64/impeccable"
-    },
-    "darwin-x64": {
-      "asset": "impeccable-darwin-x64",
-      "sha256": "153971b0c00719dff9ebac13370cb7dbbbe12838b696fbaf3f7ab0b1b3726b52",
-      "size": 14400568,
-      "url": "https://download.xgent.ai/vendor/impeccable/engine/v0.1.5/darwin-x64/impeccable"
+      "sha256": "7427918d6e75507401a1b7b691eefe58a7c01a2fc63b712016ffc5a0ac1c05e6",
+      "size": 14845040,
+      "url": "https://download.xgent.ai/vendor/impeccable/engine/v0.1.11/darwin-arm64/impeccable"
     }
   },
-  "fetchedAt": "2026-09-22T15:38:00.906Z",
-  "publishedAt": "2026-09-22T15:40:54.468Z"
+  "fetchedAt": "2026-10-02T09:20:08.048Z",
+  "publishedAt": "2026-10-02T09:23:34.098Z"
 }