Skip to content

文档维护规范

本项目把文档视为实验系统的一部分。代码入口、配置、评测口径和论文事实变化时,文档必须能指出“哪一层发生了变化”。

信息来源优先级

  1. 当前仓库代码与测试:解释“本项目实际做什么”;
  2. 当前 Gin 配置:解释默认可运行实验,不把 Python 默认值误写成实验默认值;
  3. results.json、日志和 BENCHMARKS.md:解释本仓库实际结果;
  4. 论文原文及附录:解释作者提出了什么;
  5. 作者/机构官方代码:补足论文未写清的实现细节;
  6. 二手文章只用于发现线索,不作为关键数字的唯一证据。

当论文与本仓库不一致时,必须并列写清“论文设定”和“本仓库实现”,不能为追求叙述平滑而混为一体。

模型页固定结构

每个模型页至少包含:

  1. 一句话定位与状态卡;
  2. 论文与官方实现来源;
  3. 输入、输出和 item 表示;
  4. 核心机制及必要公式;
  5. 从数据集到指标的端到端流程;
  6. 代码文件、类和函数映射;
  7. 当前配置与可直接复制的命令;
  8. checkpoint、缓存和外部模型依赖;
  9. 评测口径;
  10. 与论文差异、已知限制和失败证据;
  11. 调试/扩展建议;
  12. 参考文献。

新页面可复制模型文档模板。

状态声明

不要只写“支持”。使用可验证的状态组合,例如:

代码:完整链路
评测:item-level full catalog
复现:历史 checkpoint 待按新口径重评
最近核验:2026-08-30

禁止以下写法:

  • “SOTA”“显著提升”但没有数据集、口径和来源;
  • “与论文一致”但未列出核验项;
  • 把 SID-level、sampled-negative、in-batch 与 full-catalog 指标放进同一列;
  • 把 tokenizer 当作独立推荐模型计数;
  • 用当前默认配置解释历史 checkpoint,却不记录历史配置;
  • 从旧日志复制结果但不保留来源路径。

时间与版本

  • 领域目录首页记录**资料检索截止日期**,避免“最新”成为永久承诺;
  • 模型页只在行为发生变化时更新“最近核验”,不为无内容改动刷日期;
  • 不稳定结论写“截至 YYYY-MM-DD”;
  • 未来论文或尚未公开工作标为 preprint,不提前写会议接收状态;
  • 代码行号容易漂移,文档优先链接文件、类与函数名。

结果变更检查表

结果进入文档前检查:

  • model / split / seed / protocol / metric level 完整;
  • checkpoint 与精确源码 provenance 可定位;
  • valid 选择规则与 test 报告规则明确;
  • SID 模型已报告 collision,并使用 item-level headline;
  • 多 seed 的均值/标准差没有跨协议聚合;
  • 论文数字明确标“论文报告”,本项目数字明确标“本仓库复现”;
  • 失败实验保留诊断与下一步,不只留下最好数字。

文档验证

本地建议执行:

pip install -e ".[docs]"
mkdocs build --strict

提交前还应搜索陈旧状态词和缺失页面:

rg -n "待补充|TODO|训练中|7 种模型|8 种模型" docs/zh
rg -n "^# " docs/zh/models docs/zh/architecture docs/zh/landscape

如果只维护中文,中文是事实的 canonical 版本;英文页允许暂时 fallback,但导航和状态页必须明确英文覆盖不完整,不能宣称双语完全同步。