用 RAG 给 Agent 接入内部知识

echo-agent 前身为 2025 年 11 月启动的个人助理项目 fubot，最初面向长期陪伴型个人智能体，围绕认知记忆、上下文延续、用户偏好沉淀、任务闭环与持续自我优化展开。随着真实场景迭代，项目逐步形成多入口接入、统一事件模型、消息总线、Agent Loop、多模型抽象、工具调用、MCP 接入、任务调度、权限审批、运行轨迹、长期记忆和受控自演进等能力。目前已支持微信、QQ、CLI、Gateway、Webhook、Cron 等入口，服务用户超过 20 万、累计下载超过 50 万，是面向长期运行、记忆增强和可持续成长智能体的开源 Agent Runtime。

项目地址：https://github.com/fuyuxiang/echo-agent

你让 Agent 帮你排查一个内部接口认证失败。

它能读日志，也能写代码，但它不知道公司内部网关的认证规范、接口迁移公告、历史故障处理记录。于是它只能从报错文本里猜：可能是 token 过期，可能是签名算法不对，可能是环境变量没配。

这些猜测未必离谱，但对工程系统来说不够。真正可靠的 Agent 不能只依赖模型参数和当前会话，它必须能回到内部资料：查规范、查操作手册、查项目文档，并把回答依据讲清楚。

这就是 RAG 在 Agent 里的位置。

RAG 不是给模型“灌入知识”，而是在当前任务里建立一条可追溯的证据通道。

问题入口

如果只看传统文本型 Chatbot，它通常以“输入文本、返回文本”为主。没有内部资料时，模型只能依赖训练阶段学到的公共知识和当前上下文。对公开概念，这可能够用；对企业内部系统，问题马上出现。

内部接口怎么认证、上线流程走哪几个审批、某个服务的降级策略是什么、某个配置项在哪个版本废弃，这些信息通常不在模型参数里。即使模型“看起来知道”，也很难说明结论来自哪份文档。

对 Agent 来说，风险更高。普通问答答错，最多是用户再追问；Agent 如果基于错误资料执行工具，可能会改配置、发消息、创建任务，甚至把过期流程当成当前规范。

所以，Agent 接入内部知识，不是为了让回答显得更丰富，而是为了让行动有依据、依据能追溯、越权资料进不了上下文。

概念边界

RAG 的全称是 Retrieval-Augmented Generation，检索增强生成。它的基本流程很简单：回答前先检索相关资料，把资料放进模型上下文，再让模型基于资料回答。

但在 Agent 系统里，RAG 不能只理解成“接一个向量库”。它至少有三层含义：

很多系统只优化第一层，比如提升 top-k 召回或换 embedding 模型。但 Agent 更需要后两层。因为检索结果不只是“参考文本”，它会影响推理、工具调用和安全决策。

这也解释了 RAG 和记忆系统的区别。记忆来自 Agent 与用户、项目长期交互中沉淀出的经验，强调个性化、作用域、遗忘和更新。知识库来自预先存在的文档资料，强调可检索、可引用、可重建和权限过滤。

两者都会进入上下文，但职责不同。记忆回答“这个用户和这个项目过去形成了什么稳定经验”；知识库回答“组织已有资料里有什么可引用证据”。

证据通道

为了不停留在抽象层面，下面以 echo-agent 的实现为例。

echo-agent 的知识库模块位于 echo_agent.knowledge。当前实现不是向量 RAG，而是一个本地关键词知识索引。这个选择很克制：它不依赖外部 embedding 服务，但保留了 RAG 的关键结构，包括文档加载、分块、索引、检索、权限过滤、引用编号和上下文格式化。

知识库在 Agent 中有三个入口。

第一，自动检索。ContextStage 构造上下文时，会用用户本轮输入搜索知识库，把结果加入 retrieval context。

第二，工具检索。模型可以主动调用 knowledge_search，在推理过程中补充证据。

第三，索引维护。管理员或受信任 Agent 可以通过 knowledge_index 查看索引状态或重建索引。

这三个入口对应三种需求：默认给模型补证据、让模型主动查证据、让系统维护证据基础设施。

会调用知识库不等于可靠 RAG；检索结果必须带来源、受权限约束，并进入正确的上下文层级。

