whodb impeccable 技能的 typeset 工作流：一套证据驱动的排版优化方法论

• 数据库客户端
• 后端
• 前端
• CLI
• 桌面应用
• 数据可视化
• AI 应用

whodb 仓库内置了一个名为impeccable的 Agent 设计技能（.agents/skills/impeccable/），其中typeset子命令专门负责"在既有视觉身份内改进排版层次与字体使用"。本文以 typeset.md 为主体，完整拆解它的评估-设定-应用-验证四步工作流与 live-mode 参数契约，并结合仓库中的 detect.mjs 检测器、反模式规则注册表 以及 whodb 前端真实的字体资产 brand-fonts.css，说明这套方法如何落地为可执行、可复验的操作。读完本文，你将掌握一套可复制的界面排版审查流程：从角色定义、机械扫描，到字号阶、行高、度量（measure）与字体交付的逐项调优标准。

typeset 的定位：改进而非替换身份

SKILL.md 的命令表把typeset [target]归在 Enhance 类，描述为"Improve typography hierarchy and fonts"——即它是对既有界面的增强，而不是新作品：

typeset.md 开篇即给出总原则：Typography carries information, hierarchy, and voice. Improve it inside the established visual world; do not replace the identity unless the user asked to.排版承载信息、层级与声音，应在已建立的视觉世界里改进它，除非用户明确要求，否则不要替换字体身份。由此引出一条重要的路由规则：

• 如果替换字体会导致产生一套全新身份，必须改走 new-work.md 流程，并同步更新 DESIGN.md；
• 其余情况下，应保留已确认的字体族（family），只改进其使用方式。

这保证了 typeset 永远在"调参"而不是"换品牌"，与 SKILL.md 中"Refinement preserves; redesign replaces"的原则一致。

先选访客模式：同一套排版，不同的目标函数

进入评估之前，typeset 要求先按访客模式（Visitor mode）确定排版的目标函数：

• Persuade + Experience：展示型字体可以承载品牌声音。当构图需要时，使用果断的对比与响应式缩放（responsive scale）。
• Operate + Read：稳定性、可扫描性、度量（measure）优先。一个调校良好的单一字体族 + 固定的角色字号阶，往往就是正确答案。
• Native：遵循 ios.md 或 android.md 的平台规范，包括平台文本缩放与无障碍行为。

以 whodb 这类数据库客户端为例：主界面属于 Operate/Read 场景（表格、查询结果、元数据），按此模式它应偏向"单一字体族 + 固定角色阶"，而不是营销页式的大字号展示。事实上 whodb 的 DESIGN.md 中声明的类型系统正是这一取向：

fontFamily: "Hanken Grotesk, Inter, ui-sans-serif, system-ui, sans-serif" # 各角色统一 # 等宽角色： fontFamily: "JetBrains Mono, ui-monospace, SF Mono, Menlo, monospace"

DESIGN.md 还明确记录了一条易被误判的事实："Hanken Grotesk carries the UI; Bricolage Grotesque is self-hosted and available (brand-fonts.css) but not currently applied anywhere in the product UI — treat it as reserved"。这正是 typeset 评估问题"Is every family necessary?（每个字体族都是必要的吗？）"的真实案例：自我托管不等于被使用，评估必须基于渲染证据而非文件存在。

两次相互独立的评估

typeset.md 要求在执行编辑前完成两次隔离的评估：一次是人工排版评估，一次是机械扫描。当有可用的子代理工具时两者应独立执行，否则按顺序自己完成，并且不要让检测器的发现先入为主地锚定设计判断。

排版评估：六个必须用证据回答的问题

检查代表性页面与样式，每个问题都要用"文件、选择器或计算值"作答，而不是凭感觉：

1. Authority and fit（权威与契合）：哪些字体、字重、角色是既定的？它们契合产品与所选"视觉世界"吗，还是未经审视的默认值？每个字体族都是必要的吗？
2. Hierarchy（层级）：标题、正文、标签、元数据、数据五类角色能否一眼区分？相邻字号或字重是否太接近、以至于无法承担不同的工作？
3. Scale and consistency（规模与一致性）：存在刻意的角色字号阶，还是任意数值的堆砌？同一重复角色在不同屏幕与状态下是否完全一致？
4. Reading（阅读）：正文是否保持在 45–75 字符/行的舒适度量内？行高、段落节奏、对比度、字距是否针对实际的字体、宽度、语言与底色调过？
5. Stress（压力测试）：超长标题、本地化膨胀、浏览器缩放、窄容器、缺失字重、字体回退时会发生什么？
6. Delivery（交付）：是否只加载了实际使用的字体资产？回退度量、加载策略、可变字体设置是否避免了文字不可见与破坏性重排？

机械扫描：detect.mjs 与 type 作用域

第二项是机械扫描，命令即文档给出的：

node .agents/skills/impeccable/scripts/detect.mjs --json --scope type [target files or dirs]

从源码看，这条命令的落地链路很清晰：

• detect.mjs 只是一个 21 行的入口：按候选路径定位detector/detect-antipatterns.mjs后await detectCli()；
• --scope参数的合法值来自 antipatterns.mjs 中RULE_SCOPES——它由每条规则的scopes字段动态聚合而成，因此--scope type会精确过滤出声明了scopes: ['type']的规则（filterByScopes 按"至少命中一个请求 scope"保留 finding）；
• 扫描引擎还包含对 Google Fonts URL 的解析（fonts.mjs 从fonts.googleapis.com/css2?family=...中抽取并归一化字体族名），用于核对"页面实际加载的字体族"与声明的一致性。

