Local Vector Search MCP

LocalVectorSearchMcp

为 Codex、Claude Code 和 ChatGPT 提供一个本地、可编辑、感知项目的 Markdown 工作台。

LocalVectorSearchMcp 是一个本地 MCP 服务，可将一个项目的 Markdown 文件索引到项目专属的 SQLite 数据库中。Agent 可以搜索、读取聚焦的语义片段、通过语义指针编辑、管理 Markdown 文件、浏览工作区，以及管理普通图像资源。

它能帮助 Agent 找到合适的规范、架构决策、指南或不变量，而无需将整套文档加载到上下文中。

为什么使用它？

大型代码库中往往包含所需答案，但答案可能不在 Agent 首先打开的文件里。

• 精确文本搜索可查找标识符、API 名称和引用术语。
• 向量搜索可以找到概念相关的文档，即使措辞不同也能匹配。
• 混合搜索通过 Reciprocal Rank Fusion 合并两组结果。
• kb_read 会从当前 Markdown 源文件中返回聚焦的片段，而不必强迫 Agent 阅读整个文件或等待索引完成。
• 元素级乐观并发控制可防止 Agent 覆盖读取后发生变化的语义目标，同时不相关的文档编辑不会阻止补丁应用。
• 可选的文件监视功能可让索引与 VS Code、Obsidian 或其他编辑器中的修改保持同步。
• PNG、JPEG、WebP 和 GIF 文件可作为非索引资源存储在 knowledgeBase.root（默认为 images/）下的任何位置。
• 每个项目都有自己的本地 SQLite 索引。
• 无需云数据库，也不强制要求 YAML 配置。

工作原理

Workspace Markdown (source of truth)
       ↓
Markdown elements and search chunks
       ↓
SQLite FTS5 (+ sqlite-vec when embeddings are enabled)
       ↓
Scoped retrieval + semantic editing
       ↓
MCP tools over stdio

images/ assets
       ↓
save / list / load / delete / safe move
       ↓
not indexed

Claude Code 和 Codex 可以直接启动 stdio 服务。ChatGPT 可以通过 OpenAI Secure MCP Tunnel 使用相同的 MCP 接口，由外部 tunnel-client 将 ChatGPT 连接到本地 stdio 进程。

快速开始：离线词法搜索

安装 .NET 工具（需要 .NET 10）：

dotnet tool install --global DimonSmart.LocalVectorSearchMcp

或者，使用 dnx 直接运行指定版本的已发布程序（需要 .NET 10 SDK；无需全局安装工具）：

dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \
  --project-root "$PWD" --embedding-provider none --search-mode lexical --status

官方 MCP Registry 使用规范名称 io.github.DimonSmart/local-vector-search-mcp。只有在匹配的 NuGet 版本成功注册后，才会显示该条目。

使用 dnx 注册服务，无需全局安装：

codex mcp add local-vector-search -- dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \
  --project-root "$PWD" --embedding-provider none --search-mode lexical --watch-files

claude mcp add --transport stdio local-vector-search -- dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \
  --project-root "$PWD" --embedding-provider none --search-mode lexical --watch-files

将 <version> 替换为已发布到 NuGet.org 的版本，并在 Markdown 项目的根目录运行这些命令。此处服务使用 stdio 和离线词法模式；无需 Ollama 端点或 API 密钥。

在要建立索引的项目中运行以下命令。无需 Ollama 服务、 远程嵌入端点或 API 密钥：

local-vector-search-mcp --project-root "$PWD" \
  --embedding-provider none --search-mode lexical --reindex

使用相同的参数注册项目专属 MCP 服务：

codex mcp add local-vector-search -- \
  local-vector-search-mcp --project-root "$PWD" \
  --embedding-provider none --search-mode lexical --watch-files

SQLite FTS5 索引存储在项目根目录下的 .local-vector-search-mcp/index.db 中。Markdown 仍是事实来源。除非在 YAML 中明确设置 knowledgeBase.allowWrites: true，否则服务对 Markdown 和图像为只读。

请参阅 IDD 集成示例，了解 .idd/intent、显式路径、dnx 和 Claude Code 的用法。

可选的混合／语义搜索快速入门

1. 安装工具和嵌入模型

dotnet tool install --global DimonSmart.LocalVectorSearchMcp
ollama pull bge-m3:latest

首次重新索引前，请确保 Ollama 正在运行。

2. 连接客户端

在要为其文档建立索引的项目中运行命令。

Claude Code

claude mcp add local-vector-search \
  --scope local \
  --transport stdio \
  -- local-vector-search-mcp

Codex

codex mcp add local-vector-search \
  -- local-vector-search-mcp

ChatGPT

将 LocalVectorSearchMcp 保持为本地 stdio 服务，并使用 OpenAI Secure MCP Tunnel 进行桥接。对于隧道场景，请使用显式配置，并指定绝对知识库路径和存储路径。

请参阅 通过 Secure MCP Tunnel 使用 ChatGPT。

3. 让 Agent 初始化并使用索引

Check the local documentation index status. Reindex it if necessary,
then find the project's main architectural decisions and summarize them
with file references.

默认情况下，服务会为检测到的项目根目录下的 *.md 文件建立索引，并将索引存储在 .local-vector-search-mcp/index.db 中。

完整的设置和验证流程请参阅入门指南。

示例任务

Before changing the indexing pipeline, find the documented architectural
decisions and constraints that apply to it.

Search the project documentation for rules governing persisted state.
Summarize the relevant invariants and cite the source files.

Attach this PNG and save it as cover.png in the project images folder.
Return the Markdown image reference.

功能

功能	实现方式
精确搜索	使用 BM25 的 SQLite FTS5
语义搜索	sqlite-vec
混合排序	倒数排名融合
存储	项目本地 SQLite
索引内容	Markdown
可编辑内容	Markdown，通过精确元素和子树哈希进行保护
图像资源	PNG、JPEG、WebP、GIF；所有图像工具均使用相对于根目录的路径，默认保存到 images/
导航	文件列表、图像列表和标题大纲
传输方式	通过 stdio 使用 MCP
客户端	Claude Code、Codex、通过 OpenAI Secure MCP Tunnel 使用的 ChatGPT
默认嵌入	兼容 Ollama 的本地端点；离线且仅使用 FTS5 时，请设置 embedding.provider: none

MCP 服务提供十八个工具。MCP 重新索引采用异步方式：kb_reindex 会启动或加入当前唯一的活动重新索引任务，并立即返回；kb_status.indexing 会报告进度和上次结果。CLI --reindex 命令仍为同步执行，只有在索引完成后才会退出。

• kb_status — 检查当前索引。
• kb_reindex — 在后台启动索引构建或重建；监控 kb_status.indexing 以查看进度和最终结果。
• kb_search — 针对派生索引运行可选路径范围限定的词法、语义或混合搜索；每个结果都会通过 indexedSourceHash 标明其索引版本。
• kb_read — 根据语义指针读取当前 Markdown 源文件，并返回精确的源版本 sourceHash。
• kb_patch — 原子性地替换或删除单个语义元素或完整标题章节，并在元素之前或之后插入内容。
• kb_edit_table — 通过哈希表格指针，对 GFM 表格单元格、行、列和对齐方式进行感知源文件的编辑。
• kb_create、kb_move、kb_delete — 管理 Markdown 源文件。
• kb_list_files — 列出 Markdown 文件和未编入索引的资源；使用 pathPrefix 指定目录或确切文件，使用 includeGlob 指定文件名模式。
• kb_outline — 返回确定性的标题树。
• kb_create_pdf_book — 将 Markdown 文档渲染为格式化的 PDF 书籍。
• kb_download_file — 将任何获准访问的工作区文件作为可下载的二进制资源返回。
• kb_save_image — 保存通过 OpenAI 文件参数提供的图像（可选 targetPath）。
• kb_list_images — 通过游标分页递归列出支持的图像资源。
• kb_load_image — 将现有图像作为真实的 MCP 图像内容块返回。
• kb_delete_image — 删除根目录下的一张二进制图像，不更改 Markdown。
• kb_move_image — 在根目录内安全移动一张二进制图像，不更改 Markdown 引用。

对于底层 MCP 或连接器调用，即使工具不需要用户参数，也必须显式提供空的 arguments 对象。规范的 kb_status 线级调用如下：

{
  "name": "kb_status",
  "arguments": {}
}

客户端不应省略参数对象；对于无参数工具，{} 是可互操作的约定。

文件列表筛选条件

kb_list_files.pathPrefix 是相对于根目录的目录路径或确切文件路径， 而非部分文件名前缀。books 和 books/ 会包含 books/ 下的文件； books/chapter.md 会选择该确切文件；books/chapter 不会匹配 books/chapter.md。使用 includeGlob 匹配文件名。提供时，两个筛选条件 都会生效。

目标	参数
列出目录	{ "request": { "pathPrefix": "books" } }
选择单个文件	{ "request": { "pathPrefix": "books/chapter.md" } }
查找匹配的文件名	{ "request": { "includeGlob": "qa-*.md" } }
将模式限定在目录中	{ "request": { "pathPrefix": "books", "includeGlob": "**/*.md" } }

PDF 图书导出

kb_create_pdf_book(path, outputPath?, pageFormat?, style?, profile?) 根据相对于根目录的 Markdown 文件创建 PDF。它会渲染标题、强调、代码、列表、引用、链接、GFM 表格和本地图片。默认输出文件名与源文件相同，扩展名为 .pdf；输出文件必须位于 knowledgeBase.root 下。作为衍生阅读文件，后续再次导出时，会原子替换该路径下已有的 PDF。导出需要设置 knowledgeBase.allowWrites: true，不会更改 Markdown、资源或搜索索引，并返回 {path,bytes,warnings}。无法使用的图片会以 PDF 占位符表示，并列入 warnings；不会获取远程和绝对图片 URL。页面格式：a4、a5（默认）、a6、b5、letter；样式：compact（默认）、classic、modern、technical、academic。

预设配置（由应用定义）：screen = 96 DPI / JPEG 质量 65，standard = 150 DPI / JPEG 质量 82（默认），print = 300 DPI / JPEG 质量 95。所有配置均使用 PDF 完全压缩，保留 Unicode 文本以及图片的布局和物理尺寸，并共享相同的嵌入图片资源。高分辨率 JPEG 和 PNG 可能会降采样；未更改或已优化的文件会保留原编码。带 EXIF/ICC/Adobe 元数据的 JPEG，以及带明确颜色元数据的 PNG，会保留原样，以免方向或颜色发生变化；不支持的 GIF/WebP 沿用渲染器之前的处理方式。无法保证输出文件大小符合 kb_download_file 不变的 25 MiB 限制。Print 配置适用于普通打印，不适用于 PDF/X、CMYK 印刷制作或印前就绪检查。图片处理可能比以前耗时更长；默认配置可能会改变先前导出的 PDF 的栅格质量和大小。

示例（所有调用均使用现有的嵌套 request）：

{"request":{"path":"book.md","outputPath":"exports/screen.pdf","profile":"screen"}}

{"request":{"path":"book.md","outputPath":"exports/standard.pdf"}}

{"request":{"path":"book.md","outputPath":"exports/print.pdf","pageFormat":"a4","style":"classic","profile":"print"}}

工作区文件下载

