gitnodes

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="public/brand/gitnodes-wordmark-dark.png"> <img alt="GitNodes" src="public/brand/gitnodes-wordmark-light.png" width="460"> </picture> </p> <p align="center"> <strong>将 GitHub 仓库的 Markdown 笔记转化为知识图谱，您可以与 AI 代理一起探索、搜索和编辑。</strong> </p> <p align="center"> <a href="https://github.com/AndreaBozzo/gitnodes/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/AndreaBozzo/gitnodes/ci.yml?branch=main&label=CI&style=flat-square"></a> <a href="https://github.com/AndreaBozzo/gitnodes/releases/latest"><img alt="最新版本" src="https://img.shields.io/github/v/release/AndreaBozzo/gitnodes?style=flat-square&color=blue"></a> <a href="LICENSE"><img alt="许可证：AGPL-3.0 / Apache-2.0" src="https://img.shields.io/badge/license-AGPL--3.0%20%2F%20Apache--2.0-blue?style=flat-square"></a> <img alt="Rust" src="https://img.shields.io/badge/rust-stable-CE412B?style=flat-square&logo=rust&logoColor=white"> <img alt="使用 Leptos 构建" src="https://img.shields.io/badge/built%20with-Leptos%200.8-EF3939?style=flat-square"> </p> GitNodes 指向一个 GitHub 仓库的 Markdown 文件，并使其可导航：一个强制有向图，展示您的笔记如何相互链接，一个类似维基的阅读器，以及一个应用内编辑器，可以直接提交更改到 GitHub。您可以在一个 `.gitnodes.yml` 文件中声明您自己的笔记类型和关系，GitNodes 为您构建图谱、类型化链接和全文搜索索引。 您的笔记保留在 Git 中 - 没有单独的数据库需要迁移，也没有任何内容会锁定您。指向 MCP 服务器中的同一个仓库，并让编码代理（Claude Code、Cursor、Codex 等）搜索和遍历图谱，而不是盲目地 grep，然后像普通的可审查提交一样写回更改。 - **浏览** - 探索您的笔记及其链接的图谱，带有排名全文搜索。 - **编辑** - 在应用内创建、链接和重命名笔记；每个更改都会作为直接提交或拉取请求落地，遵循您的 GitHub 权限。 - **代理原生** - 只读 MCP 服务器让代理遍历您的知识图谱；它们通过 Git 编写，不会在您不知情的情况下修改。 - **Git 原生** - Git 是单一的事实来源。本地索引只是可重建的投影：删除它，它将仅从 `git clone` 重建。 <p align="center"> <img alt="GitNodes 将知识库渲染为强制有向图" src="public/screenshots/graph.png" width="860"> </p> <p align="center"> <a href="https://gitnodes-demo-production.up.railway.app" rel="external">▶ 尝试在线演示</a> </p> <p align="center"> <em>上述大脑包含在 <a href="examples/demo-brain"><code>examples/demo-brain</code></a> 中 - 运行 <code>gitnodes preview examples/demo-brain</code> 以自行探索。</em> </p> ## 早期介绍 GitNodes 在其前身工作名称 **Brain UI** 下于 2026 年 6 月 3 日在 Talent Garden Cosenza 上公开演示。活动记录可在 [LinkedIn](https://www.linkedin.com/events/7467916975424606209/) 上找到。 ## 快速开始 > **预发布：** 以下安装命令将在 **GitNodes 0.1.0** 于 **2026 年 7 月 1 日** 发布时生效。在此之前，[从源代码构建](#build-from-source)。 ### 安装 **macOS / Linux** - 下载、审查、运行： ```bash curl -fSLo install-gitnodes.sh https://raw.githubusercontent.com/AndreaBozzo/gitnodes/main/scripts/install.sh less install-gitnodes.sh # 审查后再运行 sh install-gitnodes.sh ``` **Windows (PowerShell)** - 下载、审查、运行： ```powershell Invoke-WebRequest https://raw.githubusercontent.com/AndreaBozzo/gitnodes/main/scripts/install.ps1 -OutFile install-gitnodes.ps1 Get-Content .\install-gitnodes.ps1 # 审查后再运行 & .\install-gitnodes.ps1 ``` 两者都将一个单独的 `gitnodes` 二进制文件放在您的 `PATH` 上 - 无需 Rust 工具链，无需编译。如果您愿意自己获取？从 [版本](https://github.com/AndreaBozzo/gitnodes/releases/latest) 中获取存档，并将 `gitnodes`（或 `gitnodes.exe`）放在 `PATH` 上。 > Homebrew 和 WinGet 软件包将在 0.1.0 版本发布后不久发布。 ### 首次运行 ```bash gitnodes init my-brain # 启动笔记 + .gitnodes.yml + AGENTS.md cd my-brain gitnodes preview # 打开只读图谱；无需 GitHub 或登录 ``` 同一个工作树立即对编码代理可用。配置代理启动此 stdio 命令，而不是手动运行： ```bash gitnodes mcp . # 只读 stdio MCP 服务器 ``` 当您想要协作编辑和拉取请求工作流程时，请发布： ```bash git add . && git commit -m "初始化 GitNodes 知识库" gh repo create my-brain --private --source=. --remote=origin --push gitnodes doctor # 验证笔记、Git 状态、远程和 gh 身份验证 gitnodes serve # 发现仓库，重用 `gh 身份验证` ``` 如果需要，在上述命令之前运行 `gh auth login`。GitNodes 读取存储库和分支来自本地 Git 检出，并使用 GitHub CLI 存储的凭证；它不会将该令牌复制到 `.env` 或另一个文件中。 `GITHUB_PAT` 仍然作为显式单用户备用方案提供。 `gitnodes preview` 将其 SQLite 投影和会话保留在内存中，从不将运行时状态写入知识目录。生成的 `AGENTS.md` 教导编码代理（Claude Code、Codex、Cursor 等） 您的脑图的约定，以便它们可以正确地添加和链接笔记。GitNodes 适用于人类和代理。 > 此每个脑图的 `AGENTS.md` 根据您的脑图的 `.gitnodes.yml` 生成，并描述了 > 该知识库的分类法。它与根目录下的 `AGENTS.md` 不同， > 该文件指导为 GitNodes 本身工作的贡献者。 源边界很重要：`preview` 和 MCP 读取本地工作树， 包括未提交的文件；`serve` 和部署读取推送的 GitHub 分支。参见 [端到端入门 指南](docs/guides/GETTING_STARTED.md) 在切换模式之前。 ## 从源代码构建 您更喜欢自己编译，还是在没有预编译二进制文件的平台上？ ```bash rustup target add wasm32-unknown-unknown cargo install cargo-leptos --locked --version 0.3.6 npm ci npm run build:css cargo leptos build --release cargo build --release -p gitnodes-app --bin gitnodes-app \ --no-default-features --features embed-assets ``` 将 `target/release/gitnodes-app`（或 `.exe`）放在 `PATH` 上作为 `gitnodes`。 ## 文档 - [入门：本地预览到 GitHub 支持的使用](docs/guides/GETTING_STARTED.md) - [配置参考](docs/guides/CONFIGURATION.md) - [部署指南](docs/guides/DEPLOYMENT.md) - [完整的特性清单和限制](docs/FEATURES.md) - [操作员笔记和恢复](docs/OPERATOR_NOTES.md) - [路线图](docs/ROADMAP.md) ## AI 代理访问 GitNodes 包括一个只读本地 MCP 服务器（`gitnodes mcp [dir]`，stdio）。 它在每次请求之前重新索引工作树，通过与 web UI 相同的 SQLite 投影和 FTS5 搜索路径，因此未提交的笔记立即可见。 无需 PAT、GitHub 登录、推送或运行 Web 服务器。 它公开了五个工具： - **`search_brain`** - 全文搜索，类似于 UI（类型/标签/路径过滤器）。 - **`list_nodes`** - 按类型、标签或目录筛选笔记。 - **`read_node`** - 一个笔记的投影元数据及其 Markdown 正文。 - **`node_links`** - 步行一个笔记的传入和传出图谱边（正文链接， 前面链接，共享标签），因此代理可以遍历图谱而不是 grep。 - **`validate_brain`** - 报告格式错误的 frontmatter，分类法不匹配， 无效标签和未解析的链接，而不更改工作树。 ### 将其连接到您的代理 启动命令对于每个客户端都是相同的 - `gitnodes mcp <path-to-your-brain>`。 唯一的区别是 *config 在哪里*，并且在发布版本中发生变化，因此请使用 存在的一行 CLI 命令，否则请插入标准的 JSON。 在以下示例中使用 您的脑图检出的绝对路径。 **CLI 代理** - 每个命令： ```bash # Claude Code（添加 --scope project 以在仓库中编写一个可提交的 .mcp.json） claude mcp add gitnodes -- gitnodes mcp /absolute/path/to/my-brain # Codex CLI（或编辑 ~/.codex/config.toml 在 [mcp_servers.gitnodes] 下） codex mcp add gitnodes -- gitnodes mcp /absolute/path/to/my-brain ``` **JSON 配置编辑器** - Cursor（`.cursor/mcp.json`），Antigravity （`~/.gemini/config/mcp_config.json`，或 IDE 的 *Manage MCP Servers → View raw config*）， Cline，Windsurf，Claude Desktop，Continue。添加标准的 `mcpServers` 条目；参见每个 客户端的 MCP 文档以获取确切的文件： ```json { "mcpServers": { "gitnodes": { "command": "gitnodes", "args": ["mcp", "/absolute/path/to/my-brain"] } } } ``` ### 60 秒测试 配置服务器后，请您的代理执行一些强制图谱跳转的操作， 例如： > 使用 gitnodes 工具查找有关 *knowledge graphs* 的笔记，然后显示 > 顶级结果链接到什么并总结它。 一个正常运行的设置将调用 `search_brain`，然后在顶部命中路径上调用 `node_links`， 然后调用 `read_node` 以提取完整笔记 - 发现您从未 必须描述的结构。 ### 让代理维护大脑 MCP 服务器**出于设计考虑**是只读的：代理通过它进行发现，但它们 通过 Git 进行编写，这始终是唯一的事实来源。创作循环： 1. 代理直接在检出中编辑 Markdown 文件。生成的 `AGENTS.md` （从 `.gitnodes.yml` 生成）教导它节点类型，前面规则和链接约定， 因此其编辑落地在分类法上。 2. 提交并推送，或打开拉取请求 - 每个更改都是一个普通的， 可审查的提交。 3. `gitnodes serve`（或部署的应用）从 Git 重新构建投影； 新笔记出现在图谱中和代理的工具中。 因为 Git 是接口，所以不需要特殊的写入 API，也不会有任何内容 在您不知情的情况下编辑您的知识库。 ## 技术栈 - **Rust / Leptos 0.8** - SSR + WASM 水合（`cargo leptos`） - **Axum 0.8** - HTTP 服务器，会话中间件，身份验证路由 - **tower-sessions 0.14** + `tower-sessions-sqlx-store 0.15` - SQLite 上的持久会话 - **reqwest 0.12** - GitHub REST API 客户端（无 octocrab） - **pulldown-cmark** - Markdown → HTML，在 SSR 和客户端（实时编辑预览）之间共享 - **Tailwind CSS 3 + `@tailwindcss/typography`** - 样式，通过 Node 工具链构建 - **SQLite** - 会话，审计日志和目标范围投影（`nodes`，`edges`，`files`，`backlinks`，`work_items`，`work_item_bindings`）；内容源仍然存在于 GitHub ## 工作空间布局 ``` crates/ gitnodes-domain/ # 纯领域类型：BrainConfig，NodeTypeSpec，WorkItem，GithubClient gitnodes-graph/ # 图构建 + 强制有向布局（无 I/O） gitnodes-storage/ # GitHub API 调用：树遍历，文件 CRUD，资产上传，原子 Git 数据提交 gitnodes-auth/ # GitHub OAuth 令牌交换 + 可选组织成员资格检查 gitnodes-app/ # Leptos 应用 + Axum 入口点（SSR 二进制 + WASM 包） src/ main.rs # Axum 入口点，会话存储，身份验证路由 api.rs # 服务器函数：图/文件/工作项读取，写入，重建 mcp.rs # 只读本地代理工具通过 stdio MCP markdown.rs # pulldown-cmark 包装器 + 前面拆分器 server/assets.rs # 身份验证的私人仓库图像代理 server/projection/ # SQLite 投影物化 + 读取模型 server/health.rs # /healthz 和 /readyz 运行时探测 server/pending_sync_job.rs # 提供商同步出口的后台重试循环 server/webhook.rs # GitHub webhook 入口点（推送 + 项目同步） server/sse.rs # 每个目标的 SSE 事件总线 + 流端点 server/installation_token.rs # GitHub 应用 JWT → 安装令牌，缓存 + 刷新 knowledge/ page.rs # /knowledge 路由组合 graph_canvas.rs # SVG 图视图 filter_panel.rs # 标签 + 类型过滤器（动态来自配置） editor/ # 创建/更新表单分为专注的子模块 detail_bar.rs # 底部条：悬停/选择摘要 detail_panel.rs # 右侧滑出：渲染 Markdown + 工作项卡 orphan_banner.rs # 琥珀色警告未知节点类型 config_loader.rs # .gitnodes.yml 的 30 秒 TTL 缓存 draft.rs # localStorage 自动保存（schema v2） docs/ README.md FEATURES.md guides/ GETTING_STARTED.md CONFIGURATION.md DEPLOYMENT.md OPERATOR_NOTES.md ROADMAP.md ``` ## 配置 节点类型在目标仓库的根目录中声明在 `.gitnodes.yml` 中。 二进制文件提供了一个内置的默认等效于七个启动类型 （概念，adr，会议，事后总结，项目，运行手册，标签），因此没有 该文件的仓库保持不变。创建仓库之前重命名存储库仍然可以从 遗留的 `.brain-config.yml` 读取，如果 `.gitnodes.yml` 不存在。 内置默认值作为一个工作示例：任何具有 YAML 前面元数据的 Markdown 文件仓库 都作为目标使用，有或没有配置文件。 工作项配置相同：节点类型可以声明 `work_item_kind`，并且 `.gitnodes.yml` 中的标签分类法驱动提供者面向的标签而无需硬编码 GitHub 特定名称的应用。 保存的视图接受一个可选的 `weight:`（整数；较低 = 较早，默认为 0），因此单个固定的视图可以浮动到顶部而无需重新排序每个条目。 单个笔记可以在其 frontmatter 中声明一个可选的 `cover:` - 一个仓库相对路径或绝对的 `https://` URL - 在详细面板顶部渲染一个英雄图像。 详细面板中的反向链接按节点类型分组，以与 `node_types[]` 相同的顺序。 ### 类型图边（`link_fields`） 节点类型可以通过声明 `link_fields:` 来选择加入 **类型边** - 一个从 frontmatter 字段名称到目标节点类型的映射。图构建器解析 这些字段中的 slug 值与现有文件并解析带有源字段名称的边， 以及已经存在的正文链接。 ```yaml - name: pokemon directory: pokemon link_fields: trainer: trainer # pokemon.trainer → 所有权 locations: route # pokemon.locations → 遭遇地理 evolves_to: pokemon # pokemon.evolves_to → 进化链 ``` 画布按边缘类型（`Body`，`Frontmatter(field)`，`Tag`）样式化边缘并 在底部左侧公开一个切换图例，以便用户可以隔离所有权， 地理，进化或标签关系。未解析的 slug 被静默忽略 - 有用 用于记录未来实体而不会破坏图谱。字段是可选的并且 向后兼容（空 = 无类型边）。 ## 环境变量 对于本地 `gitnodes serve [dir]`，目标仓库、分支和凭证从 Git 检出和 GitHub CLI 登录中发现。显式环境配置始终优先。 需要部署或检出时没有 `origin` 远程仓库： | 变量 | 用途 | | -------------------------- | ----------------------------------------- | | `TARGET_GITHUB_REPOSITORY` | 默认仓库，以 `owner/repo` 格式表示 | 选择一种身份验证模式： | 变量 | 用途 | | ---------------------- | ------- | | `GITHUB_PAT` | 单用户模式：为每个 GitHub 请求使用此 PAT；不需要 OAuth 应用。 | | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` | 多用户模式：GitHub OAuth 应用凭证。 | > **OAuth 范围说明。** 在多用户 OAuth 模式下，登录请求 GitHub 的 `repo` 范围 - OAuth 应用不能限制为单个仓库，因此颁发的令牌可以读取和写入用户的所有仓库。GitNodes 在存储时加密它，仅在服务器端使用，并且仍然通过实时仓库权限控制每个目标（没有 `pull` 权限的用户将看不到）。为了更严格的权限控制，请优先使用单用户 PAT 模式（`GITHUB_PAT`，您可以选择其范围）或安装 GitNodes 作为 GitHub 应用，限定范围为所选仓库。 常见可选设置： | 变量 | 默认值 | 用途 | | ---------------------- | --------------------------- | ------- | | `TARGET_GITHUB_BRANCH` | `main` | 读取/写入的分支。 | | `LEPTOS_SITE_ADDR` / `PORT` | `127.0.0.1:3000` | 绑定地址。像 Railway 和 Fly 这样的主机注入 `PORT`。 | | `SESSION_DB_URL` | `sqlite://data/sessions.db` | 会话、审计日志和投影的 SQLite 路径。在生产环境中持久化挂载它。 | | `GITHUB_LOGIN_ORG` | _(无组织限制)_ | 将登录限制在某个组织内。目标访问仍然根据实时仓库权限控制。 | | `BRAND_NAME` | `GitNodes` | 在标题和页面标题中显示的品牌名称。 | | `RUST_LOG` | `gitnodes_app=info,warn` | tracing-subscriber 过滤器。 | 其他设置都有安全的默认值，仅在特定设置下需要 - 基于 Webhook 的同步（`WEBHOOK_SECRET`，`GITHUB_APP_*` 三元组，`GITHUB_TOKEN`）， 每个 IP 的速率限制，保留和同步作业调整，显式会话密钥管理（`SESSION_ENCRYPTION_KEY*`）， 以及循环逃生口（`GITNODES_ALLOW_REMOTE_PAT`，`GITNODES_ALLOW_REMOTE_PREVIEW`，`GITNODES_NO_OPEN`）。 大多数部署从不涉及这些。 OAuth 应用的回调 URL 必须是 `{host}/auth/callback`。 有关身份验证模式、持久性、Webhook 和完整的运营环境表，请参阅[部署指南](docs/guides/DEPLOYMENT.md)。 现有部署可以继续使用 `TARGET_GITHUB_ORG`、`TARGET_GITHUB_REPO` 和其旧的 `GITHUB_*` 别名。 这些分离的变量保留了历史上的登录组织备用。新部署使用 `TARGET_GITHUB_REPOSITORY` 默认无组织登录。 任何 GitHub 用户都可以在默认设置下完成 OAuth，但 GitNodes 仅在 GitHub 报告具有 `pull` 权限时才提供目标。 写入和管理功能继续遵循 `push`、`maintain` 和 `admin`。 ## 本地开发 前提条件：来自 `rust-toolchain.toml` 的 Rust 工具链，Node 18+，`cargo-leptos`， `wasm32-unknown-unknown` 目标，可选 [`just`](https://github.com/casey/just)。 ```bash just setup # 一次性 - 安装 tailwind + typography 插件 just css-watch & # 在更改时重建 style/main.css just dev # cargo leptos watch ``` 或者不使用 `just`：`npm install`，`npm run watch:css &`，`cargo leptos watch`。 对于 OAuth 开发，请复制 `.env.example` 并填写其三个主要值。 对于基于本地检出的使用，`gitnodes serve` 可以发现目标并在没有 `.env` 的情况下重用 `gh auth`。 ## 生产构建 ```bash docker build -t gitnodes . docker run -p 3000:3000 \ -e GITHUB_CLIENT_ID=... \ -e GITHUB_CLIENT_SECRET=... \ -e TARGET_GITHUB_REPOSITORY=your-owner/your-repository \ -v gitnodes_data:/app/data \ gitnodes ``` 将 `/app/data` 挂载到持久卷，以便会话和生成的加密密钥在重启后存活。 基于 Webhook 的投影重建需要服务器端凭证 - 设置 `GITHUB_APP_*` 三元组（首选，自动轮换）或 `GITHUB_TOKEN`（PAT 回退）。 在存储环境变量为主字符串的主机上（Railway，Fly，k8s Secrets），粘贴 PEM 并带有真实换行符； 仅当 `.env` 文件需要 `\n` 转义。 ## 状态和路线图 GitNodes 建立在成熟的核心上：配置驱动的节点类型，原子多文件 Git 提交层，可重建的 SQLite 投影， Webhook + SSE 实时同步，多仓库路由，双向工作项同步和权限感知直接写入与拉取请求流程均已就绪。 安全，运行状况检查（/healthz，/readyz，速率限制，会话加密）和模式操作强化车道已关闭。 有关总体方向，请参见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。 ## 许可证 此工作区是分许可的： - **库 crate** - `gitnodes-domain`，`gitnodes-graph`，`gitnodes-auth`， `gitnodes-storage` - 在 [Apache License, Version 2.0](LICENSE-APACHE) 下许可。可自由重用。 - **可部署应用程序** - `gitnodes-app` - 在 [GNU Affero General Public License v3.0 或更高版本](LICENSE-AGPL) 下许可。 如果您运行修改后的 GitNodes 作为网络服务，AGPL 需要您为用户提供相应的源代码。 `gitnodes-app` 包含 Apache-2.0 库（单向兼容到 AGPL），因此组合应用程序在 AGPL 下分发， 而库仍然可以在 Apache-2.0 下独立使用。 版权所有 (C) 2026 Andrea Bozzo。