Matrix

Claude Code 的 Matrix

Claude Code 可以搜索代码，但无法按含义搜索 PDF、Word 文档、扫描件或图表。Matrix 会为文档文件夹建立本地语义索引，并提供文件、页码和段落引用、条款之间的交叉引用，以及跨多个文档的表格——所有操作都在你的电脑上运行，而 Claude Code 本身就是大模型，因此无需额外的大模型或 API 密钥。DEMO.md 将其与单独使用 Claude Code 的效果进行比较，测试范围为 442 页和 1,592 页的公开文档。

为什么要使用它

进行了两次测量，对比单独使用 Claude Code 与使用插件的效果（DEMO.md 列出了数据、问题和正确答案）： 一次涵盖 442 页的欧盟法规和一份报告（4 个问题，每个问题运行 2 次），另一次涵盖 14 份、共 1,592 页、使用四种语言的文档（版本 0.2.3，4 个问题，每个问题运行 1 次）。

• 处理大量文档更省力。 442 页：每个问题平均耗时 42 秒，而非 126 秒（约快 3 倍；视问题而定，快 2–4 倍），工具调用次数不到一半（9.5 次，而非 21.4 次），输入 token 也不到一半（303 k，而非 651 k）。1,592 页：耗时减少 35%（4 个问题共 117 秒，而非 180 秒），输入 token 减少 34%（405 k，而非 615 k），输出 token 减少 60%，轮次减半。对于用不同措辞或另一种语言询问某项条款的问题，收益最大；对于答案分散在多个法案中的问题，收益最小（几乎没有：无论如何，Claude 都会逐个搜索法案）。
• 索引一次，反复提问。 索引只需在你的电脑上运行一次，不消耗 Claude token；索引会保留在不同会话之间，并自动跟随文件夹更新。之后每次询问同一批文档，速度都会更快，token 消耗也更少（参见 DEMO.md）。文档数量多或篇幅长、可能会继续询问同一批文档，并且答案需要附带依据时，这种方式更有价值——例如合同、法规、项目文件、技术手册、研究报告、会议纪要或报告。对于一次性问题，Claude 也可以自行搜索文件；如果答案没有文件内容作为依据，它会说明这一点。
• 提供文件、条款和段落引用，并对照文本核验。 两次测试中的每个答案都指出了正确的文档、条款和段落。在大型文档集中，有两个页码偏差了一页，这是因为段落跨越了分页符（已知问题，尚未修复）；单独使用 Claude Code 时页码准确。
• 可查找改写内容、扫描件和图表。 搜索基于含义，因此即使问题的措辞与文本不同，也能找到对应条款；图表中独有的数值也能在图表所在页找到。在 30 个测试问题中，使用可选的重新排序模型时，正确位置有 17 次排在首位（0.2.2 版为 12 次），有 27 次出现在前五位（此前为 19 次），每条搜索结果约为 1,160 个 token，而非 5,500 个。在混合多种语言的文件夹中，使用文档所用的语言搜索效果最好；相关技能也会指示 Claude 使用该语言搜索。
• 跨多个文档生成表格。 可针对每份文档或每个段落提出同一个问题，并以表格呈现，每个单元格都附有来源。
• 完全本地运行，无需额外访问其他模型。 索引和搜索都在你的电脑上运行；Claude Code 本身就是大模型，因此无需第二个模型或 API 密钥。
• 单独使用 Claude Code 也正确回答了所有问题（8/8 和 4/4）；在 442 页测试的第一轮中，使用插件时有一个答案错误（图表标签太小，无法辨认），随后已在 ask 技能中修复，之后正确率达到 4/4。它提升的是效率，而非正确率。

对于规模较小、结构清晰且 Claude Code 本来就能快速读取的文档集，它的帮助不大：单独使用 Claude Code，处理一份简短文档的效果同样好；而每个文件夹只需花几分钟建立一次索引。

安装

目前需要一台搭载 Apple silicon 的 Mac（macOS，arm64）和 Node.js 18 或更高版本（用于 npx）。

claude plugin marketplace add matthiasnordwig/matrix-mcp
claude plugin install matrix@matrix-mcp

然后启动 claude（最好在存放文档的文件夹中），直接向 Claude 询问文档内容即可——首次使用时，Claude 会和你一起设置 Matrix（也可以运行 /matrix:setup）。你无需阅读其他内容。

工作原理

