feat: 建立初级维护者文档体系 (#2)

scripts/check_harness.py

@@ -1,4 +1,4 @@
-"""检查 DevHarness 必需文件和任务归档的基本结构。"""
+"""检查 DevHarness 必需文件、核心文档和任务归档的基本结构。"""
 
 from __future__ import annotations
 
@@ -10,12 +10,81 @@ from wiki_docs import WikiDocsError, load_config, parse_mirror
 
 
 ROOT = Path(__file__).resolve().parents[1]
+CORE_PAGE_PATHS = {
+    "Home": "docs/README.md",
+    "Project-Profile": "docs/00-project-profile.md",
+    "Development-Workflow": "docs/01-workflow.md",
+    "Architecture-and-Code-Map": "docs/02-architecture-and-code-map.md",
+    "Business-Rules-and-Glossary": "docs/03-business-rules-and-glossary.md",
+    "Local-Development-and-Verification": (
+        "docs/04-local-development-and-verification.md"
+    ),
+    "Common-Changes": "docs/05-common-changes.md",
+    "Troubleshooting": "docs/06-troubleshooting.md",
+    "New-Project-Documentation-Setup": (
+        "docs/07-new-project-documentation-setup.md"
+    ),
+    "Task-Archive-Template": "docs/templates/task-archive.md",
+}
+CORE_DOCUMENT_REQUIREMENTS = {
+    "docs/README.md": (
+        "## 第一次阅读",
+        "## 五分钟开始",
+        "## 简单修改从哪里开始",
+        "## 事实来源",
+    ),
+    "docs/00-project-profile.md": (
+        "## 基本信息",
+        "## 技术栈与运行环境",
+        "## 阅读入口",
+        "## 常用命令",
+        "## 环境、配置与凭据",
+    ),
+    "docs/01-workflow.md": (
+        "## 面向初级维护者的修改边界",
+        "## 每个任务的文档影响",
+        "## 稳定文档与任务归档",
+    ),
+    "docs/02-architecture-and-code-map.md": (
+        "## 项目定位",
+        "## 代码地图",
+        "## 两条主要执行路径",
+        "## 不可破坏的边界",
+    ),
+    "docs/03-business-rules-and-glossary.md": (
+        "## 核心术语",
+        "## 工单状态",
+        "## 稳定业务规则",
+        "## 新项目需要补充什么",
+    ),
+    "docs/04-local-development-and-verification.md": (
+        "## 环境要求",
+        "## 第一次运行",
+        "## 常用调试方式",
+        "## 完成修改前",
+    ),
+    "docs/05-common-changes.md": (
+        "## 风险分级",
+        "## 修改 Wiki 文案",
+        "## 调整 Harness 检查",
+        "## 看懂 Agent 的修改",
+    ),
+    "docs/06-troubleshooting.md": (
+        "## 排查顺序",
+        "## 必须停止的情况",
+    ),
+    "docs/07-new-project-documentation-setup.md": (
+        "## 初始化顺序",
+        "## 完成标准",
+    ),
+}
 REQUIRED_FILES = (
     "AGENTS.md",
     "README.md",
     "docs/00-project-profile.md",
     "docs/01-workflow.md",
     "docs/templates/task-archive.md",
+    *CORE_DOCUMENT_REQUIREMENTS,
     "wiki-docs.json",
     "scripts/wiki_docs.py",
     "scripts/sync_wiki_docs.py",
@@ -61,6 +130,41 @@ def check_archives(errors: list[str]) -> None:
             errors.append(f"{path.name} 没有记录未验证部分")
 
 
+def missing_sections(content: str, required: tuple[str, ...]) -> list[str]:
+    return [section for section in required if section not in content]
+
+
+def check_core_documents(errors: list[str], root: Path = ROOT) -> None:
+    """检查初级维护者所需主题页的固定结构。"""
+
+    for relative_path, required in CORE_DOCUMENT_REQUIREMENTS.items():
+        path = root / relative_path
+        if not path.is_file():
+            continue
+        try:
+            _, body = parse_mirror(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, WikiDocsError):
+            continue
+        for section in missing_sections(body, required):
+            errors.append(f"{relative_path} 缺少核心章节：{section}")
+
+
+def check_task_template(errors: list[str], root: Path = ROOT) -> None:
+    path = root / ".gitea" / "issue_template" / "task.md"
+    if not path.is_file():
+        return
+    content = path.read_text(encoding="utf-8")
+    required = (
+        "## 文档影响",
+        "- [ ] 不影响长期文档，原因：",
+        "- [ ] 更新架构与代码地图",
+        "- [ ] 更新业务规则与术语",
+        "- [ ] 更新常见修改或故障排查",
+    )
+    for section in missing_sections(content, required):
+        errors.append(f"单元任务模板缺少：{section}")
+
+
 def check_wiki_mirrors(errors: list[str]) -> None:
     """检查每份本地文档都有显式映射和可追踪的镜像头。"""
 
@@ -70,6 +174,13 @@ def check_wiki_mirrors(errors: list[str]) -> None:
         errors.append(str(exc))
         return
 
+    configured_mappings = {mapping.page: mapping.path for mapping in config.mappings}
+    for page, expected_path in CORE_PAGE_PATHS.items():
+        if configured_mappings.get(page) != expected_path:
+            errors.append(
+                f"核心 Wiki 页面映射缺失或路径错误：{page} -> {expected_path}"
+            )
+
     mapped_paths = {mapping.path for mapping in config.mappings}
     actual_paths = {
         path.relative_to(ROOT).as_posix() for path in (ROOT / "docs").rglob("*.md")
@@ -112,6 +223,8 @@ def main() -> int:
     check_required_files(errors)
     check_project_profile(errors, warnings, args.strict)
     check_wiki_mirrors(errors)
+    check_core_documents(errors)
+    check_task_template(errors)
     check_archives(errors)
 
     for warning in warnings: