draftgo-cli 3.0.55 → 4.0.1

package/resources/skill/references/frontend.md

@@ -6,252 +6,106 @@ version: 2.0.0
 
 # DraftGo 前端开发规范
 
-> 根 `SKILL.md` 是完整核心规则源；本文件只展开前端实现方法。若表述冲突，以根 `SKILL.md` 为准，不额外叠加固定验收动作。
+本文件只保留 DraftGo 前端特有的运行契约和操作边界。架构见 `architecture.md`，iframe、认证和路由见 `runtime.md` / `app-api.md`，动态 DB 见 `data.md`。根 `SKILL.md` 的交付与验收规则优先，不在此重复增加浏览器动作。
 
-> 本文件只规定前端**操作性规则**，已剥离的内容见：
-> 架构原理 → `references/architecture.md`
-> App API / Token / 路由 / 运行时 → `references/runtime.md` · `references/app-api.md`
-> 动态 DB / filters → `references/data.md`
-> 安全边界 → 本文件“必须 / 禁止”与 `references/runtime.md`；自定义服务权限与审计见 `references/custom-services.md`
-
----
-
-## 页面开发强制规则
-
-### 真实闭环（强制）
-
-- 页面必须有可访问 route，从真实入口可达（导航/首页/后台菜单/相关按钮至少一处）
-- 按钮、表单、搜索、筛选、分页、提交、删除等交互默认真实有效
-- 涉及异步数据、提交、搜索、筛选或接口调用时，必须覆盖相关加载态/空态/错误态/成功态，不能只堆静态卡片
-- 展示可维护内容时主动判断是否需要后台管理页 + 同一份真实数据
-- 业务模块尽量不要复制大量同构工作台；列表、详情、编辑、管理页优先按任务差异设计结构、密度和操作区
-- 无法实现真实闭环时停止开发，向用户说明阻塞点；确认为平台限制、可复用经验或连续排查失败时再写入 `.draftgo/lessons/`
-
-### 数据型页面可用性约束（强制）
-
-数据型页面必须保证主要操作可达、滚动边界清晰，并使分页、批量操作或保存控件在空数据、少量数据和长列表状态下始终可用。横向溢出不能把核心操作藏到不可达区域，加载态、空态、错误态和成功态都必须保持页面结构稳定。
-
-具体信息架构、DOM、组件、布局和视觉风格由 Agent 根据任务目标、受众、数据规模和现有资源自主设计。CLI 与 Skill 不提供页面骨架，也不指定工作台、表格页或其他固定页面结构。
-
-### 文本与图标换行控制（强制）
-
-按钮、标签、导航项、状态徽章等**小范围整体区域**内的文本和图标，**禁止自动换行**：
-
-```css
-/* ✅ 不换行，整体在同行显示 */
-.btn-content { white-space: nowrap; }
-
-/* ❌ 允许换行 → 宽度不足时文本/图标散落，视觉参差不齐 */
-.btn-content { white-space: normal; } /* 默认即 normal，必须显式覆盖 */
-```
-
-**常见中招场景**：
-- 按钮内文字 + 图标（`提交` + `→` 换行变两行）
-- 操作行内的多个 icon+文字 组合（不同按钮高度不一）
-- 标签/徽章内文字换行导致错位
-- 表单字段名 + 输入框 并排时字段名换行
-
-**判断标准**：这块内容在视觉上是一个整体（属于同一个操作、同一个标签、同一个单元），就不应该因为容器宽度被拆开。整行拆行是可以的，但**同组内的子元素不能拆行**。
-
----
-
-### 移动端与多端适配（按页面目标与影响范围）
-
-移动端适配是产品与受众判断，不是所有页面的固定验收门。公众页面、可能从手机访问的业务页面、已有响应式断点，或本次修改涉及布局、导航和弹窗时，应认真处理窄屏；明确的桌面工作台、仅改文案或数据逻辑时，不要机械增加移动端检查。
-
-响应式实现只规定结果，不提供固定配方：
-
-- 内容使用可用空间并避免整页横向溢出；容器宽度、断点和边距沿用现有设计系统，或根据真实内容和目标设备确定。
-- 并排区域必须在目标窄屏上保持阅读顺序、核心操作和导航可达；是否堆叠、隐藏次要信息或调整密度由 Agent 自主设计。
-- 按钮、链接和导航项应提供适合目标设备的操作区域，相邻操作避免误触。
-- 字体、标题层级和间距在目标视口保持清晰且不遮挡内容，不预设统一字号或间距尺度。
-- 表格、代码和其他超宽内容应在合理边界内可访问，不能让核心操作因溢出而不可达。
-- 弹窗和抽屉在目标视口内完整可用，长内容有明确滚动边界。
-
-需要浏览器证据时按页面受众和现有断点运行 `draftgo verify <type> <id> --url <url>`；只有验收确实覆盖多端时加 `--viewport both`，不要机械遍历与任务无关的视口。业务 HTML 位于 iframe 时默认 `--frame auto` 会检查顶层和可见 iframe，`--selector` 可直接定位业务 DOM。
-
-### 导航与系统页边界（强制）
-
-- 顶部导航已有内置资源时，先通过 MCP 查询导航元数据；需要分析或编辑完整 HTML 时执行 `draftgo checkout nav <id>`，读取 worktree 文件。需要新导航时优先基于现有结构创建或复刻，而不是直接改坏内置导航。
-- 导航栏通常要同时考虑未登录 / 已登录 / 管理员三种状态，以及收起 / 展开状态；普通用户不显示管理后台入口，管理员额外显示管理后台入口。
-- 管理端侧边栏通常基于现有内置侧边栏修改，新增业务管理路由优先追加或局部调整；删除系统内置页面入口前先确认影响。
-- 业务页面内可以做局部二级导航或侧边栏，但必须考虑外部导航已存在且可单独配置，避免重复渲染全局导航。
-- 系统内置页面通常不改；确需修改登录、设置、权限、用户、系统配置等页面时，先说明影响、验证方式和保留的管理员能力。
-- 页面风格不要照搬管理侧内置页面；业务前台按业务用户和品牌语境设计，管理侧按操作效率和信息密度设计。
+## 页面决策
 
 ### 页面身份与创建
 
