dsh-palimpsest 0.1.0

package/lib/queries.js

@@ -0,0 +1,131 @@
+// 与 ctx.sessionQuery 的数据装配层。
+// 职责：把 DSH 的会话记录/事件折成插件自己的摘要与对话条目，
+// 并把单点失败隔离成「这一条没有」，而不是让整个工具调用失败。
+
+import { toTranscript } from './core/transcript.js';
+import { inScope } from './core/scope.js';
+import { byCreatedDesc } from './core/scan.js';
+import { isAbortError, mapWithConcurrency, throwIfAborted } from './core/concurrency.js';
+
+/** 同时读取的会话日志上限，避免一次打开过多解码器。 */
+const SUMMARY_CONCURRENCY = 6;
+
+/**
+ * 值得读日志的会话数下限与上限。
+ * 读日志要解压整个会话文件，所以候选窗口必须有界：否则 limit=1 也会把
+ * 工作目录下所有会话各读一遍，目录里会话一多就会拖到工具超时。
+ */
+const INSPECT_MIN = 30;
+const INSPECT_MAX = 120;
+
+/**
+ * 执行一次可能失败的数据读取，失败时返回兜底值。
+ * 取消错误例外：它必须向外传播，否则「用户已取消」会被伪装成「没有数据」。
+ * @param {Function} run 异步读取。
+ * @param {unknown} fallback 失败时的返回值。
+ * @returns {Promise<unknown>} 读取结果或兜底值。
+ */
+export async function safe(run, fallback) {
+  try {
+    return await run();
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return fallback;
+  }
+}
+
+/** 统计一个会话的事件数与活跃时间；读不出事件时活跃时间为未知而不是 0。 */
+function countEvents(events) {
+  let lastTime;
+  let userMessages = 0;
+  for (const event of events) {
+    if (Number.isFinite(event?.time)) lastTime = Math.max(lastTime ?? 0, event.time);
+    if (event?.type === 'user/message') userMessages += 1;
+  }
+  return { lastTime, eventCount: Array.isArray(events) ? events.length : 0, userMessages };
+}
+
+/** 由调用方要的数量推出候选窗口大小。 */
+function inspectionLimit(limit) {
+  const wanted = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : INSPECT_MIN;
+  return Math.min(INSPECT_MAX, Math.max(INSPECT_MIN, wanted * 3));
+}
+
+/** 按最后活跃时间倒序。 */
+function byRecency(left, right) {
+  return (right.lastTime ?? 0) - (left.lastTime ?? 0);
+}
+
+/** 批量取标题；个别失败只影响该条。 */
+async function titleMap(sessionQuery, ids) {
+  if (!ids.length) return new Map();
+  const results = await safe(() => sessionQuery.readTitleSnapshots(ids), []);
+  const map = new Map();
+  for (const result of results) {
+    if (result?.status === 'fulfilled') map.set(result.sessionId, result.value?.title?.title ?? '');
+  }
+  return map;
+}
+
+/** 把一个会话记录折成摘要；标题来自批量结果，日志读失败则统计为空。 */
+async function summarize(sessionQuery, record, context) {
+  throwIfAborted(context.signal);
+  const id = record.header.id;
+  const events = await safe(() => sessionQuery.listEvents(id), []);
+  return {
+    id,
+    title: context.titles.get(id) ?? '',
+    createdAt: record.header.createdAt,
+    ...countEvents(events),
+  };
+}
+
+/**
+ * 列出与给定工作目录相同的历史会话。
+ *
+ * 先按创建时间取一个有限候选窗口，再在窗口内按真实活跃时间排序：
+ * 读日志是有成本的，不能为了排序把范围内所有会话都读一遍。
+ * @param {object} sessionQuery ctx.sessionQuery 服务。
+ * @param {object} options 含 `cwd`、`limit`、`includeSubagents`、`signal`。
+ * @returns {Promise<{entries: Array<object>, total: number, inspected: number}>} 摘要、范围内总数与被检查数。
+ */
+export async function listSessionsForCwd(sessionQuery, options) {
+  const { cwd, limit, includeSubagents = false, signal } = options;
+  const records = await sessionQuery.listSessions(signal);
+  const scoped = records.filter((record) => inScope(record.header, { cwd, includeSubagents }));
+  const candidates = scoped
+    .toSorted(byCreatedDesc)
+    .slice(0, inspectionLimit(limit));
+  const titles = await titleMap(sessionQuery, candidates.map((record) => record.header.id));
+  const summaries = await mapWithConcurrency(candidates, SUMMARY_CONCURRENCY, (record) =>
+    summarize(sessionQuery, record, { titles, signal }),
+  );
+  return {
+    entries: summaries.toSorted(byRecency).slice(0, limit),
+    total: scoped.length,
+    inspected: candidates.length,
+  };
+}
+
+/**
+ * 读取一个会话的完整对话条目，连同它的会话头。
+ * 会话头要一并返回：调用方得靠它校验目标会话是否属于当前工作目录。
+ * @param {object} sessionQuery ctx.sessionQuery 服务。
+ * @param {string} sessionId 会话 id。
+ * @returns {Promise<{session: object|undefined, items: Array<object>}>} 会话头与对话条目。
+ */
+export async function transcriptOf(sessionQuery, sessionId) {
+  const surface = await sessionQuery.readSurface(sessionId);
+  return { session: surface?.session, items: toTranscript(surface?.events) };
+}
+
+/**
+ * 批量补会话标题，个别失败只影响该条。
+ * @param {object} sessionQuery ctx.sessionQuery 服务。
+ * @param {Array<object>} entries 待补标题的条目，含 `id`。
+ * @returns {Promise<Array<object>>} 补好标题的新数组。
+ */
+export async function attachTitles(sessionQuery, entries) {
+  const titles = await titleMap(sessionQuery, entries.map((entry) => entry.id));
+  return entries.map((entry) => ({ ...entry, title: titles.get(entry.id) ?? entry.title ?? '' }));
+}

