# Fuser Lab 参考调研:PLoop 的 UI 与 Python 架构边界 核查日期:2026-08-31。范围是对本机 [`~/workspace/project/fuser_lab`](/Users/pptg/workspace/project/fuser_lab/README.md) 源码的静态阅读;没有启动其前后端、没有连接其数据库或消息队列。因此下文明确区分“源码已观察到”与“PLoop 拟采用”。第一轮已决定直接建设平台,具体落地范围以 [V1 平台契约](../design/v1-platform-contract.md) 为准。 ## 结论 Fuser Lab 是一个合适的**产品信息架构和 Python 分层参考**,特别适合 PLoop 后续从本地文件型 P0 演化出可查看 Run 与单条证据的界面。但它不是可以直接引入的依赖,也不是 PLoop 的目标架构: ```text Fuser UI 的产品路径 → 借鉴并用 React 重构 Fuser Python 的职责分层 → 借鉴,但 API 直接调用 application service Fuser 的 gRPC/proto/stub → PLoop 当前明确不采用 Fuser Kafka/ClickHouse/RBAC → PLoop 当前明确不采用 PLoop P0 的 CLI/manifest → 保持不变,先作为未来服务化的事实来源 ``` ## 1. 已观察到的 Fuser Lab 结构 ### 1.1 前端:以评测工作流组织界面 源码入口是 `frontend/`:Vue 3 + TypeScript + Vite + Pinia + Element Plus,而不是 React。评测路由位于 `frontend/src/router/routes/evaluation.ts`,形成三层对象: ```text 评测 ├─ 评测集 Dataset │ └─ 详情:版本切换、条目、导入/导出、单条历史 ├─ 评估器 Evaluator │ └─ 详情:版本、Judge 配置、Prompt 版本/发布 └─ 实验 Experiment └─ 详情:绑定的评估器、Run 列表、进度刷新、重新评估 └─ Run 条目:输入 / 输出 / reference、执行状态、评分、评估明细 drawer ``` 这不是只展示一个最终分数:在 `experiment/run-items.vue` 中,每个条目显示执行状态、评估状态、最终分和加权分、输出预览、执行错误;再通过侧边 drawer 展示各评估器的记录、原因和 judge 请求/响应。这个“从总览逐层下钻到可解释原始记录”的信息结构与 PLoop 的 Trace 目标高度一致。 目录组织上还观察到另一条可借鉴规则:`pages/observe/trace/` 自己拥有 `apis/index.ts`、`apis/type.ts`、detail components 和页面状态;`pages/context/dataset/` 自己拥有 `apis/`、`components/` 与页面代码。全局层则保留 `http/axios.ts`、`common/utils/`、`common/components/`、layouts 等真正通用的能力。PLoop 不复制其 Vue 文件,但采用同一条“页面专属代码就近放,跨页能力再提升”的作用域原则,详见 [V1 前端架构](../design/frontend-architecture.md)。 ### 1.2 UI 语言与可复用交互模式 源码中的 `layouts/`、`ListPage` 和 `_common.scss` 已体现一套统一后台界面语言: | Fuser 已观察到的模式 | 源码证据 | PLoop 参考方式 | |---|---|---| | 左侧固定导航 + 顶部面包屑/标签页 + 内容区 | `layouts/modes/LeftMode.vue`、`Sidebar`、`NavigationBar` | PLoop 未来管理台采用同类空间划分;菜单按 Dataset、目标 RAG、Run、Artifacts 组织。 | | 轻灰页面底色、白色卡片、8px 圆角、12px 内容边距 | `_common.scss` | 借鉴视觉节奏,不复制 SCSS 或 Element Plus token。 | | 蓝紫主色 `#5b5fc7`、浅色 active state、状态 Tag | `variables.css`、`StatusBadge` | 可作为早期视觉参考;React 实现用自身 token,不承诺完全像素复刻。 | | 列表页 = 标题 + 即时搜索 + 刷新 + 列管理 + 创建动作 + 分页表格 | `ListPage`、`DebouncedSearch`、`ColumnManagerPopover` | PLoop 先做只读 Run 列表;列管理、创建弹窗在真实需要出现时引入。 | | 详情页 = 返回、标题/ID copy、描述卡、版本/Run 表、刷新进度 | `DetailPageHeader`、experiment/detail | PLoop 重点借鉴:Run 状态、耗时、artifact hash、失败数和可重评入口必须同屏可见。 | | 单条抽屉下钻 | `experiment/run-items.vue` | PLoop drawer 应展示 request、Raw Result、Canonical Trace、gold(仅授权角色)、评分明细和 artifact 链接。 | Fuser 当前 sidebar 会从路由与权限决定可见菜单,列表页还可按权限显示创建/删除操作。PLoop 初期不需要抄 RBAC;但应保留“读 Run”和“看到私有 gold”是不同权限的概念,防止产品页面反过来把金标泄漏给被测系统或普通使用者。 ### 1.3 后端:评测对象与运行状态机 源码入口为 `backend/`,核心技术是 FastAPI、Pydantic、SQLModel、Alembic;完整部署还包含 gRPC、Kafka、Redis、PostgreSQL/pgvector 与 ClickHouse。实际评测域代码位于 `module/lab/`: ```text HTTP API endpoint → gRPC stub # Fuser 特有,PLoop 不采用 → application app # proto/DO 转换、调用 domain service → domain service # 规则、快照、状态推进、计算 → repository / infra model # 持久化 → worker(Kafka) # 单条 execute / evaluate ``` 以 Experiment 为例,Fuser 的 `ExperimentService.start_experiment_run()` 会读取评测集的当前版本,创建 Run 和每个 item 的执行记录,再发布逐条执行任务。完成执行后,通过 barrier 将 Run 从 `executing` 推进到 `evaluating`;全部评估结束才推进到 `done`。它还支持从已有输出发起 `re_evaluate`,不再执行目标应用。 这一机制中值得借鉴的是**快照、阶段与重评语义**,而不是 Kafka 或 gRPC 本身。 ## 2. Fuser 概念到 PLoop 概念的映射 | Fuser | PLoop 对应物 | 采用方式 | 关键差异 | |---|---|---|---| | Evalset + EvalsetVersion + item | Dataset snapshot:英文/中文 MultiHop-RAG、私有 gold、corpus、translation manifest | 采用版本不可变、运行绑定具体版本 | PLoop Dataset 必须把 request 与私有 gold 物理/逻辑隔离。 | | Evaluator + EvaluatorVersion | 官方 evaluator、PLoop evaluator、答案规范化器、可选 judge 配置 | 采用评分器版本与配置冻结 | P0 不用 LLM judge 取代证据评分;一个 Run 可有多维结果,不能默认汇成单一加权分。 | | Experiment + binding | Evaluation definition:被测 RAG 配置 + dataset variant + retrieval budget + evaluator set | 采用明确配置与可读绑定 | PLoop 要保存 SUT 命令/版本和 language/scope,不绑定 Fuser 的 `app_id`。 | | ExptRunLog | Run manifest / 将来的 Run record | 采用 phase、状态、计数、开始结束时间、parent run | P0 已用文件 manifest;平台化时应引用该 manifest,不能创造第二套不一致事实。 | | ExptItemResult | Case execution / canonical trace 的索引 | 采用 per-case 状态、错误、重试、结果入口 | 原始 Raw Result 与大 Trace 应保留为 artifact 文件/对象引用,避免只将摘要 JSON 塞进数据库。 | | EvaluatorRecord | 每个指标/评分器的 evidence | 采用每条评分解释、版本、错误与产物链接 | 证据映射/引用判断须保留结构化证据,而非只有一个 judge score。 | | Worker task | 未来 async job | 只采用稳定 `run_id + case_id + phase` 的幂等任务语义 | P0 不引入 Kafka;先以本地 batch、状态文件和超时产物验证。 | ## 3. PLoop 未来服务化的目标分层 第一轮直接采用下面的 Python 分层;这是平台实现目标,但不会照搬 Fuser 的 gRPC 或微服务拆分。 ```text React + TypeScript 管理台 ↓ HTTP/JSON FastAPI router + Pydantic schema ↓ 直接 Python 调用(无 gRPC) Application service ↓ Domain service ├─ Dataset / translation lineage ├─ Evaluation definition ├─ Run state machine: queued → executing → normalizing → evaluating → done/failed └─ Re-evaluate:只读已有 canonical trace ↓ Repository / artifact store adapter ├─ metadata:Dataset、SUT、Run、Case 状态、指标索引 └─ immutable artifacts:request、raw result、trace、score、manifest ``` API router 只完成认证(若有)、输入验证、调用 application service 与返回 schema;不得在 route 内直接拼命令、做评分或直接访问数据库。Application service 负责事务边界与 DTO 转换;PLoop 的充血 aggregate/domain policy 负责不可变快照、状态机、重试/重评规则;repository/infra 负责文件、数据库或对象存储。该 DDD 细化比 Fuser 的 service-centric 参考更严格,见 [DDD 与充血领域模型设计](../design/ddd-rich-domain-model.md)。 这比 Fuser 少了一层 RPC conversion:没有 proto、`pb2`、stub 或 module 间 gRPC。若以后拆服务,先证明进程边界和吞吐需求;再把 application service 的稳定接口提取成 RPC,而不是现在为可能的拆分预埋 proto。 ## 4. React 重构的 UI 范围 不移植 `.vue`、Pinia store、Element Plus 或 Fuser 的通用组件。React 实现应该根据 PLoop 的实体和 Trace 契约重新设计下面四个工作区: | 工作区 | 首要内容 | Fuser 启发 | PLoop 特有内容 | |---|---|---|---| | 数据集 | 英文/中文变体、SHA、语言、corpus 规模、翻译审查/例外 | Dataset list/detail/version switch | `lineage_case_id`、翻译模型/prompt hash、gold 访问边界。 | | 被测 RAG | 命令/SDK adapter、版本、索引配置、scope、top-k | Fuser Experiment 中的 app 选择 | PLoop 的 SUT 是外部命令或 adapter,不是假定的平台内应用。 | | Run | 状态、阶段进度、成功/失败、耗时、成本、关联数据/配置/评分器版本 | Experiment detail + run table + refresh | `execute → normalize → evaluate` 三段与 artifact manifest。 | | Case 明细 | 问题、retrievals、citations、answer、指标、错误与 artifact 链接 | Run items + evaluator drawer | 分栏显示 Raw Result 与 Canonical Trace;gold 默认遮蔽并与请求严格隔离。 | 第一轮实现受控的 Run 创建与只读 artifact 下钻;Dataset 在线编辑、通用评估器编辑和任意数据上传仍延后。这样 UI 不会反向决定还没有稳定的评测语义。 ## 5. 明确不照搬的点 1. **不引入 gRPC**:Fuser 的 API → gRPC stub → application 层来自微服务边界;PLoop 现阶段没有这个边界,直接调用更简单、可调试。 2. **不引入 Kafka worker**:Fuser 已有按 item 分发、Kafka 消费、barrier 推进的实现;PLoop 首先依赖已有 Batch / manifest / Raw Result 语义,队列的选择另行决策。 3. **不默认总分取平均**:Fuser Run 会保存 `final_score`;PLoop 必须继续按 dataset × language × slice × metric 报告。英文/中文、检索/回答/引用均不可简单平均。 4. **不让 reference payload 泄漏**:Fuser 的运行条目包含 `input_payload`、`reference_payload`、`output_payload` 以支持评测。PLoop 的 gold evidence/answer 在任何 target RAG 可读路径中都必须不可见;UI 也要分权显示。 5. **不复制全栈基础设施**:第一轮有意采用 PostgreSQL 与 Redis 来支撑持久 Run 和异步 worker;但不复制 Fuser 的 Kafka、ClickHouse、gRPC、RBAC、微服务部署或云基础设施。采用的只是满足本轮状态机与 artifact 语义的最小集合。 ## 6. 核查来源 - Fuser 根说明与技术入口:[`README.md`](/Users/pptg/workspace/project/fuser_lab/README.md)、[`CLAUDE.md`](/Users/pptg/workspace/project/fuser_lab/CLAUDE.md)。 - 前端路由、布局与评测页面:[`frontend/src/router/routes/evaluation.ts`](/Users/pptg/workspace/project/fuser_lab/frontend/src/router/routes/evaluation.ts)、[`frontend/src/layouts`](/Users/pptg/workspace/project/fuser_lab/frontend/src/layouts)、[`frontend/src/pages/evaluation`](/Users/pptg/workspace/project/fuser_lab/frontend/src/pages/evaluation)。 - Python API / 自动路由:[`backend/api/main.py`](/Users/pptg/workspace/project/fuser_lab/backend/api/main.py)、[`backend/api/endpoints/register.py`](/Users/pptg/workspace/project/fuser_lab/backend/api/endpoints/register.py)。 - 评测服务、Run worker 与数据模型:[`backend/module/lab`](/Users/pptg/workspace/project/fuser_lab/backend/module/lab)、[`backend/proto/lab`](/Users/pptg/workspace/project/fuser_lab/backend/proto/lab)。