@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,317 @@
+---
+name: "[你的 App 中文名]"
+description: "[一句话：这块工作区是什么，给谁用。]"
+colors:
+  app-identity: "#2563EB"
+  app-identity-hover: "#1D4ED8"
+  app-identity-dark: "#5B8DEF"
+  brand-blue: "#0063D3"
+  brand-blue-hover: "#0054B3"
+  brand-blue-press: "#00408A"
+  brand-orange: "#FF6B02"
+  ink: "#0B1220"
+  ink-2: "#1A2233"
+  ink-3: "#2A3447"
+  paper: "#FAFAFC"
+  white: "#FFFFFF"
+  slate-50: "#F2F4F9"
+  slate-100: "#E7EBF2"
+  slate-200: "#D5DBE6"
+  slate-300: "#B6BECF"
+  slate-400: "#8E99B0"
+  slate-500: "#6E7A94"
+  slate-600: "#54607A"
+  slate-700: "#3E4A60"
+  success-500: "#1F9D55"
+  warning-500: "#D89400"
+  danger-500: "#D6293E"
+typography:
+  title:
+    fontFamily: "Space Grotesk, ui-sans-serif, system-ui, sans-serif"
+    fontSize: "20px"
+    fontWeight: 600
+    lineHeight: 1.3
+    letterSpacing: "-0.01em"
+  body:
+    fontFamily: "Space Grotesk, ui-sans-serif, system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 400
+    lineHeight: 1.5
+    letterSpacing: "0"
+  label:
+    fontFamily: "Space Grotesk, ui-sans-serif, system-ui, sans-serif"
+    fontSize: "13px"
+    fontWeight: 500
+    lineHeight: 1.3
+    letterSpacing: "0"
+  mono:
+    fontFamily: "JetBrains Mono, ui-monospace, SF Mono, Menlo, monospace"
+    fontSize: "13px"
+    fontWeight: 400
+    lineHeight: 1.5
+    letterSpacing: "0"
+rounded:
+  sm: "4px"
+  md: "8px"
+  lg: "12px"
+  xl: "16px"
+  pill: "999px"
+spacing:
+  xs: "4px"
+  sm: "8px"
+  md: "16px"
+  lg: "24px"
+  xl: "32px"
+  "2xl": "48px"
+components:
+  button-primary:
+    backgroundColor: "{colors.app-identity}"
+    textColor: "{colors.white}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 14px"
+  button-secondary:
+    backgroundColor: "{colors.white}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 14px"
+  button-ghost:
+    backgroundColor: "transparent"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 14px"
+  button-danger:
+    backgroundColor: "{colors.danger-500}"
+    textColor: "{colors.white}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 14px"
+  input:
+    backgroundColor: "{colors.white}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 12px"
+  select:
+    backgroundColor: "{colors.white}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 32px 0 12px"
+  badge:
+    backgroundColor: "{colors.slate-100}"
+    textColor: "{colors.slate-700}"
+    rounded: "{rounded.pill}"
+    padding: "3px 9px"
+  card:
+    backgroundColor: "{colors.white}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.lg}"
+    padding: "20px"
+  tab-active:
+    backgroundColor: "transparent"
+    textColor: "{colors.app-identity}"
+    rounded: "{rounded.md}"
+    height: "34px"
+    padding: "6px 10px"
+---
+
+# Design System: [你的 App 中文名]
+
+## 1. Overview
+
+**Creative North Star: "[一句话北极星，例如「像一张随时可核对的账」]"**
+
+<!-- 填写指引：2–3 段。第一段说这块工作区在做什么、密度取向；第二段说它与底座的关系（下面那段可直接留用）；
+     第三段说明确拒绝什么（可从 PRODUCT.md 的 Anti-references 里提炼一句）。 -->
+
+[第一段：这块工作区的性格。它是密集的数据面还是引导式的流程？用户一屏之内在找什么？]
+
+**你画的是内容区，不是一个站。** 版头（应用图标 + 应用名 + 面包屑 + 帮助 / 全屏 / 刷新）与一级侧栏归门户，你的界面从版头之下开始。所以本系统不定义 logo 区、不定义全局导航、不定义登录与设置入口——那些在壳里已经有了一份。你要做的是让内容区**看起来像同一栋楼里的一间房**：同一套中性色、同一套圆角与投影、同一套状态语言，只有身份色和领域语汇是你自己的。
+
+主题不是你的选择：宿主经 `sdk.onTheme` 推 `light` / `dark`，你把它落到自己根节点的 `data-theme` 上，两套都必须过 AA。**iframe 是独立文档**——宿主的 CSS 变量、字体、Tailwind 配置一律不会继承过来，token 与字体都要在你自己的 `index.css` / `index.html` 里再声明一份（本模板的 frontmatter 就是那份的权威值）。
+
+> 本文件只管**长什么样**。SDK 行为（主题 / 语言 / 面包屑 / 弹层 / 路由）以 `portal-micro-app` skill 为准；
+> 设计推进用 `impeccable` skill（它开工前会读本文件与 `PRODUCT.md`）。
+
+**关键特征：**
+- 冷调 slate 中性色，浅色底是 `paper` (#FAFAFC)，深色底是 `ink` (#0B1220)；两套都是一等公民。
+- 一个身份色（`app-identity`）承担 App 内的强调与激活；橙色（#FF6B02）是门户的信号色，**App 内不用**。
+- 几何无衬线 Space Grotesk 撑住整个界面；等宽 JetBrains Mono 只给机器值。
+- 控件 8px 圆角、发丝边框、hover / focus 是感觉得到而不是看得见（120ms ease-out）。
+
+## 2. Colors
+
+### Primary
+
+**你的身份色**（`app-identity`，模板里给的 #2563EB 是占位值，**必须换掉**）。它是这个 App 在门户里的名字之外的第二个识别物：门户会用它画应用市场 / 侧栏 / 通知里的 App Glyph（那枚圆角方块底色，由 manifest 的 `color` 字段给），你在 App 内用它画激活态、选中态、焦点环和图表的种子色。
+
+三条硬约束：
+1. **不要和已有 App 撞色**，也不要撞 XGENT 蓝 #0063D3（撞了就等于没有身份）。
+2. **manifest 的 `color` 与这里的 `app-identity` 必须是同一个值**——一个在壳里、一个在房里，色不一样就是同一个 App 说两种话。
+3. **深色主题下要单独给一个更亮的值**（`app-identity-dark`）：饱和蓝紫在 `ink` 上普遍掉到 AA 以下。
+
+**「主按钮归谁」是你要做的唯一一次取舍**，全 App 只选一次、一致到底（两种在门户里都有先例）：
+
+| 取舍 | 主按钮 / 焦点环 | 什么时候选它 |
+| --- | --- | --- |
+| **A. 继承门户蓝** | `brand-blue` #0063D3 | App 的交互与门户高度同构（表单、审批、配置类），你希望它读起来就是底座的一部分 |
+| **B. 用身份色** | `app-identity` | App 有强烈的领域感（内容创作、数据分析），你希望进来之后是「另一间房」 |
+
+选了 B，`brand-blue` 仍然保留在调色板里，只用于**指回门户**的东西（例如指向平台配置页的链接）。
+
+### Secondary
+
+本系统**没有**第二个强调色。门户的橙色 #FF6B02 是平台信号（未读 / 新增），App 内复用它会让「平台在说话」和「App 在说话」混在一起。需要第二层强调时，用身份色的 8–16% 淡色底，不要引入新色相。
+
+### Neutral
+
+- **Ink** (#0B1220)：浅色态的正文色；深色态的页面底色。整套投影都用它调（`rgba(11,18,32,…)`）。
+- **Slate 600 / 500 / 400** (#54607A / #6E7A94 / #8E99B0)：次级与三级文字、meta、图标缺省色。
+- **Slate 300 / 200** (#B6BECF / #D5DBE6)：控件强边框与发丝分隔线。
+- **Slate 100 / 50** (#E7EBF2 / #F2F4F9)：下沉面与第二层面板（搜索框、分段控件轨道、骨架屏）。
+- **Paper / White** (#FAFAFC / #FFFFFF)：浅色态的页面底与抬升面。
+- **Ink 2 / Ink 3** (#1A2233 / #2A3447)：深色态的抬升面与第二层面。
+
+### Status
+
+**Success** (#1F9D55) · **Warning** (#D89400) · **Danger** (#D6293E)，各配一个 50 淡色底（浅色态 #E7F6EE / #FBF3DD / #FCE6E9；深色态用同色 16% 透明）。Info 复用门户蓝。
+
+### Named Rules
+
+**The Tint, Not Fill Rule.** 选中与 hover 用主色的 8–16% 淡色叠在中性色上，**不用**实心。实心色只留给「你该点的那一个」和「你该读的那个状态」。
+
+**The Borrowed-Color Rule（反向版）.** 门户把中性留给你，好让你的身份色读得出来；作为交换，**App 内不使用门户的橙色**，也不要在内容区里重现门户的品牌元素。
+
+**The Status-Never-Alone Rule.** 状态色永远和图标或文字一起出现。色盲用户、灰度打印、以及 `forced-colors` 模式下，色相是第一个消失的东西。
+
+## 3. Typography
+
+**正文 / UI 字体：** Space Grotesk（回退 `ui-sans-serif, system-ui, -apple-system, sans-serif`）
+**等宽字体：** JetBrains Mono（回退 `ui-monospace, SF Mono, Menlo, Consolas, monospace`）
+
+**字体要你自己引。** iframe 不继承宿主的字体加载，在你的 `index.html` 里加：
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+```
+
+`/apps/<key>/` 的 CSP 已放行 `style-src … https://fonts.googleapis.com` 与 `font-src 'self' https://fonts.gstatic.com data: blob:`——**其它字体 CDN 不在放行名单里，会静默不加载**（症状：本地好看，线上变系统字）。要用别的来源就自托管进 `dist`（`'self'`）。
+
+### Hierarchy
+
+嵌进壳里的界面比门户自己的页面**小一档**：页面标题那一级已经由版头的应用名占掉了，你的最大标题是区块标题。
+
+- **Title / h1**（Space Grotesk, 20px, 600, 行高 1.3）：视图标题。整屏最大的字，不要再往上加。
+- **Section / h2**（18px → 16px, 600）：卡片与分组标题。
+- **Body**（14px, 400, 行高 1.5）：默认阅读尺寸。长文本裁到 65–75ch；密集表格可以更宽。
+- **Label**（13px, 500）：表单标签、按钮文字、标签页、chip。
+- **Meta / caption**（12px, 400, `slate-500`）：时间、计数、辅助说明。**不要再往下**——12px 已经是 CJK 的可读下限。
+- **Eyebrow**（12px, 600, 大写, tracking 0.08em）：只给分组分隔线与下拉分区标题，**不是**每个区块头上都要戴一顶。
+- **Mono**（JetBrains Mono, 13px）：ID、token、scope、cron、IP、金额与数量的对齐列、行内代码。
+
+### Named Rules
+
+**The Mono-Means-Machine Rule.** 等宽字表示「这是一个字面量机器值」。不要拿它做强调，不要用它排人话。
+
+**No-Display-Face-Inside-The-Shell.** 门户有一款展示字（Iceland），只给登录页那种 hero 时刻。嵌入式 App 里**没有** hero 时刻，一个都不要用。
+
+## 4. Elevation
+
+默认是平的。分隔靠发丝边框（`--border`）和第二层中性面，不靠投影；只有**离开平面**的东西才有阴影（弹层、模态、抽屉、分段控件被抬起的滑块）。浅色态阴影用 ink 调色，深色态用纯黑加大不透明度——深色下 4% 的黑等于没有。
+
+### Shadow Vocabulary
+
+- **Shadow 1** `0 1px 2px rgba(11,18,32,.04), 0 1px 1px rgba(11,18,32,.06)`：小元素的接触阴影（图标块、分段滑块、开关旋钮）。
+- **Shadow 2** `0 4px 12px rgba(11,18,32,.06), 0 2px 4px rgba(11,18,32,.04)`：确实需要浮起来的卡片。
+- **Shadow 3** `0 12px 28px rgba(11,18,32,.10), 0 4px 8px rgba(11,18,32,.06)`：Popover 与锚定下拉。
+- **Shadow 4** `0 24px 56px rgba(11,18,32,.18), 0 8px 16px rgba(11,18,32,.10)`：模态与抽屉。
+- **Focus ring** `0 0 0 2px var(--bg), 0 0 0 4px var(--ring)`：键盘焦点唯一处理；输入框另外叠一圈 3px 的主色 16% 辉光。
+
+深色态整体替换为 `rgba(0,0,0,.4 → .6)`。
+
+### Named Rules
+
+**The Flat-At-Rest Rule.** 静止的面是平的。阴影是「离开了平面」的回应，不是卡片的默认装饰。静止卡片上出现 Shadow 3 就是错的。
+
+**The Popover-Stays-Inside Rule（iframe 专属）.** 你的弹层**出不了 iframe 的边界**——超出的部分直接被裁掉，而在本地全屏调试时你看不出来。锚定弹层必须做边界翻转（flip / shift），长内容自己滚动；确实需要更高的可视区就调 `sdk.resize`，不要指望溢出到宿主页面上。
+
+## 5. Components
+
+每个可交互组件都要有 default / hover / focus / active / disabled，内容可能缺失的地方还要有 loading（骨架屏）与 empty / error（状态块）。手感是精确克制：8px 圆角、发丝边框、120ms ease-out。
+
+### Buttons
+- **形状**：8px 圆角，三档高度（sm 30 / md 36 / lg 40px），字重 600，单行。
+- **Primary**：实心（身份色或门户蓝，见 §2 的取舍），白字。一屏之内**只有一个**。
+- **Secondary**：白底 / 深色态 `ink-2` 底，正文色，`slate-300` 强边框。hover 转 `slate-50`。
+- **Ghost**：透明、无边框，给密集工具条里的低强调动作。
+- **Danger**：实心 #D6293E，只给破坏性动作，且破坏性动作必须二次确认（**用 App 内的 DOM 模态框**，见 §6）。
+- **Disabled**：40% 不透明 + `not-allowed`。**禁用必须能解释原因**（tooltip 或旁注），不然用户只能猜。
+- **Icon button**：36px 见方，8px 圆角，`slate-500` 图标；激活态用主色 8% 淡底 + 主色图标。
+
+### Inputs / Fields
+- **样式**：36px 高、白底、`slate-300` 边框、8px 圆角、13–14px 字，可带前导图标与 `*` 必填标记。
+- **Focus**：边框转主色 + 3px 主色 16% 辉光。
+- **Error**：边框与帮助文字转 danger，帮助行说清**怎么改**，不是只说「格式错误」。
+- **中文输入法**：输入框回车提交前必须挡掉输入法候选确认的那一次 Enter（`keyCode === 229`），否则用户在选词时就被提交了。用 `@xgent/portal-ui` 的 `./keyboard` / `./input`，不要自己写一份。
+
+### Select（硬规则，不是风格偏好）
+原生 `<select>` 直接套输入框的类，留下的是**浏览器原生箭头**——位置 / 大小 / 颜色全归浏览器，`pr-*` 推不动它（padding 只影响文字），也不跟主题走。这个错误反复出现，因为类型检查、lint、单测**全绿**，只有人眼看得出来。
+
+```
+appearance-none                       ← 唯一硬要求：关掉原生箭头
+pr-8                                  ← 给自绘箭头留位（按图标宽 + 右内缩算）
+<ChevronDown size={14} className="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-3" />
+```
+
+收进你自己的 `Select` 原语里，视图代码里**不写裸 `<select>`**。宽度写在哪取决于 `className` 转发给谁：转发给 `<select>`（内部已有 `w-full`）就得在外面套一层定宽 `div`；转发给外层 wrapper 就直接写在组件上。
+
+### Cards / Containers
+- 12px 圆角（模态 / 抽屉 16px），白底 / `ink-2` 底，1px `slate-200` 发丝边框，内边距 20–24px。
+- 静止不带阴影。**卡片里不套卡片**——需要第二层就用 `slate-50` 下沉面或一条分隔线。
+- 卡片是偷懒的答案：先问一句这些内容是不是本来就该是一张表或一个列表。
+
+### Tables / Lists
+- 服务端分页，复用平台的 `Page<T>` 契约；不要一次拉全量再前端分页。
+- 表头吸顶、数字右对齐且用等宽、行 hover 用主色 8% 淡底、选中行同色更深一档。
+- 列宽稳定：异步加载不要让列宽跳动（骨架屏用等宽占位）。
+
+### Feedback States
+- **Loading**：骨架屏（按内容形状），不是转圈圈铺满整块。
+- **Empty**：一句说明 + 一个动作。区分「还没有数据」和「筛选后没有命中」——后者要给「清除筛选」。
+- **Error**：说清发生了什么、用户能做什么。业务失败是 HTTP 200 + 响应体错误结构，**别把它当网络故障渲染**。
+
+### [Signature Component]
+
+<!-- 填写指引：如果本 App 有一个撑起它身份的自定义组件（一个编辑器、一块画布、一种卡片、一张时间线），
+     在这里写清它的结构、状态与由来。没有就整段删掉。 -->
+
+[名字 + 一段：它长什么样、有哪些状态、为什么是它而不是通用组件。]
+
+## 6. Do's and Don'ts
+
+### Do:
+- **Do** 把身份色用在激活 / 选中 / 焦点上，并让它与 manifest 的 `color` 逐字相同。
+- **Do** 用主色 8–16% 淡底表达选中与 hover，实心色只给「该点的那一个」。
+- **Do** 每个状态色都配图标或文字。
+- **Do** 两套主题都过 AA，并在**深色态下单独校一遍身份色**。
+- **Do** 用 `sdk.setBreadcrumbs()` 表达页面层级（首页推 `[]`，每次全量覆盖，label 用当前语言解析好）。
+- **Do** 用 `@xgent/portal-ui` 已有的组件（`UserPicker`、IME 安全输入）再造新轮子。
+- **Do** 机器值用等宽字，加载用骨架屏，空 / 错用状态块。
+- **Do** 每个动效都给 `prefers-reduced-motion` 替代；过渡落在 120–280ms ease-out。
+
+### Don't:
+- **Don't** 在 App 内自绘应用图标 / 应用名 / tagline / 侧栏 / 租户切换 / 用户菜单 / 主题切换 / 通知铃铛——版头和壳已经有一份。
+- **Don't** 自建「设置」页与它的侧栏入口（租户配置走平台应用配置页），也不自建审计页与通知中心。
+- **Don't** 用 `window.alert` / `confirm` / `prompt`——跨源沙箱 iframe 里**被静默忽略**，用户什么都不会看到，代码却以为用户确认了。一律用 App 内的 DOM 模态框。
+- **Don't** 给卡片 / 列表项 / 提示框加左侧色条（`border-left`）。
+- **Don't** 在 var() 颜色上用 Tailwind 的 `/alpha` 修饰符（`bg-primary/50`）——**静默失效**，用 `opacity-NN` 或预先算好的色值。
+- **Don't** 用门户的橙色，不用展示字体 Iceland，不用第三个字体家族。
+- **Don't** 让静止卡片带阴影，不要卡片套卡片。
+- **Don't** 写裸 `<select>`（见 §5），不要拿 `pr-*` 去推原生箭头。
+- **Don't** 先想模态框：能内联、能抽屉、能就地展开的，都不要打断用户。
+- **Don't** 只看 diff 就说 UI 改完了——类型检查和单测只证明代码对。改动要从宿主进入、在真浏览器里走通主路径与关键边界；环境起不来就**显式说明「未在浏览器中验证」**。

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

@@ -0,0 +1,87 @@
+# Product
+
+## Register
+
+product
+
+<!-- 填写指引：几乎所有出仓 App 都是 `product`（已认证的应用 UI，设计**服务**产品）。
+     只有当这个仓库交付的主界面是官网 / 落地页 / 长内容（设计**就是**产品）时才写 `brand`。
+     `service` 型（无前端）App 仍写 `product`——它的「界面」是平台控制台里的配置面与错误文案。
+     裸词一个，不要加句号、不要加解释。 -->
+
+## Users
+
+本 App 被嵌在 XGENT.ai Portal 的应用版头之下（`service` 型无前端，直接跳到第三条）。用户不是从零进来的：他们已经登录、已经选好租户、已经在门户的侧栏里点了本 App。
+
+- **租户普通成员**（TDT `claims.role === "user"`）。主要受众。[他们在做什么工作、一屏之内的首要任务是什么、他们一天来几次]。他们看到的功能面由角色基线 + ACL（`claims.permissions`）决定，**不是**由界面藏不藏按钮决定。
+- **租户管理员**（`claims.role === "admin"`）。做结构性动作：[列出本 App 里只有管理员能做的事，例如建/删业务对象、改本 App 的租户级设置]。他们需要密度、准确、以及对状态（成功 / 失败 / 待定）诚实的反馈。
+- **平台管理员 / 运维**。他们不进你的前端，只在**门户控制台**里看你的 listing、部署状态、用量与审计。你欠他们的是：可读的健康信封、可读的部署失败原因、以及同意屏上不是裸 scope 名的中文文案。
+
+<!-- 填写指引：本 App 若有自己的业务角色（老师/学生、审核人/提交人…），在这里补成第四条，
+     并写明它是「门户角色 + ACL PID 的组合」还是「你自己表里的一列」——后者要说明它如何与租户隔离共存。 -->
+
+上下文：已认证、多租户、桌面优先（数据密集面）但需响应式，主 locale 是 `zh-CN`（界面语言由宿主推送，见 `sdk.onLocale`）。**角色决定看见什么，不决定界面怎么工作。**
+
+## Product Purpose
+
+[一段话：本 App 解决什么问题、为什么它值得单独存在、什么算成功。用具体的名词和动词，别用「赋能 / 一站式 / 全流程」。]
+
+**边界（这一段不要删）**：本 App 是门户里的一块工作区，不是一个站。下列能力**已由门户提供**，本仓不重造、不自建入口：
+
+| 已归门户 | 你该怎么做 |
+| --- | --- |
+| 登录 / 2FA / 会话 / 租户切换 | 什么都不做。iframe 里拿到的就是已认证上下文 |
+| 应用图标 + 应用名 + tagline（版头最左那一级） | 不在 App 内再画一份；页面层级用 `sdk.setBreadcrumbs()` 上报 |
+| 成员管理 / 角色矩阵 / 权限授予 | 声明 `aclManifest` 的 PID，权限在门户里配 |
+| 本 App 的租户级配置页 | 走平台「应用配置」，不自建「设置」页与侧栏入口 |
+| 审计日志 | 写 `POST /api/v1/audit`，不自建审计页 |
+| 通知 / 消息 | 走平台消息服务，不自建通知中心 |
+| 文件存储 / 预览 | 走 Files App，不自建文件管理 |
+| 帮助页入口 | 清单里声明 `helpEntry`，版头会长出一枚帮助按钮，不占侧栏 |
+
+本 App 真正拥有的是：[列 3–5 条只有你能做的事]。
+
+## Brand Personality
+
+本 App 的个性表现在**身份色、领域语汇、信息结构**上，**不**表现在另起一套控件、圆角和排版——那些跟门户同族（见 `DESIGN.md`）。
+
+[三个词：例如「精准、克制、可信」。然后两句话说清语气：文案是陈述句还是引导句？错误信息说人话还是说错误码？空状态是给指令还是给解释？]
+
+底座已定的调性（继承，不覆盖）：precise, engineered, quietly confident——开发者平台那一族（Linear / Stripe / Vercel 的手感），冷调中性色、几何无衬线（Space Grotesk）、机器值用等宽（JetBrains Mono）。界面应该像可信的基础设施：安静、该密的地方密、不为装饰而装饰。
+
+## Anti-references
+
+继承门户的四条：
+
+- **过时的后台模板**（Bootstrap / AdminLTE / 默认 Ant Design Pro）：灰、通用、把每个功能都摆出来、没有观点。
+- **无生气的老企业软件**（SAP / Oracle / 旧政务门户）：沉重、表单密度高而没有层级。
+- **过度装饰的消费风**：到处渐变、吉祥物、什么都圆、游戏化。
+- **AI 味**：奶油色背景、渐变文字、每个段落上面一条 eyebrow、一模一样的卡片网格。
+
+再加两条**出仓 App 专属**（这两条是外部团队最常犯的）：
+
+- **「iframe 里的第二个门户」**：App 内自绘版头 / 侧栏 / 租户切换 / 用户菜单 / 主题切换按钮 / 通知铃铛。同屏说两次，而且租户改过 App 名之后两处会说得不一样。
+- **「移植过来的独立站」**：把一个原本独立的 SaaS 整个塞进 iframe，带着自己的登录页、自己的用户管理、自己的设置中心和自己的一整套设计语言。
+
+[如果有具体的反面参照（某个竞品、某个旧版本），点名写在这里，并说明**具体是哪一点**不要。]
+
+## Design Principles
+
+<!-- 填写指引：3–5 条。前两条是平台派生的，建议保留；其余换成从你的领域里长出来的原则。
+     原则是战略判断（「先给答案再给表格」），不是视觉规则（「用 8px 圆角」——那属于 DESIGN.md）。 -->
+
+1. **门户已经提供的，不要再造一份。** 边界表里的每一行都是平台的事。重造的代价不是多写代码，是两个事实源开始互相说谎。
+2. **角色决定看见什么，不决定怎么工作。** 管理员与普通成员共用同一套组件、间距和状态语言；差别只在内容多寡。
+3. [你的领域原则]
+4. [你的领域原则]
+
+## Accessibility & Inclusion
+
+双主题（light / dark，由宿主经 `sdk.onTheme` 推送，App 自己落到根节点的 `data-theme`）都要过 **WCAG 2.1 AA**：
+
+- 正文对比度 ≥ 4.5:1，大字 ≥ 3:1，**placeholder 也算正文**。
+- 每个可交互元素都能键盘到达并有可见焦点态。
+- 每个动效都有 `prefers-reduced-motion` 替代路径。
+- 主 locale 是 `zh-CN`，排版要处理好 CJK（行高、标点、断行）；界面语言跟随宿主，不在 App 内自建语言切换。
+- 状态色（成功 / 警告 / 危险）必须同时带图标或文字，不能只靠色相。
+- [本 App 特有的可访问性约束：例如长表格要有表头吸顶、拖拽操作要有键盘替代、图表要有数据表兜底。]

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

@@ -0,0 +1,78 @@
+# 槽位填写指南
+
+三份模板在 `references/` 下：`external-app-CLAUDE.template.md` · `external-app-PRODUCT.template.md` · `external-app-DESIGN.template.md`。
+它们 95% 的文字是平台口径，**逐字照抄**；只有下面列出的槽位需要你填。行号是模板当前行号，改模板后以内容定位为准。
+
+`AGENTS.md` 没有模板：它是渲染完的 `CLAUDE.md` 的镜像，只把第 1 行标题换成 `# AGENTS.md`，正文逐字相同。
+
+## 0. 三条硬约束（改坏了 impeccable 就解析不出来）
+
+- **PRODUCT.md**：七个二级标题，名字与顺序固定 —— `Register` / `Users` / `Product Purpose` / `Brand Personality` / `Anti-references` / `Design Principles` / `Accessibility & Inclusion`。别改名、别加段、别调序。`## Register` 的正文只能是裸词 `product` 或 `brand`，不加句号、不加解释。
+- **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` → 追问 |
+
+`<APP_KEY>` 在 CLAUDE 模板里出现十余处（含 `xgent-<APP_KEY>`、`<APP_KEY>_SERVER_PORT`、`/svc/<APP_KEY>`），逐个替换，别漏。
+
+## 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 解决什么问题？什么算成功？」 | 一段话；具体名词动词，**禁用**「赋能 / 一站式 / 全流程」 |
+| S8 | PRODUCT `## Product Purpose` 边界表下方 | 本 App 真正拥有的 3–5 条 | 从 S5–S7 与 `scopes` 命名空间归纳 → 追问 | 「只有本 App 能做的事有哪些？」 | 3–5 条；不能与边界表里「已归门户」的行重叠 |
+| S9 | PRODUCT `## Brand Personality` | 三个词 + 两句语气说明 | 由 S7 与领域推断 | 可不问 | 标注为**建议**；语气两句要回答：陈述句还是引导句、错误信息说人话还是错误码、空状态给指令还是给解释 |
+| 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，值里的 `"` 与 `\` 必须转义 |
+| 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 形态推断 | 可不问 | 其后两段（「你画的是内容区」「主题不是你的选择」）**原样保留** |
+| S17 | DESIGN `### [Signature Component]` | 撑起产品身份的自定义组件：结构、状态、由来 | 组件目录里识别 | 「有没有一个撑起产品身份的自定义组件（编辑器 / 画布 / 时间线）？」 | 没有 → **连标题整段删掉**；有 → 标题换成组件真名 |
+
+## 3. 身份色
+
+- `app-identity` **必须**与 manifest 的 `color` 逐字相同 —— 一个在壳里（应用市场 / 侧栏的 App Glyph），一个在房里，色不一样就是同一个 App 说两种话。无 manifest 时追问，别用模板的占位值 `#2563EB`。
+- `app-identity-hover` 由 `app-identity` 压暗一档（约 −12% 亮度），`app-identity-dark` 提亮一档（约 +18% 亮度，深色底上饱和蓝紫普遍掉到 AA 以下）。两个都是**推导值**：在 frontmatter 上方留一行 YAML 注释注明「由 app-identity 推导，可按需调整」。
+- 不要撞 XGENT 蓝 `#0063D3`，不要撞已有 App 的色。
+
+## 4. 必须做的一次取舍：主按钮归谁
+
+DESIGN `## 2. Colors` 的 A / B 表格是**给用户的选择题**，不是背景介绍。渲染时按判断挑一个，在表格下方写明选了哪个、为什么，并把没选的那行留在表里（它解释了另一种先例）：
+
+- **A. 继承门户蓝 `brand-blue` #0063D3** —— App 的交互与门户高度同构（表单、审批、配置类）。
+- **B. 用身份色 `app-identity`** —— App 有强烈领域感（内容创作、数据分析），进来之后是「另一间房」。
+
+选 B 时 `brand-blue` 仍保留在调色板里，只用于**指回门户**的东西。
+
+## 5. 可选小节的删留
+
+| 位置 | 留的条件 | 删法 |
+| --- | --- | --- |
+| 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. 六处填写指引注释与两处元注释
+
+模板里 `<!-- 填写指引：… -->` 共六处（PRODUCT 三处、DESIGN 两处、CLAUDE `## Design Context` 一处），**填完即删**。CLAUDE `## Design Context` 里那条讲链接路径的注释也删 —— 三份文件同在仓根，链接就是模板里写的样子。
+
+## 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 的权威副本，**一个字不改也是对的**；除身份色三条外不要调。