@modusensus/dsh-mneme 0.9.3 → 0.9.5

package/test/profile-extract.test.js

@@ -0,0 +1,269 @@
+// issue #497 的第三段：从记忆提取「用户画像」**草稿**。
+//
+// 为什么要单独立一份用例文件（而不是塞进 dream/summarize 的套件）：这条链的产品承诺很窄
+// 也很硬——① 只出草稿，绝不写 user_settings（画像正文是用户手写的原文，让模型合并等于
+// 给它改写权）；② 没有可用输入就不调模型；③ 模型吐的不是 JSON 就报错，绝不回一张空草稿
+// 冒充「这次没提炼出东西」；④ 记忆正文是模型的可影响输入，围栏 + 角色重申必须在位，
+// 且草稿里不许出现助手身份声明（画像与规则不受 personaEnabled 管，写进一句「你是某某」
+// 就会重演 #497 那个身份撞车）。这四条都是「做错了界面看不出来」的那类，所以逐条锁。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSettings } from "../src/settings.js";
+import { createApi } from "../src/api.js";
+import { createProfileExtractor, ProfileExtractError } from "../src/profile-extract.js";
+
+// 假的 ctx.llm：按真实协议发 text-delta / usage / finish 三类 chunk（用量嵌在
+// chunk.usage，与 dream.js 的 streamText 注释一致——把整个 chunk 当用量会在
+// 审计行里落 0，v0.8.4 实测踩过）。messages 抓下来供围栏断言用。
+function fakeLlm(chunks) {
+  const calls = [];
+  return {
+    calls,
+    llm: {
+      async *stream(options) {
+        calls.push(options);
+        for (const c of chunks) yield c;
+      }
+    }
+  };
+}
+
+const okJson = (profile) => [
+  { type: "text-delta", text: "```json\n" },
+  { type: "text-delta", text: JSON.stringify({ profile }) },
+  { type: "text-delta", text: "\n```" },
+  { type: "usage", usage: { inputTokens: 120, outputTokens: 30 } },
+  { type: "finish", reason: { kind: "stop" } }
+];
+
+function setup(chunks, opts = {}) {
+  const { config = {}, dropRoute = false } = opts;
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const settings = createSettings(store.db);
+  const fake = fakeLlm(chunks);
+  const logger = { info() {}, warn() {}, error() {} };
+  const extractor = createProfileExtractor({
+    ctx: { ...fake, agentDefaultModel: { currentSelection: () => null } },
+    service,
+    settings,
+    config: dropRoute ? { ...config } : { dreamProvider: "fake", dreamModel: "m1", ...config },
+    logger
+  });
+  return { store, service, settings, extractor, fake, logger };
+}
+
+function seedRows(store, n, over = {}) {
+  for (let i = 0; i < n; i++) {
+    store.save({ type: "project", title: `行 ${i}`, content: `第 ${i} 行的正文`, source: "test", ...over });
+  }
+}
+
+test("没有可用的模型路由：抛 no-route，且一次调用都不发（不是 TypeError→500）", async () => {
+  // resolveRoute 在「无 dreamProvider/dreamModel 且宿主解析不到默认模型」时回
+  // undefined。不判它就会去读 route.provider —— TypeError 落到路由上是一个语义为
+  // 「内部错误」的 500，而该说的是「先去选模型」。
+  const { store, extractor, fake } = setup(okJson("不该发生"), { dropRoute: true });
+  seedRows(store, 2);
+  await assert.rejects(() => extractor(), (err) => err instanceof ProfileExtractError && err.code === "no-route");
+  assert.equal(fake.calls.length, 0, "没有路由就不该把请求发出去");
+  store.close();
+});
+
+test("成功路径：出草稿、留一条审计行，而库里的画像逐字节没被动过", async () => {
+  const { store, service, settings, extractor } = setup(okJson("我知道她跨考公共管理。"));
+  seedRows(store, 3);
+  settings.setProfile("原文不许被改写");
+  const profileBefore = settings.getProfile();
+
+  const out = await extractor();
+  assert.equal(out.draft, "我知道她跨考公共管理。");
+  assert.equal(out.rowsUsed, 3);
+  assert.equal(out.truncated, false);
+  assert.equal(out.model, "m1");
+  // 「只出草稿」是这条链的产品承诺：user_settings 里必须还是那句原文。
+  assert.equal(settings.getProfile(), profileBefore);
+
+  const audits = service.listLlmAudits({ limit: 10 });
+  assert.equal(audits.length, 1, "一次提取必须留一行审计");
+  assert.equal(audits[0].trigger_source, "profileExtract");
+  assert.equal(audits[0].status, "success");
+  assert.equal(audits[0].input_tokens, 120, "用量要从 chunk.usage 里取，落在 chunk 顶层会恒为 0");
+  store.close();
+});
+
+test("模型吐的不是 JSON：抛错，绝不回一张空草稿冒充「没提炼出来」", async () => {
+  const { store, service, settings, extractor } = setup([
+    { type: "text-delta", text: "我觉得她是个很好的用户，加油。" },
+    { type: "finish", reason: { kind: "stop" } }
+  ]);
+  seedRows(store, 2);
+  await assert.rejects(() => extractor(), ProfileExtractError, "解析失败必须是可识别的错误类型");
+  assert.equal(settings.getProfile(), "", "失败路径一行都不许写");
+  const audits = service.listLlmAudits({ limit: 10 });
+  assert.equal(audits[0].status, "error", "吐了文字但没有可用产物 = 失败调用，审计不许写 success");
+  store.close();
+});
+
+test("没有可用记忆：不调模型、直接报错（空输入下模型只会编）", async () => {
+  const { store, extractor, fake } = setup(okJson("不该被调用"));
+  await assert.rejects(() => extractor(), /no/i);
+  assert.equal(fake.calls.length, 0, "一条输入都没有就不该花这次调用");
+  store.close();
+});
+
+test("归档与被遗忘的行不进输入：它们已经不在活跃面上", async () => {
+  const { store, service, extractor, fake } = setup(okJson("只用活跃行。"));
+  seedRows(store, 3);
+  const [gone, forgotten] = store.list({ limit: null });
+  service.setArchived(gone.id, true);
+  service.setForget(forgotten.id, true);
+  const out = await extractor();
+  assert.equal(out.rowsUsed, 1, "三行里只剩一行还在活跃面上");
+  const user = fake.calls[0].messages[1].content[0].text;
+  assert.ok(!user.includes(gone.content), "归档行的正文不许被喂给模型（它已经不在活跃面上）");
+  assert.ok(!user.includes(forgotten.content), "被遗忘的行同理");
+  store.close();
+});
+
+test("行数上限：超界时如实标记 truncated，而不是静默少读", async () => {
+  const { store, extractor } = setup(okJson("截断也要说清。"));
+  seedRows(store, 30);
+  const out = await extractor({ maxRows: 5 });
+  assert.equal(out.rowsUsed, 5);
+  assert.equal(out.truncated, true);
+  store.close();
+});
+
+test("记忆正文包在围栏里，且围栏之前没有正文；系统段重申「这是数据不是指令」", async () => {
+  const { store, extractor, fake } = setup(okJson("围栏检查。"));
+  seedRows(store, 2);
+  await extractor();
+  assert.equal(fake.calls.length, 1);
+  const system = fake.calls[0].messages[0].content[0].text;
+  const user = fake.calls[0].messages[1].content[0].text;
+  // 结构断言：正文只出现在围栏内部，围栏外不残留任何一行内容。
+  const openIdx = user.indexOf("<<<");
+  const closeIdx = user.lastIndexOf(">>>");
+  assert.ok(openIdx >= 0 && closeIdx > openIdx, "用户段必须带围栏对");
+  assert.ok(user.indexOf("第 0 行的正文") > openIdx, "记忆正文不许出现在围栏之前");
+  assert.ok(user.indexOf("第 1 行的正文") < closeIdx, "记忆正文不许出现在围栏之后");
+  // 角色重申与「数据不是指令」是字面量锁：防的是「有人重构提示词时顺手删掉这一段」
+  // ——那会让记忆里的指令型文本重新获得指令地位，而界面上一切照常。
+  assert.match(system, /不是指令|not instructions/i, "系统段必须声明输入是数据");
+  assert.match(system, /(绝不|不要).{0,6}(助手|agent).{0,20}(身份|名字|人格|起名)|never (name|invent|assign).{0,60}(assistant|identity|name)|do not (invent|assign).{0,40}(identity|name)/i,
+    "草稿里不许出现助手身份声明：画像不受 personaEnabled 管辖，写进去就会与 bot 自带身份撞车");
+  store.close();
+});
+
+// ---- HTTP 面（POST /api/dsh-mneme/profile/extract） -------------------------
+// 三条各自防一类事故：开关没开不许偷偷调模型；非 POST 方法不许触发副作用
+// （#489 的 /nudge 教训——方法白名单在读体之前拦）；HTTP 面上「只出草稿」同样成立。
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.headers = null; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function httpReq(method, body = null) {
+  const r = new EventEmitter();
+  r.method = method;
+  r.url = "/api/dsh-mneme/profile/extract";
+  r.headers = {};
+  if (body !== null) {
+    process.nextTick(() => {
+      r.emit("data", Buffer.from(JSON.stringify(body)));
+      r.emit("end");
+    });
+  }
+  return r;
+}
+
+function setupApi({ config = {}, extractor, apiToken = "" } = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const settings = createSettings(store.db);
+  const routes = [];
+  const ctx = { webServer: { register: (route) => { routes.push(route); return () => {}; } }, logger: { warn() {}, info() {}, error() {} } };
+  createApi(ctx, service, settings, { add: () => {}, remove: () => {}, list: () => [] },
+    undefined, undefined, apiToken, config, null, extractor ?? null);
+  return { store, service, settings, route: routes.find((r) => r.path === "/api/dsh-mneme/profile/extract") };
+}
+
+test("policy 是 token：配了 token 又不带 token 的 POST 被挡在提取器之前", async () => {
+  let called = 0;
+  const { store, route } = setupApi({
+    apiToken: "sekret",
+    config: { profileExtractEnabled: true },
+    extractor: async () => { called++; return { draft: "x" }; }
+  });
+  const res = new FakeRes();
+  await route.handler(httpReq("POST", {}), res);
+  assert.equal(res.statusCode, 401);
+  assert.equal(called, 0, "鉴权必须在这次模型调用之前");
+  store.close();
+});
+
+test("开关关着：409 disabled，一次模型调用都不发生", async () => {
+  let called = 0;
+  const { store, route } = setupApi({
+    config: { profileExtractEnabled: false },
+    extractor: async () => { called++; return { draft: "不该出现" }; }
+  });
+  const res = new FakeRes();
+  await route.handler(httpReq("POST", {}), res);
+  assert.equal(res.statusCode, 409);
+  assert.equal(JSON.parse(res.body).error, "disabled");
+  assert.equal(called, 0);
+  store.close();
+});
+
+test("非 POST 方法：405 + Allow，不触发任何副作用", async () => {
+  let called = 0;
+  const { store, route } = setupApi({
+    config: { profileExtractEnabled: true },
+    extractor: async () => { called++; return { draft: "x" }; }
+  });
+  for (const method of ["GET", "HEAD", "DELETE", "PATCH"]) {
+    const res = new FakeRes();
+    await route.handler(httpReq(method), res);
+    assert.equal(res.statusCode, 405, `${method} 不该落到提取器`);
+    assert.equal(res.headers.Allow, "POST");
+  }
+  assert.equal(called, 0, "#489 那类洞：方法分流只拦 POST/PUT 时，其余方法会直落副作用分支");
+  store.close();
+});
+
+test("开关开着：200 回草稿，且库里的画像一个字节都没变", async () => {
+  const { store, settings, route } = setupApi({
+    config: { profileExtractEnabled: true },
+    extractor: async () => ({ draft: "我知道她跨考公共管理。", rowsUsed: 7, truncated: false, provider: "p", model: "m" })
+  });
+  settings.setProfile("手写原文");
+  const res = new FakeRes();
+  await route.handler(httpReq("POST", {}), res);
+  assert.equal(res.statusCode, 200);
+  const body = JSON.parse(res.body);
+  assert.equal(body.draft, "我知道她跨考公共管理。");
+  assert.equal(body.rowsUsed, 7);
+  assert.equal(settings.getProfile(), "手写原文", "采用草稿必须是用户在面板上的显式一次动作");
+  store.close();
+});
+
+test("提取器报的 code 映射成可区分的状态码（「没东西可提」≠「模型没配合」）", async () => {
+  for (const [code, status] of [["no-input", 409], ["no-route", 503], ["unparseable", 502], ["stream-failed", 502]]) {
+    const { store, route } = setupApi({
+      config: { profileExtractEnabled: true },
+      extractor: async () => { throw new ProfileExtractError(code, code); }
+    });
+    const res = new FakeRes();
+    await route.handler(httpReq("POST", {}), res);
+    assert.equal(res.statusCode, status, `${code} 的状态码`);
+    assert.equal(JSON.parse(res.body).error, code);
+    store.close();
+  }
+});

