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再给出 23 条有理由支撑的下一步建议。本文以 .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的菜单以信号为依据推荐 23 条高价值命令作为导语完整命令表作为兜底。在 SKILL.md 的 Routing 一节中这两条路径被明确挂接无参数时读取 routing.md 并呈现其上下文感知菜单且绝不自动运行任何命令显式或隐含的命令请求则加载对应命令的参考文件。二、Workflow questions只给建议不执行routing.md 对工作流问题给出的第一原则是Give advice without executing commands; the menu below is only for bare invocations.具体规则如下不执行命令当用户只是在问“该怎么做”时Agent 输出建议即可菜单本身只服务于裸调用bare invocation按需查阅命令参考在给出建议前如涉及某个命令的前提条件或适用范围应查阅对应参考文件如 critique.md、polish.md而不是凭记忆回答遵循更广的工作流指南对于更宏观的工作流应引导用户参考项目内的 SKILL.md 与命令表原文此处链接到外部文档站仓库内对应的工作流权威是 SKILL.md 的 Commands 表与 Routing 节用户要求执行时跟随执行如果用户不仅提问、还要求顺手执行则以执行为准。这条规则的实质是“建议与执行解耦”路由阶段只负责决策与推荐真正的执行权永远留在用户手中。三、无参路由上下文感知菜单的完整工作流当用户无参调用/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.rsgather_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 } }各命名空间的采集方式均有源码依据命名空间字段采集方式signals.rssetuphasProduct/hasDesign/hasCode/platformload_context检查 PRODUCT.md、DESIGN.md 是否存在has_code检查package.json或src/app/pages/site/public/components/lib目录之一是否存在platform由extract_platform从 PRODUCT.md 解析critiquelatestslug/score/p0/p1/timestamp/fileread_latest_snapshot_across_targets跨目标读取最新 critique 快照无快照时该字段为nullscore取total_score或scorep0/p1取p0_count/p1_count或p0/p1见 critique_storage.rsgitisRepo/branch/base/changedFiles/changedCountgit_signals依次探测仓库、上游分支、基分支changedFiles优先来自git diff --name-only base...HEAD否则回退git status --porcelain最多取 50 条非仓库时返回空集devServerrunning/portsdev_server_signals对 7 个常见开发端口[4321, 3000, 5173, 5174, 8080, 8000, 4200]做 250ms 超时的 TCP 连接探测有任一端口可连即running: truescantargets/viascan_targets按优先级推导可扫描目标详见第六节第 3 步解析信号选出 23 条高价值推荐拿到 JSON 后Agent 需要在每个信号上做推理而不是机械地看某个分数。routing.md 明确写道Reason over the signals; there is no score to obey.——信号只是证据不是必须服从的分数。随后进入第四节逐条解读。第 4 步输出“导语 菜单”结构最终输出必须遵守推荐是导语the lede23 条精准的下一步建议每条一行理由并附可原样键入的确切命令菜单是兜底the fallback完整命令表即 SKILL.md 的 Commands 表按类别分组展示在推荐之后保证用户想手动挑选时永远有完整参照绝不自动运行命令推荐只是建议必须由用户确认后才执行。四、信号逐条解读每条信号对应什么推荐routing.md 给出了一组带明确因果的解读规则。下表将其完整收录并补充了对应的源码依据信号条件推荐动作理由/依据setup.hasDesign为 false且setup.hasCode为 truedocument有代码但没捕获视觉系统先生成 DESIGN.md。document会从代码库自动提取颜色、排版、间距、圆角与组件模式见 command-metadata.jsoncritique.latest为null/impeccable critique surface项目从未被评审过对已设置好、且有真实界面的项目这是一条强默认推荐。latest为 null 意味着快照仓库里没有任何 critique 存档critique_storage.rscritique.latest存在但score低或p0/p1非零polishpolish 把该快照当作自己的待办清单backlog来读并在快照过期或被清除时关闭它git.changedFiles指向单一 surface把audit或polish收敛到这些文件并点名文件变更集是当下最相关的范围changedFiles来自 git diff/statussignals.rsdevServer.running为 truelive可用于浏览器内迭代live需要运行中的 dev server 做 HMR 热替换见 command-metadata.jsondevServer.ports给出实际端口devServer.running为 false不要以live打头无 dev server 则 live 无意义setup.platform为ios/android/adaptive不要以live或detect打头live与impeccable detect都仅限 Web浏览器覆盖层与 HTML 规则引擎不适用于原生应用代码上述规则都不命中按意图分组构建新东西 / 改进已有 / 视觉迭代分组需贴合当前 surface 与setup.platform其中平台字段由extract_platform从 PRODUCT.md 解析signals.rs因此ios/android/adaptive的判定完全取决于 init 阶段记录的平台信息。五、detect 集成用真实扫描信号替代猜测这是路由层最“硬核”的一步routing.md 要求在满足条件时运行一次捆绑的本地检测器把真实的扫描命中折入推荐而不是靠猜。触发条件同时满足以下两条才运行scan.targets非空setup.platform不是ios/android/adaptivedetect 读取 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标注其来源共四种via值含义推导逻辑git-changes工作区脏树上可扫描的标记/样式文件最相关的一组在 git 仓库且有变更时过滤changedFiles只保留扩展名属于.html/.htm/.css/.scss/.jsx/.tsx/.js/.ts/.vue/.svelte/.astro、且不在 vendored 目录node_modules、dist、build、隐藏目录等下的现存文件最多 50 个source-dir源码目录如src、app无 git 变更时按SOURCE_DIRS [src, app, components, pages, public]取存在的目录htmlindex.html无源码目录时若存在index.html则扫描它root项目根目录.有代码但无更具体目标时退化到根目录命中如何折叠成推荐拿到 detect 的 JSON findings 后按“家族”slop family映射到具体命令大量 quality / contrast 类命中→audit或polish技术质量与收尾特定 slop 家族 → 对应命令渐变文字gradient text或眉标/眼标eyebrows过度 →quieter/typeset扁平或灰色调色板flat / gray palette→colorize依此类推命中类型与命令表一一对应。routing.md 对此的定位是Its a real, current signal that beats guessing.——这是真实的、当下的信号胜过凭空猜测。失败与降级两条重要的容错规则detect 报错或树太大太慢→ 跳过它直接建议用户自己运行audit绝不让 detect 阻塞推荐即使没有扫描结果推荐与菜单也照常给出。六、输出纪律推荐是导语菜单是兜底routing.md 的收尾对输出格式给出了硬性约束这也是“上下文感知菜单”区别于静态菜单的关键23 条精准推荐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 中查询类别命令典型用途Buildcraft已废弃别名、shape、init、document、extract规划、捕获上下文、生成 DESIGN.md、抽取设计系统Evaluatecritique、auditUX 评审打分、技术质量检查Refinepolish、bolder、quieter、distill、harden、onboard收尾、增强/收敛、简化、生产化、首次体验Enhanceanimate、colorize、typeset、layout、delight、overdrive动效、配色、排版、布局、惊喜感、突破常规Fixclarify、adapt、optimizeUX 文案、跨设备适配、性能Iteratelive浏览器内视觉变体迭代路由推荐时从这张表中挑选并按第四节/第五节的信号规则给出理由——因此菜单本身是静态的推荐永远是动态的。八、落地核查一个完整的路由推演示例假设impeccable signals返回如下关键信号setup.hasDesign: false、setup.hasCode: true、setup.platform: webcritique.latest: nullgit.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-changesdetect --json返回大量 contrast 类命中。路由推理应得到类似结论document——有代码无 DESIGN.md先捕获视觉系统setup信号critique src/pages/landing.tsx——从未评审过critique.latest: null且变更正集中在 landing 表面detect 的 contrast 命中叠加在已变更的 landing 上 → 把audit/polish收敛到src/pages/landing.tsx src/components/hero.tsx两个文件并点名。由于devServer.running为 truelive可以出现在菜单的完整命令表中作为可用项但由于已有更具体的质量信号它不必占据 23 条推荐位。九、小结routing.md 看似只有 24 行实际定义了 impeccable skill 一套完整的“无参路由”协议触发边界工作流问题只建议不执行无参调用才进入上下文感知菜单上下文优先消费impeccable context的NO_PRODUCT_MD判定缺 PRODUCT.md 时以init打头信号驱动impeccable signals的五个命名空间setup / critique / git / devServer / scan在 signals.rs 中有对应的采集实现——文件探测、git 差异、端口扫描、可扫描目标推导真实扫描折叠条件满足时运行捆绑的impeccable detect --json把本地命中映射到 audit / polish / quieter / typeset / colorize 等具体命令失败或过慢则优雅跳过、绝不阻塞输出纪律23 条可原样键入的确切命令作为导语SKILL.md 命令表作为兜底菜单命令执行权始终保留给用户。对需要在其他 Agent 框架中实现“智能命令推荐”的开发者而言这套协议本身就是一份可复用的设计样板先收集低成本的运行时信号再按信号语义推理出推荐最后用静态菜单兜底——信号是证据推荐是结论确认权在用户。关键文件索引路由规则原文.qoder/skills/impeccable/reference/routing.mdSkill 总入口与 Commands 表.qoder/skills/impeccable/SKILL.mdsignals 命令实现JSON 采集crates/context/src/signals.rscritique 快照存储score/p0/p1 来源crates/context/src/critique_storage.rsdetect CLI--json、退出码、模式crates/detect/src/cli.rsNO_PRODUCT_MD指令生成crates/context/src/context_cli.rs命令元数据description / argumentHint.qoder/skills/impeccable/scripts/command-metadata.jsonLauncher 脚本信号与 detect 的实际入口.qoder/skills/impeccable/scripts/impeccable【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考