Software 2.0

Doc-Serve：私有代码智能检索

admin -

在AI代理的时代，一个持久的挑战脱颖而出：幻觉和代码代理的遗忘。即使是最先进的工具，如Claude Code，在查询复杂的、特定领域的信息时，也会自信地生成看似合理但不正确的答案，特别是当它缺少私有文档和专有代码库时。公共知识库有所帮助，但对于内部项目、企业系统或专用软件，真正的"真相来源"存在于封闭的门后。

这就是Doc-Serve改变游戏规则的地方。这是一个代理技能，它提供了一个私有的检索增强生成（RAG）系统，结合了智能文档索引、语义搜索，以及关键的深度代码理解，以提供准确、有根据的响应。其核心是Doc-Serve代理技能，这是一个原生代理技能，适用于Claude Code、Open AI、Gemini CLI、OpenCode等。这是一个集成，可以通过无缝访问您的私有知识库，将AI助手转变为强大的领域专家。

私有上下文丰富的RAG代理技能，用于搜索代码库和内部文档

我希望有一种方法可以下载代码和文档，并使它们可供我的代码代理搜索，这就是doc-serve代理技能的诞生。我编写了代理技能和工具，以递归方式下载Notion页面代理技能、JIRA票证代理技能和Confluence代理技能文档。将其与来自GitHub的代码库结合。加入Word文档、PDF、PowerPoint幻灯片，然后使用您自己的个人上下文语义RAG与LlamaIndex对它们进行索引，您的编码助手可以访问您的整个私有知识库。这也适用于SDD代理技能（规范驱动开发），因为现在我的规范是可搜索的，架构代理因为现在保存的计划、设计和指令是可搜索的。这也适用于项目内存代理技能。这可以帮助为您的编码代理提供更多的真实基础，以改进设计和编码工作。

摄取代码和文档，使其可通过RAG（向量相似性搜索和BM25）搜索

1、什么使Doc-Serve与众不同？

大多数RAG系统将文档视为纯文本。Doc-Serve更深入，特别是对于源代码：

  • 代码感知摄取：支持10种主要编程语言（Python、TypeScript、JavaScript、Java、Kotlin、C、C++、Go、Rust、Swift），使用Tree-sitter进行AST感知分块。这意味着沿着函数、类和逻辑边界进行智能拆分，而不是任意的行数。
  • LLM增强摘要：每个代码块都会获得由Claude Haiku提供支持的AI生成摘要，显著提高语义搜索的相关性。我们使用文档的标题和部分作为语义上下文。
  • 统一搜索文档和代码：一次查询所有内容，或按语言、来源类型（文档与代码）或两者精确过滤。
  • 混合搜索功能：结合向量嵌入（OpenAI的text-embedding-3-large）进行语义理解，与BM25进行精确关键字匹配。
  • 上下文感知分块：重叠的块在边界之间保留含义，避免碎片化结果。

结果如何？自然语言查询，如"后端中如何实现身份验证？"不仅返回相关文档，还返回带有摘要、交叉引用和精确上下文的实际代码片段。

摄取不同类型的代码库，并提供上下文感知分块以改进RAG，为您的编码代理提供改进的基础

1.1 Doc-Serve代理技能

突出的功能是doc-serve-skill包，这是一个专用的Claude Code代理技能，直接集成到AI工作流程中。

代理技能现在是一个标准，适用于GitHub Copilot、OpenCode、Gemini、Codex、Forge、Cursor等。

在Doc Serve代理技能的SKILL.md中定义的，是暴露简单而强大的命令：

  • query：使用自然语言搜索文档和代码，可选地按语言或来源类型过滤。
  • index：添加或更新文档和代码以保持知识库的当前状态。
  • status：监控索引的健康状况和进度。

一旦配置完成，Claude Code（或Codex或OpenCode）可以自主查询您的私有RAG系统。不再猜测，不再过时的公共信息。无论您是调试遗留代码库、入职新开发人员，还是构建需要可靠技术知识的AI代理，Doc-Serve代理技能每次都能提供有根据的、准确的响应。

1.2 现实世界的影响

想象这个场景：

您正在处理一个大型单体应用程序，文档分散，数千行Python和TypeScript代码。您问Claude：

"向我展示用户服务中如何保护API端点。"

