@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/src/facets/schema.mjs

@@ -0,0 +1,75 @@
+/**
+ * Fixed facet schema (v1).
+ *
+ * The schema is deliberately small and closed. The extractor may only emit
+ * values listed here; an unknown concept belongs in `unknown`, not in a new
+ * facet value. Schema evolution is a separate, versioned operation.
+ */
+export const SCHEMA_VERSION = 1;
+
+export const SLOTS = Object.freeze([
+  'activity',
+  'interaction',
+  'random',
+  'participants',
+  'medium',
+  'topic',
+]);
+
+export const VALUES = Object.freeze({
+  activity: ['跑团', '开发', '调试', '测试', '文档', '对话', '其他'],
+  interaction: ['回合制', '指令式', '自由对话', '无'],
+  random: ['有', '无'],
+  participants: ['单人', '多人', '协作', '对抗', '无'],
+  medium: ['文字', '代码', '图像', '语音', '无'],
+  topic: ['剧情', '技术', '设备', '记忆', '规则', '其他'],
+});
+
+/** Query aliases are cached expansions, not identities. */
+export const DEFAULT_ALIASES = Object.freeze({
+  // Aliases are retrieval anchors, not full identity bundles. Keep them
+  // minimal: a maximal bundle makes every technical turn match 开发 and 调试.
+  跑团: { activity: '跑团' },
+  开发: { activity: '开发' },
+  调试: { activity: '调试' },
+  测试: { activity: '测试' },
+  记忆: { topic: '记忆' },
+  规则: { topic: '规则' },
+  图像: { topic: '设备', medium: '图像' },
+  技术: { topic: '技术' },
+  TRPG: { activity: '跑团' },
+  掷骰子: { activity: '跑团' },
+  角色扮演: { activity: '跑团' },
+  头像: { topic: '设备', medium: '图像' },
+  立绘: { topic: '设备', medium: '图像' },
+  记忆宫殿: { topic: '记忆' },
+});
+
+export function facetKey(slot, value) {
+  return `${slot}:${value}`;
+}
+
+export function isKnownFacet(slot, value) {
+  return SLOTS.includes(slot) && Array.isArray(VALUES[slot]) && VALUES[slot].includes(value);
+}
+
+export function normalizeFacets(input) {
+  const out = {};
+  if (Array.isArray(input)) {
+    for (const item of input) {
+      const [slot, ...rest] = String(item).split(':');
+      const value = rest.join(':').trim();
+      if (isKnownFacet(slot, value)) out[slot] = value;
+    }
+  } else if (input !== null && typeof input === 'object') {
+    for (const slot of SLOTS) {
+      const value = input[slot];
+      if (isKnownFacet(slot, value)) out[slot] = value;
+    }
+  }
+  return out;
+}
+
+export function aliasFacets(alias) {
+  return normalizeFacets(DEFAULT_ALIASES[String(alias ?? '').trim()] ?? {});
+}

package/src/facets/seed-examples.mjs

@@ -0,0 +1,58 @@
+/**
+ * Hand-written seed phrases for cold-start facet extraction.
+ * These are not labels from history; they are a prior over the fixed schema.
+ */
+import { SLOTS, VALUES } from './schema.mjs';
+
+export const SEED_EXAMPLES = Object.freeze({
+  activity: {
+    跑团: ['我们掷骰决定行动，角色在场景里探索。', '跑团开始，我先描述角色要做什么。'],
+    开发: ['写代码实现这个插件功能。', '修改模块并打包发布。'],
+    调试: ['看报错日志，定位进程和配置问题。', '这个 bug 复现了，先查调用栈。'],
+    测试: ['跑测试用例，检查回归。', '新增断言并验证结果。'],
+    文档: ['写安装说明和交接文档。', '整理报告，记录结论。'],
+    对话: ['我们聊聊这个东西的意义。', '你怎么看这件事？'],
+    其他: ['处理一个不属于上述类别的杂项。'],
+  },
+  interaction: {
+    回合制: ['一轮一轮来，等我描述完再继续。', '轮到你了，下一步怎么行动？'],
+    指令式: ['执行这个命令，把结果给我。', '按步骤完成操作。'],
+    自由对话: ['随便聊聊，不用按流程。', '我们自由讨论一下。'],
+    无: ['没有明确的交互形式。'],
+  },
+  participants: {
+    单人: ['我一个人在检查这个文件。', '我自己先想一下。'],
+    多人: ['几个人一起讨论方案。', '多人协作完成。'],
+    协作: ['我们一起把这件事做完。', '你和我配合处理。'],
+    对抗: ['双方对抗，各自争取胜利。', '对手和我对立。'],
+    无: ['没有参与者信息。'],
+  },
+  medium: {
+    文字: ['用中文写一段说明。', '这段是纯文本对话。'],
+    代码: ['这里是 TypeScript 代码和命令行。', '```js\nconst x = 1\n```'],
+    图像: ['![](.png) 看这张图。', '生成一张头像和对照图。'],
+    语音: ['听这段语音。', '用 TTS 读出来。'],
+    无: ['没有媒介。'],
+  },
+  topic: {
+    剧情: ['故事里的角色走进灯室。', '这一段是剧情推进。'],
+    技术: ['插件运行在 Node 上，改 engine 逻辑。', '接口和实现细节。'],
+    设备: ['手机、显卡和性能对比。', '这台设备的配置。'],
+    记忆: ['记忆宫殿、连续性和身份。', '我们之前聊过的那段记忆。'],
+    规则: ['规则要求每轮写 TAG。', '政策和闸的判定。'],
+    其他: ['其他话题。'],
+  },
+});
+
+export function seedRows() {
+  const rows = [];
+  for (const slot of SLOTS) {
+    if (slot === 'random') continue;
+    for (const value of VALUES[slot]) {
+      for (const text of SEED_EXAMPLES[slot]?.[value] ?? []) {
+        rows.push({ text, facets: { [slot]: value } });
+      }
+    }
+  }
+  return rows;
+}

