学习笔记检索 Agent 的项目设计

我计划从一个和日常学习有关的任务开始：让 Agent 从自己的笔记中找出相关内容，并回答带有明确出处的问题。比如“工具超时后，程序应该重试还是结束”，回答需要指向笔记中的具体说明，而不能只凭模型记忆补出一个看似合理的结论。

第一阶段关注检索与阅读的决策，先建立可检查的实验任务。它目前是项目计划，本文确定实现范围与验收方法。

第一版任务范围

输入是一段问题，环境是一组固定版本的 Markdown 笔记，输出是答案与引用。笔记需要有稳定的文件标识和段落标识，使引用能被重新定位。

第一版暂时不接开放互联网。固定语料可以减少网页更新造成的变化，也方便检查系统是否找到了支持答案的内容。之后若加入联网检索，会作为另一个实验设置单独记录。

search_notes(query, top_k) 返回匹配片段及文件、段落标识。read_note(note_id, section_id) 返回指定段落与必要上下文。程序检查标识与参数，工具错误以结构化结果返回，模型无法通过这两个工具修改笔记。

下面是准备采用的返回格式示例，其中的内容和标识只是示意。

{
  "note_id": "tool-error-handling",
  "section_id": "timeout",
  "text": "对于临时网络超时，可以在预算内进行有限重试。"
}

模型读完结果后，可以继续检索、阅读，或者生成答案。调用次数与总运行时间都有上限；耗尽预算时返回已有证据支持的内容，或说明尚未找到答案。

三个版本使用相同问题和基础模型。固定检索与 Agent 使用同一语料、检索器和引用要求，另行记录各自的资源消耗。直接回答只是辅助对照：它没有访问笔记，不能把它与另外两个版本的差异全部归因于 Agent 架构。

计划先人工整理 30 个小规模用例，覆盖单篇笔记可回答、跨段落组合、关键词不直接匹配、语料缺少答案四类情况。每个用例标注必要事实与支持段落，缺少答案的用例则明确预期是说明信息不足。

用例分为开发部分与保留测试部分。开发部分用于调整提示词和实现，保留部分只在阶段性评测时使用。这个规模用于发现初期问题，不足以支持对真实用户整体表现的广泛结论。

每个用例准备运行三次，记录成功比例与波动。人工检查答案是否有证据支撑，程序检查引用是否存在、工具参数是否有效，以及预算是否超限。后续有明确评分规则后，再考虑引入模型评分，并检查它与人工判断是否一致。

每次运行记录问题编号、模型版本、提示词版本、工具请求、返回内容、停止原因、答案、耗时与 token 用量。接口没有返回用量时标记缺失，不用字符数冒充 token 数。

失败先按发生位置分类：没有检索到证据，找到了却未阅读，读到了却误解，引用与答案不一致，或者在无答案时仍然编造回答。分类后再选择要改检索、工具、上下文还是提示词，避免同时修改所有组件。

这个项目中的“何时检索、检索什么、何时停止”可以进一步成为策略学习的问题。Search-R1 将多轮搜索纳入训练，给出了一个相关研究入口，但自己的笔记任务仍需重新定义环境与奖励。Search-R1

训练候选任务会先限制为答案和出处可以检查的窄问题，成功判据同时包含答案正确与引用有效。调用成本先作为独立评测指标，之后再实验是否加入奖励，避免一开始就鼓励模型为减少调用而放弃任务。

仅调用托管聊天 API 的推理接口，不会在这个项目中完成模型参数更新。训练阶段需要另选可训练模型和支持训练的资源，固定数据划分，并核对轨迹与损失计算方式。实现时可参考 verl 对模型生成 token 与工具返回 token 的区分。verl Agent Loop

完成条件是：三种版本能运行相同用例；回答的引用可以定位到原文；工具失败、无答案和预算耗尽都有明确处理；评测输出包含结果与成本；至少整理一组失败轨迹并提出下一轮假设。

完成后再决定是否把检索能力接入 Loopy。博客入口用于展示和阅读，离线实验用于测量变化，两者共享经过检查的内容与实现，但分别记录各自的边界。