排障报告模板

「不生效，帮忙看看」很难让下一位复现者进入同一个现场。报告应让别人知道：在哪里启动、用了什么输入、预期是什么、实际失败到哪一步，以及哪些条件已经比较过。先记录观察，再提出猜测；猜测可以保留，但不要拿它代替证据。

本站目前没有公众可访问的 issue 仓库，也没有接收报告的在线表单。你可以在此复制模板，保存到自己的记录，填写并脱敏后交给你选择的支持渠道。复制按钮只复制模板，不代表已提交反馈。

复制与下载

问题报告模板全文

复制后填写真实观察。也可在文本框中选中全文，使用系统复制操作。

# 问题标题：<症状，而非猜测的根因> ## 环境与范围 - 日期、系统、架构： - 客户端与实际版本命令输出： - 当前目录、启动方式（私人路径替换为 <project>）： - 配置位置与影响范围（不粘贴秘密）： ## 期望与实际 - 固定输入与期望： - 实际输出、退出码与错误发生阶段： ## 最小复现 1. 在无私人资料的新目录准备输入。 2. 写出可直接运行的命令与运行目录。 3. 提供脱敏的必要日志。 ## 区分性检查 | 检查 | 实际结果 | 能支持或排除什么 | | --- | --- | --- | | <一次只改一个条件> | <原始观察> | <不要过度推断> | ## 处理与复测 - 实际改动： - 用相同输入复测的命令、日期、输出： - 仍未知 / 未测的平台： ## 附件检查 - [ ] 无 token、Cookie、邮箱地址、私人仓库资料或完整配置 - [ ] 截图与日志来自这次实际运行 - [ ] 未把另一个版本或客户端的结果当成本次结果

模板版本 1.0.0，复核日期 2026-10-18，作者为 CodexCase 维护者小伟。它来自本方原创 examples/templates/troubleshooting-report.md，页面复制内容与下载使用同一源码。

资源	内容
问题报告 Markdown	可直接填写的报告结构
脱敏填写实例	本方本地 MCP 入口路径故障
完整模板包 v1.0.0	README、报告和 AGENTS.md 两类模板及实例

先核对实际版本与环境

客户端名称不等于版本。把实际执行的版本命令与输出放在一起，并写明系统、架构、启动目录和终端、IDE 或应用等启动方式。Node 练习可以记录 node --version，Codex CLI 可以记录 codex --version。未安装的工具无需为了填表而安装，写「不适用」即可。

配置只摘取相关字段并标明用户层或项目层；配置位置依据可核对 OpenAI 配置基础文档，于 2026-10-18 复核。路径中的用户名与私人项目名统一换成 <project> 等标记。替换路径时保留相对关系，否则读者无法判断脚本是否位于工作目录之外。不要粘贴 token、Cookie、私人仓库内容或完整用户配置。

缩小到能复现的步骤

最小复现应使用可公开的固定输入，写出运行目录与准确命令，并保留退出码。每次只改一个条件；如果同时重装、换网络和清配置，成功了也难以知道原因。不能复现时也应如实记录频率和未知条件，不要为了让报告完整而编写一次成功日志。

本方 MCP 练习 的报告可以压缩为下面的观察，完整证据见 真实运行记录：

检查	实际结果	支持的判断
启动 missing-server.mjs	Node 退出 1，MODULE_NOT_FOUND	在协议握手响应之前失败
只改成 server.mjs	initialize、list、call 完成	本例支持入口路径是原因
调用 greet，name 为 reader	Hello, reader	该固定调用得到预期内容

这些结果来自 macOS、Node v22.23.3 和本方 stdio 探针；没有测试 HTTP、OAuth 或每种 Codex 客户端。报告要保留这一边界，不能把一个成功调用写成所有 MCP 服务恢复。

发出之前做一次复读

让报告里的每条结论都能指向一条观察。处理后使用原输入、原启动方式复测，写清日期、输出和仍未知项。截图应来自这次实际操作；若截取局部，要保留足以定位错误的上下文，并检查终端标题、账号和路径是否泄露私人信息。

本模板仅组织证据，不自动诊断或上传资料。需要选择检查顺序时返回 故障排查栏目，需要解释本站实测、引用和验证范围的区别时读 编辑与验证方法。后续修改模板版本时，应同步更新下载包与填写实例，避免报告字段相互矛盾。