diff --git a/AGENTS.md b/AGENTS.md index 5595285..537665e 100644 --- a/AGENTS.md +++ b/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 折叠块 `
/` 结构 | 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 引用语料路径和锚点检查 diff --git a/README.md b/README.md index 5fdb536..d8151a9 100644 --- a/README.md +++ b/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` | diff --git a/scripts/README.md b/scripts/README.md index 03a9772..bf9f1f3 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -6,7 +6,7 @@ - `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。 - `check-markdown-details.py`：仓库内 Markdown `
/` 折叠块结构检查脚本。 -- `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 引用语料路径和锚点检查脚本。 diff --git a/scripts/check-doc-structure.py b/scripts/check-doc-structure.py index 242ea2e..f27f72c 100644 --- a/scripts/check-doc-structure.py +++ b/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" 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: