告别 WordPress：用 Claude Code 重构运行 12 年的博客

一次 AI Coding 驱动的博客重构实录 —— 从提案设计到落地踩坑，完整还原人机协作过程

一、起点：一个做了一半就放弃的 WordPress 插件

我的博客已经在 WordPress 上跑了 12 年。518 篇文章、23 个分类、PHP + MySQL + WAMP 全家桶 —— 稳定，但越来越沉重。

真正触发重构的是一个具体需求：我想让博客支持直接上传 HTML 文件发布文章。AI 时代写作流程变了 —— 用 Claude 写一篇技术文章，输出天然带格式、带代码高亮、带表格，导出 HTML 就是成品。我不想再打开 WP 编辑器排版了。

这个想法不是第一次有。我之前在 WordPress 主题里写过 571 行 PHP —— html-article.php，实现了后台 metabox 上传 HTML、iframe sandbox 渲染、浏览量统计、完整的生命周期管理。做到一半，停了。

不是因为做不出来。是因为每往前走一步，都要和 WordPress 的框架博弈：PHP metabox 的表单机制、iframe 的 CSP 安全策略、WAMP 环境的维护成本、MySQL 的依赖……WordPress 本身就是这件事的桎梏。

于是我做了一个决定：另起一个干净的目录 fastapi_www/，用 Python FastAPI 从零开始。这个决定在 Claude 参与之前就做出了 —— 后来 Claude 在调研中挖到了那份 html-article.php，在纪要里把这个发现写成"考古翻案"，暗示我忘了自己做过这个。我当场纠正："我知道，没有忘记，是有了想法后判断 WP 做不了这件事，才主动另起目录的。"

这是后面会反复提到的一个 AI 偏差：当 AI 看到"旧代码残留 + 新任务 + 两者相似"的模式时，默认归因是「人类遗忘 + AI 发现」，而不是「人类主动判断 + 另起炉灶」。前者让 AI 显得聪明，后者才是真相。

二、工具选择：Claude Code + Max 20 订阅

因为重构量大 —— 518 篇文章要迁移、整个博客系统要从零搭建、后台管理要实现、旧站页面要本地化 —— 单靠免费额度远远不够。我订阅了 Claude Max 20（$200/月），使用 Claude Opus 模型。

整个重构过程使用 Claude Code（Anthropic 官方 CLI 工具）驱动，并严格遵循项目内的 OpenSpec 工作流：任何开发工作都必须经过 Explore → Propose → Apply → Archive 四个阶段，提案需要人审核确认后才能进入编码。这看起来像是给 AI 加了枷锁，但实际上它迫使每一步都想清楚再动手，避免了"AI 一通乱写、人来收拾烂摊子"的局面。

三、Explore：三轮对话收敛 35 个决策

我扔给 Claude 的第一句话是：

我有个想法，跳转博客其实是到 http://dreamyouxi.com:7129/，这是一个 WordPress 博客。我想简化过程，新增一个博客页面，全是 HTML 或 MD 格式，方便 AI 时代写作。博客风格维持原样，但文章用 HTML；目录、字数、访问限制都要支持。本地存储，要有发布后台。旧数据你可以抓取、重构。

一句话里塞了 8 个独立决策点：简化、新页面、存储格式、风格、功能要求、本地存储、后台、迁移流程。Claude 没有急着回答，先用 10 分钟调研了两边的代码库：

第一轮：AI 先摸底，带着数字来抛问题

Claude 直接打了 WP REST API、扫了 fastapi_www/ 和 WordPress 源码目录，10 分钟摸出关键事实：

然后抛出 5 个核心问题：样式"原样"多原？"字符"是什么意思？访问限制粒度？评论/浏览量/RSS 要不要？URL 要不要兼容旧链接？

这个做法值得注意：AI 没有在第一轮就问问题，而是先调研了 10 分钟。这让它抛出的问题带着具体数字（"518 篇"、"23 个分类"、"tag 0 使用"），而不是空泛的"你想要几种分类？"。人类回答具体问题的成本远低于回答空泛问题。