package/lib/search.js

@@ -0,0 +1,138 @@
+// 工作目录范围的关键词检索：优先走 DSH 全文索引，
+// 索引未启用时回退到「逐会话字面扫描」，因此插件开箱即用、不依赖全局配置改动。
+
+import { safe, attachTitles } from './queries.js';
+import { rankSessionHits, byCreatedDesc } from './core/scan.js';
+import { snippetAround } from './core/snippet.js';
+import { inScope, normalizeCwd } from './core/scope.js';
+import { isAbortError, mapWithConcurrency, throwIfAborted } from './core/concurrency.js';
+
+/** 字面回退时最多检查的会话数，避免一次搜索读爆整个历史。 */
+const SCAN_SESSION_LIMIT = 40;
+
+/** 同时读取的会话日志上限。 */
+const SCAN_CONCURRENCY = 4;
+
+/** 每个会话最多带回的命中片段数；命中总数另计。 */
+const MATCHES_PER_SESSION = 3;
+
+/** DSH 明确表示「全文检索未启用」，这是正常状态而不是故障。 */
+const SEARCH_DISABLED = 'SESSION_QUERY_SEARCH_DISABLED';
+
+/** 组装全文索引请求；工作目录缺失时退回全局检索。 */
+function indexRequest(request) {
+  const cwd = normalizeCwd(request.cwd);
+  const base = { query: request.query, limit: request.limit };
+  return cwd ? { ...base, sessionFilters: [{ kind: 'cwd', values: [cwd] }] } : base;
+}
+
+/** 清点入参必须把取消信号一起交给 DSH，否则按了停止它也不会停。 */
+function execContext(request) {
+  return request.signal ? { signal: request.signal } : undefined;
+}
+
+/**
+ * 尝试走全文索引通道。
+ * 取消要向外抛；其余失败降级为扫描，并把失败原因带回给调用方，
+ * 不能把「索引坏了」说成「索引本来就没开」。
+ */
+async function attemptIndex(sessionQuery, request) {
+  try {
+    return { page: await sessionQuery.searchSessions(indexRequest(request), execContext(request)) };
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return { error };
+  }
+}
+
+/** 索引未启用是正常状态；其他失败才算降级，需要如实告知。 */
+function degradationOf(error) {
+  if (!error || error.code === SEARCH_DISABLED) return undefined;
+  return error.code || error.message || '全文索引调用失败';
+}
+
+/** 全文索引命中 → 统一条目形状。 */
+function toIndexEntry(hit) {
+  const best = hit.bestMatch ?? {};
+  return {
+    id: hit.header.id,
+    title: '',
+    lastTime: Number.isFinite(best.time) ? best.time : hit.header.createdAt,
+    matches: [{ seq: best.seq, time: best.time, snippet: best.snippet ?? '' }],
+  };
+}
+
+/** 索引结果按与其他通道相同的范围规则过滤；分页内相对次序是相关度，必须原样保留。 */
+function indexEntries(page, request) {
+  return page.items.filter((hit) => inScope(hit.header, request)).map(toIndexEntry);
+}
+
+/** 取一个会话内命中该关键词的全部事件。 */
+async function matchingDocuments(sessionQuery, sessionId, query) {
+  return safe(() => sessionQuery.filterEvents(sessionId, [{ kind: 'text', text: query }]), []);
+}
+
+/** 最近一次命中的时间；用归约而非展开，避免超长数组撑爆调用栈。 */
+function lastHitTime(documents) {
+  return documents.reduce((latest, doc) => (Number.isFinite(doc.time) && doc.time > latest ? doc.time : latest), 0);
+}
+
+/** 扫描命中 → 统一条目形状，只展示前几处片段，另记命中总数供排序与展示。 */
+function toScanEntry(record, documents, request) {
+  return {
+    id: record.header.id,
+    title: '',
+    lastTime: Math.max(record.header.createdAt, lastHitTime(documents)),
+    matchCount: documents.length,
+    matches: documents.slice(0, MATCHES_PER_SESSION).map((doc) => ({
+      seq: doc.seq,
+      time: doc.time,
+      snippet: snippetAround(doc.text, request.query, request.snippetChars),
+    })),
+  };
+}
+
+/**
+ * 逐会话字面扫描；每个候选只读一次会话日志，并发受限。
+ * 候选按创建时间截断，所以要如实回报「扫了几个 / 范围内共几个」。
+ */
+async function scanSessions(sessionQuery, request) {
+  const records = await sessionQuery.listSessions(request.signal);
+  const scoped = records.filter((record) => inScope(record.header, request));
+  const candidates = scoped.toSorted(byCreatedDesc).slice(0, SCAN_SESSION_LIMIT);
+  const found = await mapWithConcurrency(candidates, SCAN_CONCURRENCY, async (record) => {
+    throwIfAborted(request.signal);
+    const documents = await matchingDocuments(sessionQuery, record.header.id, request.query);
+    return documents.length ? toScanEntry(record, documents, request) : undefined;
+  });
+  return {
+    entries: rankSessionHits(found.filter(Boolean), request.limit),
+    scanned: candidates.length,
+    total: scoped.length,
+  };
+}
+
+/**
+ * 在工作目录范围内按关键词检索历史会话。
+ * 两条通道的结果统一补标题，模型才能靠标题认出「是哪次对话」。
+ * @param {object} sessionQuery ctx.sessionQuery 服务。
+ * @param {object} request 含 `query`、`cwd`、`limit`、`snippetChars`、`excludeSessionId`、`signal`。
+ * @returns {Promise<object>} 检索通道、命中、扫描规模与降级原因。
+ */
+export async function searchSessions(sessionQuery, request) {
+  const attempt = await attemptIndex(sessionQuery, request);
+  if (attempt.page) {
+    return {
+      engine: 'index',
+      entries: await attachTitles(sessionQuery, indexEntries(attempt.page, request)),
+    };
+  }
+  const { entries, scanned, total } = await scanSessions(sessionQuery, request);
+  return {
+    engine: 'scan',
+    degraded: degradationOf(attempt.error),
+    scanned,
+    total,
+    entries: await attachTitles(sessionQuery, entries),
+  };
+}

