draftgo-cli 2.0.5 → 3.0.0

package/resources/skill/rules/frontend.md

@@ -1,675 +1,210 @@
----
+---
 name: draftgo-frontend-rules
 description: DraftGo frontend page development rules.
-version: 1.0.0
+version: 2.0.0
 ---
 
 # DraftGo 前端开发规范
 
-## 架构认知
-
-DraftGo 前端**不是传统 SPA**：
-- 平台壳层使用 React + Vite 编译，shadcn/ui + Tailwind CSS 已作为默认前端范式引入
-- 业务页面 HTML 存在数据库，运行在 `iframe.srcdoc`
-- 导航栏 HTML 存在数据库，由壳层按需加载
-- 页面通过 `window.parent.App` 调用平台能力
-
----
-
-## 前端 UI 能力调用声明
-
-平台前端开发默认采用 React + shadcn/ui + Tailwind CSS；新增壳层管理界面、组件、弹窗、表单、表格和设置页时，优先复用 `frontend/src/components/ui` 下的 shadcn 组件与 Tailwind token。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用；本文件同时规定 DraftGo 前端运行时、资源、数据、路由、入口绑定和验证方法。
-
----
-
-## dg-* = shadcn（最高优先级）
-
-在 DraftGo 中，`dg-*` 就意味着 shadcn。
-
-- `dg-*` 是 shadcn/ui 在数据库 HTML 页面机制里的协议化表达，不是一套自研 UI 库。
-- 数据库页面仍然写 HTML，不进入 Vite/React 编译链；因此不能把 TSX 版 shadcn 组件直接写进 `page.value.html`。
-- 需要 shadcn 组件能力时，优先写对应 `dg-*` 标签，例如 `dg-button`、`dg-card`、`dg-form`、`dg-table`、`dg-tabs`、`dg-dialog`、`dg-dropdown-menu`、`dg-sheet`。
-- 若 shadcn 有组件，DraftGo 必须有对应 `dg-*` 映射。当前 runtime 已按映射表提供基础协议覆盖；复杂组件在 iframe 中以 HTML runtime 方式复用 shadcn 语义，而不是直接运行 React/Radix 组件。
-- `dg-*` 的属性、状态、交互预期和 token 命名应跟随 shadcn：例如 `variant`、`size`、`disabled`、`default-value`、`data-state`、`aria-*`。
-- `dg-dialog`、`dg-sheet`、`dg-dropdown-menu`、`dg-popover`、`dg-tooltip` 等复杂组件使用 trigger/content/open-state 协议；`dg-table[source]` 支持基础数据拉取和 `data-dg-props.columns` 渲染。
-
-AI 开发时的判断句：**看到 `dg-*`，必须读作 shadcn；要用 shadcn，数据库页面就写 `dg-*`。**
-
----
-
-## 运行时机制（Runtime）
-
-### 壳层启动流程
-
-壳层入口由 Vite/React 工程加载，当前兼容 runtime 仍通过 `frontend/src/core/runtime.js` 的 `createAppRuntime()` 完成以下初始化：
-
-1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
-2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
-3. `loadSetupStatus()` — 检查系统是否已初始化（`/api/system/setup/status`）
-4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
-
-### iframe 注入机制
-
-壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
-- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数）
-- 主题 CSS 变量
-- 静态资源（数据库页面使用的本地 Tailwind runtime、FontAwesome、GSAP 等）
-
-页面 HTML 以 `iframe.srcdoc` 方式渲染，**不是独立 URL**，因此：
-- `window.location` 指向壳层地址，不可用于读取路由参数
-- `window.parent.App` 是壳层暴露的能力对象
-
-### App 对象来源
-
-壳层将 `app` 对象赋值给 `window.App`（通过 `Object.assign(app, ...)`），页面内通过 `window.parent.App` 访问。
-
-`app` 对象包含以下模块（均已合并到顶层）：
-
-| 属性/方法 | 来源模块 | 说明 |
-|---|---|---|
-| `get/post/put/patch/delete` | `api.js` | HTTP 请求，自动携带 token |
-| `uploadFile(file, onProgress)` | `api.js` | 文件上传 |
-| `toast(msg, type?, duration?)` | `feedback.js` | Toast 通知（type: success/error/warning/info，默认 info） |
-| `showSuccess(msg)` | `feedback.js` | 成功 Toast 3000ms ✓ |
-| `showError(msg)` | `feedback.js` | 错误 Toast 4000ms ✕ |
-| `showWarning(msg)` | `feedback.js` | 警告 Toast 3000ms ⚠ |
-| `showInfo(msg)` | `feedback.js` | 信息 Toast 3000ms ℹ |
-| `confirm(msg, title?)` | `feedback.js` | 确认弹窗，返回 Promise\<boolean\> |
-| `showModal(msg, title?)` | `feedback.js` | 信息模态框，带确定按钮 |
-| `showLoading() / hideLoading()` | `feedback.js` | 全局 loading 蒙层 |
-| `navigate(route)` | `runtime.js` | 路由跳转（pushState） |
-| `getCurrentRoute()` | `runtime.js` | 当前路径字符串 |
-| `getCurrentRouteContext()` | `runtime.js` | 完整路由上下文（含 query） |
-| `reloadGlobalLayer()` | `runtime.js` | 重载前端全局层 |
-| `openGlobalWidget(name)` / `closeGlobalWidget(name)` | `runtime.js` | 触发全局挂件打开/关闭事件 |
-| `logout()` | `runtime.js` | 登出并跳转登录页 |
-| `setAuthTokens({access_token, refresh_token})` | `runtime.js` | 登录后写入 token |
-| `applyTheme(theme)` | `runtime.js` | 切换主题（light/dark），同步写 localStorage + iframe |
-| `t(key, fallback?)` | `i18n.js` | 国际化文本 |
-| `currentUser` | state | 当前用户对象（未登录为 null） |
-| `isAdmin` | state | 是否管理员 |
-| `isAuthenticated` | state | 是否已认证 |
-| `hasToken` | state | 是否有 token（含未验证） |
-| `config` | state | 系统配置键值对 |
-| `theme` | state | 当前主题名（`'light'` \| `'dark'`） |
-
-### Token 存储
-
-| key | 说明 |
-|---|---|
-| `localStorage.dg_access_token` | 访问 token |
-| `localStorage.dg_refresh_token` | 刷新 token |
-
-登录成功后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。
-
-### 禁止使用浏览器默认弹窗（强制）
-
-**禁止**在页面中使用 `alert()`、`confirm()`、`prompt()`。它们会阻塞主线程、与平台交互协议不一致，且在 iframe 环境中行为不可预期。
-
-使用 App 提供的替代方案：
-
-| 浏览器原生 | DraftGo 替代 | 说明 |
-|---|---|---|
-| `alert(msg)` | `App.showModal(msg, title?)` | 信息展示，带确定按钮 |
-| `confirm(msg)` | `await App.confirm(msg, title?)` | 二次确认，返回 `Promise<boolean>`，注意必须 `await` |
-| `prompt(msg)` | 自行构建输入弹窗 | 平台无内置 prompt，需在页面内自建 modal + input，并保持与当前页面和平台交互一致 |
-
-```javascript
-// ❌ 禁止
-if (confirm('确认删除？')) { doDelete(); }
-
-// ✅ 正确
-const ok = await App.confirm('确认删除？', '删除确认');
-if (ok) { doDelete(); }
-
-// ❌ 禁止
-const name = prompt('请输入名称');
-
-// ✅ 正确：自建输入弹窗
-showInputModal('请输入名称', async (value) => {
-  if (value) { await save(value); }
-});
-```
-
-### 前端全局层（强制）
-
-全局浮窗、全局客服/反馈入口、统计监控脚本、Toast 二开、全站挂件等，属于前端全局层，不属于单个业务页面。全局层通过 `sys_config.category = frontend_global` 存储，并在页面管理的「全局」分类编辑固定槽位。
-
-规则：
-
-- 不要在业务页面内重复实现全局浮窗、客服、反馈入口或统计脚本。
-- 不允许新增全局项；只能编辑系统内置固定槽位。
-- 如果不了解用途，不要修改全局层；它会影响所有页面。
-- Toast 调用协议保持稳定：继续用 `App.toast()` / `App.showSuccess()` / `App.showError()`；默认时长可通过全局项二开。
-- 保存全局层后调用 `App.reloadSystemConfig()` 或 `App.reloadGlobalLayer()` 让运行时立即重载。
-
-常见槽位：
-
-| config_key | 用途 |
-|---|---|
-| `frontend_global_head_html` | 注入父级壳层 head |
-| `frontend_global_body_html` | 注入父级壳层 body 末尾 |
-| `frontend_global_css` / `frontend_global_js` | 父级壳层全局 CSS/JS |
-| `frontend_global_iframe_head_html` | 注入每个业务页面 iframe head |
-| `frontend_global_widget_html/css/js` | 全局挂件层 |
-| `frontend_global_toast_css/position/duration_*` | Toast 二开 |
-
-### 全局事件
-
-| 事件名 | 触发时机 |
-|---|---|
-| `dg:auth-ready` | token 验证完成（成功或失败） |
-| `dg:auth-changed` | token 变更（登录/登出） |
-
-页面内监听：`window.parent.addEventListener('dg:auth-ready', handler)`
+> 本文件只规定前端**操作性规则**，已剥离的内容见：  
+> 架构原理 → `{{SKILL_DIR}}/core/architecture.md`  
+> App API / Token / 路由 / 运行时 → `{{SKILL_DIR}}/specs/runtime.md` · `{{SKILL_DIR}}/quickref/app-api.md`  
+> dg-* 映射 → `{{SKILL_DIR}}/specs/ui-protocol.md` · `{{SKILL_DIR}}/quickref/dg-components.md`  
+> 动态 DB / filters → `{{SKILL_DIR}}/specs/data.md`  
+> 开发禁区 → `{{SKILL_DIR}}/specs/security.md`
 