启用Doc-Serve代理技能后：

  1. Claude使用过滤到Python代码的查询命令。
  2. 它检索相关函数及其AI生成的摘要。
  3. 它交叉引用相关文档。
  4. 您获得来自实际代码库的精确片段、文件路径和解释。

目标：无幻觉。无遗忘。无需挖掘文件。只需可靠、丰富的答案。我注意到的是，最多只能减少。

1.3 易于入门

Doc-Serve对开发者友好且开源（MIT许可）：

git clone https://github.com/SpillwaveSolutions/doc-serve-skill.git

cd doc-serve-skill

task install

cp doc-serve-server/.env.example doc-serve-server/.env

添加您的OpenAI和Anthropic密钥：

task dev

我相信这个技能会自行安装，因此从技术上讲，您只需安装技能并告诉它设置自己。

然后索引您的项目：

doc-svr-ctl index ./my-project --include-code

然后查询：

doc-svr-ctl query \
"authentication flow" \
languages python typescript

再次强调，这个技能知道如何完成所有这些，因此您只需告诉它要索引哪些目录以及要搜索的内容，它就会运行正确的命令。

Doc-Serve代理技能无缝集成到您的AI编码助手工作流程中。

1.4 有根据的AI的未来

Doc-Serve代理技能不仅仅是另一个RAG工具。它是下一代AI代理的蓝图，这些代理以企业级可靠性运行。通过结合私有知识、代码智能和原生代码代理集成，它消除了现实世界AI采用的最大障碍之一：信任。您可以为您的私有企业知识提供基础。

无论您是独自开发人员维护复杂项目，还是团队构建专有系统，Doc-Serve都能使您的AI助手真正理解您的领域。

查看存储库https://github.com/SpillwaveSolutions/doc-serve-skill，为其点星，尝试这个技能，并加入朝着更可靠、有根据的AI发展的运动。无幻觉的技术援助时代已经到来。

2、安装指南

2.1 安装skilz

Skilz是AI技能的通用包管理器。

pip install skilz

验证安装：

skilz --version

2.2 安装doc-serve-skill

选项A — 全局/用户安装

安装到您的默认代理技能目录（例如，Claude的~/.claude/skills）：

skilz install https://github.com/SpillwaveSolutions/doc-serve-skill

选项B — 项目级安装

如果您希望技能与特定项目目录绑定，请使用此选项：

skilz install https://github.com/SpillwaveSolutions/doc-serve-skill --project

这将本地安装到：

./.claude/skills/

（或等效于您的代理）

2.3 定位特定AI代理（可选）

您可以使用--agent为不同的编码助手特别安装Doc-Serve。您可以在用户安装或项目安装--project中使用此标志。

示例：为Codex（Cursor等）安装

skilz install https://github.com/SpillwaveSolutions/doc-serve-skill \
  --agent codex

您可以将codex替换为以下任何选项：

--agent gemini
--agent copilot
--agent opencode
--agent claude

（...等等 — 总共14个代理。）

对于项目级别，这将在以下位置安装技能

.codex/skills
.gemini/skills
.github/copilot/skills
.opencode/skill
.claude/skills（如果您省略代理，这是默认值）

对于用户级别（无--project）

~/.codex/skills
~/.gemini/skills
~/.config/opencode/skill
~/.claude/skills（如果您省略代理，这是默认值）

2.4 使用Doc-Serve

安装后：

进入规划模式（或您的代理的等效模式）。描述您想要包含的代码库和文档。

要求您的编码助手：

  • "使用doc-serve技能使以下位置可搜索... "

然后让它自由发挥。

因为Doc-Serve已经索引了您的：

  • 规范 设计/代码/内部文档

...您的代理现在将在您的真实私有上下文中为答案提供基础，而不是通用知识。

或者，如果您有notion、confluence或JIRA技能，您可以说

"保存以下JIRA中的史诗上下文...并查找Confluence中的相关文档和风格指南，以及这些Github仓库，然后搜索相关的Github仓库并将它们下载。将confluence页面和子页面存储在./confluence下，将史诗和相关票证存储在./tickets下，并将仓库放在架构代理目录中的./related-repos下。"

我最近做了类似的事情，效果非常好。当你制定一个计划并成功实施时，感觉真棒。

