setup-doctor

setup-doctor

审查项目级和用户级 AI 编码 Agent 的配置，为结果打出 0 到 100 分，并准确指出需要修复的内容。它还会将你的本地使用情况汇总成可分享的卡片。

上方的徽章显示了此仓库自身的评分，该评分通过对其运行 setup-doctor 得出。

功能

• Doctor 会审查指令文件、技能、子 Agent、MCP 服务、插件、设置和钩子。它会在 6 个类别中运行 30 条规则，并报告评分、等级（优秀、良好、需要改进或较差），以及每项检查结果对应的具体修复方法。
• Wrapped 会汇总你的本地会话日志（会话数、活跃天数、令牌数、预估费用、连续使用天数和个性标签），并生成可分享的 SVG 卡片，也可选择生成 PNG。
• Badge 会为你的 README 生成静态或动态评分徽章。
• HTML 报告会生成单个独立文件，不会发起网络请求。
• MCP 服务会将 Doctor 和 Wrapped 作为只读工具提供给任何 MCP 客户端。

快速开始

无需安装。在项目根目录运行：

npx setup-doctor

默认命令会审查项目并输出报告：

Setup Doctor  score 85/100  (Good)   rules v1.2.0

Instruction files  29/30   Skills  n/a   MCP  n/a   Plugins  n/a   Settings  5/10   Freshness  n/a

Always-loaded context: about 0 tokens

HIGH  SET-02  Hook PreToolUse in .claude/settings.json points to scripts/missing.sh which is missing or not executable
      Fix: Correct the path, make the script executable, or remove the hook.
LOW   INS-01  No instruction file found for claude
      Fix: Create CLAUDE.md (or the agent's equivalent) with build and test commands, code style rules and a short project layout.

2 findings

为便于阅读，此处的检查结果消息缩短了绝对路径。

阅读入门指南，了解如何解读评分和每项检查结果。

命令

命令	用途
setup-doctor [doctor] [path]	审查配置并输出评分。这是默认命令。
setup-doctor wrapped	汇总本地使用情况并生成可分享的卡片。
setup-doctor badge	生成 README 徽章文件。
setup-doctor rules	列出每条规则及其类别、严重性和启用状态。
setup-doctor explain <RULE_ID>	说明规则的检查内容以及如何修复。
setup-doctor diff <before.json> <after.json>	说明两个已保存报告之间的评分变化。
setup-doctor mcp	通过标准输入/输出启动 MCP 服务。

运行 setup-doctor --help 查看所有标志，或参阅命令参考。

支持的 Agent

Agent	Doctor	Wrapped
Claude Code	完整支持（全部 30 条规则）	是
Codex	指令和 MCP 规则	是
GitHub Copilot CLI	指令、技能、MCP、设置和钩子	是
Cursor	指令、MCP 和项目技能	是，需要 Node 22.5 或更高版本
其他 Agent（.windsurfrules、.clinerules）	仅指令规则	否

不适用于某个 Agent 的类别（例如 Codex 的插件）会从其评分中排除，不会计为失败。详情请参阅 agents。

安装

方式	命令或位置
npm（无需安装）	npx setup-doctor
Homebrew	brew install saxenakapil/setup-doctor/setup-doctor
Claude Code 插件	可在 Anthropic 插件目录中找到。提供 /setup-doctor:doctor 和 /setup-doctor:wrapped。
Cursor 技能	将 skills-cursor/ 复制到项目的 .cursor/skills/。参阅 Cursor 技能。
MCP 客户端	已列入官方 MCP 注册表，名称为 io.github.saxenakapil/setup-doctor。参阅 MCP 服务。
GitHub Action	saxenakapil/setup-doctor-action@v1。参阅 CI 集成。
pre-commit	将此仓库添加为钩子源。参阅 CI 集成。

常用选项

选项	命令	说明
--agent claude|codex|cursor|copilot|all	doctor、badge、wrapped	要读取的 Agent。doctor 和 badge 默认会自动检测。wrapped 默认使用 claude。
--scope project|global|all	doctor、badge	要检查的位置。
--format terminal|json|html	doctor	输出格式。
--ci --fail-under <n>	doctor	如果得分低于 n，则以代码 1 退出。
--ci --compare	doctor	与上次记录的运行结果进行比较，如果得分下降，则以代码 1 退出。
--fix、--dry-run	doctor	预览或应用安全的机械修复。参见修复模式。
--period 7d|30d|ytd|all|YYYY-MM-DD:YYYY-MM-DD	wrapped	时间范围。默认为 30d。
--anonymize、--show-projects、--no-cost	wrapped	隐私和成本控制。参见 Wrapped。
--config <path>	doctor、badge、rules、wrapped	使用 <project>/.setupdoctorrc 以外的配置文件。参见配置。

完整的标志参考：doctor、wrapped。

徽章

将得分添加到 README：

npx setup-doctor badge

这会写入 setup-doctor-badge.svg，并输出包含当前得分的 Markdown 片段。若要自动更新徽章，请通过 CI 发布 shields.io 端点文件。参见 CI 集成。

隐私与安全

• 运行时不会访问网络。 不会收集遥测数据，也不会检查更新。CI 中有自动检查来确保这一点（scripts/check-no-network.mjs）。
• 审计绝不会更改 Agent 配置。 只有 doctor --fix 会编辑配置文件，并且会显示差异、要求确认，并在写入前创建备份。badge、wrapped 和 --out 只会写入新的输出文件。
• 绝不会打印密钥。 检查结果会报告规则和位置，具体值会显示为 [REDACTED]。
• 可分享的输出只包含汇总数据。 Wrapped 卡片和徽章绝不会包含提示词、文件路径、用户名或仓库名称。本地报告（HTML 和 JSON）可能包含文件路径，分享前请先检查。
• 会话日志仅读取元数据。 读取时间戳、模型名称、令牌数量和工具名称。消息文本会逐行丢弃。
• 无需账户、API 密钥或登录。

文档

• 快速入门：首次运行以及如何解读输出
• Doctor：所有审计选项、输出格式和退出代码
• Wrapped：时间段、隐私控制、卡片和输出格式
• 修复模式：预览和应用修复、备份以及可修复的内容
• 配置：.setupdoctorrc、禁用规则、阈值和忽略模式
• Agents：各 Agent 会读取的内容以及共享文件的评分方式
• CI 集成：GitHub Actions、得分历史、PR 评论、徽章和 pre-commit
• MCP 服务：通过 MCP 客户端使用 Doctor 和 Wrapped
• Cursor 技能：在 Cursor 中安装 Doctor 和 Wrapped 技能
• 故障排除：常见问题及其解决方法

参考文档：

• 规则：v1 规则规范
• 主题：视觉主题设计令牌
• 决策日志：开发过程中的假设、偏差和决策

贡献

欢迎提交问题和拉取请求。提交拉取请求前，请运行完整检查：

npm install
npm run check        # typecheck, tests, privacy guard, version sync, em dash guard
npm run build        # bundles src/bin.ts to dist/bin.js

每条规则都在 src/rules/ 下有自己的文件，并在 test/fixtures/ 下配有触发用例和正常用例。规则是归一化模型的纯函数：只有 src/adapters/ 下的适配器会访问文件系统。

许可证

MIT。请参阅 LICENSE。随附字体的许可证（SIL Open Font License 1.1）见 src/data/fonts/LICENSES.md。