Obsidian+MCP+Skills：搭建本地知识库提升AI测试用例覆盖率

测试用例覆盖率卡在60%上不去通常不是测试同学在摸鱼而是该查的资料压根没被看到。我最近把Obsidian、MCP、Skills三样东西组合到一起做了一套本地知识库检索系统AI 写用例之前会先翻历史缺陷、产品需求和测试规范实测下来覆盖率提升非常明显。这套东西不复杂核心就三步用 Obsidian 管知识、用 MCP 把知识库接到 AI、用 Skills 约束 AI 按规则干活。下面把完整路线和踩过的坑一次讲清楚。1. 覆盖率卡住的真正原因是什么1.1 测试用例写不好通常不是人的问题我见过太多测试团队用例评审开了三轮上线还是翻车。原因很简单写用例的人手里只有一份 PRD顶多再附几个历史 bug 链接。需求里的边界条件、历史踩过的坑、跨部门评审时提出的疑问全都散落在 Jira、Confluence、企业微信聊天记录里。让一个人去翻完所有资料再设计用例不现实更没时间。很多团队的现状是老测试靠脑子记经验新测试靠直觉猜场景。同一个模块A 写了登录校验B 忘了写密码错误三次锁定这周刚修复的并发下单问题下周的新需求又踩一遍。这不是执行力的问题是知识没有沉淀和复用的问题。我用一个简单的对比来说明维度传统人工设计用例知识库驱动设计用例需求来源单人阅读PRD检索需求库历史变更记录历史缺陷靠记忆、碰运气自动检索缺陷库同类问题边界条件凭经验临场发挥基于历史数据和规则库推导新人上手需要老带新半年直接读取沉淀的知识资产1.2 覆盖率不是用例数量的堆砌很多团队误以为用例写得越多覆盖率越高于是把大量精力花在复制粘贴相似的用例上。真正影响覆盖率的是场景的多样性正常流程、异常输入、边界值、数据组合、并发冲突、权限差异、第三方依赖异常。这些场景靠一己之力很难想全但组织里大概率有人遇到过、踩过坑、记录过。解决问题的思路不是让测试人员强行记住所有历史而是把历史转变成可检索的知识库再让 AI 在生成用例时自动把相关知识拉出来作为参考。这就相当于给每个测试人员配了一个拥有全团队记忆的助手。知识库 AI 的组合让覆盖率提升从依赖个人变为依赖系统。2. 为什么拿 Obsidian 做知识库底座2.1 本地知识库的核心诉求要做这件事知识库的载体选择很关键。我考虑过 Notion、语雀、Confluence最后选了 Obsidian理由很直接第一数据必须本地化。测试用例、缺陷记录、需求文档都涉及公司业务隐私不可能为接入 AI 就把这些数据传到云端第三方平台。Obsidian 的文件就是一个本地文件夹存储完全自主可控。第二纯 Markdown 格式。Markdown 是文本文件可以被脚本轻松读取和索引也方便用代码解析内容。数据库、二进制格式在接入 MCP 时要做额外的解析复杂度高不少。第三插件生态足够好。Obsidian 本身支持安装社区插件MCP 相关的接入方案已经比较成熟可以直接通过本地服务器暴露知识库内容给 AI 客户端调用。2.2 知识库的结构设计Obsidian 建库容易但要让 AI 检索到有效内容目录规划必须在一开始就想清楚。我的建议是分四个一级板块01 需求库存放产品需求文档、需求变更记录、功能说明。02 缺陷库按模块存放历史 bug每条记录包含现象、复现步骤、根因分析、修复方案。03 用例库历史功能测试用例按模块和优先级归档。04 规范库测试设计规范、命名规范、边界值规则、测试环境说明。每个板块内部不要嵌套太多层级保持两级目录即可。文件名尽量包含模块名比如登录模块-密码策略需求.md、登录模块-历史缺陷汇总.md。这样的命名对后续 MCP 检索非常友好。2.3 双向链接不是摆设Obsidian 的特色是双链在组织测试知识时这个功能很有价值。比如一条缺陷记录里通过[[登录模块-密码策略需求]]指向对应的需求文档一条需求文档里用[[登录模块-历史缺陷汇总]]反向关联历史问题。这样 AI 在检索一条内容时还能顺着链接找到关联上下文生成用例时考虑得更全面。我在实践中发现双链特别适合构建缺陷和需求的对应关系。有了这条关系链AI 在生成用例时能自动把该模块的历史问题映射到新的需求场景里覆盖率自然就上去了。3. MCP Skills 技术拆解3.1 MCP给 AI 装一个 USB-C 接口MCPModel Context Protocol模型上下文协议解决的核心问题是AI 模型默认接触不到外部数据而不同的数据源接入方式五花八门。MCP 把一个统一的接口标准定下来就像给所有外设统一成了 USB-C。AI 客户端比如 Claude Desktop、Codex通过 MCP 客户端连接本地 MCP 服务端服务端再把检索请求转发给 Obsidian 的知识库目录。整个链路里有一个关键点MCP 本身不负责语义理解它只负责传输。也就是说MCP 服务端只做两件事接收 AI 发来的工具调用请求执行对应的操作搜索文件、读取内容、列出目录把结果原样返回给 AI。真正的理解发生在 AI 模型那边。因此MCP 服务端的代码可以很轻量重点是暴露哪些工具给 AI 使用。我推荐的工具集包括search_notes(query, path)在知识库目录里做关键词搜索read_note(path)读取指定笔记的完整内容list_notes(path)列出某个目录下的全部文件get_backlinks(path)获取笔记的所有反向链接用于上下文扩展3.2 Skills让 AI 按你的套路干活MCP 解决了数据从哪来的问题但AI 拿到数据后怎么组织用例是另一件事。默认情况下你让 Claude 或 GPT 生成测试用例它只会按照训练数据里的套路写不会考虑你们团队的测试规范、优先级划分、历史缺陷的根因模式。这就需要 Skills 来约束。Skills 本质上是一套写在 Markdown 文件里的指令模板告诉 AI 面对某个任务时应该遵循哪些步骤、参考哪些数据、按什么格式输出。你可以把 Skills 想象成给实习生准备的作业流程图里面有明确的操作步骤和质量标准。Skill 文件通常放在 AI 客户端指定的目录下比如 Claude 的project/.claude/skills/目录。每个 Skill 是一个文件夹里面包含一个SKILL.md主文件以及可选的示例文件、参考文档。4. 实操从搭库到落地全流程4.1 第一步把知识资产灌进 Obsidian搭建 Obsidian 库之后最重要的一步是数据录入。这一步最容易偷懒也最不能偷懒。建议按优先级推进先把缺陷库和历史用例库建起来。从 Jira、禅道或 TestRail 导出历史 bug 和用例转成 Markdown 后按模块入库。每条缺陷记录至少包含现象、复现步骤、根因、修复方案、影响版本。如果原来数据质量不高宁可精简也不要大段粘贴无结构文本否则 AI 检索到后会产生严重误解。需求库的录入可以小批量做。每个版本迭代开始前把当期的 PRD、接口文档、原型说明文件导入对应模块目录。注意把变更记录单独拆出来比如登录模块-2025年6月需求变更.mdAI 能通过变更记录分析回归影响范围。4.2 第二步搭建 MCP 服务端我用 Node.js 写了一个轻量 MCP 服务端核心代码如下。MCP SDK 提供了现成的McpServer类定义工具非常简洁import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import fs from fs/promises; import path from path; const server new McpServer({ name: obsidian-kb-server, version: 1.0.0, }); server.tool( search_notes, 在知识库中按关键词搜索笔记, { query: string, dir: string }, async ({ query, dir }) { const root path.resolve(process.env.KB_ROOT ?? ./kb); const targetDir path.join(root, dir || ); const files await fs.readdir(targetDir); const matched []; for (const file of files) { if (!file.endsWith(.md)) continue; const content await fs.readFile(path.join(targetDir, file), utf-8); if (content.includes(query)) { matched.push({ file, preview: content.slice(0, 300) }); } } return { content: [{ type: text, text: JSON.stringify(matched, null, 2) }] }; } ); const transport new StdioServerTransport(); await server.connect(transport);这个服务端通过stdio和 AI 客户端通信不走网络端口安全性高也不容易被防火墙拦截。读取逻辑非常简单在指定目录下扫描 Markdown 文件做关键词匹配返回文件路径和内容预览。实际生产环境里建议把关键词检索升级成向量检索。可以引入本地向量库如 sqlite-vec、LanceDB把 Obsidian 里的每篇笔记按 chunk 切成向量存起来检索时用语义相似度替代关键词匹配效果会好很多。但起步阶段关键词就够用了先把链路跑通最重要。4.3 第三步配置 AI 客户端连接 MCP以 Claude Desktop 为例编辑claude_desktop_config.json{ mcpServers: { obsidian-kb: { command: node, args: [/path/to/obsidian-kb-server/dist/index.js], env: { KB_ROOT: /path/to/obsidian/vault } } } }配置完成后重启客户端AI 就能自动识别到search_notes、read_note这些工具。这时候你可以先做个测试直接问 AI在知识库里搜索登录模块的历史缺陷看它是否调用了工具并返回结果。4.4 第四步编写测试用例生成Skill我创建了一个名为generate-test-cases的 Skill 目录文件结构如下.claude/skills/generate-test-cases/ SKILL.md examples/ login-module-sample.md references/ coverage-calculation.mdSKILL.md是核心指令文件内容这样写# 测试用例生成 Skill ## 任务 根据用户提供的需求描述或需求文档路径生成完整的测试用例列表目标覆盖率不低于建议阈值。 ## 输入 - 需求文档文件名可选 - 功能模块名称 ## 执行步骤 1. 调用 search_notes 在 01 需求库 下检索相关需求文档。 2. 调用 search_notes 在 02 缺陷库 下检索对应模块的历史缺陷记录。 3. 调用 search_notes 在 04 规范库 下检索测试设计规范。 4. 综合以上内容生成测试用例。 ## 用例覆盖维度 必须覆盖以下维度 - 正常流程主流程能跑通 - 异常流程输入错误、依赖异常、权限不足等 - 边界值上下限、空值、超长、特殊字符 - 数据组合多条件组合、重复提交、并发 - 历史缺陷回归需求中涉及的历史 bug 必须设计对应回归用例 ## 输出格式 按统一表格输出用例编号、模块、场景描述、前置条件、测试步骤、预期结果、优先级、关联缺陷编号。 ## 质量要求 - 每个功能点至少覆盖正常和异常两个场景 - 边界值必须包含上下限和类型异常 - 如果缺陷库中有同类历史缺陷必须关联并在预期结果中明确回归标准这个 Skill 的工作方式是纯文本指令AI 读到后会自动按步骤执行。注意里面写清了必须先检索再生成的顺序这是关键。很多场景下 AI 会跳过检索直接凭常识生成指令里写明顺序能有效约束它的行为。4.5 实战验证以登录模块为例我在 Obsidian 库中放入了登录模块的需求文档、三条历史缺陷记录、登录测试规范。然后在 Claude 里输入生成登录模块的测试用例功能点包括手机号密码登录、短信验证码登录、忘记密码。AI 的自动检索路径是在01 需求库检索到登录模块-需求说明.md读取内容。在02 缺陷库检索到三条历史缺陷其中一条是验证码在弱网下重复发送导致 Redis 缓存击穿。在04 规范库检索到登录测试规范.md里面明确要求手机号格式校验的 11 位限制。最终输出的用例中不仅包含了正常的登录成功用例还额外生成了弱网重复请求验证码的回归用例、手机号 10 位和 12 位的边界用例、验证码过期后提交的异常用例。这基本覆盖了之前手动设计时最容易遗漏的三个场景。5. 常见问题与排查技巧实录5.1 MCP 服务连不上或工具不显示最常见的问题是路径配置错误。MCP 配置里的command和args指向的脚本路径如果包含空格或中文字符node 启动时很容易失败。建议把服务端脚本和依赖放在纯英文路径下。排查时先手动在终端里执行一次node /path/to/index.js看有没有报错。其次检查KB_ROOT环境变量是否指向 Obsidian 库根目录这个变量对应代码里的process.env.KB_ROOT。5.2 AI 检索到无关内容结果杂乱关键词检索的天然缺陷是相关性差。比如搜索登录可能把注销也搜出来。解决方法是提升知识库文件命名的精确度确保模块名清晰。另外我建议给每个一级目录加一个index.md说明这个目录下内容性质AI 在检索后可以先用 index 做一轮筛选。如果团队有条件早点引入向量检索是更彻底的解法。5.3 Skill 没有被自动调用部分客户端不会自动触发 Skills需要在对话里显式指定比如输入使用 generate-test-cases skill 生成用例。如果是 Claude Code 环境检查 Skill 目录是否放在项目根目录的.claude/skills/下以及文件名是否为SKILL.md。个别情况下需要重启客户端才能生效。5.4 历史缺陷数据质量太差反而误导 AI导入 Obsidian 的缺陷如果只是复制粘贴里面没有根因分析AI 会把现象当成规范来用。比如某条缺陷记录登录按钮点击无响应AI 可能生成一条验证点击登录按钮是否无响应的无效用例。解决方法是在导入前做数据清洗只保留有根因分析的缺陷没有根因的删掉现象描述里模糊的部分或者补充根因未知待补充这样的标记AI 看到后会谨慎处理。5.5 覆盖率统计口径没对齐很多团队说提高覆盖率但不清楚当前覆盖率是怎么算的。如果是用例条数覆盖率知识库驱动的方式会显著增加用例数量如果是需求覆盖的原子功能点覆盖率建议在 Obsidian 里给需求文档加一个功能点清单让 AI 在生成用例时对照清单标注每个功能点覆盖情况。实测下来原子功能点覆盖率能提升到 90% 以上。问题现象排查优先级常见解法MCP 工具不显示高检查路径、环境变量手动启动服务端验证检索结果相关差中优化命名、加 index.md、升级向量检索Skill 不触发中检查目录命名、显式指定 Skill、重启客户端历史数据误导 AI高数据清洗、补充根因分析、标注待补信息覆盖率口径不一致低在知识库中定义原子功能点清单对照统计我做这套东西踩过最大的坑是在第一步知识库还没有搭建好就急着接 MCP结果 AI 检索半天一无所获产出全是空壳用例。后来沉下心用两周时间把当前迭代涉及的核心模块历史数据整理入库再把模型接进来效果立刻不同。从我的经验看这套方案的瓶颈不在技术而在知识沉淀的持续性。知识库不是一次性工程需要跟着迭代持续更新但每一次更新都是在扩充团队的集体记忆回报非常明显。后续可以考虑把每次评审中讨论的问题也沉淀进规范库让 AI 生成的用例越来越贴合团队实际语境。