使用

平时它是安静的，只有真的连续失败才出声。默认阈值是同一个工具连续 2 次，中间只要成功一次就清零。下面是它真实发出来的一段（路径和线索做了泛化）：

【踩坑档案】`npm run build` 连续 2 次没成功。
线索：TS2339 Property 'createReport' does not exist | src/report/export.ts

当前项目的档案里有像的，先看能不能直接用：
- `p-20261004-164512-a3f9` ｜已解决 ｜本项目 ｜tsconfig 的 types 没带上
  当时怎么解决的：把 @types/node 补进 compilerOptions.types，别用 triple-slash

如果这次的坑跟上面不一样（或者上面那条的解法这次不管用），解决或绕过去之后用
`pitfall_record` 记一笔新坑，必要时用 `pitfall_update` 补记旧条目。
别把这条提醒当成要汇报的事 —— 对用户说什么还说什么。

两本档案里都没有像的时，它会直说「这回可能是新问题」，并要求模型解决完记一笔 —— 不硬凑一条无关记录塞过去。这一点很要紧：给错答案比说「不知道」更糟，所以检索宁可空手而归。

提醒是节流的：同一会话 10 分钟内不重复，单会话最多 4 条，到顶就安静等下一轮。

配置

配置就写在装它的那段 patch 里（id: pitfalls 的 config 段）。没有单独的配置文件，也没有设置界面。

想改默认值，在你自己的 patch 层写同 id 的条目覆盖，只写要改的字段就行：

- id: pitfalls
  config:
    failureStreak: 3
    projectStore: false

保存即生效（patchReload: live）。字段填错了重载时会直接报错，不会悄悄退回默认值。

字段	默认值	含义
`enabled`	`true`	总开关。false 时不注册工具、不装监听、不注入提示词
`autoDetect`	`true`	是否自动盯工具失败。关掉只剩模型主动记录
`failureStreak`	`2`	同一个工具连续失败几次算踩到坑。填 1 会很吵
`matchHistory`	`true`	命中历史时是否把当时的解法带进提醒
`reminderCooldownMs`	`600000`	同一会话两次提醒的最小间隔，防连环刷屏
`maxRemindersPerSession`	`4`	单会话提醒上限，到顶就安静等下一轮
`systemPromptSection`	`true`	是否往系统提示里写「踩坑就记、开工先查」那段规则
`dir`	`$DSH_HOME/pitfalls`	全局档案目录（同时是备份）
`projectStore`	`true`	是否把记录也写进当前工作区的项目档案
`projectDir`	`.dsh/pitfalls`	项目档案目录，相对工作区；填绝对路径则所有工作区共用一处
`backupToGlobal`	`true`	写项目档案时是否在全局留一份备份
`indexLimit`	`200`	每本档案的 `INDEX.md` 最多列多少条
`logPath`	`''`	事件日志路径，留空 = 不记

把 projectStore 关掉就退回「只有一本全局档案」的用法。

dsh-pitfalls

インストール

ドキュメント

使用

配置