Code2Prompt 默认模板解析从source_tree目录树压缩到 Markdown/XML 双格式渲染【免费下载链接】code2promptA CLI tool to convert your codebase into a single LLM prompt with source tree, prompt templating, and token counting.项目地址: https://gitcode.com/GitHub_Trending/co/code2prompt导读本文围绕 Code2Prompt 的「默认模板Default Template」展开回答一个实际开发者常遇到的问题当目标目录中多个子目录包含大量重复文件时如何让最终生成的 LLM Prompt 里的目录树Source Tree既完整又精简。文章以默认模板的结构与渲染机制为主线结合crates/code2prompt-core/src下的模板定义、目录遍历与配置源码讲解source_tree变量的生成链路、../../相对引用式目录压缩原理以及 Markdown 与 XML 两种默认输出格式的差异帮助读者在自定义模板与优化 Prompt Token 消耗时做到心中有数。一、默认模板是什么Code2Prompt 是一个把代码库转换为单个 LLM Prompt 的 CLI 工具输出内容由 Handlebars 模板驱动。所谓「默认模板」是指未指定--template或自定义模板时工具内置使用的两套模板文件默认 Markdown 模板面向常规 LLM 对话输出可读性强的 Markdown。默认 XML 模板面向偏结构化的解析场景用 XML 标签包裹各个数据段。两者共享同一套数据模型只是渲染外层不同。因此理解默认模板关键在于理解它消费了哪些模板变量以及这些变量尤其是source_tree是如何被生成出来的。二、默认模板的完整结构与变量清单2.1 Markdown 默认模板default_template_md.hbs 全文如下Project Path: {{ absolute_code_path }} Source Tree: txt {{ source_tree }}{{#if code_map}} Code Map:{{#each code_map}}{{path}}: {{#each entities}}{{kind}} {{name}}{{#if signature}}{{signature}}{{/if}} (lines {{start_line}}-{{end_line}}) {{/each}}{{/each}} {{/if}} {{#each files}} {{#if code}}{{path}}:{{#unless ../no_codeblock}}{{extension}} {{code}}{{code}} {{/unless}} {{/if}} {{/each}} {{#if git_diff}} Git Diff: {{ git_diff }} {{/if}}它按以下区块组织最终 Prompt头部信息absolute_code_path代码库的展示路径目录树source_tree整个项目的目录结构可视化即本文章节三的主角Code Map可选当启用实体映射entity_map时通过code_map变量输出每个文件的类、函数等实体清单每条记录包含kind、name、signature与起止行号文件内容区遍历files对每个含代码的文件输出{{path}}标题与其代码是否用三个反引号包裹由no_codeblock控制Git Diff 区可选当diff_enabled时追加git_diff。2.2 XML 默认模板default_template_xml.hbs 结构更紧凑directory{{absolute_code_path}}/directory source-tree {{source_tree}} /source-tree files {{#each files}} {{#if code}} file path{{path}} {{code}} /file {{/if}} {{/each}} /files {{#if git_diff}} git-diff {{git_diff}} /git-diff {{/if}}XML 模板没有 Code Map 区块与no_codeblock分支适用于希望以file path...标签直接投喂给结构化处理管道的场景。2.3 内置变量白名单Code2Prompt 用正则从模板中提取未定义变量用于校验自定义模板。内置变量白名单定义在 template.rsabsolute_code_path、source_tree、files、path、code、extensionno_codeblock、git_diff、git_diff_branch、git_log_branch任何不在白名单内的{{变量}}都会被extract_undefined_variables识别为「需要用户补充数据的自定义变量」。这意味着你在自定义模板时可以直接使用上述内置变量无需手工注入数据。三、核心机制目录树为何会出现../../压缩这是默认模板文档展示的核心示例也是读者最需要理解的机制。文档给出了如下目录树片段./ ├── ja/ │ ├── ブログ/ # ja 下的博客目录日文命名 │ └── ドキュメント/ # ja 下的文档目录 ├── fr/ │ ├── blog/ │ └── docs/ ├── de/ │ ├── blog/ │ └── docs/ ├── es/ │ ├── blog/ │ └── docs/当fr/、de/、es/等分支下的内容与ja/分支完全重复即目录层级相同、文件名相同时默认模板渲染出的目录树不会把重复内容原样罗列而是压缩为对上一级公共分支的相对引用./ ├── ja/ │ ├── ブログ/ │ └── ドキュメント/ ├── fr/ │ ├── ../../blog/ # 引用 ja/blog 的重复内容 │ └── ../../docs/ # 引用 ja/docs 的重复内容 ├── de/ │ ├── ../../blog/ │ └── ../../docs/ ├── es/ │ ├── ../../blog/ │ └── ../../docs/3.1 为什么这样压缩目的非常直接让代码块、命令与变量名保持一致so the code blocks, commands and variable names remain the same。当多语言站点或任何多分支目录只是重复同一套blog/、docs/结构时逐一展开每个分支会让 Prompt 中目录树占据大量 Token让 LLM 读到大量雷同路径分散对关键结构的注意力使输出与源文件的实际组织结构产生不必要的重复噪音。而压缩为../../blog/后树的可读性与信息密度都得到提升重复分支以最短路径表达Prompt 整体更聚焦。3.2 从源码看目录树的生成链路目录树并非模板硬编码而是运行时生成后注入source_tree变量。关键调用链如下会话加载session.rs 中load_codebase()调用traverse_directory(self.config, ...)得到(tree, files)随后self.data.source_tree Some(tree)将树字符串存入会话数据目录遍历path.rs 的traverse_directory分三个阶段执行discover_files发现并建树、process_files_parallel并行读取文件、assemble_results排序汇总树的数据结构discover_files返回TreeString来自termtreecrate逐路径组件向树中插入节点path.rs排序与字符串化assemble_results 调用sort_tree见 sort.rs 的termtree::TreeD递归排序与sort_files最后tree.to_string()得到最终目录树文本注入模板会话渲染阶段把source_tree提供给 Handlebars 上下文由默认模板中的{{ source_tree }}输出。值得注意TreeString节点的Display字符串化正是「重复内容以../../相对路径引用」这一压缩行为的落点。从源码结构看termtree的渲染在叶子节点路径可折叠时以相对引用输出从而既保留完整层级关系又避免重复展开。3.3 与目录树相关的配置项控制目录树生成行为的配置定义在 configuration.rs其中与树直接相关的包括配置字段命令行对应说明full_directory_tree--full-directory-tree为true时生成完整目录树忽略 include/exclude 过滤树中仍显示未入选文件为false时树只展示被选中文件对应的路径hidden--hidden是否包含隐藏文件默认false通过 WalkBuilder 的.hidden(!config.hidden)控制path.rsno_ignore--no-ignore为true时忽略.gitignore规则.git_ignore(!config.no_ignore)follow_symlinks--follow-symlinks是否跟随符号链接.follow_links(config.follow_symlinks)sort_method--sort目录树与文件列表的排序方式NameAsc/NameDesc/DateAsc/DateDescsort.rs从 path.rs 可以看到树与文件选择的联动include_in_tree config.full_directory_tree || entry_match——即要么强制展示完整树要么只展示被过滤/选择逻辑命中的路径。理解这一点就能解释为什么同一代码库在不同--include/--exclude参数下目录树形态完全不同。四、默认模板的完整渲染示例把原文档的示例合并到完整上下文中一份典型的 Markdown 默认模板输出大致为Project Path: my-site Source Tree: txt ./ ├── ja/ │ ├── ブログ/ │ └── ドキュメント/ ├── fr/ │ ├── ../../blog/ │ └── ../../docs/ ├── de/ │ ├── ../../blog/ │ └── ../../docs/ ├── es/ │ ├── ../../blog/ │ └── ../../docs/模板渲染过程中代码块、命令与变量名保持原样becomes 之后的树与原树语义等价最终整个目录树作为 source_tree 变量被嵌入 Prompt 的 Source Tree 区块。 --- ## 五、如何查看与切换默认模板 ### 5.1 命令行查看渲染结果 在 [命令行文档](https://link.gitcode.com/i/2dd3aed5cd74554cdc55790b24300a10) 与 [安装指南](https://link.gitcode.com/i/d1176f40a3fbcb4a4d1e9cd0b75a77f8) 中有完整用法核心思路是不传 --template 即使用默认模板传 --template 名称 或通过配置指定自定义模板字符串时才会覆盖默认行为。 ### 5.2 自定义模板时的注意点 - 模板必须是合法 Handlebars 语法配置项 custom_template 在 build() 时校验语法错误会直接报错[configuration.rs](https://link.gitcode.com/i/93d73218ca904395f9cc3f3216a65066) - 可安全使用的内置变量即 2.3 节白名单 - no_codeblock 为 true 时 Markdown 模板不再用 包裹代码由 {{#unless ../no_codeblock}} 分支控制适用于不希望输出 Markdown 围栏的场景 - 想保留 XML 结构解析能力时可在 XML 模板基础上增删区块。 --- ## 六、总结与延伸阅读 默认模板的实质是一套「变量注入 Handlebars 渲染」的确定性流程traverse_directory 生成目录树与文件内容 → load_codebase 存入会话 → 默认模板按区块组织输出。其中目录树的 ../../ 压缩机制是控制 Prompt 信息密度的关键设计而 full_directory_tree、hidden、no_ignore、sort_method 等配置则决定了树的具体形态。 建议继续阅读以下仓库文件加深理解 - 默认 Markdown 模板源码[default_template_md.hbs](https://link.gitcode.com/i/499095ae4471732cb63b2a4369825eae) - 默认 XML 模板源码[default_template_xml.hbs](https://link.gitcode.com/i/d00516984d4d793ce02a069533028d08) - 模板变量注册与未定义变量提取[template.rs](https://link.gitcode.com/i/1a318b1b0c31f724a11fa786c13850d5) - 目录遍历与树生成[path.rs](https://link.gitcode.com/i/c2f1067d2147f644ddd8e87d97b95ab9) - 树与文件排序[sort.rs](https://link.gitcode.com/i/a7a8ba84dfb9c94c7681cd79214e8bc9) - 会话加载与渲染入口[session.rs](https://link.gitcode.com/i/d97b5afd1ba256cd5d34dbde7b252b27) - 模板集成测试[template_integration_test.rs](https://link.gitcode.com/i/014ff4fb742354998e54a264927ecfd3)【免费下载链接】code2promptA CLI tool to convert your codebase into a single LLM prompt with source tree, prompt templating, and token counting.项目地址: https://gitcode.com/GitHub_Trending/co/code2prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Code2Prompt 默认模板解析：从 `source_tree` 目录树压缩到 Markdown/XML 双格式渲染
Code2Prompt 默认模板解析从source_tree目录树压缩到 Markdown/XML 双格式渲染【免费下载链接】code2promptA CLI tool to convert your codebase into a single LLM prompt with source tree, prompt templating, and token counting.项目地址: https://gitcode.com/GitHub_Trending/co/code2prompt导读本文围绕 Code2Prompt 的「默认模板Default Template」展开回答一个实际开发者常遇到的问题当目标目录中多个子目录包含大量重复文件时如何让最终生成的 LLM Prompt 里的目录树Source Tree既完整又精简。文章以默认模板的结构与渲染机制为主线结合crates/code2prompt-core/src下的模板定义、目录遍历与配置源码讲解source_tree变量的生成链路、../../相对引用式目录压缩原理以及 Markdown 与 XML 两种默认输出格式的差异帮助读者在自定义模板与优化 Prompt Token 消耗时做到心中有数。一、默认模板是什么Code2Prompt 是一个把代码库转换为单个 LLM Prompt 的 CLI 工具输出内容由 Handlebars 模板驱动。所谓「默认模板」是指未指定--template或自定义模板时工具内置使用的两套模板文件默认 Markdown 模板面向常规 LLM 对话输出可读性强的 Markdown。默认 XML 模板面向偏结构化的解析场景用 XML 标签包裹各个数据段。两者共享同一套数据模型只是渲染外层不同。因此理解默认模板关键在于理解它消费了哪些模板变量以及这些变量尤其是source_tree是如何被生成出来的。二、默认模板的完整结构与变量清单2.1 Markdown 默认模板default_template_md.hbs 全文如下Project Path: {{ absolute_code_path }} Source Tree: txt {{ source_tree }}{{#if code_map}} Code Map:{{#each code_map}}{{path}}: {{#each entities}}{{kind}} {{name}}{{#if signature}}{{signature}}{{/if}} (lines {{start_line}}-{{end_line}}) {{/each}}{{/each}} {{/if}} {{#each files}} {{#if code}}{{path}}:{{#unless ../no_codeblock}}{{extension}} {{code}}{{code}} {{/unless}} {{/if}} {{/each}} {{#if git_diff}} Git Diff: {{ git_diff }} {{/if}}它按以下区块组织最终 Prompt头部信息absolute_code_path代码库的展示路径目录树source_tree整个项目的目录结构可视化即本文章节三的主角Code Map可选当启用实体映射entity_map时通过code_map变量输出每个文件的类、函数等实体清单每条记录包含kind、name、signature与起止行号文件内容区遍历files对每个含代码的文件输出{{path}}标题与其代码是否用三个反引号包裹由no_codeblock控制Git Diff 区可选当diff_enabled时追加git_diff。2.2 XML 默认模板default_template_xml.hbs 结构更紧凑directory{{absolute_code_path}}/directory source-tree {{source_tree}} /source-tree files {{#each files}} {{#if code}} file path{{path}} {{code}} /file {{/if}} {{/each}} /files {{#if git_diff}} git-diff {{git_diff}} /git-diff {{/if}}XML 模板没有 Code Map 区块与no_codeblock分支适用于希望以file path...标签直接投喂给结构化处理管道的场景。2.3 内置变量白名单Code2Prompt 用正则从模板中提取未定义变量用于校验自定义模板。内置变量白名单定义在 template.rsabsolute_code_path、source_tree、files、path、code、extensionno_codeblock、git_diff、git_diff_branch、git_log_branch任何不在白名单内的{{变量}}都会被extract_undefined_variables识别为「需要用户补充数据的自定义变量」。这意味着你在自定义模板时可以直接使用上述内置变量无需手工注入数据。三、核心机制目录树为何会出现../../压缩这是默认模板文档展示的核心示例也是读者最需要理解的机制。文档给出了如下目录树片段./ ├── ja/ │ ├── ブログ/ # ja 下的博客目录日文命名 │ └── ドキュメント/ # ja 下的文档目录 ├── fr/ │ ├── blog/ │ └── docs/ ├── de/ │ ├── blog/ │ └── docs/ ├── es/ │ ├── blog/ │ └── docs/当fr/、de/、es/等分支下的内容与ja/分支完全重复即目录层级相同、文件名相同时默认模板渲染出的目录树不会把重复内容原样罗列而是压缩为对上一级公共分支的相对引用./ ├── ja/ │ ├── ブログ/ │ └── ドキュメント/ ├── fr/ │ ├── ../../blog/ # 引用 ja/blog 的重复内容 │ └── ../../docs/ # 引用 ja/docs 的重复内容 ├── de/ │ ├── ../../blog/ │ └── ../../docs/ ├── es/ │ ├── ../../blog/ │ └── ../../docs/3.1 为什么这样压缩目的非常直接让代码块、命令与变量名保持一致so the code blocks, commands and variable names remain the same。当多语言站点或任何多分支目录只是重复同一套blog/、docs/结构时逐一展开每个分支会让 Prompt 中目录树占据大量 Token让 LLM 读到大量雷同路径分散对关键结构的注意力使输出与源文件的实际组织结构产生不必要的重复噪音。而压缩为../../blog/后树的可读性与信息密度都得到提升重复分支以最短路径表达Prompt 整体更聚焦。3.2 从源码看目录树的生成链路目录树并非模板硬编码而是运行时生成后注入source_tree变量。关键调用链如下会话加载session.rs 中load_codebase()调用traverse_directory(self.config, ...)得到(tree, files)随后self.data.source_tree Some(tree)将树字符串存入会话数据目录遍历path.rs 的traverse_directory分三个阶段执行discover_files发现并建树、process_files_parallel并行读取文件、assemble_results排序汇总树的数据结构discover_files返回TreeString来自termtreecrate逐路径组件向树中插入节点path.rs排序与字符串化assemble_results 调用sort_tree见 sort.rs 的termtree::TreeD递归排序与sort_files最后tree.to_string()得到最终目录树文本注入模板会话渲染阶段把source_tree提供给 Handlebars 上下文由默认模板中的{{ source_tree }}输出。值得注意TreeString节点的Display字符串化正是「重复内容以../../相对路径引用」这一压缩行为的落点。从源码结构看termtree的渲染在叶子节点路径可折叠时以相对引用输出从而既保留完整层级关系又避免重复展开。3.3 与目录树相关的配置项控制目录树生成行为的配置定义在 configuration.rs其中与树直接相关的包括配置字段命令行对应说明full_directory_tree--full-directory-tree为true时生成完整目录树忽略 include/exclude 过滤树中仍显示未入选文件为false时树只展示被选中文件对应的路径hidden--hidden是否包含隐藏文件默认false通过 WalkBuilder 的.hidden(!config.hidden)控制path.rsno_ignore--no-ignore为true时忽略.gitignore规则.git_ignore(!config.no_ignore)follow_symlinks--follow-symlinks是否跟随符号链接.follow_links(config.follow_symlinks)sort_method--sort目录树与文件列表的排序方式NameAsc/NameDesc/DateAsc/DateDescsort.rs从 path.rs 可以看到树与文件选择的联动include_in_tree config.full_directory_tree || entry_match——即要么强制展示完整树要么只展示被过滤/选择逻辑命中的路径。理解这一点就能解释为什么同一代码库在不同--include/--exclude参数下目录树形态完全不同。四、默认模板的完整渲染示例把原文档的示例合并到完整上下文中一份典型的 Markdown 默认模板输出大致为Project Path: my-site Source Tree: txt ./ ├── ja/ │ ├── ブログ/ │ └── ドキュメント/ ├── fr/ │ ├── ../../blog/ │ └── ../../docs/ ├── de/ │ ├── ../../blog/ │ └── ../../docs/ ├── es/ │ ├── ../../blog/ │ └── ../../docs/模板渲染过程中代码块、命令与变量名保持原样becomes 之后的树与原树语义等价最终整个目录树作为 source_tree 变量被嵌入 Prompt 的 Source Tree 区块。 --- ## 五、如何查看与切换默认模板 ### 5.1 命令行查看渲染结果 在 [命令行文档](https://link.gitcode.com/i/2dd3aed5cd74554cdc55790b24300a10) 与 [安装指南](https://link.gitcode.com/i/d1176f40a3fbcb4a4d1e9cd0b75a77f8) 中有完整用法核心思路是不传 --template 即使用默认模板传 --template 名称 或通过配置指定自定义模板字符串时才会覆盖默认行为。 ### 5.2 自定义模板时的注意点 - 模板必须是合法 Handlebars 语法配置项 custom_template 在 build() 时校验语法错误会直接报错[configuration.rs](https://link.gitcode.com/i/93d73218ca904395f9cc3f3216a65066) - 可安全使用的内置变量即 2.3 节白名单 - no_codeblock 为 true 时 Markdown 模板不再用 包裹代码由 {{#unless ../no_codeblock}} 分支控制适用于不希望输出 Markdown 围栏的场景 - 想保留 XML 结构解析能力时可在 XML 模板基础上增删区块。 --- ## 六、总结与延伸阅读 默认模板的实质是一套「变量注入 Handlebars 渲染」的确定性流程traverse_directory 生成目录树与文件内容 → load_codebase 存入会话 → 默认模板按区块组织输出。其中目录树的 ../../ 压缩机制是控制 Prompt 信息密度的关键设计而 full_directory_tree、hidden、no_ignore、sort_method 等配置则决定了树的具体形态。 建议继续阅读以下仓库文件加深理解 - 默认 Markdown 模板源码[default_template_md.hbs](https://link.gitcode.com/i/499095ae4471732cb63b2a4369825eae) - 默认 XML 模板源码[default_template_xml.hbs](https://link.gitcode.com/i/d00516984d4d793ce02a069533028d08) - 模板变量注册与未定义变量提取[template.rs](https://link.gitcode.com/i/1a318b1b0c31f724a11fa786c13850d5) - 目录遍历与树生成[path.rs](https://link.gitcode.com/i/c2f1067d2147f644ddd8e87d97b95ab9) - 树与文件排序[sort.rs](https://link.gitcode.com/i/a7a8ba84dfb9c94c7681cd79214e8bc9) - 会话加载与渲染入口[session.rs](https://link.gitcode.com/i/d97b5afd1ba256cd5d34dbde7b252b27) - 模板集成测试[template_integration_test.rs](https://link.gitcode.com/i/014ff4fb742354998e54a264927ecfd3)【免费下载链接】code2promptA CLI tool to convert your codebase into a single LLM prompt with source tree, prompt templating, and token counting.项目地址: https://gitcode.com/GitHub_Trending/co/code2prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
