AI驱动模板化工作流：从Vibe Coding到可复用课程站点生成-平芜编程栈

1. 项目概述：从“一次性生成”到“可复用模板”的思维跃迁

如果你和我一样，在过去一年里深度体验过各种AI代码生成工具，那你一定对那种“瞬间生成一个漂亮网页”的兴奋感不陌生。输入一段描述，几秒钟后，一个看起来相当不错的页面就摆在你面前。这种被称为“Vibe Coding”或“氛围编程”的方式，确实让人着迷。但兴奋过后，现实问题接踵而至：生成的代码结构混乱，想微调一个按钮样式却无从下手；下次想做个类似页面，又得从头描述一遍，风格还无法统一；最要命的是，这些“一次性”的产出物，根本无法沉淀为你的资产，更别提团队协作了。

这正是我开发agent-skill-lecture-builder这个项目的初衷。它不是一个简单的页面生成器，而是一套完整的“模板化工作流”解决方案。核心思想是：将AI从“随机创作者”转变为“结构化执行者”。我们不再依赖AI去凭空创造整个页面，而是让它基于我们预先定义好的、高质量的模板和规则去填充内容、执行构建。这样一来，生成的结果是可控的、风格一致的、并且完全可维护的。

这个项目本质上是一个课程讲义网页的静态站点生成器，但它被深度集成到了AI工作流中。你只需要提供课程主题或原始的Markdown讲稿，通过一个封装好的“Agent Skill”（智能体技能），AI就能自动帮你完成从内容结构化、配置生成、页面构建到预览部署的全过程。最终产出的不是一个黑盒，而是一个标准的、由Markdown和YAML配置文件驱动的静态网站目录，你可以用Git管理，可以手动调整，可以无限次复用。

2. 核心设计思路：为何选择“模板+Agent”的双引擎架构

在构思这个项目时，我评估过几种主流方案。最简单的是直接用AI生成完整的HTML/CSS/JS，但正如开头所说，这不可维护。另一种是使用现成的静态站点生成器（如Hugo、Jekyll），但它们的学习曲线和配置复杂度，又让快速生成变得不那么“AI友好”。

因此，我设计了一个折中但更强大的“双引擎”架构：模板引擎 + Agent执行引擎。

2.1 模板引擎：定义输出的“骨”与“肉”

模板引擎负责将结构化的内容（Markdown）和配置（YAML）渲染成最终的HTML页面。它的核心是一个高度语义化的Markdown扩展语法和一套对应的HTML/CSS模板。

为什么选择扩展Markdown，而不是纯HTML？

内容与样式分离：讲师或内容创作者可以专注于撰写讲义内容，无需关心复杂的HTML标签和CSS类名。#代表章节，>代表引言，[bonus]代表弹窗，直观易懂。
AI友好：Markdown是AI最擅长理解和生成的格式之一。让AI根据规则生成或转换Markdown，比让它直接生成正确且美观的HTML要可靠得多。
可维护性：纯文本的Markdown文件可以用任何编辑器打开，易于版本控制（Git），也方便进行批量查找替换等操作。

项目中的reference/base.html文件就是整个页面的骨架模板。它使用了Nunjucks这类模板引擎语法，定义了页面的整体结构（Header, Hero, Content, Footer），并预留了插槽来注入从Markdown解析出的组件和从YAML读取的配置数据。这种设计确保了无论内容如何变化，页面的基础样式和布局始终保持一致。

2.2 Agent执行引擎：串联工作流的“大脑”与“双手”

模板定义了“做什么”，而Agent执行引擎定义了“怎么做”以及“谁来做”。在这个项目中，它特指与AI助手（如ChatGPT Codex模式）集成的自动化脚本和工作流。

Agent Skill 是什么？你可以把它理解为一个封装好的、可被AI调用的“宏”或“插件”。当你在AI对话中输入“帮我生成课程页面”时，AI识别到这个意图，就会自动触发course-page-generator这个Skill。这个Skill背后是一系列定义好的步骤：

