codebase-memory-mcp 的 PyPI 发行包：如何用一个纯标准库 Python 包装器安全投递原生运行时

本文以 pkg/pypi/README.md 为主体，解析 codebase-memory-mcp 发布到 PyPI 的包装器设计：它如何用一次 pip install 完成原生二进制的受检下载、缓存自愈、并发锁保护与参数透传。读完后你可以复现其安装/升级/卸载的完整操作路径，并理解“下载—校验—安全解包—原子发布—崩溃恢复”这条供应链安全链在源码中的每一环，以及为什么该包装器仅依赖 Python 标准库即可实现。

PyPI 包是什么：一个原生二进制的“受检启动器”

README 对包的定位非常明确：codebase-memory-mcp 是一个面向 AI 编码智能体的高速代码智能引擎（mcp-name 为 io.github.DeusData/codebase-memory-mcp），平均仓库以毫秒级完成索引，Linux 内核（2800 万行）约 3 分钟，结构化查询响应在 1ms 以内。而发布在 PyPI 上的 Python 包本身不包含引擎代码，它的职责是：

首次运行时从 GitHub Releases 下载所选的 codebase-memory-mcp 运行时集，在发布到你的操作系统缓存目录之前先对其进行验证。该运行时集包含原生可执行文件和经过认证集成的资产，图形 UI（graph UI）在每一个构建中都内嵌其中。

这一点从包结构可以直接印证：pyproject.toml 中包名为 codebase-memory-mcp，当前版本 0.10.8，requires-python >= 3.8，MIT 协议，wheel 打包目标只有一个 src/codebase_memory_mcp 包。入口点定义为：

[project.scripts]
codebase-memory-mcp = "codebase_memory_mcp:main"

init.py 仅做版本读取（importlib.metadata）并转发 main。全部逻辑集中在 _cli.py 中，且其 import 列表（hashlib、json、secrets、stat、subprocess、tarfile、zipfile、urllib……）全部来自 Python 标准库——没有任何第三方运行时依赖，这对一个要投递“零依赖静态二进制”的发行包来说是一种刻意的架构选择：包装器自身不会引入新的供应链面。

安装与平台构成：一条命令，无需选择变体

README 给出的安装方式只有两种：

pip install codebase-memory-mcp
# or
pipx install codebase-memory-mcp

并强调：“每个平台只有一种构成（one composition per platform）：graph UI 内嵌在所有构建中，因此不需要变体选择。” 这与源码中的常量相互印证——Unix 与 Windows 发行包各有一个精确的“根文件白名单”（_cli.py）：

• Unix（tar.gz）：codebase-memory-mcp、LICENSE、install.sh、THIRD_PARTY_NOTICES.md
• Windows（zip）：codebase-memory-mcp.exe、LICENSE、install.ps1、THIRD_PARTY_NOTICES.md

也就是说，不存在“带 UI / 不带 UI”“标准版 / 便携版”这类多工件组合——下载器只接受这一组精确文件名，多一个、少一个、大小写冲突都会被拒绝。测试 test_release_archives_carry_no_sidecars 专门固化了这一契约：白名单中不允许出现集成侧车文件，任何回归都会使 pip install 拒绝所有归档。

构建侧的供应链约束

值得留意的是，pyproject.toml 把构建后端 hatchling 钉死在 1.28.0，注释说明了原因：python -m build 会在隔离环境中现解析后端，某个开始输出 Metadata-Version 2.5 的 hatchling 发布版本曾被钉住的 twine 6.2.0 拒绝，直接中断过 v0.10.1 的 PyPI 发布——“整条工具链必须钉住，不能只钉一半”。配套的 requirements-publish.txt 进一步把发布步骤用到的 build、twine 及其全部传递依赖（cryptography、requests、rich 等）做成了带 SHA256 哈希的哈希锁定清单，注释明确指出这是为了 OSSF Scorecard 的 pinned-dependencies 项：“任何在运行时解析任意版本的 pip 命令都是供应链缺口，仅钉版本号并不绑定制品字节”。

