draftgo-cli 3.0.35 → 3.0.39

package/resources/skill/scripts/draftgo_push.py

@@ -1,1022 +0,0 @@
-#!/usr/bin/env python3
-"""
-DraftGo Push Script
-推送本地修改到云端。覆盖所有 init 拉取的类型：
-  pages / nav / db_meta / aihub / system_config / roles / users
-  docs / doc_categories / custom_scripts
-
-用法：
-  python draftgo_push.py pages           [page_id ...]
-  python draftgo_push.py nav             [nav_id ...]
-  python draftgo_push.py db_meta         [db_meta_id ...]
-  python draftgo_push.py aihub           [aihub_id ...]
-  python draftgo_push.py system_config   [config_key ...]
-  python draftgo_push.py docs            [article_id ...]
-  python draftgo_push.py doc_categories  [category_id ...]
-  python draftgo_push.py custom_scripts  [script_id ...]
-  python draftgo_push.py roles           [role_id ...]
-  python draftgo_push.py users           [user_id ...]
-"""
-import json, sys, re, datetime
-from pathlib import Path
-import urllib.request, urllib.error
-
-SCRIPT_DIR = Path(__file__).resolve().parent
-PROBE_ROUTES = False
-DRY_RUN = False
-RUN_FAILURES = 0
-
-
-def find_project_root(start: Path) -> Path:
-    """向上查找包含 `.draftgo/` 的目录作为项目根。"""
-    cur = start
-    for _ in range(10):
-        if (cur / ".draftgo").is_dir():
-            return cur
-        if cur.parent == cur:
-            break
-        cur = cur.parent
-    # CWD 回退：脚本可能在中文路径下被调用，SCRIPT_DIR 解析失败时用 CWD
-    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"], cfg
-
-
-def _lessons_reminder(cfg):
-    if DRY_RUN:
-        return
-    if not cfg.get("lessons_on_push", False):
-        return
-    print("")
-    print("[Lessons 回顾] Push 完成。回顾本次是否需要写入 .draftgo/lessons/：")
-    print("  - 踩了文档没写的坑")
-    print("  - 尝试了 ≥2 次才找到正确方案")
-    print("  - 发现了违反直觉的行为或约束")
-    print("  - 产出了通用性强的设计模式")
-    print("  未命中则跳过。")
-
-
-def api_call(method, server, token, path, body=None, acceptable_errors=()):
-    """发起 API 调用，并记录调用方不会恢复的失败。"""
-    global RUN_FAILURES
-    data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "User-Agent": (
-            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
-            "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
-        ),
-        "Accept": "application/json",
-    }
-    if data is not None:
-        headers["Content-Type"] = "application/json"
-    req = urllib.request.Request(
-        f"{server}{path}",
-        data=data,
-        method=method,
-        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:
-        body_text = e.read().decode(errors="replace")
-        if e.code not in acceptable_errors:
-            RUN_FAILURES += 1
-        return False, e.code, body_text
-    except Exception as e:
-        RUN_FAILURES += 1
-        return False, None, str(e)
-
-
-def _info(ok, status, body):
-    """把 api_call 三元组压成简短描述，兼容旧打印格式。"""
-    if ok:
-        return status
-    if status is None:
-        return body or "error"
-    return f"HTTP {status}: {body}"
-
-
-def _extract_created_id(body_text):
-    """从 POST 成功响应中提取新建资源的 id。
-    信封格式: {code, data: {id:...}} 或 {code, data: [{id:...}]}
-    """
-    try:
-        resp = json.loads(body_text)
-        data = resp.get("data") if isinstance(resp, dict) else None
-        if isinstance(data, list):
-            data = data[0] if data else None
-        if isinstance(data, dict):
-            return data.get("id")
-    except Exception:
-        pass
-    return None
-
-
-def _writeback_index(rel_index, items):
-    """将更新后的 index 列表写回 .draftgo/ 下的 index.json。"""
-    path = DEFAULT_ROOT / ".draftgo" / rel_index
-    if not path.exists() and not (DEFAULT_ROOT / ".draftgo").exists():
-        path = DEFAULT_ROOT / rel_index
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(items, ensure_ascii=False, indent=2), encoding="utf-8")
-
-
-def _safe_slug(s):
-    """与 pull 脚本一致的文件名 slug 规则。"""
-    return str(s).strip("/").replace("/", "_") or "root"
-
-
-def _rename_to_canonical(sub_dir, old_rel, prefix, new_id, slug_src, ext):
-    """新建成功后把本地文件重命名为 pull 约定的 {prefix}_{id}_{slug}.{ext}，
-    与 /draftgo pull 落地命名保持一致。返回新的相对路径（.draftgo/...）；
-    任何异常都回退为原相对路径，不阻断推送。"""
-    new_name = f"{prefix}_{new_id}_{_safe_slug(slug_src)}.{ext}"
-    new_rel = f".draftgo/{sub_dir}/{new_name}"
-    try:
-        old_path = DEFAULT_ROOT / old_rel
-        new_path = DEFAULT_ROOT / new_rel
-        if old_path.exists() and old_path.resolve() != new_path.resolve():
-            old_path.rename(new_path)
-        return new_rel
-    except Exception:
-        return old_rel
-
-
-def _load_index(rel_index, allow_missing=False):
-    """读取 .draftgo/ 下的 index.json；支持旧 (pages/index.json) 与新 (.draftgo/pages/index.json) 两种布局。"""
-    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():
-        if allow_missing:
-            print(f"  WARN {rel_index} 不存在，将尝试从云端恢复指定目标的索引")
-            return []
-        print(f"ERR: {rel_index} not found under .draftgo/, run /draftgo init first", file=sys.stderr)
-        sys.exit(1)
-    return json.loads(path.read_text(encoding="utf-8"))
-
-
-def _filter_items_by_ids(items, ids, id_key, type_name, orphan=None):
-    """按用户指定 id 过滤；指定 id 不存在时直接失败，避免 0 目标假成功。"""
-    if not ids:
-        return items
-    wanted = [str(x) for x in ids]
-    found = {str(it.get(id_key)) for it in items if it.get(id_key) is not None}
-    missing = [x for x in wanted if x not in found]
-    if missing:
-        print(f"ERR: {type_name} index.json 未登记目标 {id_key}: {', '.join(missing)}", file=sys.stderr)
-        if orphan:
-            hints = orphan(missing)
-            if hints:
-                print("     发现疑似未入索引的本地文件：", file=sys.stderr)
-                for hint in hints[:8]:
-                    print(f"     - {hint}", file=sys.stderr)
-        print("     请先恢复/追加对应 index 元数据，或重新运行 pull 后再 push。", file=sys.stderr)
-        sys.exit(1)
-    return [it for it in items if str(it.get(id_key)) in wanted]
-
-
-def _response_items(body):
-    """解析列表接口的常见统一信封格式。"""
-    try:
-        raw = json.loads(body)
-    except Exception:
-        return []
-    if isinstance(raw, dict) and "data" in raw:
-        raw = raw["data"]
-    if isinstance(raw, list):
-        return raw
-    if isinstance(raw, dict):
-        for key in ("items", "results", "data"):
-            if isinstance(raw.get(key), list):
-                return raw[key]
-        return [raw]
-    return []
-
-
-def _response_item(body):
-    """解析单资源响应的统一信封。"""
-    try:
-        raw = json.loads(body)
-    except Exception:
-        return None
-    if isinstance(raw, dict) and "data" in raw:
-        raw = raw["data"]
-    return raw if isinstance(raw, dict) else None
-
-
-def _cloud_version_allows_push(server, token, path, local_item, label):
-    """云端优先：本地 pull 基线落后于云端时禁止静默覆盖。
-
-    没有历史 updated_at 的旧缓存保持兼容；404 由调用方按默认重建策略处理。
-    """
-    global RUN_FAILURES
-    baseline = local_item.get("updated_at")
-    if not baseline:
-        return True
-    ok, status, body = api_call("GET", server, token, path, acceptable_errors=(404,))
-    if not ok and status == 404:
-        return True
-    if not ok:
-        return False
-    remote = _response_item(body)
-    remote_updated = remote.get("updated_at") if remote else None
-    if remote_updated and str(remote_updated) != str(baseline):
-        RUN_FAILURES += 1
-        conflict_dir = DEFAULT_ROOT / ".draftgo" / "sync-conflicts"
-        conflict_dir.mkdir(parents=True, exist_ok=True)
-        identity = str(local_item.get("id") or label).replace("/", "_").replace("\\", "_")
-        stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-        conflict_path = conflict_dir / f"{identity}-{stamp}.json"
-        conflict_path.write_text(json.dumps({
-            "kind": "remote-newer",
-            "resource_path": path,
-            "baseline_updated_at": baseline,
-            "remote_updated_at": remote_updated,
-            "local": local_item,
-            "remote": remote,
-        }, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
-        print(
-            f"  ERR [{label}] 云端版本已变化（local={baseline}, remote={remote_updated}）；"
-            f"云端优先，已保存冲突快照：{conflict_path.relative_to(DEFAULT_ROOT)}。",
-            file=sys.stderr,
-        )
-        return False
-    return True
-
-
-def _recover_missing_index_entries(
-    server, token, items, ids, id_key, type_name, rel_index, endpoint,
-    file_spec=None, drop_fields=(),
-):
-    """补齐缺失的 index 条目，且绝不覆盖本地受管内容。
-
-    只有显式指定的目标才可恢复，防止 `push --all` 把不明文件自动纳管。
-    file_spec 为 (目录, index 文件字段, 文件名前缀, 扩展名列表)。
-    """
-    if not ids:
-        return items
-    wanted = [str(value) for value in ids]
-    registered = {str(item.get(id_key)) for item in items if item.get(id_key) is not None}
-    missing = [value for value in wanted if value not in registered]
-    if not missing:
-        return items
-    if DRY_RUN:
-        print(
-            f"ERR: {type_name} index.json 未登记目标 {id_key}: {', '.join(missing)}。"
-            "dry-run 不会回读云端或修改本地索引。",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    ok, status, body = api_call("GET", server, token, endpoint)
-    if not ok:
-        print(
-            f"ERR: 无法恢复 {type_name} index.json：云端回读失败 -> {_info(ok, status, body)}",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-    remote_by_id = {
-        str(item.get(id_key)): item
-        for item in _response_items(body)
-        if isinstance(item, dict) and item.get(id_key) is not None
-    }
-    absent = [value for value in missing if value not in remote_by_id]
-    if absent:
-        print(
-            f"ERR: {type_name} 云端不存在目标 {id_key}: {', '.join(absent)}。"
-            "本地资源可能已成为孤儿文件，请确认后删除本地文件及其引用，"
-            "或改为新建资源推送。",
-            file=sys.stderr,
-        )
-        if file_spec:
-            rel_dir, _, prefix, exts = file_spec
-            hints = _orphan_hints(rel_dir, prefix, absent, exts)
-            for hint in hints:
-                print(f"     建议删除：{hint}", file=sys.stderr)
-        sys.exit(1)
-
-    recovered = []
-    for value in missing:
-        meta = dict(remote_by_id[value])
-        if file_spec:
-            rel_dir, file_field, prefix, exts = file_spec
-            candidates = _orphan_hints(rel_dir, prefix, [value], exts)
-            if len(candidates) != 1:
-                detail = "未找到" if not candidates else f"找到 {len(candidates)} 个"
-                print(
-                    f"ERR: {type_name} {id_key}={value} 云端存在，但本地孤儿文件{detail}，"
-                    "无法安全补齐索引。请恢复唯一的本地文件或运行 pull 后重试。",
-                    file=sys.stderr,
-                )
-                sys.exit(1)
-            meta[file_field] = candidates[0]
-        for field in drop_fields:
-            meta.pop(field, None)
-        items.append(meta)
-        recovered.append(value)
-
-    _writeback_index(rel_index, items)
-    print(f"  OK {type_name}: 已从云端补齐 index.json 目标 {', '.join(recovered)}，继续推送本地内容")
-    return items
-
-
-def _orphan_hints(rel_dir, prefix, missing_ids, exts):
-    base = DEFAULT_ROOT / ".draftgo" / rel_dir
-    if not base.exists():
-        return []
-    hints = []
-    for mid in missing_ids:
-        for ext in exts:
-            for p in base.glob(f"{prefix}_{mid}_*{ext}"):
-                hints.append(f".draftgo/{rel_dir}/{p.name}")
-    return hints
-
-
-def _warn_orphan_files(rel_dir, items, file_field, prefix, exts, type_name):
-    base = DEFAULT_ROOT / ".draftgo" / rel_dir
-    if not base.exists():
-        return
-    indexed = {str(it.get(file_field, "")).replace("\\", "/") for it in items}
-    orphans = []
-    for p in base.iterdir():
-        if not p.is_file():
-            continue
-        if not p.name.startswith(f"{prefix}_") or p.suffix not in exts:
-            continue
-        rel = f".draftgo/{rel_dir}/{p.name}"
-        if rel not in indexed:
-            orphans.append(rel)
-    if orphans:
-        print(f"  WARN {type_name}: 发现 {len(orphans)} 个未登记到 index.json 的本地文件，本次不会推送：")
-        for rel in orphans[:8]:
-            print(f"       - {rel}")
-
-
-def _summary(type_name, targets):
-    print(f"  SUMMARY {type_name}: targets={targets}")
-
-
-def _preview(type_name, items, id_key="id"):
-    """打印不会产生云端或本地副作用的推送预览。"""
-    if not DRY_RUN:
-        return False
-    for item in items:
-        identity = item.get(id_key)
-        label = item.get("title") or item.get("name") or item.get("code") or identity or "(new)"
-        action = "UPDATE" if identity else "CREATE"
-        print(f"  DRY-RUN {action} [{label}]")
-    _summary(type_name, len(items))
-    return True
-
-
-def sync_pages(server, token, ids=None):
-    all_pages = _load_index("pages/index.json", allow_missing=bool(ids))
-    all_pages = _recover_missing_index_entries(
-        server, token, all_pages, ids, "id", "pages", "pages/index.json", "/api/pages/",
-        file_spec=("pages", "html_file", "page", [".html"]), drop_fields=("value",),
-    )
-    _warn_orphan_files("pages", all_pages, "html_file", "page", [".html"], "pages")
-    pages = _filter_items_by_ids(
-        all_pages, ids, "id", "pages",
-        orphan=lambda missing: _orphan_hints("pages", "page", missing, [".html"]),
-    )
-    if _preview("pages", pages):
-        return
-    dirty = False
-    for page in pages:
-        pid = page.get("id")
-        title = page.get("title", pid or "(new)")
-        html_file = DEFAULT_ROOT / page.get("html_file", "")
-        if not html_file.exists():
-            print(f"  SKIP [{title}] html_file not found: {page.get('html_file')}")
-            continue
-        html = html_file.read_text(encoding="utf-8")
-        _lint_page_html(html, title)
-        payload = {
-            "title": page.get("title", ""),
-            "route": page.get("route", ""),
-            "tag": page.get("tag"),
-            "menu": page.get("menu"),
-            "status": page.get("status", "active"),
-            "permission": page.get("permission", {}),
-            "value": {"html": html},
-        }
-        if pid:
-            if not _cloud_version_allows_push(server, token, f"/api/pages/{pid}", page, title):
-                continue
-            ok, status, body = api_call("PUT", server, token, f"/api/pages/{pid}", payload, acceptable_errors=(404,))
-            # PUT 404：本地 id 与云端不一致（删了重建 / 跨环境），按 route 自动创建
-            if not ok and status == 404:
-                print(f"  WARN [{title}] page_id={pid} 不存在，尝试创建")
-                pid = None
-            else:
-                print(f"  {'OK' if ok else 'ERR'} [{title}] page_id={pid}{'' if ok else ' -> ' + _info(ok, status, body)}")
-        if not pid:
-            ok, status, body = api_call("POST", server, token, "/api/pages/", payload)
-            new_id = _extract_created_id(body) if ok else None
-            if ok and new_id:
-                page["id"] = new_id
-                new_rel = _rename_to_canonical(
-                    "pages", page.get("html_file", ""), "page", new_id,
-                    page.get("route", new_id), "html")
-                page["html_file"] = new_rel
-                dirty = True
-                print(f"  OK [{title}] 已创建 page_id={new_id}（已回写 index）")
-            else:
-                print(f"  ERR [{title}] 创建失败 -> {_info(ok, status, body)}")
-    if dirty:
-        _writeback_index("pages/index.json", all_pages)
-    _summary("pages", len(pages))
-
-
-def sync_db_meta(server, token, ids=None):
-    all_metas = _load_index("db_meta/index.json", allow_missing=bool(ids))
-    all_metas = _recover_missing_index_entries(
-        server, token, all_metas, ids, "id", "db_meta", "db_meta/index.json", "/api/db-meta",
-    )
-    metas = _filter_items_by_ids(all_metas, ids, "id", "db_meta")
-    if _preview("db_meta", metas):
-        return
-    dirty = False
-    for meta in metas:
-        mid = meta.get("id")
-        label = meta.get("label", meta.get("type", mid or "(new)"))
-        payload = {
-            "type": meta.get("type"),
-            "label": meta.get("label"),
-            "describe": meta.get("describe"),
-            "schema": meta.get("schema"),
-            "permission": meta.get("permission"),
-            "schema_validation": meta.get("schema_validation", 0),
-            "extra": meta.get("extra"),
-        }
-        if mid:
-            ok, status, body = api_call("PUT", server, token, f"/api/db-meta/{mid}", payload, acceptable_errors=(404,))
-            # 本地 index 的 id 与云端不一致（删了重建 / 跨环境同步）时 PUT 404，按 type 创建
-            if not ok and status == 404:
-                print(f"  WARN [{label}] db_meta_id={mid} 不存在，尝试按 type 创建")
-                mid = None
-            else:
-                print(f"  {'OK' if ok else 'ERR'} [{label}] db_meta_id={mid}{'' if ok else ' -> ' + _info(ok, status, body)}")
-        if not mid:
-            ok, status, body = api_call("POST", server, token, "/api/db-meta", payload)
-            new_id = _extract_created_id(body) if ok else None
-            if ok:
-                if new_id:
-                    meta["id"] = new_id
-                    dirty = True
-                print(f"  OK [{label}] 已创建 db_meta_id={new_id}{'（已回写 index）' if new_id else ''}")
-            else:
-                print(f"  ERR [{label}] 创建失败 -> {_info(ok, status, body)}")
-    if dirty:
-        _writeback_index("db_meta/index.json", all_metas)
-    _summary("db_meta", len(metas))
-
-
-def sync_nav(server, token, ids=None):
-    all_navs = _load_index("navigations/index.json", allow_missing=bool(ids))
-    all_navs = _recover_missing_index_entries(
-        server, token, all_navs, ids, "id", "nav", "navigations/index.json", "/api/navigations",
-        file_spec=("navigations", "html_file", "nav", [".html"]), drop_fields=("html",),
-    )
-    _warn_orphan_files("navigations", all_navs, "html_file", "nav", [".html"], "nav")
-    navs = _filter_items_by_ids(
-        all_navs, ids, "id", "nav",
-        orphan=lambda missing: _orphan_hints("navigations", "nav", missing, [".html"]),
-    )
-    if _preview("nav", navs):
-        return
-    dirty = False
-    for nav in navs:
-        nid = nav.get("id")
-        name = nav.get("name", nid or "(new)")
-        html_file = DEFAULT_ROOT / nav.get("html_file", "")
-        if not html_file.exists():
-            print(f"  SKIP [{name}] html_file not found: {nav.get('html_file')}")
-            continue
-        html = html_file.read_text(encoding="utf-8")
-        if nid:
-            ok, status, body = api_call("PUT", server, token, f"/api/navigations/{nid}", {"html": html}, acceptable_errors=(404,))
-            if not ok and status == 404:
-                print(f"  WARN [{name}] nav_id={nid} 不存在，尝试创建")
-                nid = None
-            else:
-                print(f"  {'OK' if ok else 'ERR'} [{name}] nav_id={nid}{'' if ok else ' -> ' + _info(ok, status, body)}")
-        if not nid:
-            # 创建需要完整字段（name/code 必填），PUT 不发的字段在此补齐
-            payload = {
-                "name": nav.get("name", ""),
-                "code": nav.get("code", ""),
-                "html": html,
-                "tag": nav.get("tag"),
-                "order": nav.get("order", 0),
-                "status": nav.get("status", "active"),
-            }
-            ok, status, body = api_call("POST", server, token, "/api/navigations", payload)
-            new_id = _extract_created_id(body) if ok else None
-            if ok and new_id:
-                nav["id"] = new_id
-                new_rel = _rename_to_canonical(
-                    "navigations", nav.get("html_file", ""), "nav", new_id,
-                    nav.get("code") or nav.get("name") or new_id, "html")
-                nav["html_file"] = new_rel
-                dirty = True
-                print(f"  OK [{name}] 已创建 nav_id={new_id}（已回写 index）")
-            else:
-                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
-    if dirty:
-        _writeback_index("navigations/index.json", all_navs)
-    _summary("nav", len(navs))
-
-
-def sync_aihub(server, token, ids=None):
-    all_items = _load_index("aihub/index.json", allow_missing=bool(ids))
-    all_items = _recover_missing_index_entries(
-        server, token, all_items, ids, "id", "aihub", "aihub/index.json", "/api/aihub",
-    )
-    items = _filter_items_by_ids(all_items, ids, "id", "aihub")
-    if _preview("aihub", items):
-        return
-    dirty = False
-    for it in items:
-        iid = it.get("id")
-        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}
-        if iid:
-            ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload, acceptable_errors=(404,))
-            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)
-    _summary("aihub", len(items))
-
-
-def sync_system_config(server, token, keys=None):
-    items = _load_index("system_config/index.json", allow_missing=bool(keys))
-    items = _recover_missing_index_entries(
-        server, token, items, keys, "config_key", "system_config", "system_config/index.json", "/api/system/config",
-    )
-    items = _filter_items_by_ids(items, keys, "config_key", "system_config")
-    if _preview("system_config", items, "config_key"):
-        return
-    for it in items:
-        ck = it.get("config_key")
-        if not ck:
-            continue
-        # 优先使用 parsed_value（init 时 GET 返回的解析值），其次 config_value
-        value = it.get("parsed_value") if "parsed_value" in it else it.get("config_value")
-        value_payload = {"config_value": value}
-        meta_payload = {
-            "config_value": value,
-            "value_type": it.get("value_type"),
-            "category": it.get("category"),
-            "description": it.get("description"),
-            "is_sensitive": it.get("is_sensitive"),
-            "status": it.get("status"),
-        }
-        meta_payload = {k: v for k, v in meta_payload.items() if v is not None}
-        # 前端全局层属于系统默认配置，默认字段的描述/分类/状态由基座维护。
-        # 推送时只更新值，避免旧 index 中的元信息触发“系统默认字段不允许修改字段描述”。
-        payload = value_payload if _is_frontend_global_config(it) else meta_payload
-        ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", payload, acceptable_errors=(404,))
-        if not ok and _is_protected_system_config_error(body) and payload != value_payload:
-            print(f"  WARN [{ck}] 系统默认字段元信息受保护，改为仅推送 config_value")
-            ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", value_payload, acceptable_errors=(404,))
-        if not ok and status == 404:
-            print(f"  WARN [{ck}] system_config 不存在，尝试创建")
-            create_payload = _system_config_create_payload(ck, it, value)
-            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)}")
-    _summary("system_config", len(items))
-
-
-def _is_frontend_global_config(item):
-    return (
-        str(item.get("category") or "") == "frontend_global"
-        or str(item.get("config_key") or "").startswith("frontend_global_")
-    )
-
-
-def _is_protected_system_config_error(body):
-    text = body if isinstance(body, str) else json.dumps(body, ensure_ascii=False)
-    return "系统默认字段不允许修改字段" in text
-
-
-def _system_config_create_payload(config_key, item, value):
-    return {
-        "config_key": config_key,
-        "config_value": value,
-        "value_type": item.get("value_type") or _infer_system_config_value_type(value),
-        "category": item.get("category") or "custom",
-        "description": item.get("description") or "",
-        "is_sensitive": bool(item.get("is_sensitive", False)),
-        "status": item.get("status") or "active",
-    }
-
-
-def _infer_system_config_value_type(value):
-    if isinstance(value, bool):
-        return "bool"
-    if isinstance(value, int) and not isinstance(value, bool):
-        return "int"
-    if isinstance(value, (dict, list)):
-        return "json"
-    return "string"
-
-
-def sync_roles(server, token, ids=None):
-    items = _load_index("roles/index.json", allow_missing=bool(ids))
-    items = _recover_missing_index_entries(
-        server, token, items, ids, "id", "roles", "roles/index.json", "/api/roles",
-    )
-    items = _filter_items_by_ids(items, ids, "id", "roles")
-    if _preview("roles", items):
-        return
-    for it in items:
-        rid = it.get("id")
-        code = it.get("code", rid)
-        # RoleUpdateRequest 字段
-        payload = {k: it.get(k) for k in (
-            "name", "description", "status", "sort_order", "user_visible",
-        ) if it.get(k) is not None}
-        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)}")
-    _summary("roles", len(items))
-
-
-def sync_users(server, token, ids=None):
-    items = _load_index("users/index.json", allow_missing=bool(ids))
-    items = _recover_missing_index_entries(
-        server, token, items, ids, "id", "users", "users/index.json", "/api/users",
-    )
-    items = _filter_items_by_ids(items, ids, "id", "users")
-    if _preview("users", items):
-        return
-    for it in items:
-        uid = it.get("id")
-        uname = it.get("username", uid)
-        # UserUpdateRequest 字段子集（不下发 password / role_ids 之类敏感修改）
-        payload = {k: it.get(k) for k in (
-            "username", "email", "phone_number", "nickname",
-            "avatar", "status", "notes",
-        ) if it.get(k) is not None}
-        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)}")
-    _summary("users", len(items))
-
-
-def sync_docs(server, token, ids=None):
-    """文档文章：从 .draftgo/docs/articles/index.json + 同目录 .md 文件回填正文。"""
-    all_items = _load_index("docs/articles/index.json", allow_missing=bool(ids))
-    all_items = _recover_missing_index_entries(
-        server, token, all_items, ids, "id", "docs", "docs/articles/index.json", "/api/docs/admin/articles",
-        file_spec=("docs/articles", "content_file", "article", [".html", ".md"]), drop_fields=("content",),
-    )
-    _warn_orphan_files("docs/articles", all_items, "content_file", "article", [".html", ".md"], "docs")
-    items = _filter_items_by_ids(
-        all_items, ids, "id", "docs",
-        orphan=lambda missing: _orphan_hints("docs/articles", "article", missing, [".html", ".md"]),
-    )
-    if _preview("docs", items):
-        return
-    dirty = False
-    for it in items:
-        aid = it.get("id")
-        title = it.get("title", aid or "(new)")
-        content_rel = it.get("content_file") or ""
-        content_path = DEFAULT_ROOT / content_rel if content_rel else None
-        if not content_path or not content_path.exists():
-            print(f"  SKIP [{title}] content_file not found: {content_rel}")
-            continue
-        content = content_path.read_text(encoding="utf-8")
-        # ArticleUpdate / ArticleCreate 接受字段（仅 title 必填，其余有默认值）
-        payload = {k: it.get(k) for k in (
-            "title", "slug", "category_id", "summary", "cover", "tags",
-            "status", "is_top", "sort_order", "seo_title", "seo_description",
-            "permission",
-        ) if it.get(k) is not None}
-        payload["content"] = content
-        payload["content_type"] = "html"
-        if aid:
-            ok, status, body = api_call("PUT", server, token, f"/api/docs/articles/{aid}", payload, acceptable_errors=(404,))
-            if not ok and status == 404:
-                print(f"  WARN [{title}] article_id={aid} 不存在，尝试创建")
-                aid = None
-            else:
-                print(f"  {'OK' if ok else 'ERR'} [{title}] article_id={aid}{'' if ok else ' -> ' + _info(ok, status, body)}")
-        if not aid:
-            ok, status, body = api_call("POST", server, token, "/api/docs/articles", payload)
-            new_id = _extract_created_id(body) if ok else None
-            if ok and new_id:
-                it["id"] = new_id
-                new_rel = _rename_to_canonical(
-                    "docs/articles", it.get("content_file", ""), "article", new_id,
-                    it.get("slug") or it.get("title") or new_id, "html")
-                it["content_file"] = new_rel
-                dirty = True
-                print(f"  OK [{title}] 已创建 article_id={new_id}（已回写 index）")
-            else:
-                print(f"  ERR [{title}] 创建失败 -> {_info(ok, status, body)}")
-    if dirty:
-        _writeback_index("docs/articles/index.json", all_items)
-    _summary("docs", len(items))
-
-
-def sync_doc_categories(server, token, ids=None):
-    all_items = _load_index("doc_categories/index.json", allow_missing=bool(ids))
-    all_items = _recover_missing_index_entries(
-        server, token, all_items, ids, "id", "doc_categories", "doc_categories/index.json", "/api/docs/categories?flat=true",
-    )
-    items = _filter_items_by_ids(all_items, ids, "id", "doc_categories")
-    if _preview("doc_categories", items):
-        return
-    dirty = False
-    for it in items:
-        cid = it.get("id")
-        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}
-        if cid:
-            ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload, acceptable_errors=(404,))
-            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)
-    _summary("doc_categories", len(items))
-
-
-def _route_specs_from_code(code):
-    specs = []
-    for m in re.finditer(r'@route\(\s*["\']([A-Za-z]+)\s+([^"\']+)["\']\s*\)', code):
-        specs.append((m.group(1).upper(), m.group(2)))
-    for m in re.finditer(r'\.Route\(\s*["\']([A-Za-z]+)["\']\s*,\s*["\']([^"\']+)["\']', code):
-        specs.append((m.group(1).upper(), m.group(2)))
-    return specs
-
-
-def _probe_script_routes(server, token, script_meta, code):
-    slug = script_meta.get("slug")
-    if not slug:
-        return
-    for method, route_path in _route_specs_from_code(code):
-        if method != "GET":
-            print(f"  SKIP probe [{slug}] {method} {route_path}（只自动探测 GET，避免副作用）")
-            continue
-        path = route_path if route_path.startswith("/") else f"/{route_path}"
-        ok, status, body = api_call("GET", server, token, f"/api/x/{slug}{path}")
-        print(f"  {'OK' if ok else 'ERR'} probe GET /api/x/{slug}{path}{'' if ok else ' -> ' + _info(ok, status, body)}")
-
-
-def sync_custom_scripts(server, token, ids=None):
-    """自定义脚本：从 .draftgo/custom_scripts/index.json + 同目录代码文件回填 code。"""
-    all_items = _load_index("custom_scripts/index.json", allow_missing=bool(ids))
-    all_items = _recover_missing_index_entries(
-        server, token, all_items, ids, "id", "custom_scripts", "custom_scripts/index.json", "/api/scripts/",
-        file_spec=("custom_scripts", "code_file", "script", [".py", ".js", ".ts", ".sh", ".go", ".txt"]), drop_fields=("code",),
-    )
-    _warn_orphan_files("custom_scripts", all_items, "code_file", "script", [".go"], "custom_scripts")
-    items = _filter_items_by_ids(
-        all_items, ids, "id", "custom_scripts",
-        orphan=lambda missing: _orphan_hints("custom_scripts", "script", missing, [".go"]),
-    )
-    if _preview("custom_scripts", items):
-        return
-    dirty = False
-    for it in items:
-        sid = it.get("id")
-        name = it.get("name") or it.get("slug") or sid or "(new)"
-        code_rel = it.get("code_file") or ""
-        code_path = DEFAULT_ROOT / code_rel if code_rel else None
-        if not code_path or not code_path.exists():
-            print(f"  SKIP [{name}] code_file not found: {code_rel}")
-            continue
-        code = code_path.read_text(encoding="utf-8")
-        if sid:
-            if not _cloud_version_allows_push(server, token, f"/api/scripts/{sid}", it, name):
-                continue
-            # ScriptUpdate 接受字段（不含 slug/mode，避免误改启停/路由）
-            payload = {k: it.get(k) for k in (
-                "name", "description", "config", "permission", "go_mod", "go_sum",
-            ) if it.get(k) is not None}
-            payload["code"] = code
-            ok, status, body = api_call("PUT", server, token, f"/api/scripts/{sid}", payload, acceptable_errors=(404,))
-            if not ok and status == 404:
-                print(f"  WARN [{name}] script_id={sid} 不存在，尝试创建")
-                sid = None
-            else:
-                print(f"  {'OK' if ok else 'ERR'} [{name}] script_id={sid}{'' if ok else ' -> ' + _info(ok, status, body)}")
-            if ok and PROBE_ROUTES and str(it.get("mode") or "").lower() in ("route", "mixed"):
-                _probe_script_routes(server, token, it, code)
-        if not sid:
-            # ScriptCreate 必填 name/slug/code/mode；触发来源统一以代码装饰器为准
-            payload = {
-                "name": it.get("name", ""),
-                "slug": it.get("slug", ""),
-                "code": code,
-                "mode": it.get("mode", "route"),
-                "config": it.get("config"),
-                "permission": it.get("permission"),
-                "description": it.get("description"),
-                "go_mod": it.get("go_mod"),
-                "go_sum": it.get("go_sum"),
-            }
-            payload = {k: v for k, v in payload.items() if v is not None}
-            ok, status, body = api_call("POST", server, token, "/api/scripts/", payload)
-            new_id = _extract_created_id(body) if ok else None
-            if ok and new_id:
-                it["id"] = new_id
-                ext = (code_rel.rsplit(".", 1)[-1] if "." in code_rel else "txt")
-                new_rel = _rename_to_canonical(
-                    "custom_scripts", code_rel, "script", new_id,
-                    it.get("slug") or it.get("name") or new_id, ext)
-                it["code_file"] = new_rel
-                dirty = True
-                print(f"  OK [{name}] 已创建 script_id={new_id}（已回写 index）")
-                if PROBE_ROUTES and str(it.get("mode") or "").lower() in ("route", "mixed"):
-                    _probe_script_routes(server, token, it, code)
-            else:
-                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
-    if dirty:
-        _writeback_index("custom_scripts/index.json", all_items)
-    _summary("custom_scripts", len(items))
-
-
-def _lint_page_html(html, label):
-    """Non-blocking lint for page HTML. Prints warnings, never raises."""
-    warnings = []
-    # Extract all <script> content
-    script_blocks = re.findall(r'<script[^>]*>(.*?)</script>', html, re.DOTALL | re.IGNORECASE)
-    for block_idx, block in enumerate(script_blocks):
-        # Detect let/const duplicate declarations in same scope
-        decls = {}
-        for line_offset, line in enumerate(block.split('\n'), start=1):
-            for m in re.finditer(r'\b(let|const)\s+([A-Za-z_$][\w$]*)', line):
-                kind, name = m.group(1), m.group(2)
-                if name in decls:
-                    prev_kind, prev_line = decls[name]
-                    warnings.append(
-                        f"变量 '{name}' 重复声明 ({prev_kind} @行~{prev_line}, {kind} @行~{line_offset})"
-                    )
-                else:
-                    decls[name] = (kind, line_offset)
-        # Detect destructured let/const: let {a, b} = ... or let [a, b] = ...
-        for line_offset, line in enumerate(block.split('\n'), start=1):
-            for m in re.finditer(r'\b(let|const)\s*[\[{]([^}\]]+)[}\]]', line):
-                kind = m.group(1)
-                names_str = m.group(2)
-                for nm in re.findall(r'([A-Za-z_$][\w$]*)', names_str):
-                    if nm in decls and decls[nm][1] != line_offset:
-                        prev_kind, prev_line = decls[nm]
-                        warnings.append(
-                            f"变量 '{nm}' 重复声明 ({prev_kind} @行~{prev_line}, {kind} 解构 @行~{line_offset})"
-                        )
-        # Detect browser native dialogs (alert/confirm/prompt)
-        for line_offset, line in enumerate(block.split('\n'), start=1):
-            # Match bare alert/confirm/prompt calls, exclude App.confirm
-            for m in re.finditer(r'(?<!\w)(?<!App\.)(alert|confirm|prompt)\s*\(', line):
-                fn = m.group(1)
-                alt = {'alert': 'App.showModal()', 'confirm': 'await App.confirm()', 'prompt': 'custom input modal'}
-                warnings.append(
-                    f"禁止使用浏览器原生 {fn}() (@行~{line_offset}), 请用 {alt[fn]}"
-                )
-    if warnings:
-        print(f"  [!] [lint] [{label}] found {len(warnings)} potential issue(s):")
-        for w in warnings:
-            print(f"       {w}")
-
-
-HANDLERS = {
-    "pages":           sync_pages,
-    "nav":             sync_nav,
-    "db_meta":         sync_db_meta,
-    "aihub":           sync_aihub,
-    "system_config":   sync_system_config,
-    "roles":           sync_roles,
-    "users":           sync_users,
-    "docs":            sync_docs,
-    "doc_categories":  sync_doc_categories,
-    "custom_scripts":  sync_custom_scripts,
-}
-
-
-def run_batch(server, token, args):
-    """批量推送：--batch pages 1,2,3 nav 4 custom_scripts 7,8
-    解析为多组 (mode, [ids]) 依次执行，共享同一连接配置。"""
-    groups = []
-    i = 0
-    while i < len(args):
-        mode = args[i]
-        if mode not in HANDLERS:
-            print(f"ERR: unknown mode '{mode}' in --batch", file=sys.stderr)
-            sys.exit(1)
-        i += 1
-        ids = []
-        if i < len(args) and args[i] not in HANDLERS and not args[i].startswith("-"):
-            ids = args[i].split(",")
-            i += 1
-        groups.append((mode, ids or None))
-    print(f"[batch] {len(groups)} group(s) to push")
-    for mode, ids in groups:
-        print(f"\n--- {mode} {'(all)' if not ids else ','.join(ids)} ---")
-        HANDLERS[mode](server, token, ids)
-    result = "previewed" if DRY_RUN else "pushed"
-    print(f"\n[batch] done, {len(groups)} group(s) {result}")
-
-
-def main():
-    global PROBE_ROUTES, DRY_RUN
-    if len(sys.argv) < 2:
-        print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]\n"
-              f"       draftgo_push.py --batch <mode> <ids> [<mode> <ids> ...]")
-        sys.exit(1)
-
-    args = sys.argv[1:]
-    if "--probe-routes" in args:
-        PROBE_ROUTES = True
-        args = [a for a in args if a != "--probe-routes"]
-    if "--dry-run" in args:
-        DRY_RUN = True
-        args = [a for a in args if a != "--dry-run"]
-
-    if not args:
-        print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]")
-        sys.exit(1)
-
-    if args[0] == "--all":
-        args = ["--batch", *HANDLERS]
-
-    if args[0] == "--batch":
-        server, token, cfg = load_config()
-        run_batch(server, token, args[1:])
-        _lessons_reminder(cfg)
-        if RUN_FAILURES:
-            print(f"ERR: push finished with {RUN_FAILURES} failed request(s)", file=sys.stderr)
-            sys.exit(1)
-        return
-
-    if args[0] not in HANDLERS:
-        print(f"usage: draftgo_push.py {{{'|'.join(HANDLERS)}}} [id ...]")
-        sys.exit(1)
-    mode = args[0]
-    ids = args[1:] or None
-    server, token, cfg = load_config()
-    HANDLERS[mode](server, token, ids)
-    _lessons_reminder(cfg)
-    if RUN_FAILURES:
-        print(f"ERR: push finished with {RUN_FAILURES} failed request(s)", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()