内容处理：如果用户只给了主题，AI会先扮演专家角色，生成结构化的content.md。如果给了原始讲稿，AI会将其清理、格式化，转换成符合项目语法的content.md。
配置生成：AI会根据内容，智能地生成或补充config.yaml文件，例如提取核心关键词作为页面标题和副标题。
执行构建：AI自动在后台调用build.mjs脚本，将上两步的产出物结合模板，生成index.html。
生成预览图：调用generate-og.mjs，利用Puppeteer无头浏览器打开生成的页面并截图，生成用于社交媒体分享的OG Image。
启动服务：最后调用dev.mjs启动本地开发服务器，并自动在浏览器中打开预览。

这个设计的精妙之处在于：它将复杂的、多步骤的构建过程，简化成了一个自然语言指令。用户无需记忆任何命令，无需手动操作文件，AI成为了整个工作流的协调者和执行者。这极大地降低了技术门槛，让内容创作者能专注于创作本身。

2.3 双层配置系统：兼顾统一与灵活

任何需要批量生产的内容系统，都会面临“统一品牌”和“个性定制”的矛盾。为此，我设计了一个两层的配置合并系统。

全局配置 (config/global.yaml)：存放“不变”的信息。比如讲者的姓名、头像、个人简介、社交媒体链接、页脚的版权信息等。这些信息通常在所有课程页面中都是一致的。把它放在全局，就避免了在每个课程目录里重复填写。
课程配置 (<course-dir>/config.yaml)：存放“变化”的信息。比如本门课程的标题、Hero区域的副标题、特定的开场/结束金句等。这里只需要填写需要覆盖或新增的字段，其余全部从全局配置继承。

技术实现上，采用的是“深度合并(deep merge)”。对于普通对象，课程配置的字段会覆盖全局配置的同名字段。但对于数组（如socials社交链接），策略是“替换”而非“合并”，即课程的socials会完全取代全局的socials。这是因为社交链接通常要么全用全局的，要么为某门课程指定一套全新的，很少需要混合。

此外，配置文件的查找机制也很智能。build.mjs脚本会从当前课程目录开始，向上递归查找最多4层父目录，寻找config/global.yaml。这意味着你可以把全局配置放在项目根目录，也可以根据课程分类，在不同层级的子目录里放置不同的全局配置，实现了配置的“作用域”管理，非常适合管理多系列课程。

3. 从零开始：手把手创建你的第一门课程

理论说得再多，不如动手做一遍。让我们抛开AI，先纯手动走一遍流程，这能帮你彻底理解整个系统是如何运作的。假设我们要创建一门名为my-first-ai-course的课程。

3.1 环境准备与项目初始化

首先，你需要一个基础环境。确保你的系统已经安装了Node.js (版本16或以上)和npm。

# 1. 克隆或下载项目 git clone <项目仓库地址> cd agent-skill-lecture-builder # 2. 安装项目依赖 # 注意：因为OG图片生成依赖puppeteer，它可能会下载Chromium，网络环境不好时可能需要耐心等待或配置镜像。 npm install

安装完成后，你的项目结构应该和文档中描述的一致。重点关注两个目录：config/用于放全局配置，example/是一个现成的课程示例。

3.2 创建课程目录与核心文件

我们不修改示例，而是新建自己的课程。

# 在项目根目录下创建课程文件夹和资源子目录 mkdir -p my-first-ai-course/assets

接下来，创建两个核心文件：content.md和config.yaml。

第一步：编写课程内容 (my-first-ai-course/content.md)你可以从最简单的开始，复制下面的示例。注意我们使用了项目约定的扩展语法，比如# LABEL：TITLE的章节格式，以及[bonus]区块。

# 🧠 核心概念：什么是Agent Skill？ > 将复杂操作封装成一个“技能”，让AI像调用函数一样执行它。 在这一章，我们将拆解Agent Skill的核心思想。它不仅仅是自动化脚本，更是一种与AI协同工作的范式转变。 ## 传统脚本 vs. Agent Skill ### 🔧 传统脚本 你需要记住命令、参数和正确的执行顺序。 ```bash node ./some-script.js --input file.md --output dir/

🔧 Agent Skill

你只需要用自然语言描述你的目标。

帮我为这份讲稿生成一个课程页面。

AI理解你的意图，自动选择并执行正确的技能。

关键优势

[flow]

降低认知负荷：无需记忆复杂命令。
提升交互自然度：用说话的方式指挥电脑。
实现复杂工作流：单个指令可触发一连串动作。 [/flow]