-### API 请求路径解析规则
-
-`App.get/post/...` 的路径参数解析（来自 `api.js`）：
-
-| 传入值 | 实际请求 |
-|---|---|
-| `'pages'` | `{apiBase}/api/pages` |
-| `'pages/123'` | `{apiBase}/api/pages/123` |
-| `'/api/pages'` | `{apiBase}/api/pages` |
-| `'https://...'` | 直接请求（绝对 URL） |
-
-### GET 请求筛选范式
-
-**分页**（绝大多数列表接口）：
-
-```javascript
-App.get('users', { page: 1, page_size: 20 })
-App.get('pages/', { page: 1, page_size: 20 })
-```
-
-> 分页参数统一使用 `page` 与 `page_size`。GET 列表请求若不携带这两个参数，则返回全量数据；当数据量超过 10000 条时后端会拒绝并返回 400，此时必须传入 `page` 与 `page_size`。
-
-**通用筛选参数**：
-
-| 参数 | 类型 | 说明 |
-|---|---|---|
-| `page` | int | 页码，从 1 开始 |
-| `page_size` | int | 每页条数 |
-| `search` | string | 全文搜索（users/roles/pages/navigations/feedback —— **注意：动态 DB 不用 search，见下方**） |
-| `status` | string | 状态过滤（`active`/`inactive`/`published` 等，按资源而定） |
-| `type` | string | 类型过滤（notices/feedback/aihub） |
-| `tag` | string | 标签过滤（pages/aihub） |
-
-**典型示例**：
-
-```javascript
-// 用户列表，带搜索+状态+角色过滤
-App.get('users', { page: 1, page_size: 20, search: 'alice', status: 'active', role_id: 3 })
-
-// 页面列表，带标签+状态过滤
-App.get('pages/', { page: 1, page_size: 20, search: 'home', tag: 'blog', status: 'published' })
-```
-
-### 动态 DB（`/api/db/{type}`）检索范式
-
-动态 DB 的检索**不用 `search` 参数**，改用 **`filters` 结构化条件**，直接对记录的 `data` JSON 字段做查询。
-
-```javascript
-// 动态 DB 列表查询：filters 每项形如 "字段:操作符:值"，可传多个（数组），多个为 AND
-App.get(`db/${type}`, {
-  page: 1, page_size: 20,
-  filters: ['title:like:公告', 'views:gte:100', 'status:eq:paid'],
-  order_by: 'views', order: 'desc',
-})
-
-// 动态 DB 创建：业务字段必须放在 data 包裹里，不要平铺到 body 顶层
-App.post(`db/${type}`, { data: { name: '张三', age: 30 }, status: 1 })
-
-// 动态 DB 更新：同样用 data 包裹
-App.put(`db/${type}/${id}`, { data: { age: 31 } })
-```
-
-**filters 操作符**（字段必须在 db_meta schema 里标 `searchable`，且操作符要匹配字段的检索模式）：
-
-| 操作符 | 含义 | 适用 searchable 模式 |
-|---|---|---|
-| `eq` | 精确等于 | exact / fuzzy / range |
-| `like` | 模糊包含（`%`/`_` 会被自动转义，按字面匹配） | fuzzy |
-| `gte` / `lte` / `gt` / `lt` | 数值范围 | range |
-| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy / range |
-| `contains` | 数组字段包含某值 | contains |
-
-- 省略操作符时（`filters: ['title:公告']`）默认 `like`。
-- 字段间互相隔离，按 `data.字段` 精确定位，不存在跨字段串扰；中文可正常检索。
-- `order_by` 只能用 searchable 字段；`order` 取 `asc`/`desc`，默认 `desc`。
-- 字段不可检索、或操作符与字段模式不匹配时，后端返回 400。
-
-**DB Meta 说明**：涉及动态数据库操作前，先读取 `db_meta/index.json` 了解当前项目有哪些 DB 类型（`type`）以及各字段的 `searchable` 模式，再调用 `/api/db/{type}`。不要硬编码 type 值，也不要对未标 searchable 的字段做 filters。
-
----
+若本地 Agent 存在前端 UI Skills，前端界面开发时优先调用。
 
 ---
 
