Agent 工具的 doctor 不能只会“正常运行”：一次配置优先级排查记录

给 Agent 使用的开发工具，通常都会提供 doctor 或类似的自检命令。它看起来只是一个辅助功能，但当 Agent 遇到环境问题时会优先读取这段输出，因此它实际上承担了“事实来源”的角色。只要自检结果和真实执行路径不一致，Agent 就可能沿着错误方向继续操作。

最近阅读开源项目 workvault 时，我遇到了一个很典型的问题：Python 入口的 doctor 与 Node.js CLI 对 vault 目录采用了不同的优先级。

项目文档约定的顺序是：

--vault > WORK_VAULT_VAULT > 配置文件 > 默认目录

Node.js CLI 的实现也符合这个顺序：

const v = a["vault"] ?? envVault ?? config.vault;

但 Python 包装脚本里的 doctor 写成了：

vault = vault_override or cfg_vault or env_vault or default_vault

两者只在“配置文件和环境变量同时存在”时暴露差异。

为了验证，我创建了两个目录，分别作为“配置文件指定目录”和“环境变量指定目录”，然后同时设置两项配置：

mkdir -p /tmp/wv-demo/config-vault /tmp/wv-demo/env-vault
cat > /tmp/wv-demo/workvault.config.json <<'JSON'
{"vault":"/tmp/wv-demo/config-vault"}
JSON

WORK_VAULT_VAULT=/tmp/wv-demo/env-vault \
python3 skills/workvault/scripts/workvault_cli.py doctor

doctor 报告的是配置文件中的 /tmp/wv-demo/config-vault；而按文档和 CLI 代码，此时应该使用环境变量中的 /tmp/wv-demo/env-vault。

这个问题值得单独写下来，因为它不是普通的显示错误。若 Agent 把结果写入错误的知识库，通常不会立刻报错：目录存在、权限正常、命令也能成功，只是数据落在了错误位置。这种“成功但对象错误”的问题，比直接失败更难发现。

继续阅读代码后，还能看到第二个类似问题：配置加载函数的注释说会兼容旧配置名，但旧文件实际只在用户主目录被查找，工作目录和仓库根下并没有纳入查找链。单看 doctor 的“配置文件：已找到”，很难意识到这一点。

根因并不复杂：Node.js CLI 和 Python 包装脚本各自维护了一套配置解析逻辑。只要两个入口都直接调用同一个配置解析模块，或者在包装脚本中显式复用 CLI 的解析结果，这类漂移就不容易发生。

修复时我会优先做三件事：

1. 统一 vault 优先级，并让 doctor 输出实际来源。
2. 统一新旧配置文件的查找位置，避免注释、文档和实现各说一套。
3. 用测试覆盖“参数、环境变量、配置文件同时存在”的组合，而不是只测单一配置来源。

这次排查给我的启发是：Agent 工具的自检命令不仅要证明“命令能跑”，还要证明“它看到的配置和真实执行使用的是同一份配置”。对自动化系统来说，可验证的一致性往往比功能数量更重要。