前言¶

DSH 智能體在處理工具失敗時，常遇到弱模型反覆猜測錯誤路徑的問題。報錯信息通常只說明“不存在”，卻未指出“何處存在”。dsh-tool-error-hints 旨在解決這一痛點，在失敗結果後追加可執行的提示，防止模型陷入無效的路徑猜測循環。

它做什麼¶

插件運行在 tools/post-execute 階段（瀑布流末尾），識別失敗工具並在結果後注入 source.kind='plugin' 的提示。主要能力包括：

1. 路徑不存在：提供最近的已存在祖先目錄及其內容，輔助模型修正路徑。
2. 命令不存在：提示容器內缺少該可執行文件，建議使用 command -v 探測。
3. 權限不足：提示以非 root 運行，說明 sudo、apt-get 或寫 /var 會失敗。
4. 把目錄當文件讀：提示應改用 ls 命令。
5. 誤報防護：區分 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。