oh-my-piomp cleanseChecker Discovery 提示词机制解析从用户请求到可执行诊断命令的自动化链路【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读在 oh-my-piomp的cleanse命令中有一条「请求 → 命令 → 诊断 → 修复」的自动化链路当用户提出一个无法用内置规则自动匹配的修复请求时系统会派遣一个发现型 AgentChecker Discovery Agent让它以只读方式勘察项目并输出一份符合 JSON Schema 的检查器清单。本文以仓库中的 discovery.md 提示词为骨架结合 agent.ts、checkers.ts、parsers.ts 等源码完整讲解该提示词的约束体系、五步工作流、已知解析器Known parsers与输出 Schema并剖析它与内置 Checker 发现的异同。读完本文你将掌握omp cleanse的检查器发现机制如何工作以及如何为其扩展一个新的诊断命令。一、discovery.md 在 cleanse 流程中的位置omp cleanse的整体流程定义在 index.ts 的runCleanse中其核心是「检测项目诊断 → 派发有界修复批次 → 验证」三阶段。其中诊断来源有两种内置发现调用discoverCleanseDiagnosticSuite实现在 checkers.ts根据项目中的Cargo.toml、tsconfig.json、pyproject.toml等标记文件自动生成检查器计划提示词发现Prompted Discovery当用户通过--request传入自由文本描述或内置发现找不到可用检查器时系统把 discovery.md 渲染为结构化子代理的任务提示派遣一个CleanseDiscovery代理要求其返回符合 Schema 的checkers数组。这两条路径在 agent.ts 的discoverCheckers方法中汇合它调用runStructuredSubagent将渲染后的discoveryPrompt与DISCOVERY_SCHEMA一起交给模型再通过parseDiscoverySpecs把结构化输出转成可执行的CustomCleanseCheckerSpec[]最后交给buildCustomCleanseSuitecheckers.ts落地为可运行套件。二、提示词的三条硬性约束criticaldiscovery.md 开头用critical标签给出三条不可逾越的约束这是该提示词安全性的根基绝不修改项目文件发现阶段是只读的read-and-verify discovery only。这保证发现 Agent 与后续修复 Agent 职责分离——发现者只负责「探测与验证命令」修复者才拥有写权限。每个提出的命令必须实际运行一次Agent 不能凭空捏造命令必须真实执行并观察输出这是防止「幻觉命令」的关键防线。最终只输出一个符合 Schema 的 JSON 对象不得附带任何散文prose或代码围栏code fences确保结构化输出可直接被parseDiscoverySpecs消费。在源码侧这三条约束被进一步强化DISCOVERY_SCHEMA 规定了checkers数组的字段与类型command为字符串数组、parser限定枚举parseDiscoverySpecsagent.ts则做防御性校验label必须非空、command数组必须非空不合格条目被直接丢弃而不是抛错中断。三、五步工作流workflow详解提示词要求发现 Agent 按以下顺序行动步骤动作要点1检查清单文件扫描 manifests、configs、lockfiles、scripts定位相关工具链2确定命令与工作目录优先项目本地二进制node_modules/.bin、.venv/bin、gradlew等包装脚本其次才是全局工具3选择输出格式优先匹配下方 Known parsers 表中已知的机器可读输出否则退回 gcc 风格file:line:col: severity: message并指定generic解析器4运行一次验证确认命令可执行且输出能被所选解析器解析非零退出但输出可解析可用崩溃或用法错误不可用5按命令返回条目若多个命令共同覆盖请求每个命令返回一个条目3.1 项目本地二进制优先原则的源码印证第 2 步的「优先本地二进制」在 checkers.ts 的resolveBinary中有完整实现它会从cwd向项目根逐级向上搜索node_modules/.bin、.venv/binWindows 下为Scripts、venv/bin、vendor/bin最后才回退到PATH。例如 Rust 项目会优先用cargo本身的--message-formatjsonJVM 项目会优先使用仓库内的gradlew/mvnw包装脚本checkers.ts。3.2 「非零退出可接受」的语义第 4 步隐含了一个重要语义检查器返回非零退出码不代表发现失败——lint 工具发现问题时通常会以非零码退出但这恰恰是「有诊断」的证据。真正不可接受的是命令崩溃或用法错误usage error。这一语义在 checkers.ts 的runChecker中得到体现只有当exitCode ! 0且解析不到任何诊断时才会生成一条checkerFailureDiagnostic失败诊断。四、Known parsers已知解析器全表提示词要求发现 Agent 为每个命令选择最合适的解析器 id。完整表格如下来自 discovery.mdCLEANSE_PARSER_KINDS常量在 parsers.ts 中与此一一对应id预期输出格式rustcargo … --message-formatjsonrust-testcargo test … --message-formatjsongogo vet -jsongo-testgo test -jsonstaticcheckstaticcheck -f jsongolangcigolangci-lint 默认文本输出ruffruff check --output-formatjsonpyrightpyright/basedpyright--outputjsonmypymypy 默认文本输出pylintpylint --output-formatjsonflake8flake8 默认文本输出tyty check --output-format conciseeslinteslint --formatjsonbiomebiome check --reporterjsonoxlintunix 格式行file:line:col: message [Error/rule]--formatunixdeno-lintdeno lint --jsonstylelintstylelint --formatter jsonrubocoprubocop --format jsonphpstanphpstan analyse --error-formatjsonpsalmpsalm --output-formatjsonswiftlintswiftlint lint --reporter jsondartdart analyze --format machinecredomix credo --formatjsonshellcheckshellcheck --formatjson1hlinthlint --jsonterraformterraform validate -jsontflinttflint --formatjsonactionlintactionlint 的 JSON-format模板genericgcc 风格file:line:col: severity: message行tsc/tsgo--pretty false、mypy、clang、zig、MSVC 风格4.1 解析器在源码中的落地方式parsers.ts 的parseCleanseDiagnostics是这张表的总分发入口每个 id 对应一个专用解析函数。几个值得注意的实现细节JSON 流解析parseJsonValuesparsers.ts不仅能解析完整 JSON还能从混有噪声文本的输出中逐个提取 JSON 对象/数组这对cargo、go test这类逐行输出 JSON 的工具尤为重要位置归一化normalizeFileparsers.ts把绝对路径、file://URL、相对路径统一转为项目相对路径并丢弃指向项目外的文件severity 归一化normalizeSeverityparsers.ts把各工具不同的严重级别映射为统一的error | warning | info数字严重级别按「≥2 为 error、1 为 warning、0 为 info」折算——这与 types.ts 中的CleanseSeverity类型完全对应零基坐标修正pyright、pylint 等工具使用 0-based 行列zeroBasedparsers.ts统一加 1 转成 1-basedgeneric 回退解析parseGenericparsers.ts同时支持 gcc 风格file:line:col: severity: message与 MSVC 风格file(line,col): severity: message是提示词第 3 步所说的「最后防线」。4.2 内部调试级细节rust-test 与 go-test 的失败提取值得说明的是rust-test与go-test并非只解析 JSONparseRustTestparsers.ts还会从 stderr 正则提取thread xxx panicked at file:line:col的 panic 位置parseGoTestparsers.ts则从Output字段中提取file.go:line:col: message并标注Action: fail的测试名。这表明 Known parsers 表中的「预期输出」只是入口实际解析逻辑远比单格式更健壮。五、输出 Schema 与字段语义提示词要求最终返回恰好一个JSON 对象其 Schema 原型为{ checkers: [ { label: tsc (packages/app), language: TypeScript, cwd: packages/app, command: [tsc, --noEmit, --pretty, false], parser: generic } ] }字段规则提示词原文 源码补充commandargv 数组首元素是二进制名或项目相对路径绝不允许 shell 包装NEVER shell-wrap。这意味着不能用command: tsc --noEmit这种字符串必须拆成数组元素。在 agent.ts 的 Schema 中command被声明为minItems: 1的字符串数组checkers.ts 的buildCustomCleanseSuite会把首元素作为binary、其余作为args。cwd项目相对工作目录省略则视为项目根目录。源码在buildCustomCleanseSuite中通过normalizeCustomRootcheckers.ts校验如果cwd解析后逃逸出项目根path.relative以..开头该检查器会被判为不可用并进入skipped列表。parser已知解析器 id省略则默认generic。源码中的回退逻辑在 checkers.tsCLEANSE_PARSER_KINDS.find(kind kind spec.parser) ?? generic未知 id 一律降级为generic。label与language前者用于状态板展示如 CLI 输出的[checker] tsc (packages/app): tsc --noEmit --pretty false后者描述语言族两者在 types.ts 的CleanseCheckerDescriptor中对应label/language字段。特别地当项目中不存在能产生该诊断的任何命令时必须返回checkers: []——这对应 index.ts 中的「Checker discovery produced no runnable command」分支最终以unsupported状态退出。六、从 JSON 到可运行套件buildCustomCleanseSuite 的落地发现 Agent 输出的 specs 并不会被直接信任buildCustomCleanseSuite 会做二次校验命令非空缺command的条目进入skipped原因记为empty command工作目录合法cwd逃逸项目根的条目被丢弃原因记为working directory escapes the project可执行文件存在若binary含路径分隔符/或\按项目相对路径解析并用Bun.file(candidate).exists()验证否则调用resolveBinary按「本地优先、PATH 兜底」查找。找不到的条目进入skipped原因记为executable not found: xxx不安装任何工具这正是discoverCleanseDiagnosticSuite注释checkers.ts「Discover configured language checkers without installing missing tools」的原则——发现阶段只承认环境里真实存在的工具。通过校验的计划会获得custom-N形式的 id并被包装进统一的CleanseDiagnosticSuite从而与内置发现的检查器共享同一套run/select执行模型。七、发现阶段与执行阶段的协同约束discovery.md 虽然是给发现 Agent 的提示词但其输出会直接影响后续执行的安全边界只读与可写的隔离发现 Agent 只读真正写文件的是后续按 assignment.md 运行的修复 Worker。两者通过 loop.ts 串联成「收集 → 分组 → 派发 → 验证」循环。流式诊断的去重长时运行的检查器如cargo clippy在 checkers.ts 中每flushMs默认 5 秒按「最后一个完整换行」截断做部分解析diagnosticKeycheckers.ts保证每条诊断在流式阶段只投递一次最终解析后还会经deduplicateProjectDiagnostics全量去重排序。项目内文件过滤runChecker中inProjectcheckers.ts只保留诊断文件属于项目快照的条目排除构建产物、node_modules、.git等被忽略目录IGNORED_DIRECTORIEScheckers.ts中的噪声。变更类检查器的串行执行标记为mutates的检查器如cargo clippy --fix会先于其他并行检查器单独执行完毕且流式解析对其关闭——原因在源码注释中写得很清楚防止修复 Worker 编辑一个格式化器正在重写的文件checkers.ts。八、扩展实践如何为 omp cleanse 接入新的诊断命令结合 discovery.md 的规则与源码结构接入新命令的推荐路径有两种路径一利用提示词发现无需改代码。运行omp cleanse --request 帮我检查项目中所有未使用的导入这类自由文本请求时发现 Agent 会按五步工作流自行探测tsconfig.json、eslint.config.js等清单挑选合适的解析器例如eslint --formatjson或tsc --noEmit --pretty falsegeneric运行验证后返回规范化的checkers数组。适合临时性、非常规的检查诉求。路径二扩展内置发现需改代码。在 checkers.ts 中仿照现有discoverXxx系列函数如discoverJavaScript、discoverRust、discoverTerraform新增一个发现函数并在discoverCleanseDiagnosticSuite的调用列表checkers.ts中注册通过rootsForBasenames/rootsForPattern定位标记文件用resolveBinary解析可执行文件然后在 parsers.ts 中补充对应的解析器 id 与parseXxx函数最后把 id 加入CLEANSE_PARSER_KINDS常量并同步更新 discovery.md 的 Known parsers 表。若新检查器带有--fix类写操作记得把PlanRequest.mutates置为true以享受串行执行保护。结语discovery.md 看似只是一份百行提示词实际承载了omp cleanse诊断链路中最关键的安全与格式契约只读勘察、命令必验、结构化输出、解析器映射。它与 checkers.ts、parsers.ts、types.ts 共同构成了一套「提示词约定 ↔ 源码校验」双向咬合的机制提示词约束 Agent 行为源码校验 Agent 输出任何一方的偏差都会被另一方的防线拦截。理解这条链路是深入定制和扩展omp cleanse能力的前提。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考