impeccable 无参路由与上下文感知菜单：用 signals 信号驱动 Agent 的下一步设计命令推荐

impeccable 无参路由与上下文感知菜单：用 signals 信号驱动 Agent 的下一步设计命令推荐

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

导读

当你对 AI 设计助手只输入一个裸的/impeccable，它应该推荐什么命令？impeccable 的答案是：不依赖静态菜单，而是先读取项目自身的运行时信号（impeccable signals输出的 JSON），再给出 2～3 条有理由支撑的下一步建议。本文以 .qoder/skills/impeccable/reference/routing.md 为骨架，结合 signals.rs、cli.rs 等源码实现，完整讲解路由决策的触发场景、信号结构与逐条解读规则、detect 扫描的折叠策略，以及“推荐为导语、菜单为兜底”的输出纪律。读完你既能复现这套路由逻辑，也能理解每个信号在源码里是如何被采集与计算的。

一、这份参考文档在什么场景被读取

routing.md是 impeccable skill 的“命令路由”参考文件，它只服务两类触发场景，其余请求一律走 SKILL.md 中的 Routing 分支：

• Workflow questions（工作流问题）：用户询问“我该用什么命令 / 下一步做什么”这类建议型问题，此时只给建议，不执行任何命令；
• No-argument routing（无参调用）：用户直接调用/impeccable（不带任何子命令），此时 Agent 被要求不要弹出静态菜单，而是生成一个上下文感知（context-aware）的菜单：以信号为依据推荐 2～3 条高价值命令作为导语，完整命令表作为兜底。

在 SKILL.md 的 Routing 一节中，这两条路径被明确挂接：无参数时读取 routing.md 并呈现其上下文感知菜单，且绝不自动运行任何命令；显式或隐含的命令请求则加载对应命令的参考文件。

二、Workflow questions：只给建议，不执行

routing.md 对工作流问题给出的第一原则是：

Give advice without executing commands; the menu below is only for bare invocations.

具体规则如下：

1. 不执行命令：当用户只是在问“该怎么做”时，Agent 输出建议即可，菜单本身只服务于裸调用（bare invocation）；
2. 按需查阅命令参考：在给出建议前，如涉及某个命令的前提条件或适用范围，应查阅对应参考文件（如 critique.md、polish.md），而不是凭记忆回答；
3. 遵循更广的工作流指南：对于更宏观的工作流，应引导用户参考项目内的 SKILL.md 与命令表（原文此处链接到外部文档站，仓库内对应的工作流权威是 SKILL.md 的 Commands 表与 Routing 节）；
4. 用户要求执行时跟随执行：如果用户不仅提问、还要求顺手执行，则以执行为准。

这条规则的实质是“建议与执行解耦”：路由阶段只负责决策与推荐，真正的执行权永远留在用户手中。

三、无参路由：上下文感知菜单的完整工作流

当用户无参调用/impeccable时，路由流程分为明确的四步。routing.md 规定 Setup 阶段（impeccable context）已经在会话内运行过一次，因此路由阶段可以直接消费其产物。

第 1 步：判断NO_PRODUCT_MD

先看 Setup 阶段impeccable context的输出是否包含NO_PRODUCT_MD标记。该标记在 context_cli.rs 中生成，表示项目还没有被捕获过产品上下文（PRODUCT.md 缺失）：

• 有NO_PRODUCT_MD：菜单顶部必须把/impeccable init作为第一推荐，并给出一行原因（例如“项目尚未捕获产品上下文，先记录用户/品牌/原则，后续所有命令才有据可依”），其余菜单照常展示在下面；同时不要悄悄跳进 init——推荐归推荐，确认权在用户；
• 无NO_PRODUCT_MD：进入第 2 步。

值得注意的是，NO_PRODUCT_MD并不等于项目不可用。从 context_cli.rs 的指令生成逻辑看：对有存量代码但缺 PRODUCT.md 的项目，init/teach/shape及新建或替换视觉世界的请求必须先写 PRODUCT.md；而其他窄范围命令可以基于代码上下文直接推进，再把init作为后续建议提供——路由层把这条“不阻塞、只建议”的语义保持了下来。

第 2 步：运行signals并读取 JSON

对于已设置好上下文的项目，路由要求先执行一次：

.qoder/skills/impeccable/scripts/impeccable signals