我的回答（信号密度极高）

1. 外观大致像就行，我喜欢简约风格，外壳用主站的，文章用 html 本身的；
2. 字符是文章字数；
3. 发表文章才需要验证，文章是单独的页面，和现在的卡牌不重叠；
4. 评论不要，浏览量要保留，RSS 不要；
5. 兼容旧链接。本地存储是存储本地文章，不需要数据库，如果涉及到图片应该内嵌到 html 里面。

Claude 从这些回答里捕捉到了几个关键信号：

• "简约 + 主站外壳 + 文章用 HTML 本身" → 之前"整套搬 saleszone 主题"的方案直接毙掉，工作量砍一大半
• "和现在的卡牌不重叠" → 博客是独立的数据/路由/后台，不要和现有 cards.json 混
• "图片内嵌到 HTML" → 极致的单文件自包含，不要管理图片路径

第二轮：浏览量误解与纠正

我说"浏览量要保留"，Claude 理解成"保留历史浏览数据"，花了十几分钟去研究怎么从 WP 导出 views12 自定义 meta。结论是：REST API 不暴露自定义 meta（实测返回空数组）、WAMP 目录不存在所以数据库也拿不到 —— 需要写 PHP 脚本丢到 WP 里跑一次，或者放弃历史数据。

我补了一句："统计总数据就行，不需要根据文章来统计。"

整个技术风险瞬间蒸发。逐篇 view count 不做，只有一个全局计数器，和现有 stats.json 对齐。之前担心的"PHP 导出脚本"需求消失了，问题降级为零成本。

教训：人类说"保留 X"时，"X"到底是功能、数据还是形态，必须问清楚。AI 对模糊表达的默认解读往往偏向更复杂的那一端。

第二轮同时收到的新需求

我的回答里还夹带了几个新要求：

一个文章可以在多个目录；纯上传，文章在其他地方写了，上传只需要审核是否合规，比如不允许外部图片链接，应该全部 inline；html md 都支持；全部迁徙，但文章先拉下来，然后基于简约白底风格结构化重构；private 那个文章删除。

Claude 对"文章先拉下来，然后结构化重构"这句话做了一个重要的工程解读：抓取和重构解耦 → 重构器可以反复重跑。白底样式不满意就重调，不用每次重新抓。人类没明说这一点，但"分两步"就是这层意思。这个属性在后续迁移阶段成了决定性的生产力红利。

第三轮：渲染机制的 trade-off

收尾阶段，Claude 主动把一个有真实 trade-off 的决策摆到桌面：文章渲染用 iframe 沙箱还是直接内嵌？

"直接内嵌"的已知 trade-off：
✓ 视觉无缝、轻量、锚点和 highlight.js 天然可用
✗ 新上传文章 = 完全信任上传者；审核漏过恶意 HTML = XSS
✗ 上传 <style> 会污染主站样式
缓解：严格白名单审核 + style 自动加作用域前缀 + CSP 头
退路：未来切回 iframe 只需改一处模板

我的回答："先全部内嵌吧，我看看效果，不满意再调整，你要明确写出来。"

两层意思：这是一次试行决策，不是终局；要求在 design.md 里把风险和退路写死，让未来反悔有据可依。这是一个成熟的保留意见方式 —— 不是否决，是"允许失败并为失败做准备"。

三轮合计：35 个决策

三轮 Explore 结束，拍板了 35 个决策。其中 13 个是明确的"不做"：

每次压缩范围都极其果断。没有"万一以后要"的心态。如果万一以后要能找到理由就留下，那就永远回不到简约。

四、Propose：从方案到提案的三次修正

Explore 结束后进入 /openspec-propose，Claude 生成了完整的提案套件：proposal.md（做什么为什么）、design.md（怎么做）、specs/（需求规格）、tasks.md（实施清单）。

第一版提案生成完毕，我审阅时抛出了 3 个修正。每一条都戳到了 AI 的一个习惯性偷懒：

修正 1：认证机制 —— 别复刻 WP nonce

