whodb 中 impeccable 技能的无参数路由：上下文感知菜单的设计与实现

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

whodb 仓库在.agents/skills/impeccable/目录下内置了一套名为impeccable的前端界面设计 Agent 技能，它通过$impeccable <command>提供 critique、audit、polish 等二十多个子命令。本文以 routing.md 这份“无参数路由”参考文档为主体，讲清楚当用户不带任何参数直接调用$impeccable时，技能如何采集项目信号、按规则推理、并用本地检测器预扫描，最终把一份静态命令菜单变成一份“推荐 2–3 条下一步命令”的上下文感知菜单，并给出每条推荐的精确命令与一句理由。

1. 背景：无参数调用为什么需要专门的路由文档

impeccable技能的入口定义在 SKILL.md。其 Setup 流程要求每个会话先运行一次上下文加载脚本：

node .agents/skills/impeccable/scripts/context.mjs

context.mjs负责解析并打印PRODUCT.md、DESIGN.md、匹配的表面简报（surface brief）以及原生平台指引，并带有若干指令（directive）供 Agent 分支决策。而 SKILL.md 的 Routing 一节对“无参数”这一入口做了明确约定：

No argument:read routing.md and present its context-aware menu; never auto-run a command.

也就是说，当用户输入裸$impeccable时，他实际在问的是“我接下来该做什么”。如果 Agent 只是机械地贴出一张静态命令表，体验是差强人意的；routing.md 正是为此而写的行为准则——它要求菜单必须是上下文感知的：先读懂项目现状，再给出有理由的推荐。该文档开头的定位也点明了这一点：

Read this when the user invokes$impeccablewith no argument. They are asking "what should I do?" Make the menu context-aware instead of static.

2. 无参数路由的完整流程

routing.md 把无参数路由分成两条分支，核心步骤可以概括为：

分支一：NO_PRODUCT_MD（项目尚未捕获产品上下文）。Setup 阶段运行的context.mjs如果打印了NO_PRODUCT_MD:前缀消息，说明项目中还没有PRODUCT.md。此时 Agent 应当：

• 把$impeccable init作为置顶推荐，用一行文字说明为什么（init 负责与用户共同捕获持久的产品上下文并写入PRODUCT.md，对应 reference/init.md）；
• 仍然展示下面的完整菜单，不得不声不响地直接跳进 init 流程。

NO_PRODUCT_MD并非空输出这种隐式信号，而是context.mjs在 cli() 入口 主动打印的显式文本——源码注释解释了原因：直接打印消息比依赖空输出更可靠，因为“廉价模型更容易漏掉空输出这种情况”。当hasProduct为 false 时，脚本会区分“已有既有视觉实现”（附EXISTING_VISUAL_SYSTEM等指令，允许限定范围的精修命令直接以现有代码为权威继续）与“纯绿地项目”两种文案。

分支二：已有产品上下文，走信号推理。否则，Agent 运行一次信号采集脚本并读取其 JSON 输出：

node .agents/skills/impeccable/scripts/context-signals.mjs

然后以2–3 条最高价值的下一步命令领衔回复，每条附一句从信号中提炼的理由，其后才是完整菜单（即 SKILL.md 的 Commands 表，按 Build / Evaluate / Refine / Enhance / Fix / Iterate 分类）。文档同时立了一条硬约束：

Never auto-run a command; the recommendation is a suggestion the user confirms.

推荐只是建议，执行权始终在用户手里。

3. 信号源：context-signals.mjs 的 JSON 契约

context-signals.mjs 是无参数路径专用的“上下文信号采集器”。它的头部注释明确了设计哲学，值得逐条对照源码：

• 不打分、不排序（It does NOT score or rank）：脚本只输出原始信号，由 Agent 结合 SKILL.md 命令目录自行推理。这正对应 routing.md 的一句“Reason over the signals; there is no score to obey”。
• 刻意轻量：无 LLM 调用、不运行检测器（npx impeccable detect更重且是可选路径）、不写任何文件。
• 每个探测都是 best-effort 且从不抛异常，输出恒为合法 JSON。

入口函数gatherSignals()组装出五组信号：

return { setup: { hasProduct, productPath, hasDesign, designPath, hasCode, platform }, critique: { latest: latestCritique(cwd) }, git, devServer: await devServerSignals(), scan: scanTargets(cwd, git), };

下面逐组拆解，这也是 routing.md 中所有推理规则的取值来源。

3.1setup：产品上下文与代码存在感

setup复用context.mjs导出的loadContext()，提供PRODUCT.md/DESIGN.md的解析结果（hasProduct、hasDesign、对应路径），以及两个关键字段：

• hasCode：判断“这里到底有没有代码，还是只有一些上下文文件/空仓库”。实现 检查项目根目录是否存在package.json，或存在src、app、pages、site、public、components、lib之一。
• platform：由extractPlatform()从PRODUCT.md的## Platform小节读取第一行非空内容，识别web、ios、android、adaptive四种值；同时出现ios与android的列表（如ios, android）也归一为adaptive。旧格式文件没有该小节时返回null，技能按默认的web对待。

