44 lines
1.9 KiB
Python
44 lines
1.9 KiB
Python
"""校验接口文档权威性与 docs 编号唯一性（TODO T0.2）。
|
||
|
||
原实现只打印一行结论、从不失败，等于没有检查。现在它会真正拦截三类问题：
|
||
|
||
1. 缺少唯一权威接口文档 `docs/05-接口文档.md`；
|
||
2. 废弃稿没有明确历史标记，或未归档到 `99-` 前缀；
|
||
3. `docs/` 下出现两份同编号文档——历史上出现过两份 `05` 与两份 `15`，
|
||
会直接误导实现（错误码、路径、SSE 三个维度都可能被带偏）。
|
||
"""
|
||
|
||
from collections import defaultdict
|
||
from pathlib import Path
|
||
|
||
ROOT = Path(__file__).resolve().parents[1]
|
||
docs = ROOT / "docs"
|
||
canonical = docs / "05-接口文档.md"
|
||
deprecated = docs / "99-已废弃-公共Agent平台接口规范.md"
|
||
legacy_deprecated = docs / "05-公共Agent平台接口规范.md"
|
||
|
||
if not canonical.exists():
|
||
raise SystemExit("缺少唯一权威接口文档：docs/05-接口文档.md")
|
||
|
||
if deprecated.exists():
|
||
text = deprecated.read_text(encoding="utf-8")
|
||
if not any(marker in text for marker in ("历史稿", "已废弃", "废弃声明")):
|
||
raise SystemExit("废弃接口文档没有明确历史标记")
|
||
if legacy_deprecated.exists():
|
||
text = legacy_deprecated.read_text(encoding="utf-8")
|
||
if not any(marker in text for marker in ("历史稿", "已废弃", "废弃声明")):
|
||
raise SystemExit("历史接口文档没有明确废弃标记")
|
||
|
||
by_number: dict[str, list[str]] = defaultdict(list)
|
||
for path in sorted(docs.glob("*.md")):
|
||
if path == legacy_deprecated:
|
||
continue
|
||
by_number[path.name.split("-", 1)[0]].append(path.name)
|
||
|
||
collisions = {number: names for number, names in by_number.items() if len(names) > 1}
|
||
if collisions:
|
||
raise SystemExit(f"docs 编号撞车：{collisions}")
|
||
|
||
print(f"authoritative interface document: {canonical.name}")
|
||
print(f"checked {sum(len(names) for names in by_number.values())} documents, no number collision")
|