拓冰网站定制 
文档教程人工智能大模型AI Agent【免费下载链接】12-factor-agentsWhat are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?项目地址https://gitcode.com/GitHub_Trending/12/12-factor-agents点击查看免费下载导读walkthroughgen 是 12-factor-agents 仓库中一套专用于生成 walkthrough逐步演练教程、tutorial、README 与技术文档的命令行工具。它让你只用一份结构简单的walkthrough.yaml描述教程的每一步即可同时产出人类可读的 Markdown 教程、按章节划分的可运行工作目录以及累计到最终状态的完整工程。读完本文你将掌握 walkthrough.yaml 的完整配置语法targets / sections / steps / init、wtg build与walkthroughgen generate的用法、diff 与 cp 指令的生成逻辑以及如何在 packages/walkthroughgen 源码与测试的佐证下为任意技术主题搭建可维护的实战教程。1. walkthroughgen 是什么一次 YAML三种产物walkthroughgen 的核心思想非常朴素教程的内容源是每个步骤最终应该存在的文件快照而不是手工写死的 Markdown。作者只需按步骤编号维护一组增量文件如00-package.json、01-index.ts、02-cli.ts再用 YAML 描述何时复制哪个文件、何时运行哪条命令、期待什么输出工具便会自动渲染出教程正文并顺带构建出可运行的中间工程状态。其安装方式对应 packages/walkthroughgen/readme.mdnpm install -g walkthroughgen而 prompt.md 给出了两套并行的命令形式一套是全局命令wtg build默认读取当前目录下的walkthrough.yaml另一套是 src/cli.ts 中实际实现并经过端到端测试验证的命令walkthroughgen generate yaml-filenpm i -g wtg wtg build # 等价地也可以显式指定配置文件 walkthroughgen generate walkthrough.yaml从 src/cli.ts 的入口逻辑可以看到 CLI 的完整形态支持--help / -hgenerate子命令必须携带 YAML 文件路径缺少路径、文件不存在、YAML 解析失败、缺少title或text必填字段时都会给出明确错误提示。这些分支全部被 test/e2e/test-e2e.ts 中的CLI basics测试组覆盖可作为命令行行为的事实依据。在开始前先建立标准的教程目录结构以 examples/typescript 为例├── walkthrough │ ├── 00-package-lock.json │ ├── 00-package.json │ ├── 01-index.ts │ ├── 02-cli.ts │ └── 02-index.ts └── walkthrough.yaml其中walkthrough/目录存放每个步骤引入的增量文件文件名前的数字序号即步骤次序walkthrough.yaml负责编排。运行构建后会在build/下生成三样产物walkthrough.md完整教程、by-section/每节一个可运行工作目录、final/累计到最终状态的完整工程。2. walkthrough.yaml 配置详解这是整个工具的核心。一份最小但完整的配置取自 examples/typescript/walkthrough.yamltitle: setting up a typescript cli text: this is a walkthrough for setting up a typescript cli targets: - markdown: ./build/walkthrough.md # 生成 walkthrough.md 文件 onChange: # 默认行为——文件变更时展示 diff 与 cp 命令 diff: true cp: true newFiles: # 新文件出现时只展示复制命令 cat: false cp: true - final: ./build/final # 将最终工程输出到 final 目录 - folders: ./build/by-section # 为每个 section 生成独立工作目录 sections: - name: setup title: Copy initial files steps: - file: {src: ./walkthrough/00-package.json, dest: package.json} - file: {src: ./walkthrough/00-package-lock.json, dest: package-lock.json} - file: {src: ./walkthrough/00-tsconfig.json, dest: tsconfig.json} - name: initialize title: Initialize the project steps: - text: initialize the project command: | npm install - text: then add index.ts file: {src: ./walkthrough/01-index.ts, dest: src/index.ts} - text: run it with tsx command: | npx tsx src/index.ts results: - text: you should see a hello world message code: | hello world - name: add-cli title: Add a CLI steps: - text: add a cli file: {src: ./walkthrough/02-cli.ts, dest: src/cli.ts} - text: add a cli file: {src: ./walkthrough/02-index.ts, dest: src/index.ts}2.1 顶层字段字段类型说明titlestring教程标题必填会成为 Markdown 的 H1textstring教程导读文本必填紧跟 H1 输出targetsarray输出目标配置markdown / final / folderssectionsarray教程各章节每个 section 含name、title、text与stepsinitarray可选的初始步骤列表见 examples/walkthroughgen/walkthrough.yaml在首个 section 之前执行从 src/cli.ts 的WalkthroughData接口可以看出title与text是强校验字段cli中会直接断言二者必须为 string否则报Invalid YAML structure ... Missing required title or text fields。2.2 targets三种输出目标targets同时声明产什么样的文档和构建什么样的工程每个 target 有各自的开关markdown 目标markdown: ./build/walkthrough.md指定 Markdown 输出路径。onChange.diff对已有文件被覆盖的步骤是否渲染diff代码块onChange.cp对文件变更步骤是否给出cp命令当 diff 已展示时可折叠为detailssummaryskip this step/summarynewFiles.cat对新文件是否展示完整内容newFiles.cp对新文件是否给出cp命令。final 目标final: ./build/final把全部步骤执行完毕后的工程状态输出到指定目录。folders 目标folders: ./build/by-section为每个 section 生成一个独立工作目录该目标还支持对象写法以携带更多选项见 2.4。在 examples/typescript/walkthrough.yaml 中三种目标同时启用src/cli.ts 的处理顺序是先构建 folders 目标内部用一个临时工作目录逐步累积状态最后再渲染 Markdown因而两份产物共享同一份 YAML 语义。2.3 sections 与 steps教程的章节编排每个 section 代表教程的一个逻辑章节sections: - name: setup # 用于文件夹命名与 skip 数组匹配 title: Copy initial files # 展示标题 text: Set up the base files # 章节描述可选 steps: # ... 步骤列表name是可选但推荐的关键字段它会参与目录命名与 skip 过滤见 2.4。在 src/cli.ts 的getSectionBaseName中可以看到降级逻辑若未提供name则用title转小写、非字母数字字符替换为-生成目录名。steps是 section 的最小动作单元支持四类动作1文本说明——纯提示文字直接进入 Markdown- text: initialize the project2文件复制——把 walkthrough 目录下的增量文件复制到目标工程位置- file: {src: ./walkthrough/01-index.ts, dest: src/index.ts}渲染时会输出cp ./walkthrough/01-index.ts src/index.ts并把源文件内容折叠展示在detailssummaryshow file/summary中。3命令执行——写进 Markdown 的 shell 命令- text: run it with tsx command: | npx tsx src/index.ts注意command默认只写入教程文本并不会真的在构建时执行只有显式标记incremental: true的命令才会在 folders / final 构建时于对应工作目录中真实运行execSync以cwd: workingDir执行这一点由 src/cli.ts 中step.command step.incremental true的判断与 test/e2e/test-e2e.ts 中should handle incremental commands correctly用例共同印证。4期望输出results——给读者预期反馈- command: npm run test results: - text: You should see: code: | All tests passed!results.code会以四空格缩进的等宽块写入 Markdown让读者自行核对命令输出。此外还有目录创建动作- dir: {create: true, path: src}在 Markdown 中渲染为mkdir -p src并在 folders 构建时真实创建目录。2.4 folders 目标的进阶选项skip 与 final在 prompt.md 的示例中 folders 目标只写了基础路径形式而仓库的 readme.md 与 workshops/2025-05/walkthrough.yaml 展示了更完整的对象写法targets: - folders: path: ./build/by-section # 分节工作目录的根路径 skip: [cleanup] # 跳过这些 name 的 section不为它们建目录 final: dirName: final # 最终状态目录名path所有分节目录的父路径。skip某些纯准备 / 清理章节如 cleanup不需要单独工作目录通过name匹配跳过同时该 section 的步骤仍会写入 Markdown只是不生成文件夹。final.dirName在path下生成一个累积了全部非跳过章节状态的最终目录并写入一份拼接而成的累计 README。src/cli.ts 的文件夹命名逻辑为序号-基名非跳过的 section 按00-、01-递增编号编号只计可见章节例如00-setup、01-add-cli。每个 section 目录中会生成自己的README.md内容由generateRichSectionMarkdown基于该目录当下的文件快照渲染——这正是每个章节都自带可运行工程与说明文档的实现来源。3. 构建产物与运行效果运行wtg build或walkthroughgen generate walkthrough.yaml之后基于 prompt.md 中的目标配置会得到如下目录树├── walkthrough │ ├── 00-package-lock.json │ ├── 00-package.json │ ├── 01-index.ts │ ├── 02-cli.ts │ └── 02-index.ts ├── build │ ├── by-section │ │ ├── 00-initialize # 只包含 init 阶段的文件 │ │ │ ├── readme.md # 该章节的步骤说明 │ │ │ ├── package.json │ │ │ ├── package-lock.json │ │ │ └── tsconfig.json │ │ └── 01-add-cli # 包含到第 1 节开始前的所有文件 │ │ ├── readme.md │ │ ├── package.json │ │ ├── package-lock.json │ │ ├── tsconfig.json │ │ └── src │ │ └── index.ts │ ├── final # 全部步骤执行后的最终工程 │ │ ├── package.json │ │ ├── package-lock.json │ │ ├── tsconfig.json │ │ └── src │ │ ├── cli.ts │ │ └── index.ts │ └── walkthrough.md关键语义值得强调第 N 个 section 的文件夹只包含前 N-1 个 section 执行完毕的状态不含它自身步骤引入的文件。这条规则由 src/cli.ts 的构建流程保证——工具先把当前累计状态复制进该 section 目录再执行该 section 的步骤推进临时工作目录test/e2e/test-e2e.ts 中should include files from previous sections与should correctly generate section folders...两个用例对第一节不含自身文件、第二节含第一节文件但不含自身文件做了精确断言。生成的walkthrough.md形态如下取自 prompt.md 的渲染示意# Setting up a typescript cli this is a walkthrough for setting up a typescript cli ## Copy initial files cp walkthrough/00-package.json package.json cp walkthrough/00-package-lock.json package-lock.json cp walkthrough/00-tsconfig.json tsconfig.json ## Initialize the project initialize the project npm install then add index.ts cp walkthrough/01-index.ts src/index.ts and run it with tsx npx tsx src/index.ts you should see a hello world message hello world ## Add a CLI add a cli cp walkthrough/02-cli.ts src/cli.ts update index.ts to use the cli diff const main async () { return cli(); }; main(); or just: cp walkthrough/02-index.ts src/index.ts4. 源码视角diff、cp 与show file是如何生成的Markdown 渲染并非简单的 YAML 到文本直译而是带状态追踪的动态生成。src/cli.ts 维护一个virtualFileState: Mapstring, string按步骤顺序记录每个目标文件的当前内容新文件虚拟状态中不存在输出cp命令并附加detailssummaryshow file/summary折叠块展示完整内容语言按扩展名推断baml映射为rust高亮。覆盖已有文件若onChange.diff: true且新旧内容不同则通过formatMinimalDiff生成精简 diff。该函数基于diff库的createPatch并过滤掉删除行与新增行文本相同的无效配对避免出现无意义的变化行diff 之后若onChange.cp: truecp 命令会被折叠进detailssummaryskip this step/summary因为读者可以直接按 diff 手动修改。每次处理后同步更新虚拟状态因此跨 section 的多次覆盖也能正确追踪test/e2e/test-e2e.ts 中should show diffs when files are overwritten用例验证了 v1 → v2 的package.json覆盖会产出diff块与skip this step折叠。同样section README 的生成generateRichSectionMarkdown会先递归读取该 section 目录的实际文件建立快照再按同样规则渲染 diff、cp 与 show file 块保证每个by-section子目录内的 README 与文件状态严格一致。5. 实战示例仓库里的两种用法5.1 TypeScript CLI 教程最小闭环示例examples/typescript/walkthrough.yaml 是 prompt.md 中的可运行示例配套的增量文件位于 examples/typescript/walkthrough00-package.json、00-package-lock.json、00-tsconfig.json、01-index.ts、02-cli.ts、02-index.ts。它演示了从复制初始文件到npm install tsx 运行再到引入 CLI 模块的完整三步编排是学习配置语法的最小闭环。5.2 自举示例用 walkthroughgen 教 walkthroughgenexamples/walkthroughgen/walkthrough.yaml 是工具的自我教学示例——它把 walkthroughgen 的初始化与构建过程本身写成教程章节中用到npx wtg init my-project、npx wtg build等真实命令并展示了init字段的用法在第一个 section 前批量复制初始文件。5.3 规模化实践12-factor agent 工作坊仓库把 walkthroughgen 用在了真实教学场景。workshops/2025-05/walkthrough.yaml 是一份 671 行的完整工作坊配置主题是从零构建 12-factor agent 模板包含 cleanup / hello-world / cli-and-agent 等十余个章节每个章节的增量文件对应对应编号的walkthrough/XX-*.{ts,baml}文件见 workshops/2025-05/walkthrough 目录并大量使用incremental: true让npm install、npx baml-cli init、npx baml-cli generate等命令在 folders 构建时真实执行。它是 walkthroughgen 在真实技术培训中的规模化样例最终由同一份 YAML 同时产出 walkthrough.md、by-section 分节工程与 final 完整工程。6. 使用建议与注意事项结合 readme.md 的 Tips 与源码行为实践中有几个要点用有意义的name它直接决定分节目录名00-name也会参与skip匹配不写name时由title降级生成。incremental: true只作用于 folders 构建普通command步骤仅出现在 Markdown 中不会在构建时执行只有显式标记的命令会在工作目录真实运行。二者都会被写入 Markdown因此展示命令与构建状态可以解耦。善用skip排除准备/清理章节cleanup 这类不产出内容的章节无需独立目录但它的说明仍会保留在教程正文里参考 workshops/2025-05/walkthrough.yaml 的 cleanup 章节。diff 自动化的前提是步骤顺序正确diff 依赖虚拟文件状态的先后覆盖因此增量文件要按00-、01-、02-的顺序编号并保证 dest 路径一致才能得到改了什么而不是删了又加。命令的执行环境folders 构建会在临时工作目录中逐步累积状态incremental命令以该目录为cwd执行execSync(step.command, { cwd: workingDir, stdio: inherit })因此依赖相对路径的命令要确保在对应步骤时文件已就位。7. 总结walkthroughgen 把写教程从重复的手工 Markdown 排版收敛为维护增量文件 一份 YAML 编排。同一份配置同时驱动三类产物面向读者的walkthrough.md、面向分步实践的by-section/工作目录、面向结果验收的final/工程而 diff、cp 指令与 show file 折叠块全部由源码自动生成杜绝了教程与代码不同步的问题。其核心实现集中在 packages/walkthroughgen/src/cli.ts行为契约由 packages/walkthroughgen/test/e2e/test-e2e.ts 全面锁定且已在 workshops/2025-05/walkthrough.yaml 这样的大型真实工作坊中得到规模化验证——如果你正在维护技术教程、培训材料或项目 README这是一个值得引入仓库的文档自动化基础设施。赞分享文档教程人工智能大模型AI Agent【免费下载链接】12-factor-agentsWhat are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?项目地址https://gitcode.com/GitHub_Trending/12/12-factor-agents点击查看免费下载相关推荐用 YAML 驱动生成步进式教程walkthroughgen 配置、原理与实战指南用 YAML 驱动生成步进式教程walkthroughgen 配置、原理与实战指南 导读 walkthroughgen 是 12 factor agents文档教程人工智能大模型AI AgentTerraforming Rails工厂模式优化使用FactoryLinter避免测试数据冲突的完整教程Terraforming Rails工厂模式优化使用FactoryLinter避免测试数据冲突的完整教程 在Rails应用开发中测试数据的稳定性直接影响测试doctoc: 自动化Markdown文件目录生成工具教程doctoc: 自动化Markdown文件目录生成工具教程 1. 项目目录结构及介绍 doctoc 是一个用于自动为Markdown文件生成目录的小型命令行工具开发工具上一篇ServerScan使用教程下一篇Bitdefender x86 反汇编器 (bddisasm) 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 walkthroughgen 从 YAML 生成实战教程：walkthrough、分节工作目录与 final 工程一体的文档自动化方案
文档教程人工智能大模型AI Agent【免费下载链接】12-factor-agentsWhat are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?项目地址https://gitcode.com/GitHub_Trending/12/12-factor-agents点击查看免费下载导读walkthroughgen 是 12-factor-agents 仓库中一套专用于生成 walkthrough逐步演练教程、tutorial、README 与技术文档的命令行工具。它让你只用一份结构简单的walkthrough.yaml描述教程的每一步即可同时产出人类可读的 Markdown 教程、按章节划分的可运行工作目录以及累计到最终状态的完整工程。读完本文你将掌握 walkthrough.yaml 的完整配置语法targets / sections / steps / init、wtg build与walkthroughgen generate的用法、diff 与 cp 指令的生成逻辑以及如何在 packages/walkthroughgen 源码与测试的佐证下为任意技术主题搭建可维护的实战教程。1. walkthroughgen 是什么一次 YAML三种产物walkthroughgen 的核心思想非常朴素教程的内容源是每个步骤最终应该存在的文件快照而不是手工写死的 Markdown。作者只需按步骤编号维护一组增量文件如00-package.json、01-index.ts、02-cli.ts再用 YAML 描述何时复制哪个文件、何时运行哪条命令、期待什么输出工具便会自动渲染出教程正文并顺带构建出可运行的中间工程状态。其安装方式对应 packages/walkthroughgen/readme.mdnpm install -g walkthroughgen而 prompt.md 给出了两套并行的命令形式一套是全局命令wtg build默认读取当前目录下的walkthrough.yaml另一套是 src/cli.ts 中实际实现并经过端到端测试验证的命令walkthroughgen generate yaml-filenpm i -g wtg wtg build # 等价地也可以显式指定配置文件 walkthroughgen generate walkthrough.yaml从 src/cli.ts 的入口逻辑可以看到 CLI 的完整形态支持--help / -hgenerate子命令必须携带 YAML 文件路径缺少路径、文件不存在、YAML 解析失败、缺少title或text必填字段时都会给出明确错误提示。这些分支全部被 test/e2e/test-e2e.ts 中的CLI basics测试组覆盖可作为命令行行为的事实依据。在开始前先建立标准的教程目录结构以 examples/typescript 为例├── walkthrough │ ├── 00-package-lock.json │ ├── 00-package.json │ ├── 01-index.ts │ ├── 02-cli.ts │ └── 02-index.ts └── walkthrough.yaml其中walkthrough/目录存放每个步骤引入的增量文件文件名前的数字序号即步骤次序walkthrough.yaml负责编排。运行构建后会在build/下生成三样产物walkthrough.md完整教程、by-section/每节一个可运行工作目录、final/累计到最终状态的完整工程。2. walkthrough.yaml 配置详解这是整个工具的核心。一份最小但完整的配置取自 examples/typescript/walkthrough.yamltitle: setting up a typescript cli text: this is a walkthrough for setting up a typescript cli targets: - markdown: ./build/walkthrough.md # 生成 walkthrough.md 文件 onChange: # 默认行为——文件变更时展示 diff 与 cp 命令 diff: true cp: true newFiles: # 新文件出现时只展示复制命令 cat: false cp: true - final: ./build/final # 将最终工程输出到 final 目录 - folders: ./build/by-section # 为每个 section 生成独立工作目录 sections: - name: setup title: Copy initial files steps: - file: {src: ./walkthrough/00-package.json, dest: package.json} - file: {src: ./walkthrough/00-package-lock.json, dest: package-lock.json} - file: {src: ./walkthrough/00-tsconfig.json, dest: tsconfig.json} - name: initialize title: Initialize the project steps: - text: initialize the project command: | npm install - text: then add index.ts file: {src: ./walkthrough/01-index.ts, dest: src/index.ts} - text: run it with tsx command: | npx tsx src/index.ts results: - text: you should see a hello world message code: | hello world - name: add-cli title: Add a CLI steps: - text: add a cli file: {src: ./walkthrough/02-cli.ts, dest: src/cli.ts} - text: add a cli file: {src: ./walkthrough/02-index.ts, dest: src/index.ts}2.1 顶层字段字段类型说明titlestring教程标题必填会成为 Markdown 的 H1textstring教程导读文本必填紧跟 H1 输出targetsarray输出目标配置markdown / final / folderssectionsarray教程各章节每个 section 含name、title、text与stepsinitarray可选的初始步骤列表见 examples/walkthroughgen/walkthrough.yaml在首个 section 之前执行从 src/cli.ts 的WalkthroughData接口可以看出title与text是强校验字段cli中会直接断言二者必须为 string否则报Invalid YAML structure ... Missing required title or text fields。2.2 targets三种输出目标targets同时声明产什么样的文档和构建什么样的工程每个 target 有各自的开关markdown 目标markdown: ./build/walkthrough.md指定 Markdown 输出路径。onChange.diff对已有文件被覆盖的步骤是否渲染diff代码块onChange.cp对文件变更步骤是否给出cp命令当 diff 已展示时可折叠为detailssummaryskip this step/summarynewFiles.cat对新文件是否展示完整内容newFiles.cp对新文件是否给出cp命令。final 目标final: ./build/final把全部步骤执行完毕后的工程状态输出到指定目录。folders 目标folders: ./build/by-section为每个 section 生成一个独立工作目录该目标还支持对象写法以携带更多选项见 2.4。在 examples/typescript/walkthrough.yaml 中三种目标同时启用src/cli.ts 的处理顺序是先构建 folders 目标内部用一个临时工作目录逐步累积状态最后再渲染 Markdown因而两份产物共享同一份 YAML 语义。2.3 sections 与 steps教程的章节编排每个 section 代表教程的一个逻辑章节sections: - name: setup # 用于文件夹命名与 skip 数组匹配 title: Copy initial files # 展示标题 text: Set up the base files # 章节描述可选 steps: # ... 步骤列表name是可选但推荐的关键字段它会参与目录命名与 skip 过滤见 2.4。在 src/cli.ts 的getSectionBaseName中可以看到降级逻辑若未提供name则用title转小写、非字母数字字符替换为-生成目录名。steps是 section 的最小动作单元支持四类动作1文本说明——纯提示文字直接进入 Markdown- text: initialize the project2文件复制——把 walkthrough 目录下的增量文件复制到目标工程位置- file: {src: ./walkthrough/01-index.ts, dest: src/index.ts}渲染时会输出cp ./walkthrough/01-index.ts src/index.ts并把源文件内容折叠展示在detailssummaryshow file/summary中。3命令执行——写进 Markdown 的 shell 命令- text: run it with tsx command: | npx tsx src/index.ts注意command默认只写入教程文本并不会真的在构建时执行只有显式标记incremental: true的命令才会在 folders / final 构建时于对应工作目录中真实运行execSync以cwd: workingDir执行这一点由 src/cli.ts 中step.command step.incremental true的判断与 test/e2e/test-e2e.ts 中should handle incremental commands correctly用例共同印证。4期望输出results——给读者预期反馈- command: npm run test results: - text: You should see: code: | All tests passed!results.code会以四空格缩进的等宽块写入 Markdown让读者自行核对命令输出。此外还有目录创建动作- dir: {create: true, path: src}在 Markdown 中渲染为mkdir -p src并在 folders 构建时真实创建目录。2.4 folders 目标的进阶选项skip 与 final在 prompt.md 的示例中 folders 目标只写了基础路径形式而仓库的 readme.md 与 workshops/2025-05/walkthrough.yaml 展示了更完整的对象写法targets: - folders: path: ./build/by-section # 分节工作目录的根路径 skip: [cleanup] # 跳过这些 name 的 section不为它们建目录 final: dirName: final # 最终状态目录名path所有分节目录的父路径。skip某些纯准备 / 清理章节如 cleanup不需要单独工作目录通过name匹配跳过同时该 section 的步骤仍会写入 Markdown只是不生成文件夹。final.dirName在path下生成一个累积了全部非跳过章节状态的最终目录并写入一份拼接而成的累计 README。src/cli.ts 的文件夹命名逻辑为序号-基名非跳过的 section 按00-、01-递增编号编号只计可见章节例如00-setup、01-add-cli。每个 section 目录中会生成自己的README.md内容由generateRichSectionMarkdown基于该目录当下的文件快照渲染——这正是每个章节都自带可运行工程与说明文档的实现来源。3. 构建产物与运行效果运行wtg build或walkthroughgen generate walkthrough.yaml之后基于 prompt.md 中的目标配置会得到如下目录树├── walkthrough │ ├── 00-package-lock.json │ ├── 00-package.json │ ├── 01-index.ts │ ├── 02-cli.ts │ └── 02-index.ts ├── build │ ├── by-section │ │ ├── 00-initialize # 只包含 init 阶段的文件 │ │ │ ├── readme.md # 该章节的步骤说明 │ │ │ ├── package.json │ │ │ ├── package-lock.json │ │ │ └── tsconfig.json │ │ └── 01-add-cli # 包含到第 1 节开始前的所有文件 │ │ ├── readme.md │ │ ├── package.json │ │ ├── package-lock.json │ │ ├── tsconfig.json │ │ └── src │ │ └── index.ts │ ├── final # 全部步骤执行后的最终工程 │ │ ├── package.json │ │ ├── package-lock.json │ │ ├── tsconfig.json │ │ └── src │ │ ├── cli.ts │ │ └── index.ts │ └── walkthrough.md关键语义值得强调第 N 个 section 的文件夹只包含前 N-1 个 section 执行完毕的状态不含它自身步骤引入的文件。这条规则由 src/cli.ts 的构建流程保证——工具先把当前累计状态复制进该 section 目录再执行该 section 的步骤推进临时工作目录test/e2e/test-e2e.ts 中should include files from previous sections与should correctly generate section folders...两个用例对第一节不含自身文件、第二节含第一节文件但不含自身文件做了精确断言。生成的walkthrough.md形态如下取自 prompt.md 的渲染示意# Setting up a typescript cli this is a walkthrough for setting up a typescript cli ## Copy initial files cp walkthrough/00-package.json package.json cp walkthrough/00-package-lock.json package-lock.json cp walkthrough/00-tsconfig.json tsconfig.json ## Initialize the project initialize the project npm install then add index.ts cp walkthrough/01-index.ts src/index.ts and run it with tsx npx tsx src/index.ts you should see a hello world message hello world ## Add a CLI add a cli cp walkthrough/02-cli.ts src/cli.ts update index.ts to use the cli diff const main async () { return cli(); }; main(); or just: cp walkthrough/02-index.ts src/index.ts4. 源码视角diff、cp 与show file是如何生成的Markdown 渲染并非简单的 YAML 到文本直译而是带状态追踪的动态生成。src/cli.ts 维护一个virtualFileState: Mapstring, string按步骤顺序记录每个目标文件的当前内容新文件虚拟状态中不存在输出cp命令并附加detailssummaryshow file/summary折叠块展示完整内容语言按扩展名推断baml映射为rust高亮。覆盖已有文件若onChange.diff: true且新旧内容不同则通过formatMinimalDiff生成精简 diff。该函数基于diff库的createPatch并过滤掉删除行与新增行文本相同的无效配对避免出现无意义的变化行diff 之后若onChange.cp: truecp 命令会被折叠进detailssummaryskip this step/summary因为读者可以直接按 diff 手动修改。每次处理后同步更新虚拟状态因此跨 section 的多次覆盖也能正确追踪test/e2e/test-e2e.ts 中should show diffs when files are overwritten用例验证了 v1 → v2 的package.json覆盖会产出diff块与skip this step折叠。同样section README 的生成generateRichSectionMarkdown会先递归读取该 section 目录的实际文件建立快照再按同样规则渲染 diff、cp 与 show file 块保证每个by-section子目录内的 README 与文件状态严格一致。5. 实战示例仓库里的两种用法5.1 TypeScript CLI 教程最小闭环示例examples/typescript/walkthrough.yaml 是 prompt.md 中的可运行示例配套的增量文件位于 examples/typescript/walkthrough00-package.json、00-package-lock.json、00-tsconfig.json、01-index.ts、02-cli.ts、02-index.ts。它演示了从复制初始文件到npm install tsx 运行再到引入 CLI 模块的完整三步编排是学习配置语法的最小闭环。5.2 自举示例用 walkthroughgen 教 walkthroughgenexamples/walkthroughgen/walkthrough.yaml 是工具的自我教学示例——它把 walkthroughgen 的初始化与构建过程本身写成教程章节中用到npx wtg init my-project、npx wtg build等真实命令并展示了init字段的用法在第一个 section 前批量复制初始文件。5.3 规模化实践12-factor agent 工作坊仓库把 walkthroughgen 用在了真实教学场景。workshops/2025-05/walkthrough.yaml 是一份 671 行的完整工作坊配置主题是从零构建 12-factor agent 模板包含 cleanup / hello-world / cli-and-agent 等十余个章节每个章节的增量文件对应对应编号的walkthrough/XX-*.{ts,baml}文件见 workshops/2025-05/walkthrough 目录并大量使用incremental: true让npm install、npx baml-cli init、npx baml-cli generate等命令在 folders 构建时真实执行。它是 walkthroughgen 在真实技术培训中的规模化样例最终由同一份 YAML 同时产出 walkthrough.md、by-section 分节工程与 final 完整工程。6. 使用建议与注意事项结合 readme.md 的 Tips 与源码行为实践中有几个要点用有意义的name它直接决定分节目录名00-name也会参与skip匹配不写name时由title降级生成。incremental: true只作用于 folders 构建普通command步骤仅出现在 Markdown 中不会在构建时执行只有显式标记的命令会在工作目录真实运行。二者都会被写入 Markdown因此展示命令与构建状态可以解耦。善用skip排除准备/清理章节cleanup 这类不产出内容的章节无需独立目录但它的说明仍会保留在教程正文里参考 workshops/2025-05/walkthrough.yaml 的 cleanup 章节。diff 自动化的前提是步骤顺序正确diff 依赖虚拟文件状态的先后覆盖因此增量文件要按00-、01-、02-的顺序编号并保证 dest 路径一致才能得到改了什么而不是删了又加。命令的执行环境folders 构建会在临时工作目录中逐步累积状态incremental命令以该目录为cwd执行execSync(step.command, { cwd: workingDir, stdio: inherit })因此依赖相对路径的命令要确保在对应步骤时文件已就位。7. 总结walkthroughgen 把写教程从重复的手工 Markdown 排版收敛为维护增量文件 一份 YAML 编排。同一份配置同时驱动三类产物面向读者的walkthrough.md、面向分步实践的by-section/工作目录、面向结果验收的final/工程而 diff、cp 指令与 show file 折叠块全部由源码自动生成杜绝了教程与代码不同步的问题。其核心实现集中在 packages/walkthroughgen/src/cli.ts行为契约由 packages/walkthroughgen/test/e2e/test-e2e.ts 全面锁定且已在 workshops/2025-05/walkthrough.yaml 这样的大型真实工作坊中得到规模化验证——如果你正在维护技术教程、培训材料或项目 README这是一个值得引入仓库的文档自动化基础设施。赞分享文档教程人工智能大模型AI Agent【免费下载链接】12-factor-agentsWhat are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?项目地址https://gitcode.com/GitHub_Trending/12/12-factor-agents点击查看免费下载相关推荐用 YAML 驱动生成步进式教程walkthroughgen 配置、原理与实战指南用 YAML 驱动生成步进式教程walkthroughgen 配置、原理与实战指南 导读 walkthroughgen 是 12 factor agents文档教程人工智能大模型AI AgentTerraforming Rails工厂模式优化使用FactoryLinter避免测试数据冲突的完整教程Terraforming Rails工厂模式优化使用FactoryLinter避免测试数据冲突的完整教程 在Rails应用开发中测试数据的稳定性直接影响测试doctoc: 自动化Markdown文件目录生成工具教程doctoc: 自动化Markdown文件目录生成工具教程 1. 项目目录结构及介绍 doctoc 是一个用于自动为Markdown文件生成目录的小型命令行工具开发工具上一篇ServerScan使用教程下一篇Bitdefender x86 反汇编器 (bddisasm) 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考