ploop/docs/decisions/decisions.md

22 KiB
Raw Blame History

决策记录

本文件按时间记录 PLoop 的范围、口径和架构决定。未经确认的事项明确标为待决,不能被实现假定为已决定。

已决定

D-001:先建立文档化评测契约,再选择或实现运行框架

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:根目录保留项目入口 README.md;设计、数据集、实验契约、参考资料和决策记录放在 docs/。
  • 原因:知识库评测的口径、证据和范围比具体 harness 更先决定结果是否可比较。

D-002:评测结果必须包含可审计 Trace,而非仅最终答案或总分

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:后续 Run 设计应保留版本、检索候选、重排、实际上下文、回答、引用、评分和成本/延迟信息。
  • 原因:需要对“未召回”“召回未使用”“引用错误”“越权”进行独立归因与重评。

D-003:公开 memory benchmark 只作为题型和方法参考

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:不把公开集的厂商/论文分数视为 PLoop 的能力结论;只有同数据、同配置、同评分器下的实跑结果可横向比较。
  • 原因:现有调研已发现 judge、金标、检索预算和定制 harness 会显著改变分数。

D-004:P0 采用“执行 → Trace → 评测”的本地三段式链路

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:先以代码和文件产物实现批量执行某个 RAG、标准化其结果、独立评测标准 Trace;暂不实现平台服务。
  • 原因:执行、结果清洗和评分的口径需独立演进。先把它们的输入/输出契约跑通,后续长任务异步化、批量调度和平台控制面才能不破坏评测语义。

D-005:平台化需求提前约束,但不提前实现

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:P0 从首版起使用 Batch、稳定 Run/Case ID、文件 manifest、原始产物、状态、超时和独立重评;不实现队列、worker、数据库或 Web API。
  • 原因:这些边界足以支持未来异步/批量演进,同时避免在真实运行模式和故障类型尚未收敛时过早建设平台。

D-006:首批公共基准选 CRAG、MultiHop-RAG 与 RGB

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:以 CRAG 覆盖动态 Web/KG 型端到端 RAG,以 MultiHop-RAG 覆盖静态知识库的跨文档检索与推理,以 RGB 覆盖噪声、拒答、信息整合和反事实鲁棒性。
  • 原因:三者都是面向 RAG 的公开学术基准,且彼此的失效模式互补;不将它们的分数合并为单一“通用 RAG 分数”。完整的规模、输入输出、评分和 PLoop 映射见 benchmark-selection.md。

D-007:保留官方评分,另行报告 PLoop 的证据与引用评分

  • 日期:2026-08-28
  • 状态:已决定
  • 决定:每个基准都同时输出其官方 evaluator 结果和 PLoop 的确定性 Trace 评分;报告按 benchmark 与 slice 分开,不以加权平均伪造单一“RAG 总分”。RGB 的 supplied context 绝不计作检索召回,CRAG 没有证据 ID 映射时 citation coverage 标记为 unavailable。
  • 原因:MultiHop-RAG、RGB、CRAG 对“正确”、拒答、证据和动态信息的定义不同。保留原始口径才可与社区比较;保留 Trace 评分才可定位检索、生成、引用或工具层的失效。字段级协议和负例见 benchmark-formats-and-scoring.md。

D-008:P0 首版只执行 MultiHop-RAG 及其中文派生集

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:P0 的首个可运行评测范围收敛为两个独立数据集:上游冻结快照 MultiHop-RAG(英文)与由同一快照离线派生的 MultiHop-RAG-zh(中文)。后者同时翻译 corpus、问题、答案和可对齐的金标证据,保留一一对应的 lineage;两个语料库必须隔离索引、隔离运行、隔离报告。
  • 评分:英文集保留上游官方 retrieval / QA evaluator,并附 PLoop 证据与引用指标;中文集报告与官方 retrieval 指标同语义的派生实现、中文确定性答案指标和 PLoop 指标。中英文分数不平均、不互相替代,只在同一 lineage_case_id 上报告配对差异。
  • 延后:RGB、CRAG 仍保留为已调研的后续候选,不进入 P0 首版执行或通过门槛。
  • 原因:先把一个固定、多跳、带 gold evidence 的完整链路做可复现,才能判断检索、生成和中文化的真实差异;过早并行接入异构基准会让 adapter、Trace 和评分问题相互遮蔽。完整数据与评分语义见 双语数据与评分契约。

D-009:Fuser Lab 作为平台化参考;React 重构 UI,Python 分层不引入 gRPC

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:以 ~/workspace/project/fuser_lab 的评测域信息架构和 Python 分层作为 PLoop 未来平台化参考。前端借鉴其 Dataset / Experiment / Run / Item 明细的用户路径、列表与详情的交互秩序,但一律以 React + TypeScript 重构;不复制其 Vue、Element Plus、Pinia 或业务组件代码。后端借鉴 FastAPI + schema + application service + domain service + repository/infra 的职责分离,但 PLoop 的 API 层直接调用 Python application service,首版不定义 proto、不生成 stub、不部署 gRPC。
  • 边界:P0 维持本地文件产物和三段式 CLI;Kafka worker、ClickHouse trace、RBAC、数据库和 Web UI 都不是这项决定授权的当前实现范围。若未来需要异步服务化,先在稳定 Run/manifest 语义之上添加 job repository / queue adapter,再单独决定是否需要消息总线。
  • 原因:Fuser 已实现评测对象、版本、实验、运行记录和单条下钻的完整参考路径;但其微服务/RPC/基础设施规模远超过 PLoop 当前验证数据契约与评分链的需要。详细核查见 fuser-lab-reference.md。

D-010:第一轮直接交付平台;三段式 CLI 成为平台的执行内核

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:第一轮从“本地 P0 原型”升级为可直接使用的前后端平台。交付 React + TypeScript 管理台、FastAPI HTTP API、PostgreSQL 元数据/状态库、Redis 队列和独立 Python worker;保留并复用 execute → normalize → evaluate 的数据契约、Trace 与 artifact 语义。API 层直接调用 Python application service,不采用 gRPC / proto / stub。
  • 首轮业务范围:只管理冻结的 MultiHop-RAG 与 MultiHop-RAG-zh、平台注册的被测 RAG adapter、异步 Run、Case 明细、评分结果和 re-evaluate。Dataset 在线编辑/任意上传、用户/RBAC/多租户、动态 Web、记忆、Kafka、ClickHouse、LLM judge 不进入第一轮。
  • 运行安全:目标 RAG 只能选择服务器预注册的 CLI/SDK adapter;任何 Web 表单字段不得作为 shell 命令执行。worker 只接收 request 投影和允许的 corpus,gold/翻译内部资料只保留在评分与 artifact 边界内。
  • 关系:本决定取代 D-004、D-005、D-009 中“当前不实现平台/Web/worker”的范围限制;但其 Run/manifest、可重评与不使用 gRPC 的语义继续有效。
  • 原因:数据与评测口径已经明确收敛为双语 MultiHop-RAG。现在直接用平台形态验证真实的批量、异步、可视化排障与结果复核,避免之后再把临时 CLI 生命周期迁移成第二套状态机。完整范围、接口、数据模型与验收条件见 V1 平台契约。

D-011:V1 用 Fuser Lab 的 Run 语义和 Fuser Mate 的 React 工程边界实施

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:V1 保留现有 execute → normalize → evaluate 的 JSONL / manifest / trace / score 作为 worker 的事实来源;平台只在其外层补齐 Dataset/SUT/Run/Shard/EvaluationPass 的持久状态、artifact 索引、Redis 投递、租约恢复和安全投影。Python 采用 FastAPI router → application → domain → infra/ / worker 的直接调用分层,不复制 Fuser Lab 的 gRPC、Kafka 或 ClickHouse。
  • 前端采用 Fuser Mate 已验证的 React 工程边界:按业务收拢、共享 typed API client / layout / UI、React Query、路由级 loading/error boundary,及 logic/component/Playwright/Compose E2E 分层测试。具体目录和状态归属由后续 D-014 细化。前端只重新实现 PLoop 组件与 API 类型,不复制聊天业务、WebSocket/Electron、API envelope、样式或资产。
  • 首个可证明闭环按两个门槛交付:先用 demo-keyword-rag 跑一个确定性 sample,验证异步执行、Trace、评测、下钻与重评;再在冻结的英文 MultiHop-RAG sample 上验证官方/PLoop 指标与 gold 隔离,最后接入中文派生集。全量运行只在 sample 闭环和人工验收之后启动。
  • 原因:Fuser Lab 的 ExperimentService、逐 item 状态推进与条件更新证明了“快照 + 运行项 + 阶段 barrier + 重评”的必要性;Fuser Mate 的 feature/API/layout/test 组织可避免 React 管理台在 Run 增长后失控。完整目录、阶段、API、数据表和验收门见 v1-frontend-backend-delivery-plan.md。

