codebase-memory-mcp 的 SQLite 本地补丁手册：MAX_PATHNAME 4 KiB 提升与 Amalgamation 更新流程

codebase-memory-mcp（下称 CBM）将代码库索引持久化为 SQLite 知识图谱，其存储层使用的是内嵌（vendored）的 SQLite amalgamation 单文件源码。本篇技术文章围绕 vendored/sqlite3/PATCHES.md 展开：讲解 CBM 对 SQLite 施加的本地补丁（Unix VFS 路径上限 MAX_PATHNAME 从 512 提升到 4096）、该补丁解决的真实故障模式（SQLITE_CANTOPEN），以及 amalgamation 刷新后"重放补丁 + 更新校验和"的完整维护流程，并结合仓库源码给出每一处改动与构建配置的验证依据。

1. 为什么要在 vendored SQLite 上打本地补丁

SQLite 本身处于公有领域（见 vendored/sqlite3/LICENSE.md），但 CBM 并不直接使用官方发布的 amalgamation，而是把它放入仓库的 vendored/sqlite3/ 目录，自行编译并施加少量本地修改。当前快照下该目录包含 5 个文件：

• sqlite3.c / sqlite3.h / sqlite3ext.h：SQLite 3.51.3 的 amalgamation 与头文件（版本定义见 vendored/sqlite3/sqlite3.h，其来源标注为 Fossil check-in 737ae4a34738ffa0c3ff7f9bb18df914dd1c，见 sqlite3.c 文件头注释）；
• LICENSE.md：公有领域声明；
• PATCHES.md：本地补丁清单，即本文主体文档。

之所以需要维护一份"补丁清单"，根源在于 amalgamation 是周期性刷新的大文件：一旦从上游拉取新版 SQLite 重新合并，所有本地修改都会被覆盖丢失。因此 PATCHES.md 的开头明确了维护契约——

Reapply every patch below after refreshing the amalgamation, then update scripts/vendored-checksums.txt (shasum -a 256 vendored/sqlite3/sqlite3.c).

即：每次刷新 amalgamation 后，必须逐条重放补丁，并重新计算 sqlite3.c 的 SHA-256 更新进校验和清单。该校验和清单 scripts/vendored-checksums.txt 中同时登记了 sqlite3 目录下全部 5 个文件的哈希（scripts/vendored-checksums.txt），其中 sqlite3.c 当前快照的 SHA-256 为 190d82e7899c6cf74260f122c4a737f77c68e98e8d516750df8d56e7fc00ad5——任何对 amalgamation 的改动（包括补丁是否遗漏重放）都会使该值变化，从而可以被 CI 或人工比对发现。

2. 补丁 1：Unix VFS 路径上限 MAX_PATHNAME 512 → 4096

PATCHES.md 目前登记了唯一一个本地补丁，其内容与动机如下：

#define MAX_PATHNAME 4096

2.1 问题：上游 512 字节上限与 CBM 的 4 KiB 路径假设

按 PATCHES.md 的说明：上游 SQLite 的 Unix VFS 将数据库文件的完整绝对路径上限硬编码为 512 字节，而 CBM 在自身各处支持 4 KiB 的路径——典型场景是"深层 home 目录下的缓存根路径"与"Linux 上的长项目路径"。若沿用上游默认值，一旦知识图谱 store 的绝对路径超过 512 字节，sqlite3_open 就会直接失败，返回 SQLITE_CANTOPEN。

"CBM 支持 4 KiB 路径"这一点在源码中有直接证据：知识图谱存储模块 src/store/store.c 为打开、预写和 seal 数据库文件的路径都使用了 4096 字节缓冲，例如 src/store/store.c 的 char open_path[4096];，同文件还有 prepare_path[4096]、seal_path[4096] 等多处；src/foundation/constants.h 也定义了 CBM_SZ_4K = 4096 常量。换言之，CBM 上层代码完全按 4096 字节路径来工作，若底层 SQLite Unix VFS 仍然在 512 处截断，就会形成"上层认为路径合法、下层打不开文件"的断层。

2.2 为什么取 4096 以及影响面

PATCHES.md 给出了取值的两条理由：

1. 4096 与 Linux 的 PATH_MAX 一致，也与 CBM 自身的路径缓冲尺寸对齐；
2. 影响面仅限 Unix VFS：Windows 与其余 VFS 层不使用 MAX_PATHNAME，因此该补丁不会改变其他平台的打开路径行为。

