企业官网建设流程全解析

impeccable 无参数路由：用 context-signals 生成上下文感知命令菜单

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

当用户在 Agent 中裸敲/impeccable而不带任何子命令时，项目如何回答“我现在该做什么”？impeccable（一个让 AI harness 更懂设计的 skill 套件）并没有给出一张静态命令清单，而是通过一份名为 routing.md 的路由 playbook，结合 context-signals.mjs 收集的实时项目信号，动态生成一份“2–3 个最高价值建议 + 完整菜单兜底”的上下文感知菜单。读完本文，你将理解这套无参数路由的完整决策链：从NO_PRODUCT_MD分支、五大类信号采集，到detect.mjs深度扫描信号的融入规则，以及“只建议、绝不自动执行”的安全边界。

一、路由 playbook 的触发时机与总体原则

routing.md 开头就界定了自己的定位：

Read this when the user invokes/impeccablewith no argument. They are asking "what should I do?" Make the menu context-aware instead of static.

也就是说，它专门服务于无参数调用这一入口。这份文档由 SKILL.md 的路由规则直接挂接：

No argument:read routing.md and present its context-aware menu; never auto-run a command.

（见 SKILL.src.md 的 Routing 小节，rule:skill-routing。）两条总体原则贯穿全文：

1. 推荐是引导（lede），菜单是兜底（fallback）。Agent 应先给出 2–3 个最有价值的下一步命令，每个配一行来自信号的理由，然后再附上按类别分组的完整 Commands 表。
2. 绝不自动执行任何命令。推荐只是“等待用户确认的建议”（the recommendation is a suggestion the user confirms）。这是整个路由层的安全边界：信号再强，也只转化为措辞，不转化为执行。

二、前置分支：NO_PRODUCT_MD时的菜单引导

Setup 阶段（SKILL.md 第 1 步）已经在会话开始时运行过context.mjs。context.mjs 负责加载 PRODUCT.md、DESIGN.md、匹配的 surface brief 以及原生平台指引；当它在任何位置都找不到 PRODUCT.md时，会向 stdout 打印一条显式的NO_PRODUCT_MD:消息（见 context.mjs#L1131-L1162）。routing.md 要求 Agent 据此走第一个分支：

• 以/impeccable init作为菜单头条推荐，并用一句话说明原因（项目还没有捕获的产品上下文）；
• 仍然展示其余完整菜单，不能因为缺 PRODUCT.md 就静默跳进 init 流程（don't silently jump into init）。

值得注意的是，NO_PRODUCT_MD在实际实现中有两种措辞变体，都出现在 context.mjs#L1131-L1185：

这个区分保证了裸调用在“有代码但没上下文”的项目上不会过度打断用户——窄范围命令可以继续，init只是被置顶的建议，而不是强制门槛。

三、信号采集：context-signals.mjs的 JSON 输出

当 PRODUCT.md 存在时，routing.md 指示 Agent 运行一次：

node .agent/skills/impeccable/scripts/context-signals.mjs

并读取其 JSON。该脚本（源文件 skill/scripts/context-signals.mjs）的设计契约写在文件头注释里，非常克制：

It does NOT score or rank. The agent reasons over the raw signals… Deliberately light: no LLM calls, no detector run, no file writes. Every probe is best-effort and never throws; the output is always valid JSON.

即：不打分、不排序（推理交给 Agent 的模型能力）、无 LLM 调用（不调用 detector、不写文件）、任何探测都是尽力而为且永不抛错，输出永远是合法 JSON。入口函数 gatherSignals 组装出五组信号：

其中git.changedFiles的采集是这份信号里工程含量最高的部分。gitSignals 并不假设仓库一定有main/master：它按“最具体优先”的顺序检测 diff 基分支——先取当前分支配置的 upstream（@{u}全符号引用解析），再取develop（git-flow 仓库的功能分支通常合入 develop），再取各 remote 的默认分支 symref（origin/HEAD），最后才落到main/master惯例名；如果当前分支本身就是一条集成分支（或处于 detached HEAD），则只对工作区做 scope 提示，不做分支 diff，避免两条集成分支互相 diff 出全量差异。源码注释明确指出这段逻辑修复的是 issue #302（develop 基线上特征分支的改动对扫描目标“隐身”），并有专门测试印证：diffs a feature branch against a develop integration branch (#302)（tests/context-signals.test.mjs#L231-L250）。

四、scan.targets：detector 扫描目标的四级优先级

scan组是路由中“第二次深入”的输入。scanTargets 按固定优先级选出本地目标，scan.via字段标明来源：

源码注释解释了为什么目标永远是本地路径：URL 意味着昂贵的 Puppeteer 浏览器渲染，而被探测到的 dev-server 端口甚至可能不属于当前项目；本地 HTML 文件或源码树由无 jsdom 依赖的静态引擎扫描，成本极低。测试同样固定了这一契约：targets a local source dir (never a URL), even with a dev server up（tests/context-signals.test.mjs#L155-L162）。

