OmX 研究型专家评估面：researcher / dependency-expert / explore 的角色边界与交接回归覆盖

OmX 研究型专家评估面：researcher / dependency-expert / explore 的角色边界与交接回归覆盖

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

本文基于仓库文档 docs/qa/research-specialist-eval-surface-2026-04-18.md 展开，对应 issue #1712「为 researcher、dependency-expert、explore 三个专家角色建立更清晰的边界与交接回归覆盖」。文章以该验证面为骨架，结合 OmX 团队编排源码、提示词契约与测试用例，说明这三个角色在路由、排班（staffing）与输出契约三个层面如何被系统性地测试与保障。

导读

在 OmX 的多 Agent 团队编排（omx team）中，"谁来做、做什么、产出长什么样"是三个必须同时稳定的问题：本地代码库探查该由explore承担，外部文档与已选技术栈研究该由researcher承担，依赖选型与升级评估该由dependency-expert承担。本文介绍的评估面（eval surface）用三类回归测试把这条边界钉死：路由启发式测试、交接排班测试、角色输出契约测试。读完本文，你将掌握这三个角色的职责划分依据、底层关键词路由与排班逻辑，以及如何在本地复跑整套验证命令。

这个验证面在保证什么

根据原文档，该验证面（2026-04-18，issue #1712）从四个层面锁定三个专家角色的行为：

1. 代表性路由夹具（routing fixtures）存在：覆盖explore、researcher、dependency-expert单角色场景，以及explore + researcher、explore + dependency-expert混合场景。混合场景专门验证"本地探查 + 外部研究/依赖评估"同时出现时的分流顺序。
2. 角色输出契约检查（role output-contract checks）：
   • researcher必须保留 source URLs、官方文档优先偏好、版本说明语言；必须停留在"已选技术栈的文档/行为问题"上，而不是默默滑向依赖对比。
   • dependency-expert必须保留候选对比、维护/许可证/风险语言；拥有 adopt（采用）/ upgrade（升级）/ replace（替换）/ migrate（迁移）决策权，并把"已选技术栈文档问题"交还给researcher。
   • explore必须保持本地、只读，输出绝对路径与文件关系指引；拥有仓库本地事实，并把外部文档/依赖建议向上交接。
3. 执行交接排班（handoff staffing）：混合车道场景必须同时分配两条 lane，避免"只派一个角色"造成的信息断链。
4. 刻意非目标（non-goals）：不新增 benchmark 框架、不做线上网页质量评分、不引入额外 runtime/e2e 基建，全部复用现有测试面。这意味着该验证面是"低成本、可回归"的契约层，而不是重型的端到端评测系统。

当前回归面一览

原文档给出三个回归面，对应三个测试文件与覆盖内容：

验证命令：本地可复跑

原文档给出两条命令，可在仓库根目录直接执行：

npm run build node --test dist/team/__tests__/role-router.test.js dist/team/__tests__/followup-planner.test.js dist/hooks/__tests__/prompt-guidance-wave-two.test.js

注意第二条命令运行的是编译产物（dist/目录下的.js），因此必须先执行npm run build完成 TypeScript 编译。这样验证面与实际发布路径保持一致，避免"源码测试通过、打包后行为漂移"的假阴性。

第一层：路由启发式 —— role-router 如何分流

路由层位于 src/team/role-router.ts，对外暴露routeTaskToRole(taskSubject, taskDescription, phase, fallbackRole)，返回RoleRouterResult（含role、confidence：high/medium/low、reason）。三个专家角色由一组专用判定函数按固定优先级决定。

判定函数的优先级链

在routeTaskToRole内（src/team/role-router.ts），先处理 build-fix / debug 意图，然后依次检查：

1. isLocalExplorationTask(text)→explore（high）
2. isImplementationHeavyDependencyTask(text)→ 走 fallback 实现车道（medium），防止把"实现替换工作"误判给 dependency-expert
3. isDependencyEvaluationTask(text)→dependency-expert（high）
4. isResearchTask(text)→researcher（high）
5. 其余再按 docs / design / cleanup / review / verification 等意图与关键词计分兜底

