Feynman 架构演进:从单体研究代理到"研究内核 + 适配器"的边界重构
Feynman 架构演进:从单体研究代理到"研究内核 + 适配器"的边界重构
Feynman 是一个开源的 AI 研究代理(research agent),当前仓库中的 architecture.md 记录了一次关键的架构演进提案:将 Feynman 从"功能堆积的单体"重构为以研究内核(research kernel)为核心、外围由 CLI / Pi 扩展 / MCP / 插件适配器接入的小型架构。本文以此提案为骨架,结合仓库中已落地的 src/research/contracts.ts、src/research/plugin-manifest.ts、scripts/check-architecture.mjs 等源码证据,完整讲解模块拆分目标、插件槽位契约、MCP 暴露面、命令拆分方案、配置与密钥治理,以及分阶段的落地 PR 计划。读完本文,你将掌握 Feynman 当前架构的边界规则、已实施的架构守卫机制,以及未来插件与 MCP 接入的最小正确路径。
为什么需要边界重构:一次不是新功能、而是结构性的一次改造
提案开篇就给出明确的结论(The Pick):Feynman 应该成为一个带有 source/scoring/artifact 适配器的小型研究内核。这意味着下一阶段的代码工作不是加功能,而是一次"边界重构"(boundary refactor)——把"研究真相"(research truth)收归内核,让 CLI、Pi 命令、MCP、插件都只是进入或扩展内核的方式。
从仓库现状看,这个结论有直接的代码依据:src/rank/paper-rank.ts 目前已有 6,756 行,src/cli.ts 有 1,414 行,src/pi/package-ops.ts 有 1,031 行(文档撰写时分别记录为 6,673 / 1,322 / 734 行,行数仍在增长)。这是典型的"god-file"问题:搜索、评分、全文解析、工件生成、模型合成全部堆在一个文件里,任何新功能都难以在不破坏现有行为的前提下叠加。
提案用一张 mermaid 流程图给出了目标架构:
flowchart LR
CLI["CLI commands"] --> Runs["Research run orchestrators"]
Pi["Pi extension/packages"] --> Runs
MCP["Feynman MCP server"] --> Runs
Plugins["Research plugins"] --> Slots["Adapter slots"]
Slots --> Kernel["Research kernel"]
Runs --> Kernel
Kernel --> Artifacts["Artifacts + provenance"]
Kernel --> Telemetry["Metadata-only telemetry"]
subgraph Kernel["Research kernel"]
Papers["papers: resolve + content"]
Graph["evidence graph"]
Rank["ranking + scoring"]
Verify["calibration + reproduction"]
Synthesis["bounded synthesis packets"]
end
内核内部由五个能力域构成:
- papers:论文解析(resolve)与内容获取(content);
- evidence graph:证据图(引用图、信号);
- ranking + scoring:排序与打分;
- calibration + reproduction:校准与复现验证;
- bounded synthesis packets:有边界的模型综合包。
向外,内核只产出两类东西:带溯源(provenance)的工件(artifacts)与仅元数据的遥测(metadata-only telemetry)。外围的 CLI、Pi 扩展、MCP 服务器、研究插件全部通过"适配器槽位"接入,不再直接触及研究真相。
第一拆:src/rank/paper-rank.ts 的模块化目标
提案把 6,000+ 行的 paper-rank.ts 拆成三层职责:
papers 层(论文解析与内容)
src/papers/types.ts—PaperCandidate、ResolvedPaper、PaperContent及共享 source ID;src/papers/openalex.ts— OpenAlex 搜索、按 ID 获取、引文/被引获取、fixture 归一化;src/papers/access.ts— 合法访问候选规划与resolvePaperAccess;src/papers/full-text.ts— AlphaXiv / Europe PMC / 内容抽取与章节解析。
evidence 层(证据图)
src/evidence/types.ts—EvidenceSpan、EvidenceGraph、带溯源的信号证据;src/evidence/graph.ts— 引用图构建、PageRank、图扩展合并逻辑。
rank 层(排序、校准、复现与综合)
src/rank/types.ts—RankSignal、PaperScore、分数画像与校准类型;src/rank/scoring.ts— 主题相关性、引用影响、图谱声望、速度、方法论、可复现性打分;src/rank/field-map.ts— 领域聚类与论文角色分配;src/rank/critique.ts— 确定性批评与批评置信度;src/rank/calibration.ts— 偏好文件解析与分数画像评估;src/rank/reproduction.ts— 复现笔记解析、台账生成与复现目标;src/rank/next-actions.ts— 下一步研究动作生成;src/rank/synthesis.ts— 模型综合包、提示词与综合结果处理;src/rank/run.ts— 仅保留runPaperRank编排。
artifacts 层(工件输出)
src/artifacts/paper-access.ts— 论文访问报告/JSON 写入;src/artifacts/paper-rank.ts— 主报告、分数审计、溯源、批评/综合报告;src/artifacts/graph-explorer.ts— 图谱探索器的 HTML/CSS/JS 载荷。
utils 层(仅共享时抽取)
src/utils/markdown.ts、src/utils/html.ts— 仅在至少两个工件模块共用时提供转义/链接/代码块辅助函数。
从当前源码看,这些拆分目标与 paper-rank.ts 中实际存在的导出函数一一对应:fetchOpenAlexWorks(L1191)、fetchOpenAlexWorksByIds(L1217)、buildFullTextAccessPlan(L1601)、buildCitationGraph(L1766)、computePageRank(L1902)、scorePapers(L1935)、generatePaperCritiques(L2092)、generateFieldMap(L2126)、generateScoreCalibration(L2289)、generateReproductionEvidenceLedger(L2539)、generateNextResearchActions(L2642)、buildModelSynthesisPacket(L3081)、extractEvidenceSpans(L3524)、extractFullTextSections(L3840)、runPaperRank(L4195)、resolvePaperAccess(L4388)等。换句话说,这个文件本质上已经"装下"了论文、证据、排序、工件四层逻辑,拆分是纯机械的搬移,而不是重新发明。
提案同时强调一条硬规则:每个被抽出的模块,其测试必须随之迁移或新增,放在 tests/ 下或新建 tests/rank/ 布局中,与所属行为紧邻(提案引用自 codex/AGENTS.md:59-60)。仓库中的 tests/architecture-check.test.ts 也印证了这一点——它断言架构守卫输出中必须出现 src/rank/paper-rank.ts: \d+ lines、src/cli.ts: \d+ lines 等当前"拆分债务"命名。
第二拆:src/cli.ts 的命令分发重构
src/cli.ts 目前 1,414 行,提案将其拆为:
src/cli/main.ts— 环境加载、遥测生命周期、bootstrap、runMain;src/cli/options.ts— 顶层parseArgsschema 与类型化命令上下文;src/commands/setup.ts、status.ts、model.ts、search.ts、packages.ts、update.ts、alpha.ts、rank.ts、paper.ts。
规则是:命令模块自行解析自己专属的 flag,src/cli/options.ts 只解析全局 flag 与第一个位置参数(命令名)。这遵循 OpenCode 的"main 函数读起来像 happy path,支撑细节放在下面/helper 里"原则(opencode/AGENTS.md:95-116)。
从当前 src/cli.ts 的 dispatch 逻辑看,命令集合完全对得上:setup(L1032)、doctor(L1054)、status(L1065)、serve(L1076)、model(L1093)、search(L1098)、packages(L1103)、update(L1108)、alpha(L1113,含 status 子命令)、rank(L1122)、paper(L1262)以及 chat(L525)、help(L1027)。runMain(L897)负责整体编排,正是拆分后 src/cli/main.ts 的主体。
第三拆:src/pi/package-ops.ts 的运行时包操作
src/pi/package-ops.ts 现有 1,031 行,提案将其拆为:
src/pi/packages/context.ts— 创建 SettingsManager / DefaultPackageManager 上下文;src/pi/packages/sources.ts— 解析/去重 npm/git/local 源与运行时 peer spec;src/pi/packages/install.ts— install/update 命令执行与输出过滤;src/pi/packages/bundled.ts— 内置包 seeding/pruning;src/pi/packages/compat.ts— 原生包支持与遗留 Pi alias 处理。
同时明确职责边界:Pi 运行时补丁继续保留在 src/pi/runtime-patches.ts,包操作代码只负责"调用它",不持有补丁细节。
Feynman 插件形态:一个 Pi 包 + 一份研究清单
提案的关键设计决策是:Feynman 不创建第二套运行时。一个 Feynman 插件 = 一个 Pi 包 + 一份 Feynman 研究 manifest。仓库中的 src/research/plugin-manifest.ts 已把这个契约落地为可校验的类型与校验函数。
manifest 示例(完整继承)
manifest_version: 1
name: scholar-inbox
version: 0.1.0
description: Adds Scholar Inbox as a source adapter for conference/topic paper feeds.
research_jobs:
- discovering_prior_art
- synthesizing_artifacts
slots:
source_adapters:
- ./dist/source-adapter.js
entity_extractors:
- ./dist/entity-extractor.js
experiment_runners:
- ./dist/reproduction-runner.js
artifact_exporters:
- ./dist/conference-summary-exporter.js
pi:
extensions:
- ./dist/pi-extension.js
skills:
- ./skills
requires_env:
- name: SCHOLAR_INBOX_API_KEY
secret: true
对照 src/research/plugin-manifest.ts 的校验实现,可以逐字段理解约束:
- 顶层键:
manifest_version、name、version、description、research_jobs、slots、pi、requires_env之外的键会触发 warning("unknown top-level key ignored by v1"); - manifest_version 必须严格等于
1; - name 必须是包安全标识符:正则
^[a-z0-9][a-z0-9._-]*$,且不含..、/、\; - research_jobs 必须是非空数组,且每个值都必须是
src/research/contracts.ts中researchJobValues的成员(discovering_prior_art、reading_paper_content、extracting_research_entities、ranking_evidence、verifying_claims、planning_reproduction、running_research_experiments、synthesizing_artifacts、visualizing_research_structure、improving_research_loop); - slots 键必须在
feynmanPluginSlotValues内(见下文),路径必须是停留在插件根目录内的相对路径(拒绝绝对路径、..、/../逃逸); - pi 资源只允许
extensions、skills、prompts、themes四个键,同样做相对路径安全校验; - 至少声明一个 slots 或 pi 资源,否则校验失败;
- requires_env 的元素可以是字符串或对象;
name必须匹配^[A-Z][A-Z0-9_]*$的 env 变量命名规范,secret: true用于标记密钥类变量。
允许的插件槽位(slot types)
提案定义了 9 类允许的槽位,src/research/plugin-manifest.ts 中的 feynmanPluginSlotValues 与之完全一致:
- source_adapters — 从 Scholar Inbox、OpenReview、Semantic Scholar、arXiv、PubMed 或会议 feed 等来源返回论文候选;
- access_resolvers — 返回合法全文/访问候选;
- entity_extractors — 从论文、图表、caption、表格、源码文本或代码中抽取类型化研究实体,例如分子图、配体、蛋白质、基因、assay、方程、数据集、代码路径、基准名、方法;
- rank_scorers — 增加有边界的打分信号并带溯源;不得静默覆盖核心打分语义;
- experiment_runners — 对显式输入运行/打包有边界的复现或模型调用,并把工件路径与 caveat 写回
ResearchRun; - artifact_exporters — 从
ResearchRun产出报告、表格、图或包输出; - visualizers — 仅当证据图视图会改变研究决策时才渲染;
- subagents — 仅当它们服务于研究任务时提供 Pi 子代理提示词;
- mcp_servers — 暴露随插件打包的外部工具服务器。
明确拒绝的槽位
提案明确拒绝以下槽位类型,防止插件体系演变成通用的"什么都能干"平台:
- 通用 hooks;
- outreach / 冷邮件;
- 基金/提案工作流;
- 管理/项目管理工作流;
- 任意的模型提示词转换;
- 直接 patch Feynman 核心文件的插件。
已落地的 ResearchRun 脊柱
提案提到"src/research/contracts.ts 现在定义了第一个 ResearchRun 脊柱"。从源码看,这个脊柱包含:
- ResearchJob 枚举(10 个研究任务,见上);
- ResearchRunStatus:
planned / running / completed / partial / blocked / failed; - VerificationState:
not_checked / inferred / partial / verified / blocked / failed; - ResearchArtifactKind:
report / json / jsonl / graph / html / audit / provenance / template / prompt / model_output / ledger / plan / manifest; - ResearchRunPaper:带
roles、verification(state + summary)与 DOI/arXiv/PMID/PMCID/OpenAlex ID 等标识; - ResearchToolRun:
kind覆盖source_adapter / access_resolver / entity_extractor / rank_scorer / experiment_runner / artifact_exporter / visualizer / model,与插件槽位一一对应; - ResearchRun:
schemaVersion: "feynman.researchRun.v1",聚合 runId、workflow、slug、topic、status、researchJobs、sources、papers、entities、tools、artifacts、nextActions、verification、constraints; - 约束:
rawFullTextStored、promptsStored、modelOutputsStored三个布尔约束,且校验函数强制rawFullTextStored不得为 true(即原始全文不进 manifest); - buildResearchRunId:用 SHA-256 对
workflow + slug + generatedAt生成确定性 runId; - validateResearchRun:完整的 schema 校验,覆盖必填字段、枚举合法性、至少一个 primary artifact 等。
这些类型说明"研究运行"在 Feynman 中是有 schema 约束、可验证、带溯源的,而不是散落的输出文件。
Feynman MCP 暴露面:域拆分之后的薄表面
提案明确 MCP 服务器在域拆分之后发布("Ship after the domain split, not before"),因为 MCP 只是内核稳定导入的薄包装。
首批暴露的工具:
resolve_paper({ identifier, fetchFullText })rank_papers({ topic, limit, expandCitations, fullTextTop, critiqueTop, synthesize })list_research_outputs({ cwd, topic? })get_research_artifact({ path })inspect_evidence_graph({ runId | artifactPath })
这些参数名与 paper-rank.ts 中 PaperRankOptions(L1027)的实际字段(parseRankLimit、parseFullTextTop、parseCitationExpansion、parseCritiqueTop、parseSynthesisTop,见 L1101–L1137)高度吻合,且默认/上限常量都在文件头部明确定义(DEFAULT_RANK_LIMIT = 25、MAX_RANK_LIMIT = 100、MAX_CITATION_EXPANSION_WORKS = 100、DEFAULT_SYNTHESIS_TOP = 5 等)。
明确不暴露的操作:setup、update、model login/logout、packages install/remove、插件安装。理由是这些操作会改变操作者状态(mutate operator state),应当保持 CLI-first。
研究模式拆分:plan 与 rank/lit 的分工
提案借用 OpenCode 的 plan/build 区分,并翻译到研究场景:
feynman plan <topic>:只读研究模式——产出研究计划、来源清单、问题、预期工件;不允许用会写入项目状态的工具调用模型综合,除非是输出工件;feynman rank <topic>/feynman lit <topic>:运行模式——产出工件与溯源。
并明确:在 CLI 拆分完成之前不要新增该命令。当前仓库中 src/cli.ts 已存在 rank(L1122)与 paper(L1262)命令入口,plan 模式属于后续演进。
配置与密钥治理:采用 Hermes 规则
提案对配置/密钥引入 Hermes 规则:
- 密钥留在
.env、认证存储、keychain 或 provider 专属的密钥存储中; - 行为设置留在
~/.feynman/settings.json或项目配置中; - 不再新增
FEYNMAN_*行为类 env 变量,除非它们需要桥接内部进程需求。
仓库中对应的基础设施包括:src/workbench/settings-store.ts、src/workbench/secret-ledgers.ts、src/workbench/oauth-store.ts 以及 Pi/Feynman settings 路径(提案引用 settings.md:221-260 说明 Pi 文档已有设置路径与包配置说明)。也就是说,密钥与行为设置的分离在代码层面已有承载,新代码不应开倒车。
最小正确落地路径:五步 PR 计划
提案给出了严格的顺序纪律,核心是"先机械抽取、再扩展表面":
- 第一个 PR(当前已应用):
scripts/check-architecture.mjs架构守卫落地。它行为保持(behavior-preserving),保护当前脏的 release candidate 不被进一步压缩。先做守卫、不做插件、不加 MCP。 - 下一个 PR:机械抽取
src/rank/paper-rank.ts为 source/access/graph/scoring/artifact 模块,保持公共导出兼容、测试全绿。为什么第一:- 直接攻击最严重的热点(worst hotspot);
- 创建插件与 MCP 所需的接口;
- 行为保持且可测试;
- 不扩张产品表面。
- 第二个 PR:拆分
src/cli.ts的命令处理器。 - 第三个 PR:通过
feynman architecture:check或npm run architecture:check标记超过阈值的源文件,并禁止领域模块导入命令模块。 - 第四个 PR:添加一个测试覆盖的内置示例适配器——Scholar Inbox 只作为
source_adapter(会议/主题论文 feed);分子结构解析器作为第一个entity_extractor;BioNeMo 风格 NIM 调用归属experiment_runners。三者都不能演变成通用摘要、outreach 或 admin 产品。 - 第五个 PR:当
resolvePaperAccess、runPaperRank、工件列举与证据图检查都成为稳定导入后,再添加 MCP 服务器。
架构守卫的实际行为(已落地)
scripts/check-architecture.mjs 当前执行的检查规则:
- 行数阈值:警告线 800 行,失败线 1200 行;
src/rank/paper-rank.ts、tests/paper-rank.test.ts、src/cli.ts作为已知债务被允许放行但持续报告;src/model/commands.ts、scripts/patch-embedded-pi.mjs落在警告区; - 领域边界:
src/artifacts/、src/evidence/、src/papers/、src/rank/四个领域根目录下的模块,禁止导入src/cli、src/commands/、src/setup/、src/ui/中的任何模块;导入检查覆盖静态 import/export 与动态import(); - 扫描范围:
src、extensions、scripts、tests下的.ts/.mts/.mjs,跳过node_modules、dist、.git、.feynman。
在 package.json 中已注册脚本:
"architecture:check": "node ./scripts/check-architecture.mjs"
运行方式(在仓库根目录):
npm run architecture:check
预期输出会先打印已知债务(known architecture debt),再打印待拆分警告,全部通过时打印 [feynman:architecture] checked N source files;任何失败会以非零退出码结束。tests/architecture-check.test.ts 已验证该行为:它断言输出必须包含 src/rank/paper-rank.ts、src/cli.ts、tests/paper-rank.test.ts 的当前行数报告,以及 src/model/commands.ts 的警告报告。
ML Intern 风格的研究配方工件(recipe artifact)
提案建议把"研究配方"作为现有 rank/lit 路径产出的工件形态,而不是单独的新工作流,且需在 PaperRank 模块拆分之后实施。该工件需要回答六个问题:
- 哪些论文重要(Which papers matter)?
- 每篇论文实际产出了什么结果(What result did each paper actually produce)?
- 什么数据集/基准/实验设置产生了该结果(What dataset, benchmark, or experimental setup produced that result)?
- 什么方法/配置让它有效(What method/configuration made it work)?
- 什么代码或仓库实现了该方法(What code or repo implements the method)?
- 下一步该做什么验证/复现动作(What verification/reproduction action should happen next)?
建议输出文件:outputs/<slug>-recipes.md 与 outputs/<slug>-recipes.json。
建议行字段(完整继承):
| Field | Meaning |
|---|---|
paper |
title, DOI/arXiv/OpenAlex ID, year, source |
result |
benchmark/metric/result text with evidence span |
dataset |
dataset name/source/HF availability/schema status when known |
method |
method/training/evaluation setup with evidence span |
code |
linked implementation, repo, file path, or missing status |
why_it_worked |
concrete mechanism, not generic summary |
verification_next |
exact reproduction/claim-check action |
提案明确这是 ML Intern recipe table 要求的 Feynman 翻译(ml-intern/agent/tools/research_tool.py:196-220),目标是直接改进排序、理解、验证、复现规划与可审计综合,而不是变成基金撰写器、outreach 工具或通用摘要器。
总结:一份"先收边界、再长表面"的演进路线图
回到提案的核心判断:Feynman 需要的不是一个新功能,而是一次边界重构。已落地的证据表明这次重构正在按计划推进:
- 内核脊柱已成型:src/research/contracts.ts 定义了带 schema 版本、可校验、含溯源与约束的
ResearchRun; - 插件契约已可校验:src/research/plugin-manifest.ts 实现了 9 类槽位 + Pi 资源 + env 声明的完整校验,且拒绝路径逃逸与未知键;
- 架构守卫已生效:scripts/check-architecture.mjs 通过
npm run architecture:check守护行数阈值与领域导入边界,并由 tests/architecture-check.test.ts 固化行为。
后续的关键路径清晰可预期:先机械拆分 src/rank/paper-rank.ts(论文/证据/排序/工件),再拆 src/cli.ts 命令处理器,然后引入第一个测试覆盖的内置示例适配器,最后在稳定导入之上薄薄地包一层 Feynman MCP。整个过程的纪律是:行为保持优先,表面扩张靠后——这正是把研究代理做成可维护、可扩展、可审计内核的正确顺序。