首次运行流程：从“什么都没有”到“可执行二进制”

入口 main()（_cli.py L1288-L1331）的流程是：

1. 通过 importlib.metadata 读取包版本，缓存未就绪时调用 _download(version)；
2. 就绪判断不是“文件存在”，而是 _runtime_set_ready_locked——在持锁状态下要求二进制是正则文件，并实际执行候选二进制验证（见下）；
3. 以列表形式 argv 转发参数：Unix 上 os.execv 直接替换进程，Windows 上 subprocess.run 并回传退出码。

源码注释特别解释了转发方式的安全性：forwarded 是一个列表而非 shell 字符串，因此每个参数都是离散的 argv 条目——没有 shell 解释、没有注入面，而“转发 sys.argv 本身就是这个 shim 存在的意义”。

平台检测与归档命名

_download（L1159-L1168）按 sys.platform 与 platform.machine() 推导平台：

• 操作系统：仅接受 linux / darwin / win32，其余直接退出；
• 架构：仅接受 arm64/aarch64 归一为 arm64，x86_64/amd64 归一为 amd64；
• 归档名：codebase-memory-mcp-{os}-{arch}{-portable}.{tar.gz|zip}。

其中 Linux 有一个细节（L1163-L1166 的注释）：Linux 附带一个完全静态链接的 -portable 构建；标准 linux 二进制动态链接 glibc 2.38+，在老发行版上会失败。因此 PyPI 路径上的 Linux 用户实际拿到的是 portable 版，且该选择要求与 install.sh、pkg/npm/install.js、src/cli 中的对应逻辑保持同步。

HTTPS 受界下载

_download_https（L89-L134）不使用 urllib 的默认 opener，而是自建一个禁用的重定向处理器，把每一次跳转都暴露给显式校验：

• _validate_url_scheme 在每一跳之前拒绝非 https、无主机名、或带凭据（user:pass@）的 URL——注释说明了动机：urllib 默认 handler 接受 file://、ftp:// 与自定义 scheme，一个恶意重定向可能把下载变成任意本地文件读取；
• 重定向最多 _MAX_REDIRECTS = 5 次，每跳都要重新过 scheme 校验；
• 120 秒网络超时按“每跳单调时钟截止”实现，64KB 分块读取；
• 校验清单 checksums.txt 有 1MiB 的下载字节上限（_MAX_CHECKSUM_MANIFEST_BYTES）。

SHA256 校验

_verify_checksum（L276-L333）从同一版本的 release 下载 checksums.txt，对目标归档逐行匹配：

• 摘要必须是 64 位十六进制；同一归档出现两条不一致的摘要直接以“conflicting checksums”退出；
• 找不到该归档的摘要、或计算结果与期望不符，均以明确的 CHECKSUM MISMATCH（含期望值与实际值）退出；
• 成功则向 stderr 打印 checksum verified.。

安全解包：白名单即全部信任边界

_safe_extract_tar 与 _safe_extract_zip（L199-L273）实现了比“解压”严格得多的语义：

• tar 中任何非普通文件成员（目录、符号链接、硬链接）直接拒绝；zip 成员路径逐段检查，拒绝绝对路径、盘符、..、空段、以点或空格结尾的段，并做 dest 逃逸检查；
• 解包前先用 _validate_archive_names 做“精确根命名空间”比对：归档必须恰好包含白名单里的每个文件、且没有多余成员；Windows zip 额外启用大小写折叠，拒绝大小写冲突（注释：否则“归档顺序”可能决定便携 shim 最终执行哪个二进制）；
• 验证通过后只把运行时文件逐一读出并写为普通文件，不复用平台 zip 路径重写行为。

测试用例把这几条边界固化为回归：test_unix_tar_rejects_hardlink_members 构造含硬链接成员的 tar 期望 SystemExit；test_windows_zip_rejects_symlink_metadata 构造带符号链接外部属性的 zip 成员同样期望被拒。

候选验证与原子发布