-## 页面资产开发
+## 页面开发强制规则
 
-### 页面默认按完整页面功能处理（强制）
+### 真实闭环（强制）
 
-用户说“做 / 新建 / 增加一个页面”时，默认不是静态稿，而是一个可被真实使用的页面功能：
-- 页面必须有可访问 route，且 route 与 page_id / 本地文件对应清楚。
-- 页面必须从真实入口可达：导航栏、首页模块、后台菜单、列表操作按钮或相关页面链接至少绑定一个。
-- 页面里的按钮、表单、搜索、筛选、分页、详情跳转、提交、保存、删除等交互默认要真实有效；只有用户明确说“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”时，才允许做静态。
-- 页面必须有加载态、空态、错误态、成功态，不能只堆静态卡片。
-- 若页面展示可维护内容（案例、新闻、产品、招聘、资料等），主动判断是否需要后台管理页和同一份真实数据；不要只写死 HTML 或前端数组。
-- 若 DraftGo 动态 DB、已有 db_meta、custom_scripts、外部 API、AIHub 等能力都无法完成真实闭环，不要写伪功能交差；停止开发，向用户说明阻塞点，并按 dev-workflow 写入 `.draftgo/lessons/`。
+- 页面必须有可访问 route，从真实入口可达（导航/首页/后台菜单/相关按钮至少一处）
+- 按钮、表单、搜索、筛选、分页、提交、删除等交互默认真实有效
+- 必须有加载态/空态/错误态/成功态，不能只堆静态卡片
+- 展示可维护内容时主动判断是否需要后台管理页 + 同一份真实数据
+- 无法实现真实闭环时停止开发，向用户说明阻塞点，写入 `.draftgo/lessons/`
 
