mohanagy/madar

# Madar **在编码代理开始搜索之前，为他们提供所需的仓库上下文。** Madar构建你的TypeScript/Node仓库的本地图，然后为Claude Code、Cursor、Codex、Copilot、Gemini、Aider和OpenCode等代理提供针对你提出的问题的任务感知上下文包。 它帮助代理减少重新发现相同文件、路由、导入和流程的时间。 [](https://www.npmjs.com/package/@lubab/madar) [](https://nodejs.org/) [](#privacy) [](https://github.com/mohanagy/madar/blob/main/LICENSE) ## 为什么 在大型仓库中，编码代理在回答问题之前往往会耗尽上下文： - 在无关文件夹中进行广泛的搜索 - 每次会话重复发现文件 - 由于第一个上下文太浅而编辑了错误的文件 Madar为代理提供了一个更小、基于仓库的起点。 它不会取代代理。它帮助代理从更好的证据开始。 ## 安装 ``` npm install -g @lubab/madar ``` Madar需要Node.js 20或更高版本。 ## 快速开始 在你的仓库中运行以下命令： ``` madar try "how does auth work?" ``` 该命令构建或重用本地图，打印第一个上下文包结果，并建议下一个安装命令。 对于手动流程： ``` madar generate . madar summary madar doctor madar status ``` 然后连接一个代理： ``` madar claude install ``` 现在向你的代理提出正常的仓库问题： ``` How does auth work? Where is the report generated? Add telemetry to this flow. Why does this endpoint return 403? ``` 代理可以在进行原始仓库搜索之前向Madar请求相关文件、符号、代码片段和关系。 ## 支持的代理 ``` madar claude install madar codex install madar cursor install madar copilot install madar gemini install madar aider install madar opencode install ``` 安装配置文件后，运行`madar doctor`和`madar status`。安装器详细信息请参阅[CLI和MCP参考](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md). ## 无MCP使用 您还可以直接从CLI生成上下文： ``` madar pack "how does auth work?" --task explain --format text ``` 创建一个代理准备好的提示： ``` madar prompt "how does auth work?" --provider claude ``` 创建一个安全的交接，用于其他编码工具： ``` madar handoff "add auth telemetry" --task implement --consumer copilot ``` ## 它构建了什么 Madar分析你的本地仓库，并创建一个文件、导入、导出、符号、路由、处理程序、调用关系、依赖关系、框架元数据和任务相关代码片段的图。 该图存储在项目输出文件夹中。 ## 适用性 Madar在以下情况下最有用： - 你的仓库是中等或大型 - 项目是TypeScript或Node.js - 代理经常打开太多文件 - 你询问架构、流程、审查或影响问题 - 在编辑之前想要更多任务感知的上下文 - 令牌使用、延迟或本地仓库隐私很重要 当以下情况发生时，Madar的帮助较少： - 仓库很小 - 任务可以从一个文件中明显看出 - 问题需要实时运行时行为 - 代码严重依赖于静态分析无法看到的动态模式 - 大型仓库更改后生成的图已过时 如果仓库变化很大，请重新生成： ``` madar generate . ``` ## 新鲜度 Madar记录图的 freshness，以便代理可以判断上下文是否仍然与仓库匹配。在git工作区中，freshness 与图构建提交加上工作树 diff 相关联，因此无关更改默认不会阻塞专注的任务。 ``` madar pack "how does auth work?" --require-fresh-context madar pack "how does auth work?" --require-fresh-graph ``` 当所选文件必须新鲜时，请使用`--require-fresh-context`。当整个图必须与当前仓库匹配时，请使用`--require-fresh-graph`。 ## 证据 在一个经过验证的GoValidate后端解释任务中，Madar减少了： | 指标 | 没有Madar | 有Madar | | --- | ---: | ---: | | 工具调用 | 28 | 7 | | 输入令牌 | 2,366,946 | 498,688 | | 墙上时钟延迟 | 158,995 毫秒 | 72,420 毫秒 | | 成本 | $2.6595 | $0.9728 | 这不是一个通用的基准声明。这是一个仓库、一个提示、一个代理运行时和一个经过验证的安装路径。 公共证据映射跟踪已证明的内容、混合的内容以及尚未声明的声明：[声明和证据](https://github.com/mohanagy/madar/blob/main/docs/claims-and-evidence.md). ## 隐私 Madar在本地运行。生成图不需要API密钥或云服务。你的代码不会通过Madar图生成离开你的机器。 你的编码代理可能仍然会根据该代理的配置将其提示或所选文件上下文发送到其自己的模型提供商。 将每个本地MCP安装、钩子或代理配置文件视为你的本地信任边界的一部分。威胁模型在此处记录：[MCP威胁模型](https://github.com/mohanagy/madar/blob/main/docs/security/mcp-threat-model.md). ## 遥测 除非你明确启用，否则遥测是禁用的。 ``` madar telemetry status madar telemetry enable madar telemetry disable madar telemetry clear madar telemetry report MADAR_ENABLE_TELEMETRY=1 madar generate . ``` 它不会记录提示文本、答案文本、源路径、源内容或仓库名称。完整控制：[docs/telemetry.md](https://github.com/mohanagy/madar/blob/main/docs/telemetry.md). ## 新增功能 当前版本：`0.27.9`。 此版本包括稳定的下一个跟踪采用包：一键`madar try`流程、可选遥测、经过验证的代理快速入门、公共基准套件工作、freshness改进和Windows Claude工作流程修复。 阅读完整的说明请参阅[0.27.9变更日志](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md#0279---2026-06-04). ## 文档 | 需要 | 链接 | | --- | --- | | 首次运行 | [入门](https://github.com/mohanagy/madar/blob/main/docs/tutorials/getting-started.md) | | 代理设置 | [代理快速入门](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md) | | CLI和MCP工具 | [CLI和MCP参考](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md) | | 上下文包模型 | [上下文包](https://github.com/mohanagy/madar/blob/main/docs/concepts/context-packs.md) | | 声明和限制 | [声明和证据](https://github.com/mohanagy/madar/blob/main/docs/claims-and-evidence.md) | | 基准测试 | [基准套件](https://github.com/mohanagy/madar/blob/main/docs/benchmarks/suite/README.md) | | 路线图 | [路线图](https://github.com/mohanagy/madar/blob/main/docs/roadmap.md) | | 变更日志 | [变更日志](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md) | ## 贡献 目前最有用的贡献是： - 在真实的TypeScript和Node.js仓库上测试Madar - 报告上下文包遗漏重要文件的情况 - 提高Windows、WSL和MCP设置的可靠性 - 为常见的仓库模式添加框架检测 - 使用真实设置示例改进文档 对于活跃的开发，请针对`next`分支打开问题或PR。 在打开PR之前，请运行： ``` npm test npm run build npm run release:verify ``` 在[GitHub贡献者](https://github.com/mohanagy/madar/graphs/contributors)上查看完整的贡献者图。 ## 贡献者 感谢每一位塑造Madar的人。以下列表在每次向`main`推送时自动更新。

mohanagy

Gunselheli

qorexdevs

zhengjynicolas

jamemackson

特别感谢[@jamemackson](https://github.com/jamemackson)为[#54](https://github.com/mohanagy/madar/pull/54)，这是Madar的第一个社区贡献功能。 ## 许可证 MIT。使用它，分叉它，分发它。

标签：Aider, AI 辅助开发, Claude Code, Codex, Copilot, Cursor, Gemini, GNU通用公共许可证, Madar, MITM代理, Node.js, npm, OpenCode, TypeScript, 代码上下文, 代码优化, 代码分析, 代码助手, 代码复用, 代码审查, 代码导航, 代码库管理, 代码推荐, 代码搜索, 代码智能, 代码理解, 代码生成, 代码编辑, 凭证管理, 安全可观测性, 安全插件, 开发效率, 数据管道, 本地化搜索, 渗透测试工具, 版本控制, 网络可观测性, 自动化攻击, 软件工程