dsh-plugin-lrc 0.2.0

package/src/cursor.ts

@@ -0,0 +1,195 @@
+/**
+ * 增量游标：只提炼上次之后的新增对话。
+ *
+ * ## 为什么需要
+ *
+ * 每次卸载都把整段 transcript 重新提炼一遍，同一句话会被反复写入 ——
+ * 这是"上下文抢救"造成记忆膨胀的根因。
+ *
+ * ## 哈希校验
+ *
+ * transcript 可能被宿主截断或重写（比如会话恢复）。若只记行号，
+ * 行号会指向错误的内容。所以同时记录"最后一行内容的哈希"：
+ * 对不上就判定游标失效，退回全量提炼并记 warn。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface CursorState {
+  sessionId: string;
+  /** 已处理到第几行（0 表示还没处理过） */
+  lastLine: number;
+  /** 第 lastLine 行内容的哈希，用于校验 transcript 是否被重写 */
+  lastHash: string;
+  updatedAt: number;
+}
+
+export interface SliceResult {
+  /** 需要送去提炼的新增文本 */
+  text: string;
+  /** 本次从第几行开始（0-based） */
+  fromLine: number;
+  /** 游标是否失效（transcript 被重写），调用方应记 warn */
+  reset: boolean;
+}
+
+/** 行内容哈希（取前 16 位十六进制，够用且省空间）。 */
+export function hashLine(line: string): string {
+  return createHash('sha256').update(line, 'utf8').digest('hex').slice(0, 16);
+}
+
+/**
+ * 快照的**实质内容指纹**：折叠空白后取哈希。
+ *
+ * 为什么折叠空白：快照是 1~3 行短文本，换行/缩进差异不构成"状态变了"，
+ * 但会让宿主认为 runtime-context 变了并 append 一条新消息。
+ */
+export function snapshotFingerprint(text: string): string {
+  return hashLine(text.replace(/\s+/g, ' ').trim());
+}
+
+/**
+ * 快照是否发生了**实质变化**（仅空白差异不算）。
+ *
+ * ## 为什么需要
+ *
+ * 宿主把 `systemPrompt.context` 渲染成一条 runtime-context 用户消息，
+ * 文本一变就 append 一条新消息（旧消息留在 surface 里）。快照每轮都变
+ * 就会不断插入新消息：既打乱前缀缓存，又让上下文持续膨胀。
+ *
+ * 因此只有实质变化才更新快照；内容相同（含仅空白差异）时保持原样，
+ * 让宿主侧 `RuntimeContextProjection` 判定"无需更新"。
+ */
+export function snapshotChanged(previous: string, next: string): boolean {
+  if (previous === next) return false;
+  return snapshotFingerprint(previous) !== snapshotFingerprint(next);
+}
+
+/**
+ * 按游标切出新增文本（**纯函数**，便于测试）。
+ *
+ * @param lines 当前 transcript 的全部行
+ * @param state 上次保存的游标（null 表示首次）
+ */
+export function sliceByCursor(lines: string[], state: CursorState | null): SliceResult {
+  if (state === null || state.lastLine <= 0) {
+    return { text: lines.join('\n'), fromLine: 0, reset: false };
+  }
+
+  // 游标越界：transcript 变短了
+  if (state.lastLine > lines.length) {
+    return { text: lines.join('\n'), fromLine: 0, reset: true };
+  }
+
+  // 哈希校验：最后一行内容变了 ⇒ transcript 被重写
+  const anchor = lines[state.lastLine - 1] ?? '';
+  if (hashLine(anchor) !== state.lastHash) {
+    return { text: lines.join('\n'), fromLine: 0, reset: true };
+  }
+
+  return {
+    text: lines.slice(state.lastLine).join('\n'),
+    fromLine: state.lastLine,
+    reset: false,
+  };
+}
+
+/** 根据本次处理结果推进游标。 */
+export function advanceCursor(
+  lines: string[],
+  sessionId: string,
+  fromLine: number,
+  consumedLines: number,
+): CursorState {
+  const lastLine = Math.min(fromLine + consumedLines, lines.length);
+  return {
+    sessionId,
+    lastLine,
+    lastHash: lastLine > 0 ? hashLine(lines[lastLine - 1] ?? '') : '',
+    updatedAt: Date.now(),
+  };
+}
+
+/** 文件持久化的游标存储（按 sessionId 分槽）。 */
+export class CursorStore {
+  private readonly filePath: string;
+  private cache: Record<string, CursorState> | null = null;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  private loadAll(): Record<string, CursorState> {
+    if (this.cache !== null) return this.cache;
+    try {
+      if (existsSync(this.filePath)) {
+        this.cache = JSON.parse(readFileSync(this.filePath, 'utf8')) as Record<string, CursorState>;
+      } else {
+        this.cache = {};
+      }
+    } catch {
+      // 文件损坏不应阻断卸载：当作空游标，退回全量
+      this.cache = {};
+    }
+    return this.cache;
+  }
+
+  get(sessionId: string): CursorState | null {
+    return this.loadAll()[sessionId] ?? null;
+  }
+
+  set(state: CursorState): void {
+    const all = this.loadAll();
+    all[state.sessionId] = state;
+    try {
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      writeFileSync(this.filePath, JSON.stringify(all, null, 2), 'utf8');
+    } catch {
+      // 落盘失败不影响本次卸载，下次会退回全量
+    }
+  }
+}
+
+/**
+ * 最近已发送块的持久化。
+ *
+ * 为什么需要：`Offloader.recent` 是内存态，插件重启后丢失，
+ * 跨会话的换措辞复述会重新入库。落盘后查重窗口跨重启保留。
+ */
+export class RecentStore {
+  private readonly filePath: string;
+  private cache: string[] | null = null;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  load(): string[] {
+    if (this.cache !== null) return this.cache;
+    try {
+      if (existsSync(this.filePath)) {
+        const parsed = JSON.parse(readFileSync(this.filePath, 'utf8')) as unknown;
+        this.cache = Array.isArray(parsed)
+          ? parsed.filter((item): item is string => typeof item === 'string')
+          : [];
+      } else {
+        this.cache = [];
+      }
+    } catch {
+      // 文件损坏不应阻断卸载：当作空窗口
+      this.cache = [];
+    }
+    return this.cache;
+  }
+
+  save(items: string[]): void {
+    this.cache = items;
+    try {
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      writeFileSync(this.filePath, JSON.stringify(items), 'utf8');
+    } catch {
+      // 落盘失败不影响本次卸载
+    }
+  }
+}