注意第 2 步的防误判设计：如果任务同时命中依赖信号、实现意图与依赖实现信号（如 adapter、call sites、imports、wire），且包含 adopt/migrate/replace/upgrade 等动作词、却不包含assess/choose/compare/evaluate/options/recommend/select/trade-offs 等评估词，则判定为"实现密集的依赖替换工作"，交给 fallback 实现车道而非 dependency-expert。对应测试夹具见 src/team/tests/role-router.test.ts（"Replace auth SDK integration"）。

三个角色的信号词

• explore：LOCAL_EXPLORATION_VERB（check、find、locate、map、search、trace、understand、which files...）+LOCAL_EXPLORATION_SUBJECT（file、symbol、repo、path、usage、relationship、wiring、flow、local...），或LOCAL_USAGE_DISCOVERY（call sites、how we use、integration points、our usage...）。典型夹具："Map which files and symbols implement the local session refresh flow in this repo" → explore（role-router.test.ts）。
• researcher：RESEARCH_SIGNAL（official docs、upstream docs、api docs、release notes、versioning、compatibility、research）+RESEARCH_VERB，或CHOSEN_TECH_RESEARCH_SIGNAL（api、framework、library、sdk、service、tool、vendor）+CHOSEN_TECH_RESEARCH_NEED（best way、behavior、how to、in the wild、parameter、what does、why does...）。两个关键夹具：仅凭 "best way to use this framework feature + expected behavior" 这类不含显式 docs 关键词的已选技术问题也能路由到 researcher（role-router.test.ts）；"Check how we use this SDK today and whether we should upgrade it" 这类本地使用 + 升级决策任务则优先路由到 explore（role-router.test.ts）。
• dependency-expert：DEPENDENCY_EVALUATION_SIGNAL（dependency、package、sdk、library、framework、npm、pypi、license、maintenance、download stats、migration path、vendor）+ 评估动词（adopt、assess、choose、compare、evaluate、recommend、replace、select、swap、upgrade）或评估语境（candidate、comparison、risk、trade-offs...）。夹具："Compare npm packages for maintenance, license compatibility, migration path, and download stats" → dependency-expert（role-router.test.ts）。

其余保障设计

• 角色名安全校验SAFE_ROLE_PATTERN = /^[a-z][a-z0-9-]*$/，loadRolePrompt拒绝路径穿越（如../../../etc/passwd）、大写、含点角色名，见 role-router.test.ts。
• listAvailableRoles只扫描.md文件并按文件名去扩展名排序，测试同时保证不会把*-AGENTS指令文件暴露为角色。
• 路由确定性：相同输入必得相同输出，测试覆盖于 role-router.test.ts。
• 关键词计分兜底：同类别命中 ≥2 个关键词为 high、恰好 1 个为 medium、0 个则依赖 phase 语境或 fallbackRole 且为 low。

第二层：交接排班 —— followup-planner 如何组队

路由层解决"单个任务给谁"，排班层解决"混合任务该同时派哪些 lane"。核心实现在 src/team/followup-planner.ts 的buildFollowupStaffingPlan(mode, task, availableAgentTypes, options)。

排班结构

对于team模式，workerCount ≥ 2时分配质量车道（test-engineer / verifier / quality-reviewer），workerCount ≥ 3时调用pickSpecialistRole分配专家支持车道，workerCount ≥ 4时扩展主实现车道容量。pickSpecialistRole与路由层采用同一套信号词判定wantsExplore、wantsDependencyExpert、wantsResearcher，并用chooseDistinctAvailableRole确保混合任务选出的专家角色与主角色互斥，避免同一人同时干两条互相矛盾的 lane。

混合车道的三个测试夹具

对应 src/team/tests/followup-planner.test.ts：

• explore + researcher："Find which files implement session refresh in the repo, then research the official docs and version compatibility notes for the auth SDK" → 主 lane 为 explore（reason 含primary），专家 lane 为 researcher（reason 含specialist），见 followup-planner.test.ts。
• explore + dependency-expert（对比+迁移）："Map which local packages currently handle logging, then compare replacement npm packages for license risk, maintenance, and migration path" → 主 lane explore、专家 lane dependency-expert，见 followup-planner.test.ts。
• explore + dependency-expert（本地使用 + 升级）："Check how we use this SDK today and whether we should upgrade it" → 同样 explore 主、dependency-expert 专家，见 followup-planner.test.ts。