-业务新页面默认是数据库中的完整 HTML 页面。开始正文工作前，结合用户表达与 MCP 中的标题、route、用途和入口判断目标：
+业务新页面默认是数据库中的完整 HTML 页面。先结合用户意图与 MCP 中的标题、route、用途和入口判断目标：
 
-- 用户指定页面、ID、已有 route，或现有页面与需求职责明确一致时，按已有页面修改并 checkout 对应 ID。
-- 用户明确要求新增，或需求需要独立 route/职责且定向搜索后没有合适页面时，按新页面处理。通过 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 使用实时创建契约，取得新页面 ID 后再 checkout；完整 HTML 仍只走 checkout/commit。
-- “做一个功能页面”本身不等于新增，也不等于修改。证据足以形成唯一合理方案时 Agent 直接推进；若多个已有候选或新增/修改会产生明显不同的产品结果，再用一个简短问题澄清。
+- 用户指定页面、ID、已有 route，或现有页面职责明确一致：修改已有页面，确认唯一 ID 后 checkout。
+- 用户明确要求新增，或需求需要独立 route 且定向搜索无合适页面：通过实时 API 创建，取得 ID 后 checkout；完整 HTML 仍只走 checkout/commit。
+- “做一个功能页面”本身不等于新增，也不等于修改。证据足够时直接推进；多个候选会导致不同产品结果时再向用户澄清。
 
-搜索用于确认页面身份和避免重复，按标题、route 或业务用途逐步缩小范围即可，无需枚举无关资源。Checkout 应对应已确认的目标资源；新资源先创建并取得 ID。
+搜索只需按标题、route 或用途逐步缩小范围。Checkout 应对应已确认的目标资源；新资源先创建并取得 ID。不要枚举无关页面。
 
-### 新增页面入口
+### 入口与导航
 
