和 Codex 一起重构博客
Table of Contents
起因是看到了项目 impeccable，一个面向网页设计优化的 skills 集。我想验证这套能力在自己的博客上能推进到什么程度，于是以现有站点为对象做了一次完整重构。
注意：本文大部分是 codex 自己生成的，我只是简单做了校订。
这次工作持续了2小时1，范围从界面审计逐步扩展到发布链、样式系统和入口内容统一。最终结果不是单点修补，而是一次沿着“审计 -> 修复 -> 抽象 -> 打磨 -> 回收内容层问题”推进的系统性整理。
Impeccable 项目
这是一个专业的网页设计优化 skill 集，支持多种 agent 工具，他提供以下几个有用的 commands，也是我这次项目中使用的
audit审计，能对现在的设计做全面的设计审计，给出问题报告，包括评分和建议，往往是所有过程的开始critique批评，从用户体验角度做质量评估，提供可用反馈harden硬化，优化错误处理，文本信息，边界条件处理等，提供健壮性normalize规范化设计，让各页面的设计保持统一optimize优化性能，减少图片、字体等加载延迟adapt多尺寸设备支持clarify改进文案，标签和 thumbnail ，让界面更可理解animate提供更好的交互动画colorize提供更好的颜色，优化可读性extract提取可复用组件，让系统更好维护
可以看到，这整套 skills 是符合设计流程和工程流程的，一站式解决了开发者”随手写的样式很难看“，但抄样式又抄不出统一性的问题。
博客样式优化流程
起点：先让它做一次足够严格的审计
起点不是直接改样式，而是先做一次比较完整的 audit。这样可以先建立问题列表，再决定修改顺序，而不是围绕模糊的审美直觉来回试错。
第一轮结论大体准确：站点并不属于典型的 AI 模板风格，但存在一批长期维护项目常见的问题，包括共享 CSS/JS 的历史遗留缺陷、导出器责任混杂、页面级内容完成度不一致，以及首页和文章页层级不够稳定。更重要的是，这一轮已经把问题按层拆开：共享资源、导出链、内容源、视觉细节。后续协作基本都沿着这条分层继续推进。
先把上下文钉死：引导 AI 正确理解项目构建方式
在开始修改之前，我先把项目的真实边界补充完整，我的项目是使用 使用 org-mode 写博客 ，所以工程化方式很特殊：
assets/目录是静态的，可以直接改。- 其他 HTML 页面都由
~/.emacs.d/site-lisp/ox-publish-blog.el生成。 - 平时我在 Emacs 里用
M-x my/preview-blog预览，站点跑在localhost:8080。 - 只要全套环境加载完整，也可以 batch 执行发布。
这些信息后来都写进了本地的 AGENTS.md 。这样做的直接作用，是把“哪些文件可直接修改、哪些必须回源头”的规则固定下来，避免后续把时间浪费在错误层面。
第一阶段：先做 harden，把共享层的硬问题处理掉
明确生成链路之后，最先推进的是 harden，而不是样式打磨。共享层不稳，后续的 visual polish 很容易变成返工。
这一阶段主要处理了三类问题：
- 修共享前端资源里的问题
桌面端 TOC 观察逻辑原来有选择器错误，移动端 TOC 开关也不是一个真正可访问的按钮。修正之后，目录才真正成为稳定的导航系统。
- 修共享样式和主题 token
dark token、对比度、触控尺寸、长文本溢出等基础问题也做了一轮修补。这些修改不显眼，但决定了站点的整体完成度。
- 把修复放回导出链，而不是手改生成页
skip link、外链 noopener noreferrer 、CDN 图片统一升级到 HTTPS、图片 alt 和 lazy/decode、页面语言标记等处理，都回收到了 ox-publish-blog.el 的后处理逻辑里。目标不是修当前输出，而是保证后续发布默认就是正确的。
第二阶段：normalize 和 optimize，把“系统感”补起来
共享层基本稳定后，继续推进的是 normalize 和 optimize。
normalize 的核心不是换皮，而是把零散数值收成一套稳定 token，包括颜色、阴影、圆角、间距、字体角色和明暗主题规则。到这一步后，共享样式才真正具备统一性。
optimize 更偏工程层。最大的收益是移除了每个 HTML 页面重复注入的 Org 默认内联样式，统一改成依赖共享样式文件。这一步也暴露出一个事实：页面其实仍然依赖其中一批 Org 基础规则。后续又补回了标题、对齐、tag、timestamp、postamble 等基础样式，才使这次优化真正闭环。
第三阶段：extract，把导出器从“能跑”整理成“能维护”
这次协作里，工程价值最高的一段其实是 extract。
原来的 ox-publish-blog.el 能完成发布，但更像长期演化出来的工作脚本，而不是边界清晰的发布系统。随着修复逐步增多，如果继续往里堆逻辑，维护成本会很快上升。
因此后来连续做了几轮 extract：
- 把 shared publish config 抽出来
- 把 HTML 后处理流水线拆成明确步骤
- 把 sitemap 里的 HTML 片段模板化
- 把 postamble、analytics、license、元信息行拆成可复用片段
- 最后把
org-publish-project-alist也改成统一 builder 生成
这部分完成之后，最明显的改进不在页面，而在维护性。导出器的职责边界更清楚，后续继续扩展时不必再依赖历史记忆。
第四阶段：polish，不是改花，而是把不顺的地方收平
进入 polish 阶段后，重点不是添加更多视觉元素，而是消除那些影响阅读节奏和版面一致性的细小问题。
这一阶段最有效的调整包括：
- 首页不再是所有文章权重一样的长列表，而是有主推和次级层级
- 文章页的 TOC 被明确降级成辅助导航，不再抢标题区的注意力
- 中英混排的字体气质重新统一，避免英文像一套设计、中文像另一套设计
- 首页首卡逐渐减轻“组件感”，更像编辑导语区
- 导航、文章标题链接、目录链接的 hover 和 active 状态变得更自然
- 有 TOC 的文章页里，首段和正文列宽重新统一，不再突然窄一截
其中一个很典型的问题，是带 TOC 的文章页里首段和正文宽度不一致。最后定位到的根因并不是容器宽度，而是一条专门作用于 p:first-of-type 和 blockquote + p 的 max-width: 58ch 规则。删除这条规则之后，版面立即恢复一致。这个例子说明，AI 在这类工作里最有效的作用往往不是“自动生成更好的 CSS”，而是帮助更快定位真正生效的那一层规则。
第五阶段：clarify，把入口内容的完成度拉齐
样式和结构稳定之后，内容层的不一致开始变得显眼。于是又做了几轮 clarify，把高曝光入口页的标题和摘要重新整理了一遍，例如 About 改成 =关于=，旧文章标题统一成更稳定的中文展示名，首页前几篇摘要也改成更适合扫读的形式。
这一步再次说明，视觉系统稳定之后，内容质量会被更清楚地暴露出来。设计系统不能替代内容整理，但它能把内容层的问题显式化。
这次协作真正让我满意的，不是页面本身
如果只看结果，这次得到的成果包括：
- 共享样式和共享脚本更稳了
- 发布链可以在 batch 环境里完整跑通
- 站点生成逻辑更清楚了
- 首页、文章页、移动端的阅读体验都更顺了
- 入口内容的标题和摘要也更统一了
更重要的是，这次协作逐渐形成了一套明确的工作方式2：
- 先审计，再分层
- 把项目边界讲清楚
- 共享问题回到 shared asset
- 生成问题回到导出器
- 内容问题回到 Org 源
- 每一轮都只解决一类问题
和单次把页面“改完”相比，这种分层处理方式更适合长期维护。
正确的与 Codex 做交互
本段是人写的
Codex 已经很聪明，但因为我目前还没让他连接 browser ，他看不到真正的 UI ，我会在预览结果后，通过截图和标注告诉 Codex 有问题的地方，让他优化。多数时候，我只是问他：你觉得你接下来要做什么？
他会告诉我，我们现在有 1/2/3 多个项目，但收益更大的是应该先做 1 。这是一种良好的判断。
或者我问：我们是不是到这里差不多了，但我有一个另外的需求。Codex 多数时候也答应。总的来说，通过这套 skill 来做样式重构还是非常简单的。
结语
这次重构之后，我更确定了一点：AI 更适合作为可纳入工作流的工程伙伴，而不是脱离上下文的万能生成器。它适合参与审计、定位、重构和复盘；前提是项目结构足够清楚，修改边界足够明确。
这次工作的最终价值，不只在于页面本身变得更稳、更统一，也在于博客的维护方式被进一步显式化。对于长期维护的个人站点来说，这比单次视觉优化更重要。