impeccable 无参数路由指南：基于信号驱动 AI 设计 Agent 的上下文感知命令推荐-创锋一号

impeccable 无参数路由指南：基于信号驱动 AI 设计 Agent 的上下文感知命令推荐

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

导读

在 impeccable 这套面向 AI 编码助手的"设计语言"技能中，/impeccable不带任何参数被调用时，Agent 面对的是一个开放式问题——"我现在该做什么？"。routing.md 定义了此时的标准答案：不是抛出一份静态命令菜单，而是先读取项目当前的真实状态（信号），再据此给出 2～3 个最高价值的下一步命令建议。读完本文，你将掌握：impeccable signals输出的五组信号各自代表什么、每条信号到命令推荐的推理规则、impeccable detect --json如何作为"实时扫描信号"参与决策，以及推荐纪律（绝不自动执行、菜单永远兜底）背后的设计意图与源码实现。

一、routing.md 在技能体系中的位置与触发场景

impeccable 的命令路由逻辑定义在 SKILL.md 的 "Routing" 一节，它区分了三种场景：

无参数调用：用户敲下/impeccable却没有附带任何子命令或目标，此时读取 routing.md，按其中的"上下文感知菜单"逻辑推荐下一步命令，永远不要自动执行任何命令；
显式或明确隐含的命令请求：加载该命令对应的 reference 文件（原生平台加载对应原生变体），按文件执行；
工作流或命令选择类问题：读取 routing.md 的 "Workflow questions" 一节——此时只给建议、不执行命令，菜单仅用于"裸调用"（bare invocations）场景；如果用户同时要求执行，则遵循该要求。

换言之，routing.md 是技能"入口处的分流器"：它决定 Agent 在面对未指定的/impeccable时如何把模糊请求收敛为精确、可执行的行动建议。

二、前置条件：先`context`，再`signals`

routing.md 规定了一个硬性前置：会话开始时应已运行过impeccable context。这一步的作用与实现可以直接在 scripts/impeccable 启动器和 context_cli.rs 中验证：

启动器会解析平台二进制（$IMPECCABLE_BIN→ 同目录bin/<os>-<arch>/impeccable→~/.impeccable/bin/impeccable→ 版本固定缓存 → PATH），全部失败才走网络下载，且下载必须通过.sha256校验（"fail closed"）；
impeccable context读取 PRODUCT.md、DESIGN.md、surface brief 与原生平台指引，并输出一组RESOLVED_CONTEXT字段与指令（directive）。

NO_PRODUCT_MD分支：如果impeccable context报告NO_PRODUCT_MD，说明项目还没有捕获产品上下文。此时菜单的第一条推荐必须是/impeccable init（附一行原因），其余命令仍展示在下方；不要默默跳进 init 流程，init 需要用户确认。这对应于 context_cli.rs 中!ctx.has_product分支输出的NO_PRODUCT_MD/PRODUCT_INIT_REQUIRED指令——代码层面已经为 Agent 准备好了上下文缺失时的应对措辞。

三、`impeccable signals`：五组信号的结构与源码对应

项目已有上下文时，路由的第一步是运行一次：

.trae/skills/impeccable/scripts/impeccable signals

并读取其 JSON 输出（该命令在旧版本中别名context-signals）。信号的产出逻辑完整实现在 signals.rs 的gather_signals中，它返回五个顶层键：

信号组	关键字段	来源与含义
`setup`	`hasProduct`、`hasDesign`、`hasCode`、`platform`	由`load_context`与`extract_platform`计算。`hasCode`检查`package.json`或`src`/`app`/`pages`/`site`/`public`/`components`/`lib`目录是否存在（signals.rs）；`platform`从 PRODUCT.md 的`## Platform`节解析，合法值为`web`、`ios`、`android`，同时包含两者则归一为`adaptive`（context.rs）
`critique`	`latest`（含`slug`/`score`/`p0`/`p1`/`timestamp`/`file`）	跨目标读取最新的 critique 快照，来自`.impeccable/critique/`存储（signals.rs），底层是 critique_storage.rs 的`read_latest_snapshot_across_targets`——未关闭（无`closed: true`标记）且按路径排序最新的快照胜出
`git`	`isRepo`、`branch`、`base`、`changedFiles`（最多 50 个）、`changedCount`	优先用`git diff <base>...HEAD --name-only`，无 base 时退化为`git status --porcelain`（signals.rs）；base 的推导会依次尝试 upstream、develop、远程头、main/master
`devServer`	`running`、`ports`	并发探测 7 个常见开发端口`[4321, 3000, 5173, 5174, 8080, 8000, 4200]`上的 TCP 连接（signals.rs）
`scan`	`targets`、`via`	可扫描目标及其来源（详见下文第五节）

路由规则强调：对信号做推理，而不是机械执行某个分数（"Reason over the signals; there is no score to obey"）。

四、信号 → 推荐的推理规则

routing.md 给出了从信号到推荐命令的完整决策表，这是无参数路由的核心：

信号状态	推荐	理由
`setup.hasDesign`为 false 且`setup.hasCode`为 true	`document`	项目有代码但没记录视觉系统，先把视觉系统沉淀进 DESIGN.md
`critique.latest`为 null	`critique <surface>`	项目从未被评审过；对已 setup 且有真实界面的项目，这是强默认项
`critique.latest`分数低，或`p0`/`p1`非零	`polish`	polish 会把该快照当作自己的积压清单，并在快照过期或被清除时关闭它
`git.changedFiles`指向某一个 surface	将`audit`或`polish`限定到这些文件，并逐一命名	变更即关注点，避免全量扫描
`devServer.running`为 true	可推荐`live`（浏览器内迭代）	反之则不要用 live 打头
`setup.platform`为`ios`/`android`/`adaptive`	两者都不推荐	`live`与内置`impeccable detect`仅限 Web；浏览器 overlay 与 HTML 规则引擎不适用于原生应用代码
其他情况	按意图分组	构建新东西 / 改进现有东西 / 视觉迭代，贴合当前 surface 与`setup.platform`

