企业官网建设流程全解析

Impeccable 无参数路由指南：如何用 context 与 signals 驱动上下文感知命令菜单

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

导读

当用户在 AI 编程助手中敲下{{command_prefix}}impeccable（例如/impeccable或npx impeccable）却不带任何参数时，Impeccable 需要一个明确的路由决策：是直接执行某个命令，还是给用户一份建议菜单？本指南完整讲解 Impeccable 的**无参数路由（no-argument routing）**机制——它如何通过impeccable context加载项目上下文、通过impeccable signals采集项目实时信号，再基于信号推理出 2–3 条最值得执行的命令，而不是输出一份千篇一律的静态菜单。读完本文，你将掌握这套信号驱动路由的完整决策规则、signalsJSON 的每个字段含义、detect本地扫描的接入方式，以及"建议但不代跑"的 Agent 行为边界。

一、无参数路由是什么

Impeccable 的命令行（由 skill/scripts/impeccable 启动器引导，最终落到随包分发的引擎二进制）支持大量动词：init、document、critique、audit、polish、live等。但用户有时不明确指定动词，只敲下命令本身——此时他们实际在问："我下一步该做什么？"（"what should I do?"）。

skill/reference/routing.md 定义了这类调用的处理契约：

• 只给建议，不执行命令：菜单仅用于"裸调用"（bare invocation）场景。如果用户同时要求执行，才按请求执行。
• 菜单必须上下文感知（context-aware），而非静态：同样的"无参数"，面对一个有 DESIGN.md 但从未被 critique 过的项目，与面对一个 git 工作区有一堆改动文件的项目，给出的建议应当截然不同。
• 绝不自动执行：推荐只是用户确认后的建议（suggestion），Agent 不得悄悄代跑任何命令。

这与 skill/SKILL.src.md 中的 Routing 规则完全对齐：SKILL.md中明确写着 "No argument:read routing.md and present its context-aware menu; never auto-run a command."

二、前置条件：setup 与NO_PRODUCT_MD分流

路由的第一步不是猜，而是确认项目上下文是否已被捕获。按照 skill/SKILL.src.md 的 Setup 约定，每个会话应先运行一次impeccable context（Windows 无sh环境用impeccable.cmd），它会加载PRODUCT.md、DESIGN.md、surface brief 以及适用的原生平台指南。

路由规则规定：Setup 已经运行过impeccable context。如果它的输出带有NO_PRODUCT_MD，说明项目还没有被捕获任何上下文，此时路由的处理是：

• 以/impeccable init作为菜单首位推荐（附一行理由）；
• 仍然展示其余菜单项，不要悄悄跳进 init（don't silently jump into init）。

从源码看，NO_PRODUCT_MD指令由 crates/context/src/context_cli.rs 生成，它区分两种情况：

1. 项目已有既有视觉实现（incumbent visual implementation）：init、teach、shape或任何新建 surface / 替换视觉世界的请求必须先走 reference/init.md 写出PRODUCT.md；而狭窄的细化命令（narrow refinement commands）可以读取既有 CSS、tokens、组件、资源继续工作，不阻塞，事后顺带建议init。
2. 项目没有任何代码与上下文：init/teach/shape必须完成 init 的访谈流程（真人或结构化模拟用户）并先写PRODUCT.md；init 只写产品事实，绝不写DESIGN.md。

换句话说，NO_PRODUCT_MD不是"一律先 init"，而是按"新建设计 vs 既有代码细化"分流——这正是路由第一条规则背后的实现依据。

三、信号采集：impeccable signals及其 JSON 结构

当项目已有上下文（没有NO_PRODUCT_MD）时，路由进入核心步骤：运行一次{{scripts_path}}/impeccable signals并读取其 JSON。

3.1 信号从哪里来

signals（别名context-signals）的实现在 crates/context/src/signals.rs。gather_signals函数（signals.rs）聚合五大块信号：

3.2scan.via的含义

scan块的via字段说明这些扫描目标是怎么来的，对应 signals.rs 的决策链：

• git-changes：来自 git 脏工作区的标记/样式文件——最相关的集合；
• source-dir：来自src、app等源码目录；
• html：项目根有index.html；
• root：其他有代码迹象时的回退（整个目录）。

四、信号推理规则：没有需要服从的"分数"

文档强调："Reason over the signals; there is no score to obey."——信号是推理材料，不是需要最大化/最小化的分数。逐条推理规则如下（完整继承自 skill/reference/routing.md）：

1. setup.hasDesign为 false 而setup.hasCode为 true→ 推荐document（捕获视觉系统）。此时代码是既有视觉权威，缺的只是 DESIGN.md 文档（参见 context_cli.rs 中INCUMBENT_WORLD_UNDOCUMENTED指令的逻辑：有实现但无 DESIGN.md 时，细化命令可直接用实现作为权威）。
2. critique.latest为null→ 项目从未被评审；对已 setup 且有真实 surface 的项目，/impeccable critique <surface>是强力默认项。
3. critique.latest的score偏低或p0/p1非零→ 推荐polish（它把那次快照当作自己的 backlog，快照过期或被清空后即关闭）。
4. git.changedFiles指向单一 surface→ 将audit或polish的作用域限定到这些具体文件，并在建议中点名这些文件。
5. devServer.running为 true→live可用于浏览器内迭代；为 false 则不要以live打头。注意：live与内置的impeccable detect仅限 Web。若setup.platform是ios、android或adaptive，两者都不要推荐——浏览器 overlay 与 HTML 规则引擎不适用于原生应用代码。
6. 其他情况→ 按意图分组（build new / improve what's there / iterate visually），并结合当前 surface 与setup.platform量身裁剪。

