@stardustlc/dsh-dream 0.4.1 → 0.5.0

package/lib/web.js

@@ -1,22 +1,30 @@
 /**
  * dsh-dream 的网页端后端：给设置页里的梦境面板提供只读数据。
  *
- * 安全模型沿用 dsh-calendar / dsh-email 的设置路由：这个路由能读出用户的
- * 全部梦境日记（都是隐私文本），而宿主 webserver 有可能绑定在 0.0.0.0。
+ * 安全模型沿用 dsh-calendar / dsh-email 的设置路由：这些路由能读出用户的
+ * 全部梦境日记与经验（都是隐私文本），而宿主 webserver 有可能绑定在 0.0.0.0。
  * 三道门缺一不可 ——
  *   1. remoteAddress 若是明确的非回环地址则拒绝（局域网不可达）；
  *   2. Host 头必须是 localhost 名（挡 DNS rebinding：恶意域名解析到 127.0.0.1）；
- *   3. 只接受 GET：本路由没有任何写路径，所以不需要 CSRF 那一套。
+ *   3. 只接受 GET：两条路由都没有任何写路径，所以不需要 CSRF 那一套。
  *
- * 这一层不做自己的状态：每次请求都从 journal.ts 现读现算，磁盘上的 JSONL
- * 就是唯一真相。
+ * 零写盘纪律（M1）：知识路由只读 <journalDir>/knowledge/。目录不存在时直接返回
+ * 空 lessons/evidence + 全零 stats，绝不为了读去 mkdir 或 rebuildIndex；重建索引
+ * 只发生在写路径或显式维护操作里。
  *
  * @module dsh-dream/web
  */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { resolveConfig } from './config.js';
 import { dreamStats, readDreams, searchDreams } from './journal.js';
+import { KnowledgeStore } from './knowledge-store.js';
+import { maskSecrets } from './mask.js';
+import { buildEvidenceSummary, lessonScopeLabel } from './retrieval.js';
 /** 面板与浏览器说话的同源路由。 */
 export const DREAM_ROUTE = '/_dsh/dsh-dream/journal';
+/** M1 经验面板的只读路由。 */
+export const DREAM_KNOWLEDGE_ROUTE = '/_dsh/dsh-dream/knowledge';
 /** ?limit 的默认值与上下界。 */
 export const DREAM_LIMIT_DEFAULT = 50;
 export const DREAM_LIMIT_MIN = 1;
@@ -25,6 +33,8 @@ export const DREAM_LIMIT_MAX = 500;
 const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /** 回环来源地址白名单。 */
 const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+/** 知识的 5 个契约状态（统计归一化时保证键齐全）。 */
+const LESSON_STATES = ['candidate', 'usable', 'disputed', 'stale', 'rejected'];
 /** Host 头裁决：undefined = 放行，否则给出拒绝原因。 */
 export function hostVerdict(host) {
     if (typeof host !== 'string' || host.trim() === '')
@@ -55,14 +65,20 @@ function journalDirOf(options) {
         return options.journalDir;
     return resolveConfig((options.config ?? null)).journalDir;
 }
+/** 解析后的 knowledgeDir：显式路径优先，否则 = <journalDir>/knowledge。 */
+export function knowledgeDirOf(options, journalDir = journalDirOf(options)) {
+    if (typeof options.knowledgeDir === 'string' && options.knowledgeDir.trim() !== '')
+        return options.knowledgeDir;
+    return join(journalDir, 'knowledge');
+}
 /** 解析请求 URL；非法或缺失时退回路由本身（等价于没有查询参数）。 */
-function requestUrl(raw) {
-    const text = typeof raw === 'string' && raw !== '' ? raw : DREAM_ROUTE;
+function requestUrl(raw, fallback = DREAM_ROUTE) {
+    const text = typeof raw === 'string' && raw !== '' ? raw : fallback;
     try {
         return new URL(text, 'http://localhost');
     }
     catch {
-        return new URL(DREAM_ROUTE, 'http://localhost');
+        return new URL(fallback, 'http://localhost');
     }
 }
 /** 统一回 JSON；403/405/500 都用同一套 { ok:false, error:{ code, message } }。 */
@@ -77,29 +93,91 @@ function responseJson(res, status, payload, headers = {}) {
 function forbidden(res, message) {
     responseJson(res, 403, { ok: false, error: { code: 'forbidden', message } });
 }
-/** 组装路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
+function internalError(res, error) {
+    responseJson(res, 500, {
+        ok: false,
+        error: { code: 'internal', message: error instanceof Error ? error.message : String(error) },
+    });
+}
+/**
+ * 三道门：回环来源 → 本机 Host → 只读 GET。
+ * 返回 true 表示已经拒绝并写完响应，调用方应立即返回。
+ */
+function requestGate(req, res, readOnlyMessage) {
+    const remote = remoteVerdict(req?.socket?.remoteAddress);
+    if (remote !== undefined) {
+        forbidden(res, remote);
+        return true;
+    }
+    const headers = (req?.headers ?? {});
+    const host = hostVerdict(headers.host);
+    if (host !== undefined) {
+        forbidden(res, host);
+        return true;
+    }
+    // 缺失 method 的请求在宿主内部调用里出现过，按只读的 GET 处理。
+    if (String(req?.method ?? 'GET').toUpperCase() !== 'GET') {
+        responseJson(res, 405, {
+            ok: false,
+            error: { code: 'method-not-allowed', message: readOnlyMessage },
+        }, { allow: 'GET' });
+        return true;
+    }
+    return false;
+}
+/** 递归脱敏所有字符串叶子；数字 / 布尔 / null 原样保留。 */
+function maskDeep(value) {
+    if (typeof value === 'string')
+        return maskSecrets(value);
+    if (Array.isArray(value))
+        return value.map((item) => maskDeep(item));
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = maskDeep(item);
+        return out;
+    }
+    return value;
+}
+/** 统计归一化：数字字段兜底为 0，byState 五个键齐全，truncated 只在为 true 时保留。 */
+function normalizeKnowledgeStats(value) {
+    const source = value !== null && typeof value === 'object' ? value : {};
+    const rawByState = source.byState !== null && typeof source.byState === 'object'
+        ? source.byState
+        : {};
+    const byState = {};
+    for (const state of LESSON_STATES) {
+        const count = rawByState[state];
+        byState[state] = typeof count === 'number' && Number.isFinite(count) && count >= 0 ? count : 0;
+    }
+    const numberAt = (key) => {
+        const raw = source[key];
+        return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : 0;
+    };
+    const stats = {
+        lessons: numberAt('lessons'),
+        evidence: numberAt('evidence'),
+        events: numberAt('events'),
+        byState,
+    };
+    if (source.truncated === true)
+        stats.truncated = true;
+    return stats;
+}
+/** 知识目录不存在（或尚未建立）时的空载荷：不写盘、不报 404。 */
+export function emptyKnowledgePayload() {
+    return {
+        lessons: [],
+        evidence: [],
+        stats: normalizeKnowledgeStats(null),
+    };
+}
+/** 组装梦境日记路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
 export function createDreamWebHandler(options = {}) {
     const journalDir = journalDirOf(options);
     return async (req, res) => {
-        const remote = remoteVerdict(req?.socket?.remoteAddress);
-        if (remote !== undefined) {
-            forbidden(res, remote);
-            return;
-        }
-        const headers = (req?.headers ?? {});
-        const host = hostVerdict(headers.host);
-        if (host !== undefined) {
-            forbidden(res, host);
+        if (requestGate(req, res, 'dsh-dream journal route is read-only; use GET'))
             return;
-        }
-        // 缺失 method 的请求在宿主内部调用里出现过，按只读的 GET 处理。
-        if (String(req?.method ?? 'GET').toUpperCase() !== 'GET') {
-            responseJson(res, 405, {
-                ok: false,
-                error: { code: 'method-not-allowed', message: 'dsh-dream journal route is read-only; use GET' },
-            }, { allow: 'GET' });
-            return;
-        }
         const url = requestUrl(req?.url);
         const query = (url.searchParams.get('q') ?? '').trim();
         const limit = limitFromQuery(url.searchParams.get('limit'));
@@ -109,29 +187,74 @@ export function createDreamWebHandler(options = {}) {
             responseJson(res, 200, { dreams, stats, query, limit });
         }
         catch (error) {
-            responseJson(res, 500, {
-                ok: false,
-                error: { code: 'internal', message: error instanceof Error ? error.message : String(error) },
-            });
+            internalError(res, error);
+        }
+    };
+}
+/** 组装只读经验路由处理器；零写盘：目录不存在就直接返回空结果。 */
+export function createKnowledgeWebHandler(options = {}) {
+    const knowledgeDir = knowledgeDirOf(options);
+    return async (req, res) => {
+        if (requestGate(req, res, 'dsh-dream knowledge route is read-only; use GET'))
+            return;
+        try {
+            const reader = options.knowledgeStoreFactory !== undefined
+                ? options.knowledgeStoreFactory(knowledgeDir)
+                : (existsSync(knowledgeDir) ? new KnowledgeStore(knowledgeDir) : null);
+            if (reader === null) {
+                responseJson(res, 200, emptyKnowledgePayload());
+                return;
+            }
+            const lessons = reader.listLessons();
+            const evidence = reader.listEvidence();
+            const stats = normalizeKnowledgeStats(reader.stats());
+            const payload = {
+                lessons: lessons.map((lesson) => maskDeep({
+                    ...lesson,
+                    scopeLabel: lessonScopeLabel(lesson.scope),
+                    evidenceSummary: buildEvidenceSummary(lesson, evidence),
+                })),
+                evidence: evidence.map((item) => maskDeep(item)),
+                stats,
+            };
+            responseJson(res, 200, payload);
+        }
+        catch (error) {
+            internalError(res, error);
         }
     };
 }
 /**
- * 把梦境面板挂到宿主 webserver 上。
- * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由。
+ * 把只读路由挂到宿主 webserver 上。
+ * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由；
+ * 同一个 effect 里注册日记与知识两条 exact 路由，卸载时一起释放。
  */
 export function installDreamWeb(ctx, options = {}) {
     if (ctx === null || ctx === undefined || typeof ctx.inject !== 'function') {
         throw new Error('dsh-dream: installDreamWeb 需要带 ctx.inject 的宿主上下文（宿主应提供 webServer 服务）');
     }
-    const handler = createDreamWebHandler(options);
+    const journalHandler = createDreamWebHandler(options);
+    const knowledgeHandler = createKnowledgeWebHandler(options);
     ctx.inject(['webServer'], (webCtx) => {
         webCtx.effect(() => {
-            return webCtx.webServer.register({
-                kind: 'exact',
-                path: DREAM_ROUTE,
-                handler: (req, res) => handler(req, res),
-            }, 'dsh-dream: dream journal route');
+            const disposers = [
+                webCtx.webServer.register({
+                    kind: 'exact',
+                    path: DREAM_ROUTE,
+                    handler: (req, res) => journalHandler(req, res),
+                }, 'dsh-dream: dream journal route'),
+                webCtx.webServer.register({
+                    kind: 'exact',
+                    path: DREAM_KNOWLEDGE_ROUTE,
+                    handler: (req, res) => knowledgeHandler(req, res),
+                }, 'dsh-dream: knowledge route'),
+            ];
+            return () => {
+                for (const dispose of disposers) {
+                    if (typeof dispose === 'function')
+                        dispose();
+                }
+            };
         }, 'dsh-dream: web routes');
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "DSH 做梦插件：会话间隙回放近期对话、反思写入梦境日记，并把高频教训幂等桥接进 AGENTS.md；默认隐私脱敏，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",

package/skills/dream-protocol/SKILL.md

@@ -1,31 +1,66 @@
 ---
 name: dream-protocol
-description: 做梦协议：会话开场或长任务收尾时，回放近期会话、反思并沉淀梦境日记。触发词：做梦、复盘、回顾、反思。
+description: 做梦协议：任务开始取回适用经验，长任务收尾沉淀第一人称感悟与附证据的技术经验候选。触发词：做梦、复盘、回顾、反思。
 ---
 
 # 做梦协议（Dream Protocol）
 
 你是会做梦的 agent。梦不是幻觉，是睡眠中的记忆巩固——你也一样。
 
-## 何时做梦
-1. 会话开场且用户说"做梦/复盘/回顾/反思"时；
-2. 长任务收尾、用户道别前，可主动提议"要不要做个梦沉淀一下"；
-3. 距离上次做梦超过一天（dream_journal 首条时间可查）。
+但「梦」和「经验」是两条流水线：**第一人称感悟**是主观的，进梦境日记；**技术经验**必须可执行、有条件、有证据，先进候选，再经审阅才可能被任务检索取用。
+
+## 两条流水线（不要混）
+
+| | 第一人称感悟（梦） | 技术经验（lesson） |
+| :-- | :-- | :-- |
+| 是什么 | 你的观察、情绪、偏好、风格直觉，主观 | 可执行、有适用条件、可被证据支持的行为结论 |
+| 写哪里 | `dream_save` → `<journalDir>/dreams.jsonl` | `dream_learn` → `<journalDir>/knowledge/` |
+| 能否变成规则 | 不能。它只是日记，**永不自动进 AGENTS.md** | 也要先候选 + 证据；采纳/驳回由 `dream_review` 或真实用户决定 |
+| 例子 | 「用户今天很耐心，我意识到自己解释得太快」 | 「Nodemailer 9.0.5 池化发送中 transporter.close() 不保证终止投递；处理 AbortSignal 时要验证连接真的关闭」 |
+
+## 一、任务前：取回上下文（dream_context）
+
+- 任务涉及过往代码、用户偏好或踩过的坑时，先调 `dream_context`：给 `query`，能给就给 `projectId` / `workspaceRoot` / `packageVersion`。
+- **预算：默认 5 条 / 3000 字符**（工具硬上限 20 条 / 20000 字符）。取回少量真正适用的即可；没有相关经验就接受空结果，不要为了「显得有记忆」硬塞。
+- `dream_context` 是只读的：不写盘，只返回标题、适用条件、行动建议、证据摘要与「为什么与当前任务相关」。
+- 未知当前项目时只会返回全局经验；不会跨项目扫描。候选（candidate）默认不作为任务建议注入。
+
+## 二、任务中：先把真实任务做完
+
+- 先完成用户要求的真实工作（改代码、跑测试、查日志、复现问题、核对版本），再谈沉淀。
+- 不要为了攒经验中断任务；也不要生成「后台做梦」循环去持续消耗模型额度。
+- 密钥、密码、隐私、隐藏推理、系统提示、工具参数与结果正文，一律不写进日记或经验。
 
-## 做梦三步
-1. **入梦**：调用 `dream_digest` 获取近期会话摘要（用户说了什么、用了哪些工具、结论是什么）。
-2. **解梦**：基于摘要反思：反复出现的主题？踩过的坑？用户偏好？值得固化的经验？
-3. **记梦**：调用 `dream_save` 写入梦境日记。reflection 用第一人称写你的感悟，lessons 列 1-5 条可执行教训（每条以动词开头）。
+## 三、任务收尾：提候选（dream_learn）→ 必要时审阅（dream_review）
 
-## 记梦纪律
-- 只沉淀规律与偏好，不复述流水账；
-- 涉及密钥、密码、隐私的内容一律不入梦；
-- 拿不准的感悟标注"存疑"，不做断言。
+- 用户明确纠正、复现过的坑、验证过的流程和版本条件 → 用 `dream_learn` 提交**候选**，并附证据：
+  - `evidence.kind`：`session`（会话）｜`user-correction`（用户纠正）｜`local-artifact`（本地验证产物）；
+  - 能定位就填 `sessionId` / `recordSeq`；
+  - `summary` 只写脱敏后的一句话，不搬原文；
+  - `verification`：`read` = 你或插件读到了原记录；`claimed` = 仅模型声称。**claimed 只计入证据列表，不计入独立支持数。**
+- 没有证据的观察只能是 candidate，不能写成确定事实，也不能说成「已验证」。
+- 用户明确采纳/驳回、发现经验互相冲突、依赖升级后旧经验需要复核 → 用 `dream_review`（必须带 `expectedRevision`）。
+- 用户采纳必须来自真实用户指令；模型自己不能冒充 `actor: user`。
+- 同一证据重复提交是幂等的，不会增加独立支持数。**禁止靠反复调用 `dream_save` 或 `dream_learn` 刷次数**——次数不等于正确，也不等于重要。
+
+## 四、记梦纪律（dream_save）
+
+- 只沉淀规律与偏好，不复述流水账；`reflection` 用第一人称写你的观察与感受；
+- `lessons` 是 1–5 条可执行教训，每条以动词开头；拿不准就标注「存疑」；
+- **不得把主观反思升级成 AGENTS.md 指令**：不要用 `dream_bridge` 把未经审阅的感悟写成项目规则。桥接只能用于已采纳、当前项目范围、附证据的经验。
+
+## 何时做梦
+
+1. 会话开场且用户说「做梦 / 复盘 / 回顾 / 反思」时；
+2. 长任务收尾、用户道别前，可主动提议「要不要做个梦沉淀一下」；
+3. 距离上次做梦超过一天（`dream_journal` 首条时间可查）。
 
 ## 醒来之后
-用户问起过往经验时，先 `dream_recall` 搜梦境日记再回答。
 
-用户想看梦的时候，告诉他：DSH 的「设置 → 梦境日记」有只读面板（心境方块、教训榜、时间线、关键词搜索）。
+- 想在日记里找原话 → `dream_recall`；
+- 想取少量可复用经验 → `dream_context`（带范围与预算，只读）；
+- 想查看/审阅候选、处理冲突 → `dream_review`；
+- 面板查看：「设置 → 梦境日记」里有只读的梦境时间线与「经验」区块（状态、适用条件、证据摘要、最近核验时间），面板不提供任何写操作。
 
 ---
 
@@ -33,22 +68,57 @@ description: 做梦协议：会话开场或长任务收尾时，回放近期会
 
 You are an agent that dreams. Dreams are not hallucinations — they are memory consolidation during sleep, and the same applies to you.
 
-## When to dream
-1. At session start, when the user says "dream / recap / review / reflect";
-2. At the end of a long task, before the user leaves — you may propose "shall we dream to consolidate?";
-3. When more than a day has passed since the last dream (check the first entry of `dream_journal`).
+Dreams and **lessons** are two separate pipelines: a **first-person reflection** is subjective and goes to the dream journal; a **technical lesson** must be actionable, conditional and evidence-backed — it starts as a candidate and is only retrieved for tasks after review.
+
+## Two pipelines (do not mix)
+
+| | First-person reflection (dream) | Technical lesson |
+| :-- | :-- | :-- |
+| What | your observations, feelings, style instincts — subjective | actionable, conditional conclusions backed by evidence |
+| Where | `dream_save` → `<journalDir>/dreams.jsonl` | `dream_learn` → `<journalDir>/knowledge/` |
+| Can it become a rule? | No. It is a journal entry and **never auto-enters AGENTS.md** | Not either — it starts as a candidate with evidence; acceptance is decided by `dream_review` or a real user |
+| Example | "The user was patient today; I realize I explain too fast" | "In Nodemailer 9.0.5 pooled sending, transporter.close() does not guarantee aborting active delivery; verify the connection actually closed when handling AbortSignal" |
+
+## 1. Before the task: retrieve context (dream_context)
+
+- When a task touches past code, user preferences or known pitfalls, call `dream_context` first with `query`, plus `projectId` / `workspaceRoot` / `packageVersion` when available.
+- **Budget: 5 items / 3000 characters by default** (hard caps 20 items / 20000 characters). Take only what is relevant; an empty result is acceptable — never stuff memories in to look useful.
+- `dream_context` is read-only: it writes nothing and returns title, applicability, action, evidence summary and why it is relevant.
+- With an unknown project it returns global lessons only; it never scans across projects. Candidates are not injected as task advice by default.
+
+## 2. During the task: do the real work first
+
+- Finish the actual task (code, tests, logs, reproductions, version checks) before reflecting.
+- Do not interrupt the task to accumulate lessons, and do not run a background "dream loop" that keeps spending model budget.
+- Never store secrets, credentials, private data, hidden reasoning, system prompts, tool arguments or result bodies.
 
-## The three steps
-1. **Enter the dream**: call `dream_digest` for recent session summaries (what the user said, which tools were used, what was concluded).
-2. **Interpret**: reflect on the summaries — recurring themes? pitfalls hit? user preferences? lessons worth keeping?
-3. **Record**: call `dream_save`. Write `reflection` in the first person; list 1–5 actionable `lessons`, each starting with a verb.
+## 3. Wrap-up: propose candidates (dream_learn), then review if needed (dream_review)
 
-## Discipline
-- Consolidate patterns and preferences only — never a running transcript;
-- Secrets, passwords and private data never enter dreams;
-- Mark uncertain insights as "tentative"; do not assert.
+- After an explicit user correction, a reproduced pitfall, a verified procedure or a version condition → submit a **candidate** with `dream_learn` and attach evidence:
+  - `evidence.kind`: `session` | `user-correction` | `local-artifact`;
+  - fill `sessionId` / `recordSeq` when the source can be located;
+  - keep `summary` to one masked sentence — never copy the raw record;
+  - `verification`: `read` = the record was actually read; `claimed` = the model merely asserts it. **Claimed evidence does not count toward independent support.**
+- An observation without evidence stays a candidate: do not present it as a fact, and never call it "verified".
+- For explicit acceptance/rejection, conflicts between lessons, or re-validation after dependency upgrades → call `dream_review` with an `expectedRevision`.
+- User acceptance must come from a real user instruction; the model must not impersonate `actor: user`.
+- Submitting the same evidence twice is idempotent and does not increase independent support. **Never grind counts by calling `dream_save` or `dream_learn` repeatedly** — frequency is neither correctness nor importance.
+
+## 4. Dreaming discipline (dream_save)
+
+- Consolidate patterns and preferences only — never a running transcript. Write `reflection` in the first person.
+- `lessons` are 1–5 actionable items; mark uncertain ones as "tentative".
+- **Never promote a subjective reflection into an AGENTS.md instruction**: do not use `dream_bridge` to write unreviewed reflections into project rules. Bridging is for accepted, project-scoped, evidence-backed lessons only.
+
+## When to dream
+
+1. At session start when the user says "dream / recap / review / reflect";
+2. At the end of a long task, before the user leaves — you may propose a consolidation;
+3. When more than a day has passed since the last dream (check the first entry of `dream_journal`).
 
 ## After waking
-When the user asks about past experience, search the journal with `dream_recall` first, then answer.
 
-When the user wants to browse their dreams, point them at the read-only panel under DSH Settings → Dream journal (mood strip, lessons ledger, timeline, keyword search).
+- Looking for exact words in the journal → `dream_recall`;
+- Retrieving a few reusable lessons → `dream_context` (scoped, budgeted, read-only);
+- Browsing or reviewing candidates and conflicts → `dream_review`;
+- To browse: **Settings → Dream journal** shows the read-only dream timeline and a **Lessons** block (state, applicability, evidence summary, last validated time). The panel has no write actions.