Vue Doctor 项目健康检查 ​

负责人：肖龙  ｜  分类：AI 工具  ｜  状态：可用

简介 ​

Vue Doctor 是 dh-ai 里的 Vue 项目健康检查工具。它会在本地扫描 Vue 项目，检查安全、正确性、性能、包体积、组件结构、可维护性、可访问性和视觉规范问题。

它适合用在接手项目、提交前自检和发版前检查。扫描后会输出 0 到 100 健康分、中文诊断、可视化报告和修复任务：Doctor 负责找问题，Agent 根据任务改代码，改完后再用 Doctor 复检。默认只做本地扫描，不上传源码。

支持 Vue 2、Vue 3，也能识别 Vite、Vue CLI、Nuxt、Quasar、VitePress 和 VuePress 项目。

我们的能力 ​

• 本地扫描：不上传源码，直接在项目里给出 0 到 100 健康分。
• 增量检查：只看本次改动新引入的问题，适合提交前和 CI。
• 构建产物检查：发版前看包体积、拆包、大资源和构建失败。
• 页面性能体检：测量真实页面的加载和性能表现，输出可处理的问题清单。
• 页面运行巡检：实际打开页面，发现白屏、崩溃、控制台报错和失败请求。
• 工程简化检查：找出过度封装和可能可删的代码，减少不必要的复杂度。
• 中文报告：终端、Markdown、HTML、JSON 和 Agent 任务清单都会生成。
• Agent 修复：Doctor 找出问题并生成任务；Agent 根据文件位置和修复建议改代码，完成后再复检。
• 规则配置：可以跳过生成文件、关闭误报规则，或调整规则级别。

快速开始 ​

第 1 步：安装 ​

没有 dh-ai 也可以从这里开始。先安装 Node.js 长期支持版，重新打开终端，运行 node -v 和 npm -v 确认可用。在项目目录执行下面的命令，局部安装 CLI，后续通过 npx dh-ai 使用，无需全局安装。

npm config set @szhn:registry https://npmmirror.digitalhainan.com.cn/
npm i -D @szhn/ai-cli@latest

第 2 步：跑体检 ​

npx dh-ai doctor .

第 3 步：交给 Agent 修复，再复检 ​

终端会直接告诉你健康分、Top 问题和修完预计能涨多少分，并生成 .dh-doctor/tasks.md。把这份任务清单交给 Agent 修复；改完后再跑一次检查，确认问题已经解决。

跑完长什么样 ​

终端会先给结论，再列问题。下面这张截图来自一次真实 Vue 项目扫描：先看问题、分数和提升空间，再从底部拿到可交给 Agent 修复的任务。

终端截图怎么看 ​

可视化报告怎么看 ​

report.html 更适合给团队快速看结论。它把终端信息整理成几个面板：健康分、首屏、性能、安全、结构、Top 问题，以及可以直接交给 Agent 修复的问题组。

这张图是完整报告样例，用来展示报告的阅读方式。除了健康分和 Top 问题，还能看到首屏相关信号、性能和结构评分、构建产物、最大资源，以及适合交给 Agent 或需要人工判断的修复任务。实际结果会随项目代码和是否执行构建检查而变化。

分数怎么理解 ​

推荐工作流 ​

先做一次完整扫描，确认问题后分批处理；每批处理完只复检改动部分，避免反复扫完整个项目。

能检查什么 ​

不用背规则 ID，知道 8 类检查即可：

某条规则看不懂时：

dh-ai doctor rules explain no-sync-route-component

输出会说明四件事：问题是什么、会带来什么影响、建议怎么改、改完怎么验证。

输出结果 ​

扫描结束后，默认写到项目根目录：

.dh-doctor/
  report.md      给人看：总览、分类、Top 问题、修复建议
  report.html    给人看：首屏、性能风险和修复优先级页面
  tasks.md       给 Agent 看：按优先级排好的修复任务
  report.json    给脚本 / CI 看：结构化数据
  build-baseline.json  下次构建体积对比的内部参照（仅在跑过 --build 后生成）

建议把 .dh-doctor/ 加入 .gitignore。

不想翻终端时，直接打开 report.html 看首屏、性能和优先级；需要完整依据时，打开 report.md；需要给 Agent 修复时，打开 tasks.md。即使用 --json、--score 等方式让终端只输出机器可读结果，这些报告仍会写进输出目录。

常用命令 ​

命令太多时，把常用命令写进 package.json：

{
  "scripts": {
    "doctor": "dh-ai doctor . --verbose",
    "doctor:check": "dh-ai doctor . --scope changed",
    "doctor:release": "dh-ai doctor . --verbose --build"
  }
}

测试或线上页面怎么查 ​

