impeccable 命令路由指南：用信号驱动的上下文感知菜单精准选择下一个设计命令

impeccable 命令路由指南：用信号驱动的上下文感知菜单精准选择下一个设计命令

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

导读

本文基于 impeccable 的 routing.md 路由规范，深入讲解当用户仅输入/impeccable（无参数）时，Agent 应如何把"你应该做什么"这个问题，从一份静态菜单升级为基于项目实时信号的上下文感知推荐。你将掌握impeccable context与impeccable signals的前置流程、五组决策信号的完整 JSON 字段与判定规则、detect本地扫描结果的融合方式，以及"2-3 个精准建议 + 全量菜单兜底、永不自动执行"的交互原则——并结合仓库源码看清每条信号背后的真实实现。

路由的两大入口：工作流问题与无参数调用

/impeccable的路由行为分为两种截然不同的场景，见 SKILL.md 的 Routing 章节：

工作流问题的边界：只建议，不执行

当用户询问"我接下来该做什么"这类工作流问题时，Agent 应只给出建议而不执行任何命令；文档列出的命令菜单仅用于裸调用（bare invocations）。必要时按需查阅相关命令的 reference 以确认前置条件与作用范围，更完整的工作流指南可参考仓库内文档体系。如果用户同时明确要求执行，才跟随该请求去执行。

无参数路由：先看信号，再给建议

无参数调用的完整流程如下：

1. 前置检查：Setup 阶段已经运行过impeccable context。
2. 判断 NO_PRODUCT_MD：如果 context 输出NO_PRODUCT_MD，说明项目尚未捕获任何上下文，此时菜单要把/impeccable init作为置顶推荐（附一行理由），其余菜单项仍展示在下方——不要静默跳过 init 直接进入别的命令。
3. 读取信号：否则先运行一次.pi/skills/impeccable/scripts/impeccable signals并读取其 JSON 输出。
4. 给出推荐：以信号为依据，置顶2-3 个最高价值的下一步命令，每个都附上一行来自信号的理由，随后才是完整菜单（SKILL.md 中按类别分组的 Commands 表）。
5. 永不自动执行：推荐只是用户确认前的建议，Agent 不得擅自运行命令。

为什么有 NO_PRODUCT_MD 这个分支

NO_PRODUCT_MD不是普通日志，而是一条带指令的上下文诊断。在 context_cli.rs 中可以看到它的两种形态：

• 项目已有既有视觉实现但没有 PRODUCT.md：对init、teach、shape或任何新建 surface / 替换视觉世界的请求，必须先加载 init.md 创建 PRODUCT.md；其他窄范围细化命令可以基于代码继续而不阻塞，随后建议运行 init。
• 项目完全没有PRODUCT.md 也无既有实现：从零构建类请求必须走 init 完成人工或模拟用户访谈并写出 PRODUCT.md 后才能开始设计；对已有代码的局部命令则用代码作上下文继续，把 init 作为建议（不阻塞）。

这条指令正是 routing 规则中"NO_PRODUCT_MD → 置顶 init"决策的底层依据。

signals 信号：五个命名空间与真实 JSON 结构

impeccable signals（别名context-signals）由 signals.rs 实现，其gather_signals函数把散落在各模块的信息汇聚为一个 JSON 对象，包含五个顶层命名空间。routing.md 的每条决策规则都直接消费这些字段：

{ "setup": { "hasProduct": true, "productPath": "PRODUCT.md", "hasDesign": false, "designPath": null, "hasCode": true, "platform": "web" }, "critique": { "latest": null }, "git": { "isRepo": true, "branch": "feature/x", "base": "main", "changedFiles": ["src/hero.tsx"], "changedCount": 1 }, "devServer": { "running": false, "ports": [] }, "scan": { "targets": [], "via": null } }

各命名空间的来源与判定逻辑（均有源码支撑）：

• setup：由load_context与has_code汇总。hasDesign/hasProduct来自上下文加载结果；hasCode的实现（signals.rs）检查package.json是否存在，或src/app/pages/site/public/components/lib任一目录是否存在；platform由 PRODUCT.md 内容提取（extract_platform），可能为ios/android/adaptive等。
• critique：读取最近一次 critique 快照（跨 target 读取最新快照），归一化输出slug、score、p0、p1、timestamp、file。从未评审过则为null——这正是"从未被 critique 过的项目，默认推荐/impeccable critique <surface>"的信号来源。
• git：通过git_run包装的 git 命令获取仓库状态（signals.rs）。非仓库时isRepo=false且其余字段为空；仓库内会解析分支、比较基准（优先 upstream，其次develop/main/master等集成分支），并产出变更文件列表（最多 50 个）。
• devServer：并发探测[4321, 3000, 5173, 5174, 8080, 8000, 4200]这 7 个常见开发端口（signals.rs），任一端口可连接即running=true并列出开放的端口。
• scan：按优先级链生成可扫描目标（signals.rs）：git-changes（工作树中可扫描的 markup/style 文件，最相关）→source-dir（src/app/components/pages/public）→html（根目录index.html）→root（仅当有代码时指向.）。

决策规则：五条核心信号 + 意图分组兜底

routing.md 强调"基于信号进行推理，没有需要服从的分数"。具体规则如下：

平台边界：live 与 detect 仅限 Web

live和内置的impeccable detect仅适用于 Web 项目。若setup.platform是ios、android或adaptive，不要置顶这两者——浏览器 overlay 与 HTML 规则引擎对原生应用代码不适用。这是 routing.md 明确划出的红线。

意图分组兜底

当以上信号都不命中时，按用户意图分组给出建议：构建新东西（Build）/ 改进已有内容（Refine）/ 视觉迭代（Enhance/Iterate），并贴合当前 surface 与setup.platform定制。

融合 detect 扫描：用真实、当前的信号替代猜测

routing.md 要求：当scan.targets非空且setup.platform不是ios/android/adaptive时，运行一次：

.pi/skills/impeccable/scripts/impeccable detect --json <scan.targets 以空格连接>

--json参数在 detect 的 CLI 定义 中有明确声明（Output results as JSON），用法示例即impeccable detect --json .（见 cli.rs）。这是内置的本地文件检测器：无网络、无 npx，直接读取 HTML/CSS，因此对原生项目跳过。

scan.via告知目标的来历：git-changes（脏工作树中的 markup/style 文件，最相关）、source-dir（如src、app）、html或root。命中结果的折叠方式：

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

detect 是"真实、当前的信号，胜过猜测"。但若 detect 报错或目录树太大扫描缓慢，跳过它，改为建议用户自己运行audit；绝不让 detect 阻塞推荐。

菜单兜底：SKILL.md 的 Commands 表

完整菜单即 SKILL.md 中的 Commands 表，按类别分组，作为推荐的兜底。推荐置顶后，菜单保持可用：

• Build（构建）：shape（先规划 UX/UI）、init（捕获 PRODUCT.md）、document（从代码生成 DESIGN.md）、extract（抽取 token 与组件进设计系统）
• Evaluate（评估）：critique（启发式 UX 评分）、audit（可访问性/性能/响应式技术质量检查）
• Refine（细化）：polish（发布前最终质量关卡）、bolder、quieter、distill、harden、onboard
• Enhance（增强）：animate、colorize、typeset、layout、delight、overdrive
• Fix（修复）：clarify、adapt、optimize
• Iterate（迭代）：live（浏览器视觉变体模式）

每个命令都有对应的 reference 文档，位于 .pi/skills/impeccable/reference/ 目录下；原生的adapt/audit有.native变体。

运行机制补充：signals 与 detect 如何被调用

impeccable signals与impeccable detect都通过.pi/skills/impeccable/scripts/impeccable这个 POSIX shell 启动器调用（Windows 下用同目录的impeccable.cmd）。启动器（impeccable）遵循如下解析顺序：$IMPECCABLE_BIN环境变量 → 随脚本分发同平台的二进制 →~/.impeccable/bin/impeccable（经 engine-probe 握手校验）→ 版本固定缓存 → PATH 上的impeccable（同样先 probe 校验，防止误命中已退役的 3.x npm CLI）→ 最后才从发布渠道按版本下载并做 SHA-256 校验。整个过程不需要 Node 或任何其他运行时——这是 routing 流程可以在任意干净环境中稳定执行的前提。

交互铁律：推荐是 lede，菜单是 fallback

无论信号如何，最终输出都应克制在2-3 个针对性建议，给出用户可直接照抄的命令原文，每个附一行理由；完整菜单始终作为后备展示在下方。推荐是文章的标题（lede），菜单是兜底——而"绝不自动运行命令"是贯穿始终的红线：Agent 的任务是告诉用户该做什么、为什么，执行与否由用户确认。

小结：一条可复现的路由链路

把整条链路串起来就是：impeccable context（Setup 判定 NO_PRODUCT_MD 与否）→ 有上下文则impeccable signals取回 setup/critique/git/devServer/scan 五组信号 → 按平台与信号折叠出 2-3 个推荐（document / critique / polish / 定向 audit / live / detect 融合）→ 输出推荐 + 全量菜单，等待用户确认。这条链路完全由 routing.md 定义、由 signals.rs 提供数据、由 detect CLI 提供本地扫描佐证，从决策到执行的每个环节都可审计、可复现。

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