编码代理集成

dowsing 的设计把编码代理当作首要使用者。面向代理的接口是先做的，面向人的表格与报告在后。

为什么代理优先

CodeScene 设计时的前提是「技术负责人看仪表盘」。今天，是 Claude Code 这样的代理在决定重构什么，并且动手去做。

代理不需要一条「这个文件很复杂」的告警。它需要的是有依据的优先级顺序。dowsing 正是以结构化数据返回这个。

没有 MCP 服务器

Phase 1 实现过，但在 2026-07-31 删除了。它暴露的每个 tool 都与一个 CLI 子命令一一对应，而代理本来就能执行 shell。为同一件事维护两套接口只会增加成本；另一方面，MCP 的 tool 定义会常驻上下文，而实际调用在一次会话中只有一两次。

留下来的东西更小，覆盖面却更广。

dowsing --help

这份输出就是唯一权威：命令与选项列表之后，还有表格无法表达的部分——dowsing 对仓库的前提要求、输出格式、退出码，以及缓存行为。没有单独的 --agent-help：代理本来就会敲 --help，多一个标志只会让命令列表变成两处维护并逐渐失真。

每个命令都支持 --json，所以代理读的是数据，而不是排好版的表格。

安装 Agent Skill

CLI 本身就能用。可选的 Agent Skill 让兼容的代理知道何时该用 dowsing，更重要的是——怎么读返回的数字。

gh skill install yhay81/dowsing dowsing --agent claude-code --scope user

把 claude-code 换成你的宿主：codex、cursor、github-copilot、opencode、cline、kiro-cli 或 windsurf。想让代理自己安装，就让它读 install-agent.md。

skill 里不写任何选项（那是 --help 的职责；抄一份只会在 CLI 变更时变成谎言）。它承载的是解释：

• score 为 0 的文件不要建议重构，无论它多复杂——没人碰它，改了也没有回报
• 发现 hidden coupling 一定用 dowsing why 求证——复制粘贴的代码和刻意约定的协议，在数字上完全一样
• 不要按面值接受 churn——effectiveRatio 偏低说明是重命名把它撑起来的
• health 必须连同扣分明细一起给出——只说「health 4.9」无法据此行动
• bus factor 是风险，不是对个人的评价

告诉仓库，而不只是告诉你的宿主

Skill 是按宿主安装的，只能影响安装者自己的代理。写进 AGENTS.md 的一行则随仓库传播——在这个仓库里工作的任何宿主的代理都会读到，包括从没听说过 dowsing 的那些。

npx dowsing init            # 向 AGENTS.md 追加 dowsing 小节
npx dowsing init --dry-run  # 先看看会写入什么

重复执行不会重复添加，只会更新那一节。

每次结果都会附带的信息

分析结果里包含这次分析是在什么条件下跑的。

{
  "meta": {
    "git": {
      "since": "12 months ago",
      "commitCount": 3920,
      "exclusions": { "merges": 6, "bots": 0, "formatOnly": 1 },
      "shallow": false
    }
  },
  "config": { "complexity": "loc" }
}

这样代理报告的就不是「它被改了 255 次」，而是「最近 12 个月 255 次，已排除合并与 bot 提交」。

重复调用很便宜

大仓库首次分析也只要几秒。结果缓存在 .dowsing/cache，以 HEAD、工作区状态和分析选项为键——所以同一会话里 hotspots、coupling、why 连着敲都是秒回。

命中缓存时会在 stderr 明确说明，而不会伪装成一次新的分析。改动较大之后加上 --refresh。

dowsing 不会改你的代码

改代码是代理的工作。dowsing 负责在动手前指出「改哪里」，在改完后测量「是否奏效」。

dowsing diff origin/main

它会在两个版本上分别重新测量每个变更文件，报告复杂度实际的变化。它不关心是谁改的，所以人写的提交、代理的重构、CI 里的 PR 都一样适用；变差时也会照实报告。