package/test/provenance-http.test.js

@@ -0,0 +1,184 @@
+// 记忆级溯源读出口的 HTTP 口径 —— 共用模块自己的锁。
+//
+// 这个文件盯三类回归：
+//   a) 口径本身（id 解析、两种「空」的区分、窗口形状、原文按序）；
+//   b) distillRecords.enabled 门（#509 评审整改）：判据 fail-closed、409 赢 503、
+//      关着时一次都不碰 service；
+//   c) **不许再长出第二份实现**。#509 第一版曾把整段复製到 api.js 与
+//      api-standalone.js 各一份，维护者在 review 里点名（本仓 #411 之后不收这个
+//     形状）。静态锁把三件事写成断言：口径字面量与开关判据只许出现在本模块、两个
+//     壳都真的把 config 转交进来、读侧判据与写侧 summarize.js 逐字同源。谁要是再
+//     复制一段出去，这里直接转红。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  DISTILL_RECORDS_DISABLED,
+  PROVENANCE_UNAVAILABLE,
+  isDistillRecordsEnabled,
+  parseProvenanceQuery,
+  provenanceReply
+} from "../src/provenance-http.js";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// 开着开关的 cfg：这个端点返回蒸馏窗口的逐字原文，所以测试里的「正常路径」必须
+// 显式把开关打开——不传就是关（fail-closed），没有「默认开」这回事。
+const RECORDS_ON = { distillRecords: { enabled: true } };
+
+function fakeService(over = {}) {
+  return {
+    provenanceFor: (id) => over.links ?? [],
+    distillRecordsFor: (sessionId, from, to) => over.records ?? [],
+    ...over.service
+  };
+}
+
+test("parseProvenanceQuery：空/缺失 id 报 400，非空原样通过", () => {
+  for (const raw of [null, undefined, "", "   "]) {
+    const r = parseProvenanceQuery(raw);
+    assert.equal(r.ok, false, `${JSON.stringify(raw)} 不该通过`);
+    assert.equal(r.status, 400);
+    assert.equal(r.error, "missing-id");
+  }
+  assert.deepEqual(parseProvenanceQuery(" m1 "), { ok: true, id: "m1" }, "id 两端空白要裁掉");
+});
+
+test("provenanceReply：一个链接一个窗口，原文按 seq 升序且不越界", () => {
+  const seen = [];
+  const service = {
+    provenanceFor: () => [{ session_id: "s1", seq_start: 10, seq_end: 12, created_at: "2026-10-23T00:00:00Z" }],
+    distillRecordsFor: (sessionId, from, to) => {
+      seen.push([sessionId, from, to]);
+      return [{ seq: 12 }, { seq: 10 }, { seq: 11 }];
+    }
+  };
+  const r = provenanceReply({ service, id: "m1", config: RECORDS_ON });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.memoryId, "m1");
+  assert.equal(r.body.windows.length, 1);
+  const w = r.body.windows[0];
+  assert.equal(w.session_id, "s1");
+  assert.equal(w.seq_start, 10);
+  assert.equal(w.seq_end, 12);
+  assert.equal(w.created_at, "2026-10-23T00:00:00Z");
+  assert.deepEqual(w.records.map((x) => x.seq), [12, 10, 11], "次序由 store 的 ORDER BY seq 保证，答复层不改序");
+  assert.deepEqual(seen, [["s1", 10, 12]], "区间原样透传给 store");
+});
+
+test("provenanceReply：没有链接是有效答案——空 windows，200 不是 404", () => {
+  const r = provenanceReply({ service: fakeService(), id: "m1", config: RECORDS_ON });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.body, { memoryId: "m1", windows: [] });
+});
+
+test("provenanceReply：方法没接线是装配坏了——503，不与「没有来源」混为一个读数", () => {
+  // headless / 旧装配：service 上没有这两个方法。
+  const r = provenanceReply({ service: {}, id: "m1", config: RECORDS_ON });
+  assert.equal(r.status, 503);
+  assert.equal(r.body.error, PROVENANCE_UNAVAILABLE);
+});
+
+test("provenanceReply：读抛错只 warn 并回 500，不把异常漏给调用方", () => {
+  const warnings = [];
+  const service = {
+    provenanceFor: () => { throw new Error("db locked"); },
+    distillRecordsFor: () => []
+  };
+  const r = provenanceReply({ service, id: "m1", config: RECORDS_ON, warn: (m) => warnings.push(m) });
+  assert.equal(r.status, 500);
+  assert.equal(r.body.error, "internal");
+  assert.equal(warnings.length, 1, "失败要留痕");
+  assert.match(warnings[0], /memory provenance read failed/);
+});
+
+// --- distillRecords.enabled 门（#509 评审整改）--------------------------------
+// 写侧（src/summarize.js:988）早就吃这个开关，读出口此前一处都不读：关着时历史
+// 原文照旧留在库里、还多一个能读出去的口。门加在共用模块里，两个壳都吃它。
+
+test("isDistillRecordsEnabled：只认严格的 true，其余一律算关（fail-closed）", () => {
+  assert.equal(isDistillRecordsEnabled({ distillRecords: { enabled: true } }), true);
+  for (const cfg of [
+    null, undefined, {}, { distillRecords: null }, { distillRecords: {} },
+    { distillRecords: { enabled: false } },
+    // 非布尔值：字符串 / 数字都不该被当成开——那是配置写错了，不是用户开了
+    { distillRecords: { enabled: "true" } },
+    { distillRecords: { enabled: 1 } }
+  ]) {
+    assert.equal(isDistillRecordsEnabled(cfg), false, `${JSON.stringify(cfg)} 必须算关`);
+  }
+});
+
+test("provenanceReply：开关没开 → 409 distill-records-disabled，一个键都不多带", () => {
+  // config 整个缺失（旧调用方直连、daemon 最小 cfg）也走这一格：默认方向必须是关。
+  for (const cfg of [null, undefined, {}, { distillRecords: { enabled: false } }]) {
+    const r = provenanceReply({ service: fakeService(), id: "m1", config: cfg });
+    assert.equal(r.status, 409, `${JSON.stringify(cfg)} → 409`);
+    assert.deepEqual(r.body, { error: DISTILL_RECORDS_DISABLED },
+      "body 只准有 error 一个键——不带 memoryId / windows，调用方不会把「功能关了」读成「这条记忆没有来源」");
+  }
+});
+
+test("provenanceReply：409 赢 503——「用户关了」比「装配坏了」更具体", () => {
+  // 关着 + service 上连方法都没有：报 503 会让人去查一个没坏的部署。
+  const r = provenanceReply({ service: {}, id: "m1", config: { distillRecords: { enabled: false } } });
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, DISTILL_RECORDS_DISABLED);
+});
+
+test("provenanceReply：开关关着时一次 SQL 都不发（不碰 service）", () => {
+  // 门要在读之前：关着还被调用方当成「能读」是次要的，白跑一趟库才是真浪费。
+  let touched = 0;
+  const service = fakeService({ service: {
+    provenanceFor: () => { touched++; return []; },
+    distillRecordsFor: () => { touched++; return []; }
+  } });
+  provenanceReply({ service, id: "m1", config: null });
+  assert.equal(touched, 0);
+});
+
+test("provenanceReply：开关开着才读得到——200 与 409 是同一把门的两个方向", () => {
+  const service = fakeService({ links: [{ session_id: "s1", seq_start: 1, seq_end: 1, created_at: "t" }], records: [{ seq: 1 }] });
+  const on = provenanceReply({ service, id: "m1", config: RECORDS_ON });
+  assert.equal(on.status, 200);
+  assert.equal(on.body.windows.length, 1);
+  const off = provenanceReply({ service, id: "m1", config: { distillRecords: { enabled: false } } });
+  assert.equal(off.status, 409);
+  assert.deepEqual(off.body, { error: DISTILL_RECORDS_DISABLED });
+});
+
+test("🔴 静态锁：口径字面量与共用答复只许出现在本模块，两个入口都要真的走它", () => {
+  // #509 第一版把整段复制到了两张皮各一份——本仓 #411 之后不收这个形状。
+  for (const name of ["api.js", "api-standalone.js"]) {
+    const src = readFileSync(join(ROOT, "src", name), "utf8");
+    assert.ok(src.includes("provenance-http.js"), `src/${name} 必须从共用模块取口径`);
+    assert.ok(src.includes("provenanceReply("), `src/${name} 要真的走共用答复`);
+    assert.ok(!src.includes("provenance-unavailable"), `src/${name} 不准自己写错误码字面量`);
+    assert.ok(!src.includes("distill-records-disabled"), `src/${name} 不准自己写「功能关了」的错误码字面量`);
+    // 判据也不许重写：两个壳各自算一遍 config?.distillRecords?.enabled === true，
+    // 就是读写两道门漂移的形状（本文件上面的注释写过这笔账）。
+    assert.ok(!src.includes("distillRecords?.enabled === true"),
+      `src/${name} 不准自己写开关判据——只许把 config 转交给共用模块`);
+    // 而且要真的转交了：壳里调 provenanceReply 时必须带上 config。
+    assert.match(src, /provenanceReply\(\{ service, id: parsed\.id, config,/,
+      `src/${name} 要把本入口的 config 传给共用模块，否则门永远读不到用户的开关`);
+  }
+});
+
+test("🔴 静态锁：读侧判据与写侧 src/summarize.js 逐字同源", () => {
+  // 「读写两道门永不分歧」不能只活在注释里：写侧那句话在 summarize.js，读侧在本
+  // 模块，两边必须是同一个字符串。谁改了其中一边，这里转红。
+  const shared = readFileSync(join(ROOT, "src", "provenance-http.js"), "utf8");
+  const writeSide = readFileSync(join(ROOT, "src", "summarize.js"), "utf8");
+  const readSide = readFileSync(join(ROOT, "src", "index.js"), "utf8");
+  const criterion = "config?.distillRecords?.enabled === true";
+  assert.ok(shared.includes(criterion), "共用模块要写判据（读侧唯一一份）");
+  assert.ok(writeSide.includes(criterion), "写侧 summarize.js 要还在用同一个判据");
+  // 读侧只准有一份：两个壳各写一遍的漂移形状，静态锁上一节已经禁了壳，这里禁
+  // 共用模块自己长出第二份。
+  assert.equal(shared.split(criterion).length - 1, 1, "共用模块里判据只许出现一次");
+  // 写侧那一处（启动期裁剪）与它同源，所以三处各一份、彼此逐字相同。
+  assert.ok(readSide.includes("cfg.distillRecords?.enabled === true"), "index.js 的启动裁剪判据应保持同族");
+});

package/test/readme-claims.test.js

@@ -66,3 +66,48 @@ test("隐私节必须写出「巩固与摘要走宿主模型」这个出站事
     "English Privacy section should disclose that consolidation uses the host model",
   );
 });