kb_download_file(path) 将一个根目录相对路径的工作区文件的原始字节作为嵌入式 MCP 二进制资源返回，随后附上 {path,mimeType,bytes,sha256} 元数据。无需写入权限即可使用，支持最大 25 MiB 的任意常规文件；未知扩展名使用 application/octet-stream。不允许使用绝对路径、路径遍历、.git、内部索引文件以及符号链接／联接／重解析点路径。如果需要图片预览或 GIF 转 PNG，请改用 kb_load_image。

图片资源

所有五种图片工具都支持 knowledgeBase.root 下任意位置的 PNG、JPEG、WebP 和 GIF 文件。路径相对于根目录；禁止使用 .git/、内部 SQLite 文件、路径遍历以及符号链接／联接／重解析点路径。建议默认使用 images/ 文件夹，但这不是 API 限制。图片是普通资源，不会被编入索引或嵌入。

kb_save_image(file, fileName?, altText?, targetPath?) 需要设置 allowWrites=true，并保留 OpenAI openai/fileParams 元数据。请在客户端上传或选择实际图片，并传入生成的文件引用。任意文本、原始 Base64 和 data URI 都不是有效的 file 值；如果客户端在调用工具前拒绝这些值，服务端无法规范化这种客户端验证。下载仅支持 HTTPS，并具备 SSRF／重定向保护、25 MiB 流式传输限制、MIME／签名检查和 SHA-256 校验。未指定 targetPath 时，默认保存到 images/，使用 fileName 或源文件名，并在文件名冲突时添加数字后缀（cover.png、cover-2.png）。显式指定的 targetPath 包含最终文件名和扩展名，可以创建中间安全目录，并且绝不会重命名或覆盖已占用的目标路径（ALREADY_EXISTS）。同时使用 targetPath 和 fileName 无效。

保存结果包含 path、mimeType、bytes、小写的 sha256 和 markdown。生成的 Markdown 目标路径相对于工作区根目录。如果文档位于 chapters/ 中，调用方必须根据该文档重新计算并转义相对目标路径。 kb_list_images(cursor?, pageSize?) 会列出根目录下支持的图片扩展名，并按不区分大小写排序，遇到相同项时再按序数排序。游标分页默认返回 50 个项目（范围为 1–200），并支持最后一个游标项目已被删除的情况。kb_load_image(path) 会验证签名、扩展名和大小；其 MCP 结果先包含一个 ImageContentBlock，再包含有关原始文件的 JSON 元数据，不包含 StructuredContent。PNG/JPEG/WebP 会返回原始字节。GIF 会以 PNG 图像块（image/png）的形式返回第一帧，因为部分 ChatGPT 连接器不会公开 image/gif 图像块；文本元数据仍会报告源 GIF 的路径、MIME 类型、字节数和 SHA-256。原始 GIF 保持不变。预览为静态图像（无动画）。

kb_move_image 仅重命名或移动根目录下任意位置的单个二进制图片。输入为 {sourcePath,targetPath,expectedSha256?}。expectedSha256 是可选的 64 位十六进制乐观并发检查值；不匹配时会返回 CONFLICT。必须使用 kb_read 和 kb_patch 单独更新 Markdown 链接。响应为 {previousPath,path,sha256}，不包含 Markdown/索引字段。

kb_delete_image(path) 只会删除受支持的二进制文件，不会扫描 Markdown 引用、检查文件是否正在使用，也不会删除其父目录。其结果仍为 {path,deleted:true}。二进制图片移动和删除都可能留下失效的 Markdown 链接。图片操作不会安排索引编制。

要修复链接，请对可正确寻址的 Markdown 元素分别调用 kb_read / kb_patch。移动并修补的工作流不是多文件事务：请在移动前查找相关文档，移动图片，使用当前语义锚点修补必要元素，并验证新路径。无法安全寻址的原始链接结构不应通过替换任意较大区段来重写。可使用 Git 恢复。

保存、移动和删除需要：

knowledgeBase:
  allowWrites: true

