kawngraph

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="brand/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="brand/logo-light.svg"> <img src="brand/logo.svg" alt="KawnGraph" width="320"> </picture> ### KawnGraph **一个项目宇宙。每个编码代理。** KawnGraph 将代码、文档、数据、测试和 Git 变更映射到有证据支持的**上下文包**，使 Claude、Codex 和 Cursor 可以在不阅读整个存储库的情况下找到正确的文件。 [](https://xd7fx.github.io/kawngraph-site/) [](https://www.npmjs.com/package/kawngraph) [](LICENSE) [](package.json) [](tsconfig.base.json) [](docs/PRIVACY.md) [](docs/PRIVACY.md) [](SUPPORT.md) [](https://www.linkedin.com/in/abdulrahman-alnashri-ai/) [](https://github.com/sponsors/xd7fx) <!-- LANGBAR:START --> **简体中文** · [English](../) · [العربية](README.ar.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Deutsch](docs/i18n/README.de.md) · [Português (BR)](docs/i18n/README.pt-BR.md) · [繁體中文](docs/i18n/README.zh-TW.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [हिन्दी](docs/i18n/README.hi.md) · [Bahasa Indonesia](docs/i18n/README.id.md) · [Türkçe](docs/i18n/README.tr.md) · [Русский](docs/i18n/README.ru.md) · [Italiano](docs/i18n/README.it.md) · [فارسی](docs/i18n/README.fa.md) · [اردو](docs/i18n/README.ur.md) · [Polski](docs/i18n/README.pl.md) · [Nederlands](docs/i18n/README.nl.md) · [Українська](docs/i18n/README.uk.md) · [Tiếng Việt](docs/i18n/README.vi.md) · [ภาษาไทย](docs/i18n/README.th.md) · [Svenska](docs/i18n/README.sv.md) · [Ελληνικά](docs/i18n/README.el.md) · [Română](docs/i18n/README.ro.md) · [Čeština](docs/i18n/README.cs.md) · [Suomi](docs/i18n/README.fi.md) · [Dansk](docs/i18n/README.da.md) · [Norsk](docs/i18n/README.no.md) · [Magyar](docs/i18n/README.hu.md) · [עברית](docs/i18n/README.he.md) _{English is canonical · العربية is AI-assisted · owner review pending · the other 29 languages are machine-assisted (human review needed) — see [translation status](docs/i18n/STATUS.md).} <!-- LANGBAR:END --> **[快速开始](#快速开始)** · **[工作原理](#工作原理)** · **[工作室](#工作室)** · **[基准测试](#基准测试)** · **[文档](#文档)** · **[贡献](#贡献)** </div> --- <div align="center"> <img src="docs/assets/context-pack-flow.svg" alt="A task ('Fix the Zid OAuth callback') flows into KawnGraph, which returns a token-budgeted Context Pack: must-read files, related docs, tables, tests, risks, an excluded list, and a confidence score." width="860"> </div> --- ## 为什么选择 KawnGraph? 当您给编码代理一个任务时，它通常会从*读取*开始 - 大量读取。它会打开数十个文件，重新推导路由如何到达数据库，并为每个请求重建相同的思维模型。这很慢，token 昂贵，而且往往不准确：代理会错过一个重要的文件，却沉溺于五个无关的文件中。 KawnGraph 仅需**一次**扫描存储库，构建一个分层的、有证据支持的图，展示事物之间的关系，然后为特定任务回答，提供**几个相关文件** - 以及相关的文档、相关的数据库表、要运行的测试和要关注的风险。这个包就是**上下文包**。图是基础；上下文包是产品。 > **给代理一张地图，而不是存储库。** --- ## 快速开始 使用**一个命令**安装并运行 KawnGraph - `npx` 会获取它，不需要克隆（Node ≥ 18）： ```bash npx kawngraph setup # 扫描，检测您的代理，连接它们，验证检索 kawn check # 健康检查：图是否新鲜？谁已连接？ kawn map # 打开本地只读可视化资源管理器 ``` **或从源代码**（此 monorepo，供贡献者使用 - [pnpm](https://pnpm.io)）： ```bash pnpm install && pnpm build # 构建工作区 pnpm kawn setup --agent all --yes # 扫描 + 连接 Claude Code / Codex / Cursor pnpm kawn check # 图是否新鲜？谁已连接？ pnpm studio:build && pnpm kawn map # 打开只读可视化资源管理器 ``` 然后打开您的代理并描述您的任务 - 它会自己拉取相关的文件。无需 API 密钥，无遥测，无扫描或检索期间的网络调用。新手？从 **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** 开始。 --- ## 将其连接到您的编码代理 KawnGraph 的重点是代理**自动**查找地图。 一个命令将项目连接到您使用的代理 - 无需编辑 `CLAUDE.md` 或 `AGENTS.md`，每个更改都是可逆的： ```bash kawn setup # 扫描（如果需要），检测代理，连接，验证 kawn setup --agent all --yes # 非交互式（CI），所有支持的代理 kawn setup --dry-run # 预览确切的文件更改，不写入任何内容 kawn status # 图是否新鲜？谁已连接？ kawn disconnect codex # 清洁地删除仅 KawnGraph 的条目 ``` `setup` 检测您的编码代理 - **Claude Code**，**Codex**，**Cursor**，**Copilot**，**Gemini CLI** 和 **Aider**（以及一个 `generic` Markdown/JSON 导出和一个可选的**本地 LLM**）- 并安装一个**只读集成**，限定在项目（`.mcp.json`，`.cursor/mcp.json`，`.codex/config.toml`，`.vscode/mcp.json`，`.gemini/settings.json` 或 Aider 上下文文件），备份它所触及的内容，并通过实时握手验证每个 MCP 服务器。完整的合约：**[docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md)**。 **MCP 服务器**是一个只读的 stdio JSON-RPC 环路，**没有 MCP SDK**（手动制作）和四个工具： | 工具 | 它做什么 | | ---- | ------------ | | `kawn_context` | 任务的 token-budgeted 上下文包。 | | `kawn_query` | 图的排名、模式范围搜索。 | | `kawn_affected` | 反向影响：什么依赖于符号。 | | `kawn_changes` | 当前更改集的影响（未提交，或分支与基准引用）。仅本地 git。 | 它**仅读取**图 - 它永远不会扫描、重建或写入图（当图看起来陈旧时，它会警告并指向 `kawn update`）。 --- ## 工作原理 一个项目不仅仅是代码。它是代码**和**文档**和**SQL**和**测试**和**配置**，它们把它们联系在一起。KawnGraph 将每个建模为一个单独的**层**，因此查询会询问它需要的内容，而不是不需要的内容 - 代码影响查询永远不会拖入营销文档；文档查询永远不会返回原始调用图，除非您询问。 <div align="center"> <img src="docs/assets/architecture.svg" alt="KawnGraph 使用确定性扫描器读取您的存储库到一个分层图在 .kawn/graph.json（代码、数据、配置、文档、测试层），为 kawn CLI、MCP 服务器和 Studio 提供只读服务。无网络，无 LLM，无遥测。" width="860"> </div> | 层 | 示例 | | -------- | --------------------------------------------------- | | `code` | 文件、函数、类、导入、调用、路由、测试 | | `data` | SQL 表、迁移、外键 | | `config` | 工作区包、依赖项 | | `docs` | markdown 章节、链接、提及 | | `test` | 测试及其覆盖范围 | 边携带**证据**（源路径、行范围、代码段）和置信度 - 机械派生，扫描器可以附加；每个节点都有一个**稳定、基于内容的 ID**，因此图在扫描之间保持可区分。更深层次的模型： **[docs/GRAPH_MODEL.md](docs/GRAPH_MODEL.md)**。 ### 上下文包，端到端 ```text $ kawn ask "fix the Zid OAuth callback that writes store tokens" Must-read app/api/zid/oauth/callback/route.ts 入口路由 packages/zid/src/oauth.ts token exchange packages/db/.../storeTokens.ts writes store_tokens Docs docs/zid-oauth-core.md#callback-flow 期望行为 Tables store_tokens (written) · merchants (fk) Tests oauth.test.ts Risks token encryption · tenant isolation Excluded unrelated UI components (over budget) · confidence 0.6 ``` 相同的包可用作 Markdown、JSON 或代理中立的**通用上下文协议** (`--format ucp` / `ucp-md`). 更多信息： **[docs/CONTEXT_PACKS.md](docs/CONTEXT_PACKS.md)**. --- ## 工作室 `kawn map` 打开 **KawnGraph Studio** - 一个本地 **只读** 资源管理器，通过 `127.0.0.1` 提供服务，它读取现有的 `.kawn/graph.json` 并且永远不会扫描、重建或写入。它提供交互式 2D 图、 可扩展的 3D "Universe" 星图（预算充足，因此它永远不会一次绘制整个大图）、上下文包构建器、反向影响、Git 更改视图和行为基准视图。内置英文和阿拉伯语（RTL 感知）。从源代码运行 `pnpm studio:build && pnpm kawn map`. <div align="center"> <img src="docs/assets/studio-universe.webp" alt="KawnGraph Studio - 只读 3D 'Universe' 视图此存储库的图：1,261 个节点，按层聚类（Code 815，Docs 430，Config 13，Data 3）带有连接线，以及每个层/类型/边过滤器。" width="860"> <br>_{3D <b>Universe</b> 视图 - 此存储库的图（1,261 个节点），只读。} </div> <div align="center"> <img src="docs/assets/studio-map.webp" alt="KawnGraph Studio - 2D 星座地图：此存储库的图作为圆形节点的力导向星图，颜色按层（较大 = 度数较高），薄边，级别详细标签和层/类型/边过滤器。" width="860"> <br>_{2D <b>constellation Map</b> - 图的力导向星图（节点颜色按层，大小按度数），具有过滤器、搜索、悬停和缩放。} </div> --- ## KawnGraph 与纯存储库搜索 中立的**方法**比较（不是竞争对手攻击）。每个单元格都是可辩护的；“varies”意味着它取决于特定的工具。 | 能力 | 纯搜索 | 通用 RAG | 通用图查看器 | **KawnGraph** | | --- | :---: | :---: | :---: | :---: | | 确定性本地扫描 | ✅ | varies | ✅ | ✅ | | 符号级关系 | ❌ | varies | ✅ | ✅ | | 文档 / 数据 / 测试层 | ❌ | varies | varies | ✅ | | 边上的证据 | ❌ | ❌ | varies | ✅ | | 有限影响分析 | ❌ | ❌ | varies | ✅ | | Git 更改上下文 | varies | ❌ | ❌ | ✅ | | Token-budgeted 上下文包 | ❌ | varies | ❌ | ✅ | | 只读 MCP 检索 | ❌ | varies | varies | ✅ | | 不需要内部 LLM | ✅ | ❌ | ✅ | ✅ | 过时、来源、三列比较对抗成熟的图工具（KawnGraph 领先的**和**它不具备的能力）位于 **[docs/COMPARISON.md](docs/COMPARISON.md)**. --- ## 基准测试 KawnGraph 配备了一个**本地 A/B 套件**，在**相同**任务上运行**相同**代理任务，并记录行为。结果是诚实的且**任务依赖** - 包括中性和负面案例。 <!-- BENCH:START --> <!-- Generated by scripts/readme-benchmark.mjs from benchmarks/published/campaign-2026-06-20.summary.json — do not edit by hand. --> 本地 A/B 套件：72 个会话运行，60 个可用，10 个任务单元格，种子 1，3 次重复/臂（3/臂后分组 - **探索性，n<5，仅方向性**）。 相同代理，相同任务，相同存储库快照；A = 无 KawnGraph，B = 有。 Δ = B − A。 12 个会话因黄金出处而被排除（见制品）。 黄金验证：所有保留运行都有有效的黄金参考。 **头部任务 - `zid-oauth`（检索）在 `nextjs-supabase` 上：** *Claude Code - 相同任务，相同存储库，相同模型（模型未固定在制品中）：* | 指标 | 无 KawnGraph | 有 KawnGraph | 差异 | | --- | --- | --- | --- | | 任务正确性 | 100% | 100% | 0 pp | | 自动调用 KawnGraph | 0% | 100% | +100 pp | | 相关文件找到（召回率） | 100% | 93% | -7 pp | | 打开文件精度 | 83% | 89% | +6 pp | | 不同文件打开 | 6 | 5.3 | -0.7 | | 工具调用 | 8.3 | 8.7 | +0.3 | | 到第一个相关文件的耗时 | 20.7 秒 | 22.4 秒 | +1.7 秒 | | 总墙上时间 | 54.6 秒 | 61.9 秒 | +7.3 秒 | | 输出令牌 | 2,867 | 3,130 | +262 | *Codex - 相同任务，相同存储库，相同模型（模型未固定在制品中）：* | 指标 | 无 KawnGraph | 有 KawnGraph | 差异 | | --- | --- | --- | --- | | 任务正确性 | 100% | 100% | 0 pp | | 自动调用 KawnGraph | 0% | 0% | 0 pp | | 相关文件找到（召回率） | 80% | 87% | +7 pp | | 打开文件精度 | 25% | 61% | +36 pp | | 不同文件打开 | 1 | 4.3 | +3.3 | | 工具调用 | 2.7 | 8 | +5.3 | | 到第一个相关文件的耗时 | 18.7 秒 | 17.8 秒 | -884 毫秒 | | 总墙上时间 | 36.4 秒 | 41 秒 | +4.5 秒 | | 输出令牌 | 822 | 1,082 | +260 | > KawnGraph 是任务依赖的。它可以减少不熟悉的多文件工作的存储库资源探索，同时在已经聚焦的任务上增加开销。 在 [docs/BENCHMARKS.md](docs/BENCHMARKS.md) 中查看完整的文档和方法论。 **它帮助、保持中立或伤害的地方（所有 10 个任务单元格）：** | 任务家族 | 代理 | 模式 | 结果 | 工具调用 Δ | 时间 Δ | | --- | --- | --- | --- | --- | --- | | 上下文包排名 | claude | 检索 | 中立 | -0.3 | +6.2 秒 | | 文档到代码链接 | claude | 检索 | 中立 | -0.3 | +9.6 秒 | | 新鲜度门控 | claude | 检索 | 改进 | -9.7 | -54.6 秒 | | oauth 代码防护 | claude | e2e | 中立 | -0.3 | +5.9 秒 | | zid-oauth | claude | 检索 | 回归 | +0.3 | +7.3 秒 | | 上下文包排名 | codex | 检索 | 回归 | +4 | +33.3 秒 | | 文档到代码链接 | codex | 检索 | 改进 | -0.7 | -4.6 秒 | | 新鲜度门控 | codex | 检索 | 中立 | 0 | -2.1 秒 | | oauth 代码防护 | codex | e2e | 回归 | 0 | +1.5 秒 | | zid-oauth | codex | 检索 | 回归 | +5.3 | +4.5 秒 | 结果标签（`改进` / `中立` / `回归` / `数据不足`）根据工具调用和墙上时间增量确定；每个单元格为 n=3/臂，因此都是方向性的。完整的每个指标表格： [benchmarks/published/campaign-2026-06-20.md](benchmarks/published/campaign-2026-06-20.md). <!-- BENCH:END --> 方法和环境、样本大小、每个指标的表格和局限性： **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** - 从提交的、验证的制品中生成 `benchmarks/published/`。 --- ## 支持的扫描器和层 每种语言/格式都是一个有版本号的**扫描器插件**，位于一个注册表后面（检测 → 扫描 → 完成）：确定顺序，每个文件失败隔离，显式注册和有限的文件大小。 | 语言/格式 | 提取 | | ----------------- | --------- | | TypeScript / JS | 文件、顶级函数/类、导入、调用、Next.js 路由、测试 | | Python | 顶级 `def`/`async def`/`class`、装饰器、方法（作为元数据）、导入、FastAPI/Flask 路由、文档字符串、测试（通过 `@lezer/python` - 纯 JS，无错误容忍） | | SQL | 表（`CREATE`/`ALTER`）、外键关系 | | package.json | 工作区包和内部依赖项 | | Markdown | 链接到代码、SQL 和路由的标题/章节 | 两个代码扫描器中的刻意省略：方法和嵌套函数永远不是独立节点（方法位于其类上作为元数据），环境声明文件（`.d.ts`，`.pyi`）永远不会被声明。详细信息： **[docs/SCANNERS.md](docs/SCANNERS.md)**. --- ## 隐私和安全 - **默认情况下无网络**。扫描和检索读取您的存储库并在 `.kawn/` 下写入 JSON。没有任何内容离开机器。 - **无内部 LLM**。代码、文档和 SQL 在结构上进行解析；AI 丰富是可选的，并且本地优先。 - **无遥测。默认情况下无查询日志记录**。 - **只读 MCP**。服务器提供图；它永远不会扫描、重建或写入 - 如果它无法信任图的模式，它会拒绝提供服务。 - **可逆、基于项目的集成**。原子写入、时间戳备份、结构化（非字符串）配置编辑；默认情况下永远不会编辑 `CLAUDE.md` / `AGENTS.md`，也不会触及全局配置。 完整模型： **[docs/PRIVACY.md](docs/PRIVACY.md)**. 通过 **[SECURITY.md](SECURITY.md)** 私下报告漏洞。 --- ## 状态与限制 KawnGraph 处于**积极开发**状态（`v0.1.0`，尚未发布到 npm）。已端到端构建和测试：代码/数据/配置/文档/测试图、文档到代码的链接、作用域查询、影响分析、Git/PR 影响、基于令牌预算的上下文包、通用上下文协议、只读 MCP 服务器、一键代理设置（Claude Code、Codex、Cursor、Copilot、Gemini、Aider、通用导出、本地 LLM）、 Studio 和 A/B 基准测试框架。 **诚实的限制。** 已发布的基准测试是**探索性的（每组 n < 5 - 方向性的，不显著的）**。KawnGraph 在不熟悉的多文件发现方面帮助最大，但在已经聚焦的单文件任务上可能会增加开销。尚未构建：仅建议的钩子、视觉层、语义/AI 丰富性和运行时层 — 所有这些都是按设计选择加入的。请参阅 [PROJECT_PLAN.md](PROJECT_PLAN.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/FAQ.md](docs/FAQ.md) · [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。 --- ## 文档 | 指南 | 内容 | | ----- | ------------- | | [快速入门](docs/GETTING_STARTED.md) | 安装、扫描、第一个上下文包 | | [代理集成](docs/AGENT_INTEGRATION.md) | MCP 设置合同、可逆性 | | [上下文包](docs/CONTEXT_PACKS.md) | 排名、预算、UCP 线格式 | | [图模型](docs/GRAPH_MODEL.md) | 节点、边、层、证据、ID | | [扫描器](docs/SCANNERS.md) | 每个语言插件提取的内容 | | [基准测试](docs/BENCHMARKS.md) | 方法论、环境、完整结果 | | [比较](docs/COMPARISON.md) | 过时、有来源的能力比较 | | [隐私](docs/PRIVACY.md) | 每个层的 数据边界 | | [故障排除](docs/TROUBLESHOOTING.md) · [FAQ](docs/FAQ.md) | 常见问题和疑问 | --- ## 贡献 欢迎贡献。从源代码构建，运行套件，并阅读指南： ```bash pnpm install && pnpm build pnpm test # node: 测试套件（图、上下文、MCP、代理、Studio） pnpm pack:check # 打包审核（打包每个包，从 tarball 安装） ``` 请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)** 以获取设置、约定和每个 PR 传递的隐私审查； **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** 以获取社区期望； **[docs/i18n/TRANSLATING.md](docs/i18n/TRANSLATING.md)** 以添加或审查语言；以及 **[SUPPORT.md](SUPPORT.md)** 以获取提问的地方。 --- ## 许可证与致谢 **[MIT](LICENSE)** KawnGraph 贡献者。 由 **[Abdulrahman Alnashri](https://www.linkedin.com/in/abdulrahman-alnashri-ai/)** 创建和维护。 **Kawn**（阿拉伯语 **كَوْن** — *宇宙、宇宙、存在*）将存储库视为一个充满活力的知识宇宙； **Graph** 是其核心的基于证据的 Agent Context Graph。使用 [TypeScript](https://www.typescriptlang.org/)、 [Vite](https://vitejs.dev/)、 [React](https://react.dev/)、 [React Flow](https://reactflow.dev/)、 [Three.js](https://threejs.org/) 和 [`@lezer/python`](https://lezer.codemirror.net/) 构建。