企业官网建设流程全解析

用 code2prompt 把个人笔记打包成结构化 LLM 上下文：history_notes 示例全解析

【免费下载链接】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 是一款把整个代码库（或任意资料目录）转换为单一 LLM Prompt 的命令行工具，输出中会包含目录树（Source Tree）、文件内容与 Token 统计。本指南以仓库内置示例history_notes（个人历史笔记）为线索，完整解读它生成的 prompt 文件website/src/assets/examples/history_notes/prompt.md的每一部分，并结合默认 Markdown 模板与文件选择引擎源码，说明这一格式是如何从原始目录一步步生成的。读完本文，你将掌握 code2prompt 输出的完整结构、底层模板机制，以及如何用它把自己的笔记、资料、文档目录变成 AI 可直接理解的上下文。

一、示例在项目中的定位：Goal + Format + Context 框架

history_notes是 code2prompt 官方网站首页（website/src/components/Section0.astro）上三个交互式示例之一，被归类为Personal Notes 📖（个人笔记），另外两个分别是代码库示例node_app（Codebase）与菜谱数据库示例my_recipes（Recipes Database）。

官网首页把 code2prompt 定位为一种"上下文工程（Context Engineering）工具"，其核心理念是一个Goal + Format + Context框架（见 Section0.astro）：

• Goal：你要达成什么目标；
• Format：你希望 AI 输出什么结构；
• Context：code2prompt 提供的、与任务相关的资料（即生成的 prompt 主体）。

history_notes示例正好是这个框架的完整演示：Goal 与 Format 来自用户侧的question.txt，而 Context 就是prompt.md——由 code2prompt 自动生成的结构化上下文。

在Section0.astro中，每个示例 Tab 会展示目录树、可用命令（$ code2prompt history_notes）、Goal 与 Format 的拆解视图，右侧则直接渲染prompt.md的原始内容（见 Section0.astro）。也就是说，prompt.md不只是静态示例，而是被官网组件逐字读取、解析目录树、拆解 Goal/Format 后动态呈现的"活"素材。

二、完整解读 prompt.md：一份标准输出长什么样

以下是website/src/assets/examples/history_notes/prompt.md的完整内容，也是 code2prompt 默认 Markdown 模板在个人笔记目录上的实际渲染结果：

Project Path: history_notes Source Tree: ```txt history_notes ├── history │ ├── medieval.txt │ ├── renaissance.txt │ └── ww2.txt └── meta └── my_revision_goals.txt

history_notes/history/medieval.txt:

Key events: Fall of Rome, Viking raids, Magna Carta Important dates: 476 AD, 793 AD, 1215 AD

history_notes/history/renaissance.txt:

Key figures: Leonardo da Vinci, Michelangelo, Copernicus Cultural shifts: Humanism, art revival, printing press

history_notes/history/ww2.txt:

Key events: D-Day, Hiroshima, End of War Leaders: Churchill, Roosevelt, Hitler, Stalin

history_notes/meta/my_revision_goals.txt:

Focus: Memorize key events, understand causes & consequences Deadline: 2 weeks

这份输出由三个逻辑区块组成，每一块都能在默认模板源码中找到对应出处。 ### 1. Project Path：告诉模型"上下文从哪来" 首行 `Project Path: history_notes` 对应模板变量 `absolute_code_path`（见 [default_template_md.hbs](https://link.gitcode.com/i/f3dc14cef8c66be4a07171398a0eac4c)），用于标识本次上下文的根路径，方便 LLM 理解后续所有相对路径的基准。 ### 2. Source Tree：一张目录结构"地图" 紧接着的 ```txt` 代码块是 `source_tree` 变量（见 [default_template_md.hbs](https://link.gitcode.com/i/797a312484b33f179021c03414f843ce)）。它以树状图展示： - `history/` 下三份按历史时期划分的笔记：`medieval.txt`（中世纪）、`renaissance.txt`（文艺复兴）、`ww2.txt`（二战）； - `meta/` 下的复习目标文件 `my_revision_goals.txt`。 这张地图让模型在阅读具体内容之前，先建立对整个资料集的整体认知——哪类信息放在哪个文件、文件之间如何组织。`Section0.astro` 中的 `extractDirectoryTree` 函数正是通过正则匹配 `prompt.md` 里 ```txt ... ``` 代码块来提取这棵目录树并单独展示的（见 [Section0.astro](https://link.gitcode.com/i/c2467ba0dd4ce8487f81301251fa123e)）。 ### 3. 文件内容区：逐文件完整注入 剩下的四个小节，每段都以反引号包裹的文件路径作为小标题，后面紧跟该文件的完整内容： | 文件 | 内容要点 | | --- | --- | | `history/medieval.txt` | 关键事件（罗马陷落、维京劫掠、大宪章）与关键日期（476/793/1215 AD） | | `history/renaissance.txt` | 关键人物（达芬奇、米开朗基罗、哥白尼）与文化变迁（人文主义、艺术复兴、印刷术） | | `history/ww2.txt` | 关键事件（诺曼底登陆、广岛、战争结束）与领导人（丘吉尔、罗斯福、希特勒、斯大林） | | `meta/my_revision_goals.txt` | 复习重点（记忆关键事件、理解因果）与截止日期（2 周） | 这一块对应模板中的 `{{#each files}}` 循环：对每个文件输出 `` `{{path}}`: `` 标题与代码块（见 [default_template_md.hbs](https://link.gitcode.com/i/76605e73de90846d4dd52eea2e7185d5)）。值得注意两点： - 内容区被标记为 `txt` 代码块，说明该目录下的文件按文本（`.txt`）处理，扩展名由 `extension` 变量提供； - 即使是非代码文件（个人笔记），code2prompt 也一视同仁地完整注入——这正是它用于"任意资料目录"而非仅限源码的体现。 ## 三、配套的 question.txt：Goal + Format 从哪来 `prompt.md` 旁边的 `website/src/assets/examples/history_notes/question.txt` 定义了示例要演示的"任务指令"，内容如下： ```txt Goal: Create interactive flashcards for my upcoming history exam Format: Generate question-answer pairs in markdown format: - Each flashcard as a separate section - Questions that test key facts, dates, and connections - Concise but comprehensive answers - Organized by historical period

它明确了两点：

• Goal：为即将到来的历史考试创建交互式闪卡（flashcards）；
• Format：输出 Markdown 格式的问答对，每张闪卡独立成节，问题覆盖关键事实、日期与关联，答案简洁而全面，并按历史时期组织。

在官网首页，Section0.astro会把question.txt按Goal:与Format:切分，分别渲染成蓝色 Goal 卡片与绿色 Format 卡片（见 Section0.astro）。把prompt.md（Context）与question.txt（Goal + Format）组合在一起，才构成一个完整可用的 LLM 请求——这正是"上下文工程"的完整闭环：资料由工具生成，任务由用户定义。

四、输出格式的源头：默认 Markdown 模板源码对照

prompt.md并非手写，而是 Handlebars 模板渲染的产物。仓库内置的默认 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}}

