AsiaOstrich/EngramGraph

# EngramGraph [](https://www.npmjs.com/package/engramgraph) [](./LICENSE) [](https://nodejs.org) **许可证：** MIT · **运行环境：** Node.js ≥ 22 · **图数据库：** [Kuzu](https://kuzudb.com/)（嵌入式，Cypher）· **无需 LLM**（确定性的） EngramGraph 是一个通用引擎。其默认设置（“单一代码库 + 通用 markdown + git 信号”）开箱即用，适用于任何项目；通过可插拔的 adapter，可以提供特定于项目的行为。 ## 为什么选择图？ 向量搜索（“查找相似的 memory”）和图遍历（“查找结构上相关的节点”）是互补的。EngramGraph 补全了图的那一半： ## 安装 ``` npm install -g engramgraph ``` 这会将 `egr` CLI 添加到您的 `PATH` 中，以便下方的快速入门命令可以在任意目录下运行。或者，在不进行全局安装的情况下运行 CLI： ``` npx engramgraph index ./src ``` ### 平台支持矩阵 EngramGraph 依赖于 [`ryugraph`](https://github.com/predictable-labs/ryugraph) 来 实现其嵌入式图数据库，该数据库为每个平台提供了预构建的原生二进制文件。截至 `ryugraph@25.9.1`，已验证的支持情况如下： | 平台 | 状态 | 备注 | |---|---|---| | macOS ARM64 (Apple Silicon) | ✅ 正常 | 已通过[跨平台兼容性检查](.github/workflows/release-compat-check.yml)（`macos-latest`）验证 | | macOS x64 (Intel) | ⚠️ 未经 CI 验证（已知限制，见下文） | 无已知问题 —— `ryujs-darwin-x64.node` 是一个独立且合法构建的二进制文件（与 Linux ARM64 情况不同），但未被自动化发布门禁测试 | | Linux x64, glibc ≥ 2.38 (Ubuntu 24.04+, Debian 13+) | ✅ 正常 | 已通过 CI glibc 兼容性矩阵（`node:24-trixie`，glibc 2.41）验证 | | Linux x64, glibc < 2.38 (Ubuntu 22.04 LTS, Debian 12) | ❌ 损坏 | 上游 `ryugraph` 二进制文件需要比这些仍然常见的 LTS 发行版所提供的更新的 glibc。已通过 CI glibc 兼容性矩阵（`node:24`，glibc 2.36）验证 | | Linux ARM64 (任意 glibc) | ❌ 损坏 | 上游在 arm64 文件名下提供了 x86-64 的二进制文件 —— 在 [predictable-labs/ryugraph#48](https://github.com/predictable-labs/ryugraph/issues/48) 中追踪。已通过 CI（`ubuntu-24.04-arm`）验证 | | Windows x64 | ✅ 正常 | 已通过 CI（`windows-latest`）验证 | 这会影响 **Apple Silicon Mac 上的 Docker Desktop**（默认使用 `linux/arm64`）以及 **AWS Graviton / 其他 ARM64 Linux 主机** —— 如果 `egr` 在那里运行失败，很可能是 [#48](https://github.com/predictable-labs/ryugraph/issues/48) 导致的，而不是您的 设置有问题。在受影响的 Docker 主机上强制使用 `--platform linux/amd64` 可以作为一种权宜之计（代价是在 ARM64 硬件上以模拟方式运行），直到上游修复此问题。 另请注意：npm ≥ 11 默认会在批准提示后将原生安装脚本（包括 `ryugraph` 的脚本）拦截。如果 `npm install` 打印出 `npm warn allow-scripts`，请运行 `npm approve-scripts --all` 并重新安装 —— 否则原生二进制文件永远不会被复制到位。 **为什么 macOS Intel 不在自动化发布门禁中。** 这不是疏忽 —— 而是经过深思熟虑的决定。两个独立的事实指向了同一个方向： - **GitHub 自己的 Intel Mac（`macos-13`）托管运行器目前存在严重的队列容量限制。** 2026 年 7 月 10 日的一次实际测试运行在 `queued` 状态下停留了约 50 分钟，且始终未开始。GitHub Actions 的 `timeout-minutes` 无法限制这一点 —— 它只在作业实际开始执行时才开始倒计时，而不是在排队时 —— 因此没有可靠的方法来限制发布在这个运行器上卡住等待的时间。 - **Apple 自身的支持生命周期正在走向终结。** macOS 26 "Tahoe" 是最后一个支持 Intel Mac 的主要 版本；macOS 27 "Golden Gate"（预计 2026 年 9 月发布）将彻底放弃 Intel，macOS 26 上仅会继续提供仅针对安全性的更新，直至大约 2029 年。无论在 Apple 还是 GitHub 方面，Intel Mac 都是一个正在落幕的平台。 鉴于此，为了一个正在逐渐被淘汰的平台，去阻塞每次发布在一个可能永远无法使用的 runner 上 —— 这毫无意义。相反，`release-compat-check.yml` 中的 [`macos-x64-intel-manual`](.github/workflows/release-compat-check.yml) 将 Intel Mac 验证作为一个**尽力而为、非阻塞**的作业运行：可以在任何人想要检查时通过 `workflow_dispatch` 手动触发，使用 `continue-on-error: true` 因此它永远不会导致发布失败，并且被排除在 `release: published` 触发器之外，这样真正的发布永远不会因为它而处于等待状态。如果您特别需要确认是否支持 Intel Mac，请手动触发该作业并检查其结果 —— 但发布流程本身并不依赖它。 ### 故障排除：令人困惑的原生二进制文件错误 Linux 上的原生二进制文件加载失败是通过 Node 的 `dlopen` 抛出的，其错误文本并不总能描述真正的原因： | 您看到的错误 | 通常的含义 | |---|---| | `ryujs.node: cannot open shared object file: No such file or directory`（根据 `ls` 显示文件*确实*存在） | CPU 架构错误 —— 该路径下的二进制文件适用于与您当前运行的平台/架构不同的环境 | | `.../libc.so.6: version 'GLIBC_2.38' not found` | 您发行版的 glibc 版本低于预构建二进制文件要求的版本（见上方矩阵） | | `npm warn allow-scripts ... not yet covered by allowScripts` | npm ≥ 11 阻止了复制原生二进制文件的安装脚本 —— 运行 `npm approve-scripts --all` 然后重新安装/重新构建 | 如果您遇到了此处未涵盖的问题，在假定这是 EngramGraph 的 Bug 之前，请检查 [predictable-labs/ryugraph 的 issues](https://github.com/predictable-labs/ryugraph/issues) —— 大多数原生加载失败都源于 `ryugraph` 依赖项，而不是本包。 ### 依赖项漏洞警告（`npm audit`，已弃用的包） 普通的 `npm install` —— 无论是全局安装、`npx` 还是作为项目依赖 —— 目前都会打印出类似这样的警告： ``` npm warn deprecated npmlog@6.0.2: This package is no longer supported. npm warn deprecated are-we-there-yet@3.0.1: This package is no longer supported. npm warn deprecated gauge@4.0.4: This package is no longer supported. npm warn deprecated tar@6.2.1: ...widely publicized security vulnerabilities... 4 high severity vulnerabilities ``` 所有这四个警告都可以追溯到一个链条：`ryugraph`（本包的嵌入式图数据库 引擎）固定使用 `cmake-js@^7.3.0`，它依赖于 `tar@^6.2.0`（存在几个高危 路径遍历 CVE，已在 `tar@7.5.11`+ 中修复）以及现已弃用的 `npmlog`/`gauge`/ `are-we-there-yet` 技术栈。`cmake-js@8.0.0` 已经移除了 `npmlog` 并将 `tar` 升级到了 `^7.5.6` —— 上游已存在修复方案，只是 `ryugraph` 尚未采用。在 [predictable-labs/ryugraph#49](https://github.com/predictable-labs/ryugraph/issues/49) 中追踪。 **实际暴露的风险比警告数量所暗示的范围要窄。** `ryugraph` 自身的 `install.js` 仅在您的平台不存在预构建的原生二进制文件时才会调用 `cmake-js`（进而是 `tar`） —— 请参阅上方的平台支持矩阵。在矩阵中标记为 `✅ Works` 的每个平台上，预构建的二进制文件会被直接复制，而 `cmake-js`/`tar` 会被下载到 `node_modules` 中但永远不会被执行。声明的漏洞是真实的 （无论如何都会在 `npm audit`/SBOM 工具中显示），但实际的利用窗口实际上仅限于从源码构建的路径（不受支持的平台，或显式设置了 `NPM_CONFIG_BUILD_FROM_SOURCE`）。 **如果您在自己的项目中将 `engramgraph` 作为依赖项使用**（非全局 安装），您现在可以自行清除它 —— 将相同的 override 添加到*您自己的* `package.json` 中： ``` "overrides": { "cmake-js": "^8.0.0" } ``` （此处显示的仅为 npm 语法；pnpm/Yarn 具有等效的 `pnpm.overrides` / `resolutions` 字段。）这之所以有效，是因为 npm 的 `overrides` 字段仅在运行 `npm install` 的项目的根目录下生效 —— 它**不会**从依赖项自身的 `package.json` 传播到您的项目中，这正是为什么 `engramgraph` 自己的 `overrides` 条目（在早期的修复中添加）对您没有帮助的原因：它仅清除此代码库自身源码检出中的 `npm audit`，而对于任何安装已发布包的用户无效。对于全局安装或 `npx engramgraph`，没有可用于附加 override 的项目根目录，因此该路径目前没有任何可用的权宜之计 —— 它取决于关联的上游 issue 是否落地。 ## 快速入门 ``` # 1. 将 repo 索引到 graph 中（代码 + 可选文档） egr index ./src --docs # 2. "如果我更改了这个函数，会破坏什么？" egr callers myFunction --depth 2 # 3. "这个 spec 背后有哪些决策？" egr impact SPEC-001 ``` 图数据库位于 `ENGRAM_DB`（默认为 `./.engram/graph.db`）。 完整的命令参考：**[docs/CLI.md](./docs/CLI.md)**。 ### 嵌入式使用（进程内，零 HTTP） ``` import { EmbeddedClient } from "engramgraph"; const client = new EmbeddedClient(); // SingleRepoIsolation by default await client.init(); // opens graph.db + ensures schema const rows = await client.query("MATCH (f:Function) RETURN f.name AS name"); await client.close(); ``` ### REST 使用方式 ``` import { createServer, GraphConnection } from "engramgraph"; const conn = GraphConnection.open("./.engram/graph.db"); const app = createServer({ connection: conn }); // Hono app; routes under /graph/* // GET /health → { status: "ok" } ``` 或者只需执行 `egr serve --port 3000`。API 参考：**[docs/API.md](./docs/API.md)**。 ## 三种模式 | 模式 | 入口 | 用例 | |------|-------|----------| | **Embedded** | `EmbeddedClient` | 同进程，零 HTTP 开销（例如同进程集成） | | **REST** | `createServer()` (Hono) / `egr serve` | 独立的图服务；路由位于 `/graph/*` 下 | | **MCP** | `egr-mcp` (stdio) / `egr mcp` | 为编程助手（Claude Code、Codex、Cursor 等）提供即插即用支持 | ## MCP —— 从编程助手中使用 EngramGraph EngramGraph 内置了一个 MCP 服务器 (stdio)，公开了 8 个工具 —— `index_code`、 `index_docs`、`call_chain`、`impact_analysis`、`ingest_feedback`、`implementers`、 `implemented_specs`、`related` —— 因此任何支持 MCP 的助手都可以将其用作 代码 + 知识图谱。零 LLM，确定性，**无需 Docker**。 ``` # Claude Code，来自已安装的 package： claude mcp add egr -- npx egr-mcp ``` 完整设置（Claude Code / Codex / Cursor / Windsurf），全部 8 个工具，以及 示例流程：**[docs/MCP.md](./docs/MCP.md)**。 ## Core 与 Adapter 的边界 | 层级 | 内容 | 外部可用性 | |-------|----------|--------------------| | **Generic Core** | CodeGraph (tree-sitter → graph)、SAGE 演进、Kuzu 抽象、REST/MCP/Embedded 模式、node-sdk | 零特定于项目的依赖 | | **Pluggable Adapters (接口)** | (1) 知识源 (2) 隔离模型 (3) SAGE 信号源 | Core 内置接口 + 通用默认实现 | ### 三个 adapter 1. **知识源** —— `KnowledgeSource → { nodes, edges }`。 默认：`MarkdownKnowledgeSource` 将任何 front-matter markdown （`id` / `title` / `status` + `[[ref]]` 链接）解析为通用的 `Doc` 节点。 2. **隔离模型** —— `IsolationModel.dbPath(ctx) → string`。 默认：`SingleRepoIsolation`（一个 `graph.db`，无组织概念）。 可选：`OrgProjectIsolation`（`org-{orgId}/project-{projectId}/graph.db`）。 3. **SAGE 信号源** —— `SignalSource → FeedbackEvent[]`。 默认：`GitHistorySignalSource`、`TestExitCodeSignalSource`。 ## 图 schema 6 个节点表 —— `Function`、`Class`、`Module`、`Spec`、`Decision`、`Doc`。 8 个关系表 —— `CALLS`、`IMPORTS`、`DEFINES`、`IMPLEMENTS`、`IMPACTS`、 `SUPERSEDES`、`RELATES`、`REFERENCES`。有关完整的 DDL 以及驱动知识摄取的 front-matter schema，请参阅 **[docs/API.md](./docs/API.md)**。 状态 - [x] **阶段 1** —— 脚手架（MIT、Node 22、ESM+CJS、tsup、vitest），Kuzu 抽象 + 幂等 schema（6 个 NODE / 7 个 REL 表），三个 adapter 接口 + 通用默认实现，Hono `GET /health`，`EmbeddedClient` - [x] **阶段 2** —— CodeGraph：tree-sitter 提取器/索引器，跨文件 `CALLS` 解析，scope 限定的函数 id - [x] **阶段 3** —— KnowledgeGraph：front-matter markdown → `Spec` / `Decision` + `IMPACTS` / `SUPERSEDES` 边 - [x] **阶段 4** —— SAGE 演进层：置信度反馈（`STEP` 0.25， 下限 0.1），`topByConfidence`，`rankedImpact` - [x] **阶段 5** —— REST 路由（`/graph/call-chain`、`/graph/impact-analysis`、 `/graph/ingest`），MCP 服务器（5 个工具），独立 `egr` CLI ## 贡献 有关开发设置、构建/测试/健康检查循环，以及 kuzu + tree-sitter 的清理注意事项，请参阅 **[CONTRIBUTING.md](./CONTRIBUTING.md)**。变更记录在 **[CHANGELOG.md](./CHANGELOG.md)** 中追踪。 ## 许可证 MIT —— 详见 [LICENSE](./LICENSE)。

标签：GNU通用公共许可证, MITM代理, Node.js, SOC Prime, Tree-sitter, 代码分析, 凭证管理, 开发工具, 自动化攻击