D-012:V1 后端采用 DDD;领域对象使用充血模型

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:PLoop 的核心业务对象采用 DDD 的 bounded context、aggregate root、entity、immutable value object、domain event 和 repository port。DatasetVersion、SutVersion、Run、RunShard、EvaluationPass、Artifact 的状态改变和不变量必须由领域方法表达;application service 只做命令编排、事务、加载/保存 aggregate 和发布已提交事件,不能以 if status == ... 形式承载领域规则。
  • 充血边界:这是“所有领域模型充血”,不是把每个 Python class 都塞进方法。Pydantic request/response、SQLAlchemy persistence model、Redis/outbox job、OpenAPI type、报表/列表 projection 和外部 JSONL 都是边界/技术数据结构,保持简单且不得泄漏进 domain。domain 不依赖 FastAPI、SQLAlchemy、Redis、subprocess 或 artifact 文件系统。
  • 一致性:Run 只拥有生命周期、不可变快照和全局阶段;每个 RunShard 独立拥有 lease/attempt/执行结果,避免将大量 Case 装进一个大 aggregate。run_cases 和 evaluation_case_results 是由密封 Trace/score 建立的读模型,不是可任意修改的领域实体。跨 aggregate 的队列推进通过 domain event + 事务 outbox/job 进行,Redis 仅负责已提交事件的投递和唤醒。
  • 原因:评测平台具有不可变快照、阶段 barrier、取消/重试、artifact seal、gold 隔离和重评等不断演进的业务约束,适合充血模型;但列表查询、ORM 映射和 worker 运行时是技术复杂度,不应伪装成领域行为。详细模型和迁移规则见 ddd-rich-domain-model.md。

D-013:建立 pkg/ 公共包与可执行的工程质量/CI/CD 门

  • 日期:2026-08-31
  • 状态:已决定
  • pkg/:在 backend/src/ploop/pkg/ 建立跨层公共、可复用且无业务语义的叶子包。它只承载纯序列化/hash/time helper、日志/observability context、redaction 和测试 helper;不得承载 aggregate、业务 value object、repository base CRUD、FastAPI schema、SQLAlchemy PO 或 Redis client。domain/ 只能按白名单依赖其中无框架/无 I/O 的 pkg/kernel/;其余层可依赖适用公共包,但 pkg/ 不能反向导入 api、application、domain、infra、worker。
  • 质量门:以根目录 Makefile 和 scripts/ 为唯一命令入口,CI 与本地使用同一组只读检查:格式、lint、类型、单元/集成测试、OpenAPI→前端类型契约、数据库迁移、Docker Compose E2E、artifact/gold 泄漏扫描,以及 AST 结构/依赖/危险调用检查。禁止 CI 自动修改并提交代码;修复应由显式 make fmt 完成。
  • CI/CD:PR 只使用 demo/fake RAG 和 fixture,不使用真实 RAG、LLM token、private gold 或生产数据;main/nightly 才运行更重的 Compose/基准 sample 检查。release tag 只产生版本化、可追溯镜像和 release manifest;实际 registry 发布、数据库迁移和任何环境部署须有已确认目标与人工批准,不能由当前仓库自动推断。
  • 参考与差异:借鉴 Fuser Lab 的 backend-ci skill、结构/边界/Service 检查、Makefile、hooks 与 release script 的“规范可执行化”;不复制其 proto 生成、gRPC 约束、BaseDO/BaseRepo 泛 CRUD 或自动修复并 re-stage 的提交钩子。完整设计见 engineering-quality-ci-cd.md。