补丁在仓库中确实已生效：vendored/sqlite3/sqlite3.c 第 39381 行即为 #define MAX_PATHNAME 4096。围绕该宏的使用点也印证了其作用域——Unix VFS 内用于拼接收拾器信号量名、临时目录与数据库文件名的数组（如 char aSemName[MAX_PATHNAME+2]、char zDirname[MAX_PATHNAME+1] 等）均受此上限约束；而 mxPathname 字段同样引用 MAX_PATHNAME（见 vendored/sqlite3/sqlite3.c）。

3. 维护流程：刷新 amalgamation 后的标准动作

结合 PATCHES.md 的约定与仓库现状，一次完整的 SQLite amalgamation 升级流程为：

1. 用上游新版替换 vendored/sqlite3/ 中的 amalgamation 文件（sqlite3.c、sqlite3.h、sqlite3ext.h）；
2. 逐条重放 PATCHES.md 中登记的补丁。当前版本只有一条：把 Unix VFS 段的 #define MAX_PATHNAME 512 改为 4096（即第 2 节所示修改，落在 sqlite3.c 的 os/unix 实现段）；
3. 重算并更新校验和：按文档给出的命令执行

   shasum -a 256 vendored/sqlite3/sqlite3.c
   

   将结果写回 scripts/vendored-checksums.txt 中 vendored/sqlite3/sqlite3.c 对应条目；
4. 验证：检查 sqlite3.c 中确实存在 #define MAX_PATHNAME 4096（当前快照位于 vendored/sqlite3/sqlite3.c），并可运行仓库内针对存储层的测试（如 tests/test_sqlite_writer.c、tests/test_store_search.c 等）确认行为回归。

需要强调的是：跳过第 2、3 步的后果是静默的——校验和不匹配会被工具链发现，但"补丁忘记重放"本身不会报错，只会让长路径场景重新出现 SQLITE_CANTOPEN。因此 PATCHES.md 这种"补丁即清单"的文档化方式，价值在于把隐性的手工步骤变成了可核查的书面契约。

4. 旁证：amalgamation 在 CBM 中的编译方式

虽然不属于 PATCHES.md 的内容，但理解补丁生效环境需要了解 amalgamation 如何被编译。Makefile.cbm 中 sqlite3 目标显示：

• 直接编译 vendored 的 vendored/sqlite3/sqlite3.c（SQLITE3_SRC = vendored/sqlite3/sqlite3.c），注释说明"vendored amalgamation — compiled ourselves for ASan instrumentation"，即自行编译以便接入 sanitizer；
• 构建参数包含 -DSQLITE_DQS=0（不将双引号字符串当作 SQL 标识符）、-DSQLITE_THREADSAFE=1（序列化线程安全模式）、-DSQLITE_ENABLE_FTS5，以及关键的安全裁剪 -DSQLITE_OMIT_LOAD_EXTENSION。

其中 SQLITE_OMIT_LOAD_EXTENSION 的理由在 Makefile 注释中写明：CBM 没有任何代码调用 sqlite3_load_extension 或 sqlite3_enable_load_extension，而且"绝不允许一个图数据库有机会拉入（外部）扩展"。这与 MAX_PATHNAME 补丁同属"对 vendored 依赖做最小化、可审计定制"的思路：一个放宽了 CBM 真实需要的路径上限，一个移除了运行时加载任意代码的入口。

此外 Makefile 为 amalgamation 维护了三套目标文件——测试构建（-O1 -g）、TSan 构建（tsan_sqlite3.o）与生产构建（-O2，见 Makefile.cbm）——三者编译同一份打过补丁的 sqlite3.c，保证测试与生产环境行为一致。

5. 小结

事项	依据
本地补丁唯一一条：MAX_PATHNAME 512 → 4096	vendored/sqlite3/PATCHES.md
补丁动机：上游 512 上限导致长绝对路径返回 SQLITE_CANTOPEN	vendored/sqlite3/PATCHES.md
4096 与 Linux PATH_MAX、CBM 自身 4 KiB 路径缓冲（open_path[4096] 等）对齐	src/store/store.c、src/foundation/constants.h
补丁已实际落在 amalgamation 中	vendored/sqlite3/sqlite3.c
刷新后须重放补丁并以 shasum -a 256 更新校验和	scripts/vendored-checksums.txt
当前 SQLite 版本 3.51.3，构建时裁剪扩展加载	vendored/sqlite3/sqlite3.h、Makefile.cbm

对维护 vendored 依赖的 C 项目而言，这套模式的核心经验是：改动尽量小（单个宏定义）、动机写成文档（PATCHES.md）、落点可定位（精确到 amalgamation 中的宏与数组）、变更可校验（SHA-256 清单），并配套裁剪无关攻击面（SQLITE_OMIT_LOAD_EXTENSION）。这也是 CBM 能在"单静态二进制、零外部依赖"前提下长期跟随上游 SQLite 版本演进的工程基础。