前言¶
在 DSH 里跑 Agent、装全局 CLI、用 Homebrew 和 npm 维护工具链时，「要不要升、升了会不会牵动别的包」往往比「怎么升」更费时间。常见做法是逐个 brew outdated、npm outdated 或凭感觉全量升级，容易把依赖库当成待升级工具，或在共享依赖上踩版本冲突。
cli-doctor（维护者 MaxHou-infinity）面向同一痛点：对本机 CLI 与开发环境做只读体检，按生态列出版本、可用更新与依赖影响，并给出可复制的手动升级命令，不替你执行升级。同仓库还提供 Codex 侧栏插件与 Agent Skill；下文聚焦 DeepSeek Harness（DSH）侧栏插件 dsh-cli-doctor。
这是什么¶
cli-doctor 优先支持 macOS，扫描 Homebrew、npm 全局包、Python/pip、Rust、Bun、uv 以及自更新类 CLI，把「工具」与「被工具带进来的依赖库」分开，输出人读或 Agent 可解析的报告。当前统一版本为 v0.2.0（Agent Skill、CLI 与 Codex 侧栏插件同号）。
分类上属于 DSH 社区目录中的客户端插件：在左侧栏打开面板，点「一键诊断当前状态」才会运行检查；安装过程本身不会诊断或升级本机工具。
核心功能¶
下面介绍与 DSH 使用直接相关、且资料中已写明的能力。
只报不升¶
不会执行 brew upgrade、npm i -g、pip install -U 等操作。报告里的命令需你逐项确认后再执行。
工具与依赖分层¶
采集结果按两层组织：工具类（Homebrew leaves、npm 全局、Python CLI、Rust/Bun/uv、自更新 CLI 等）与依赖包类（共享库与底层依赖，默认摘要展示）。Agent Skill 侧对待升级项使用固定七字段（工具名称、当前/最新版本、手动升级命令、作用、耦合、风险）；CLI 负责采集事实，Skill 负责决策型报告，两者不混为一层。
侧栏诊断与底层命令¶
DSH 面板触发的是 bin/check.js --json --no-update，与独立 CLI 共用同一套逻辑。页面会把「有可用更新」和「建议更新」分开，并结合已装 Homebrew formula、npm 全局顶层包及当前 python3 解释器中的发行包元数据做依赖影响判断；大版本变化会要求你自行做兼容验证。完整联网查询可能持续数分钟；未联网核验项会标为「待核验」，不会在 --fast 等模式下误报为「全部最新」。
覆盖范围（摘要）¶
| 生态 | 检查内容 |
|---|---|
| Homebrew | leaves 工具、outdated 依赖、服务重启提示 |
| npm | 全局包、当前/最新版本、大版本跳跃 |
| Python/pip | 通过 console_scripts 区分 CLI 与库依赖 |
| Rust | rustup 工具链、cargo install 工具 |
| Bun / uv | 本体版本与升级命令、uv tools |
| 自更新 CLI | hermes、agy、bsk 等资料中列出的本地工具 |
安装与启用¶
DSH 侧栏与 Codex 插件、Agent Skill 是三种独立安装方式，互不影响；DSH 实现自包含在仓库 dsh/ 目录，npm 包名为 dsh-cli-doctor。
方式一：通过 Agent 安装（推荐按官方提示词）¶
把 README 中的整段「DSH 侧栏」提示词粘贴到 DSH 任意对话，由 Agent 通过 plugin_manager 安装并核对。安装会写入 profile 目录，需你批准一次；不要手工改写 profile 的 cordis.patch.yml。
方式二：界面或 CLI¶
- 左侧栏 Plugins → Add plugin，填写
dsh-cli-doctor（本地开发可填dsh/的绝对路径）。 - 或在终端执行（将
<profile>换成你的 profile 名）：
dsh plugin --profile <profile> add dsh-cli-doctor
npm 包为预构建发布，安装时不跑构建脚本。DSH 侧栏不做热更新，升级需先卸载再重装；desktop profile 一般由桌面应用持有，安装后通常需要重启 DSH。若出现 incompatible-version，应先核对 peers 与运行时版本，资料明确不建议用 set_version_exemption 强行放行。
运行环境：Node.js 18+。侧栏插件启用后，从左侧 CLI Doctor 入口打开面板，点击「一键诊断当前状态」开始只读检查。
典型用法¶
侧栏一键诊断¶
安装并（如需）重启 DSH 后，打开 CLI Doctor，点「一键诊断当前状态」。这与在仓库外直接跑采集器等价于带 --json --no-update 的检查，不会主动 brew update。
不装侧栏，仅跑 CLI¶
无需 Skill 也可从 GitHub 拉取并执行采集器（适合脚本或临时查看）：
# 人类可读的采集摘要
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor
# 给 AI / Agent 的结构化数据
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --json
常用变体：
# 跳过网络刷新与版本比对，快速看本地清单
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --fast
# 只跳过 Homebrew 索引刷新
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --no-update
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --help
npx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --version
在对话里用自然语言（需另装 Agent Skill）¶
若已用 skills CLI 安装同仓库的 cli-doctor Skill，可在新对话中用例如「帮我检查 CLI 类工具版本状态」或显式 使用 $cli-doctor 检查我的 CLI 工具版本。Skill 与 DSH 侧栏插件安装相互独立。
Skill 安装示例（来自 README）：
npx skills@latest add MaxHou-infinity/cli-doctor
适用场景与注意¶
适合谁：经常在 macOS 上维护多生态 CLI、希望在升级前先看依赖与风险地图的 DSH 用户；需要把版本事实交给 Agent 做七字段升级决策报告时，可配合 Agent Skill 与 --json 输出。
权限与安全：诊断以当前 DSH 进程权限读取本机环境；安装前应自行查看 GitHub 仓库 源码与 MIT 许可证。插件只读，但仍会访问本机包管理器与解释器信息；联网比对版本时可能耗时较久。
边界：不扫描其他项目目录、虚拟环境或 lockfile；不验证目标版新增依赖与运行时 API 兼容性。正在运行的 CLI、自带服务和大版本跳跃项，资料建议避开运行期并单独复核。
结尾¶
cli-doctor 把「升级前地图」做成 DSH 左侧栏里的只读体检：分清工具与依赖、标出待核验与建议更新，命令给你复制，执行权留在你手里。社区目录页：cli-doctor（SkillHub）；源码与完整说明：MaxHou-infinity/cli-doctor。
