Claude Code Codegraph Harness

用于 Claude Code 与 Codex 的离线本地 codegraph 网关、双客户端适配器、评测运行器与跨平台打包系统。

状态：v0.2.0-rc.1，公共夹具发布候选版。运行时可用，但实测 Codex 图谱输入令牌增加 48–52%，而强制使用 Claude 图谱使有效输入增加 58–112%。在公司进行 Windows/macOS 隔离验证并获得许可前，仍不开放公司源代码。本发布版本不作任何 token 削减声明。

面向业务用户及管理员、用于日文的说明，请从 このハーネスの仕組み 开始阅读。生成的每个离线 ZIP 包中，也包含相同字节内容的 HOW-IT-WORKS-JA.md。

已实现功能

• 公司专属的 Go stdio 网关，提供五个有界、只读工具；

• 该网关背后的 Codebase-Memory v0.10.8 原生二进制支持；

• 明确的管理员索引构建、不可变世代、原子 current 指针、绑定仓库的状态，以及逐查询新鲜度检查；

• Claude Code Plugin/Rule 和一个 Codex 用户 Skill，共用同一套策略路由；

• 针对 arm64 和 x86_64 运行时包的 macOS 与 Windows 安装程序；

• 确定性的、带校验和的纯适配器及四平台内部 ZIP；

• 一个公共装置评测运行器，可记录令牌用量、延迟、有界 oracle 结果与工具名，同时丢弃提示与模型输出。

网关只暴露：

• codegraph_status

• codegraph_search

• codegraph_neighbors

• codegraph_impact

• codegraph_architecture

索引、变更、任意图谱查询、源码提取、URL 以及上游 MCP 工具，均不可交给模型调用。

Related MCP server: codebase-rag

运行时架构

Claude Code Plugin + Rule ----\
                               > registered local stdio gateway
Codex user Skill -------------/              |
                                              v
                                  pinned Codebase-Memory native binary
                                              |
                                              v
                              private repository-bound graph generations

administrator command -> gateway index build -> validate -> atomic activation

Claude Code 和 Codex 共享同一个网关、后端、索引、新鲜度模型与五工具契约。Plugin 与 Skill 仅包含导航性路由指示，从不直接启动上游后端。

当前端技术选型

Graphify v0.9.48 已被排除在公司代码之外，因为其固定上游 MCP 内含 GitHub 关联的 Pull Request 工具与外部大模型路径。Codebase-Memory v0.10.8 是有条件的原生后端，因为其 production 原生路径未观察到外部网络依赖，可以关闭 UI/监视/自动索引，并覆盖四个目标 OS/CPU 组合；而其 npm、PyPI、Go 和升级层的包装器都被禁止，因为它们会从 GitHub 下载代码。

这些受控网关与后端曾在禁止外部网络访问的一次性沙箱中，用公共 fixture 进行了整体验证。它生成了 759 个节点和 1,760 条边，跳过、未索引或部分索引的文件数为 0；搜索、影响、分析、架构、schema 校验以及陈旧/根拒绝均通过。

重复的 Codex 对照组 并未 体现出节约：

Claude Code 也成功使用了网关，但同样 并未 显示节约：