package/src/facets/sensitivity.mjs

@@ -0,0 +1,98 @@
+/**
+ * Facet relevance scoring and temporal sensitivity.
+ *
+ * No LLM. A turn/topic score is an IDF-weighted cosine with a coverage penalty;
+ * the temporal series subtracts the corpus baseline so unrelated topics stay
+ * near zero.
+ */
+import { normalizeFacets } from './schema.mjs';
+
+function vectorize(facets) {
+  return Object.entries(normalizeFacets(facets ?? {}));
+}
+
+export function facetScore(facets, queryFacets, idf) {
+  const x = vectorize(facets);
+  const q = vectorize(queryFacets);
+  if (x.length === 0 || q.length === 0) return { score: 0, coverage: 0, hits: 0 };
+
+  const weight = (slot, value) => idf?.get?.(`${slot}:${value}`) ?? 1;
+  const xMap = new Map(x);
+  let dot = 0;
+  let hits = 0;
+  let qNorm = 0;
+  let xNorm = 0;
+  for (const [slot, value] of q) {
+    const w = weight(slot, value);
+    qNorm += w * w;
+    if (xMap.get(slot) === value) {
+      dot += w * w;
+      hits += 1;
+    }
+  }
+  for (const [slot, value] of x) {
+    const w = weight(slot, value);
+    xNorm += w * w;
+  }
+  if (qNorm === 0 || xNorm === 0) return { score: 0, coverage: 0, hits: 0 };
+  const cosine = dot / Math.sqrt(qNorm * xNorm);
+  const coverage = hits / q.length;
+  return { score: cosine * coverage * coverage, coverage, hits };
+}
+
+export function sensitivitySeries(entries, queryFacets, {
+  idf = null,
+  window = 2,
+  weights = [0.5, 0.3, 0.2],
+} = {}) {
+  const raw = entries.map((entry) => ({
+    turn: entry.turn,
+    seqStart: entry.seqStart,
+    seqEnd: entry.seqEnd,
+    time: entry.time ?? null,
+    ...facetScore(entry.facets, queryFacets, idf),
+  }));
+  const baseline = raw.length === 0 ? 0 : raw.reduce((sum, row) => sum + row.score, 0) / raw.length;
+  const positive = raw.map((row) => Math.max(0, row.score - baseline));
+  const smoothed = positive.map((value, index) => {
+    let sum = 0;
+    let weightSum = 0;
+    for (let k = 0; k <= Math.min(window, index); k += 1) {
+      const weight = weights[k] ?? 0;
+      sum += positive[index - k] * weight;
+      weightSum += weight;
+    }
+    return weightSum === 0 ? 0 : sum / weightSum;
+  });
+  return raw.map((row, index) => ({
+    ...row,
+    baseline,
+    positive: positive[index],
+    smoothed: smoothed[index],
+  }));
+}
+
+export function foldPriority(entries, queryFacets, {
+  idf = null,
+  recentTurns = 20,
+  protectScore = 0.5,
+} = {}) {
+  if (entries.length === 0) return [];
+  const latestTurn = Math.max(...entries.map((entry) => entry.turn));
+  return entries
+    .filter((entry) => entry.turn <= latestTurn - recentTurns)
+    .map((entry) => {
+      const score = facetScore(entry.facets, queryFacets, idf).score;
+      const age = latestTurn - entry.turn;
+      return {
+        turn: entry.turn,
+        seqStart: entry.seqStart,
+        seqEnd: entry.seqEnd,
+        score,
+        protected: score >= protectScore,
+        priority: (1 - Math.min(1, score)) * age,
+      };
+    })
+    .filter((entry) => !entry.protected)
+    .sort((a, b) => b.priority - a.priority);
+}

