先从一个真实困难开始

今天读到某个 Agent SDK 增加了工具输出防护，明天看到另一个框架强调运行状态与上下文隔离。我们很容易知道“又发布了什么”，却仍然回答不了自己的工程问题：工具返回的内容在哪一步交给模型？一段外部文本为什么可能改变下一轮行为？哪些约束应该写进 Prompt，哪些必须落在服务端代码中？

对正在从 Java 后端转向 Agent 工程的开发者，这种困难不只是资料太多。更大的问题是，资料里的概念、框架中的实现、自己系统的设计和能够验证的行为，经常没有连成一条线。 看懂一句发布说明，并不等于知道怎样设计自己的系统。

Agent Evidence Lab 想把这条线接起来。它面向个人 Agent 工程学习与研发决策：围绕具体问题收集材料，保留来源，解释机制，在适用时提出受控实验，最后形成可以保存、重读和继续核查的研发判断。

这一章先建立大方向。后面五章再进入实际数据流、循环、上下文、引用与实验，不要求先记住接口和类名。

“研究 Agent 的 Agent”到底研究什么

研究对象是 Agent 的工程机制：循环怎样推进、上下文怎样形成、工具怎样执行、运行怎样恢复、结论怎样受到验证。模型、框架或 Release 是取得材料的入口，不是研究的终点。

例如，研究“工具输出防护”时，可以形成四层不同的问题：

层次 要回答的问题 需要的材料
变化 来源究竟说增加或修改了什么？ 对应版本的原文
机制 防护发生在工具调用前、结果返回后，还是进入模型上下文前？ 文档、实现、测试或足够具体的说明
借鉴 自己的 Java Agent 应把哪项责任放在哪里？ 已知机制、自己的架构与明确假设
验证 指定输入下，约束是否实际生效？ 独立验收依据与受控实验

当前系统已经能从保存的材料形成带引用的研究报告，也能对完整已保存原文做显式复核。后面三层需要多少额外材料，取决于问题。发布标题通常不足以还原具体规则；报告应保留这个缺口，而不是因为文章需要完整故事就自动填满。

因此，长期产品目标是帮助用户得到机制解释、代码与模型分工、可借鉴做法，以及尚未解决的边界。它不是任意主题的全网研究服务，也不提供任意外部代码执行。

人、模型和代码各自承担什么

人提出值得研究的问题，确认采用条件和风险，审阅报告，并决定是否批准适用的实验。模型帮助理解语义、连接问题与材料、解释陌生机制、提出建议。代码提供可以执行和检查的边界：来源身份、权限、工具契约、调用次数、预算、保存与引用校验。

Agent Evidence Lab从工程问题走向可继续核查的研发判断

先明确想解决的问题，再取得和解释材料。长期目标还包括受控实验与持续运行。

  1. 01人的问题

    例如：工具输出怎样进入下一轮上下文，应该在哪一层约束？

  2. 02来源与证据

    固定研究对象与材料版本，保留原文和证据缺口。

  3. 03受限研究

    代码组织检索与调用，模型解释语义，校验器检查允许的输出。

  4. 04报告与建议

    说明机制、适用范围、可借鉴做法与未知，保存为可重读记录。

当前已实现受限的研究与固定实验切片。主动追读材料、通用受控实验和服务器长期服务仍是后续能力。

图 01 · 产品目标与当前切片的关系示意；不表示每次研究都已执行实验。

这不是“把确定性步骤全部自动化，剩下随便交给模型”。哪些输入可以进入哪条路径，哪些输出可以被接受，仍需要逐项设计。比如引用能在原文中匹配，代码可以检查；一段引用是否真正支持问题中的命题，包含语义判断；是否允许执行某个实验，属于审批与执行权限，不能由模型的一句建议决定。

本项目的实际分工比一个通用 Agent 示意图更窄。当前首次证据搜索是代码确定的，有候选后模型主要做支持、反驳或证据不足判断。这个限制能让第一条链路更容易验收，也意味着主动寻找下一份外部材料仍是后续方向。第三章会沿源码展开。

为什么一个普通后端服务还需要这些机制

普通业务 API 往往可以把输入映射为明确流程。Agent 增加了一个概率性判断边界：外部材料可能不完整或带有伪指令，模型可能误解问题、返回非法结构、选错引用，供应商调用也可能超时或缺失用量。