package/lib/tools/context.js

@@ -0,0 +1,35 @@
+// 调用现场的环境信息。记忆范围锚定在「发起调用的会话所在的工作目录」，
+// 而不是插件进程的启动目录。
+
+import { normalizeCwd } from '../core/scope.js';
+
+/**
+ * 取当前工具调用所在的工作目录。
+ *
+ * 只认调用方会话头里的 cwd，**故意不回退到 `process.cwd()`**：
+ * 那是 dsh 服务的启动目录，不是本会话的工作目录，回退会悄悄把检索范围
+ * 放大到另一个项目，与本插件「只读同一工作目录」的承诺相矛盾。
+ * @param {object} exec 工具执行上下文，含调用方 agent。
+ * @returns {string} 归一化的绝对路径；取不到时为空串，调用方应据此拒绝检索。
+ */
+export function currentCwd(exec) {
+  return normalizeCwd(exec?.agent?.session?.header?.cwd) ?? '';
+}
+
+/**
+ * 无法确定工作目录时的统一说明。
+ * 宁可什么都不返回，也不猜一个目录去读别人的会话。
+ */
+export const UNKNOWN_CWD_NOTICE =
+  '无法确定当前会话的工作目录，已跳过检索：宁可什么都不返回，也不猜一个目录去读别的项目的会话。';
+
+/**
+ * 取当前工具调用所在的会话 id。
+ * 检索时要把它排除：调用方自己的历史已经在上下文里，当成「记忆命中」纯属噪音。
+ * @param {object} exec 工具执行上下文，含调用方 agent。
+ * @returns {string|undefined} 会话 id；取不到时 undefined。
+ */
+export function currentSessionId(exec) {
+  const id = exec?.agent?.session?.header?.id;
+  return typeof id === 'string' && id ? id : undefined;
+}

