dsh-error-atlas 0.11.25 → 0.11.26

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to **dsh-error-atlas**. Versions follow `0.11.x` while the p
 is in the DSH marketplace pipeline; the panel's `V##` chip is the **client bundle** build
 stamp, which only moves when `client.js` changes — a `V51 · 0.11.24` panel is expected.
 
+## 0.11.26
+
+- `atlas_impact` — the read-only tool that says whether the mechanism pays for itself:
+  how many lessons exist, how many can be judged (they name failures still recorded), how
+  many of those were followed by the same failure returning, and how much of the store the
+  lessons cover. Also exposed as `impact` in `/error-atlas/data` so the panel can show it.
+- Real store at release: 59 lessons (49 model · 10 auto), **30 judgeable, 6 recurred (20%),
+  24 held (80%)**, 61% of signatures carry a lesson, 235 failures in the last 30 days.
+
 ## 0.11.25
 
 - Client tests no longer depend on the checkout's line endings: the test seam matches the

package/README.md

@@ -6,7 +6,7 @@
 
 ![错误星图面板](https://raw.githubusercontent.com/chaos-miku/dsh-error-atlas/main/docs/screenshot.jpg)
 
-*面板实拍：顶部是统计与操作，左侧是颜色图例，中间是 GPU 渲染的错误星系，底部是「记忆」开关、教训有效性榜单与最近事件表。标题旁的 `V33` 是 build 号，用来确认页面跑的是哪一代客户端代码。*
+*面板实拍：顶部是统计与操作，左侧是颜色图例，中间是 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
@@ -28,7 +28,24 @@ DSH 报过的错、踩过的坑，默认会随会话结束消失。这个插件
 
 - 一段全局提示词要求「编程任务收尾前写复盘」；
 - 每次请求动态注入简报：**失效教训优先**（写完又复发的），再加几条最近的规则；没有教训时整段不出现，不产生固定开销；
-- 只读工具 `atlas_lessons`，可按 `query` / `program` / `limit` 查询全部教训。
+- 只读工具 `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` |
+
+一句话区别：**给每个失败一个身份（去重签名）、一个位置（会话岛 / 程序卫星）、一个判决（写完教训之后又犯了吗）**。前者是采集，中间是可视化，后者是唯一能证明「教训有用」的东西——这也是它和上面几个不重叠的部分。
 
 ## 噪声与本质
 
@@ -125,7 +142,7 @@ DSH 报过的错、踩过的坑，默认会随会话结束消失。这个插件
 plugin_manager install_bundle target="dsh-error-atlas"
 ```
 
-指定版本：`target="dsh-error-atlas@0.11.4"`。
+指定版本：`target="dsh-error-atlas@0.11.25"`。
 
 本地目录安装（开发用）：
 
@@ -180,7 +197,7 @@ npm test        # 157 项断言：宿主事件/路由/存储 + 客户端渲染
 npm run smoke   # 干净 DSH_HOME 下的冷启动冒烟：空库 → 写复盘 → 读回 → CLI 可读
 ```
 
-客户端为零依赖手写 bundle（`window.__ModuleLoader__`），宿主为纯 ESM。面板标题旁的 `V30`/`V35`… 是 BUILD 号，用来确认页面加载的是哪一代客户端代码。
+客户端为零依赖手写 bundle（`window.__ModuleLoader__`），宿主为纯 ESM。面板标题旁的 `V51` 就是 BUILD 号，用来确认页面加载的是哪一代客户端代码。
 
 ## 已知边界
 

package/index.js

@@ -931,6 +931,61 @@ function createStore(config) {
       return lines.join('\n')
     }
 
+    // What the lessons bought, in numbers that are honest about being proxies: a lesson
+    // counts as "judged" only when it names failures that are still in the store, and only
+    // then can its signatures be watched afterwards. Everything else is bookkeeping.
+    function impactOf(days = 30) {
+      const span = Math.max(1, Math.min(365, Math.floor(days || 30)))
+      const windowMs = span * 24 * 60 * 60 * 1000
+      const since = Date.now() - windowMs
+      const recordById = new Map()
+      for (const entry of state.records.values()) recordById.set(entry.id, entry)
+      const ambient = ambientIds()
+      const linked = new Set()
+      let model = 0
+      let auto = 0
+      let judgeable = 0
+      let failed = 0
+      let firstLessonAt = Infinity
+      for (const retro of state.retros) {
+        if (retro.auto) auto += 1
+        else model += 1
+        if (!retro.auto && Number.isFinite(retro.at) && retro.at < firstLessonAt) firstLessonAt = retro.at
+        const ids = (retro.errorIds || []).filter((id) => recordById.has(id))
+        for (const id of ids) linked.add(id)
+        if (retro.auto || ids.length === 0) continue
+        judgeable += 1
+        const relapse = recurrenceOf(retro, recordById, ambient)
+        if (relapse && relapse.times > 0) failed += 1
+      }
+      let hits = 0
+      let hitsInWindow = 0
+      let afterFirstLesson = 0
+      for (const event of state.log) {
+        hits += 1
+        if (event.at >= since) hitsInWindow += 1
+        if (Number.isFinite(firstLessonAt) && event.at > firstLessonAt) afterFirstLesson += 1
+      }
+      const distinct = state.records.size
+      return {
+        days: span,
+        lessons: model + auto,
+        model,
+        auto,
+        judgeable,
+        failed,
+        held: judgeable - failed,
+        rate: judgeable > 0 ? Math.round((failed / judgeable) * 100) : 0,
+        distinct,
+        withLesson: linked.size,
+        coverage: distinct > 0 ? Math.round((linked.size / distinct) * 100) : 0,
+        hits,
+        hitsInWindow,
+        afterFirstLesson,
+        firstLessonAt: Number.isFinite(firstLessonAt) ? firstLessonAt : 0,
+      }
+    }
+
   function snapshot() {
     const all = [...state.records.values()].sort((a, b) => b.count - a.count || b.last - a.last)
     const recordById = new Map()
@@ -1212,6 +1267,7 @@ function createStore(config) {
       prefs: prefs(),
       trend: trendOf(Date.now()),
       lessons: lessonBoard(),
+      impact: impactOf(30),
       nodes,
       links,
       retros: state.retros.slice(0, config.maxRetros),
@@ -1233,6 +1289,7 @@ function createStore(config) {
     applyPrefs,
     lessonList,
     lessonBriefing,
+    impactOf,
   }
 }
 
@@ -1816,6 +1873,78 @@ export function apply(ctx, config = {}) {
           }),
         'error-atlas: lesson tool',
       )
+
+      // Whether the mechanism pays for itself: how many lessons exist, how many can be
+      // judged at all, and how many of those had their signatures come back anyway.
+      scope.effect(
+        () =>
+          scope.tools.register({
+            name: 'atlas_impact',
+            description:
+              'Report what the recorded lessons bought: how many exist, how many can be judged (they name failures that are still in the store), how many of those were followed by the same failure returning, and how much of the store the lessons cover. These are counts from the local store, not a controlled experiment.',
+            parameters: {
+              type: 'object',
+              properties: {
+                days: { type: 'number', description: 'Window for the failure counts, 1 to 365; defaults to 30.' },
+              },
+              additionalProperties: false,
+            },
+            output: {
+              schema: {
+                type: 'object',
+                properties: {
+                  days: { type: 'number' },
+                  lessons: { type: 'number' },
+                  model: { type: 'number' },
+                  auto: { type: 'number' },
+                  judgeable: { type: 'number' },
+                  failed: { type: 'number' },
+                  held: { type: 'number' },
+                  rate: { type: 'number' },
+                  distinct: { type: 'number' },
+                  withLesson: { type: 'number' },
+                  coverage: { type: 'number' },
+                  hits: { type: 'number' },
+                  hitsInWindow: { type: 'number' },
+                  afterFirstLesson: { type: 'number' },
+                  firstLessonAt: { type: 'number' },
+                },
+                required: ['days', 'lessons', 'judgeable', 'failed', 'held', 'rate', 'coverage'],
+                additionalProperties: false,
+              },
+              render(_args, value) {
+                if (value.lessons === 0) return [{ type: 'text', text: 'no lessons recorded yet' }]
+                if (value.judgeable === 0) {
+                  return [
+                    {
+                      type: 'text',
+                      text:
+                        value.lessons +
+                        ' lesson(s), none judgeable yet: a lesson is judged only once it names failures that are still recorded',
+                    },
+                  ]
+                }
+                return [
+                  {
+                    type: 'text',
+                    text: [
+                      'impact · ' + value.days + ' day window',
+                      'lessons: ' + value.lessons + ' (' + value.model + ' model · ' + value.auto + ' auto) · ' + value.judgeable + ' judgeable',
+                      'verdict: ' + value.failed + ' of ' + value.judgeable + ' judged lessons recurred (' + value.rate + '% failed · ' + (100 - value.rate) + '% held)',
+                      'coverage: ' + value.withLesson + ' of ' + value.distinct + ' signatures carry a lesson (' + value.coverage + '%)',
+                      'failures: ' + value.hitsInWindow + ' in window · ' + value.afterFirstLesson + ' since the first lesson',
+                    ].join('\n'),
+                  },
+                ]
+              },
+            },
+            execute(args) {
+              const days = Number.isFinite(args.days) ? Math.max(1, Math.min(365, Math.floor(args.days))) : 30
+              return Promise.resolve(store.impactOf(days))
+            },
+          }),
+        'error-atlas: impact tool',
+      )
     })
 
     ctx.inject(['systemPrompt'], (scope) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-error-atlas",
-  "version": "0.11.25",
+  "version": "0.11.26",
   "type": "module",
   "description": "Records runtime errors and coding-task retrospectives, collapses noisy shell failures into command fingerprints, distils each lesson into one injected rule, and renders the whole thing as an interactive GPU knowledge graph (WebGL) with lesson links, recurrence flags, program satellites, session islands, orbit-any-node camera, search and activity trends.",
   "icon": "icon.svg",

package/test/run.mjs

@@ -823,6 +823,107 @@ async function lessonSection() {
 }
 
 
+// ── impact ─────────────────────────────────────────────────────────────────
+// The number the plugin exists for: of the lessons that can be judged at all, how many
+// had their signatures come back anyway.
+async function impactSection() {
+  section('impact')
+  const home = tempHome('impact')
+  const now = Date.now()
+  const hour = 60 * 60 * 1000
+  const retro = (id, at, errorIds, extra) =>
+    Object.assign(
+      {
+        id,
+        at,
+        auto: false,
+        title: 'task ' + id,
+        done: 'changed',
+        cause: 'c',
+        fix: 'f',
+        lesson: 'lesson ' + id,
+        tags: ['edit'],
+        tools: ['edit'],
+        files: ['C:/work/proj-a/src/a.ts'],
+        cwd: 'C:/work',
+        errors: [],
+        errorIds,
+      },
+      extra || {},
+    )
+  writeFileSync(
+    join(home, 'error-atlas', 'records.json'),
+    JSON.stringify({
+      version: 2,
+      updatedAt: now,
+      records: [
+        {
+          key: 'tool\u0000edit\u0000boom',
+          id: 'e1',
+          kind: 'tool',
+          name: 'edit',
+          message: 'boom',
+          count: 2,
+          first: now - 5 * hour,
+          last: now - 10 * 60 * 1000,
+          sessions: ['s'],
+        },
+        {
+          key: 'tool\u0000pwsh\u0000sunless',
+          id: 'e2',
+          kind: 'tool',
+          name: 'pwsh',
+          message: 'no lesson here',
+          count: 1,
+          first: now - 4 * hour,
+          last: now - 4 * hour,
+          sessions: ['s'],
+        },
+      ],
+      log: [
+        { at: now - 10 * 60 * 1000, kind: 'tool', name: 'edit', message: 'boom', sessionId: 's' },
+        { at: now - 4 * hour, kind: 'tool', name: 'pwsh', message: 'no lesson here', sessionId: 's' },
+        { at: now - 40 * 24 * hour, kind: 'tool', name: 'edit', message: 'ancient', sessionId: 's' },
+      ],
+      retros: [
+        retro('r1', now - 3 * hour, ['e1']),
+        retro('r2', now - 2 * hour, []),
+        retro('r3', now - hour, [], { auto: true }),
+      ],
+    }),
+  )
+
+  const host = await bootHost(home)
+  const tool = host.tools.find((item) => item.name === 'atlas_impact')
+  check('the impact tool is registered', Boolean(tool))
+  if (!tool) return
+
+  const impact = await tool.execute({})
+  eq('every retrospective is counted', impact.lessons, 3)
+  eq('model retrospectives are separated', impact.model, 2)
+  eq('auto skeletons are separated', impact.auto, 1)
+  eq('only lessons that name a live failure are judgeable', impact.judgeable, 1)
+  eq('a lesson whose failure came back counts as failed', impact.failed, 1)
+  eq('nothing was held against the only judged lesson', impact.held, 0)
+  eq('the failure rate is a percentage', impact.rate, 100)
+  eq('the store size is reported', impact.distinct, 2)
+  eq('coverage counts signatures with a lesson', impact.withLesson, 1)
+  eq('coverage is a percentage', impact.coverage, 50)
+  eq('the failure log is counted', impact.hits, 3)
+  eq('the window keeps the old failure out', impact.hitsInWindow, 2)
+  check('failures after the first lesson are counted', impact.afterFirstLesson >= 1, String(impact.afterFirstLesson))
+  eq('the default window is 30 days', impact.days, 30)
+  eq('a shorter window is honoured', (await tool.execute({ days: 1 })).days, 1)
+  eq('a silly window is clamped', (await tool.execute({ days: 9999 })).days, 365)
+
+  const text = tool.output.render({}, impact)[0].text
+  check('the rendered impact reads like a report', text.includes('judged lessons recurred'), text.slice(0, 120))
+  check('the rendered impact reports coverage', text.includes('carry a lesson'))
+
+  const payload = (await host.call('/error-atlas/data')).json
+  eq('the panel payload carries the same numbers', payload.impact ? payload.impact.judgeable : -1, 1)
+}
+
 // ── board ──────────────────────────────────────────────────────────────────
 // The effectiveness leaderboard: a lesson library is only useful if the reader can see
 // which kinds of lesson keep failing without opening every entry.
@@ -1034,7 +1135,7 @@ async function noiseSection() {
 }
 
 // ── run ────────────────────────────────────────────────────────────────────
-const sections = [storeSection, retroSection, prefsSection, trendSection, projectSection, exportSection, lessonSection, noiseSection, boardSection, clientSection, capSection, manifestSection]
+const sections = [storeSection, retroSection, prefsSection, trendSection, projectSection, exportSection, lessonSection, noiseSection, impactSection, boardSection, clientSection, capSection, manifestSection]
 for (const run of sections) {
   try {
     await run()