OmX 分诊实战：用 needs-repro 模板把不可复现的 issue 收敛为可执行包

OmX 分诊实战用 needs-repro 模板把不可复现的 issue 收敛为可执行包【免费下载链接】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导读本文围绕 OmXOh My codeX在docs/pipeline/templates/triage/needs-repro-question.md中定义的最小复现追问模板展开说明当 GitHub 上报的 bug 缺乏可复现证据时维护者应如何通过一条结构化评论把模糊报告收敛为可执行的工作包。读完本文你将掌握needs-repro标签与needs_repro状态的完整语义、最小复现提问的标准话术与信息边界版本、环境、脱敏规则、超时关闭的兜底策略以及复现成功后如何无缝进入 OmX 的包身份package identity与 worktree 分派流程。一、模板定位分诊管道中的不可复现兜底在 OmX 的 GitHub / PR / package identity 管道中所有来自 GitHub issue 或 Discord 社区的反馈都会先进入统一的 intake 流程分类classify→ 去重dedupe→ 复现reproduce→ 风险门禁risk-gate。其中复现环节是决定一个 bug 报告能否升级为正式工作包的关键分水岭报告可复现→ 进入ready状态创建package_id并绑定分支、worktree、OMX 会话报告疑似 bug 但缺少复现证据→ 标记为needs_repro由维护者发出最小复现追问超时仍未回复 → 按timeout-close模板关闭为 not actionable。needs-repro-question.md正是第二种场景下的标准评论模板它在 templates/triage/ 目录中与timeout-close.md、duplicate-close.md、reproducible-bug-package.md、feature-contract-proposal-gate.md并列共同构成公开可版本化的分诊策略资产。按照 templates/README.md 的约定这些模板是可复制、可评审、可入库的公开契约而聊天消息只是协调提示coordination hintsGitHub issue、PR 和包产物才是事实来源source of truth。二、模板原文逐段解析needs-repro-question.md全文如下这是发布到 issue 上的评论正文Thanks for the report. I need one focused reproduction detail before this can become an executable package:What is the smallest exact command or prompt that reproduces the problem, and what output do you get?Please include only the environment facts needed to run that command (oh-my-codexversion, OS/shell, Node.js version) and redact secrets from logs. We will keep this labeledneeds-reprountil the issue can be reproduced or narrowed to a specific contract. If there is no follow-up after the timeout window, maintainers may close it as not actionable.逐句拆解它实际上编码了五条分诊纪律聚焦一个复现细节one focused reproduction detail评论开门见山点明目标——在报告成为可执行包executable package之前只需要一个最小化、可验证的复现输入。最小精确命令或提示词smallest exact command or prompt。对于 OmX 这类 CLI 工具复现单元通常是某条omx命令、某个 prompt 输入或某个 hook 触发场景要求最小且精确是为了排除环境噪音、定位到具体契约contract。必须附带输出what output do you get复现不仅要有输入还要有实际输出含报错文本用于与预期行为比对。严格的信息边界只需要运行该命令所必需的环境事实——oh-my-codex版本、OS/shell、Node.js 版本其余一律不要求。同时对日志中的 secrets 必须脱敏redact。超时与标签语义issue 在复现成功或被收窄到具体契约之前持续保持needs-repro标签超时窗口内无跟进维护者可关闭为 not actionable。三、需要提供的环境事实清单Minimal Environment Facts模板明确指定了三项运行该命令所必需的环境事实这是信息收集的上限而非下限——不要追问与复现无关的机器配置、网络拓扑或历史操作记录事实项说明为何必要oh-my-codex版本例如omx version的输出行为差异、回归定位依赖版本锚点OS / shell例如 Linux bashmacOS zsh路径语义、hook 触发、进程生命周期差异Node.js 版本例如node --version输出OmX 的 TS 侧工具链与运行时兼容性模板同时强调redact secrets from logs贴日志时必须抹除 token、凭证、私密 URL、私有频道名等敏感内容。这一点与 github-pr-package-identity.md 的Public safety checklist一脉相承——公开产物issue、PR、包文件中严禁出现密钥、凭证、私有队列名或主机拓扑。四、状态机与标签needs_repro的完整生命周期在 OmX 推荐的包状态机见 github-pr-package-identity.md 的 States 一节中needs_repro是紧随intake之后的分诊态intake报告已收到尚未创建包needs_repro疑似 bug 的报告缺少精确复现细节本文主题duplicate关闭或重定向到 canonical issueproposal功能/契约提案等待维护者范围门禁ready包身份已创建变异mutation尚未开始executing/review/merge_ready/merged/closed后续执行生命周期。状态身份建议记录在 issue 正文或包产物的 issue-package-identity.md 身份块中state: needs_repro而 issue 上的needs-repro标签与状态保持一致。也就是说标签是 UI 层的信号状态是身份块中的事实两者由分诊协调器同步维护。五、超时兜底timeout-close的关闭话术当超时窗口内没有收到复现细节时维护者应切换使用 timeout-close.md 模板关闭 issueClosing because the requested reproduction details were not provided within the timeout window. If you can still reproduce this, please open a new issue or ask to reopen with: the exact command or prompt, environment details, expected vs actual behavior, redacted logs/screenshots. Chat context alone is not enough to reopen; the GitHub issue must contain the actionable evidence.这段模板强调了两个容易被社区忽略的规则重新打开的最低门槛必须包含精确命令/提示词、环境细节、预期 vs 实际行为、脱敏日志/截图四要素聊天上下文不能作为重开依据因为chat messages are coordination hints, not truth——事实必须沉淀在 GitHub issue 中否则后续维护者无从审计。六、复现成功后的流转从追问到可执行包如果 reporter 提供了足够细节且问题被复现流程随即进入 reproducible-bug-package.md 模板描述的状态——维护者在 issue 上贴出包身份块package_id: issue-0000-short-slug branch: fix/issue-0000-short-slug worktree: ../oh-my-codex-worktrees/issue-0000-short-slug omx_session: issue-0000-short-slug state: ready同时附上 Mutation gate 清单重复搜索已完成、复现步骤已写入 issue、风险等级已记录、恰好一个变异运行时被指派给 worktree、包产物存在或随实现一并提交。随后由协调器执行 github-pr-package-identity.md 中的显式分派命令git fetch origin dev git worktree add ../oh-my-codex-worktrees/issue-2087-pipeline-templates \ -b docs/issue-2087-pipeline-templates origin/dev cd ../oh-my-codex-worktrees/issue-2087-pipeline-templates OMX_PACKAGE_IDissue-2087-pipeline-templates \ omx team 1:executor Implement issue-2087; keep package artifacts current. gh pr create --base dev --head docs/issue-2087-pipeline-templates \ --title docs: add issue package pipeline templates \ --body-file .github/pr-body.md由此可见needs-repro-question并非孤立模板而是整条报告 → 复现 → 包 → PR → 合并链路的守门员它把不可复现的报告挡在包创建之前确保只有带证据的工作才会消耗变异资源。七、源码级佐证分诊协调器如何触发该模板github-pr-package-identity.md 的 Coordinator skeleton 给出了公开契约层面的参考实现TypeScript其中intakeLoop对needsRepro的处理为if (classification.needsRepro) { await commentFromTemplate(issue, triage/needs-repro-question.md, classification); await label(issue, [needs-repro]); continue; }从这段代码可以推断出三条实现约定Classification类型携带needsRepro: boolean与kind: bug | feature | contract | duplicate | support | invalid字段说明是否需要复现是分类器输出的独立维度触发动作是贴模板评论 打needs-repro标签continue表示该 issue 本轮不再向下流转进入等待状态仅当kind bug且needsRepro false时才会调用createPackageIdempotently创建包——这与模板before this can become an executable package的措辞完全吻合。从源码结构看该协调器是基础设施中立infrastructure-neutral的参考骨架仓库实际部署时可以用 GitHub Actions、机器人或定时脚本实现但模板与状态机才是事实标准。八、维护者实操清单在真实 issue 上使用本模板时建议按以下顺序操作先做重复搜索确认不是duplicate此时应改用 duplicate-close.md 关闭并重定向到 canonical issue确认是 bug 类而非提案类功能/契约提案应改用 feature-contract-proposal-gate.md等待维护者确认契约后再进入实施期间不得创建变异 worktree贴出 needs-repro-question 评论并打上needs-repro标签记录身份块在 issue 正文或包产物中记录state: needs_repro参考 issue-package-identity.md 的字段约定启动超时计时超时后按 timeout-close.md 关闭若收到合格复现则切换至 reproducible-bug-package.md 创建包并分派。九、结语needs-repro-question.md虽只有寥寥数行却是 OmX 将社区反馈工程化的关键一环它以一个最小复现细节为锚点用最小环境事实 脱敏限定信息收集边界用needs-repro标签与needs_repro状态维持可审计性再用超时关闭策略防止低质量报告长期滞留。对于任何希望以证据驱动方式运营开源 bug 管道的团队这套模板与其配套的分诊状态机、包身份块和 gate 清单都是可以直接照抄进仓库的公开契约资产。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考