draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/references/frontend.md

@@ -0,0 +1,788 @@
+---
+name: draftgo-frontend-rules
+description: DraftGo frontend page development rules.
+version: 2.0.0
+---
+
+# DraftGo 前端开发规范
+
+> 根 `SKILL.md` 是完整核心规则源；本文件只展开前端实现方法。若表述冲突，以根 `SKILL.md` 为准，不额外叠加固定验收动作。
+
+> 本文件只规定前端**操作性规则**，已剥离的内容见：
+> 架构原理 → `{{SKILL_DIR}}/references/architecture.md`
+> App API / Token / 路由 / 运行时 → `{{SKILL_DIR}}/references/runtime.md` · `{{SKILL_DIR}}/references/app-api.md`
+> 动态 DB / filters → `{{SKILL_DIR}}/references/data.md`
+> 开发禁区 → `{{SKILL_DIR}}/references/security.md`
+
+---
+
+## 页面开发强制规则
+
+### 真实闭环（强制）
+
+- 页面必须有可访问 route，从真实入口可达（导航/首页/后台菜单/相关按钮至少一处）
+- 按钮、表单、搜索、筛选、分页、提交、删除等交互默认真实有效
+- 涉及异步数据、提交、搜索、筛选或接口调用时，必须覆盖相关加载态/空态/错误态/成功态，不能只堆静态卡片
+- 展示可维护内容时主动判断是否需要后台管理页 + 同一份真实数据
+- 业务模块尽量不要复制大量同构工作台；列表、详情、编辑、管理页优先按任务差异设计结构、密度和操作区
+- 无法实现真实闭环时停止开发，向用户说明阻塞点；确认为平台限制、可复用经验或连续排查失败时再写入 `.draftgo/lessons/`
+
+### 操作型页面布局（强制）
+
+后台管理、表格、列表等操作型页面用**工作台布局**，不用文档流堆叠：
+强烈建议直接使用antd的组件
+```css
+.workbench-page { min-height:100vh; display:flex; flex-direction:column; overflow:hidden; }
+.workbench-toolbar { flex-shrink:0; }
+.workbench-body { flex:1; min-height:0; display:flex; flex-direction:column; }
+.workbench-data { flex:1; min-height:0; overflow:auto; }
+.workbench-footer { flex-shrink:0; }
+```
+
+- 分页/操作栏/保存栏固定在工作区底部，不随数据量上浮
+- 滚动发生在数据区，不是整页
+
+### 表格数据区与分页钉底
+
+当页面主体是表格、日志列表、后台数据管理页时，必须先做固定高度的 flex column 容器，再放表格。不要让分页跟随表格内容高度往下跑，也不要让整页滚动。
+
+推荐骨架：
+
+```css
+/* 整页表格页 */
+.table-page {
+  height: 100vh;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+/* 如果页面外已有顶部导航，用实际导航高度替换 56px */
+.table-page.with-top-nav {
+  height: calc(100vh - 56px);
+}
+
+.table-toolbar {
+  flex-shrink: 0;
+}
+
+.table-shell {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.table-data {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.table-pagination {
+  flex-shrink: 0;
+  margin-top: auto;
+}
+```
+
+antd Table 推荐结构：
+
+```javascript
+h('div', { className: 'table-page' },
+  toolbar && h('div', { className: 'table-toolbar' }, toolbar),
+  h('div', { className: 'table-shell' },
+    h('div', { className: 'table-data' },
+      h(antd.Table, {
+        rowKey: 'id',
+        columns,
+        dataSource: items,
+        loading,
+        pagination: false,
+        scroll: { x: 1100 },
+        onChange: handleTableChange,
+      })
+    ),
+    h('div', { className: 'table-pagination' },
+      h(antd.Pagination, {
+        current: page,
+        pageSize,
+        total,
+        showSizeChanger: true,
+        onChange: loadPage,
+      })
+    )
+  )
+)
+```
+
+如果表格列很多，横向滚动条必须固定在分页上方，而不是藏在长数据列表底部。做法是让 antd Table 自己生成 `.ant-table-body` 滚动区：外层 `.table-data` 只负责 flex 占位和 `overflow:hidden`，Table 设置 `pagination:false`、`scroll:{ x: 1100, y: '100%' }`，再用 CSS 让 `.ant-table-body` 填满剩余高度。
+
+```css
+.table-data {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.table-data .ant-table-wrapper,
+.table-data .ant-spin-nested-loading,
+.table-data .ant-spin-container,
+.table-data .ant-table,
+.table-data .ant-table-container {
+  flex: 1;
+  min-height: 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.table-data .ant-table-header { flex-shrink: 0; }
+.table-data .ant-table-body {
+  flex: 1 1 0;
+  min-height: 0;
+  max-height: none !important;
+  overflow: auto !important;
+}
+```
+
+```javascript
+h(antd.Table, {
+  rowKey: 'id',
+  columns,
+  dataSource: items,
+  loading,
+  pagination: false,
+  scroll: { x: 1100, y: '100%' },
+})
+```
+
+硬性验收：
+
+- 最外层容器高度明确：整页用 `height:100vh`；有顶部导航时用 `calc(100vh - 顶部导航高度)`；嵌在已固定高度的工作区时用 `height:100%; min-height:0`。
+- 布局必须是 `display:flex; flex-direction:column`。
+- 顶部筛选区 / toolbar 若存在，使用自适应高度并 `flex-shrink:0`。
+- 中间表格区域必须是 `flex:1; min-height:0; overflow:auto`。
+- 分页区域必须在容器最底部，使用 `flex-shrink:0; margin-top:auto`。
+- 禁止分页随数据内容高度下移；数据很多时只滚动 `.table-data`。
+- 表格列多时使用 antd `scroll.x` 或内部横滚，禁止撑出整页横向滚动条；需要随时可横向滑动时，横向滚动条必须固定在分页上方。
+- 不要同时让 `body`、页面容器、表格容器三层都滚动；最多保留表格数据区滚动。
+
+### 文本与图标换行控制（强制）
+
+按钮、标签、导航项、状态徽章等**小范围整体区域**内的文本和图标，**禁止自动换行**：
+
+```css
+/* ✅ 不换行，整体在同行显示 */
+.btn-content { white-space: nowrap; }
+
+/* ❌ 允许换行 → 宽度不足时文本/图标散落，视觉参差不齐 */
+.btn-content { white-space: normal; } /* 默认即 normal，必须显式覆盖 */
+```
+
+**常见中招场景**：
+- 按钮内文字 + 图标（`提交` + `→` 换行变两行）
+- 操作行内的多个 icon+文字 组合（不同按钮高度不一）
+- 标签/徽章内文字换行导致错位
+- 表单字段名 + 输入框 并排时字段名换行
+
+**判断标准**：这块内容在视觉上是一个整体（属于同一个操作、同一个标签、同一个单元），就不应该因为容器宽度被拆开。整行拆行是可以的，但**同组内的子元素不能拆行**。
+
+---
+
+### 移动端与多端适配（按页面目标与影响范围）
+
+移动端适配是产品与受众判断，不是所有页面的固定验收门。公众页面、用户可能从手机访问的业务页面、已有响应式断点，或本次修改涉及布局/CSS/导航/弹窗时，应认真处理窄屏；明确的桌面工作台、仅改文案/数据逻辑、后端或脚本任务，不要机械增加移动端检查。需要窄屏布局时，可以先保证小屏可用，再在宽屏增强信息密度。
+
+---
+
+#### 1. 容器宽度：禁止固定像素，用流式布局
+
+内容容器宽度必须随可用空间伸缩，永远不要写死像素宽度：
+
+```css
+/* ✅ */
+.container { width: 100%; max-width: 960px; margin: 0 auto; padding: 0 16px; }
+
+/* ❌ 窄屏必然横向溢出 */
+.container { width: 1200px; }
+```
+
+Tailwind：`w-full max-w-4xl mx-auto px-4`
+
+---
+
+#### 2. 并排布局：默认纵向堆叠，宽屏才横排
+
+任何"左右并排"的布局，首先决定窄屏下如何堆叠，再决定多宽时切换为横排：
+
+```css
+/* 窄屏纵向，768px+ 横排 */
+.layout { display: flex; flex-direction: column; gap: 16px; }
+@media (min-width: 768px) {
+  .layout { flex-direction: row; }
+  .sidebar { width: 240px; flex-shrink: 0; }
+  .main { flex: 1; min-width: 0; } /* min-width:0 防长内容撑破父容器 */
+}
+```
+
+Tailwind：`flex flex-col md:flex-row gap-4`，主内容区加 `flex-1 min-w-0`。
+
+多列卡片 / 统计块，让列数随宽度自动伸缩：
+
+```css
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; }
+```
+
+Tailwind 固定列数降级写法：`grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4`
+
+---
+
+#### 3. 可点击区域：触控友好
+
+手指触摸区域不能太小，按钮、链接、导航项应结合页面密度提供足够内边距和间距，相邻元素避免误触：
+
+```css
+.btn { padding: 8px 16px; display: inline-flex; align-items: center; }
+.nav-item { display: flex; align-items: center; padding: 8px 12px; }
+```
+
+---
+
+#### 4. 文字：正文不缩，标题宽屏再放大
+
+正文 16px 在任何屏幕都合适，不需要响应式。大标题在手机上不要过大，宽屏再逐步放大：
+
+```css
+.title { font-size: 20px; }
+@media (min-width: 1024px) { .title { font-size: 28px; } }
+```
+
+Tailwind：`text-xl lg:text-3xl`
+
+---
+
+#### 5. 超宽内容（表格、代码）：容器内横滚，不让整页横滚
+
+表格列多时，不能让整个页面出现横向滚动条，必须在容器层限制：
+
+```html
+<div style="overflow-x: auto;">
+  <table style="min-width: 640px; width: 100%;">...</table>
+</div>
+```
+
+antd Table 加 `scroll={{ x: 'max-content' }}`，无需额外包裹。
+
+---
+
+#### 6. 间距：小屏收紧，大屏舒展
+
+```css
+.page { padding: 16px; }
+@media (min-width: 768px) { .page { padding: 24px 32px; } }
+```
+
+Tailwind：`p-4 md:p-6 lg:p-8`
+
+---
+
+#### 7. 弹窗与抽屉：宽度跟屏幕走
+
+```css
+.modal { width: min(90vw, 520px); }           /* 窄屏自动收缩 */
+.modal-body { max-height: 60vh; overflow-y: auto; } /* 内容多时内部滚动 */
+```
+
+antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"`。
+
+---
+
+#### 按需验收参考
+
+| 参考宽度 | 适用时的观察项 |
+|---|---|
+| **390px** | 面向手机用户时，观察横向溢出、核心操作和文字截断 |
+| **768px** | 涉及平板或断点切换时，观察重叠和挤压 |
+| **1440px** | 桌面工作台或宽屏页面，观察信息密度和空间利用 |
+
+不要为了收尾机械遍历全部宽度。需要浏览器证据时优先运行 `draftgo verify-ui <url> --mobile-check auto`：默认单个 `390x844` 视口，检查空白页、横向溢出、console/page error 和可选关键元素，仅失败时截图。只有必须依赖用户现有登录会话、浏览器扩展或真实桌面状态时才考虑 computer use。
+
+---
+
+### 导航与系统页边界（强制）
+
+- 顶部导航已有内置资源时，通常先读 `.draftgo/navigations/index.json` 和对应 HTML；需要新导航时优先复制/复刻一份再改造，而不是直接改坏内置导航。
+- 导航栏通常要同时考虑未登录 / 已登录 / 管理员三种状态，以及收起 / 展开状态；普通用户不显示管理后台入口，管理员额外显示管理后台入口。
+- 管理端侧边栏通常基于现有内置侧边栏修改，新增业务管理路由优先追加或局部调整；删除系统内置页面入口前先确认影响。
+- 业务页面内可以做局部二级导航或侧边栏，但必须考虑外部导航已存在且可单独配置，避免重复渲染全局导航。
+- 系统内置页面通常不改；确需修改登录、设置、权限、用户、系统配置等页面时，先说明影响、验证方式和保留的管理员能力。
+- 页面风格不要照搬管理侧内置页面；业务前台按业务用户和品牌语境设计，管理侧按操作效率和信息密度设计。
+
+### 新增页面绑定（强制）
+
+- 公开页 → 顶部/侧边导航、首页入口、相关按钮之一
+- 后台页 → 后台导航、管理菜单或现有后台入口
+- 多页面功能：列表/详情/新建/编辑/管理必须互相走通
+- 用户明确要求"隐藏页/草稿页"才可不绑定，但必须在 changelog / Task 说明原因
+
+### `page_1_root.html` 首页特例（强制）
+
+- 仍是默认内置首页 → 通常按官网介绍、品牌门面和入口聚合重新实现，不沿用内置文案和结构；只有用户明确要“进入即使用”的首页，才把首页当实际工作台
+- 已被用户改过 → 只做要求范围内的修改，不强制重做
+- 判断依据：看 HTML 内容是否保留 DraftGo 默认文案/系统介绍/未定制品牌，不要只凭文件名判断
+
+---
+
+## 必须 / 禁止
+
+### 必须
+- 完整 HTML 文档结构（`<html><head><body>`）
+- 静态资源用本地路径（见下方资源清单）
+- 配色优先使用系统主题语义 token `var(--dg-*)`，并同时适配浅色 / 深色模式
+- 弹窗用 `App.confirm()` / `App.toast()`，禁止 `window.alert/confirm/prompt`
+- 弹窗/抽屉优先做成无外层滚动条，滚动控制在内容区
+- 页面初始渲染展示默认状态（骨架屏），不能因请求延迟空白
+
+### 禁止
+- 需要 CDN 时优先使用国内镜像引入；已有本地资源时优先使用 `/assets/` 本地路径
+- ❌ `window.alert/confirm/prompt`
+- ❌ `App()` 写法 → ✅ `const App = window.parent?.App`
+- ❌ `window.location.search` 读参数 → ✅ `window.__DG_ROUTE_CONTEXT__.query`
+- ❌ 页面内 `window.location.href=...` 跳转 → ✅ `window.parent.location.href=...`
+- ❌ TSX/React 版组件写进数据库 HTML（数据库页面不支持 React）
+- ❌ 硬编码颜色值 → ✅ `var(--dg-*)`
+- ❌ 在业务页面实现全局浮窗/客服/统计脚本 → ✅ `frontend_global_*` 固定槽位
+- ❌ 在业务页面重写 Toast 组件 → ✅ 使用 `App.toast()`，视觉、位置、大小、透明度、时长通过 `frontend_global_toast_*` 系统配置统一调整
+
+---
+
+## 本地静态资源清单
+
+| 路径 | 说明 |
+|---|---|
+| `/assets/tailwindcss.js` | Tailwind CSS 运行时 |
+| `/assets/antd/reset.css` | Ant Design 5.29.3 reset CSS（antd 必须） |
+| `/assets/react/react.min.js` | React 18 UMD → `window.React` |
+| `/assets/react-dom/react-dom.min.js` | ReactDOM 18 UMD → `window.ReactDOM` |
+| `/assets/dayjs/dayjs.min.js` | dayjs → antd DatePicker 依赖 |
+| `/assets/antd/antd.min.js` | Ant Design 5.29.3 UMD → `window.antd` |
+| `/assets/fontawesome/css/all.min.css` | FontAwesome 6 |
+| `/assets/icons/{name}.svg` | 内置精选 SVG 图标库（kebab-case 命名） |
+| `/assets/icons/manifest.json` | 图标库映射清单 |
+| `/assets/fonts/inter.css` | Inter 字体 |
+| `/assets/fonts/lexend.css` | Lexend 字体 |
+| `/assets/fonts/plus-jakarta-sans.css` | Plus Jakarta Sans |
+| `/assets/fonts/plus-jakarta-sans-jetbrains-mono.css` | Plus Jakarta Sans + JetBrains Mono |
+| `/assets/vendor/marked/marked.min.js` | Markdown 解析 |
+| `/assets/vendor/highlightjs/highlight.min.js` | 代码语法高亮（highlight.js） |
+| `/assets/vendor/prism/prism.min.js` | 轻量代码高亮（Prism.js） |
+| `/assets/vendor/dompurify/purify.min.js` | HTML 净化，渲染用户输入前必须过一遍 |
+| `/assets/vendor/html2canvas/html2canvas.min.js` | html2canvas 1.4.1，页面截图 / DOM 导出图片 |
+| `/assets/draftgo-chat.js` | DraftGo Chat SDK 完整版，注册 `<dg-chat>` 与 `DraftGoChat` |
+| `/assets/vendor/gsap/gsap.min.js` | GSAP 核心（先于其他 GSAP 插件加载） |
+| `/assets/vendor/gsap/ScrollTrigger.min.js` | GSAP ScrollTrigger |
+| `/assets/vendor/gsap/ScrollToPlugin.min.js` | GSAP ScrollTo |
+| `/assets/vendor/gsap/Draggable.min.js` | GSAP Draggable |
+| `/assets/vendor/gsap/Flip.min.js` | GSAP Flip |
+| `/assets/vendor/gsap/SplitText.min.js` | GSAP SplitText |
+| `/assets/vendor/gsap/MorphSVGPlugin.min.js` | GSAP MorphSVG |
+| `/assets/vendor/gsap/MotionPathPlugin.min.js` | GSAP MotionPath |
+| `/assets/vendor/gsap/DrawSVGPlugin.min.js` | GSAP DrawSVG |
+| `/assets/vendor/gsap/Observer.min.js` | GSAP Observer（统一手势/滚动监听） |
+| `/assets/vendor/gsap/EasePack.min.js` | GSAP 扩展缓动（Bounce/Elastic 等） |
+| `/assets/vendor/gsap/CustomEase.min.js` | GSAP 自定义缓动曲线 |
+| `/assets/vendor/gsap/TextPlugin.min.js` | GSAP 打字机效果 |
+
+**图标用法**：
+```html
+<!-- 跟随文字颜色（推荐） -->
+<span aria-hidden="true" style="width:16px;height:16px;display:inline-block;background:currentColor;-webkit-mask:url('/assets/icons/fingerprint.svg') center/contain no-repeat;mask:url('/assets/icons/fingerprint.svg') center/contain no-repeat;"></span>
+<!-- 保留原色 -->
+<img src="/assets/icons/fingerprint.svg" alt="" width="16" height="16">
+```
+
+AI 模型 / Provider 品牌图标可以使用 LobeHub 静态图标的 npmmirror 镜像 CDN。优先固定版本号，避免 `latest` 变更导致图标漂移；只在模型、供应商、AI 服务品牌标识场景使用，不替代通用 UI 图标。
+
+```html
+<!-- SVG，保留品牌原色 -->
+<img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/1.91.0/files/icons/openai.svg" alt="OpenAI" width="18" height="18">
+<img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/1.91.0/files/icons/anthropic.svg" alt="Anthropic" width="18" height="18">
+<img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/1.91.0/files/icons/deepseek-color.svg" alt="DeepSeek" width="18" height="18">
+```
+
+---
+
+## Ant Design 使用规范
+
+Ant Design 5.29.3 已内置为 UMD 包（`window.antd`），可优先选择使用。
+
+> `Segmented` 的默认样式视觉厚重、组件库感过强，禁止原样用于成品界面；优先根据语义改用 `Tabs`、`Radio.Group` 等更合适的控件，确需使用时必须通过 `ConfigProvider`、design token 或组件公开 API 调整为与页面一致的轻量样式。
+
+### ① 依赖加载顺序（缺一不可，顺序不可乱）
+
+```html
+<link href="/assets/antd/reset.css" rel="stylesheet">
+<script src="/assets/react/react.min.js"></script>
+<script src="/assets/react-dom/react-dom.min.js"></script>
+<script src="/assets/dayjs/dayjs.min.js"></script>
+<script src="/assets/antd/antd.min.js"></script>
+```
+
+> 资源版本固定为 5.29.3。只加载 `/assets/antd/reset.css` 和 UMD JS；组件样式由 UMD 运行时注入，禁止额外加载或引用 `/assets/antd/antd.min.css`，也禁止混用其他版本的 Ant Design CSS。
+
+### ② 强烈建议：跟随 DraftGo 系统主题
+
+用 `antd.ConfigProvider` 包裹根组件，读取 `App.theme` 和 CSS 变量 `--dg-accent`，实现 dark/light 自动切换和主题色联动：
+
+```javascript
+const App = window.parent?.App;
+
+function getAntdThemeConfig() {
+  const isDark = App?.theme === 'dark';
+  const accent = getComputedStyle(document.documentElement)
+    .getPropertyValue('--dg-accent').trim() || '#27272a';
+  return {
+    algorithm: isDark ? antd.theme.darkAlgorithm : antd.theme.defaultAlgorithm,
+    token: { colorPrimary: accent }
+  };
+}
+
+const Root = () => {
+  const [themeConfig, setThemeConfig] = React.useState(getAntdThemeConfig);
+  React.useEffect(() => {
+    const ob = new MutationObserver(() => setThemeConfig(getAntdThemeConfig()));
+    ob.observe(document.documentElement, {
+      attributes: true, attributeFilter: ['style', 'class', 'data-theme']
+    });
+    return () => ob.disconnect();
+  }, []);
+  return React.createElement(antd.ConfigProvider, { theme: themeConfig },
+    React.createElement(YourApp)
+  );
+};
+ReactDOM.createRoot(document.getElementById('root')).render(React.createElement(Root));
+```
+
+### ③ 组件状态样式的单一所有权
+
+交互组件的 hover、focus、disabled、error 等状态，在同一视觉属性上只能由一个层级负责。组件库已经管理内部 DOM 和状态样式时，业务页不得再以 CSS 介入同一状态的边框、轮廓、阴影、背景或颜色；否则 CSS 层叠会把两套状态效果同时呈现，或在组件升级后产生不可预期的覆盖。
+
+- 使用 AntD 等组件库时，组件库是状态样式的所有者。主题联动和样式调整走 `ConfigProvider`、design token 或组件公开的配置 API，不为其内部结构补写全局或通用选择器。
+- 自建组件时，业务页才是状态样式的所有者；状态规则必须收敛到该组件的专有类或页面根容器内，不能影响其他组件或页面。
+- 改动前先确认所有权；同一状态属性不得同时由 token/API 和 CSS 覆盖定义。若必须接管第三方组件样式，先移除或禁用原有对应效果，再用有作用域的规则完整接管。
+
+### ④ 强烈建议：弹窗和 Toast 走 DraftGo 系统
+
+| antd 原生 | 改用 |
+|-----------|------|
+| `Modal.confirm(...)` | `await App.confirm(msg, title)` |
+| `Modal.info / warning(...)` | `App.showModal(msg, title)` |
+| `message.success(...)` | `App.showSuccess(msg)` |
+| `message.error(...)` | `App.showError(msg)` |
+| `message.info / warning(...)` | `App.showInfo / showWarning(msg)` |
+
+Tooltip（hover 浮层）无对应 App API，保留 antd 原生。
+
+### ⑤ 禁止 ESM 方式加载 antd
+
+```html
+<!-- ❌ 禁止 —— antd ESM 版 Button 是 object 而非 React 组件 -->
+<script type="module">
+  import * as antd from 'https://cdn.jsdelivr.net/npm/antd@6.x/+esm';
+</script>
+```
+
+---
+
+## 空状态（Empty State）规范
+
+**触发：页面需要展示"暂无数据"、"列表为空"等空状态**
+
+### ❌ 禁止写法（图标偏左 bug）
+
+```javascript
+// 错误：display:block 使 <i> 变为块级元素，text-align:center 对块级元素无效 → 图标偏左
+h('div', { style: { textAlign: 'center' } },
+  h('i', { className: 'fa-solid fa-plug', style: { display: 'block' } }),
+  '暂无数据'
+)
+```
+
+### ✅ antd 页面：用 `antd.Empty`（首选）
+
+```javascript
+const { Empty } = antd;
+
+// Table 的 locale.emptyText
+locale={{ emptyText: React.createElement(Empty, {
+  image: Empty.PRESENTED_IMAGE_SIMPLE,
+  description: '暂无数据'
+}) }}
+
+// 独立空状态区域
+React.createElement(Empty, {
+  image: Empty.PRESENTED_IMAGE_SIMPLE,
+  description: '暂无 API，点击右上角「新增」开始注册'
+})
+```
+
+### ✅ 非 antd 页面 / 自定义样式：flexbox 容器（禁止用 text-align 居中图标）
+
+```html
+<style>
+.dg-empty {
+  display: flex; flex-direction: column;
+  align-items: center; justify-content: center;
+  padding: 48px 24px; gap: 10px;
+  color: var(--dg-text-muted);
+}
+.dg-empty-icon { font-size: 28px; opacity: .4; }
+.dg-empty-text { font-size: 13px; }
+</style>
+
+<div class="dg-empty">
+  <i class="fa-solid fa-plug dg-empty-icon"></i>
+  <span class="dg-empty-text">暂无数据</span>
+</div>
+```
+
+```javascript
+// React h() 写法
+h('div', { style: { display:'flex', flexDirection:'column', alignItems:'center',
+  justifyContent:'center', padding:'48px 24px', gap:10, color:'var(--dg-text-muted)' } },
+  h('i', { className: 'fa-solid fa-plug', style: { fontSize:28, opacity:.4 } }),
+  h('span', { style: { fontSize:13 } }, '暂无数据')
+)
+```
+
+> **核心原则**：图标居中必须用 `align-items: center`（flexbox），不能依赖 `text-align: center` + `display: block`。
+
+---
+
+## GSAP 动效规范
+
+**做页面时，尽可能引入 GSAP 提升体验感**。GSAP 是 DraftGo 内置动效库，适合入场动画、滚动交互、状态切换、数字滚动等所有需要"动起来"的场景。
+
+加载规则：
+- 核心 `gsap.min.js` 必须首先加载，其余插件按需选加
+- 使用插件前必须调用 `gsap.registerPlugin(...)`
+- GSAP 优先使用 `/assets/vendor/gsap/` 本地路径；确需 CDN 时优先使用国内镜像引入
+
+```html
+<script src="/assets/vendor/gsap/gsap.min.js"></script>
+<script src="/assets/vendor/gsap/ScrollTrigger.min.js"></script>
+<script>
+  gsap.registerPlugin(ScrollTrigger);
+</script>
+```
+
+### 常用模式速查
+
+**页面入场（卡片/列表逐个淡入上移）**
+```javascript
+gsap.from('.card', {
+  y: 30, opacity: 0, duration: 0.5, stagger: 0.08,
+  ease: 'power2.out', clearProps: 'all'
+});
+```
+
+**滚动触发（元素进入视口时播放）**
+```javascript
+gsap.from('.section', {
+  scrollTrigger: { trigger: '.section', start: 'top 80%' },
+  y: 40, opacity: 0, duration: 0.6, ease: 'power3.out'
+});
+```
+
+**Timeline 编排（多步骤有序动画）**
+```javascript
+const tl = gsap.timeline({ defaults: { ease: 'power2.out', duration: 0.4 } });
+tl.from('.title',    { y: -20, opacity: 0 })
+  .from('.subtitle', { y: -10, opacity: 0 }, '-=0.2')
+  .from('.btn',      { scale: 0.9, opacity: 0 }, '-=0.1');
+```
+
+**数字滚动（计数器）**
+```javascript
+gsap.to({ val: 0 }, {
+  val: 9527, duration: 1.5, ease: 'power1.out',
+  onUpdate() { el.textContent = Math.round(this.targets()[0].val).toLocaleString(); }
+});
+```
+
+**按钮 hover 微交互**
+```javascript
+document.querySelectorAll('.btn').forEach(btn => {
+  btn.addEventListener('mouseenter', () => gsap.to(btn, { scale: 1.04, duration: 0.2 }));
+  btn.addEventListener('mouseleave', () => gsap.to(btn, { scale: 1,    duration: 0.2 }));
+});
+```
+
+**SplitText 逐字入场**
+```javascript
+gsap.registerPlugin(SplitText);
+const split = new SplitText('.headline', { type: 'chars' });
+gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.04, duration: 0.5, ease: 'back.out(1.7)' });
+```
+
+### 注意事项
+
+- 动画时长：微交互 0.15–0.25s，元素入场 0.4–0.6s，页面级过渡 0.6–1s
+- `clearProps: 'all'` 适合只播一次的入场动画，避免 inline style 污染后续样式
+- 页面卸载时清理：`ScrollTrigger.getAll().forEach(t => t.kill())`
+- 不要同一元素混用 CSS transition 和 GSAP tween（会产生竞争）
+- 不要为动效而动效；动画必须服务于体验，不能影响可用性
+
+---
+
+## 颜色 Token（强制）
+
+| Token | 用途 |
+|---|---|
+| `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` | 背景层级 |
+| `--dg-text-primary` / `--dg-text-secondary` / `--dg-text-muted` | 文字层级 |
+| `--dg-accent` / `--dg-accent-hover` / `--dg-accent-subtle` | 主题色 |
+| `--dg-border` / `--dg-success` / `--dg-error` / `--dg-warning` | 功能色 |
+
+配色决策顺序：
+
+- 默认优先采用系统主题 token，让页面继承当前站点的 `App.theme` 与 `App.colorScheme`
+- 页面与系统 token 明显不搭配、品牌要求、用户明确指定或图表需要区分多系列时，允许使用自主配色
+- 自主配色必须提供浅色与深色两套变量或覆盖，不能只在当前主题下看起来正常
+- 自主配色仍优先落成页面局部 CSS 变量，再由组件引用，避免把 hex / rgb 散落在样式里
+- 所有正文、按钮、输入框、状态提示的文字对比度必须达到 WCAG AA（正文 4.5:1）
+
+例外：品牌色、图表色。硬编码时必须同时提供 `[data-theme="dark"]` 覆盖；如浅色主题也偏离系统 token，应同时提供 `[data-theme="light"]` 或默认变量。
+
+主题机制：壳层注入时已把 CSS 变量写入 `<head>`，页面无需初始化，直接用 `var(--dg-*)` 即可。
+
+```javascript
+// 读取（仅需 JS 分支时才读）
+const theme = App?.theme;          // 'light' | 'dark'
+const scheme = App?.colorScheme;   // 'dark-gray-white' | 'deep-blue-white' | ...
+
+// 切换
+App.applyTheme('dark');
+App.setColorScheme('deep-blue-white');
+```
+
+---
+
+## 导航栏开发
+
+| 属性 | 说明 |
+|---|---|
+| `data-nav-position="top\|side"` | 根元素必填 |
+| `data-nav-width="220px"` | 侧边栏展开宽度（可选，默认 260px） |
+| `data-nav-collapsed-width="64px"` | 收起宽度（可选，默认 72px） |
+
+```html
+<aside data-nav-position="side" data-nav-width="220px">
+  <a href="/dashboard" data-page-route="/dashboard">仪表盘</a>
+</aside>
+```
+
+导航链接推荐用 `data-page-route` 实现路由感知跳转，避免硬编 `onclick`。
+
+导航栏设计建议：
+- 未登录态可突出登录 / 注册 / 介绍入口
+- 已登录态显示常用业务入口和个人入口
+- 管理员态额外显示后台入口，但不要让普通用户看到管理入口
+- 收起状态保留最小可识别导航，不要只剩装饰图标
+
+---
+
+## AIHub 页面 SDK
+
+新页面需要 AI 对话 UI 时，加载完整版脚本并使用原生 `<dg-chat>`：
+
+```html
+<script src="/assets/draftgo-chat.js"></script>
+<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
+```
+
+需要动态创建时使用 `DraftGoChat.create()`：
+
+```javascript
+const chat = DraftGoChat.create('#chat-host', {
+  protocol: 'draftgo-agent',
+  agentId,
+  surface: 'inline',
+  view: 'conversation'
+});
+```
+
+完整配置、协议、事件、历史、扩展与安全约束见 `references/chat-sdk.md`。
+
+`DraftGoAI` 是同一脚本提供的旧代码兼容门面，只用于没有对话 UI 的轻量调用或图片生成：
+
+```javascript
+// 聊天（默认流式；onDelta(delta, full) 每个增量触发，Promise resolve 完整文本）
+const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
+
+// 多轮：传 sessionId 复用会话（→ body.session_id）；Agent 开启“持续对话”后服务端续写历史。不传 = 无状态单轮
+await DraftGoAI.chat(agentId, '接着上一条', handler, { sessionId: threadKey });
+
+// 图片生成（必须用 /images 接口，不要用 /chat）
+const result = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
+
+// 用户选模型
+const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
+await DraftGoAI.chat(agentId, '你好', handler, { model: selectedModel, sessionId: threadKey });
+```
+
+- 使用 `DraftGoAI` 前同样必须先加载 `/assets/draftgo-chat.js`；壳层不会默认注入。
+- `DraftGoAI.chat` 内部创建隐藏 `<dg-chat>`，始终流式。新页面的可见对话、附件、模型选择器、推理、历史和重生成直接使用 `<dg-chat>`。
+- Agent 的能力与 `spec` 字段（工具/子智能体/记忆/结构化输出/多模态/持续对话/ttft failover）见 `references/aihub.md`。
+
+---
+
+## 退出登录
+
+```javascript
+window.parent.location.href = '/login';  // ✅ 完整刷新，导航栏重新加载
+// App.navigate('/login') ❌ 导航栏不会更新
+```
+
+---
+
+## 加载体验
+
+- 初始渲染必须先展示骨架屏，再异步填数据
+- 禁止因请求失败导致整页空白
+- 空态必须有明确文案 + 后续操作入口，不能留空或只有 loading
+- 若父级是 flex 工作区，空态容器应 `flex:1` 承接剩余空间，避免高度塌陷
+- 弹窗/抽屉内容区建议隐藏外层滚动条，把滚动控制在内容区：`overflow:hidden` + 内部 `overflow:auto; min-height:0`，避免双滚动条和粗糙滚动体验
+
+## 选择器与表单体验
+
+- 涉及下拉选项样式时，优先做自定义弹层菜单，确保触发态、浮层、选中态和禁用态都与页面风格一致
+- 若确实使用原生控件，只能作为退化方案，不作为首选风格；不要把系统默认下拉样式当作最终交付
+
+---
+
+## 平台能力调用快速参考
+
+```javascript
+const App = window.parent?.App;
+
+// 响应信封：{ code: 200, data: <载荷>, message: "success" }
+const res = await App.get('pages'); // 全量列表；表格/后台列表建议显式传 page + page_size
+if (res.code !== 200) { App.showError(res.message); return; }
+const items = res.data.items;
+
+// 非后台管理页面读取动态 DB 业务列表：
+// 当前用户是管理员时带 scope=mine，避免业务视角拿到全量 owner 数据。
+const params = { page: 1, page_size: 20 };
+if (App.isAdmin && !App.getCurrentRoute?.()?.startsWith('/admin')) params.scope = 'mine';
+const dbRes = await App.get('db/order', params);
+
+// URL 参数（三阶回落）
+const q = (window.__DG_ROUTE_CONTEXT__ || window.__DG_GET_ROUTE_CONTEXT__?.() || App?.getCurrentRouteContext?.() || { query: {} }).query;
+```
+
+完整 API 表 → `{{SKILL_DIR}}/references/app-api.md`