-- 公开页 → 顶部/侧边导航、首页入口、相关按钮之一
-- 后台页 → 后台导航、管理菜单或现有后台入口
-- 多页面功能：列表/详情/新建/编辑/管理必须互相走通
-- 隐藏页、回调页、按链接直达的详情页或草稿页可按产品目的不绑定全局入口；需要入口时优先接入现有导航或业务流程
+- 新页面应从真实业务入口可达：公开页接导航、首页或相关操作；后台页接后台导航或管理菜单。隐藏页、回调页和链接直达页可按产品目的不绑定全局入口。
+- 多页面功能应让列表、详情、新建、编辑或管理流程互相走通。
+- 顶部导航先用 MCP 定位；需要完整 HTML 时 `draftgo checkout nav <id>`。新增业务入口优先局部调整现有导航，不破坏系统入口。
+- 导航按产品需要处理未登录、已登录、管理员及收起状态。普通用户不得看到管理入口。
+- 业务页面可有局部导航，但不要重复渲染外部全局导航。修改登录、设置、权限、用户、系统配置等内置页面前先核对影响和管理员能力。
 
-### `page_1_root.html` 首页特例（强制）
+导航资源根元素使用：
 
-- 仍是默认内置首页 → 根据用户目标、受众和现有资源自主决定改造方式；CLI 不指定官网、工作台或其他页面结构
-- 已被用户改过 → 只做要求范围内的修改，不强制重做
-- 判断依据：看 HTML 内容是否保留 DraftGo 默认文案/系统介绍/未定制品牌，不要只凭文件名判断
+| 属性 | 含义 |
+|---|---|
+| `data-nav-position="top\|side"` | 必填位置 |
+| `data-nav-width="220px"` | 可选侧栏展开宽度，默认 260px |
+| `data-nav-collapsed-width="64px"` | 可选收起宽度，默认 72px |
 
----
+链接使用 `href` 与 `data-page-route`，避免用硬编码 `onclick` 模拟路由。
 
-## 页面实践经验
+### 首页特例
 
-任何前端页面的开发都应从用户体验出发，而不是只完成静态结构或功能清单。先理解用户、核心任务、使用频率、数据规模和目标设备，再自主选择信息架构、组件库、视觉语言与实现方式。
+`page_1_root.html` 若仍保留 DraftGo 默认文案、系统介绍和未定制品牌，可按用户目标改造；已经定制时只改需求范围。不要只凭文件名判断。
 
-- 让主要任务形成真实闭环，并为加载、空数据、错误、成功、无权限和重试等状态提供清晰反馈。
-- 主动考虑适量动效能否帮助用户理解层级、状态变化、空间关系和操作结果。没有明确体验收益时可以不用，不为动效而动效。
-- 动效可按场景使用 CSS transition/animation、Web Animations API、组件库能力或 GSAP；具体方案由 Agent 根据页面需要决定。
-- 动效不能阻塞操作、掩盖等待或造成明显布局跳动；关键状态不能只靠动画表达，并为 `prefers-reduced-motion` 提供降级。
-- 修改既有页面时尊重原有产品语言和交互习惯；新增体验应与页面目标一致，而不是机械套用统一模板。
+## 体验结果
 
-具体 GSAP 资源、插件加载和生命周期处理见下方“GSAP 动效规范”。
+任何前端页面的开发都应从用户体验出发。根据用户、核心任务、频率、数据规模和目标设备决定信息架构、组件、布局与视觉，不套固定页面骨架。
 
----
+- 按钮、表单、搜索、筛选、分页、提交和删除等已呈现交互应真实有效；主要流程必须闭环。
+- 异步流程覆盖相关加载、空数据、错误、成功、无权限和重试状态，不能因请求延迟或失败整页空白。
+- 数据型页面应让主要操作、分页、批量操作和保存控件在空、短、长列表下都可达；滚动边界明确，横向溢出不能隐藏核心操作。
+- 展示可维护内容时判断是否需要管理入口并复用同一份真实数据。列表、详情和编辑结构按任务差异设计，不复制大量同构工作台。
+- 按钮、标签、导航项、徽章等视觉整体内部使用 `white-space: nowrap`；整组可换行，但图标与文字不能被拆散。
+- 空态需有明确文案和下一步操作；自定义空态用 flex 对齐图标与文字，不依赖 `text-align` 居中块级图标。
+- 弹窗和抽屉把滚动放在内容区，避免双滚动条；flex 内容区使用 `min-height: 0` 保持滚动可用。
+- 下拉选择使用组件库选择器或可访问的自定义弹层，不使用浏览器默认 `<select>`。
 