Claude 实验在每次运行中调用微服务或令牌下，此时并不支持路书，因此自动工具选择尚未确立；其他细节可看 [Claude Code 评估](docs/ev证据。因此，该图谱在性质上是可选的、显式路径导航能力，不是总成本优化器。可另见 Codex 评估。

无代码外泄边界

端点安装器不包含下载器，施加任何包管理器。网关只会在合成的、私有 home 和极简环境中，启动哈希固定的本地后端与 Git 可执行程序。状态数据完全来自源仓库之外。工具结果只含有界符号索引，不返回源码正文。

这些控制不是企业级沙箱。stdio 并不会阻止子进程连接 DNS 或 HTTPS。运行时必须在安装、标记和每次启动时使用显式绝对路径 --allowed-root/-AllowedRoot 并附加该 release-candidate 网关载荷的生产版本；一条 label、一个不同 checkout、一个被忽略的额外文件或某个不同 repository 都会无法允许。本版本仍然是 public-fixture-only；在用于公司源码前，必须完成 Windows/macOS 企业协议、Endpoint/AppSec 等区域的跨系统验证。

公开纯适配器 ZIP

公开发布包刻意保持精简，只含适配器、安装器、契约与文档：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
codegraph-harness bundle \
  --version 0.2.0-rc.1 \
  --profile packaging/profiles/public.json \
  --output dist/codegraph-harness-0.2.0-rc.1.zip

安装本 ZIP 不会启用任何图谱运行时。

内部运行时 ZIP

内部工件流水线为全部四个目标构建 gateway 的主权平台包，并从经过批准的镜像中提取四个 Codebase-Memory 可执行文包。随后，在 runtime-matrix.json.in 中由包的网关 metadata token，运行构建流程：

codegraph-harness bundle \
  --version COMPANY_RELEASE_VERSION \
  --profile /approved/input/runtime-matrix.json \
  --vendor-dir /approved/input/native \
  --output /approved/output/codegraph-harness-COMPANY_RELEASE_VERSION.zip

构建器只读取显式列举的常规文件，验证每个 SHA-256，拒绝目录遍历/特定符号备注，并生成确定性 ZIP、运行时 manifest 和 SHA256SUMS。当前的测试四平台 ZIP 压缩后 172 MB，解压后 1.1 GB；端点端只需要安装与其匹配的 gateway/后端对即可。

端点命令

./install.sh --dry-run
./install.sh

powershell.exe -NoProfile -File .\install.ps1 -DryRun
powershell.exe -NoProfile -File .\install.ps1

对企业普通端点 GXP5

对于运行时 ZIP，管理员必须将端点限定为与该 gateway 二进制文件编译完全一致的那个公共 fixture checkout：

./install.sh --dry-run --allowed-root /absolute/approved/public-fixtures
./install.sh --allowed-root /absolute/approved/public-fixtures

powershell.exe -NoProfile -File .\install.ps1 -DryRun -AllowedRoot C:\Approved\PublicFixtures
powershell.exe -NoProfile -File .\install.ps1 -AllowedRoot C:\Approved\PublicFixtures

在构建时，打包验证每个 gateway 内嵌内容的允许清单与其 Runtime 配置一致；在端点安装时，对压出的每个文件校验 SHA256SUMS，选择本地 OS/CPU 组合，安装 Claude Rule 与 Codex Skill，而不覆盖未声明归属的文件，需要时可安装 Claude Code 的 Marketplace 内 Plugin，将同一 gateway 同时注册到两边的客户端并写入校验和对账单。中间任一步失败都会回滚。

卸载默认保留减除后的图谱状态，以避免静默的数据丢失。而当策略要求彻底删除时，需要引入 --purge-graph-state 或 -PurgeGraphState。

在解落地之前，务必通过独立于 ZIP 的 signature 或另行获取的 SHA-256 验签。内含 SHA256SUMS 只能防部分文件被替换，它本身不是整套替换掉 ZIP 后的信任根。

评测运行器

仓库内检验的运行器仅接受公共固定汇聚；它会先拒绝 company-source，并返回条件 JSON 与环境变量之后才会启动工具。已启用 Claude Code 与 Codex 基线/条件，可测试。标准输出将被哈希校验而不是持久存储，除非显式请求读取。

参见 Evaluation protocol。条件文件实质是可执行的配置，应将其视为可信代码。

验证

当前本地验证包括：85 个已有 Python 测试、Black、mypy strict、Go 单元/race、四种目标 Go cross-build、Claude Plugin strict 校验，以及实际 macOS arm64 安装→索引→MCP 查询→卸载循环。Windows 二进制为交叉编译，PowerShell 流程可运行于 GitHub Actions；真正的 Windows 原生 Codebase-Memory 与 EDR 验证仍等达预期。

延伸阅读

• 架构

• 内部 harness 集成

• 离线分发

• 亚太大数据模型

• 后端选择 ADR

• 上游-wrapper ADR

• 双客户端运行时 ADR

• 备选 egress 审计

• Runtime 证据

许可证

仓库本文件为 Apache-2.0 授权。Codebase-Memory 保留 MIT 许可证，仅可在内部审查之后随其原生 notices 重新发布。