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