企业官网建设流程全解析

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

导读

本文围绕 OmX（Oh 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 hints），GitHub 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.

逐句拆解，它实际上编码了五条分诊纪律：

1. 聚焦一个复现细节（one focused reproduction detail）：评论开门见山点明目标——在报告成为"可执行包"（executable package）之前，只需要一个最小化、可验证的复现输入。
2. 最小精确命令或提示词：smallest exact command or prompt。对于 OmX 这类 CLI 工具，复现单元通常是某条omx命令、某个 prompt 输入或某个 hook 触发场景；要求"最小且精确"，是为了排除环境噪音、定位到具体契约（contract）。
3. 必须附带输出（what output do you get）：复现不仅要有输入，还要有实际输出（含报错文本），用于与预期行为比对。
4. 严格的信息边界：只需要"运行该命令所必需的环境事实"——oh-my-codex版本、OS/shell、Node.js 版本；其余一律不要求。同时对日志中的 secrets 必须脱敏（redact）。
5. 超时与标签语义：issue 在复现成功或被收窄到具体契约之前，持续保持needs-repro标签；超时窗口内无跟进，维护者可关闭为 not actionable。

三、需要提供的环境事实清单（Minimal Environment Facts）

模板明确指定了三项"运行该命令所必需的环境事实"，这是信息收集的上限而非下限——不要追问与复现无关的机器配置、网络拓扑或历史操作记录：

模板同时强调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 issue；
• proposal：功能/契约提案等待维护者范围门禁；
• 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 模板关闭 issue：

Closing 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.

这段模板强调了两个容易被社区忽略的规则：

1. 重新打开的最低门槛：必须包含"精确命令/提示词、环境细节、预期 vs 实际行为、脱敏日志/截图"四要素；
2. 聊天上下文不能作为重开依据：因为"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_ID=issue-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; }

从这段代码可以推断出三条实现约定：

1. Classification类型携带needsRepro: boolean与kind: "bug" | "feature" | "contract" | "duplicate" | "support" | "invalid"字段，说明"是否需要复现"是分类器输出的独立维度；
2. 触发动作是"贴模板评论 + 打needs-repro标签"，continue表示该 issue 本轮不再向下流转，进入等待状态；
3. 仅当kind === "bug"且needsRepro === false时才会调用createPackageIdempotently创建包——这与模板"before this can become an executable package"的措辞完全吻合。

从源码结构看，该协调器是"基础设施中立"（infrastructure-neutral）的参考骨架：仓库实际部署时可以用 GitHub Actions、机器人或定时脚本实现，但模板与状态机才是事实标准。

八、维护者实操清单

在真实 issue 上使用本模板时，建议按以下顺序操作：

1. 先做重复搜索：确认不是duplicate（此时应改用 duplicate-close.md 关闭并重定向到 canonical issue）；
2. 确认是 bug 类而非提案类：功能/契约提案应改用 feature-contract-proposal-gate.md，等待维护者确认契约后再进入实施，期间不得创建变异 worktree；
3. 贴出 needs-repro-question 评论并打上needs-repro标签；
4. 记录身份块：在 issue 正文或包产物中记录state: needs_repro（参考 issue-package-identity.md 的字段约定）；
5. 启动超时计时：超时后按 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