--scope type会命中的代表规则（均取自 antipatterns.mjs，描述为原文摘录）：

文档对此的定位很克制："A clean scan is a floor, not proof of good typography."扫描干净只是地板，不是好排版的证明。检测器无法解释的动态或任意字号值仍要人工补查。两次评估完成后，先综合（synthesis）再动手，并记录"各自单独发现了什么"。

动手之前：先把类型系统声明出来

typeset.md 要求编辑前必须先陈述五件事：

• 界面需要哪些角色（roles）；
• 这些角色之间预期多大的对比；
• 阅读的度量与密度（measure and density）；
• 哪些既有字体与字重具有权威性（authoritative）；
• 是否存在性能、本地化、无障碍约束。

方法论核心是：用最少的角色和字体族让层级无可置疑。刻意组合尺寸、字重、空间与色调来表达层级，而不是"让字号一个人扛所有工作"。角色命名与 token 应描述用途而非数值——这与 whodb 的 DESIGN.md 按角色声明fontFamily的组织方式一致。

Apply：可直接执行的排版规则

文档的 Apply 一节是全套可操作标准，逐条继承如下：

• 正文底线：保持正文舒适可读且可缩放。常规 Web 正文以1rem / 16px 为底线，除非是密集角色、平台惯例或用户设置给出了正当理由。
• 度量区间：散文保持在45–75ch；行高与度量反向调节——行越宽，越需要更大的 leading。
• 暗底浅字的三维补偿：浅色文字放在深色表面时，在三个感知轴上同时补偿：略微更大的行高、略微更宽的字距、需要时升一档字重。
• 行高没有万能比：针对字体、宽度、语言与对比度调行高，而不是套一个通用比率。
• 跨屏一致：同一重复角色在不同屏幕与状态下保持完全一致。
• 启用字体特性：内容受益时启用 tabular numbers（等宽数字）、代码与标签特性——这对 whodb 这类表格/结果集产品尤为关键（数值列对齐依赖font-variant-numeric: tabular-nums）。
• 只加载用到的字体：仅加载实际使用的字体资产与字重；提供度量兼容的回退（metric-compatible fallback），避免阻塞文字渲染。
• 展示区响应空间：营销展示字体可以随可用空间变化；而密集的产品界面与阅读界面要保持空间可预测性。
• 保留平台缩放：保留浏览器缩放、用户字体设置、Dynamic Type 与平台文本缩放。
• 段落节奏二选一：以段落间距或首行缩进作为主要段落节奏；两者同时用通常会让边界被"双重标记"。

两条收尾禁令：不要让文字以牺牲可理解为代价成为装饰；没有它能独自完成的清晰角色，就不引入第二个字体族。

字体交付这一点在 whodb 前端有现成的工程范例：brand-fonts.css 以自托管可变 woff2 交付 Bricolage Grotesque、Hanken Grotesk、JetBrains Mono，每个字族按 latin / latin-ext / cyrillic / vietnamese 等脚本切分unicode-range子集，全部声明font-display: swap——这正是"只加载使用到的资产 + 避免文字不可见"两条规则的具体实现。字体文件位于 frontend/public/fonts。

Verify：用证据闭环，再跑一次扫描

验证清单（每条都要求用"渲染或源码证据"作答，禁止裸答 "yes"）：

• 主、次、正文、元数据四类角色在不读文字的情况下即可辨识；
• 长文本在相关宽度与语言下仍然舒适；
• 排版属于该产品及其既定视觉世界；
• 加载过程不产生破坏性重排或文字不可见；
• 缩放、文本缩放、焦点、对比度、窄视口路径依然可用；
• 最终的机械扫描没有无法解释的 finding。

验证后重跑一次--scope type扫描确认清零；当层级站稳后，typeset.md 将其移交$impeccable polish做收尾。

Live-mode signature params：可变字阶的参数契约

typeset.md 的最后一段约束 live 模式（浏览器内生成视觉变体）下的签名参数：

每个变体声明一个粗粒度的scale参数，并让字号阶对着var(--p-scale, 1)编写。

{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}

规则是：

• scale参数是必选基线；
• 仅当它代表真实的系统级选择时，最多加一个配对（pairing）或字重参数；
• 其余参数行为遵循 live.md 的参数契约——该契约定义了range（驱动--p-<id>CSS 变量，作者写var(--p-scale, 1)）、steps（驱动data-p-<id>属性）、toggle（同时驱动变量与属性存在性）三种 kind，以及每变体 0–4 个参数的预算。

也就是说，scale让"整体字阶放大 10%–30%"成为浏览器里一个零重新生成成本的滑块，而 CSS 侧只需对var(--p-scale, 1)做乘数计算即可接入。

小结

typeset.md 的价值在于把"排版好"这个模糊判断拆成了可执行链条：选模式 → 六问评估（以文件/选择器/计算值为证据）→ 机械扫描（--scope type规则集兜底）→ 声明系统 → 逐条 Apply 规则 → 证据化 Verify → live 模式以var(--p-scale, 1)参数化字阶。配合 detect.mjs 的可复用检测器与 whodb 前端 DESIGN.md + brand-fonts.css 的落地范式，这套流程既可作为 Agent 技能的执行手册，也可以直接当作人工界面审查的检查单使用。

• 数据库客户端
• 后端
• 前端
• CLI
• 桌面应用
• 数据可视化
• AI 应用