Silica Core

Silica 会为一个根目录下的 Markdown、代码、PDF 和 Office 文件建立索引，并将它们提供给 Claude Code、Cursor、Hermes、Codex、OpenCode 及其他所有流行的运行框架，既可作为 MCP 工具，也可作为输出相同 JSON 的 shell 命令。每条命中都包含路径、章节、行号、文本窗口，以及用于评估它的数据。循环由运行框架负责。

只需三条命令，就能像提问其他问题一样提出问题。运行框架会调用 silica_search，回答中会标明来源文件、页码和行号。

安装

在 Claude Code 中，请改为安装插件，它自带服务，也包含 dense leg。

uv tool install 'silica-core[mcp]'         # BM25 over documents and their sections (faster, lighter)
uv tool install 'silica-core[mcp,dense]'   # in addition the dense leg: numpy, a static model (still fast, more precise)

第二行会添加 dense leg：numpy 和一个静态的 model2vec 模型，不需要 torch 或 GPU。只有在指定模型并为章节生成嵌入向量后，它才会启用——这一步是快速入门的最后一段。对于与文本没有共同词语的释义式提问，可以使用它；无论如何，精确术语或标识符都由词法检索部分回答，且只有该部分会报告 terms_absent。

pipx 的用法相同。包和命令都是 silica-core，工具名称为 silica_*。

从 0.9 或更早版本升级：自 0.10.0 起，silica 命令改为 silica-core（silica 属于 silica-harness）。旧版 silica setup 注册的客户端仍会启动 silica mcp，而 uvx 获取 0.10.0 后，该命令将无法再启动。运行一次 silica-core setup <client> 即可重写该条目。

快速入门

在任意包含 Markdown、代码、PDF 或 Office 文件的文件夹中：

silica-core init                              # adopt the folder: ignore file, vault.yaml, first index; the MCP server serves adopted folders only
silica-core search "leveled compaction" -k 5  # the best located passages
silica-core setup claude                      # register the MCP server, write the guidance block into ~/.claude/CLAUDE.md

# optional, with the [dense] extra: the dense leg, a static model, nothing leaves the machine
export SILICA_EMBEDDING_MODEL=model2vec/minishlab/potion-retrieval-32M
silica-core index --embed

九篇 arXiv 论文，2.1 s 即完成索引。命中结果会标明文件、页码和段落；旁边的页面可供核对。

工具

工具	Shell	返回内容
silica_files	silica-core files	文件清单，以及索引对每个文件的处理结果：indexed、changed、excluded、failed、unconverted
silica_search	silica-core search	排序后的段落：路径、章节、行号、BM25、匹配词、coverage，以及语料库中缺失的查询词
silica_read	silica-core read	按行或标题截取的内容（PDF 中为页面）、大纲，以及供后续使用的 version
silica_code_pack	silica-core code-pack	在字符数预算内，为一个源文件生成 AST 上下文包
silica_write_note	silica-core write-note	一次原子写入，并对结构和未解析的维基链接进行 lint 检查

在源代码树中，每个函数、方法、类和常量都是一个独立单元： 命中项的 section 是符号，span 是其行范围， silica_read(path, section=…) 会返回正文。对于名称 已知的符号，grep 更有效；对于未点名具体符号的问题，则应先搜索： 工具描述和 silica-core setup claude 写入的代码块都说明了这一点。 契约、响应格式和验收检查见 TOOLS.md。无需 API 密钥或网络连接。

搜索如何给出否定结果

排序列表总会有首位，即使语料库无法回答问题。三个 字段说明结果的参考价值：

• coverage：命中项匹配词所覆盖的查询词 IDF 权重占比。接近 1 表示匹配了所有罕见词；接近 0 表示只匹配了常见词。
• terms_absent：在语料库中任何地方都未出现的查询词。
• matched_terms：该命中项实际包含的词。

在同一组九篇论文中搜索 raft consensus log replication：其中没有任何一篇 出现 raft 和 consensus，coverage 降至 0.19，排名第一的命中项 讨论的是数据复制。在 254 篇论文中，有答案的问题的排名第一命中项 得分为 0.69 至 1.00；语料库无法覆盖的问题则为 0.44。Silica 会提供这些信号；是否停止、阅读或改写问题，则由执行框架决定。

