@yandy0725/memory-core 1.0.1 → 2.0.1

package/dist/orchestration/surfacing.js

@@ -1,4 +1,8 @@
-import { buildSideQueryTask } from "../injection.js";
+import { buildSideQueryTask, renderSurfacedEntries } from "../injection.js";
+/** 去掉已注入的文件，得到真正进入侧查询的候选清单。 */
+function candidates(input) {
+    return input.manifest.filter((entry) => !input.injectedFiles.has(entry.file));
+}
 /** 从侧查询的回复里解析 `selected_files`，只保留确实在候选清单里的文件。 */
 function parseSelectedFiles(result, candidates, maxFiles) {
     try {
@@ -13,38 +17,30 @@ function parseSelectedFiles(result, candidates, maxFiles) {
         return [];
     }
 }
-/**
- * 跑一轮轻量侧查询，选出与用户输入相关的 entry 文件名。
- *
- * 超时/失败一律返回 `[]`，**没有回退**：auto-surfacing 是纯增益，选不出来就不注入，
- * 绝不因为侧查询挂了而打断用户这一轮。
- *
- * 返回的是**文件名**，不是注入内容 —— 「注入到哪个通道、本 session 已注入过哪些」是适配层的事。
- */
-export async function runSideQuery(opts, ports) {
-    const candidates = opts.manifest.filter((entry) => !opts.injectedFiles.has(entry.file));
-    if (candidates.length === 0)
-        return [];
-    const task = buildSideQueryTask(candidates, opts.userPrompt, opts.maxFiles);
-    try {
-        const result = await ports.headless.run({
-            task,
-            cwd: opts.cwd,
-            model: opts.model,
-            effort: opts.effort,
-            maxTurns: 1,
-            timeoutMs: 30_000,
-            // 零工具就是意图：侧查询只需要回一个 JSON，给它任何工具都是白烧 token。
-            builtinTools: "none",
-            memoryTool: null,
-            sessionPersistence: opts.sessionPersistence,
-        });
-        if (result === null)
-            return [];
-        return parseSelectedFiles(result, candidates, opts.maxFiles);
-    }
-    catch {
-        return [];
-    }
-}
+/** autoSurfacing 描述符：core 自读 `cfg.autoSurfacing` 的预算，适配层只给宿主数据。 */
+export const autoSurfacing = {
+    id: "autoSurfacing",
+    plan: {
+        maxTurns: 1,
+        timeoutMs: 30_000,
+        memoryTool: null,
+        lock: "none",
+        errorPolicy: "swallow",
+    },
+    buildPrompt(cfg, _deps, input) {
+        const remaining = candidates(input);
+        if (remaining.length === 0)
+            return null;
+        return buildSideQueryTask(remaining, input.userPrompt, cfg.autoSurfacing.maxFiles);
+    },
+    async parse(cfg, deps, input, text) {
+        const selected = parseSelectedFiles(text, candidates(input), cfg.autoSurfacing.maxFiles);
+        // 只返回真正渲染出来的文件：预算被 maxInjectionBytes 截断、或 readEntry 读不到时，
+        // 未渲染的文件不能进 `files`，否则适配层会把它们标记成已注入、整个 session 不再浮现。
+        return renderSurfacedEntries(deps.store, selected, cfg.autoSurfacing.maxEntryBytes, cfg.autoSurfacing.maxInjectionBytes);
+    },
+    notCompleted() {
+        return { files: [], content: "" };
+    },
+};
 //# sourceMappingURL=surfacing.js.map

package/dist/orchestration/surfacing.js.map

@@ -1 +1 @@
-{"version":3,"file":"surfacing.js","sourceRoot":"","sources":["../../src/orchestration/surfacing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAmBrD,kDAAkD;AAClD,SAAS,kBAAkB,CAAC,MAAc,EAAE,UAA2B,EAAE,QAAgB;IACxF,IAAI,CAAC;QACJ,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAClE,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,KAAK,GAAa,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;QACpD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAsB,EACtB,KAAsC;IAEtC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5E,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;YACvC,IAAI;YACJ,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,MAAM;YACjB,2CAA2C;YAC3C,YAAY,EAAE,MAAM;YACpB,UAAU,EAAE,IAAI;YAChB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;SAC3C,CAAC,CAAC;QACH,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAC/B,OAAO,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC"}
+{"version":3,"file":"surfacing.js","sourceRoot":"","sources":["../../src/orchestration/surfacing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAkB5E,+BAA+B;AAC/B,SAAS,UAAU,CAAC,KAAqB;IACxC,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,kDAAkD;AAClD,SAAS,kBAAkB,CAAC,MAAc,EAAE,UAA2B,EAAE,QAAgB;IACxF,IAAI,CAAC;QACJ,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAClE,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,KAAK,GAAa,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;QACpD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAgD;IACzE,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE;QACL,QAAQ,EAAE,CAAC;QACX,SAAS,EAAE,MAAM;QACjB,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,SAAS;KACtB;IACD,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK;QAC5B,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,kBAAkB,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACpF,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;QACjC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACzF,0DAA0D;QAC1D,qDAAqD;QACrD,OAAO,qBAAqB,CAC3B,IAAI,CAAC,KAAK,EACV,QAAQ,EACR,GAAG,CAAC,aAAa,CAAC,aAAa,EAC/B,GAAG,CAAC,aAAa,CAAC,iBAAiB,CACnC,CAAC;IACH,CAAC;IACD,YAAY;QACX,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnC,CAAC;CACD,CAAC"}

package/dist/orchestration/task.d.ts

@@ -0,0 +1,84 @@
+import { type MemoryConfig, type ModelTask, type SessionPersistenceConfig } from "../config.js";
+import { type MemoryStore } from "../store/memory-store.js";
+import type { MemoryAction } from "../tool/actions.js";
+import type { HeadlessRunRequest, HostTranscriptPort, IncompleteOutcome, OrchestrationPorts } from "./ports.js";
+/** 任务描述符里的编排骨架：全是 core 常量；两个 skip 由 `lock` 派生，不再单独编码。 */
+export interface TaskPlan {
+    maxTurns?: number;
+    timeoutMs: number;
+    /** 注入子会话的 memory 工具 action 集；`null` = 不注入。三个任务的 builtinTools 恒为 "none"。 */
+    memoryTool: readonly MemoryAction[] | null;
+    /** 互斥与快照：none / 整轮逻辑锁 / 逻辑锁 + 进入时全目录快照。 */
+    lock: "none" | "logical" | "logical+snapshot";
+    /** 端口抛错（传输级失败）时怎么办：surfacing 吞、extract 与 dream 上抛。 */
+    errorPolicy: "swallow" | "rethrow";
+}
+/** 任务需要的 core 侧原料：store 恒有；transcript 只有 extract 用。 */
+export interface TaskDeps {
+    store: MemoryStore;
+    transcript?: HostTranscriptPort;
+}
+/** 一次 `runTask` 调用的上下文：config 由 core 自己消费，适配层不再把它摊平成参数。 */
+export interface TaskContext {
+    cfg: MemoryConfig;
+    cwd: string;
+    store: MemoryStore;
+    ports: OrchestrationPorts;
+    signal?: AbortSignal;
+}
+/** `buildRequest` 的宿主侧参数：`cfg` 的值与 plan 一起在这里合流成端口请求。 */
+export interface RequestHost {
+    /** 子会话 cwd；三个任务恒为 memoryDir。 */
+    cwd: string;
+    /** 宿主自己的模型标识，已由 `runTask` 从 `cfg` 解析（`requiredModel`）。 */
+    model: string;
+    /** 宿主自己的思考/推理档位，core 原样透传。 */
+    effort?: string;
+    /** 宿主的会话持久化开关，core 原样透传。 */
+    sessionPersistence?: SessionPersistenceConfig;
+    signal?: AbortSignal;
+}
+/** `memory` 工具的写入回调；只有实现了 `memoryToolHooks` 的描述符会产出它。 */
+export type MemoryToolOnWrite = (info: {
+    action: MemoryAction;
+    name?: string;
+}) => void;
+/** `notCompleted` 收的 `why`：core 自己的判定，或端口给的非 completed 结果。 */
+export type Incomplete = {
+    status: "no-input";
+} | {
+    status: "lock-busy";
+} | IncompleteOutcome;
+export interface MemoryTask<I, R> {
+    readonly id: ModelTask;
+    readonly plan: TaskPlan;
+    /** `null` = core 自己判定这一轮不跑（候选为空、消息为空）。预算值自己从 `cfg` 读。 */
+    buildPrompt(cfg: MemoryConfig, deps: TaskDeps, input: I): string | null;
+    /** 回复 → 结果。必须防御式：dsh 的 stream 通道拿不到强制结构化输出。 */
+    parse(cfg: MemoryConfig, deps: TaskDeps, input: I, text: string): R | Promise<R>;
+    /** core 没跑、或端口没跑成时怎么呈现（三个任务词汇不同的唯一合法处）。 */
+    notCompleted(cfg: MemoryConfig, deps: TaskDeps, input: I, why: Incomplete): R;
+    /** 只有 extractMemories 实现：把 `input.onWrite` 透给子会话的工具。 */
+    memoryToolHooks?(input: I): {
+        onWrite?: MemoryToolOnWrite;
+    } | undefined;
+}
+/**
+ * 构造端口请求：plan 的取值与 `runTask` 从 `cfg` 解析出的宿主参数在这里合流。
+ *
+ * 只收构造请求真正需要的入参，`cfg` 与 `TaskContext` 都不进来：解析留在 `runTask`
+ * （model / effort / sessionPersistence 都从 `cfg` 读），请求形状因此只在这里写一遍。
+ */
+export declare function buildRequest(task: MemoryTask<unknown, unknown>, prompt: string, host: RequestHost, onWrite?: MemoryToolOnWrite): HeadlessRunRequest;
+/**
+ * 三个 LLM 任务的通用编排。顺序是契约：
+ *
+ * 1. 读模型（缺模型在这里抛可读错误，而不是发出 `model: ""` 的请求）；
+ * 2. 读 effort / sessionPersistence；
+ * 3. `buildPrompt`，`null` → `notCompleted({ status: "no-input" })`（在**任何锁之前**）；
+ * 4. 施加 `plan.lock`（`logical` 拿不到锁 → `notCompleted({ status: "lock-busy" })`）；
+ * 5. 端口调用（传输级异常按 `plan.errorPolicy` 收口）；
+ * 6. `completed` → `parse`；其余 → `notCompleted(outcome)`。
+ */
+export declare function runTask<I, R>(task: MemoryTask<I, R>, input: I, ctx: TaskContext): Promise<R>;
+//# sourceMappingURL=task.d.ts.map

package/dist/orchestration/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/orchestration/task.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/task.js

@@ -0,0 +1,145 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { requiredModel, } from "../config.js";
+import { BACKUP_DIR } from "../store/memory-store.js";
+import { createSnapshot } from "../store/snapshot.js";
+import { isReservedWindowsName } from "../store/windows-names.js";
+/**
+ * 构造端口请求：plan 的取值与 `runTask` 从 `cfg` 解析出的宿主参数在这里合流。
+ *
+ * 只收构造请求真正需要的入参，`cfg` 与 `TaskContext` 都不进来：解析留在 `runTask`
+ * （model / effort / sessionPersistence 都从 `cfg` 读），请求形状因此只在这里写一遍。
+ */
+export function buildRequest(task, prompt, host, onWrite) {
+    const plan = task.plan;
+    return {
+        task: prompt,
+        cwd: host.cwd,
+        model: host.model,
+        effort: host.effort,
+        maxTurns: plan.maxTurns,
+        timeoutMs: plan.timeoutMs,
+        signal: host.signal,
+        // 三个任务的 builtinTools 恒为 "none"：侧查询只要一个 JSON，dream / extract 只走 memory 工具。
+        builtinTools: "none",
+        memoryTool: plan.memoryTool === null
+            ? null
+            : {
+                actions: plan.memoryTool,
+                skipLogicalLock: plan.lock !== "none",
+                skipSnapshot: plan.lock === "logical+snapshot",
+                onWrite,
+            },
+        // 继承规则（per-task ?? defaults）由调用方在传参前解析完，这里只做透传。
+        sessionPersistence: host.sessionPersistence,
+    };
+}
+/** 会话持久化的继承规则：per-task ?? `defaults`。config 消费点收在 core，适配层不再各写一份。 */
+function resolveSessionPersistence(cfg, task) {
+    return cfg[task]?.sessionPersistence ?? cfg.defaults?.sessionPersistence;
+}
+/** 「宿主/库抛出来的任意值」→ 一句可读文本。core 不能 import 适配层的 errors.ts（中立性约束），
+ *  这里只保留 `not-run.detail` 需要的最小口径：文本、Error、普通对象 `.message`，再退到 JSON / 兜底。 */
+function errorMessage(error) {
+    if (typeof error === "string")
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    try {
+        const json = JSON.stringify(error);
+        return typeof json === "string" ? json : "unknown error";
+    }
+    catch {
+        return "unknown error";
+    }
+}
+/** 进入时快照要拍的目录条目：跳过 dotfile；win32 上再跳过保留设备名（CON 等）。 */
+async function snapshotFiles(memoryDir, platform = process.platform) {
+    const entries = await readdir(memoryDir, { withFileTypes: true }).catch(() => []);
+    return (entries
+        .filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+        // win32：保留设备名文件按名打开会命中设备（CON 等），`createSnapshot` 的 cp 会失败；
+        // dream 是 fail-closed 的，一次 cp 失败就打断整轮（与 `MemoryStore` 的 `#entryFiles` 同一契约）。
+        .filter((entry) => !(platform === "win32" && isReservedWindowsName(entry.name)))
+        .map((entry) => entry.name)
+        .sort());
+}
+/**
+ * 三个 LLM 任务的通用编排。顺序是契约：
+ *
+ * 1. 读模型（缺模型在这里抛可读错误，而不是发出 `model: ""` 的请求）；
+ * 2. 读 effort / sessionPersistence；
+ * 3. `buildPrompt`，`null` → `notCompleted({ status: "no-input" })`（在**任何锁之前**）；
+ * 4. 施加 `plan.lock`（`logical` 拿不到锁 → `notCompleted({ status: "lock-busy" })`）；
+ * 5. 端口调用（传输级异常按 `plan.errorPolicy` 收口）；
+ * 6. `completed` → `parse`；其余 → `notCompleted(outcome)`。
+ */
+export async function runTask(task, input, ctx) {
+    const cfg = ctx.cfg;
+    const deps = { store: ctx.store, transcript: ctx.ports.transcript };
+    const model = requiredModel(cfg, task.id);
+    const effort = cfg[task.id]?.thinkLevel;
+    const sessionPersistence = resolveSessionPersistence(cfg, task.id);
+    const prompt = task.buildPrompt(cfg, deps, input);
+    if (prompt === null)
+        return task.notCompleted(cfg, deps, input, { status: "no-input" });
+    const run = async () => {
+        const request = buildRequest(task, prompt, { cwd: ctx.cwd, model, effort, sessionPersistence, signal: ctx.signal }, task.memoryToolHooks?.(input)?.onWrite);
+        let outcome;
+        try {
+            outcome = await ctx.ports.headless.run(request);
+        }
+        catch (e) {
+            if (task.plan.errorPolicy === "swallow") {
+                return task.notCompleted(cfg, deps, input, {
+                    status: "not-run",
+                    cause: "host-refused",
+                    detail: errorMessage(e),
+                });
+            }
+            throw e;
+        }
+        if (outcome.status === "completed")
+            return await task.parse(cfg, deps, input, outcome.text);
+        return task.notCompleted(cfg, deps, input, outcome);
+    };
+    switch (task.plan.lock) {
+        case "none":
+            return run();
+        case "logical": {
+            const result = await ctx.store.tryWithLogicalLock(run);
+            if (result === null)
+                return task.notCompleted(cfg, deps, input, { status: "lock-busy" });
+            return result;
+        }
+        case "logical+snapshot": {
+            // 只有 dream 用这档锁。整轮持锁是刻意的：dream 的多次 `replace` / `remove` 必须对
+            // 同进程的 `memory add` 与 extract 呈现为**一个**原子区间，否则用户会在 dream 中途读到
+            // 半合并的状态。锁在进程内（不是 `.lock`），所以跨进程的其它 worktree 仍能正常写入 ——
+            // 它们的每次物理写入只被挡毫秒级。
+            //
+            // 其内部的每个原语调用必须带 `{ skipLogicalLock: true, skipSnapshot: true }`（由
+            // `memoryTool` 请求字段表达，适配层据此构造子会话的工具），否则它们会去抢自己已持有的
+            // 锁而自锁到超时，并且会为同一批变更各拍一次快照。
+            return ctx.store.withLogicalLock(async () => {
+                // 启动自检：忘了包 withLogicalLock 会静默失去整轮互斥。
+                if (!ctx.store.logicalLockActive()) {
+                    throw new Error(`${task.id} must run under the memory logical lock`);
+                }
+                // 进入时对整目录拍一次快照；这一轮里各原语的逐文件快照被 skipSnapshot 跳过。
+                const files = await snapshotFiles(ctx.cwd, ctx.store.cfg.platform);
+                await createSnapshot(join(ctx.cwd, BACKUP_DIR), task.id, files, ctx.cwd, {
+                    keep: ctx.store.cfg.lock.snapshotKeep,
+                    platform: ctx.store.cfg.platform,
+                });
+                return run();
+            });
+        }
+    }
+}
+//# sourceMappingURL=task.js.map

package/dist/orchestration/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/orchestration/task.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/tasks.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryTask } from "./task.js";
+/**
+ * 任务注册表：描述符的唯一声明处。
+ *
+ * 这一层单独成文件是为了让依赖方向单向：`tasks.ts → 描述符 → task.ts`。注册表原本住在 `task.ts`
+ * 里，而描述符要从 `task.ts` 拿 `runTask` / `MemoryTask`，于是构成模块环 —— 当时只靠「没人
+ * 在模块求值时读 `runTask`」才没炸（TDZ 侥幸）。把注册表挪出来后环消失，描述符里出现顶层
+ * 使用也不会在 import 时崩。
+ *
+ * `satisfies Record<ModelTask, MemoryTask<any, any>>` 让注册表**可证明完整**：漏一个描述符、
+ * 或键名写错，这里直接编译报错，而不是等调用方在运行时撞 `TASKS.dream === undefined`。
+ */
+export declare const TASKS: {
+    readonly autoSurfacing: MemoryTask<import("./surfacing.js").SurfacingInput, import("./surfacing.js").SurfacingResult>;
+    readonly extractMemories: MemoryTask<import("./extract.js").ExtractInput, import("./extract.js").ExtractResult>;
+    readonly dream: MemoryTask<Record<string, never>, string>;
+};
+//# sourceMappingURL=tasks.d.ts.map

package/dist/orchestration/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/orchestration/tasks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK;;;;CAIjB,CAAC"}

package/dist/orchestration/tasks.js

@@ -0,0 +1,16 @@
+import { dream } from "./dream.js";
+import { extractMemories } from "./extract.js";
+import { autoSurfacing } from "./surfacing.js";
+/**
+ * 任务注册表：描述符的唯一声明处。
+ *
+ * 这一层单独成文件是为了让依赖方向单向：`tasks.ts → 描述符 → task.ts`。注册表原本住在 `task.ts`
+ * 里，而描述符要从 `task.ts` 拿 `runTask` / `MemoryTask`，于是构成模块环 —— 当时只靠「没人
+ * 在模块求值时读 `runTask`」才没炸（TDZ 侥幸）。把注册表挪出来后环消失，描述符里出现顶层
+ * 使用也不会在 import 时崩。
+ *
+ * `satisfies Record<ModelTask, MemoryTask<any, any>>` 让注册表**可证明完整**：漏一个描述符、
+ * 或键名写错，这里直接编译报错，而不是等调用方在运行时撞 `TASKS.dream === undefined`。
+ */
+export const TASKS = { autoSurfacing, extractMemories, dream };
+//# sourceMappingURL=tasks.js.map

package/dist/orchestration/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/orchestration/tasks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,aAAa,EAAE,eAAe,EAAE,KAAK,EAI3D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yandy0725/memory-core",
-	"version": "1.0.1",
+	"version": "2.0.1",
 	"description": "Harness-agnostic file-system memory layer: one memory = one Markdown file, a MEMORY.md index, two-level locking, snapshots, and the LLM orchestration around them.",
 	"license": "MIT",
 	"repository": {
@@ -28,6 +28,8 @@
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
 		"prepublishOnly": "npm run build",
+		"prepack": "node ../scripts/sync-license.mjs",
+		"postpack": "node ../scripts/sync-license.mjs --remove",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"typecheck": "tsc --noEmit",

package/src/config.ts

@@ -1,8 +1,15 @@
-import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 
-export type ThinkLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * 宿主的思考/推理档位，**不透明字符串**：core 原样透传，不解释、不校验。
+ * pi 的合法值是 `off|minimal|low|medium|high|xhigh`；dsh 的合法值按 provider 路线是数据
+ * （DeepSeek 路线 `off|low|high|max`），所以 core 不能把它写成闭枚举。
+ * 合法性由适配层在启动期用宿主的 resolve 接口校验。
+ */
+export type EffortLevel = string;
+/** @deprecated pi 词汇，等价于 `EffortLevel`；保留是为了已发布适配层的类型重导出不破。 */
+export type ThinkLevel = EffortLevel;
 
 /** Session persistence configuration for headless memory-agent sub-sessions. */
 export interface SessionPersistenceConfig {
@@ -22,7 +29,7 @@ export interface DefaultsConfig {
 export interface AutoSurfacingConfig {
 	enabled: boolean;
 	model?: string;
-	thinkLevel: ThinkLevel;
+	thinkLevel: EffortLevel;
 	maxFiles: number;
 	/**
 	 * 单条 entry 注入正文的字节上限。
@@ -37,7 +44,7 @@ export interface ExtractMemoriesConfig {
 	/** 每轮自动提取。opt-in：默认 `false` —— 开启后每轮结束都会跑一次 headless 模型调用。 */
 	enabled: boolean;
 	model?: string;
-	thinkLevel: ThinkLevel;
+	thinkLevel: EffortLevel;
 	maxContextTokens: number;
 	/** 渲染进 extract prompt 时，单条 tool_result 的字符上限。 */
 	maxToolResultChars: number;
@@ -68,11 +75,14 @@ export interface MemoryConfig {
 	 * **没有** ttl / 心跳 / 接管字段：跨进程 `.lock` 永远只持毫秒且永不自动回收。
 	 */
 	lock: { timeoutMs: number; snapshotKeep: number };
+	/**
+	 * dream 任务本身：模型、思考档位、会话落盘。
+	 * 触发它的**策略**（隔多少个会话 / 多少小时后提醒）是宿主知识，**不**在这里 —— 需要它的适配层
+	 * 自己持有（pi 的 `PiHostConfig`），dsh 没有这套策略。
+	 */
 	dream: {
-		nudgeAfterSessions: number;
-		nudgeAfterHours: number;
 		model?: string;
-		thinkLevel: ThinkLevel;
+		thinkLevel: EffortLevel;
 		sessionPersistence?: SessionPersistenceConfig;
 	};
 	sessionSearch: { maxSessions: number; maxMatches: number };
@@ -96,7 +106,7 @@ export const DEFAULT_CONFIG: MemoryConfig = {
 	memIndexInjectMaxLines: 50,
 	memIndexInjectMaxBytes: 16384,
 	lock: { timeoutMs: 5000, snapshotKeep: 5 },
-	dream: { nudgeAfterSessions: 5, nudgeAfterHours: 24, thinkLevel: "high" },
+	dream: { thinkLevel: "high" },
 	sessionSearch: { maxSessions: 10, maxMatches: 5 },
 	autoSurfacing: {
 		enabled: true,
@@ -125,13 +135,32 @@ export function taskModel(cfg: MemoryConfig, task: ModelTask): string | undefine
 	return cfg[task]?.model ?? cfg.defaults?.model;
 }
 
-/** 会执行的任务及其模型值。dream 恒在执行集合内（没有包级开关可以让它不跑）。 */
-export function requiredModels(cfg: MemoryConfig): Array<{ task: ModelTask; value: string | undefined }> {
-	const out: Array<{ task: ModelTask; value: string | undefined }> = [
-		{ task: "dream", value: taskModel(cfg, "dream") },
-	];
-	if (cfg.extractMemories.enabled) out.push({ task: "extractMemories", value: taskModel(cfg, "extractMemories") });
-	if (cfg.autoSurfacing.enabled) out.push({ task: "autoSurfacing", value: taskModel(cfg, "autoSurfacing") });
+/**
+ * 会执行的任务及其模型值。
+ *
+ * `tasks`：适配层声明自己实现了哪些任务（如 dsh 本轮不实现 dream，就传 `["autoSurfacing"]`）。
+ * 省略 = 既有行为不变（dream 恒在执行集合内，另两个按 `enabled`）；给定则**只**考虑这些任务，
+ * dream 不再被强制加入，另两个仍按 `enabled` 过滤。顺序与调用方列举顺序无关，恒为
+ * dream → extractMemories → autoSurfacing。
+ *
+ * 缺省路径上**不是**逐字不变，唯一的例外（实现期已裁定）：`deepMerge` 会把用户写的
+ * `"extractMemories": null` / `"autoSurfacing": null` 原样带进来，旧实现直接读 `.enabled` 会抛
+ * `TypeError`，现在按 falsy 跳过该任务。这与 `taskModel` 对 `"dream": null` 的既有防御同一取向：
+ * 配置读不懂时应给出「该任务关闭 / 没有模型」这种可读结果，而不是把启动校验变成一句看不懂的
+ * 初始化失败。
+ */
+export function requiredModels(
+	cfg: MemoryConfig,
+	tasks?: readonly ModelTask[],
+): Array<{ task: ModelTask; value: string | undefined }> {
+	const order: readonly ModelTask[] = ["dream", "extractMemories", "autoSurfacing"];
+	const out: Array<{ task: ModelTask; value: string | undefined }> = [];
+	for (const task of order) {
+		if (tasks !== undefined && !tasks.includes(task)) continue;
+		// dream 没有包级开关：进了候选即在执行集合内（省略 `tasks` 时它恒是候选）。另两个看 `enabled`。
+		// 这里用 `?.`，与 `taskModel` 同理：`deepMerge` 会把用户写的 `"extractMemories": null` 原样带进来。
+		if (task === "dream" || cfg[task]?.enabled) out.push({ task, value: taskModel(cfg, task) });
+	}
 	return out;
 }
 
@@ -139,10 +168,15 @@ export function requiredModels(cfg: MemoryConfig): Array<{ task: ModelTask; valu
  * 启动校验：空数组 = 通过。
  * `resolve` 由调用方注入（生产时是 `(v) => resolveModel(v, ctx.modelRegistry) !== undefined`），
  * 因此本函数不依赖 SDK 的 registry 类型，可用假 resolve 单测。
+ * `tasks`：原样透传给 `requiredModels`（只校验列出的任务；`null` 子树跳过那个例外同上）。
  */
-export function modelConfigErrors(cfg: MemoryConfig, resolve: (value: string) => boolean): string[] {
+export function modelConfigErrors(
+	cfg: MemoryConfig,
+	resolve: (value: string) => boolean,
+	tasks?: readonly ModelTask[],
+): string[] {
 	const errors: string[] = [];
-	for (const { task, value } of requiredModels(cfg)) {
+	for (const { task, value } of requiredModels(cfg, tasks)) {
 		if (value === undefined) {
 			errors.push(`no model for ${task} — set "${task}.model" or "defaults.model" in memory.json`);
 		} else if (!resolve(value)) {
@@ -188,13 +222,13 @@ function deepMerge<T>(base: T, over: Partial<T>): T {
 	return out;
 }
 
-function readJsonSafe(path: string): Partial<MemoryConfig> {
-	try {
-		if (existsSync(path)) return JSON.parse(readFileSync(path, "utf-8")) as Partial<MemoryConfig>;
-	} catch {
-		// ignore malformed
-	}
-	return {};
+/**
+ * 把 `overlay` 深合并到 `base` 上：`undefined` 跳过、plain object 递归、数组整体替换、`null` 子树原样带入。
+ * 返回**新对象**，不改 `base` —— 这是合并语义的**唯一**一份实现：适配层读文件、读行 config、
+ * 读任何宿主侧的 overlay，都把它交给这里。core 不读任何配置文件。
+ */
+export function mergeConfig(base: MemoryConfig, overlay: unknown): MemoryConfig {
+	return deepMerge(base, (overlay ?? {}) as Partial<MemoryConfig>);
 }
 
 /**
@@ -211,25 +245,3 @@ export function defaultMemoryRoot(env: NodeJS.ProcessEnv = process.env, home: st
 	const base = xdg && isAbsolute(xdg) ? xdg : join(home, ".local", "share");
 	return join(base, "simple-memory");
 }
-
-export interface LoadConfigFromOptions {
-	/** 命名/展开规则跟随的平台。默认 `process.platform`。 */
-	platform?: NodeJS.Platform;
-	/** 覆盖共享数据根（测试注入缝）。默认 `defaultMemoryRoot()`。 */
-	memoryRoot?: string;
-}
-
-/**
- * 把 `files` 里存在且可解析的 JSON 按顺序 deep-merge 到默认值上，最后展开 `memoryDir` 的 `~`。
- *
- * core **不认识任何宿主的配置文件路径**：`files` 由适配层组装（全局配置在哪、项目配置在哪、
- * 项目不受信任时该不该读，全都是宿主的事）。不存在与 JSON 损坏的文件都跳过。
- */
-export async function loadConfigFrom(files: string[], opts: LoadConfigFromOptions = {}): Promise<MemoryConfig> {
-	let cfg: MemoryConfig = { ...DEFAULT_CONFIG, memoryDir: opts.memoryRoot ?? defaultMemoryRoot() };
-	for (const file of files) {
-		cfg = deepMerge(cfg, readJsonSafe(file));
-	}
-	cfg.memoryDir = expandTilde(cfg.memoryDir, opts.platform ?? process.platform);
-	return cfg;
-}

package/src/index.ts

@@ -52,12 +52,12 @@ export { sanitizeForInjection, stripInvisibleChars } from "./store/sanitize.js";
 export { escapeWindowsTrailing, isReservedWindowsName, windowsSafeName } from "./store/windows-names.js";
 
 // ── 配置（默认值、合并语义、模型校验、共享数据根）──────────────────────────────
-// 配置文件**在哪**是宿主知识，由适配层组装成 `loadConfigFrom` 的 `files` 入参。
+// core 只给默认值与合并语义；配置文件在哪、读不读，是适配层的事。
 export {
 	DEFAULT_CONFIG,
 	defaultMemoryRoot,
 	expandTilde,
-	loadConfigFrom,
+	mergeConfig,
 	modelConfigErrors,
 	requiredModel,
 	requiredModels,
@@ -66,8 +66,8 @@ export {
 export type {
 	AutoSurfacingConfig,
 	DefaultsConfig,
+	EffortLevel,
 	ExtractMemoriesConfig,
-	LoadConfigFromOptions,
 	MemoryConfig,
 	ModelTask,
 	SessionPersistenceConfig,
@@ -102,20 +102,30 @@ export type { EntryManifest } from "./injection.js";
 // ── orchestration/ LLM 编排 ───────────────────────────────────────────────────
 // 适配层实现 `HeadlessAgentPort` 与 `HostTranscriptPort` 两个端口，就能拿到与 pi 完全相同的
 // dream / extract / 侧查询行为（prompt 文本、锁与快照边界、截断预算、错误语义）。
-export { runDream } from "./orchestration/dream.js";
-export type { RunDreamOpts } from "./orchestration/dream.js";
-export { runExtract } from "./orchestration/extract.js";
-export type { ExtractPorts, RunExtractOpts } from "./orchestration/extract.js";
+export { runTask } from "./orchestration/task.js";
+export { TASKS } from "./orchestration/tasks.js";
+export { moduleStatusRows } from "./orchestration/status.js";
+export type { ModuleStatusRow } from "./orchestration/status.js";
+export type {
+	Incomplete,
+	MemoryTask,
+	MemoryToolOnWrite,
+	TaskContext,
+	TaskDeps,
+	TaskPlan,
+} from "./orchestration/task.js";
+export type { ExtractInput, ExtractResult } from "./orchestration/extract.js";
 export { renderConversation } from "./orchestration/conversation.js";
 export type { ConversationLimits } from "./orchestration/conversation.js";
-export { runSideQuery } from "./orchestration/surfacing.js";
-export type { RunSideQueryOpts } from "./orchestration/surfacing.js";
+export type { SurfacingInput, SurfacingResult } from "./orchestration/surfacing.js";
 export { buildDreamTask, buildExtractTask } from "./orchestration/prompts.js";
 export type {
 	ExtractMessage,
 	HeadlessAgentPort,
+	HeadlessOutcome,
 	HeadlessRunRequest,
 	HostTranscriptPort,
+	IncompleteOutcome,
 	OrchestrationPorts,
 } from "./orchestration/ports.js";
 export { memoryToolSchema } from "./tool/schema.js";