chore: enforce docs readme block order

AGENTS.md

@@ -66,7 +66,7 @@ git push origin develop
 | `make lint` | 校验全仓库 Markdown | Node.js 22+；通过 `npx --yes markdownlint-cli@0.48.0` 执行 |
 | `make check-links` | 校验仓库内 Markdown 相对链接 | Python 3 |
 | `make check-details` | 校验 Markdown 折叠块 `<details>/<summary>` 结构 | Python 3 |
-| `make check-doc-structure` | 校验 docs 线性 README 主章节顺序、重复锚点与目录入口 | Python 3 |
+| `make check-doc-structure` | 校验 docs 线性 README 标准块顺序、主章节顺序、重复锚点与目录入口 | Python 3 |
 | `make check-directory-docs` | 校验仓库自有目录 README/AGENTS 覆盖 | Python 3 |
 | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 |
 | `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 |
@@ -228,7 +228,7 @@ git push origin develop
 - `.github/workflows/ci.yml` - GitHub Actions：develop/master 分支 markdown-lint + link-checker
 - `scripts/check-local-links.py` - 仓库内 Markdown 相对链接与锚点检查脚本，供 `make check-links` 与 CI 使用
 - `scripts/check-markdown-details.py` - 仓库内 Markdown 折叠块结构检查脚本，供 `make check-details` 与 CI 使用
-- `scripts/check-doc-structure.py` - docs 线性 README 主章节顺序、重复锚点与目录入口检查脚本，供 `make check-doc-structure` 与 CI 使用
+- `scripts/check-doc-structure.py` - docs 线性 README 标准块顺序、主章节顺序、重复锚点与目录入口检查脚本，供 `make check-doc-structure` 与 CI 使用
 - `scripts/check-directory-docs.py` - 仓库自有目录 README/AGENTS 覆盖检查脚本，供 `make check-directory-docs` 与 CI 使用
 - `scripts/check-metadata.py` - metadata 路径与锚点检查脚本，供 `make check-metadata` 与 CI 使用
 - `scripts/check-ai-citation.py` - llms 与 AI 引用语料路径和锚点检查脚本，供 `make check-ai-citation` 与 CI 使用
@@ -281,7 +281,7 @@ feat|fix|docs|chore|refactor|test: scope - summary
 1. `markdown-lint` - Markdown 格式检查
 2. `check local markdown links and anchors` - 仓库内相对链接与锚点检查
 3. `check markdown details and summaries` - Markdown 折叠块结构检查
-4. `check docs README structure` - docs 线性 README 主章节顺序、重复锚点与目录入口检查
+4. `check docs README structure` - docs 线性 README 标准块顺序、主章节顺序、重复锚点与目录入口检查
 5. `check required directory README and AGENTS files` - 仓库自有目录 README/AGENTS 覆盖检查
 6. `check metadata paths and anchors` - metadata 路径与锚点检查
 7. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查

README.md

@@ -220,7 +220,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 | 全仓 Markdown lint | `make lint` | `Makefile` + `.github/lint_config.json` |
 | 本地相对链接检查 | `make check-links` | `scripts/check-local-links.py` |
 | 折叠块结构检查 | `make check-details` | `scripts/check-markdown-details.py` |
-| docs 线性目录结构检查 | `make check-doc-structure` | `scripts/check-doc-structure.py` |
+| docs 线性目录结构检查 | `make check-doc-structure` | 校验标准块顺序、主章节顺序、锚点和目录入口 |
 | 目录 README/AGENTS 覆盖检查 | `make check-directory-docs` | `scripts/check-directory-docs.py` |
 | Metadata 路径检查 | `make check-metadata` | `scripts/check-metadata.py` |
 | AI 引用路径检查 | `make check-ai-citation` | `scripts/check-ai-citation.py` |

scripts/README.md

@@ -6,7 +6,7 @@
 
 - `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 引用语料路径和锚点检查脚本。

scripts/check-doc-structure.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Check docs README structure, stable anchors and duplicate manual anchors."""
+"""Check docs README standard blocks, stable anchors and duplicate manual anchors."""
 
 from __future__ import annotations
 
@@ -17,6 +17,13 @@ SKIP_PREFIXES = [
 ]
 ANCHOR_PATTERN = re.compile(r"<a\s+id=[\"']([^\"']+)[\"']")
 SUMMARY_LINE = "<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>"
+STANDARD_README_BLOCKS = [
+    ("顶部标题块", re.compile(r"^#\s+.+$", re.MULTILINE)),
+    ("字多不看", re.compile(r"^##\s+字多不看\s*$", re.MULTILINE)),
+    ("快速导航", re.compile(r"^##\s+快速导航\s*$", re.MULTILINE)),
+    ("完整细粒度目录", re.compile(re.escape(SUMMARY_LINE))),
+    ("使用方式", re.compile(r"^##\s+使用方式\s*$", re.MULTILINE)),
+]
 
 
 def strip_fenced_code(text: str) -> str:
@@ -69,6 +76,8 @@ def check_linear_readme(path: Path, expected_anchors: list[str]) -> list[str]:
     text = strip_fenced_code(path.read_text(encoding="utf-8", errors="ignore"))
     errors: list[str] = []
 
+    errors.extend(check_standard_readme_blocks(path, text))
+
     if "完整细粒度目录（点击展开/收起）" not in text:
         errors.append(f"{rel}: missing collapsible full fine-grained table of contents")
 
@@ -107,6 +116,33 @@ def check_linear_readme(path: Path, expected_anchors: list[str]) -> list[str]:
     return errors
 
 
+def check_standard_readme_blocks(path: Path, text: str) -> list[str]:
+    """Validate the standard top-level README block order used under docs/."""
+    rel = path.relative_to(ROOT)
+    errors: list[str] = []
+    positions: list[tuple[str, int]] = []
+
+    for block_name, pattern in STANDARD_README_BLOCKS:
+        match = pattern.search(text)
+        if match is None:
+            errors.append(f"{rel}: missing standard README block '{block_name}'")
+            continue
+        positions.append((block_name, match.start()))
+
+    if len(positions) != len(STANDARD_README_BLOCKS):
+        return errors
+
+    previous_name, previous_pos = positions[0]
+    for block_name, position in positions[1:]:
+        if position <= previous_pos:
+            errors.append(
+                f"{rel}: standard README block '{block_name}' must appear after '{previous_name}'"
+            )
+        previous_name, previous_pos = block_name, position
+
+    return errors
+
+
 def active_toc_text(text: str) -> str:
     in_fence = False
     fence_marker = ""
@@ -180,6 +216,11 @@ 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))
+
     errors.extend(check_docs_index())
 
     if errors: