<img src="assets/jinni_banner_1280x640.png" alt="Jinni Banner" width="400"/>

Jinni: 将你的项目带入上下文

Jinni 是一个高效的工具，可以为大型语言模型提供你的项目上下文。它提供了一个包含相关项目文件的整合视图，并附带元数据，克服了逐个读取文件的局限性和低效率。

这个工具背后的理念是，LLM 的上下文窗口很大，模型很智能，直接看到你的项目能最好地帮助模型处理你提出的任何问题。

有一个 MCP（模型上下文协议）服务器用于与 AI 工具集成，以及一个命令行实用程序（CLI）用于手动使用，它将项目上下文复制到剪贴板，随时可以粘贴到你需要的地方。

这些工具对什么算作相关的项目上下文有自己的看法，以便在大多数用例中开箱即用，自动排除：

* 二进制文件
* 点文件和隐藏目录
* 日志、构建目录、临时文件等的常见命名约定

如果需要，可以使用 .contextfiles 完全自定义包含/排除项 - 这类似于 .gitignore，但定义的是包含项。

MCP 服务器可以提供尽可能多或尽可能少的项目内容。默认情况下，范围是整个项目，但模型可以要求提供特定的模块/匹配模式/等等。

MCP 快速入门

Cursor / Roo / Claude Desktop / 选择的客户端的 MCP 服务器配置：

{
    "mcpServers": {
    "jinni": {
        "command": "uvx jinni-server"
        // 可选地限制服务器仅在树中读取（推荐用于安全）：
        // "command": "uvx jinni-server --root /absolute/path/"
    }
    }
}

如果你的系统上没有 uv，请安装它：https://docs.astral.sh/uv/getting-started/installation/

重新加载你的 IDE，现在你可以要求代理读取上下文。

如果你想将其限制为特定的模块/路径，只需询问 - 例如“读取测试的上下文”。

在 Cursor 中的实际应用：

<img src="assets/use_example.png" alt="Usage Example">

Cursor 用户须知

Cursor 可能会静默地丢弃大于允许的最大值的上下文，因此如果你的项目很大，并且代理的行为就像工具调用从未发生过一样，请尝试减少你引入的内容（“读取 xyz 的上下文”）

组件

1. jinni MCP 服务器：

   • 与 Cursor、Cline、Roo、Claude Desktop 等 MCP 客户端集成。
   • 公开一个 read_context 工具，该工具返回一个连接的字符串，其中包含来自指定项目目录的相关文件内容。

2. jinni CLI：

   • 一个用于手动生成项目上下文转储的命令行工具。
   • 可用于通过复制粘贴或文件输入将上下文馈送到 LLM。或者将输出管道传输到你需要的地方。

特性

• 高效的上下文收集： 在一个操作中读取和连接相关的项目文件。
• 智能过滤（Gitignore 风格的包含）：
  • 使用基于 .gitignore 语法的系统（pathspec 库的 gitwildmatch）。
  • 支持使用放置在项目目录中的 .contextfiles 进行分层配置。规则根据正在处理的文件/目录动态应用。
  • 匹配行为： 模式匹配相对于正在处理的目标目录的路径（如果未给出特定目标，则匹配项目根目录）。例如，如果目标是 src/，则 src/.contextfiles 中的规则 !app.py 将匹配 app.py。输出路径仍然相对于原始项目根目录。
  • 覆盖： 支持 --overrides (CLI) 或 rules (MCP) 以专门使用一组特定的规则。当覆盖处于活动状态时，内置的默认规则和任何 .contextfiles 都将被忽略。覆盖的路径匹配仍然相对于目标目录。
  • 显式目标包含： 显式提供为目标的文件始终包含在内（绕过规则检查，但不绕过二进制/大小检查）。显式提供为目标的目录始终进入，然后相对于该目标目录继续进行规则发现/匹配。
• 可自定义的配置 (.contextfiles / 覆盖)：
  • 使用应用于相对路径的 .gitignore 风格的模式，精确定义要包含或排除的文件/目录。
  • 以 ! 开头的模式否定匹配（排除模式）。（请参阅下面的配置部分）。
• 大型上下文处理： 如果包含文件的总大小超过可配置的限制（默认值：100MB），则中止并显示 DetailedContextSizeError。错误消息包括一个导致大小增加的前 10 个最大文件的列表，帮助你识别排除的候选对象。有关管理上下文大小的指导，请参阅故障排除部分。
• 元数据标头： 输出包括每个包含文件的文件路径、大小和修改时间（可以使用 list_only 禁用）。
• 编码处理： 尝试多种常见的文本编码（UTF-8、Latin-1 等）。
• 仅列表模式： 选项仅列出将包含的文件的相对路径，而不包含其内容。

用法

MCP 服务器 (read_context 工具)

