showboat完整实战案例:让Claude Code自动为你的项目生成可复现的工作证明文档

原创2026-10-14 04:37:12842 阅读

showboat完整实战案例:让Claude Code自动为你的项目生成可复现的工作证明文档

showboat 是一款用 Go 编写的命令行工具,专门帮助 AI Agent(如 Claude Code)生成可执行的 Markdown 演示文档:文档里混合了解说文字、真实执行过的代码块和被捕获的原始输出,既是可以直接阅读的文档,也是一份随时可以重新运行、逐行比对的"工作证明"。

一、为什么需要"可复现的工作证明文档"?

用过 AI 编程助手的朋友都有这样的经历:Agent 信誓旦旦地说"问题已修复,命令可以跑通",但你自己一敲,输出却对不上。口头承诺很难验证,而证据可以重放。

showboat 的思路很直接:把 Agent 的每一步操作写成一份标准的 Markdown 文档——

  • 解说(commentary):解释这一步在做什么
  • 代码块(exec):真实执行过的命令,语言任意(bash、python 等)
  • 输出块(output):命令执行时的 stdout/stderr 原样捕获

关键点在于:文档生成之后,任何人(包括另一个 Agent)都可以重新执行其中所有代码块,如果输出与记录一致,说明工作真实有效、至今可复现。这就是 docs/plans/2026-02-06-showboat-design.md 中定义的核心理念——"show and prove"。

二、一键安装 showboat:3 种方式任选其一

showboat 支持 Python 包和 Go 二进制两种分发方式,任选其一:

# 方式1:通过 pip 安装
pip install showboat

# 方式2:免安装直接运行(推荐尝鲜)
uvx showboat --help

# 方式3:Go 用户直接安装
go install github.com/simonw/showboat@latest

如果希望阅读源码或参与贡献,也可以克隆仓库本地构建:

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

安装完成后运行 showboat --help,你会看到一份极其完整的使用说明——这不仅是给人看的文档,更是 Agent 的"操作手册",后面会重点讲。

三、实战:6 步生成一份可复现的 demo 文档

下面用一个"搭建 Python 项目"的例子,完整走一遍 showboat 的工作流。

第 1 步:init 创建新文档

showboat init demo.md "Setting Up a Python Project"

一条命令生成带标题和时间戳的 Markdown 文件骨架,同一文件重复 init 会报错,防止误覆盖。

第 2 步:note 追加解说文字

showboat note demo.md "First, let's create a virtual environment."

解说以普通 Markdown 段落追加到文档中,负责"讲故事"的部分。

第 3 步:exec 执行代码并自动捕获输出

showboat exec demo.md bash "python3 -m venv .venv && echo 'Done'"
showboat exec demo.md python "print('Hello from Python')"

这是整个工具的灵魂:exec 会真实执行命令,把输出自动写入紧跟其后的 output 代码块。同时它会把输出打印到终端并透传退出码——这意味着 Agent 能立刻看到命令是否失败,从而决定下一步(比如回退重做)。

第 4 步:image 插入截图证据

showboat image demo.md screenshot.png
# 或者带 alt 文本
showboat image demo.md 'Homepage screenshot'

图片会被复制到文档同目录并生成唯一文件名(<uuid>-<date>.<ext>),文档中自动追加引用,截图也成为可复现证据的一部分。

第 5 步:pop 撤销写错的最后一步

演示中写错命令很正常。pop 会移除文档中最近的一条记录(对于 exec/image 条目会连同代码块和输出块一起删除):

showboat pop demo.md

Agent 看到非零退出码后,用 pop 清掉失败条目、重新执行正确命令——文档里只留下干净的过程。这个机制在官方示例 demos/shell-output-and-pop.md 中有完整演示。

第 6 步:verify 一键验证全部输出

showboat verify demo.md

verify 会按顺序重新执行文档中每个代码块(跳过图片块),并将新输出与文档中记录的输出逐一 diff:全部一致则退出码为 0;有任何变化会打印 diff 并以退出码 1 结束。配合 --output <file> 还能导出更新后的副本而不动原文件。

最终生成的文档长这样

# Setting Up a Python Project

*2026-02-06T15:30:00Z*

First, let's create a virtual environment.

​```bash
python3 -m venv .venv && echo 'Done'
​```

​```output
Done
​```

​```python
print('Hello from Python')
​```

​```output
Hello from Python
​```

解说、代码、输出三段式结构,一眼就能看懂,且每一行输出都经过了真实执行。

四、extract:反向还原文档的构建过程

除了正向验证,showboat 还提供反向能力。extract 会解析文档,输出从零重建这份文档的完整 CLI 命令序列:

showboat extract demo.md

输出类似:

showboat init demo.md 'Setting Up a Python Project'
showboat note demo.md 'First, let'\''s create a virtual environment.'
showboat exec demo.md bash 'python3 -m venv .venv && echo '\''Done'\'''

配合 --filename 参数还能替换生成的文件名,方便复制文档到新项目。这背后是 markdown/ 包实现的严格双向格式:每条 CLI 命令与 Markdown 结构一一对应,完全可往返。核心实现见 markdown/parser.go、markdown/writer.go 和 markdown/blocks.go,命令逻辑在 cmd/ 目录,代码执行与截图处理在 exec/runner.go 和 exec/image.go。

五、如何让 Claude Code 自动使用 showboat?

这是 showboat 设计上最巧的部分:showboat --help 的输出就是面向 Agent 的唯一文档。

help 文本里包含完整的子命令清单、一个真实可跑的工作流示例(init → note → exec → pop → verify),以及 stdin 用法约定(cat script.sh | showboat exec demo.md bash)。设计目标非常明确——Agent 只需运行一次 showboat --help,就能立刻产出格式正确的演示文档,无需查阅其他资料。完整帮助内容见 help.txt。

配合 Claude Code 的典型用法:

  1. 告诉 Agent:"用 showboat 为本次修复过程生成一份 demo 文档"
  2. Agent 读取 showboat --help,开始 init → note → exec 循环
  3. 执行失败时,Agent 依据透传的退出码自行 pop 并重试
  4. 最后运行 showboat verify 确认文档可复现

此外还有两个进阶能力值得了解:

  • --workdir <dir>:全局参数,指定代码块执行时的工作目录,默认当前目录
  • 远程实时流式推送:设置环境变量 SHOWBOAT_REMOTE_URL 后,每次 init/note/exec/image/pop 都会把内容 POST 到指定地址,实现文档构建过程的实时观看

六、常见问题(FAQ)

Q:命令执行失败会不会中断文档生成? 不会。exec 会把输出照常写入文档,同时向调用方透传退出码,由 Agent 决定是用 pop 撤销还是继续。

Q:verify 时输出变了怎么办? 说明环境有变化(依赖升级、输出格式改变等)。此时可用 showboat verify demo.md --output updated.md 生成一份带新输出的文档副本,人工确认后再替换。

Q:支持哪些语言? 任意可通过解释器直接运行的语言都可以,exec 第二参数就是解释器名,例如 bash、python、python3。

七、写在最后

showboat 把"Agent 说自己做了什么"变成了"文档证明它确实做了什么"。对于正在评估 AI 编程助手产出的团队来说,一份能通过 verify 的 Markdown,比任何口头汇报都更有说服力。

📌 延伸阅读:

现在就可以安装 showboat,让你的下一次 Agent 交付都带上"可复现证明"。

登录后查看全文
showboat