张胜宇
e239eb778b
1) 客服 Agent 四份交付文档 + 构建脚手架：品牌由包装占位 XX科技 / 旧名 南方财富 统一为南方基金（热线 400-889-8899 / 官网 nffund.com），系统名改为「智能服务系统」； 同步追加 §0.4 修订记录行，工程记录行保留原占位字面以支撑硬编码扫描验收。 2) 开发文档：清理 28 份已作废/残留文档（14 份移出归档 + 14 份仓库副本）， 新增《文档规整方案与开发前待决事项-2026-09-17》。 3) 客服agent 四份交付文档首次纳入本分支。
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")
|