package/src/event-classify.ts

@@ -0,0 +1,75 @@
+/**
+ * 事件分类：**全插件唯一的事件类型判定入口**。
+ *
+ * ## 为什么必须收口
+ *
+ * 之前每个模块各自写 `if (type === 'assistant/message')`：
+ * - `session-text.ts` 判用户消息
+ * - `context-trim.ts` 判裁剪边界
+ * - `index.ts` 判沉淀来源
+ *
+ * 结果是每出现一个新事件类型（`system/message`、`user-approval`、
+ * `skill-catalog`…）就要挨个补一遍，漏一个就是一次生产故障
+ * （`system/message` 漏判直接让 trim 必挂并熔断）。
+ *
+ * 收口后只有这里需要认识新类型，其余模块只消费分类结果。
+ */
+
+/** 一个 surface 事件的内容类别。 */
+export type EventCategory =
+  /** 系统提示（DSH 某些版本把它作为 surface 的 node 0） */
+  | 'system'
+  /** 宿主注入的上下文：技能目录 / 运行时 / 时间 / 模型切换 / 审批提示 */
+  | 'injected'
+  /** 用户真正说的话 */
+  | 'user'
+  /** 助手消息（正文 / 推理 / 工具调用） */
+  | 'assistant'
+  /** 工具结果 */
+  | 'tool-result'
+  /** 未知类型（保守处理：不参与裁剪、不参与沉淀） */
+  | 'unknown';
+
+/**
+ * 判定一个事件的内容类别。
+ *
+ * 用**白名单**：只有明确认识的类型才归入对话类别，其余一律 `unknown`。
+ * 这样新类型出现时最坏是「不处理」，而不是「被误当成可裁剪节点」。
+ *
+ * @param event - 会话事件
+ * @returns 内容类别
+ */
+export function classifyEvent(event: unknown): EventCategory {
+  const e = event as { type?: string; data?: { source?: { kind?: string } } };
+  switch (e?.type) {
+    case 'system/message':
+      return 'system';
+    case 'assistant/message':
+      return 'assistant';
+    case 'tool/result':
+      return 'tool-result';
+    case 'user/message': {
+      const kind = e.data?.source?.kind;
+      // 没有 source 视为真实用户消息（兼容旧格式）
+      return kind === undefined || kind === 'user' ? 'user' : 'injected';
+    }
+    default:
+      return 'unknown';
+  }
+}
+
+/**
+ * 是否是可替换的对话节点（裁剪边界、剪枝目标）。
+ *
+ * `system` / `injected` / `unknown` 都不能被替换：
+ * 替换系统提示会被 `compactRegion` 拒绝，替换注入上下文会丢运行时事实。
+ */
+export function isConversationNode(event: unknown): boolean {
+  const category = classifyEvent(event);
+  return category === 'user' || category === 'assistant' || category === 'tool-result';
+}
+
+/** 是否是真实用户消息（沉淀来源判定）。 */
+export function isRealUserEvent(event: unknown): boolean {
+  return classifyEvent(event) === 'user';
+}

