# 故障排查

[← 回到 README](../README.md)

## 先做这三件事

1. **重启 DSH** —— bundle 插件在启动时装载，装完不重启不会生效。
2. 打开 **设置 → Office 转换**，看「当前转换器」是什么、Python 环境探测结果如何。
3. 用页面上的「试转一个文件」直接在本机跑一遍 —— 它不进模型、不走缓存，能把问题范围缩到最小。

## 常见现象

| 现象 | 可能原因 | 处理 |
| --- | --- | --- |
| 装完看不到插件 | 没重启 DSH | 重启一次 |
| 设置里没有「Office 转换」这一页 | profile 没有 `webServer` 服务（如 CLI profile） | 属正常现象，工具与技能不受影响 |
| 工具调用了但转换失败 | 文件类型不被当前转换器支持 | 看返回的说明；`.pdf` 与旧格式需要 MarkItDown |
| 一直用兜底转换器，保真度低 | 没有可用的 MarkItDown | 设置页点「一键配置 MarkItDown 环境」 |
| 设置了 `converter` 却不生效 | 填的值不在合法取值里，或该级不可用 | 对照 [配置文档](configuration.md)；填错会退回自动探测 |
| `pythonPrefer: config` 但不生效 | 没配 `pythonPath` | 两者要一起配；缺一个会退回 `auto` |
| 模型仍然直接把 Office 文件读进上下文 | `guardReadTool` 被关掉，或文件扩展名不在支持列表 | 检查配置项；见 [使用文档](usage.md) |
| 提示 uvx 相关失败 | `uv` 不在本机，或 `allowUvxDownload` 为 `false` | 属预期行为，插件会继续探测下一级 |
| 产物没更新 | 源文件没变，走了缓存 | 传 `force: true` |
| 同一目录下堆了很多 `.md` | 源文件反复改动 | 用 `action: "clean"`，或打开 `pruneStaleArtifacts` |
| 卸载后 Python 环境还在 | 环境记录里没有那些包，或 `removeEnvOnUninstall` 为 `false` | 见 [卸载文档](uninstall.md) 的清理范围说明 |
| 卸载后 `env.json` / `removal.log` 还在 | 看门狗没跑完（例如超时） | 属收尾文件，可手工删除 |

## 「先卸载再安装新版」这个提示

DSH 界面在某些情况下会建议先卸载再安装。**本插件不要这么做** ——
卸载会触发 Python 环境清理，于是你得到一个更新了的插件和一个空掉的环境。
正确做法见 [安装文档的「升级」](installation.md#升级)。

## 报告问题时请附上

- 「设置 → Office 转换」页面上的当前转换器与本机 Python 探测结果截图或文字；
- 触发时的工具调用参数与返回信息；
- DSH 数据目录里那行清理日志（如果是卸载相关问题）。

---

> 本文档主要由 AI 生成，现象与处理对照过源码，但未逐条实测。
> 说明与免责见 [README 的「关于本文档」](../README.md#关于本文档)。