Jinni：把你的项目放在背景中
Jinni是一个高效地为大型语言模型提供项目上下文的工具。它提供了相关项目文件的统一视图，克服了逐一读取文件的局限性和低效性。每个文件的内容前面都有一个简单的标头，指示其路径：
print("hello")
这个工具背后的理念是，LLM上下文窗口很大，模型很智能，直接看到你的项目最能让模型帮助你处理任何事情。
有一个MCP（模型上下文协议）服务器用于与AI工具集成，还有一个命令行实用程序（CLI）用于手动使用，可以将项目上下文复制到剪贴板，随时粘贴到您需要的地方。
这些工具对什么是相关的项目上下文有自己的看法，以便在大多数用例中最好地开箱即用，自动排除：
- Binary files
- Dotfiles and hidden directories
- Common naming conventions for logs, build directories, tempfiles, etc
如果需要，可以使用以下方式以完整的粒度自定义包含/排除 `.contextfiles` –这就像 `.gitignore` 除了定义夹杂物。 `.gitignore` 文件本身也会自动受到尊重，但其中的任何规则 `.contextfiles` 优先考虑。
MCP服务器可以根据需要提供尽可能多或尽可能少的项目。默认情况下，范围是整个项目，但模型可以要求特定的模块/匹配模式等。
# MCP快速入门
Cursor/Rou/Claude Desktop/所选客户端的MCP服务器配置文件：
{ "mcpServers": { "jinni": { "command": "uvx", "args": ["jinni-server"] } } }
*为了安全起见，您可以选择将服务器限制为仅在树中读取，以防您的LLM出现问题：add `"--root", "/absolute/path/"` 到 `args` 列表。*
如果您的系统上没有安装uv：https://docs.astral.sh/uv/getting-started/installation/
重新加载IDE，现在可以让代理在上下文中读取。
如果你想将其限制在特定的模块/路径上，只需询问，例如“读取测试上下文”。
在使用游标时：
# 游标用户注意事项
游标可以静默地删除大于允许最大值的上下文，因此，如果您有一个相当大的项目，并且代理的行为就像从未发生过工具调用一样，请尝试减少您带来的内容（“读取xyz的上下文”）
## 组件
1. **`jinni` MCP服务器：**
- 与Cursor、Cline、Roo、Claude Desktop等MCP客户端集成。
- 暴露a `read_context` 该工具从指定的项目目录返回相关文件内容的连接字符串。
1. **`jinni` CLI：**
- 用于手动生成项目上下文转储的命令行工具。
- 可用于通过复制粘贴或文件输入向LLM提供上下文。或者在需要的地方用管道输送输出。
## 特性
- **高效的上下文收集：** 在一个操作中读取并连接相关的项目文件。
- **智能过滤（Gitignore风格包含）：**
- 使用基于以下内容的系统 `.gitignore` 语法(`pathspec` 图书馆 `gitwildmatch`).
- 自动加载 `.gitignore` 文件从项目根目录向下。这些排除可以被以下规则覆盖 `.contextfiles`.
- 支持使用分层配置 `.contextfiles` 放置在项目目录中。规则根据正在处理的文件/目录动态应用。
- **匹配行为：** 模式与路径相对应 **目标目录** 正在处理中。输出路径相对于原始项目根保持不变。
- **规则根行为：** 每个目标都有自己的规则根：
- 项目根（或CWD）中的目标使用项目根/CWD作为其规则根
- 外部目标将自己用作规则根，确保自包含的规则集
- **覆盖：** 支持 `--overrides` （CLI）或 `rules` （MCP）专门使用一组特定的规则。当覆盖处于活动状态时，内置默认规则和任何 `.contextfiles` 被忽略。覆盖的路径匹配仍然相对于目标目录。
- **明确目标纳入：** 明确作为目标提供的文件始终包含在内（绕过规则检查，但不包括二进制/大小检查）。
- **可定制配置(`.contextfiles` /覆盖）：**
- 使用以下命令精确定义要包含或排除的文件/目录 `.gitignore`-应用于的样式模式 **相对路径**.
- 模式开始于 `!` 否定匹配（排除模式）。（请参阅下面的配置部分）。
- **大上下文处理：** 中止与a `DetailedContextSizeError` 如果包含的文件的总大小超过可配置的限制（默认值：100MB）。错误消息包括一个导致大小的10个最大文件的列表，帮助您识别排除的候选文件。有关管理上下文大小的指导，请参阅故障排除部分。
- **元数据标头：** 输出包括每个包含文件的路径头（例如，\`\`\` path=src/app.py`). This can be disabled with `list_only。
- **编码处理：** 尝试多种常见的文本编码（UTF-8、Latin-1等）。
- **仅列表模式：** 选项仅列出将包含的文件的相对路径，不包括其内容。
## 用法
### MCP服务器(`read_context` 工具）
1. **设置：** 配置您的MCP客户端（例如，Claude Desktop的 `claude_desktop_config.json`)运行 `jinni` 服务器通过 `uvx`.
1. **调用：** 当通过MCP客户端与LLM交互时，模型可以调用 `read_context` 工具。
- **`project_root` （字符串，必填）：** 项目根目录的绝对路径。规则发现和输出路径与此根相关。
- **`targets` （JSON字符串数组，必填）：** 指定 **强制性的** 内的文件/目录列表 `project_root` 处理。必须是字符串路径的JSON数组（例如。， `["path/to/file1", "path/to/dir2"]`).路径可以是绝对的，也可以是相对于CWD的。所有目标路径必须解析到内部位置 `project_root`。如果列表为空 `[]` 提供，整个 `project_root` 正在处理。
- **`rules` （JSON字符串数组，必填）：** A. **强制性的** 内联过滤规则列表（使用 `.gitignore`-风格语法。， `["src/**/*.py", "!*.tmp"]`).提供一个空列表 `[]` 如果不需要特定的规则（这将使用内置的默认值）。如果非空，则仅使用这些规则，忽略内置默认值和 `.contextfiles`.
- **`list_only` （布尔值，可选）：** 如果为true，则仅返回相对文件路径的列表，而不是内容。
- **`size_limit_mb` （整数，可选）：** 覆盖上下文大小限制（MB）。
- **`debug_explain` （布尔值，可选）：** 在服务器上启用调试日志记录。
- **`exclusions` （对象，可选）：** 包含三个可选字段的排除配置：
- **`global`** （字符串数组）：要全局排除的关键字（例如。， `["tests", "deprecated"]`)
- **`scoped`** （object）：用于范围排除的关键字数组的路径映射（例如。， `{"src/legacy": ["old", "deprecated"]}`)
- **`patterns`** （字符串数组）：要排除的文件模式（例如。， `["*.test.js", "*_old.*"]`)
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", "args": ["jinni-server"] } } }
*为了安全起见，您可以选择将服务器限制为仅在树中读取，以防您的LLM出现问题：add `"--root", "/absolute/path/"` 到 `args` 列表。*
*有关精确的设置步骤，请参阅特定MCP客户端的文档。确保 `uv` 已安装*
### 命令行实用程序(`jinni` CLI）
jinni [OPTIONS] [ ]
- **`
` （可选）：** 要分析的项目目录或文件的一个或多个路径。默认为当前目录(`.`)如果没有提供。
- **`-r ` / `--root ` （可选）：** 指定项目根目录。如果提供，规则发现从这里开始，输出路径相对于此目录。如果省略，则根是从的共同祖先推断出来的 `
` 参数（或CWD，如果只处理“.”）。
- **`--output ` / `-o ` （可选）：** 将输出写入 `` 而不是打印到标准输出。
- **`--list-only` / `-l` （可选）：** 仅列出将包含的文件的相对路径。
- **`--overrides ` （可选）：** 从以下位置添加规则 `` 作为高优先级规则，除了 `.contextfiles` 和 `.gitignore`.
- **`--size-limit-mb ` / `-s ` （可选）：** 覆盖最大上下文大小（MB）。
- **`--debug-explain` （可选）：** 将详细的包含/排除原因打印到stderr和 `jinni_debug.log`.
- **`--root ` / `-r ` （可选）：** 见上文。
- **`--no-copy` （可选）：** 打印到标准输出时，防止将输出内容自动复制到系统剪贴板（默认为复制）。
- **`--not ` （可选，可重复）：** 排除与关键字匹配的模块/目录（例如。， `--not tests --not vendor`).可以多次使用。
- **`--not-in
` （可选，可重复）：** 排除路径内的特定关键字（例如。， `--not-in src/legacy:old,deprecated`).可以多次使用。
- **`--not-files
` （可选，可重复）：** 排除与模式匹配的文件（例如。， `--not-files '*.test.js' --not-files '*_old.*'`).可以多次使用。
- **`--keep-only ` （可选）：** 仅保留指定的模块/目录，排除其他所有内容（逗号分隔，例如。， `--keep-only src,lib,docs`).
### 排除示例
**CLI示例：**
Exclude all test directories
jinni --not tests
Exclude multiple keywords
jinni --not tests --not vendor --not deprecated
Exclude old code only in specific paths
jinni --not-in src/legacy:old,deprecated --not-in lib/v1:legacy
Exclude specific file patterns
jinni --not-files "*.test.js" --not-files "*_old.*"
Keep only src and docs, exclude everything else
jinni --keep-only src,docs
Combine different exclusion types
jinni --not tests --not-in src/experimental:wip --not-files "*.bak"
**注：** 排除命令(`--not*` 标志）除了现有的工作 `.gitignore` 和 `.contextfiles` 规则。他们进一步过滤掉了原本会包含的内容。
**MCP示例：**
{ "project_root": "/path/to/project", "targets": [], "rules": [], "exclusions": { "global": ["tests", "vendor"], "scoped": { "src/legacy": ["old", "deprecated"], "lib/experimental": ["wip", "unstable"] }, "patterns": ["*.test.js", "*_backup.*"] } }
## 安装
您可以使用安装Jinni `pip` 或 `uv`:
**使用pip：**
pip install jinni
**使用紫外线：**
uv pip install jinni
这将使 `jinni` CLI命令在您的环境中可用。请参阅上面的“运行服务器”部分，了解如何根据您的安装方法启动MCP服务器。
## 平台特定注意事项
### Windows+WSL
Jinni v0.1.7+自动转换WSL路径。
提供以下任一项 `project_root` （CLI `--root` 或MCP参数）：
/home/user/project vscode-remote://wsl+Ubuntu-22.04/home/user/project
不需要包装器、挂载或额外的标志——Jinni解析UNC路径(`\\wsl$\...`)在Windows上自动。
**UNC路径格式：** Jinni总是使用 `\\wsl$\\...` 以最大限度地兼容支持WSL的所有Windows版本。
**地区名称处理：** 发行版名称中允许使用空格和大多数特殊字符。只有真正非法的UNC字符才会被替换为 `_`.
**缓存：** WSL路径查找和转换被缓存以提高性能。如果在Jinni运行时安装WSL，请重新启动Jinni以获取新的 `wslpath`.
**选择退出：** 设置环境变量 `JINNI_NO_WSL_TRANSLATE=1` 禁用所有WSL路径转换逻辑。
仅 `wsl+` URI和绝对POSIX路径（以 `/`)被翻译；对于SSH或容器远程，请在该环境中运行Jinni。
|运行时操作系统|你传递了什么|什么 `_translate_wsl_path()` 退货|
|---------------|-------------------------------------------|------------------------------------------|
| **视窗** | `vscode-remote://wsl%2BUbuntu/home/a/b` | `\\wsl$\\Ubuntu\home\a\b` |
| **视窗** | `/home/a/b` | `\\wsl$\\Ubuntu\home\a\b` （通过wslpath）|
| **Linux/WSL** | `vscode-remote://wsl+Ubuntu/home/a/b` | `/home/a/b` |
| **Linux/WSL** | `/home/a/b` | `/home/a/b` （不变）|
## 例子
- **转储上下文 `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` 在任何目录中。规则发现从规则根（内部目标的项目根，外部目标的目标本身）开始，向下进行到正在处理的当前目录。
- **格式：** 纯文本，UTF-8编码，每行一种模式。
- **语法：** 使用标准 `.gitignore` 模式语法（特别是 `pathspec`s `gitwildmatch` 实施）。
- **评论：** 以开头的行 `#` 被忽略。
- **包容模式：** 指定要包含的文件/目录（例如。， `src/**/*.py`, `*.md`, `/config.yaml`).
- **排除模式：** 以开头的行 `!` 指示应排除匹配的文件（否定模式）。
- **锚固：** 领先 `/` 将模式锚定到包含 `.contextfiles`.
- **目录匹配：** A尾随 `/` 仅匹配目录。
- **通配符：** `*`, `**`, `?` 工作如in `.gitignore`.
- **规则应用逻辑：**
1. **确定目标：** Jinni标识目标目录（明确提供或项目根目录）。
1. **超控检查：** 如果 `--overrides` （CLI）或 `rules` （MCP）提供，这些规则仅供使用。全部 `.contextfiles` 并且忽略内置默认值。路径匹配是相对于目标目录的。
1. **动态上下文规则（无覆盖）：** 处理文件或子目录时：
- Jinni找到所有 `.gitignore` 和 `.contextfiles` 从规则根向下到当前项的目录。
- 规则按顺序组合：内置默认值， `.gitignore` 规则， `.contextfiles` 规则（优先）。
- 它将这些组合规则编译成规范(`PathSpec`).
- 它与当前文件/子目录路径匹配，计算 *相对于目标目录*，与此规范相反。
1. **匹配：** 这 **最后一个图案** 在与项目的相对路径匹配的组合规则集中，决定了它的命运。 `!` 否定比赛。如果没有用户定义的模式匹配，则包含该项，除非它匹配内置的默认排除（如 `!.*`).
1. **目标处理：** 明确的目标文件绕过规则检查。输出路径始终相对于原始路径保持不变 `project_root`.
### 示例(`.contextfiles`)
**示例1：包含Python源代码和根配置**
位于 `my_project/.contextfiles`:
Include all Python files in the src directory and subdirectories
src/**/*.py
Include the main config file at the root of the project
/config.json
Include all markdown files anywhere
*.md
Exclude any test data directories found anywhere
!**/test_data/
**示例2：在子目录中覆盖**
位于 `my_project/src/.contextfiles`:
In addition to rules inherited from parent .contextfiles...
Include specific utility scripts in this directory
utils/*.sh
Exclude a specific generated file within src, even if *.py is included elsewhere
!generated_parser.py
## 发展
- **设计细节：** [设计.md](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上下文的一部分？
1. **配置排除：** 使用 `.contextfiles` 或 `--overrides` / `rules` 用于排除不必要的文件或目录的选项。
- **示例(`.contextfiles`):** 排除所有 `.log` 文件和特定的大数据目录：# Exclude all log files !*.log
# Exclude a large data directory !large_data_files/
- 请参阅 **配置** 以上部分详细介绍语法和用法。
1. **增加限制（小心使用）：** 如果所有包含的文件都是真正必要的，您可以使用以下命令增加大小限制 `--size-limit-mb` （CLI）或 `size_limit_mb` （MCP）。请注意LLM上下文窗口限制和处理成本。
1. **使用 `jinni usage` / `usage`:** 如果在故障排除时需要参考这些说明或配置详细信息，请使用 `jinni usage` 命令或 `usage` MCP工具。