ploop/docs/README.md
2026-08-31 20:48:43 +08:00

10 KiB
Raw Permalink Blame History

文档索引

这里保存 PLoop 的设计记录、基准资料、外部参考和决策历史。根目录 README.md 是项目入口;本文件是 docs/ 的唯一分类导航。

所有在 docs/ 下新增或移动的文档遵守 文档贡献约定:先确定事实归属,再链接而不是复制;内部文档当前以中文单源维护。

docs/
├─ plan/         当前执行计划、TODO 与里程碑
├─ requirements/ 用户目标、范围、非目标与验收条件
├─ design/       PLoop 自己的架构、契约与运行时设计
├─ benchmarks/   公共数据集、格式、评分与对比资料
├─ reference/    外部项目和调研的观察记录
├─ decisions/    已拍板的决策与变更历史
└─ guides/       面向使用者的操作文档

requirements:需求与验收

文档 用途 状态
README.md 需求编号、状态与索引 活跃
R-001 V1 平台的用户结果、范围、非目标和验收 已确认
R-002 AI 驱动开发的可控、可追溯工作流 已确认

plan:计划与执行状态

文档 用途 状态
TODO.md 当前执行任务、状态、证据、阻塞项与下一步;实施进度唯一台账 活跃
v1-frontend-backend-delivery-plan.md 从工程骨架到双语 MultiHop-RAG 首个真实 Run 的实施顺序、契约与验收门 已决定
m0a-toolchain-quality-gates-plan.md M0a 依赖锁定、前端壳、check-docs 与统一质量门 已完成
m0a-cloud-dev-services-plan.md M0a 受控云中间件环境、显式连通性检查与 Compose v2 前提 已完成
m0b-executable-architecture-checks-plan.md M0b 后端 AST 架构与危险调用检查 已完成
m1-domain-foundation-plan.md M1 的 domain、持久化、artifact store 与 operator importer 分段实施计划 进行中
m2-readonly-control-plane-plan.md M2 只读 API、开发 Demo、OpenAPI 合同与页面骨架实施计划 已完成
m3-platform-runtime-and-cli-cutover-plan.md M3 的 Run command、outbox、worker、页面、bootstrap 与 CLI 切除实施顺序 待开始
document-structure-refactor-plan.md 当前 V1 契约与历史原型的迁移计划 已完成
traceability.md 需求 → 架构/决策 → 计划/工作项 → 验证证据的导航 活跃
work-items/README.md 非平凡 AI 实施的最小工作包模板与状态约定 活跃
W-M0a-01 已完成的 monorepo 前后端包边界迁移 已完成
W-M0a-02 当前 V1 契约与历史 P0 原型的边界收敛 已完成
W-M0a-03 依赖锁定、前端壳与统一质量门 已完成
W-M0a-04 云开发中间件环境与 Compose v2 前提 已完成
W-M0b-01 可执行架构与危险调用检查 已完成
W-M1-01 领域 aggregate、值对象、事件与 repository port 已完成
W-M1-02 mapper/UoW、Alembic 初始 schema 与 local artifact store 阻塞
W-M1-03 operator importer、安全 catalog seed 与 M2-safe query seam 阻塞
W-M2-01 只读控制面、全合成开发 Demo 与安全页面边界 已完成
W-M2-02 前端静态 import AST 解析正确性修复 已完成
W-M3-01 平台运行时、受控 fake Run 与 CLI 切除 待开始

design:架构、契约与运行时

