内存导入处理器

概述

内存导入处理器是一个功能，允许您通过使用 @file.md 语法从其他 Markdown 文件导入内容，从而模块化您的 GEMINI.md 文件。

此功能使您能够将大型 GEMINI.md 文件分解为更小、更易管理的组件，这些组件可以在不同上下文中重用。导入处理器支持相对路径和绝对路径，并具有内置的安全功能来防止循环导入并确保文件访问安全。

重要限制

语法

使用 @ 符号后跟您要导入的 Markdown 文件的路径：

# 主要 GEMINI.md 文件

这是主要内容。

@./components/instructions.md

这里是更多内容。

@./shared/configuration.md

支持的路径格式

相对路径

• @./file.md - 从同一目录导入
• @../file.md - 从父目录导入
• @./components/file.md - 从子目录导入

绝对路径

• @/absolute/path/to/file.md - 使用绝对路径导入

示例

基本导入

# 我的 GEMINI.md

欢迎使用我的项目！

@./getting-started.md

## 功能

@./features/overview.md

嵌套导入

导入的文件本身可以包含导入，创建嵌套结构：

# main.md

@./header.md
@./content.md
@./footer.md

# header.md

# 项目标题

@./shared/title.md

安全特性

循环导入检测

处理器自动检测并防止循环导入：

# file-a.md

@./file-b.md

# file-b.md

@./file-a.md 

文件访问安全

validateImportPath 函数确保只允许从指定目录导入，防止访问允许范围之外的敏感文件。

最大导入深度

为防止无限递归，有一个可配置的最大导入深度（默认：10 层）。

错误处理

非 MD 文件尝试

如果您尝试导入非 Markdown 文件，将看到警告：

@./instructions.txt 

控制台输出：

[WARN] [ImportProcessor] Import processor only supports .md files. Attempting to import non-md file: ./instructions.txt. This will fail.

文件缺失

如果引用的文件不存在，导入将优雅失败，并在输出中显示错误注释。

文件访问错误

权限问题或其他文件系统错误会得到优雅处理，并显示适当的错误消息。

API 参考

processImports(content, basePath, debugMode?, importState?)

处理 GEMINI.md 内容中的导入语句。

参数：

• content (string): 要处理导入的内容
• basePath (string): 当前文件所在的目录路径
• debugMode (boolean, 可选): 是否启用调试日志记录（默认：false）
• importState (ImportState, 可选): 用于循环导入预防的状态跟踪

返回值：

Promise<string> - 解析导入后的处理内容

validateImportPath(importPath, basePath, allowedDirectories)

验证导入路径以确保它们是安全的并在允许的目录范围内。

参数：

• importPath (string): 要验证的导入路径
• basePath (string): 解析相对路径的基目录
• allowedDirectories (string[]): 允许的目录路径数组

返回值：

boolean - 导入路径是否有效

最佳实践

故障排除

常见问题

调试模式

启用调试模式以查看导入过程的详细日志：

const result = await processImports(content, basePath, true);