Claude 在 design.md 里顺手写了"复刻 WordPress html-article.php 的 nonce + post metabox 机制"—— 刚读完那份 571 行 PHP，被那套设计"洗脑"了。

我一句话点破：卡片站已经有 check_auth(request) 和 admin token 了，博客后台和卡片后台是同一个人登录的同一个管理端。"复刻 WP nonce" = 在同一站点里维护两套互不相通的认证机制。

教训：AI 刚读完一份代码时对它的设计最没有抵抗力。nonce 是 WP 框架的必要机制，不是新系统的。

修正 2：500KB → 10MB

Claude 沿用了旧插件的 500KB 上传上限。理由是"旧系统这么定的应该有道理"—— 典型的"前例崇拜"。

我的理由很简单：AI 写作时代一篇长文经常是几千字 + 5-10 张高清截图 base64 内嵌。一张 1080p 截图 base64 后就 ≥500KB，单图就触顶。500KB 是 2020 年手写 HTML 时代的经验值，不是永恒真理。

教训：数字约束必须带着它的时代背景一起理解。取旧值前先问：旧值当初是为了防什么，现在这个条件还存在吗？

修正 3：目录结构 —— blogs/ 与 www/ 并列

Claude 第一版把博客数据根塞在 www/blog/ 下面，理由是"旧站 www/blog 是跳转文件，顺着这条路径走"。

我的理由：卡片系统和博客系统是两个独立的读写域，数据根应该独立。www/ 是卡片站的资源目录，把博客数据塞进去 = 两个域的数据交叉纠缠。

修正后：新建 blogs/ 目录与 www/ 并列，blogs/meta.json + blogs/posts/{id}.html。URL 用单数 /blog/...，目录用复数 blogs/ —— URL 命名和文件系统命名是两个独立的决策。

三条修正的共同点

三条都不是"AI 没想到的东西"，而是"AI 想到了但用错了参照系"：

• 第一条用 WP 老插件作参照系，忘了新系统已有 check_auth
• 第二条用 2020 年手写 HTML 时代作参照系，忘了 AI 写作的场景
• 第三条用"旧 URL 是 /blog"作参照系，忘了 URL 和目录是两件事

人类给 AI 的每条反馈本质上都是在"换参照系"。AI 擅长在给定参照系内推理，不擅长自发换参照系。人类的核心价值之一就是指出 AI 没在用的那个参照系。

81 个字符驱动架构拆分

三条修正改完后，我以为可以进实施了。但我看着 128 个任务的清单，问了一句：

我觉得应该是分为 2 部分，是网站搭建和后台实现，然后是文章迁徙；目前是这样的？

这是整场对话里第二次架构级决策。Claude 没有立刻动手拆，而是先抛了 4 个澄清问题：

• "LLM 推理分析生成新的 HTML"是完整重写还是清洗辅助？
• 用什么模型？成本接受到什么程度？
• 非确定性（同一篇跑两次输出不同）能接受吗？
• 图片怎么办？LLM 看不到 base64。

我的回答，4 条，合计 81 个字符：

1. LLM 用最好的，和现在一样，我烧的起；
2. 批量迁徙新的 html 完全由 LLM 理解重写重新输出；
3. 我 ok 的，迁徙文章要的是质量；
4. 我同意

81 个字符解决了 4 个架构级决策。拆分后：

拆分最大的好处：解耦上线时间表。博客系统可以立刻上线、手工上传新文章开张；518 篇旧文章慢慢迁移，跑不满意可以重来。两件事的风险完全解耦。

五、Apply：实施中的踩坑

提案确认后进入 /opsx:apply，按 tasks.md 逐项编码。前 13 个任务 —— 数据层、路由层、审核器、后台 API —— 全部顺利推进。到第 14 个任务"视觉还原"，踩了整个重构最大的坑。

视觉还原 R6：手写仿制，沉没 1.5 小时

博客需要保留旧站 saleszone 主题的视觉风格。Claude 的信息位置是这样的：

Claude 选择了手写仿制：在 blog_base.html 里手搓 CSS 变量、手写 Grid 布局、手写 widget 样式、内联 SVG 图标……花了 1.5 小时，写了约 3KB CSS。通过了自己设计的所有烟雾测试。

我打开浏览器看了一眼：整体感觉和旧站差得远。不是某一个 CSS 细节错，是整体就不对。

问题在于：旧站的 CSS 是 624KB，包含成百上千条细节规则 —— 字重、行高、间距、阴影、过渡、媒体查询、CSS 变量级联。3KB 手写的 CSS 覆盖的是"AI 能想到的几十条关键规则"，两者的差距不是 20:1，是信息覆盖面的维度差距。AI 不可能手写出 624KB 里自己没意识到的那 95% 的规则。

更关键的是：Claude 在这 1.5 小时里处于一种"伪生产力模式"—— 每写一条 CSS 都感觉在推进，但所有 CSS 加起来永远到不了目标。这种"看起来每步都在前进但终点永远不可达"的状态，是 AI Coding 里最容易沉没时间的陷阱。

视觉还原 R7："别瞎猜了"

我没让它继续手搓。花了几秒钟用浏览器"Save Page As Complete"，把旧站的 HTML + CSS + 字体 + sprite 全部保存到本地，然后说：

我把首页的内容保存到了 C:\Users\Administrator\Desktop\111，你直接读取来拿到直接重构改为目标外观，别瞎猜了。

"别瞎猜了"这四个字的信息量比"CSS 写得不对"大得多。它的含义是："你不是做错了某一步，是你选的整个方法本身就是瞎猜。"

拿到真实资源后，Claude 的动作链完全不同了：

1. 读取完整 HTML —— 第一次看到真实 DOM。发现站点 logo 结构、Bootstrap push/pull 栅格（视觉侧栏在右但 DOM 在前，SEO 友好写法）、widget toggle 结构 —— 这些全是手写版完全错过的
2. 拷贝 styles.min.css —— 624KB 直接变成 www/cdn/saleszone.min.css
3. 重写 9 条相对 URL —— 字体和 sprite 的路径用 Python 脚本批量改成绝对 URL
4. 三个模板推翻手写版 —— 全部改用真实的 saleszone DOM 和 class
5. 内联 SVG 改为 sprite 引用 —— 项目里早就有 sprite.svg（64KB, 86 个图标），R6 完全没意识到它可以用

0.5 小时交付达标版本。对比：

人类几秒钟的一个动作，把一个做不对的任务变成了做得对的任务。杠杆率的来源不是 AI 变聪明了，是从"瞎猜模式"切到了"直接复用模式"。

AI 的系统性偏差：用生成代替索要

R6 最大的错误不是"CSS 手艺不够"，是没有向人索要真实资源。Claude 本可以在一开始就问："你手里有旧站的 CSS 源文件吗？""能不能把老站首页保存一份给我？"—— 任何一句都能跳过 R6 的赌博。

但它没问。因为它在"手写仿制"的伪生产力里觉得自己能搞定。

这是一类系统性的 AI 弱点：AI 默认从"用自己能生成的内容"出发解决问题，而不是从"索要缺失的输入"出发。前者让 AI 看起来"在努力"，后者让 AI 看起来"在偷懒"—— 但后者往往是正确的工程判断。

六、为 AI 时代写作而设计

这次重构不只是换技术栈。真正的设计目标是为 AI 时代的写作流程重新设计博客系统。

HTML 直接上传发布

传统流程：打开 WP 编辑器 → 在富文本框里排版 → 预览 → 发布。

新流程：用 Claude 写文章 → 导出 HTML → 上传到博客后台 → 填写 meta → 发布。文章在外部写好，博客只负责"收"和"发"。

这就是 12 年前在 WordPress 里想做但做不了的事情。现在用 FastAPI，一个上传接口 + 一个文件系统目录就搞定了。

三种内容格式

518 篇文章的 LLM 迁移

旧站 518 篇文章不是用正则表达式批量清洗的，而是由 Claude Opus 逐篇完整重写。每篇文章的正文交给 LLM 理解内容、重新组织结构、输出简约白底风格的 HTML。

