dsh-compact-relay 0.3.5 → 0.4.0

package/lib/core/pin-suggest.js

@@ -0,0 +1,129 @@
+/**
+ * 压缩预览「建议锁定」候选识别（0.4 P1-1）—— 纯本地启发式，零依赖、不调模型。
+ *
+ * 目标：在压缩预览里指出「这次要压掉的历史中，哪些消息看起来值得先 /pin 再压」，
+ * 让用户在不可逆的压缩前把「关键决策 / 报错堆栈 / 明确要求别改」保留下来。
+ *
+ * 红线：
+ *  - **只提示、绝不自动锁**：本模块只返回候选（seq/角色/理由/一句摘要），不写任何记录；
+ *    客户端只渲染提示，锁定动作仍由用户执行 `/pin`；
+ *  - 隐私：只产出截断的一句摘要（默认 60 字符，不贴全文），用于本机 UI；
+ *  - 启发式宁可少报：长度太短、没有明确信号的消息不进入候选。
+ *
+ * 三类信号（优先级从高到低）：
+ *   1. `明确要求别改`：用户消息里说「不要改 / 别动 / 保持原样 / 必须保留 …」；
+ *   2. `报错堆栈`：异常类名 / 堆栈帧 / 中文「堆栈/报错」等；
+ *   3. `关键决策`：决定 / 拍板 / 采用 / 改用 / 结论 / 定稿等取舍用语。
+ */
+
+import {
+  isUserAuthoredMessage,
+  messageSnippetOf,
+  messageTextOf,
+  roleLabelOf,
+} from './pin-anchors.js';
+
+/** 一次预览最多建议几条（太多会变成噪声）。 */
+export const PIN_SUGGEST_LIMIT = 5;
+
+/** 文本至少这么长才参与识别（避免「好」「继续」这类短句误报）。 */
+export const PIN_SUGGEST_MIN_CHARS = 12;
+
+/** 摘要截断长度（与 pin 列表一致）。 */
+export const PIN_SUGGEST_SNIPPET_CHARS = 60;
+
+/** 三类理由的唯一文案（客户端直接展示）。 */
+export const PIN_SUGGEST_REASONS = Object.freeze({
+  error: '报错堆栈',
+  keep: '明确要求别改',
+  decision: '关键决策',
+});
+
+/** 用户明确要求「别改 / 保留」的措辞。 */
+const KEEP_RE =
+  /(?:(?:不要|别|勿|禁止|不能|不许|请勿|切勿)\s*(?:再)?\s*(?:修改|改动|改|动|变更|碰|删|删除))|(?:保持原样|保留原样|原样保留|必须保留|务必保留|千万别改|不要动)/iu;
+
+/** 报错 / 堆栈信号（异常类名、堆栈帧、中文「堆栈」等）。 */
+const ERROR_RE =
+  /(?:TypeError|ReferenceError|SyntaxError|RangeError|URIError|EvalError|AggregateError|Error:|Exception|Traceback|panic:|stack trace|UnhandledPromiseRejection|at\s+[^\s]+\s*\([^)]*:\d+:\d+\)|堆栈|错误日志|报错)/iu;
+
+/** 决策 / 取舍信号。 */
+const DECISION_RE =
+  /(?:决定|决策|拍板|结论|定稿|选型|采用|改用|改成|就按|最终方案|确定用|方案定为|取舍)/iu;
+
+/**
+ * 单条消息的候选理由；不是候选返回 null。
+ * @param {object} event
+ * @returns {'报错堆栈'|'明确要求别改'|'关键决策'|null}
+ */
+function reasonOf(event) {
+  const type = event?.type;
+  const text = messageTextOf(event);
+  if (text.length < PIN_SUGGEST_MIN_CHARS) return null;
+
+  // 用户消息优先判「明确要求别改」：这是最该原样保留的意图。
+  if (isUserAuthoredMessage(event) && KEEP_RE.test(text)) return PIN_SUGGEST_REASONS.keep;
+  // 报错堆栈/错误日志（用户贴的、助手复述的、工具结果里的都算）。
+  if (ERROR_RE.test(text)) return PIN_SUGGEST_REASONS.error;
+  // 决策/取舍：只认真实对话消息，不把工具结果里的普通输出当决策。
+  if (type !== 'tool/result' && DECISION_RE.test(text)) return PIN_SUGGEST_REASONS.decision;
+  return null;
+}
+
+/**
+ * 单条事件是否可能成为候选（类型过滤）：用户真实消息 / 助手消息 / 工具结果。
+ * 系统消息与运行时合成的 user/message（source.kind 非 user，如 checkpoint/时间上下文）
+ * 不参与建议。
+ * @param {object} event
+ * @returns {boolean}
+ */
+function eligibleOf(event) {
+  const type = event?.type;
+  if (type === 'assistant/message' || type === 'tool/result') return true;
+  if (type === 'user/message') return isUserAuthoredMessage(event);
+  return false;
+}
+
+const REASON_PRIORITY = Object.freeze({
+  [PIN_SUGGEST_REASONS.keep]: 0,
+  [PIN_SUGGEST_REASONS.error]: 1,
+  [PIN_SUGGEST_REASONS.decision]: 2,
+});
+
+/**
+ * 从「即将被压掉」的事件里挑值得先锁定的候选。
+ *
+ * @param {object[]} events 按历史顺序（旧→新）的事件列表；通常传 range.shadowedSeqs 对应的事件
+ * @param {{limit?:number}} [options]
+ * @returns {Array<{seq:number, role:string, reason:string, snippet:string}>}
+ *   按 seq 升序（文档顺序）返回；同一 seq 只出现一次。
+ */
+export function suggestPinCandidates(events, { limit = PIN_SUGGEST_LIMIT } = {}) {
+  if (!Array.isArray(events) || events.length === 0) return [];
+  const max = Number.isInteger(limit) && limit > 0 ? limit : PIN_SUGGEST_LIMIT;
+  const seen = new Set();
+  const matched = [];
+
+  for (const event of events) {
+    if (event === null || typeof event !== 'object') continue;
+    const seq = event.seq;
+    if (!Number.isInteger(seq) || seq < 0 || seen.has(seq)) continue;
+    if (!eligibleOf(event)) continue;
+    const reason = reasonOf(event);
+    if (reason === null) continue;
+    seen.add(seq);
+    matched.push({
+      seq,
+      role: roleLabelOf(event.type),
+      reason,
+      snippet: messageSnippetOf(event, PIN_SUGGEST_SNIPPET_CHARS),
+    });
+  }
+
+  if (matched.length <= max) return matched.sort((left, right) => left.seq - right.seq);
+  // 超过上限：先保「明确要求别改」，再报错堆栈，再关键决策；同级取更早的（更在压缩范围里）。
+  const picked = [...matched]
+    .sort((left, right) => REASON_PRIORITY[left.reason] - REASON_PRIORITY[right.reason] || left.seq - right.seq)
+    .slice(0, max);
+  return picked.sort((left, right) => left.seq - right.seq);
+}