然后完整读取其 JSON 输出（Windows 无 sh 的 shell 可调用.qoder/skills/impeccable/scripts/impeccable.cmd等价命令）。这条命令的底层实现位于 signals.rs：gather_signals(cwd, env)汇总五个命名空间，run()以json_pretty格式打印到 stdout，返回码 0。

从 signals.rs 的gather_signals可以还原出完整的 JSON 骨架：

{ "setup": { "hasProduct": true, "productPath": "PRODUCT.md", "hasDesign": true, "designPath": "DESIGN.md", "hasCode": true, "platform": "web" }, "critique": { "latest": { "slug": "home", "score": 72.5, "p0": 2, "p1": 5, "timestamp": "…", "file": ".impeccable/critique/…" } }, "git": { "isRepo": true, "branch": "feature/x", "base": "main", "changedFiles": ["src/pages/index.tsx"], "changedCount": 3 }, "devServer": { "running": true, "ports": [5173] }, "scan": { "targets": ["src/pages/index.tsx"], "via": "git-changes" } }

各命名空间的采集方式（均有源码依据）：

第 3 步：解析信号，选出 2～3 条高价值推荐

拿到 JSON 后，Agent 需要在每个信号上做推理，而不是机械地看某个分数。routing.md 明确写道："Reason over the signals; there is no score to obey."——信号只是证据，不是必须服从的分数。随后进入第四节逐条解读。

第 4 步：输出“导语 + 菜单”结构

最终输出必须遵守：

• 推荐是导语（the lede）：2～3 条精准的下一步建议，每条一行理由，并附可原样键入的确切命令；
• 菜单是兜底（the fallback）：完整命令表（即 SKILL.md 的 Commands 表，按类别分组）展示在推荐之后，保证用户想手动挑选时永远有完整参照；
• 绝不自动运行命令：推荐只是建议，必须由用户确认后才执行。

四、信号逐条解读：每条信号对应什么推荐

routing.md 给出了一组带明确因果的解读规则。下表将其完整收录，并补充了对应的源码依据：

其中平台字段由extract_platform从 PRODUCT.md 解析（signals.rs），因此ios/android/adaptive的判定完全取决于 init 阶段记录的平台信息。

五、detect 集成：用真实扫描信号替代猜测

这是路由层最“硬核”的一步：routing.md 要求，在满足条件时运行一次捆绑的本地检测器，把真实的扫描命中折入推荐，而不是靠猜。

触发条件

同时满足以下两条才运行：

1. scan.targets非空；
2. setup.platform不是ios/android/adaptive（detect 读取 HTML/CSS，原生项目直接跳过）。

命令形式为：

.qoder/skills/impeccable/scripts/impeccable detect --json <scan.targets 以空格连接的列表>

捆绑检测器的定位

这条命令是捆绑在 skill 目录里的本地检测器（随 skill 分发的impeccable二进制执行），因此：无网络、无 npx、不开 dev server。它的 CLI 定义在 cli.rs：--json把结果以 JSON 输出到 stdout（人类可读文本走 stderr）；支持 HTML 静态分析、非 HTML 文件正则匹配、URL 浏览器渲染三种模式；退出码 0 表示无主级发现、1 表示有目标无法扫描、2 表示存在主级发现。所以路由层用--json读取命中时，天然可以按退出码和 findings 数组做结构化判断。

scan.via：告诉你 targets 是什么

scan.targets由 signals.rs 的scan_targets按优先级推导，scan.via标注其来源，共四种：

命中如何折叠成推荐

拿到 detect 的 JSON findings 后，按“家族”（slop family）映射到具体命令：

• 大量 quality / contrast 类命中→audit或polish（技术质量与收尾）；
• 特定 slop 家族 → 对应命令：
  • 渐变文字（gradient text）或眉标/眼标（eyebrows）过度 →quieter/typeset；
  • 扁平或灰色调色板（flat / gray palette）→colorize；
  • 依此类推，命中类型与命令表一一对应。

routing.md 对此的定位是："It's a real, current signal that beats guessing."——这是真实的、当下的信号，胜过凭空猜测。

失败与降级

两条重要的容错规则：

1. detect 报错或树太大太慢→ 跳过它，直接建议用户自己运行audit；
2. 绝不让 detect 阻塞推荐：即使没有扫描结果，推荐与菜单也照常给出。

六、输出纪律：推荐是导语，菜单是兜底