[summary] Agent Skill的本质是“意图到执行”的桥梁。它通过预定义的能力描述，让AI能够可靠地完成特定领域的复杂任务，将人类从繁琐的操作细节中解放出来。 [/summary]

[bonus title="💡 设计心得"] 在设计course-page-generator这个Skill时，我刻意将“内容生成”和“页面构建”分开。

内容生成：可以依赖AI的创造力，根据主题自由发挥。
页面构建：必须严格遵循模板和规则，确保输出稳定。

这种“松耦合”设计使得Skill更加健壮。即使未来更换AI模型，或者完全手动编写Markdown，构建部分依然可以完美工作。 [/bonus]

**第二步：创建课程配置 (`my-first-ai-course/config.yaml`)** 这个文件用于覆盖全局设置，定义本课程特有的信息。 ```yaml page: title: "AI智能体技能开发入门" badge: "实战教程" hero_title: "告别一次性代码<br>构建可复用的AI工作流" subtitle: "掌握模板思维，将你的AI创作转化为可持续资产" quotes: opening: text: "最好的工具，是那些用完后让你变得更强大的工具。" closing: text: > 现在，你不仅拥有了一个页面，更拥有了一套生产页面的方法。

注意：这里没有写instructor或footer信息，因为它们会从config/global.yaml继承。你需要先确保全局配置已正确设置。如果还没有，可以在项目根目录创建config/global.yaml，参考项目文档中的示例填写你的个人信息。

3.3 执行构建与预览

有了内容和配置，现在可以手动触发构建过程，看看效果。

# 在项目根目录执行构建命令，指向你的课程文件夹 node .agents/skills/course-page-generator/scripts/build.mjs my-first-ai-course

如果一切顺利，你会在my-first-ai-course/目录下看到新生成的index.html文件。用浏览器直接打开它，就能看到初步的静态页面了。

不过，更推荐使用开发服务器模式，它支持热重载：

# 启动开发服务器，默认端口3000 node .agents/skills/course-page-generator/scripts/dev.mjs my-first-ai-course # 或者指定端口 node .agents/skills/course-page-generator/scripts/dev.mjs my-first-ai-course --port 8080

执行此命令后，脚本会自动先运行一次构建，然后启动一个本地服务器，并自动在浏览器中打开页面。接下来，如果你修改了content.md、config.yaml甚至全局的global.yaml或模板文件，保存后，页面会自动刷新。这个功能对于内容创作和样式调试来说极其高效。

3.4 生成社交媒体预览图

在分享课程链接到社交媒体时，一张精美的预览图能极大提升点击率。项目内置了OG图生成脚本。

node .agents/skills/course-page-generator/scripts/generate-og.mjs my-first-ai-course

这个脚本会：

在后台启动一个无头浏览器。
访问你刚生成的课程页面（通常是http://localhost:3000，如果dev服务器在运行的话）。
对页面进行截图，并裁剪成1200x630像素的标准OG图像尺寸。
将图片保存为my-first-ai-course/assets/og-{timestamp}.jpg。

你需要确保在运行此命令前，课程页面可以通过一个URL访问（无论是dev服务器还是已经部署到线上的地址）。你可以在课程的config.yaml中通过seo.image字段指定这张图的永久链接，这样社交媒体爬虫就能正确抓取。

4. 深度解析：Markdown扩展语法的实战应用与原理

项目的易用性很大程度上得益于一套设计精巧的Markdown扩展语法。它们不是简单的标记，而是对应着一个个具有特定样式和交互的UI组件。理解它们，你就能写出既美观又结构清晰的讲义。

4.1 章节与卡片：构建内容的清晰骨架

基础Markdown的标题（#，##）在这里被赋予了更强的语义。

# LABEL：TITLE：这是顶级章节。LABEL部分（如🧠 核心概念）会以徽章的形式展示在标题左侧，非常适合用于标识章节类型（如概念、实操、案例）。这个语法是整个内容目录（导航栏）生成的依据。
> lead text：如果一段引用块>紧跟在#章节标题行之后，它不会被渲染成普通的引用块，而是会成为该章节的“引言”或“摘要”，使用特殊的样式突出显示，给读者一个章节概览。
### 🔧 Title：三级标题有一个特殊用途。当你在标题前加入一个Emoji（如 🔧、📌、⚠️ 等），它会被渲染成一个“卡片”组件。卡片具有独立的背景、边框和内边距，视觉上从正文中剥离出来，非常适合用于封装一个完整的小知识点、一个工具介绍或一个注意事项。

在背后，构建脚本会解析这些标题，不仅用于渲染，还会自动提取#级标题的ID和文字，生成页面右侧（或移动端顶部）的导航栏（Nav）。这意味着你几乎不需要手动维护导航菜单，内容结构就是导航结构，极大减少了维护成本。

4.2 特色内容区块：让表达形式更丰富

除了标准Markdown，项目定义了几种自定义区块，用[tag]...[/tag]的形式包裹。

[flow]...[/flow]：流程步骤区块。内部的列表项会被渲染成带有编号和连接线的垂直时间轴样式，直观地展示操作步骤或事件顺序。
[summary]...[/summary]：总结卡片。通常放在章节末尾，内容会被放在一个视觉上醒目的总结框内，帮助读者回顾重点。
[tags]...[/tags]：标签组。内部用空格分隔的词汇，会被渲染成不同颜色（green, orange, purple, blue）的小标签，常用于标注技术栈、关键词、状态等。
[image-text]...[/image-text]：图文并排版。这是非常实用的一个功能。你可以在里面放一张图片和一段文字，通过position和width属性控制左右布局和图片宽度。在移动端会自动堆叠，响应式体验很好。
[bonus title="..."]...[/bonus]：扩展内容弹窗。这是实现渐进式披露的好方法。将一些扩展阅读、深度分析、幕后花絮放在这里，页面上只会显示一个按钮，点击后以模态框形式弹出内容，保持主内容的简洁。

4.3 代码与提示块：针对技术内容的优化

对于技术教程，代码展示和操作提示至关重要。

标准代码块：使用```language语法，支持语法高亮。
提示块：使用```prompt [label="..."]语法。这会被渲染成一个模拟终端样式的区块，label属性会显示为终端的标签头（如user@host ~ $），非常适合展示命令行操作或AI对话中的Prompt示例，增强场景感。
洞察框：使用> **Bold Title**后跟内容的格式。这会被渲染成一个带有图标和边框的提示框，用于强调重点、警告或技巧。

4.4 媒体嵌入：无缝集成视频与图片

图片：标准Markdown语法![alt](src)被增强。图片会自适应居中，并且alt文字会自动成为图片下方的说明文字（<figcaption>）。结合[image-text]区块，可以轻松实现图文混排。
YouTube视频：通过[youtube id="..."]语法嵌入。脚本会自动生成响应式的16:9视频iframe。考虑到可访问性和打印友好性，在打印样式下，iframe会被替换为视频的直接链接。

一个综合示例：

# 🛠️ 实战：配置你的第一个Skill > 让我们通过一个具体例子，将理论付诸实践。 ### 🔧 步骤一：定义Skill清单 首先，在 `.agents/skills/` 目录下为你的Skill创建一个文件夹，例如 `deploy-to-server`。 [flow] 1. 创建 `skill.yaml` 文件，描述技能的名称、能力和触发词。 2. 编写核心执行脚本 `main.mjs`。 3. 添加说明文档 `README.md`。 [/flow] ### 🔧 步骤二：编写执行脚本 你的脚本需要能够处理AI传递的参数。 ```javascript // main.mjs 示例片段 export async function run({ input, context }) { const { projectPath } = input; console.log(`开始部署项目: ${projectPath}`); // ... 你的部署逻辑 }