三个夹具的共同点：凡涉及仓库本地事实的任务，explore 永远先于外部评估角色——这正呼应了输出契约中"explore 拥有 repo-local facts，把外部文档/依赖建议向上交接"的边界。

启动提示与验证计划

排班结果同时生成launchHints与verificationPlan。team 模式启动命令为omx team <N>:<fallbackRole> "<task>"（skill 形态$team ...），Ralph 模式为omx ralph "<task>"；验证计划固定 3 个检查点，强调"交付 lane 并行 + 独立验证 lane 在关闭前捕获新鲜证据"。测试还验证了通过codexHomeOverride注入.omx-config.json的agentReasoning可对特定角色（如 architect）覆写推理档位为xhigh，见 followup-planner.test.ts。

第三层：输出契约 —— prompt 级边界检查

排班与路由解决"谁来做"，输出契约解决"做出来长什么样"。该层由 src/hooks/tests/prompt-guidance-wave-two.test.ts 驱动，通过loadSurface读取prompts/*.md并对三个角色提示词做正则断言。契约名单WAVE_TWO_CONTRACTS定义于 src/hooks/prompt-guidance-contract.ts，除researcher、explore外还包含 architect、critic、debugger、test-engineer、code-reviewer、quality-reviewer。

researcher 契约（prompts/researcher.md）

• 工作流要求：classify the request（先分类请求）、按authoritative docs structure收敛到smallest set of pages、在文档锚定之后再给examples that add value、保留source-reference evidence。
• 引用纪律：OSS 证据必须用org/repo@sha:path:line格式，且never a moving branch（禁止引用移动分支）；输出契约必须包含OSS Reference Implementations小节。
• 范围守卫：already chosen technology（只研究已选技术栈）；repo-local usage必须转交explore；package/SDK adoption必须转交dependency-expert。
• 输出要素：source URL、Prefer official documentation、Version compatibility or version uncertainty is noted when relevant/### Version Note、version/date certainty。

dependency-expert 契约（prompts/dependency-expert.md）

• 候选要求：at least two credible candidates（至少两个可信候选）；评估要素覆盖license requirements|license sources、release and commit activity|adoption/download signals、Risks。
• 决策权与边界：必须明确adoption, upgrade, replacement, or migration decision（采用/升级/替换/迁移决策归它所有），同时把已选技术栈的文档问题route it to researcher。

explore 契约（prompts/explore.md）

• 输出形态：ALL paths are absolute（所有路径绝对化）、Relationships between files/patterns explained（解释文件/模式间关系）。
• 行为边界：Read-only、repo-local facts only；遇到依赖推荐时report that handoff upward（向上交接，不自行做外部评估）。

契约测试同时验证各提示词都带 grounded-evidence 措辞（如 researcher 的citation sufficiency、explore 的answer is grounded），从提示词源头约束"证据充分才下结论"。

如何扩展这套评估面

从源码结构看，扩展新角色边界遵循三步模式：

1. 路由层：在 src/team/role-router.ts 增加信号正则与判定函数，并在routeTaskToRole的优先级链中插入位置；在 role-router.test.ts 补正例与负例（尤其是"看似该角色、实则不属于"的对抗性用例，如实现密集的替换任务）。
2. 排班层：在 src/team/followup-planner.ts 的pickSpecialistRole中扩展wants*判定，并在 followup-planner.test.ts 补"主 lane + 专家 lane"混合夹具。
3. 契约层：更新 prompts/researcher.md、prompts/dependency-expert.md、prompts/explore.md 中对应的输出契约措辞，并在 prompt-guidance-wave-two.test.ts 补正则断言。

小结

这个评估面是 OmX 团队编排中"专家角色纪律"的可执行化：路由启发式保证任务流向正确角色，交接排班保证混合任务不缺 lane，输出契约保证每个角色的产出形态与边界措辞不漂移。三者共同回答 issue #1712 的核心问题——如何让researcher、dependency-expert、explore在协同工作时既各司其职、又正确交接，而不是互相越界或静默滑向对方职责。对希望在自己的 Agent 编排中复刻这套"边界回归面"的开发者，上述三个测试文件与提示词文件即是可直接对照的模板。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex