Feynman 架构演进:从单体研究代理到"研究内核 + 适配器"的边界重构

原创2026-09-23 19:39:071,927 阅读

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 — 顶层 parseArgs schema 与类型化命令上下文;
  • 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 计划

提案给出了严格的顺序纪律,核心是"先机械抽取、再扩展表面":

  1. 第一个 PR(当前已应用):scripts/check-architecture.mjs 架构守卫落地。它行为保持(behavior-preserving),保护当前脏的 release candidate 不被进一步压缩。先做守卫、不做插件、不加 MCP。
  2. 下一个 PR:机械抽取 src/rank/paper-rank.ts 为 source/access/graph/scoring/artifact 模块,保持公共导出兼容、测试全绿。为什么第一:
    • 直接攻击最严重的热点(worst hotspot);
    • 创建插件与 MCP 所需的接口;
    • 行为保持且可测试;
    • 不扩张产品表面。
  3. 第二个 PR:拆分 src/cli.ts 的命令处理器。
  4. 第三个 PR:通过 feynman architecture:check 或 npm run architecture:check 标记超过阈值的源文件,并禁止领域模块导入命令模块。
  5. 第四个 PR:添加一个测试覆盖的内置示例适配器——Scholar Inbox 只作为 source_adapter(会议/主题论文 feed);分子结构解析器作为第一个 entity_extractor;BioNeMo 风格 NIM 调用归属 experiment_runners。三者都不能演变成通用摘要、outreach 或 admin 产品。
  6. 第五个 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/rank/paper-rank.ts(论文/证据/排序/工件),再拆 src/cli.ts 命令处理器,然后引入第一个测试覆盖的内置示例适配器,最后在稳定导入之上薄薄地包一层 Feynman MCP。整个过程的纪律是:行为保持优先,表面扩张靠后——这正是把研究代理做成可维护、可扩展、可审计内核的正确顺序。

登录后查看全文
feynman