预期的工具错误会返回 IsError=true，以及包含 code 和 message 的 JSON 文本对象，例如 INVALID_PATH、UNSUPPORTED_FORMAT、ALREADY_EXISTS、CONFLICT、PERMISSION_DENIED。图片工具没有 indexSynchronized；对于 Markdown 修改，只有在已确认完成协调或无需协调时，其值才为 true；源文件修改成功但协调尚未确认时，其值为 false。

本地优先且项目隔离

每个服务进程只属于一个项目和一个已配置的 Markdown 根目录。它无法通过 MCP API 选择或搜索其他项目的索引。

默认的嵌入端点是本地 Ollama。除非在 YAML 中明确启用，否则会拒绝远程嵌入端点。不会记录文档文本、嵌入文本、API 密钥、原始向量和签名图片下载 URL。

文档

• 快速入门
• 离线 IDD 集成
• MCP Registry 发现（首个注册表版本发布后即可查看条目）
• Claude Code 设置
• Codex 设置
• 通过 Secure MCP Tunnel 使用 ChatGPT
• 配置
• 维护与更新
• 验证
• 故障排除
• 产品规范
• 架构决策

可编辑工作区

写入和外部文件监视均需显式启用：

knowledgeBase:
  root: .
  allowWrites: true
  watchFiles: true

Markdown 文件仍是索引知识的唯一可信来源。kb_read 和 kb_outline 会直接解析当前源文件；kb_search 使用派生的 SQLite 索引，因此可能暂时返回较旧的索引版本。对 Markdown 的修改会先提交源文件，然后安排同步派生的 SQLite 索引。修改调用不会等待同步完成；indexSynchronized: false 表示源文件已成功提交，但尚未确认派生索引同步完成。内部语义指针仍是逻辑结构地址。公开的具体元素指针采用 logical~selfHash~subtreeHash 格式，其中两个值都是基于精确 UTF-8 源内容计算的 16 位小写 XxHash64 哈希。selfHash 覆盖元素本身；标题的 subtreeHash 覆盖 replace_section 和 delete_section 所拥有的完整章节源内容范围，叶节点的两个哈希值相同。kb_patch 仅根据类型和 selfHash 重新定位；replace_section 和 delete_section 还会校验 subtreeHash。对于 kb_move 和 kb_delete 等整文件操作，kb_read 仍会返回 sourceHash。

对于结构性编辑，replace_element 会替换恰好一个 Markdown 元素，delete 会删除恰好一个元素；使用 delete 删除标题时会保留其章节正文。replace_section 会替换一个标题及其完整的所属章节子树，而 delete_section 会删除整个子树。这两种章节操作都要求使用规范的 v2 标题指针，并会校验 subtreeHash。

五种图像工具均不会修改 Markdown，也不会安排 Markdown 索引同步。

kb_patch 示例

MCP 方法接受一个 request 对象。其中的 operations 始终是数组，即使只应用一项操作也是如此。新的具体元素指针应使用 kb_read、kb_search 或 kb_outline 返回的规范 v2 锚点。旧版 logical~selfHash 锚点仍可用于导航和 Self 修改，但 replace_section 需要 v2 子树哈希。kb_patch 不接受 expectedSourceHash。

使用 replace_element 可替换恰好一个可编辑 Markdown 元素。对于标题，它只会更改标题本身，并保留现有的章节正文。替换内容必须解析为恰好一个可编辑元素；替换标题时，标题级别必须保持不变。旧版 replace 仍受支持，但已弃用，且使用相同的验证规则。

使用 replace_section 可原子地重写完整的标题章节。目标必须是同时包含 selfHash 和 subtreeHash 的规范 v2 标题锚点。替换范围从该标题开始，延伸至下一个级别小于或等于目标级别的标题之前，或延伸至文件末尾。替换内容必须以相同级别的标题开头，之后只能包含更深层级的标题。

替换一个元素：