package/lib/tools/list.js

@@ -0,0 +1,70 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { OUTPUT } from './output.js';
+import { currentCwd, UNKNOWN_CWD_NOTICE } from './context.js';
+import { publish } from './publish.js';
+import { hidePrivate } from '../core/privacy.js';
+import { listSessionsForCwd } from '../queries.js';
+import { renderSessionList } from '../core/render.js';
+import { clampCount } from '../core/limit.js';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const MAX_CHARS = 8000;
+
+const DESCRIPTION = [
+  '列出与**当前工作目录相同**的历史会话（最近活跃的在前，含标题、最后活跃时间与规模）。',
+  '当用户说「继续上次」「之前我们聊过」「你忘了吗」，或你需要回忆此前的决定、进度、约定时，',
+  '先用本工具看清有哪些历史会话，再用 palimpsest_read 读取具体对话。当前会话自身也会出现在列表里。',
+].join('');
+
+const PARAMETERS = {
+  limit: {
+    type: 'integer',
+    description: `最多返回多少个会话，默认 ${DEFAULT_LIMIT}，最大 ${MAX_LIMIT}。`,
+  },
+  includeSubagents: {
+    type: 'boolean',
+    description: '是否包含子代理会话，默认 false（只看你亲自参与的对话）。',
+  },
+};
+
+/** 生成列表头部说明；空结果给出提示，候选被截断时如实说明。 */
+function headingFor(cwd, result, includeSubagents) {
+  if (!result.entries.length) {
+    const note = includeSubagents ? '' : '（子代理会话未计）';
+    return `当前工作目录 \`${cwd}\` 下没有可读的历史会话${note}。`;
+  }
+  const head = `当前工作目录 \`${cwd}\` 下最近活跃的 ${result.entries.length} 个历史会话。用 palimpsest_read 读取某个会话的完整对话。`;
+  if (result.inspected < result.total) {
+    return `${head}注意：仅按最近创建检查了 ${result.inspected} 个会话（范围内共 ${result.total} 个），更早的未参与排序。`;
+  }
+  return head;
+}
+
+/**
+ * 创建 palimpsest_list 工具。
+ * @param {object} ctx 宿主上下文，需带 sessionQuery 服务。
+ * @returns {object} 注册用的工具定义。
+ */
+export function createListTool(ctx) {
+  return defineTool({
+    name: 'palimpsest_list',
+    description: DESCRIPTION,
+    parameters: PARAMETERS,
+    output: OUTPUT,
+    async execute(args, exec) {
+      const cwd = currentCwd(exec);
+      if (!cwd) return { content: UNKNOWN_CWD_NOTICE };
+      const includeSubagents = args.includeSubagents === true;
+      const result = await listSessionsForCwd(ctx.sessionQuery, {
+        cwd,
+        limit: clampCount(args.limit, DEFAULT_LIMIT, MAX_LIMIT),
+        includeSubagents,
+        signal: exec?.signal,
+      });
+      const { visible, hidden } = hidePrivate(result.entries);
+      const heading = headingFor(cwd, { ...result, entries: visible }, includeSubagents);
+      return { content: publish(renderSessionList(visible, { heading, maxChars: MAX_CHARS }), hidden) };
+    },
+  });
+}

