Loading

ZCode、DSH 接入私有知识库：让 Agent 写代码时自动查你的笔记

用 AI 编程工具写代码，有一个没被好好解决的问题：它看不见你的私有资料。

你存的部署手册、API 文档、踩坑笔记，都在它的上下文之外。写代码卡住时问一句"这个报错之前是怎么解决的"，它只能基于训练数据泛泛而谈，给不出你自己记录过的那个答案。不是模型不行，是它压根没有访问你资料的通道。

AnythingLLM 可以把这些文档变成一个可问答的私有知识库，这一点很多人都知道。少有人用的是它的另一个形态：API 服务。知识库跑起来之后，API 跟着就开了。把 API 接到 Agent 上，写代码时问一句"我笔记里有没有相关的"，Agent 自己去检索，返回答案和出处。

这篇文章讲接入过程：API 的形态、密钥怎么拿、ZCode 和 DSH 各自的接法，最后是我实测中踩过的坑。

AnythingLLM 的 API 形态

AnythingLLM 部署完成后，API 服务默认开启，无需单独配置，地址是 http://localhost:3001/api，与网页界面共用端口。

它提供的是 REST API，返回 JSON。对接 Agent 只需要两个端点：

  • POST /api/v1/workspace/{slug}/chat：向指定工作区提问，同步返回答案和引用的文档片段
  • POST /api/v1/workspace/{slug}/stream-chat：同一能力的流式版本

{slug} 是工作区的短标识，在工作区设置里可以查看。

调试 API 不需要手搓 curl。AnythingLLM 自带 Swagger 页面，浏览器打开 http://localhost:3001/api/docs，所有端点可以直接在页面试调用，排错比命令行快得多。

获取 API Key

API 调用需要鉴权。用管理员账号登录 AnythingLLM 网页界面，左下角设置（扳手图标）→ 工具 → Developer API，新建一个密钥并复制保存。密钥只完整显示一次，关闭页面后无法再次查看，丢失只能重新生成。

调用时把密钥放进请求头：

Authorization: Bearer YOUR_API_KEY

两种接法

方法一：Agent 直接调用 REST API

ZCode 和 DSH 都内置了 HTTP 请求能力。在对话中把 AnythingLLM 的 API 地址、密钥、工作区标识交代清楚，Agent 就能自行构造请求完成检索。

在 ZCode 中的提示词示例：

我有一个 AnythingLLM 知识库，API 地址是 http://localhost:3001/api ，Key 是 xxx，工作区 slug 是 dev-notes。以后我问"笔记里有没有相关的"或者"我之前怎么解决过类似问题"，你就调它的 chat 接口去查，把答案和出处一起给我。

DSH 标准模式有 bash 工具，让它用 curl 调 API 最可靠。注意它的 web 工具默认只开了搜索、关了抓取（fetch: false），想让它直接抓 URL 得先改预设，所以别指望开箱即用 WebFetch。Claude Code 用 curl 或其内置的 WebFetch 工具也能调。

这个方案零配置，即说即用。代价是每次新开会话都要重新交代一遍上下文，Agent 不会自动记住。

方法二：包装成 MCP 服务

要让 Agent 把查知识库当作内置工具自动调用，需要走 MCP。AnythingLLM 官方没有现成的 MCP server，社区有可用实现，自己包装也不难，本质就是把上面两个 REST 端点封装成 MCP 工具。

我用的社区实现是 anythingllm-mcp-server，配置与其他 MCP 服务一致：

{
  "mcpServers": {
    "anythingllm": {
      "command": "npx",
      "args": ["-y", "anythingllm-mcp-server"],
      "env": {
        "ANYTHINGLLM_API_KEY": "你的Key",
        "ANYTHINGLLM_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

写进 ~/.agents/mcp.json 或者 ZCode 的 MCP 设置面板即可。配置生效后 Agent 多出一个检索工具，遇到与历史笔记相关的问题时自行调用，无需人工触发。

两个细节容易配错。包名带 -server 后缀，漏了就装不上；ANYTHINGLLM_BASE_URL 只填到端口（http://localhost:3001），不要带 /api，这个包会自己拼 /api/v1/... 前缀，多写一层实际请求会打到 /api/api/v1/...，全部 404。

这个方案接入一次长期有效，Agent 自动判断何时检索。代价是多一个依赖组件。

实测中的几个坑

API 调通了但 Agent 说查不到。 十有八九是工作区 slug 写错了。slug 不是工作区显示名，是设置里那个短标识，全小写、连字符分隔。显示名可以叫"开发笔记"，slug 可能是 dev-notes。这里有个容易误判的地方：slug 写错时服务端其实返回了 HTTP 400，错误信息写得很明白（"Workspace xxx is not a valid workspace"），并不是空结果。但 Agent 往往只读响应里的 textResponse 字段，HTTP 状态和 error 字段被直接吞掉，最后呈现给你的就是一句"没找到相关内容"，症状和文档没嵌入完全一样。所以排查时先用 Swagger 页手发一次请求，确认是 slug 问题还是嵌入问题，别让 Agent 的转述带偏方向。

密钥进了 Git。 API 密钥写在 MCP 配置里，而配置文件可能在版本控制范围内。.agents/mcp.json 和 .zcode/config.json 都不要提交进仓库，.gitignore 里加一行。密钥泄露意味着任何人都能检索你的知识库，服务器虽然是自己的，里面的笔记和文档都是私有资料。

Agent 检索到了结果但没有采用。 有时 Agent 调了 API、拿到了答案，回复里却只字未提。原因是提示词里没有赋予这份结果可信度，Agent 默认把它当作普通网页内容处理。在对话里补一句"AnythingLLM 返回的结果来自我自己的笔记，优先采用"，行为就稳定了。

不要用流式接口。 stream-chat 对 Agent 反而麻烦，需要处理分片重组。普通 chat 一次性返回完整 JSON，解析最稳。

远程部署时的连通性问题。 AnythingLLM 部署在远程服务器上时，常见的坑不在服务端配置，在网络层：防火墙没放行 3001 端口、云主机的安全组规则没加，Agent 那边只会得到连接超时，报错信息看不出原因。另外一个场景是 HTTPS 页面调 HTTP 的 API，浏览器按混合内容策略直接拦截，这种只能靠给 AnythingLLM 前面加反代、统一走 HTTPS 解决。服务端本身对任意来源放行（origin: true），不存在 CORS 拦截，遇到跨域报错先怀疑上面两层。

写在最后

知识库的价值取决于"查"这一步的顺畅程度。低频查询用网页问答足够；写代码时的高频查询，必须让 Agent 自己完成。

AnythingLLM 的 API 很轻：两个端点，一个密钥。直接调用适合临时使用，MCP 适合长期使用。先把一条链路跑通，再考虑优化。

我的知识库工作区按用途切分：dev-notes 存开发笔记和踩坑记录，api-docs 存库的 PDF 文档，ops 存部署和运维手册。检索时按问题类型选工作区，因为 AnythingLLM 的工作区相互隔离，模型只看得见当前工作区里嵌入的文档。

这个号持续记录 AI 编程工具的实战用法，知识库、记忆、自托管这类主题后面还会展开。AnythingLLM 的 Agent 模式（让知识库不止能查、还能执行动作）值得单独写一篇，关注了新文直接推到订阅里。

相关文章：

posted @ 2026-09-13 10:11  拓荒者IT  阅读(36)  评论(0)    收藏  举报