代码扫描之外，Doctor 还可以检查已经能访问的页面。下面这些命令适合在测试环境或上线前使用：

perf 是实验室性能测量，实时扫描需要 Node 22.18+ 和 @unlighthouse/cli；如果已有性能结果，使用 --input 可以直接读取。runtime 需要 Node 18+ 和本机 Chrome 或 Edge。它只访问同站安全链接，不点击按钮或提交表单；截图默认关闭，开启 --screenshots 前请注意截图可能包含业务内容。

交给 Agent 修复 ​

1. 安装 skill ​

推荐走统一 Skill 安装，装完后可在 AI 工具里使用 /vue-doctor：

dh-ai skill init frontend/vue-doctor --tool qoder --scope user

完整安装、触发方式和修复流程见 vue-doctor Skill。

也可以用快捷入口，把同一份 skill 写到常见 Agent 目录：

dh-ai doctor install --dry-run  # 先预览会写入哪些文件
dh-ai doctor install            # 交互选择要使用的 Agent

使用 dh-ai doctor install -y 时，会默认安装给 Codex、DeepSeek 和 Qwen Code；需要 Claude Code 或 Cursor 时，请用不带 -y 的交互安装并勾选。

2. 扫描并修复 ​

dh-ai doctor . --verbose

然后在 DeepSeek、Qwen Code、Claude Code 或 Cursor 里使用 /vue-doctor，或扫描结束后在终端选“交给 Codex / DeepSeek / Qwen Code / 复制 prompt”。

终端交接只会在可交互终端出现；CI 或 Agent 环境会自动跳过。此时直接把 .dh-doctor/tasks.md 交给负责修复的人或 Agent 即可。

Agent 会读 .dh-doctor/tasks.md，按 Top 问题分批修。每批修完再跑：

dh-ai doctor . --scope changed

适合交给 Agent 的问题通常是局部、机械、可复检的改动，比如补稳定 key、给图片补 alt、给外链补 rel、把全量 lodash 改成按需引入。

安全、权限、接口封装、路由兜底、构建失败这类问题，建议先由人确认边界，再让 Agent 改具体代码。

项目配置 ​

大多数项目不用配。只有“生成代码要跳过”“某条规则太吵”时才需要。在项目根目录建 doctor.config.json：

{
  "ignore": {
    "files": ["src/generated/**"],
    "rules": ["no-v-html"]
  }
}

也支持写在 package.json 的 dhAiDoctor 字段里。

doctor 会按下面顺序合并配置：

• package.json 里的 dhAiDoctor
• package.json 里的 vueDoctor
• doctor.config.json
• vue-doctor.config.json（同名规则以后面的设置为准）

常用字段只有三个：ignore.files 跳过文件，ignore.rules 关闭规则，rules 调整单条规则级别。

发版前怎么用 ​

默认扫描不会执行构建，速度更快。发版前建议加 --build：

dh-ai doctor . --verbose --build

这会先执行项目的 build 脚本，再检查真实产物。构建失败不会让 doctor 直接中断，它会把失败原因写进报告，方便先修构建。

如果项目构建很慢，可以调长等待时间：

dh-ai doctor . --build --build-timeout 300

边界 ​

• 只支持 Vue 项目，要有 vue 依赖或 .vue 文件。
• 默认不跑构建；查拆包、大文件请加 --build。
• 诊断是线索，不是判决；修之前看一眼对应文件。
• 页面性能体检和运行巡检都不等于真实用户监控，运行巡检也不能代替完整的交互流程测试。

常见问题 ​

dh-ai doctor 和 ai-cli doctor 有区别吗？ ​

功能没有区别。正式命令是 dh-ai doctor，ai-cli doctor 只用于兼容旧脚本。

为什么我跑出来没有可视化报告？ ​

先看终端底部有没有 可视化报告 路径。默认路径是 .dh-doctor/report.html。如果传了 --output-dir，就去指定目录找。

为什么 --scope changed 没有扫出问题？ ​

它只看相对基线新增的问题。默认会优先找 prod，也可以手动指定：

dh-ai doctor . --scope changed --base dev

规则误报怎么办？ ​

先确认是不是测试、mock、fixture、生成代码或历史包袱。如果确实不需要检查，用 ignore.files 或 ignore.rules 收敛，不要为了消掉提示去改业务行为。

能在 CI 里用吗？ ​

可以。CI 里建议用结构化输出：

dh-ai doctor . --json --json-compact --no-interactive

CI 会自动跳过终端交接选择；--no-interactive 用来明确表达这一点，便于团队统一脚本行为。

联系与支持 ​

工具属于 @szhn/ai-cli 的 doctor 子命令。如需反馈规则误报、报告展示或接入问题，请联系负责人 肖龙。