案例 1 · 血染钟楼学习笔记（2026 年 6 月）
这套 playbook 的第一次实战——从零搭建《血染钟楼》主题博客的完整执行记录。这次的所有踩坑都被消化成了 playbook 主体内容。
一、背景
- 主题来源：用户没玩过血染钟楼，但玩过狼人杀和阿瓦隆，想系统性学习
- 目标受众：自己 + 桌游圈朋友
- 内容预期：教学指南（6 篇）+ 实战复盘（不定）
- 技术诉求：本地写得舒服 + 朋友看得清爽 + 自动化部署
二、执行时间线
Day 0 · 内容创作（约 1 小时）
~/game/血染钟楼/
├── README.md # 总览
├── 01-快速入门.md # 4.7 KB
├── 02-完整规则.md # 6.7 KB
├── 03-暗流涌动角色详解.md # 9.2 KB
├── 04-新手策略与误区.md # 8.5 KB
├── 05-学习资源.md # 6.6 KB
└── 06-术语速查表.md # 5.9 KB教学内容写完。
Day 1 · 实战复盘（多次迭代）
写第 1 局复盘 游戏复盘.md（13 KB），经历 6 次迭代优化：
- 初稿（用户笔记式记录）
- 重新组织成 9 章节
- 修正座位图（从圆桌 → 长方形）
- 修复"绝对化措辞"（
一定→概率较高） - 重写信号 5（去除武断推理 + 加入"跨局印象污染"反思）
- 优化开篇文案（强调"输赢不是重点"）
💡 这次迭代过程让我意识到：复盘文档的重写次数 = 思考深度的代理指标。
Day 2 · 上版本管理 + Gitee（约 5 分钟）
git init -b main
# 配置 git config user.name / user.email
# 生成 SSH key
# 通过 API 创建 Gitee 仓库 + 上传公钥
# 添加 origin remote + 推送遇到的坑：
- ⚠️ Gitee 默认创建私有仓库，即使 API 传
private: false—— 需要再调 PATCH 改成公开
Day 3 · 搭 VitePress 博客（约 1 小时）
brew install node
npm init -y # ❌ 失败！npm 不接受中文项目名
# 改成手动写 package.json
npm install -D vitepress
# 配 .vitepress/config.mts
# 写 index.md + about.md
# 跑 dev server 验证
# 跑 build 验证（首次失败：dead links）遇到的坑：
- ⚠️ npm init 拒绝中文项目名 → 手动 package.json
- ⚠️ Build 报 9 个死链（跨文件链接没改）→ 手动改成绝对 URL
Day 3 · GitHub mirror + Vercel 部署（约 30 分钟）
# 通过 GitHub API 创建仓库
# 上传 SSH 公钥到 GitHub
# 添加 github 第二 remote
# 推送
# 在 Vercel 网页 Import GitHub 仓库遇到的坑（连环 4 个）：
- ⚠️ Vercel 报错 "No Output Directory named 'dist'" → 加
vercel.json指定outputDirectory: ".vitepress/dist" - ⚠️ 部署后访问博客是 401 Authentication Required → Vercel Team 默认开 Deployment Protection，关掉
- ⚠️ 直接访问子页面 URL 返回 404（如
/游戏复盘）→vercel.json加cleanUrls: true - ⚠️ 复制中文 URL 到微信变成
%E6%B8%B8%E6%88%8F...→ 用 VitePressrewrites把 URL 重写成英文路径
Day 3 · 收尾（30 分钟）
把所有跨文件链接改成新的英文 URL，build 再次验证，推送，Vercel 自动重建。
最终博客：https://botc-learning-notes.pages.dev
Day 4 · 实战发现：Vercel 在国内需要 VPN（关键转折）
反馈：朋友在国内裸连访问 botc-learning-notes.vercel.app 打不开。
根因：Vercel 的 CDN 节点在国内大量地区被墙或不稳定。
初版修复：双部署——同时接入 Cloudflare Pages，国内朋友用 pages.dev、国际朋友用 vercel.app。
最终决定：放弃 Vercel，只保留 Cloudflare Pages——
- Cloudflare Pages 国内国外都能访问，单部署已经足够
- 双部署增加心智成本（两份构建状态要监控、两份域名要同步说明），不值得
- 配置精简胜过功能冗余
⚠️ 这个反思已经回流到
docs/05-deploy.md——以 Cloudflare Pages 为主推方案，Vercel 降为"备选"。下次新博客默认单 Cloudflare。
Day 5 · 加入 Giscus 评论系统（约 30 分钟）
动机：博客是单向输出，加个评论让读者能反馈。
选型：Giscus（基于 GitHub Discussions）——
- 不要数据库、不要服务器、不要外部账号系统
- 评论数据沉淀在自己的 GitHub 仓库，永远不会被平台绑架
- 自动支持深色/浅色模式
实现：
- 启用源仓库（
mmqqdd/botc-learning-notes）的 Discussions - 安装
giscus app到该仓库 - 用 giscus.app/zh-CN 自助生成 repoId / categoryId
- 创建
.vitepress/theme/Giscus.vue组件（深色模式跟随 + 路由变化重渲染） - 创建
.vitepress/theme/index.ts用doc-after槽位注入到每篇文档末尾
关键技术细节：
- 路由切换重渲染 —— VitePress 是 SPA，不监听路由会导致换文章评论不变
- 暗色模式 postMessage —— iframe 不会自动跟随主页主题，需要手动 setConfig
收益：每篇文章/复盘下面都有了独立的讨论区，读者可以用 GitHub 账号留言、反应（emoji）。
🔄 这个实现已经抽成模板：
templates/vitepress-theme/Giscus.vue和templates/vitepress-theme/index.ts（GitHub 仓库）。下次新博客只要替换 4 个 ID 就能用。完整说明：
docs/07-enhancements.md。
三、关键产物
| 产物 | 价值 |
|---|---|
~/game/血染钟楼/ | 主题仓库（Gitee + GitHub 双远端） |
https://botc-learning-notes.vercel.app | 博客（朋友可访问） |
~/.config/gitee/{token,user.env,gitee.sh} | Gitee API 工具链 |
~/.config/github/{token,user.env,github.sh} | GitHub API 工具链 |
~/.zshrc 加 2 行 | 自动加载工具链 |
~/.ssh/{id_ed25519,config,known_hosts} | SSH 一把钥匙开两扇门 |
| 本 playbook | 元产物——下次不用重新踩坑 |
四、踩坑总结表
| # | 阶段 | 错误现象 | 根因 | 修复 |
|---|---|---|---|---|
| 1 | git/api | Gitee 仓库私有 | 默认行为 | API PATCH 改 |
| 2 | npm | Invalid name: "血染钟楼" | npm 不收中文 | 手动写 package.json |
| 3 | vitepress build | 9 个 dead link | 跨文件链接没跟随 rewrites | 改成绝对 URL |
| 4 | vercel build | No "dist" directory | VitePress 输出在 .vitepress/dist | vercel.json 指定 |
| 5 | vercel access | 401 Auth Required | Team 默认开保护 | 关 Deployment Protection |
| 6 | vercel routing | 子页面 404 | cleanUrls 不生效 | vercel.json 加 cleanUrls |
| 7 | sharing | 中文 URL 在微信变丑 | URL encode | rewrites 改英文路径 |
五、关键决策回顾
决策 1：要不要把 token 删了？
初稿建议："用完就删"。 修正后：长期保留 + 定期轮换——token 是 API 的钥匙，删了下次创建仓库就要重新生成。
这是这次实践中最有方法论价值的反思之一。错误的"安全"建议会让用户重复造轮子。
决策 2：URL 用中文还是英文？
初版：直接用中文文件名当 URL。 用户反馈："复制到微信会变 URL-encode 成丑长串"。 修正：用 rewrites 把源文件中文名映射到英文 URL—— 源仓库友好 + 博客分享友好。
这是典型的"理论 vs 实战"差异——技术上中文 URL 完全合法，但实际分享场景下会出问题。
决策 3：座位图用什么风格画？
经历：圆桌 → 长方形 → 加说书人位置 → 调整左右两侧对称 收获：ASCII art 反复迭代是写作正常成本。让用户看到第一版后说"应该是这样"，远比你猜测好。
决策 4：是否轮换 GitHub token？
初版建议：90 天定期轮换 vs 一次配好长期用。 用户选择：90 天定期。 配套设计：在 github.sh 里写明续期命令的注释（用户 90 天后看代码就能知道怎么换）。
设计原则：把维护说明写到代码自身里，而不是单独的"运维文档"。
六、用户反馈（精华引述）
💬 "我觉得 token 需要长期保留吧，是不是没有 token 就没法创建仓库和更多操作？"
—— 用户的这个追问让我修正了"用完就删"的错误建议。
💬 "我希望最终就是，能给别人一个链接都能访问。"
—— 这条诉求驱动了"关闭 Vercel Authentication"的发现。
💬 "我把链接复制到微信里，自动转成 utf8 编码了，如果这样是不是不如用英文？"
—— 这条诉求驱动了"URL rewrites 改英文"的优化。
💬 "每个仓库建立一个网站，有不同的博客，这样好一点，之后也可以进行定制操作。"
—— 这条诉求驱动了 playbook 本身的诞生（"一主题一仓库"哲学）。
七、时间投入分析
| 阶段 | 实际花费 | 理论最快（有 playbook 后） |
|---|---|---|
| 内容创作 | 1 小时 | 1 小时（不可压缩） |
| 复盘迭代 | 1 小时 | 1 小时（不可压缩） |
| Git + Gitee | 5 分钟 | 1 分钟（用 gitee-init-and-push） |
| GitHub mirror | 30 分钟 | 1 分钟（用 github-init-and-push） |
| VitePress 配置 | 1 小时 | 10 分钟（拷模板 + 改 sidebar） |
| Vercel 部署 + 踩坑 | 30 分钟 | 5 分钟（坑都修过） |
| 切换到 Cloudflare Pages | 10 分钟 | 0 分钟（默认就用 CF） |
| URL 重写优化 | 30 分钟 | 0 分钟（模板已含 rewrites） |
| Giscus 评论系统 | 30 分钟 | 5 分钟（拷模板 + 改 ID） |
| 总计 | 约 5.5 小时 | 约 2.5 小时 |
结论：playbook 让"非内容部分"从 ~2.5 小时压缩到 ~30 分钟——节省 80% 流程时间。
八、可改进的地方
下次实践可以尝试：
- 用 Vercel CLI 跳过网页 Import（这次还要手动点击）
- 写一个
new-blog-topic.sh脚手架（自动生成模板 + init git + 推远端） - 预先验证 build 成功再首推（避免推到远端后又 fix 一堆 vercel.json）
- 加一个 link-checker 工具（建链接前先扫描所有跨文件链接）
九、回到 首页
这是第 1 个案例。期待第 2 个、第 3 个、第 N 个。每多一次实践，方法论就成熟一分。