企业官网建设流程全解析

impeccable 无参数路由全解析：如何用 context 信号与本地检测器生成上下文感知的命令菜单

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

导读

在 impeccable 这套 AI 设计技能体系中，用户输入/impeccable（不带任何参数）时，Agent 面对的是一个开放性问题——"我现在该做什么？"。本文围绕 .hermes/skills/impeccable/reference/routing.md 展开，系统讲解 impeccable 的**命令路由（Command Routing）**机制：如何通过impeccable context与impeccable signals收集项目实时状态，如何根据 setup / critique / git / dev-server / platform / scan 六类信号做出决策，以及如何在 2-3 条高价值建议与完整命令菜单之间组织回复。读完本文，你将掌握 impeccable 技能在"无参数调用"场景下的完整决策协议，理解每一条信号背后的含义与优先级，并能将其复用到自己的 AI Agent 工具编排设计中。

路由总览：三种入口，一个原则

routing.md 开篇定义了路由的三个入口，它们共享同一条核心原则：永远不自动执行命令，推荐只是交给用户确认的建议。

在 .hermes/skills/impeccable/SKILL.md 的 Routing 一节中，这一原则被进一步细化为四层判定：无参数时读 routing.md 并展示菜单；显式或明确隐含的命令请求加载其 reference；工作流/命令选择类问题走 Workflow questions；其余情况按一般设计工作处理——缺 PRODUCT.md 的新表面走 init + new-work，既有代码的窄幅精修则直接推进并在事后建议 init，而不是阻塞在 init 上。

值得注意的是，工作流问题场景下"只给建议不执行命令"并不意味着完全空手——routing.md 明确要求 Agent按需查阅相关命令的 reference以确认前置条件与作用范围，即建议必须建立在真实命令语义之上，而不是凭记忆拼凑。

无参数调用的第一步：读取 context 输出

会话开头的impeccable context

按 SKILL.md 的 Setup 流程，每个会话开始都要运行一次：

.hermes/skills/impeccable/scripts/impeccable context

启动器脚本 .hermes/skills/impeccable/scripts/impeccable 是一个无 Node 依赖的 sh 启动器：它按IMPECCABLE_BIN→ 随行平台二进制 →~/.impeccable/bin→ 版本固定缓存 → PATH 的顺序解析引擎，最后才通过网络下载并校验 SHA-256。context子命令会加载 PRODUCT.md、DESIGN.md、对应的 surface brief 与原生平台指引，并在输出中携带一系列关键信号。

关键分歧点：NO_PRODUCT_MD

routing.md 规定，如果impeccable context报告了NO_PRODUCT_MD，说明项目尚未捕获任何产品上下文（还没有 PRODUCT.md）。此时菜单的编排规则是：

• 置顶推荐/impeccable init，并给出一行理由；
• 菜单其余部分照常展示；
• 不要静默跳进 init——init 涉及多轮访谈与产品事实确认，必须由用户明确确认。

从源码看，这一信号的产生逻辑位于 crates/context/src/context_cli.rs：当项目缺少 PRODUCT.md 时，context CLI 会区分两种情况——存在既有视觉实现（has an incumbent visual implementation）与完全从零开始。前者建议 init 记录既有系统，后者则要求先完成访谈并写入 PRODUCT.md。这解释了为何 routing.md 说"不要静默跳入 init"：init 的产物（PRODUCT.md）是后续一切命令的事实基础。

impeccable signals：读取结构化决策信号

当项目已具备上下文（无NO_PRODUCT_MD）时，无参数路由进入第二步：

.hermes/skills/impeccable/scripts/impeccable signals

运行一次并读取其 JSON 输出。这些信号是路由推荐的事实依据。routing.md 特别强调："Reason over the signals; there is no score to obey"——信号之间不存在可机械加总的分数，Agent 需要人工推理。

信号的生成实现在 crates/context/src/signals.rs：例如changedFiles在非 Git 仓库时被置为空数组（第 106-111 行），在 Git 仓库中则通过git diff收集（第 235 行，最多取前 50 个文件），hasDesign直接取自ctx.has_design（第 328 行）。也就是说，你看到的每个信号字段都对应着仓库中一段可验证的采集逻辑。

六类信号的决策规则

routing.md 给出了无参数路由的核心决策表，下面逐条展开，并补充每条信号背后的实现逻辑与命令语义。

1. setup：设计系统缺失但有代码 →document

当setup.hasDesign为 false 而setup.hasCode为 true 时，推荐/impeccable document。该命令从代码库自动抽取颜色、排版、间距、圆角与组件模式，生成遵循 Google Stitch DESIGN.md 格式的视觉设计系统文档（参见 .hermes/skills/impeccable/scripts/command-metadata.json 中document条目）。其语义是"记录既有视觉系统"，与init（捕获产品事实）和 new-work（创建新视觉世界）严格分工——.hermes/skills/impeccable/reference/init.md 明确写道 init "does not invent a visual world and does not write DESIGN.md"。

2. critique：从未评审过 →critique <surface>

当critique.latest为 null 时，说明该项目从未做过设计评审。对于一个已完成 setup、存在真实表面的项目，/impeccable critique <surface>是强默认推荐。critique 会运行两个相互隔离的评估（设计评审 + 检测器/浏览器证据），产出 Nielsen 十启发式评分表、设计特异性判定、P0-P3 优先级问题、人物角色红旗等完整报告，并将快照持久化到.impeccable/critique/（参见 .hermes/skills/impeccable/reference/critique.md）。

3. critique：低分或存在 P0/P1 →polish