以 whodb 仓库自身为例：根目录的 PRODUCT.md 中没有## Platform小节，因此setup.platform为null，路由按 Web 项目处理，live与本地检测器都属于可用工具集。

3.2critique.latest：最近一次评审快照

critique命令会把每次评审写成带时间戳前缀的 Markdown 快照（见 critique-storage.mjs），文件形如：

.impeccable/critique/2026-05-12T18-30-00-123Z__<slug>.md

文件名中的时间戳由nowFilenameStamp()生成（冒号替换为连字符，规避 Windows 文件名限制），因此按文件名做字典序排序即得到时间序。快照头部是一个小型 YAML frontmatter，携带分数与 P0/P1 计数；latestCritique() 取.impeccable/critique/下最新的一个，解析出结构化对象：

{ "slug": "...", "score": 24, "p0": 0, "p1": 2, "timestamp": "...", "file": ".impeccable/critique/....md" }

目录不存在或没有快照时返回null。值得注意的是polish工作流也读取最新快照作为修复 backlog——这就是 routing.md 把“低分或有 P0/P1”映射到polish的底层原因。在 whodb 仓库当前状态下，.impeccable/ 下只有design.json与live/config.json，没有critique/目录，所以critique.latest为null，按路由规则“对已配置好且有真实表面的项目，推荐$impeccable critique <surface>是一个强默认项”。

3.3git：分支与变更文件构成的范围提示

git信号用于回答“用户当前在改哪些界面”，其 gitSignals() 输出isRepo、branch、base、changedFiles（截断到前 50 个）、changedCount。变更文件有两种来源：

• 若能确定 diff 基线（base），执行git diff --name-only <baseRev>...HEAD；
• 否则回退到工作区，执行git -c core.quotepath=false status --porcelain，逐行截取前 3 个字符后的路径（重命名形如old -> new取new）。

基线检测是整个函数中逻辑最重的部分，其顺序是：分支配置的 upstream（@{u}，以完整符号 ref 解析以区分本地/远程跟踪）→ 远程默认分支 symref（origin/HEAD等）→ 约定集成名（develop、main、master）。源码注释记录了两次事故驱动的修正：硬编码main/master会让 develop 为主的仓库 diff 到错误的基线（issue #302），把整段 develop/main 分叉塞进scan.targets；而当前分支本身处于集成分支（或 detached HEAD）时，一律以工作区为范围，任何信号都不得覆盖这一决策。这些细节保证了git.changedFiles是一个“指向当前表面”的可靠范围提示，而非噪声。

3.4devServer：本地开发服务器的可用性

live命令（浏览器内实时迭代）需要本地开发服务器。devServerSignals() 对一组常见开发端口做 TCP 探测：

const COMMON_DEV_PORTS = [4321, 3000, 5173, 5174, 8080, 8000, 4200];

每个端口用net.Socket连接127.0.0.1，250ms 超时，结果按端口排序后输出{ running, ports }。running为 true 时live才进入推荐候选池；为 false 时路由规则明确要求“不要以live领衔”。

3.5scan：交给本地检测器的目标清单

scan信号决定“如果要跑一次本地反模式检测，应该扫哪里”。scanTargets() 按以下优先级输出{ targets, via }：

1. git-changes（最相关集合）：脏树中符合可扫描扩展名的文件。可扫描扩展名为.html、.htm、.css、.scss、.jsx、.tsx、.js、.ts、.vue、.svelte、.astro；同时过滤掉 vendored 路径（以.开头的隐藏目录，仅豁免.vitepress/.vuepress/.storybook，以及node_modules、dist、build、__pycache__）——源码注释指出这对应 issue #303：vendored 的 AI 工具安装物（.claude/skills/...、.cursor/、.impeccable/）不是应用源码，不应被 resurface。最多取 50 个。
2. source-dir：src、app、components、pages、public中实际存在的目录。
3. html：根目录存在index.html时指向该文件。
4. root：存在代码但没有约定源码目录时，最后兜底扫描项目根.。

函数头注释强调了两点安全边界：目标是本地路径，绝不给 URL——URL 意味着昂贵的 Puppeteer 浏览器渲染，而且探测到的端口未必属于本项目；本地 HTML/源码由无 jsdom 依赖的静态引擎扫描，成本低。该脚本本身不运行检测器，只是把目标“递”给 Agent 去跑detect.mjs。

4. 信号推理规则：从原始信号到命令推荐

routing.md 的核心是五条信号→命令映射规则，Agent 对信号“推理”而非查表：

其中最后一条规则还捆绑了平台约束：live与捆绑的detect.mjs都是 Web 专属能力；当setup.platform是ios、android或adaptive时，两者都不要领衔，因为浏览器叠加层与 HTML 规则引擎不适用于原生 App 代码。

兜底规则是：以上都不命中时，按意图分组（构建新的 / 改进现有的 / 视觉迭代），并结合当前表面与setup.platform组织推荐。

