换一个 AI 就失忆?让四个 Agent 共用一份知识库

一句话读懂:换一个 AI 工具就要把背景和规范重讲一遍?根源是每个工具的记忆都是私有的。本文把记忆抽成三层:git 仓库存 Markdown 事实、两百行 C# 手写 stdio MCP 服务负责读写、一段全局协议约束调用时机,并给出四个工具的具体配置位置(含豆包工作的自定义连接器与仅本地模式限制)、WorkBuddy 信任开关、验证步骤、实测数据(169 条目单次检索 90 毫秒)与七个真踩过的坑,附可直接运行的示例仓库。

😩 01 换一个 AI,我就得从头讲一遍

我平时同时在用四个 AI 工具:TRAE 写前端和桌面端,Qoder 看后端仓库,WorkBuddy 处理零散脚本,豆包工作做跨工具的统筹——写文章、出图、跑本地连接器都在它上面。用久了发现一个很浪费的现象——同一件事,我要说四遍。

同一个代码规范,四个工具各讲一遍;上周在 A 工具里踩过的坑,这周在 B 工具里原样再踩一次;我刚跟 A 说清楚「这个项目的分页参数叫 page/pageSize」,切到 B,它照样给我写成 current/size。

原因不复杂:每个工具的记忆都是私有的。TRAE 写自己的项目记忆和会话流水,Qoder 写 MEMORY.md,WorkBuddy 又是另一套格式,豆包工作则把记忆绑在账号侧,彼此不可见。切换工具的那一刻,上一份上下文就断了。

于是我决定把「记忆」从工具里抽出来:不再指望每个 AI 自己记事,而是让它们读写同一份外部知识库。

🏗️ 02 结论先行:三层,缺一层就退化

这套东西最终落成了三层结构。

三层架构

层 负责什么 具体是什么
数据层 事实存在哪 一个 git 仓库,全部 Markdown + front-matter
接入层 怎么读写 一个 stdio MCP 服务,提供 5 个工具
规则层 什么时候读写 各工具全局规则里的一段协议

一句话分工:数据层管「是什么」,接入层管「怎么读写」,规则层管「什么时候读写」。

三者缺一个就会退化。只有数据层,AI 不知道它存在;只有接入层,AI 会乱写;只有规则层,AI 会说「好的我记住了」,然后记在它自己的私有记忆里。

📁 03 数据层:为什么必须是 Markdown + git

选 Markdown 不是为了好看,是三个实际需求叠加的结果:

  1. 人和 AI 都要能改。出问题时我能直接打开文件看、直接改,不需要先写代码解析。
  2. 要能当 Obsidian vault。把 AI 知识库当个人笔记库用,人和 AI 共用同一份文件,这是最省事的方案。
  3. 要能回滚。AI 改坏一条结论的风险是真实存在的,git diff 和 git checkout 是最便宜的保险。

目录按「知识的使用范围」切,不按技术栈切:

kb/
├── INDEX.md              唯一入口,≤200 行,只放 id + 摘要 + 标签
├── profile/              跨项目画像:身份、代码规范、本机环境
├── domain/               跨项目领域知识:一个主题一个 md
├── projects/<slug>/      一个项目一个文件夹,主文件 project.md
├── rules/                全局协议的单一真源,各工具同步这同一段文本
└── archive/<YYYY-MM>/    每日流水,复用 2 次以上再晋升

每个条目自带 front-matter:

---
id: projects/demo-app/project
title: demo-app 项目长期约定
tags: [Vue3, .NET, 接口约定]
scope: project
updated: 2026-11-17
source: TRAE-CN
---

关键在于 INDEX.md 是唯一入口且限死 200 行。AI 开工先读它,判断有没有相关条目,再按 id 读正文。这一步决定了 token 成本和准确率——如果允许「整库加载」,库越大越慢、越容易被无关内容带偏。

🔌 04 接入层:两百行 C# 手写一个 MCP 服务

有人会问:既然是普通文件,为什么不让 AI 直接读写文件夹?

可以,但会丢三样东西:统一的写入格式(front-matter 靠 AI 手写迟早写歪)、统一的检索逻辑、以及「写完自动提交」。用 MCP 是因为它是宿主应用都认的标准协议,一次实现,四个工具都能接。

服务本身很薄:stdio 收 JSON-RPC,分发到 5 个工具。主循环不到 20 行:

string? line;
while ((line = stdin.ReadLine()) is not null)
{
    if (string.IsNullOrWhiteSpace(line)) continue;

    var response = HandleRequest(line, store);
    if (response is null) continue;   // 通知类请求不回包

    stdout.WriteLine(response.ToJsonString(ResponseOptions));
    stdout.Flush();
}

检索没有上向量库,就是逐文件扫描加加权计分——标题命中权重最高,其次标签,最后正文:

