Jinni上下文工具

@smat-dev/jinni

0 Stars 322 次浏览 smat-dev 更新于 2026-08-23

Jinni 是一个能够高效为大型语言模型提供项目上下文的工具。它提供了相关项目文件的整合视图，包含完整的元数据，克服了逐个读取文件的限制和低效问题。该工具背后的哲学是，LLM 上下文

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "jinni": {
      "args": [
        "jinni-server"
      ],
      "command": "uvx"
    }
  }
}

服务介绍

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

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

这个工具背后的哲学是：大型语言模型的上下文窗口很大，模型很智能，直接查看您的项目最能帮助模型处理您提出的任何问题。

有一个MCP（Model Context Protocol）服务器用于与AI工具集成，还有一个命令行实用程序（CLI），用于手动使用，将项目上下文复制到剪贴板，以便您可以将其粘贴到需要的地方。

这些工具对什么是相关的项目上下文有明确的观点，以最好地在大多数用例中开箱即用，自动排除：

* Binary files
* Dotfiles and hidden directories
* Common naming conventions for logs, build directories, tempfiles, etc

如果需要，可以通过 .contextfiles 以完全细粒度的方式自定义包含/排除项——这类似于 .gitignore，但用于定义包含项。

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

MCP 快速入门

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

{
    "mcpServers": {
    "jinni": {
        "command": "uvx jinni-server"
        // Optionally constrain the server to only read within a tree (recommended for security):
        // "command": "uvx jinni-server --root /absolute/path/"
    }
    }
}

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

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

如果您希望限制特定模块/路径，只需询问即可 - 例如 "读取测试的上下文"。

在 Cursor 中的实际操作：

对于Cursor用户的通知

Cursor 可能会无声地丢弃超过允许最大值的上下文，因此，如果您有一个较大的项目，并且代理表现得好像从未发生过工具调用一样，请尝试减少引入的内容（“读取xyz的上下文”）

组件

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

请注意，原文档中的“Usage”部分没有提供具体内容，因此翻译保持了这一结构，等待进一步补充。

设置： 配置您的MCP客户端（例如，Claude Desktop的claude_desktop_config.json），通过uvx运行jinni服务器。
调用： 当通过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 (布尔值, 可选): 在服务器上启用调试日志记录。
输出： 该工具返回一个包含拼接后的内容（带有标题）或文件列表的单个字符串。标题/列表中的路径相对于提供的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...> (optional): 一个或多个要分析的项目目录或文件的路径。如果未提供，则默认为当前目录 (.)。
-r <DIR> / --root <DIR> (optional): 指定项目根目录。如果提供了该选项，规则发现将从这里开始，并且输出路径将是相对于此目录的。如果省略，则根目录将从 <PATH...> 参数的共同祖先（如果只处理 . 则为 CWD）推断。
--output <FILE> / -o <FILE> (optional): 将输出写入 <FILE> 而不是打印到标准输出。
--list-only / -l (optional): 仅列出将被包含的文件的相对路径。
--overrides <FILE> (optional): 使用 <FILE> 中的规则而不是发现 .contextfiles。
--size-limit-mb <MB> / -s <MB> (optional): 覆盖最大上下文大小（以 MB 为单位）。
--debug-explain (optional): 将详细的包含/排除原因打印到 stderr 和 jinni_debug.log。
--root <DIR> / -r <DIR> (optional): 见上文。
--no-copy (optional): 防止在打印到标准输出时自动将输出内容复制到系统剪贴板（默认情况下会复制）。

安装

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

使用 pip:

pip install jinni

使用 uv:

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 会在 Windows 上自动解析 UNC 路径 (\\wsl$\...)。

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

只有 wsl+<distro> URI 和绝对 POSIX 路径（以 / 开头）会被转换；对于 SSH 或容器远程，需在该环境中运行 Jinni。

运行时操作系统	你传入的内容	`_translate_wsl_path()` 返回的内容
Windows	`vscode-remote://wsl%2BUbuntu/home/a/b`	`\\wsl$\\Ubuntu\home\a\b`
Windows	`/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/ # 处理单个目录
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：

# 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

开发

设计细节： 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个最大文件的列表。这有助于您识别可能需要排除的候选文件。

解决方法：

审查最大的文件： 检查错误消息中提供的列表。是否有大型文件（如数据文件、日志、构建产物、媒体文件）不应作为LLM上下文的一部分？
配置排除项： 使用.contextfiles或--overrides/rules选项来排除不必要的文件或目录。
- 示例（.contextfiles）： 排除所有.log文件和特定的大数据目录：
```
# 排除所有日志文件
!*.log

# 排除一个大数据目录
!large_data_files/
```
- 请参考上面的配置部分获取详细的语法和用法。
增加限制（谨慎使用）： 如果所有包含的文件确实都是必需的，可以使用--size-limit-mb（CLI）或size_limit_mb（MCP）来增加大小限制。请注意LLM上下文窗口限制和处理成本。
使用jinni usage / usage： 如果在故障排除时需要参考这些说明或配置详情，请使用jinni usage命令或usage MCP工具。

查看源码项目主页

MCP 服务配置

服务介绍

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

MCP 快速入门

对于Cursor用户的通知

组件

功能

用法

MCP 服务器 (read_context 工具)

MCP 服务器 (usage 工具)

命令行工具 (jinni CLI)

安装

平台特定说明

Windows + WSL

示例

配置（.contextfiles 和覆盖）

示例（.contextfiles）

开发

故障排除

上下文大小错误 (DetailedContextSizeError)

相关 MCP 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务