1. 为什么我要用 TraeCode 搭一套自己的 Wiki 知识库先说结论我折腾个人知识库这件事前后换过不下五套方案从最早的纯文件夹加 Markdown到后来上 Obsidian 双链再到自己写脚本调 LLM 做摘要最后稳定下来的组合是TraeCode 本地 Markdown 仓库 RAG 检索层。这套东西解决的核心问题只有一个我每天读的东西太多但真正能被我调用的太少。收藏夹里躺着几百篇文章真到要用的时候搜不出来、想不起来、串不起来。TraeCode 在这里扮演的角色不是又一个笔记软件而是知识库的构建引擎和查询入口。它本身是一个 AI 编程工具能理解项目上下文、能读写文件、能跑命令、能按规则rules约束自己的行为。我把它当成一个住在仓库里的图书管理员——我扔进去一堆原始材料它帮我整理成结构化的 Wiki 页面我需要的时候再用自然语言问它它去检索、去拼装、去回答。这套方案适合谁三类人最合适。第一类是技术从业者手里有大量代码片段、踩坑记录、配置文档散落在各个地方第二类是内容工作者需要长期积累素材、做主题研究但不想被某个平台的私有格式绑架第三类是任何想认真对待自己信息资产的人愿意花一个周末把架子搭起来之后长期受益。关键词里提到的LLM、RAG、Wiki、知识库其实就是这套系统的四个支柱Wiki 是最终形态知识库是底层数据LLM 是理解引擎RAG 是检索增强的手段。下面我按设计思路 → 核心细节 → 实操落地 → 问题排查的顺序把这套东西完整拆一遍。你不需要全部照抄但每一步背后的为什么我都写清楚了你可以按自己的情况裁剪。2. 整体架构设计与方案选型思路2.1 为什么是本地 Markdown TraeCode而不是现成笔记软件我一开始也用过各种现成的知识库工具图形化、双链、云同步体验确实好。但用久了发现三个硬伤数据不在自己手里、格式不透明、AI 能力是黑盒。你没法控制它怎么切分你的文档没法控制它用什么模型更没法把检索逻辑改成适合自己领域的样子。本地 Markdown 仓库的好处是纯文本、可版本控制、可被任何工具读取。TraeCode 直接在这个仓库里工作读写的就是.md文件没有任何中间层。这意味着哪天我不想用 TraeCode 了我的知识库还是完整的、可读的、可迁移的。这一点对我这种被平台坑过的人来说是底线。提示知识库的底层格式一定要选十年后还能打开的东西。Markdown 就是这种格式别用任何私有二进制格式存你的核心知识。2.2 三层结构原始层、加工层、检索层我把整个知识库分成三层这个划分是整套方案的地基后面所有操作都围绕它展开。原始层raw所有未经处理的输入。网页剪藏、PDF 转出来的文本、随手记的碎片、代码片段、会议记录。这一层的特点是脏、乱、全不做任何加工只做归档。我给它按日期和来源分文件夹比如raw/2025-01-web/、raw/papers/。加工层wiki这是 TraeCode 主要干活的地方。它读取原始层的内容按我定义的模板和规则生成结构化的 Wiki 页面。每个页面有统一的 frontmatter标题、标签、来源、创建时间、关联页面正文是提炼后的要点、我的批注、相关链接。这一层是给人看的也是给检索用的。检索层index这是给 RAG 用的。加工层的每个页面会被切分成块chunk生成向量索引存到本地。查询的时候先检索相关块再交给 LLM 生成回答。这一层是给机器用的人一般不直接看。三层分离的好处是职责清晰。原始层永远不动加工层可以反复重写检索层可以随时重建。哪一层出问题单独修那一层就行不会牵一发动全身。2.3 为什么用 RAG 而不是直接把所有文档塞给 LLM这是很多人会问的问题。我的知识库现在有几百个页面全塞进上下文窗口一是塞不下二是就算塞得下成本和速度都受不了三是 LLM 在长上下文里会注意力涣散反而找不准关键信息。RAG 的思路是先检索、再生成。用户提问 → 向量检索找出最相关的 N 个块 → 把这 N 个块和问题一起交给 LLM → LLM 基于这些块回答。这样 LLM 只需要处理几 KB 的相关内容又快又准还能给出引用来源。关键词里提到的agentic RAG、ontology RAG是更进阶的玩法前者让 agent 自己决定检索几轮、怎么改写查询后者引入本体结构做更精准的语义检索。我目前的方案是基础 RAG 查询改写够用了。等知识库再大一圈我会考虑上 agentic 那套。2.4 TraeCode 的 rules 机制是整套方案的粘合剂TraeCode 有个我很喜欢的能力rules规则。你可以写一份规则文件告诉它在这个项目里你生成 Wiki 页面时必须遵守以下格式处理原始材料时按这个流程走回答问题时必须引用来源。这相当于给 AI 装了一套工作手册。没有 rules 的 AI 工具每次输出风格都不一样你得反复纠正。有了 rules它就像一个熟悉你习惯的老员工第一次交代清楚后面基本不用管。我把 rules 分成三类格式规则frontmatter 怎么写、标题怎么编号、流程规则先读什么、再做什么、最后输出什么、质量规则不许编造、必须标注来源、不确定就说不确定。3. 核心细节解析与实操要点3.1 仓库目录结构怎么设计才不后悔目录结构这东西一开始设计不好后面迁移成本极高。我踩过的坑是按主题分类结果一个主题下堆了几百个文件找东西全靠搜索后来改成按来源时间又发现同一主题的内容散落各处串不起来。最后我用的方案是混合制knowledge-base/ ├── raw/ # 原始层只增不改 │ ├── 2025-01/ │ ├── papers/ │ └── clips/ ├── wiki/ # 加工层TraeCode 主战场 │ ├── topics/ # 按主题聚合的页面 │ ├── entities/ # 人物、工具、概念等实体页 │ └── index.md # 全局索引手工维护 ├── index/ # 检索层自动生成 │ ├── vectors/ │ └── chunks.json ├── .trae/ # TraeCode 配置 │ └── rules.md └── README.md关键点是wiki 层用主题 实体双维度。主题页回答这件事是什么实体页回答这个东西是什么。比如我有一篇主题页叫topics/rag-basics.md同时有一个实体页叫entities/vector-database.md。主题页里链接到实体页实体页里反向链接到所有提到它的主题页。这样无论我从哪个角度切入都能顺藤摸瓜找到相关内容。注意raw层永远不要手动改。原始材料一旦加工过就失去了原始的意义。要改就在wiki层改raw层只做归档。3.2 frontmatter 是知识库的骨架必须统一每个 Wiki 页面顶部的 frontmatter是整套系统能运转的关键。没有它检索层没法按标签过滤TraeCode 没法判断页面之间的关系你自己也没法批量管理。我的 frontmatter 模板长这样--- title: RAG 基础原理 tags: [rag, llm, retrieval] source: raw/2025-01/rag-intro.md created: 2025-01-15 updated: 2025-01-20 related: [entities/vector-database, topics/embedding] status: draft ---字段不多但每个都有用。tags用于检索过滤source用于溯源related用于构建页面图谱status用于区分草稿和定稿。TraeCode 在生成页面时我会在 rules 里强制它填这些字段缺一个就报错重来。这里有个经验tags 不要超过 5 个且必须从预定义词表里选。我一开始让 AI 自由打标签结果出现了rag、RAG、检索增强、retrieval-augmented四种写法指同一个东西检索的时候全乱套。后来我维护了一份tags.md词表rules 里要求只能从词表选问题就解决了。3.3 文档切分策略切得好检索才准RAG 的效果七成取决于切分。切得太碎语义不完整切得太粗检索不精准。我试过固定长度切分比如每 500 字一刀效果很差经常把一句话从中间切断。现在我用的是语义切分 重叠优先按 Markdown 标题切分每个##或###段落作为一个候选块如果某个块超过 800 字再按段落切相邻块之间保留 100 字左右的重叠避免边界信息丢失每个块前面加上页面标题和所属章节标题作为上下文前缀最后这条特别重要。一个孤立的块可能看不出在讲什么但加上来自《RAG 基础原理》的检索策略章节这个前缀语义就完整了。实测下来加了前缀的检索准确率能提升两成左右。3.4 用 TraeCode 的 rules 约束生成质量rules 文件我写了大概两百行核心是这几条## Wiki 页面生成规则 1. 每个页面必须有完整 frontmatter字段缺一不可 2. 标题层级从 ## 开始必须带数字编号 3. 正文中每个事实性陈述必须能追溯到 source 文件 4. 不确定的内容标注 [待核实]不许编造 5. 页面末尾必须列出 related 页面的链接 6. tags 只能从 tags.md 词表中选取第 3 条和第 4 条是防幻觉的关键。LLM 最大的毛病就是一本正经地胡说八道你让它整理资料它可能给你编一个不存在的来源。我在 rules 里明确要求凡是 source 里没有的一律不许写拿不准的标 [待核实]。这样我复查的时候只需要看标了 [待核实] 的地方效率高很多。4. 完整实操流程与关键环节实现4.1 环境准备与 TraeCode 初始化第一步是把仓库建起来。我习惯用 git 管理这样每次 TraeCode 批量生成页面后我能用git diff看清楚它到底改了什么出问题随时回滚。mkdir knowledge-base cd knowledge-base git init mkdir -p raw wiki/topics wiki/entities index .trae touch README.md .trae/rules.md wiki/index.md然后在 TraeCode 里打开这个目录把.trae/rules.md写好。TraeCode 会自动读取这个文件作为项目级规则。我建议一开始 rules 别写太复杂先跑通流程再逐步加约束。提示TraeCode 的桌面端和命令行都能用我日常用桌面端做交互式整理用命令行做批量任务。批量任务适合写脚本调用交互式适合边看边改。4.2 原始材料入库从乱到有序原始材料入库这一步我做了个半自动流程。网页剪藏我用浏览器插件导出成 MarkdownPDF 用工具转文本代码片段直接复制。所有材料先扔进raw/对应目录文件名统一成日期-来源-简短标题.md。然后我让 TraeCode 做第一遍清洗去掉导航栏、广告、页脚这些噪音保留正文补一个简单的头部信息。这一步的 prompt 大概是这样读取 raw/2025-01/ 下所有文件对每个文件 1. 去掉与正文无关的内容导航、广告、版权声明 2. 在文件顶部加一行注释来源 URL、抓取时间 3. 保持原文不动不要改写、不要总结 4. 处理完输出一个清单列出每个文件处理前后的字数关键是第 3 条不要改写。原始层就是原始层任何改写都会引入偏差。清洗只做减法不做加法。4.3 加工层生成让 TraeCode 批量产出 Wiki 页面这是整套流程的核心环节。我的做法是分批处理每批 5 到 10 个原始文件太多了 AI 会偷懒质量下降。处理一个原始文件时我给的指令是读取 raw/2025-01/rag-intro.md生成一个 Wiki 页面到 wiki/topics/rag-basics.md。 要求 - 按 .trae/rules.md 的格式规范 - 提炼 3 到 5 个核心要点每个要点配一句原文引用 - 识别文中提到的实体工具、概念、人物在 related 里链接到对应实体页 - 如果实体页不存在先创建一个占位页 - 不确定的内容标 [待核实]这里有个技巧让 AI 先输出大纲我确认后再让它写正文。直接让它写全文经常跑偏先看大纲不对就改改完再展开效率高很多。这个两步走是我试了很多次才总结出来的。生成完一批后我会用git diff过一遍重点看三处frontmatter 是否完整、有没有编造的内容、related 链接是否合理。发现问题就在 rules 里补一条下次就不会再犯。4.4 检索层构建向量索引与查询检索层我用的是本地向量库具体选型看你的技术栈。Python 生态里chromadb、faiss都行Node 生态里也有对应的库。核心流程是遍历wiki/下所有.md文件按 3.3 的切分策略切成块每个块调用 embedding 模型生成向量向量和块的元数据来源页面、章节、原文一起存进向量库查询的时候def query(question, top_k5): q_vec embed(question) results vector_store.search(q_vec, top_k) context \n\n.join([r.text for r in results]) prompt f基于以下资料回答问题必须引用来源\n\n{context}\n\n问题{question} return llm.generate(prompt)top_k我一般设 5太多会引入噪音太少可能漏掉关键信息。这个值可以调看你的知识库密度。4.5 查询改写让检索更准的一招用户提问的方式和文档里写的方式往往对不上。比如你问怎么防止 AI 瞎编文档里写的是幻觉抑制策略。直接拿问题去检索可能什么都搜不到。我的做法是先让 LLM 改写查询把口语化的问题改写成几个可能的专业表述分别检索结果合并去重。这一步成本很低但效果提升明显。用户问题怎么防止 AI 瞎编 改写为 1. 幻觉抑制策略 2. LLM 事实性校验 3. 检索增强生成中的 grounding 方法三个查询分别检索取并集再交给 LLM 生成回答。实测下来召回率能提升三成以上。5. 常见问题与排查技巧实录5.1 检索不准怎么办从四个方向排查检索不准是最常见的问题我整理了一个排查顺序现象可能原因排查方法解决方向搜不到相关内容切分太碎或太粗打印几个块的原文看看调整切分策略搜到了但不相关embedding 模型不适合中文换模型对比换多语言模型相关但排序靠后缺少上下文前缀检查块是否带标题加前缀时好时坏查询表述差异大记录失败案例上查询改写我遇到最多的是第一种和第四种。第一种靠调切分参数解决第四种靠查询改写解决。第二种和第三种相对少见但一旦遇到排查起来更费劲。5.2 TraeCode 生成内容跑偏rules 要写负面清单AI 生成内容跑偏很多时候不是它能力不行而是你没告诉它不要做什么。我后来在 rules 里加了一节禁止事项## 禁止事项 - 禁止编造 source 中不存在的事实 - 禁止使用众所周知显而易见等模糊表述 - 禁止在未确认的情况下修改 raw 层文件 - 禁止生成超过 2000 字的单页超长必须拆分 - 禁止使用 emoji 和装饰性符号负面清单比正面要求更有效。你告诉它要准确它不知道什么叫准确你告诉它不许编造它就知道边界在哪了。5.3 知识库越用越乱定期做体检知识库用久了一定会乱。重复页面、失效链接、过时内容都是必然的。我的做法是每月做一次体检让 TraeCode 跑一遍全库扫描扫描 wiki/ 下所有页面输出以下报告 1. 孤立页面没有任何页面链接到它 2. 失效链接related 里指向不存在的页面 3. 重复内容相似度超过 80% 的页面对 4. 超过 90 天未更新的页面 5. frontmatter 字段缺失的页面拿到报告后孤立页面要么合并要么删除失效链接修掉重复内容合并过时内容标记或归档。这个体检流程跑一次大概十几分钟但能省下后面无数找东西的时间。5.4 密钥和敏感信息泄露这是红线关键词里有人问使用 LLM 时如何防止密钥等鉴权信息泄露这个问题我必须单独说。我的原则是密钥永远不进知识库永远不进 git。具体做法所有密钥存在环境变量或独立的.env文件里.env加进.gitignore知识库里如果必须记录配置只写密钥存在环境变量 XXX 中不写具体值用 TraeCode 处理材料时如果原始材料里含密钥先手动脱敏再入库定期用工具扫一遍仓库看有没有误提交的密钥注意git 历史里的密钥删掉文件是没用的必须用git filter-repo之类的工具彻底清除然后立刻轮换密钥。这个坑我踩过一次代价是半夜爬起来换密钥。5.5 性能问题知识库大了之后怎么办知识库到几百个页面、几千个块之后检索会变慢。我的优化顺序是先加缓存embedding 结果缓存起来同样的文本不重复计算再上近似检索精确检索换成 HNSW 之类的近似算法速度提升一个数量级最后做分层热数据常查的和冷数据分开存冷数据用更慢但更省空间的方案大部分个人知识库做到第一步就够了。别一上来就搞复杂架构那是给自己找麻烦。6. 我在这套方案上的一些个人体会这套东西我用了大半年最大的感受是知识库的价值不在于存了多少而在于用起来多顺。我见过太多人花大力气搭知识库搭完就再也不打开了。问题就出在用这一环——检索不准、查询麻烦、结果不可信用几次就放弃了。TraeCode 在这套方案里的价值是它把整理和查询这两件最耗精力的事自动化了。整理的时候它按规则批量生成结构化页面查询的时候它做检索改写和答案拼装。我要做的是定义规则、审核结果、维护词表这些判断性的工作。这个分工我觉得是对的——机器做重复劳动人做判断。如果你打算开始搭我的建议是别追求一步到位。先建仓库、写 rules、扔十个文件进去跑通流程用一周感受一下哪里不顺手再改。知识库是长出来的不是设计出来的。我现在的目录结构和 rules和最初版本比已经改了七八轮每一轮都是被实际问题逼出来的。最后分享一个小技巧给知识库加一个每日一问的习惯。每天从知识库里随机抽一个页面问自己一个问题看能不能答上来。答不上来说明这个页面写得不够清楚或者你根本没消化。这个习惯坚持下来知识库才真正变成你的东西而不是一个躺在硬盘里的文件夹。