关键点：脚本必须导出run函数，AI会将用户输入解析为参数传入。

🔧 步骤三：测试与集成

使用CLI工具本地测试你的Skill。

node .agents/skills/deploy-to-server/main.mjs --input '{"projectPath": "./my-course"}'

[image-text position="right" width="45"]一个完整的Skill通常包含三部分：元数据（YAML）、执行逻辑（JS）、文档（MD）。清晰的分离有助于长期维护。 [/image-text]

[summary] 构建一个可靠的Agent Skill，关键在于清晰的接口设计和完善的错误处理。让AI知道它能做什么，以及在出错时如何向用户反馈。 [/summary]

[bonus title="📂 项目结构建议"] 对于复杂的Skill，我建议采用如下结构：

deploy-to-server/ ├── skill.yaml # 技能定义 ├── main.mjs # 主入口 ├── utils/ # 工具函数 │ └── ssh-helper.mjs ├── configs/ # 配置模板 │ └── nginx-template.conf └── README.md # 开发文档

[/bonus]

通过组合使用这些语法元素，你可以创造出信息密度高、层次分明、阅读体验极佳的技术讲义。 ## 5. 与AI协同：将Skill集成到你的智能体工作流 手动操作展示了项目的全部能力，但真正的威力在于与AI的集成。这里以兼容OpenAI ChatGPT Code Interpreter（或类似代码执行环境）的AI助手为例。 ### 5.1 配置AI环境以识别Skill 要让AI能调用你的Skill，你需要确保AI能够访问到这些技能定义。通常有两种模式： **模式一：本地编辑器模式** 你可以在本地IDE（如VSCode）中打开项目，并安装能连接AI助手的插件。这些插件通常允许你将整个工作区或特定目录“暴露”给AI。AI在分析项目结构后，就能发现 `.agents/skills/` 目录下的技能，并在对话中提供相应的建议或自动触发。 **模式二：终端CLI模式** 有些AI工具允许你运行一个本地代理服务器，AI通过这个服务器执行命令和访问文件。你需要确保代理服务器的工作目录是你的项目根目录。这样，当你说“生成课程页面”时，AI就能直接找到并执行 `course-page-generator` 技能背后的脚本。 > **实操心得**：无论哪种模式，第一次使用时，最好主动告诉AI你的项目结构。你可以发送一条消息如：“在这个项目中，我定义了一个名为 `course-page-generator` 的Agent Skill，用于从Markdown生成课程网页。它的入口脚本位于 `.agents/skills/course-page-generator/scripts/build.mjs`。” 这能帮助AI更快地建立上下文，准确调用。 ### 5.2 两种核心使用场景详解 项目文档提到了两种主要场景，我们深入看一下AI在其中扮演的角色。 **场景一：从主题到完整页面（AI作为内容创作者）** 你输入：“扮演一位资深前端工程师，设计一门‘现代CSS布局实战’的课程讲义，并生成网页。” 1. **AI理解与规划**：AI首先理解你要扮演的角色和课程主题。它会规划课程大纲（可能包含Flexbox、Grid、容器查询等章节）。 2. **调用Skill**：AI识别出“生成网页”这个任务，匹配到 `course-page-generator` 技能。它知道这个技能需要 `content.md` 和 `config.yaml`。 3. **生成内容**：AI开始撰写结构化的 `content.md`，它会自觉运用 `# LABEL：TITLE`, `[flow]`, `[summary]` 等扩展语法。同时，它会根据内容提炼出课程标题、副标题，生成 `config.yaml`。 4. **执行构建**：AI在后台运行 `build.mjs` 脚本，传入它刚刚创建的课程目录。 5. **反馈结果**：AI将生成的HTML页面内容或本地预览链接提供给你，并告知你文件已生成在哪个目录。 **场景二：从讲稿到美化页面（AI作为内容格式化助手）** 你输入：“帮我把这段混乱的会议笔记转换成结构化的课程页面。” 然后粘贴一大段文本。 1. **AI分析与结构化**：AI读取你的原始笔记，识别其中的核心观点、步骤、代码片段。它会进行重写、分段，并套用项目约定的Markdown语法。 2. **查漏补缺**：AI可能会发现缺少开场总结或章节标签，它会主动补充。例如，为一系列操作步骤加上 `[flow]` 区块。 3. **生成配置**：AI从内容中提取关键信息，生成或补充 `config.yaml`。 4. **调用Skill构建**：后续步骤与场景一相同。 **在这个过程中，你的角色从“写代码的人”变成了“提需求的产品经理”和“内容质量的审核者”**。你关注的是课程的核心逻辑、知识点的准确性以及最终呈现的效果，而将格式转换、文件创建、命令执行等重复性工作交给了AI。 ### 5.3 调试与优化AI输出 AI并非总是完美的，尤其是在初期，它可能不熟悉你自定义的语法。 * **问题1：AI不使用扩展语法**。它可能生成标准的 `###` 标题，而不是 `### 🔧 Title` 卡片格式。 * **解决**：在指令中明确要求。例如：“请使用 `### 🔧 工具名` 的格式来介绍每个工具，使其渲染为卡片。” 或者，你可以把 `reference/components.md` 的内容发给AI，让它学习这套规范。 * **问题2：生成的导航不理想**。AI可能把一些不该作为导航的标题用了 `#`。 * **解决**：手动调整 `content.md`。导航只由 `#` 级标题生成，确保每个 `#` 都是一个主要的课程模块。 * **问题3：配置项不全或错误**。 * **解决**：AI生成的 `config.yaml` 是一个很好的起点，但你通常需要手动检查和微调，特别是 `hero_title`、`subtitle` 和 `quotes`，这些对页面氛围影响很大。 一个高效的协作模式是：**让AI完成初稿，然后你进行精细化的手动调整**。由于所有产出都是纯文本文件，你可以在喜欢的编辑器里轻松修改。调整后，运行 `dev.mjs` 即可实时看到效果。 ## 6. 部署与分享：让你的课程上线 生成静态HTML只是第一步，你还需要把它放到网上，才能分享给他人。这里推荐使用 **GitHub Pages**，因为它免费、简单，且与代码仓库天然集成。 ### 6.1 部署到GitHub Pages 假设你的项目已经是一个GitHub仓库。 1. **构建产物**：确保你的课程目录下已经生成了 `index.html` 和相关的 `assets`（如图片、OG图）。 2. **配置GitHub Pages源**：在仓库的 `Settings` -> `Pages` 页面，将 `Source` 设置为 **GitHub Actions**。 3. **创建工作流文件**：在项目根目录创建 `.github/workflows/deploy.yml` 文件。这个工作流会在你推送代码时自动构建并部署。 ```yaml name: Deploy to GitHub Pages on: push: branches: [ main, master ] # 在推送到主分支时触发 workflow_dispatch: # 允许手动触发 permissions: contents: read pages: write id-token: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' - name: Install dependencies run: npm ci # 使用ci确保依赖锁一致 - name: Build all courses run: | # 假设你的所有课程目录都在根目录下，且不以点开头 for dir in */; do if [[ -f "$dir/content.md" ]]; then echo "Building course: $dir" node .agents/skills/course-page-generator/scripts/build.mjs "${dir%/}" fi done # 注意：这个简单循环假设每个课程目录都直接包含content.md。 # 更复杂的项目结构需要调整查找逻辑。 - name: Setup Pages uses: actions/configure-pages@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: . # 上传整个项目根目录，因为生成的index.html在各个课程子目录里 - name: Deploy to GitHub Pages uses: actions/deploy-pages@v4