1. 设置： 配置你的 MCP 客户端（例如，Claude Desktop 的 claude_desktop_config.json）以通过 uvx 运行 jinni 服务器。
2. 调用： 通过 MCP 客户端与你的 LLM 交互时，模型可以调用 read_context 工具。
   • project_root (字符串，必需)： 项目根目录的绝对路径。规则发现和输出路径相对于此根目录。
   • targets (字符串的 JSON 数组，必需)： 指定要处理的 project_root 中文件/目录的强制性列表。必须是字符串路径的 JSON 数组（例如，["path/to/file1", "path/to/dir2"]）。路径可以是绝对路径或相对于 CWD 的路径。所有目标路径必须解析为 project_root 内的位置。如果提供一个空列表 []，则处理整个 project_root。
   • rules (字符串的 JSON 数组，必需)： 内联过滤规则的强制性列表（使用 .gitignore 风格的语法，例如，["src/**/*.py", "!*.tmp"]）。如果不需要特定规则，请提供一个空列表 []（这将使用内置的默认值）。如果非空，则专门使用这些规则，忽略内置的默认值和 .contextfiles。
   • list_only (布尔值，可选)： 如果为 true，则仅返回相对文件路径的列表，而不返回内容。
   • size_limit_mb (整数，可选)： 覆盖上下文大小限制（以 MB 为单位）。
   • debug_explain (布尔值，可选)： 在服务器上启用调试日志记录。
   3. 输出： 该工具返回一个包含连接内容（带有标头）或文件列表的单个字符串。标头/列表中的路径相对于提供的 project_root。如果出现上下文大小错误，它将返回一个 DetailedContextSizeError，其中包含有关最大文件的详细信息。

MCP 服务器 (usage 工具)

• 调用： 模型可以调用 usage 工具（不需要参数）。
• 输出： 将 README.md 文件的内容作为字符串返回。

（详细的服务器设置说明将因你的 MCP 客户端而异。通常，你需要配置客户端以执行 Jinni 服务器。）

运行服务器：

• 推荐方法： 使用 uvx 直接运行服务器入口点（需要将 jinni 包发布到 PyPI 或可由 uvx 找到）：

  uvx jinni-server [OPTIONS]
  

  示例 MCP 客户端配置（例如，claude_desktop_config.json）：

  {
    "mcpServers": {
      "jinni": {
        "command": "uvx jinni-server"
        // 可选地限制服务器仅在树中读取（推荐用于安全）：
        // "command": "uvx jinni-server --root /absolute/path/"
      }
    }
  }
  

请查阅你的特定 MCP 客户端的文档以获取精确的设置步骤。确保 uv（对于 uvx）或正确的 Python 环境（对于 python -m）可访问。usage 工具对应于 jinni usage CLI 命令。

命令行实用程序 (jinni CLI)

jinni [OPTIONS] [<PATH...>]

• <PATH...> (可选)： 要分析的项目目录或文件的一个或多个路径。如果未提供任何路径，则默认为当前目录 (.)。
• -r <DIR> / --root <DIR> (可选)： 指定项目根目录。如果提供，则规则发现从此处开始，并且输出路径相对于此目录。如果省略，则从 <PATH...> 参数的公共祖先（如果仅处理 '.'，则从 CWD）推断根目录。
• --output <FILE> / -o <FILE> (可选)： 将输出写入 <FILE> 而不是打印到标准输出。
• --list-only / -l (可选)： 仅列出将包含的文件的相对路径。
• --overrides <FILE> (可选)： 使用来自 <FILE> 的规则而不是发现 .contextfiles。
• --size-limit-mb <MB> / -s <MB> (可选)： 覆盖最大上下文大小（以 MB 为单位）。
• --debug-explain (可选)： 将详细的包含/排除原因打印到 stderr 和 jinni_debug.log。
• --root <DIR> / -r <DIR> (可选)： 见上文。
• --no-copy (可选)： 阻止在打印到标准输出时自动将输出内容复制到系统剪贴板（默认设置为复制）。

安装

你可以使用 pip 或 uv 安装 Jinni：

使用 pip：

pip install jinni

使用 uv：

uv pip install jinni

这将在你的环境中提供 jinni CLI 命令。有关如何根据你的安装方法启动 MCP 服务器，请参阅上面的“运行服务器”部分。

示例

• 将 my_project/ 的上下文转储到控制台：

  jinni ./my_project/ # 处理单个目录
  jinni ./src ./docs/README.md # 处理多个目标
  jinni # 处理当前目录 (.)
  

• 列出将包含在 my_project/ 中的文件，而不包含内容：

  jinni -l ./my_project/
  jinni --list-only ./src ./docs/README.md
  

• 将 my_project/ 的上下文转储到名为 context_dump.txt 的文件：

  jinni -o context_dump.txt ./my_project/
  

• 使用来自 custom.rules 的覆盖规则而不是 .contextfiles：

  jinni --overrides custom.rules ./my_project/
  

• 显示调试信息：

  jinni --debug-explain ./src
  

• 转储上下文（默认情况下，输出会自动复制到剪贴板）：

  jinni ./my_project/
  

• 转储上下文，但不复制到剪贴板：

  jinni --no-copy ./my_project/
  

