Graph Maintainer

让每一处见解，都有迹可循

Graph Maintainer 是一个以 Datasource 生命周期为边界的、来源可追溯的知识图维护库。核心库负责 Datasource 对账、Snapshot、子图贡献、共享节点、证据和事务一致性；仓库中的 Web、CLI、Worker 与 MCP 只是同一套核心 API 的参考运行适配器。

先理解 Datasource（DS）

Datasource，简称 DS，不是一个普通的“数据源条目”，而是 Graph Maintainer 中一份可独立更新、替换、撤销和追溯的子图贡献。每个 DS 从一个确定的外部来源产生自己的 Snapshot、Node 贡献、Edge 和证据；所有处于生效状态的 DS 子图按规范节点身份合并，组成你最终查询和浏览的全局知识图。

这带来三个重要结果：

• 更新一个 DS，只原子替换这个 DS 的子图，不会重建其他来源。
• 多个 DS 可以共同支撑同一个 Node；同一个概念会合并，而不是简单复制。
• Edge 始终属于一个 DS；撤销某个 DS 时，它的 Edge 会被移除，但仍被其他 DS 支撑的共享 Node 会保留。

从来源配置、发现、建图到更新与删除的完整操作路径，见 Datasource How-to。

核心能力

• 插件化的数据来源发现、验证、缓存和建图。
• Datasource Snapshot、来源证据、Node/Edge 生命周期与共享节点回收。
• 节点 embedding、全文检索与混合检索。
• 可注入 LLM、embedding 与插件实现的 GraphMaintainer API。
• 随仓库提供的 Web UI、SQLite CLI、Worker、HTTP MCP 和 stdio MCP 参考适配器。

Graph Maintainer 不内置面向某个本地模型运行时或个人配置目录的专用协议。默认适配器通过显式环境变量连接 OpenAI-compatible 服务；宿主应用也可以直接向 GraphMaintainer 注入自己的 llm、embeddings 和插件。参见 Library-first API。

项目实跑效果

下面的页面来自 Graph Maintainer 对本仓库自身的实际建模结果。导入同时读取了设计文档与 TypeScript 源码，生成了 Datasource、Graph Importer 等领域概念，以及 DatasourceProcessor、GraphQueryService、TypeRegistry 等代码结构。

知识节点支持全文与语义混合检索，并保留节点类型、来源和 Maintainer 摘要：

代码中的关键数据结构会形成可追溯的节点详情、依赖关系与 Snapshot 证据：

环境要求

• Node.js 22 LTS（最低 Node.js 20）。
• pnpm 11；推荐通过 Node.js 自带的 Corepack 安装。
• macOS、Linux，或 Windows + WSL2。
• 本机可用的 C/C++ 编译工具链。安装依赖时，better-sqlite3、sqlite-vec 等原生模块可能需要编译。

确认环境：

node --version
corepack enable
pnpm --version

如果系统没有 Corepack，也可以运行 npm install -g pnpm@11。

快速启动

git clone [email protected]:kawhicurry/GraphMaintainer.git
cd GraphMaintainer
pnpm install
cp .env.example .env

打开 .env，配置生成模型和 embedding 服务：

LLM_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini
OPENAI_API_MODE=responses

EMBEDDING_API_KEY=your-api-key
EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

初始化 SQLite 数据库：

pnpm db:migrate

开发环境可以用一条命令同时启动 Web、Worker 和 HTTP MCP：

pnpm daemon -- --dev

打开 http://127.0.0.1:3500。HTTP MCP 默认位于 http://127.0.0.1:3600/mcp，健康检查地址为 http://127.0.0.1:3600/health。

也可以在两个终端中分别运行：

# 终端 1：Web 和 HTTP MCP
pnpm dev

# 终端 2：后台任务 Worker
pnpm worker

Worker 是必需进程。Web 会创建发现、建图、Maintainer 和 embedding 任务，但只有 Worker 会执行这些任务。

完成第一次导入

服务启动后：

1. 打开 /datasource-configs。
2. 新建数据源配置，选择文件或 Git 仓库 Source Plugin，并选择 Graph Importer。
3. 填写一个当前进程有读取权限的本地路径。
4. 先执行验证，再执行完整发现。
5. 在 /datasources 查看处理状态，在 /nodes 查看生成的知识图节点。