package/lib/core/policy.js

@@ -58,6 +58,22 @@ export function ratioOf(pressure, window) {
 /** 压缩范围至少要比摘要大这么多 token 才划算（摘要 ~1K，留 4 倍安全系数）。 */
 export const MIN_COMPRESS_TOKENS = 4_000;
 
+/* ------------------------------------------------------------------ *
+ * 0.4 P0-1：cue 注入门控常量（方案 §3.2）
+ *
+ * cue 从「每轮都发」改成「合适时机发」：容量落在 10%–40%、且距上次注入
+ * ≥3 轮才发一次。三项都是可调参数，0.4.x 看真实数据再调，不改压缩行为。
+ * ------------------------------------------------------------------ */
+
+/** cue 注入区间的下限：10% 以下压缩不划算（且会被工具拒绝），不发 cue。 */
+export const CUE_MIN_RATIO = 0.1;
+
+/** cue 注入区间的上限：40% 及以上该直接建议压缩，不该再记节点（与默认压缩线一致）。 */
+export const CUE_MAX_RATIO = 0.4;
+
+/** 距上次注入至少这么多轮才再次注入（防每轮都发变成背景噪声）。 */
+export const CUE_MIN_TURNS = 3;
+
 /**
  * 「值得压缩」的最小容量比例（最小线，0.3.1）。
  *

package/lib/dsh/diag-counters.js

@@ -0,0 +1,204 @@
+/**
+ * 诊断计数 / 耗时 / 错误码（dcr 0.4 P0-2）—— 纯内存，进程内累计，重启清零。
+ *
+ * 为什么单独一个模块：诊断包只允许「数值 / 枚举 / 布尔 / 错误码」，计数必须在动作层
+ * 顺手记，但上界、聚合口径与产物形状要有一处唯一实现。本模块：
+ *   - 不读会话、不读文件、不发起任何网络请求；
+ *   - 只保留最近 20 个耗时样本 / 最近 20 条错误码，长时间运行不膨胀；
+ *   - `snapshot()` 每次返回全新对象，调用方改不坏内部状态；
+ *   - 错误只收 `code` / `phase` / `at` / `count`，**绝不收 message**（可能含聊天/路径）。
+ *
+ * 单例在 lib/index.js 装配到 `deps.diag`；actions 通过 `deps.diag.*` 埋点。
+ */
+
+/** 耗时样本上限（最近 20 次）。 */
+export const LATENCY_SAMPLE_LIMIT = 20;
+/** 错误码条目上限（按 code+phase 聚合后的条数）。 */
+export const ERROR_ENTRY_LIMIT = 20;
+/** 错误码 / 阶段名截断长度（防止异常长字符串撑大诊断包）。 */
+const CODE_MAX_CHARS = 60;
+const PHASE_MAX_CHARS = 20;
+
+/** 会被计数的动作类别（只统计这两条执行路径）。 */
+const ACTION_KINDS = Object.freeze(['compact', 'handoff']);
+
+function pad2(value) {
+  return String(value).padStart(2, '0');
+}
+
+/**
+ * 本地 ISO 时间（带时区偏移，例如 2026-10-24T15:40:00+08:00）。
+ *
+ * 不用 `toISOString()`：那是 UTC，用户看诊断包时要能对得上本地时间。
+ * @param {Date|number|string} [date]
+ * @returns {string}
+ */
+export function localIso(date = new Date()) {
+  const time = date instanceof Date ? date.getTime() : new Date(date).getTime();
+  const safe = Number.isNaN(time) ? new Date() : new Date(time);
+  const offsetMinutes = -safe.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absolute = Math.abs(offsetMinutes);
+  return (
+    `${safe.getFullYear()}-${pad2(safe.getMonth() + 1)}-${pad2(safe.getDate())}` +
+    `T${pad2(safe.getHours())}:${pad2(safe.getMinutes())}:${pad2(safe.getSeconds())}` +
+    `${sign}${pad2(Math.floor(absolute / 60))}:${pad2(absolute % 60)}`
+  );
+}
+
+/** 把任意文本规整成「单行 + 截断」的短标识；空串返回 null。 */
+function normalizeToken(value, maxChars) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.replace(/\s+/gu, ' ').trim();
+  if (trimmed.length === 0) return null;
+  return trimmed.length > maxChars ? `${trimmed.slice(0, Math.max(0, maxChars - 1))}…` : trimmed;
+}
+
+/**
+ * 错误 → 稳定的短 code（只用于诊断计数，不进用户文案）。
+ *
+ * 优先 `error.code`（本插件动作层自己抛的稳定 code），其次 `error.name`
+ * （AbortError / TypeError 等），都没有就 `'error'`。
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorCodeOf(error) {
+  if (error !== null && typeof error === 'object') {
+    const code = normalizeToken(error.code, CODE_MAX_CHARS);
+    if (code !== null) return code;
+    const name = normalizeToken(error.name, CODE_MAX_CHARS);
+    if (name !== null && name !== 'Error') return name;
+  }
+  return 'error';
+}
+
+/**
+ * 最近 rank 口径的百分位（nearest-rank）：p 分位 = 排序后第 ceil(p*n) 个。
+ * 样本为空返回 null；样本 < 3 时也照实给值（n 分别是 1 / 2）。
+ * @param {number[]} sorted 已升序排序的样本
+ * @param {number} fraction 0–1
+ * @returns {number|null}
+ */
+function percentile(sorted, fraction) {
+  if (!Array.isArray(sorted) || sorted.length === 0) return null;
+  const rank = Math.ceil(fraction * sorted.length);
+  const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));
+  return sorted[index];
+}
+
+/**
+ * 进程内诊断计数器。
+ *
+ * 返回：
+ *   - `bumpAction(kind, ok)`：压缩/交接成功或失败 +1（kind: 'compact' | 'handoff'）；
+ *   - `recordDuration(kind, ms)`：记录一次耗时（只留最近 20 个样本）；
+ *   - `bumpPin()`：一次成功的「锁定」动作 +1（toggle 走一次只记一次）；
+ *   - `bumpCueInjected()`：0.4 P0-1 —— cue 实际注入一次 +1（只记次数，不记原文）；
+ *   - `bumpMark(ok)`：0.4 P0-1 —— `mark_compress_point` 调用一次：markCalls 必 +1，
+ *     ok=true 时 markAccepted +1，否则 markRejected +1（被拒也算调用）；
+ *   - `recordError(code, phase)`：按 (code, phase) 聚合并保留最近 20 条；丢弃 message；
+ *   - `snapshot()`：返回 `{ counters, latency, errors }`（形状严格白名单，见方案 §3）。
+ *
+ * @returns {{bumpAction:Function, recordDuration:Function, bumpPin:Function, bumpCueInjected:Function, bumpMark:Function, recordError:Function, snapshot:Function}}
+ */
+export function createDiagCounters() {
+  const action = {
+    compact: { ok: 0, fail: 0 },
+    handoff: { ok: 0, fail: 0 },
+  };
+  let pins = 0;
+  // 0.4 P0-1：判断机制的四个计量（cue 注入 / 工具调用 / 接受 / 拒绝），只记次数。
+  let cueInjected = 0;
+  let markCalls = 0;
+  let markAccepted = 0;
+  let markRejected = 0;
+  const durations = { compact: [], handoff: [] };
+  /** key = `${phase}:${code}`；Map 的插入顺序即最近使用顺序（命中时删除再插入）。 */
+  const errors = new Map();
+
+  const isKind = (kind) => ACTION_KINDS.includes(kind);
+
+  function bumpAction(kind, ok) {
+    if (!isKind(kind)) return;
+    if (ok === true) action[kind].ok += 1;
+    else action[kind].fail += 1;
+  }
+
+  function recordDuration(kind, ms) {
+    if (!isKind(kind)) return;
+    const value = typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 ? Math.round(ms) : null;
+    if (value === null) return;
+    const samples = durations[kind];
+    samples.push(value);
+    if (samples.length > LATENCY_SAMPLE_LIMIT) samples.splice(0, samples.length - LATENCY_SAMPLE_LIMIT);
+  }
+
+  function bumpPin() {
+    pins += 1;
+  }
+
+  function bumpCueInjected() {
+    cueInjected += 1;
+  }
+
+  /**
+   * `mark_compress_point` 调用一次：被拒也算调用（被拒是零副作用的正常结果）。
+   * @param {boolean} ok 工具是否接受并写入记录
+   */
+  function bumpMark(ok) {
+    markCalls += 1;
+    if (ok === true) markAccepted += 1;
+    else markRejected += 1;
+  }
+
+  function recordError(code, phase) {
+    const codeText = normalizeToken(code, CODE_MAX_CHARS) ?? 'error';
+    const phaseText = normalizeToken(phase, PHASE_MAX_CHARS) ?? 'unknown';
+    const key = `${phaseText}:${codeText}`;
+    const existing = errors.get(key);
+    if (existing === undefined) {
+      errors.set(key, { code: codeText, phase: phaseText, at: localIso(), count: 1 });
+      // 只保留最近 20 条：最久没再出现的那条先淘汰（Map 头部）。
+      while (errors.size > ERROR_ENTRY_LIMIT) {
+        const oldestKey = errors.keys().next().value;
+        errors.delete(oldestKey);
+      }
+      return;
+    }
+    existing.count += 1;
+    existing.at = localIso();
+    // 命中即「最近出现过」：挪到 Map 尾部，淘汰顺序才准确。
+    errors.delete(key);
+    errors.set(key, existing);
+  }
+
+  function latencyOf(kind) {
+    const sorted = [...durations[kind]].sort((left, right) => left - right);
+    return {
+      n: sorted.length,
+      p50: percentile(sorted, 0.5),
+      p95: percentile(sorted, 0.95),
+    };
+  }
+
+  function snapshot() {
+    return {
+      counters: {
+        compactOk: action.compact.ok,
+        compactFail: action.compact.fail,
+        handoffOk: action.handoff.ok,
+        handoffFail: action.handoff.fail,
+        pins,
+        cueInjected,
+        markCalls,
+        markAccepted,
+        markRejected,
+      },
+      latency: { compact: latencyOf('compact'), handoff: latencyOf('handoff') },
+      // 最近出现的在前（诊断包最关心「刚炸了什么」）。
+      errors: [...errors.values()].reverse().map(({ code, phase, at, count }) => ({ code, phase, at, count })),
+    };
+  }
+
+  return { bumpAction, recordDuration, bumpPin, bumpCueInjected, bumpMark, recordError, snapshot };
+}