微信扫一扫article
README
🚀 Jinni 项目指南
Jinni 项目旨在为开发者提供便捷的文件处理和上下文管理功能，通过灵活的规则配置，能够精准地控制哪些文件被纳入上下文，有效解决上下文大小限制等问题。
🚀 快速开始
在使用 Jinni 前，你需要了解一些基本的配置和规则应用逻辑。下面将详细介绍项目根目录的设置、规则应用的流程以及如何处理上下文大小错误等关键信息。
✨ 主要特性
- 灵活的根目录配置：可自定义项目根目录，决定文件上下文范围。
- 多样化的规则应用：支持覆盖规则和动态上下文规则，满足不同场景需求。
- 上下文大小错误处理：提供详细的错误信息和多种解决方法。
- 丰富的配置方式：可通过命令行参数或 MCP 客户端进行配置。
📦 安装指南
文档未提及安装步骤，暂不提供相关内容。
💻 使用示例
基础用法
在开发环境中运行服务器模块，可使用以下命令：
python -m jinni.serve serve --root /path/to/your/project_root
高级用法
若需要调整 Python 路径，可以根据实际需求修改环境变量。
📚 详细文档
项目根目录
- 参数设置：使用
--root或root可指定项目的根目录。若未指定，默认使用 MCP 客户端中配置的路径。 - 作用说明：该设置决定了哪些文件可以被包含在上下文中，并作为所有相对路径计算的基础。
规则应用逻辑
- 确定目标：Jinni 会识别出处理的目标目录，该目录可以由用户提供，也可以是项目根目录。
- 覆盖检查：若使用了
--overrides（命令行接口）或rules（MCP），这些规则将被优先使用，同时忽略所有.contextfiles和默认规则。路径匹配基于目标目录。 - 动态上下文规则（无覆盖）：处理每个文件或子目录时，Jinni 会从目标目录开始向下查找所有
.contextfiles，直至当前项的目录。然后将这些发现的.contextfiles规则与默认规则结合，编译成一个规范（PathSpec），并匹配当前文件/子目录的相对路径（基于目标目录计算）。 - 匹配规则：最后一个匹配当前项相对路径的模式决定其命运，
!表示否定匹配。若没有用户定义的模式匹配，则包含该项，除非它与默认排除（如!.*）匹配。 - 目标处理：显式提供的文件会跳过规则检查，显式提供的目录成为其内容规则发现和匹配的根。输出路径始终基于原始
project_root。
上下文大小错误 (DetailedContextSizeError)
- 问题描述：当包含的上下文大小超过限制时，Jinni 会提供一个包含 10 个最大文件的列表，这些文件是被尝试包含的。
- 解决方法：
- 审查 largest 文件：检查错误信息中的文件列表，判断是否有大文件（如数据文件、日志、构建产物、媒体）不应该成为 LLM 的上下文。
- 配置排除：使用
.contextfiles或--overrides/rules来排除不必要的文件或目录。例如，在.contextfiles中排除所有.log文件和特定的大数据目录：
# 排除所有日志文件
!*.log
# 排除一个大数据文件目录
!large_data_files/
- 增加限制（谨慎使用）：若所有包含的文件都是必要的，可以使用
--size-limit-mb（命令行接口）或size_limit_mb（MCP）来增加大小限制。但需注意 LLM 上下文窗口限制和处理成本。 - 使用
jinni usage/usage：若需要再次查阅这些说明或配置细节，可使用jinni usage命令或查看usage文档。
配置文件
- 覆盖规则：使用
--overrides参数指定自定义的.contextfiles文件路径，以覆盖默认行为。 - MCP 配置：在 MCP 客户端中设置
rules属性为一个数组，包含要排除或包含的具体路径。
🔧 技术细节
规则应用的技术实现
Jinni 的规则应用逻辑基于目标目录的确定、规则的覆盖检查和动态上下文规则的计算。通过查找 .contextfiles 并与默认规则结合，编译成 PathSpec 进行路径匹配，确保规则的准确应用。
上下文大小错误处理机制
当上下文大小超过限制时，Jinni 会分析包含的文件，提取 10 个最大文件的信息，并提供相应的解决方法，帮助用户解决问题。
📄 许可证
文档未提及许可证信息，暂不提供相关内容。
💡 使用建议
- 在配置规则时，建议先进行小规模测试，确保规则的正确性。
- 处理上下文大小错误时，优先审查大文件，避免不必要的文件被包含。
- 增加上下文大小限制时，要充分考虑 LLM 的上下文窗口限制和处理成本。
⚠️ 重要提示
- 运行服务器模块时，若需要调整 Python 路径，请谨慎修改环境变量，避免影响其他程序的正常运行。
- 遇到未列出的问题时，请及时参考项目文档或联系维护团队，避免自行处理导致问题恶化。