-### 操作型页面空间利用（强制）
+### 操作型页面布局（强制）
 
-后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先按**工作台布局**处理，而不是普通内容文档流。先分配页面空间，再放组件：
-- 页面根容器应占满可用视口 / iframe 内容区，使用 `display:flex; flex-direction:column; min-height:100vh` 或等效结构。
-- 顶部筛选、搜索、批量入口、标题操作区保持稳定高度，不应随数据量漂移。
-- 主体数据区使用 `flex:1; min-height:0; overflow:auto` 承接剩余空间，数据少时保留工作区空白，不让页面高度随行数塌陷。
-- 分页、批量操作栏、保存栏、流程按钮等控制区应固定在当前工作区底部或保持稳定位置，不能跟随 1-2 条数据上浮。
-- 内部滚动优先发生在数据区 / 表格区，避免整个后台页面因为少量内容显得松散，也避免大量内容把操作区挤出视野。
-
-参考结构：
+后台管理、表格、列表等操作型页面用**工作台布局**，不用文档流堆叠：
 
 ```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;
-}
+.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; }
 ```
 
-不要让分页、保存栏、批量操作栏跟随少量数据上浮；不要用纯文档流堆叠后台管理页面。
+- 分页/操作栏/保存栏固定在工作区底部，不随数据量上浮
+- 滚动发生在数据区，不是整页
 
 ### 新增页面绑定（强制）
 
-创建或新增页面后，必须继续处理“绑定”：
-- 公开前台页面：绑定到顶部/侧边导航、首页入口模块、相关列表/详情按钮之一。
-- 后台管理页面：绑定到后台导航、管理菜单或现有后台入口。
-- 多页面功能：列表、详情、新建、编辑、管理等页面之间必须互相能走通。
-- 导航链接必须使用 `data-page-route`，例如 `<a href="/cases" data-page-route="/cases">案例库</a>`。
-- 推送时同时推送页面和被修改的导航栏 / 入口页面。
-- 验证时必须从真实入口点击进入目标页面；只手动输入 route 打开不算完整验证。
-
-如果用户明确要求创建“暂不公开页面 / 隐藏页 / 草稿页”，可以不绑定导航，但必须在 Task / changelog / 完成说明里写明“暂不绑定入口”的原因。
+- 公开页 → 顶部/侧边导航、首页入口、相关按钮之一
+- 后台页 → 后台导航、管理菜单或现有后台入口
+- 多页面功能：列表/详情/新建/编辑/管理必须互相走通
+- 导航链接必须用 `data-page-route`：`<a href="/orders" data-page-route="/orders">订单</a>`
+- 用户明确要求"隐藏页/草稿页"才可不绑定，但必须在 changelog / Task 说明原因
 
 ### `page_1_root.html` 首页特例（强制）
 
-`draftgo init` 会把内置系统页面拉取到 `.draftgo/pages/`。这些系统页只用于理解平台能力和默认资源结构，不能作为新项目首页的直接改写模板。
+- 仍是默认内置首页 → 按用户需求和本地 UI Skills 重新实现，不沿用内置文案和结构
+- 已被用户改过 → 只做要求范围内的修改，不强制重做
+- 判断依据：看 HTML 内容是否保留 DraftGo 默认文案/系统介绍/未定制品牌，不要只凭文件名判断
 
-当目标页面是首页（常见标识：`id=1`、文件名为 `.draftgo/pages/page_1_root.html`、route 为 `/` 或标题为「首页」）时，先判断它是否仍是 init 拉取下来的**默认内置首页**：
-- 如果仍是默认内置首页，把它视为项目自己的首页资源，按用户需求、Story 和本地 UI Skills 重新实现，不沿用内置页的文案和业务结构。
-- 如果首页已经被用户改过，只做用户要求范围内的修改，不强制重做整页。
-- 判断是否仍为默认内置首页时，优先看 HTML 内容是否明显保留 DraftGo 默认首页的文案、结构、系统介绍、默认模块和未定制品牌；不要只凭文件名或 `id=1` 下结论。
-- 修改前先读取 `.draftgo/story.yaml`（如存在）和用户需求；若 Story 不存在且用户只要求“重做首页/设计首页”，按高风险任务处理，先确认方向再做。
-- 无论首页如何实现，都必须遵守本文件的资源、主题、弹窗、路由和响应格式规则。
-- 验证时除常规 console / push 外，还要检查桌面和移动宽度下无明显布局破损，且用户路径入口可达。
+---
 
-一句话：**`page_1_root.html` 是项目自己的首页资源；默认内置首页不要直接套改，已定制首页不要强制重做。**
+## 必须 / 禁止
 
 ### 必须
 - 完整 HTML 文档结构（`<html><head><body>`）