package/src/facets/service.mjs

@@ -0,0 +1,53 @@
+/**
+ * Main-thread client for the facet worker.
+ */
+import { Worker } from 'node:worker_threads';
+
+export function createFacetService({ modelPath, timeoutMs = 5000 } = {}) {
+  if (typeof modelPath !== 'string' || modelPath.length === 0) {
+    throw new Error('facet service: modelPath is required');
+  }
+  const worker = new Worker(new URL('./worker.mjs', import.meta.url), {
+    workerData: { modelPath },
+  });
+  let nextId = 1;
+  const pending = new Map();
+
+  worker.on('message', (message) => {
+    const entry = pending.get(message?.id);
+    if (entry === undefined) return;
+    pending.delete(message.id);
+    clearTimeout(entry.timer);
+    if (message.ok) entry.resolve(message.result);
+    else entry.reject(new Error(message.error));
+  });
+  worker.on('error', (error) => {
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  });
+
+  return {
+    extract(text) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error('facet service: timeout'));
+        }, timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        worker.postMessage({ id, text: String(text ?? '') });
+      });
+    },
+    async close() {
+      for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error('facet service: closed'));
+      }
+      pending.clear();
+      await worker.terminate();
+    },
+  };
+}

package/src/facets/store.mjs

@@ -0,0 +1,39 @@
+/**
+ * Persistence for facet MVP: index + cursor + residual.
+ * JSON files are read/written atomically from the CLI; the pure index remains
+ * the source of truth for querying.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+function atomicWrite(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, text, 'utf8');
+  fs.renameSync(temp, file);
+}
+
+export function saveIndex(file, index) {
+  atomicWrite(file, `${JSON.stringify({
+    total: index.total,
+    idf: [...index.idf.entries()],
+    entries: index.entries,
+  }, null, 2)}\n`);
+}
+
+export function loadIndex(file) {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return {
+    total: Number(raw.total) || 0,
+    idf: new Map(Array.isArray(raw.idf) ? raw.idf : []),
+    entries: Array.isArray(raw.entries) ? raw.entries : [],
+  };
+}
+
+export function saveCursor(file, cursor) {
+  atomicWrite(file, `${JSON.stringify(cursor, null, 2)}\n`);
+}
+
+export function loadCursor(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}

package/src/facets/worker.mjs

@@ -0,0 +1,23 @@
+/**
+ * Facet worker: loads a serialized local small model and answers extract
+ * requests off the host main thread.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import fs from 'node:fs';
+import { deserializeClassifier } from './classifier.mjs';
+import { hybridExtractor } from './hybrid.mjs';
+
+const raw = JSON.parse(fs.readFileSync(workerData.modelPath, 'utf8'));
+const model = deserializeClassifier(raw);
+const extract = hybridExtractor(model);
+
+parentPort.on('message', (message) => {
+  const id = message?.id;
+  try {
+    const text = String(message?.text ?? '');
+    const result = extract(text);
+    parentPort.postMessage({ id, ok: true, result });
+  } catch (error) {
+    parentPort.postMessage({ id, ok: false, error: String(error?.message ?? error) });
+  }
+});

package/src/folds-store.mjs

@@ -0,0 +1,109 @@
+/**
+ * Folded range sidecar (~/.dsh/continuity/folds.json).
+ *
+ * The engine records every compaction it performs: the original shadowed range
+ * and the gist summary seq. find/load use this local record to distinguish
+ * visible seqs from folded ones without querying the session log.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+
+let writeQueue = Promise.resolve();
+
+export function continuityHome() {
+  const override = process.env.DSH_CONTINUITY_HOME;
+  return override !== undefined && override.length > 0
+    ? override
+    : join(homedir(), '.dsh', 'continuity');
+}
+
+export function foldsFile() {
+  return join(continuityHome(), 'folds.json');
+}
+
+function normalizeFold(value) {
+  const from = Number(value?.from);
+  const to = Number(value?.to);
+  const gistSeq = Number(value?.gistSeq);
+  if (!Number.isInteger(from) || !Number.isInteger(to) || from > to) return null;
+  const count = Number(value?.count);
+  return {
+    from,
+    to,
+    gistSeq: Number.isInteger(gistSeq) ? gistSeq : null,
+    ...(Number.isInteger(count) && count >= 0 ? { count } : {}),
+    ...(typeof value?.compactionId === 'string' && value.compactionId ? { compactionId: value.compactionId } : {}),
+    at: typeof value?.at === 'string' ? value.at : new Date().toISOString(),
+  };
+}
+
+/** @returns {Promise<{folds: object[], missing: boolean, corrupt: boolean}>} */
+export async function readFolds(sessionId) {
+  const id = String(sessionId);
+  try {
+    const raw = await readFile(foldsFile(), 'utf8');
+    const parsed = JSON.parse(raw);
+    const session = parsed?.sessions?.[id];
+    const folds = Array.isArray(session?.folds)
+      ? session.folds.map(normalizeFold).filter(Boolean)
+      : [];
+    return { folds, missing: false, corrupt: false };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { folds: [], missing: true, corrupt: false };
+    return { folds: [], missing: false, corrupt: true };
+  }
+}
+
+/** Append one fold record for a session; serialized and atomic. */
+export async function recordFold(sessionId, { from, to, gistSeq, count, compactionId } = {}) {
+  const id = String(sessionId);
+  const fold = normalizeFold({ from, to, gistSeq, count, compactionId });
+  if (fold === null) return null;
+  const operation = writeQueue.then(async () => {
+    let state = { version: 1, sessions: {} };
+    try {
+      const raw = await readFile(foldsFile(), 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        state = {
+          version: 1,
+          sessions: parsed.sessions !== null && typeof parsed.sessions === 'object' && !Array.isArray(parsed.sessions)
+            ? parsed.sessions
+            : {},
+        };
+      }
+    } catch { /* missing/corrupt: start clean */ }
+    const session = state.sessions[id] !== null && typeof state.sessions[id] === 'object'
+      && !Array.isArray(state.sessions[id])
+      ? state.sessions[id]
+      : { folds: [] };
+    const folds = Array.isArray(session.folds) ? session.folds : [];
+    folds.push(fold);
+    state.sessions[id] = { folds, updatedAt: new Date().toISOString() };
+    const dir = continuityHome();
+    await mkdir(dir, { recursive: true });
+    const file = foldsFile();
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+      await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+      await rename(temp, file);
+    } catch (error) {
+      try { await unlink(temp); } catch { /* best effort */ }
+      throw new Error(`continuity: cannot write ${file}: ${error?.message ?? error}`);
+    }
+    return fold;
+  });
+  writeQueue = operation.catch(() => {});
+  return operation;
+}
+
+/** Latest fold containing seq, or null. */
+export function foldForSeq(folds, seq) {
+  const number = Number(seq);
+  for (let index = (folds?.length ?? 0) - 1; index >= 0; index -= 1) {
+    const fold = folds[index];
+    if (number >= fold.from && number <= fold.to) return fold;
+  }
+  return null;
+}

