dsh-error-atlas

Error Atlas · 错误星图

把 DSH 自己的运行错误和每个编程任务的复盘，沉淀成一张可以被人看见、也可以被模型读到的记忆图谱。

*面板实拍：顶部是统计与操作，左侧是颜色图例，中间是 GPU 渲染的错误星系，底部是「记忆」开关、教训有效性榜单与最近事件表。标题旁的 V## 是客户端 build 号，用来确认页面跑的是哪一代代码（截图拍的是 V33，当前是 V51）。*

A local-first memory plugin for DeepSeek Harness: it records runtime failures and coding-task retrospectives, injects the reusable lessons back into the prompt, and renders the whole atlas as an interactive WebGL knowledge graph.

它解决什么

DSH 报过的错、踩过的坑，默认会随会话结束消失。这个插件做两件事：

写侧：把错误和复盘结构化地存下来。

• 运行期错误自动入库：agent/error（步/轮失败）、api-session/error、agent-loop/config-start-failed、tools/result 里的工具失败与非零退出码；
• 同一签名（类型 + 工具 + 消息）自动去重聚合，记次数、首末时间、涉及会话；
• 每次编程任务收尾由模型调用 atlas_retro 写一条复盘：做了什么 / 根因 / 怎么修 / 教训；模型没写的，宿主用工具与文件留一条自动骨架（不会抢模型手写的份额）。

读侧：让教训在下次真的被用上。

• 一段全局提示词要求「编程任务收尾前写复盘」；
• 每次请求动态注入简报：失效教训优先（写完又复发的），再加几条最近的规则；没有教训时整段不出现，不产生固定开销；
• 只读工具 atlas_lessons，可按 query / program / limit 查询全部教训；
• 只读工具 atlas_impact，回答「这套机制到底管不管用」：多少条教训可以被判定、其中多少条的失败在写完后又回来了，以及教训覆盖了多少种错误签名。

当前库的实测（59 条复盘 / 102 个签名）：30 条可判定，其中 6 条复发（20%），24 条成立（80%）；61% 的签名已经有过教训。

它不是什么

生态里已经有做「记忆」和「复盘」的插件，先把边界说清楚，省得装完发现不是想要的：

已有的方向 · 代表 · 我们和它的分工 经验库：任务后整理候选经验、审阅采纳、按项目召回、冲突处理、到期复核 · dsh-dream · 它管「经验文本的采纳流程」，我们管「失败证据的采集与度量」。它更成熟，可以一起装 云端失败案例检索：带证据评级的历史案例 · misakanet · 它查别人的案例库（走公共 MCP 服务），我们只记你这台机器上真实发生的事，不联网、不上传 单仓库修复经验：只从测试验证过的修复里积累 · dsh-reforge · 它要求「先修好、有测试证明」，覆盖 Python 单仓；我们记录任意工具/命令的失败，不要求已经修好 错误提醒 / 自动重试 / 诊断 · dsh-pharos、bark-notify、dsh-client-auto-continue、dsh-plugin-debugging · 那些是「处理与提示」，错误过去就过去了；我们做「沉淀」 服务端错误跟踪 · Sentry、GlitchTip 一类 · 那类要靠 instrumentation 上报到服务器、跨机器聚合；这里没有服务端、没有传输，数据只落在 $DSH_HOME/error-atlas/records.json

一句话区别：给每个失败一个身份（去重签名）、一个位置（会话岛 / 程序卫星）、一个判决（写完教训之后又犯了吗）。前者是采集，中间是可视化，后者是唯一能证明「教训有用」的东西——这也是它和上面几个不重叠的部分。

噪声与本质

原始记录里最没用的部分是「同一条命令换个目录再失败一次」，最有用的是「一句话说清下次怎么做」。所以入库和注入两头都做了收窄：

• 命令指纹：失败不再记整条命令行，而是记 可执行 + 脚本/子命令。cd A; node build.mjs 与 cd B; node build.mjs 是同一条 node build.mjs；node -e "…" 记成 node -e；@' … '@ 这类脚本片段记成 shell，不会碎成 node const 这种垃圾签名。stderr 的最后一行留下来做「详情」，所以第二次看到它时还认得出是什么错。
• 噪声静音：退出码干巴巴出现 ≥5 次、又没有 stderr 详情的那种，默认不进图谱（stats.noise 会告诉你静音了几条）。想看就打开 showNoise，GET|POST /error-atlas/prefs 或者面板里的过滤都能改。
• 本质规则 `essence`：每条复盘都会有一行 ≤96 字符的本质——如果 → → 下次 。模型写复盘时可以自己给 essence，没给就由宿主从教训里压一行出来。
• 注入只发本质：上下文简报最多 3 行、跳过自动骨架、失效教训必须真的关联过错误才置顶；每行只发 essence，不再把整段教训塞进每次请求。
• 环境噪声不算「教训失效」：一个签名如果被 ≥4 条复盘同时引用，它就是环境（比如这个 shell 的 stderr 习惯），不是哪条教训要防的错——它的复发不再把整排教训判红，裸退出码的复发也不算数。
• 一次性迁移：旧库（version < 3）在 load() 时把 exit 记录重算成指纹、合并重复签名、把复盘的 errorIds 重映射到新 id（连边不会断），并补写 essence；迁移和派生都只落盘一次。