-- 新增页面必须处理入口绑定；若修改入口页或导航栏，也要同步 push
-- 静态资源优先使用本地路径：
-  ```html
-  <script src="/assets/tailwindcss.js"></script>
-  <link href="/assets/fontawesome/css/all.min.css" rel="stylesheet">
-  ```
-- 颜色全部用语义 token（见下方"颜色 Token"）
-- 弹窗用 `App.confirm()` / `App.toast()`
-- 页面初始渲染必须展示默认状态，不能因网络请求延迟导致空白
-- 需要 shadcn 组件能力时优先使用对应 `dg-*` 标签；`dg-*` 必须映射 shadcn 组件语义
+- 静态资源用本地路径（见下方资源清单）
+- 颜色全用语义 token `var(--dg-*)`
+- 弹窗用 `App.confirm()` / `App.toast()`，禁止 `window.alert/confirm/prompt`
+- 页面初始渲染展示默认状态（骨架屏），不能因请求延迟空白
+- 需要组件能力时用对应 `dg-*` 标签
 
 ### 禁止
-- 禁止引用境外 CDN（`fonts.googleapis.com`、`cdn.jsdelivr.net`、`cdnjs.cloudflare.com`、`unpkg.com` 等）
-- 如需外部 CDN，只允许国内镜像（`npmmirror.com`、`staticfile.net`），且优先用本地资源
-- 禁止 `window.alert()` / `window.confirm()` / `window.prompt()`
-- 禁止在页面内渲染系统 Header、Logo、用户头像下拉等全局导航元素
-- 禁止 `App()` 写法（`App` 是对象不是函数）
-- 禁止 `const App = () => window.parent?.App`（正确：`const App = window.parent?.App`）
-- 禁止把 React/TSX 版 shadcn 组件直接写进数据库 HTML
-- 禁止把 `dg-*` 当作 daisyUI / Bootstrap / Ant Design / Element Plus / 自研组件库；`dg-*` 只能是 shadcn 的 HTML 协议形态
+- ❌ 境外 CDN（googleapis / jsdelivr / cdnjs / unpkg）→ ✅ 国内镜像或本地资源
+- ❌ 外部 CDN 引入图标 → ✅ `/assets/icons/{name}.svg`
+- ❌ `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 版 shadcn 组件写进数据库 HTML
+- ❌ `dg-*` 当 daisyUI / Bootstrap / Ant Design
+- ❌ 硬编码颜色值 → ✅ `var(--dg-*)`
+- ❌ 在业务页面实现全局浮窗/客服/统计脚本 → ✅ `frontend_global_*` 固定槽位
+
+---
 
-### 本地静态资源清单
+## 本地静态资源清单
 
 | 路径 | 说明 |
 |---|---|
 | `/assets/tailwindcss.js` | Tailwind CSS 运行时 |
-| `/assets/fontawesome/css/all.min.css` | FontAwesome 6 图标库 |
+| `/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/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/prism/prism.min.js` | 代码语法高亮 |
-| `/assets/vendor/prism/themes/prism-tomorrow.min.css` | Prism 主题 |
-| `/assets/vendor/prism/components/prism-python.min.js` | Prism Python 语言支持 |
-| `/assets/vendor/prism/components/prism-json.min.js` | Prism JSON 语言支持 |
-| `/assets/vendor/prism/components/prism-yaml.min.js` | Prism YAML 语言支持 |
-| `/assets/vendor/gsap/gsap.min.js` | GSAP 3.15.0 动画核心库 |
-| `/assets/vendor/gsap/ScrollTrigger.min.js` | GSAP 滚动触发插件 |
-| `/assets/vendor/gsap/ScrollToPlugin.min.js` | GSAP 滚动定位插件 |
-| `/assets/vendor/gsap/Observer.min.js` | GSAP 输入事件观察插件 |
-| `/assets/vendor/gsap/Draggable.min.js` | GSAP 拖拽插件 |
-| `/assets/vendor/gsap/Flip.min.js` | GSAP 布局过渡插件（FLIP 动画） |
-| `/assets/vendor/gsap/MotionPathPlugin.min.js` | GSAP 路径动画插件 |
-| `/assets/vendor/gsap/SplitText.min.js` | GSAP 文字拆分动画插件 |
-| `/assets/vendor/gsap/TextPlugin.min.js` | GSAP 文字逐字动画插件 |
-| `/assets/vendor/gsap/CustomEase.min.js` | GSAP 自定义缓动曲线 |
-| `/assets/vendor/gsap/EasePack.min.js` | GSAP 扩展缓动集合（Bounce/Elastic 等） |
-| `/assets/vendor/gsap/DrawSVGPlugin.min.js` | GSAP SVG 路径描边动画插件 |
-| `/assets/vendor/gsap/MorphSVGPlugin.min.js` | GSAP SVG 形变动画插件 |
-
-> **GSAP 使用规范**：如需使用 GSAP，禁止引用任何境外 CDN（gsap.com/cdn.jsdelivr.net 等），必须使用上表本地路径。按需引入所需插件，注册插件后方可使用：`gsap.registerPlugin(ScrollTrigger, CustomEase)`。
-
----
-
-## URL 参数读取
-
-页面运行在 `iframe.srcdoc` 中，`window.location.search` 不可靠——它指向壳层地址，不是页面路由。
-
-### 注入机制
-
-壳层通过 `decorateFrameHtml()` 向每个页面注入 `<script data-dg-route-bridge>`，该脚本将路由上下文写入 iframe 的 `window`：
-
-- `window.__DG_ROUTE_CONTEXT__` — 完整路由上下文（冻结对象），含 `query`、`route`、`params` 等
-- `window.__DG_QUERY__` — `routeContext.query` 的快捷方式
-- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式的兜底读取
-
-### 标准读取方式（三阶回落）
-
-```javascript
-const routeContext =
-  window.__DG_ROUTE_CONTEXT__        // 首选：bridge 注入的主变量
-  || window.__DG_GET_ROUTE_CONTEXT__?.()  // 备选：函数兜底
-  || window.parent?.App?.getCurrentRouteContext?.()  // 三选：壳层 API
-  || { query: {} };                  // 兜底：空对象防崩溃
-const query = routeContext.query || {};
-
-// 使用示例
-// 路由 /doctor/prescription-estimate?patientId=42&visitId=7
-const patientId = query.patientId;  // "42"
-const visitId = query.visitId;      // "7"
-```
-
-### 禁止
-
-- `new URLSearchParams(window.location.search)` — iframe 中取不到壳层 URL
-- `window.location.search` 直接解析 — 同上
-
-### 常见陷阱
-
-页面 JS 中引用 `window.__DG_ROUTE_CONTEXT__` 是**读取**操作。框架注入 bridge 的检测基于 `<script data-dg-route-bridge>` 标记，不会因页面代码读取该变量而误判跳过注入。
-
----
-
-## 平台能力调用（App API）
-
-```javascript
-const App = window.parent?.App;
-
-// ─── 响应格式 ───
-// App.get/post/put/patch/delete 原样返回后端 JSON，不做任何剥壳。
-// 后端统一信封：{ code: 200, message: "success", data: ... }
-//
-// 统一消费模式：
-//   const res = await App.get('some/endpoint');
-//   if (res.code !== 200) { App.showError(res.message || '操作失败'); return; }
-//   const payload = res.data;       // 业务数据
-//   // 分页列表：payload.items / payload.total / payload.page / payload.page_size
-//   // 非分页列表：payload 本身是数组
-
-// GET（第二参数为 query params）
-const res = await App.get('pages', { page: 1, page_size: 20 });
-const pages = res.data.items;  // Array
-
-// POST / PUT / PATCH / DELETE
-await App.post('feedback', { type: 'bug', title: '标题' });
-await App.put('pages/123', { title: '新标题' });
-await App.delete('pages/123');
-
-// Toast（推荐用便捷方法）
-App.toast('操作成功', 'success');            // 通用方法，type 默认 'info'
-App.showSuccess('操作成功');                  // 成功提示
-App.showError('操作失败');                    // 错误提示
-App.showWarning('请注意');                    // 警告提示
-App.showInfo('提示信息');                     // 信息提示
-
-// 确认弹窗
-const ok = await App.confirm('确认删除？', '删除确认');
-if (!ok) return;
-// App.confirm(msg, title?) — 返回 Promise<boolean>，取消/点击蒙层返回 false
-
-// 信息模态框
-App.showModal('Token 详情内容', 'Token 明细');
-// App.showModal(msg, title?) — 替代 window.alert()
-
-// Loading 蒙层
-App.showLoading(); await someAsyncOp(); App.hideLoading();
-
-// 文件上传（返回格式同标准信封）
-const res = await App.uploadFile(file, progress => console.log(progress));
-const url = res.data?.url || res.data?.path;
-
-// 外部 API 调用（已注册到「外部 API 接入」）
-// 认证由后端注入；不要在页面里写 API Key / Bearer
-const r = await App.callApi('weather-now', {
-  path_params: { city: 'beijing' },   // 替换 path 模板里的 {city}
-  query_params: { unit: 'metric' },
-  // body: { ... },                    // POST/PUT/PATCH 才生效
-  // headers: { 'X-Trace': 't1' },     // 不会覆盖后端注入的认证头
-});
-// 返回：{ status_code, headers, body, duration_ms, error }
-// body 已按 Content-Type 自动解析；上游业务错误看 status_code，不是 error
-
-// 列出当前用户可调用的外部 API（含 code / name / 各 JSON Schema）
-const apis = await App.listApis();
-```
-
-路径解析：`https://...` 直接请求 · `/api/...` 拼接 origin · 其他相对路径拼接 apiBase
-
-### AIHub 页面 SDK
-
-```javascript
-// 聊天型 Agent
-const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => {
-  render(full);
-});
-
-// 图片生成型 Agent
-const imageResult = await DraftGoAI.images(agentId, '生成一张产品主图', {
-  size: '1024x1024',
-  quality: 'auto',
-  response_format: 'url',
-  n: 1,
-});
-
-// 用户自主选择模型
-const selectable = await DraftGoAI.getSelectableModels(agentId);
-if (selectable.user_selectable && selectable.models.length) {
-  renderModelPicker(selectable.models);
-}
-
-await DraftGoAI.chat(agentId, '你好', (delta, full) => {
-  render(full);
-}, {
-  model: getSelectedModel(),
-});
+| `/assets/vendor/prism/prism.min.js` | 代码高亮 |
+| `/assets/vendor/gsap/gsap.min.js` | 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/CustomEase.min.js` | GSAP CustomEase |
+
+**图标用法**：
+```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">
 ```
 
