【免费下载链接】feynmanThe open source AI research agent.项目地址https://gitcode.com/gh_mirrors/feynman/feynman点击查看免费下载本文基于 Feynman 开源仓库The open source AI research agent内部的outputs/.plans/code-organization-review/规划文档与对应源码实现系统讲解 Feynman 如何在保持简单而强大simple yet potent的 AI 科研代理定位前提下借鉴 Claude Code、OpenAI Codex、OpenCode、Hermes Agent 等 Agent 项目的架构纪律将当前以paper-rank.ts、cli.ts为代表的巨型文件god-file逐步重构为研究内核 适配器插槽 MCP 主机面的清晰形态。读完本文你将理解 Feynman 的代码组织需求基线、八大核心科研任务边界、ResearchRun运行时契约与插件清单校验规则以及一条以架构守卫为第一步、机械拆分为第二步的分阶段落地路线。一、需求背景为什么 Feynman 需要一次形状优先的重构1.1 用户目标研究外部 Agent 项目反哺自身组织形态requirements.md给出的用户目标非常明确通过研究 Claude Code、OpenAI Codex、OpenCode 与 Hermes Agent 这四个外部 Agent/CLI/runtime/plugin 项目的组织方式为 Feynman 找到更优的代码与产品组织方案。在此基础上同一规划批次还补充了 Hugging Face ML Intern 作为对比对象用于吸收研究配方research recipe与运行轨迹run trace层面的纪律。与常见的抄功能式对比不同这里的关键限定是只吸收那些能让 Feynman 成为更好 AI 科研代理的模式而不是照搬整个产品面。仓库配套文档outputs/.plans/code-organization-review/STATUS.md记录了对比对象在 2026-06-23 固定的提交OpenAI Codex63f8f547…、Claude Code12281998…、OpenCoded568fed0…、Hermes Agent5ecf3bf0…、ML Intern550a2097…全部以 pinned commit 方式检入研究目录作为可复核的对比证据。1.2 硬约束不改产品代码、不建第二套运行时规划文档明确列出了一组硬约束Hard Constraints这些约束是理解后续所有决策的前提Feynman 必须是 AI 科研代理而不是相邻生产力工作流的捆绑包此条来自仓库契约 AGENTS.md 的 Feature scope每个新特性都必须对应一个具名核心科研任务且在实现前要有具体、可测试的价值AGENTS.md:33-46Pi 运行时变更必须基于已安装的 Pi 包版本/文档/源码优先复用既有 Pi 包与扩展能力而不是本地自造 shimAGENTS.md:50-53测试与默认路径不得使用 Pro 级模型——src/cli.ts 的 rank 命令已明确阻止显式指定 Pro 级模型用于 PaperRank 综合规划文档引用了该文件 1039-1043 行位置当前仓库该文件已增长到 1414 行不得为了与 Claude/OpenCode/Codex/Hermes 对等而加功能只取架构纪律在代码变更范围被接受之前不得从本轮研究中直接改动产品代码该约束在架构守卫落地后解除了一小部分见下文第四节。二、核心科研任务清单一切功能的准入考试规划文档强调requirements.md中的Core Research Jobs Allowed To Grow直接复制自仓库契约 AGENTS.md原文标注AGENTS.md:35-42。任何超出该清单的诉求除非被显式限定在某次活跃研究运行内否则一律拒绝。八个允许增长的科研任务为发现相关论文、代码、数据集或先验工作discovering relevant papers, code, datasets, or prior art阅读、提取与理解论文内容reading, extracting, and understanding paper content排序证据、方法、可复现性或引文结构ranking evidence, methods, reproducibility, or citation structure核实对来源、代码、数据或实验的声明verifying claims against sources, code, data, or experiments规划或运行复现与科研实验planning or running reproductions and research experiments综合科研结论为可审计工件synthesizing research into auditable artifacts可视化研究结构——且仅当可视化会改变研究决策时visualizing research structure when the visualization changes a research decision改进研究循环的速度、可观测性、溯源与可靠性improving speed, observability, provenance, or reliability of the research loop。这套清单在仓库里不仅是文字约束已经进一步形式化为代码src/research/contracts.ts中的ResearchJob联合类型与researchJobValues数组精确对应上述八类扩展为十个枚举值含extracting_research_entities与visualizing_research_structure的细分并成为后续ResearchRun清单与插件清单校验的共同依据。三、改进计划的验收标准与明确非目标3.1 验收标准Acceptance Criteria规划文档要求最终改进计划必须做到指明 Feynman 对内应该暴露的窄腰narrow waist指明当前哪些文件应当最先拆分及为什么定义契合 Pi 的插件/包/MCP 方向而不是再造一套并行运行时对 Claude Code、Codex、OpenCode、Hermes 分别区分采纳的启发与拒绝的启发提供带测试与回滚点的分阶段实施顺序为手册中每一个事实性声明记录引用citation。3.2 非目标Non-Goalsrequirements.md用一整节列出明确不做的事用于防止研究跑偏不做 grant 挖掘/提案撰写扩展不做通用任务/项目管理产品线不复制 Hermes 的个人助理网关产品在出现真实研究插件消费方之前不做任意插件钩子市场plugin hook marketplace不引入本地路径假设、外联工作流、重复的摘要命令、外部分支带来的类 Bernoulli 式提示词蔓延除非映射到核心研究循环不复制 ML Intern 的完整云端 Jobs/沙箱/网关产品——Feynman 已有计算工作流只取其研究配方、运行轨迹、工件与工具边界纪律。配套文档 handoff.md 将上述拒绝清单进一步细化为可直接执行的 Accepted/Rejected Inspiration 对照表例如拒绝Hermes 个人代理网关广度、拒绝ML Intern 全套云端作业/沙箱/前端/网关、拒绝任意钩子先于真实科研插件需求。四、第一步落地可执行的架构守卫4.1 问题巨型文件与不可见的模块边界规划文档给出的文件体检数据source-inventory.md记录了wc -l实测非常触目惊心文件规划时行数当前仓库实测行数src/rank/paper-rank.ts6,4826,756tests/paper-rank.test.ts2,3502,377src/cli.ts1,3221,414src/pi/package-ops.ts7341,031src/model/commands.ts1,0361,028src/rank/paper-rank.ts单个文件里同时塞入了类型定义、OpenAlex 抓取、访问规划、引文图、打分、批评、领域映射、校准、复现、下一步动作、模型综合、全文抓取器、PaperRank 编排、工件渲染、图探索器 HTML/CSS/JS、溯源、序列化与转义工具——是典型的 god-file。规划文档明确指出纸质架构笔记挡不住下一次编辑继续撑大同一批文件边界必须是可执行的。4.2 架构守卫的实现check-architecture.mjs为此本轮已实际落地applied的代码改进是新增 scripts/check-architecture.mjs并通过 package.json 的architecture:check脚本暴露为npm run architecture:check。其行为规则均可在脚本源码中验证警戒线 800 行超过 800 行的文件输出警告warn失败线 1200 行超过 1200 行且不在白名单内的文件直接判失败fail白名单债务登记src/rank/paper-rank.ts、tests/paper-rank.test.ts、src/cli.ts三个已知巨型文件被显式登记为已知架构债务allowed oversized files各自带一句债务理由如Existing PaperRank god-file. Split into papers/evidence/rank/artifact modules before adding new ranking surface.允许暂时存在但绝不允许继续膨胀领域边界导入检查位于src/artifacts/、src/evidence/、src/papers/、src/rank/的领域模块禁止 import 来自src/cli、src/commands/、src/setup/、src/ui/的模块违反即失败扫描范围覆盖src、extensions、scripts、tests下全部.ts/.mts/.mjs文件自动跳过node_modules、dist、.git、.feynman。STATUS.md 记录了干净环境Daytona 一次性 Linux 沙箱验证npm ci→npm run architecture:check→npm test325/325→npm run typecheck→npm run build→npm audit --omitdev全部通过npm pack --dry-run生成 135 个文件、约 51-52 MB 的包。五、目标架构小型研究内核 适配器5.1 架构选择The Pick配套规划文档 architecture.md 给出了核心决策Feynman 应成为一个小型研究内核research kernel外围挂载 source/scoring/artifact 适配器。也就是说下一阶段的代码工作不是再加一个特性而是一次边界重构boundary refactor。内核负责研究真相research truth包含五大能力块papers论文解析与内容获取evidence graph证据图ranking scoring排序与打分calibration reproduction校准与复现bounded synthesis packets有界综合包。CLI 命令、Pi 扩展/包、Feynman MCP 服务器、研究插件只是进入或扩展这个内核的入口。数据流为CLI/Pi/MCP/插件 → Research run 编排器 → 研究内核 → 工件与溯源 / 仅元数据遥测。5.2 内部窄腰十个稳定研究对象规划文档why-chains.md 第 2 节给出了 Feynman 内部应暴露的窄腰对象清单PaperCandidate、ResolvedPaper、PaperContentEvidenceSpan、EvidenceGraphRankSignal、RankedPaperResearchArtifact、ProvenanceRecord、ResearchRun其论证逻辑是外部项目Codex 的 workspace crates 拆分、OpenCode 的 V2 session core、Hermes 的 narrow waist 与 Footprint Ladder都指向同一结论——扩展应挂接到稳定的研究对象上而不是 import 整个命令实现。对应的拒绝替代方案也很有价值既不能把 PaperRank 的全部 helper 暴露成公共 API会把 god-file 变成公共 API也不能只依赖 Pi 包而完全不做领域适配器插槽。5.3 模块拆分路线图规划文档给出了三条具体拆分路径注意这些是计划当前仓库尚未执行属可以推断的规划内容第一次拆分src/rank/paper-rank.ts规划 6,673 行为src/papers/{types,openalex,access,full-text}.ts、src/evidence/{types,graph}.ts、src/rank/{types,scoring,field-map,critique,calibration,reproduction,next-actions,synthesis,run}.ts、src/artifacts/{paper-access,paper-rank,graph-explorer}.ts外加共享的src/utils/markdown.ts与src/utils/html.ts规则是每个模块的测试随代码一起迁移Codex 明确要求 extraction 时同步搬走 tests/docs第二次拆分src/cli.ts为src/cli/{main,options}.ts加src/commands/{setup,status,model,search,packages,update,alpha,rank,paper}.ts规则是命令模块各自负责自己的参数解析options.ts只解析全局标志与第一个位置参数借鉴 OpenCode main 函数读起来是 happy path 的约定第三次拆分src/pi/package-ops.ts规划 734 行为src/pi/packages/{context,sources,install,bundled,compat}.ts同时明确Pi 运行时补丁留在src/pi/runtime-patches.tspackage ops 调用它而不是拥有它的细节。architecture.md还给出了最小的正确首个 PR排序先加架构守卫已落地→ 机械抽取 PaperRank保持公共导出兼容、测试全绿→ 拆分 CLI 命令 → 加architecture:check强制约束 → 加一个内置示例适配器Scholar Inbox 作为source_adapter、分子结构解析器作为entity_extractor、BioNeMo 风格 NIM 调用归属experiment_runners→ 最后加 MCP server。六、ResearchRun运行时契约的代码化6.1 第一根代码级脊梁requirements.md的验收标准要求定义一个契合 Pi 的插件/包/MCP 方向而规划配套文档 runtime-contracts.md 给出了完整的 TypeScript 契约草案。这些契约已经从草案变成了真实代码src/research/contracts.ts 现在定义了第一个代码级版本即feynman.researchRun.v1。核心类型包括ResearchJob十个枚举值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_loopResearchRun携带runId、workflow、slug、topic、statusplanned|running|completed|partial|blocked|failed、researchJobs、sources、papers、entities、tools、artifacts、nextActions、verification与constraintsResearchArtifactkind已扩展为report|json|jsonl|graph|html|audit|provenance|template|prompt|model_output|ledger|plan|manifestvalidateResearchRun一个纯函数校验器检查schemaVersion必须是feynman.researchRun.v1、researchJobs非空且值合法、至少一个 primary 工件、rawFullTextStored不得为true等——关键约束是清单绝不存储原始全文。6.2 PaperRank 已开始写入研究清单在 src/rank/paper-rank.ts 中runPaperRank的工件生成逻辑现在会为每次 rank 运行写出slug-research-run.json并用validateResearchRun校验通过后才继续写其余工件集src/rank/paper-rank.ts#L4849-L4853附近先构造buildPaperRankResearchRun(input, artifacts)校验失败直接抛错成功后才写report/papers/scores/score-audit/rank-sensitivity/citation-graph/graph-explorer/field-map/provenance等一整套工件。tests/paper-rank.test.ts也已断言 PaperRank 会输出有界的 ResearchRun 清单且rawFullTextStored: false配套的 tests/research-contracts.test.ts105 行覆盖 ResearchRun 主干与合法/非法插件清单。STATUS.md 记录的本地 installed-tarball E2E 验证展示了完整链路安装companion-ai/feynman0.3.4到全新临时工程运行feynman --version返回0.3.4跑 PaperRank 发出feynman.researchRun.v1排序 4 篇论文保留 top 论文WFOUNDATION写出 11 个工件rawFullTextStored: false。6.3 研究配方Research Recipe契约受 ML Intern 强制要求排序配方表启发runtime-contracts.md定义了 Feynman 版本的研究配方契约ResearchRecipe每条记录包含paper标题/DOI/arXiv/OpenAlex ID/年份、result声明 benchmark 指标 证据片段、dataset名称/来源/HF hubId/可用性verified|candidate|missing|not_checked 证据、method摘要 参数 证据、code仓库/路径/URL/状态、whyItWorked与verificationNext。配套规则强调配方提取永远不能单独压过确定性 PaperRank它只服务综合与复现规划JSON 工件必须保持有界、不存原始全文Markdown 工件沿用既有转义纪律。规划建议输出到outputs/slug-recipes.md与outputs/slug-recipes.json作为现有rank/lit路径在 PaperRank 拆分后新增的工件形态。七、插件形态Pi 包 研究清单不造第二套运行时7.1 核心原则requirements.md的硬约束明确要求如果 Pi 已经提供了正确的层就不要再造第二个插件/运行时系统。因此规划结论是Feynman 插件 一个 Pi 包 一份 Feynman 研究清单manifest。插件可以携带 Pi 资源extensions、skills、prompts、themes也可以注册 Feynman 领域插槽source_adapters、access_resolvers、rank_scorers、artifact_exporters、visualizers、subagents等但必须声明research_jobs且来自允许清单且不得补丁核心文件、不得注入任意钩子直到出现具体消费方。architecture.md给出了示例清单scholar-inboxmanifest_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: true7.2 允许的插槽类型与明确拒绝的类型允许的插槽含语义说明source_adapters从 Scholar Inbox、OpenReview、Semantic Scholar、arXiv、PubMed 或会议 feed 返回论文候选access_resolvers返回合法的全文/访问候选仅限合法访问禁止绕过付费墙entity_extractors从论文、图、说明、表、源码提取分子图、配体、蛋白质、基因、assay、方程、数据集、代码路径、benchmark 名与方法等类型化实体rank_scorers添加有界打分信号并携带溯源不得静默改写核心打分语义experiment_runners针对显式输入运行有界复现/模型调用如 BioNeMo 式折叠、对接、序列搜索、分子生成、benchmark 重跑并把工件路径与 caveats 写回ResearchRunartifact_exporters从ResearchRun产出报告、表格、图或包输出visualizers仅在可视化会改变研究决策时渲染证据图视图subagents仅当服务于科研任务时提供 Pi subagent 提示词mcp_servers暴露随插件打包的外部工具服务器。当前拒绝的类型通用钩子、外联/冷邮件、grant/提案工作流、管理/项目管理工作流、任意模型提示词变换、以及补丁 Feynman 核心文件的插件。配套的 why-chains.md 给出拒绝理由Hermes 拒绝投机性钩子是因为插件依赖之后移除很难hermes-agent/AGENTS.md:96-101。7.3 清单校验的代码实现这份契约同样已代码化src/research/plugin-manifest.ts 实现了validateFeynmanPluginManifest。可以在源码中逐条验证的校验规则manifest_version必须是1name必须是包安全标识符不允许/、\、..或绝对路径isSafePackageName用正则^[a-z0-9][a-z0-9._-]*$校验research_jobs必须是非空数组且值必须在researchJobValues之内每个插槽路径与 Pi 资源路径必须解析在插件根目录内isSafeRelativePath拒绝绝对路径、..与../前缀——与 Hermes/Codex 的路径穿越防御一致未知的顶层 key 在 v1 中仅告警未知插槽 key 直接失败未知的pi资源 key 失败至少声明一个slots或pi资源requires_env中的条目必须是合法环境变量名/^[A-Z][A-Z0-9_]*$/可带secret标志。八、MCP 表面主机面而非核心规划文档architecture.md 与 why-chains.md 第 4 节的结论是MCP 是让 Claude/Codex/OpenCode/Hermes 等宿主调用 Feynman 科研能力的主机面而不是 Feynman 的核心因此必须在领域拆分稳定之后才发布feynman mcp排在第五个 PR。首批工具不暴露 setup/update/model auth/包管理/插件安装等会改动操作者状态的命令那些保持 CLI-firstresolve_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 })runtime-contracts.md进一步规定 MCP 工具必须调用稳定的内核函数并返回有界工件/路径而非原始全文resolve_paper返回访问候选、元数据、内容摘要与工件路径inspect_evidence_graph返回图指标与选定的节点/边而不是整图倾泻。拒绝方案包括把每个 CLI 命令都暴露成 MCPsetup/update/auth/包管理是操作命令而非研究工具与把插件安装放进 MCP插件安装会改动本地可执行面应留在 CLI 侧做显式信任/校验。九、配置与密钥纪律规划采用 Hermes 的规则并将行为配置与密钥严格分层密钥留在.env、认证存储、keychain 或各 provider 专用密钥库中行为设置留在~/.feynman/settings.json或项目配置中不再新增用户可配置的FEYNMAN_*行为环境变量除非是为了桥接内部进程需求。依据Hermes 拒绝用非密钥环境变量控制行为hermes-agent/AGENTS.md:102-107而 Feynman 已通过 Pi 设置路径settings.md:221-260与包配置拥有对应的承载面。插件清单中的requires_env只用于声明真正需要环境变量的 provider 必需项行为配置一律走 Feynman settings。十、测试策略从输出快照走向不变量规划why-chains.md 第 5 节特别警告模块抽取如果只靠断言工件文本或 happy-path 输出会在重构中悄悄破坏行为。借鉴 Codexagent 逻辑变更必须有集成测试、OpenCode避免 mock测真实实现、Hermes行为契约优于快照三家的纪律Feynman 的测试策略是为每个被抽取模块添加契约测试contract tests保留一个端到端 PaperRank fixture 测试断言研究行为而非精确措辞排序顺序只允许因可解释的信号变化而改变引文图边数必须与 fixture 匹配全文访问状态有界且被溯源记录缺失校准/复现输入时输出显式状态工件 sidecar 列出来源账目source accounting拒绝把快照渲染报告文本当作主要安全网——报告文本只覆盖必需章节与链接不锁定措辞。这条策略与仓库现状直接呼应tests/paper-rank.test.ts已 2377 行规划要求测试随模块抽取一起迁移到tests/rank/等目录。十一、遥测边界与可观测性契约runtime-contracts.md的遥测契约明确了数据边界与 AGENTS.md 的 Pi 可观测性规则一致只发射纯元数据的 spans/events永不发射提示词、工具参数、论文全文、含用户私有项目名的文件路径或原始源内容维持既有 PostHog/Pi 遥测分工Feynman CLI 围绕命令发 spanPi 生命周期/工具/模型 span 走pi-otel新增插件/MCP 遥测只上报插件名、插槽类型、时长、状态、计数与错误类别。十二、分阶段实施路线带测试与回滚点综合规划文档architecture.md The Smallest Correct First PR、handoff.md The Decision最终落地顺序如下架构守卫已落地scripts/check-architecture.mjsnpm run architecture:check行为保持、保护脏的 release candidate 不被继续撑大机械抽取 PaperRank把src/rank/paper-rank.ts拆成 papers/evidence/rank/artifacts 模块首个 PR 保留paper-rank.ts作为兼容性 barrel不改打分数学、不加 Scholar Inbox/MCP/插件安装/新命令测试随模块迁移拆分src/cli.ts命令处理器为src/commands/*ResearchRun与研究配方工件契约契约代码已先行落地于src/research/contracts.tsPi 之上的研究插件清单/校验器已落地于src/research/plugin-manifest.tsfeynman plugins用户命令暂缓等待真实适配器消费方如 Scholar Inbox 源或分子结构实体提取器feynman mcp仅在resolvePaperAccess、runPaperRank、工件列举与证据图检查成为稳定 import 之后发布。配套 STATUS.md 给出当前执行状态提示产品代码工作树存在未提交的本地修改规划文档明确下一动作是提交并推送本轮产品契约补丁然后继续 PaperRank 的机械抽取——在出现真实 source adapter、entity extractor 或 experiment runner 之前不添加用户可见的插件命令。结语形状优先功能其次requirements.md与其配套规划文档共同传递的核心方法论可以概括为一句话当产品表面在膨胀时第一优先级的代码工作不是加功能而是修正形状。Feynman 通过把AI 科研代理这一身份固化为八个核心科研任务、把运行时契约收敛为feynman.researchRun.v1、把插件方向锁定为Pi 包 研究清单、把巨型文件拆解为可执行架构守卫监督下的研究内核与适配器插槽在吸收 Claude Code/Codex/OpenCode/Hermes/ML Intern 架构纪律的同时明确拒绝了它们的产品面诱惑。对希望为 Feynman 贡献代码或扩展的开发者而言这条从需求基线 → 运行时契约 → 插件清单 → 架构守卫 → 分阶段重构的完整链路就是仓库当前最重要的组织地图——相关规划文档与代码均可直接在本仓库中继续查阅requirements.md、architecture.md、runtime-contracts.md、why-chains.md、STATUS.md、handoff.md。赞分享【免费下载链接】feynmanThe open source AI research agent.项目地址https://gitcode.com/gh_mirrors/feynman/feynman点击查看免费下载相关推荐海尔智能家居集成在Home Assistant中统一控制Haier/Candy/Hoover家电的终极指南海尔智能家居集成在Home Assistant中统一控制Haier/Candy/Hoover家电的终极指南 想要摆脱多个手机APP的困扰将所有海尔系智能家电如何优雅地处理EGOCache缓存过期超时策略全解析如何优雅地处理EGOCache缓存过期超时策略全解析 EGOCache是一款为Objective C打造的高性能缓存库完美支持iPhone和Mac平台。作为AlphaFold2 结构预测与审计Feynman 开源 AI 研究代理的蛋白质结构工作流指南AlphaFold2 结构预测与审计Feynman 开源 AI 研究代理的蛋白质结构工作流指南 导读 AlphaFold2 是当前蛋白质结构预测领域的代表性方上一篇Translumo3分钟上手Windows最强实时屏幕翻译工具下一篇终极资源下载神器5分钟学会全网视频一键保存秘籍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
