Jinni：将您的项目纳入背景
Jinni 是一款高效地为大型语言模型提供项目上下文的工具。它提供了相关项目文件的统一视图，克服了逐个读取文件的局限性和低效性。每个文件的内容前面都有一个简单的文件头，指示其路径：
该工具背后的理念是，LLM 上下文窗口很大，模型很智能，并且直接查看您的项目可以最好地使模型帮助您解决任何问题。
有一个用于与 AI 工具集成的 MCP（模型上下文协议）服务器和一个用于手动使用的命令行实用程序（CLI），可将项目上下文复制到剪贴板，以便粘贴到您需要的任何位置。
这些工具对于什么算作相关的项目上下文有自己的看法，以便在大多数用例中开箱即用，自动排除：
如果需要，可以使用.contextfiles以完全粒度的方式自定义包含/排除 - 这与.gitignore类似，只是定义了包含项.gitignore文件本身也会自动得到尊重，但.contextfiles中的任何规则都优先。
MCP 服务器可以根据需要提供项目所需的内容。默认情况下，范围是整个项目，但模型可以请求特定的模块/匹配模式等。
MCP 快速入门
适用于 Cursor / Roo / Claude Desktop / 客户端的 MCP 服务器配置文件：
您可以选择限制服务器仅在树内读取以确保您的 LLM 出现问题时的安全：将
如果您的系统上没有 uv，请安装： https://docs.astral.sh/uv/getting-started/installation/
重新加载您的 IDE，您现在可以要求代理读取上下文。
如果您想将其限制到特定的模块/路径，只需询问 - 例如“读取测试上下文”。
使用 Cursor 进行操作：
光标用户须知
游标可以悄悄地删除大于允许最大值的上下文，因此，如果您有一个相当大的项目，并且代理的行为就像工具调用从未发生过一样，请尝试减少您引入的内容（“读取 xyz 的上下文”）
成分
jinni与 Cursor、Cline、Roo、Claude Desktop 等 MCP 客户端集成。
公开一个
read_context工具，该工具从指定的项目目录返回相关文件内容的连接字符串。
jinni用于手动生成项目上下文转储的命令行工具。
适用于通过复制粘贴或文件输入向 LLM 提供上下文。或者将输出通过管道传输到任何需要的地方。
Related MCP server: MCP JinaAI Search Server
特征
**高效的上下文收集：**在一次操作中读取并连接相关的项目文件。
智能过滤（Gitignore 风格包含）：
使用基于
.gitignore语法（pathspec库的gitwildmatch）的系统。自动从项目根目录向下加载
.gitignore文件。这些排除项可以被.contextfiles中的规则覆盖。支持使用放置在项目目录中的
.contextfiles进行分层配置。规则会根据正在处理的文件/目录动态应用。匹配行为：（如果未指定具体目标，则为项目根目录）的相对路径进行匹配。例如，如果目标是
src/，则src/.contextfiles中的规则!app.py将匹配app.py。输出路径仍相对于原始项目根目录。**覆盖：**支持
--overrides（CLI）或 rules（MCP）rules，以独占使用一组特定的规则。当覆盖启用时，内置默认规则和任何.contextfiles都将被忽略。覆盖的路径匹配仍然相对于目标目录。**显式目标包含：**显式指定为目标的文件始终会被包含（绕过规则检查，但不会绕过二进制/大小检查）。显式指定为目标的目录始终会被输入，然后规则发现/匹配将相对于该目标目录进行。
可定制配置（
使用应用于相对路径的
.gitignore样式模式精确定义要包含或排除的文件/目录。以
!开头的模式否定匹配（排除模式）。（请参阅下面的“配置”部分）。
**大型上下文处理：**如果包含的文件总大小超过可配置的限制（默认值：100MB），则会中止并抛出
DetailedContextSizeError错误。错误消息会列出造成大小差异最大的10个文件，帮助您确定需要排除的文件。有关管理上下文大小的指导，请参阅“故障排除”部分。**元数据标头：**输出包含每个包含文件的路径标头（例如，````path=src/app.py`
). This can be disabled with。**编码处理：**尝试多种常见的文本编码（UTF-8、Latin-1 等）。
**仅列出模式：**仅列出将包含的文件的相对路径，但不列出其内容。
用法
MCP 服务器（ read_context工具）
**设置：**配置您的 MCP 客户端（例如，Claude Desktop 的
claude_desktop_config.json）以通过uvx运行jinni服务器。**调用：**当通过 MCP 客户端与您的 LLM 交互时，模型可以调用
read_context工具。**
project_root(字符串，必需)：**项目根目录的绝对路径。规则发现和输出路径都相对于此根目录。targets处理的文件/目录列表。必须是 JSON 字符串路径数组（例如，["path/to/file1", "path/to/dir2"]）。路径可以是绝对路径，也可以是相对于 CWD 的相对路径。所有目标路径必须解析到project_root内部的位置。如果提供的是空列表[]，则处理整个project_root。rules强制的内联过滤规则列表（使用.gitignore风格的语法，例如["src/**/*.py", "!*.tmp"]）。如果不需要特定规则，请提供一个空列表[]（这将使用内置默认值）。如果非空，则仅使用这些规则，忽略内置默认值和.contextfiles。**
list_only（布尔值，可选）：**如果为真，则仅返回相对文件路径列表而不是内容。**
size_limit_mb（整数，可选）：**覆盖上下文大小限制（以 MB 为单位）。**
debug_explain（布尔值，可选）：**在服务器上启用调试日志记录。
**输出：**该工具返回一个包含连接内容（带标题）或文件列表的字符串。标题/列表中的路径相对于提供的
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 出现问题时的安全：将
请参阅特定 MCP 客户端的文档，了解精确的设置步骤。确保已安装
命令行实用程序（ 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。
运行时操作系统 | 你传递的内容 |
返回的内容 |
视窗 |
|
|
视窗 |
|
（通过 wslpath） |
Linux/WSL |
|
|
Linux/WSL |
|
（未更改） |
示例
将
jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)列出将包含在
jinni -l ./my_project/ jinni --list-only ./src ./docs/README.md将
jinni -o context_dump.txt ./my_project/使用
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中相同。
规则应用逻辑：
确定目标： Jinni 识别目标目录（明确提供或项目根目录）。
**覆盖检查：**如果提供了
--overrides(CLI) 或rules(MCP)，则仅使用这些规则。所有.contextfiles和内置默认值都将被忽略。路径匹配是相对于目标目录的。**动态上下文规则（无覆盖）：**处理目标目录中的文件或子目录时：
Jinni 从目标目录开始到当前项目目录查找所有
.gitignore和.contextfiles。首先应用
.gitignore中的规则，然后是内置默认值，最后是任何.contextfiles（优先）。它将这些组合规则编译成一个规范（
PathSpec）。它根据此规范匹配相对于目标目录计算的当前文件/子目录路径。
匹配：决定了它的命运。
!表示否定匹配。如果没有用户定义的模式匹配，则该项目会被包含，除非它匹配内置的默认排除项（例如!.*）。**目标处理：**明确指定的目标文件会绕过规则检查。明确指定的目录将成为规则发现和匹配其内容的根目录。输出路径始终相对于原始
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 个最大文件的列表。这有助于您识别可能需要排除的文件。
要解决此问题：
**检查最大文件：**检查错误消息中提供的列表。是否存在不应包含在 LLM 上下文中的大文件（例如，数据文件、日志、构建工件、媒体文件）？
**配置排除：**使用
.contextfiles或--overrides/rules选项排除不必要的文件或目录。**示例（
.contextfiles）：**要排除所有.log文件和特定的大型数据目录：# Exclude all log files !*.log # Exclude a large data directory !large_data_files/有关详细语法和用法，请参阅上面的配置部分。
**增加限制（谨慎使用）：**如果所有包含的文件确实有必要，可以使用
--size-limit-mb(CLI) 或size_limit_mb(MCP) 增加大小限制。请注意 LLM 上下文窗口的限制和处理成本。**使用
jinni usage/usage：**如果您在排除故障时需要参考这些说明或配置详细信息，请使用jinni usage命令或usageMCP 工具。