前言¶
在 DeepSeek Harness（DSH）里跑 agent，提示词可以规定「该怎么做」，但同一台机器上重复出现的报错——模块找不到、权限 EPERM、fetch failed——往往不会因为你多写一段 system prompt 就消失。常见做法是人工记笔记或散落在聊天记录里，下次报错时再搜一遍，成本高且 agent 在工具失败当下拿不到上下文。
dsh-experience 把「踩过的坑」收成可检索的本地 Markdown 知识库：错误发生时用签名加权检索并主动注入症状与避坑；收尾时把缺口写成正式条目。不调用模型、不用向量库、默认不上网，索引约每 3 秒与磁盘对齐。
这是什么¶
插件全名 dsh-experience，仓库 wqx11235/dsh-experience，维护者 wqx11235，在 SkillHub 等社区目录中归类为「记忆」。当前开源版本 0.1.0（MIT），简介为：Self-learning experience library for DeepSeek Harness — local markdown knowledge, error-signature retrieval, gap→entry closure, sidebar panel. No network access.
一句话定位：给 DSH 用的自学习经验库——本地索引 Markdown，失败时检索命中，解决后把「问题」闭环为「条目」，并在 Web 侧边栏浏览与认领缺口。
和「再写一段提示词」的差别¶
经验库补的是「同一错误再次出现」这一层：错误签名 → 命中已有条目 → 当场注入症状与避坑 → 解决后把缺的那条补齐。README 中把这条链路称为决定性机制，改动检索或闭环逻辑前应先读仓库内 docs/architecture.md 与 library/README.md（条目格式）。
下面按机制简述（均来自 README 表格，不展开实现细节）：
| 机制 | 作用 |
|---|---|
| 分区加权检索 | 标题/正文命中外，「诊断关键词」「避坑」分区加权；中文 2-gram 兜底；别名半权扩展 |
| 错误签名路由 | ERR_MODULE_NOT_FOUND、EPERM、fetch failed、Error NNN 等签名专属加权，并记录复发频率 |
| 精确重排与去重 | top15 重排；近似条目降权；severity: critical 提权 |
| read-as-click 闭环 | 按签名搜并读条目记为解法；短时间同签名真实复发记 miss 降权 |
| 失败采集 + 修复证据 | 工具 isError 或 value.ok === false 进候选；同工具 30 分钟内成功调用可回填修复证据 |
| 缺口 → 条目闭环 | 复发无解法的签名、未命中查询、待认领草稿 → experience_promote 入库（模板、查重、分类 README、删草稿、重建索引） |
| 主动推送 | 工具失败时自动检索，分数过阈值注入「症状 + 避坑」；阈值按采纳率自适应 |
| 面板 | 侧边栏：按库浏览、结构化正文（避坑一键复制）、缺口与待认领、候选池 |
安装与启用¶
Web profile 下从 GitHub 安装（README 给出的当前主要方式）：
dsh plugin --profile web add github:wqx11235/dsh-experience
npm 发布后可用：
dsh plugin --profile web add dsh-experience
官方桌面端请在应用 设置 → 插件 中安装，不要用命令行改桌面 profile。
装完后重启宿主（host 插件不热更），侧边栏应出现「经验库」。首次启动会把包内 library/ 复制到库根；已有库不会被覆盖。
兼容性：engines.dsh >= 0.1.7-rc.2，不设上限；README 写明已在 0.1.7-rc.2 实测，0.1.7 以上预计可直接用。
库根与配置¶
优先级：config.experienceRoot → 环境变量 DSH_EXPERIENCE_ROOT → 默认 ~/.dsh/experience。
在 profile 的 cordis.patch.yml 里按插件 id 覆盖（不要重复 insert）：
- id: experience
config:
experienceRoot: '/absolute/path/to/experience'
seed: false
seed: false 可关闭首次把包内 library/ 播种到空库根的行为。
两条库的边界¶
| 私有库 | 公开起步库 | |
|---|---|---|
| 位置 | 库根（默认 ~/.dsh/experience） |
仓库 library/ |
| 来源 | 使用积累（采集 / 认领 / 归档） | 白名单 + 脱敏构建 |
| 谁写 | 运行时 | 仅 tools/build-library.mjs |
| 是否发布 | 永不 | 随 npm/git 包 |
运行时代码不写仓库内 library/；本地私有库不会随插件发布或上传。
工具与典型用法¶
插件向 agent 暴露以下工具（用途来自 README）：
| 工具 | 用途 |
|---|---|
experience_search |
检索；空格分词、中文 2-gram、报错签名加权；返回摘要与元数据 |
experience_read |
读全文；记录阅读次数与解法关联 |
experience_ask |
要结论而非文件列表：按 top 命中汇总症状/原因/避坑 |
experience_gaps |
缺口清单：反复出现无解法的签名、待认领草稿、未命中查询 |
experience_promote |
把草稿/签名/未命中查询写成正式条目；dryRun: true 先预览 |
典型闭环可以概括为：
- 工具执行失败时，插件监听
tools/result，必要时自动检索并在分数过阈值时注入上下文。 - agent 或你主动调用
experience_search/experience_read或experience_ask对齐已有条目。 - 用
experience_gaps看反复无解法的签名与草稿，再用experience_promote入库（可先dryRun: true）。
面板与上述能力同源，还提供 HTTP 端点（如 /experience/list、/search、/read、/gaps、/promote 等），便于侧边栏浏览与 inbox 操作。
隐私与适用注意¶
- 数据默认全部在本地；README 写明插件没有任何网络请求（唯一例外是你配置的
verify: url校验）。 - 公开起步库由构建期隐私闸门生成，细节见仓库
docs/privacy.md。
适用对象：长期在 DSH Web profile 上开发、希望把重复性报错沉淀为可检索本地知识、并愿意在失败与收尾阶段维护条目的开发者。
安全与权限：插件以当前 DSH 进程权限读写库根与监听工具结果；安装前请自行查看源码与 MIT 许可证，确认路径与隐私策略符合你的环境。社区目录（如 SkillHub 插件页）为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文安装命令以仓库 README 为准。
结尾¶
dsh-experience 用本地 Markdown + 错误签名路由 + 缺口入库闭环，把「同一报错再来一次」从重复排查变成可检索、可主动推送、可侧边栏维护的经验库；无模型、无向量库、默认离线。