-图片生成型 Agent 必须调用 `/api/agents/{id}/images`，不要用 `/chat` 代替。模型是否支持生图由真实上游调用决定，管理端图片诊断只是可选参考。
-
-`DraftGoAI.getSelectableModels(agentId)` 返回 `{ user_selectable, models }`。`models` 是 Agent 主模型 + 备用模型白名单，不是供应商全量模型列表；只有管理端开启“用户选模型”后才会返回非空列表。用户选择值通过 `options.model` 传给 `DraftGoAI.chat/images`，后端仍会按 Agent 白名单校验。
-
-**外部 API 注意事项：**
-- code 不知道时先 `await App.listApis()` 查询
-- `r.error` 仅在代理层错误（超时 / 网络 / 校验失败）时非空
-- API 未注册 / 已禁用 / 无权限 → 后端以 4xx 抛错，会被 `App.callApi` 当成异常 throw
+GSAP：禁止引用任何境外 CDN，必须用本地路径，注册插件后才能使用：`gsap.registerPlugin(ScrollTrigger, CustomEase)`
 
 ---
 
 ## 颜色 Token（强制）
 
-禁止硬编码任何 hex / rgb / rgba / hsl 值。
-
 | Token | 用途 |
 |---|---|
-| `--dg-bg-base` | 页面底色 |
-| `--dg-bg-page` | 内容区背景 |
-| `--dg-bg-surface` | 卡片/面板背景 |
-| `--dg-text-primary` | 主文字 |
-| `--dg-text-secondary` | 次要文字 |
-| `--dg-text-muted` | 弱化文字 |
-| `--dg-accent` | 主题色 |
-| `--dg-accent-hover` | 主题色 hover |
-| `--dg-border` | 边框 |
-| `--dg-success/error/warning/info` | 状态色 |
-
-例外：SVG 的 `fill`/`stroke` 可用 `currentColor` 或 `var(--dg-accent)`。
-
----
+| `--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` | 功能色 |
 