这个工作流做了几件事：安装依赖、遍历所有包含content.md的子目录并构建课程、将整个构建后的项目上传为制品，最后部署到GitHub Pages。

访问页面：部署成功后，你的页面地址通常是https://<你的用户名>.github.io/<仓库名>/<课程目录名>/。例如，my-first-ai-course课程的访问地址就是https://yourname.github.io/agent-skill-lecture-builder/my-first-ai-course/。

6.2 自定义域名与SEO优化

如果你有自己的域名，可以将其指向GitHub Pages，并在仓库设置中配置自定义域名，提升专业度。

此外，为了获得更好的搜索引擎收录和社交分享效果，请务必完善课程config.yaml中的seo部分：

seo: title: "AI智能体技能开发入门 - 你的品牌" description: "本课程教你如何利用模板思维和Agent Skill，将AI生成的内容转化为可维护、可复用的资产，告别一次性代码。" image: "https://yourdomain.com/path/to/og-image.jpg" # 使用绝对路径 url: "https://yourdomain.com/path/to/course/"

确保image指向的OG图片链接是公开可访问的。运行generate-og.mjs脚本后，你需要将生成的图片也一并提交到仓库，并使用正确的URL。

6.3 版本管理与协作

由于所有课程内容都是Markdown和YAML文件，你可以轻松地使用Git进行版本管理。

