9.4 KiB
9.4 KiB
文档索引
这里保存 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 合同与页面骨架实施计划 | 已完成 |
| 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 与安全页面边界 | 已完成 |
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 与安全投影合同 | 已决定 |
| 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 | 本地示例 RAG 的完整运行方式 | 初版 |
| 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,不能复制维护。
- 将外部或上游资料视为带日期的参考;采用前重新核对其版本、协议和可运行性。