-## 主题机制（App.theme / App.colorScheme）
+例外：品牌色、图表色。硬编码时必须同时提供 `[data-theme="dark"]` 覆盖，对比度达 WCAG AA（文字 4.5:1）。
 
-### 概念分层
-
-| 概念 | 键 | 取值 | 说明 |
-|---|---|---|---|
-| 显示模式 | `App.theme` / `dg_theme` | `'light'` \| `'dark'` | 亮色/暗色 |
-| 配色方案 | `App.colorScheme` / `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` | light 模式下的色彩搭配 |
-
-### 内置配色方案
-
-| 方案 | 键 | 主题色 | 特点 |
-|---|---|---|---|
-| 深灰白（默认） | `dark-gray-white` | #27272a |
-| 深蓝白 | `deep-blue-white` | #1e3a5f |
-| 橙白 | `orange-white` | #ea580c |
-| 自定义 | `custom` | 用户自选 |
-
-### 入场主题
-
-页面以 `iframe.srcdoc` 渲染，壳层在注入 HTML 时已将当前主题的 CSS 变量写入 `<head>` 最顶部。
-
-**页面无需任何初始化代码**，CSS 变量在 DOM 解析时已生效，直接用 `var(--dg-*)` 即可。
-
-### 读取当前主题
+主题机制：壳层注入时已把 CSS 变量写入 `<head>`，页面无需初始化，直接用 `var(--dg-*)` 即可。
 
 ```javascript
-const App = window.parent?.App;
+// 读取（仅需 JS 分支时才读）
 const theme = App?.theme;          // 'light' | 'dark'
-const scheme = App?.colorScheme;   // 'dark-gray-white' | 'deep-blue-white' | 'orange-white' | 'custom'
-```
+const scheme = App?.colorScheme;   // 'dark-gray-white' | 'deep-blue-white' | ...
 
-仅在需要**按主题做 JS 逻辑分支**时才读取，纯样式差异用 CSS 变量解决。
-
-### 切换主题
-
-```javascript
-App.applyTheme('dark');                             // 切换显示模式
-App.setColorScheme('deep-blue-white');              // 切换为预设方案
-App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
-```
-
-调用后：壳层更新 CSS 变量 → 写入 localStorage → 同步注入当前 iframe。
-
-### 获取方案详情
-
-```javascript
-const info = App.getColorScheme();
-// { name: 'dark-gray-white', vars: { ... }, schemes: { ... } }
+// 切换
+App.applyTheme('dark');
+App.setColorScheme('deep-blue-white');
 ```
 
-### 监听主题变化
-
-壳层不广播主题变更事件。如果页面需要响应用户切换主题，用 `MutationObserver` 监听根元素 CSS 变量变化，或在切换按钮的回调里手动处理。
-
-### 禁止
-
-- 禁止在页面内读取 `localStorage.dg_theme`（通过 `App.theme` 获取）
-- 禁止在页面内读取 `localStorage.dg_color_scheme`（通过 `App.colorScheme` 获取）
-- 禁止在页面内调用 `document.documentElement.style.setProperty` 设置主题变量
-- 禁止硬编码任何颜色值作为主题分支的输出
-
 ---
 