{
  "request": {
    "path": "chapter.md",
    "operations": [
      {
        "kind": "replace_element",
        "pointer": "1.2.p2~8f41c721d904a8bc~8f41c721d904a8bc",
        "markdown": "New paragraph."
      }
    ]
  }
}

替换整个章节：

{
  "request": {
    "path": "chapter.md",
    "operations": [
      {
        "kind": "replace_section",
        "pointer": "1.2~0123456789abcdef~fedcba9876543210",
        "markdown": "## Updated section\n\nNew body.\n\n### Nested heading\n\nNested body."
      }
    ]
  }
}

在后面插入：

{
  "request": {
    "path": "chapter.md",
    "operations": [
      {
        "kind": "insert_after",
        "pointer": "1.2.p2~8f41c721d904a8bc~8f41c721d904a8bc",
        "markdown": "Additional paragraph."
      }
    ]
  }
}

删除：

{
  "request": {
    "path": "chapter.md",
    "operations": [
      {
        "kind": "delete",
        "pointer": "1.2.p2~8f41c721d904a8bc~8f41c721d904a8bc"
      }
    ]
  }
}

支持的 kind 值包括 replace、replace_element、replace_section、delete_section、insert_before、insert_after 和 delete。replace、replace_element、replace_section 和插入操作需要 markdown；删除操作不需要。特殊的 document 指针不含哈希，可与 insert_before 或 insert_after 配合，在文档边界处插入。现有有效的单元素 replace 请求仍保持兼容；通过 replace 替换多个元素会被明确拒绝，应改用 replace_section 或其他明确指定的操作。

如果目标的 selfHash 仍然有效，文件其他位置的不相关编辑不会使 Self 修改失效。如果目标因上方插入内容而移动，只有在相同元素类型和完全匹配的 selfHash 能唯一标识当前元素时，kb_patch 才会重新定位该元素。随后，replace_section 还会验证原始 subtreeHash，因此所有发生在所属章节范围内的编辑（包括原始/未索引的 Markdown）都会被拒绝，而不会被覆盖。

当前范围

当前版本支持已索引的本地 Markdown 和普通图片资源。五种图片工具均以 knowledgeBase.root 作为边界；默认保存到 images/。支持通过 OpenAI Secure MCP Tunnel 从 ChatGPT 远程访问，该隧道会在外部启动并桥接现有的本地 stdio 服务。

PDF/DOCX/OCR、任意二进制文件上传、图片嵌入/搜索、图片调整大小/转码/生成缩略图、自动插入 Markdown 图片、媒体数据库、Web UI、Git 历史索引、直接远程 HTTP MCP 传输、应用层身份验证、多用户模式、CRDT 和自动合并均不在当前范围内。

可寻址的 Markdown 列表项和不透明引用块

kb_read 将单个列表项作为 list_item 暴露，使用 li1、1.li2、1.li2.li1 以及常规的双井号锚点后缀。父级文本不包含嵌套项的文本。replace_element（及其已弃用的别名 replace）会更改该项在首个嵌套子项之前的自身源内容，保留所有后代及其后未触及的父级内容；它会检查 selfHash。显式使用 replace_subtree 或 delete 会替换／移除整个子树，且要求提供当前的两个哈希值。相邻插入会检查自身哈希，并接受一个缩进符合源格式且列表标记兼容的同级项；空行和有序列表编号都不会被静默规范化。

独立的 Markdown 引用块是一个不透明的 block_quote，标识符为 qN 或 1.qN，无论其内部 Markdown 内容如何（包括 > - item）。它只能作为整体读取、搜索、删除、在其前后插入或替换。在列表／引用块内被隐藏的旧段落指针必须重新读取。

列表项编辑使用精确的左闭右开源范围：子树包含所有后代，而父级自身的文本仅包含不属于子项的源片段。replace_element 会替换连续的自身前缀，保留所有嵌套项及其后属于父级的源内容；replace_subtree 会替换整个子树；delete 会在存在行结束符时将其一并删除；insert_after 会在所有后代之后插入。不会进行 AST 序列化或全篇空白规范化，未修改的源字节（包括 BOM 和混合 EOL）都会保留。

