draftgo-cli 3.0.33 → 3.0.35

package/README.md

@@ -123,6 +123,9 @@ CLI 随包分发的 DraftGo skill 会同步基座 API 约定。集合写入统
 
 前端资源约定：
 
+- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航使用原生 HTML，不可写入 TSX、ESM import 或 npm 构建产物。数据库页面需要 React 时使用内置 React 18 UMD。
+- 内置组件库：Ant Design 5.29.3（React 18 UMD）、Basecoat UI 1.0.2（HTML + CSS/JS）、Oat UI 0.7.0（Web Components）。组件清单、运行方式和资源路径见 `resources/skill/references/frontend.md`；该文档不规定选型。
+- `/assets/adapters/draftgo-ui.js` 提供 `window.DraftGoUI` 和 `DraftGoUI.load(name)`；Basecoat/Oat 的主题适配资源为 `/assets/adapters/draftgo-theme.css`，加载顺序见 `resources/skill/references/frontend.md`。
 - DraftGo 基座内置 SVG 图标库，运行时路径为 `/assets/icons/{name}.svg`。
 - 图标文件统一使用 `kebab-case.svg` 命名；完整映射见 `/assets/icons/manifest.json`。
 - 页面或导航栏需要单色图标时，优先用 CSS mask + `currentColor`，可自动适配深浅主题。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.33",
+  "version": "3.0.35",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/SKILL.md

@@ -27,7 +27,7 @@ description: Use this skill when developing, maintaining, debugging, synchronizi
 | 本地资源缺失、过期或需要云端版本 | 使用 `pull/SKILL.md`，运行 `draftgo pull [type] [id...]`。 |
 | 新建资源 | 在对应 index 中登记不带 `id` 的完整条目并创建其引用文件；运行 `draftgo check` 后，通过 `draftgo push <type>` 创建并回读写回的 `id` 和文件路径。 |
 | 删除资源 | 确认目标 `id` 和引用后运行 `draftgo delete <type> <id>`；该命令同时删除云端资源和本地登记，随后重新运行 `map` 与 `check`。 |
-| 页面、导航、交互或布局 | 读取 `references/frontend.md`；页面运行和布局证据使用 `draftgo verify-ui <url> --mobile-check auto`。 |
+| 页面、导航、交互或布局 | 读取 `references/frontend.md` 的“前端底座与组件库清单”，确认壳层源码或数据库 HTML 页面及资源加载方式；页面运行和布局证据使用 `draftgo verify-ui <url> --mobile-check auto`。 |
 | 页面或导航 HTML | 运行 `draftgo check`，验证入口、HTML 解析和资源登记；语法异常读取 `references/debugging-syntax.md`。 |
 | 动态 DB、filters 或 order_by | 先读对应 `db_meta` schema 和 `references/data.md`。 |
 | DraftGo 底座 API | 运行 `draftgo api <keyword>`，确认请求字段、响应结构和鉴权。 |

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.33",
+  "version": "3.0.35",
   "entry": "SKILL.md",
   "description": "DraftGo 应用的开发、资源同步、验证与交付工作流。",
   "license": "MIT",
@@ -20,8 +20,15 @@
     "network:explicit"
   ],
   "resources": {
-    "references": ["references"],
+    "references": [
+      "references"
+    ],
     "scripts": "scripts",
-    "subskills": ["init", "pull", "push", "story"]
+    "subskills": [
+      "init",
+      "pull",
+      "push",
+      "story"
+    ]
   }
 }

package/resources/skill/references/frontend.md

@@ -30,7 +30,6 @@ version: 2.0.0
 ### 操作型页面布局（强制）
 
 后台管理、表格、列表等操作型页面用**工作台布局**，不用文档流堆叠：
