mcpField
C
codex-doctor

codex-doctor

github.com/zjp1997720Agent 工作流78643 次安装2 天前更新
代码仓库

关于 codex-doctor

codex-doctor 是用于检查 Codex 安装、配置、运行状态及工作区上下文治理的 Skill。它结合 Codex 内置诊断与只读扫描器，并提供审慎解读和修复指引。

主要功能

  1. 01Codex 内置健康检查
  2. 02只读工作区扫描器
  3. 03严重性与置信度指引
  4. 04基于审批的修复流程
  5. 05未使用 Skill 审计指引

适用场景

  1. 01排查 Codex 配置问题
  2. 02检查工作区上下文规范
  3. 03评估可能未使用的 Skill

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/zjp1997720/zhijian-skills --skill codex-doctor

安装后在 Claude Code 中输入/codex-doctor确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
LICENSE
agents/
openai.yaml
evals/
evals.json
references/
checks-and-repair-policy.md
scripts/
scan_workspace.py
tests/
test_scan_workspace.py

详细介绍

Codex Doctor

运行两层健康检查：

  1. 复用 Codex 稳定的内置 codex doctor --json，检查安装、配置、身份验证、运行时、Git 环境、终端、app-server、更新和会话清单。当默认提供方在已索引历史记录中仅占少数时，给出一条范围有限的提供方警告。
  2. 运行随附的只读扫描器，检查内置命令未涵盖的工作区上下文治理情况。

扫描器会收集确定性证据，由你作出语义判断。这种分工很重要，因为脚本可以证明某段文本重复出现，却无法安全判断某项业务事实、安全边界、品牌语气或目录规则是否可以删除。

运行检查

从已加载的 Skill 路径解析 Skill 目录，然后运行：

python3 <skill-dir>/scripts/scan_workspace.py --cwd "$PWD" --compact-json

如果同一任务中已运行内置报告，可更快地仅检查工作区：

python3 <skill-dir>/scripts/scan_workspace.py --cwd "$PWD" --compact-json --skip-built-in

--compact-json 会保留每条发现和每行内置检查结果，同时省略大量 Skill 清单和冗长的通过检查详情。仅在需要完整的确定性清单证据时使用 --json。

不要将内置报告原文保存在仓库中。如果需要临时存储，请使用 /tmp，并在完成前将其删除。

解读发现

在提出任何清理或修复方案之前，请阅读 checks-and-repair-policy.md。将严重性与置信度分开：

  • S0：已证实的密钥泄露或破坏性风险
  • S1：有效配置损坏、硬性规则被截断、启用的可执行文件缺失，或安装与更新不匹配
  • S2：完全重复、活动名称/来源重复，或明确的项目规范问题
  • S3：维护压力、过时的禁用条目、新版本通知，或描述过长
  • S4：信息性内容、语义候选项或证据缺口

将 semantic_candidates 视为需要检查的提示，而不是发现。阅读相关源内容，并将其归类为以下类型之一：

  • 行为规则或安全边界：保留
  • 用户偏好、品牌语气、业务事实或目录约定：保留
  • 需要综合多个文件才能得出的仓库事实：通常保留
  • 可直接查明的清单、框架版本、依赖列表或目录列表：可考虑精简
  • 过时或矛盾的陈述：提出变更前先对照仓库核实

未使用的 Skill 证据

静态发现无法证明某个 Skill 未被使用。如果用户明确询问未使用或低频使用的 Skill，请以只读审计模式使用已安装的 codex-skill-admin Skill：

python3 <codex-skill-admin-dir>/scripts/codex_skill_admin.py audit-unused --cwd "$PWD" --days 30

报告证据时间范围和不同会话/来源的数量。除非用户另行提出请求并批准目标列表，否则不要禁用任何内容。

报告结构

先给出总体结果，然后仅展示可采取行动或与决策相关的项目：

# Codex 健康检查

状态：PASS / WARN / FAIL

## 需要处理
- [finding id] severity / confidence — conclusion
  Evidence: source and observed state
  Impact: concrete failure or context cost
  Recommendation: exact next action

## 建议人工审查
- semantic candidates with why they may be inferable or stale

## 已通过
- grouped domains, not every low-level row

## Evidence gaps
- checks that cannot be proven from public/local data

将内置 doctor 的子检查作为独立事实保留。例如，HTTP 连通性失败和 WebSocket 成功必须分列为两行；不要将其合并为“网络故障”。

修复协议

诊断并不代表获准修复。当用户要求修复发现的问题时：

  1. 展示一个问题 ID、确切的源内容、错误原因，以及仅涉及单个文件的统一差异。
  2. 如果更改会删除或在语义上改写指令、更改配置、启用／禁用组件或移动文件，请先征求用户对该问题 ID 的明确批准。
  3. 应用补丁前，立即重新计算源文件的 SHA-256。如果结果与扫描证据不同，则停止操作。
  4. 仅使用 apply_patch 应用获批的差异。
  5. 重新运行相关检查，并报告修复前后的结果。

绝不自动执行以下操作：

  • 删除或弱化安全规则、品牌／角色规则、业务事实、项目事实、Git 门禁或目录边界
  • 仅因 AGENTS.md 和 CLAUDE.md 中存在重复文本就将其删除；跨主机保持一致可能是有意为之
  • 执行钩子以测量性能
  • 信任钩子、登录 MCP、暴露凭据、安装依赖、更新 Codex 或更改提供方
  • 修改沙箱、审批、模型、网络或身份验证设置
  • 运行具有破坏性的 Git 命令、清理未跟踪文件或移动受保护的项目目录

完成检查

报告完成前：

  • 确认扫描器未对仓库进行任何更改
  • 区分 Codex 内置诊断与工作区治理问题
  • 将推断标注为推断
  • 报告跳过的检查和证据缺口
  • 如果已获准修复，请验证每个已更改的文件并重新运行其领域检查

评论

支持 Markdown