• 文档按其自身结构拆分——PDF 布局、标题、文章、表格——而不是由大模型拆分（语义分块器并非默认选项）。
• 搜索结合语义和关键词，并会沿着条款之间的交叉引用查找；扫描件和图表也能找到。
• 次优模型会将最佳段落排在前面（重排，可选：从 Hugging Face 下载约 0.6 GB，采用 Apache-2.0 许可证，仅在你同意后下载一次；不使用它时，搜索方式与之前相同）。
• 命中结果简洁明了：约 300 个字符的摘录，附带文件、页码和大纲路径（文档 › 章节 › 条款 › 段落）；同一条款的命中结果会合并。Claude 会先用 get_chunks 读取全文，并用 get_section 读取整篇文章或整个章节，然后再引用。
• 每个回答都会引用文件、页码和段落，并根据原文核对引用内容。
• 跨多个文档的表格会通过队列（llm_tasks / llm_answer）将小模型任务交给 Claude；这些任务会在你的 Claude Code 会话中运行，并使用你的 Claude 配额。
• 索引、模型和获准文件夹列表都存放在 ~/Library/Application Support/Matrix MCP；除 Claude 读取的段落外，其他内容都不会离开你的电脑。
• Matrix 会读取你启动 Claude Code 时所在的文件夹；对于其他文件夹，Matrix 会征求你的同意（Accept / Decline），并记住你的选择。
• 已索引的文件夹会保持同步：新增和修改的文件会自动重新读取（在启动时和搜索前检查，最多每分钟一次）；已删除的文件会保留在集合中，标记为缺失且不纳入搜索——不会替你删除任何内容。
• 随时运行 /matrix:status，即可查看 Matrix 保存的内容和执行的操作。

使用

命令	功能
/matrix:setup	引导完成首次启动：选择文件夹和搜索模型、建立索引、尝试示例问题
/matrix:status	查看 Matrix 保存的内容和执行的操作：集合、搜索模型、获准文件夹、等待处理的模型任务、正在运行的作业
/matrix:index <folder>	将文件夹编入集合（支持 PDF，包括扫描件和图表，以及 Word、Excel、PowerPoint、Markdown、文本和图像）
/matrix:ask <question>	根据文档回答问题并附上引用（文件、页码、段落），并根据原文核对
/matrix:table <question>	针对多个文档或段落回答同一问题，并以表格呈现，每个单元格都注明来源
/matrix:search-model	根据推荐日期检查搜索模型，并查找更好的模型

你也可以直接提问；Claude 会选择匹配的技能。服务还提供自己的提示词 （输入 / 并查找 index_and_ask、compare_documents 等）。表格会将小模型任务交给 Claude（llm_tasks，通过 llm_answer 回答）；任务较多时，Claude 可以通过并行子 Agent 完成这些任务。 这些任务会像你委托的其他工作一样使用你的 Claude Code 会话；Claude 会先告知任务数量。

详情

文件夹。 Matrix 会读取你启动 Claude Code 时所在的文件夹。对于其他文件夹，它会先征求你的同意（接受 / 拒绝），并保留你的选择，直到你撤销授权（请 Claude 撤销）。它绝不会读取 /、你的整个主文件夹、系统文件夹、主文件夹中的隐藏文件夹或 ~/Library，也绝不会更改或删除你的文件。若想始终允许访问文件夹而不再征求同意，可在安装时设置（用逗号分隔多个文件夹；文件夹名称不能包含逗号）——Claude Code 2.1.222 在 /plugin 下没有配置界面：

claude plugin install matrix@matrix-mcp --config folders=/path/one,/path/two

更改设置后，重启 Claude Code。同样的方式也适用于 --config embedding_model=... 和 --config embedding_api_key=...。不存在或无法读取的文件夹会按名称报告（/matrix:status）；在 macOS 上，Documents、Desktop 和 Downloads 的隐私保护可能是原因——请在“系统设置 › 隐私与安全性 › 文件与文件夹”中允许运行 Claude Code 的应用访问。索引文件夹 ~/Library/Application Support/Matrix MCP 必须已存在或可创建，并且你必须拥有读写权限；Claude Code 运行时不要删除该文件夹。