图谱只是这些数据的一个视图——它不是装饰，但也不是产品本身：价值在于「教训能被下次会话读到」。

使用方式

1. 打开面板

左侧栏点击 错误图谱（图标是一颗星）。第一次打开是空的——它只记录安装之后发生的事。

2. 正常干活

不需要做任何事。之后你在 DSH 里跑命令、改文件、插件加载失败、工具非零退出，都会自动入库并按签名聚合；重复犯同一个错，那颗点会变大变亮，次数 +1。

3. 收尾写复盘

一段全局提示词会让模型在每个编程任务收尾前调用 atlas_retro，写入四条信息：做了什么、根因、怎么修、教训（那条「下次别再犯」的规则）。如果模型忘了写，宿主会留一条自动骨架，保证「这一轮干过什么」不丢。

面板上紫色的 RETRO 节点就是复盘，一条紫色的「教训」线把它连向它要治的那个错误；线上会有光点从错误流向复盘，表示这条教训正在被应用。同一错误在复盘之后又出现，管线会反过来倒灌并变红，面板顶部统计格里的「教训失效」计数 +1。

4. 让教训回到下一次

• 新会话开始后，宿主会自动把「失效教训 + 最近几条规则」注入上下文，模型不用查就知道；
• 你也可以让它主动查：模型可以调用 atlas_lessons（按程序 / 关键词 / 条数），面板上的「导出」则给人看。

5. 会话分岛

中心是 DSH 本体，往外每一圈是一个会话窗口：这个窗口里出过的错误围着它转，程序卫星再挂在整张图的外层轨道上。所以一眼能回答「哪个窗口在出错」「这个错误属于哪个程序」，而不是所有节点挤在一个球里。

同一签名在多个窗口出现时仍然只画一个节点（这是签名图，不是回合日志），它挂在最先出事的那个窗口上——sessions 里记录的其余窗口仍会在详情卡里列出来。

6. 维护

• 噪声太多：卡片上点「忽略」，把这条签名加入前缀规则，永久静音；顶部「过滤 ≥N」按命中次数裁剪视图；
• 程序卫星：程序枢纽被摆到外层轨道而不是云团中心——同一程序的所有复盘文件落在同一目录，它就悬在云外，连线像缆绳一样从错误节点拉出去，一眼能看出「是哪一团错误属于这个程序」，而不是所有东西挤成一个球；
• 找东西：搜索框输入标签、程序名、错误文本，命中高亮、其余压暗；点教训有效性榜单里的任意一行，图谱会过滤到那一类；
• 太久之前：点「清空」删除运行时错误记录（青色开发错误与紫色复盘是保留的）；点「导出」把整份数据写成 Markdown。

3.5 看得清

• 一个「外观」放四个滑条：点顶部「外观」弹出面板，里面有自转速度、节点大小、光点大小、光晕四个滑条，调节即时生效并各自记住上次的值。
• 节点大小：「大小」滑条缩放整张图的节点（10%–300%），与相机距离解耦——缩放只改变位置，不改变点的直径。
• 光点大小：「光点」滑条（20%–400%）只调沿教训线流动的那批小球，与节点的粗细互不影响。
• 间距：「间距」滑条（35%–240%）缩放整张图的位置，连线的长短、岛屿之间的距离一起变；节点与光点自身的直径不变，所以「拉开看清楚」和「点变大」是两件事。
• 颜色筛选：顶栏「刷新」左边有两排小圆点——左边一排是节点类型（AGENT/TOOL/EXIT/CONFIG/SESSION/PROJECT/DEV/RETRO），右边一排是连线类型（核心辐条/枢纽辐条/程序系绳/教训线/失效教训）。每排前面有个「亮着/总数」的计数，3/4 这种数字就是还有四个里有三个在显示。点一下关掉那一类，再点一下开回来，选择会被记住。
• 光晕大小：「光晕」滑条（0%–400%）控制每个节点外层的辉光，走的是电灯式两层叠加——紧致的一圈亮边加一圈更宽更淡的散射光；0% 是完全清晰的点阵，100% 是默认的星云感。
• 贴着线走：光点严格画在连线上（不做弧线抬升），不会浮在线旁边。
• 点击 = 对准：点任意节点，相机会把它转到屏幕中心并拉近；点空白或「重排」回退到全景。
• 节点是实的：每个节点是带抗锯齿边缘的亮球（中心亮、边缘暗），外面只留一层很淡的光晕——密集区不再糊成一片白。

面板上都有什么

区域 · 说明 顶部统计 · 累计错误 / 去重条目 / 图谱节点 / 会话 / 工具 / 程序 / 开发错误 / 任务复盘 / 教训失效 顶部操作 · 刷新、搜索、暂停、外观（自转速度 / 节点大小 / 间距 / 光点大小 / 光晕）、过滤 ≥N、重排、导出、清空、标题开关 左侧图例 · 见下表 中央星图 · 拖拽旋转、滚轮缩放、点节点看详情卡，视野拉近到该节点并以它为中心旋转（点空白处回到整体）、双击带会话的节点跳回该会话 底部「记忆」 · 两枚开关：收尾提示 / 注入教训 教训有效性 · 按标签与程序统计复盘数、失效数、失效率；可收起；行可点击过滤 最近事件 · 最新 400 条事件的表格视图（次数、类型、工具、消息、首次/最近）

图例与配色：

节点 · 颜色 · 含义 AGENT · 亮红 #ff4453 · 模型自身在某一轮/步失败 TOOL · 橙 #ffb570 · 工具调用返回了错误 EXIT · 杏黄 #ffd68f · 命令非零退出码 SESSION · 粉 #ff859d · 会话枢纽（出过错的那个窗口）：每个窗口是一座岛，自己的错误围在它周围 CONFIG · 紫 #d89eff · 会话/插件配置启动失败 DEV · 青 #7ff3e0 · 插件自己的开发错误（内置 12 条，随版本更新） RETRO · 紫 #c7a4ff · 一条任务复盘 PROJECT · 浅蓝 #7fd4ff · 程序卫星：停在错误云外层轨道，缆绳般的连线拉到它犯过的错误上 STALE · 红 #ff5b4d · 教训失效（复盘之后同一错误又出现）

安装

市场安装：在 DSH 插件市场搜索 error-atlas / 错误星图。

从 npm 安装（推荐，装最新版）：

plugin_manager install_bundle target="dsh-error-atlas"

指定版本：target="dsh-error-atlas@0.11.25"。

本地目录安装（开发用）：

plugin_manager install_bundle target="<本包绝对路径>"

安装后重启 DSH（宿主半边要注册路由、工具和提示词段），再刷新页面。

两个记忆开关

面板底部有一条「记忆」栏，两枚开关都是即时生效、重启后保留：

开关 · 关闭后 收尾提示 · 不再注册「编程任务收尾前写复盘」的提示词段（省掉每轮固定字符） 注入教训 · 不再每轮注入历史教训简报（图谱与复盘照常记录）

只想安静记录、不想被提示词影响的人，两个都关掉即可；复盘与图谱不受影响。

命令行

包内自带两个 CLI，也可被直接调用：

node bin/atlas-digest.mjs                 # 终端摘要：概览、Top 失败、失效教训、最近复盘
node bin/atlas-digest.mjs --json          # 机器可读
node bin/atlas-retro.mjs --list           # 列出复盘
node bin/atlas-retro.mjs --upgrade <id> --lesson "…"   # 升级/改写某条复盘
node bin/atlas-retro.mjs --new --title "…" --lesson "…" # 手写一条复盘

不想先装包也能跑（npx 直接从 npm 拉）：

npx -y -p dsh-error-atlas atlas-digest

atlas-retro 优先通过宿主路由写入（POST /error-atlas/retro，仅回环可访问）；宿主不在时退化为直接改库文件并给出警告。

数据与隐私

• 数据只落在本机：$DSH_HOME/error-atlas/records.json（日志、聚合错误、复盘、偏好设置）；
• 导出的 Markdown 写到 $DSH_HOME/error-atlas/exports/；
• 所有 HTTP 路由（/error-atlas/data|prefs|retro|clear|export）都只接受回环地址；
• 不联网、不上报、不采集对话内容；错误消息里可能含命令与路径，介意的话用面板的「清空」一键删除运行时记录（开发错误、任务复盘是内置/用户自己的数据，不会被清空）。

开发与测试

npm test        # 157 项断言：宿主事件/路由/存储 + 客户端渲染（借用本机 DSH 的 React）
npm run smoke   # 干净 DSH_HOME 下的冷启动冒烟：空库 → 写复盘 → 读回 → CLI 可读

客户端为零依赖手写 bundle（window.__ModuleLoader__），宿主为纯 ESM。面板标题旁的 V51 就是 BUILD 号，用来确认页面加载的是哪一代客户端代码。

已知边界

• 只看得见工具层失败与非零退出，模型在「成功路径」上的逻辑错误不会自动入库——那部分要靠复盘自己写；
• 教训注入是全局的（每轮一次），不按工作区精确匹配；
• 程序枢纽只从复盘的 files + cwd 推导，错误记录本身不存路径，所以没写过复盘的目录不会出现在图里；
• 图谱上限 2400 个节点（约 2400 条去重签名）：超出时 stats.truncated 会如实标记，且被复盘引用的错误不会被裁掉；
• 规模变大后布局换成网格斥力（只算近邻）+ 岛屿锚定，2400 节点首次落位约几十毫秒、稳态每帧十几毫秒；240 节点以下仍是精确力模型；
• 会话岛采用「唯一归属」：同一签名只挂在最先出事的窗口上，其余窗口在详情卡里列出，避免一个节点被复制成多份；
• 需要 Node ≥ 20；客户端需要 WebGL2（不可用时面板退化为提示）。

相关链接

• 源码与问题反馈：
• 作者：

License

MIT