ploop/docs/AGENTS.md
2026-08-31 15:27:34 +08:00

2.9 KiB
Raw Blame History

PLoop 文档贡献约定

本文是 docs/ 子树的维护规则;根目录 README.md 是项目入口,README.md 是分类导航,plan/TODO.md 是唯一的执行状态台账。

归属:一个事实只有一个家

按读者要解决的问题落位,而不是按文件格式随意新增目录:

内容 唯一归属
用户问题、目标、范围、非目标与用户验收 requirements/
当前实施状态、证据、阻塞与下一步 plan/TODO.md
非平凡 AI 实施的目标、允许路径、验收与完成证据 plan/work-items/
已确认的取舍与原因 decisions/decisions.md
PLoop 自身架构、数据/接口/运行时契约 design/
公共 benchmark 的格式、评分、结果与采用边界 benchmarks/
外部项目或论文的观察,以及可借鉴/不照搬边界 reference/
能由另一位开发者实际复现的操作流程 guides/

上层文档只概述并链接到事实所有者;不要复制字段表、评分口径、架构理由或执行状态。设计文档描述当前机制,决策文档保存取舍,指南提供按步骤验证的操作,参考文档不暗示已被 PLoop 采用。

语言与来源

  • 当前内部文档以中文为单一权威来源,不要求把每份设计/计划翻成英文。
  • 只有明确面向外部发布且承诺双语的文档,才建立英文/中文配对与对应 CI 规则;在此之前不创建半完成的翻译副本。
  • 数据集原文、gold、自动生成的 OpenAPI/JSON Schema 与运行 artifact 的权威来源是冻结数据、生成器或代码。文档只说明版本、派生关系和读取方式,不手抄第二份真值。
  • 仓库内文档相互引用使用相对 Markdown 链接;本机研究快照可以作为证据链接,但不能是 PLoop 运行所依赖的路径。

与实现同步

  • 改变用户结果、范围或验收时,先更新 requirements/;改变公开 API、领域契约、数据格式、评分口径、运行命令或安全边界时,同一变更必须更新其拥有文档、相关 README/guide 和必要的决策记录。
  • 新增或调整任务时更新 plan/TODO.md;没有可复现证据,实施项不得标记为 DONE。
  • 非平凡 AI 实施先创建/更新 plan/work-items/ 中的工作项;它链接需求、设计与验证,TODO 只保存当前状态和入口链接。
  • 文档站若未来启用,Markdown 仍留在其业务归属目录;站点只能由显式清单投影,不能复制维护一套内容。

检查与规模

  • 当前提交至少确认新增/移动的相对链接有效。M0a 已提供 make check-docs,检查仓库内相对路径与 Markdown 锚点,并被 make check 和 CI 调用。
  • 在文档规模尚小时,以清晰的归属和短链为先,不设机械字数预算或全仓文档示例编译。只有相应文档站、双语发布面或生成 API 实际出现后,才针对该子树增加专项检查。