05 - 差距分析

这份文件汇集了项目文档和代码库中记录的每一个已知缺陷、限制和待解决问题——这些并非推测，而是项目本身已经标记的事项，加上阅读实际代码时发现的一些观察。按类别整理，大致按对您重要的程度排序。

一个有效的 API 密钥以明文形式存储在配置文件中。 apps/agent-server/mcp_servers.json 直接将 Tavily 网络搜索 API 密钥存储在代码读取的 JSON 中——该文件自身的注释自我说明了这一点。项目中没有任何密钥管理器的间接处理。任何能读取该文件（或其备份，或如果意外提交到 git 的提交）的人都会拥有该密钥。

写入执行前没有人工审批环节。 写入路径的护栏仅限制代理可以写入的位置（仅限知识库文件夹内），但在实际写入发生之前没有任何暂停确认的步骤。这已在 AGENT_SERVER_GUIDE_v2.md 自身的护栏清单中明确标记为尚未构建的一项。

速率限制和缓存是单进程、内存中的。 每个键的速率限制器、AGENT.md 缓存、自引用门的嵌入缓存以及 MCP 会话池都是普通的进程内字典。在当前规模下（一个进程、一台 Mac）这完全没问题，但一旦 agent-server 运行在负载均衡器后方的多个实例上，它们将无声地无法正常工作——每个实例将独立允许达到配置的限制。

备份位于它们所保护的卷上。 这涵盖了意外删除和错误编辑；但不涵盖驱动器故障。项目自身的 SFP（标准操作程序）已标记此问题并建议至少每季度将备份副本复制到外部设备——根据最后记录的状态，这尚未成为常规习惯。

两个知识库存在真实且已承认的覆盖范围缺陷，不是因为 bug，而是因为源文档确实难以自动获取：13 个 GAO/服务财务报告文件中约有 10 个，以及 17 个 DFAS/服务 FM 文件中的 14-16 个被 .mil/.gov 网站阻止，这些网站拒绝自动下载，需要手动获取。K-12 的 03-Lesson-Materials/ 文件夹和 DOD-FM 的 03-SOPs-Internal/、04-Reference-Data/ 和 05-Examples/ 文件夹覆盖率为 0%——项目自身的文档注明，这些类别只能从所有者自身的组织内容中填充，而非公共互联网，因此在有人刻意添加相关素材之前可能一直保持为空。

代理的沙箱无法发起出站网络请求。 每个知识库下载脚本都必须由人类主人在其自己的终端中运行——这是一个恒定的运营约束，而非一次性 bug，它塑造了任何未来批量摄取工作必须如何进行的方式。

**目前的 20 题质量基线处于 65% 的水平（13 通过 / 7 失败）。**这是一个真实测得的数值，而非猜测——但样本量也较小。在上次测量中的 7 次失败里，大多数可追溯至真实的检索质量缺口（答案存在于源文本中，但未被很好地呈现），一次是排序问题（已通过源权威权重修复），还有一次是答案深度投诉（已通过调整检索深度修复）。更广泛的测试覆盖范围将能提供更多信心，证明修复措施具有通用性，而不仅是对已测特定问题的修补。

**无跨请求提示缓存。**一个庞大且稳定的系统提示前缀（中位数约 4,400 个 token）会在每次请求中被重新发送和重新处理。其他推理栈（以及某些云服务提供商）会缓存重复的提示前缀以跳过重新处理——Ollama 对此没有控制手段，该项目自身的标准操作程序也指出这是一个现实存在的、未解决的延迟成本，且不切换推理层就无法修复。

**vLLM 是解决 FIFO 请求队列的标准方案，但在此硬件上不可用。**它需要 CUDA，完全无法在 Apple Silicon 上运行——因此必须通过调整 Ollama 自身的 NUM_PARALLEL 和上下文长度设置来管理并发请求瓶颈，而无法彻底解决。

流式和非流式请求是同一控制流的两种单独实现。 graph.py 的波次执行器处理非流式请求；流式路径则手写了一个等价的“规划后工具”循环，以便在标记到达时立即发射。未来对工具轮次预算、钩子执行顺序或内存记录的任何更改都必须手动应用于这两处——它们并不共享同一条代码路径。

技能匹配系统存在与刚在其他地方修复的问题完全相同的误报风险。 skills/loader.py 通过关键词重叠来匹配技能，且已确认存在真实案例：关于一个完全不相关技术主题的内容仅因共用词汇而匹配到了一个 K-12 特定技能。为自引用路由门限构建的两层（正则后嵌入）修复方案（步骤 5.9/5.10）已被明确指出可直接复用于此——但尚未应用。

自引用路由门限基于一个虽小但真实的样本进行校准。 0.80 并非猜测得出，但它也未在大規模对抗性集合上测试过——新的表述风格或真正的边缘情况可能会悄然导致合法领域问题的工具访问被禁用，且没有自动化回归测试来监控这种情况。

**对传入请求体无模式验证。**主端点解析原始 JSON，而非针对定义好的模式进行验证，因此格式错误的请求往往以不透明的内部错误形式呈现，而非清晰、友好的 400 响应。

有两个 MCP 服务器已接入但上线即失效。 fetch 和 secedgar 在使用当前安装的 MCP SDK 版本导入时均会崩溃——它们已被正确禁用，而非静默失败，但这确实表明 MCP Python 生态的 API 仍在此活跃演变中，未来新增的任何服务器在投入使用前都应在终端中进行冒烟测试。

记忆层的知识薄弱点检测仅依赖子串和正则表达式匹配。 成本低且易于审计，但较为脆弱——如果学生用意想不到的措辞或正则列表未涵盖的方式表达困惑，这些情况不会被记录；发生此类情况时也不会报错，只是静默漏捕信号。

CI 中未配置自动化测试套件。 虽已编写了真实的端到端和流式测试（test_endpoint_e2e.py、test_streaming.py），且通过评分测试题运行来评估质量，但尚未将其与代码变更自动关联——当前的正确性目前依赖于人工记得去手动运行它们。

微调流水线虽有雏形，但极其早期。 可供训练的已通过评分（PASS）示例仅 13 个——项目自身代码已明确标注，数量过少无法训练出有意义的适配器。只有一次真实的 LoRA 训练成功完成，但使用的是小型替代模型而非实际的生产模型，因为生产模型的 MLX 转换结果意外成为了一个视觉-语言变体，与所使用的纯文本微调工具不兼容。使用质量基线对训练好的适配器进行评估（这一步才能真正验证该方向是否值得继续）尚未进行。

代码中引用了其中一个构建步骤（5.8），但工程指南中从未将其撰写成文——这是一个已知的、小型的文档空白，而非功能性缺陷。

存在少量孤立遗留下的文件（memory_test2.db、过期的 wiki 导入状态文件、随意放置的 .webui_secret_key）——它们已被标记为可能无害的无效残留，但尚未清理。

约 19 个其他已集成项目中，仅有 1 个被直接验证过能正确接入新的代理服务器；其余项目均按相同模式假设运作，但尚未逐一确认。

这些都不是危机——项目自身的构建历史表明，一贯都是在实际使用中暴露出此类空白，随后通过精准且合理的机制加以修复。此处列出的仅是当前诚实的现状记录：已知、已记录、尚未完成。06_Improvement_Roadmap.md 已将其转化为一份优先级计划。