内容迭代：每次对讲义的修改都是一个commit，你可以清晰地看到课程的演变历史。
团队协作：团队成员可以克隆仓库，在各自分支上撰写或修改课程，通过Pull Request进行合并，审核内容变更。
多版本并存：你可以通过Git分支来管理课程的不同版本（如入门版、进阶版）。

7. 常见问题排查与进阶技巧

在实际使用中，你可能会遇到一些问题。这里记录了一些常见坑点及其解决方案。

7.1 构建与开发阶段问题

问题：运行npm install时，puppeteer下载Chromium失败或极慢。

原因：puppeteer默认会下载一个Chromium浏览器用于OG截图，网络环境可能导致下载失败。
解决：
1. 使用镜像源：设置环境变量PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors。
2. 如果你确定不需要OG截图功能，可以跳过puppeteer安装。但更推荐安装，因为它是生成分享预览图的关键。
3. 在CI/CD环境中（如GitHub Actions），通常自带Chromium，可以通过环境变量PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true跳过下载，然后通过apt-get等系统包管理器安装。

问题：运行dev.mjs或build.mjs时出现模板语法错误。

原因：最可能是content.md中自定义语法标签没有正确闭合，例如[flow]没有对应的[/flow]，或者Markdown格式有误（如列表缩进不正确）。
解决：仔细检查报错位置附近的Markdown语法。构建脚本会给出相对准确的行号提示。确保所有自定义区块标签都是成对出现且正确嵌套。

问题：页面样式错乱，或自定义组件没有正确渲染。

原因：可能是构建过程中，模板文件 (base.html) 或全局CSS/JS资源路径引用错误。
解决：
1. 检查构建命令指定的课程路径是否正确。
2. 检查config/global.yaml中引用的资源路径（如头像图片）是否存在。
3. 在浏览器中按F12打开开发者工具，查看Console和Network标签页，确认是否有404错误（找不到CSS/JS文件）。

7.2 与AI协作问题

问题：AI无法识别或触发我定义的Skill。

解决：
1. 确认暴露路径：确保你的AI工具（如ChatGPT Code Interpreter或本地AI助手插件）有权限访问到.agents/skills/目录。
2. 清晰描述：直接告诉AI：“在这个工作区中，我有一个预定义的Skill，路径是.agents/skills/course-page-generator，请你查看它的skill.yaml文件来了解如何使用它。”
3. 手动触发：如果AI无法自动触发，你可以手动指示它执行命令：“请运行node .agents/skills/course-page-generator/scripts/build.mjs my-course来构建我的课程页面。”

问题：AI生成的Markdown不符合我的扩展语法规范。

解决：这是预期之中的。你需要“训练”AI。最有效的方法是提供范例。将reference/components.md文件的内容和一份写好的content.md示例发给AI，并说明：“请严格按照这种格式和语法来生成课程内容。” 在后续的指令中，你也可以反复强调：“请使用[flow]区块来列举步骤”，“请用### 🔧开头表示工具卡片”。

7.3 样式与功能定制

项目提供的模板和样式是开箱即用的，但你可能想进行个性化定制。

修改全局样式：主要的样式定义在reference/base.html模板文件内的<style>标签中。你可以修改这里的CSS来改变字体、颜色、间距等全局样式。
添加自定义组件：如果你想增加新的Markdown扩展语法（例如一个[warning]警告框），你需要：
1. 在构建脚本（build.mjs）中修改Markdown解析逻辑，将新语法转换为对应的HTML结构。
2. 在base.html的CSS中添加新组件对应的样式。
3. 更新components.md文档，说明新语法的用法。
集成分析工具：在base.html的<head>部分，你可以添加Google Analytics或Umami等统计代码的脚本标签，这样所有生成的页面都会自动包含它。

7.4 性能与规模化建议

当课程数量非常多时，一些简单的优化可以提升体验。

增量构建：目前的脚本是每次构建全部课程。你可以修改构建脚本，只构建发生变化的课程目录，这需要结合Git来判断文件变更。
资源优化：确保assets目录下的图片经过压缩（可以使用工具如Sharp进行自动化）。如果课程中有大量高清图片，考虑使用懒加载。
CI/CD优化：在GitHub Actions工作流中，可以利用缓存来加速npm install和puppeteer的安装过程。

这个项目的魅力在于，它始于一个解决个人痛点的工具，但因其清晰的架构和文本驱动的本质，最终演变成了一套可扩展、可协作、并能与AI深度协同的内容生产系统。它教会我们的不仅是技术，更是一种思维模式：在AI时代，我们的目标不应是成为更快的打字员，而是成为更高效的设计师和指挥家，让AI去执行那些可重复的、结构化的任务，而我们则专注于创造、设计和决策。