group_fqcd_jr/tools/check_authoritative_docs.py

"""校验接口文档权威性与 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")