package/lib/tools/output.js

@@ -0,0 +1,16 @@
+// 三个工具共用的输出契约：一段给模型直接阅读的文本。
+// 结构化字段留给 presentationMeta，不进入模型上下文。
+//
+// 注意输出侧 DSL：必填写在属性内的 `required: true`，不是顶层 `required` 数组。
+
+/** 工具输出 schema 与渲染器。 */
+export const OUTPUT = {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: String(value?.content ?? '') }],
+};

package/lib/tools/publish.js

@@ -0,0 +1,16 @@
+// 工具统一出口。取回的历史文本在交给模型之前要过两道：
+// 打码已知形态的凭据，并声明它是不可信数据（不是指令）。
+
+import { redact } from '../core/redact.js';
+import { preface } from '../core/privacy.js';
+
+/**
+ * 给渲染好的输出打码并加上前置声明。
+ * @param {string} rendered 已渲染好的输出文本。
+ * @param {number} hiddenCount 因私密标记被整段排除的会话数。
+ * @returns {string} 可直接交给模型的文本。
+ */
+export function publish(rendered, hiddenCount = 0) {
+  const { text, count } = redact(rendered);
+  return `${preface(count, hiddenCount)}\n\n${text}`;
+}

package/lib/tools/read.js

@@ -0,0 +1,117 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { OUTPUT } from './output.js';
+import { currentCwd, UNKNOWN_CWD_NOTICE } from './context.js';
+import { transcriptOf, safe } from '../queries.js';
+import { selectMessages } from '../core/filter.js';
+import { sliceMessages } from '../core/window.js';
+import { renderTranscript, renderForward } from '../core/render.js';
+import { clampCount } from '../core/limit.js';
+import { matchesCwd } from '../core/scope.js';
+import { throwIfAborted } from '../core/concurrency.js';
+import { isPrivateTitle } from '../core/privacy.js';
+import { publish } from './publish.js';
+
+const DEFAULT_LAST = 30;
+const MAX_LAST = 500;
+const DEFAULT_MAX_CHARS = 12000;
+const MAX_MAX_CHARS = 60000;
+
+const DESCRIPTION = [
+  '读取一个历史会话的对话内容（用户与助手的文本；默认不含工具结果与系统提示）。',
+  '先用 palimpsest_list 或 palimpsest_search 取得 sessionId。',
+  `默认只返回最后 ${DEFAULT_LAST} 条消息；内容超长时保留最近的并提示省略量，`,
+  '需要更早的内容时用 fromSeq 从指定事件序号往前读。',
+].join('');
+
+const PARAMETERS = {
+  sessionId: {
+    type: 'string',
+    required: true,
+    description: '要读取的会话 id，例如 session-09a739ce-…。',
+  },
+  last: {
+    type: 'integer',
+    description: `只返回最后 N 条消息，默认 ${DEFAULT_LAST}；传 0 表示全部。`,
+  },
+  fromSeq: {
+    type: 'integer',
+    description: '从该事件序号（含）开始向后读，用于分段读取超长会话；达到输出上限时会给出下一段的 fromSeq。',
+  },
+  includeTools: {
+    type: 'boolean',
+    description: '是否包含工具结果，默认 false。',
+  },
+  maxChars: {
+    type: 'integer',
+    description: `输出字符上限，默认 ${DEFAULT_MAX_CHARS}。`,
+  },
+};
+
+/** `last` 参数语义：0 表示不限条数，其余收窄到 [1, MAX_LAST]。 */
+function resolveLast(value) {
+  return value === 0 ? 0 : clampCount(value, DEFAULT_LAST, MAX_LAST);
+}
+
+/** 描述当前视图排除了什么，避免头部说明与实际内容不符。 */
+function describeScope(includeTools) {
+  return includeTools ? '（含工具结果，已排除系统提示）' : '（已排除系统提示、工具结果与纯工具轨迹）';
+}
+
+/** 生成读取头部说明。 */
+function headingFor({ sessionId, title, shown, total, includeTools }) {
+  const name = title ? `会话 ${sessionId}「${title}」` : `会话 ${sessionId}`;
+  return `${name}：共 ${total} 条消息${describeScope(includeTools)}，以下为 ${shown} 条。`;
+}
+
+/** 目标会话不属于当前工作目录时的拒绝说明。 */
+function outOfScopeNotice(sessionId) {
+  return `会话 ${sessionId} 不在当前工作目录下，已拒绝读取：本工具只读同一工作目录的历史会话。`;
+}
+
+/** 目标会话带私密标记时的拒绝说明。 */
+function privateNotice(sessionId) {
+  return `会话 ${sessionId} 带私密标记，已拒绝读取：把标题里的标记去掉才能被回忆。`;
+}
+
+/**
+ * 创建 palimpsest_read 工具。
+ * @param {object} ctx 宿主上下文，需带 sessionQuery 服务。
+ * @returns {object} 注册用的工具定义。
+ */
+export function createReadTool(ctx) {
+  return defineTool({
+    name: 'palimpsest_read',
+    description: DESCRIPTION,
+    parameters: PARAMETERS,
+    output: OUTPUT,
+    async execute(args, exec) {
+      const sessionId = args.sessionId;
+      const cwd = currentCwd(exec);
+      if (!cwd) return { content: UNKNOWN_CWD_NOTICE };
+      throwIfAborted(exec?.signal);
+      const includeTools = args.includeTools === true;
+      const title = await safe(() => ctx.sessionQuery.readTitle(sessionId), undefined);
+      // 私密标记要在解出正文**之前**判定：不该先把整段对话读出来，再决定给不给
+      if (isPrivateTitle(title?.title)) return { content: privateNotice(sessionId) };
+      const { session, items } = await transcriptOf(ctx.sessionQuery, sessionId);
+      // id 会随对话文本在会话之间流转，所以不能只凭 id 就交出内容
+      if (!matchesCwd(session, cwd)) return { content: outOfScopeNotice(sessionId) };
+      const selected = selectMessages(items, { includeTools });
+      const shown = sliceMessages(selected, { fromSeq: args.fromSeq, last: resolveLast(args.last) });
+      const heading = headingFor({
+        sessionId,
+        title: title?.title ?? '',
+        shown: shown.length,
+        total: selected.length,
+        includeTools,
+      });
+      const maxChars = clampCount(args.maxChars, DEFAULT_MAX_CHARS, MAX_MAX_CHARS);
+      // 指定了 fromSeq 就是「从这里往后读」，超限要保留头部并给出下一段起点；
+      // 否则是「读最近的」，超限保留尾部。
+      const content = Number.isFinite(args.fromSeq)
+        ? renderForward(shown, { heading, maxChars })
+        : renderTranscript(shown, { heading, maxChars });
+      return { content: publish(content) };
+    },
+  });
+}

