用 Impeccable 优化个人 Wiki 的实践记录
本文目录
最近整理这个 Wiki，我借助 Impeccable 做了一轮前端优化。最初想改的是配色、Logo 和博客展示，真正影响日常使用的问题却陆续出现在搜索失败、字体下载、键盘操作和移动端布局里。
这次最有用的经验是：先告诉 AI 这个网站用来做什么，再把设计意见变成可以复现、可以验收的任务。 对我的运维笔记本来说，找得到笔记、读得清楚，比首页多几个漂亮组件更重要。
Impeccable 能帮忙做什么
Impeccable 是面向 AI 编码助手的一套设计技能，提供设计指导、专项命令和确定性检测工具。它可以参与新页面设计，也可以针对已有界面检查和修改。具体改动仍由编码助手在项目里完成。
我更看重它提供的工作方式。原来一句“帮我优化一下”，可以拆成检查阅读体验、调整排版、处理异常状态、适配小屏幕等明确任务。每次讨论的范围更小，也更容易判断改动是否有效。
官方把产品背景与视觉规范分开保存：PRODUCT.md 记录受众、用途和约束，DESIGN.md 记录配色、字体、组件等设计决策。这个区分很实用：网站用于个人查阅，是长期目标；具体选择哪种绿色、标题用什么字体，则可以继续调整。官方介绍
安装与常用入口
按官方安装说明，可以在项目目录运行：
npx impeccable install
根据安装提示选择正在使用的编码工具和安装范围，安装后重新加载工具。不同安装渠道的版本和命令入口可能不同，以实际安装内容为准。
下面采用这次使用环境中的 $impeccable 写法。这些是发给编码助手的提示，不在终端里执行。官方文档也使用 /impeccable 展示命令。
不必先记住全部命令，我在维护已有站点时主要关注这些：
| 当前问题 | 适合的命令 | 我会补充的任务范围 |
|---|---|---|
| 页面重点不清楚，查找路径别扭 | critique | 从个人查笔记的过程评价首页 |
| 想检查可访问性、性能和响应式 | audit | 列出问题、位置、影响与复现步骤 |
| 正文、标题、代码的字体关系混乱 | typeset | 分别检查中文、英文和命令 |
| 加载失败、长内容或连续操作出错 | harden | 重点检查搜索与重试 |
| 小屏幕或横屏时内容放不下 | adapt | 保证核心入口可见、可操作 |
| 图标、文字和间距不齐 | layout | 修正导航栏的局部对齐 |
| 页面资源过重 | optimize | 检查字体和搜索索引的加载方式 |
| 准备交付 | polish | 检查已修改路径的一致性与遗漏 |
命令提供分工，具体目标仍需要自己讲清楚。命令说明
先确定这个 Wiki 应该保留什么
这次改版一开始也走过弯路。把笔记分成“操作教程、故障排查、命令速查”，看起来很整齐，但我平时首先想到的是 Linux、Nginx、Kubernetes 或数据库。换成文章类型分类，反而多了一步判断。
于是目录继续沿用原来的技术主题。首页保留诗词，Logo 最后定为折页 J；正文与控件则优先保持清楚、稳定。配色从“亮色水墨、暗色科技”的描述，逐渐收敛到青瓷浅色与深墨柔翠，同时去掉影响阅读的模糊和发光效果。
如果重新开始，我会先给出这样的约束：
$impeccable critique 首页和笔记阅读页
这是我自己查阅运维笔记的网站，主要任务是找笔记和读技术内容。
保留现有技术分类、首页诗词和折页 J 标记。
首页可以有个人风格，正文、表格、命令和搜索要清楚。
先指出影响查找和阅读的问题，给出具体页面位置与原因。
这段约束比“更高级一点”“减少 AI 味”更有用。它让后续修改有了取舍依据：装饰可以减少，常用入口和已有内容不能随意重组。
三个最值得记录的修复
搜索要覆盖失败和重复操作
统一搜索后，导航建议和完整结果页共用本地索引，笔记与博客都能被检索。审计又推动了几个更细的处理：加载失败要结束等待并允许重试，清空按钮要容易点击，方向键与回车要能完成选择。
但第一轮验证结束后，仍然发现了一个容易遗漏的问题：
- 输入
nginx，等建议出现。 - 按 Escape 关闭，再按向下方向键打开。
- 第一条结果短暂选中，随后选中状态消失。
- 按回车，进入全部结果页，而不是刚才选中的笔记。
原因是浮层重新打开时重复触发查询，异步更新了结果数组，组件又随之清空选中项。最后的处理是保留最近一次成功结果；相同查询重新打开时复用结果，显式重试仍会重新查询。
已有的 10 项搜索测试当时全部通过，覆盖的是索引读取、并发隔离、失败恢复和超时，并没有覆盖这一串界面操作。 这提醒我，测试通过之后，还要按用户的实际顺序走一遍。
浮层高度要把底部操作算进去
另一个问题发生在较矮的视口里。结果列表已经设置了最大高度，但整个浮层还有状态说明和底部操作区。几部分加起来，“查看全部结果”仍然被挤出了屏幕。
修复时限制的是整个浮层的可用高度：状态说明与操作区保留空间，结果列表允许收缩，并在内部滚动。这样在 390×300 的模拟视口里，底部入口仍然完整可见。
这个问题适合交给 adapt，但提示词最好带上验收条件：
$impeccable adapt 顶部搜索浮层
在 390×300、390×360 和桌面矮视口中检查。
结果列表可以滚动，底部“查看全部结果”必须始终可见、可点击。
保留现有配色，并验证方向键选择与回车跳转。
这些检查证明了模拟视口中的布局与键盘行为。手机软键盘弹起、真机触摸滚动和不同浏览器的表现，还需要对应设备验证。
按钮扩大后的图标对齐
移动端菜单按钮扩大到 44×44px 后，三条横线看起来比旁边的 Logo 高了一截。测量才发现，按钮盒子已经居中，内部的 30×30px 图标仍贴着左上角，垂直中心相差约 7px。
最后只需要让按钮内部也居中：
@media (max-width: 996px) {
.navbar__toggle {
display: flex;
align-items: center;
justify-content: center;
min-width: 44px;
min-height: 44px;
}
}
这类问题在静态规则扫描中未必会被指出。看清实际页面，再检查元素尺寸和计算样式，比凭感觉加一个偏移量更可靠。
阅读体验也包括字体和加载成本
中英文混排最后采用了不同分工：英文正文和数字使用 Source Sans 3，中文正文使用 Noto Sans SC，诗词与部分展示标题使用 Noto Serif SC，代码使用 JetBrains Mono。字体托管在站内，继续保留系统字体回退。
我没有把正文统一换成仿宋。这个站点里有很多命令、路径、表格和中英文混排，正文优先保持易扫读；书卷感主要留给首页与诗词。这个选择服务于我的阅读习惯，不是对某种字体下结论。
字体本地化之后，还要检查实际下载量。优化时一次首页冷缓存采样中，字体资源下载量约从 2.45 MB 降到 0.60 MB：首页常见字符使用较小分片，未覆盖的字符仍回退到完整字库，避免新增文章后丢字。字体文件独立缓存，也不再把小分片内嵌进关键 CSS。
搜索索引则从约 5.95 MB 的 JSON 压缩到约 1.54 MB，在 Worker 中下载、解压和检索。这些数字记录的是当时页面内容与构建产物的资源体积；首页诗词、最新文章和缓存状态变化后，请求量也会变化，不能直接换算成固定的加载速度提升。
相关实现已提交到这次 Wiki 审计修复，字体来源与维护方式记录在仓库字体说明。
我会继续使用的工作顺序
下一次优化已有页面，我会从一次小范围审查开始：
$impeccable audit 搜索和阅读页
请先列出问题与复现步骤，按影响排序，暂不修改代码。
重点检查明暗主题、小屏幕、键盘操作和失败恢复。
区分已经复现的问题与需要进一步确认的风险。
确认清单后，再按问题选择 harden、adapt、typeset 或 optimize。修改完成时，用 polish 检查整条使用路径，并要求交付时说明改了什么、怎么验证、还没覆盖哪些环境。
每次只处理明确的一组问题，保留可回退的提交。涉及配色和 Logo 时先比较方向，方向确定后再收敛细节；涉及搜索、布局和性能时，用复现步骤与检查结果验收。这样既能保留个人偏好，也能避免在“再改得好看一点”里反复打转。
用下来，我愿意继续把 Impeccable 放在这个 Wiki 的维护流程里。它让设计讨论更具体，也促使我把注意力从截图移到真实使用过程。页面是否顺手，最后仍要靠自己输入一次关键词、打开一篇笔记、读完一段命令来判断。