从 signals.rs 看，setup块实际输出的字段为hasProduct、productPath、hasDesign、designPath、hasCode、platform，critique块为latest（内含slug、score、p0、p1、timestamp、file），这些字段正是上述规则的输入。critique.latest为空对象而非null时，规则同样成立——它表示"尚无评审记录"。

五、接入本地检测器：impeccable detect --json

路由的最后一个数据源是实时信号：当scan.targets非空且setup.platform不是ios/android/adaptive时，先运行一次：

{{scripts_path}}/impeccable detect --json <scan.targets 以空格连接>

关键特性（文档明确说明，与 skill/scripts/impeccable 启动器"无需 Node、自带二进制"的定位一致）：

• 内置检测器针对本地文件：无网络、无 npx，直接读取 HTML/CSS；
• 因为读取 HTML/CSS，原生项目应跳过这一步；
• scan.via告诉你目标是什么：git-changes（脏树里的标记/样式文件，最相关）、source-dir、html或root。

命中结果如何折叠进推荐：

• 大量质量/对比度类命中 →audit或polish；
• 某一类具体的 slop（设计偷懒模式）家族 → 匹配的命令：渐变文字或 eyebrow（眉题小标签）→quieter/typeset；扁平或灰扑扑的调色板 →colorize，依此类推。

文档特别强调这是"真实、当下的信号，胜过猜测"（"It's a real, current signal that beats guessing"）。同时设置了失败降级：如果 detect 报错或目录树过大、扫描缓慢，跳过它，改为建议用户自行运行audit；绝不让 detect 阻塞推荐（never block the suggestion on it）。

从命令元数据（skill/scripts/command-metadata.json）看，audit生成带 P0–P3 严重级别与行动计划的有分报告，polish做上线前的收尾质量通过，quieter调低过度刺激的视觉，typeset修复字体层级，colorize为单色 UI 增加策略性色彩——这些描述与"命中家族 → 匹配命令"的折叠规则一一对应。

六、输出形态：2–3 条精准推荐 + 完整菜单兜底

路由的最终输出遵循严格格式：

1. 2–3 条精准推荐（lede）：每条附一行从信号推导出的理由，并给出可直接输入的确切命令（exact command to type）；
2. 完整菜单（fallback）：即 skill/SKILL.src.md 中 Commands 表格按类别（Build / Evaluate / Refine / Enhance / Fix / Iterate）分组的全部命令；
3. 推荐是"结论在前"，菜单兜底在后——"the recommendation is the lede"。

为什么是 2–3 条而不是一张大表？因为无参数调用时用户需要的是决策辅助，而不是被二十多个动词淹没；把信号推理收敛成少数高价值选项，是路由的核心价值。

七、与 SKILL.md 其余路由规则的衔接

无参数路由只是 Impeccable 完整路由体系的一条分支。理解它需要看到整棵决策树（skill/SKILL.src.md 的 Routing 一节）：

此外，pin/unpin（创建独立{{command_prefix}}<command>快捷方式）、hooks（管理设计检测钩子，参考 skill/reference/hooks.md）、doctor（修复项目 Impeccable 工件与版本之间的漂移，参考 skill/reference/doctor.md）都有各自独立的入口；无参数路由建议的命令应当落在上述动词集合内，并把用户引向对应 reference 文件。

八、实践要点与常见陷阱

把路由规则落到真实 Agent 会话中，有几个反复出现的实践要点：

1. 不要越权执行：无论信号多强烈，推荐 ≠ 授权。规则的措辞是 "Never auto-run a command; the recommendation is a suggestion the user confirms."
2. 不要盲信单一信号：信号要交叉推理。例如devServer.running为 true 只说明live可用，还要确认平台是 web 而非原生；critique.latest有低分才推荐polish，null则应推荐critique。
3. detect 是可丢弃的增强信号：它失败或过慢就跳过，转交audit给用户，永远不做阻塞项。
4. 平台是硬约束：ios/android/adaptive下，live与detect都不可用，推荐应转向原生适配与原生审计类命令（如adapt、audit的原生变体）。
5. 推荐要可执行：不只是说"建议做 audit"，而是给出作用域明确的完整命令，例如针对git.changedFiles点名的文件运行{{scripts_path}}/impeccable audit src/App.tsx components/Hero.tsx。

结语

Impeccable 的无参数路由把"用户没有指明方向"从一次尴尬的空白，变成一次高质量的决策辅助：impeccable context确认上下文地基，impeccable signals采集项目实时脉搏（setup / critique / git / devServer / scan 五类信号），本地detect提供文件级事实，最终收敛为 2–3 条带理由、可直接执行的具体命令，配以完整命令菜单兜底，且全程只建议、不代跑。这套机制的关键实现都可以在当前仓库中直接阅读——路由规则本体在 skill/reference/routing.md，信号聚合在 crates/context/src/signals.rs，上下文加载与指令生成在 crates/context/src/context.rs 与 crates/context/src/context_cli.rs，命令全集与描述在 skill/scripts/command-metadata.json 及 skill/SKILL.src.md。

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