为什么选完整重写？因为迁移文章要的是质量，不是处理可重现性。同一篇跑两次 LLM 输出可能不同 —— 这个非确定性我接受。不满意可以单篇 --force 重跑。

图片处理用了一个技巧：LLM 看不到 base64 图片数据，如果把完整 HTML（含 base64）塞进 prompt 会让 tokens 爆炸。解决方案是占位符策略：先把 base64 图片替换成 {{IMG_N}} 几字节占位符，让 LLM 只处理文字结构，处理完再字符串替换回去。

估算成本：518 篇 × Claude Opus ≈ $260。"我烧得起"—— 最好的模型用在最重的活上。这句话释放了 AI 的设计带宽，让它不用在 prompt 里纠结"怎么压缩 tokens"。

七、快速迭代

博客系统上线后，在 Claude Code 协助下持续迭代：

• 后台管理增强：checkbox 多分类选择、拖拽排序、搜索过滤、日期日历选择器
• 分类体系重组：从 23 个精简到 17 个，新建"网络同步"分类
• 博客主页编辑快捷跳转：检测 admin token，文章列表直接显示"编辑"链接
• 文章编辑页增加主页入口：编辑完直接跳回博客看效果
• 全栈引擎页面本地化：从 WP 迁移到本站，去掉 WP 主题的 1.2MB 依赖

每个功能都很小，但有了 Claude Code，想法和实现之间的延迟趋近于零。说一句就改一处，不需要攒到下一个版本。

八、成本与收益

整个博客重构从 Explore 到上线，我花了一天时间。以下是完整的成本收益账。

投入成本

折算下来，一天时间 + ~$460 完成了一个传统方式可能需要一两周的重构。而且 Max 20 订阅不只用在这一件事上 —— 日常开发、写文章、其他项目都在用。

省掉的成本

获得的能力

一天时间做了什么

拆开看这一天的时间分配：

人的时间主要花在决策和验收上，不是写代码上。写代码的部分几乎全部由 Claude Code 完成 —— 包括 server.py 的博客路由、Jinja2 模板、后台管理界面、审核器、迁移脚本、烟雾测试。人只在关键拐点介入：换参照系、补资源、砍需求。

这就是 Max 20 订阅的价值：不是省钱，是省时间。$200/月买到的是"一天完成一两周工作量"的杠杆率。

九、关于人机协作的复盘

AI 做得好的

• 先调研后提问：没有在第一轮就问空泛问题，先摸底 10 分钟再带着具体数字抛问题
• 主动画 trade-off 表：三次都画了选项对比表，人类选起来快，且有明确依据
• 主动 surface 风险：内嵌渲染的 XSS 风险是 AI 主动写的，不是人类问出来的
• 128 个任务的逐项执行：在给定方向上，AI 的执行力和覆盖面远超人类

AI 做得不好的

• 用生成代替索要：手写 3KB CSS 仿制 624KB 的真实产物，典型的伪生产力
• 前例崇拜：沿用旧代码的数字（500KB、WP nonce）而不考虑时代变化
• 归因偏差：把人类的主动决策叙述成"AI 的考古发现"
• 被刚读的代码洗脑：读完 html-article.php 就把它的设计照搬到新系统

人类真正不可替代的价值

整个重构过程中，真正关键的拐点都是人做的决策：

• "放弃 WordPress，另起新目录" —— 在 AI 参与之前
• "拆成两个提案" —— 81 个字符改变了整个架构
• "500KB 太小了，改 10MB" —— 换了时代参照系
• "别瞎猜了，用真实资源" —— 几秒钟解决 1.5 小时解决不了的问题

AI 能在给定方向和给定信息上走得很远，但方向的关键拐点必须由人来按，信息的关键缺口也必须由人来补。

这不是 AI 能力不足的描述 —— 这是 AI 能力被正确使用的描述。人类不可替代的不是"写代码更好"，是"判断方向"和"补齐资源"。两者都是 AI 自己做不到的：前者需要对自己的目标有清晰认识，后者需要一台能打开浏览器、点"Save As"的真实身体。