thalixinc/dsh-plugin-vibe-doctor

Vibe Doctor

“告诉我我的应用为什么坏了，用通俗英语解释，并给我最安全的下一步操作。”

Vibe Doctor 是 DeepSeek Harness 的诊断助手插件。它注册了一个面向模型的工具 vibe_doctor，该工具对项目目录执行只读诊断，将可能的根本原因与级联故障区分开，并返回一份通俗英语的 markdown 报告，其中包含建议的下一步操作。

状态： 0.1.0 — 预发布版。基于 DeepSeek Harness 0.1.0-rc.8 包 API（@deepseek-ai/dsh-tools@0.0.1-rc.1、@deepseek-ai/cordis@4.0.1）构建并测试，这些 API 本身也是候选发布版；在 harness 发布稳定版本之前，API 预计还会变动。

适用对象

开发者——尤其是借助 AI 辅助进行开发的“vibe 编码者”——他们遇到构建失败、依赖冲突、缺少配置或开发服务器挂掉，而又不想自己解读原始日志。智能体调用 vibe_doctor，用户得到的是结构化诊断，而不是日志转储。

检查内容（v0.1）

- 项目与框架检测（Next.js、Vite、React、Vue、Svelte、Astro、Express、Fastify、NestJS、Remix、Nuxt）
- 包管理器检测（npm / pnpm / yarn / bun）以及混合 lockfile 冲突
- package.json 有效性、node_modules 缺失/不完整、lockfile 漂移
- JSON 配置文件语法（tsconfig.json、turbo.json、……，兼容 JSONC）
- 环境变量——仅名称和是否存在，绝不涉及值
- Git 状态：仓库是否存在、进行中的合并；启用命令时还包括 git status / 最近提交
- npm-debug.log、yarn-error.log 和 logs/.log 的有界尾部内容
- 开发服务器端口冲突（回环绑定探测）
- 错误归一化（TS 错误、模块未找到、EADDRINUSE、ERESOLVE、语法错误……）以及根本原因与级联的排序

诊断示例

Vibe Doctor diagnosis

Project: /home/dev/my-app

Health summary

❌ The project has errors and is likely broken right now.

Most likely root cause

Dependencies are not installed (node_modules is missing).

- Confidence: high (90%)
- Reasoning: Based on 1 observation(s) from node_modules. This would explain 2 extracted error signature(s).
- Recommended next step: Run your package manager install (e.g. npm install / pnpm install) and retry the failing command.
- Suggested fix: Install dependencies with the package manager the lockfile identifies, then rerun the build.

Probably consequences, not causes

- A required module "react" cannot be found.

Supporting evidence

- [error] package.json declares 4 dependencies but node_modules is missing — dependencies are not installed. _(source: node_modules, collector: dependencies)_
…

Privacy note

All evidence above was collected read-only. Likely secrets are redacted before analysis, and environment variables are reported by name only.

要求

- Node.js ^22.19.0 || >=24.0.0
- 一个 DeepSeek Harness 部署，组合了 @deepseek-ai/dsh-tools（工具注册表）
- 可选：@deepseek-ai/dsh-system-prompt（工具指导部分）和一个 ctx.shell 执行器（只读的 git/包管理器探测）

安装

npm install dsh-plugin-vibe-doctor
或者，在 harness checkout 生态内：
pnpm add dsh-plugin-vibe-doctor

尚未发布到 npm —— 参见 docs/publishing.md。在此之前，从 checkout 安装：npm install /path/to/dsh-plugin-vibe-doctor。

在 DeepSeek Harness 中启用

Cordis 组合是插件行列表。在拥有你的 agent 工具的组合中添加一行（agent 预设的 agent.cordis.yml，或已加载 @deepseek-ai/dsh-tools 的宿主 cordis.yml）：

- id: vibe-doctor
name: 'dsh-plugin-vibe-doctor'
config:
allowCommands: false # 设为 true 以允许通过 ctx.shell 进行只读的 git/pm 探测

对于按会话的 agent 预设，将随附的预设复制到 ${DSH_HOME:-~/.dsh}/.agent-presets//，并将该行追加到其 agent.cordis.yml。有关可直接复制粘贴的端到端步骤，参见 docs/installation.md。

禁用 / 卸载

无需改动源码即可禁用 —— 翻转该行：

- id: vibe-doctor
name: 'dsh-plugin-vibe-doctor'
disabled: true

或完全删除该行。无论哪种方式，插件的 fiber 都会被释放：vibe_doctor 工具及其提示部分会被注销（这已被测试覆盖）。要卸载，请删除该行并执行 npm remove dsh-plugin-vibe-doctor。

调用

向 agent 提出类似 _“我的应用坏了，你能找出原因吗？”_ 的问题 —— 已注册的提示指导会引导模型调用 vibe_doctor。该工具接受一个可选参数：

- path —— 要诊断的项目目录（绝对路径，或相对于会话工作区；默认为会话工作区）。

配置

| 键                 | 默认值     | 含义                                                                                                      |
| ------------------ | ---------- | --------------------------------------------------------------------------------------------------------- |
| allowCommands    | false    | 选择启用只读、允许列表内的 shell 探测（需要组合的 ctx.shell）                                           |
| collectors.     | 全部 true | 各收集器的启用标志（project、dependencies、configFiles、envFiles、git、logs、ports）        |
| maxFileBytes     | 262144   | 每文件读取上限                                                                                            |
| maxLogBytes      | 16384    | 每日志尾部上限                                                                                            |
| maxEvidenceItems | 120      | 全局证据上限                                                                                              |
| maxReportChars   | 24000    | 最终报告上限                                                                                          |
| commandTimeoutMs | 10000    | 每次 shell 探测                                                                                           |
| redactPatterns   | []       | 额外的脱敏正则表达式（加载时校验）                                                               |

完整参考：docs/configuration.md。

安全与隐私

- 只读。 不写入文件、不执行改变状态的命令、不升级依赖、不删除缓存/锁文件——在任何配置下都绝不。
- 命令为选择性启用，即便如此，也只有一份精确允许列表中的只读探测可以运行。
- 可能的机密信息（API 密钥、令牌、JWT、认证头、cookie、连接字符串凭据、PEM 密钥）在证据构建时即被脱敏——未脱敏的文本绝不会进入处理流程。
- 环境文件仅读取变量名称；值绝不会出现在任何地方。
- 所有读取都是有界的（文件上限、日志尾部、无递归扫描），且每个副作用都依附于插件 fiber，因此禁用插件即可完全清理。
- 无遥测、无网络调用、无托管服务。

详情：docs/privacy-and-security.md。

开发

git clone  && cd dsh-plugin-vibe-doctor
npm install
npm run verify   # format + lint + typecheck + tests + build

单独命令：npm run format / npm run lint / npm run typecheck / npm test / npm run build。参见 docs/development.md 和 docs/testing.md。

故障排除

| 症状                                          | 原因 / 修复                                                                                                    |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| 工具列表中缺少 vibe_doctor         | 组合未在此行之前加载 @deepseek-ai/dsh-tools，或该行为 disabled: true。         |
| no project directory available 错误           | 会话没有工作区 cwd；传入 path 参数。                                                    |
| not a readable directory 错误                 | path 参数不存在或不是目录。                                                        |
| 缺少 Git/包管理器证据             | allowCommands 为 false（默认）或未组合 ctx.shell 执行器——基于文件的证据仍然有效。 |
| 配置加载错误提及 redactPatterns[i] | 该自定义模式不是有效的正则表达式；修复或移除它。                                                    |

已知限制
- 无浏览器控制台 / 网络请求捕获：该测试框架目前未暴露稳定的宿主侧 API 用于页面诊断。一旦存在这样的 API，收集器接缝（src/collect/context.ts）就是扩展点。
- 日志证据基于文件；运行中的进程不会被附加。
- 根因排序是启发式的；置信度值诚实但近似。
- 参见 docs/limitations.md。

路线图

通过稳定的测试框架 API 实现浏览器诊断、可插拔的第三方收集器、框架特定的探针、更深入的锁文件解析。参见 docs/roadmap.md。

贡献

参见 CONTRIBUTING.md。安全报告：SECURITY.md。

许可证

MIT