| title | 欢迎 |
|---|
{fig-align="center" width="60%"}
这是一个 Quarto 书籍模板的演示站点。本页面是读者打开本书时看到的第一屏，作者通常会在这里写一段简短的开场白：本书写给谁、解决什么问题、读完之后能拿到什么。
模板已经预置了写作长篇技术书所需的一整套基础设施，作者只要替换正文即可。本页面下方列出了模板提供的核心功能，点开示例章节可以看到每一类排版元素的实际效果。
- 5 类 callouts：note（蓝色）、tip（绿色）、warning（黄色）、important（红色）、caution（橙色），用于区分不同语气的提示。
- 4 类语义代码块：
opencode（橙色，标注用户给 AI 的提示词）、agent（蓝色，标注 agent 定义）、skill（绿色，标注 skill 定义）、bash（终端窗口风格）。 - Mermaid 流程图：原生支持流程图、序列图、状态图等。
- 跨引用：
@fig-xxx、@tbl-xxx自动展开为"图 1.1"、"表 1.1"等本地化标签。 - Markdown 表格：标准 GitHub 风格表格，支持图表标题。
- 双 profile：
full渲染整本书，selection只渲染选定章节，方便预览或试读发布。
::: {.callout-tip}
本模板的目录结构、构建命令、章节扩展方式，详见项目根目录的 README.md。README.md 还说明了如何把本模板克隆为新书，以及如何在 _quarto.yml 中改写元信息。
:::
下面是占位的章节目录，作者请把它替换为真实的章节标题，并在 chapters/ 下添加新的章节文件夹。每条链接指向对应章节的入口页面 index.md。
新增章节的最快方式是运行 ./scripts/new-chapter.sh 1 "章节标题"，脚本会从 chapters/chapter-template/ 复制一份新目录，并打印出需要追加到 _quarto-full.yml 的 YAML 片段。
模板根目录有一个轻量的 Lua 过滤器（opencode-prompt.lua），它把几个语义化的代码块语言渲染为带标签和复制按钮的样式卡片。下表是约定俗成的语义标签，用于让正文中的代码块在视觉上一眼可辨：
| 标签 | 用途 | 配色 |
|---|---|---|
```opencode |
用户输入给 AI 编程助手的自然语言提示词 | 橙色 |
```agent |
Agent 定义文件（YAML frontmatter + 系统提示词） | 蓝色 |
```skill |
Skill 定义文件（YAML frontmatter + 执行步骤） | 绿色 |
```bash |
读者需要在终端中执行的 shell 命令 | 终端窗口风格 |
其他标准语言标记（python、json、yaml、txt 等）走 Quarto 默认渲染。完整说明请参考 docs/semantic-code-blocks.md。
::: {.callout-note appearance="simple"} 本页、章节模板、所有图片都只是占位内容。正式发布之前请用真实内容替换。 :::