cartographer

██████╗ █████╗ ██████╗ ████████╗ ██████╗ ██████╗ ██████╗ █████╗ ██████╗ ██╗ ██╗███████╗██████╗ ██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║ ██║██╔════╝██╔══██╗ ██║ ███████║██████╔╝ ██║ ██║ ██║██║ ███╗██████╔╝███████║██████╔╝███████║█████╗ ██████╔╝ ██║ ██╔══██║██╔══██╗ ██║ ██║ ██║██║ ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║██╔══╝ ██╔══██╗ ╚██████╗██║ ██║██║ ██║ ██║ ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██║ ██║ ██║███████╗██║ ██║ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ``` > MCP 管理服务器，采用 **Go** 语言，为 *Agentic Wiki* 提供服务 —— 知识库通过构建和维护，而不是简单的查询。 [](https://github.com/BeppeTemp/cartographer/actions/workflows/ci.yml) [](https://github.com/BeppeTemp/cartographer/releases/latest) [](https://goreportcard.com/report/github.com/BeppeTemp/cartographer) [](LICENSE) [](https://go.dev/) []() > [!WARNING] > **测试软件。** Cartographer 目前处于预发布阶段（0.x 版本），MCP 工具界面、CLI 和配置可能会在小版本更新中发生变化，而不提供废弃期。重大变更会提升小版本号（遵循 0.x 语义），并在 [更新日志](CHANGELOG.md) 中记录。期待 rough edges —— 欢迎提交 bug 报告。 LLM 代理在会话之间会忘记所有内容，而无状态 RAG 只能在这种健忘症上添加检索功能。另一种方法是构建一个知识库，代理本身 **在一段时间内构建和维护** —— 但是让代理直接访问文件夹可能会导致链接损坏、历史记录丢失和静默数据腐败。 **Cartographer** 是治理层，使模式安全：代理通过 MCP 工具与知识库交互，服务器强制执行每条不变性规则 —— 验证、链接、不可变性门控、一个 git 提交记录。  ## 什么是 Cartographer **Cartographer** 实现了 _Agentic Wiki_：一个持久的知识库，由相互链接的 Markdown 文件组成，LLM 代理通过与服务器的 MCP 协议交互来增长和维护知识库。代理 **永远不会直接触摸文件**。 知识库基于 **Karpathy 的“LLM Wiki”模式**（运营模式：知识随着时间的推移而积累，而不是无状态 RAG），建立在 **OKF** 基础上（Open Knowledge Format v0.1 by Google Cloud）—— 每个知识库都是一个 `.md` 文件夹，带有 YAML 前言，自成体系，通过 git 进行版本控制。零锁定：知识库可由任何工具读取，包括 Obsidian 和任何文本编辑器。 Cartographer 提供了 **两种互补的配置文件**： - **本地核心** —— 单个代理，stdio 传输，本地 git。捕获模式价值，复杂度最小化。 - **服务器** —— 多知识库，HTTP + token 身份验证，可选语义嵌入。适用于共享和远程部署。 ## 主要功能 - 🔧 **完整的 MCP 工具套件** —— 完整列表见 [`docs/control-plane.md`](docs/control-plane.md) - 📖 **读取和导航** —— `kb_overview`、`concept_read`、`archive_list` / `dossier_list`、`graph_neighbors` - 🔍 **搜索** —— 关键词（纯 Go 倒排索引）+ 可选混合语义搜索（通过 Ollama） - ✍️ **验证写入**，乐观并发（`if_match` / 内容哈希） - 🛡️ **治理** —— 确定性 `lint`（损坏链接、过时声明、孤立节点）、`commit_gate`、`gate_check`、`supersede`、矛盾跟踪 - 🧬 **事务性 git** —— 每个写入操作一个提交；可选同步到远程仓库（fetch/pull-rebase 然后 push）—— git 作为多个实例之间的同步层；代理冲突处理（标记 `degraded` + `conflicts_list` 工具 + 有指导的技能） - 🗂️ **多知识库**，`?kb=<name>` 路由；带有作用域 / RBAC 的 bearer-token 身份验证 - 🔐 **审计日志** —— 仅追加的哈希链和 Ed25519 签名 - 🧩 **领域技能**（`SKILL.md` / agentskills.io 格式），带有供应和客户端 ↔ 服务器同步 - 🔑 **通过 SOPS 的机密** —— 仅引用，纯文本值从不存储 - ⚙️ **多提供商配置器** —— 为 Claude Code、Codex CLI、Kiro、OpenCode 生成 MCP 配置 - 📦 **OKF 合规** —— 每个知识库都是 OKF 包和独立的 git 仓库，零锁定（仅 git + Markdown） ## 架构 Cartographer 将 **数据平面** 与 **控制平面** 分开： - **数据平面** —— 知识库本身：`data/` 下的 OKF Markdown 文件，组织为 `archive → dossier → concept`。普通文件 + git：历史记录、差异、备份、免费共享。 - **控制平面** —— 代理调用的 MCP 工具。服务器应用每个不变性规则（验证、门控、不可变性），因此代理在没有直接文件系统访问的情况下安全运行。 交互基于 **MCP + 技能 + 钩子** 三元组：MCP 携带数据和能力，技能携带按需加载的程序化知识，钩子携带确定性 0-token 自动化。 ```mermaid flowchart LR A["🤖 代理（LLM）<br/><i>仅通过 MCP — 从不直接触摸文件</i>"] S["Cartographer<br/>Go MCP 服务器<br/><i>服务器端强制执行不变性规则</i>"] KB[("知识库<br/>Markdown + git")] R[("远程 git")] A -- "MCP 工具" --> S S -- "有界读取" --> A S -- "每个写入<br/>一个提交" --> KB KB -. "同步进/出" .-> R ``` ## 安装 ```bash # macOS (Homebrew) brew install beppetemp/tap/cartographer # Linux / macOS without Homebrew curl -fsSL https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.sh | sh # 从源码编译（Go 1.26+） go install github.com/BeppeTemp/cartographer/cmd/cartographer@latest ``` ## 快速开始 ```bash # 本地 stdio（本地核心） cartographer serve --kb /path/to/kb --init # HTTP 多知识库（服务器配置文件，禁用身份验证） CARTOGRAPHER_KB=/data/kb CARTOGRAPHER_HTTP=:8080 CARTOGRAPHER_AUTH=false \ cartographer serve # 启用身份验证的 HTTP CARTOGRAPHER_KB=/data/kb CARTOGRAPHER_HTTP=:8080 CARTOGRAPHER_AUTH=true \ CARTOGRAPHER_TOKENS=mytoken cartographer serve # 本地原生服务（macOS 上 launchd，Linux 上 systemd 用户单元） cartographer service install # 生成配置文件，安装并启动服务 cartographer service status # 退出状态：0 运行中 / 3 已停止 / 4 未安装 # 将代理客户端（Claude Code、OpenCode、Codex、Kiro）连接到正在运行的服务器 cartographer connect cartographer status # 漂移检查：退出状态 0 同步 / 1 漂移 / 2 错误 cartographer sync # 重新应用漂移后 ``` `connect` 命令不带标志，在 TTY 中打开交互式表单（服务器 URL、服务器名称、令牌环境变量、身份验证）而不是标志默认值；传递 `--no-input` 以强制非交互式行为。 ## 配置 | 环境变量 | 默认值 | 描述 | |---|---|---| | `CARTOGRAPHER_KB` | — | 知识库路径（单个或多个，以逗号分隔） | | `CARTOGRAPHER_DATA` | — | 其子文件夹自动发现为知识库的目录 | | `CARTOGRAPHER_HTTP` | — | HTTP 地址（例如 `:8080`）。不存在 = 仅限 stdio | | `CARTOGRAPHER_AUTH` | 自动 | `true` / `false` / 未设置（HTTP 上自动开启） | | `CARTOGRAPHER_TOKENS` | — | 以逗号分隔的 bearer token | | `CARTOGRAPHER_GIT_AUTOCOMMIT` | `true` | 每个写入操作一个 git 提交 | | `CARTOGRAPHER_GIT_SYNC` | `true` | 每个写入操作时 fetch/pull-rebase + push 到 `origin` | | `CARTOGRAPHER_OLLAMA` | — | 用于语义搜索的 Ollama 服务器 URL | | `CARTOGRAPHER_OLLAMA_MODEL` | `nomic-embed-text` | Ollama 嵌入模型 | | `CARTOGRAPHER_AUDIT_LOG` | — | 审计日志文件路径 | | `CARTOGRAPHER_AUDIT_KEY` | — | 用于审计签名的 Ed25519 密钥 | 完整的列表，包括 CLI 标志和默认值，请参见 [`docs/deployment.md`](docs/deployment.md)。 ## 构建和测试 ```bash make build # → bin/cartographer make test # 单元测试（go test ./...） make smoke # stdio 烟雾测试 make smoke-http # 操作级 HTTP 烟雾测试（通过 curl 创建临时知识库） make e2e # 代理级 E2E 测试，带有无头 OpenCode（9 个场景） make e2e-quick # 仅 CRUD 场景 ``` E2E 测试驱动 **无头模式下的 OpenCode** 作为真实代理，针对本地服务器，使用故意设计的经济模型作为清晰度门控： 如果廉价模型可以完成任务，则系统对于生产环境来说足够清晰。 它需要 OpenAI 兼容的端点（`E2E_LLM_BASE_URL`）；完整策略 → [`docs/testing.md`](docs/testing.md)。 ## 项目结构 ``` cmd/ cartographer/main.go # 入口点：子命令调度（serve/version/help/agents/connect/status/sync） cartographer/serve.go # 服务器：标志 + 环境变量 + YAML 配置，stdio/HTTP cartographer/tui.go # 交互式仪表盘（无参数，TTY） internal/ config/ # 服务器 YAML 配置（标志 > 环境变量 > YAML > 默认值） okf/ # OKF 原语：ConceptID、frontmatter、content-hash kb/ # 数据平面：Open、Init、Read/WriteConcept、Validate kb/graph.go # 图形导航：ExtractLinks、GraphNeighbors kb/gate.go # 提交门控 kb/gitsync.go # 事务性 git：锁定、提交、同步进/出 kb/conflicts.go # 冲突注册表、MarkDegraded mcpserver/ # MCP 服务器：stdio、HTTP 处理程序、多知识库服务器、工具（按域拆分） mcpserver/gitwrap.go # 写入包装器：锁定 + 提交 + 同步 search/ # 纯 Go 倒排索引 sqlindex/ # 持久化 SQLite 索引：FTS5 trigram + 嵌入缓存 lint/ # 确定性 lint gitx/ # git 包装器：提交、变基、推送、获取、stash audit/ # 审计日志：JSONL 哈希链 + Ed25519 auth/ # TokenStore、中间件、RBAC、作用域 embed/ # 嵌入接口 + Ollama 适配器 + 向量存储 skill/ # SKILL.md 加载器和验证器（agentskills.io） sops/ # SOPS 解密包装器 configurator/ # 多提供商适配器，HTTP-only（Claude Code、Codex、Kiro、OpenCode） provisioning/ # 清单、锁定（v1/v2 多提供商）、差异、应用 — 客户端 ↔ 服务器同步 agents/ # Detect() 安装的代理 CLI clientconfig/ # .cartographer.yaml（服务器 URL、连接的代理） client/ # 客户端的最小 MCP 客户端（HTTP 上的 JSON-RPC） docs/ # 完整文档（参见 docs/index.md） test/e2e/ # 代理级 E2E 测试套件 ``` ## 文档 完整的索引位于 [`docs/index.md`](docs/index.md)。主要入口： - [`docs/overview.md`](docs/overview.md) — 愿景、指导原则、架构 - [`docs/data-plane.md`](docs/data-plane.md) — 知识库模型、层次结构、OKF - [`docs/control-plane.md`](docs/control-plane.md) — Go 服务器、MCP 工具 API - [`docs/concurrency.md`](docs/concurrency.md) — 单写入者、git 同步、冲突 - [`docs/deployment.md`](docs/deployment.md) — 拓扑结构（本地服务 / k8s / 多服务器）、备份、环境变量 ## 贡献 欢迎提交问题和 PR —— 请参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)，了解构建/测试循环、PR 流程（压缩合并、约定标题、同一 PR 中更新文档）以及如何在代码库中找到方向。Cartographer 是一个个人项目，在尽力而为的基础上维护：没有响应时间 SLA。对于安全报告，请参见 [`SECURITY.md`](SECURITY.md)。 ## 许可证 在 Apache License 2.0 下发布。参见 [`LICENSE`](LICENSE)。