Jinni

🚀 Jinni 项目指南

Jinni 项目旨在为开发者提供便捷的文件处理和上下文管理功能，通过灵活的规则配置，能够精准地控制哪些文件被纳入上下文，有效解决上下文大小限制等问题。

🚀 快速开始

在使用 Jinni 前，你需要了解一些基本的配置和规则应用逻辑。下面将详细介绍项目根目录的设置、规则应用的流程以及如何处理上下文大小错误等关键信息。

✨ 主要特性

• 灵活的根目录配置：可自定义项目根目录，决定文件上下文范围。
• 多样化的规则应用：支持覆盖规则和动态上下文规则，满足不同场景需求。
• 上下文大小错误处理：提供详细的错误信息和多种解决方法。
• 丰富的配置方式：可通过命令行参数或 MCP 客户端进行配置。

📦 安装指南

文档未提及安装步骤，暂不提供相关内容。

💻 使用示例

基础用法

在开发环境中运行服务器模块，可使用以下命令：

python -m jinni.serve serve --root /path/to/your/project_root

高级用法

若需要调整 Python 路径，可以根据实际需求修改环境变量。

📚 详细文档

项目根目录

• 参数设置：使用 --root 或 root 可指定项目的根目录。若未指定，默认使用 MCP 客户端中配置的路径。
• 作用说明：该设置决定了哪些文件可以被包含在上下文中，并作为所有相对路径计算的基础。

规则应用逻辑

1. 确定目标：Jinni 会识别出处理的目标目录，该目录可以由用户提供，也可以是项目根目录。
2. 覆盖检查：若使用了 --overrides（命令行接口）或 rules（MCP），这些规则将被优先使用，同时忽略所有 .contextfiles 和默认规则。路径匹配基于目标目录。
3. 动态上下文规则（无覆盖）：处理每个文件或子目录时，Jinni 会从目标目录开始向下查找所有 .contextfiles，直至当前项的目录。然后将这些发现的 .contextfiles 规则与默认规则结合，编译成一个规范（PathSpec），并匹配当前文件/子目录的相对路径（基于目标目录计算）。
4. 匹配规则：最后一个匹配当前项相对路径的模式决定其命运，! 表示否定匹配。若没有用户定义的模式匹配，则包含该项，除非它与默认排除（如 !.*）匹配。
5. 目标处理：显式提供的文件会跳过规则检查，显式提供的目录成为其内容规则发现和匹配的根。输出路径始终基于原始 project_root。

上下文大小错误 (DetailedContextSizeError)

• 问题描述：当包含的上下文大小超过限制时，Jinni 会提供一个包含 10 个最大文件的列表，这些文件是被尝试包含的。
• 解决方法：
  1. 审查 largest 文件：检查错误信息中的文件列表，判断是否有大文件（如数据文件、日志、构建产物、媒体）不应该成为 LLM 的上下文。
  2. 配置排除：使用 .contextfiles 或 --overrides / rules 来排除不必要的文件或目录。例如，在 .contextfiles 中排除所有 .log 文件和特定的大数据目录：

# 排除所有日志文件
!*.log

# 排除一个大数据文件目录
!large_data_files/

3. 增加限制（谨慎使用）：若所有包含的文件都是必要的，可以使用 --size-limit-mb（命令行接口）或 size_limit_mb（MCP）来增加大小限制。但需注意 LLM 上下文窗口限制和处理成本。
4. 使用 jinni usage / usage：若需要再次查阅这些说明或配置细节，可使用 jinni usage 命令或查看 usage 文档。

配置文件

• 覆盖规则：使用 --overrides 参数指定自定义的 .contextfiles 文件路径，以覆盖默认行为。
• MCP 配置：在 MCP 客户端中设置 rules 属性为一个数组，包含要排除或包含的具体路径。

🔧 技术细节

规则应用的技术实现

Jinni 的规则应用逻辑基于目标目录的确定、规则的覆盖检查和动态上下文规则的计算。通过查找 .contextfiles 并与默认规则结合，编译成 PathSpec 进行路径匹配，确保规则的准确应用。

上下文大小错误处理机制

当上下文大小超过限制时，Jinni 会分析包含的文件，提取 10 个最大文件的信息，并提供相应的解决方法，帮助用户解决问题。

📄 许可证

文档未提及许可证信息，暂不提供相关内容。

💡 使用建议

• 在配置规则时，建议先进行小规模测试，确保规则的正确性。
• 处理上下文大小错误时，优先审查大文件，避免不必要的文件被包含。
• 增加上下文大小限制时，要充分考虑 LLM 的上下文窗口限制和处理成本。

⚠️ 重要提示

• 运行服务器模块时，若需要调整 Python 路径，请谨慎修改环境变量，避免影响其他程序的正常运行。
• 遇到未列出的问题时，请及时参考项目文档或联系维护团队，避免自行处理导致问题恶化。