当critique.latest存在但分数较低，或带有非零的p0/p1计数时，推荐/impeccable polish。polish 会把 critique 快照当作自己的积压清单（backlog）来读取：通过impeccable critique-storage latest "<target>" --json取出最近一次快照，比对文件内容指纹，处理其中的 P0/P1 问题，并在全部清空后关闭该快照（参见 .hermes/skills/impeccable/reference/polish.md）。当快照过期或被清空时，polish 的这一轮 backlog 也随之关闭。这形成了 "critique 发现 → polish 修复 → 快照关闭" 的闭环。

4. git：变更指向单一表面 → 收窄范围

当git.changedFiles指向一个具体的表面（surface）时，将audit或polish的作用域收窄到这些文件，并在推荐中明确点名。从 crates/context/src/signals.rs 的实现看，该信号还包含仓库状态判定（isRepo、branch、base分支探测），changedFiles最多截取前 50 个文件，避免超大变更集污染推荐。

5. devServer：运行中 →live可用

当devServer.running为 true 时，说明浏览器内迭代工具/impeccable live可用；若为 false，则不要用live打头。live 模式允许用户在浏览器中选中元素、选择设计动作，获得 AI 生成的 HTML+CSS 变体并经 HMR 热替换（参见 .hermes/skills/impeccable/reference/live.md）。

6. platform：web-only 边界

这是最容易踩坑的边界条件。routing.md 明确指出：

live和随附的impeccable detect仅限 Web。当setup.platform为ios、android或adaptive时，两者都不能打头推荐——浏览器覆盖层与 HTML 规则引擎不适用于原生应用代码。

audit 命令也遵循同样的平台分流：.hermes/skills/impeccable/reference/audit.md 开篇即声明"Web only"，原生平台路由到audit.native.md。而impeccable context只有在 init 写入 PRODUCT.md 后才能真正知道平台（init 完成时若记录的是原生平台，会自行加载 ios.md / android.md），这是无参数路由推荐init后不得重跑 context 的原因之一。

兜底：按意图分组

当上述信号都不构成强推荐时，按用户意图分组组织菜单：构建新东西（build new）/ 改进现有东西（improve what's there）/ 视觉迭代（iterate visually），并针对当前表面与setup.platform定制措辞。

impeccable detect：本地、实时、无网络的增量信号

routing.md 给出了无参数路由中唯一的一次额外命令执行（且是条件性的）：

若scan.targets非空且setup.platform不是 ios/android/adaptive，运行一次.hermes/skills/impeccable/scripts/impeccable detect --json <scan.targets 以空格连接>。

这里的关键特性值得展开：

• 无网络、无 npx：这是随附的本地检测器，直接在本地文件上运行，因此读的是 HTML/CSS——原生项目应跳过；
• scan.via说明目标来源：git-changes（工作区脏树中的标记/样式文件，最相关的一组）、source-dir（如src、app）、html、或root；
• 命中结果映射到命令：大量质量/对比度命中 →audit或polish；特定 slop 族（如渐变文字或 eyebrow 眉题 →quieter/typeset，扁平或灰色调色板 →colorize，以此类推）；
• 失败不阻塞：若 detect 报错或目录树过大导致缓慢，直接跳过，改为建议用户自行运行audit，永远不要让推荐被它卡住。

routing.md 的措辞是"它（detect 结果）是真实的、当前的信号，胜过猜测"——这正是该机制的设计意图：用一次本地扫描把推荐从"基于历史信号的外推"升级为"基于当前代码状态的实证"。

输出格式：精简的推荐 + 兜底菜单

无参数路由的最终输出遵守两条纪律：

1. 只给 2-3 条精准的、可照抄的命令建议——每条建议附一行从 signals 推导出的理由；菜单只是兜底（fallback），推荐才是头条（lede）；
2. 推荐的命令必须给出确切的、可输入的完整命令，例如impeccable critique src/pages/index.astro，而不是模糊的"考虑做一次评审"。

在回复结构上，这正好与 .hermes/skills/impeccable/reference/critique.md 对"报告先行、问题收尾"的硬性要求互补——无参数路由的输出同样遵循"先给结论、再给选项"的信息顺序，把完整命令菜单放在推荐之后，避免推荐被淹没。

命令菜单的语义锚点

无参数路由的"完整菜单"并非静态清单，而是 .hermes/skills/impeccable/SKILL.md 中 Commands 表按类别分组的投影。四个类别及代表命令如下（完整命令列表及描述见 .hermes/skills/impeccable/scripts/command-metadata.json）：

菜单中还需如实反映两个兼容性注记：craft是 new-work 的废弃别名（"adds nothing"）；teach是init的别名。这些语义在 .hermes/skills/impeccable/SKILL.md 的 Routing 与 Pin/Unpin 段落中均有明文。

总结：从"静态菜单"到"信号驱动的推荐"

impeccable 的无参数路由本质上是把"用户问'我该做什么'"这个模糊问题，转化为一个可证伪的决策流水线：

1. impeccable context建立项目事实基线（缺 PRODUCT.md 则路由到 init）；
2. impeccable signals产出 setup / critique / git / devServer / platform / scan 六类结构化信号；
3. 条件性的impeccable detect --json把本地文件扫描结果作为"比猜测更真实"的当前信号折入决策；
4. Agent 推理信号（而非机械打分），输出 2-3 条精确命令 + 完整菜单兜底；
5. 任何情况下不自动执行命令，把确认权留给用户。

这套设计对构建 AI 工具编排的开发者有直接的参考价值：用轻量、无网络依赖的本地信号替代猜测，用明确的平台边界防止跨领域误推荐，用"推荐 + 兜底菜单"的两层结构保证输出既聚焦又完备。深入研读 crates/context/src/signals.rs 与 crates/context/src/context_cli.rs 的源码实现，可以进一步看到每个信号字段的采集成本与边界处理——这正是一个生产级命令路由系统应有的样子。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable