codebase-memory-mcp 第三方依赖治理实战:从 vendored 组件清单到 LICENSE 溯源与再集成规范

本文基于仓库根目录的 THIRD_PARTY.md 展开,系统讲解 codebase-memory-mcp 如何管理一个"单文件静态二进制、零运行时依赖"项目中的全部第三方资产:tree-sitter 运行时与 160+ 个语法的版本溯源、11 个 vendored C/C++ 库的许可证清单、本地补丁的登记与再集成规则,以及 CI 层的许可证门禁。读完后,你既能快速查清任一 vendored 组件的上游出处与许可证,也能理解其"补丁可重放、校验和可审计"的依赖治理机制。

一、总体原则:每个组件自带 LICENSE,补丁必须可重放

THIRD_PARTY.md 的开篇确立了项目的基本约定:所有第三方代码以 vendored(源码内嵌)方式引入,每个 vendored 组件目录都随源码携带上游的 LICENSE(或 COPYING / NOTICE)文件。这与项目的分发形态强相关——发布物是单个静态二进制,运行环境不存在包管理器,因此许可证文本、版本锚点和补丁记录必须全部随仓库与发布包一起交付。

文档按资产类型分为六个板块,下文逐一展开:

1. Tree-sitter 运行时(含唯一的本地补丁);
2. Tree-sitter 语法(含规范溯源记录 MANIFEST 与特例清单);
3. Vendored C/C++ 库清单(11 个库);
4. 内嵌模型数据(nomic-embed-code 词元向量);
5. Hybrid LSP 的参考语言服务器致谢与标准库类型数据来源;
6. 内嵌 Graph UI 前端依赖的许可证登记。

这套结构本身就是可复制的实践:先按"资产类别"分层,再对每一层给出"路径 + 许可证 + 出处 + 本地修改"四元组。

二、Tree-sitter 运行时:唯一的本地补丁与再集成规则

tree-sitter C 运行时 vendored 在 internal/cbm/vendored/ts_runtime/,许可证 MIT,版权 (c) 2018–2024 Max Brunsfeld。文档同时声明了一处本地修改,这也是全文档中信息密度最高的段落。

2.1 CBM patch:为 GLR 栈合并设置递归深度上限

补丁位于 stack.c,在第 913 行附近(上游行号)对 stack_node_add_link 的递归歧义合并加了深度上限:

• 上限宏为 CBM_TS_STACK_MERGE_MAX_DEPTH,值 512,定义在 stack.c#L28;
• 深度检查在 stack.c#L255 生效:if (depth < CBM_TS_STACK_MERGE_MAX_DEPTH) 才执行合并,超限后歧义留在 GLR 栈上不做合并。

