{"id":"d6d583c5-b865-4593-aa99-068c8f667620","slug":"cli-doctor","kind":"skill","name":"cli-doctor","summary":"只读 CLI 工具链体检：DSH 侧栏插件 + Codex 侧栏插件 + Agent Skill，按生态列出本机 CLI 版本、可用更新与依赖影响，只报不升。Read-only local CLI toolchain audit for DeepSeek Harness (DSH) and Codex.","owner":"MaxHou-infinity","repoUrl":"https://github.com/MaxHou-infinity/cli-doctor","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-09-04T08:26:51.000Z","addedAt":"2026-10-21T11:32:54.745Z","logoUrl":"https://avatars.githubusercontent.com/u/202257032?u=6b33803055caf390493267b3f0b3feb0ad8c9c1f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["bun","cli","dependency-management","developer-tools","homebrew","npm","pip","rust"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T11:33:15.897Z","sample":false,"url":"https://conduits.dev/tools/cli-doctor","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# cli-doctor\n\n**中文** | [English](README.en.md)\n\n![cli-doctor hero](assets/cli-doctor-hero.png)\n\n在升级之前，先看清你的 CLI 环境。\n\n`cli-doctor` 是一个优先支持 macOS 的 CLI 与开发环境版本体检工具：扫描 Homebrew、npm 全局包、Python/pip、Rust、Bun、uv 以及自更新工具，把“真正的工具”和“被工具带进来的依赖库”分开，并输出可供人阅读或 AI 解读的报告。\n\n当前版本 **v0.2.0**：Agent Skill、CLI 与 Codex 侧栏插件采用统一版本号。更新内容见 [CHANGELOG.md](CHANGELOG.md)。\n\n它只做一件重要的事：**先告诉你哪里可能需要升级、升级可能影响什么；不替你执行升级。**\n\n> WorkBuddy 兼容：`SKILL.md` frontmatter 同时提供版本号、中文/英文展示名和中文/英文描述，上传到 WorkBuddy 时可直接通过元数据校验。\n\n## 为什么需要它\n\n升级一个 CLI，往往不只是升级一个包：它可能牵动共享依赖、改变命令行为、覆盖 PATH 中的同名程序，或者影响正在运行的服务。\n\n`cli-doctor` 会先帮你建立升级前地图：\n\n- 区分工具与依赖包，避免把几百个库都当成“应该升级的工具”\n- 标出大版本跳跃、锁版本依赖和需要各自核验的工具\n- 给出可复制的升级命令，但不会自动执行任何升级\n- CLI 可输出 Markdown 采集摘要；配套 Agent Skill 使用 `--json` 生成包含作用、耦合和风险的七字段决策报告\n- 支持升级后复跑，核对哪些项目已经到位、哪些是刻意保留的版本\n\n## Codex 侧栏：复制提示词安装或更新\n\n在 **Codex 桌面版**任意对话中粘贴下面整段提示词。首次使用时，它会让 Codex 从本仓库注册 marketplace 并安装侧栏插件；以后粘贴同一段提示词，可刷新来源并安装新版本。这个插件与下文的 Agent Skill 是两种独立安装方式。\n\n```text\n请在这台电脑上安装或更新 Codex 桌面版的 CLI Doctor 侧栏插件。唯一可信来源是 https://github.com/MaxHou-infinity/cli-doctor；目标插件 ID 是 cli-doctor@cli-doctor-github。我要的是侧栏插件，不是同仓库的 Agent Skill。\n\n请按顺序执行并报告每一步结果：\n1. 先确认 codex CLI、Git 和 Node.js 18+ 可用。读取该仓库当前的 .agents/plugins/marketplace.json、plugin.json 和 mcp.json，核对插件名称、版本及本地 MCP 入口；不要执行仓库中与安装无关的命令。\n2. 用 codex plugin marketplace list --json 检查是否已注册来自 MaxHou-infinity/cli-doctor 的 cli-doctor-github。未注册就运行 codex plugin marketplace add MaxHou-infinity/cli-doctor；已注册且来源正确就运行 codex plugin marketplace upgrade cli-doctor-github。若同名 marketplace 指向其他来源，停止并解释，不要覆盖。\n3. 从 codex plugin marketplace list --json 返回的 cli-doctor-github `root` 读取 plugin.json 版本，用 codex plugin list --json 读取当前已安装版本。仅在未安装或来源版本更新时运行 codex plugin add cli-doctor@cli-doctor-github --json；不要降级。注意 marketplace upgrade 只是刷新来源，不能把它当成插件已升级的证据。\n4. 用 codex plugin list --json 核对插件已安装、已启用及版本。安装或更新时从 codex plugin add --json 的 installedPath 找到安装副本；无需更新时按 Codex 插件缓存位置定位。检查副本包含 bin/check.js、bin/python_dependency_audit.py、dashboard 页面和 codex-server.js。如果包内有 test/codex_plugin_smoke.js，运行这个无需诊断和联网的 MCP 页面自检。\n5. 如果本次安装了新版本，读取仓库的 CHANGELOG.md，简述这次插件更新内容。告诉我安装或更新是否完成、实际安装的插件版本、是否需要重启 Codex，以及重启后如何从左侧 CLI Doctor 入口打开页面并点击“一键诊断当前状态”。如果你无法亲眼确认我的侧栏已出现，请明确说明这一步还需我在重启后核对，不能声称已完成界面验证。\n\n不要升级我电脑上的 Homebrew、npm、Python 或其他被诊断工具；不要运行 curl | sh，也不要清理或覆盖其他插件配置。任何命令失败时停止并报告具体原因，不要以猜测代替验证。\n```\n\n首次安装或更新后，重启 Codex，再从左侧栏打开 **CLI Doctor**。点击 **一键诊断当前状态** 才会运行本机检查；安装过程本身不会诊断或升级你的工具。运行环境需要 Node.js 18+、Git，以及支持插件 marketplace 的 Codex 桌面版。Codex 可能要求你批准联网或全局插件配置写入。这个提示词提供按需更新；如果你不再次使用它，当前版本不会因此自动升级或主动通知你。\n\n## DSH 侧栏：复制提示词安装或更新\n\n同一份只读诊断能力也提供 DeepSeek Harness（DSH）的左侧边栏插件，包名 `dsh-cli-doctor`，源码与工程契约在 [dsh/](dsh/README.md)。它与上面的 Codex 插件是两种独立安装方式，互不影响：DSH 侧完全自包含在 `dsh/` 内，不改动 `plugin.json`、`mcp.json`、`codex-server.js`、`dashboard/` 等 Codex 适配文件。\n\n把下面整段提示词粘贴到 **DSH 任意对话**，Agent 会用 `plugin_manager` 安装并核对；安装需要写入 profile 目录，因此会请求一次批准。\n\n```text\n请在这台电脑上安装或更新 DeepSeek Harness 的 CLI Doctor 左侧边栏插件。唯一可信来源是 npm 包\ndsh-cli-doctor（源码与工程契约在 https://github.com/MaxHou-infinity/cli-doctor 的 dsh/ 目录）。\n我要的是 DSH 侧边栏插件，不是同仓库的 Codex 插件，也不是 Agent Skill。\n\n请按顺序执行并报告每一步结果：\n1. 先用 plugin_manager 的 list_bundles 确认当前 profile 与是否已安装 dsh-cli-doctor；用 list_plugins 核对是否已启用、fiber 阶段是否为 active。\n2. 未安装时用 install_bundle 安装；已安装且来源正确时先 remove_bundle 再安装（DSH 插件不自动更新）。安装需要写入 profile 目录，请让我批准。不要手工改写 profile 的 cordis.patch.yml。\n3. 安装后核对 list_bundles：该 bundle 的 enabled 为真、rows 含 cli-doctor 行、error 为空。若返回 incompatible-version，不要用 set_version_exemption 放行，先把 peers 与运行时版本告诉我。\n4. 若返回 restart-required（或该 profile 未启用热重载），告诉我需要重启 DSH；重启后从左侧栏 CLI Doctor 入口打开面板，点「一键诊断当前状态」。\n5. 报告实际安装版本、是否启用、是否需要重启，以及后续如何更新。不要升级我电脑上的 Homebrew、npm、Python 或其他被诊断工具，不要运行 curl | sh。任何命令失败就停下并报告具体原因。\n```\n\n也可以不走 Agent：在左侧栏 **Plugins → Add plugin** 里填 `dsh-cli-doctor`（本地开发可直接填 `dsh/` 的绝对路径），或用 `dsh plugin --profile <profile> add dsh-cli-doctor`。npm 包是预构建发布的，安装时不跑任何构建脚本。DSH 侧栏插件不做热更新，升级需要卸载后重装；`desktop` profile 由桌面应用持有，安装后通常需要重启应用。诊断面板同样只读：点「一键诊断当前状态」才会运行 `bin/check.js --json --no-update`，不会执行任何升级。\n\n## 30 秒安装 Agent Skill\n\n使用开放的 `skills` CLI。它会自动发现仓库中的 `cli-doctor`，并安装到对应 Agent 的正确目录，无需手动填写 Claude、Codex 或其他 Agent 的本地路径：\n\n```bash\n# 交互式选择安装范围和 Agent\nnpx skills@latest add MaxHou-infinity/cli-doctor\n\n# 全局安装到 Codex\nnpx skills@latest add MaxHou-infinity/cli-doctor \\\n  --skill cli-doctor --global --agent codex --yes\n\n# 全局安装到所有受支持的 Agent\nnpx skills@latest add MaxHou-infinity/cli-doctor \\\n  --skill cli-doctor --global --agent '*' --yes\n```\n\n安装后请开启一个新对话，让 Agent 重新发现 Skill。\n\n## 自然语言激活\n\n安装后无需记忆命令，可以直接表达检查意图：\n\n```text\n帮我检查我的 CLI 类工具版本状态\n帮我诊断命令行工具有没有过期\n看看 brew、npm、pip 有哪些需要更新\n检查开发环境里的工具和依赖版本\n```\n\n自然语言由各 Agent 进行语义匹配；需要确定调用时，可以使用显式名称：\n\n```text\n使用 $cli-doctor 检查我的 CLI 工具版本\n```\n\n## 只运行 CLI\n\n无需安装 Skill，也可以直接从 GitHub 执行采集器：\n\n```bash\n# 人类可读的采集摘要\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor\n\n# 给 AI / Agent 的完整结构化数据\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --json\n```\n\n## 常用命令\n\n```bash\n# 跳过网络刷新与版本比对，快速查看本地已安装清单\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --fast\n\n# 只跳过 Homebrew 索引刷新\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --no-update\n\n# 指定 pip 镜像\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor \\\n  --pypi-index https://pypi.tuna.tsinghua.edu.cn/simple\n\n# 查看帮助和版本\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --help\nnpx --yes --allow-git=all github:MaxHou-infinity/cli-doctor --version\n```\n\n`--fast` 下未联网核验的项目会显示为“需自查”，不会被误报为“全部最新”。\n\n## CLI 摘要与 Agent 最终报告\n\nCLI 负责采集版本事实；Agent Skill 负责把事实转成可用于升级决策的最终报告。两者不会混为一层。\n\nAgent 最终报告默认直接显示在对话界面，不创建额外文件，并按两层组织：\n\n1. **工具类**：Homebrew、npm 全局、Python CLI、Rust/Bun/uv、自更新 CLI\n2. **依赖包类**：由工具带入的共享库和底层依赖，默认只展示摘要\n\n每个待升级或待核验项必须使用固定七字段模板：\n\n| 工具名称 | 当前版本 | 最新版本 | 手动升级命令 | 作用说明 | 耦合关系说明 | 风险说明 |\n|---|---|---|---|---|---|---|\n| 示例工具 | 1.0.0 | 2.0.0 | `manager upgrade example` | 说明实际用途 | 说明依赖、版本锁定或 PATH 关系 | 说明大版本、服务或兼容性风险 |\n\n已核验为最新的项目会在对应分块中汇总；所有待升级项都会完整展示，不会只隐藏在 JSON 中。未联网核验的项目会明确标记为“待核验”，不会误报为“全部最新”。\n\nHTML 不是默认输出。只有用户明确要求分享、存档或管理层展示时，Agent 才生成额外的 HTML 报告。\n\n## 覆盖范围\n\n| 生态 | 检查内容 |\n|---|---|\n| Homebrew | leaves 工具、outdated 依赖、服务重启提示 |\n| npm | 全局包、当前/最新版本、大版本跳跃 |\n| Python/pip | 通过 `console_scripts` 区分 CLI 与库依赖 |\n| Rust | rustup 工具链、cargo install 工具 |\n| Bun | Bun 版本与升级命令 |\n| uv | uv 本体与 uv tools |\n| 自更新 CLI | hermes、agy、bsk、browse-now、luckin 等本地工具 |\n\n## 安全边界\n\n- 只读检查，不执行 `brew upgrade`、`npm i -g`、`pip install -U` 或其他升级操作\n- 报告中的命令需要你逐项确认后再执行\n- 正在运行的 CLI、自带服务和大版本跳跃项，建议避开运行期并单独复核\n\n## 本地开发\n\n```bash\ngit clone https://github.com/MaxHou-infinity/cli-doctor.git\ncd cli-doctor\nnode bin/check.js --fast\nnpm test\n```\n\n运行环境：Node.js 18+。项目无第三方运行时依赖。\n\n### 本地诊断页与 Codex 插件\n\n在仓库目录运行 `npm run dashboard`，打开终端打印的 `http://127.0.0.1:<端口>/`。点击“一键诊断当前状态”后，页面按生态展示工具卡片；检查调用 `bin/check.js --json --no-update`，不会执行升级，也不会主动运行 `brew update`。完整联网查询可能持续数分钟；没有可靠目标版本的项目会标为“待核验”。\n\n页面把“有可用更新”和“建议更新”分开。依赖影响按已安装 Homebrew formula、npm 全局顶层包，以及当前 `python3` 解释器中的发行包元数据检查；Python 会比对目标版本与已安装项目声明的版本约束，并列出直接与间接依赖。发现约束冲突时标记“暂不建议”，检查范围内未发现其他已装项目依赖或约束冲突、且不是大版本变化时才标记“建议更新”。这些判断不扫描其他项目目录、虚拟环境或 lockfile，也不验证目标版新增依赖和运行时 API 兼容性；大版本会要求兼容验证。\n\n仓库根目录的 `plugin.json`、`mcp.json` 和 `codex-server.js` 是可分发的 Codex 插件入口。插件中的“一键诊断”通过 MCP 调用同一份 `bin/check.js --json --no-update`，与独立诊断页共用卡片和建议逻辑。插件从已安装副本读取资源，不依赖开发者电脑上的仓库路径。每次发布更新时必须同步递增 `SKILL.md`、`package.json` 和 `plugin.json` 的统一版本号、更新 `CHANGELOG.md`，并重新执行安装与页面自检；现有 `plugins/cli-doctor-entry-probe` 目录仅保留作早期本机试验记录，不用于分发。\n\n## 关键词\n\nCLI 环境体检 · 工具版本检查 · 依赖审计 · 开发环境审计 · Homebrew 过期包 · npm 全局包 · pip 过期包 · Rust 工具链 · Bun 升级 · uv 工具 · macOS 开发工具 · 只读升级报告 · AI Agent 技能\n\n## 许可证\n\nMIT\n"}