CLI 命令

npx dowse <command> [options]

通用选项

大多数命令都可用。

选项	默认值	说明
--since <date>	12 months ago	git 时间窗口的起点。任何 git 能解析的表达式。
--until <date>	—	git 时间窗口的终点
--complexity <type>	loc	复杂度代理：loc | cyclomatic | cognitive
--json	false	将 JSON 写到标准输出

---

analyze

分析 workspace，写出 .dowse/dowse.json，并打印摘要。

dowse analyze [dir]

选项	默认值	说明
--top <n>	10	显示的 hotspot 数量
--out <path>	.dowse/dowse.json	输出路径
--verify-churn [n]	关闭	用 AST 验证前 N 个文件（默认 20）的改动频率
--min-degree <n>	0.3	最小耦合度（也接受 30 这样的百分比写法）
--min-shared <n>	5	耦合的最小共享提交数

加上 --json 时报告输出到标准输出，不写文件。

---

hotspots

只打印 hotspot 排名。

dowse hotspots [dir] --top 15

---

coupling

显示变更耦合。

dowse coupling [dir] --hidden

选项	默认值	说明
--hidden	false	只显示隐藏耦合（无依赖的共变更）
--files	false	同时显示文件粒度的耦合
--top <n>	20	行数
--min-degree <n>	0.3	最小耦合度
--min-shared <n>	5	最小共享提交数

调低阈值以捞回遗漏

两个非常活跃的包分母很大，会把耦合度压下去。--min-degree 15 常常能捞出真实的配对。

---

why

解释两个对象为什么一起改动。

dowse why <a> <b>

每个对象可以是包名、文件路径或目录——按这个顺序解析（包名 → 精确路径 → 前缀匹配）。

dowse why @acme/admin-web @acme/doctor-web
dowse why packages/ui src/api --since "6 months ago"

选项	默认值	说明
--cwd <path>	.	要分析的目录
--top <n>	10	显示的文件对数量
--commits <n>	10	代表性提交数量

---

health

显示 Code Health 与坏味道明细。

dowse health [dir]
dowse health --file src/foo.ts    # 单个文件的扣分明细

选项	默认值	说明
--file <path>	—	只显示单个文件的明细
--top <n>	10	行数

---

knowledge

显示 ownership 与 bus factor。

dowse knowledge [dir] --top 15

按包给出 bus factor、贡献者列表，以及主要开发者离开后哪些文件会无人负责的模拟。

---

report

生成自包含的单文件 HTML 报告。它不发起任何外部请求，数据已内嵌，可以直接分享。

dowse report [dir] --out report.html

---

diagnose

用 LLM 诊断排名靠前的 hotspot（需要 Claude Code）。

dowse diagnose [dir] --top 3

选项	默认值	说明
--top <n>	3	诊断数量（成本与之成正比）
--model <model>	—	使用的模型

这是判断，不是测量值

请与确定性指标分开处理。

---

fix

让代理实际修复 hotspot，验证结果，并实测复杂度差值（需要 Claude Code）。

dowse fix [target]
dowse fix src/foo.ts --apply

选项	默认值	说明
--apply	false	把通过验证的修改保留在工作分支上
--cwd <path>	.	要分析的目录
--top <n>	1	未指定目标时处理的数量
--max-diff-lines <n>	400	可接受的最大 diff 行数
--skip-diagnosis	false	跳过诊断直接修复
--skip-verification	false	跳过类型检查与测试（不推荐）
--typecheck-command <script>	自动推断	类型检查对应的 package.json 脚本名
--test-command <script>	自动推断	测试对应的 package.json 脚本名

默认是空跑。 安全阀详见闭环修复。

---

check

质量门禁。有违规时退出码为 1。

dowse check [dir] --min-file-health 3

选项	说明
--min-file-health <n>	文件 health 下限
--min-package-health <n>	包 health 下限
--max-hotspot <n>	hotspot 分数上限（0–1）
--min-bus-factor <n>	包 bus factor 下限
--max-hidden-coupling <n>	隐藏耦合数量上限
--sarif <path>	输出 SARIF 供 GitHub Code Scanning

默认什么都不检查

只有你显式指定的阈值才会被执行。请先测量现状，从今天能通过的水平起步。

---

diff

评估自某个基线以来的改动是否踩到了高风险区域。

dowse diff <base>
dowse diff origin/main --markdown

选项	默认值	说明
--head <ref>	HEAD	比较目标
--cwd <path>	.	要分析的目录
--markdown	false	把 PR 评论用的 Markdown 输出到标准输出
--out <path>	—	把 Markdown 写入文件

---

mcp

以 stdio 启动 MCP 服务器。

dowse mcp [dir] --since "6 months ago"

参见编码代理集成与 MCP 参考。