基准测试

BEIR SciFact · NFCorpus 上的 nDCG@10；所有组使用相同的文档和查询。BEIR 公布的 BM25 基线为 0.665 · 0.325。Silica 的词法索引无需模型；其他方案则从同时存储嵌入的索引提供词法搜索。

模式	Silica	zvec-grep 0.2.2	ck 0.7.11
词法	0.662 · 0.311	0.649 · 0.297	0.630 · 0.289
混合，使用相同的 potion-retrieval-32M 嵌入器	0.675 · 0.328	0.672 · 0.330

代码检索评测使用 zvec-grep 为其自身基准发布的 20 个 SWE-QA 问题，采用相同嵌入器，k = 10，并根据参考答案所依据的文件和符号评分。

组别	文件命中率@5 · @10	文件 MRR	符号命中率@10	符号召回率	返回字符数
Silica，混合	0.85 · 0.90	0.68	0.75	0.24	8,266
Silica，向量	0.80 · 0.85	0.67	0.65	0.21	6,225
Silica，词法	0.65 · 0.75	0.47	0.45	0.14	8,194
zvec-grep 0.2.2，混合	0.65 · 0.75	0.54	0.55	0.17	7,326
zvec-grep 0.2.2，向量	0.60 · 0.80	0.61	0.55	0.18	6,821
zvec-grep 0.2.2，FTS	0.45 · 0.60	0.36	0.45	0.11	6,690

在 BEIR 上，两种混合方案在 95% 置信区间内不分上下：相同的向量排名相同，且无需守护进程或向量存储。在代码检索上，Silica 混合方案的文件 MRR 比 zvec-grep 混合方案高 +0.135（95% 置信区间为 +0.01 至 +0.27），按问题配对比较。融合方案的 MRR 也比 Silica 的词法组高 +0.21，符号命中率高 +0.30；未使用重排序器或图扩展。

在本次评测范围内，Silica 是一款紧凑的本地检索器，性能可与 SOTA 媲美：它在 BEIR 上与 zvec-grep 持平，并在使用相同嵌入器的配对 SWE-QA 代码定位重放评测中领先。

只有在不损失答案质量的前提下让 Agent 减少工作量，检索才有意义。以下是相互独立的实验，数据未合并：

工作负载和组别	运行次数	质量	使用搜索	轮次	工具调用次数	秒数	热启动成本
仓库，优先搜索约定	20	评审得分 59.7	17/20	4.7	—	24	$0.197
仓库，同一插件但无约定	20	评审得分 50.6	0/20	6.5	—	28	$0.180
文档，驻留的 Silica 工具	12 项任务	12/12 正确	12/12	3.9	2.9	—	$0.20
文档，无插件	12 项任务	12/12 正确	—	5.0	4.0	—	$0.22

仓库结果仅进行了一次重复实验：轮次减少了 1.75（95% 置信区间：减少 0.55 至 3.05 轮），而评审得分和成本方面的结论尚不明确。文档组的数据来自一项研究，共运行 144 次，覆盖十二个问题和一个 550 万 token 的语料库。这些结果表明在该工作负载下工作量有所减少，并不能证明 Agent 在所有场景下都有此表现。

语料库、置信区间、各任务的例外情况和复现命令见基准测试。

Harnesses

silica-core setup <client> 会将注册信息写入客户端自己的配置文件，并备份原有内容；对于 claude，还会在 ~/.claude/CLAUDE.md 中加入一段指导，说明何时应先搜索再使用 grep。silica-core setup --list 会列出客户端：claude、codex、cursor、windsurf、zed、cline、roo、continue、goose、opencode、openhands、gemini、antigravity、dsh、hermes、openclaw、agent-zero、claude-desktop、lmstudio、anythingllm 和 librechat；shell、python 和 generic 会为其他客户端打印配置方案。服务会提供客户端打开的文件夹；使用 --vault DIR 或 SILICA_VAULT 可指定根目录。