routing.md 的收尾对输出格式给出了硬性约束，这也是“上下文感知菜单”区别于静态菜单的关键：

• 2～3 条精准推荐（pointed picks），每条附可以原样键入的确切命令——不是“可以考虑 audit”，而是impeccable audit src/pages/index.tsx；
• 菜单保持兜底地位：完整命令表始终展示在推荐之下（即 SKILL.md 的 Commands 表，按 Build / Evaluate / Refine / Enhance / Fix / Iterate 类别分组），保证用户随时可以自主挑选；
• 推荐永远是建议："Never auto-run a command; the recommendation is a suggestion the user confirms."——即使信号再强（例如从未 critique、p0 明显非零），Agent 也只推荐、不执行。

这一纪律与 SKILL.md 的命令体系一脉相承：路由层只负责“把用户带到正确的命令面前”，而命令的执行细节、前提条件与范围，交给对应参考文件（如 critique.md、polish.md、audit.md）去约束。

七、与 SKILL.md 命令体系的衔接

无参路由的输出会引用 SKILL.md 的完整 Commands 表作为菜单。该表共 21 条命令，按类别组织（命令与 argument-hint 均可在 command-metadata.json 中查询）：

路由推荐时从这张表中挑选，并按第四节/第五节的信号规则给出理由——因此菜单本身是静态的，推荐永远是动态的。

八、落地核查：一个完整的路由推演示例

假设impeccable signals返回如下关键信号：

• setup.hasDesign: false、setup.hasCode: true、setup.platform: "web"；
• critique.latest: null；
• git.changedFiles: ["src/pages/landing.tsx", "src/components/hero.tsx"]；
• devServer.running: true、ports: [5173]；
• scan.targets: ["src/pages/landing.tsx", "src/components/hero.tsx"]、via: "git-changes"；
• detect --json返回大量 contrast 类命中。

路由推理应得到类似结论：

1. document——有代码无 DESIGN.md，先捕获视觉系统（setup信号）；
2. critique src/pages/landing.tsx——从未评审过（critique.latest: null），且变更正集中在 landing 表面；
3. detect 的 contrast 命中叠加在已变更的 landing 上 → 把audit/polish收敛到src/pages/landing.tsx src/components/hero.tsx两个文件并点名。

由于devServer.running为 true，live可以出现在菜单的完整命令表中作为可用项，但由于已有更具体的质量信号，它不必占据 2～3 条推荐位。

九、小结

routing.md 看似只有 24 行，实际定义了 impeccable skill 一套完整的“无参路由”协议：

1. 触发边界：工作流问题只建议不执行；无参调用才进入上下文感知菜单；
2. 上下文优先：消费impeccable context的NO_PRODUCT_MD判定，缺 PRODUCT.md 时以init打头；
3. 信号驱动：impeccable signals的五个命名空间（setup / critique / git / devServer / scan）在 signals.rs 中有对应的采集实现——文件探测、git 差异、端口扫描、可扫描目标推导；
4. 真实扫描折叠：条件满足时运行捆绑的impeccable detect --json，把本地命中映射到 audit / polish / quieter / typeset / colorize 等具体命令，失败或过慢则优雅跳过、绝不阻塞；
5. 输出纪律：2～3 条可原样键入的确切命令作为导语，SKILL.md 命令表作为兜底菜单，命令执行权始终保留给用户。

对需要在其他 Agent 框架中实现“智能命令推荐”的开发者而言，这套协议本身就是一份可复用的设计样板：先收集低成本的运行时信号，再按信号语义推理出推荐，最后用静态菜单兜底——信号是证据，推荐是结论，确认权在用户。

关键文件索引

• 路由规则原文：.qoder/skills/impeccable/reference/routing.md
• Skill 总入口与 Commands 表：.qoder/skills/impeccable/SKILL.md
• signals 命令实现（JSON 采集）：crates/context/src/signals.rs
• critique 快照存储（score/p0/p1 来源）：crates/context/src/critique_storage.rs
• detect CLI（--json、退出码、模式）：crates/detect/src/cli.rs
• NO_PRODUCT_MD指令生成：crates/context/src/context_cli.rs
• 命令元数据（description / argumentHint）：.qoder/skills/impeccable/scripts/command-metadata.json
• Launcher 脚本（信号与 detect 的实际入口）：.qoder/skills/impeccable/scripts/impeccable

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