chore(workflow): adopt lightweight governance (#221)

dev_scripts/harness.py

@@ -67,6 +67,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/00-project-profile.md": (
         "## 基本信息",
+        "## 项目治理模式",
         "## 建设基线",
         "## 交付单元",
         "## 文档事实来源",
@@ -74,6 +75,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 当前阶段",
     ),
     "docs/01-workflow.md": (
+        "## 语言与术语",
         "## 事实来源",
         "## 权威源与事实边界",
         "## Gitea 交互与工单最小读取",
@@ -102,6 +104,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/04-local-development-and-verification.md": (
         "## Windows PowerShell 与 UTF-8",
+        "### PowerShell 语法与外部命令",
         "## 通用检查",
         "## 服务端验证",
         "## Web 验证",
@@ -271,9 +274,14 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "#### 明确停止条件",
         "单元任务是唯一正式实施单位",
         "高风险修改必须停止",
+        "### 项目治理模式与明确授权后的执行",
+        "默认采用轻量治理",
+        "不能单独构成人工授权",
+        "不得仅因操作不可逆而重复询问或拒绝",
+        "平台自身强制的审批、安全策略或权限限制继续有效",
         "用户没有明确验收通过前不得关闭",
         "只有长期事实变化时才更新 Wiki",
-        "Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源",
+        "需要工单的任务以 Gitea 工单作为单次需求、变化、实现、测试、提交和验收的事实来源",
         "Wiki 同步由长期事实变化触发，不由任务完成触发",
         "标准流程不创建 Wiki 任务归档",
         "工单默认只在开始实施、集中回写待验收、验收关闭三个节点更新",
@@ -289,6 +297,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据",
         "提交只包含当前工单相关文件",
         "不得仅为设置编码重复启动一层 PowerShell",
+        "不得默认套用 Bash",
+        "复杂正则优先使用变量或 `rg -e`",
+        "单引号 PowerShell here-string",
+        "`foreach`、`if` 等语句块",
+        "使用真实目录配合 `-g/--glob`",
         "文件解码和控制台输出分别处理",
         "不得默认使用 `-ExecutionPolicy Bypass`",
         "### 工单与设计证据双门禁",
@@ -316,6 +329,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "不得臆造用户原话",
         "不复制完整聊天",
         "Gitea 工单全文不导出到仓库",
+        "用户可以使用中文、英文或合理的中英混合语言交流",
+        "默认使用中文分析、回复、编写工单和维护内部项目文档",
+        "日志和错误原文保持原样",
     )
     for section in missing_sections(content, required):
         errors.append(f"AGENTS.md 缺少：{section}")
@@ -562,32 +578,47 @@ def run_check(args: argparse.Namespace) -> int:
 
 
 def run_sync(args: argparse.Namespace) -> int:
-    """--verify 依次执行导出、结构检查和一致性校验，替代原来的三条命令。"""
+    """同步核心镜像；--verify 复用本轮完整读取完成初始化验证。"""
 
     if args.verify:
-        steps = (
-            ("同步", lambda: run_sync(
-                argparse.Namespace(check=False, verify=False, config=args.config))),
-            ("结构检查", lambda: run_check(argparse.Namespace(strict=True))),
-            ("一致性校验", lambda: run_sync(
-                argparse.Namespace(check=True, verify=False, config=args.config))),
-        )
-        for name, step in steps:
-            code = step()
-            if code != 0:
-                print(f"错误：{name}未通过，已停止")
-                return code
+        try:
+            config = load_config(Path(args.config).resolve())
+            messages = sync_all(
+                config, WikiClient(config), check=False, deep_check=True
+            )
+        except WikiDocsError as exc:
+            print(f"错误：{exc}")
+            return 1
+        for message in messages:
+            print(message)
+        code = run_check(argparse.Namespace(strict=True))
+        if code != 0:
+            print("错误：结构检查未通过，已停止")
+            return code
+        print("Wiki 镜像初始化验证通过")
         return 0
 
     try:
         config = load_config(Path(args.config).resolve())
-        messages = sync_all(config, WikiClient(config), check=args.check)
+        deep_check = getattr(args, "deep_check", False)
+        messages = sync_all(
+            config,
+            WikiClient(config),
+            check=args.check or deep_check,
+            deep_check=deep_check,
+        )
     except WikiDocsError as exc:
         print(f"错误：{exc}")
         return 1
     for message in messages:
         print(message)
-    print("Wiki 镜像检查通过" if args.check else "Wiki 镜像同步完成")
+    print(
+        "Wiki 镜像深度检查通过"
+        if deep_check
+        else "Wiki 镜像检查通过"
+        if args.check
+        else "Wiki 镜像同步完成"
+    )
     return 0
 
 
@@ -652,13 +683,21 @@ def main() -> int:
     p_check.set_defaults(func=run_check)
 
     p_sync = sub.add_parser("sync", help="从 Gitea Wiki 单向同步核心 docs 镜像")
-    p_sync.add_argument(
-        "--check", action="store_true", help="只检查 Wiki 与镜像是否一致，不写文件"
+    sync_mode = p_sync.add_mutually_exclusive_group()
+    sync_mode.add_argument(
+        "--check",
+        action="store_true",
+        help="按 revision 快速检查 Wiki 与镜像，不写文件",
     )
-    p_sync.add_argument(
+    sync_mode.add_argument(
+        "--deep-check",
+        action="store_true",
+        help="下载全部 Wiki 正文并逐页检查镜像，不写文件",
+    )
+    sync_mode.add_argument(
         "--verify",
         action="store_true",
-        help="依次执行导出、check --strict 和一致性校验",
+        help="完整读取并导出 Wiki，再执行 check --strict 初始化验证",
     )
     p_sync.add_argument(
         "--config", default=str(DEFAULT_CONFIG), help="Wiki 页面映射 JSON 文件"

dev_scripts/wiki_docs.py

@@ -8,6 +8,7 @@ import os
 import re
 import subprocess
 import tempfile
+import time
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
@@ -26,6 +27,7 @@ HEADER_PATTERN = re.compile(
     rf"{re.escape(MIRROR_END)}\n\n(?P<body>.*)\Z",
     re.DOTALL,
 )
+RATE_LIMIT_RETRY_DELAYS = (1.0, 2.0, 4.0)
 
 
 class WikiDocsError(RuntimeError):
@@ -142,11 +144,33 @@ class WikiClient:
             data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
             headers["Content-Type"] = "application/json"
         request = Request(url, data=data, headers=headers, method=method)
-        try:
-            with urlopen(request, timeout=30) as response:
-                body = response.read()
-        except HTTPError as exc:
-            if self.token and method == "GET" and exc.code in {401, 403, 404}:
+        request_error: HTTPError | URLError | None = None
+        body = b""
+        for attempt in range(len(RATE_LIMIT_RETRY_DELAYS) + 1):
+            try:
+                with urlopen(request, timeout=30) as response:
+                    body = response.read()
+                request_error = None
+                break
+            except HTTPError as exc:
+                if (
+                    method == "GET"
+                    and exc.code == 429
+                    and attempt < len(RATE_LIMIT_RETRY_DELAYS)
+                ):
+                    exc.close()
+                    time.sleep(RATE_LIMIT_RETRY_DELAYS[attempt])
+                    continue
+                request_error = exc
+                break
+            except URLError as exc:
+                request_error = exc
+                break
+        else:  # pragma: no cover - for 循环必定通过成功或异常分支退出
+            raise WikiDocsError(f"Gitea API {method} {api_path} 请求失败")
+
+        if isinstance(request_error, HTTPError):
+            if self.token and method == "GET" and request_error.code in {401, 403, 404}:
                 # 公共仓库可能可匿名读取，而当前 shell 中的通用令牌属于
                 # 另一个实例或已失效。只对只读请求安全降级为匿名访问。
                 anonymous_headers = {"Accept": "application/json"}
@@ -167,12 +191,13 @@ class WikiClient:
                         f"无法连接 Gitea：{anonymous_exc.reason}"
                     ) from anonymous_exc
             else:
-                detail = exc.read().decode("utf-8", errors="replace")
+                detail = request_error.read().decode("utf-8", errors="replace")
                 raise WikiDocsError(
-                    f"Gitea API {method} {api_path} 返回 {exc.code}: {detail}"
-                ) from exc
-        except URLError as exc:
-            raise WikiDocsError(f"无法连接 Gitea：{exc.reason}") from exc
+                    f"Gitea API {method} {api_path} 返回 "
+                    f"{request_error.code}: {detail}"
+                ) from request_error
+        elif isinstance(request_error, URLError):
+            raise WikiDocsError(f"无法连接 Gitea：{request_error.reason}") from request_error
         if not body:
             return None
         try:
@@ -381,8 +406,73 @@ 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:
         dirty = dirty_mirror_paths(config)
@@ -392,10 +482,43 @@ def sync_all(config: Config, client: WikiClient, *, check: bool = False) -> list
                 "已映射的本地镜像存在未提交改动，已停止以防覆盖：\n" + details
             )
 
-    messages: list[str] = []
+    pages = client.list_pages()
+    resolved: list[tuple[Mapping, Path, WikiPage | None, str | None]] = []
     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 "无变化"
+            resolved.append(
+                (
+                    mapping,
+                    target,
+                    None,
+                    f"{action}：{mapping.path} <- "
+                    f"{mapping.page}@{remote_revision[:12]}",
+                )
+            )
+            continue
+
+        page = client.get_page_from_metadata(metadata, mapping.page)
+        resolved.append((mapping, target, page, None))
+
+    messages: list[str] = []
+    for mapping, target, page, skip_message in resolved:
+        if skip_message is not None:
+            messages.append(skip_message)
+            continue
+        if page is None:  # pragma: no cover - resolved 元组由上面的单一路径构造
+            raise WikiDocsError(f"Wiki 页面未解析：{mapping.page}")
         if check:
             errors = check_mirror(mapping, page, target)
             if errors: