前言¶
DSH 智能体在处理工具失败时，常遇到弱模型反复猜测错误路径的问题。报错信息通常只说明“不存在”，却未指出“何处存在”。dsh-tool-error-hints 旨在解决这一痛点，在失败结果后追加可执行的提示，防止模型陷入无效的路径猜测循环。
它做什么¶
插件运行在 tools/post-execute 阶段（瀑布流末尾），识别失败工具并在结果后注入 source.kind='plugin' 的提示。主要能力包括：
- 路径不存在：提供最近的已存在祖先目录及其内容，辅助模型修正路径。
- 命令不存在：提示容器内缺少该可执行文件，建议使用
command -v探测。 - 权限不足：提示以非 root 运行，说明
sudo、apt-get或写/var会失败。 - 把目录当文件读：提示应改用
ls命令。 - 误报防护：区分 STRONG（如
No such file or directory）和 WEAK 错误，避免误伤合法的空结果。
安装与启用¶
通过提供的安装脚本部署：
bash /nas/dsh/工具/dsh-tool-error-hints/install.sh
dsh-restart
激活方式：在 ~/.dsh/profiles/web/cordis.patch.yml 文件中配置 insert: 条目。
注意：不要将配置写入 package.json 的 dsh.profile.bundles，否则会被还原。
确认加载¶
配置有不代表已加载。插件在 apply() 时会写入心跳日志：
tail -1 ~/.dsh-logs/tool-error-hints-loaded.log
# 2026-09-13T14:10:00.000Z pid=12345 roots=/nas/dsh maxEntries=24
设计约束¶
插件严格遵循以下约束以确保稳定：
- 只读：仅使用
existsSync、readdirSync、statSync，绝不执行命令、绝不写文件。 - 不覆盖：通过
additionalContexts追加内容，不修改原始工具输出。 - 异常全吞：插件异常不会中断正常的工具流程。
总结¶
该插件解决了弱模型在工具报错时无法获取有效上下文的问题。如需了解更多细节，可访问插件目录：https://www.skillhub.cn/plugins/ikta2010/dsh-tool-error-hints 或查看源码：https://github.com/ikta2010/dsh-tool-error-hints。