文档 用途 状态
evaluation-framework.md 评什么、如何拆分指标、整体运行链路 初版
experiment-contract.md Case、Run、Trace 与评分产物的最小契约 初版
v1-platform-contract.md 第一轮平台范围、总体架构、异步 Run、页面/API 与验收 已决定
multihop-rag-bilingual-contract.md 英文/中文派生集的翻译、运行、评分与验收契约 已决定
frontend-architecture.md 页面优先目录、全局/页面 API 边界、按需提升与质量门 已决定
ddd-rich-domain-model.md DDD 边界、聚合根、充血模型、事件、仓储与 application/infra 职责 已决定
engineering-quality-ci-cd.md pkg/、Makefile/scripts、代码调用检查、CI/CD 已决定
m0b-executable-architecture-checks.md M0b 后端 AST 检查、P0 兼容例外与规则升级条件 已确认
m2-readonly-control-plane.md M2 只读 API、页面骨架、开发 Demo 与安全投影合同 已决定
platform-only-runtime.md 平台唯一入口、CLI 迁移、开发 bootstrap 与 worker 内核边界 已决定
legacy/p0-runtime-prototype.md 现有三段式 CLI 原型的历史行为说明 历史原型
legacy/p0-synthetic-dataset-and-cases.md 早期合成数据与案例探索 历史探索

benchmarks:公共评测资料

文档 用途 状态
benchmark-selection.md 已选公共 RAG 基准、规模、评分与接入流程 初版
benchmark-formats-and-scoring.md 三个基准的字段级 I/O、官方评分与 PLoop 映射 初版
standard-rag-benchmark-alternatives.md MultiHop-RAG 的标准文档型 RAG 替代/补充基准 待决建议
kilt-and-crud-rag-contracts.md KILT、CRUD-RAG 的数据形态、被测接口和官方评分 待决建议
crud-rag-six-task-contracts.md CRUD-RAG 六类任务的字段、接口、官方评分与 PLoop 补充 待决建议
crud-rag-reported-results.md CRUD-RAG 官方基线结果与可比性边界 资料快照
gold-evidence-benchmarks.md 有明确 supporting evidence/provenance 的评测集筛选 待决建议
hotpotqa-contract.md HotpotQA-fullwiki 的字段、RAG I/O、官方评分与映射 待决建议
multihop-rag-vs-crud-rag.md MultiHop-RAG 与 CRUD-RAG 的知名度、I/O、评分和边界对比 待决建议
multihop-rag-leaderboard-and-adoption.md MultiHop-RAG 榜单、采用论文与可比性边界 资料快照

reference:外部参考与调研

文档 用途 状态
fuser-lab-reference.md Fuser Lab 的 UI、Python 评测链路、可借鉴点与不照搬边界 资料快照
fuser-mate-react-reference.md Fuser Mate 的 React 工程组织、测试与 PLoop 采用边界 资料快照
reference-research.md Harbor、记忆评测和 MemoryLake 调研的可借鉴结论 资料快照
deepseek-harness-docs-reference.md DeepSeek Harness 的文档分层、站点投影、双语契约和自动质量门 资料快照

decisions:决策

文档 用途 状态
decisions.md 已决定、待决定和变更记录 活跃

guides:使用说明

文档 用途 状态
quickstart.md 当前平台入口与 M3 迁移边界 活跃
ai-development-workflow.md AI 从需求到代码验证的分流、关口与交付流程 活跃
cloud-dev-services.md 云 PostgreSQL/Redis 开发配置、显式连通性检查与安全边界 活跃

维护约定

  • 新的架构选择、指标口径或数据集变更,先更新 decisions/decisions.md,再改对应设计文档。
  • 新的用户目标、范围、非目标或验收条件先更新 requirements/;需求、架构、计划与验证的导航由 plan/traceability.md 维护。
  • 实施进度只更新 plan/TODO.md;完成项必须关联 Case、数据版本、被测系统版本、评分器版本或可复现验证证据。
  • 页面、API、契约等 PLoop 自己的规范放 design/;基准调研放 benchmarks/;外部项目的观察放 reference/,不与采用决定混写。
  • 文档的归属、语言边界、与实现同步和最小检查规则以 docs/AGENTS.md 为准;未来文档站只能投影源 Markdown,不能复制维护。
  • 将外部或上游资料视为带日期的参考;采用前重新核对其版本、协议和可运行性。