D-014:V1 前端采用轻量领域分层与三类状态归属

  • 日期:2026-08-31
  • 状态:已决定
  • 目录:前端使用 app → pages → widgets → features → entities → shared 的轻量分层。entities 承担 Dataset/SUT/Run/RunCase/EvaluationPass 的安全读模型、DTO adapter、query key 和 read query;features 承担 create/cancel/re-evaluate、受控表单、筛选与 Case URL 状态等单一用户动作;widgets 承担 Run 总览、指标表、Case 表/抽屉等业务展示;pages 只做路由组合;app/shell 只提供全局框架和导航。并非每个小组件都必须独立成层,只有存在稳定复用或独立演进理由才提升。
  • 状态归属:React Query 是唯一的服务端状态缓存;可分享的筛选、分页、case 和 tab 放 URL;Dialog、pending、未提交表单草稿等短暂状态留在本地组件。V1 不引入 Redux/Zustand 等全局 store。Run list/detail 只在非终态时以 HTTP 轮询刷新,终态自动停轮询;创建、取消、重评以后端确认和精确 query invalidation 为准,不做乐观 phase 迁移。
  • 合同与安全:FastAPI OpenAPI 生成 transport 类型,但 UI 不直接依赖生成物;entity adapter 只向浏览器提供 API 的安全 projection。gold、private artifact、翻译内部资料和 host path 不得进入 API response、query cache、URL、日志或前端 fixture。AppShell 不读取具体 Run、保存 Case drawer 选择或承载页面 mutation,避免演变为全局业务 controller。
  • 原因:Fuser Mate 的 feature/client/query/boundary/test 组织值得继承,但其复杂工作区 controller 和部分 rail 数据读取不适合 PLoop 的长时 Run、轮询、Case 下钻和证据隔离。此分层既保留必要的领域边界,也避免在第一轮引入完整 FSD 的额外仪式。详见 frontend-architecture.md。

D-015:V1 前端改用页面优先的作用域控制

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:为让人和后续 AI 修改时尽量局限影响面,目录的第一落点从 D-014 的全局 entity/feature/widget 分层调整为 pages/<业务域>/<路由页>/。一个页面专属的 endpoint、DTO adapter、query/mutation、URL state、业务组件和局部测试必须与该页面同目录;不同路由页不得互相导入内部文件。
  • 全局边界:shared/api 只承载 HTTP transport、OpenAPI generated 类型、跨页失效必需的 cache-key factory,以及已被两个以上路由实际使用的 endpoint;shared/ui/shared/lib 只承载无评测业务名词的 UI primitive/纯工具。没有第二个真实消费者的 API/工具不能以“未来复用”为由提前全局化。
  • 局部提升:同一业务域的两个以上页面稳定复用、但不适合全站复用时,提升到 pages/<业务域>/_shared/;跨域复用且无业务语义时才进入 shared/。重复少量局部代码优于建立模糊全局耦合。
  • 保留:D-014 中 React Query/URL/本地状态三类归属、无全局 Run store、后端确认 mutation、安全 projection、gold 隔离和 AppShell 不持有 Run 状态的规则继续有效;被本决定替换的仅是目录第一落点。完整目录和质量门见 frontend-architecture.md。
  • 原因:Fuser Lab 的实际前端把 pages/observe/trace/apis、pages/context/dataset/apis 与相应页面就近组织,而全局仅有 http/axios、common/utils、common/components 等能力;这种结构更适合用目录边界约束 AI 的改动范围。

D-016:文档按单一事实归属维护;内部中文单源,发布面按需双语

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:docs/AGENTS.md 定义文档归属和维护规则。计划状态只在 plan/TODO.md,设计契约在 design/,取舍在 decisions/,外部观察在 reference/,可复现操作在 guides/;上层链接到事实所有者而不复制。内部文档以中文为单一权威来源,不引入全仓英中配对。未来只有明确公开且承诺双语的发布子树,才建立成对文档与 CI 配对校验;文档站只能从归属目录的 Markdown 显式投影。
  • 原因:借鉴 DeepSeek Harness 的“one home per fact”和文档质量门,同时避免首轮因站点、翻译三件套和专项脚本增加无效维护成本。M0a 实现不联网的 make check-docs,检查仓库内相对 Markdown 路径与锚点;站点 build、翻译配对和示例编译随真实发布面出现后再增加。

