draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/scripts/draftgo_push.py

@@ -2,7 +2,7 @@
 """
 DraftGo Push Script
 推送本地修改到云端。覆盖所有 init 拉取的类型：
-  pages / nav / db_meta / aihub / external_apis / system_config / roles / users
+  pages / nav / db_meta / aihub / system_config / roles / users
   docs / doc_categories / custom_scripts
 
 用法：
@@ -10,19 +10,21 @@ DraftGo Push Script
   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 external_apis   [api_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 ...]   ⚠️ 涉及账号，调用前应人工确认
+  python draftgo_push.py roles           [role_id ...]
+  python draftgo_push.py users           [user_id ...]
 """
-import json, sys, re
+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:
@@ -43,46 +45,6 @@ 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"
     if not cfg_path.exists():
@@ -93,6 +55,8 @@ def load_config():
 
 
 def _lessons_reminder(cfg):
+    if DRY_RUN:
+        return
     if not cfg.get("lessons_on_push", False):
         return
     print("")
@@ -104,7 +68,9 @@ def _lessons_reminder(cfg):
     print("  未命中则跳过。")
 
 
-def api_call(method, server, token, path, body=None):
+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}",
@@ -126,8 +92,12 @@ def api_call(method, server, token, path, body=None):
         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")
+        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)
 
 
@@ -159,8 +129,9 @@ def _extract_created_id(body_text):
 def _writeback_index(rel_index, items):
     """将更新后的 index 列表写回 .draftgo/ 下的 index.json。"""
     path = DEFAULT_ROOT / ".draftgo" / rel_index
-    if not path.exists():
+    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")
 
 
@@ -185,22 +156,247 @@ def _rename_to_canonical(sub_dir, old_rel, prefix, new_id, slug_src, ext):
         return old_rel
 
 
-def _load_index(rel_index):
+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")
-    pages = all_pages
-    if ids:
-        pages = [p for p in all_pages if str(p.get("id")) in ids]
+    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")
@@ -221,9 +417,9 @@ 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):
+            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)
+            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} 不存在，尝试创建")
@@ -245,13 +441,17 @@ def sync_pages(server, token, ids=None):
                 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")
-    metas = all_metas
-    if ids:
-        metas = [m for m in all_metas if str(m.get("id")) in ids]
+    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")
@@ -266,9 +466,7 @@ 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)
+            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 创建")
@@ -287,13 +485,22 @@ def sync_db_meta(server, token, ids=None):
                 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")
-    navs = all_navs
-    if ids:
-        navs = [n for n in all_navs if str(n.get("id")) in ids]
+    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")
@@ -304,9 +511,7 @@ 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})
+            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
@@ -336,13 +541,17 @@ def sync_nav(server, token, ids=None):
                 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")
-    items = all_items
-    if ids:
-        items = [it for it in all_items if str(it.get("id")) in ids]
+    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")
@@ -353,9 +562,7 @@ 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)
+            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
@@ -376,61 +583,25 @@ def sync_aihub(server, token, ids=None):
                 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):
-    all_items = _load_index("external_apis/index.json")
-    items = all_items
-    if 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 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}
-        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)
+    _summary("aihub", len(items))
 
 
 def sync_system_config(server, token, keys=None):
-    items = _load_index("system_config/index.json")
-    if keys:
-        items = [it for it in items if str(it.get("config_key")) in keys]
+    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")
-        payload = {
+        value_payload = {"config_value": value}
+        meta_payload = {
             "config_value": value,
             "value_type": it.get("value_type"),
             "category": it.get("category"),
@@ -438,23 +609,66 @@ def sync_system_config(server, token, keys=None):
             "is_sensitive": it.get("is_sensitive"),
             "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)
+        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 = {"config_key": ck, **payload}
+            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")
-    if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+    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)
@@ -462,16 +676,19 @@ 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)}")
+    _summary("roles", len(items))
 
 
 def sync_users(server, token, ids=None):
-    items = _load_index("users/index.json")
-    if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+    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)
@@ -480,18 +697,25 @@ 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)}")
+    _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")
-    items = all_items
-    if ids:
-        items = [it for it in all_items if str(it.get("id")) in ids]
+    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")
@@ -509,10 +733,9 @@ def sync_docs(server, token, ids=None):
             "permission",
         ) if it.get(k) is not None}
         payload["content"] = content
+        payload["content_type"] = "html"
         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)
+            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
@@ -525,7 +748,7 @@ def sync_docs(server, token, ids=None):
                 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, "md")
+                    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）")
@@ -533,13 +756,17 @@ def sync_docs(server, token, ids=None):
                 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")
-    items = all_items
-    if ids:
-        items = [it for it in all_items if str(it.get("id")) in ids]
+    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")
@@ -549,9 +776,7 @@ 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)
+            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
@@ -568,26 +793,45 @@ def sync_doc_categories(server, token, ids=None):
                 print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
     if dirty:
         _writeback_index("doc_categories/index.json", all_items)
+    _summary("doc_categories", len(items))
 
 
-def _normalize_script_triggers(mode, triggers):
-    """归一化 custom_script.triggers。
+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
 
-    - scheduled：实际调度只读代码里的 @scheduled(...)，CLI push 主动回写空 dict，
-      避免把误导性的 cron 元数据继续推回云端。
-    - 其他模式：保留本地 triggers 元数据。
-    """
-    if str(mode or "").lower() == "scheduled":
-        return {}
-    return triggers
+
+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")
-    items = all_items
-    if ids:
-        items = [it for it in all_items if str(it.get("id")) in ids]
+    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")
@@ -598,33 +842,34 @@ def sync_custom_scripts(server, token, ids=None):
             print(f"  SKIP [{name}] code_file not found: {code_rel}")
             continue
         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):
+            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",
+                "name", "description", "config", "permission", "go_mod", "go_sum",
             ) if it.get(k) is not None}
-            payload["triggers"] = normalized_triggers
             payload["code"] = code
-            ok, status, body = api_call("PUT", server, token, f"/api/scripts/{sid}", payload)
+            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；scheduled 的 cron 以代码装饰器为准
+            # ScriptCreate 必填 name/slug/code/mode；触发来源统一以代码装饰器为准
             payload = {
                 "name": it.get("name", ""),
                 "slug": it.get("slug", ""),
                 "code": code,
                 "mode": it.get("mode", "route"),
-                "triggers": normalized_triggers,
                 "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)
@@ -638,10 +883,13 @@ def sync_custom_scripts(server, token, ids=None):
                 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):
@@ -693,7 +941,6 @@ HANDLERS = {
     "nav":             sync_nav,
     "db_meta":         sync_db_meta,
     "aihub":           sync_aihub,
-    "external_apis":   sync_external_apis,
     "system_config":   sync_system_config,
     "roles":           sync_roles,
     "users":           sync_users,
@@ -723,32 +970,39 @@ def run_batch(server, token, args):
     for mode, ids in groups:
         print(f"\n--- {mode} {'(all)' if not ids else ','.join(ids)} ---")
         HANDLERS[mode](server, token, ids)
-    print(f"\n[batch] done, {len(groups)} group(s) pushed")
+    result = "previewed" if DRY_RUN else "pushed"
+    print(f"\n[batch] done, {len(groups)} group(s) {result}")
 
 
 def main():
-    global FORCE
-
+    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> ...]\n"
-              f"       --force  跳过冲突检测，强制覆盖")
+              f"       draftgo_push.py --batch <mode> <ids> [<mode> <ids> ...]")
         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] 已跳过冲突检测，将强制覆盖云端数据")
+    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:
@@ -759,6 +1013,9 @@ def main():
     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__":