docs: split docs readmes into topic files

scripts/AGENTS.md

@@ -7,7 +7,7 @@
 - 脚本默认从仓库根目录运行，路径解析必须稳定。
 - 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile` 和根目录 `AGENTS.md` 的命令清单；只有 CI 环境稳定具备所需输入时才纳入 CI。
 - `check-directory-docs.py` 对根 `.github/` 只要求 `AGENTS.md`，不要重新补 `.github/README.md`。
-- 修改 docs 线性 README 的主章节或锚点后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。
+- 修改 docs README 或主题正文的主章节、锚点、索引后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。
 - 修改 GitHub Wiki 独立仓库后，运行 `make check-wiki WIKI_DIR=/path/to/wiki`；不要把 Wiki checkout 提交进主仓。
 - 检查失败输出应包含文件路径、行号或可定位的错误信息。
 - 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。

scripts/README.md

@@ -6,9 +6,9 @@
 
 - `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。
 - `check-markdown-details.py`：仓库内 Markdown `<details>/<summary>` 折叠块结构检查脚本。
-- `check-doc-structure.py`：`docs/` 线性 README 的标准块顺序、主章节顺序、重复锚点与细粒度目录入口检查脚本。
+- `check-doc-structure.py`：`docs/` README 的标准块顺序、目录入口、重复锚点与细粒度目录入口检查脚本。
 - `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本；根 `.github/` 仅要求 `AGENTS.md`，避免 GitHub 首页误展示平台配置说明。
 - `check-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。
 - `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。
 - `check-wiki.py`：GitHub Wiki 独立仓库本地 checkout 的页面覆盖、内链和旧口径检查脚本。
-- `sync-doc-toc.py`：根据 `metadata/taxonomy.yml` 和文档锚点重建 docs 线性 README 的完整细粒度目录。
+- `sync-doc-toc.py`：兼容旧线性 README 的细粒度目录生成脚本；当前拆分结构下通常无变更。

scripts/check-doc-structure.py

@@ -220,9 +220,6 @@ def main() -> int:
         errors.extend(duplicate_manual_anchors(markdown_file))
 
     doc_readmes = doc_readmes_from_taxonomy()
-    if not doc_readmes:
-        errors.append("metadata/taxonomy.yml: no docs README anchors found under documents")
-
     for rel_path, expected_anchors in doc_readmes.items():
         path = ROOT / rel_path
         if not path.exists():
@@ -230,10 +227,19 @@ def main() -> int:
             continue
         errors.extend(check_linear_readme(path, expected_anchors))
 
-    docs_index = ROOT / "docs" / "README.md"
-    if docs_index.exists():
-        text = strip_fenced_code(docs_index.read_text(encoding="utf-8", errors="ignore"))
-        errors.extend(check_standard_readme_blocks(docs_index, text))
+    readme_paths = {Path("docs/README.md")}
+    for fields in taxonomy_sections().values():
+        entry = fields.get("entry", "")
+        if entry.startswith("docs/") and entry.endswith("/README.md"):
+            readme_paths.add(Path(entry))
+
+    for rel_path in sorted(readme_paths):
+        path = ROOT / rel_path
+        if not path.exists():
+            errors.append(f"{rel_path}: missing docs README")
+            continue
+        text = strip_fenced_code(path.read_text(encoding="utf-8", errors="ignore"))
+        errors.extend(check_standard_readme_blocks(path, text))
 
     errors.extend(check_docs_index())
 

scripts/sync-doc-toc.py

@@ -122,7 +122,12 @@ def main() -> int:
     changed: list[str] = []
     errors: list[str] = []
 
-    for rel_path, main_anchors in doc_readmes_from_taxonomy().items():
+    doc_readmes = doc_readmes_from_taxonomy()
+    if not doc_readmes:
+        print("OK synced docs TOC blocks: 0 changed")
+        return 0
+
+    for rel_path, main_anchors in doc_readmes.items():
         path = ROOT / rel_path
         if not path.exists():
             errors.append(f"{rel_path}: missing docs README")