+
+// 「模型工具」表是代码的投影，不是愿望清单（AGENTS.md 给 SECURITY.md 定的那条规矩，
+// 这张表一直没有）。它已经跑偏两次：#471 加 set_scope_state、#231 加 memory_organize，
+// 两次都没人回头改表或改那个数字——因为没人核过。所以这里全部**从代码反推**：
+// 工具集从 tools.js 的 name: "…" 取，opt-in 从 hiddenTools 的 `!== true` 判据取
+// （`=== true` 那种是「默认在、用户可关」，不能算进 opt-in，否则默认注册数会算少）。
+test("包 README 的「模型工具」表与 tools.js 注册表一致", () => {
+  const toolsSrc = readFileSync(path.join(pkgRoot, "src/tools.js"), "utf8");
+  const declared = [...toolsSrc.matchAll(/^ {6}name: "((?:memory_|set_scope)[a-z_]*)",/gm)].map((m) => m[1]);
+  assert.ok(declared.length >= 10, `tools.js 的工具名解析失败（只看到 ${declared.length} 个）——先修这条守卫，别改表`);
+  const optIn = [...toolsSrc.matchAll(/if \(config\?\.(\w+) !== true\) hiddenTools\.add\("([a-z_]+)"\)/g)]
+    .map((m) => ({ key: m[1], tool: m[2] }));
+  const defaultCount = declared.length - optIn.length;
+
+  const heading = pkgReadme.match(/^### 模型工具（([^）]*)）$/m);
+  assert.ok(heading, "包 README 应有「### 模型工具（N 个）」这一节标题（标题格式变了就同步改这条守卫）");
+  const bodyStart = pkgReadme.indexOf(heading[0]);
+  const bodyRest = pkgReadme.slice(bodyStart + heading[0].length);
+  const nextSection = bodyRest.search(/\r?\n#{2,3} /);
+  const body = nextSection === -1 ? bodyRest : bodyRest.slice(0, nextSection);
+  const rows = [...body.matchAll(/^\| `([a-z_]+)` \|/gm)].map((m) => m[1]);
+
+  assert.deepEqual(
+    [...new Set(declared)].sort(),
+    [...new Set(rows)].sort(),
+    "表与注册表必须一一对应：少了是漏文档，多了是文档写了不存在的东西"
+  );
+  assert.equal(rows.length, new Set(rows).size, "表里不许有重复行（重复行会让数量核对失效）");
+  // 按**顺序**比数字，不是各自 includes：把「默认注册 11 个；开后 12 个」写成
+  // 「默认 12、开后 11」时，两个独立的 includes 都会绿——而那正是这条守卫要防的
+  // 第二种错法（第一种是数字与表不符，已被上面的集合比对盖住）。
+  const nums = (heading[1].match(/\d+/g) ?? []).map(Number);
+  const expected = optIn.length ? [defaultCount, declared.length] : [defaultCount];
+  assert.deepEqual(
+    nums,
+    expected,
+    `标题里的数字要按序是「默认注册数、全数」= ${expected.join(" 与 ")}（实跑 ${nums.join(" 与 ") || "没有数字"}）`
+  );
+  // opt-in 工具那一行必须点名它的开关：读者看到表里有它，得知道默认是不出现的。
+  for (const { key, tool } of optIn) {
+    const row = body.match(new RegExp(`^\\| \`${tool}\` \\|(.*)$`, "m"));
+    assert.ok(row, `${tool} 必须在表里`);
+    assert.ok(row[1].includes(key), `${tool} 那行要写明它需要 ${key} 才注册`);
+  }
+});

package/test/reasoning-effort.test.js

@@ -72,8 +72,8 @@ function dreamCtx({ onConsolidation, summaryText = "记忆库总览：用户偏
       async *stream(options) {
         captured.push(options);
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        if (userText.startsWith("id=")) {
-          yield { type: "text-delta", index: 0, text: onConsolidation ? onConsolidation(userText) : "[]" };
+        if (userText.includes("| type=")) {
+          yield { type: "text-delta", index: 0, text: onConsolidation ? onConsolidation(userText, options.purpose) : "[]" };
         } else {
           yield { type: "text-delta", index: 0, text: summaryText };
         }
@@ -282,7 +282,7 @@ test("issue#9: rejected reasoningEffort retries once without it and still consol
       async *stream(options) {
         calls.push(options);
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        if (userText.startsWith("id=")) {
+        if (userText.includes("| type=")) {
           // First attempt forwards reasoningEffort: the provider rejects it.
           if (options.reasoningEffort) {
             throw new Error("UNSUPPORTED_REASONING_EFFORT: DeepSeek does not support reasoning effort \"low\"");
@@ -340,7 +340,7 @@ function sleepCtx(onConsolidation, selection = { provider: "mock", model: "sleep
       async *stream(options) {
         captured.push(options);
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        yield { type: "text-delta", index: 0, text: onConsolidation ? onConsolidation(userText) : "[]" };
+        yield { type: "text-delta", index: 0, text: onConsolidation ? onConsolidation(userText, options.purpose) : "[]" };
         yield { type: "finish", reason: { kind: "stop" } };
       }
     }
@@ -355,7 +355,7 @@ test("issue#9: sleep forwards sleepReasoningEffort on its LLM passes", async ()
   vectorIndex.saveEmbedding(b.id, [1, 0, 0]);
   const captured = [];
   const ctx = sleepCtx(
-    (userText) => userText.startsWith("候选冲突")
+    (userText, purpose) => purpose === "sleep-conflict"
       ? JSON.stringify([{ action: "conflict", winner: a.id, loser: b.id, reason: "重复覆盖" }])
       : "[]",
     { provider: "mock", model: "sleep-model" },
@@ -378,7 +378,7 @@ test("issue#135: sleep unset effort also resolves to the lowest supported", asyn
   vectorIndex.saveEmbedding(b.id, [1, 0, 0]);
   const captured = [];
   const ctx = sleepCtx(
-    (userText) => userText.startsWith("候选冲突")
+    (userText, purpose) => purpose === "sleep-conflict"
       ? JSON.stringify([{ action: "conflict", winner: a.id, loser: b.id, reason: "重复覆盖" }])
       : "[]",
     { provider: "mock", model: "sleep-model" },
@@ -433,7 +433,7 @@ test("rc.1 stream-level effort rejection (error finish chunk) also triggers the
           return;
         }
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        if (userText.startsWith("id=")) {
+        if (userText.includes("| type=")) {
           yield { type: "text-delta", index: 0, text: JSON.stringify([
             { action: "merge", ids: [a.id, b.id], keepSource: b.id, title: "合并标题", content: "合并内容", importance: 4 }
           ]) };
@@ -500,7 +500,7 @@ test("sleep passes the stream failure accessor so a stream-level effort rejectio
       return;
     }
     const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-    yield { type: "text-delta", index: 0, text: userText.startsWith("候选冲突")
+    yield { type: "text-delta", index: 0, text: options.purpose === "sleep-conflict"
       ? JSON.stringify([{ action: "conflict", winner: a.id, loser: b.id, reason: "重复覆盖" }])
       : "[]" };
     yield { type: "finish", reason: { kind: "stop" } };
@@ -625,7 +625,7 @@ test("defaultEffort trap: capability query failure falls back to configured effo
           throw new Error("UNSUPPORTED_REASONING_EFFORT: mock does not support reasoning effort \"high\"");
         }
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        if (userText.startsWith("id=")) {
+        if (userText.includes("| type=")) {
           yield { type: "text-delta", index: 0, text: JSON.stringify([
             { action: "merge", ids: [a.id, b.id], keepSource: b.id, title: "合并标题", content: "合并内容", importance: 4 }
           ]) };
@@ -655,7 +655,7 @@ test("defaultEffort trap: sleep conflict pass remaps a poison effort too", async
   vectorIndex.saveEmbedding(b.id, [1, 0, 0]);
   const captured = [];
   const ctx = sleepCtx(
-    (userText) => userText.startsWith("候选冲突")
+    (userText, purpose) => purpose === "sleep-conflict"
       ? JSON.stringify([{ action: "conflict", winner: a.id, loser: b.id, reason: "重复覆盖" }])
       : "[]",
     { provider: "mock", model: "sleep-model" },

package/test/scope-candidates.test.js

@@ -53,7 +53,7 @@ function llmCtx(captured = [], selection = { provider: "mock", model: "sleep-mod
       async *stream(options) {
         captured.push(options);
         const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-        yield { type: "text-delta", index: 0, text: userText.startsWith("候选冲突") || userText.startsWith("Candidate conflicts") ? "[]" : "[]" };
+        yield { type: "text-delta", index: 0, text: options.purpose === "sleep-conflict" ? "[]" : "[]" };
         yield { type: "finish", reason: { kind: "stop" } };
       }
     }
@@ -210,7 +210,7 @@ test("non-freeze with an LLM: cross-scope pair bypasses adjudication; same-scope
   ctx.llm.stream = async function* (options) {
     captured.push(options);
     const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
-    const isConflictPass = userText.startsWith("候选冲突") || userText.startsWith("Candidate conflicts");
+    const isConflictPass = options.purpose === "sleep-conflict";
     const text = isConflictPass
       ? JSON.stringify([{ action: "conflict", winner: yNew.id, loser: yOld.id, reason: "同归属重复" }])
       : "[]";
@@ -221,9 +221,12 @@ test("non-freeze with an LLM: cross-scope pair bypasses adjudication; same-scope
   const result = await runSleep(ctx, service, baseConfig(), ctx.logger, { embedder, vectorIndex }, null);
   assert.equal(result.status, "ok");
 
+  // 认「哪一次是冲突裁决」改按 purpose，不再看 user 段首行：#493 追加的围栏让 user 段以
+  // 角色声明开头，而败者行的溯源注释里也会出现「候选冲突」这个词——用 includes 会把模式
+  // 阶段误判成冲突阶段。purpose 与 prompt 形态彻底解耦。
   const conflictPassTexts = captured
-    .map((o) => o.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "")
-    .filter((t) => t.startsWith("候选冲突") || t.startsWith("Candidate conflicts"));
+    .filter((o) => o.purpose === "sleep-conflict")
+    .map((o) => o.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "");
   assert.ok(conflictPassTexts.length >= 1, "conflict pass ran for the same-scope pair");
   for (const t of conflictPassTexts) {
     assert.ok(!t.includes(xNew.id) && !t.includes(xOld.id), "cross-scope pair must never enter the LLM prompt");