解包后，_verify_candidate（L137-L149）会实际执行候选二进制（--version，15 秒超时，stdout/stderr 全部丢弃）——“能哈希通过”不等于“能在本机运行”。随后文件被复制为 . <name>. <pid>.tmp 暂存文件，进入 _publish_runtime_set（L1056-L1157）的发布事务，其要点是：

• 先取发布锁，检查是否有“竞争者已经发布了完整集合”（指纹 = 各文件 SHA256 元组）；有则直接放弃，不删除、不覆盖那个先到的完整赢家；
• 把旧二进制移入备份事务目录 .cbm-runtime-backup-<32位hex>（“先退役可执行文件：直到最后一步 rename 之前，就绪状态都为假”），写入 .retirement-complete 标记；
• os.replace 原子换入新二进制，再次执行验证器；失败则走恢复路径，成功则清理备份；
• 注释直言设计意图：“发布过程中崩溃会留下不完整缓存；就绪检查会拒绝它，下一次调用时修复它。”

缓存目录：版本化、平台惯例、二进制即本体

_cache_dir（L364-L371）遵循各平台惯例：

平台	缓存根目录
Windows	%LOCALAPPDATA%\codebase-memory-mcp
macOS	~/Library/Caches/codebase-memory-mcp
Linux/POSIX	$XDG_CACHE_HOME（默认 ~/.cache）下的 codebase-memory-mcp

其下按版本分子目录（_runtime_dir），二进制就放在版本目录根部：Unix 上为 codebase-memory-mcp，Windows 上为 codebase-memory-mcp.exe。_execution_path 在任何平台都返回缓存二进制本身（L388-L390），测试 test_windows_executes_the_cached_binary 固化了“缓存文件即执行文件”这一不变式——不存在额外 shim 层，升级即替换该文件。

并发与崩溃自愈：带心跳的所有权锁

这是包装器工程含量最高的部分。缓存目录内使用名为 .codebase-memory-mcp-runtime.lock 的发布锁（_cli.py L46-L56），关键参数：

• 等待上限 45 秒（_RUNTIME_LOCK_WAIT_SECONDS），轮询间隔 25ms；
• 租约 300 秒（_RUNTIME_LOCK_LEASE_SECONDS），心跳每 20 秒续期一次；
• 无主（owner 记录不可读）的陈旧锁 30 秒后可被回收。

锁的获取（_acquire_runtime_lock，L713-L770）采用“claim 文件 + os.link 抢占”的无死锁模式：

1. 以 O_CREAT|O_EXCL 创建 .lock.claim-<token>，写入 {pid, token, lease_expires_ms} owner 记录（token 来自 secrets.token_hex(16)）；
2. os.link 到正式锁名；link 失败（FileExistsError）说明有人先抢到，转入回收判定或轮询等待；
3. link 成功后先校验“我持有的描述符与锁名指向同一 inode”，再关闭 claim 描述符、删除 claim 名、重新打开正式名并复核身份与 owner 记录——注释解释了 Windows 细节：该描述符在 Windows 上不授予删除共享，必须先行关闭。

释放（_release_runtime_lock）同样严格：close 描述符 → 重开正式名验证 → rename 到 .lock.released-<token> → 再验证 → 删除；任何“对象被替换”（inode 变化）或“owner 被替换”（pid/token 不符）都抛错并保留锁文件。回收判定（_try_reclaim_runtime_lock）在移动锁之前会二次确认它仍然符合回收条件，若发现已不满足则原路放回，绝不删除一个“身份不是我检查过的那个”的锁。

进程活性探测也分平台处理（_process_is_alive，L521-L534）：POSIX 用 kill(pid, 0) 并把 PermissionError 保守地视为“活着”；Windows 通过 OpenProcess(SYNCHRONIZE) + WaitForSingleObject 探测（L465-L518），且任何 API 失败都保守按“活着”处理——宁可少回收，也不允许误判活着的 owner 已死。测试类 ProcessLivenessTests 专门断言“Windows 路径绝不调用 os.kill”、ERROR_INVALID_PARAMETER 才判定进程不存在。

备份事务则构成一个小型崩溃日志：.retirement-complete 标记区分“退役完成”与“部分发布”，.cleanup-only 标记使删除可重试（L803-L805 的注释）。每次持锁就绪检查都会执行 _reconcile_runtime_backups（L979-L1046）：当前集合已就绪则清理所有备份；只有一个活动备份且无冲突则恢复；多个备份并存则抛出“需要人工恢复”而不是猜。测试把这套行为压成了可验证的场景：

• test_concurrent_publishers_preserve_the_first_complete_winner：两个发布者竞争，断言最终缓存中是第一个完整发布的字节；
• test_killed_publisher_is_reconciled_by_locked_readiness：真实子进程在发布中途被 kill，断言下一次 _runtime_set_ready_locked 能从备份恢复、清理备份目录并留下无锁现场;
• test_failure_never_deletes_a_complete_foreign_winner：注入“不合作的赢家”后失败发布不得删除它。

使用：透传原生 CLI，特殊动词单独治理

README 的使用章节给出的核心命令是：

codebase-memory-mcp install   # configure your coding agents
codebase-memory-mcp --help

包装器对参数透传做了一处“动词治理”（_runtime_mutation_action）：

• install / uninstall：识别为“缓存敏感变更”，不直接 exec，而是走 _run_cache_sensitive_mutation（L1367-L1409）——先取发布锁并启动 20 秒心跳守护线程，再 Popen 原生二进制，期间若锁心跳失败就终止子进程并抛错，保证 install/uninstall 全程独占缓存目录；
• update：拒绝执行，直接以退出码 2 提示——“这份 PyPI 拷贝由 pip 维护，请用 python -m pip install --upgrade codebase-memory-mcp 升级；如需受管的独立安装，运行 codebase-memory-mcp install --yes”（test_update_guidance_uses_pip_and_names_managed_install 固化了这段提示文案）；
• uninstall：若用户未显式给 --dir，_native_args 会自动补上受管安装目录的默认值——POSIX 为 ~/.local/bin，Windows 为 %LOCALAPPDATA%\Programs\codebase-memory-mcp（_default_managed_install_dir）。测试 test_wrapper_uninstall_never_defaults_to_its_cache_binary 锁定了这条安全约束：卸载永远不得默指向缓存二进制本身；
• --help/--version/cli/hook-augment/config 及未知首参：按普通透传处理，直接执行原生二进制。

Windows 上 uninstall 失败时还会追加一段提示，说明该 PyPI 拷贝是便携式的，包维护应走 python -m pip uninstall codebase-memory-mcp（main L1315-L1325）。

支持平台矩阵

README 的平台表完整保留如下：

操作系统	架构
macOS	arm64, amd64
Linux	arm64, amd64
Windows	arm64, amd64

源码侧的对应限制：

• 架构白名单之外（如 i686、riscv64）会以 unsupported architecture 退出（L355-L361），操作系统同理（L344-L352）；
• Linux 上实际投递的是完全静态链接的 -portable 构建，因此不依赖发行版 glibc 版本；macOS/Windows 无此变体；
• 版本目录与缓存路径按平台惯例落在用户级目录，无需 root/管理员权限——这是该发行方式相比系统包管理器的一层实用差异。

小结：一个发行包装器能承载多少工程

回到 pkg/pypi/README.md 的三行核心声明——“首次运行下载、发布前验证、graph UI 内嵌于每个构建”——源码给出的展开是：一个纯标准库 Python 包装器，用 HTTPS-only 受界下载 + 精确校验 + 严格根白名单解包 + 真实执行验证 + 带心跳的所有权锁 + 可重试的备份事务，把“从 PyPI 装一个多平台原生二进制”这件供应链上最脆弱的事，压缩成了用户视角的一条 pip install。若想继续深入，值得按顺序阅读 _cli.py 的下载/锁/发布三段实现与 test_cli.py 中 RuntimeSetTests 的并发与崩溃场景；更完整的功能文档见仓库主 README.md 与 docs/ 目录。