draftgo-cli 2.0.9 → 3.0.0

package/resources/skill/scripts/draftgo_delete.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+DraftGo Delete Script
+删除云端资源，并同步移除本地 index.json 条目和文件。
+
+用法：
+  python draftgo_delete.py pages           <id>
+  python draftgo_delete.py nav             <id>
+  python draftgo_delete.py db_meta         <id>
+  python draftgo_delete.py custom_scripts  <id>
+  python draftgo_delete.py docs            <id>
+  python draftgo_delete.py doc_categories  <id>
+  python draftgo_delete.py external_apis   <id>
+  python draftgo_delete.py aihub           <id>
+"""
+import json, sys
+from pathlib import Path
+import urllib.request, urllib.error
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+
+def find_project_root(start: Path) -> Path:
+    cur = start
+    for _ in range(10):
+        if (cur / ".draftgo").is_dir():
+            return cur
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    cwd = Path.cwd()
+    if (cwd / ".draftgo").is_dir():
+        return cwd
+    return start.parents[3] if len(start.parents) >= 4 else start
+
+
+DEFAULT_ROOT = find_project_root(SCRIPT_DIR)
+
+
+def load_config():
+    cfg_path = DEFAULT_ROOT / ".draftgo/config.json"
+    if not cfg_path.exists():
+        print("ERR: .draftgo/config.json not found, run /draftgo init first", file=sys.stderr)
+        sys.exit(1)
+    cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+    return cfg["server"].rstrip("/"), cfg["token"]
+
+
+def api_delete(server, token, path):
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+    }
+    req = urllib.request.Request(
+        f"{server}{path}",
+        method="DELETE",
+        headers=headers,
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as r:
+            return True, r.status, r.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        return False, e.code, e.read().decode(errors="replace")
+    except Exception as e:
+        return False, None, str(e)
+
+
+def _load_index(rel_index):
+    new_path = DEFAULT_ROOT / ".draftgo" / rel_index
+    legacy_path = DEFAULT_ROOT / rel_index
+    path = new_path if new_path.exists() else legacy_path
+    if not path.exists():
+        print(f"ERR: {rel_index} not found", file=sys.stderr)
+        sys.exit(1)
+    return path, json.loads(path.read_text(encoding="utf-8"))
+
+
+def _remove_local_file(rel_path):
+    if not rel_path:
+        return
+    full = DEFAULT_ROOT / rel_path
+    if full.exists():
+        full.unlink()
+        print(f"  deleted local file: {rel_path}")
+
+
+# type → (api_prefix, index_rel, id_field, file_field)
+TYPE_MAP = {
+    "pages":          ("/api/pages",           "pages/index.json",                   "id", "html_file"),
+    "nav":            ("/api/navigations",      "navigations/index.json",             "id", "html_file"),
+    "db_meta":        ("/api/db-meta",          "db_meta/index.json",                 "id", None),
+    "custom_scripts": ("/api/scripts",          "custom_scripts/index.json",          "id", "code_file"),
+    "docs":           ("/api/docs/articles",    "docs/articles/index.json",           "id", "content_file"),
+    "doc_categories": ("/api/docs/categories",  "doc_categories/index.json",          "id", None),
+    "external_apis":  ("/api/external-apis",    "external_apis/index.json",           "id", None),
+    "aihub":          ("/api/aihub",            "aihub/index.json",                   "id", None),
+}
+
+
+def delete_resource(type_name, resource_id):
+    if type_name not in TYPE_MAP:
+        print(f"ERR: unknown type '{type_name}'. Supported: {', '.join(TYPE_MAP)}", file=sys.stderr)
+        sys.exit(1)
+
+    api_prefix, index_rel, id_field, file_field = TYPE_MAP[type_name]
+    server, token = load_config()
+
+    # 1. 找到 index 条目
+    index_path, items = _load_index(index_rel)
+    item = next((it for it in items if str(it.get(id_field)) == str(resource_id)), None)
+    label = (
+        item.get("title") or item.get("name") or item.get("type") or item.get("slug") or resource_id
+        if item else resource_id
+    )
+
+    # 2. 调用 DELETE API
+    ok, status, body = api_delete(server, token, f"{api_prefix}/{resource_id}")
+    if not ok and status != 404:
+        print(f"  ERR [{label}] 删除失败: HTTP {status}: {body}")
+        sys.exit(1)
+
+    if status == 404:
+        print(f"  WARN [{label}] 云端不存在（id={resource_id}），仅清理本地")
+    else:
+        print(f"  OK [{label}] 已从云端删除（id={resource_id}）")
+
+    # 3. 删除本地文件
+    if item and file_field:
+        _remove_local_file(item.get(file_field))
+
+    # 4. 从 index 移除条目
+    new_items = [it for it in items if str(it.get(id_field)) != str(resource_id)]
+    if len(new_items) < len(items):
+        index_path.write_text(json.dumps(new_items, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(f"  OK [{label}] 已从本地 index 移除")
+    else:
+        print(f"  WARN [{label}] 本地 index 中未找到 id={resource_id}")
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(f"usage: draftgo_delete.py <{'|'.join(TYPE_MAP)}> <id>", file=sys.stderr)
+        sys.exit(1)
+
+    type_name = sys.argv[1]
+    resource_id = sys.argv[2]
+    delete_resource(type_name, resource_id)
+
+
+if __name__ == "__main__":
+    main()

package/resources/skill/scripts/draftgo_push.py

@@ -43,6 +43,45 @@ def find_project_root(start: Path) -> Path:
 
 DEFAULT_ROOT = find_project_root(SCRIPT_DIR)
 
+# ── 冲突检测 ──
+FORCE = False
+
+
+def fetch_get(server, token, path):
+    """GET 请求，返回解析后的 JSON 或 None。"""
+    ok, _status, body = api_call("GET", server, token, path)
+    if not ok:
+        return None
+    try:
+        return json.loads(body)
+    except Exception:
+        return None
+
+
+def check_conflict(server, token, path, local_updated_at, label):
+    """检查云端 updated_at 是否与本地基线一致。返回 True 表示可以继续推送。"""
+    if FORCE:
+        return True
+    if not local_updated_at:
+        return True
+    raw = fetch_get(server, token, path)
+    if raw is None:
+        print(f"  WARN [{label}] 无法获取云端状态，跳过冲突检测")
+        return True
+    data = raw.get("data") if isinstance(raw, dict) else None
+    if not isinstance(data, dict):
+        return True
+    remote_updated = data.get("updated_at")
+    if not remote_updated:
+        return True
+    if str(remote_updated) != str(local_updated_at):
+        print(f"  SKIP [{label}] 云端已被他人修改")
+        print(f"       本地基线: {local_updated_at}")
+        print(f"       云端时间: {remote_updated}")
+        print(f"       请先 pull 同步后再 push，或使用 --force 强制覆盖")
+        return False
+    return True
+
 
 def load_config():
     cfg_path = DEFAULT_ROOT / ".draftgo/config.json"
@@ -182,6 +221,8 @@ def sync_pages(server, token, ids=None):
             "value": {"html": html},
         }
         if pid:
+            if not check_conflict(server, token, f"/api/pages/{pid}", page.get("updated_at"), title):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/pages/{pid}", payload)
             # PUT 404：本地 id 与云端不一致（删了重建 / 跨环境），按 route 自动创建
             if not ok and status == 404:
@@ -225,6 +266,8 @@ def sync_db_meta(server, token, ids=None):
             "extra": meta.get("extra"),
         }
         if mid:
+            if not check_conflict(server, token, f"/api/db-meta/{mid}", meta.get("updated_at"), label):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/db-meta/{mid}", payload)
             # 本地 index 的 id 与云端不一致（删了重建 / 跨环境同步）时 PUT 404，按 type 创建
             if not ok and status == 404:
@@ -261,6 +304,8 @@ def sync_nav(server, token, ids=None):
             continue
         html = html_file.read_text(encoding="utf-8")
         if nid:
+            if not check_conflict(server, token, f"/api/navigations/{nid}", nav.get("updated_at"), name):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/navigations/{nid}", {"html": html})
             if not ok and status == 404:
                 print(f"  WARN [{name}] nav_id={nid} 不存在，尝试创建")
@@ -308,6 +353,8 @@ def sync_aihub(server, token, ids=None):
             "tags", "describe", "permission", "status",
         ) if it.get(k) is not None}
         if iid:
+            if not check_conflict(server, token, f"/api/aihub/{iid}", it.get("updated_at"), name):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload)
             if not ok and status == 404:
                 print(f"  WARN [{name}] aihub_id={iid} 不存在，尝试创建")
@@ -347,6 +394,8 @@ def sync_external_apis(server, token, ids=None):
             "param_schema", "tags", "description", "status",
         ) if it.get(k) is not None}
         if iid:
+            if not check_conflict(server, token, f"/api/external-apis/{iid}", it.get("updated_at"), code):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/external-apis/{iid}", payload)
             if not ok and status == 404:
                 print(f"  WARN [{code}] api_id={iid} 不存在，尝试创建")
@@ -390,6 +439,8 @@ def sync_system_config(server, token, keys=None):
             "status": it.get("status"),
         }
         payload = {k: v for k, v in payload.items() if v is not None}
+        if not check_conflict(server, token, f"/api/system/{ck}", it.get("updated_at"), ck):
+            continue
         ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", payload)
         if not ok and status == 404:
             print(f"  WARN [{ck}] system_config 不存在，尝试创建")
@@ -411,6 +462,8 @@ def sync_roles(server, token, ids=None):
         payload = {k: it.get(k) for k in (
             "name", "description", "status", "sort_order", "user_visible",
         ) if it.get(k) is not None}
+        if not check_conflict(server, token, f"/api/roles/{rid}", it.get("updated_at"), code):
+            continue
         ok, status, body = api_call("PUT", server, token, f"/api/roles/{rid}", payload)
         print(f"  {'OK' if ok else 'ERR'} [{code}] role_id={rid}{'' if ok else ' -> ' + _info(ok, status, body)}")
 
@@ -427,6 +480,8 @@ def sync_users(server, token, ids=None):
             "username", "email", "phone_number", "nickname",
             "avatar", "status", "notes",
         ) if it.get(k) is not None}
+        if not check_conflict(server, token, f"/api/users/{uid}", it.get("updated_at"), uname):
+            continue
         ok, status, body = api_call("PUT", server, token, f"/api/users/{uid}", payload)
         print(f"  {'OK' if ok else 'ERR'} [{uname}] user_id={uid}{'' if ok else ' -> ' + _info(ok, status, body)}")
 
@@ -455,6 +510,8 @@ def sync_docs(server, token, ids=None):
         ) if it.get(k) is not None}
         payload["content"] = content
         if aid:
+            if not check_conflict(server, token, f"/api/docs/articles/{aid}", it.get("updated_at"), title):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/docs/articles/{aid}", payload)
             if not ok and status == 404:
                 print(f"  WARN [{title}] article_id={aid} 不存在，尝试创建")
@@ -492,6 +549,8 @@ def sync_doc_categories(server, token, ids=None):
             "name", "slug", "description", "icon", "parent_id", "sort_order", "status",
         ) if it.get(k) is not None}
         if cid:
+            if not check_conflict(server, token, f"/api/docs/categories/{cid}", it.get("updated_at"), name):
+                continue
             ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload)
             if not ok and status == 404:
                 print(f"  WARN [{name}] category_id={cid} 不存在，尝试创建")
@@ -541,6 +600,8 @@ def sync_custom_scripts(server, token, ids=None):
         code = code_path.read_text(encoding="utf-8")
         normalized_triggers = _normalize_script_triggers(it.get("mode"), it.get("triggers"))
         if sid:
+            if not check_conflict(server, token, f"/api/scripts/{sid}", it.get("updated_at"), name):
+                continue
             # ScriptUpdate 接受字段（不含 slug/mode，避免误改启停/路由）
             payload = {k: it.get(k) for k in (
                 "name", "description", "config", "permission",
@@ -666,22 +727,35 @@ def run_batch(server, token, args):
 
 
 def main():
+    global FORCE
+
     if len(sys.argv) < 2:
         print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]\n"
-              f"       draftgo_push.py --batch <mode> <ids> [<mode> <ids> ...]")
+              f"       draftgo_push.py --batch <mode> <ids> [<mode> <ids> ...]\n"
+              f"       --force  跳过冲突检测，强制覆盖")
+        sys.exit(1)
+
+    # 解析 --force（可出现在任意位置）
+    args = [a for a in sys.argv[1:] if a != "--force"]
+    if len(args) < len(sys.argv) - 1:
+        FORCE = True
+        print("[force] 已跳过冲突检测，将强制覆盖云端数据")
+
+    if not args:
+        print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]")
         sys.exit(1)
 
-    if sys.argv[1] == "--batch":
+    if args[0] == "--batch":
         server, token, cfg = load_config()
-        run_batch(server, token, sys.argv[2:])
+        run_batch(server, token, args[1:])
         _lessons_reminder(cfg)
         return
 
-    if sys.argv[1] not in HANDLERS:
+    if args[0] not in HANDLERS:
         print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]")
         sys.exit(1)
-    mode = sys.argv[1]
-    ids = sys.argv[2:] or None
+    mode = args[0]
+    ids = args[1:] or None
     server, token, cfg = load_config()
     HANDLERS[mode](server, token, ids)
     _lessons_reminder(cfg)

package/resources/skill/specs/data.md

@@ -0,0 +1,108 @@
+---
+read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时
+---
+
+# 动态 DB & 数据层
+
+## DB Meta 结构
+
+```json
+{
+  "type": "order",
+  "label": "订单",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name":   { "type": "string",  "title": "姓名",   "required": true,  "searchable": "fuzzy" },
+      "status": { "type": "string",  "title": "状态",   "required": false, "searchable": "exact" },
+      "amount": { "type": "number",  "title": "金额",   "required": false, "searchable": "range" },
+      "tags":   { "type": "array",   "title": "标签",   "required": false, "searchable": "contains" },
+      "note":   { "type": "string",  "title": "备注",   "required": false, "searchable": false }
+    }
+  },
+  "permission": {
+    "public":  { "read": "none",  "create": "none",  "update": "none",  "delete": "none" },
+    "login":   { "read": "all",   "create": "all",   "update": "owner", "delete": "owner" },
+    "admin":   { "read": "all",   "create": "all",   "update": "all",   "delete": "all" }
+  }
+}
+```
+
+**searchable 模式**：`false`（不可检索）/ `"exact"`（精确）/ `"fuzzy"`（模糊）/ `"range"`（数值范围）/ `"contains"`（数组包含）
+
+---
+
+## CRUD 操作范式
+
+```javascript
+// 查询（分页 + 结构化检索）
+const res = await App.get(`db/order`, {
+  page: 1, page_size: 20,
+  filters: ['name:like:张', 'status:eq:paid', 'amount:gte:100'],
+  order_by: 'amount', order: 'desc',
+});
+const { items, total } = res.data;
+
+// 创建（业务字段必须放在 data 包裹里）
+await App.post(`db/order`, { data: { name: '张三', amount: 200 }, status: 1 });
+
+// 更新
+await App.put(`db/order/${id}`, { data: { amount: 250 } });
+
+// 删除
+await App.delete(`db/order/${id}`);
+
+// 批量更新（原子事务，任一失败全批回滚）
+await App.patch(`db/order/batch`, [
+  { id: 1, data: { status: 'paid' } },
+  { id: 2, data: { status: 'paid' } },
+]);
+```
+
+---
+
+## filters 操作符
+
+| 操作符 | 含义 | 适用 searchable 模式 |
+|---|---|---|
+| `eq` | 精确等于 | exact / fuzzy / range |
+| `like` | 模糊包含 | fuzzy |
+| `gte` / `lte` / `gt` / `lt` | 数值范围 | range |
+| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy |
+| `contains` | 数组字段包含某值 | contains |
+
+- 省略操作符（`filters: ['name:张三']`）默认 `like`
+- 多个 filters 为 AND
+- 字段未标 searchable 或操作符不匹配 → 后端返回 400
+
+---
+
+## db_meta 本地文件
+
+开发前先读 `.draftgo/db_meta/index.json` 了解可用 type 和字段：
+
+```json
+[
+  {
+    "id": 1,
+    "type": "order",
+    "label": "订单",
+    "schema": { ... }
+  }
+]
+```
+
+⚠️ **GET `/api/db-meta/{type}` 用 type（如 `order`），不是 id。PUT/DELETE 才用 id。**
+
+---
+
+## 通用筛选参数（非动态 DB）
+
+用于 users / roles / pages / navigations / feedback 等标准资源：
+
+| 参数 | 说明 |
+|---|---|
+| `page` / `page_size` | 分页（不传返回全量，超 10000 条后端拒绝） |
+| `search` | 全文搜索（动态 DB 不用此参数） |
+| `status` | 状态过滤 |
+| `type` / `tag` | 类型/标签过滤 |

package/resources/skill/specs/runtime.md

@@ -0,0 +1,98 @@
+---
+read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问题时
+---
+
+# 运行时机制（Runtime）
+
+## 壳层启动流程
+
+1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
+2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
+3. `loadSetupStatus()` — 检查系统是否已初始化
+4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
+
+---
+
+## iframe 注入机制
+
+壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
+
+- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数），冻结对象
+- `window.__DG_QUERY__` — `routeContext.query` 快捷方式
+- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
+- 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
+- 静态资源（Tailwind runtime、FontAwesome、GSAP 等）
+
+页面以 `iframe.srcdoc` 渲染，**不是独立 URL**，因此：
+- `window.location` 指向壳层地址，**不可用于读取路由参数**
+- `window.parent.App` 是壳层暴露的能力对象
+- `window.location.href = '/path'` 只跳 iframe 自身！导航必须用 `window.parent.location.href`
+
+---
+
+## App 对象来源
+
+壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
+
+`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
+
+完整 API 见 `{{SKILL_DIR}}/quickref/app-api.md`
+
+---
+
+## Token 存储
+
+| key | 说明 |
+|---|---|
+| `localStorage.dg_access_token` | 访问 token |
+| `localStorage.dg_refresh_token` | 刷新 token |
+
+登录后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。  
+401 时壳层自动用 refresh token 刷新，无需页面处理。
+
+---
+
+## URL 参数读取（标准三阶回落）
+
+```javascript
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__
+  || window.__DG_GET_ROUTE_CONTEXT__?.()
+  || window.parent?.App?.getCurrentRouteContext?.()
+  || { query: {} };
+const query = routeContext.query || {};
+
+// 路由 /orders?orderId=42
+const orderId = query.orderId;  // "42"
+```
+
+**禁止**：`new URLSearchParams(window.location.search)` / 直接读 `window.location.search`
+
+---
+
+## 全局事件
+
+| 事件名 | 触发时机 |
+|---|---|
+| `dg:auth-ready` | token 验证完成（成功或失败） |
+| `dg:auth-changed` | token 变更（登录/登出） |
+
+监听方式：`window.parent.addEventListener('dg:auth-ready', handler)`
+
+---
+
+## 前端全局层
+
+全局浮窗、客服入口、统计脚本等属于全局层，不属于单个业务页面。
+
+存储：`sys_config.category = frontend_global`
+
+| config_key | 用途 |
+|---|---|
+| `frontend_global_head_html` | 注入壳层 head |
+| `frontend_global_body_html` | 注入壳层 body 末尾 |
+| `frontend_global_css` / `_js` | 壳层全局 CSS/JS |
+| `frontend_global_iframe_head_html` | 注入每个业务页面 iframe head |
+| `frontend_global_widget_html/css/js` | 全局挂件层 |
+
+规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**

package/resources/skill/specs/security.md

@@ -0,0 +1,74 @@
+---
+read_when: 开发前检查合规性时 · Code Review 时
+---
+
+# 开发禁区（违反必报错）
+
+## 网络资源
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| 任何境外 CDN（googleapis / jsdelivr / cdnjs / unpkg） | 国内镜像（npmmirror.com / staticfile.net）或本地资源 |
+| 外部 CDN 引入图标 | `/assets/icons/{name}.svg` 内置图标库 |
+
+---
+
+## App 对象使用
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| `App()` 写法（App 是对象不是函数） | `const App = window.parent?.App` |
+| `const App = () => window.parent?.App` | 去掉箭头函数 |
+| `App?.user?.role` 判断权限 | `App.isAdmin` 或 `App.currentUser?.role_code` |
+
+---
+
+## 路由 & 导航
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| `window.location.search` 读参数 | `window.__DG_ROUTE_CONTEXT__.query` |
+| `navigate('/login')` 退出 | `window.parent.location.href = '/login'` |
+| 页面内 `window.location.href = ...` 跳转 | `window.parent.location.href = ...`（页面在 iframe 中） |
+
+---
+
+## 弹窗 & 交互
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| `window.alert(msg)` | `App.showModal(msg, title?)` |
+| `window.confirm(msg)` | `await App.confirm(msg, title?)` |
+| `window.prompt(msg)` | 自建 modal + input |
+
+---
+
+## UI 组件
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| 把 React/TSX 版 shadcn 组件写进数据库 HTML | 用对应 `dg-*` 标签 |
+| 把 `dg-*` 当 daisyUI / Bootstrap / Ant Design | `dg-*` 只能是 shadcn 的 HTML 协议形态 |
+| 硬编码 hex / rgb / rgba 颜色 | 用 `var(--dg-*)` 语义 token |
+| 在页面内读 `localStorage.dg_theme` | `App.theme` |
+
+---
+
+## 全局层
+
+| ❌ 禁止 | ✅ 替代 |
+|---|---|
+| 在业务页面内实现全局浮窗 / 客服 / 统计脚本 | 使用 `frontend_global_*` 固定槽位 |
+| 在页面内渲染系统 Header / Logo / 用户头像下拉 | 这些属于壳层，不属于业务页面 |
+| 新增全局层槽位 | 只能编辑系统内置固定槽位 |
+
+---
+
+## 颜色 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` | 功能色 |

package/resources/skill/specs/ui-protocol.md

@@ -0,0 +1,68 @@
+---
+read_when: 开发数据库页面时需要 dg-* 组件 · 了解 shadcn 映射关系时
+---
+
+# dg-* 完整映射表
+
+## 核心认知
+
+```
+dg-* ≠ 自研组件库
+dg-* = shadcn/ui 在数据库 HTML 页面里的协议化表达
+```
+
+数据库页面不进入 Vite/React 编译链，不能写 TSX；改用 `dg-*` 标签，runtime 解析并渲染对应 shadcn 语义。
+
+---
+
+## shadcn → dg-* 完整映射
+
+| shadcn 组件 | dg-* 标签 | 说明 |
+|---|---|---|
+| Button | `dg-button` | variant/size/disabled 属性对齐 |
+| Card | `dg-card` + `dg-card-header/title/description/content/footer` | |
+| Badge | `dg-badge` | variant: default/secondary/destructive/outline |
+| Skeleton | `dg-skeleton` | 骨架屏 |
+| Input | `dg-input` | type/placeholder/value/disabled |
+| Textarea | `dg-textarea` | |
+| Select | `dg-select` + `dg-select-item` | |
+| Checkbox | `dg-checkbox` | |
+| Switch | `dg-switch` | |
+| RadioGroup | `dg-radio-group` + `dg-radio-item` | |
+| Form | `dg-form` + `dg-form-item` + `dg-form-message` | |
+| Table | `dg-table` | source 属性拉取数据，columns via data-dg-props |
+| Tabs | `dg-tabs` + `dg-tabs-list/trigger/content` | default-value 属性 |
+| Dialog | `dg-dialog` + `dg-dialog-trigger/content/header/title/footer` | |
+| Sheet | `dg-sheet` + `dg-sheet-trigger/content/header/title` | side: right/left/top/bottom |
+| DropdownMenu | `dg-dropdown-menu` + `dg-dropdown-menu-trigger/content/item/separator` | |
+| Tooltip | `dg-tooltip` | content 属性 |
+| Popover | `dg-popover` + `dg-popover-trigger/content` | |
+| Alert | `dg-alert` + `dg-alert-title/description` | variant: default/destructive |
+| Progress | `dg-progress` | value/max 属性 |
+| Separator | `dg-separator` | orientation: horizontal/vertical |
+| ScrollArea | `dg-scroll-area` | |
+| Avatar | `dg-avatar` + `dg-avatar-image/fallback` | |
+
+---
+
+## 属性约定
+
+`dg-*` 属性命名跟随 shadcn 语义：
+- `variant`、`size`、`disabled`、`default-value`、`data-state`、`aria-*` 保持原意
+- 复杂组件使用 `data-dg-props='{"key":"value"}'` 传递结构化配置
+
+---
+
+## 禁止混淆
+
+- ❌ `dg-*` 不是 daisyUI
+- ❌ `dg-*` 不是 Bootstrap
+- ❌ `dg-*` 不是 Ant Design / Element Plus
+- ❌ `dg-*` 不是任意相似样式的泛称
+- ✅ `dg-*` 只能是 shadcn 的 DraftGo HTML 协议形态
+
+---
+
+## 使用示例速查
+
+完整带代码的示例见 `{{SKILL_DIR}}/quickref/dg-components.md`