Impeccable 命令路由指南AI 设计 Agent 如何用上下文感知信号决策/impeccable无参菜单【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本篇技术指南深入讲解 Impeccable 技能包中的「命令路由」机制当用户在项目中输入一个不带任何参数与动作意图的/impeccable时AI Agent 如何借助impeccable context与impeccable signals采集的工程上下文在 20 多个设计命令中选出 2–3 个高价值推荐并给出精确可执行命令而不是机械地抛出一张静态菜单。读完本文你将掌握信号字段setup.*、critique.latest、git.changedFiles、devServer.running、scan.targets的解读规则、detect二次扫描信号的折叠策略以及 iOS / Android / adaptive 等原生平台下的豁免逻辑可以直接照着复现这套「不自动执行、推荐先行、菜单兜底」的路由决策流程。一、路由规则的适用边界什么场景该看这份文档命令路由Command guidance是 .opencode/skills/impeccable/reference/routing.md 的核心主题但它并非对所有调用都生效。文档首先划定了边界工作流类问题Workflow questions当用户问「我该用什么命令」「critique和audit有什么区别」这类问题时Agent 应当只给建议、不执行任何命令下面的菜单规则仅适用于「裸调用」bare invocation即不带参数、没有明确意图的/impeccable。必要时按需查阅相关命令参考文档reference 目录下每个命令一份 md确认前置条件与作用范围若用户同时明确要求执行则遵循用户请求。带参或意图明确的调用走 SKILL.md 中 Routing 一节的另外两条分支——显式或清晰隐含的命令请求加载对应参考文档执行一般性设计工作则按impeccable context的指令走 init → new-work 或直接对既有实现做窄幅精修。也就是说本文要展开的「上下文感知菜单」只在用户输入/impeccable且不带任何参数时激活其语义等价于用户在问「我现在该做什么」。二、路由的前置条件context 与 signals 两个数据来源路由不是拍脑袋。在进入菜单逻辑之前有两个数据源必须就位且它们的产出物直接决定了推荐的走向。1.impeccable context会话级上下文装载按照 SKILL.md 的 Setup 步骤每个会话 Agent 都要运行一次impeccable contextskill-base-dir/scripts/impeccable context在 Windows 无sh的 shell 下改用impeccable.cmd。它负责读取PRODUCT.md、DESIGN.md、匹配的 surface brief 与原生平台指导并输出装载结果。路由规则里特别关注的是它的一个失败分支如果 context 报告了NO_PRODUCT_MD说明项目尚未捕获任何产品上下文。此时菜单的榜首推荐必须是/impeccable init并附上一句话理由同时仍需把其余菜单展示出来——绝不能静默跳进 init。NO_PRODUCT_MD并非随意字符串而是引擎中的真实指令。在 crates/context/src/context_cli.rs 中可以看到它有两种形态对已有视觉实现但缺PRODUCT.md的项目引导先走init/teach/shape创建PRODUCT.md而窄幅精修类命令可先读 CSS、tokens、组件与资源继续推进随后再建议init对完全无PRODUCT.md的项目init之前禁止设计。相关文案同样出现在 crates/context/src/concept_seed.rs 的NO_PRODUCT_MD: the dice stay in the cup until product truth exists提示中——没有产品事实之前一切设计方向都是无根之木。2.impeccable signals一次性的 JSON 信号采集当 context 装载正常未报告NO_PRODUCT_MD时路由要求运行一次.opencode/skills/impeccable/scripts/impeccable signals读取其输出的 JSON并以信号为准组织推荐。这份 JSON 的生成逻辑在 crates/context/src/signals.rs 的gather_signals中顶层结构为{ setup: { hasProduct: ..., productPath: ..., hasDesign: ..., designPath: ..., hasCode: ..., platform: ... }, critique: { latest: null | {...} }, git: { isRepo: ..., branch: ..., base: ..., changedFiles: [...], changedCount: ... }, devServer: { running: true|false, ports: [...] }, scan: { targets: [...], via: git-changes|source-dir|html|root|null } }几个值得注意的实现细节均可从源码确认devServer.running靠端口探测dev_server_signals会并发尝试连接 7 个常见开发端口4321、3000、5173、5174、8080、8000、4200见 signals.rs任一端口可连通即视为有开发服务器在运行——这决定了live命令是否可用。scan.targets有四级来源scan_targetssignals.rs优先取 git 脏工作区中可扫描的标记文件扩展名限于.html/.htm/.css/.scss/.jsx/.tsx/.js/.ts/.vue/.svelte/.astro共 11 种并过滤掉 node_modules、dist、build 等 vendored 路径随后依次回退到src/app/components/pages/public等源码目录、根目录index.html、最后是整库根。命令本身由技能自带的自包含二进制执行无 Node 运行时依赖见启动器 scripts/impeccable 的注释与engine-probe握手逻辑。三、上下文感知菜单的决策树信号 → 推荐拿到 JSON 后Agent 应当「reason over the signals」文档明确强调不存在必须服从的分数there is no score to obey信号只是证据推荐由解读产生。文档给出的信号解读规则可整理为如下决策表信号条件推荐动作一句话理由setup.hasDesign false且setup.hasCode truedocument捕获既有视觉系统生成 DESIGN.mdcritique.latest nullcritique surface项目从未被评审对已 setup 且有真实 surface 的项目是强默认项critique.latest存在且score低或p0/p1非零polishpolish 会把该快照当作待办积压陈旧或清空后关闭git.changedFiles指向单个 surface将audit或polish收窄到这些文件精确点名文件避免全库扫描devServer.running true可推荐live浏览器内迭代的前提是开发服务器在跑devServer.running false不带头推荐live无服务器则 live 不可用setup.platform为ios/android/adaptive不推荐live与detect浏览器 overlay 与 HTML 规则引擎不适用于原生应用代码以上均不命中按意图分组新建 / 改进既有 / 视觉迭代结合当前 surface 与setup.platform定制三条硬性约束必须始终遵守永远不自动执行命令Never auto-run a command推荐只是建议最终由用户确认Agent 不能自作主张跑任何一条。live与内置impeccable detect都是纯 Web 能力对原生平台项目两者都不能作为牵头推荐——浏览器 overlay 与 HTML 规则引擎对原生代码毫无意义。只保留 2–3 条精准推荐且每条附上「从信号中提炼的一句话理由」与可直接输入的完整命令。四、二次信号detect --json本地扫描器文档在信号基础上还加入了一道「真实、当前、胜过猜测」的强化信号——内置检测器对本地文件的扫描.opencode/skills/impeccable/scripts/impeccable detect --json scan.targets 以空格连接它的触发条件是scan.targets非空且setup.platform不是ios/android/adaptive检测器读取 HTML/CSS原生项目应跳过。与npx或在线服务不同它是捆绑在引擎里的本地检测器无网络、无 npx、纯本地文件读取并且每个会话只跑一次避免拖慢决策。scan.via字段告诉 Agent 这些 targets 从何而来四种取值对应四种语义git-changes脏工作区中的标记/样式文件是最相关的集合优先使用source-dirsrc、app等源码目录html仅根index.htmlroot整库根目录。把命中折叠进推荐detect 的输出是「质量/对比度命中」与「slop 家族命中」两类信息路由规则要求把它们折叠进最终选择大量质量 / 对比度命中→audit或polish技术质量关特定的 slop 家族→ 对应命令渐变文字或 eyebrow眉毛式小标题→quieter/typeset扁平或灰调色板 →colorize其余类推。「它是真实、当前的信号胜过猜测」——这正是整套路由设计里最值得品味的工程取舍用一次本地扫描替代 Agent 对代码库的臆测。降级路径绝不阻塞建议detect 是可选项而非拦路虎。文档明确了两条降级规则若detect执行报错或代码树过大导致扫描缓慢跳过它直接建议用户自己运行audit无论如何不要让 detect 阻塞推荐本身——推荐照常给出detect 只是加分项。五、输出纪律2–3 条点名推荐菜单兜底路由的最后一步是输出文档给出的格式纪律值得单独提炼精简保持 2–3 条有明确指向的推荐pointed picks每条给出用户可以直接敲的精确命令如/impeccable critique landing-page而不是泛泛的「考虑做一次评审」结构推荐是「导语」the lede完整菜单是「兜底」the fallback。即先把高价值推荐放最前面随后再附上 SKILL.md 中按类别分组的完整 Commands 表不越权全程只建议确认权始终在用户手中。与这条纪律配套的命令分类体系在 SKILL.md 的 Commands 表 中共 22 个命令、6 个类别菜单按类别分组时直接引用它类别命令Buildcraft已废弃别名、shape、init、document、extractEvaluatecritique、audit含 native 变体Refinepolish、bolder、quieter、distill、harden、onboardEnhanceanimate、colorize、typeset、layout、delight、overdriveFixclarify、adapt含 native 变体、optimizeIteratelive每个命令的触发语义与参数提示在 command-metadata.json 中有更完整的描述如critique的 argumentHint 是[area (feature, page, component...)]路由推荐时可以为用户补全这些参数占位。六、原生平台豁免为什么 iOS / Android 不进 Web 命令路由规则中最容易被忽略但最严谨的一处是平台判断。setup.platform来自PRODUCT.md的产品事实提取见 signals.rs 的extract_platform调用。当其为ios、android或adaptive时不牵头推荐live浏览器 overlay 依赖 DOM 与 HMR原生代码没有对应的迭代面不牵头推荐内置detectHTML 规则引擎读的是 HTML/CSS原生控件不在其覆盖范围。这背后是 Impeccable 的技能架构中「Web 规则引擎」与「原生平台指导」的明确分界——原生项目有自己的audit.native.md、adapt.native.md参考文档见 SKILL.md 中带 native 变体的命令路由时应把用户导向这些原生变体而不是生硬套用 Web 工具链。七、从文档到源码完整证据链小结至此可以回看整条路由链路的落地证据全部位于当前仓库入口.opencode/commands/impeccable.md声明了subtask: true的 command 钩子将调用委托给impeccable技能触发 SKILL.md 的 Setup 与 Commands 流程前置装载impeccable context的NO_PRODUCT_MD分支实现在 crates/context/src/context_cli.rs是路由判断「是否带头推荐 init」的唯一依据信号采集impeccable signals的 JSON 由 crates/context/src/signals.rs 的gather_signals组装涵盖 setup / critique / git / devServer / scan 五大块扫描目标推导signals.rs 的scan_targets实现了 git-changes → source-dir → html → root 的逐级回退SCANNABLE_EXT与SOURCE_DIRS常量定义了可扫描面执行载体所有命令经 scripts/impeccable 启动器解析按IMPECCABLE_BIN→ 同级二进制 → 用户缓存 → PATH 的顺序查找引擎本地文件检测无需网络输出规范SKILL.md 的 Commands 表与 command-metadata.json 共同构成菜单的权威数据源。整套设计传递的核心工程原则可以浓缩为三句话信号驱动、而非模板驱动每个项目的推荐都源自它自己的 git 状态、评审历史与扫描命中建议不越权Agent 永远只推荐、不自动执行Web 与原生严格分界live与detect只对 Web 面生效。理解了这条路由链路就等于理解了 Impeccable 技能包如何在数十条命令中快速定位「此刻对这个项目最有价值的那件事」。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考