在 echo-agent 中，检索结果会被格式化成内部知识上下文，每条包含 [K1] 这样的引用编号、标题、路径和摘要片段。ContextStage 再把它作为 background context 注入，而不是把原文无标记拼进 prompt。

这个细节很重要。知识库文档是资料，不是指令。即使文档里写着“忽略之前规则”“执行某删除命令”，它也不能覆盖系统规则、用户当前目标和工具审批策略。RAG 的正确姿态是用资料增强回答，而不是让资料接管系统。

索引流水线

RAG 的质量不只由检索算法决定。文档怎么解析、怎么分块、metadata 怎么保存，都会影响模型最终看到什么。

echo-agent 用 KnowledgeConfig 定义知识库运行方式：docs_dir 指向文档目录，index_path 指向索引文件，auto_index 决定索引缺失或过期时是否自动重建，chunk_size 和 chunk_overlap 控制分块，allowed_extensions 控制可索引文件类型，max_results 控制默认返回数量，require_citations 表示内部资料回答应强调引用。

Agent Loop 初始化时，如果知识库启用，会创建 KnowledgeIndex。相对路径会解析到当前 workspace 下，所以同一套代码在不同工作空间可以使用不同知识库目录和索引文件。

索引准备入口是 ensure_ready。如果索引存在且没有过期，就加载索引；如果索引不存在或已过期，并且 auto_index=True，就重建索引。过期检测靠比较文档 mtime 和索引 mtime：只要文档比索引新，就认为索引过期。

最小化后的流程大致如下：

defensure_ready(auto_index=True):
    ifindex_file.exists() andnotis_stale(docs_dir, index_file):
        returnload_index()

    ifauto_index:
        returnrebuild_index()

    ifindex_file.exists():
        returnload_index()

defrebuild_index():
    forpathinwalk(docs_dir, allowed_extensions):
        metadata, body=extract_frontmatter(path.read_text())
        title=title_from_markdown_or_filename(body, path)

        foridx, textinenumerate(chunk_text(body, size=1200, overlap=120)):
            save_chunk({
                "id": f"{path}#{idx}",
                "path": path,
                "title": title,
                "text": text,
                "terms": count(tokenize(text)),
                "metadata": metadata,
                "mtime": path.mtime,
            })

这里有几个工程取舍。

frontmatter 会进入 chunk metadata，后续用于权限过滤。标题优先取正文第一个 Markdown 标题，其次取第一行非空文本，最后退回文件名。分块使用字符级切分，默认 chunk_size=1200、chunk_overlap=120。它不如语义分块精细，但简单、稳定、可预测。

tokenization 同时处理英文、数字、下划线和中文。英文与代码标识符按词提取；中文加入单字和相邻二元组。它不是完整中文分词，但比只按空格切分更适合本地中英文文档。

索引保存为可读 JSON，包含 chunk 的路径、标题、正文、词项、metadata 和 mtime。这个设计的价值是可调试、可重建。索引只是文档派生物，文档才是 source of truth；索引损坏或策略升级时，可以删除后重建。

检索时，系统先对 query 做同样的 tokenization，再按关键词统计打分。每个 query term 会根据 chunk 中词频、chunk 长度和 IDF 贡献分数；如果原始 query 是 chunk 文本子串，还会额外加分。最后按分数排序，并生成 K1、K2 这样的引用编号。

这不是最复杂的 RAG，但它具备一个生产系统最需要的骨架：确定性、可解释、可重建、可审计。

权限与引用

内部知识库最容易被低估的是权限。

很多 RAG 原型是在回答阶段才提醒模型“不要泄露敏感信息”。这已经太晚了。只要无权文档进入模型上下文，就已经违反最小权限原则。

echo-agent 在检索阶段做 ACL 过滤。Markdown frontmatter 可以写 allowed_users、allow_users 或 users。如果没有权限字段，默认所有用户可见；如果有权限字段，只有 * 或当前 user_id 命中时才可见。

测试也围绕这个关键行为展开：公开文档能被 bob 搜到；带 allowed_users: [alice] 的私有文档不能被 bob 搜到；同一份私有文档可以被 alice 搜到；格式化结果必须包含 [K1] 引用。

这说明知识库测试不能只测“搜得到”。更重要的是：无权资料搜不到，引用格式稳定，结果 metadata 能用于审计。