-## 必须 / 禁止
-
-### 必须
-- 完整 HTML 文档结构（`<html><head><body>`）
-- 静态资源用本地路径（见下方资源清单）
-- 配色优先使用系统主题语义 token `var(--dg-*)`，并同时适配浅色 / 深色模式
-- 弹窗用 `App.confirm()` / `App.toast()`，禁止 `window.alert/confirm/prompt`
-- 弹窗/抽屉优先做成无外层滚动条，滚动控制在内容区
-- 页面初始渲染展示默认状态（骨架屏），不能因请求延迟空白
-
-### 禁止
-- ❌ 境外 CDN（googleapis / jsdelivr / cdnjs / unpkg）；优先使用 `/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、ESM import、npm 依赖或构建产物直接写进数据库 HTML；需要 React 时使用基座内置的 React UMD 与兼容组件库
-- ❌ 硬编码颜色值 → ✅ `var(--dg-*)`
-- ❌ 在业务页面实现全局浮窗/客服/统计脚本 → ✅ `frontend_global_*` 固定槽位
-- ❌ 在业务页面重写 Toast 组件 → ✅ 使用 `App.toast()`，视觉、位置、大小、透明度、时长通过 `frontend_global_toast_*` 系统配置统一调整
+### 响应式
 
----
+移动端是产品范围，不是固定验收门。公众页面、手机访问场景或已有响应式布局应处理窄屏；明确桌面工作台或仅改数据逻辑时不机械增加多端工作。
 
-## 前端底座与组件库清单
+在目标设备上保证：无整页横向溢出；阅读顺序和核心操作可达；表格/代码等宽内容有可访问滚动边界；弹窗完整可用；文字、导航和操作区不重叠。断点、堆叠和密度由真实内容及现有设计系统决定。
 
-### 运行形态
+### 动效
 
-- **壳层前端**位于 DraftGo 基座的 `frontend/`，技术栈为 React 19 + Vite 8 + Tailwind CSS 4；这是维护壳层代码时使用的构建链路。
-- **业务页面和导航 HTML**存储在数据库资源中，由壳层以 iframe 运行。它们必须是完整的原生 HTML 文档，不能写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
-- 数据库页面需要 React 时，只能使用下方内置的 React 18 UMD 资源和 `window.React` / `window.ReactDOM`。不要把壳层的 React 19 npm 依赖、外部 CDN 或其他 React 版本混入页面。
-- 只有用户明确要求修改 DraftGo 壳层前端时，才处理 `frontend/` 源码。
+动效仅用于解释层级、状态、空间关系或操作结果。可用 CSS、Web Animations、组件库或内置 GSAP，并为 `prefers-reduced-motion` 降级；不得阻塞操作、掩盖等待、引发布局跳动或成为唯一状态表达。
 
-### 内置组件库清单
+GSAP 从 `/assets/vendor/gsap/gsap.min.js` 先加载核心，再按需加载插件并 `gsap.registerPlugin(...)`。可用插件：`ScrollTrigger`、`ScrollToPlugin`、`Draggable`、`Flip`、`SplitText`、`MorphSVGPlugin`、`MotionPathPlugin`、`DrawSVGPlugin`、`Observer`、`EasePack`、`CustomEase`、`TextPlugin`。页面卸载时 kill timeline/trigger；同一属性不要同时由 CSS transition 与 GSAP 控制。
 
-| 名称 | 版本 | 运行形态 | 本地资源 |
-|---|---:|---|---|
-| Ant Design | 5.29.3 | React 18 UMD，导出 `window.antd` | `/assets/antd/reset.css`、`/assets/react/react.min.js`、`/assets/react-dom/react-dom.min.js`、`/assets/dayjs/dayjs.min.js`、`/assets/antd/antd.min.js` |
-| Basecoat UI | 1.0.2 | HTML + CSS/JS，导出 `window.basecoat` | `/assets/vendor/basecoat/basecoat.min.css`、`/assets/vendor/basecoat/basecoat.min.js` |
-| Oat UI | 0.7.0 | Web Components，导出 `window.ot` | `/assets/vendor/oat/oat.min.css`、`/assets/vendor/oat/oat.min.js` |
+## 运行形态
 
-此清单不规定组件库选择或场景对应关系；根据页面需求自行决定是否使用其中任一库。
+- DraftGo 壳层位于 `frontend/`，使用 React 19 + Vite 8 + Tailwind CSS 4。只有用户明确要求修改壳层时才编辑该源码。
+- 业务页面与导航存储为数据库中的完整 HTML 文档，由壳层在 iframe 中运行。不得写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
+- 数据库页面需要 React 时，只能使用内置 React 18 UMD 的 `window.React` / `window.ReactDOM`；不要混入壳层 React 19 或其他版本。
+- 页面使用 `const App = window.parent?.App`。参数读取 `window.__DG_ROUTE_CONTEXT__.query`；页面跳转使用父窗口；登出调用 `await App.logout()`。
 
-### 主题适配与标准加载方式
+## 必须与禁止
 
-基座提供两个适配资源：`/assets/adapters/draftgo-ui.js` 和 `/assets/adapters/draftgo-theme.css`。
+必须：
 
-- `draftgo-ui.js` 暴露 `window.DraftGoUI`，其中 `DraftGoUI.load(name)` 接受 `antd`、`basecoat`、`oat`，按资源清单加载对应库；加载 AntD 后会为 React 根节点接入 DraftGo 的主题 token。
-- `draftgo-theme.css` 用于 Basecoat 和 Oat，将其语义变量映射到 DraftGo 的 `--dg-*` token。它必须在对应组件库 CSS **之后**加载。
-- 页面手工引入 AntD 时，必须严格遵守下方的依赖顺序；不要附加第三方 AntD CSS，也不要使用 ESM/CDN 版本。
+- 提交完整 `<html><head><body>` 文档，静态资源使用下方本地路径。
+- 默认使用 `var(--dg-*)` 主题 token，并支持浅色/深色；用户输入或不可信 HTML 经 DOMPurify 净化。
+- 使用 `App.confirm()`、`App.toast()` 或对应反馈 API；关键状态不能只靠颜色或动画。
+- 初始渲染立即显示稳定的加载状态。
 
-```html
-<!-- Basecoat：组件 CSS 在前，DraftGo 主题适配层在后 -->
-<link href="/assets/vendor/basecoat/basecoat.min.css" rel="stylesheet">
-<link href="/assets/adapters/draftgo-theme.css" rel="stylesheet">
-<script src="/assets/adapters/draftgo-ui.js"></script>
-<script src="/assets/vendor/basecoat/basecoat.min.js" defer></script>
+禁止：
 
