企业官网建设流程全解析

本文基于 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-46）；
• Pi 运行时变更必须基于已安装的 Pi 包版本/文档/源码，优先复用既有 Pi 包与扩展能力，而不是本地自造 shim（AGENTS.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）。任何超出该清单的诉求，除非被显式限定在某次活跃研究运行内，否则一律拒绝。八个允许增长的科研任务为：

1. 发现相关论文、代码、数据集或先验工作（discovering relevant papers, code, datasets, or prior art）；
2. 阅读、提取与理解论文内容（reading, extracting, and understanding paper content）；
3. 排序证据、方法、可复现性或引文结构（ranking evidence, methods, reproducibility, or citation structure）；
4. 核实对来源、代码、数据或实验的声明（verifying claims against sources, code, data, or experiments）；
5. 规划或运行复现与科研实验（planning or running reproductions and research experiments）；
6. 综合科研结论为可审计工件（synthesizing research into auditable artifacts）；
7. 可视化研究结构——且仅当可视化会改变研究决策时（visualizing research structure when the visualization changes a research decision）；
8. 改进研究循环的速度、可观测性、溯源与可靠性（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-Goals）

requirements.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.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 test（325/325）→npm run typecheck→npm run build→npm audit --omit=dev全部通过，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、PaperContent
• EvidenceSpan、EvidenceGraph
• RankSignal、RankedPaper
• ResearchArtifact、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.ts，package 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_loop）；
• ResearchRun：携带runId、workflow、slug、topic、status（planned|running|completed|partial|blocked|failed）、researchJobs、sources、papers、entities、tools、artifacts、nextActions、verification与constraints；
• ResearchArtifact：kind已扩展为report|json|jsonl|graph|html|audit|provenance|template|prompt|model_output|ledger|plan|manifest；
• validateResearchRun：一个纯函数校验器，检查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.ts（105 行）覆盖 ResearchRun 主干与合法/非法插件清单。

STATUS.md 记录的本地 installed-tarball E2E 验证展示了完整链路：安装@companion-ai/feynman@0.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-inbox）：

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

7.2 允许的插槽类型与明确拒绝的类型

允许的插槽（含语义说明）：

• source_adapters：从 Scholar Inbox、OpenReview、Semantic Scholar、arXiv、PubMed 或会议 feed 返回论文候选；
• access_resolvers：返回合法的全文/访问候选（仅限合法访问，禁止绕过付费墙）；
• entity_extractors：从论文、图、说明、表、源码提取分子图、配体、蛋白质、基因、assay、方程、数据集、代码路径、benchmark 名与方法等类型化实体；
• rank_scorers：添加有界打分信号并携带溯源，不得静默改写核心打分语义；
• experiment_runners：针对显式输入运行有界复现/模型调用（如 BioNeMo 式折叠、对接、序列搜索、分子生成、benchmark 重跑），并把工件路径与 caveats 写回ResearchRun；
• artifact_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必须是1；
• name必须是包安全标识符，不允许/、\、..或绝对路径（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-first）：

• 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 })

runtime-contracts.md进一步规定 MCP 工具必须调用稳定的内核函数并返回有界工件/路径而非原始全文：resolve_paper返回访问候选、元数据、内容摘要与工件路径；inspect_evidence_graph返回图指标与选定的节点/边，而不是整图倾泻。拒绝方案包括"把每个 CLI 命令都暴露成 MCP"（setup/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 输出，会在重构中悄悄破坏行为。借鉴 Codex（agent 逻辑变更必须有集成测试）、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 围绕命令发 span；Pi 生命周期/工具/模型 span 走pi-otel；
• 新增插件/MCP 遥测只上报插件名、插槽类型、时长、状态、计数与错误类别。

十二、分阶段实施路线（带测试与回滚点）

综合规划文档（architecture.md "The Smallest Correct First PR"、handoff.md "The Decision"），最终落地顺序如下：

1. 架构守卫（已落地）：scripts/check-architecture.mjs+npm run architecture:check，行为保持、保护脏的 release candidate 不被继续撑大；
2. 机械抽取 PaperRank：把src/rank/paper-rank.ts拆成 papers/evidence/rank/artifacts 模块；首个 PR 保留paper-rank.ts作为兼容性 barrel，不改打分数学、不加 Scholar Inbox/MCP/插件安装/新命令，测试随模块迁移；
3. 拆分src/cli.ts命令处理器为src/commands/*；
4. ResearchRun与研究配方工件契约（契约代码已先行落地于src/research/contracts.ts）；
5. Pi 之上的研究插件清单/校验器（已落地于src/research/plugin-manifest.ts；feynman plugins用户命令暂缓，等待真实适配器消费方，如 Scholar Inbox 源或分子结构实体提取器）；
6. 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。