排错时最有用的问题是：**最后一个成功的动作是什么？**下载完成、服务启动、网页打开、模型回复、文件修改和测试通过，是六个不同的检查点。这篇把它们分别处理，避免一次故障就删除全部配置。
命令示例固定 0.1.2-rc.1。除明确写“本站验证”的结果外，下述故障分支是文档和通用诊断整理，不声称每种错误都在本机复现。
先选症状
| 你看到的现象 | 从哪一节开始 |
|---|---|
| node/npx 找不到，PowerShell 拒绝脚本 | 终端与安装 |
| 下载卡住，没有出现地址 | 包获取与启动 |
| 终端有地址，浏览器仍打不开 | 本地服务与访问 |
| 页面能打开，但无法输入 | 工作区和模型选择 |
| 有具体接口错误 | 模型请求 |
| Agent 一直操作但没修好 | 工具执行与成果 |
终端与安装：先确认三个版本
node --version
npm --version
npx @deepseek-ai/dsh@0.1.2-rc.1 --version前两条失败时，还没有进入 DSH 层。先重新打开终端并检查 Node 安装位置。本站使用 Node 24.13.0；不要用“电脑装过 Node”代替当前终端输出。
Windows PowerShell 若仅拒绝 npm.ps1 或 npx.ps1，先使用对应的 npm.cmd、npx.cmd。不要未经判断修改全局执行策略，更不要把普通 PATH 错误当成模型密钥问题。
包获取与启动：先确认请求的是哪个包
查询固定版本的公开元信息：
npm view @deepseek-ai/dsh@0.1.2-rc.1 version
npm config get registry期望第一条返回 0.1.2-rc.1。查询都失败时，检查错误里是 DNS、证书、网络超时还是 registry 返回找不到包。公司网络使用镜像时，向管理员确认该版本是否同步；不要为排错永久改掉所有项目的 registry。
需要更详细日志时，可以在终端运行：
npm exec --loglevel verbose --package=@deepseek-ai/dsh@0.1.2-rc.1 -- dsh --version公开日志前删除凭据、内部地址和个人路径。不要用关闭证书验证的方式“修好”TLS 错误；应修复受信任证书或正确代理配置。
如果 npm 查询成功但启动失败，保留第一条明确异常及其堆栈开头，不要只截最后一行。
本地服务与访问：先看终端，不猜 URL
运行：
npx @deepseek-ai/dsh@0.1.2-rc.1 web --no-open --port 3088应输出可访问地址并保持进程运行。如果立即退出，浏览器重试没有意义，先处理终端错误。本站实际版本打印过带 ?token=... 的地址，初次访问使用完整地址；不要分享 token。
**端口占用：**为本次运行换一个空闲端口，不随意结束不认识的进程。无法自动打开浏览器：--no-open 加手动访问就是合理路径，不等于服务失败。
**远程运行：**远程机器的 127.0.0.1 不等于你电脑的本地地址。需要正确的 SSH 转发安排，不能简单把 host 改成 0.0.0.0；当前 CLI 文档明确不支持这一写法。公司部署请沿专门的网络与访问方案处理，本篇不把公网部署混进新手排错。
页面能打开，但无法输入
依次看：
- 是否已关闭初始声明与配置引导？
- 是否真正添加并选择了工作区，而不只是启动终端位于项目目录？
- 是否选择了有效模型？
- 当前会话是否正在执行、等待确认或处于不可输入状态？
练习工作区里应该能找到 budget.mjs 和 budget.test.mjs。压缩包预览、父目录和另一个同名文件夹，都可能导致后续“文件不存在”。
模型请求：先发不调用工具的最小消息
发送“只回复连接成功，不调用工具”。如果这一步也失败，优先检查模型层。
MISSING_CREDENTIAL：路由引用的凭据未找到；在设置里检查对应提供方，环境变量方案需要检查启动进程是否继承了变量。UNKNOWN_MODEL：选择或配置中不存在该模型 ID；使用有效目录项重新开会话验证。- 401：核对 Key 与端点；429：核对限流/额度的具体错误语义。
- 网关拒绝 developer role 或 token 字段：按照 兼容性排查 调整相应字段，不批量复制陌生配置。
每次只改变一项，然后重发同一条请求。换模型、换网关、升级程序同时进行，会失去判断原因的依据。
工具执行与成果：调用出现不等于成功
在过程记录中配对看调用参数与返回结果。
| 现象 | 先检查 | 合理下一步 |
|---|---|---|
| read 找不到文件 | 路径与实际工作区 | 纠正路径，再读取 |
| edit 提示旧文本未匹配 | 文件是否改变、旧文本是否精确 | 重新读取当前文件，再形成替换 |
| 提示需要先读取 | 当前会话是否观察过文件 | read 后再 edit；不先禁用策略 |
| 操作被拒绝 | 当前会话权限及拒绝原因 | 调整任务范围或合理确认 |
| 已修改但测试找不到 | 命令工作目录 | 在包含测试文件的目录执行 |
| 工具报错后仍宣称成功 | 回答是否忽略失败结果 | 指出真实结果，要求修正结论 |
不能假定每次失败都会自动弹审批，也不能把用户拒绝解释为文件已修改。
Agent 陷入循环，怎样中止并保留证据
使用界面的停止操作，或在明确需要停止整个本地服务时回到启动终端按 Ctrl+C。停止是协作过程，发出停止请求后还应确认进程/任务状态与文件变化。
保留以下三段最小证据：最后一次合法任务描述、重复工具调用及其错误、当前文件实际状态。然后用新的明确任务要求它先分析失败原因，不再重复同一条无效操作。若涉及超范围修改，先人工核查再继续。
用练习项目判断“恢复正常”
不必拿整个业务项目作为排错探针。重新解压 练习包，先运行：
node --test budget.test.mjs原始状态应为 1 通过 / 2 失败。让 DSH 修复唯一允许的文件后，再由你运行一次，应为 3 通过 / 0 失败。源码正确而测试仍失败时，先排除终端指向另一份解压目录。
一份可以提交给维护者的记录
DSH 版本与安装方式：
操作系统 / Node / npm 版本：
最后成功的动作：
最短复现步骤（从新会话开始）：
期望：
实际错误首行：
工具名、脱敏参数、对应结果：
已经尝试的单项调整：不要附 API Key、Cookie、带 token 的本地 URL 或整份私人会话。向 官方仓库支持入口 提供最小材料，比贴满屏无关日志更容易复现。