draftgo-cli 2.0.5 → 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_pull.py

@@ -48,7 +48,7 @@ ENDPOINTS = {
     "roles":           "/api/roles",
     "users":           "/api/users?page=1&page_size=500",
     "db_meta":         "/api/db-meta",
-    "aihub":           "/api/aihub",
+    "aihub":           "/api/aihub?page=1&page_size=500",
     "external_apis":   "/api/external-apis?page=1&page_size=500",
     "system_config":   "/api/system/config",
     "doc_categories":  "/api/docs/categories?flat=true",

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} 不存在，尝试创建")
@@ -294,36 +339,85 @@ def sync_nav(server, token, ids=None):
 
 
 def sync_aihub(server, token, ids=None):
-    items = _load_index("aihub/index.json")
+    all_items = _load_index("aihub/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         iid = it.get("id")
-        name = it.get("name", iid)
+        name = it.get("name", iid or "(new)")
         # 服务端 AIHubUpdate 接受的字段子集
         payload = {k: it.get(k) for k in (
             "type", "name", "data", "priority", "version",
             "tags", "describe", "permission", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{name}] aihub_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        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} 不存在，尝试创建")
+                iid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{name}] aihub_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not iid:
+            create_payload = {k: payload.get(k) for k in (
+                "type", "name", "data", "priority", "version",
+                "tags", "describe", "permission",
+            ) if payload.get(k) is not None}
+            ok, status, body = api_call("POST", server, token, "/api/aihub", create_payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{name}] 已创建 aihub_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("aihub/index.json", all_items)
 
 
 def sync_external_apis(server, token, ids=None):
-    items = _load_index("external_apis/index.json")
+    all_items = _load_index("external_apis/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         iid = it.get("id")
-        code = it.get("code", iid)
+        code = it.get("code", iid or "(new)")
         # 服务端 ExternalAPIUpdate 接受字段
         payload = {k: it.get(k) for k in (
             "name", "base_url", "method", "path", "headers",
             "auth_type", "auth_config", "timeout_ms", "permission",
             "param_schema", "tags", "description", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/external-apis/{iid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{code}] api_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        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} 不存在，尝试创建")
+                iid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{code}] api_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not iid:
+            create_payload = {k: it.get(k) for k in (
+                "code", "name", "base_url", "method", "path", "headers",
+                "auth_type", "auth_config", "timeout_ms", "permission",
+                "param_schema", "tags", "description",
+            ) if it.get(k) is not None}
+            ok, status, body = api_call("POST", server, token, "/api/external-apis", create_payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{code}] 已创建 api_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{code}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("external_apis/index.json", all_items)
 
 
 def sync_system_config(server, token, keys=None):
@@ -345,8 +439,16 @@ 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)
-        print(f"  {'OK' if ok else 'ERR'} [{ck}]{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not ok and status == 404:
+            print(f"  WARN [{ck}] system_config 不存在，尝试创建")
+            create_payload = {"config_key": ck, **payload}
+            ok, status, body = api_call("POST", server, token, "/api/system/", create_payload)
+            print(f"  {'OK' if ok else 'ERR'} [{ck}] 已创建{'' if ok else ' -> ' + _info(ok, status, body)}")
+        else:
+            print(f"  {'OK' if ok else 'ERR'} [{ck}]{'' if ok else ' -> ' + _info(ok, status, body)}")
 
 
 def sync_roles(server, token, ids=None):
@@ -360,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)}")
 
@@ -376,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)}")
 
@@ -404,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} 不存在，尝试创建")
@@ -428,18 +536,38 @@ def sync_docs(server, token, ids=None):
 
 
 def sync_doc_categories(server, token, ids=None):
-    items = _load_index("doc_categories/index.json")
+    all_items = _load_index("doc_categories/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         cid = it.get("id")
-        name = it.get("name", cid)
+        name = it.get("name", cid or "(new)")
         # CategoryUpdate 字段
         payload = {k: it.get(k) for k in (
             "name", "slug", "description", "icon", "parent_id", "sort_order", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{name}] category_id={cid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        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} 不存在，尝试创建")
+                cid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{name}] category_id={cid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not cid:
+            ok, status, body = api_call("POST", server, token, "/api/docs/categories", payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{name}] 已创建 category_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("doc_categories/index.json", all_items)
 
 
 def _normalize_script_triggers(mode, triggers):
@@ -472,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",
@@ -597,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` | 全局挂件层 |
+
+规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**