package/src/groups.mjs

@@ -0,0 +1,167 @@
+/**
+ * 归拢探测（纯函数）：从标签关键词与 multi-hit 日志里提出“该有父”的候选。
+ * 只提议，不建组；名字优先取查询原话，其次取共享词。
+ */
+const SCAFFOLD = new Set(["T", "标签", "记录", "线头", "thread", "tag"]);
+
+export function normalizeTags(tags) {
+  return Object.entries(tags?.tags ?? {}).map(([id, t]) => ({
+    id,
+    alias: t?.alias ?? id,
+    label: t?.label ?? "",
+    keywords: Array.isArray(t?.keywords) ? t.keywords.filter((k) => k && !SCAFFOLD.has(k)) : [],
+  }));
+}
+
+function jaccard(a, b) {
+  const A = new Set(a), B = new Set(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const x of A) if (B.has(x)) inter++;
+  return inter / (A.size + B.size - inter);
+}
+
+/** 返回提议数组；每条 {kind, members, score, name}。 */
+export function detectGroups(tags, routeLines = [], options = {}) {
+  const minJaccard = Number(options.minJaccard ?? 0.5);
+  const minPairHits = Number(options.minPairHits ?? 2);
+  const rawEntries = normalizeTags(tags);
+  const entries = options.groups ? collapseGroups(rawEntries, options.groups) : rawEntries;
+  const proposals = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i], b = entries[j];
+      const score = jaccard(a.keywords, b.keywords);
+      if (score < minJaccard) continue;
+      const shared = a.keywords.filter((k) => b.keywords.includes(k));
+      proposals.push({ kind: "keyword-overlap", members: [a.alias, b.alias], score: Number(score.toFixed(2)), name: shared[0] ?? "" });
+    }
+  }
+
+  const multi = routeLines
+    .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+    .filter((x) => x && typeof x.conclusion === "string" && x.conclusion.startsWith("multi:"))
+    .map((x) => ({ head: x.head ?? "", tags: x.conclusion.slice(6).split(",").filter(Boolean) }));
+  const pair = new Map();
+  for (const m of multi) {
+    for (let i = 0; i < m.tags.length; i++) {
+      for (let j = i + 1; j < m.tags.length; j++) {
+        const key = [m.tags[i], m.tags[j]].sort().join("|");
+        const cur = pair.get(key) ?? { count: 0, head: m.head };
+        cur.count++;
+        pair.set(key, cur);
+      }
+    }
+  }
+  for (const [key, v] of pair) {
+    if (v.count < minPairHits) continue;
+    // 父名优先取成员关键词的交集；没有就留空（由实例或人提炼），原句只作凭据。
+    const ids = key.split("|");
+    const kws = ids.map((id) => entries.find((e) => e.alias === id || e.id === id)?.keywords ?? []);
+    const shared = kws.length >= 2 ? kws[0].filter((k) => kws[1].includes(k)) : [];
+    proposals.push({ kind: "query-ambiguity", members: ids, score: v.count, name: shared[0] ?? "", evidence: String(v.head).slice(0, 60) });
+  }
+  return proposals;
+}
+
+
+/**
+ * 按 groups 把成员标签折叠成一个节点（组名），避免同一主题的多个阶段被当成独立标签。
+ * groups 形如 { "标签治理": { members: ["T16","T21"] } }。
+ */
+export function collapseGroups(entries, groups) {
+  const byMember = new Map();
+  for (const [name, g] of Object.entries(groups ?? {})) {
+    for (const m of g?.members ?? []) byMember.set(m, name);
+  }
+  const collapsed = new Map();
+  for (const e of entries) {
+    const key = byMember.get(e.alias) ?? byMember.get(e.id) ?? e.alias ?? e.id;
+    const cur = collapsed.get(key) ?? { id: key, alias: key, label: groups?.[key]?.label ?? e.label, keywords: [] };
+    cur.keywords.push(...e.keywords);
+    collapsed.set(key, cur);
+  }
+  return [...collapsed.values()];
+}
+
+
+/**
+ * 把组名递归展开成标签 id 集合。members 里可以嵌套组名。
+ * 环引用直接抛错（A⊃B⊃A 是数据错误，不该静默）。
+ */
+export function expandGroup(groups, name, seen = new Set()) {
+  if (!groups || typeof groups !== "object") return new Set();
+  if (!groups[name]) throw new Error("未知组: " + name);
+  if (seen.has(name)) throw new Error("组循环引用: " + [...seen, name].join(" -> "));
+  const next = new Set(seen);
+  next.add(name);
+  const out = new Set();
+  for (const member of groups[name].members ?? []) {
+    if (groups[member]) {
+      for (const id of expandGroup(groups, member, next)) out.add(id);
+    } else {
+      out.add(member);
+    }
+  }
+  return out;
+}
+
+
+/**
+ * 从多命中证据里提炼父名：取这些句子里反复出现、但不在两个标签关键词里的 2–4 字词。
+ * 找不到就返回空串（交给提问）。
+ */
+export function nameFromEvidence(heads, keywordsA = [], keywordsB = []) {
+  const banned = new Set([...(keywordsA ?? []), ...(keywordsB ?? [])]);
+  const texts = (heads ?? []).map((h) => String(h ?? ""));
+  const df = new Map();
+  for (const text of texts) {
+    const seen = new Set();
+    for (let n = 2; n <= 4; n++) {
+      for (let i = 0; i + n <= text.length; i++) {
+        const g = text.slice(i, i + n);
+        if (!/^[\u4e00-\u9fa5]+$/.test(g)) continue;
+        if (banned.has(g)) continue;
+        seen.add(g);
+      }
+    }
+    for (const g of seen) df.set(g, (df.get(g) ?? 0) + 1);
+  }
+  // 词边界：真词两侧要么“干净”（句首/标点），要么邻字多样；碎片两侧恒定（如“机性”）。
+  const isBoundary = (ch) => ch === "" || /[\s，。！？、；：""''（）()\[\]【】—…·]/.test(ch);
+  const sideOk = (term, side) => {
+    const map = new Map();
+    let allBoundary = true;
+    for (const text of texts) {
+      let i = -1;
+      while ((i = text.indexOf(term, i + 1)) >= 0) {
+        const ch = side === "prev" ? (i > 0 ? text[i - 1] : "") : (i + term.length < text.length ? text[i + term.length] : "");
+        if (!isBoundary(ch)) { allBoundary = false; map.set(ch, (map.get(ch) ?? 0) + 1); }
+      }
+    }
+    if (allBoundary) return true;
+    const total = [...map.values()].reduce((a, b) => a + b, 0);
+    if (total === 0) return true;
+    let h = 0;
+    for (const c of map.values()) { const p2 = c / total; h -= p2 * Math.log2(p2); }
+    return h >= 0.9;
+  };
+  const boundaryOk = (term) => sideOk(term, "prev") && sideOk(term, "next");
+  // 与标签关键词共享 ≥2 字的片段也算“已有关键词的一部分”，不能当父名（如“机性价”）。
+  const grams2 = (s) => { const out = new Set(); for (let i = 0; i + 2 <= s.length; i++) out.add(s.slice(i, i + 2)); return out; };
+  const bannedSub = (g) => {
+    const gg = grams2(g);
+    return [...banned].some((k) => {
+      if (typeof k !== "string" || k.length < 2) return false;
+      if (g.includes(k) || k.includes(g)) return true;
+      for (const x of grams2(k)) if (gg.has(x)) return true;
+      return false;
+    });
+  };
+  const ranked = [...df.entries()]
+    // 长词（≥3）比 2 字词可靠；2 字词必须两侧都多样，否则多半是碎片。
+    .filter(([g, c]) => c >= 2 && !bannedSub(g) && (g.length >= 3 || boundaryOk(g)))
+    .sort((a, b) => (b[0].length - a[0].length) || (b[1] - a[1]));
+  return ranked.length > 0 ? ranked[0][0] : "";
+}