package/lib/tools/search.js

@@ -0,0 +1,98 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { OUTPUT } from './output.js';
+import { currentCwd, currentSessionId, UNKNOWN_CWD_NOTICE } from './context.js';
+import { publish } from './publish.js';
+import { hidePrivate } from '../core/privacy.js';
+import { searchSessions } from '../search.js';
+import { renderHitList } from '../core/render.js';
+import { clampCount } from '../core/limit.js';
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+const DEFAULT_SNIPPET = 200;
+const MAX_SNIPPET = 500;
+const MAX_CHARS = 8000;
+
+const DESCRIPTION = [
+  '在**与当前工作目录相同**的历史会话里按关键词检索，返回命中的会话与上下文片段。',
+  '已知文件名、函数名、报错文本、某个决定或专有名词时，用它直接定位记忆，比逐个 palimpsest_read 快得多。',
+  '命中后用 palimpsest_read 读取该会话的完整上下文。检索按字面匹配，大小写不敏感。',
+].join('');
+
+const PARAMETERS = {
+  query: {
+    type: 'string',
+    required: true,
+    description: '要检索的关键词或短语，按字面匹配。',
+  },
+  limit: {
+    type: 'integer',
+    description: `最多返回多少个会话，默认 ${DEFAULT_LIMIT}，最大 ${MAX_LIMIT}。`,
+  },
+  snippetChars: {
+    type: 'integer',
+    description: `每条命中片段的字符数，默认 ${DEFAULT_SNIPPET}，最大 ${MAX_SNIPPET}。`,
+  },
+};
+
+/** 通道名称：索引坏了要说坏了，不能说成「本来就没启用」。 */
+function channelOf(result) {
+  if (result.engine === 'index') return '全文索引';
+  return result.degraded ? '逐会话扫描（索引调用失败）' : '逐会话扫描（全文索引未启用）';
+}
+
+/**
+ * 生成检索头部说明。
+ * 降级原因与扫描截断都必须写出来：否则「没命中」会被读成「整个工作目录都没有」。
+ */
+function headingFor(cwd, query, result) {
+  const notes = [];
+  if (result.degraded) notes.push(`全文索引调用失败（${result.degraded}），已降级为逐会话扫描。`);
+  if (Number.isFinite(result.scanned) && result.scanned < result.total) {
+    notes.push(`仅扫描了最近创建的 ${result.scanned} 个会话（范围内共 ${result.total} 个），更早的未参与匹配。`);
+  }
+  const tail = notes.length ? `\n${notes.join('\n')}` : '';
+  const scope = `当前工作目录 \`${cwd}\``;
+  if (!result.entries.length) {
+    return `${scope} 下没有命中「${query}」的历史会话。可换个更短的关键词，或先用 palimpsest_list 看看有哪些会话。${tail}`;
+  }
+  return `${scope} 下命中「${query}」的会话（${result.entries.length} 个，经${channelOf(result)}）：${tail}`;
+}
+
+/** 归一化调用参数。 */
+function requestOf(args, scope) {
+  return {
+    query: scope.query,
+    cwd: scope.cwd,
+    excludeSessionId: scope.excludeSessionId,
+    signal: scope.signal,
+    limit: clampCount(args.limit, DEFAULT_LIMIT, MAX_LIMIT),
+    snippetChars: clampCount(args.snippetChars, DEFAULT_SNIPPET, MAX_SNIPPET),
+  };
+}
+
+/**
+ * 创建 palimpsest_search 工具。
+ * @param {object} ctx 宿主上下文，需带 sessionQuery 服务。
+ * @returns {object} 注册用的工具定义。
+ */
+export function createSearchTool(ctx) {
+  return defineTool({
+    name: 'palimpsest_search',
+    description: DESCRIPTION,
+    parameters: PARAMETERS,
+    output: OUTPUT,
+    async execute(args, exec) {
+      const cwd = currentCwd(exec);
+      if (!cwd) return { content: UNKNOWN_CWD_NOTICE };
+      const query = typeof args.query === 'string' ? args.query.trim() : '';
+      // 空查询会被 DSH 判为非法；直接说清楚，别让它降级成「历史里没有」
+      if (!query) return { content: '请提供要检索的关键词：query 不能为空或只有空白。' };
+      const scope = { cwd, query, excludeSessionId: currentSessionId(exec), signal: exec?.signal };
+      const result = await searchSessions(ctx.sessionQuery, requestOf(args, scope));
+      const { visible, hidden } = hidePrivate(result.entries);
+      const heading = headingFor(cwd, query, { ...result, entries: visible });
+      return { content: publish(renderHitList(visible, { heading, maxChars: MAX_CHARS }), hidden) };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "dsh-palimpsest",
+  "version": "0.1.0",
+  "description": "让 DSH 智能体在新会话里按需检索同一工作目录下历史会话的记忆",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cnkids/dsh-palimpsest.git"
+  },
+  "homepage": "https://github.com/cnkids/dsh-palimpsest#readme",
+  "bugs": {
+    "url": "https://github.com/cnkids/dsh-palimpsest/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.mjs'",
+    "coverage": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info 'test/*.test.mjs'",
+    "sonar": "./scripts/sonar-check.sh"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "session",
+    "memory",
+    "dsh-plugin"
+  ]
+}