你还在用 Word 写部署手册、用截图传操作步骤？

告诉你个真事儿：我之前光 README 里的示例代码过期了三次，每次都被人 issue 吐槽”跑不通”。后来学乖了，把文档直接变成可执行的测试——哪行过期了，CI 直接报错。

这个混搭思路的源头，是一个叫 mdproof 的开源项目。

把 Markdown 当测试文件跑

mdproof 做一件很酷的事：让你的 Markdown 文件变成可执行的测试套件。

你写一个这样的文件：

“`markdown

API 冒烟测试

第一步：健康检查

“`bash
curl -sf http://localhost:8080/health
“`
Expected:
– exit_code: 0
– jq: .status == “ok”

第二步：创建用户

“`bash
curl -s -X POST http://localhost:8080/users -d ‘{“name”:”alice”}’
“`
Expected:
– jq: .id != null
– jq: .name == “alice”
“`

然后跑一下：
“`bash
mdproof sandbox api-proof.md
“`

输出长这样：
“`
✓ Step 1 健康检查 52ms
✓ Step 2 创建用户 18ms
───────────────────────────
2/2 passed 80ms
“`

失败的时候，它会精确告诉你：哪一步、哪个断言、哪行 Markdown 出了问题。

这东西解决什么问题？

文档和测试终于同步了。以前 README 里的示例代码没人维护，时间一长就跑不通。mdproof 把测试塞进文档里，每次 CI 都能顺手验证——文档永远是最新的。

部署手册可以直接跑。写完部署文档，顺手跑一遍验证步骤，Ops 能读、CI 也能跑，部署前就知道哪步会挂。

对 AI 编程特别友好。mdproof 自带一个 skills/SKILL.md，装进 Claude Code 或其他编程 Agent，Agent 就能直接生成测试文档——不需要学任何测试框架 API，用自然语言描述步骤就行。

支持哪些玩法

断言类型很全：exit_code、jq（对 JSON 结构做断言）、正则匹配、子串包含、快照对比。覆盖 CLI 工具测试、API 冒烟测试、部署验证、README 示例验证这些高频场景。

输出格式支持 JSON / JUnit XML，接 CI 很方便。还有 GitHub Actions 注解模式，PR 里直接内联报错。

安装方式

一线命令搞定：

curl -fsSL https://raw.githubusercontent.com/runkids/mdproof/main/install.sh | sh

或者：

brew install runkids/tap/mdproof

Windows 用户用 PowerShell：

irm https://raw.githubusercontent.com/runkids/mdproof/main/install.ps1 | iex

适合谁用

• 写 README 的开发者：想让示例代码永远不过期
• DevOps / 运维：把部署手册变成可验证的流程
• AI 编程玩家：让 Agent 用 Markdown 生成测试，不额外学框架

GitHub 在这里：https://github.com/runkids/mdproof

14 stars，还很早期，但思路很清晰——文档即测试，这个混搭玩法值得一玩。

GitHub: https://github.com/runkids/mdproof