-## 空态容器
+## 导航栏开发
 
-当页面需要展示“暂无数据”“列表为空”“加载失败”等状态时，必须渲染明确的状态容器、文案和后续操作入口，不能让页面空白或只有不可解释的 loading。
+| 属性 | 说明 |
+|---|---|
+| `data-nav-position="top\|side"` | 根元素必填 |
+| `data-nav-width="220px"` | 侧边栏展开宽度（可选，默认 260px） |
+| `data-nav-collapsed-width="64px"` | 收起宽度（可选，默认 72px） |
 
-若父级是 flex 工作区，空态容器应能承接剩余空间，避免数据区高度塌陷。具体呈现交给本地 UI Skills 或 Agent 自身判断。
+```html
+<aside data-nav-position="side" data-nav-width="220px">
+  <a href="/dashboard" data-page-route="/dashboard">仪表盘</a>
+</aside>
+```
 
----
+所有导航链接必须用 `data-page-route`，不要硬编 `onclick` 跳转。
 
-## 导航栏开发
+---
 
-导航栏是**数据库资产**，HTML 存储在 `navigation.html` 字段，由前端 runtime 动态挂载。
+## AIHub 页面 SDK
 
-### 导航类型
+```javascript
+// 聊天
+const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
 
-| 类型 | 根元素 | 必填属性 | 布局 |
-|---|---|---|---|
-| 顶栏 | `<header>` | `data-nav-position="top"` | 顶部 |
-| 侧边 | `<aside>` | `data-nav-position="side"` | 左侧，可声明自定义宽度 |
+// 图片生成（必须用 /images 接口，不要用 /chat）
+const result = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
 
-### 必须
-- 根元素加 `data-nav-position="top|side"`
-- 所有导航链接必须用 `data-page-route`：
-  ```html
-  <a href="/dashboard" data-page-route="/dashboard">仪表盘</a>
-  ```
+// 用户选模型
+const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
+await DraftGoAI.chat(agentId, '你好', handler, { model: selectedModel });
+```
 
-### 侧边栏宽度
+---
 
-侧边导航宽度由壳层 `#nav-container` 控制，导航根元素内部应保持 `width:100%;height:100%`。需要自定义宽度时，在根 `<aside>` 上声明：
+## 退出登录
 
-```html
-<aside data-nav-position="side" data-nav-width="220px" data-nav-collapsed-width="64px">
+```javascript
+window.parent.location.href = '/login';  // ✅ 完整刷新，导航栏重新加载
+// App.navigate('/login') ❌ 导航栏不会更新
 ```
 
-- `data-nav-width`：展开宽度，可选；不写默认 `260px`
-- `data-nav-collapsed-width`：收起宽度，可选；不写默认 `72px`
-- 支持纯数字（按 px 处理）或合法 CSS 长度，如 `220px`、`14rem`、`clamp(200px,20vw,260px)`
-- 不要在导航脚本里硬编码覆盖 `#nav-container` / `#page-container` 的 `260px`，优先用上述属性让 runtime 同步布局
+---
 
-### 常见错误
+## 加载体验
 
-| 错误 | 原因 | 修复 |
-|---|---|---|
-| 导航不显示 | `status` 为 `inactive` | 改为 `active` |
-| 布局错乱 | 缺少 `data-nav-position` | 在根元素加上该属性 |
-| 链接点击无效 | 缺少 `data-page-route` | 在 `<a>` 上加该属性 |
-| 主题切换后颜色异常 | 使用了硬编码颜色 | 改用 `var(--dg-*)` 变量 |
+- 初始渲染必须先展示骨架屏，再异步填数据
+- 禁止因请求失败导致整页空白
+- 空态必须有明确文案 + 后续操作入口，不能留空或只有 loading
+- 若父级是 flex 工作区，空态容器应 `flex:1` 承接剩余空间，避免高度塌陷
 
 ---
 
-## 退出登录
+## 平台能力调用快速参考
 
 ```javascript
-window.location.href = '/login';  // 正确：完整刷新，导航栏重新加载
-// 错误：navigate('/login')  — 导航栏不会更新
-```
+const App = window.parent?.App;
 
----
+// 响应信封：{ code: 200, data: <载荷>, message: "success" }
+const res = await App.get('pages', { page: 1, page_size: 20 });
+if (res.code !== 200) { App.showError(res.message); return; }
+const items = res.data.items;
 
-## 加载体验
+// URL 参数（三阶回落）
+const q = (window.__DG_ROUTE_CONTEXT__ || window.__DG_GET_ROUTE_CONTEXT__?.() || App?.getCurrentRouteContext?.() || { query: {} }).query;
+```
 
-- 禁止因网络请求失败导致整个页面空白
-- 页面初始化必须先渲染默认状态，再异步填充数据
-- 推荐使用 shadcn Skeleton 对应的 `dg-skeleton`，或使用与 shadcn token 对齐的骨架样式。
+完整 API 表 → `{{SKILL_DIR}}/quickref/app-api.md`