企业官网建设流程全解析

导读

本文讲解 jevgrep 仓库中 SWE-bench 官方研究证据的归档保存（research preservation）机制：为什么历史上数十轮 spike 实验要与产品代码（main分支）彻底隔离、如何用不可变快照与 SHA-256 manifest 逐字节固化 358 份研究文件、以及如何正确解读这些"源代码历史"而不误将其当成"可运行承诺"或"发布验收依据"。读完本文，你将掌握该仓库证据管理的主干规则——归档边界、校验手段、证据分级与本地运行存储的依赖关系，并能在检索旧实验、复现结论时避免踩中"证据误读"的典型陷阱。

一、背景：为什么官方 spike 历史需要单独归档

jevgrep 是一个面向编码 Agent 的检索 CLI：用一句话问题让jg返回相关文件、阅读线索与逐字源码摘录，其核心依托 Jev 对目录、文件与声明进行相关性判定（见 README.md）。在把它做成产品之前，仓库经历了大量SWE-bench spike（探索性实验）——不同的检索策略、打包形态、提示词与评估通路都被反复试错。这些实验是宝贵的证据来源，但不能与维护中的产品代码混在一起：

• spike 里包含大量被废弃、被替代甚至失败的 runner 与历史指令，若并入main分支，会让"产品实现"与"历史尝试"边界模糊；
• 旧实验的模型、时序、输出与状态描述只属于它自己的研究语境，不代表当前发布版本的行为；
• 因此 research-archive.md 明确定下规则：归档分支与main刻意分离，禁止把过时的 runner 或历史说明合并进产品。

这一分离原则在仓库文档体系中层层呼应：官方基准评估入口 evals/README.md 声明"研究档案在 Git 中保存被取代的官方实验，但不向main添加过时 runner"；specs/done/jevgrep/README.md 则记录"旧 spike 提示词、源码字节、启发式或输出格式无需保持不变"——即产品测试不再受旧 spike 约束。

二、归档机制：archive tag、不可变快照与原始相对路径

归档的核心载体是一个archive tag：archive/swebench-spikes-2026-09-26。临时归档分支在保存完成后即被删除，只保留该 tag 指向的不可变快照。快照包含全部 358 个此前未被 Git 跟踪的官方研究文件，并且严格保留它们在仓库中的原始相对路径，包括：

• 实验实现（experiment implementations）与对应测试；
• 原生 Agent 测试框架变体（native-agent harness variants）；
• 冻结配置（frozen configurations）与提示词（prompts）；
• 结果报告与分析（result reports and analysis）。

按原始相对路径存放的意义在于：档案中的每个文件仍可对照其历史位置理解上下文，研究记录中记录的路径、哈希与引用关系不会因迁移而失效。这也正是 specs/done/jevgrep/research.md 中"冻结参考"的做法——被冻结的 spike 源码（如 hierarchy-unit-locators-spike.ts）连同 SHA-256 摘要一起固化，原始 trace 与账单另行保留，拷贝的审计文件不能替代它们。

三、校验链路：research-snapshot-manifest.json 与逐字节 SHA-256

快照配套一份research-snapshot-manifest.json清单，记录其中每个文件的 SHA-256 摘要，并且"每个字节都对照本地归档验证过"（every byte was verified against the local archive）。

这种"清单 + 摘要"的校验思想并非只存在于归档环节，而是贯穿整个评估工具链，可以从 installed.py 的源码中看到一致的实现模式：

• digest(path)用hashlib.sha256计算文件摘要；
• 冻结计划（frozen plan）把 runner、broker、registry、skill、package 等所有必需构件的 SHA-256 写入plan.json的artifacts字段；
• 加载计划时逐项校验（load_cohort），任何构件摘要不匹配立即抛错Frozen artifact changed；
• 基线证据同样受保护：load_pair对照 fixed-baselines.json 校验基线 receipt、prompt 的prompt_sha256与官方评分结果，任何漂移都拒绝执行，且基线绝不重跑（"there is no baseline execution command"）。

由此可见，研究档案的 manifest 与评估 harness 的摘要校验同源同构：证据一旦冻结，就只能通过哈希比对确认未变，而不会被重新生成或改写。

四、保存的边界：不做模型调用、不重跑基线、不重算结果

归档保存是一个纯搬运与校验动作，明确排除了三类会改变证据语义的操作：

1. 无模型调用（No model calls）：保存过程不向任何模型发送请求，因此不会产生新的费用或新的推理结果；
2. 无基线重跑（baseline reruns）：基线证据保持其历史状态，不会为了"改善对比"而重跑；
3. 无结果重算（result recomputation）：官方评分与成本统计保持原样，不因归档而重新计算。

