Jinni: Bring Your Project Into Context

Jinni：将您的项目纳入背景

Jinni 是一款高效地为大型语言模型提供项目上下文的工具。它提供了相关项目文件的统一视图，克服了逐个读取文件的局限性和低效性。每个文件的内容前面都有一个简单的文件头，指示其路径：

该工具背后的理念是，LLM 上下文窗口很大，模型很智能，并且直接查看您的项目可以最好地使模型帮助您解决任何问题。

有一个用于与 AI 工具集成的 MCP（模型上下文协议）服务器和一个用于手动使用的命令行实用程序（CLI），可将项目上下文复制到剪贴板，以便粘贴到您需要的任何位置。

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

如果需要，可以使用.contextfiles以完全粒度的方式自定义包含/排除 - 这与.gitignore类似，只是定义了包含项.gitignore文件本身也会自动得到尊重，但.contextfiles中的任何规则都优先。

MCP 服务器可以根据需要提供项目所需的内容。默认情况下，范围是整个项目，但模型可以请求特定的模块/匹配模式等。

MCP 快速入门

适用于 Cursor / Roo / Claude Desktop / 客户端的 MCP 服务器配置文件：

您可以选择限制服务器仅在树内读取以确保您的 LLM 出现问题时的安全：将"--root", "/absolute/path/"添加到args列表中。

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

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

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

使用 Cursor 进行操作：

光标用户须知

游标可以悄悄地删除大于允许最大值的上下文，因此，如果您有一个相当大的项目，并且代理的行为就像工具调用从未发生过一样，请尝试减少您引入的内容（“读取 xyz 的上下文”）

成分

1. jinni MCP 服务器:
   • 与 Cursor、Cline、Roo、Claude Desktop 等 MCP 客户端集成。
   • 公开一个read_context工具，该工具从指定的项目目录返回相关文件内容的连接字符串。
2. jinni命令行界面：
   • 用于手动生成项目上下文转储的命令行工具。
   • 适用于通过复制粘贴或文件输入向 LLM 提供上下文。或者将输出通过管道传输到任何需要的地方。

特征

• **高效的上下文收集：**在一次操作中读取并连接相关的项目文件。
• 智能过滤（Gitignore 风格包含）：
  • 使用基于.gitignore语法（ pathspec库的gitwildmatch ）的系统。
  • 自动从项目根目录向下加载.gitignore文件。这些排除项可以被.contextfiles中的规则覆盖。
  • 支持使用放置在项目目录中的.contextfiles进行分层配置。规则会根据正在处理的文件/目录动态应用。
  • 匹配行为：模式会根据正在处理的目标目录（如果未指定具体目标，则为项目根目录）的相对路径进行匹配。例如，如果目标是src/ ，则src/.contextfiles中的规则!app.py将匹配app.py 。输出路径仍相对于原始项目根目录。
  • **覆盖：**支持--overrides （CLI）或 rules（MCP） rules ，以独占使用一组特定的规则。当覆盖启用时，内置默认规则和任何.contextfiles都将被忽略。覆盖的路径匹配仍然相对于目标目录。
  • **显式目标包含：**显式指定为目标的文件始终会被包含（绕过规则检查，但不会绕过二进制/大小检查）。显式指定为目标的目录始终会被输入，然后规则发现/匹配将相对于该目标目录进行。
• 可定制配置（ .contextfiles / Overrides）：
  • 使用应用于相对路径的.gitignore样式模式精确定义要包含或排除的文件/目录。
  • 以!开头的模式否定匹配（排除模式）。（请参阅下面的“配置”部分）。
• **大型上下文处理：**如果包含的文件总大小超过可配置的限制（默认值：100MB），则会中止并抛出DetailedContextSizeError错误。错误消息会列出造成大小差异最大的10个文件，帮助您确定需要排除的文件。有关管理上下文大小的指导，请参阅“故障排除”部分。
• **元数据标头：**输出包含每个包含文件的路径标头（例如，````path=src/app.py` ). This can be disabled with 。
• **编码处理：**尝试多种常见的文本编码（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 （布尔值，可选）：**如果为真，则仅返回相对文件路径列表而不是内容。
   • **size_limit_mb （整数，可选）：**覆盖上下文大小限制（以 MB 为单位）。
   • **debug_explain （布尔值，可选）：**在服务器上启用调试日志记录。
   3. **输出：**该工具返回一个包含连接内容（带标题）或文件列表的字符串。标题/列表中的路径相对于提供的project_root 。如果出现上下文大小错误，它将返回一个DetailedContextSizeError错误，其中包含有关最大文件的详细信息。

MCP 服务器（ usage工具）

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

（详细的服务器设置说明将根据您的 MCP 客户端而有所不同。通常，您需要配置客户端来执行 Jinni 服务器。）

运行服务器：

• **推荐方法：**使用uvx直接运行服务器入口点（需要在 PyPI 上发布jinni包或uvx可以找到该包）：
  uvx jinni-server [OPTIONS]
  MCP 客户端配置示例（例如， claude_desktop_config.json ）：
  { "mcpServers": { "jinni": { "command": "uvx", "args": ["jinni-server"] } } }

您可以选择限制服务器仅在树内读取以确保您的 LLM 出现问题时的安全：将"--root", "/absolute/path/"添加到args列表中。

请参阅特定 MCP 客户端的文档，了解精确的设置步骤。确保已安装uv

命令行实用程序（ jinni CLI）

• **<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：

使用紫外线：

这将使jinni CLI 命令在您的环境中可用。请参阅上面的“运行服务器”部分，了解如何根据您的安装方式启动 MCP 服务器。

特定于平台的说明

Windows + WSL

Jinni v0.1.7+ 自动转换 WSL 路径。

提供以下任一内容作为project_root （CLI --root或 MCP 参数）：

无需包装器、挂载或额外标志 - Jinni 会自动解析 Windows 上的 UNC 路径（ \\wsl$\... ）。

UNC 路径格式： Jinni 始终使用\\wsl$\<distro>\...格式，以便与所有支持 WSL 的 Windows 版本实现最大兼容性。**发行版名称处理：**发行版名称中允许使用空格和大多数特殊字符。只有真正非法的 UNC 字符才会被替换为_ 。缓存： WSL 路径查找和转换会被缓存以提高性能。如果您在 Jinni 运行时安装 WSL，请重新启动 Jinni 以应用新的wslpath 。**选择退出：**设置环境变量JINNI_NO_WSL_TRANSLATE=1以禁用所有 WSL 路径转换逻辑。

仅翻译wsl+<distro> URI 和绝对 POSIX 路径（以/开头）；对于 SSH 或容器远程，在该环境中运行 Jinni。

示例

• 将my_project/的上下文转储到控制台：
  jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
• 列出将包含在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 从目标目录开始到当前项目目录查找所有.gitignore和.contextfiles 。
     • 首先应用.gitignore中的规则，然后是内置默认值，最后是任何.contextfiles （优先）。
     • 它将这些组合规则编译成一个规范（ PathSpec ）。
     • 它根据此规范匹配相对于目标目录计算的当前文件/子目录路径。
  4. 匹配：组合规则集中最后一个与项目相对路径匹配的模式决定了它的命运。 !表示否定匹配。如果没有用户定义的模式匹配，则该项目会被包含，除非它匹配内置的默认排除项（例如!.* ）。
  5. **目标处理：**明确指定的目标文件会绕过规则检查。明确指定的目录将成为规则发现和匹配其内容的根目录。输出路径始终相对于原始project_root 。

示例（ .contextfiles ）

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

位于my_project/.contextfiles ：

示例 2：在子目录中覆盖

位于my_project/src/.contextfiles ：

发展

• 设计细节： DESIGN.md
• **本地运行服务器：**在开发过程中（使用uv pip install -e .或类似命令安装后），您可以直接运行服务器模块：
  python -m jinni.server [OPTIONS]
  本地开发的 MCP 客户端配置示例：
  { "mcpServers": { "jinni": { // Adjust python path if needed, or ensure the correct environment is active "command": "python -m jinni.server" // Optionally constrain the server to only read within a tree (recommended for security): // "command": "python -m jinni.server --root /absolute/path/to/repo" } } }

故障排除

上下文大小错误（ DetailedContextSizeError ）

如果您遇到指示超出上下文大小限制的错误，Jinni 将提供其尝试包含的 10 个最大文件的列表。这有助于您识别可能需要排除的文件。

要解决此问题：

1. **检查最大文件：**检查错误消息中提供的列表。是否存在不应包含在 LLM 上下文中的大文件（例如，数据文件、日志、构建工件、媒体文件）？
2. **配置排除：**使用.contextfiles或--overrides / rules选项排除不必要的文件或目录。
   • **示例（ .contextfiles ）：**要排除所有.log文件和特定的大型数据目录：
     # Exclude all log files !*.log # Exclude a large data directory !large_data_files/
   • 有关详细语法和用法，请参阅上面的配置部分。
3. **增加限制（谨慎使用）：**如果所有包含的文件确实有必要，可以使用--size-limit-mb (CLI) 或size_limit_mb (MCP) 增加大小限制。请注意 LLM 上下文窗口的限制和处理成本。
4. **使用jinni usage / usage ：**如果您在排除故障时需要参考这些说明或配置详细信息，请使用jinni usage命令或usage MCP 工具。