showboat文档格式规范全解：5种块类型与CLI命令的1:1映射设计

showboat 是一个 Go 编写的 CLI 工具，专门帮助 AI Agent 构建可执行的 Markdown 演示文档——同一个文件里混合了解说文字、可执行代码块和捕获到的真实输出，既是给人读的文档，也是能被verify重新执行、逐条验证的"工作证明"。本文完整拆解 showboat 文档格式的5 种块类型，以及它们与CLI 命令之间 1:1 映射的精妙设计，帮你一次看懂这个开源项目的文档规范。

为什么 Agent 需要"可执行"的演示文档？

普通的 README 只能"说"，却不能"证明"。当 Agent 完成一项任务后，用户往往想确认：这些命令现在还能跑出同样的结果吗？

showboat 的解法很简单：把演示过程实时追加进一个 Markdown 文件，每个代码块都带着当初真实运行的输出。之后任何人执行一次showboat verify，工具就会重新跑遍所有代码块并做 diff 比对——输出一致，文档就是可信的"证据链"。

项目 README 对它的定位是：

Create executable demo documents that show and prove an agent's work.

—— 见 README.md

安装也很直接，一条命令即可试用，无需先安装：

uvx showboat --help # 或正式安装 pip install showboat

5 种块类型：showboat 文档的"积木"

showboat 文档不是随意写的 Markdown，而是由 5 种**块（Block）**拼装而成的严格结构。所有块类型定义在 markdown/blocks.go 中，每种块实现统一的Type()接口：

一个完整的 showboat 文档长这样（摘自 help.txt 中的官方示例）：

# Setting Up a Python Project *2026-02-06T15:30:00Z* <!-- showboat-id: 550e8400-e29b-41d4-a716-446655440000 --> First, let's create a virtual environment. ```bash python3 -m venv .venv && echo 'Done'

Done

print('Hello from Python')

Hello from Python

screenshot.png

screenshot

观察这个结构就能发现规律：**代码块和输出块总是成对出现**，解说块自由穿插在中间，标题块永远位于文档最顶部。 ## 1:1 映射设计：每条 CLI 命令对应一种文档模式 这是 showboat 最核心的设计哲学（出自 [docs/plans/2026-02-06-showboat-design.md](https://link.gitcode.com/i/13e91b98bd93614ae54341e8d47eb88a)）： > **Markdown 文件就是唯一事实来源（source of truth）。** 每条 CLI 命令精确对应文档中的一种块模式，整个格式完全可往返（round-trippable）。 也就是说，showboat **没有数据库、没有外部状态**。每条命令的工作流程都一样：读文件 → 解析成块列表 → 追加新块 → 整体写回。这套读写逻辑集中在 [cmd/build.go](https://link.gitcode.com/i/5018a00a9a08e4aff35371fdcb48a52b) 的 `readBlocks` / `writeBlocks` 两个辅助函数里： ```text init → TitleBlock（标题 + 时间戳 + UUID） note → CommentaryBlock（一段解说文字） exec → CodeBlock + OutputBlock（代码 + 真实输出，成对追加） image → CodeBlock{image} + ImageOutputBlock（图片引用 + 图片行） pop → 删除文档"最后一个条目"（成对块一起删） verify → 重新执行所有代码块，diff 比对输出 extract → 反向输出重建文档所需的完整命令序列

写侧：命令如何追加块