3、结束语

我写这个doc serve技能已经有一段时间了，最近才开始更多地使用它。在实际构建之前，我考虑构建它已经很久了。它已经酝酿了一段时间。我曾在2023年为一个客户构建了类似的东西，但项目在上线之前就结束了。现在的工具要好得多。LlamaIndex太棒了。

我肯定想要添加的是基于Ollama的文本嵌入，这样我就可以在本地环境中保留所有内容以供搜索。我还想使用基于Ollama的LLM进行摘要，可能还用于搜索相关任务。这在原始规范和计划中，还有很多其他事情，但我想要一个最小的可行版本，可以工作，然后我可以逐步发展。在我看来，项目成功的最快方式是让最小的可行版本工作，然后在此基础上添加。即使是基于AI的项目，如果太过雄心勃勃，也会半途而废。保持简单，它已经比你想象的要难得多。

目前，我知道我正在使用Claude Haiku进行上下文感知分块的摘要，以及OpenAI最新的嵌入进行向量索引和查找。我希望使所有这些都可配置，以便用户可以更轻松地交换组件。例如，基于Ollama的嵌入和LLM。

我的一个重要目标是使其完全私有和本地化，这样任何东西都不必离开您的机器。幸运的是，我有一台性能相当强大的机器，因此对于我个人来说，性能不应该是一个主要问题。但是，并非每个人都拥有一台会烧坏你腿的笔记本电脑。

我希望改进的另一件事是安装体验和整体设置的严谨性。我希望更清晰地支持多个安装，使轻量级BM25索引与轻量级向量搜索并行运行更容易，并一般改进端口和资源管理。理想情况下，系统应该跟踪正在使用的端口，并使每个项目的安装更无缝。目前还没有达到这个水平。

目前，它可以工作，但仍然感觉像是一个工作原型，而不是一个成熟的产品。话虽如此，它实际上工作得相当好。我已经尝试过，并且成功使用过，只是没有我希望的那么频繁，因为我被其他项目拉走了。这是吃饭的需要、新鲜事物和不断出现的项目的组合。

从长远来看，我希望将其转变为一个功能齐全的插件，具有适当的命令和代理。但这可能目前不是优先事项。我喜欢保持它作为"代理技能"的一点是，它仍然与许多不同的AI编码代理兼容。一旦它成为正式的插件，跨工具的兼容性可能会变得更棘手。到目前为止，我主要在使用我的架构代理时测试了它，这是一个管理其他编码代理的代理技能。我平等地使用Claude Code和OpenCode，并混合使用Codex和Gemini。

另外，我还有其他项目使用Postgres，支持BM25和通过pgvector的向量嵌入。我希望创建一个此doc-serve系统的版本，也适用于Postgres。我真的很喜欢这个组合。我目前的想法是，它将创建自己的Postgres数据库，并可能为每个项目创建一个单独的数据库，以便一切保持隔离。但也许更好的是启动docker容器。我不确定。并非每个人都有98GB的内存。另外，如果有人愿意捐赠10,000美元，我将非常乐意拥有一台配备512GB内存的新Mac Studio。我太想要一台了。

我肯定希望保持索引分开，而不是将所有内容混在一个巨大的存储中。我还没有完全确定最佳的设计，因此需要更多地思考这一点。

最初，我的计划是仅使用DuckDB及其向量嵌入支持。但在实际中，我经常同时在多个AI编码代理上使用此系统，我对DuckDB是否能在多代理、网络场景中良好扩展没有信心。但DuckDB可以是一个选项，甚至是新的轻量级SQLight变体/分支，内置网络和复制功能，但不是高优先级。

这就是为什么我真的希望有更多的网络服务层，以便多个代理可以同时查询它。我经常在OpenCode、Claude Code、Gemini CLI和Codex之间切换，有时甚至在同一个项目上，具体取决于我正在做的事情或遇到的令牌限制。我确实需要针对同一个语料库进行RAG。

这就是我目前的思考。这是一个有趣的项目，我很兴奋继续改进它。它今天已经很有用，但可以使用一些关爱。

向LlamaIndex致敬，它使得所有这些变得如此可行和容易。

原文链接：Give your Claude Code, OpenCode and Codex full RAG over docs and code repos

汇智网翻译整理，转载请标明出处