dsh-tool-error-hints

给失败的工具结果追加一条可执行的提示，治"弱模型瞎猜路径"。

为什么需要（有真实数据）

2026-09-13 对真实会话 session-7b9b38a1（本地 27B 跑长任务）的 796 条 tool/result 取证：

• 失败 92 条（12%）
• 最高频形态：ls: cannot access '<path>': No such file or directory [exit code: 2]

问题不在报错文案，而在报错只说"不存在"、不说"哪儿存在"： 本地模型反复瞎猜绝对路径（/nas/dsh/docker/dsh、/home/ikta/bin/wake-v100.sh）， 而压缩之后它会退回已经纠正过的错误写法——同一个错路径能再错 4 次。

它做什么

挂在 tools/post-execute（waterfall），在失败结果之后注入一条 source.kind='plugin' 的提示：

识别到的失败	注入的提示
路径不存在	最近的已存在祖先目录及其内容（模型据此即可改对）+ 工作区根提示
命令不存在	说明容器内没有该可执行文件，建议先 command -v 探测
权限不足	说明以非 root 运行，sudo/apt-get/写 /var 会失败
把目录当文件读	提示改用 ls

误报防护（重要）

grep 未找到匹配项、(无匹配)、no matches 都是合法的空结果，不是错误。 自测时踩过这个坑，因此按证据强度分两级：

• STRONG（No such file or directory / cannot access / 文件不存在 …）→ 抽不到路径也给兜底提示
• WEAK（泛化的 not found / 未找到 / 找不到）→ 必须先抽出像路径的 token 才提示

自测用例 10/10 通过（5 类真报错都提示、5 类正常输出零误伤）。

配置

- id: tool-error-hints
  name: 'dsh-tool-error-hints'
  config:
    enabled: true
    roots: [/nas/dsh]      # 解析相对路径、找"最近的已存在目录"时的根
    maxEntries: 24         # 列目录条数上限
    maxHintsPerPath: 2     # 同一路径本轮最多提示几次（防刷屏）
    include: []            # 只对哪些工具生效（空=全部）
    exclude: []            # 排除哪些工具

安装

bash /nas/dsh/工具/dsh-tool-error-hints/install.sh
dsh-restart

激活方式：~/.dsh/profiles/web/cordis.patch.yml 里的 insert: 条目。 不要写进 package.json 的 dsh.profile.bundles —— 实测 dsh web 每次启动 会把 package.json 还原成出厂版本，写进去的会被冲掉（见 dsh-loop-breaker 的同类记录）。

确证是否真的加载

dump-config 只组合配置树、不 import 模块，所以"配置里有"不等于"加载了"。 插件在 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 追加，不改写工具输出本身
• 异常全吞：提示插件绝不能影响正常工具流程