配置 (.contextfiles & 覆盖)

Jinni 使用 .contextfiles（或覆盖文件）来确定要包含或排除哪些文件和目录，基于 .gitignore 风格的模式。

• 核心原则： 规则在遍历期间动态应用，相对于正在处理的当前目标目录。
• 位置 (.contextfiles)： 将 .contextfiles 放置在任何目录中。当处理目录（无论是初始目标还是子目录）时，Jinni 从该目录向下查找 .contextfiles。当在该目标内进行处理时，来自当前目标目录外部的父目录的规则将被忽略。
• 格式： 纯文本，UTF-8 编码，每行一个模式。
• 语法： 使用标准的 .gitignore 模式语法（特别是 pathspec 的 gitwildmatch 实现）。
  • 注释： 以 # 开头的行将被忽略。
  • 包含模式： 指定要包含的文件/目录（例如，src/**/*.py、*.md、/config.yaml）。
  • 排除模式： 以 ! 开头的行表示应排除匹配的文件（否定模式）。
  • 锚定： 前导 / 将模式锚定到包含 .contextfiles 的目录。
  • 目录匹配： 尾随 / 仅匹配目录。
  • 通配符： *、**、? 的工作方式与 .gitignore 中相同。
• 规则应用逻辑：
  1. 确定目标： Jinni 标识目标目录（显式提供或项目根目录）。
  2. 覆盖检查： 如果提供了 --overrides (CLI) 或 rules (MCP)，则专门使用这些规则。所有 .contextfiles 和内置的默认值都将被忽略。路径匹配相对于目标目录。
  3. 动态上下文规则（无覆盖）： 当处理目标目录中的文件或子目录时：
     • Jinni 查找从目标目录到当前项目的目录的所有 .contextfiles。
     • 它将来自这些发现的 .contextfiles 的规则与内置的默认规则组合在一起。
     • 它将这些组合的规则编译成规范 (PathSpec)。
     • 它将当前文件/子目录路径（相对于目标目录计算）与此规范进行匹配。
  4. 匹配： 组合规则集中与项目的相对路径匹配的最后一个模式决定了它的命运。! 否定匹配。如果没有用户定义的模式匹配，则除非该项目匹配内置的默认排除项（如 !.*），否则该项目将被包含在内。
  5. 目标处理： 显式定位的文件绕过规则检查。显式定位的目录成为规则发现和匹配其内容的根目录。输出路径始终相对于原始 project_root。

示例 (.contextfiles)

示例 1：包含 Python 源代码和根配置

位于 my_project/.contextfiles：

# 包含 src 目录及其子目录中的所有 Python 文件
src/**/*.py

# 包含项目根目录中的主配置文件
/config.json

# 包含任何位置的所有 markdown 文件
*.md

# 排除任何位置找到的任何测试数据目录
!**/test_data/

示例 2：在子目录中覆盖

位于 my_project/src/.contextfiles：

# 除了从父 .contextfiles 继承的规则之外...

# 包含此目录中的特定实用程序脚本
utils/*.sh

# 排除 src 中的特定生成文件，即使在其他地方包含 *.py
!generated_parser.py

开发

• 设计细节： DESIGN.md

• 在本地运行服务器： 在开发期间（在使用 uv pip install -e . 或类似命令安装后），你可以直接运行服务器模块：

  python -m jinni.server [OPTIONS]
  

  用于本地开发的示例 MCP 客户端配置：

  {
    "mcpServers": {
      "jinni": {
        // 如果需要，调整 python 路径，或确保正确的环境处于活动状态
        "command": "python -m jinni.server"
        // 可选地限制服务器仅在树中读取（推荐用于安全）：
        // "command": "python -m jinni.server --root /absolute/path/to/repo"
      }
    }
  }
  

故障排除

上下文大小错误 (DetailedContextSizeError)

如果你遇到指示超出上下文大小限制的错误，Jinni 将提供它尝试包含的前 10 个最大文件的列表。这有助于你识别排除的潜在候选对象。

要解决此问题：

1. 查看最大的文件： 检查错误消息中提供的列表。是否有不应成为 LLM 上下文一部分的大文件（例如，数据文件、日志、构建工件、媒体）？
2. 配置排除项： 使用 .contextfiles 或 --overrides / rules 选项排除不必要的文件或目录。
   • 示例 (.contextfiles)： 要排除所有 .log 文件和特定的大型数据目录：

     # 排除所有日志文件
     !*.log
     
     # 排除大型数据目录
     !large_data_files/
     

   • 有关详细的语法和用法，请参阅上面的配置部分。
3. 增加限制（谨慎使用）： 如果所有包含的文件都是真正必要的，你可以使用 --size-limit-mb (CLI) 或 size_limit_mb (MCP) 增加大小限制。请注意 LLM 上下文窗口限制和处理成本。
4. 使用 jinni usage / usage： 如果你在进行故障排除时需要参考这些说明或配置详细信息，请使用 jinni usage 命令或 usage MCP 工具。