Agents Md Generator

兼容任何支持 MCP 的客户端：Claude Code、Gemini CLI、Cursor、Windsurf、Codex CLI 等。

该服务提供了三个职责明确的工具：

• generate_agents_md — 主入口。内部运行分析流程，将写入规则嵌入负载，并向客户端返回分块读取说明。
• scan_codebase — 独立的上下文工具，适用于需要深入了解代码库但不生成任何文件的场景。
• read_payload_chunk — 无论负载由哪个工具生成，都会以分块形式传回。

不会有大量数据通过 MCP 线路传输。

目录

• 安装
  • 选项 A — 使用 pip 安装 + 设置向导
  • 选项 B — uvx
• 使用方法
  • 工具
  • 工具参数
• 生成内容
• 增量扫描的工作原理
  • 大型负载如何分块传输
  • 缓存和负载位置
• 项目配置
  • 选项
  • 环境变量
  • 项目大小配置
• 分析可检测的内容
• 致谢

安装

要求： Python 3.11+、Git，以及任何支持 MCP 的客户端。

有关完整指南（包括先决条件和故障排除），请参阅 INSTALLATION.md。

选项 A — 使用 pip 安装 + 设置向导（推荐）

pip install agents-md-generator
agents-md-generator setup

设置向导会检测已安装的客户端，询问是进行全局配置还是按项目配置，并自动修改配置文件。支持 Claude Code、Gemini CLI、Cursor、Windsurf 和 Codex CLI。

选项 B — uvx（无需安装）

如果已安装 uv，uvx 无需预先安装即可运行此软件包。请在客户端的 MCP 配置中手动添加条目：

{
  "mcpServers": {
    "agents-md": {
      "command": "uvx",
      "args": ["agents-md-generator"]
    }
  }
}

具体针对 Claude Code：

claude mcp add agents-md -- uvx agents-md-generator

claude mcp add 默认使用 --scope local（仅限当前项目）。添加 -s user 可将其注册到所有项目。

使用方法

注册后，向 AI 客户端提出请求：

“为此项目生成 AGENTS.md”

客户端会自动调用 generate_agents_md。若要扫描其他目录：

“为位于 /path/to/project 的项目生成 AGENTS.md”

工具

工具参数

生成内容

生成的 AGENTS.md 遵循 agents.md 开源标准。它是面向 AI Agent 的 README，而不是面向人类的文档。包含以下章节：

完全省略未检测到数据的章节。

增量扫描的工作方式

1. 首次运行（冷启动） — 使用 tree-sitter 解析所有由 git 跟踪的源文件并缓存
2. 后续运行 — 仅重新解析自上次扫描以来 SHA-256 哈希发生变化的文件
3. 语义差异 — 对于已修改的文件，负载中仅包含发生变化的公共符号
4. 源文件没有变化？ — 工具会停止，并询问你是否仍想改进现有的 AGENTS.md 内容
5. 私有符号和测试文件内部内容会同时从缓存和负载中排除 — 对 AGENTS.md 而言，只有公共 API 表面重要

大型负载如何分块传输

对于大型代码库，分析负载可能过大，无法通过 MCP 线路以内联方式返回。服务会通过 read_payload_chunk 透明地处理这种情况。

扫描会在独立进程中运行，并发送阶段进度通知，超时时间为五分钟。取消操作会停止扫描工作进程。在一个服务实例中，每个项目一次只能运行一个扫描；对于超出时限的仓库，请使用 .agents-config.json 缩小分析范围。

生成操作始终会组装当前快照，并为未更改的源文件复用缓存的符号。即使负载已被读取或运行了其他扫描，中断的生成操作也可以重试。客户端仍需负责写入 AGENTS.md。

序列化负载最多为 300,000 个字符。被丢弃的分析部分会记录在 metadata.degradations 和 metadata.truncated_sections 中。现有的 AGENTS.md 内容和写入说明会得到保留；如果仅这些内容就超出预算，工具会返回错误，而不是截断文档。

此流程完全通过 MCP 完成——客户端无需访问文件系统。任何兼容 MCP 的客户端都可以按此流程操作。

缓存和负载位置

所有运行时产物都存储在项目之外的用户缓存目录中：

~/.cache/agents-md-generator/<project-hash>/cache.json  ← incremental scan cache

<project-hash> 是项目绝对路径的 SHA-256 哈希值——每个项目各不相同。不会向你的仓库写入任何内容。

**注意：**分析期间，服务也会在此目录中写入临时的 payload.json，但它完全由 read_payload_chunk 工具管理，并会在读取最后一个分块后自动删除。你无需直接访问它。

项目配置

在项目根目录下创建 .agents-config.json 以自定义行为。此文件为可选项——所有字段均有默认值，你可以将其提交到代码仓库，与团队共享设置。

{
  "project_size": "medium",
  "exclude": [
    "**/node_modules/**",
    "**/bin/**",
    "**/obj/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/__pycache__/**",
    "**/*.min.js",
    "**/*.min.css",
    "**/*.bundle.js",
    "**/vendor/**",
    "**/packages/**",
    "**/.venv/**",
    "**/venv/**",
    "**/bower_components/**",
    "**/app/lib/**",
    "**/wwwroot/lib/**",
    "**/wwwroot/libs/**",
    "**/static/vendor/**",
    "**/public/vendor/**",
    "**/assets/vendor/**",
    "**/site-packages/**"
  ],
  "include": [],
  "languages": "auto",
  "agents_md_path": "./AGENTS.md",
  "max_file_size_bytes": 1048576
}

选项

环境变量

项目规模配置文件

project_size 设置用于控制负载压缩的力度。一个参数即可调整所有内部上限——每个类的方法数、每个文件的符号数、目录聚合、路由上限、目录树深度和影响过滤。

分析检测内容

环境变量

服务会使用特定于语言的模式扫描所有源文件，查找环境变量引用：

它还会解析项目根目录下的 .env.example、.env.template 和 .env.sample 文件。

入口点

名为 index、main、app、server、program、bootstrap 或 startup 的文件（扩展名不限，只要受支持）会被识别为入口点，并标注推断出的角色（例如，“HTTP 服务引导程序”、“Electron 主进程”）。

公共 API 范围

Tree-sitter 会解析每个源文件并提取公共符号——类、函数、方法和接口——同时过滤掉私有或受保护成员以及以下划线开头的符号。对于类和结构体，也会包含构造函数（当其有参数时）和公共属性，从而揭示依赖注入模式和数据结构。接口方法始终会被纳入，因为它们定义了公共契约。以上信息用于检测各层的命名约定、DI 模式和导出契约。

架构提炼

对于大型代码库，工具会应用多种启发式方法，以确保负载始终包含高价值信息：

• 样板代码抑制 — Migrations、bin、obj 和 Properties 等常见目录会被自动标记，并在项目结构中折叠，避免它们使目录列表过于庞大。
• 低熵摘要 — 主要包含数据结构（DTO、实体）且没有逻辑方法的文件会被“精简”。工具不会逐一列出所有属性，而是提供高层摘要（例如，“包含 25 个 DTO 类”）。
• 语义聚类 — 聚合器会在目录层级对这些精简摘要进行分组，让使用结果的 AI 能通过单行高价值信息理解整个数据层。
• 指令嵌入 — 通过 generate_agents_md 调用时，负载中会直接嵌入编写规则，让 AI agent 在处理代码架构之前先阅读“参与规则”。直接调用 scan_codebase 会返回纯数据，不附带任何约束。

致谢

AGENTS.md 格式基于开放的 agents.md 标准。