dsh-prime-memory 0.11.0 → 0.12.0

package/dist/store/vec-utils.js

@@ -0,0 +1,24 @@
+/**
+ * vec0 编码工具:抽取向量 ↔ Buffer 的**唯一**编码约定。
+ *
+ * 为什么单独一个文件:`l1_vec` / `l0_vec`（在 `sqlite.ts`）与 `graph_node_vec`
+ * （在 `graph-store.ts`）必须用**同一种**二进制编码，否则同一份 vec0 扩展会出现
+ * 两种字节布局。而 `sqlite.ts` 已经 import 了 `GraphStore`——若让 `graph-store.ts`
+ * 反过来 import `sqlite.ts`，就形成模块环：能跑，但生死取决于加载顺序，
+ * 属于"隐式依赖"，不是可以留在代码里的东西。
+ */
+/** 全零向量(cosine 未定义,不可入向量表)。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
+export function isZeroVector(vec) {
+    for (const v of vec) {
+        if (v !== 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Float32Array → Buffer（零拷贝视图，共享底层 ArrayBuffer）。
+ * vec0 的 `float[N]` 列按 little-endian 连续 float32 读取，这正是该视图的布局。
+ */
+export function vecToBuffer(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}

package/dist/tools/index.js

@@ -1,5 +1,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { normPersistence } from '../types.js';
+import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from '../store/receipts.js';
+import { renderConflictResolution, resolveConflictPair } from '../conflict-service.js';
+import { normPersistence, normScope, resolveRecordScope } from '../types.js';
+import { scopeFilterOf, workspaceIdOf } from '../workspace.js';
 import { GRAPH_STATUS_LABELS } from '../prompts/graph-projection.js';
 const OFF_NOTICE = '本会话的记忆档位为"关闭":该会话对记忆系统完全隐身,不读取也不写入记忆。';
 const WRITE_ONLY_NOTICE = '本会话为只写模式:记忆照常沉淀,但不读取。';
