ploop/docs/design/platform-only-runtime.md

4.3 KiB
Raw Permalink Blame History

PLoop:平台唯一运行入口

状态:已决定(D-021)
日期:2026-08-31
范围:取消 PLoop 面向操作者的 CLI 产品入口,将评测能力收敛为浏览器驱动的平台闭环。

1. 决策目标

PLoop 的用户可见产品只保留 Web 平台。操作者从浏览器选择已登记的 Dataset/SUT、创建 Run、观察状态、取消 Run 和发起重评;不再通过 ploop execute、ploop normalize、ploop evaluate、ploop import-dataset 或 ploop seed-dev 操作产品。

这不等于删除已验证的计算语义:现有 execute.py、normalize.py、evaluate.py 会成为 worker 的内部调用目标。目标 RAG 仍可由服务器登记为受控 CLI 或 SDK adapter,但浏览器和用户都不能提交命令模板、环境变量或宿主路径。

2. 当前态与目标态

当前代码仍处于过渡态:backend/pyproject.toml 暴露 ploop entry point,ploop.cli 同时承载历史文件型执行、operator import 和开发 Demo seed。M2 的只读页面由该 CLI 预先写入合成数据;这只是历史交付证据,不是目标产品路径。

M3 起的目标路径为:

Browser
  → FastAPI CreateRun / CancelRun / ReEvaluate
  → application command + domain aggregate + UoW/outbox
  → Redis job
  → worker claim lease
  → registered adapter
  → execute → normalize → evaluate
  → sealed artifact / read model
  → Browser polling and detail views

API router 只调用 application command;worker 只经 application/domain 推进 Run 与 RunShard。Redis 只是投递和唤醒机制,不能成为状态机或 gold 访问策略的来源。

3. 数据登记与开发 Demo

取消产品 CLI 后,不以公开 HTTP endpoint 替换 import-dataset 或 seed-dev:浏览器上传任意数据、路径或命令仍不在 V1 范围内。

  • 开发 Demo 使用 Compose 的一次性 dev-bootstrap 服务登记全合成 Dataset 与 demo-keyword-rag@dev。该服务直接组合既有 application/importer/infra 代码;它不是 API 进程启动钩子,不在默认 make check、CI、前端构建或 API factory 中自动写入数据。
  • 冻结 benchmark 的 operator import 保持服务器侧受控流程,后续与 M5 的真实数据登记一并提供专门的内部 job/container 合同;在此之前不暴露浏览器 mutation。
  • PLOOP_DATABASE_URL、artifact root 与 operator staging root 仍只由运行环境提供,不能进入 OpenAPI、浏览器状态、日志或演示数据。

4. 迁移边界

M3 的前置工作项必须按以下顺序完成:

  1. 将现有三段式函数包装为 worker 可调用的受控执行服务,固定 adapter registry 与安全 ProcessSpec,不再接受用户命令模板。
  2. 建立 CreateRun / CancelRun / ReEvaluate 的 HTTP 与 application 命令、outbox、Redis job、lease/reconcile 和开发 bootstrap 服务。
  3. 在浏览器 → API → worker 的 fake-RAG 闭环通过后,移除 [project.scripts] 的 ploop entry point、backend/src/ploop/cli.py 和 CLI 专属测试;保留计算内核及其单元测试。
  4. 更新所有当前态指南;已完成 M1/M2 工作项中的 CLI 记录保留为历史证据,不改写为新的运行说明。

不得为了提前删除 CLI 而把 seed 写入 API startup,或新增可接收任意 manifest/path/command 的 HTTP endpoint。

5. 验收

  • 安装后不再产生 ploop 可执行命令,源码和测试不再导入 ploop.cli。
  • 默认质量门继续离线、只读,不触发 bootstrap、migration、Redis、worker、真实 RAG 或云服务。
  • 开发 Compose 环境由独立一次性 bootstrap 服务登记仅限全合成 Demo,且可重复执行、不创建 Run。
  • 浏览器创建 demo Run 后,可通过 FastAPI、application、domain、outbox、Redis 与 worker 完成可恢复的执行链;worker 重启和重复投递不绕过 Run/RunShard 领域规则。
  • 受控 adapter 输入与浏览器/API/log/artifact 边界继续满足 gold、private artifact、密钥和宿主路径隔离要求。

6. 关系

本设计细化 V1 平台契约 的部署与异步运行边界,沿用 DDD 设计 的 aggregate、repository 和 worker 职责。它取代 D-020 中“ploop seed-dev 是当前开发 Demo 入口”的未来运行方式,但不否定 M2 已完成的历史验证证据。