whodb 中 impeccable 技能的无参数路由：上下文感知菜单的设计与实现

数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载whodb 仓库在.agents/skills/impeccable/目录下内置了一套名为impeccable的前端界面设计 Agent 技能它通过$impeccable command提供 critique、audit、polish 等二十多个子命令。本文以 routing.md 这份“无参数路由”参考文档为主体讲清楚当用户不带任何参数直接调用$impeccable时技能如何采集项目信号、按规则推理、并用本地检测器预扫描最终把一份静态命令菜单变成一份“推荐 2–3 条下一步命令”的上下文感知菜单并给出每条推荐的精确命令与一句理由。1. 背景无参数调用为什么需要专门的路由文档impeccable技能的入口定义在 SKILL.md。其 Setup 流程要求每个会话先运行一次上下文加载脚本node .agents/skills/impeccable/scripts/context.mjscontext.mjs负责解析并打印PRODUCT.md、DESIGN.md、匹配的表面简报surface brief以及原生平台指引并带有若干指令directive供 Agent 分支决策。而 SKILL.md 的 Routing 一节对“无参数”这一入口做了明确约定No argument:read routing.md and present its context-aware menu; never auto-run a command.也就是说当用户输入裸$impeccable时他实际在问的是“我接下来该做什么”。如果 Agent 只是机械地贴出一张静态命令表体验是差强人意的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.2. 无参数路由的完整流程routing.md 把无参数路由分成两条分支核心步骤可以概括为分支一NO_PRODUCT_MD项目尚未捕获产品上下文。Setup 阶段运行的context.mjs如果打印了NO_PRODUCT_MD:前缀消息说明项目中还没有PRODUCT.md。此时 Agent 应当把$impeccable init作为置顶推荐用一行文字说明为什么init 负责与用户共同捕获持久的产品上下文并写入PRODUCT.md对应 reference/init.md仍然展示下面的完整菜单不得不声不响地直接跳进 init 流程。NO_PRODUCT_MD并非空输出这种隐式信号而是context.mjs在 cli() 入口 主动打印的显式文本——源码注释解释了原因直接打印消息比依赖空输出更可靠因为“廉价模型更容易漏掉空输出这种情况”。当hasProduct为 false 时脚本会区分“已有既有视觉实现”附EXISTING_VISUAL_SYSTEM等指令允许限定范围的精修命令直接以现有代码为权威继续与“纯绿地项目”两种文案。分支二已有产品上下文走信号推理。否则Agent 运行一次信号采集脚本并读取其 JSON 输出node .agents/skills/impeccable/scripts/context-signals.mjs然后以2–3 条最高价值的下一步命令领衔回复每条附一句从信号中提炼的理由其后才是完整菜单即 SKILL.md 的 Commands 表按 Build / Evaluate / Refine / Enhance / Fix / Iterate 分类。文档同时立了一条硬约束Never auto-run a command; the recommendation is a suggestion the user confirms.推荐只是建议执行权始终在用户手里。3. 信号源context-signals.mjs 的 JSON 契约context-signals.mjs 是无参数路径专用的“上下文信号采集器”。它的头部注释明确了设计哲学值得逐条对照源码不打分、不排序It does NOT score or rank脚本只输出原始信号由 Agent 结合 SKILL.md 命令目录自行推理。这正对应 routing.md 的一句“Reason over the signals; there is no score to obey”。刻意轻量无 LLM 调用、不运行检测器npx impeccable detect更重且是可选路径、不写任何文件。每个探测都是 best-effort 且从不抛异常输出恒为合法 JSON。入口函数gatherSignals()组装出五组信号return { setup: { hasProduct, productPath, hasDesign, designPath, hasCode, platform }, critique: { latest: latestCritique(cwd) }, git, devServer: await devServerSignals(), scan: scanTargets(cwd, git), };下面逐组拆解这也是 routing.md 中所有推理规则的取值来源。3.1setup产品上下文与代码存在感setup复用context.mjs导出的loadContext()提供PRODUCT.md/DESIGN.md的解析结果hasProduct、hasDesign、对应路径以及两个关键字段hasCode判断“这里到底有没有代码还是只有一些上下文文件/空仓库”。实现 检查项目根目录是否存在package.json或存在src、app、pages、site、public、components、lib之一。platform由extractPlatform()从PRODUCT.md的## Platform小节读取第一行非空内容识别web、ios、android、adaptive四种值同时出现ios与android的列表如ios, android也归一为adaptive。旧格式文件没有该小节时返回null技能按默认的web对待。以 whodb 仓库自身为例根目录的 PRODUCT.md 中没有## Platform小节因此setup.platform为null路由按 Web 项目处理live与本地检测器都属于可用工具集。3.2critique.latest最近一次评审快照critique命令会把每次评审写成带时间戳前缀的 Markdown 快照见 critique-storage.mjs文件形如.impeccable/critique/2026-05-12T18-30-00-123Z__slug.md文件名中的时间戳由nowFilenameStamp()生成冒号替换为连字符规避 Windows 文件名限制因此按文件名做字典序排序即得到时间序。快照头部是一个小型 YAML frontmatter携带分数与 P0/P1 计数latestCritique() 取.impeccable/critique/下最新的一个解析出结构化对象{ slug: ..., score: 24, p0: 0, p1: 2, timestamp: ..., file: .impeccable/critique/....md }目录不存在或没有快照时返回null。值得注意的是polish工作流也读取最新快照作为修复 backlog——这就是 routing.md 把“低分或有 P0/P1”映射到polish的底层原因。在 whodb 仓库当前状态下.impeccable/ 下只有design.json与live/config.json没有critique/目录所以critique.latest为null按路由规则“对已配置好且有真实表面的项目推荐$impeccable critique surface是一个强默认项”。3.3git分支与变更文件构成的范围提示git信号用于回答“用户当前在改哪些界面”其 gitSignals() 输出isRepo、branch、base、changedFiles截断到前 50 个、changedCount。变更文件有两种来源若能确定 diff 基线base执行git diff --name-only baseRev...HEAD否则回退到工作区执行git -c core.quotepathfalse status --porcelain逐行截取前 3 个字符后的路径重命名形如old - new取new。基线检测是整个函数中逻辑最重的部分其顺序是分支配置的 upstream{u}以完整符号 ref 解析以区分本地/远程跟踪→ 远程默认分支 symreforigin/HEAD等→ 约定集成名develop、main、master。源码注释记录了两次事故驱动的修正硬编码main/master会让 develop 为主的仓库 diff 到错误的基线issue #302把整段 develop/main 分叉塞进scan.targets而当前分支本身处于集成分支或 detached HEAD时一律以工作区为范围任何信号都不得覆盖这一决策。这些细节保证了git.changedFiles是一个“指向当前表面”的可靠范围提示而非噪声。3.4devServer本地开发服务器的可用性live命令浏览器内实时迭代需要本地开发服务器。devServerSignals() 对一组常见开发端口做 TCP 探测const COMMON_DEV_PORTS [4321, 3000, 5173, 5174, 8080, 8000, 4200];每个端口用net.Socket连接127.0.0.1250ms 超时结果按端口排序后输出{ running, ports }。running为 true 时live才进入推荐候选池为 false 时路由规则明确要求“不要以live领衔”。3.5scan交给本地检测器的目标清单scan信号决定“如果要跑一次本地反模式检测应该扫哪里”。scanTargets() 按以下优先级输出{ targets, via }git-changes最相关集合脏树中符合可扫描扩展名的文件。可扫描扩展名为.html、.htm、.css、.scss、.jsx、.tsx、.js、.ts、.vue、.svelte、.astro同时过滤掉 vendored 路径以.开头的隐藏目录仅豁免.vitepress/.vuepress/.storybook以及node_modules、dist、build、__pycache__——源码注释指出这对应 issue #303vendored 的 AI 工具安装物.claude/skills/...、.cursor/、.impeccable/不是应用源码不应被 resurface。最多取 50 个。source-dirsrc、app、components、pages、public中实际存在的目录。html根目录存在index.html时指向该文件。root存在代码但没有约定源码目录时最后兜底扫描项目根.。函数头注释强调了两点安全边界目标是本地路径绝不给 URL——URL 意味着昂贵的 Puppeteer 浏览器渲染而且探测到的端口未必属于本项目本地 HTML/源码由无 jsdom 依赖的静态引擎扫描成本低。该脚本本身不运行检测器只是把目标“递”给 Agent 去跑detect.mjs。4. 信号推理规则从原始信号到命令推荐routing.md 的核心是五条信号→命令映射规则Agent 对信号“推理”而非查表信号条件推荐命令文档给出的一行理由setup.hasDesign为 false 且setup.hasCode为 truedocument项目有代码但还没有DESIGN.md用document从现有代码生成 DESIGN.md捕获既有视觉系统critique.latest为nullcritique surface项目从未被评审过对已配置且有真实表面的项目这是一条强默认critique.latest分数低或p0/p1非零polishpolish会把该快照作为修复 backlog 读取若快照看起来陈旧则改为重跑critiquegit.changedFiles指向某一个表面audit或polish把命令限定到那些具体文件并在推荐中点名它们devServer.running为 truelive本地开发服务器在运行可做浏览器内迭代为 false 则不要以live领衔其中最后一条规则还捆绑了平台约束live与捆绑的detect.mjs都是 Web 专属能力当setup.platform是ios、android或adaptive时两者都不要领衔因为浏览器叠加层与 HTML 规则引擎不适用于原生 App 代码。兜底规则是以上都不命中时按意图分组构建新的 / 改进现有的 / 视觉迭代并结合当前表面与setup.platform组织推荐。5. 本地检测器预扫描detect.mjs 的使用时机与命中解读规则五之外routing.md 还定义了第二个可选的证据来源Ifscan.targetsis non-empty andsetup.platformis notios/android/adaptive, runnode .agents/skills/impeccable/scripts/detect.mjs --json scan.targets joined by spacesonce.即scan.targets非空且平台不是原生平台时运行一次捆绑检测器纯本地文件扫描无网络、不走 npx它读取 HTML/CSS因此原生项目应跳过node .agents/skills/impeccable/scripts/detect.mjs --json src appscan.targets各项以空格拼接作为位置参数。scan.via字段告诉你这些目标是什么来源——git-changes脏树中的标记/样式文件最相关的一集、source-dir如src、app、html或root——Agent 应据此判断证据的针对性。detect.mjs 本身只是一个 21 行的转发壳按顺序寻找detector/detect-antipatterns.mjs或上层的cli/engine/detect-antipatterns.mjs再await import()并调用其导出的detectCli()。真正的 CLI 定义在 detector/cli/main.mjs其 help 文本给出了完整参数面Usage: impeccable detect [options] [file-or-dir-or-url...] Options: --json Output results as JSON --quiet In text mode, only print the final findings count --scope name Only report rules in the given design domain (type, layout) --viewport WxH Browser viewport for URL scans (default 1280x800) --no-config Do not apply project config, detector ignores, inline ignore comments, or DESIGN.md --no-design-system Do not load local DESIGN.md / .impeccable/design.json context --no-advisory Suppress advisory findings entirely检测模式按目标自动选择HTML 文件走静态 HTML/CSS 分析能捕获链接的 CSS非 HTML 文件CSS、JSX、TSX 等走正则模式匹配URL 则走 Puppeteer 全浏览器渲染自动识别http(s)://与file://——而路由规则特意只让 Agent 传本地文件正好落在前两种轻量路径上。检测器还会尊重 .impeccable/config.json 中的detector.ignoreRules/ignoreFiles/ignoreValues/designSystem.enabled配置以及文件内联的impeccable-disable*忽略注释advisory 类发现单独列出、不计入失败数。拿到命中结果后routing.md 给出了解读与折叠规则大量质量/对比度类命中→ 推荐audit或polish某个具体的“slop 家族”命中→ 推荐对应命令例如 gradient text渐变文字或 eyebrows眉标小字→quieter/typeset扁平或灰暗的色板 →colorize。文档把检测器输出评价为“一个真实的、当下的信号胜过猜测”a real, current signal that beats guessing同时也给出了降级路径如果检测器报错或项目树太大导致变慢就跳过它改为建议用户自己运行audit——绝不让推荐被检测阻塞。6. 输出契约2–3 条点状推荐 完整菜单兜底routing.md 收尾两句规定了最终回复的形态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 critique src/pages/Login.tsx完整菜单SKILL.md Commands 表按 Build / Evaluate / Refine / Enhance / Fix / Iterate 分类保留为兜底内容而推荐是导语。完整命令目录可回查 SKILL.md 的 Commands 表Build 类的shape/init/document/extractEvaluate 类的critique/audit原生平台另有audit.native.md变体Refine 类的polish/bolder/quieter/distill/harden/onboardEnhance 类的animate/colorize/typeset/layout/delight/overdriveFix 类的clarify/adapt/optimize以及 Iterate 类的live。7. 小结这套路由设计值得借鉴的三个工程取舍把 routing.md 与其配套脚本放在一起读可以看到一套面向 Agent 行为约束的完整设计信号与决策分离。context-signals.mjs只采集、不判断判断规则写在 routing.md 的文档层。这样信号采集脚本保持无状态、可单独验证而决策策略可以随文档迭代而不碰代码。显式优于隐式兜底优先于完美。NO_PRODUCT_MD是显式文本而非空输出基线 diff 检测失败时回退到工作区状态检测器失败时回退到“建议用户手动audit”。每条链路都有不阻塞用户的退路。本地化与边界意识。所有探测文件存在性、git、端口、本地静态检测都不出项目边界detect.mjs明确拒绝 URL 目标以规避 Puppeteer 渲染成本changedFiles截断 50 条、快照取最新一个保证推荐流程的响应是 O(1) 量级的。对在本仓库内使用impeccable技能的开发者而言实际操作路径也很直接在技能所在项目根目录运行 context-signals.mjs 查看当前信号快照对照本文第 4 节的映射表理解每条推荐的由来再在需要时手动运行detect.mjs --json targets获取本地反模式命中。推荐永远只是建议——按 SKILL.md 的路由约束任何命令都由用户确认后才执行。赞分享数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载相关推荐Impeccable /impeccable 无参数路由指南基于 Signals 的上下文感知命令菜单Impeccable /impeccable 无参数路由指南基于 Signals 的上下文感知命令菜单 当用户在对话中直接输入 /impeccable 不带AI 技能前端CLIdsh-pluginimpeccable 无参数路由用 context-signals 生成上下文感知命令菜单impeccable 无参数路由用 context signals 生成上下文感知命令菜单 当用户在 Agent 中裸敲 /impeccable 而不带任何子AI 技能前端CLIdsh-pluginImpeccable 命令路由指南AI 设计 Agent 如何用上下文感知信号决策 /impeccable 无参菜单Impeccable 命令路由指南AI 设计 Agent 如何用上下文感知信号决策 /impeccable 无参菜单 本篇技术指南深入讲解 ImpeccablAI 技能前端CLIdsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考