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。两条总体原则贯穿全文推荐是引导lede菜单是兜底fallback。Agent 应先给出 2–3 个最有价值的下一步命令每个配一行来自信号的理由然后再附上按类别分组的完整 Commands 表。绝不自动执行任何命令。推荐只是“等待用户确认的建议”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 流程dont silently jump into init。值得注意的是NO_PRODUCT_MD在实际实现中有两种措辞变体都出现在 context.mjs#L1131-L1185变体触发条件附加指令无既有视觉实现无 PRODUCT.md且代码中未发现既有视觉实现PRODUCT_INIT_REQUIRED新构建/重设计必须先完成 init有既有视觉实现无 PRODUCT.md但hasVisualImplementation探测到 token 化样式、成体系的组件等SCOPED_EXISTING_ALLOWED窄范围精修命令可直接以现有代码为上下文继续之后再建议 init这个区分保证了裸调用在“有代码但没上下文”的项目上不会过度打断用户——窄范围命令可以继续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 组装出五组信号信号组字段含义与采集方式setuphasProduct/productPath/hasDesign/designPathPRODUCT.md / DESIGN.md 是否存在及其相对路径来自context.mjs的loadContextsetuphasCode是否存在package.json或src/app/pages/site/public/components/lib任一目录hasCodesetupplatform从 PRODUCT.md 的## Platform小节读出的web/ios/android/adaptiveios, android这类双平台写法会被归一为adaptiveextractPlatformcritiquelatest跨全部 target 的最新一条critique 快照slug/score/p0/p1/timestamp/file读取自.impeccable/critique/下按时间戳命名的 frontmatter 快照缺失时整组为nulllatestCritiquegitisRepo/branch/base/changedFiles/changedCount当前分支、diff 基分支、改动文件列表截断到 50 条与总数非 git 仓库时返回isRepo: false与空列表devServerrunning/ports探测本机127.0.0.1上的常见开发端口 [4321, 3000, 5173, 5174, 8080, 8000, 4200]COMMON_DEV_PORTS每个端口 250ms 超时只要任一端口可达即running: truescantargets/via应交给 detector 扫描的本地文件永不输出 URL及其来源见下一节其中git.changedFiles的采集是这份信号里工程含量最高的部分。gitSignals 并不假设仓库一定有main/master它按“最具体优先”的顺序检测 diff 基分支——先取当前分支配置的 upstream{u}全符号引用解析再取developgit-flow 仓库的功能分支通常合入 develop再取各 remote 的默认分支 symreforigin/HEAD最后才落到main/master惯例名如果当前分支本身就是一条集成分支或处于 detached HEAD则只对工作区做 scope 提示不做分支 diff避免两条集成分支互相 diff 出全量差异。源码注释明确指出这段逻辑修复的是 issue #302develop 基线上特征分支的改动对扫描目标“隐身”并有专门测试印证diffs a feature branch against a develop integration branch (#302)tests/context-signals.test.mjs#L231-L250。四、scan.targetsdetector 扫描目标的四级优先级scan组是路由中“第二次深入”的输入。scanTargets 按固定优先级选出本地目标scan.via字段标明来源优先级via选择逻辑1git-changes脏工作区或特征分支相对 base 的 diff中的 markup/style 文件。先用扩展名白名单过滤.html.htm.css.scss.jsx.tsx.js.ts.vue.svelte.astro再剔除 vendored 路径以.开头的目录、node_modules/dist/build等例外保留.vitepress/.vuepress/.storybook因为那里面是真 UI 源码最后校验文件仍存在。routing.md 称之为 “the markup/style files in your dirty tree, the most relevant set”2source-dir依次检查src/app/components/pages/public取存在的目录3html根目录存在index.html时指向它4root有代码但没有上述结构时回退到.detector 的 walkDir 自身会跳过node_modules/dist/build与隐藏目录源码注释解释了为什么目标永远是本地路径URL 意味着昂贵的 Puppeteer 浏览器渲染而被探测到的 dev-server 端口甚至可能不属于当前项目本地 HTML 文件或源码树由无 jsdom 依赖的静态引擎扫描成本极低。测试同样固定了这一契约targets a local source dir (never a URL), even with a dev server uptests/context-signals.test.mjs#L155-L162。五、推理规则把信号翻译成 2–3 条建议routing.md 的核心是一份“信号 → 命令”的推理清单并且特意声明 “there is no score to obey”——没有任何一个数值字段是 Agent 必须机械服从的推理本身才是路由setup.hasDesign为 false 而setup.hasCode为 true → 推荐document为既有代码捕获视觉系统生成 DESIGN.md。critique.latest为null→ 项目从未被 critique 过对已有真实 surface 的 setup 完整项目提供/impeccable critique surface是一个强默认推荐。critique.latest的score偏低或p0/p1非零 → 推荐polishpolish 会把那份快照当作自己的 backlog 来读取和消化若快照看起来已经过期则建议重跑critique。git.changedFiles指向某一个 surface → 把audit或polish的 scope 精确限定到这些文件并在措辞中点名这些文件。这正是“脏树优先”信号的产品意义用户此刻正在改什么就围绕什么给建议。devServer.running为 true →live可用于浏览器内迭代为 false 时不要用live领衔。并且live与打包的detect.mjs都是 web-only若setup.platform是ios、android或adaptive两者都不要领衔——浏览器 overlay 与 HTML 规则引擎对原生 App 代码不适用。以上都不命中时按意图分组build new / improve whats there / iterate visually并结合当前 surface 与setup.platform做定制。这套推理与 SKILL.md 的完整 Commands 表即“完整菜单”一一对应。按类别分组的菜单如下源自 SKILL.src.md 的 Commands 表路由文档要求“followed by the full menu… grouped by category”命令类别说明craft [feature]Build普通 new-work 请求的弃用别名shape [feature]Build写代码前先规划 UX/UIinitBuild将持久产品上下文捕获进 PRODUCT.mddocumentBuild从既有项目代码生成 DESIGN.mdextract [target]Build抽取可复用 token 与组件进设计系统critique [target]Evaluate带启发式打分的 UX 设计评审audit [target]Evaluate技术质量检查a11y、性能、响应式polish [target]Refine发布前的最终质量打磨bolder [target]Refine放大安全/平庸的设计quieter [target]Refine收敛激进/过度刺激的设计distill [target]Refine去繁就简剥离到本质harden [target]Refine生产就绪错误、i18n、边缘情况onboard [target]Refine首次运行流程、空状态、激活设计animate [target]Enhance添加有目的的动画与动效colorize [target]Enhance为单色 UI 添加策略性色彩typeset [target]Enhance改善字体层级与字体选择layout [target]Enhance修复间距、节奏与视觉层级delight [target]Enhance注入个性与记忆点overdrive [target]Enhance突破常规极限clarify [target]Fix改进 UX 文案、标签与错误信息adapt [target]Fix适配不同设备与屏幕尺寸optimize [target]Fix诊断并修复 UI 性能liveIterate视觉变体模式在浏览器中选取元素、生成替代方案六、可选深入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 spacesonce关键约束与取舍打包 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.mjsnever-throw / always-valid-JSON 契约每个探测各自 try/catchgit 缺失、快照 frontmatter 缺键如p1_count: nope会被安全归一为null、非 git 目录都不影响整体输出保证 Agent 总能读到一份可解析的信号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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考