前言¶

在 DSH 里跑智能体，同一个报错、同一条构建失败，往往会在不同会话里重复出现。上一次花两小时查出来的根因，下一轮对话里模型又从零试起——这不是模型「笨」，而是会话本身不持久，也没有一套和项目绑定的「教训库」。

常见做法是自己在笔记或 wiki 里记，但模型不会自动去翻；或者指望模型每次记得先查文档，实际任务一深就忘。下面介绍社区插件 dsh-pitfalls（维护者 superSizzzz）：把坑写成结构化档案（现象、怎么踩进去的、怎么解决），并提供检索工具；同时在同一工具连续失败达到阈值时，由插件主动往会话里注入提醒，并带上命中的历史解法。

这是什么¶

dsh-pitfalls 是 DeepSeek Harness 的 Cordis 插件，分类上属于「记忆」类能力。它不额外调用模型，只在事件流上统计工具失败次数，并在本地对 jsonl 档案做检索。

解决的问题可以概括成三点：记（解决或绕过后写入档案）、查（动手前先搜历史）、盯（连续失败时提醒模型先看档案）。「什么算坑」由模型通过工具描述自行判断，插件不替模型下结论，避免档案被「命令打错了」之类噪声塞满。

核心功能¶

三件事与触发方¶

默认阈值是同一工具连续失败 2 次；中间只要成功一次就清零。提醒会节流：同一会话 10 分钟内不重复，单会话最多 4 条。

四个工具¶

档案结构与存放位置¶

写入时项目档案与全局档案各写一份，同一编号；读取时先当前工作区项目档案，不够再从全局补，每条结果标注来源。

目录内典型文件：

<工作区>/.dsh/pitfalls/          或   ~/.dsh/pitfalls/
├── entries.jsonl      事实源，一行一条完整快照
├── cards/<编号>.md    单条可读卡片
└── INDEX.md           按时间倒序索引

一条记录对应 pitfall_record 的字段：现象 symptom、怎么踩进去的 cause、怎么解决的 solution、证据 evidence、范围/标签 area / tags。编号形如 p-20261004-164512-a3f9；状态为 已解决 / 已绕过 / 未解决 之一。

权限与边界（安装前宜核对）¶

插件 README 中说明的行为包括：不发网络请求、不执行 shell 命令；注册 4 个 pitfall_* 工具；可选往系统提示追加「踩坑就记、开工先查」规则（可关）；仅在连续失败时注入提醒，不改写用户消息；磁盘只写档案目录与可选日志文件。插件以当前 dsh 进程权限运行，安装前应阅读 GitHub 仓库 源码与 MIT 许可证。

安装与启用¶

环境要求（来自官方 README）：

在目标 profile 下执行（示例为 web）：

dsh plugin --profile web add github:superSizzzz/dsh-pitfalls

dsh 会读取包内 dsh.bundle.patch 并并入当前 profile，无需手写整段配置。装完默认即运行；平时安静，只有连续失败或模型主动调用工具时才有可见行为。

卸载：

dsh plugin --profile web remove dsh-pitfalls

已写入的档案不会被插件删除，仍留在工作区 .dsh/pitfalls/ 与 ~/.dsh/pitfalls/，为纯文本，可自行保留或删除。

典型用法¶

自动提醒长什么样¶

当例如 npm run build 连续 2 次失败，且项目档案里有相似条目时，会话里可能出现类似下面的注入（README 示例，路径与线索已泛化）：

【踩坑档案】`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` 补记旧条目。

若两本档案都没有合适命中，插件会表明可能是新问题，并建议解决后记录，而不是硬凑无关条目——检索宁可空，也不给错解法。

模型侧工作流¶

1. 遇到报错或异常行为：先 pitfall_search，用报错片段、命令名、文件路径作 query。
2. 命中后：pitfall_show 看细节，能复用则按档案里的 solution 处理。
3. 新问题或旧解法失效：解决或绕过后 pitfall_record 写一条；后续改进用 pitfall_update 追加。

可选配置¶

配置写在 profile patch 里 id: pitfalls 的 config 段，保存后若 profile 为 patchReload: live 则热重载。常见字段示例：

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

想确认插件是否装载、档案路径是否生效，可在 config 里设置 logPath，装载后日志会出现 event: "applied" 一行，字段含实际 globalDir、projectDir 等。

适用场景与注意¶

适合谁：长期在固定仓库里用 DSH 做开发或运维的智能体用户；团队希望把「本项目踩过的坑」留在仓库旁（.dsh/pitfalls/），必要时可纳入版本库或加入 .gitignore。

注意点：

• 项目目录会多一个 .dsh/pitfalls/；若不想提交，可忽略该路径，或关闭 projectStore 仅保留全局档案。
• 提醒只投给顶层会话；subagent 会话内的失败不会注入，相关坑需由主 agent 在结果中体现并记录。
• 拿不到工作区路径时只写全局档案。
• 社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；当前 package 版本为 0.1.0，GitHub 星标以仓库页面为准。

结尾¶

dsh-pitfalls 把「教训 learned」从个人笔记变成 DSH 可检索、可被动触达的本地档案：模型负责记与查，插件在连续失败这种客观信号上补一刀，减少同一坑反复从零排查的时间。

• 社区目录：https://www.skillhub.cn/plugins/superSizzzz/dsh-pitfalls
• 源码与完整文档：https://github.com/superSizzzz/dsh-pitfalls