@@ -9,37 +12,81 @@ export function registerMemoryTools(ctx, cfg, stores, logger, modes, live,
 ruminate) {
     if (!cfg.tools)
         return;
+    /**
+     * 沿父链解析**有效档位归属会话**(§A 修复)。
+     *
+     * 子代理以新 session id 调用工具时,其自身通常不在档位表里——原实现直接回落
+     * 全局默认档(auto),于是父会话被用户显式设为 `off`/只写时,**子代理仍能读到
+     * 用户明确关闭的记忆**,构成"用户显式指令被绕过"(P0)。
+     *
+     * 现改为沿 `session.header.parentSession` 上溯至**首个有显式档位的祖先**。
+     * 同步通路由 task_4 spike 实测确认(`findings.md §8`):子代理会话的 header
+     * **无条件**携带父会话 id(`dsh-subagent/.../child-agent.js:111-125`)。
+     *
+     * 多级链(孙代理等)需要按 id 取某个会话的 header → 走 `ctx.get('agents')`
+     * 的**宽容路径**(cordis 属性访问对未 inject 的服务会抛 "without inject";
+     * 同款先例见 `src/hooks/recall.ts:402-407,461`)。
+     *
+     * 降级(全部不抛错、不新增拒绝路径):
+     * - `exec.agent` 缺失 → 返回 undefined(保持既有 fail-open);
+     * - 服务缺失 / 链断 → 停止上溯,用自身 id(= 默认档,与修复前一致);
+     * - 链上做环检测,自环或成环都能终止。
+     */
+    const resolveModeOwner = (exec) => {
+        const agent = exec.agent;
+        const selfId = agent?.id;
+        if (selfId === undefined)
+            return undefined;
+        // 自身有显式档位 → 自己说了算(子代理会话也可被单独设置)
+        if (modes.hasEntry(selfId))
+            return selfId;
+        const seen = new Set([selfId]);
+        let cur = agent?.session?.header?.parentSession;
+        while (cur !== undefined && !seen.has(cur)) {
+            if (modes.hasEntry(cur))
+                return cur;
+            seen.add(cur);
+            // 继续上溯:取该会话的 header(服务缺失时返回 undefined → 循环自然结束)
+            const upstream = ctx.get?.('agents');
+            cur = upstream?.get?.(cur)?.session?.header?.parentSession;
+        }
+        return selfId; // 无祖先设过 → 自身(= 默认档,行为与修复前一致)
+    };
     /**
      * 调用会话的检索族(auto → undefined 不过滤;off/只写 → null 表示整体禁用)。
      * fail-open:exec.agent 缺失(宿主调用路径未带 agent 标识)按全族检索放行——
      * 档位隔离依赖宿主正确传递 exec.agent.id,缺失只告警一次不拒绝工具调用。
      */
     let warnedNoAgent = false;
-    const familyOfCaller = (agentId) => {
-        if (agentId === undefined) {
+    const familyOfCaller = (exec) => {
+        const owner = resolveModeOwner(exec);
+        if (owner === undefined) {
             if (!warnedNoAgent) {
                 warnedNoAgent = true;
                 logger.warn('[memory] 工具调用缺少 agent 标识(exec.agent 未传递),档位过滤退化为全族检索');
             }
             return undefined;
         }
-        const mode = modes.get(agentId);
+        const mode = modes.get(owner);
         if (mode === 'off')
             return null;
         // 只写会话拒读:与注入同属读维度,不拒则"不注入"从工具路径漏风
-        if (!modes.resolvedRecall(agentId, live.get().recall))
+        if (!modes.resolvedRecall(owner, live.get().recall))
             return null;
         return mode === 'auto' ? undefined : mode;
     };
     /** 拒读时的归因文案(familyOfCaller 判 null 后重查内存 Map,成本可忽略):
-     *  off 完全隐身 / 会话只写覆盖 / 全局召回关——三种停用各说各话,不谎报只写。 */
-    const blockNoticeOf = (agentId) => {
-        if (agentId !== undefined) {
-            if (modes.get(agentId) === 'off')
+     *  off 完全隐身 / 会话只写覆盖 / 全局召回关——三种停用各说各话,不谎报只写。
+     *  **注意按"有效档位归属会话"归因**:子代理拒读时文案取的是其祖先的档位,
+     *  而非子代理自身(后者未设置,会谎报成 off)。 */
+    const blockNoticeOf = (exec) => {
+        const owner = resolveModeOwner(exec);
+        if (owner !== undefined) {
+            if (modes.get(owner) === 'off')
                 return OFF_NOTICE;
-            if (modes.getRecall(agentId) === false)
+            if (modes.getRecall(owner) === false)
                 return WRITE_ONLY_NOTICE;
-            if (!modes.resolvedRecall(agentId, live.get().recall))
+            if (!modes.resolvedRecall(owner, live.get().recall))
                 return GLOBAL_OFF_NOTICE;
         }
         return OFF_NOTICE;
@@ -79,11 +126,17 @@ ruminate) {
             ],
         },
         execute: async (args, exec) => {
-            const family = familyOfCaller(exec.agent?.id);
+            const family = familyOfCaller(exec);
             if (family === null)
-                return { items: [], notice: blockNoticeOf(exec.agent?.id) };
+                return { items: [], notice: blockNoticeOf(exec) };
             const limit = Math.min(Math.max(args.limit ?? 5, 1), 20);
-            const hits = await stores.l1.search(args.query, limit, { type: args.type || undefined, family: family ?? undefined });
+            const hits = await stores.l1.search(args.query, limit, {
+                type: args.type || undefined,
+                family: family ?? undefined,
+                // §E 可见范围:`cfg.scope` 非 workspace 时恒为 undefined(= 不过滤)，
+                // 零漂移由 `scopeFilterOf` 一处收口保证，不靠各调用点各自判断。
+                workspaceId: scopeFilterOf(cfg.scope, exec),
+            });
             return {
                 items: hits.map((h) => ({
                     content: h.content,
@@ -128,8 +181,8 @@ ruminate) {
             ],
         },
         execute: async (args, exec) => {
-            if (familyOfCaller(exec.agent?.id) === null)
-                return { items: [], notice: blockNoticeOf(exec.agent?.id) };
+            if (familyOfCaller(exec) === null)
+                return { items: [], notice: blockNoticeOf(exec) };
             const limit = Math.min(Math.max(args.limit ?? 5, 1), 20);
             const records = await stores.l0.search(args.query, limit);
             return {
@@ -162,8 +215,8 @@ ruminate) {
             ],
         },
         execute: async (args, exec) => {
-            if (familyOfCaller(exec.agent?.id) === null)
-                return { content: blockNoticeOf(exec.agent?.id) };
+            if (familyOfCaller(exec) === null)
+                return { content: blockNoticeOf(exec) };
             const p = args.path.trim();
             let content;
             if (p === 'persona.md' || p === 'persona-chat.md' || p === 'persona' || p === 'persona-chat') {
@@ -174,7 +227,7 @@ ruminate) {
             }
             else {
                 // 场景文件在两族目录里按名查找(先本族后另一族)
-                const primary = familyOfCaller(exec.agent?.id) ?? 'chat';
+                const primary = familyOfCaller(exec) ?? 'chat';
                 const other = primary === 'chat' ? 'work' : 'chat';
                 content =
                     (await stores.scenes[primary].read(p)) ?? (await stores.scenes[other].read(p));
@@ -208,7 +261,7 @@ ruminate) {
      * 时间轴同时写顶层字段(时间增强列)与 metadata(列迁移前的兼容层,
      * 也是面板与图谱时间锚的读取点);`cf`/`rw` 落在 metadata.conflict/rewritten。
      */
-    function buildRecord(item, sceneName, now) {
+    function buildRecord(item, sceneName, now, workspaceId) {
         const content = String(item.content ?? '').trim();
         const type = ADD_TYPES.includes(String(item.type ?? '')) ? String(item.type) : 'episodic';
         const family = type.startsWith('work') ? 'work' : 'chat';
@@ -247,6 +300,9 @@ ruminate) {
             version: 0,
             metadata,
             family,
+            // §E 归属：与抽取管线**同一判据**（`resolveRecordScope`）。写入路径不止一条
+            // （pipeline / 本工具 / 批量导入），共用同一函数才不会有"某条路径忘了标归属"。
+            ...resolveRecordScope(normScope(cfg.scope), family, workspaceId),
             ...(validFrom !== undefined ? { validFrom } : {}),
             ...(validTo !== undefined ? { validTo } : {}),
             ...(persistence !== undefined ? { persistence } : {}),
@@ -295,14 +351,14 @@ ruminate) {
             },
             render: (_args, value) => [{ type: 'text', text: value.notice ?? ('已记录记忆 ' + (value.id ?? '')) }],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             if (!live.get().memoryMutate)
                 return { notice: MUTATE_OFF_NOTICE };
             const content = String(args.content ?? '').trim();
             if (!content)
                 return { notice: 'content 为空,未写入' };
             const scene = typeof args.scene === 'string' && args.scene.trim() ? args.scene.trim().slice(0, 120) : '__manual__';
-            const record = buildRecord(args, scene, Date.now());
+            const record = buildRecord(args, scene, Date.now(), workspaceIdOf(exec));
             await stores.l1.appendNew([record]);
             logger.info(`[memory] 高权限写入记忆(${record.type}${record.metadata?.hall ? '/' + String(record.metadata.hall) : ''},时间轴 ${record.persistence ?? '?'}):${record.content.slice(0, 120)}`);
             return { id: record.id };
@@ -361,7 +417,7 @@ ruminate) {
                 { type: 'text', text: value.notice ?? `已导入 ${value.written ?? 0} 条记忆` },
             ],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             if (!live.get().memoryMutate) {
                 return { written: 0, ids: [], skipped: [], notice: MUTATE_OFF_NOTICE };
             }
@@ -396,7 +452,7 @@ ruminate) {
                     return;
                 }
                 seen.add(key);
-                records.push(buildRecord(item, scene, now));
+                records.push(buildRecord(item, scene, now, workspaceIdOf(exec)));
             });
             if (records.length > 0)
                 await stores.l1.appendNew(records);
@@ -432,9 +488,12 @@ ruminate) {
             const query = String(args.query ?? '').trim();
             if (!query)
                 return { deleted: 0, ids: [], notice: 'query 为空,未删除' };
-            const family = familyOfCaller(exec.agent?.id);
+            const family = familyOfCaller(exec);
             const limit = Math.min(Math.max(args.limit ?? 3, 1), 10);
-            const hits = await stores.l1.search(query, limit, { family: family && family !== null ? family : undefined });
+            const hits = await stores.l1.search(query, limit, {
+                family: family && family !== null ? family : undefined,
+                workspaceId: scopeFilterOf(cfg.scope, exec),
+            });
             const ids = hits.map((h) => h.id);
             if (ids.length === 0)
                 return { deleted: 0, ids: [], notice: '未找到匹配的记忆,未删除' };
@@ -480,9 +539,9 @@ ruminate) {
             render: (_args, value) => [{ type: 'text', text: value.notice ?? renderGraphCards(value.items ?? []) }],
         },
         execute: async (args, exec) => {
-            const family = familyOfCaller(exec.agent?.id);
+            const family = familyOfCaller(exec);
             if (family === null)
-                return { items: [], notice: blockNoticeOf(exec.agent?.id) };
+                return { items: [], notice: blockNoticeOf(exec) };
             const graph = stores.graph;
             if (!graph)
                 return { items: [], notice: GRAPH_OFF_NOTICE };
@@ -524,9 +583,9 @@ ruminate) {
             render: (_args, value) => [{ type: 'text', text: value.notice ?? (value.node || '(节点不存在)') }],
         },
         execute: async (args, exec) => {
-            const family = familyOfCaller(exec.agent?.id);
+            const family = familyOfCaller(exec);
             if (family === null)
-                return { notice: blockNoticeOf(exec.agent?.id) };
+                return { notice: blockNoticeOf(exec) };
             const graph = stores.graph;
             if (!graph)
                 return { notice: GRAPH_OFF_NOTICE };
@@ -691,7 +750,121 @@ ruminate) {
             };
         },
     }));
-    logger.info('[memory] 工具已注册: memory_search / conversation_search / memory_read_scene / memory_search_graph / memory_expand_graph_node,及高权限 memory_add/memory_import/memory_delete / memory_ruminate / memory_ruminate_cancel / memory_ruminate_status');
+    // ── memory_receipts: §B 决策凭证回溯(读;受与 memory_search 同款档位门) ──
+    // 为什么给它一个模型可见的工具:凭证链的价值全在"事后能问"。若只有 RPC 端点,
+    // 用户得自己去浏览器/curl 才能回溯,而真正会问「这条记忆怎么来的」的场合
+    // 恰恰是在对话里。工具是这条链唯一的**用户可见出口**。
+    ctx.tools.register(defineTool({
+        name: 'memory_receipts',
+        description: '回溯 L1 记忆的**去重决策出处**(决策凭证链)。按 record_id 问"这条记忆出自哪一轮蒸馏、当时看到什么候选池、被判定成了什么";按 run_id 问"那一轮蒸馏都判了什么"(跨多条记录)。两者同给即问"这条记录在那一轮里被判成了什么"。返回决策当时的结论与输入指纹,**不含记忆正文**。注意:由于记录 id 每轮新铸,按 record_id 查询目前通常只返回一条——它回答的是"出自哪",不是"历次变更"。',
+        parameters: {
+            record_id: { type: 'string', description: '按记忆记录 id 回溯(与 run_id 至少给一个)' },
+            run_id: { type: 'string', description: '按某轮蒸馏的 run id 回溯(与 record_id 至少给一个)' },
+            limit: { type: 'number', description: `最大返回条数(默认 20,上限 ${RECEIPTS_QUERY_LIMIT_MAX})` },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    dimension: { type: 'string', description: '命中的维度:record / run / both / none' },
+                    items: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                receipt_id: { type: 'string' },
+                                run_id: { type: 'string' },
+                                record_id: { type: 'string' },
+                                kind: { type: 'string', description: 'store / update / merge / skip / conflict / skip_missing' },
+                                input_digest: { type: 'string' },
+                                decided_at: { type: 'string' },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    total: { type: 'number' },
+                    notice: { type: 'string', description: '非结果的状态提示(如本会话记忆已关闭)' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                { type: 'text', text: value.notice ?? renderReceipts(value.dimension, value.items ?? [], value.total ?? 0) },
+            ],
+        },
+        execute: async (args, exec) => {
+            // 档位拒读门与 memory_search 同款:off 会话对记忆系统完全隐身,不该反过来
+            // 能内省记忆系统的判定史(凭证虽不含正文,但泄漏"存在哪些记录/判了什么")。
+            const family = familyOfCaller(exec);
+            if (family === null)
+                return { dimension: 'none', items: [], total: 0, notice: blockNoticeOf(exec) };
+            const query = {
+                recordId: typeof args.record_id === 'string' && args.record_id.trim() ? args.record_id.trim() : undefined,
+                runId: typeof args.run_id === 'string' && args.run_id.trim() ? args.run_id.trim() : undefined,
+            };
+            const dimension = dimensionOf(query);
+            if (dimension === 'none') {
+                return {
+                    dimension,
+                    items: [],
+                    total: 0,
+                    notice: '需要至少一个维度:record_id(这条记忆出自哪一轮、当时候选池是什么)或 run_id(某一轮蒸馏的全部决策)。' +
+                        '不提供"查全部凭证"——那等于把整库判定史一次性导出。',
+                };
+            }
+            const limit = Math.min(Math.max(args.limit ?? 20, 1), RECEIPTS_QUERY_LIMIT_MAX);
+            const rows = stores.l1.listReceipts({ ...query, limit });
+            return { dimension, items: rows.map(toReceiptView), total: stores.l1.countReceipts(query) };
+        },
+    }));
+    // ── memory_resolve_conflict: §C 矛盾冻结的人工裁决出口 ──
+    // 冻结把裁决权交还给人,那么**必须**有一个"人能把结论说回去"的出口——
+    // 否则待裁决队列是个只进不出的黑洞,安全阀(task_24)会成为唯一出路,
+    // 那等于把 opt-in 的冻结悄悄退回成"超时后机器自己判"。
+    ctx.tools.register(defineTool({
+        name: 'memory_resolve_conflict',
+        description: '裁决一条**矛盾冻结**的待裁决对(§C)。冻结产生的冲突对停放在待裁决队列里,双方记忆都不被改写,直到你在这里给出结论:winner(判 LLM 建议的胜方为真,败方从检索中退场)、loser(判败方为真)、both(判定两者其实是各自独立的事实,都保留)。需先开启 conflictFreeze 配置;待裁决对可用 memory_conflicts 查看。',
+        parameters: {
+            pair_id: { type: 'string', description: '待裁决对的 pair_id(来自待裁决队列)' },
+            outcome: { type: 'string', description: '裁决结论:winner | loser | both' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    pair_id: { type: 'string' },
+                    outcome: { type: 'string' },
+                    resolved_at: { type: 'string', description: '裁决时刻(ISO);空串表示未生效' },
+                    removed_record_id: { type: 'string', description: '因裁决从检索中退场的记录 id(无则空串)' },
+                    notice: { type: 'string', description: '非结果的状态提示(如未开启冻结 / 该对不存在或已裁决)' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: renderConflictResolution(value) }],
+        },
+        execute: async (args, exec) => {
+            const family = familyOfCaller(exec);
+            if (family === null) {
+                return { pair_id: '', outcome: '', resolved_at: '', removed_record_id: '', notice: blockNoticeOf(exec) };
+            }
+            const empty = { pair_id: '', outcome: '', resolved_at: '', removed_record_id: '' };
+            const pairId = typeof args.pair_id === 'string' ? args.pair_id.trim() : '';
+            const outcome = typeof args.outcome === 'string' ? args.outcome.trim() : '';
+            if (!pairId)
+                return { ...empty, notice: '需要 pair_id:待裁决对没有"全部裁决"这种用法。' };
+            return resolveConflictPair({ l1: stores.l1, conflictFreezeEnabled: cfg.conflictFreeze?.enabled === true }, pairId, outcome);
+        },
+    }));
+    logger.info('[memory] 工具已注册: memory_search / conversation_search / memory_read_scene / memory_receipts / memory_search_graph / memory_expand_graph_node,及高权限 memory_add/memory_import/memory_delete / memory_resolve_conflict / memory_ruminate / memory_ruminate_cancel / memory_ruminate_status');
+}
+/** 凭证回溯的人类可读渲染(含"还有多少条没显示")。 */
+function renderReceipts(dimension, items, total) {
+    const what = dimension === 'record' ? '该记录出自哪一轮' : dimension === 'run' ? '该批次的全部决策' : '该记录在该批次中的决策';
+    if (items.length === 0)
+        return `(${what}:没有查到凭证——该 id 可能从未走过 L1 去重,或凭证已超出保留窗口)`;
+    const lines = items.map((it, i) => `${i + 1}. [${it.kind ?? ''}] run=${it.run_id ?? ''} record=${it.record_id ?? ''}` +
+        `\n   时刻: ${it.decided_at ?? ''}\n   输入指纹: ${(it.input_digest ?? '').slice(0, 16)}…`);
+    const more = total > items.length ? `\n…共 ${total} 条,已显示 ${items.length} 条` : '';
+    return `${what}(${items.length} 条):\n${lines.join('\n')}${more}`;
 }
 function renderGraphCards(items) {
     if (!items || items.length === 0)

package/dist/types.d.ts

@@ -83,6 +83,48 @@ export interface ExtractedMemory {
 export declare function normExtractedFamily(raw: unknown): MemoryFamily | undefined;
 /** 记录族三级兜底链:会话档位强制(纯档)→ 抽取显式判定(auto)→ type 前缀推导(旧输出兜底)。 */
 export declare function resolveRecordFamily(forced: MemoryFamily | undefined, extracted: unknown, type: string): MemoryFamily;
+/**
+ * 存储作用域(§E):**可见范围**,与 family(内容类型)正交(ADR-0008 条 1)。
+ * - `global`    —— 跨工作区可见(默认;既有单根数据全部归此档);
+ * - `workspace` —— 仅在本工作区可见。
+ *
+ * 正交的含义是**四象限都存在**。把这条轴与 family 合并(如"work 族一律 workspace")
+ * 会把二维决策压成一维偏好,日后任何一格需要例外时都要返工。
+ */
+export type MemoryScope = 'global' | 'workspace';
+/** 配置侧的作用域**模式**取值(与记录级归属同词汇,但语义是「新记忆默认归哪档」)。 */
+export type ScopeMode = MemoryScope;
+/** 作用域归一:非法/缺省一律归 `global`(ADR-0008 条 4:不抛错、不阻断启动)。 */
+export declare function normScope(raw: unknown): MemoryScope;
+/**
+ * 可见性判定(§E **读取侧**,与 `resolveRecordScope` 是同一判据的两面)。
+ * `global` 记录对任何工作区可见;`workspace` 记录只对**归属工作区相同**的调用可见。
+ *
+ * `want` 为空串表示"不做过滤"——调用方没传工作区标识(即 `cfg.scope='global'`)时
+ * 必须**看不见这个函数存在**,而不是"过滤掉一切"。两条路径分开写死,
+ * 免得日后有人把"没传"误当成"匹配空归属"。
+ */
+export declare function isScopeVisible(scope: unknown, workspaceId: unknown, want: string): boolean;
+/**
+ * 记录级归属判定(§E 写入侧)。与 `resolveRecordFamily` 同构的三级链:
+ * **记录显式覆盖 → 配置模式默认 → 兜底 global**。
+ *
+ * 三条刻意的规则:
+ * ① `workspace` 模式下 **work 族默认归 workspace、chat 族默认仍 global**——
+ *    个人记忆本就该跨项目("用户偏好简洁回答"不属于任何项目),而污染面恰在项目之间。
+ *    注意这是**默认值不是推导规则**:`explicit` 能把它推翻(四象限)。
+ * ② **工作区标识缺失时回落 `global`**——不抛、不阻断。宁可退化成"全局可见",
+ *    也不能因为拿不到 cwd 就让记忆**写不进去**(fail-open,与本仓库既有降级同向)。
+ * ③ `cfg='global'` 时**不写**工作区归属(清空 `workspaceId`)——保证既有部署零漂移:
+ *    检索侧"是否传 workspaceId"就是开关,不传即不过滤。
+ *
+ * @param explicit 记录级显式声明(四象限的载体)。**当前无产品调用方**,
+ *   存在的意义是把"正交"从文档里的一句话变成可测的语义;写入入口属未排期项。
+ */
+export declare function resolveRecordScope(cfgScope: ScopeMode, family: MemoryFamily, workspaceId?: string, explicit?: MemoryScope): {
+    scope: MemoryScope;
+    workspaceId: string;
+};
 /** L1 持久化记录(磁盘与 DB 的权威形状;version/source_message_ids/metadata 由写入侧补默认)。 */
 export interface MemoryRecord {
     id: string;
@@ -104,6 +146,12 @@ export interface MemoryRecord {
     sessionId?: string;
     /** 所属族(写入缺省由 familyForType(type) 回填;召回/浏览/去重候选按族过滤的唯一依据)。 */
     family?: MemoryFamily;
+    /** 可见范围(§E;写入缺省由 `resolveRecordScope` 回填,缺省 `global`)。
+     *  与 family 正交:family 问"这是什么内容",scope 问"它该在多大范围内可见"。 */
+    scope?: MemoryScope;
+    /** 工作区标识(仅 `scope='workspace'` 时非空;`global` 记录恒为空串)。
+     *  取值为会话 cwd 的归一形态——"哪个工作区"由会话本身回答,不做额外配置。 */
+    workspaceId?: string;
     /**
      * 有效期起(epoch ms):该事实在**真实世界**开始成立的时间。
      * 与 createdAt(入库时间)是两条不同的轴——"2026-03 在 A 项目"这条事实,

package/dist/types.js

@@ -36,3 +36,43 @@ export function normExtractedFamily(raw) {
 export function resolveRecordFamily(forced, extracted, type) {
     return forced ?? normExtractedFamily(extracted) ?? familyForType(type);
 }
+/** 作用域归一:非法/缺省一律归 `global`(ADR-0008 条 4:不抛错、不阻断启动)。 */
+export function normScope(raw) {
+    return typeof raw === 'string' && raw.toLowerCase() === 'workspace' ? 'workspace' : 'global';
+}
+/**
+ * 可见性判定(§E **读取侧**,与 `resolveRecordScope` 是同一判据的两面)。
+ * `global` 记录对任何工作区可见;`workspace` 记录只对**归属工作区相同**的调用可见。
+ *
+ * `want` 为空串表示"不做过滤"——调用方没传工作区标识(即 `cfg.scope='global'`)时
+ * 必须**看不见这个函数存在**,而不是"过滤掉一切"。两条路径分开写死,
+ * 免得日后有人把"没传"误当成"匹配空归属"。
+ */
+export function isScopeVisible(scope, workspaceId, want) {
+    if (normScope(scope) === 'global')
+        return true;
+    return typeof workspaceId === 'string' && workspaceId !== '' && workspaceId === want;
+}
+/**
+ * 记录级归属判定(§E 写入侧)。与 `resolveRecordFamily` 同构的三级链:
+ * **记录显式覆盖 → 配置模式默认 → 兜底 global**。
+ *
+ * 三条刻意的规则:
+ * ① `workspace` 模式下 **work 族默认归 workspace、chat 族默认仍 global**——
+ *    个人记忆本就该跨项目("用户偏好简洁回答"不属于任何项目),而污染面恰在项目之间。
+ *    注意这是**默认值不是推导规则**:`explicit` 能把它推翻(四象限)。
+ * ② **工作区标识缺失时回落 `global`**——不抛、不阻断。宁可退化成"全局可见",
+ *    也不能因为拿不到 cwd 就让记忆**写不进去**(fail-open,与本仓库既有降级同向)。
+ * ③ `cfg='global'` 时**不写**工作区归属(清空 `workspaceId`)——保证既有部署零漂移:
+ *    检索侧"是否传 workspaceId"就是开关,不传即不过滤。
+ *
+ * @param explicit 记录级显式声明(四象限的载体)。**当前无产品调用方**,
+ *   存在的意义是把"正交"从文档里的一句话变成可测的语义;写入入口属未排期项。
+ */
+export function resolveRecordScope(cfgScope, family, workspaceId, explicit) {
+    const wantWorkspace = explicit ?? (cfgScope === 'workspace' && family === 'work' ? 'workspace' : 'global');
+    // 没有工作区标识就无从谈"本工作区"——无论请求来自默认还是显式,一律回落 global
+    if (wantWorkspace === 'workspace' && workspaceId)
+        return { scope: 'workspace', workspaceId };
+    return { scope: 'global', workspaceId: '' };
+}

package/dist/workspace.d.ts

@@ -0,0 +1,46 @@
+/** 会话上下文的最小形状(与 `tools/index.ts` 的 `ToolExecLike` 同源,只取 cwd)。 */
+export interface WorkspaceExecLike {
+    agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    };
+}
+/**
+ * 把 cwd 归一成工作区标识。**纯字符串操作**——不碰文件系统、不抛、无 I/O。
+ *
+ * 三条归一:① `path.resolve` 吃掉 `..` 与尾分隔符;② Windows 大小写不敏感 →
+ * 转小写(否则 `E:\proj` 与 `e:\proj` 会被当成两个工作区,记忆凭空分成两份);
+ * ③ 空/非字符串 → `undefined`(= 不做隔离,由调用方回落)。
+ *
+ * @returns 归一后的绝对路径;无法归一时 `undefined`。
+ */
+export declare function normalizeWorkspacePath(raw: unknown, platform?: NodeJS.Platform): string | undefined;
+/**
+ * 从工具执行上下文取当前工作区标识。取不到 → `undefined`(**不隔离**)。
+ *
+ * 这是 §E 唯一从宿主读工作区的入口——所有调用点共用它,免得某处自己拼
+ * `exec.agent.session.header.cwd` 而漏掉归一(那会让两个拼写不同的同一目录
+ * 各写各的归属)。
+ */
+export declare function workspaceIdOf(exec: unknown): string | undefined;
+/**
+ * §E 统一的「要不要过滤」判据:配置归一后**不是** `workspace` 时返回 `undefined`,
+ * 调用方把它原样传给 `L1SearchOptions.workspaceId` → 走"不过滤"分支。
+ *
+ * 把判断收在这**一个**函数里,是为了让**零漂移成为结构性保证**:
+ * 既有部署(`scope='global'`)在任何调用点都**不可能**意外传进一个工作区标识。
+ * 若让每个调用点自己去读 `cfg.scope`,迟早有一处漏判——而漏判的表现是
+ * "某条路径悄悄不做隔离",不会有任何报错。
+ */
+export declare function scopeFilterOf(cfgScope: unknown, exec: unknown): string | undefined;
+/**
+ * 按会话 id 解析工作区标识(**写入侧**用:后台蒸馏手上只有 `sessionId`,没有 `exec`)。
+ *
+ * 走 `ctx.get('agents')` 的**宽容路径**——与 §A 的多级父链解析同一招,
+ * 刻意不把它写进 `inject`(声明成硬依赖会让宿主缺该服务时整棵插件树加载失败)。
+ * 任何一步拿不到(服务缺失 / agent 不在 / header 无 cwd)→ `undefined` = 不隔离。
+ */
+export declare function sessionWorkspaceIdOf(ctx: unknown, sessionId: string): string | undefined;

package/dist/workspace.js

@@ -0,0 +1,105 @@
+/**
+ * §E 工作区标识解析:从会话上下文取"当前工作区",供存储作用域过滤使用。
+ *
+ * ## 为什么是 cwd,而不是 `ctx.workspaceRegistry` 的 `WorkspaceId`
+ *
+ * DSH 宿主**已有**工作区实体(`@deepseek-ai/dsh-workspace`):`Workspace.id` 是
+ * 一个 uuid,文档明确写着 *"A generated uuid, never the path: path normalization
+ * rewrites paths, and a reference anchor must stay stable."* 看似该用它。但四条理由
+ * 决定我们用 **canonical cwd**:
+ *
+ * 1. **同步可得**。`session.header.cwd` 与 §A 用的 `session.header.parentSession`
+ *    是**同一条通路**(`dsh-session` 的 `SessionHeader`,两个字段相邻),
+ *    §A 的 spike 已经把这条通路实测过了——零新增风险。而 `WorkspaceId` 要经
+ *    `workspaceRegistry.resolveByPath()`,是 **async**。
+ * 2. **不能声明 inject**。`workspaceRegistry` 若是硬依赖,宿主缺该服务时**整棵插件树
+ *    加载失败**——违反 ADR-0008 条 4。走 `ctx.get()` 宽容路径虽可行,但那就不是
+ *    "同步可得"了,退化成异步 + 服务缺失分支。
+ * 3. **宿主自己就拿 cwd 当工作区身份**。`Workspace` 的成员判据原文:
+ *    *"Membership requires both an id in that account and a session header whose
+ *    canonical cwd equals the workspace path."* —— cwd 是宿主认可的身份来源,
+ *    不是我们另造的标尺。
+ * 4. **uuid 需要一个"已注册"的工作区记录**。消费者不该为了记忆隔离,先要求用户
+ *    去宿主里注册工作区。未注册目录在 uuid 方案下**没有 id**,只能整片回落 global,
+ *    等于隔离静默失效。
+ *
+ * ## 已知边界(如实标注,非"待办"而是"选择的代价")
+ *
+ * 本实现用**字符串归一**(`path.resolve` + Windows 小写),**不解析符号链接**;
+ * 宿主 `realpathNormalize()` 走 `fs.realpath`,两者对符号链接拼写不同的同一目录
+ * 会给出不同标识。后果是**过度隔离**(同一目录的两种拼写互相看不见),而非泄漏。
+ * 取这个方向是因为:拼写差异在实践中罕见(同一会话的 cwd 来自同一来源),
+ * 而"过度隔离"至少是安全方向;且 `ctr.realpath` 会**在路径不存在时 reject**,
+ * 把一次 fs 失败带进写入与召回主链路,代价高于收益。
+ *
+ * **另注**:`realpathNormalize` 是 async 且会抛,若要接它必须包 try/catch 并回落——
+ * 这属可选精化,已登记为开放项,不在本波做。
+ */
+import * as path from 'node:path';
+import { normScope } from './types.js';
+/**
+ * 把 cwd 归一成工作区标识。**纯字符串操作**——不碰文件系统、不抛、无 I/O。
+ *
+ * 三条归一:① `path.resolve` 吃掉 `..` 与尾分隔符;② Windows 大小写不敏感 →
+ * 转小写(否则 `E:\proj` 与 `e:\proj` 会被当成两个工作区,记忆凭空分成两份);
+ * ③ 空/非字符串 → `undefined`(= 不做隔离,由调用方回落)。
+ *
+ * @returns 归一后的绝对路径;无法归一时 `undefined`。
+ */
+export function normalizeWorkspacePath(raw, platform = process.platform) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const resolved = path.resolve(trimmed);
+        return platform === 'win32' ? resolved.toLowerCase() : resolved;
+    }
+    catch {
+        // 理论上不会走到(纯字符串解析),但宁可回落也不让一次路径解析炸掉蒸馏
+        return undefined;
+    }
+}
+/**
+ * 从工具执行上下文取当前工作区标识。取不到 → `undefined`(**不隔离**)。
+ *
+ * 这是 §E 唯一从宿主读工作区的入口——所有调用点共用它,免得某处自己拼
+ * `exec.agent.session.header.cwd` 而漏掉归一(那会让两个拼写不同的同一目录
+ * 各写各的归属)。
+ */
+export function workspaceIdOf(exec) {
+    const cwd = exec?.agent?.session?.header?.cwd;
+    return normalizeWorkspacePath(cwd);
+}
+/**
+ * §E 统一的「要不要过滤」判据:配置归一后**不是** `workspace` 时返回 `undefined`,
+ * 调用方把它原样传给 `L1SearchOptions.workspaceId` → 走"不过滤"分支。
+ *
+ * 把判断收在这**一个**函数里,是为了让**零漂移成为结构性保证**:
+ * 既有部署(`scope='global'`)在任何调用点都**不可能**意外传进一个工作区标识。
+ * 若让每个调用点自己去读 `cfg.scope`,迟早有一处漏判——而漏判的表现是
+ * "某条路径悄悄不做隔离",不会有任何报错。
+ */
+export function scopeFilterOf(cfgScope, exec) {
+    if (normScope(cfgScope) !== 'workspace')
+        return undefined;
+    return workspaceIdOf(exec);
+}
+/**
+ * 按会话 id 解析工作区标识(**写入侧**用:后台蒸馏手上只有 `sessionId`,没有 `exec`)。
+ *
+ * 走 `ctx.get('agents')` 的**宽容路径**——与 §A 的多级父链解析同一招,
+ * 刻意不把它写进 `inject`(声明成硬依赖会让宿主缺该服务时整棵插件树加载失败)。
+ * 任何一步拿不到(服务缺失 / agent 不在 / header 无 cwd)→ `undefined` = 不隔离。
+ */
+export function sessionWorkspaceIdOf(ctx, sessionId) {
+    try {
+        const agents = ctx?.get?.('agents');
+        const cwd = agents?.get?.(sessionId)?.session?.header?.cwd;
+        return normalizeWorkspacePath(cwd);
+    }
+    catch {
+        return undefined;
+    }
+}