dsh-compact-relay 0.0.0-stage → 0.3.2

package/lib/actions/settings.js

@@ -0,0 +1,191 @@
+/**
+ * 设置存储动作层（A9：从根目录 settings-store.js 拆出来）。
+ *
+ * 分层：cordis 插件配置（基础层）← 用户 JSON（覆盖层）→ resolveConfig 校验。
+ * 文件读写在 dsh/settings-file.js；字段白名单/公开视图在 core/config-schema.js。
+ * 这里只做「合并 + 校验 + 回落 + 热替换 + 错误上报」。
+ *
+ * A4（2026-10-20）：
+ * - 用户文件「合法 JSON + 非法值」不再让插件整体不激活：回落基础配置，
+ *   把 `settingsError{field,message}` 交给设置页展示。
+ * - 文件写成 `{v:1,config:{...}}` 信封；读侧兼容旧扁平文件。
+ */
+import { resolveConfig } from '../config.js';
+import { paletteForBothSchemes } from '../core/colors.js';
+import { readNativeCompaction } from '../dsh/native-compaction.js';
+import { filterSettingsPatch, publicConfigOf } from '../core/config-schema.js';
+import {
+  defaultSettingsPath,
+  readPackageVersion,
+  readSettingsFile,
+  removeSettingsFile,
+  writeSettingsFile,
+} from '../dsh/settings-file.js';
+
+export { defaultSettingsPath } from '../dsh/settings-file.js';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 深合并普通对象；数组/标量直接覆盖。 */
+function deepMerge(base, patch) {
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    out[key] = isPlainObject(value) && isPlainObject(out[key]) ? deepMerge(out[key], value) : value;
+  }
+  return out;
+}
+
+/**
+ * 把异常统一成 `{field,message}`；field 只用于定位，不写进设置文件。
+ * @param {unknown} error
+ * @returns {{field:string|null,message:string}}
+ */
+function toSettingsError(error) {
+  return {
+    field: error !== null && typeof error === 'object' && typeof error.field === 'string' ? error.field : null,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/**
+ * @param {{config?:object, file?:string}} [options]
+ */
+export function createSettingsStore({ config = {}, file = defaultSettingsPath() } = {}) {
+  const base = isPlainObject(config) ? config : {};
+  const loaded = readSettingsFile(file);
+  let user = loaded.user;
+  let settingsError = loaded.error;
+  let current;
+
+  if (settingsError === null) {
+    try {
+      current = resolveConfig(deepMerge(base, user));
+    } catch (error) {
+      // 用户覆盖层非法：忽略它，回落基础配置；错误留给设置页显示。
+      settingsError = toSettingsError(error);
+      user = {};
+    }
+  }
+  if (current === undefined) {
+    try {
+      current = resolveConfig(base);
+    } catch (error) {
+      if (settingsError === null) settingsError = toSettingsError(error);
+      // 连基础配置都非法时，保证插件仍能启动（用默认值），错误照常上报。
+      current = resolveConfig({});
+    }
+  }
+
+  // 设置页「恢复默认」显示的基准：cordis 基础配置（坏的话用默认值兜底）。
+  let baseResolved;
+  try {
+    baseResolved = resolveConfig(base);
+  } catch {
+    baseResolved = resolveConfig({});
+  }
+
+  const listeners = new Set();
+  const notify = () => {
+    for (const listener of listeners) {
+      try {
+        listener(current);
+      } catch {
+        /* 单个监听器失败不影响保存 */
+      }
+    }
+  };
+
+  const view = () => ({
+    config: publicConfigOf(current),
+    defaults: publicConfigOf(baseResolved),
+    // A8：浅/深两套派生色板（设置页预览可用；未保存编辑仍走客户端纯函数）。
+    palettes: paletteForBothSchemes(current.colors),
+    windowFallback: current.contextWindowFallback,
+    version: readPackageVersion(),
+    // 0.3.1：DSH 原生自动压缩配置（设置页开关 / 交接线上限校验用）。
+    native: (() => {
+      const nativeCfg = readNativeCompaction();
+      return { autoEnabled: nativeCfg.autoEnabled, thresholdRatio: nativeCfg.thresholdRatio, file: nativeCfg.file };
+    })(),
+    path: file,
+    settingsError: settingsError === null ? null : { ...settingsError },
+  });
+
+  return {
+    /** 当前生效的完整配置（readState / actions 每次调用时读）。 */
+    get current() {
+      return current;
+    },
+    /** 当前设置文件问题（用于 state/设置页提示）；null=正常。 */
+    get error() {
+      return settingsError === null ? null : { ...settingsError };
+    },
+    filePath: file,
+    view,
+    /**
+     * 合并保存一组设置；先校验再写盘，最后热替换当前配置。
+     * @param {object} patch
+     * @returns {object} 最新 view
+     */
+    save(patch) {
+      const filtered = filterSettingsPatch(patch);
+      if (Object.keys(filtered).length === 0) throw new Error('没有可保存的设置项');
+      const nextUser = deepMerge(user, filtered);
+      // 先校验，失败不落盘
+      let next;
+      try {
+        next = resolveConfig(deepMerge(base, nextUser));
+      } catch (error) {
+        const wrapped = new Error(error instanceof Error ? error.message : String(error));
+        wrapped.field = error !== null && typeof error === 'object' ? error.field : undefined;
+        throw wrapped;
+      }
+      // 0.3.1：原生自动压缩开着时，交接线不能 >= 原生阈值（否则原生会先动手、我们的提醒失效）。
+      const nativeCfg = readNativeCompaction();
+      if (nativeCfg.autoEnabled) {
+        const limit = nativeCfg.thresholdRatio - 0.01;
+        if (next.thresholds.handoffRatio >= nativeCfg.thresholdRatio - 1e-9) {
+          const wrapped = new Error(
+            `「交接提醒线」必须低于 DSH 原生自动压缩线（${(nativeCfg.thresholdRatio * 100).toFixed(0)}%），否则原生压缩会先动手；` +
+              `最高只能设到 ${(limit * 100).toFixed(0)}%。想设更高请先在设置里关闭「DSH 原生自动压缩」。`,
+          );
+          wrapped.field = 'thresholds.handoffRatio';
+          throw wrapped;
+        }
+      }
+      // A4：信封装盘；旧扁平文件在这时自动升级，不丢用户设置。
+      writeSettingsFile(file, nextUser);
+      user = nextUser;
+      current = next;
+      settingsError = null;
+      notify();
+      return view();
+    },
+    /** 删除用户覆盖，回到默认（含 cordis 基础配置）。 */
+    reset() {
+      removeSettingsFile(file);
+      user = {};
+      settingsError = null;
+      try {
+        current = resolveConfig(base);
+      } catch {
+        current = resolveConfig({});
+      }
+      notify();
+      return view();
+    },
+    /** 配置热替换回调；返回取消函数。 */
+    onChange(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      listeners.clear();
+    },
+  };
+}
+
+export default createSettingsStore;

package/lib/actions/stage.js

@@ -0,0 +1,36 @@
+/**
+ * 标记进度（M4，内部代号「阶段标记」）—— 把「这个阶段完成了」写进会话日志。
+ *
+ * 只写一条 plugin record：不进模型上下文、不影响 token，压缩/交接都不会碰它。
+ * 指示灯读到最新一条后外环变阶段色（默认蓝）；下一次压缩/交接（产生新 checkpoint）之后自动失效。
+ */
+import { actionError } from '../core/errors.js';
+import { STAGE_RECORD_TYPE, normalizeStageLabel } from '../core/stage.js';
+import { measurePressure } from '../dsh/pressure.js';
+
+/**
+ * @param {{engine:object, ctx?:object, cfg?:object}} deps
+ * @param {{agent:object, label?:string}} input
+ * @returns {Promise<{label:string, at:number, seq:number, ratio:number|null}>}
+ */
+export async function markStage(deps, { agent, label } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('stage', '没有活动会话');
+  const normalized = normalizeStageLabel(label);
+  const at = Date.now();
+  // 0.3.1：记下标记那一刻的容量比例，指示灯才能在环上标出「标记位置」。
+  // 测不到（会话刚开 / tokenMeter 不可用）就记 null，环上退化到当前比例。
+  const measured = await measurePressure(deps.ctx, agent, {
+    windowFallback: deps.cfg?.contextWindowFallback ?? 1_000_000,
+  }).catch(() => null);
+  const ratio =
+    measured !== null && typeof measured === 'object' && typeof measured.ratio === 'number' && Number.isFinite(measured.ratio)
+      ? Math.max(0, Math.min(1, measured.ratio))
+      : null;
+  const seq = deps.engine.appendPluginRecord(session, STAGE_RECORD_TYPE, {
+    label: normalized,
+    at,
+    ...(ratio === null ? {} : { ratio }),
+  });
+  return { label: normalized, at, seq, ratio };
+}

package/lib/actions/state.js

@@ -0,0 +1,134 @@
+/**
+ * 状态快照 —— 唯一的「当前上下文怎么样」。
+ *
+ * 指示灯、菜单、命令前置检查都读这一份；交接单的现场信息由 actions/handoff
+ * 直接调 dsh/pressure + dsh/session-view（不走这里）。客户端不再自己算阈值。
+ */
+import { paletteForBothSchemes } from '../core/colors.js';
+import { adviceFor, ratioOf, thresholdsForWindow } from '../core/policy.js';
+import { measurePressure } from '../dsh/pressure.js';
+import { selectCompactableRange } from '../dsh/select-range.js';
+import { compressHint as compressHintOf, countSummaries, lastCheckpointSurfaceSeq, livePinnedSeqs, liveSessionOf, pickAgent, surfaceSeqs } from '../dsh/session-view.js';
+import { compressHintIsActive } from '../core/compress-hint.js';
+import { readNativeCompaction } from '../dsh/native-compaction.js';
+import { relayRecordOf } from '../dsh/relay.js';
+
+/**
+ * 动作层统一解析「这次动作作用在哪个 agent」：只认显式 sessionId，
+ * 找不到就是 null（不允许退化成「最后一个 agent」压错会话）。
+ * A9：HTTP 适配层不再直接 import dsh/session-view.pickAgent。
+ * @param {{ctx:object}} deps
+ * @param {{sessionId?:string}} [input]
+ * @returns {object|null}
+ */
+export function resolveTarget(deps, { sessionId } = {}) {
+  return pickAgent(deps.ctx, sessionId);
+}
+
+/**
+ * 状态帧的单调版本号（P3-12）。
+ *
+ * 轮询响应与 SSE 帧走同一个 readState，网络乱序时旧响应可能晚到并覆盖新状态。
+ * 这里给每帧一个进程内单调递增的 revision：浏览器端只接受更大的那一帧。
+ * 只加字段（不破坏既有 HTTP 契约），旧客户端忽略它即可。
+ */
+let stateRevision = 0;
+
+/**
+ * 把 live session 包成 readState 认识的「类 agent」（只需要 id + session）。
+ * @param {object|undefined} session
+ * @returns {object|null}
+ */
+function passivized(session) {
+  return session === undefined || session === null ? null : { id: session.id, session };
+}
+
+/**
+ * @param {{ctx:object, cfg:object, lock:object}} deps
+ * @param {{sessionId?:string, agent?:object}} [target]
+ */
+export async function readState(deps, { sessionId, agent } = {}) {
+  // 指定 agent 就用它；否则按 sessionId 找 agent，找不到但会话已加载 → 退化用 live session。
+  // 后者修「刚重启、会话还没起 agent 时，指示灯数字为空/串会话」的坑。
+  const picked = agent ?? pickAgent(deps.ctx, sessionId);
+  const target = picked ?? passivized(liveSessionOf(deps.ctx, sessionId));
+
+  const measured =
+    target === null
+      ? { tokens: null, surfaceTokens: null, window: deps.cfg.contextWindowFallback, ratio: 0, nodes: [] }
+      : await measurePressure(deps.ctx, target, { windowFallback: deps.cfg.contextWindowFallback });
+
+  const summaries = target === null ? 0 : countSummaries(target.session);
+  // 阈值按「窗口比例」配置，这里换算成当前模型窗口的绝对 token 线；
+  // 窗口从 resolveModelInfo 来（拿不到时 measurePressure 已回落到 contextWindowFallback）。
+  const thresholdLines = thresholdsForWindow(deps.cfg.thresholds, measured.window);
+  const advice = adviceFor({ pressure: measured.tokens, summaries, thresholds: thresholdLines });
+
+  // 当前能不能精压（菜单里显示「可压 N 条 / 没有可压范围」，点击前就有明确反馈）。
+  // 只对活着的 agent 算；passivized 的会话没有 agent，点了也压不了，直接 null。
+  let compactRange = null;
+  if (picked !== undefined && picked !== null) {
+    const live = picked.session ?? null;
+    if (live !== null) {
+      compactRange = selectCompactableRange({
+        session: live,
+        nodes: measured.nodes.filter((node) => Number.isInteger(node?.seq)),
+        engine: deps.engine,
+        cfg: deps.cfg,
+        tokenOf: (node) => node.heuristicTokens ?? node.tokens ?? 0,
+      });
+      compactRange =
+        compactRange === null
+          ? null
+          : { nodes: compactRange.shadowedSeqs.length, tokens: compactRange.tokenCount, startSeq: compactRange.startSeq, endSeq: compactRange.endSeq };
+    }
+  }
+
+  // M6：钉住集合（菜单显示「清除钉住（N 条）」，也能在无 agent 时读 live session）。
+  const pinnedSeqs = target === null ? [] : livePinnedSeqs(target.session);
+  // 0.3.1：锁定消息在 surface 里的相对位置（0–1，方案 A：消息在历史中的位置），
+  // 指示灯环上按位置画锁定块；多个锁定按位置从早到晚排序。
+  const surface = target === null ? [] : surfaceSeqs(target.session);
+  const surfaceIndex = new Map(surface.map((seq, index) => [seq, index]));
+  const pinMarks = pinnedSeqs
+    .filter((seq) => surfaceIndex.has(seq))
+    .map((seq) => {
+      const index = surfaceIndex.get(seq);
+      const position = surface.length <= 1 ? 0 : index / (surface.length - 1);
+      return { seq, ratio: Math.max(0, Math.min(1, position)) };
+    })
+    .sort((a, b) => a.ratio - b.ratio);
+
+  // 0.3.1：模型的「这里适合压缩」判断（比最后一次压缩/交接 checkpoint 新才算数）。
+  const checkpointSeq = target === null ? undefined : lastCheckpointSurfaceSeq(target.session);
+  const hint = target === null ? null : compressHintOf(target.session);
+  const activeHint = compressHintIsActive(hint, checkpointSeq) ? { ratio: hint.ratio, at: hint.at, seq: hint.seq } : null;
+  // 0.3.1：DSH 原生自动压缩配置（读 profile 的 cordis.patch.yml + DSH 默认值）。
+  const nativeCfg = readNativeCompaction();
+
+  return {
+    revision: ++stateRevision,
+    sessionId: target?.id ?? null,
+    pressure: measured.tokens,
+    surfaceTokens: measured.surfaceTokens,
+    window: measured.window,
+    ratio: measured.ratio ?? ratioOf(measured.tokens, measured.window),
+    summaries,
+    advice,
+    level: advice === 'none' ? 'idle' : advice,
+    pins: { count: pinnedSeqs.length, seqs: pinnedSeqs.slice(-20), marks: pinMarks },
+    compactRange,
+    busy: deps.lock.isBusy(target?.id),
+    thresholds: thresholdLines,
+    // A8：两套派生色板由 host 算好下发，浏览器半只按明暗挑一套（见 core/colors.js）。
+    colors: { ...deps.cfg.colors, palette: paletteForBothSchemes(deps.cfg.colors) },
+    // A4：设置文件有误时随状态下发，设置页/客户端可提示（正常为 null）。
+    settingsError: deps.settings?.error ?? null,
+    // A5：最近一次交接的接力链记录（没有就是 null）。
+    relay: target === null ? null : relayRecordOf(target.session),
+    // 0.3.1：模型判断的「适合压缩」断点位置（没有或已失效为 null）。
+    compressHint: activeHint,
+    // 0.3.1：DSH 原生自动压缩（环上的报警最高阈值 / 设置页开关的数据源）。
+    native: { autoEnabled: nativeCfg.autoEnabled, thresholdRatio: nativeCfg.thresholdRatio },
+  };
+}

package/lib/actions/test-compact.js

@@ -0,0 +1,103 @@
+/**
+ * M1 实验动作 —— `/bctest`。
+ *
+ * 默认 dry-run 只给预览；加 confirm 才真的执行替换。
+ * 走的是和正式压缩旧会话同一条 dsh/compact-transaction，不另写一遍 append。
+ */
+import { actionError } from '../core/errors.js';
+import { TEST_INSTRUCTION } from '../core/prompts.js';
+import { selectTestRange } from '../core/ranges.js';
+import { replaceRangeWithSummary } from '../dsh/compact-transaction.js';
+import { runIdle } from '../dsh/idle.js';
+import { measurePressure } from '../dsh/pressure.js';
+import { firstCompactableIdx } from '../dsh/session-view.js';
+import { summarize } from '../dsh/summarizer.js';
+import { withLock } from './lock.js';
+
+function tokenCountOf(nodes, shadowedSeqs) {
+  const wanted = new Set(shadowedSeqs);
+  return nodes
+    .filter((node) => wanted.has(node.seq))
+    .reduce((sum, node) => sum + (node.heuristicTokens ?? node.tokens ?? 0), 0);
+}
+
+/**
+ * @param {{ctx:object, cfg:object, lock:object, engine:object}} deps
+ * @param {{agent:object, signal?:AbortSignal, confirm?:boolean, commandId?:string}} input
+ */
+export async function testCompact(deps, { agent, signal, confirm = false, commandId }) {
+  if (agent === undefined || agent === null) throw actionError('nosession', '没有活动会话');
+  const session = agent.session;
+
+  return withLock(deps.lock, agent.id, async () => {
+    const measured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback });
+    const nodes = measured.nodes.filter((node) => Number.isInteger(node?.seq));
+
+    const range = selectTestRange({
+      nodes,
+      firstIdx: firstCompactableIdx(session),
+      nodeCount: deps.cfg.dev.testRangeNodes,
+      isBalancedBefore: (seq) => deps.engine.toolPairingBalancedBefore(session, seq),
+      isBalancedAfter: (seq) => deps.engine.toolPairingBalancedAfter(session, seq),
+    });
+    if (range === null) {
+      throw actionError('range', '找不到配对平衡的小范围（会话太短，或工具有未配对调用）');
+    }
+
+    const shadowedTokenCount = tokenCountOf(nodes, range.shadowedSeqs);
+    const freshRange = { ...range, shadowedTokenCount };
+
+    if (!confirm) {
+      return {
+        dryRun: true,
+        range: freshRange,
+        shadowedTokenCount,
+        message:
+          `预览：将把 seq ${range.startSeq}–${range.endSeq} 共 ${range.shadowedSeqs.length} 条历史替换成一条摘要` +
+          `（约 ${shadowedTokenCount} token）。确认执行：/bctest confirm`,
+      };
+    }
+
+    const flush =
+      typeof deps.ctx.sessions?.flush === 'function' ? () => deps.ctx.sessions.flush(session) : undefined;
+    const estimateMessage =
+      typeof deps.ctx?.tokenMeter?.estimateMessage === 'function'
+        ? (message) => deps.ctx.tokenMeter.estimateMessage(message)
+        : undefined;
+
+    const outcome = await runIdle(agent, (idleSignal) => {
+      const combined = signal === undefined ? idleSignal : AbortSignal.any([signal, idleSignal]);
+      return replaceRangeWithSummary({
+        session,
+        range: freshRange,
+        engine: deps.engine,
+        signal: combined,
+        sourceCommandId: commandId,
+        estimateMessage,
+        summarize: ({ shadowedSeqs, signal: innerSignal }) =>
+          summarize({
+            ctx: deps.ctx,
+            engine: deps.engine,
+            agent,
+            shadowedSeqs,
+            endSeq: freshRange.endSeq,
+            instruction: TEST_INSTRUCTION,
+            requiredSections: [], // /bctest 是短段落摘要，不做六段校验
+            maxTokens: deps.cfg.summary.maxTokens,
+            signal: innerSignal,
+          }),
+        flush,
+      });
+    });
+
+    return {
+      ok: true,
+      dryRun: false,
+      range: freshRange,
+      ...outcome,
+      message:
+        `替换成功：${outcome.shadowedSeqs.length} 条历史 → 一条摘要` +
+        `（compaction seq ${outcome.startSeq}–${outcome.endSeq}，约 ${outcome.shadowedTokenCount} token）。`,
+    };
+  });
+}