package/src/governor.ts

@@ -0,0 +1,168 @@
+/**
+ * 单一步进控制器：能力门控 + 熔断 + 节流 + 有序执行。
+ *
+ * ## 为什么需要
+ *
+ * 之前每条路径各自判断「要不要跑、能不能跑、失败了怎么办」，
+ * 结果是：一条路径失败后每步重试（实测 60 次重复 flush），
+ * 另一条路径静默失效却没人知道。
+ *
+ * 把编排收口到一处后：
+ * - **能力门控**：能力矩阵说不可用，就一次都不调用
+ * - **熔断**：连续失败 N 次后禁用该动作，只告警一次
+ * - **节流**：按步数间隔执行，避免每步白扫
+ * - **有序**：先剪枝（便宜）再裁剪（贵），剪枝后 token 降下来裁剪可能就不必跑
+ *
+ * 本模块不依赖 DSH，纯编排，可直接单测。
+ */
+import type { CapabilityMatrix } from './capabilities.ts';
+
+/** 单个动作的执行结果。 */
+export interface GovernorOutcome {
+  ok: boolean;
+  /** 机器可读原因：ok / below-threshold / no-range / error:… */
+  reason: string;
+  /** 诊断细节 */
+  detail?: string;
+}
+
+/** 一个受控动作。 */
+export interface GovernorAction {
+  /** 动作名（用于熔断与状态展示） */
+  name: string;
+  /** 是否启用（能力矩阵 + 配置共同决定） */
+  enabled: boolean;
+  /** 两次执行之间至少间隔多少步（默认 1 = 每步） */
+  throttleSteps?: number;
+  /** 执行一次；允许同步或异步 */
+  run: () => GovernorOutcome | Promise<GovernorOutcome>;
+}
+
+/** 控制器状态（跨步保留）。 */
+export interface GovernorState {
+  /** 能力矩阵（首次探测后固定） */
+  capabilities: CapabilityMatrix | null;
+  /** 已执行步数 */
+  steps: number;
+  /** 每个动作的连续失败次数 */
+  failures: Record<string, number>;
+  /** 已熔断的动作 */
+  disabled: Set<string>;
+  /** 每个动作最近一次结果 */
+  lastOutcome: Record<string, GovernorOutcome>;
+  /** 每个动作上次执行的步数 */
+  lastRunStep: Record<string, number>;
+  /** 每个动作累计执行次数 */
+  runs: Record<string, number>;
+}
+
+/** 连续失败多少次后熔断。 */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+
+export function createGovernorState(): GovernorState {
+  return {
+    capabilities: null,
+    steps: 0,
+    failures: {},
+    disabled: new Set<string>(),
+    lastOutcome: {},
+    lastRunStep: {},
+    runs: {},
+  };
+}
+
+/**
+ * 执行一步。
+ *
+ * 动作按数组顺序执行；被禁用/熔断/未到节流间隔的跳过。
+ * 单个动作抛错不会中断后续动作。
+ *
+ * @param deps - 状态、动作列表、日志函数
+ * @returns 本步实际执行的动作名
+ */
+export async function runGovernor(deps: {
+  state: GovernorState;
+  actions: GovernorAction[];
+  log: (message: string) => void;
+  warn: (message: string) => void;
+}): Promise<string[]> {
+  const { state, actions, log, warn } = deps;
+  state.steps += 1;
+  const executed: string[] = [];
+
+  for (const action of actions) {
+    if (!action.enabled) continue;
+    if (state.disabled.has(action.name)) continue;
+
+    const throttle = action.throttleSteps ?? 1;
+    const last = state.lastRunStep[action.name];
+    if (last !== undefined && state.steps - last < throttle) continue;
+
+    state.lastRunStep[action.name] = state.steps;
+    state.runs[action.name] = (state.runs[action.name] ?? 0) + 1;
+    executed.push(action.name);
+
+    let outcome: GovernorOutcome;
+    try {
+      outcome = await action.run();
+    } catch (error) {
+      outcome = {
+        ok: false,
+        reason: `error:${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+    state.lastOutcome[action.name] = outcome;
+
+    if (outcome.ok) {
+      state.failures[action.name] = 0;
+      continue;
+    }
+
+    // 非异常原因（below-threshold / no-range）不算失败，不触发熔断
+    if (!outcome.reason.startsWith('error')) continue;
+
+    const failures = (state.failures[action.name] ?? 0) + 1;
+    state.failures[action.name] = failures;
+    if (failures >= MAX_CONSECUTIVE_FAILURES) {
+      state.disabled.add(action.name);
+      warn(
+        `[lrc][governor] ${action.name} 连续失败 ${failures} 次，已熔断（本次会话不再尝试）：${outcome.reason}`,
+      );
+    } else {
+      warn(
+        `[lrc][governor] ${action.name} 失败（${failures}/${MAX_CONSECUTIVE_FAILURES}）：${outcome.reason}`,
+      );
+    }
+  }
+
+  if (executed.length > 0) {
+    log(`[lrc][governor] 第 ${state.steps} 步执行：${executed.join(' → ')}`);
+  }
+  return executed;
+}
+
+/** 把控制器状态压成可读文本（`lrc_status` 工具用）。 */
+export function formatGovernorState(state: GovernorState): string {
+  const lines: string[] = [`步数：${state.steps}`];
+  const names = new Set([
+    ...Object.keys(state.runs),
+    ...Object.keys(state.lastOutcome),
+    ...state.disabled,
+  ]);
+  if (names.size === 0) {
+    lines.push('尚未执行任何动作');
+    return lines.join('\n');
+  }
+  for (const name of names) {
+    const outcome = state.lastOutcome[name];
+    const disabled = state.disabled.has(name) ? ' [已熔断]' : '';
+    const runs = state.runs[name] ?? 0;
+    const failures = state.failures[name] ?? 0;
+    lines.push(
+      `- ${name}${disabled}：执行 ${runs} 次，连续失败 ${failures}` +
+        `${outcome === undefined ? '' : `，最近 ${outcome.ok ? '成功' : outcome.reason}`}` +
+        `${outcome?.detail === undefined ? '' : `（${outcome.detail}）`}`,
+    );
+  }
+  return lines.join('\n');
+}

package/src/handoff.ts

@@ -0,0 +1,221 @@
+/**
+ * 路径 6：新建会话 + 摘要注入（会话交接）。
+ *
+ * ## 为什么需要
+ *
+ * 路径 1/2 只能把上下文压小，压到极限仍然会撞窗口。这时唯一的出路是
+ * 「另起炉灶」：把当前会话的结论整理成一份交接摘要，注入一个新会话，
+ * 原会话原样保留（可随时回看）。
+ *
+ * ## 为什么做成显式工具而不是自动触发
+ *
+ * 新建会话会改变用户的工作现场。自动触发一旦判断失误，用户会突然发现
+ * 自己在另一个会话里。所以只提供 `lrc_handoff` 工具，由用户或模型显式调用。
+ *
+ * ## 两条创建路径
+ *
+ * 1. `ctx.agents.create()` —— 建一个**带 agent 的**新会话，可直接继续对话（首选）
+ * 2. `ctx.sessions.create()` —— 只建会话，没有 agent（兜底，至少内容落盘）
+ *
+ * 两条都失败时只返回摘要文本，不抛错。
+ */
+
+/** 交接摘要的输入。 */
+export interface HandoffInput {
+  /** 当前会话的最后一条真实用户请求 */
+  lastUserRequest: string;
+  /** 最近几条助手正文（按时间正序） */
+  recentAssistant: string[];
+  /** 最近一次沉淀产出的状态快照 */
+  snapshot: string;
+  /** LRC 归档索引行（可为空） */
+  indexLines: string[];
+  /** 调用方补充的下一步说明 */
+  note: string;
+}
+
+/** 交接结果。 */
+export interface HandoffResult {
+  ok: boolean;
+  /** 新会话 id（创建成功时） */
+  sessionId?: string;
+  /** agent / session / text-only */
+  mode: string;
+  /** 交接摘要全文 */
+  text: string;
+  /** 失败原因 */
+  reason?: string;
+}
+
+/**
+ * 组装交接摘要。
+ *
+ * 只保留「接手的人必须知道」的四块：当前任务、最近结论、长期记忆索引、下一步。
+ * 不复制整段对话 —— 那等于把上下文原样搬过去。
+ */
+export function buildHandoffText(input: HandoffInput): string {
+  const sections: string[] = ['# 会话交接', ''];
+
+  sections.push('## 当前任务');
+  sections.push(input.lastUserRequest.trim().length > 0 ? input.lastUserRequest.trim() : '（未记录）');
+  sections.push('');
+
+  if (input.recentAssistant.length > 0) {
+    sections.push('## 最近结论');
+    for (const line of input.recentAssistant) {
+      const flat = line.replace(/\s+/g, ' ').trim();
+      if (flat.length > 0) sections.push(`- ${flat.length > 300 ? `${flat.slice(0, 300)}…` : flat}`);
+    }
+    sections.push('');
+  }
+
+  if (input.snapshot.trim().length > 0) {
+    sections.push('## 已沉淀状态');
+    sections.push(input.snapshot.trim());
+    sections.push('');
+  }
+
+  if (input.indexLines.length > 0) {
+    sections.push('## 长期记忆索引');
+    for (const line of input.indexLines) sections.push(`- ${line}`);
+    sections.push('');
+  }
+
+  sections.push('## 下一步');
+  sections.push(input.note.trim().length > 0 ? input.note.trim() : '（由接手方根据上述上下文继续）');
+
+  return sections.join('\n');
+}
+
+/** 从会话日志里取最后一条真实用户请求与最近几条助手正文。 */
+export function extractHandoffSource(session: unknown): {
+  lastUserRequest: string;
+  recentAssistant: string[];
+} {
+  const log = (session as { log?: unknown })?.log;
+  if (!Array.isArray(log)) return { lastUserRequest: '', recentAssistant: [] };
+
+  let lastUserRequest = '';
+  const assistant: string[] = [];
+  for (const raw of log) {
+    const event = raw as {
+      type?: string;
+      data?: { message?: { content?: unknown }; content?: unknown; source?: { kind?: string } };
+    };
+    if (event?.type === 'user/message') {
+      // 只认用户真正说的话，跳过技能目录 / 运行时上下文
+      const kind = event.data?.source?.kind;
+      if (kind !== undefined && kind !== 'user') continue;
+      const text = textOf(event.data?.content);
+      if (text.length > 0) lastUserRequest = text;
+    } else if (event?.type === 'assistant/message') {
+      const text = textOf(event.data?.message?.content);
+      if (text.length > 0) assistant.push(text);
+    }
+  }
+  return { lastUserRequest, recentAssistant: assistant.slice(-5) };
+}
+
+function textOf(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const out: string[] = [];
+  for (const block of content) {
+    const b = block as { type?: string; text?: unknown };
+    if (b?.type === 'text' && typeof b.text === 'string' && b.text.length > 0) out.push(b.text);
+  }
+  return out.join('\n');
+}
+
+function safeGet(ctx: unknown, name: string): unknown {
+  try {
+    return (ctx as { get?: (n: string) => unknown })?.get?.(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 创建新会话并注入交接摘要。
+ *
+ * 优先建「带 agent 的会话」，这样接手方可以直接继续对话；
+ * 失败则退化为「只建会话」；再失败就只返回摘要文本。
+ *
+ * @param deps - 宿主 ctx、当前 agent、交接摘要
+ * @returns 交接结果（永不抛错）
+ */
+export async function createHandoffSession(deps: {
+  ctx: unknown;
+  agent: unknown;
+  text: string;
+  log: (message: string) => void;
+}): Promise<HandoffResult> {
+  const { ctx, agent, text, log } = deps;
+  const current = agent as {
+    session?: { id?: string; header?: { cwd?: string } };
+    options?: unknown;
+  };
+  const currentId = current?.session?.id;
+  const cwd = current?.session?.header?.cwd;
+  const meta = {
+    ...(cwd === undefined ? {} : { cwd }),
+    ...(currentId === undefined ? {} : { parentSession: currentId }),
+  };
+  const userMessage = {
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  };
+
+  // 路径 A：带 agent 的新会话（可直接继续对话）
+  const agents = safeGet(ctx, 'agents') as
+    | { create?: (options: unknown) => Promise<{ agent?: { session?: unknown } }> }
+    | undefined;
+  if (typeof agents?.create === 'function') {
+    try {
+      const handle = await agents.create({
+        sessionId: `session-handoff-${Date.now()}`,
+        meta,
+        ...(current?.options === undefined ? {} : { agentOptions: current.options }),
+      });
+      const session = handle?.agent?.session as
+        | { id?: string; append?: (type: string, data: unknown) => unknown }
+        | undefined;
+      if (typeof session?.append === 'function') {
+        session.append('user/message', userMessage);
+        log(`[lrc][handoff] 已创建带 agent 的新会话：${session.id ?? 'unknown'}`);
+        return { ok: true, sessionId: session.id, mode: 'agent', text };
+      }
+    } catch (error) {
+      log(
+        `[lrc][handoff] agents.create 失败，退回 sessions.create：${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  // 路径 B：只建会话（没有 agent，但内容落盘）
+  const sessions = safeGet(ctx, 'sessions') as
+    | { create?: (id?: string, options?: unknown) => unknown }
+    | undefined;
+  if (typeof sessions?.create === 'function') {
+    try {
+      const session = sessions.create(undefined, { meta }) as
+        | { id?: string; append?: (type: string, data: unknown) => unknown }
+        | undefined;
+      if (typeof session?.append === 'function') {
+        session.append('user/message', userMessage);
+        log(`[lrc][handoff] 已创建新会话（无 agent）：${session.id ?? 'unknown'}`);
+        return { ok: true, sessionId: session.id, mode: 'session', text };
+      }
+    } catch (error) {
+      log(
+        `[lrc][handoff] sessions.create 失败，只返回摘要：${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  return { ok: false, mode: 'text-only', text, reason: 'sessions-unavailable' };
+}