每个写入的配置块以及 Claude Code 插件都会运行 silica-core mcp --retrieval local-hybrid：在服务进程中运行 potion-retrieval-32M，启动时在后台构建索引和向量；向量就绪前，搜索会使用词法检索，并显示 dense: warming。所有内容都留在本机；唯一的下载是模型，且只需下载一次。npx skills add kiycoh/silica-core 会安装这些技能（一个用于告诉 Agent 何时调用工具，另外五个用于根据已索引的文档进行讲解、总结、比较、构建纲要和绘制图表），除此之外不会安装任何内容。Shell 配置方案、Docker 和 REPL 见 public/harnesses.md。

Claude Code 插件的工作方式

在 Claude Code 中，只需使用插件：它自带服务和技能。上文的 安装 部分和 silica-core setup claude 适用于其他客户端；如果两者都配置了，就会有两个服务提供同一个文件夹。

安装

需要将 uv 添加到 PATH，它负责启动服务。

claude plugin install silica-core --marketplace kiycoh/silica-core

这一步适用于 Claude Code 2.1.275 或更高版本；在会话中运行 /plugin install silica-core --marketplace kiycoh/silica-core 也能完成同样的操作。对于较旧的客户端，请先添加 marketplace：运行 claude plugin marketplace add kiycoh/silica-core，然后运行 claude plugin install silica-core@silica-core。

首次运行

1. 在要搜索的文件夹中启动 Claude Code。
2. 等待首次启动完成。首次启动比之后的启动慢：uv 会安装软件包，服务会下载模型，且只需下载一次。
3. 按提示词上方的 Index，或输入 /silica-init。在执行此操作前，不会对任何内容建立索引。
4. 针对该文件夹提问。Claude 会使用 silica_search 搜索其中的内容。向量构建完成前，搜索会使用词法检索，回复中会显示 dense: warming。

更新

刷新 marketplace，然后更新插件。新版本会在下一个会话中加载。

claude plugin marketplace update silica-core
claude plugin update silica-core@silica-core

它运行、读取和下载的内容

该插件由一个 MCP 服务和 hooks/ 中的一个小型 mod 组成。它们都不会将你的文件、提示词或对话发送到任何地方。

• 服务端通过 uv run --frozen --project <plugin folder> 启动。插件文件夹为 ~/.claude/plugins/cache/silica-core/silica-core/<version>，其中版本号是 claude plugin list 显示的版本。首次运行时，uv 会从 PyPI 安装 uv.lock 中锁定的软件包（如果机器上没有 Python 3.11 或更新版本，还会安装 Python 构建版本），服务端则会从 Hugging Face 下载 potion-retrieval-32M 模型。除此之外不会下载任何内容。
• **索引。**在尚未建立索引的文件夹中，mod 会在提示词上方显示一个 Index 按钮；/silica-init 执行相同操作。两者都会在该文件夹中运行 uv run --frozen --project <plugin folder> --extra mcp --extra dense silica-core init，在该文件夹中写入 vault.yaml（如果是代码仓库，还会写入 .silicaignore），并在 ~/.silica 下构建索引。Not here 会在该文件夹中隐藏按钮。在你提出请求之前，不会建立任何索引。
• **搜索提示。**在已建立索引的文件夹中，如果你的问题没有提到任何文件或符号，mod 会添加一行提示，让 Claude 先尝试使用 silica_search，再使用 grep。它还会将搜索指引添加到系统提示词中，除非你的 CLAUDE.md 已经包含这些内容。mod 只会读取三个环境变量 CLAUDE_CONFIG_DIR、HOME 和 USERPROFILE，用于查找该 CLAUDE.md 并跳过你的主目录。
• **文档维护。**在已建立索引且包含 docs/ 文件夹的目录中，mod 会帮助 Claude 让文档与代码保持同步。它会发出提示；是否执行由 Claude 决定，且绝不会拒绝任何写入。
  • 写入值得记录的内容后（新文件、清单、单个回合中更改 30 行，或 ADR 列出的文件），Claude 会收到一次提醒：更新 docs/，或说明没有内容需要记录。
  • 如果某个回合写入了 docs/ 下的内容，回合结束时，mod 会检查这些文件是否存在无效链接或代码路径、是否有两个 ADR 使用相同编号，以及已接受的 ADR 的 Decision 是否发生变化。Claude 会修复它认定的缺陷，或说明原因；每个回合最多检查两次。
  • 交互会话开始时，mod 会读取 docs/adr/ 和 docs/specs/ 并运行 git，然后在提示词上方显示有多少条记录提到了不存在的内容，以及有多少条记录所关联的文件自上次以来发生了更改。/silica-docs 会列出这些记录。
  • frontmatter 含有 implementation:（implemented、partial、pending、draft、dropped 或 n/a）的记录必须符合其状态要求：implemented 和 partial 必须在 implemented_in 中注明提交或路径；pending 和 draft 不得注明任何内容；partial 和 dropped 必须填写 implementation_note。

在较旧版本的 Claude Code 上

Index 按钮、/silica-init、搜索提示和文档维护均由 mod 提供，需要 Claude Code 2.1.293 或更高版本。较旧的客户端仍可运行服务和技能。在该文件夹中打开终端，然后从终端为文件夹建立索引：

uv run --frozen --project <plugin folder> --extra mcp --extra dense silica-core init

无法正常工作时

• **找不到 silica 工具，或 Claude Code 提示无法连接到 plugin:silica-core:silica-core。**服务端未能启动；/mcp 会显示其状态。常见原因是 PATH 中找不到 uv，或首次安装失败。在该文件夹中手动启动服务端以查看错误：

  uv run --frozen --project <plugin folder> --extra mcp --extra dense silica-core mcp --retrieval local-hybrid
  

  一切正常时，会打印 serving 5 tools on stdio, waiting for a client；按 Ctrl+C 可结束运行。

• **没有 Index 按钮。**它不会在你的主目录或 / 中显示，因为这些位置太大，不适合整体建立索引。点击 Not here 后，该按钮会在该文件夹中保持隐藏，但 /silica-init 仍会为其建立索引。若客户端版本低于 2.1.293，请参阅上文。

• 此机器可读取的内容。silica-core doctor 会检查安装情况和文件夹：

  uv run --frozen --project <plugin folder> --extra mcp --extra dense silica-core doctor
  

卸载

claude plugin uninstall silica-core@silica-core

插件会留下两样东西：

• 代码仓库中的 vault.yaml 和 .silicaignore，每个已建立索引的文件夹各一份；
• ~/.silica/index/ 中的索引，每个索引各占一个文件夹。

请手动删除。若插件仍处于安装状态时删除索引，那么下次搜索对应文件夹时会重新建立索引。

说明

• 读取内容： 直接读取 markdown、.txt、.rst 和带文本层的 PDF，每个 PDF 页面作为一个分区；DOCX、EPUB、FB2、RTF、XLS 和 ODF 可通过 no extra 转换；扫描版 PDF、图像、PPTX 和 XLSX 通过带有 MinerU 的 silica-core import 处理；音频和视频通过 ffmpeg 与 SILICA_STT_BASE_URL 处理；CSV 可按行读取，但不会纳入搜索。在源代码树中，代码通道还会添加源文件，以及 json、yaml、toml、cfg 和 ini 文件。silica-core doctor 会说明这台机器支持哪些通道。
• 密集检索： 分区嵌入能够捕捉与答案没有共同罕见词汇的释义。uv tool install 仅启用词法检索，直到运行 silica-core index --embed；可使用 [dense] extra 中的本地模型，或任何兼容 OpenAI 的 /v1/embeddings 端点。只有使用远程端点时，文本才会离开本机；并且只有在运行 silica-core index --embed --allow-remote 授权该主机一次后才会离开。变量和回复状态见 TOOLS.md，ollama 配置示例见 public/harnesses.md。
• 更多接口： silica-core mcp --extended 会添加维基链接工具；silica-core connect（extra [connect]）会托管 Obsidian 插件所连接的桥接服务，因此应用打开时，写入操作会通过知识库 API 执行；silica-core repl 会通过同一组工具运行一个小型参考 Agent，这是唯一需要模型（SILICA_MODEL）的接口。
• 核心不包含： 没有记忆通道、提示词注入、摘要或撤销日志。撤销请使用 git。

许可证

MIT。详见 LICENSE。