• init（cmd/init.go）：创建文档，写入标题、RFC3339 时间戳和 UUID 文档 ID；文件已存在时直接报错，防止误覆盖。
• note（cmd/build.go）：把任意 Markdown 文字作为一个解说块追加到末尾。
• exec（cmd/build.go）：先真正执行代码、捕获输出，再把代码块和输出块成对追加。注意：它会把输出原样打印到终端、并透传退出码，这样 Agent 能"看见"发生了什么并对错误做出反应——即使命令失败，输出照样写入文档，失败现场也是演示的一部分。
• image（cmd/build.go）：把图片文件复制到文档同目录（生成带日期的独立文件名），追加一个```bash {image}代码块和一行alt图片引用。

读侧：verify 与 extract 如何"消费"块

• verify（cmd/verify.go）：解析文档后跳过所有图片块，按顺序重跑每个代码块，把新输出与文档中记录的输出逐字比对。有任何 diff 就打印差异并以退出码 1 结束；加--output <file>还能生成一份刷新了输出的副本，原文件保持不动。
• extract（cmd/extract.go）：遍历块列表，把每个块翻译回一条 CLI 命令（OutputBlock和ImageOutputBlock会被跳过，因为它们在重跑时会自然再生）。换句话说，extract是"文档 → 命令序列"的反编译器。

正是这种 1:1 映射，使得一份 showboat 文档既能被机器重放，也能被人类直接阅读——两头都不吃亏。

快速上手：一条完整的 showboat 工作流

7 条命令覆盖全流程（完整帮助信息见 help.txt，也可运行showboat --help）：

# 1. 创建演示文档 showboat init demo.md "Setting Up a Python Project" # 2. 追加解说 showboat note demo.md "First, let's create a virtual environment." # 3. 执行代码并捕获输出（输出会打印到终端） showboat exec demo.md bash "python3 -m venv .venv && echo 'Done'" # 4. 出错了？一键撤销最后一条条目（代码块+输出块一起删除） showboat pop demo.md # 5. 插入一张截图（支持 alt 语法保留 alt 文本） showboat image demo.md 'Homepage screenshot' # 6. 验证文档：重跑所有代码块并比对输出 showboat verify demo.md # 7. 查看重建该文档的完整命令序列 showboat extract demo.md

三个实用细节：

• 支持 stdin：省略文本/代码参数时从标准输入读取，例如echo "Hello" | showboat note demo.md、cat script.sh | showboat exec demo.md bash，对脚本化场景非常友好（见 main.go 的getTextArg）。
• --workdir <dir>：全局参数，可指定代码执行时的工作目录。
• 远程流式推送：设置SHOWBOAT_REMOTE_URL后，每条init/note/exec/image/pop都会把内容 POST 到远端，配合文档里的 UUID 注释即可实现"边写边看"的实时演示（实现见 cmd/remote.go）。

项目仓库里还有一份真实的 showboat 文档可以学习：demos/shell-output-and-pop.md，它用文档本身演示了"失败命令如何被pop干净撤销"的完整过程。

三个值得细看的设计细节

1. 自适应围栏，防输出内容"破框"：输出块固定用```output围栏，但如果输出本身包含反引号，围栏长度不够会破坏文档结构。markdown/writer.go 的fenceFor会扫描内容中最长的反引号序列，动态加长围栏，保证任何输出都能安全嵌入。
2. 标题块不可动摇：markdown/parser.go 规定# 标题只在文档第一个位置被识别为TitleBlock，且必须连读时间戳和可选的<!-- showboat-id: ... -->注释；cmd/pop.go 则明确禁止pop删掉标题——文档永远有"头"。
3. 成对块的原子性：exec/image追加的"代码+输出"永远被视为一个条目。pop一次移除两个块（cmd/pop.go），verify也只跳过图片块、逐个重跑代码块——块与块之间的这种"配对关系"是 1:1 映射能精确重建的前提。

如何阅读 showboat 源码：关键路径导航

想深入源码时，建议按"块定义 → 读写 → 命令 → 执行"的顺序阅读：

git clone https://gitcode.com/gh_mirrors/sh/showboat

总结

showboat 的文档格式可以一句话概括：5 种块类型 × 7 条命令 × 1 个事实来源。

• init/note/exec/image四种"写"命令，各自精确追加一种块模式；
• pop让文档可撤销，verify让文档可自证，extract让文档可再生；
• 没有隐藏的中间状态——你看到的那份 Markdown，就是全部数据。

如果你的 Agent 也需要交付"既好看又可信"的演示结果，这套 1:1 映射的设计思路非常值得借鉴。