Madar

Madar

在编码 Agent 开始搜索之前，为其提供所需的代码库上下文。

Madar 会在本地为 TypeScript 或 Node.js 代码库构建图谱，并将当前问题转化为小型的任务感知上下文包。Claude Code、Codex、Cursor、Copilot、Gemini、Aider 和 OpenCode 可以从相关文件、符号、代码片段及其关系入手，而不必从头重新探索代码库。

• 从小处着手： 在广泛搜索之前，为 Agent 提供可能的入口点和运行时路径。
• 留在本地： 生成图谱不会上传源代码，也不需要云服务。
• 保持最新： 已安装的 MCP 配置会随当前工作区变化而刷新图谱。

60 秒快速体验

安装 Node.js 20 或更高版本的 Madar，然后在代码库中运行：

npm install -g @lubab/madar
cd your-repository
madar try "how does authentication work?"

madar try 会构建或复用本地图谱，打印易读的首个结果，并推荐下一条 Agent 安装命令。它不会修改源代码。

例如，Madar 附带的密码重置工作区包含以下路径：

account-routes.ts
  -> PasswordResetService.requestPasswordReset()
  -> userRepository.saveResetToken()
  -> enqueueResetEmailJob()
  -> sendPasswordResetEmail()

这就是 Madar 在 Agent 判断是否需要检查其他文件之前，为其提供的聚焦起始路径。

连接你的 Agent

选择你使用的 Agent。以 Claude Code 为例：

madar claude install
madar doctor
madar status

安装配置后，运行 madar doctor 和 madar status。之后，你可以使用如下常规提示词，让 Agent 向 Madar 请求上下文：

How does authentication work?
Why does this endpoint return 403?
Where is the report generated?
What breaks if I change this service?
Add telemetry to this flow.

Madar 支持以下项目本地安装程序：

Agent	安装命令
Claude Code	madar claude install
Codex CLI	madar codex install
Cursor	madar cursor install
GitHub Copilot	madar copilot install
Gemini CLI	madar gemini install
Aider	madar aider install
OpenCode	madar opencode install

安装程序详情请参阅 CLI 和 MCP 参考。分步设置说明和冒烟测试请参阅 Agent 快速入门。

升级 Madar 后，重新运行 Agent 的安装命令以刷新其托管配置。较旧的配置可能缺少自动刷新功能，或不包含 Codex 更长的启动等待时间。

Codex 安装会创建工作区范围的 MCP 配置块，并设置更长的启动超时和工具超时。在初始协调期间，Madar 仍可使用；图谱就绪后，即可调用基于图谱的功能。

从 0.31.3 开始，如果在 Madar 处于 starting、pending 或 reconciling 状态时调用基于图谱的功能，系统会返回结构化的可重试响应。Agent 应在建议的延迟后重试相同的 Madar 请求，而不是绕过 Madar 或手动运行生成操作。失效的刷新进程所有者会自动恢复；只有图谱状态失败、不完整或与策略不匹配时，才需要修复。

Agent 的变化

如果没有 Madar，编码 Agent 往往会先广泛搜索文件名，反复读取文件，并猜测哪个路由、服务或处理程序负责当前任务。

有了 Madar，第一轮探索可以包括：

• 可能相关的文件、导出符号、路由和处理程序
• 与问题相关的直接代码片段
• 导入、调用、框架角色和运行时交接
• 当图谱支持时，给出静态运行时路径假设，而非实时执行跟踪
• 图谱新鲜度和索引完整性信号
• 明确指导是直接回答、附带说明回答，还是核验特定目标

Madar 不会取代你的 Agent，也不会阻止它读取代码。它为 Agent 提供了一个范围更小、以代码仓库为依据的起点。

工作原理

Your repository
      |
      v
Local Madar graph
      |
      v
Context for the current question
      |
      v
Claude, Codex, Cursor, or another coding agent

1. Madar 会为源文件、符号、导入、调用、路由、处理程序、框架元数据和选定文档建立索引。
2. 提问时会选取范围有限的上下文包，而不是将整个代码仓库倾倒进提示词。
3. 响应会报告证据强度、覆盖范围、新鲜度，以及是否仍需进行有针对性的核验。
4. 已安装的 MCP 配置会监视当前工作区，并在相关更改后刷新基于图谱的上下文。

完整的响应规范（包括有界恢复和可回答性状态）记录在 MCP 响应格式中。

不使用 MCP 运行 Madar

CLI 无需安装 Agent 集成，即可生成和检查上下文：

madar generate .
madar summary
madar pack "how does auth work?" --task explain --format text

默认情况下，madar generate . 会将 SPI 元数据与已验证的 JavaScript/TypeScript 旧版语义结合使用，并对其他受支持语言采用旧版回退模式。严格模式请参阅 CLI 参考。

创建适用于服务提供商的提示词：

madar prompt "how does auth work?" --provider claude

为其他编码工具创建可安全分享的交接内容：

madar handoff "add auth telemetry" --task implement --consumer copilot

生成的图谱和索引清单会保留在项目输出位置。有关可复现的示例工作区和预期输出，请参阅入门教程。

Madar 的适用场景

以下情况最适合使用 Madar：

• 你的代码仓库规模中等或较大
• 项目主要使用 TypeScript 或 Node.js
• Agent 总是重复打开相同文件，或搜索无关目录
• 你会提出架构、运行时流程、代码审查或影响范围方面的问题
• Token 用量、延迟或本地代码仓库隐私很重要