搜索模型。 保留 embeddinggemma-2（支持多语言，也可搜索图表和扫描件）。首次需要使用时，Claude 会告知模型大小（约 1.2 GB，来自 Hugging Face，仅下载一次），并在下载前征求同意。 可选项：embeddinggemma-2-q4（0.2 GB，仅文本）、onnx-folder:/path（你已有的模型）、endpoint:https://host/v1#model（你自己的嵌入服务；API 密钥存储在系统钥匙串中）。

重排。 搜索模型之后，Claude 会询问是否下载重排模型（bge-reranker-v2-m3，int8，约 0.6 GB，来自 Hugging Face，许可证为 Apache-2.0），仅在你同意后下载。它会按相关性重新排列前 20 个候选结果，在 Apple 芯片 Mac 上每次搜索约需 4 秒。如果你拒绝或未安装该模型，搜索会照常运行。 Claude Code 会通过 npx -y @matthiasnordwig/[email protected] 启动服务：npm 会下载一次程序（约 21 MB，不含安装脚本）。Claude Desktop 的每个版本也附带 matrix-standalone.mcpb，这是同一程序的桌面扩展。

一次性允许读取工具。 若要让 Claude Code 不再在每次读取前都询问，请将以下内容添加到 settings.json 的 permissions.allow 列表中（~/.claude/settings.json，或项目中的 .claude/settings.json）。其中只列出了读取索引且不会更改任何内容的工具；虽然也支持 mcp__plugin_matrix_matrix-standalone__* 这类通配符，但它们也会允许读取文件夹和下载模型，因此这里不使用。

{
  "permissions": {
    "allow": [
      "mcp__plugin_matrix_matrix-standalone__find_citing_chunks",
      "mcp__plugin_matrix_matrix-standalone__get_chunks",
      "mcp__plugin_matrix_matrix-standalone__get_page_image",
      "mcp__plugin_matrix_matrix-standalone__get_section",
      "mcp__plugin_matrix_matrix-standalone__get_status",
      "mcp__plugin_matrix_matrix-standalone__grid_results",
      "mcp__plugin_matrix_matrix-standalone__job_status",
      "mcp__plugin_matrix_matrix-standalone__list_allowed_folders",
      "mcp__plugin_matrix_matrix-standalone__list_contexts",
      "mcp__plugin_matrix_matrix-standalone__list_documents",
      "mcp__plugin_matrix_matrix-standalone__list_grid_profiles",
      "mcp__plugin_matrix_matrix-standalone__list_grid_runs",
      "mcp__plugin_matrix_matrix-standalone__list_norm_references",
      "mcp__plugin_matrix_matrix-standalone__list_profiles",
      "mcp__plugin_matrix_matrix-standalone__list_sheet_tables",
      "mcp__plugin_matrix_matrix-standalone__lookup_exact",
      "mcp__plugin_matrix_matrix-standalone__page_image_status",
      "mcp__plugin_matrix_matrix-standalone__query_table",
      "mcp__plugin_matrix_matrix-standalone__search_context",
      "mcp__plugin_matrix_matrix-standalone__verify_citations"
    ]
  }
}

以下工具特意未列入：setup_embedding_model（下载）、add_files（读取文件夹）、search_embedding_models （会将你的搜索词发送给 Hugging Face）以及所有会创建或更改内容的工具。

使用条款

Matrix 绝不会启动 claude，绝不会读取你的 Claude 凭据，也不会为其他人提供服务：模型任务由启动该程序的 Claude Code 会话在该会话中为你处理。这样可确保该插件符合 Claude Code 使用条款，该条款不允许通过你的套餐凭据转发其他请求。

请勿预先批准下载工具。 你同意下载搜索模型，即表示你批准调用 setup_embedding_model 工具。请勿将该工具或此服务的所有工具加入始终允许列表，也不要以会自动批准工具调用的模式运行会话。

隐私政策

完整内容：PRIVACY.md（https://github.com/matthiasnordwig/matrix-mcp/blob/main/PRIVACY.md）。

简而言之：一切都在你的电脑上进行；开发者不会收到任何信息（无遥测，也不会检查更新）。文档只会在以下情况下离开你的电脑：Claude 通过工具读取其中的段落（Claude 会按照 Anthropic 的条款处理这些内容，就像处理任何工具结果一样）；如果你配置了自己的嵌入端点，文档会发送到该端点；以及在你同意后，从 Hugging Face 下载一次搜索模型。联系方式： https://github.com/matthiasnordwig/matrix-mcp/issues。

许可证

请参阅 LICENSE。