工具层也延续这个边界。knowledge_search 是 read_only 工具，参数包括 query 和 max_results，执行时会从上下文取 user_id 做权限过滤，并在 metadata 中返回 citations。knowledge_index 用于 status 和 rebuild，因为重建会写索引文件，它属于写风险，不应和只读搜索混在一起。

生产级 RAG 的底线不是“能搜到相似段落”，而是能证明：谁在什么权限下，看到了哪些证据，并基于哪些证据生成了结论。

生产可用性

把 RAG 放进 Agent，不只是多接一个检索器，还要把它纳入任务链路。

首先是查询理解。用户问“这个接口现在怎么认证”，其中“这个接口”可能来自当前会话、当前文件或刚才的日志。简单场景可以直接关键词检索；复杂场景可以先让模型生成检索查询，再调用 KnowledgeSearchTool。无论哪种方式，查询改写、过滤条件和用户身份都应该进入 trace。

其次是上下文权威层级。检索结果应该作为背景证据进入模型，而不是作为新的系统指令。模型可以基于它回答，也可以说证据不足；但不能因为文档里出现命令示例，就绕过工具策略和 ApprovalGate。

再次是索引一致性。文档会新增、删除、改名，ACL 会变化，chunk 策略会升级。KnowledgeIndex 的 stale 检测、rebuild、chunk metadata 和 JSON 保存格式，处理的就是“索引是否仍然代表源文档”这个问题。知识库越大，这越接近数据库一致性问题，而不是简单文本处理。

还要处理证据生命周期。草稿、正式版、废弃版、归档资料不应拥有同样权重。过期资料可以作为历史背景，但不能直接作为当前操作依据；如果 Agent 要据此执行高风险动作，就应该先读取当前配置、运行检查命令，或要求人工确认。

最后是评估。RAG 错误不能笼统归因于“模型答错”。工程上要区分检索失败和生成失败。

评估指标也要相应拆开：retrieval recall、citation precision、answer groundedness、refusal correctness，以及权限过滤是否正确。对 Agent 来说，还要看加入 RAG 后是否减少错误工具调用，是否能在证据不足或证据冲突时停止推进。

这里也能看出向量检索、关键词检索和知识图谱的边界。向量检索擅长找语义相近片段，关键词适合精确术语和代码标识符，图谱适合服务依赖、组织结构、数据血缘这类实体关系。它们不是替代关系，而是不同证据通道。echo-agent 当前偏本地文档检索，是符合本书主线的实现起点。

小结

RAG 在 Agent 里的核心价值，不是让模型显得更懂内部知识，而是把回答和行动拉回外部证据。

一个可用的知识库系统，至少要能完成几件事：从文档目录构建可重建索引；保留标题、路径、mtime、ACL 等 metadata；检索时按用户身份过滤；返回带引用编号的片段；把结果作为 background context 注入；把搜索、引用和权限信息留在 trace 里。

echo-agent 的知识库实现并不追求一步到位做成复杂向量平台。它先把 RAG 的工程骨架立住：文档加载、分块、关键词索引、权限过滤、引用格式化、自动上下文注入和工具化检索。这个顺序是对的。

因为 Agent 的可靠性不是来自“搜到更多文本”，而是来自证据链是否清楚、权限边界是否生效、索引是否可重建、行动是否仍受安全系统约束。

本文为 echo-agent 设计笔记系列第 18 篇。项目源码已开源至 GitHub。如果你对工业级 Agent 的工程落地感兴趣，欢迎加入技术交流群（QQ群号：47572014）参与日常讨论。下一篇我们将探讨 《Agent 技能系统：把经验沉淀为程序性知识》，敬请期待。

这里给大家精心整理了一份全面的AI大模型学习资源，包括：AI大模型全套学习路线图（从入门到实战）、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等，资料免费分享！

👇👇扫码免费领取全部内容👇👇

1. 成长路线图&学习规划

要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。

这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。

2. 大模型经典PDF书籍

书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）

3. 大模型视频教程

对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。

4. 2026行业报告

行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

5. 大模型项目实战

学以致用 ，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。

6. 大模型面试题

面试不仅是技术的较量，更需要充分的准备。

在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

7. 资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