-<!-- 或由适配器按清单加载：await DraftGoUI.load('basecoat') -->
-```
+- 境外 CDN（googleapis、jsdelivr、cdnjs、unpkg）；品牌图标的明确例外见资源章节。
+- `window.alert/confirm/prompt`、`App()`、`window.location.search`、页面内直接 `window.location.href=...`。
+- 把 TSX、ESM、npm 依赖或构建产物写进数据库 HTML。
+- 在业务页面实现全局浮窗、客服、统计脚本或重复 Toast；使用 `frontend_global_*` 槽位和系统配置。
+- 用无作用域 CSS 覆盖组件库内部 hover、focus、disabled、error 状态。
 
-```html
-<!-- Oat：同样让主题适配层位于组件 CSS 之后 -->
-<link href="/assets/vendor/oat/oat.min.css" rel="stylesheet">
-<link href="/assets/adapters/draftgo-theme.css" rel="stylesheet">
-<script src="/assets/adapters/draftgo-ui.js"></script>
-<script src="/assets/vendor/oat/oat.min.js" defer></script>
-```
-
-## 本地静态资源清单
+## 组件与资源
 
-| 路径 | 说明 |
-|---|---|
-| `/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/adapters/draftgo-ui.js` | DraftGo UI 适配器；提供 `window.DraftGoUI`、组件库按需加载和 AntD 主题接入 |
-| `/assets/adapters/draftgo-theme.css` | Basecoat / Oat 到 DraftGo `--dg-*` 主题 token 的 CSS 映射；应后于对应组件 CSS 加载 |
-| `/assets/vendor/basecoat/basecoat.min.css` + `basecoat.min.js` | Basecoat UI 1.0.2，原生 HTML 组件库 |
-| `/assets/vendor/oat/oat.min.css` + `oat.min.js` | Oat UI 0.7.0，Web Components 组件库 |
-| `/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 图标。
+| 名称 | 版本与形态 | 本地资源 |
+|---|---|---|
+| Ant Design | 5.29.3，React 18 UMD，`window.antd` | `/assets/antd/reset.css`、React、ReactDOM、dayjs、`/assets/antd/antd.min.js` |
+| Basecoat UI | 1.0.2，HTML/CSS/JS，`window.basecoat` | `/assets/vendor/basecoat/basecoat.min.css`、`basecoat.min.js` |
+| Oat UI | 0.7.0，Web Components，`window.ot` | `/assets/vendor/oat/oat.min.css`、`oat.min.js` |
 