package/lib/adapters/commands.js

@@ -0,0 +1,177 @@
+/**
+ * 斜杠命令适配层 —— 只做「参数校验 → 调 action → 结果映射」。
+ *
+ * /bc、/handoff、/pin、/unpin、/bctest 五个入口都不含业务逻辑；
+ * 换实现只动 actions 层。
+ */
+import { betterCompact, previewBetterCompact, takePreviewPlan } from '../actions/better-compact.js';
+import { handoff } from '../actions/handoff.js';
+import { listPins, pinByIndex, pinLastTurn, unpinAll } from '../actions/pin.js';
+import { testCompact } from '../actions/test-compact.js';
+import { errorText } from '../core/errors.js';
+
+function success(outcome) {
+  return {
+    kind: 'success',
+    text: typeof outcome?.message === 'string' && outcome.message.length > 0 ? outcome.message : '完成。',
+    ...(Number.isFinite(outcome?.summarySeq) ? { sourceEventSeq: outcome.summarySeq } : {}),
+    // A5：交接命令把结构化 childId 一并交给命令卡（文本里的 #child= 只是兜底）。
+    ...(typeof outcome?.childId === 'string' && outcome.childId.length > 0 ? { childId: outcome.childId } : {}),
+  };
+}
+
+function failure(error, signal) {
+  return { kind: 'error', text: signal?.aborted ? '操作已取消。' : errorText(error) };
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ctx:object, cfg:object, lock:object, engine:object}} deps
+ */
+export function registerCommands(ctx, deps) {
+  const active = new Set();
+
+  const track = (promise) => {
+    active.add(promise);
+    const retire = () => active.delete(promise);
+    promise.then(retire, retire);
+    return promise;
+  };
+
+  const register = (definition) => {
+    ctx.effect(function* () {
+      yield async () => {
+        await Promise.allSettled(active);
+      };
+      yield ctx.commands.register(definition);
+    }, `compact-relay: /${definition.name} command`);
+  };
+
+  register({
+    name: 'bc',
+    description: '压缩旧会话：把较早会话压成摘要腾出容量，先看压缩预估再确认（/bc confirm）',
+    // 与 /bctest 同理：声明 input 才能让「/bc confirm」不被当成普通消息。
+    input: { hint: 'confirm' },
+    handler: (invocation) =>
+      track(
+        (async () => {
+          const raw = invocation.rawInput.trim();
+          if (raw !== '' && raw !== 'confirm') {
+            return { kind: 'error', text: '用法：/bc（预览）或 /bc confirm（真正执行）' };
+          }
+          try {
+            if (raw === 'confirm') {
+              // A3：确认必须绑定刚才预览的那一段；缓存过期就要求重新预览，不拿新范围冒充旧同意。
+              const expected = takePreviewPlan(invocation.agent?.id);
+              if (expected === null) {
+                return { kind: 'error', text: '预览已过期或还没预览，请先输入 /bc 重新预览，再 /bc confirm。' };
+              }
+              const outcome = await betterCompact(deps, {
+                agent: invocation.agent,
+                signal: invocation.signal,
+                commandId: invocation.commandId,
+                expected,
+              });
+              return success(outcome);
+            }
+            const outcome = await previewBetterCompact(deps, { agent: invocation.agent });
+            return success(outcome);
+          } catch (error) {
+            return failure(error, invocation.signal);
+          }
+        })(),
+      ),
+  });
+
+  register({
+    name: 'handoff',
+    description: '交接新会话：生成交接单并开新会话接着聊，旧会话保留（交接前可能压缩）（/handoff）',
+    handler: (invocation) =>
+      track(
+        (async () => {
+          if (invocation.rawInput.trim().length > 0) return { kind: 'error', text: '用法：/handoff（不带参数）' };
+          try {
+            const outcome = await handoff(deps, {
+              agent: invocation.agent,
+              signal: invocation.signal,
+              commandId: invocation.commandId,
+            });
+            return success(outcome);
+          } catch (error) {
+            return failure(error, invocation.signal);
+          }
+        })(),
+      ),
+  });
+
+  register({
+    name: 'pin',
+    description: '锁定重要消息：/pin 锁定最近一轮｜/pin list 按序号挑｜/pin clear 全部解锁',
+    input: { hint: 'list | 序号 | clear' },
+    handler: (invocation) =>
+      track(
+        (async () => {
+          try {
+            const raw = invocation.rawInput.trim();
+            const lower = raw.toLowerCase();
+            const agent = invocation.agent;
+            let outcome;
+            if (raw === '') outcome = pinLastTurn(deps, { agent });
+            else if (lower === 'list') outcome = listPins(deps, { agent });
+            else if (lower === 'clear' || lower === 'unpin') outcome = unpinAll(deps, { agent });
+            else if (/^\d+$/.test(raw)) outcome = pinByIndex(deps, { agent, index: Number(raw) });
+            else outcome = null;
+            if (outcome === null) {
+              return { kind: 'error', text: '用法：/pin（锁定最近一轮）｜/pin list（看最近 10 条）｜/pin <序号>｜/pin clear（全部解锁）' };
+            }
+            return success(outcome);
+          } catch (error) {
+            return failure(error, invocation.signal);
+          }
+        })(),
+      ),
+  });
+
+  register({
+    name: 'unpin',
+    description: '解锁消息：解除锁定，允许后续压缩合并这些消息',
+    handler: (invocation) =>
+      track(
+        (async () => {
+          try {
+            return success(unpinAll(deps, { agent: invocation.agent }));
+          } catch (error) {
+            return failure(error, invocation.signal);
+          }
+        })(),
+      ),
+  });
+
+  register({
+    name: 'bctest',
+    description: 'M1 实验：把最近几条历史换成一条摘要（默认只预览，confirm 才执行）',
+    // 必须声明 input：DSH 客户端只让「声明了 input」的命令接受带参数的行，
+    // 否则 `/bctest confirm` 会被当成普通消息发出去（matchEnter 里 bare=false → void 0）。
+    input: { hint: 'confirm' },
+    handler: (invocation) =>
+      track(
+        (async () => {
+          const raw = invocation.rawInput.trim();
+          if (raw !== '' && raw !== 'confirm') {
+            return { kind: 'error', text: '用法：/bctest（预览）或 /bctest confirm（真正执行）' };
+          }
+          try {
+            const outcome = await testCompact(deps, {
+              agent: invocation.agent,
+              signal: invocation.signal,
+              confirm: raw === 'confirm',
+              commandId: invocation.commandId,
+            });
+            return success(outcome);
+          } catch (error) {
+            return failure(error, invocation.signal);
+          }
+        })(),
+      ),
+  });
+}