devmap

DevMap

分析一次，处处复用上下文。 一款为开发者和 AI Agent 绘制代码库地图的命令行工具：入口点、关键文件、功能和路由。

文档 · 网站 · GitHub

每次与 AI 开启有关代码的新对话，都得从头开始——每次都要重新解释同一个代码库。DevMap 可以解决这个问题。

它是一款命令行工具，结合静态分析与可选的 AI 解读，一次性为项目构建结构化、可复用的理解层。这个理解层（.devmap/index.json、功能地图、DEVMAP.md）可供你和任何 AI Agent 后续读取，无需重新扫描或粘贴整个代码库。完整的代码库源码始终保留在本地，不会整体发送给 AI 模型。

安装

npm install --global @flaid/devmap

也可以无需全局安装直接运行：

npx @flaid/devmap --help

要求

• Node.js 22.12 或更高版本
• AI 提供商的 API 密钥：Groq、OpenRouter，或任何自定义的 OpenAI 兼容端点

未配置 AI 时，静态分析仍可正常工作。

快速开始

在你想要了解的项目根目录中运行以下命令：

devmap init
devmap analyze
devmap onboarding
devmap doctor

devmap init 会选择提供商、验证其密钥、在本地保存配置、准备 .devmap/、生成 DEVMAP.md，并安全地集成到 AGENTS.md 中。

配置 AI 提供商

在运行以下命令时，使用方向键选择 Groq、OpenRouter 或自定义的 OpenAI 兼容端点：

devmap init

Groq 密钥可在 https://console.groq.com/keys 获取。OpenRouter 密钥可在 https://openrouter.ai/keys 获取。

对于自定义端点，DevMap 会询问基础 URL（预填为 http://localhost:20128/v1），并列出服务器提供的模型，因此任何 OpenAI 兼容的可自托管网关都可以开箱即用。

对于 OpenRouter，DevMap 会提示：

OpenRouter model [openrouter/free]:

按 Enter 使用免费路由器，或输入任意免费或付费的 OpenRouter 模型 ID。所选模型会被保存，并作为首选模型使用。

以非交互方式配置 Groq：

GROQ_API_KEY="your-key" devmap init

在 PowerShell 中：

$env:GROQ_API_KEY="your-key"
devmap init
Remove-Item Env:GROQ_API_KEY

以非交互方式配置 OpenRouter：

OPENROUTER_API_KEY="your-key" devmap init

密钥会保存在本地的 ~/.devmap/config.json 中。请求会从你的计算机直接发送到所选提供商。DevMap 不会将密钥发送到 DevMap 自有服务器。

命令

devmap init
devmap analyze
devmap analyze --fresh
devmap map                    # full project map
devmap map <feature-or-file>  # scoped to one feature or file
devmap flow                   # curated top flows
devmap flow <feature-or-route>
devmap explain <target>       # file, feature, or function
devmap onboarding --write
devmap onboarding --write --language id
devmap doctor
devmap config model auto
devmap mcp                    # run as an MCP server

Groq 和 OpenRouter 使用 init 期间选择的模型。使用以下命令更改任一提供商的模型：

devmap config model <model-id>
devmap config model auto

MCP 服务

devmap mcp 会通过 stdio 将 DevMap 作为 Model Context Protocol 服务运行。AI Agent 可通过工具调用询问项目地图相关问题，并获取结构化 JSON，而无需一开始就读取整个上下文文件。

devmap analyze
claude mcp add devmap -- npx -y @flaid/devmap mcp

其他客户端可将同一命令（npx -y @flaid/devmap mcp）作为 stdio 服务启动：

{
  "mcpServers": {
    "devmap": {
      "command": "npx",
      "args": ["-y", "@flaid/devmap", "mcp"]
    }
  }
}

工具：devmap_overview、devmap_map、devmap_flow、devmap_routes、devmap_impact、devmap_find、devmap_analyze，以及仅在使用 --allow-ai 时提供的 devmap_explain。

此服务默认只读且仅使用静态分析：除非使用 --allow-ai 启动，否则不会联系 AI 提供商；只有在 Agent 调用 devmap_analyze 或使用 --auto-refresh 启动时，才会在 .devmap/ 中写入内容。每个回答都会说明快照是否已过时。有关客户端配置和工具输入，请参阅 MCP 指南。

生成的上下文

DevMap 会生成：

• .devmap/index.json，用于轻量级 AI Agent 导航
• .devmap/features/*.json，用于聚焦的功能映射和源码优先级
• .devmap/snapshot.json，用于完整的结构化项目分析存档
• DEVMAP.md，用于提供面向人类和 AI Agent 的使用指南
• 仅在确认后，才会在文件已存在时向 AGENTS.md 添加一小段 DevMap 内容

现有的 AGENTS.md 和 DEVMAP.md 文件绝不会被覆盖。

面向 AI Agent

首先读取 .devmap/index.json，打开相关的功能映射，并检查其中的 sourcePriority 文件。只有在轻量级导航层无法满足需求时，才使用 .devmap/snapshot.json。

脚本、编辑器、CI 或 AI Agent 请使用 --json：

devmap analyze --json
devmap onboarding --json
devmap doctor --json

JSON 模式会向 stdout 写入一个可解析的 JSON 文档，不含 ANSI 颜色、终端装饰或流式分段输出。

支持的技术栈

• 前端：Next.js、Astro、SvelteKit、Nuxt、Remix、React Router v7、TanStack Router/Start、Expo Router、SolidStart、Qwik City、Angular、React、Vue、Svelte
• 后端：Express、NestJS、Fastify、Hono、Elysia、Koa、AdonisJS

检测涵盖上述完整列表；Next.js 和 Express 会进行最深入的分析。多包工作区会按项目类型分类，因此，包含 CLI 和 Web 应用的单体仓库会同时报告这两种类型。

隐私

• 项目分析会在本地运行，然后再进行 AI 解读。
• 不会将完整的仓库源码发送给所选服务商。
• .env 文件和常见的生成目录会被忽略。
• API 密钥会存储在本地，绝不应提交。

链接

• 仓库：https://github.com/itsflaid/devmap
• 问题反馈：https://github.com/itsflaid/devmap/issues
• 更新日志：https://github.com/itsflaid/devmap/blob/main/CHANGELOG.md

许可证

MIT