// 分项计分:标题权重最高,其次标签,正文最低
var score = 0;
foreach (var token in tokens)
{
    var titleHits = CountHits(title, token);
    var tagHits = tags.Any(x => x.Contains(token, StringComparison.OrdinalIgnoreCase)) ? 1 : 0;
    var bodyHits = CountHits(body, token);

    if (titleHits + tagHits + bodyHits == 0) continue;

    score += Math.Min(titleHits, 3) * 5 + tagHits * 3 + Math.Min(bodyHits, 5);
}

五个工具覆盖了完整闭环:

工具 用途
kb_index 读索引,开工前先判断有没有现成结论
kb_search 关键词检索,返回 id、得分和命中片段
kb_get 按 id 读全文
kb_upsert 写入条目,自动补 front-matter、登记索引、git commit
kb_log 追加当日流水

真正省事的不是检索,是 kb_upsert 里这两行:

RegisterInIndex(id, title, tags, updated);          // 索引与内容不脱节
KbGit.Commit(_root, [path, indexPath], $"kb: upsert {id}");

写知识这件事,最怕的不是写错,是索引和内容慢慢对不上——条目加了但索引没加,三个月后没人知道库里有什么。自动登记把它变成不可能发生的错误。

一次任务的读写时序大致是这样:

读写时序

📜 05 规则层:协议写多细,AI 才会真的用

服务装好之后,你会发现 AI 根本不主动用——它不知道这个工具该在什么时候调用。所以每个工具的全局规则里都要贴同一段协议:

知识库协议
1. 唯一真源:E:\KnowledgeBase\kb(git 仓库),INDEX.md 是入口且 ≤200 行
2. 开工前先读 INDEX.md,按标签定位条目再读正文,禁止整库加载
3. 涉及历史决策/约定/踩坑时调用 kb_search,不凭记忆猜
4. 收工前用 kb_upsert 写回稳定结论,过程性结论用 kb_log
5. 各工具自带 memory 仅作本地缓存,事实以知识库为准

但协议文本本身别写成四份。我把它落在 rules/global-protocol.md 里,各工具的全局规则只同步这同一段:改一处、逐端覆盖。否则改了一处忘了另一处,某端会按旧规范悄悄执行,而且不会自报——这种错误你不会收到任何报错信号。

三个细节决定它有没有用:

  • 必须写绝对路径。写「知识库目录」等于没写,AI 会自己猜。
  • 必须写明时机。「可用工具」和「什么时候用」是两件事,前者 MCP 已经解决,后者只能靠规则。
  • 必须写冲突规则。否则 AI 会拿私有记忆跟知识库打架,你永远不知道它这次信的是哪份。

⏱️ 06 实测:169 个条目,单次检索 90 毫秒

有人会担心「逐文件扫描」的性能。本机实测(Windows、.NET 10、169 个 Markdown 条目、取前 5 条):

指标 数值
首次调用(含进程冷启动) 152 ms
稳定后单次耗时 82 ~ 89 ms
10 次平均 90.3 ms

实测数据

这个量级对「一次对话调用两三次」的场景完全够用。刻意没上向量检索,原因是规模不匹配:几百到几千条时,关键词加权的效果不比向量差,但可解释性好得多——得分怎么来的我能算清楚,召回错了也能直接调权重。

升级路径也想好了,但不提前做:条目过千换 SQLite FTS5(trigram 分词),再往后才考虑本地 embedding。一步跳到向量是把简单问题复杂化。

🕳️ 07 七个真踩过的坑

踩坑清单

1. stdout 被日志污染。 MCP 的 stdout 只能输出协议报文,任何一行 Console.WriteLine 调试都会让宿主解析失败,表现是「服务连上了但工具全挂」。所有诊断信息必须写文件或 stderr。

2. 中文返回被转义成 \uXXXX。 默认序列化会把整段中文变成转义码,报文体积翻几倍还难读。加上 JavaScriptEncoder.UnsafeRelaxedJsonEscaping 才是正常输出。

