perf: 优化 Wiki 镜像增量同步 (#29)

dev_scripts/wiki_docs.py

@@ -381,7 +381,72 @@ def check_mirror(mapping: Mapping, page: WikiPage, path: Path) -> list[str]:
     return errors
 
 
-def sync_all(config: Config, client: WikiClient, *, check: bool = False) -> list[str]:
+def _metadata_revision(metadata: dict[str, Any]) -> str | None:
+    last_commit = metadata.get("last_commit")
+    revision = last_commit.get("sha") if isinstance(last_commit, dict) else None
+    return revision if isinstance(revision, str) and revision else None
+
+
+def _find_page_metadata(
+    pages: list[dict[str, Any]], page_name: str
+) -> dict[str, Any]:
+    metadata = next(
+        (
+            item
+            for item in pages
+            if item.get("title") == page_name or item.get("sub_url") == page_name
+        ),
+        None,
+    )
+    if metadata is None:
+        raise WikiDocsError(
+            f"Wiki 页面不存在：{page_name}；不会自动删除或重命名本地镜像"
+        )
+    return metadata
+
+
+def _metadata_identity(
+    config: Config, metadata: dict[str, Any], fallback_title: str
+) -> tuple[str, str] | None:
+    title = metadata.get("title")
+    sub_url = metadata.get("sub_url")
+    if not isinstance(title, str) or not title:
+        title = fallback_title
+    if not isinstance(sub_url, str) or not sub_url:
+        return None
+    url = (
+        f"{config.gitea_url}/{quote(config.owner, safe='')}/"
+        f"{quote(config.repository, safe='')}/wiki/{quote(sub_url, safe='%')}"
+    )
+    return title, url
+
+
+def _local_revision(
+    path: Path, *, expected_title: str, expected_url: str
+) -> str | None:
+    if not path.is_file():
+        return None
+    try:
+        metadata, _body = parse_mirror(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, WikiDocsError):
+        return None
+    if (
+        metadata.get("wiki_page") != expected_title
+        or metadata.get("wiki_url") != expected_url
+        or not metadata.get("synchronized_at")
+    ):
+        return None
+    revision = metadata.get("wiki_revision")
+    return revision if revision else None
+
+
+def sync_all(
+    config: Config,
+    client: WikiClient,
+    *,
+    check: bool = False,
+    deep_check: bool = False,
+) -> list[str]:
     """检查或写入所有显式映射；绝不处理映射外的文件。"""
 
     if not check:
@@ -392,10 +457,28 @@ def sync_all(config: Config, client: WikiClient, *, check: bool = False) -> list
                 "已映射的本地镜像存在未提交改动，已停止以防覆盖：\n" + details
             )
 
+    pages = client.list_pages()
     messages: list[str] = []
     for mapping in config.mappings:
-        page = client.get_page(mapping.page)
+        metadata = _find_page_metadata(pages, mapping.page)
         target = ROOT / PurePosixPath(mapping.path)
+        remote_revision = _metadata_revision(metadata)
+        identity = _metadata_identity(config, metadata, mapping.page)
+        local_revision = (
+            _local_revision(
+                target, expected_title=identity[0], expected_url=identity[1]
+            )
+            if identity is not None
+            else None
+        )
+        if not deep_check and remote_revision and local_revision == remote_revision:
+            action = "一致" if check else "无变化"
+            messages.append(
+                f"{action}：{mapping.path} <- {mapping.page}@{remote_revision[:12]}"
+            )
+            continue
+
+        page = client.get_page_from_metadata(metadata, mapping.page)
         if check:
             errors = check_mirror(mapping, page, target)
             if errors: