@stardustlc/dsh-dream 0.3.4 → 0.4.0

package/lib/index.d.ts

@@ -20,6 +20,8 @@ export interface DreamPluginContext {
         }): () => void;
     };
     on?(event: string, listener: () => void): () => void;
+    /** cordis 的依赖注入（宿主必给；headless 测试夹具可能没有）。 */
+    inject?(services: string[], callback: (scopedCtx: unknown) => void): void;
 }
 /** 随包技能目录。 */
 export declare function bundledSkillsDir(): string;

package/lib/index.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { resolveConfig } from './config.js';
 import { buildDreamTools } from './tools.js';
+import { installDreamWeb } from './web.js';
 /** cordis 服务注入：要用 ctx.tools 与 ctx.skills。 */
 export const name = 'dream';
 export const inject = ['tools', 'skills'];
@@ -53,6 +54,10 @@ export function apply(ctx, config) {
             console.warn('[dsh-dream] 做梦协议技能加载失败：' + (error instanceof Error ? error.message : String(error)));
         }
     }
+    // 面板同源路由：宿主有 webServer 才由 web.ts 用 ctx.inject 挂上；headless 夹具没有 inject 就跳过。
+    if (typeof ctx.inject === 'function') {
+        installDreamWeb(ctx, { journalDir: cfg.journalDir });
+    }
     if (typeof ctx.on === 'function') {
         ctx.on('dispose', () => {
             for (const dispose of disposers)

package/lib/journal.d.ts

@@ -11,16 +11,25 @@ export declare function journalFile(journalDir: string): string;
 export declare function saveDream(journalDir: string, reflection: string, lessons: string[], mood: string): DreamEntry;
 /** 倒序读取梦境（新梦在前）；损坏行跳过。 */
 export declare function readDreams(journalDir: string, limit: number): DreamEntry[];
-/** 梦境统计：总数、心境分布、高频教训。 */
+/** 教训榜的一行：次数与最近一次出现时间（lastAt 缺失时是空串，绝不为 null）。 */
+export interface LessonStat {
+    lesson: string;
+    count: number;
+    lastAt: string;
+}
+/** 梦境统计：总数、心境分布、教训榜。 */
 export interface DreamStats {
     total: number;
     moods: Record<string, number>;
-    topLessons: Array<{
-        lesson: string;
-        count: number;
-    }>;
+    topLessons: LessonStat[];
 }
-/** 统计梦境（基于全量日记）。 */
+/**
+ * 统计梦境（基于全量日记）。
+ *
+ * count 与 lastAt 来自同一遍倒序扫描：readDreams 已经新梦在前，所以某个
+ * 教训第一次出现的那条梦，就是它最近一次出现；顺手在那次循环里记下原始
+ * 大小写，不再二次 flatMap（否则同一条教训的三个数值会来自不同的扫描）。
+ */
 export declare function dreamStats(journalDir: string): DreamStats;
-/** 关键词检索梦境（不区分大小写，命中 reflection/lessons）。 */
+/** 关键词检索梦境（不区分大小写，命中 reflection/lessons；扫描全量，上限见 FULL_SCAN_LIMIT）。 */
 export declare function searchDreams(journalDir: string, query: string, limit: number): DreamEntry[];

package/lib/journal.js

@@ -24,6 +24,8 @@ export function saveDream(journalDir, reflection, lessons, mood) {
     appendFileSync(journalFile(journalDir), JSON.stringify(entry) + '\n', 'utf8');
     return entry;
 }
+/** 需要读全量日记时的上限：检索与统计共用，避免两处上限漂移。 */
+const FULL_SCAN_LIMIT = 100000;
 /** 倒序读取梦境（新梦在前）；损坏行跳过。 */
 export function readDreams(journalDir, limit) {
     const file = journalFile(journalDir);
@@ -48,32 +50,40 @@ export function readDreams(journalDir, limit) {
     }
     return out.reverse().slice(0, limit);
 }
-/** 统计梦境（基于全量日记）。 */
+/**
+ * 统计梦境（基于全量日记）。
+ *
+ * count 与 lastAt 来自同一遍倒序扫描：readDreams 已经新梦在前，所以某个
+ * 教训第一次出现的那条梦，就是它最近一次出现；顺手在那次循环里记下原始
+ * 大小写，不再二次 flatMap（否则同一条教训的三个数值会来自不同的扫描）。
+ */
 export function dreamStats(journalDir) {
-    const dreams = readDreams(journalDir, 100000);
+    const dreams = readDreams(journalDir, FULL_SCAN_LIMIT);
     const moods = {};
-    const lessonCount = new Map();
+    const lessons = new Map();
     for (const dream of dreams) {
         const mood = dream.mood !== '' ? dream.mood : '平静';
         moods[mood] = (moods[mood] ?? 0) + 1;
         for (const lesson of dream.lessons) {
             const key = lesson.toLowerCase();
-            lessonCount.set(key, (lessonCount.get(key) ?? 0) + 1);
+            const known = lessons.get(key);
+            if (known === undefined) {
+                lessons.set(key, { lesson, count: 1, lastAt: dream.at });
+            }
+            else {
+                known.count += 1;
+            }
         }
     }
-    const topLessons = [...lessonCount.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 10)
-        .map(([key, count]) => {
-        const original = dreams.flatMap((d) => d.lessons).find((l) => l.toLowerCase() === key) ?? key;
-        return { lesson: original, count };
-    });
+    const topLessons = [...lessons.values()]
+        .sort((a, b) => b.count - a.count || b.lastAt.localeCompare(a.lastAt))
+        .slice(0, 10);
     return { total: dreams.length, moods, topLessons };
 }
-/** 关键词检索梦境（不区分大小写，命中 reflection/lessons）。 */
+/** 关键词检索梦境（不区分大小写，命中 reflection/lessons；扫描全量，上限见 FULL_SCAN_LIMIT）。 */
 export function searchDreams(journalDir, query, limit) {
     const needle = query.toLowerCase();
-    return readDreams(journalDir, 1000).filter((entry) => {
+    return readDreams(journalDir, FULL_SCAN_LIMIT).filter((entry) => {
         const haystack = (entry.reflection + ' ' + entry.lessons.join(' ')).toLowerCase();
         return haystack.includes(needle);
     }).slice(0, limit);

package/lib/web.d.ts

@@ -0,0 +1,54 @@
+/**
+ * dsh-dream 的网页端后端：给设置页里的梦境面板提供只读数据。
+ *
+ * 安全模型沿用 dsh-calendar / dsh-email 的设置路由：这个路由能读出用户的
+ * 全部梦境日记（都是隐私文本），而宿主 webserver 有可能绑定在 0.0.0.0。
+ * 三道门缺一不可 ——
+ *   1. remoteAddress 若是明确的非回环地址则拒绝（局域网不可达）；
+ *   2. Host 头必须是 localhost 名（挡 DNS rebinding：恶意域名解析到 127.0.0.1）；
+ *   3. 只接受 GET：本路由没有任何写路径，所以不需要 CSRF 那一套。
+ *
+ * 这一层不做自己的状态：每次请求都从 journal.ts 现读现算，磁盘上的 JSONL
+ * 就是唯一真相。
+ *
+ * @module dsh-dream/web
+ */
+import { type ResolvedDreamConfig } from './config.js';
+import { type DreamEntry, type DreamStats } from './journal.js';
+/** 面板与浏览器说话的同源路由。 */
+export declare const DREAM_ROUTE = "/_dsh/dsh-dream/journal";
+/** ?limit 的默认值与上下界。 */
+export declare const DREAM_LIMIT_DEFAULT = 50;
+export declare const DREAM_LIMIT_MIN = 1;
+export declare const DREAM_LIMIT_MAX = 500;
+/** Host 头裁决：undefined = 放行，否则给出拒绝原因。 */
+export declare function hostVerdict(host: unknown): string | undefined;
+/** 来源地址裁决：undefined = 放行（请求里缺失也放行），否则给出拒绝原因。 */
+export declare function remoteVerdict(remote: unknown): string | undefined;
+/** GET 返回的 JSON 形状（T2 面板按这份契约渲染）。 */
+export interface DreamWebPayload {
+    /** 倒序的梦境（新梦在前），受 ?q 与 ?limit 影响。 */
+    dreams: DreamEntry[];
+    /** 全量日记的统计，不受 ?q 影响。 */
+    stats: DreamStats;
+    /** 本次生效的检索词（已去首尾空白；空串 = 不检索）。 */
+    query: string;
+    /** 本次生效的条数上限。 */
+    limit: number;
+}
+/** 安装参数；journalDir 缺省时从 config 解析。 */
+export interface DreamWebOptions {
+    /** 梦境日记目录（优先）。 */
+    journalDir?: string;
+    /** 插件配置，用来兜底 journalDir（resolveConfig 的入参）。 */
+    config?: Record<string, unknown> | ResolvedDreamConfig | null;
+}
+/** ?limit 解析：缺省/非数字 → fallback；越界钳制到 [1, 500]。 */
+export declare function limitFromQuery(raw: unknown, fallback?: number): number;
+/** 组装路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
+export declare function createDreamWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
+/**
+ * 把梦境面板挂到宿主 webserver 上。
+ * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由。
+ */
+export declare function installDreamWeb(ctx: any, options?: DreamWebOptions): void;

package/lib/web.js

@@ -0,0 +1,137 @@
+/**
+ * dsh-dream 的网页端后端：给设置页里的梦境面板提供只读数据。
+ *
+ * 安全模型沿用 dsh-calendar / dsh-email 的设置路由：这个路由能读出用户的
+ * 全部梦境日记（都是隐私文本），而宿主 webserver 有可能绑定在 0.0.0.0。
+ * 三道门缺一不可 ——
+ *   1. remoteAddress 若是明确的非回环地址则拒绝（局域网不可达）；
+ *   2. Host 头必须是 localhost 名（挡 DNS rebinding：恶意域名解析到 127.0.0.1）；
+ *   3. 只接受 GET：本路由没有任何写路径，所以不需要 CSRF 那一套。
+ *
+ * 这一层不做自己的状态：每次请求都从 journal.ts 现读现算，磁盘上的 JSONL
+ * 就是唯一真相。
+ *
+ * @module dsh-dream/web
+ */
+import { resolveConfig } from './config.js';
+import { dreamStats, readDreams, searchDreams } from './journal.js';
+/** 面板与浏览器说话的同源路由。 */
+export const DREAM_ROUTE = '/_dsh/dsh-dream/journal';
+/** ?limit 的默认值与上下界。 */
+export const DREAM_LIMIT_DEFAULT = 50;
+export const DREAM_LIMIT_MIN = 1;
+export const DREAM_LIMIT_MAX = 500;
+/** 回环主机名白名单；带端口会被拆掉，IPv6 字面量保留方括号。 */
+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']);
+/** Host 头裁决：undefined = 放行，否则给出拒绝原因。 */
+export function hostVerdict(host) {
+    if (typeof host !== 'string' || host.trim() === '')
+        return undefined;
+    const text = host.trim().toLowerCase();
+    const name = text.startsWith('[') ? text.slice(0, text.indexOf(']') + 1) : text.split(':')[0];
+    return LOCAL_HOSTNAMES.has(text) || LOCAL_HOSTNAMES.has(name) ? undefined : `host "${host}" is not a localhost name`;
+}
+/** 来源地址裁决：undefined = 放行（请求里缺失也放行），否则给出拒绝原因。 */
+export function remoteVerdict(remote) {
+    if (typeof remote !== 'string' || remote.trim() === '')
+        return undefined;
+    const text = remote.trim().toLowerCase();
+    return LOOPBACK_ADDRESSES.has(text) ? undefined : `remote address "${remote}" is not a loopback address`;
+}
+/** ?limit 解析：缺省/非数字 → fallback；越界钳制到 [1, 500]。 */
+export function limitFromQuery(raw, fallback = DREAM_LIMIT_DEFAULT) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(DREAM_LIMIT_MAX, Math.max(DREAM_LIMIT_MIN, Math.trunc(value)));
+}
+/** 解析后的 journalDir：显式路径优先，否则回退到 resolveConfig(config)。 */
+function journalDirOf(options) {
+    if (typeof options.journalDir === 'string' && options.journalDir.trim() !== '')
+        return options.journalDir;
+    return resolveConfig((options.config ?? null)).journalDir;
+}
+/** 解析请求 URL；非法或缺失时退回路由本身（等价于没有查询参数）。 */
+function requestUrl(raw) {
+    const text = typeof raw === 'string' && raw !== '' ? raw : DREAM_ROUTE;
+    try {
+        return new URL(text, 'http://localhost');
+    }
+    catch {
+        return new URL(DREAM_ROUTE, 'http://localhost');
+    }
+}
+/** 统一回 JSON；403/405/500 都用同一套 { ok:false, error:{ code, message } }。 */
+function responseJson(res, status, payload, headers = {}) {
+    const text = JSON.stringify(payload);
+    if (typeof res?.writeHead === 'function') {
+        res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });
+    }
+    if (typeof res?.end === 'function')
+        res.end(text);
+}
+function forbidden(res, message) {
+    responseJson(res, 403, { ok: false, error: { code: 'forbidden', message } });
+}
+/** 组装路由处理器；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);
+            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'));
+        try {
+            const dreams = query === '' ? readDreams(journalDir, limit) : searchDreams(journalDir, query, limit);
+            const stats = dreamStats(journalDir);
+            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) },
+            });
+        }
+    };
+}
+/**
+ * 把梦境面板挂到宿主 webserver 上。
+ * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由。
+ */
+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);
+    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');
+        }, 'dsh-dream: web routes');
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "DSH 做梦插件：会话间隙回放近期对话、反思写入梦境日记，并把高频教训幂等桥接进 AGENTS.md；默认隐私脱敏，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",
@@ -10,6 +10,7 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./client": "./lib/client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -18,7 +19,8 @@
     "skills",
     "cordis.patch.yml",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -29,6 +31,12 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
     }
   },
   "keywords": [

package/skills/dream-protocol/SKILL.md

@@ -25,6 +25,8 @@ description: 做梦协议：会话开场或长任务收尾时，回放近期会
 ## 醒来之后
 用户问起过往经验时，先 `dream_recall` 搜梦境日记再回答。
 
+用户想看梦的时候，告诉他：DSH 的「设置 → 梦境日记」有只读面板（心境方块、教训榜、时间线、关键词搜索）。
+
 ---
 
 # Dream Protocol (English)
@@ -48,3 +50,5 @@ You are an agent that dreams. Dreams are not hallucinations — they are memory
 
 ## 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).