对照后可以确认：

• Project Path、Source Tree、`{{path}}`:与内容代码块，与prompt.md逐行对应；
• 模板还预留了code_map（实体级代码地图，列出函数/类及其行号）、git_diff（Git 差异）等可选区块——history_notes只是纯文本笔记，没有这些信息，因此{{#if}}条件让它们不输出；
• 模板使用no_escape注册（见 template.rs），即不进行 HTML 转义，保证代码与笔记内容原样输出。

模板系统支持的全部内置变量（absolute_code_path、source_tree、files、path、code、extension、no_codeblock、git_diff、git_diff_branch、git_log_branch等）都登记在 template.rs 的文档注释中，你也可以用--template参数传入自定义 Handlebars 模板替换默认行为。

五、从目录到 prompt：生成流程与背后的源码机制

1. 一条命令完成转换

在官网示例中，生成history_notes这份上下文使用的命令是：

$ code2prompt history_notes

即把history_notes目录作为path参数传入。code2prompt 会遍历该目录、过滤不需要的文件、按模板渲染，最后把结果写入 stdout（可配合--output重定向到文件）。

2. 文件选择：SelectionEngine 的取舍逻辑

目录里哪些文件进入最终 prompt，由文件选择机制决定。核心实现位于 selection.rs：

• SelectionEngine组合了基础模式过滤（include/exclude 的 glob 模式）与用户动作（显式 Include/Exclude）；
• 采用specific > generic（具体优先于通用）、recent > old（新动作优先于旧动作）的优先级规则（见 selection.rs）；
• 命中结果会写入缓存，避免重复计算（见 selection.rs）。

history_notes示例没有任何过滤参数，因此四个.txt文件全部默认入选，目录树与内容一一对应。

3. 可调配置：Code2PromptConfig

输出的形态还可以通过配置项微调。Code2PromptConfig及其 Builder 定义在 configuration.rs，与本次示例相关的关键参数包括：

• line_numbers：是否为代码内容加行号；
• absolute_path：输出绝对路径而非相对路径（示例中未开启，故显示为history_notes/...的相对形式）；
• full_directory_tree：生成完整的目录树，忽略 include/exclude 规则；
• no_codeblock：不把文件内容包在 Markdown 代码栅栏里（模板中有对应分支，见 default_template_md.hbs）；
• hidden、follow_symlinks：是否包含隐藏文件、是否跟随符号链接。

六、举一反三：同一机制处理不同资料类型

history_notes只是三个示例之一，其余示例验证了同一套流程在不同资料类型上的通用性：

• node_app（代码库）：website/src/assets/examples/node_app/prompt.md展示了一个 Node.js 应用目录（src/index.js、src/utils.js、data/sample.json、README.md），代码文件以js/json/md代码块呈现——这就是上述模板中extension变量的实际效果；
• my_recipes（菜谱数据库）：website/src/assets/examples/my_recipes/prompt.md展示了一个纯文本菜谱目录（pantry原料库 +recipes菜谱清单），同样走"目录树 + 逐文件注入"的格式。

三个示例说明：无论你的目录里是代码、结构化数据还是纯文本笔记，code2prompt 的默认模板都能稳定产出统一的、模型友好的上下文格式。

七、实操建议：复现并自定义你自己的上下文

基于history_notes示例，你可以按以下步骤把任意资料目录变成 LLM 上下文：

1. 准备目录：把笔记、文档或资料按主题放入子目录，保持清晰的层级（如history/、meta/），因为目录树本身就是给模型的"地图"；
2. 运行命令：code2prompt 你的目录名，确认输出包含Project Path、Source Tree与逐文件内容区；
3. 组合任务指令：参照question.txt的写法，用Goal:与Format:两句明确告诉模型要做什么、输出成什么结构，与生成出的 Context 一起发送；
4. 按需定制：需要调整结构时，参考 default_template_md.hbs 与 template.rs 中登记的变量表，编写自己的 Handlebars 模板；需要精细控制包含范围时，利用 include/exclude 模式与 selection.rs 的优先级规则。

history_notes看似只是几行文本笔记，但它完整呈现了 code2prompt 的核心价值：把零散的个人资料变成结构清晰、可直接投喂给 LLM 的上下文——这正是"上下文工程"在日常资料管理场景下的落地样板。

【免费下载链接】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