Codex Doctor 用于对 Codex 安装健康和工作区上下文质量做两层检查。第一层复用 Codex 内置的 codex doctor --json，覆盖安装、配置、认证、运行时、Git 环境、终端、app-server、更新和线程清单检查；当默认 provider 只占索引历史少数时，给出窄范围的 provider 范围警告。第二层运行捆绑的只读扫描器，检查内置命令未覆盖的工作区上下文治理。
用法：先解析技能目录，然后运行 python3 <skill-dir>/scripts/scan_workspace.py --cwd "$PWD" --compact-json。若同一任务已运行内置报告，可用 --compact-json --skip-built-in 只扫描工作区。--compact-json 保留所有发现和内置检查行，省略大型技能清单与冗长通过项；仅在需要完整确定性证据时使用 --json。不要将原始内置报告保存在仓库内，需临时存储时用 /tmp 并在结束前删除。
扫描器收集确定性证据，语义判断由使用者完成。严重性分为 S0 至 S4：S0 已证实密钥暴露或破坏性风险；S1 有效配置损坏、硬规则被截断、缺少可执行文件或安装/更新不匹配；S2 完全冗余、活动名称/来源重复或明显项目卫生违规；S3 维护压力、过时禁用项、新版本通知或描述过大；S4 信息性、语义候选或证据缺口。semantic_candidates 仅作为检查提示，需阅读相关源段后分类：行为规则或安全边界、用户偏好、品牌语气、业务事实、目录契约通常保留；可直接发现的清单、框架版本、依赖列表或目录列表可考虑裁剪；过时或矛盾陈述需先对照仓库验证。
静态发现无法证明技能未被使用。若用户明确要求未使用或低频技能，可用已安装的 codex-skill-admin 技能只读审计：python3 <codex-skill-admin-dir>/scripts/codex_skill_admin.py audit-unused --cwd "$PWD" --days 30，并报告证据窗口及不同会话/来源数量；未经用户单独要求并批准，不得禁用任何内容。
报告结构建议先给总体结果（PASS / WARN / FAIL），再列需要处理项、建议人工审查项、已通过项和证据缺口；内置 doctor 子检查应保持为独立事实，如 HTTP 可达性失败与 WebSocket 成功不要合并。
修复需用户明确授权：展示发现 ID、确切来源、错误原因和单文件 unified diff，删除或语义重写指令、更改配置、启用/禁用组件、移动文件时需用户明确批准该发现 ID；应用补丁前立即重新计算源文件 SHA-256，与扫描证据不一致则停止；仅用 apply_patch 应用已批准 diff，并重跑相关检查报告前后结果。绝不自动删除或削弱安全规则、品牌/人设规则、业务事实、项目事实、Git 门禁或目录边界；不因 AGENTS.md 与 CLAUDE.md 重复而删除文本；不执行钩子测性能；不信任钩子、登录 MCP、暴露凭据、安装依赖、更新 Codex 或更改 provider；不修改沙箱、审批、模型、网络或认证设置；不运行破坏性 Git 命令、清理未跟踪文件或移动受保护项目目录。报告完成前需确认扫描器未改动仓库、区分内置诊断与工作区治理发现、标注推断、报告跳过项与证据缺口，如已批准修复则验证每个改动文件并重跑其域检查。部分高级功能与平台支持细节暂未提供。