列表插入或替换必须提供一个与目标项物理缩进相同、标记样式兼容的列表项（有序列表标记的编号可以不同）。replace_element 接受不含子项的列表项；它会保留现有子项，并在无法证明源前缀安全时拒绝操作。若要有意更改嵌套列表，请使用 replace_subtree 并提供当前的 subtreeHash。replace_subtree 和同级插入支持嵌套项；当 Markdig 将代码、HTML 注释及其他 Markdown 块归属到新列表项时，这些内容也允许出现在其中。新子树之外的独立块会被拒绝。例如，如果注释将顶层列表项所在列表分隔开，- Updated\n\n 就不能替换该项；如果 Markdig 将注释归属到该项，则允许使用 - Updated\n\n 。引用块片段同样必须恰好构成一个不透明引用块，且不能吸收相邻内容。

服务器会在写入前重新解析整个提议结果：现有元素、不可寻址块、列表容器归属关系、父子关系以及相邻边界都必须保持不变。存在歧义或编辑重叠（包括在一次 kb_patch 中执行多个操作）时，操作会以结构错误原子性地失败；源文件不会更改。对于不支持的缩进、列表拆分／合并以及引用块边界歧义，系统会有意拒绝操作，而不会自动格式化。

搜索指针和读取提示仍会标识首个 chunk 元素，不一定是精确匹配的列表项。Chunker v5 要求显式重建派生索引：kb_reindex(force=true) 或 CLI --reindex --force。不会执行 Markdown 迁移。

语义化 Markdown 表格

独立的 GFM 管道符表格会作为原子 table 元素呈现，并带有分节范围内的 tN 指针。使用表格的哈希指针调用 kb_read，即可获取 table.columns（名称、索引、对齐方式）和 table.rows（从 0 开始的数据行索引及可见单元格文本）。常规文档分页不会重复包含结构化投影。

新的 kb_edit_table 工具接受 path、格式为 tN~selfHash~subtreeHash 的当前 pointer，以及以下七种操作之一：update_cells、insert_row、delete_row、insert_column、delete_column、rename_column 或 set_alignment。示例：

{
  "path": "recipes.md",
  "pointer": "1.t1~<selfHash>~<subtreeHash>",
  "action": "update_cells",
  "updates": [
    {
      "where": { "column": "Product", "equals": "Chicken" },
      "column": "Price",
      "value": "20"
    }
  ]
}

当行值唯一时，优先使用 where；当表头唯一时，优先使用 column；否则使用数字形式的 rowIndex 和 columnIndex。查找严格区分大小写，并要求精确匹配。update_cells 可原子地批量更新多个单元格。值默认作为字面 text 处理，并安全转义 Markdown；valueFormat=markdown 则允许有意使用行内格式。新插入的行值和列默认值均按字面文本处理。

成功的响应包含新的表格 pointer、更新后的 sourceHash 和索引同步状态。后续编辑请使用返回的指针；遇到 CONFLICT 时，请重新读取表格。编辑会拒绝包含额外未处理物理单元格的表格，保留无关的 Markdown，并使用现有的原子工作区写入器。代码、列表或块引用中的表格没有独立的表格指针。要完整删除表格，请使用 kb_patch。

表格解析会将派生索引格式更改为 chunker 版本 6。请使用 kb_reindex(force=true) 或 CLI --reindex --force 重建不兼容的索引；无需迁移 Markdown 文件。

Markdown 链接图

运行 kb_reindex 后，使用 kb_links 浏览任一方向的显式 Markdown 引用（也可执行限制深度的图遍历），并诊断缺失的链接文档。该图不会推断语义关系，且无需使用嵌入。请参阅 Markdown 链接图和 MCP 示例。