-```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">
-```
+`/assets/adapters/draftgo-ui.js` 提供 `window.DraftGoUI` 与 `DraftGoUI.load('antd'|'basecoat'|'oat')`。Basecoat/Oat 的 `/assets/adapters/draftgo-theme.css` 必须位于对应组件 CSS 之后。组件选择取决于任务，不强制套用。
 
----
+### Ant Design 契约
 
-## Ant Design 运行契约
-
-Ant Design 5.29.3 已内置为 UMD 包（`window.antd`）。
-
-
-### ① 依赖加载顺序（缺一不可，顺序不可乱）
+手工加载顺序不可变：
 
 ```html
 <link href="/assets/antd/reset.css" rel="stylesheet">
@@ -261,303 +115,55 @@ Ant Design 5.29.3 已内置为 UMD 包（`window.antd`）。
 <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 覆盖定义。若必须接管第三方组件样式，先移除或禁用原有对应效果，再用有作用域的规则完整接管。
-
-### ④ DraftGo 平台反馈 API 对照
-
-| antd 原生 | 对应平台 API |
-|-----------|------|
-| `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` 示例
+不要加载 `antd.min.css`、ESM/CDN AntD 或其他版本。根组件使用 `antd.ConfigProvider`，根据 `App.theme` 选择 `antd.theme.darkAlgorithm/defaultAlgorithm`，并把 `--dg-accent` 传给 `token.colorPrimary`；监听根元素的 `style/class/data-theme` 变化以刷新主题。
 
-```javascript
-const { Empty } = antd;
+组件库是其内部状态样式的唯一所有者：优先用 ConfigProvider、design token 或公开 API。自建组件才由页面 CSS 管理状态，且规则限定在组件类或页面根内。
 
-// 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 是 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 | 用途 |
+| AntD | 平台反馈 |
 |---|---|
