Main GEMINI.md file

Main GEMINI.md file【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliThis is the main content../components/instructions.mdMore content here../shared/configuration.md处理完成后每个导入语句会被替换为被导入文件的内容递归解析其内部的导入并用 HTML 注释标记边界。默认 tree 模式下的输出形如 markdown !-- Imported from: ./components/instructions.md -- 被导入文件的解析后内容 !-- End of import from: ./components/instructions.md --源码级的导入解析规则结合 memoryImportProcessor.ts 中的findImports函数实际解析比看到就切分更严格词边界检查前一个字符必须是空白符或处于行首避免把userexample.com这类邮箱、标识符中的误判为导入语句路径终止符导入路径在遇到空白字符空格、制表符或换行符\n/\r时结束因此一行内写./a.md ./b.md会被解析为两个独立导入首字符白名单路径必须非空且首字符为.、/或英文字母其他形式的xxx如TODO、2025不会被当作导入。支持的路径格式相对路径./file.md—— 从当前文件所在目录导入../file.md—— 从父目录导入./components/file.md—— 从子目录导入。绝对路径/absolute/path/to/file.md—— 使用绝对路径导入。路径解析基于path.resolve(basePath, importPath)其中basePath是当前文件的目录递归处理时每个被导入文件的basePath会更新为该文件自身的目录因此嵌套导入中的相对路径是相对于导入者所在目录而非项目根目录解析的。使用示例基础导入# My GEMINI.md Welcome to my project! ./get-started.md ## Features ./features/overview.md嵌套导入被导入的文件自身可以包含导入语句形成嵌套结构。例如main.md# main.md ./header.md ./content.md ./footer.mdheader.md# header.md # Project Header ./shared/title.md处理器会递归展开上述结构main.md中的每个导入先被替换为header.md及其内部shared/title.md的解析结果等内容同时把每一层返回的importTree挂到父节点的imports数组上保持导入发生的原始顺序。memoryImportProcessor.test.ts 中专门覆盖了嵌套导入的树形断言验证了importTree.imports按顺序保留、且多层嵌套层级正确的行为。两种输出格式tree 与 flat从 processImports 的完整签名 可以看出处理器支持两种输出格式由importFormat参数控制取值tree | flat默认treetree 模式默认把导入内容原地替换到导入语句位置并用!-- Imported from: ... --/!-- End of import from: ... --注释标记边界同时构建importTreeflat 模式把所有文件含递归导入、去重后按首次出现顺序拼成一份扁平、线性的文档每个文件包裹在--- File: 路径 ---与--- End of File: 路径 ---标记之间见 flat 模式实现。这一格式选择可以通过settings.json中的context.importFormat配置项控制默认undefined即 tree 模式定义见 settingsSchema.ts在 CLI 侧由 config.ts 透传给 core 层。相关配置说明也可参考 configuration.md。安全特性循环导入检测处理器会自动检测并阻止循环导入。例如file-a.md导入file-b.md而file-b.md又导入file-a.md# file-a.md ./file-b.md# file-b.md ./file-a.md !-- 循环引用会被检测并阻止 --实现机制是ImportState中的processedFiles集合每次递归前当前文件的规范化路径都会被加入集合再次遇到已处理文件时不会继续递归而是在输出中插入!-- File already processed: 路径 --注释见 tree 模式处理逻辑。flat 模式则用独立的processedFiles集合在入队前标记从源头杜绝重复拼接。文件访问安全validateImportPathvalidateImportPath函数确保导入只能来自允许的目录范围默认为项目根目录防止访问敏感文件。结合 validateImportPath 实现它的防护层次包括拒绝 URL 方案以file://、http://、https://开头的路径直接返回false杜绝远程或协议形式的读取符号链接规范化通过resolveToRealPath在磁盘上将路径解析为物理真实路径使符号链接无法绕过目录限制失败即拒绝fail-closed如果路径解析过程失败例如符号链接无限递归、非法路径直接判定为不合法而不是放行子路径校验将解析后的真实路径与所有允许目录的真实路径做isSubpath比较只有落在允许范围内才通过。校验失败时tree 模式输出中会插入!-- Import failed: 路径 - Path traversal attempt --注释。最大导入深度为防止无限递归处理器有一个可配置的最大导入深度默认值为 5 层ImportState.maxDepth见 默认 importState。当currentDepth达到上限时处理会停止并返回原文内容若开启 debug 模式还会输出Maximum import depth (5) reached的警告日志。错误处理文件缺失如果引用的文件不存在fs.access抛出 ENOENT导入会优雅失败不会中断整体处理而是在输出对应位置插入错误注释!-- Import failed: ./missing-file.md - ENOENT: no such file or directory, access ... --单个导入失败不影响其他导入继续处理。文件访问错误权限问题或其他文件系统错误同样被捕获处理tree 模式在输出中插入带错误消息的!-- Import failed --注释flat 模式则在 debug 日志中记录Failed to import 路径: 消息后继续处理其余文件。外层 memoryDiscovery.ts 还会对GEMINI.md本身读取失败做兜底目录名冲突EISDIR静默跳过其他错误在非测试环境下输出Warning: Could not read GEMINI.md file ...警告并保留content: null的占位结果。代码区域检测导入处理器会检测代码块与行内代码区域确保这些区域内的导入语法被原样保留、不触发解析。这对文档中讲解导入语法本身的GEMINI.md比如本文档 memport.md 自己尤为重要。实现上从源码结构看当前版本由 findCodeRegions 函数完成用正则 /()([\s\S]*?)\1/g 匹配数量一致的反引号对所围成的区域覆盖 行内代码 与多行围栏代码块再把每个导入语句的起始偏移与这些区域做区间比较落在区域内的xxx 会被原样写回输出见 tree 模式跳过逻辑。导入树结构processImports返回一个导入树importTree以层级形式展示被导入文件的结构类似于 Claude Code 的/memory功能。它帮助你调试GEMINI.md问题看清哪些文件被读取、以及它们之间的导入关系。示例树形结构Memory Files L project: GEMINI.md L a.md L b.md L c.md L d.md L e.md L f.md L included.md树按文件被导入的顺序保留并展示完整的导入链路便于排查问题。与 Claude Code/memory方式的对比Claude Code 的/memory功能对应claude.md生成的是一份扁平、线性的文档把所有包含文件拼接在一起始终用清晰的注释和路径名标记文件边界。它不显式呈现导入层级但 LLM 拿到了全部文件内容和路径需要时可以自行重建层级。gemini-cli 的 flat 模式即是对齐这一做法而 tree 模式额外提供层级结构。注导入树主要用于开发阶段的清晰呈现对 LLM 消费的实际意义有限——LLM 真正依赖的是解析后的完整内容与路径标记。项目根目录定位findProjectRootvalidateImportPath的允许目录默认是项目根目录它由findProjectRoot确定从给定起始目录向上逐级查找边界标记默认标记为.git目录或文件以兼容 git submodule / worktree 场景。结合 实现其要点包括实现为async函数使用非阻塞文件系统 API避免阻塞 Node.js 事件循环边界标记可配置标记为绝对路径或包含..时会被跳过防止标记注入路径穿越到达文件系统根仍未找到标记时回退返回起始目录本身配置层面context.memoryBoundaryMarkers可自定义边界标记列表空数组表示禁用向上遍历见 configuration.md。参数startDirstring开始搜索的目录。返回Promisestring—— 项目根目录未找到.git时返回起始目录。API 参考processImports(content, basePath, debugMode?, importState?, projectRoot?, importFormat?, boundaryMarkers?)处理GEMINI.md内容中的导入语句。文档中的核心四个参数如下content(string)要处理导入语句的内容basePath(string)当前文件所在目录路径debugMode(boolean可选)是否启用调试日志默认falseimportState(ImportState可选)用于循环导入防护的状态跟踪包含processedFiles、maxDepth默认 5、currentDepth、currentFile。源码中另有三个扩展参数见 函数签名projectRoot(string可选)允许目录范围对应的根目录缺省时自动调用findProjectRoot推导importFormatflat | tree默认tree输出格式boundaryMarkersstring[]默认[.git]根目录查找的边界标记。返回PromiseProcessImportsResult—— 包含解析后内容与导入树的对象。ProcessImportsResultinterface ProcessImportsResult { content: string; // 导入语句已解析的内容 importTree: MemoryFile; // 展示导入层级的树形结构 }MemoryFileinterface MemoryFile { path: string; // 文件路径 imports?: MemoryFile[]; // 直接导入项按导入顺序排列 }validateImportPath(importPath, basePath, allowedDirectories)校验导入路径是否安全且位于允许目录内。参数importPath(string)待校验的导入路径basePath(string)解析相对路径所用的基准目录allowedDirectories(string[])允许的目录路径数组。返回boolean—— 导入路径是否合法URL、解析失败、超出允许范围均返回false。最佳实践使用描述性文件名命名被导入的组件保持导入层级浅——避免过深的嵌套导入链默认深度上限为 5 层记录你的结构——维护清晰的导入文件层级导入树可用于随时核对测试你的导入——确保所有被引用文件存在且可访问优先使用相对路径以获得更好的可移植性。故障排查常见问题导入不生效确认文件存在且路径正确同时检查前是否为空白符、路径首字符是否符合规则.、/或字母——不符合的xxx不会被视为导入循环导入警告检查导入结构中是否存在循环引用输出中会看到File already processed注释权限错误确保文件可读且位于允许目录默认项目根目录内注意符号链接会被解析为物理路径后校验路径解析问题相对路径解析异常时可尝试绝对路径。调试模式开启 debug 模式查看导入过程的详细日志最大深度告警、flat 模式导入失败等const result await processImports(content, basePath, true);【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考