为什么是 512?源码注释(stack.c#L20-L27)给出完整推演:深度嵌套的语法歧义输入(如 Perl 的 f(f(f(...))))会按层数在原生 C 栈上递归,在 Windows 线程约 1 MB 的栈上触发 SIGSEGV,极端深度下连 8 MB 的 POSIX 栈也会溢出——且崩溃发生在 ts_parser_parse 内、任何语言提取器运行之前。512 这个值对齐了项目内 CBM_LSP_*_MAX_WALK_DEPTH 一系的遍历上限;按每层约 260 B 估算,512 层约 130 KB,对 1 MB 线程栈留有充足余量,同时远超任何现实源码的嵌套深度。超限后的行为"是合法解析、绝不产生错误结果",与上游既有的 MAX_LINK_COUNT 熔断出口同构——这是选择该机制而非直接报错的原因。

补丁在源码中以 // CBM patch: 行内标记显式标注,文档还给出了一条硬性运维规则:重新 vendored 上游(例如 ts_runtime 升级到 0.26.x)时必须重新应用该上限补丁。

2.2 common 目录:两个不同出处的"共享头"

internal/cbm/vendored/common/ 下有两组性质不同的共享文件,文档分别给出出处:

• scanner.h、tag.h:来自 tree-sitter-html(MIT,(c) 2014 Max Brunsfeld),该目录保留 tree-sitter-html 的 LICENSE;
• common/tree_sitter/ 下的核心运行时头文件 alloc.h、array.h、parser.h:属于 tree-sitter C 运行时本体(MIT,(c) 2018 Max Brunsfeld),在该子目录内携带独立 LICENSE。

区分"通用扫描器辅助头"与"运行时核心头"的出处,避免了把两组代码的版权与许可证混为一谈——对多上游共用的目录,这是溯源文档中容易踩坑的点。

三、Tree-sitter 语法:160+ 个解析器的溯源与许可证分布

文档声明 internal/cbm/vendored/grammars/<lang>/ 下 vendored 了 160 个预生成解析器(生成的 parser.c 加适用时的 scanner.c,静态编译进二进制),每个语法目录携带上游 LICENSE。

规范溯源记录是 internal/cbm/vendored/grammars/MANIFEST.md。从源码结构看,MANIFEST 比正文表格信息更细:它把每个语法的上游仓库、钉住的 commit、以及跨注册表(nvim-treesitter + Helix)交叉验证结论固化成机器可核对的记录,并在 2026-06-02 重建了最初"无版本记录"的 provenance。按 MANIFEST 2026-08-28 的口径,当前共 162 个语法(143 个来自上游、14 个第一方/自维护、5 个注册表分歧),ABI 分布为 9× ABI-13、80× ABI-14、73× ABI-15,且运行时 ABI 上限为 15——升级前不得 vendored ABI 16 语法。MANIFEST 还给出了一条可复算的口径:grep -h '#define LANGUAGE_VERSION' internal/cbm/vendored/grammars/*/parser.c | sort | uniq -c,防止计数行漂移(它自己就修正过一处历史误计)。

3.1 许可证分布

THIRD_PARTY.md 给出的语法规则汇总:

• 绝大多数语法为 MIT;
• clojure(sogaiu/tree-sitter-clojure)与 fennel 为 CC0-1.0;
• jinja2 与 just 为 Apache-2.0;
• pine 为 ISC(由上游声明);
• 第一方语法 7 个:chialisp、cobol、form、janet、magma、protobuf、wolfram——MIT、(c) DeusData,各携带与仓库根字节一致的 LICENSE。文档特别解释:chialisp 是为 Chia 智能币语言专门编写的通用 s-表达式语法,因不存在可用的公共语法,其源码与 corpus 测试位于 tools/tree-sitter-chialisp/;第一方语法不携带第三方版权,因为"没有第三方";
• 自维护 fork 7 个:arkts、assembly、cfml、cfscript、dotenv、pine、qml——保留原上游作者的许可证。其中 arkts 是 tree-sitter-typescript(MIT,(c) 2017 Max Brunsfeld;基于 tree-sitter-javascript,MIT,(c) 2014 Max Brunsfeld)的一等衍生,新增 (c) 2026 DeusData 的 ArkTS 扩展,语法源码在 tools/tree-sitter-arkts/。

3.2 特例一:tree-sitter-plsql

• 上游:AndreasMaierDe/tree-sitter-plsql,MIT,(c) 2022 AndreasMaierDe;
• Vendored 路径:internal/cbm/vendored/grammars/plsql/,钉住 commit 28aebef209be;
• 定位:社区维护的 Oracle PL/SQL 语法,不在 nvim-treesitter 或 Helix 注册表中(MANIFEST 中标记 community-niche),无外部 scanner;
• 本地补丁一处:parser.c 的 #include <tree_sitter/parser.h> 改为引号形式(其他所有 vendored 语法均用引号形式,以便从所在目录解析 tree_sitter/ 头文件),已在 MANIFEST 登记;
• 历史:PL/SQL 支持最初由 Oğuz(@ouzsrcm)在 PR #1033 中贡献。

3.3 特例二:tree-sitter-objectscript(UDL + routine)

• 上游:intersystems/tree-sitter-objectscript,MIT,(c) 2025 InterSystems Corporation;
• Vendored 路径:internal/cbm/vendored/grammars/objectscript_udl/ 与 internal/cbm/vendored/grammars/objectscript_routine/,钉住 commit a7ffcdf;
• 定位:InterSystems 官方维护的 ObjectScript(InterSystems IRIS / Caché)语法,属厂商自维护,不在 nvim-treesitter / Helix 注册表中;
• 本地修改:每个 scanner.c 的上游 #include "../../common/scanner.h" 被重指向每目录一份 objectscript_common.h(复制自上游 common/scanner.h);该副本中两个循环计数器由 uint8_t 加宽为 int(MANIFEST 登记在案)。重 vendored 时需重放 include 改名与加宽两处修改。

3.4 再集成时的补丁重放清单

MANIFEST 将"本地补丁必须随上游刷新重放"落实成两张可勾选的表:一是定义提取自定义处理表(ada、cairo、chialisp、clojure、plsql 等语法的定义节点不暴露通用提取器可识别的 name 字段,需在 extract_defs.c 中维护分支,由 tests/test_lang_contract.c 的 contract_all_grammars_in_graph 图宽度测试守护);二是本地源码补丁表,例如 crystal / rescript / purescript 三个 scanner 对零长 memcpy 的 UBSan 防护、plsql 的 include 引号形式。这类"补丁台账"是 vendored 工作流中最容易丢失的隐性知识,文档把重放责任写进了溯源文件本身。

四、Vendored C/C++ 库:11 个库的许可证清单

文档以表格给出全部 vendored C/C++ 库,完整继承如下:

库	路径	许可证	上游项目
SQLite 3	vendored/sqlite3/	Public Domain	sqlite.org
mimalloc	vendored/mimalloc/	MIT	microsoft/mimalloc
yyjson	vendored/yyjson/	MIT	ibireme/yyjson
xxHash	vendored/xxhash/	BSD-2-Clause	Cyan4973/xxHash
TRE	vendored/tre/	BSD-2-Clause	laurikari/tre
LZ4	internal/cbm/vendored/lz4/	BSD-2-Clause(库文件)	lz4/lz4
Zstandard	internal/cbm/vendored/zstd/	BSD-3-Clause(BSD / GPLv2 双许可中选定 BSD)	facebook/zstd
simplecpp	internal/cbm/vendored/simplecpp/	0BSD	danmar/simplecpp
Verstable	internal/cbm/vendored/verstable/	MIT	JacksonAllan/Verstable
wyhash	internal/cbm/vendored/wyhash/	Unlicense(公有领域)	wangyi-fudan/wyhash

两点值得注意:

1. 双许可的显式选择:Zstandard 为 BSD / GPLv2 双许可,文档明确"选定 BSD"——对希望避免 GPL 传染面的静态二进制而言,许可选择必须写死并留痕。
2. 本地修改登记:目前唯一带本地补丁的是 SQLite,记录在 vendored/sqlite3/PATCHES.md——将 Unix VFS 的 MAX_PATHNAME 上限从 512 提到 4096,以对齐 CBM 全链路的 4 KiB 路径支持;PATCHES.md 说明,深 home 目录下超过 512 字节的绝对路径在上游值下会以 SQLITE_CANTOPEN 失败,4096 与 Linux 的 PATH_MAX 及 CBM 自身路径缓冲一致,Windows 与其他 VFS 层不受影响。补丁要求每次上游刷新后重放,并纳入 scripts/vendored-checksums.txt 的 SHA-256 覆盖——该文件目前对约 1079 个 vendored 文件逐一记录了校验和,任何未登记的字节漂移都会暴露。

文档还声明了反向事实:Graph-UI 的 HTTP 服务器是第一方实现(src/ui/httpd.c + src/ui/http_server.c),没有使用任何第三方 HTTP 库。

五、内嵌模型数据:nomic-embed-code 词元向量

语义向量搜索使用的静态词元词向量派生自 nomic-embed-code 模型,vendored 在 vendored/nomic/:

• 模型:nomic-ai/nomic-embed-code;
• 许可证:Apache License 2.0;
• 版权:(c) Nomic AI;
• 精确派生过程见 vendored/nomic/NOTICE:对过滤后的词表(40,856 个 token × 768 维)运行上游模型的完整逐 token 推理,再经 int8 单位向量量化得到内嵌词表 code_tokens.h / code_tokens.txt 与 int8 向量 blob code_vectors.bin(经 code_vectors_blob.S 内嵌)。提取程序为 scripts/extract_nomic_vectors.py,NOTICE 同时声明"模型的其他部分均不分发"。

这段展示了模型权重类资产的合规处理范式:只分发派生数据,并附 NOTICE 记录模型来源、许可证与量化流程,而非打包整个模型。

六、Hybrid LSP:行为参考致谢,零源码依赖

Hybrid LSP 层(internal/cbm/lsp/)是为该项目原创的 C 实现,不含有任何语言服务器的源码。它之所以出现在 THIRD_PARTY 文档中,是因为其类型解析行为"结构上受以下语言服务器/规范启发,并以其公开行为为输出兼容性验证基准"——属于致谢与许可证备案,而非代码依赖:

语言	参考实现 / 规范	上游许可证
TypeScript / JavaScript	tsserver(microsoft/TypeScript)、typescript-go	Apache-2.0
Python	pyright	MIT
Go	gopls(golang/tools)	BSD-3-Clause
PHP	PHP 语言参考 + Composer PSR-4 自动加载规范	—
C#	Roslyn(dotnet/roslyn)	MIT
C / C++	clangd(llvm/llvm-project)	Apache-2.0 WITH LLVM-exception
Java	Java 语言规范;输出对齐 Eclipse JDT LS	EPL-2.0(仅参考)
Kotlin	Kotlin 语言规范;fwcd/kotlin-language-server	MIT
Rust	rust-analyzer	MIT OR Apache-2.0

6.1 标准库类型数据的三种来源

internal/cbm/lsp/generated/ 下的标准库类型注册表按来源分为三类,文档逐一登记了许可证:

• Python(python_stdlib_data.c):从 python/typeshed 的类型存根生成,钉住 commit a7912d521e16ff63caf7a8b64b9072542be36777,Apache-2.0,(c) typeshed 贡献者;生成器为 scripts/gen-py-stdlib.py;
• Go(go_stdlib_data.c):通过内省 Go 标准库的公开 API 生成(golang/go,BSD-3-Clause);
• Java、Kotlin、C#、PHP、C/C++、Rust:由公开 API 文档与语言规范人工整理,未提取或转录任何上游源码。

这种"参考实现(零拷贝)+ 数据派生(带来源 commit)+ 人工整理(声明无第三方代码)"的三分法,把"行为对齐"与"代码依赖"在许可证意义上彻底分开,是 LSP 类项目少见的干净做法。

七、内嵌 Graph UI:前端依赖与许可证文本的自动生成

以 --with-ui 构建的发布二进制会内嵌编译后的 graph-ui/ 前端 bundle。其 npm 依赖(React、three.js、@react-three/*、radix-ui、lucide-react、tailwindcss 等)全部处于宽松许可证(MIT / ISC / Apache-2.0 / Zlib)之下;精确依赖集记录在 graph-ui/package.json 与 graph-ui/package-lock.json,而生产 bundle 的逐包许可证文本由 scripts/gen-ui-licenses.py 生成(输出确定性排序:按 name@version),追加进随 -ui 发布归档分发的 THIRD_PARTY_NOTICES.md。

仓库内的配套机制可在构建系统中直接验证:

• Makefile.cbm 提供 cbm-with-ui 目标,经 embed 规则调用 scripts/embed-frontend.sh 将前端产物转换为可链接目标文件,再与 vendored 生产目标(OBJS_VENDORED_PROD)一起链接;
• scripts/gen-third-party-notices.sh 将各 vendored 组件的许可证文本聚合为默认输出 build/THIRD_PARTY_NOTICES.md,是发布归档内 NOTICE 文件的上游来源。

八、CI 门禁:两层校验保证清单不漂移

溯源文档的长期可信度由 CI 保障。scripts/license-gate.sh 在安全 workflow 中(干跑与发布均运行)执行两层检查:

1. 结构层:每个 vendored 组件目录必须物理携带许可证文件;
2. 检测层:用 ScanCode Toolkit 扫描全部 vendored 许可证文本与第一方源码,任何落在 scripts/license-policy.json 白名单之外的检测结果都会使门禁失败(判定逻辑见 scripts/license-gate-check.py)。

生成的语法解析器本体(无头文件的 parser.c)在运行时 ScanCode 路径中被排除,但其目录级 LICENSE 仍会被扫描,并由结构层保证每个语法必带一份。门禁还提供 --selftest 模式:植入一个违规项并断言结构层能捕获它——CI 会在正式门禁前先跑自测,确保"静默损坏的门禁"无法放行。配合 scripts/vendored-checksums.txt 的文件级 SHA-256 基线,THIRD_PARTY.md 中的每一项声明都具备"可重算、可回归"的验证路径。

九、小结:可直接借鉴的 vendored 治理清单

综合 THIRD_PARTY.md 与仓库证据,codebase-memory-mcp 的第三方依赖治理可以归纳为六条可操作规则:

1. 每目录一 LICENSE:vendored 组件目录必须携带上游许可证原文,结构缺失即 CI 失败;
2. 四元组登记:每项资产登记"路径 + 许可证 + 上游 commit/出处 + 本地修改";
3. 补丁台账化:本地补丁(SDK 栈深上限、SQLite 路径上限、objectscript include 重命名、UBSan 防护等)写入随源码分发的台账文件,并显式声明"重 vendored 必须重放";
4. 校验和兜底:全部 vendored 文件纳入 SHA-256 基线,字节漂移可检测;
5. 双许可显式选边:Zstandard 等双许可库写死所选许可(BSD);
6. 行为对齐与代码依赖分离:LSP 层对参考服务器的致谢不含任何源码,标准库数据按"生成 / 内省 / 人工整理"三类分别备案。

对于同样以静态二进制分发、依赖源码内嵌的项目,这套"文档清单 + MANIFEST 溯源 + 补丁台账 + 校验和 + CI 双层门禁"的组合,是一份可直接对照落地的依赖合规模板。