这并不让事务、状态机和接口契约失去作用。它们反而成为接住不确定性的基础。系统需要知道上一步究竟完成了什么，下一步允许做什么，什么时候应停止，以及“完成”依据是什么。

概念 用日常工程语言理解 在这个项目中的位置
Agent Loop 带观察与验证的有限执行循环 组织搜索、决策、恢复和停止
Harness 托住循环的运行约束与基础设施 权限、协议、预算、租约、Checkpoint、Trace
Context 这一次模型调用实际收到的材料 问题、预算、选定候选与引用
Tool 允许调用的具体能力和输入输出契约 当前默认循环中的证据搜索等受限接口
RAG 按问题从已有资料中取出相关材料 PostgreSQL 全文检索与证据卡片
Memory 能在进程外继续读取的结构化记录 来源、研究、报告、实验与状态的持久化
Evaluation 用事先定义的任务检查行为 固定任务集、回归与有限真实模型样本

这些是理解本项目的工作定义，不宣称所有框架都采用相同分层。尤其是“数据库里保存了资料”和“模型本轮已经看到资料”，是两件不同的事。第四章会解释中间的选择过程。

项目的长期主线怎样展开

产品希望逐步形成下面的闭环。代码块是产品概念图，不是当前每次运行都会执行的流水线。

来源 → 信号 → 主张 → 证据 → 结论 → 研发决策
                           ↑
             适用的受控实验与独立验收
                           ↑
                  明确的计划与人工审批

第一步是让研究有稳定入口和保存结果。下一步是让具体问题和证据缺口决定继续读什么。再往后，才是用更广的来源、适用的受控实验和质量评测扩展能力，并作为长期服务运行。

这里的顺序很重要。如果连“哪份材料支撑哪项说法”都没有固定下来，先扩几十个仓库只会增加难以核查的文本。反过来，一条来源少、但问题、证据和未知清楚的链路，已经可以暴露有价值的工程问题。

当前已经走到哪里

本专题核对的是已合并 8afe9f4 基线。M0 服务骨架、M1 来源采集、M2 证据处理与 M3 受限循环，已有各自限定范围验收。M4 已完成固定 Prompt-strategy A/B、Signal 锚定研究 API 和个人原文复核等切片；完整 M4/M5 仍未关闭。

当前采集的三个仓库是 openai/openai-agents-python、spring-projects/spring-ai、langchain4j/langchain4j，都只采集 GitHub Releases。工程文章、文档、论文等仍属于后续来源。主动追读外部材料和通用实验执行也不能从“已有工具调用”推出已经具备。

现阶段运行在本机。已经能够保存报告、重启读取，并不意味着服务器长期运维、安全验证或全面语义质量已经完成。单次本地隔离数据库恢复已有记录；恢复后应用接入和异机恢复仍需另外验证。

怎样读完这六章

如果刚接触这个项目，按章节顺序读：先看研究流水线，再看Loop 与 Harness，随后理解上下文和质量。最后的真实切片与下一步将这些概念放回一个实际样本。

如果需要接续研发，每章末尾都有实现索引。先固定版本，再核对输入、输出、失败和测试依据；不要把解释性伪代码直接当作生产实现，也不要把后续设计当作当前接口。

沿实现继续核查

下表中的路径是项目内的逻辑索引，不是网站运行时的依赖，也不要求公开环境能访问私人开发仓库。

核对材料 应确认的内容 不能单独证明的内容
README.md、docs/PRODUCT.md 用户、产品使命、研究闭环和非目标 某项能力已经完成验收
docs/ROADMAP.md、docs/ACCEPTANCE.md 按日期核对里程碑及测试范围 任意真实输入的质量
docs/architecture/decisions/ADR-0001-agent-execution-runtime.md Java 默认执行面及 Python 扩展条件 语言性能的普遍优劣
docs/operations/DEPLOYMENT.md 本机运行、保存、恢复与未完成运维项 全新服务器已经部署成功

项目的价值最终要由研究产物回答：它有没有帮人理解一个机制、形成一个适用范围明确的判断，或者发现一项值得继续核查的未知。后面的实现细节都应回到这个目的。