D-017:根目录是 monorepo 编排层;应用代码分置 backend/ 与 frontend/

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:Python 后端的包、测试、示例、FastAPI、worker、Alembic 和后端锁文件都位于 backend/,源码根为 backend/src/ploop/;React、Node 配置、lockfile、页面源码和浏览器测试都位于 frontend/,源码根为 frontend/src/。根目录只放跨包编排与共享材料,例如 README.md、docs/、根 Makefile、scripts/、deploy/ 和 Compose 配置;不放 Python src/、pyproject.toml、tests/ 或 Node package.json。
  • 执行:现有 P0 Python 原型已迁入 backend/ 并保持 CLI/测试语义。根 Makefile 通过明确的 backend/ 与 frontend/ 工作目录调用各自工具;不以根目录包或隐式 PYTHONPATH 串联前后端。
  • 原因:PLoop 是前后端独立演进、独立锁定依赖、由根质量门统一编排的 monorepo。显式包边界降低 AI 修改的影响范围,避免 Python/Node 配置、测试和构建产物在根目录互相污染。

D-018:AI 开发以“需求 → 架构 → 计划 → 验证”为强制追踪链

  • 日期:2026-08-31
  • 状态:已决定
  • 决定:requirements/ 是用户目标、范围、非目标和验收的唯一来源;design/ 和 D-* 记录机制与取舍;plan/ 记录里程碑、工作项和实时 TODO;追踪矩阵 连接四者。每个非平凡 AI 实施必须关联 R-*、设计/决策、M*/W-* 和实际验证证据。根 AGENTS.md 要求 AI 在开始时读取这些入口,并限定于当前工作项允许的路径。
  • 人工关口:用户结果/验收、架构边界、公开合同、gold/secret、外部依赖、真实 RAG 成本、部署或不可逆操作的变化必须升级为需求或决策并由项目负责人确认;已确认范围内的局部实现和验证由 AI 自主推进。
  • 原因:团队会持续用 AI 推动开发。通过小工作项、唯一状态台账和可复现证据,既避免 AI 从模糊愿望跳到大范围改动,也不把低风险实现变成反复审批。

D-019:M0a 开发环境直接使用受控云中间件;Docker Compose v2 保留为后续本地编排前提

  • 日期:2026-08-31
  • 状态:已决定(项目负责人确认)
  • 决定:M0a 的开发 PostgreSQL 和 Redis 直接使用项目负责人提供的云服务。连接信息只保存于仓库根 .env,该文件必须被 Git 忽略;.env.example 只声明字段和非敏感端口,不包含真实主机、用户名或密码。Docker Compose v2 作为本机工具安装并验证,但本工作项不创建或启动本地 PostgreSQL/Redis 容器。
  • 访问与安全:云服务连通性只能由显式 make check-dev-services 触发;该命令仅作超时受限的 TCP 检查,不输出凭据、不执行 SQL、不写数据库、不清 Redis。make check、CI 和任何真实 RAG 工作流都不得读取 .env 或访问这些云服务。
  • 关系:本决定细化当前 M0a 的开发依赖来源,不替代 V1 后续完整平台的 Docker Compose/E2E 目标;待 API、worker 与迁移存在后,再为自包含的本地服务编排建立独立工作项。
  • 原因:开发环境已有受控云中间件,重复启动本地服务会引入不必要的状态分叉;同时保留 Compose v2 工具前提,避免未来完整本地闭环被宿主缺少插件阻塞。

已收敛的历史问题

Q-001:第一轮的系统边界

已由 D-010 收敛:第一轮只评固定知识库 RAG 的摄取、检索、回答、引用、拒答、异步运行与重评;不含多知识空间/权限、持久记忆、写入、删除或动态 Web。后续若扩展这些能力,新增决策而不是修改本轮 Run 的含义。

待项目负责人确认

Q-002:首批被测系统与接入边界

需提供首个真实 RAG 的调用方式(API 包装命令、SDK 包装命令或完整产品 CLI)以及是否能够导出检索与引用 Trace。P0 可先按批量 JSONL 命令协议接入。

Q-003:P0 的通过门槛与优先级

需确认哪类失败是阻断项(例如跨域泄漏必须为零),以及准确性、引用、延迟和成本之间的目标取舍。

变更规则

  • 一项待决问题获得确认后,新增对应的 D-* 条目,不改写历史。
  • 任何影响数据、提示词、模型、检索预算或评分器的变更,均应视为新的实验版本。