快速开始
你需要什么
- Node.js 22 或更高版本
- 一个有 git 历史的仓库 —— 改动频率就来自这里
- 一个 TypeScript 代码库（monorepo 或单包都可以）
浅克隆下无法工作
用 git clone --depth 1，或大多数 CI 的默认设置，历史会被截断，改动频率、hotspot 和耦合就全都是错的。dowsing 会检测并警告，但它打印的数字不可信。在 CI 中请设置 fetch-depth: 0。
跑起来
无需安装。
bash
npx dowsing analyze几秒之内你会得到这样的输出——2,238 个文件、3,920 个提交的 monorepo 约需 7 秒。
Discovering workspace... 40 packages (pnpm)
Reading git history (since 12 months ago)... 3920 commits
excluded: 6 merge, 0 bot, 1 format-only, 0 ignore-revs
Parsing AST (oxc)... 2238 files
Building package graph... 40 packages, 168 edges
Computing change coupling... 500 file pairs, 25 package pairs (1 hidden)
⚠ Top hotspots (complexity=loc):
┌───┬─────────────────────────────┬───────┬────────┬────────┬─────────┐
│ # │ file │ score │ freq │ cx │ commits │
├───┼─────────────────────────────┼───────┼────────┼────────┼─────────┤
│ 1 │ services/api/src/runtime.ts │ 0.999 │ 100pct │ 100pct │ 255 │
└───┴─────────────────────────────┴───────┴────────┴────────┴─────────┘
📌 Top findings (where to look first):
🔥 services/api/src/runtime.ts — 改动频繁且复杂（255 commits, 857 LoC）
🔗 @acme/admin-web ↔ @acme/customer-web — 无依赖却一起改动了 91 次完整结果同时写入 .dowsing/dowsing.json。
为什么要打印排除了什么
每次运行都会声明剔除了合并提交、bot 提交和纯格式化提交。悄悄排除会让你把输出读成「全部分析过了」——而一个你看不出范围的数字，是无法据以行动的。
深入排查
它们为什么会一起改动？
出现隐藏耦合时，去看背后到底是什么。
bash
npx dowsing why @acme/admin-web @acme/customer-web■ 最常一起改动的文件对
src/lib/server-api.ts ↔ src/lib/server-api.ts 13
src/app/(authed)/page.tsx ↔ src/app/(authed)/page.tsx 15
■ 代表性提交（从新到旧）
c23db79c 2026-07-09 给两个 Web 应用都加上会话过期后的重新登录引导 [A:3 B:6 files]两边有同名文件，同样的修改被手工复制。这是抽取到共享包的候选。
那个改动频率是真的吗？
bash
npx dowsing analyze --verify-churn它比对 AST，把真实修改与重命名、格式化区分开。
🔍 Churn 验证（AST 比对，前 20 个文件）:
568 个版本中有 513 个是实质修改（55 个虚假：重命名 12 / 仅格式化 35 / 内容未变 8）
⚠ customer-detail-panel.tsx: 42% 的 churn 并未改变语义它需要对每个版本执行 git show，因此是可选项，且只针对前 N 个文件。
这个文件为什么复杂？
bash
npx dowsing health --file src/foo.ts health: 4.9 / 10 (仅按代码行数的基线: 10.0)
从 10.0 起的扣分:
-3.00 认知复杂度过高 (50 > 阈值 15, severity 1.00)
→ validateConfig (cognitive=50, L3)
-2.13 复杂函数 (27 > 阈值 10, severity 0.85)
→ validateConfig (cyclomatic=27, L3)LoC 基线是 10.0，health 却是 4.9——一个短小但密集的文件。只数行数的指标会完全错过它。
知识集中在哪里？
bash
npx dowsing knowledge按包给出 bus factor，以及主要开发者离开后会有多少文件无人负责。
从代理中使用
没有需要注册的东西。代理本来就能执行 CLI，而接口只有一条命令。
bash
npx dowsing --help再装上可选的 Agent Skill，代理就知道什么时候该用它，以及怎么读这些数字：
bash
gh skill install yhay81/dowsing dowsing --agent claude-code --scope user之后就可以在会话中直接问「这个仓库接下来该重构哪里？」，得到基于分析结果的回答。参见编码代理集成。
确认重构是否奏效
bash
npx dowsing diff origin/main它会在两个版本上重新测量每个变更文件，报告复杂度实际的变化。
📉 复杂度实测（base → head）:
cognitive -41 / cyclomatic -22 / LoC -111谁改的都无所谓——你自己、代理，或者 CI 里的 PR。参见实测改善效果。