这里的第 4 步会把发现到的每个来源登记为一个独立 DS。若一个目录配置发现 20 个文件，通常会形成 20 个可独立维护的 DS 子图，而不是一个不可拆分的大图。

模型配置说明

生成模型和 embedding 服务均可替换为兼容 OpenAI API 的服务。请特别注意：

• OPENAI_API_MODE 只能是 responses 或 chat_completions，并且服务端必须支持对应接口。
• EMBEDDING_DIMENSIONS 必须与 embedding 模型实际输出维度一致。
• 如果生成模型和 embedding 共用凭据，可以省略 EMBEDDING_API_KEY；它会回退到 OPENAI_API_KEY。
• 如果二者共用 Base URL，可以省略 EMBEDDING_BASE_URL。
• 不要提交 .env；仓库只提交不含密钥的 .env.example。

核心库本身不要求使用默认模型适配器。作为宿主集成时，可以直接构造符合 LlmProvider 与 EmbeddingProvider 接口的实现并注入实例。默认运行适配器的完整字段见配置参考。

数据与端口

默认本地文件：

| 项目 | 默认值 | 说明 | | --- | --- | --- | | Web | 127.0.0.1:3500 | Next.js UI 和 API | | HTTP MCP | 127.0.0.1:3600/mcp | 随 Web 自动启动 | | SQLite | ./data/graph-maintainer.db | 本地数据库，不提交到 Git | | 内容目录 | ./content | 默认文件来源目录 | | 工作目录 | ./data/workspaces | Datasource 缓存和 Snapshot |

端口、路径、Worker 与 MCP 鉴权均可在 .env 中修改。当前完整业务链路使用 SQLite；PostgreSQL schema 仍处于实验阶段。

如需重置空白本地环境，先停止所有进程，备份并删除 data/，然后重新运行 pnpm db:migrate。该操作会永久删除本地导入结果。

生产方式运行

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm build
pnpm daemon

pnpm daemon 同时运行生产 Web 服务和 Worker。反向代理到公网前，请自行配置 TLS、访问控制和进程守护；将 MCP 监听地址改为非 loopback 时，必须设置至少 16 字符的 MCP_AUTH_TOKEN。

常用命令

| 命令 | 用途 | | --- | --- | | pnpm daemon -- --dev | 同时启动开发 Web 与 Worker | | pnpm dev | 仅启动开发 Web 和 HTTP MCP | | pnpm worker | 仅启动 Worker | | pnpm db:migrate | 创建或升级数据库 schema | | pnpm cli -- db status | 检查数据库完整性和数据量 | | pnpm cli -- plugin list | 查看已注册插件 | | pnpm typecheck | TypeScript 类型检查 | | pnpm test | 运行测试 | | pnpm build | 创建生产构建 |

更多 CLI 示例见 CLI 文档，MCP 接入见 MCP 文档。

常见问题

页面能打开，但任务一直等待

确认 pnpm worker 正在运行，或者直接使用 pnpm daemon -- --dev 同时启动所有进程。

EMBEDDING_API_KEY is required

需要配置 embedding 凭据。设置 EMBEDDING_API_KEY，或确保 OPENAI_API_KEY 已配置且可被 embedding 服务接受。

端口已被占用

确认没有另一个 Graph Maintainer 实例正在运行。Web 开发端口固定为 3500；MCP 端口可通过 .env 中的 MCP_HTTP_PORT 修改。不要同时运行 pnpm dev 和 pnpm mcp:http，它们默认都会监听 MCP 端口。

原生依赖安装失败

升级到 Node.js 22 LTS，清理未完成的 node_modules 后重新运行 pnpm install。如果没有匹配的预编译包，请安装系统编译工具：macOS 使用 Xcode Command Line Tools，Debian/Ubuntu 使用 build-essential 和 Python 3。

更换 embedding 模型后搜索异常

检查 EMBEDDING_DIMENSIONS 是否与新模型一致。模型或维度变化时，已有节点向量需要重新生成。

文档

• 文档中心
• 快速开始
• Datasource How-to
• 配置参考
• 开发与测试
• 插件开发
• Library-first API
• 总体设计

参与贡献

欢迎提交 Issue 和 Pull Request。开始开发前请阅读贡献指南；安全问题请按安全策略私下报告。

许可证

本项目基于 MIT License 开源。