关于critique.latest信号有一个值得注意的实现细节：read_latest_snapshot_across_targets会过滤掉带closed: true标记的快照（即被 polish 关闭过的快照不再作为"待办信号"出现），这正是"polish 读取快照作为积压清单并在完成时关闭它"这一闭环的存储层支撑。

五、实时信号：`impeccable detect --json`的折叠逻辑

这是路由文档最有分量的一个增强信号：当scan.targets非空且setup.platform不是ios/android/adaptive时，运行一次：

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

该检测器是捆绑在技能中的本地实现——无网络、无 npx，直接读取 HTML/CSS 文件，因此对原生项目应跳过。scan.via字段告诉 Agent 这些 target 是怎么来的：

git-changes：工作区脏树中的标记/样式文件，是最相关的集合；
source-dir：例如src、app等源码目录；
html：index.html；
root：项目根目录。

这个推导逻辑实现在 signals.rs 的scan_targets：优先 git 变更（按SCANNABLE_EXT过滤.html/.css/.jsx/.tsx/.vue/.svelte/.astro等 11 种扩展名、剔除node_modules/dist/build/隐藏目录等 vendored 路径），其次源码目录，再次index.html，最后才退到根目录。

把扫描命中折叠进推荐：

大量质量 / 对比度命中 →audit或polish；
特定 slop 家族（低质生成痕迹）→ 对应命令：渐变文字或 eyebrow（眉标文字）→quieter/typeset；扁平或灰色调色板 →colorize；以此类推。

detect是一个"真实的、当前的信号，胜过猜测"（"It's a real, current signal that beats guessing"）。detect/cli.rs 的用法说明佐证了其能力边界：支持--json、--scope、--viewport、--no-config、--no-inline-ignores、--no-design-system、--no-advisory等选项；HTML 文件走静态 HTML/CSS 分析，非 HTML 文件走正则匹配，URL 走完整浏览器渲染；退出码0为干净、1为有目标无法扫描、2为有主要发现。advisory 类发现单独分区列出、不计入失败数，--no-advisory可隐藏它们。

失败降级：如果 detect 报错或代码树过大、扫描缓慢，跳过它并建议用户自行运行audit——绝不让 detect 阻塞推荐本身。

六、推荐纪律与输出格式

routing.md 对推荐的"形状"提出了三条硬要求：

2～3 个精挑细选的推荐，每个带一行从信号推导出的理由，并给出可直接敲入的精确命令（包含 surface 路径与参数，如/impeccable critique src/pages/index.astro）；
绝不自动运行命令——推荐只是建议，必须由用户确认；
菜单永远是后备（"The menu stays the fallback; the recommendation is the lede"）。菜单即 SKILL.md 中的 Commands 表，按 Build / Evaluate / Refine / Enhance / Fix / Iterate 分类组织。

这与 SKILL.md "Routing" 一节的措辞一致：Never auto-run a command。推荐的语义是"引导用户确认"，而不是替用户做决定。

七、完整会话演练：无参数`/impeccable`的一次路由

把上述规则串成一个端到端示例（以 Linux/macOS shell 为例；Windows 下用 scripts/impeccable.cmd）：

# 1. 会话开始时加载上下文（保持 cwd 在用户项目下） .trae/skills/impeccable/scripts/impeccable context # 若输出 NO_PRODUCT_MD → 菜单第一条推荐 /impeccable init # 2. 项目已有上下文，读取信号 .trae/skills/impeccable/scripts/impeccable signals

假设返回的 JSON 摘要为：

{ "setup": { "hasProduct": true, "hasDesign": true, "hasCode": true, "platform": "web" }, "critique": { "latest": { "slug": "landing", "score": 24, "p0": 0, "p1": 3 } }, "git": { "changedFiles": ["src/pages/landing.astro"], "changedCount": 1 }, "devServer": { "running": true, "ports": [4321] }, "scan": { "targets": ["src/pages/landing.astro"], "via": "git-changes" } }

Agent 的推理过程：

critique.latest.score为 24（低分）且p1为 3 → 首个推荐polish src/pages/landing.astro，它直接消费该快照作为积压清单；
git.changedFiles恰指向 landing 这一个 surface → 第二个推荐把audit限定到src/pages/landing.astro；
运行impeccable detect --json src/pages/landing.astro后若命中大量对比度问题 → 强化 audit/polish 推荐；若命中渐变文字 → 改推quieter或typeset；
devServer.running为 true 且平台是 web → 可在推荐中顺带提示live可用于浏览器内迭代，但不必打头。

最终输出形态：2～3 条推荐 + 各自一行理由 + 精确命令，随后是完整菜单作为后备。用户确认后，Agent 才加载对应命令的 reference 文件开始执行。

八、进一步阅读

命令全表与各类别定义：SKILL.md（Routing 一节）
信号采集的完整实现：signals.rs（gather_signals/scan_targets/dev_server_signals/git_signals）
上下文加载与NO_PRODUCT_MD指令的产出：context_cli.rs
critique 快照的读取、关闭与跨目标最新快照逻辑：critique_storage.rs
impeccable detect --json的用法、退出码与内联忽略语法：detect/cli.rs
critique 的完整流程（快照如何被 polish 消费）：critique.md
启动器的二进制解析、探测与校验下载逻辑：scripts/impeccable

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析