5. 本地检测器预扫描：detect.mjs 的使用时机与命中解读

规则五之外，routing.md 还定义了第二个（可选的）证据来源：

Ifscan.targetsis non-empty andsetup.platformis notios/android/adaptive, runnode .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>once.

即：scan.targets非空且平台不是原生平台时，运行一次捆绑检测器（纯本地文件扫描：无网络、不走 npx；它读取 HTML/CSS，因此原生项目应跳过）：

node .agents/skills/impeccable/scripts/detect.mjs --json src app

scan.targets各项以空格拼接作为位置参数。scan.via字段告诉你这些目标是什么来源——git-changes（脏树中的标记/样式文件，最相关的一集）、source-dir（如src、app）、html或root——Agent 应据此判断证据的针对性。

detect.mjs 本身只是一个 21 行的转发壳：按顺序寻找detector/detect-antipatterns.mjs或上层的cli/engine/detect-antipatterns.mjs，再await import()并调用其导出的detectCli()。真正的 CLI 定义在 detector/cli/main.mjs，其 help 文本给出了完整参数面：

Usage: impeccable detect [options] [file-or-dir-or-url...] Options: --json Output results as JSON --quiet In text mode, only print the final findings count --scope <name> Only report rules in the given design domain (type, layout) --viewport <WxH> Browser viewport for URL scans (default 1280x800) --no-config Do not apply project config, detector ignores, inline ignore comments, or DESIGN.md --no-design-system Do not load local DESIGN.md / .impeccable/design.json context --no-advisory Suppress advisory findings entirely

检测模式按目标自动选择：HTML 文件走静态 HTML/CSS 分析（能捕获链接的 CSS），非 HTML 文件（CSS、JSX、TSX 等）走正则模式匹配，URL 则走 Puppeteer 全浏览器渲染（自动识别http(s)://与file://）——而路由规则特意只让 Agent 传本地文件，正好落在前两种轻量路径上。检测器还会尊重 .impeccable/config.json 中的detector.ignoreRules/ignoreFiles/ignoreValues/designSystem.enabled配置以及文件内联的impeccable-disable*忽略注释；advisory 类发现单独列出、不计入失败数。

拿到命中结果后，routing.md 给出了解读与折叠规则：

• 大量质量/对比度类命中→ 推荐audit或polish；
• 某个具体的“slop 家族”命中→ 推荐对应命令，例如 gradient text（渐变文字）或 eyebrows（眉标小字）→quieter/typeset，扁平或灰暗的色板 →colorize。

文档把检测器输出评价为“一个真实的、当下的信号，胜过猜测”（a real, current signal that beats guessing），同时也给出了降级路径：如果检测器报错，或项目树太大导致变慢，就跳过它，改为建议用户自己运行audit——绝不让推荐被检测阻塞。

6. 输出契约：2–3 条点状推荐 + 完整菜单兜底

routing.md 收尾两句规定了最终回复的形态：

Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.

即：推荐控制在 2–3 条，每条给出可直接键入的精确命令（如$impeccable critique src/pages/Login.tsx）；完整菜单（SKILL.md Commands 表，按 Build / Evaluate / Refine / Enhance / Fix / Iterate 分类）保留为兜底内容，而推荐是导语。完整命令目录可回查 SKILL.md 的 Commands 表：Build 类的shape/init/document/extract，Evaluate 类的critique/audit（原生平台另有audit.native.md变体），Refine 类的polish/bolder/quieter/distill/harden/onboard，Enhance 类的animate/colorize/typeset/layout/delight/overdrive，Fix 类的clarify/adapt/optimize，以及 Iterate 类的live。

7. 小结：这套路由设计值得借鉴的三个工程取舍

把 routing.md 与其配套脚本放在一起读，可以看到一套面向 Agent 行为约束的完整设计：

1. 信号与决策分离。context-signals.mjs只采集、不判断；判断规则写在 routing.md 的文档层。这样信号采集脚本保持无状态、可单独验证，而决策策略可以随文档迭代而不碰代码。
2. 显式优于隐式，兜底优先于完美。NO_PRODUCT_MD是显式文本而非空输出；基线 diff 检测失败时回退到工作区状态；检测器失败时回退到“建议用户手动audit”。每条链路都有不阻塞用户的退路。
3. 本地化与边界意识。所有探测（文件存在性、git、端口、本地静态检测）都不出项目边界，detect.mjs明确拒绝 URL 目标以规避 Puppeteer 渲染成本；changedFiles截断 50 条、快照取最新一个，保证推荐流程的响应是 O(1) 量级的。

对在本仓库内使用impeccable技能的开发者而言，实际操作路径也很直接：在技能所在项目根目录运行 context-signals.mjs 查看当前信号快照，对照本文第 4 节的映射表理解每条推荐的由来，再在需要时手动运行detect.mjs --json <targets>获取本地反模式命中。推荐永远只是建议——按 SKILL.md 的路由约束，任何命令都由用户确认后才执行。

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