package/src/handoff-tool.mjs

@@ -0,0 +1,51 @@
+import { join } from 'node:path';
+import { assetMarker } from './assets.mjs';
+import { handoffText, writeHandoff } from './handoff.mjs';
+
+const PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    childSessionId: { type: 'string', description: 'Child/PTC session id.' },
+    runId: { type: 'string', description: 'PTC workflow run id.' },
+    summary: { type: 'string', description: 'Bounded task result for the parent; do not truncate decisions.' },
+    status: { type: 'string', description: 'Optional status, default ok.' },
+    decisions: { type: 'array', items: { type: 'string' }, description: 'Why the child chose this result.' },
+    open: { type: 'array', items: { type: 'string' }, description: 'Unfinished work.' },
+    artifacts: { type: 'array', items: { type: 'string' }, description: 'Relative artifact paths.' },
+    sourceSeqs: { type: 'array', items: { type: 'integer' }, description: 'Child event seqs worth retrieving.' },
+    confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+  },
+  required: ['childSessionId', 'runId', 'summary'],
+};
+
+function defaultHome() {
+  return join(process.env.USERPROFILE ?? process.env.HOME ?? '', '.dsh', 'continuity');
+}
+
+export function createHandoffTool({ home = defaultHome() } = {}) {
+  return {
+    name: 'ptc_handoff',
+    description: 'Register a PTC child result as a parent-visible child artifact. '
+      + 'Stores the full envelope under assets/ptc and returns a marker; use child_asset to retrieve it.',
+    parameters: PARAMETERS,
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: String(value ?? '') }],
+    },
+    timeoutMs: 20_000,
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const input = args !== null && typeof args === 'object' ? args : {};
+      const parentSessionId = exec?.agent?.session?.id ?? exec?.agent?.id;
+      if (parentSessionId === undefined || parentSessionId === null) {
+        throw new Error('ptc_handoff: no current parent session id');
+      }
+      const result = await writeHandoff({ home, parentSessionId: String(parentSessionId), envelope: input });
+      return [
+        handoffText(result.envelope),
+        assetMarker(result.written.row, 'child'),
+      ].join('\n');
+    },
+  };
+}