feat: export task archives on demand (#14)

dev_scripts/wiki_docs.py

@@ -210,6 +210,14 @@ class WikiClient:
             raise WikiDocsError(
                 f"Wiki 页面不存在：{page_name}；不会自动删除或重命名本地镜像"
             )
+        return self.get_page_from_metadata(metadata, page_name)
+
+    def get_page_from_metadata(
+        self, metadata: dict[str, Any], page_name: str | None = None
+    ) -> WikiPage:
+        """使用页面列表元数据读取正文，避免重复获取完整页面列表。"""
+
+        resolved_name = page_name or _required_string(metadata, "title")
         sub_url = _required_string(metadata, "sub_url")
         page = self._request(
             "GET",
@@ -218,20 +226,22 @@ class WikiClient:
             f"{quote(sub_url, safe='%')}",
         )
         if not isinstance(page, dict):
-            raise WikiDocsError(f"Wiki 页面响应格式无效：{page_name}")
+            raise WikiDocsError(f"Wiki 页面响应格式无效：{resolved_name}")
         encoded_content = page.get("content_base64")
         if not isinstance(encoded_content, str):
-            raise WikiDocsError(f"Wiki 页面没有 content_base64：{page_name}")
+            raise WikiDocsError(f"Wiki 页面没有 content_base64：{resolved_name}")
         try:
             text = base64.b64decode(encoded_content, validate=True).decode("utf-8")
         except (ValueError, UnicodeDecodeError) as exc:
-            raise WikiDocsError(f"Wiki 页面不是有效的 UTF-8 Markdown：{page_name}") from exc
+            raise WikiDocsError(
+                f"Wiki 页面不是有效的 UTF-8 Markdown：{resolved_name}"
+            ) from exc
         last_commit = page.get("last_commit")
         revision = last_commit.get("sha") if isinstance(last_commit, dict) else None
         if not isinstance(revision, str) or not revision:
-            raise WikiDocsError(f"Wiki 页面缺少 revision：{page_name}")
+            raise WikiDocsError(f"Wiki 页面缺少 revision：{resolved_name}")
         title = page.get("title")
-        resolved_title = title if isinstance(title, str) and title else page_name
+        resolved_title = title if isinstance(title, str) and title else resolved_name
         html_url = (
             f"{self.config.gitea_url}/{quote(self.config.owner, safe='')}/"
             f"{quote(self.config.repository, safe='')}/wiki/{quote(sub_url, safe='%')}"
@@ -303,7 +313,14 @@ def render_mirror(page: WikiPage, existing: str | None = None) -> str:
 
 
 def dirty_mirror_paths(config: Config, root: Path = ROOT) -> list[str]:
-    paths = [mapping.path for mapping in config.mappings]
+    return dirty_paths([mapping.path for mapping in config.mappings], root)
+
+
+def dirty_paths(paths: list[str], root: Path = ROOT) -> list[str]:
+    """返回指定路径中已有、修改或未跟踪的工作区条目。"""
+
+    if not paths:
+        return []
     result = subprocess.run(
         ["git", "status", "--porcelain", "--", *paths],
         cwd=root,
@@ -329,6 +346,17 @@ def _write_atomic(path: Path, content: str) -> None:
         raise
 
 
+def write_mirror(path: Path, page: WikiPage) -> bool:
+    """写入一份 Wiki 镜像；内容无变化时返回 False。"""
+
+    existing = path.read_text(encoding="utf-8") if path.is_file() else None
+    rendered = render_mirror(page, existing)
+    if existing == rendered:
+        return False
+    _write_atomic(path, rendered)
+    return True
+
+
 def check_mirror(mapping: Mapping, page: WikiPage, path: Path) -> list[str]:
     if not path.is_file():
         return [f"缺少镜像：{mapping.path}"]