以下情况的帮助较有限：

• 代码仓库很小，或任务从一个文件中就能看明白
• 问题依赖静态分析无法观察到的实时运行时行为
• 代码大量依赖图谱中未体现的动态模式
• 图谱已过时，或无法为相关源文件建立索引

Madar 与 Agent 和 IDE 索引功能互为补充。它不是托管式知识库、运行时跟踪器、PR 审查工具或漏洞扫描器。

本地优先设计

• 隐私： Madar 图谱生成在本地运行，无需 API 密钥。根据编码 Agent 的配置，它仍可能会将提示词或选定的文件上下文发送给自己的模型提供商。
• 敏感文件： 普通安全相关源代码仍可编入索引，而私钥、.env*、凭据存储以及已知的非源代码机密材料会被排除。这是路径策略，而非内容级机密扫描器。
• 时效性： 已安装的 MCP 配置文件会自动刷新。手动使用 CLI 的用户可以运行 madar generate . 重新生成；严格工作流可以要求使用 --require-fresh-context 或 --require-fresh-graph。
• 工作树： 请在同一个关联的 Git 工作树中运行 Madar 和 Agent。每个工作树都会在检出目录之外获得相互隔离的图谱构件；切换工作树后，请重新连接 MCP 服务。
• 遥测： 除非你明确启用，否则遥测处于禁用状态。相关控制项和精确的源代码安全事件架构见 遥测。

请将每个本地 MCP 安装、钩子或 Agent 配置文件都视为本地信任边界的一部分。MCP 威胁模型详细说明了这一边界。

证据与局限

Madar 会公开其基准测试声明背后的提示词、回答、追踪记录和可安全分享的报告。两种公开实验类型回答的是不同问题，不应将它们视为同一种测试来比较。

v0.30 受控证据

6 次 6 月的 TypeScript 运行时流程试验使用了源代码检出副本和针对任务定制的证明配置文件。在这些受控运行中，每行调用一次 Madar，记录结果显示：

• 工具调用次数减少 3.5x 至 18.5x
• 提供商报告的输入量减少 2.2x 至 15.6x
• 延迟降低 1.65x 至 7.09x

这些凭据记录了由配置文件辅助的 Madar 的真实测量结果。它们展示了在具备正确任务证据时，该工作流能够达到的效果。但这并不意味着未经调优的 npm 安装能针对任意问题复现相同结果，因为旧提示词和检出副本检索包含了基准测试专属要求，而普通软件包用户无法获得这些要求。

v0.31 生产构件验证

7 月的重测移除了这种辅助，并使用了相同的隔离解包 @lubab/[email protected] 软件包构件。6 个代码库中有 4 个记录到 Agent 采用失败：未发生可归因于 Madar 的 MCP 调用。另外两个调用了 Madar，但未通过严格的提示词或回答门槛。正确的结果是有效的性能比较数量为零，而不是产品在 6 次测试中均表现不佳。这些重测揭示了 Agent 采用和回答完整性方面的改进需求；它们既未证实，也未否定先前受控效率测量的结果。

请阅读基准测试套件和所有带日期的凭据记录，或更简短的声明与证据概览。

当前版本

当前版本：0.32.3。

0.32.3 更新了分词器和 WebAssembly 解析器，升级了开发工具，并修复了一项开发依赖安全公告。

0.31.4 确保回执始终关联可见上下文，并增强了 Claude/Codex 钩子的处理能力。

0.31.3 恢复了失效的刷新所有者，在存在活动刷新竞争时等待，并在临时协调期间返回重试信号，而不是促使 Agent 绕过 Madar。

0.31.2 在初始自动图刷新运行期间保持 Codex MCP 连接响应，增加了明确的 180 秒 Codex 启动窗口，并确保图就绪之前无法使用基于图的回答。

0.31.1 重建了公开的入门流程，并明确说明了每项基准测试实验所验证的内容。与 0.31.0 相比，运行时行为没有变化。

0.31.0 默认将代码图设为有向图，将证据强度与回答就绪状态分开，新增有界上下文恢复机制，明确索引完整性，在自动刷新期间保留生成策略，隔离关联工作树的产物，并从生产检索中移除了基准测试预期。

请阅读 0.32.3 更新日志中的完整说明。

文档

需求	从这里开始
首次运行	入门指南
Agent 设置	Agent 快速入门
CLI 和 MCP 工具	CLI 和 MCP 参考
上下文包	上下文包概念
新鲜度和自动刷新	自动刷新策略
索引覆盖率	索引完整性
隐私和 MCP 信任	威胁模型
证据和基准测试	声明与证据
路线图	公开路线图
发布历史	更新日志

参与贡献

目前最有帮助的贡献包括：在真实的 TypeScript 和 Node.js 仓库中进行测试、报告遗漏的上下文、改进 Windows/WSL/MCP 的可靠性、框架检测，以及更清晰的设置示例。

请针对 next 分支提交议题或拉取请求。提交 PR 前，请运行：

npm test
npm run build
npm run release:verify

请在 GitHub 贡献者页面查看完整的贡献者图谱。

贡献者

感谢所有为 Madar 添砖加瓦的人。以下列表会在每次推送到 main 时自动重新生成。

mohanagy

Gunselheli

qorexdevs

zhengjynicolas

jamemackson

特别感谢 @jamemackson 提交了 #54，这是 Madar 首个由社区贡献的功能。

许可证

MIT。随意使用、分叉并发布。