五、推理规则：把信号翻译成 2–3 条建议

routing.md 的核心是一份“信号 → 命令”的推理清单，并且特意声明 “there is no score to obey”——没有任何一个数值字段是 Agent 必须机械服从的，推理本身才是路由：

1. setup.hasDesign为 false 而setup.hasCode为 true → 推荐document（为既有代码捕获视觉系统，生成 DESIGN.md）。
2. critique.latest为null→ 项目从未被 critique 过；对已有真实 surface 的 setup 完整项目，提供/impeccable critique <surface>是一个强默认推荐。
3. critique.latest的score偏低或p0/p1非零 → 推荐polish（polish 会把那份快照当作自己的 backlog 来读取和消化）；若快照看起来已经过期，则建议重跑critique。
4. git.changedFiles指向某一个 surface → 把audit或polish的 scope 精确限定到这些文件，并在措辞中点名这些文件。这正是“脏树优先”信号的产品意义：用户此刻正在改什么，就围绕什么给建议。
5. devServer.running为 true →live可用于浏览器内迭代；为 false 时不要用live领衔。并且live与打包的detect.mjs都是 web-only：若setup.platform是ios、android或adaptive，两者都不要领衔——浏览器 overlay 与 HTML 规则引擎对原生 App 代码不适用。
6. 以上都不命中时，按意图分组（build new / improve what's there / iterate visually），并结合当前 surface 与setup.platform做定制。

这套推理与 SKILL.md 的完整 Commands 表（即“完整菜单”）一一对应。按类别分组的菜单如下（源自 SKILL.src.md 的 Commands 表，路由文档要求“followed by the full menu… grouped by category”）：

六、可选深入：detect.mjs的真实检测信号

在信号推理之上，routing.md 还允许一次可选的“实地取证”。条件与命令（以安装版 skill 路径表述）为：

Ifscan.targetsis non-empty andsetup.platformis notios/android/adaptive, runnode .agent/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>once

关键约束与取舍：

• 打包 detector，本地文件：detect.mjs 是一个薄壳，动态加载detector/detect-antipatterns.mjs（不存在时回退到cli/engine下的同名实现），对本地 HTML/CSS 跑规则引擎——no network, no npx；
• 命中的融入方式：大量 quality / contrast 命中 → 推audit或polish；命中某个具体的“slop 家族”→ 推对应命令，文档举例：渐变文字或 eyebrow 式眉标 →quieter/typeset，扁平或灰色调板 →colorize，“and so on”；
• 失败兜底：detect 报错或树太大太慢时，跳过它并建议用户自己跑audit；“never block the suggestion on it”——建议流程永远不能被检测拖住。

routing.md 把这一步定性为 “a real, current signal that beats guessing”（真实的、当下的信号胜过猜测），但它仍是从属于信号推理的增强项，而非必经之路。

七、输出形态与质量护栏

routing.md 的收尾两句话定义了 Agent 呈现结果的形式：

Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.

即：2–3 条带精确可敲命令的锐利建议领衔，完整菜单作兜底。结合前文，一份合格的无参数响应应包含：推荐理由逐条挂接信号字段、每条建议给出可直接输入的命令（如/impeccable polish src/pages/Checkout.tsx）、其后是完整的类别化 Commands 表——且全程不执行任何命令。

这套设计在实现层面有两条值得注意的质量护栏，都可在测试中验证（tests/context-signals.test.mjs）：

1. never-throw / always-valid-JSON 契约：每个探测各自 try/catch，git 缺失、快照 frontmatter 缺键（如p1_count: nope会被安全归一为null）、非 git 目录都不影响整体输出，保证 Agent 总能读到一份可解析的信号；
2. vendored 路径过滤（#303）：.claude/skills/...、.cursor/等 vendored AI-harness 安装文件的改动不会混入git-changes扫描目标，避免“改 harness 触发对 harness 的扫描”这类自指噪声；测试用例filters harness-dir files out of git-changes scan targets (#303)固化了这一行为。

八、小结

impeccable 的无参数路由把“该做什么”这个模糊问题拆解成一条确定性流水线：context.mjs判上下文是否就绪（NO_PRODUCT_MD分支置顶init）→context-signals.mjs产出五组轻量信号（setup / critique / git / devServer / scan）→ Agent 按六条推理规则把信号翻译成 2–3 条精确命令建议，可选地用一次本地detect.mjs --json扫描补足实证 → 完整 Commands 表兜底。全程无打分器、无 LLM 调用、无网络请求、无自动执行，推荐与执行之间始终隔着一道“用户确认”的边界。理解这套机制，也就理解了 impeccable 在“命令入口层”如何做到上下文感知而不越权。

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