3. 通知类请求回了包。 notifications/* 不需要响应,回一个空结果也算协议违规。判断方法名以 notifications/ 开头直接 return null 即可。

4. id 越界写入。 kb_upsert 的 id 是相对路径,如果不校验,../ 能把文件写到知识库外面。解析完路径必须确认仍在根目录内。

5. 用目录 junction 合并各工具记忆。 想过偷懒:把四个工具的记忆目录链接到一起。结论是不可行——写入格式不同(jsonl 流水、MEMORY.md、话题 md),链接同一目录会互相覆盖。junction 只适合一次性导入存量。

6. 索引和内容脱节。 前面说过,靠自动登记解决。这条是使用三个月后最值钱的一条。

7. 豆包工作的连接器只认本地电脑模式。 它在设置里能正常添加、显示「连接器已安装」,但云端任务里调用一律失败——自定义连接器只支持本地电脑。更绕的是它跑在虚拟桌面里:Windows 账户没设密码时,虚拟桌面初始化直接失败(NO_SESSION),而且虚拟桌面的登录态与主桌面独立,要单独登录一次。三条叠在一起,现象很像「服务坏了」,其实服务一直好好的。

🧹 08 治理:让知识库半年后还能用

知识库最大的敌人不是写不进去,是变成垃圾场。我给自己定了六条:

  1. 单写通道:只经 MCP 写入,不手改,保证每次变更都有提交记录。
  2. 晋升机制:archive/ 里的流水被复用 2 次以上,才提升到 projects/ 或 domain/。
  3. 索引预算:INDEX.md 不超过 200 行,超了按 scope 拆分。
  4. 过期降权:updated 超过 90 天的决策标 stale。
  5. 人工层共存:Obsidian 打开同一目录当 vault,人和 AI 共用一份文件。
  6. 敏感信息不入库:令牌、客户隐私写库前先扫描。

第 2 条是最反直觉也最有用的。如果每次对话都往库里塞一条,三个月后检索全是噪音;只有被反复复用的东西才值得晋升成正式条目。

🚧 09 这套东西不适合谁

说清楚边界,比只讲好处更有用:

  • 只用一个大模型、一个工具的人:直接用工具自带的记忆就行,别折腾。
  • 期待「AI 全自动维护知识库」的人:做不到。它仍然需要你在收工时明确说一句「把结论写回去」,协议只能降低遗忘率,不能消除。
  • 需要团队协作的场景:这套是单人单机方案。多人要加权限、冲突合并和评审流程,成本是另一个量级。

还有一条必须承认:各工具自带的记忆不会消失,它们会继续写。我们能做的只是把它降级成「本地缓存」,用冲突规则让知识库当唯一事实源。

🛠️ 10 从零配起来:六步

整套东西我放成了可运行的最小示例,两个平台内容一致:

  • GitHub:https://github.com/lixiaoliyubo/kb-mcp-demo
  • Gitee:https://gitee.com/lixiaoliyubo/kb-mcp-demo

第 1 步:编译服务

git clone https://gitee.com/lixiaoliyubo/kb-mcp-demo.git
cd kb-mcp-demo
dotnet build .\kb-server\KbMcp.csproj -c Release

产物是 kb-server\bin\Release\net10.0\KbMcp.dll。零第三方依赖,只需要 .NET 10 SDK(dotnet --version 能看到 10.x 就行)。

第 2 步:先确认两个路径

变量 指向 判断标准
dll 路径 ...\bin\Release\net10.0\KbMcp.dll 文件真实存在
KB_ROOT 知识库根目录 目录下直接有 INDEX.md

以仓库里的示例为例:

dll       D:\Projects\kb-mcp-demo\kb-server\bin\Release\net10.0\KbMcp.dll
KB_ROOT   D:\Projects\kb-mcp-demo\kb-demo

两个路径都必须是绝对路径。别用 ~ 或相对路径——MCP 进程的工作目录由宿主应用决定,跟你想的不一样。这也是我见过最多的一类配置失败。

第 3 步:把服务加到各工具里

配置永远是三要素:命令、参数、环境变量。

{
  "mcpServers": {
    "kb": {
      "command": "dotnet",
      "args": ["D:\\Projects\\kb-mcp-demo\\kb-server\\bin\\Release\\net10.0\\KbMcp.dll"],
      "env": { "KB_ROOT": "D:\\Projects\\kb-mcp-demo\\kb-demo" }
    }
  }
}

两个容易翻车的点:

  1. JSON 里反斜杠要写两个。D:\Projects 会被当成非法转义,必须写成 D:\\Projects。
  2. command 找不到就换成绝对路径。一般装在 C:\Program Files\dotnet\dotnet.exe;不确定先在终端跑 where.exe dotnet。

「去设置里找找」是最容易卡住的一步,所以直接给位置:

工具 配置位置
豆包工作 左侧「插件 · 技能 · 伙伴」→ 插件页右上「+ 添加」→ 新建自定义连接器(stdio):命令填 KbMcp.exe 绝对路径、参数留空、环境变量 KB_ROOT。仅本地电脑模式生效,配置只存账号侧,本地没有配置文件
WorkBuddy C:\Users\<用户名>\.workbuddy\mcp.json,直接用文本编辑器改
Qoder CN C:\Users\<用户名>\.qoder-cn\settings.json;同目录的 mcp-router.json 是运行时文件,不要手改
TRAE CN 设置 → MCP → 添加自定义 MCP(stdio)。配置存在应用数据库 state.vscdb 里,只能走 UI,不要手工改库;command 必须写绝对路径
Claude Desktop %APPDATA%\Claude\claude_desktop_config.json
Cursor %USERPROFILE%\.cursor\mcp.json

改完保存,重启工具才会加载。核心原则:多个工具填的是同一份配置——同一个 dll、同一个 KB_ROOT,否则又退化成各存各的。

第 4 步:WorkBuddy 还要单独开「信任」

这一步是 WorkBuddy 特有的,也是我踩过的一个坑:它把「注册」和「授权」拆成了两个文件。

  • mcp.json 负责注册服务;
  • 同目录的 mcp-approvals.json 负责记录你允不允许它被调用,内容长这样:
{
  "edea4489bb92ef30ff0e8fd85009886d71f644dce1ef8e2cf5f71a3d5d2f55cf::kb": 1794846510789
}

键是「配置哈希::服务名」,值是授权的时间戳。

只改 mcp.json 而不开信任,现象很有迷惑性:MCP 列表里能看到 kb,工具也能列出来,但一调用就被拒绝。看起来像服务有问题,其实是没授权。

处理办法:在 WorkBuddy 的 MCP 设置里对 kb 这一项点「信任 / 允许」,或者在首次调用时按弹窗确认,之后 mcp-approvals.json 会多出一条记录。

还有个后续影响:如果你改了 command、args 或 env,配置哈希会变,旧的信任记录可能对不上,需要重新确认一次。遇到「昨天还能用,今天突然调不动」,先回头看这个文件。

第 5 步:写全局规则

MCP 装好只代表「有能力」,还得告诉 AI「什么时候用」。把这段贴进每个工具的全局规则:

知识库协议
1. 唯一真源:D:\Projects\kb-mcp-demo\kb-demo(git 仓库),INDEX.md 是入口
2. 开工前先 kb_index 读索引,按标签定位条目再 kb_get 读正文,禁止整库加载
3. 涉及历史决策、约定、踩坑时先 kb_search,不凭记忆猜
4. 收工前用 kb_upsert 写回稳定结论,过程性结论用 kb_log
5. 各工具自带 memory 只当本地缓存,与知识库冲突时以知识库为准

规则放在哪也说清楚,不然它大概率躺在某个对话框里:

工具 全局规则位置
TRAE CN C:\Users\<用户名>\.trae-cn\user_rules\ 下的 md 文件
WorkBuddy C:\Users\<用户名>\.workbuddy\USER.md
豆包工作 没有全局规则文件:用长期偏好(每次会话自动注入)承载「先读索引、以库为准、收工写回」,再用一个技能承载「怎么读、怎么执行」的细节
其他工具 设置里的「全局指令 / 自定义规则 / System Prompt」入口

第 2 条和第 4 条最容易被漏。只写「你可以使用知识库」,AI 大概率不用;写清「开工先读、收工写回」,它才会形成习惯。

第 6 步:验证,别只看「保存成功」

直接在对话框里说:

读一下知识库索引

预期返回 INDEX.md 全文,能看到 id、摘要、标签组成的表格。接着说:

在知识库里搜一下 MCP 的 stdio 约束

预期返回 1~5 条命中,带 id、得分和命中片段。两条都通,说明读取链路没问题。

再验写入:

把「对外接口统一返回 code/message/data」写进知识库,挂到 projects/demo-app 下

预期返回「已写入条目」,并且在 KB_ROOT 下执行 git log -1 能看到一条 kb: upsert ... 的提交。

配不通时先查这五项

现象 大概率原因 处理
工具列表里没有 kb 配置没保存 / 没重启 重启宿主,确认改的是它真正加载的那个配置文件
工具可见但一调用就被拒 WorkBuddy 没开信任 在 MCP 设置里点「信任」,确认 mcp-approvals.json 有对应记录
报「知识库根目录不存在」 KB_ROOT 没设或写错 确认该目录下直接有 INDEX.md
报「未找到 INDEX.md」 KB_ROOT 指到了 dll 目录 改成知识库根目录,不是 bin
返回乱码 / 宿主提示解析失败 改代码时往 stdout 打了日志 调试输出一律改走日志文件
写入成功但 git log 没记录 KB_ROOT 不是 git 仓库根目录 在 KB_ROOT 里 git init 并做一次初始提交

最后一条不算故障:KB_ROOT 不是 git 仓库也能正常读写,只是丢了版本记录——不致命,但等于放弃了回滚能力。

✅ 11 最后

最后说一句我的实际感受:这套东西带来的最大变化不是「AI 更聪明了」,而是我不用再维护三份口径。省下来的不是打字时间,是每次切换工具那几分钟的重新进入状态。

posted @ 2026-11-17 22:48  源动力技术栈  阅读(21)  评论(0)    收藏  举报