这与 cost-quality-policy.md 的原则完全一致——"每个任务、模型、harness 的基线只运行一次，复用固定结果，候选变更不构成重跑基线的理由"；"冻结的计划、早先的裁决与原始证据保留当时使用的标准，不会为了制造新结果而被重写"。

五、Git 快照 ≠ 全部证据：本地运行存储的不可替代性

文档特别强调一个容易被忽略的事实：快照是源代码历史，不代表每个旧实验都能从全新 clone 运行（"not a promise that every old experiment runs from a fresh clone"）。原因在于几类大体积工件根本不进 Git，只存在于被忽略的本地运行目录中：

• evals/runs/swebench/与evals/runs/tooling/（被.gitignore忽略的 run 存储）；
• 其中包含：原始响应（raw responses）、Agent 轨迹（agent traces）、基线产物（baseline artifacts）、源码快照（source snapshots）、评估数据集（evaluator datasets）；
• 这些工件的记录路径与哈希保持不变，但一旦本地存储丢失，就无法仅凭源码快照恢复。

这与 installed.md 描述的运行时证据闭环互为表里：每次 treatment 都会产出 receipt（生命周期收据）、agent.patch、raw-rollout.jsonl、proxy.jsonl与jev-traces（精确的 Jev 请求/响应体，由 gateway_broker.py 在不含认证头的独立容器中留存），失败或中断的尝试也一律保留、绝不替换。这些原始轨迹正是归档快照之外的"可恢复证据"所在。

六、证据解读入口：五类资料的分工

文档给出了一套"如何读证据"的导航，明确了五类资料各自的职责：

关键解读规则是：旧模型、时序、输出与状态陈述只描述它们自己的研究，不代表发布。例如 architecture-lessons.md 明确退役了旧 spike 的"七分之十成本获胜"目标（seven-of-ten cost-win target），说明它不是产品验收规则；evals/README.md 与 specs/done/jevgrep/README.md 也一致声明：被更正后的十任务队列曾以accepted: false收场、历史门槛不决定晋升，产品改进须按当前架构的评估政策与前一个发布版本对比。

七、档案之外：被排除的评估与冗余清理

归档边界还做了两件"减法"：

1. 废弃的个人仓库评估被排除在公共归档之外——其工具、fixtures 与本地归档在用户明确要求下被删除；官方 SWE-bench 研究与原始证据则按前述规则完整保留。这与 evals/README.md 中"个人仓库 fixtures 与自定义评分评估已废弃、留在 Git 之外、不作为产品验收证据"的声明一致；
2. 冗余的.claudeskill 链接被移除，规范化的开发 skills 保留在.agents/skills/，避免同一技能以多份副本散落造成版本漂移。

八、实践清单：在 jevgrep 仓库中安全使用研究档案

综合本文所述规则，使用该仓库研究证据时请遵循以下清单：

1. 定位：官方 spike 历史先看归档 tagarchive/swebench-spikes-2026-09-26，当前main分支只承载维护中的 CLI 与已安装包测试框架；
2. 校验：任何引用归档内文件的操作，先对照research-snapshot-manifest.json的 SHA-256 确认字节未变；评估场景则依赖 installed.py 对 frozen plan 的自动摘要校验；
3. 分级：把"旧实验的结论"（描述其自身研究）与"最终产品证据"（由 architecture-lessons.md 与 specs/done/jevgrep/README.md 负责）区分开，不以历史 spike 门槛作为发布验收依据；
4. 保真：不要用"最便宜的变体拼凑"或"重跑基线改善对比"来制造结果；官方任务完成是首要度量，完整编码 Agent 成本（含失败尝试）必须同时报告，Jev 成本单独记账（细则见 cost-quality-policy.md 与 installed.md）；
5. 备份：认识到 Git 快照无法替代evals/runs/swebench/与evals/runs/tooling/的本地运行存储，原始轨迹、基线产物与评估数据集的丢失是不可恢复的证据损失。

结语

研究档案保存的不是"能跑的代码"，而是"曾经发生过的证据"。jevgrep 用归档 tag 隔离历史、用 SHA-256 manifest 固化字节、用"不调用、不重跑、不重算"守住证据语义，再用本地运行存储补齐 Git 无法承载的大体积原始轨迹。这套机制的价值在于：它让每一份旧实验都能被定位、校验、分级与安全引用，同时明确划出"历史教训"与"产品验收"之间的边界——这正是严谨的基准评测工程（benchmark engineering）在证据管理上的核心范式，也是任何想要复现或扩展 SWE-bench 研究的读者首先应当理解的地基。