-| `--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）
+| `Modal.confirm` | `await App.confirm(msg, title)` |
+| `Modal.info/warning` | `App.showModal(msg, title)` |
+| `message.success/error` | `App.showSuccess/showError(msg)` |
+| `message.info/warning` | `App.showInfo/showWarning(msg)` |
 
-例外：品牌色、图表色。硬编码时必须同时提供 `[data-theme="dark"]` 覆盖；如浅色主题也偏离系统 token，应同时提供 `[data-theme="light"]` 或默认变量。
+Tooltip 可保留组件库原生实现。
 
-主题机制：壳层注入时已把 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） |
+| Tailwind runtime | `/assets/tailwindcss.js` |
+| React/AntD | `/assets/react/react.min.js`、`/assets/react-dom/react-dom.min.js`、`/assets/dayjs/dayjs.min.js`、`/assets/antd/antd.min.js` |
+| UI adapters | `/assets/adapters/draftgo-ui.js`、`/assets/adapters/draftgo-theme.css` |
+| Basecoat/Oat | `/assets/vendor/basecoat/*`、`/assets/vendor/oat/*` |
+| Icons/fonts | `/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`、`/assets/icons/manifest.json`、`/assets/fonts/*.css` |
+| Markdown/code | `/assets/vendor/marked/marked.min.js`、`/assets/vendor/highlightjs/highlight.min.js`、`/assets/vendor/prism/prism.min.js` |
+| HTML/security/export | `/assets/vendor/dompurify/purify.min.js`、`/assets/vendor/html2canvas/html2canvas.min.js` |
+| Chat | `/assets/draftgo-chat.js` |
+| Motion | `/assets/vendor/gsap/*.js` |
 
-```html
-<aside data-nav-position="side" data-nav-width="220px">
-  <a href="/dashboard" data-page-route="/dashboard">仪表盘</a>
-</aside>
-```
+通用图标优先使用本地图标或 FontAwesome。模型/Provider 品牌标识可用固定版本的 LobeHub `@lobehub/icons-static-svg` npmmirror URL；不得用 `latest`，也不得替代通用 UI 图标。
 
-导航链接推荐用 `data-page-route` 实现路由感知跳转，避免硬编 `onclick`。
+## 主题
 
-导航栏设计建议：
-- 未登录态可突出登录 / 注册 / 介绍入口
-- 已登录态显示常用业务入口和个人入口
-- 管理员态额外显示后台入口，但不要让普通用户看到管理入口
-- 收起状态保留最小可识别导航，不要只剩装饰图标
+| Token | 用途 |
+|---|---|
+| `--dg-bg-base/page/surface` | 背景层级 |
+| `--dg-text-primary/secondary/muted` | 文字层级 |
+| `--dg-accent/hover/subtle` | 主题色 |
+| `--dg-border/success/error/warning` | 边框与状态 |
 
----
+壳层已把变量注入 `<head>`，直接使用即可。默认继承 `App.theme` 与 `App.colorScheme`。品牌或图表需要自主配色时，先定义页面局部变量并提供 light/dark 两套值；正文和交互文字保持 WCAG AA。不要把 hex/rgb 散落在组件样式中。
 
 ## AIHub 页面 SDK
 
-新页面需要 AI 对话 UI 时，加载完整版脚本并使用 `<dg-chat>`：
+AI 对话 UI 使用：
 
 ```html
 <script src="/assets/draftgo-chat.js"></script>
 <dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
 ```
 
-动态创建使用 `DraftGoChat.create()`；无 UI 的旧代码文本调用或图片生成可使用同一脚本提供的 `DraftGoAI` 兼容门面。完整配置、事件、会话、安全约束和示例见 `references/chat-sdk.md`，Agent 能力与 `spec` 字段见 `references/aihub.md`。
-
----
-
-## 退出登录
-
-```javascript
-const App = window.parent?.App;
-await App.logout(); // 请求服务端登出、清理认证状态、触发 auth 事件并跳转配置的登录页
-```
-
----
-
-## 加载体验
-
-- 初始渲染必须先展示骨架屏，再异步填数据
-- 禁止因请求失败导致整页空白
-- 空态必须有明确文案 + 后续操作入口，不能留空或只有 loading
-- 若父级是 flex 工作区，空态容器应 `flex:1` 承接剩余空间，避免高度塌陷
-- 弹窗/抽屉内容区建议隐藏外层滚动条，把滚动控制在内容区：`overflow:hidden` + 内部 `overflow:auto; min-height:0`，避免双滚动条和粗糙滚动体验
-
-## 选择器与表单体验
-
-- 严禁使用浏览器默认的 `<select>` 控件；下拉选择必须使用组件库提供的选择器或自定义弹层菜单
-- 确保触发态、浮层、选中态、禁用态和键盘操作都与页面风格及可访问性要求一致
+动态创建使用 `DraftGoChat.create()`；无 UI 文本或图片调用可用同一脚本的 `DraftGoAI` 兼容门面。完整事件、会话和安全契约见 `chat-sdk.md`，Agent `spec` 见 `aihub.md`。
 
-平台请求与反馈 API 见 `references/app-api.md`；iframe 路由、认证与全局层见 `references/runtime.md`；动态 DB、`scope=mine`、筛选和关系见 `references/data.md`。
+平台请求与反馈见 `app-api.md`；iframe 路由、认证与全局层见 `runtime.md`；动态 DB、`scope=mine`、筛选和关系见 `data.md`。