使用说明

Jinni：把你的项目放在背景中

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

```path=src/app.py
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的上下文”）

组件

jinni MCP服务器：
- 与Cursor、Cline、Roo、Claude Desktop等MCP客户端集成。
- 暴露a read_context 该工具从指定的项目目录返回相关文件内容的连接字符串。
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` 工具）

设置： 配置您的MCP客户端（例如，Claude Desktop的 claude_desktop_config.json)运行 jinni 服务器通过 uvx.
调用： 当通过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.*"])
1. 输出： 该工具返回一个包含连接内容（带标头）或文件列表的字符串。标题/列表中的路径与提供的路径相关 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] [<PATH...>]

<PATH...> （可选）： 要分析的项目目录或文件的一个或多个路径。默认为当前目录(.)如果没有提供。
-r <DIR> / --root <DIR> （可选）： 指定项目根目录。如果提供，规则发现从这里开始，输出路径相对于此目录。如果省略，则根是从的共同祖先推断出来的 <PATH...> 参数（或CWD，如果只处理“.”）。
--output <FILE> / -o <FILE> （可选）： 将输出写入 <FILE> 而不是打印到标准输出。
--list-only / -l （可选）： 仅列出将包含的文件的相对路径。
--overrides <FILE> （可选）： 从以下位置添加规则 <FILE> 作为高优先级规则，除了 .contextfiles 和 .gitignore.
--size-limit-mb <MB> / -s <MB> （可选）： 覆盖最大上下文大小（MB）。
--debug-explain （可选）： 将详细的包含/排除原因打印到stderr和 jinni_debug.log.
--root <DIR> / -r <DIR> （可选）： 见上文。
--no-copy （可选）： 打印到标准输出时，防止将输出内容自动复制到系统剪贴板（默认为复制）。
--not <keyword> （可选，可重复）： 排除与关键字匹配的模块/目录（例如。， --not tests --not vendor).可以多次使用。
--not-in <path:keywords> （可选，可重复）： 排除路径内的特定关键字（例如。， --not-in src/legacy:old,deprecated).可以多次使用。
--not-files <pattern> （可选，可重复）： 排除与模式匹配的文件（例如。， --not-files '*.test.js' --not-files '*_old.*').可以多次使用。
--keep-only <modules> （可选）： 仅保留指定的模块/目录，排除其他所有内容（逗号分隔，例如。， --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$\<distro>\... 以最大限度地兼容支持WSL的所有Windows版本。 地区名称处理： 发行版名称中允许使用空格和大多数特殊字符。只有真正非法的UNC字符才会被替换为 _. 缓存： WSL路径查找和转换被缓存以提高性能。如果在Jinni运行时安装WSL，请重新启动Jinni以获取新的 wslpath. 选择退出： 设置环境变量 JINNI_NO_WSL_TRANSLATE=1 禁用所有WSL路径转换逻辑。

仅 wsl+<distro> 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 模式语法（特别是 pathspecs gitwildmatch 实施）。
- 评论： 以开头的行 # 被忽略。
- 包容模式： 指定要包含的文件/目录（例如。， src/**/*.py, *.md, /config.yaml).
- 排除模式： 以开头的行 ! 指示应排除匹配的文件（否定模式）。
- 锚固： 领先 / 将模式锚定到包含 .contextfiles.
- 目录匹配： A尾随 / 仅匹配目录。
- 通配符： *, **, ? 工作如in .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:

# 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

在本地运行服务器： 在开发过程中（安装后 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 命令或 usage MCP工具。

使用说明

Jinni：把你的项目放在背景中

MCP快速入门

游标用户注意事项

组件

特性

用法

MCP服务器(read_context 工具）

MCP服务器(usage 工具）

命令行实用程序(jinni CLI）

排除示例

安装

平台特定注意事项

Windows+WSL

例子

配置(.contextfiles &覆盖）

示例(.contextfiles)

发展

故障排除

上下文大小错误(DetailedContextSizeError)

相关 MCP

浏览器自动化MCP服务器

文件与终端管理MCP服务

Shell与编码MCP服务器

容器沙箱 MCP 服务器

计算器MCP服务器

JSON数据查询与操作服务器