-强烈建议直接使用antd的组件
 ```css
 .workbench-page { min-height:100vh; display:flex; flex-direction:column; overflow:hidden; }
 .workbench-toolbar { flex-shrink:0; }
@@ -42,11 +41,51 @@ version: 2.0.0
 - 分页/操作栏/保存栏固定在工作区底部，不随数据量上浮
 - 滚动发生在数据区，不是整页
 
+### 表格工作区布局
+
+所有数据表格页面，无论使用原生表格、AntD 或其他组件库，都遵守同一布局契约：
+
+- 页面根容器占满可用视口或 iframe 内容区，使用 `height: 100%`、`height: 100vh` 或已知导航高度的 `calc(...)`；不能由表格内容决定页面高度。
+- 表格内容区占据工具栏和底部控制区以外的所有剩余空间：`flex: 1; min-height: 0`。
+- 纵向和横向滚动只能发生在表格内容区。横向滚动条必须紧贴在分页或批量操作栏上方，不能落在长列表的末尾。
+- 分页、批量操作栏、保存栏等底部控制区使用 `flex-shrink: 0`，始终停在工作区底部；数据只有一行或没有数据时也不向上漂移。
+- 禁止使用 `min-height` 加自然文档流模拟该布局，也不要让 `body`、页面根和表格内容区同时滚动。
+
+通用骨架：
+
+```html
+<main class="table-workspace">
+  <header class="table-toolbar">...</header>
+  <section class="table-viewport">
+    <table>...</table>
+  </section>
+  <footer class="table-footer">...</footer>
+</main>
+```
+
+```css
+.table-workspace {
+  height: 100%;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.table-toolbar,
+.table-footer { flex-shrink: 0; }
+.table-viewport {
+  flex: 1;
+  min-height: 0;
+  overflow: auto; /* X scrollbar remains immediately above .table-footer */
+}
+.table-viewport > table { min-width: max-content; }
+```
+
 ### 表格数据区与分页钉底
 
 当页面主体是表格、日志列表、后台数据管理页时，必须先做固定高度的 flex column 容器，再放表格。不要让分页跟随表格内容高度往下跑，也不要让整页滚动。
 
-推荐骨架：
+参考骨架：
 
 ```css
 /* 整页表格页 */
@@ -87,7 +126,7 @@ version: 2.0.0
 }
 ```
 
-antd Table 推荐结构：
+AntD Table 示例结构：
 
 ```javascript
 h('div', { className: 'table-page' },
@@ -160,17 +199,6 @@ h(antd.Table, {
 })
 ```
 
-硬性验收：
-
-- 最外层容器高度明确：整页用 `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`、页面容器、表格容器三层都滚动；最多保留表格数据区滚动。
-
 ### 文本与图标换行控制（强制）
 
 按钮、标签、导航项、状态徽章等**小范围整体区域**内的文本和图标，**禁止自动换行**：
@@ -360,6 +388,51 @@ antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"
 
 ---
 
+## 前端底座与组件库清单
+
+### 运行形态
+
+- **壳层前端**位于 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 版本混入页面。
+- 新建页面先确认是“壳层源码修改”还是“数据库 HTML 页面”。二者的组件、构建和资源加载方式不同，不能混用。
+
+### 内置组件库清单
+
+| 名称 | 版本 | 运行形态 | 本地资源 |
+|---|---:|---|---|
+| 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` |
+
+此清单不规定组件库选择或场景对应关系；根据页面需求自行决定是否使用其中任一库。
+
+### 主题适配与标准加载方式
+
+基座提供两个适配资源：`/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
+<!-- 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') -->
+```
+
+```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>
+```
+
 ## 本地静态资源清单
 
 | 路径 | 说明 |
@@ -370,6 +443,10 @@ antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"
 | `/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` | 图标库映射清单 |
@@ -416,11 +493,10 @@ AI 模型 / Provider 品牌图标可以使用 LobeHub 静态图标的 npmmirror
 
 ---
 
-## Ant Design 使用规范
+## Ant Design 运行契约
 
-Ant Design 5.29.3 已内置为 UMD 包（`window.antd`），可优先选择使用。
+Ant Design 5.29.3 已内置为 UMD 包（`window.antd`）。
 
-> `Segmented` 的默认样式视觉厚重、组件库感过强，禁止原样用于成品界面；优先根据语义改用 `Tabs`、`Radio.Group` 等更合适的控件，确需使用时必须通过 `ConfigProvider`、design token 或组件公开 API 调整为与页面一致的轻量样式。
 
 ### ① 依赖加载顺序（缺一不可，顺序不可乱）
 
@@ -434,7 +510,7 @@ Ant Design 5.29.3 已内置为 UMD 包（`window.antd`），可优先选择使
 
 > 资源版本固定为 5.29.3。只加载 `/assets/antd/reset.css` 和 UMD JS；组件样式由 UMD 运行时注入，禁止额外加载或引用 `/assets/antd/antd.min.css`，也禁止混用其他版本的 Ant Design CSS。
 
-### ② 强烈建议：跟随 DraftGo 系统主题
+### ② DraftGo 主题接入
 
 用 `antd.ConfigProvider` 包裹根组件，读取 `App.theme` 和 CSS 变量 `--dg-accent`，实现 dark/light 自动切换和主题色联动：
 
@@ -475,9 +551,9 @@ ReactDOM.createRoot(document.getElementById('root')).render(React.createElement(
 - 自建组件时，业务页才是状态样式的所有者；状态规则必须收敛到该组件的专有类或页面根容器内，不能影响其他组件或页面。
 - 改动前先确认所有权；同一状态属性不得同时由 token/API 和 CSS 覆盖定义。若必须接管第三方组件样式，先移除或禁用原有对应效果，再用有作用域的规则完整接管。
 
-### ④ 强烈建议：弹窗和 Toast 走 DraftGo 系统
+### ④ DraftGo 平台反馈 API 对照
 
-| antd 原生 | 改用 |
+| antd 原生 | 对应平台 API |
 |-----------|------|
 | `Modal.confirm(...)` | `await App.confirm(msg, title)` |
 | `Modal.info / warning(...)` | `App.showModal(msg, title)` |
@@ -512,7 +588,7 @@ h('div', { style: { textAlign: 'center' } },
 )
 ```
 
-### ✅ antd 页面：用 `antd.Empty`（首选）
+### antd 页面：`antd.Empty` 示例
 
 ```javascript
 const { Empty } = antd;
@@ -565,7 +641,7 @@ h('div', { style: { display:'flex', flexDirection:'column', alignItems:'center',
 
 ## GSAP 动效规范
 
-**做页面时，尽可能引入 GSAP 提升体验感**。GSAP 是 DraftGo 内置动效库，适合入场动画、滚动交互、状态切换、数字滚动等所有需要"动起来"的场景。
+GSAP 是 DraftGo 内置动效库。使用时遵守以下加载和清理约束。
 
 加载规则：
 - 核心 `gsap.min.js` 必须首先加载，其余插件按需选加