dsh-loop-rescue 0.0.0-stage → 0.2.0

package/src/i18n.js

@@ -0,0 +1,64 @@
+/**
+ * 面向模型与用户的文案。默认中文；只有显式 `en` 才用英文。
+ * @module dsh-loop-rescue/i18n
+ */
+
+const ZH = {
+  blockName: (kind) => (kind === 'reasoning' ? '思考' : '正文'),
+  marker: (kind, chars) => `\n〔已删除 ${chars} 字重复${kind === 'reasoning' ? '思考' : '输出'}〕`,
+  // 续跑提示只把模型送回原任务，不要求它「总结收尾」，否则它会放弃进行中的工作。
+  resume: (kind, chars) =>
+    `上一步的${kind === 'reasoning' ? '思考' : '输出'}陷入了重复（约 ${chars} 字），已被截断并从上下文中删除。`
+    + '不要复述刚才的内容，也不要解释发生了什么。直接从上一个有效进展继续你原本的任务，下一步就是具体行动。',
+  resumeSummary: (kind, chars) => `已切除 ${chars} 字重复${kind === 'reasoning' ? '思考' : '输出'}并续跑`,
+  stall: (n) =>
+    `你已连续 ${n} 次只思考、没有任何输出或工具调用。停止空转：直接执行下一步具体操作。`,
+  stallSummary: (n) => `连续 ${n} 次仅思考无产出，已提示继续`,
+  exhausted: (n) =>
+    `循环救援已连续触发 ${n} 次，自动续跑已暂停。请检查任务是否卡在同一处，或换个思路再继续。`,
+  exhaustedSummary: (n) => `连续 ${n} 次截断循环，已暂停自动续跑`,
+}
+
+const EN = {
+  blockName: (kind) => (kind === 'reasoning' ? 'reasoning' : 'output'),
+  marker: (kind, chars) => `\n[${chars} chars of repeated ${kind === 'reasoning' ? 'reasoning' : 'output'} removed]`,
+  resume: (kind, chars) =>
+    `Your previous ${kind === 'reasoning' ? 'reasoning' : 'output'} fell into repetition (~${chars} chars); `
+    + 'it was cut off and removed from the context. Do not restate it or explain what happened. '
+    + 'Continue the original task from the last real progress; your next move is a concrete action.',
+  resumeSummary: (kind, chars) => `removed ${chars} chars of repeated ${kind} and resumed`,
+  stall: (n) =>
+    `You have made ${n} consecutive calls that only reasoned, with no output or tool call. `
+    + 'Stop deliberating and take the next concrete step.',
+  stallSummary: (n) => `${n} reasoning-only calls in a row; nudged to continue`,
+  exhausted: (n) =>
+    `Loop rescue fired ${n} times in a row, so automatic resume is paused. `
+    + 'Check whether the task is stuck at the same point, or try a different approach.',
+  exhaustedSummary: (n) => `${n} loop cuts in a row; auto-resume paused`,
+}
+
+/**
+ * @param {'zh' | 'en'} lang
+ * @returns {typeof ZH}
+ */
+export function strings(lang) {
+  return lang === 'en' ? EN : ZH
+}
+
+/**
+ * 读取界面语言。设置服务可选：用 `ctx.get` 读取，缺失或出错一律回退中文。
+ * @param {any} ctx
+ * @param {'auto' | 'zh' | 'en'} preference 配置里的语言
+ * @returns {'zh' | 'en'}
+ */
+export function resolveLanguage(ctx, preference) {
+  if (preference === 'zh' || preference === 'en') return preference
+  try {
+    const settings = ctx.get?.('settings')
+    const section = settings?.get?.('locale')
+    const pref = section?.preference
+    return typeof pref === 'string' && pref.toLowerCase().startsWith('en') ? 'en' : 'zh'
+  } catch {
+    return 'zh'
+  }
+}

package/src/index.js

@@ -0,0 +1,259 @@
+/**
+ * dsh-loop-rescue：在模型陷入重复时切断流，把循环部分从落盘内容里剪掉，再自动续跑。
+ *
+ * ## 为什么能「剪掉」而不只是「截断」
+ *
+ * agent-loop 组装 `assistant/message` 时，每个 block 的最终内容取自 `block-end`
+ * 的载荷，而不是之前累计的 delta。所以在 `llm/stream` 瀑布里切断时，只要给出
+ * 剪过的 `block-end`，落盘的消息（下一轮发给模型的上下文）里就不会有循环部分。
+ * 不需要事后改写会话，也不会和会话面的 replace 规则冲突
+ * （`assistant/message` 不能携带 `sourceEventSeqs`，因此无法用 replace 改写）。
+ * 原始流仍完整保存在事件的 `stream` 记录里，轨迹视图可以看到全部内容。
+ *
+ * ## 流程
+ *
+ * 1. 包装每次 agent-loop 发起的模型调用，对每个推理/正文 block 单独跑检测器；
+ * 2. 命中后：闭合所有打开的 block（循环所在 block 换成剪过的内容），以 `stop` 结束流；
+ * 3. 在 yield 终止 chunk 之前同步拿到 `whenIdle()`，等回合真正结束后用
+ *    `followup()` 发一条带纠正语的续跑消息（运行中发出的唤醒会被宿主丢弃）；
+ * 4. 续跑的前 N 次请求可选地改用另一组采样参数（temperature / 推理强度）；
+ * 5. 连续救援达到上限就停止续跑，留一条提示等用户处理。
+ *
+ * 打开的 block 里有工具调用时不切：闭合半截工具调用会让宿主执行参数不完整的调用。
+ *
+ * @module dsh-loop-rescue
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage, isAgentLoopRequest } from '@deepseek-ai/dsh-llm'
+import { DEFAULTS, StreamLoopDetector } from './detector.js'
+import { resolveLanguage, strings } from './i18n.js'
+
+export { DEFAULTS, StreamLoopDetector, detectInText, normalizeUnit } from './detector.js'
+
+export const name = 'loop-rescue'
+
+/** 通过 `ctx.agents.get(sessionId)` 找到会话的 Agent，必须声明，否则激活即失败。 */
+export const inject = ['agents']
+
+const detectorSchema = z.object({
+  poolWindow: z.natural().min(8).default(DEFAULTS.poolWindow).description('短句池：参与判定的最近句子数'),
+  poolMaxMeanChars: z.natural().min(8).default(DEFAULTS.poolMaxMeanChars).description('短句池：句子平均长度上限（汉字按 3 计）'),
+  poolMinChars: z.natural().default(DEFAULTS.poolMinChars).description('短句池：窗口总长度下限'),
+  poolMinRepeats: z.natural().min(2).default(DEFAULTS.poolMinRepeats).description('短句池：出现几次算反复'),
+  poolMinCoverage: z.number().min(0).max(1).default(DEFAULTS.poolMinCoverage).description('短句池：反复句子的占比下限'),
+  poolGapAllowance: z.natural().default(DEFAULTS.poolGapAllowance).description('回溯循环起点时允许夹杂的新句子数'),
+  cycleMinPeriod: z.natural().min(4).default(DEFAULTS.cycleMinPeriod).description('逐字周期：最短周期'),
+  cycleMaxPeriod: z.natural().min(16).default(DEFAULTS.cycleMaxPeriod).description('逐字周期：最长周期'),
+  cycleMinChars: z.natural().min(64).default(DEFAULTS.cycleMinChars).description('逐字周期：重复部分总长下限'),
+  cycleMinReps: z.natural().min(2).default(DEFAULTS.cycleMinReps).description('逐字周期：至少重复几遍'),
+  cycleCheckEvery: z.natural().min(16).default(DEFAULTS.cycleCheckEvery).description('逐字周期：检查间隔（字符）'),
+})
+
+export const Config = z.object({
+  mode: z.union(['rescue', 'cut', 'observe']).default('rescue')
+    .description('rescue：切断+剪除+自动续跑；cut：切断+剪除，不续跑；observe：只记日志'),
+  watch: z.union(['both', 'reasoning', 'text']).default('both').description('检测哪类内容'),
+  marker: z.boolean().default(true).description('在剪除处留一行标记，让模型知道这里删过东西'),
+  maxConsecutiveRescues: z.natural().min(1).default(3)
+    .description('连续救援上限；中间出现一次正常调用就清零'),
+  stallCalls: z.natural().default(3)
+    .description('连续多少次「只思考无产出」的调用后提示继续；0 关闭'),
+  stallMinReasoningChars: z.natural().default(1024).description('计入空转的单次推理最小长度'),
+  retryTemperature: z.number().min(0).max(2).description('续跑请求改用的 temperature；不填则不改'),
+  retryReasoningEffort: z.string().description('续跑请求改用的推理强度 ID（如 low）；不填则不改'),
+  retryRequests: z.natural().default(1).description('续跑后多少次请求使用上面的参数'),
+  language: z.union(['auto', 'zh', 'en']).default('auto').description('提示语言；auto 跟随界面'),
+  detector: detectorSchema.default({}),
+})
+
+const SOURCE = { kind: 'loop-rescue' }
+
+/**
+ * 构造一条插件来源的 notice 消息。
+ * @param {string} text
+ * @param {string} summary 聊天区折叠行显示的一句话（宿主限 120 字）
+ */
+function notice(text, summary) {
+  return createUserMessage({
+    content: [{ type: 'text', text }],
+    source: { ...SOURCE, form: 'notice', summary: summary.slice(0, 120) },
+  })
+}
+
+/**
+ * @typedef {object} RescueState
+ * @property {number} consecutive 连续救援次数
+ * @property {number} stall 连续空转调用次数
+ * @property {number} overrides 剩余需要改采样参数的请求数
+ * @property {number} generation 每次救援自增；续跑前比较，判断期间是否已有新调用
+ */
+
+/**
+ * @param {any} ctx
+ * @param {any} config
+ */
+export function apply(ctx, config) {
+  /** @type {WeakMap<object, RescueState>} */
+  const states = new WeakMap()
+  const stateOf = (agent) => {
+    let s = states.get(agent)
+    if (s === undefined) {
+      s = { consecutive: 0, stall: 0, overrides: 0, generation: 0 }
+      states.set(agent, s)
+    }
+    return s
+  }
+  const lang = () => resolveLanguage(ctx, config.language)
+  const watches = (kind) => config.watch === 'both' || config.watch === kind
+
+  /**
+   * 回合结束后续跑。必须在 yield 终止 chunk 之前调用，拿到的 `whenIdle()` 才对应本回合。
+   * 期间若已有新的模型调用（用户发话、别的插件唤醒），本次续跑作废。
+   */
+  function scheduleFollowup(agent, state, message) {
+    if (typeof agent.whenIdle !== 'function' || typeof agent.followup !== 'function') return
+    const generation = state.generation
+    const idle = agent.whenIdle()
+    void Promise.resolve(idle).then(() => {
+      if (state.generation !== generation) return
+      if (agent.inbox?.hasPending) return
+      agent.followup(message)
+      ctx.logger.debug('loop-rescue: resumed after cut')
+    }).catch((error) => {
+      ctx.logger.warn(`loop-rescue: resume failed: ${String(error)}`)
+    })
+  }
+
+  ctx.on('llm/stream', (options, next) => {
+    if (!isAgentLoopRequest(options) || options.sessionId === undefined) return next()
+    const agent = ctx.agents.get(options.sessionId)
+    if (agent === undefined) return next()
+    const state = stateOf(agent)
+    // 新调用开始：之前排队的续跑作废。
+    state.generation++
+
+    return (async function* rescued() {
+      /** @type {Map<number, {blockType: string, text: string, detector?: StreamLoopDetector}>} */
+      const open = new Map()
+      let reasoningChars = 0
+      let hasOutput = false
+      let finished = false
+
+      for await (const chunk of next()) {
+        if (chunk.type === 'block-start') {
+          const kind = chunk.blockType
+          const detector = (kind === 'reasoning' || kind === 'text') && watches(kind)
+            ? new StreamLoopDetector(kind, config.detector)
+            : undefined
+          open.set(chunk.index, { blockType: kind, text: '', detector })
+        } else if (chunk.type === 'block-end') {
+          open.delete(chunk.index)
+        } else if (chunk.type === 'tool-call-delta') {
+          hasOutput = true
+        } else if (chunk.type === 'finish') {
+          finished = true
+        }
+
+        let hit
+        let hitBlock
+        if (chunk.type === 'reasoning-delta' || chunk.type === 'text-delta') {
+          if (chunk.type === 'text-delta') hasOutput = true
+          else reasoningChars += chunk.text.length
+          const block = open.get(chunk.index)
+          if (block !== undefined) {
+            block.text += chunk.text
+            hit = block.detector?.push(chunk.text)
+            if (hit !== undefined) hitBlock = { index: chunk.index, ...block }
+          }
+        }
+
+        if (hit === undefined) {
+          yield chunk
+          continue
+        }
+
+        const kind = hitBlock.blockType
+        ctx.logger.warn(`loop-rescue: ${kind} loop detected (rule ${hit.rule}, ${hit.repeatedChars} chars)`)
+        if (config.mode === 'observe') {
+          hitBlock.detector = undefined
+          const live = open.get(hitBlock.index)
+          if (live) live.detector = undefined
+          yield chunk
+          continue
+        }
+        // 半截工具调用不能闭合，放弃本次切断，继续透传。
+        if ([...open.values()].some((b) => b.blockType !== 'text' && b.blockType !== 'reasoning')) {
+          ctx.logger.warn('loop-rescue: a non-text block is open; not cutting')
+          const live = open.get(hitBlock.index)
+          if (live) live.detector = undefined
+          yield chunk
+          continue
+        }
+
+        const s = strings(lang())
+        state.consecutive++
+        state.stall = 0
+        // 先不 yield 当前 chunk：它的内容已在 block.text 里，剪切按累计文本进行。
+        const tail = []
+        for (const [index, block] of open) {
+          let text = block.text
+          if (index === hitBlock.index) {
+            text = text.slice(0, hit.cut).replace(/\s+$/, '')
+            if (config.marker) text += s.marker(kind, hit.repeatedChars)
+          }
+          tail.push({ type: 'block-end', index, block: { type: block.blockType, text } })
+        }
+        tail.push({ type: 'finish', reason: { kind: 'stop' } })
+
+        if (config.mode === 'rescue') {
+          if (state.consecutive > config.maxConsecutiveRescues) {
+            ctx.logger.warn(`loop-rescue: ${state.consecutive} consecutive cuts; auto-resume paused`)
+            agent.inject?.(notice(s.exhausted(state.consecutive), s.exhaustedSummary(state.consecutive)))
+          } else {
+            state.overrides = config.retryRequests
+            scheduleFollowup(agent, state,
+              notice(s.resume(kind, hit.repeatedChars), s.resumeSummary(kind, hit.repeatedChars)))
+          }
+        }
+        for (const c of tail) yield c
+        return
+      }
+
+      // 流自然结束。
+      if (!finished) return
+      if (hasOutput) {
+        state.consecutive = 0
+        state.stall = 0
+        return
+      }
+      // 只有推理、没有正文和工具调用：空转计数。
+      if (config.stallCalls > 0 && reasoningChars >= config.stallMinReasoningChars && config.mode === 'rescue') {
+        state.stall++
+        if (state.stall >= config.stallCalls) {
+          const s = strings(lang())
+          const n = state.stall
+          state.stall = 0
+          ctx.logger.warn(`loop-rescue: ${n} reasoning-only calls in a row`)
+          scheduleFollowup(agent, state, notice(s.stall(n), s.stallSummary(n)))
+        }
+      }
+    })()
+  })
+
+  // 续跑请求可选地换一组采样参数，打破同一前缀下的确定性复读。
+  ctx.on('agent/request', async (payload, next) => {
+    const resolved = await next()
+    const agent = payload?.agent
+    if (agent === undefined) return resolved
+    const state = states.get(agent)
+    if (state === undefined || state.overrides <= 0) return resolved
+    state.overrides--
+    const patch = {}
+    if (config.retryTemperature !== undefined) patch.temperature = config.retryTemperature
+    if (config.retryReasoningEffort) patch.reasoningEffort = config.retryReasoningEffort
+    return Object.keys(patch).length === 0 ? resolved : { ...resolved, ...patch }
+  })
+}
+
+export default { name, inject, Config, apply }

package/tools/clean-session.cmd

@@ -0,0 +1,4 @@
+@echo off
+rem Double-click to run, or drag a session folder onto this file
+node "%~dp0clean-session.mjs" %*
+pause

package/tools/clean-session.mjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * 离线清洗：把 DSH 会话历史里已经提交的循环截掉，让「已经嗝屁」的会话重新可用。
+ *
+ * 为什么是离线脚本：DSH 发给模型的请求是会话日志的纯投影且被冻结，插件只能读不能改；
+ * 所以只能在 DSH 关闭时直接改会话文件。检测规则与插件同一份（../src/detector.js），
+ * 只看已提交文本，没装过插件的老会话同样适用。
+ *
+ * 用法（不需要会话 ID）：
+ *   node tools/clean-session.mjs                 自动找 DSH 数据目录，列出有循环的会话，按序号选
+ *   node tools/clean-session.mjs --all           列表里也显示没有循环的会话
+ *   node tools/clean-session.mjs --data D:\dsh-desktop\data
+ *   node tools/clean-session.mjs <会话文件夹或文件>  直接处理这一个（可把文件夹拖到命令行）
+ *   node tools/clean-session.mjs --undo          从备份恢复（同样按序号选）
+ *   选项：--dry-run 只看不改；--yes 不再确认；--force 检测到 DSH 在运行也继续（不推荐）
+ *
+ * 改动内容（只动命中的 assistant/message 事件，其余行逐字节保留）：
+ *   - message.content 里命中的 text/reasoning 块截到循环起点；
+ *   - data.stream 里同一块的增量记录与 block-end 同步截断；
+ *   - 删掉该消息的 source.replayState（里面存着原文副本，留着会被原样重放）。
+ * 原文件先备份到 <data>/sessions-loop-rescue-backup/，再以带校验的 zstd 原子写回。
+ *
+ * 需要 Node 22.15+（内置 zstd）。不依赖 @deepseek-ai/*。
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync, renameSync, copyFileSync } from 'node:fs'
+import { join, resolve, dirname, basename, relative } from 'node:path'
+import { homedir } from 'node:os'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import * as zlib from 'node:zlib'
+import { detectInText } from '../src/detector.js'
+import { decodeLog, encodeLog } from './zstd-log.mjs'
+
+const argv = process.argv.slice(2)
+const flag = (n) => argv.includes(n)
+const opt = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : undefined }
+const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--data')
+const DRY = flag('--dry-run'), YES = flag('--yes'), FORCE = flag('--force'), ALL = flag('--all'), UNDO = flag('--undo')
+const GEN = /^session\.v(\d+)\.jsonl(\.zstd)?$/
+const BACKUP_DIR = 'sessions-loop-rescue-backup'
+
+const rl = createInterface({ input: process.stdin, output: process.stdout })
+const ask = async (q) => (await rl.question(q)).trim()
+const die = (m) => { console.error(m); rl.close(); process.exit(1) }
+
+// ---------- 读写 ----------
+function readSession(path) {
+  try { return decodeLog(readFileSync(path)) } catch (e) { die(e.message) }
+}
+function writeSession(path, text) {
+  const out = encodeLog(text, path.endsWith('.zstd'))
+  const tmp = `${path}.loop-rescue-tmp`
+  writeFileSync(tmp, out)
+  renameSync(tmp, path)
+}
+/** 会话文件夹里版本号最高的那一代日志。 */
+function latestGeneration(dir) {
+  let best
+  for (const f of readdirSync(dir)) {
+    const m = GEN.exec(f)
+    if (m && (!best || Number(m[1]) > best.v)) best = { v: Number(m[1]), path: join(dir, f) }
+  }
+  return best
+}
+
+// ---------- 找数据目录 ----------
+function findDataRoots() {
+  const given = opt('--data') ?? process.env.DSH_DATA
+  if (given) return [resolve(given)]
+  const roots = new Set()
+  // 1) 脚本放在数据目录里面时，向上找
+  for (let d = dirname(fileURLToPath(import.meta.url)); ; d = dirname(d)) {
+    if (existsSync(join(d, 'sessions'))) roots.add(d)
+    if (existsSync(join(d, 'data', 'sessions'))) roots.add(join(d, 'data'))
+    if (dirname(d) === d) break
+  }
+  // 2) 常见位置
+  const cands = []
+  if (process.platform === 'win32') {
+    for (const drive of 'CDEFG') for (const n of ['dsh-desktop', 'dsh-portable', 'dsh']) cands.push(`${drive}:\\${n}\\data`)
+    if (process.env.APPDATA) cands.push(join(process.env.APPDATA, 'dsh'), join(process.env.APPDATA, 'dsh-desktop'))
+    if (process.env.LOCALAPPDATA) cands.push(join(process.env.LOCALAPPDATA, 'dsh'), join(process.env.LOCALAPPDATA, 'dsh-desktop'))
+  }
+  cands.push(join(homedir(), '.dsh'), join(homedir(), '.config', 'dsh'), join(homedir(), '.local', 'share', 'dsh'))
+  for (const c of cands) if (existsSync(join(c, 'sessions'))) roots.add(resolve(c))
+  return [...roots]
+}
+
+// ---------- DSH 是否在运行 ----------
+function dshRunning() {
+  try {
+    const out = process.platform === 'win32'
+      ? execFileSync('tasklist', ['/fo', 'csv', '/nh'], { encoding: 'utf8', timeout: 10000 })
+      : execFileSync('ps', ['-eo', 'comm='], { encoding: 'utf8', timeout: 10000 })
+    return out.split(/\r?\n/).map((l) => l.replace(/^"|".*$/g, '')).filter((n) => /\bdsh/i.test(n) && !/loop-rescue/i.test(n))
+  } catch { return [] }
+}
+
+// ---------- 分析一个会话 ----------
+function analyze(path) {
+  const text = readSession(path)
+  const lines = text.split('\n')
+  let header, title, last = 0, loops = 0
+  const hits = [] // {line, blocks:[{idx, cut}]}
+  lines.forEach((line, li) => {
+    if (!line.trim()) return
+    let ev
+    try { ev = JSON.parse(line) } catch { return }
+    if (ev.type === 'session' && header === undefined) header = ev
+    if (typeof ev.time === 'number') last = Math.max(last, ev.time)
+    if (ev.type === 'session/title') title = ev.data?.title
+    if (ev.type !== 'assistant/message') return
+    const blocks = []
+    ;(ev.data?.message?.content ?? []).forEach((b, idx) => {
+      if (b.type !== 'text' && b.type !== 'reasoning') return
+      const d = detectInText(b.type, b.text ?? '')
+      if (d) blocks.push({ idx, cut: d.cut, removed: (b.text ?? '').length - d.cut })
+    })
+    if (blocks.length) { hits.push({ line: li, blocks }); loops += blocks.length }
+  })
+  return { path, text, lines, header, title, last, loops, hits }
+}
+
+/** 截断一条消息事件，返回新事件。 */
+function trimEvent(ev, blocks) {
+  const content = ev.data.message.content
+  const cutByIndex = new Map()
+  for (const { idx, cut } of blocks) {
+    const b = content[idx]
+    b.text = b.text.slice(0, cut).replace(/\s+$/, '')
+    cutByIndex.set(idx, b.text)
+  }
+  // stream：截断对应块的增量与 block-end
+  if (Array.isArray(ev.data.stream)) {
+    const posByIdx = new Map()
+    // content 下标与流里的 block index 一一对应（同序），按出现顺序映射
+    const streamIdx = []
+    for (const r of ev.data.stream) {
+      if (r.type === 'chunk' && r.chunk?.type === 'block-start') streamIdx.push(r.chunk.index)
+    }
+    const map = new Map() // stream index -> kept text
+    for (const [ci, kept] of cutByIndex) if (streamIdx[ci] !== undefined) map.set(streamIdx[ci], kept)
+    ev.data.stream = ev.data.stream.map((r) => {
+      if ((r.type === 'text-chunks' || r.type === 'reasoning-chunks') && map.has(r.index)) {
+        const kept = map.get(r.index)
+        let used = posByIdx.get(r.index) ?? 0
+        const texts = [], dt = []
+        for (let i = 0; i < r.texts.length && used < kept.length; i++) {
+          const piece = r.texts[i].slice(0, kept.length - used)
+          texts.push(piece); used += piece.length
+          if (i > 0) dt.push(r.dt[i - 1])
+        }
+        posByIdx.set(r.index, used)
+        if (texts.length === 0) return null
+        return { ...r, texts, dt }
+      }
+      if (r.type === 'chunk' && r.chunk?.type === 'block-end' && map.has(r.chunk.index)) {
+        return { ...r, chunk: { ...r.chunk, block: { ...r.chunk.block, text: map.get(r.chunk.index) } } }
+      }
+      return r
+    }).filter(Boolean)
+  }
+  const src = ev.data.message.source
+  if (src && src.replayState !== undefined) {
+    const { replayState, ...rest } = src
+    ev.data.message.source = rest
+  }
+  return ev
+}
+
+// ---------- 列表与选择 ----------
+function listSessions(roots) {
+  const out = []
+  for (const root of roots) {
+    const sdir = join(root, 'sessions')
+    for (const proj of safeDir(sdir)) {
+      const pdir = join(sdir, proj)
+      if (!statSync(pdir).isDirectory()) continue
+      for (const s of safeDir(pdir)) {
+        const dir = join(pdir, s)
+        if (!statSync(dir).isDirectory()) continue
+        const g = latestGeneration(dir)
+        if (!g) continue
+        try { out.push({ root, gen: g, ...analyze(g.path) }) } catch (e) { console.error(`跳过 ${dir}：${e.message}`) }
+      }
+    }
+  }
+  return out.sort((a, b) => b.last - a.last)
+}
+function safeDir(d) { try { return readdirSync(d) } catch { return [] } }
+const fmtTime = (t) => (t ? new Date(t).toLocaleString('zh-CN', { hour12: false }) : '?')
+
+async function pick(items, render, prompt) {
+  items.forEach((it, i) => console.log(`${String(i + 1).padStart(3)}. ${render(it)}`))
+  const a = await ask(prompt)
+  if (a === '') return items[0]
+  const n = Number(a)
+  if (!Number.isInteger(n) || n < 1 || n > items.length) die('没有这个序号，已退出。')
+  return items[n - 1]
+}
+
+// ---------- 主流程 ----------
+async function main() {
+  // 撤销
+  if (UNDO) {
+    const roots = findDataRoots()
+    const backups = []
+    for (const root of roots) collectBackups(join(root, BACKUP_DIR), root, backups)
+    if (!backups.length) die('没有找到备份。')
+    backups.sort((a, b) => b.mtime - a.mtime)
+    const b = await pick(backups, (x) => `${fmtTime(x.mtime)}  ${x.target}`, '恢复哪个？（回车=最新）')
+    guardRunning()
+    if (!YES && (await ask(`用备份覆盖 ${b.target}？[y/N] `)).toLowerCase() !== 'y') die('已取消。')
+    copyFileSync(b.path, b.target)
+    console.log('已恢复。')
+    return rl.close()
+  }
+
+  let session
+  if (positional[0]) {
+    const p = resolve(positional[0])
+    const file = statSync(p).isDirectory() ? latestGeneration(p)?.path : p
+    if (!file) die(`${p} 里没有会话日志。`)
+    // 推断数据目录：…/data/sessions/<项目>/<会话>/file
+    const root = dirname(dirname(dirname(dirname(file))))
+    session = { root, gen: { path: file, v: Number(GEN.exec(basename(file))?.[1] ?? 0) }, ...analyze(file) }
+  } else {
+    const roots = findDataRoots()
+    if (!roots.length) die('没找到 DSH 数据目录。用 --data 指定，例如：--data D:\\dsh-desktop\\data')
+    console.log(`扫描：${roots.map((r) => join(r, 'sessions')).join('，')}\n`)
+    let list = listSessions(roots)
+    if (!ALL) list = list.filter((s) => s.loops > 0)
+    if (!list.length) { console.log(ALL ? '没有会话。' : '没有发现带循环的会话。加 --all 可看全部。'); return rl.close() }
+    session = await pick(list, (s) => {
+      const sub = s.header?.origin === 'subagent' ? '[子] ' : ''
+      return `${fmtTime(s.last)}  ${sub}${s.title ?? '(无标题)'}  —  ${s.header?.cwd ?? '?'}  循环 ${s.loops} 段`
+    }, '\n选哪个？（回车=第一个）')
+  }
+
+  if (session.loops === 0) { console.log('这个会话里没有检测到循环。'); return rl.close() }
+  if (session.gen.v !== 4) die(`目前只支持 v4 会话，这个是 v${session.gen.v}。`)
+
+  const removed = session.hits.reduce((s, h) => s + h.blocks.reduce((t, b) => t + b.removed, 0), 0)
+  console.log(`\n${session.title ?? ''}\n  文件：${session.path}\n  将截断 ${session.loops} 段循环（${session.hits.length} 条消息），删除约 ${removed} 字。`)
+  for (const h of session.hits.slice(0, 3)) {
+    const ev = JSON.parse(session.lines[h.line])
+    const b = ev.data.message.content[h.blocks[0].idx]
+    console.log(`  · 第 ${ev.data.turn} 轮：…${b.text.slice(Math.max(0, h.blocks[0].cut - 60), h.blocks[0].cut).replace(/\s+/g, ' ')} ✂ ${b.text.slice(h.blocks[0].cut, h.blocks[0].cut + 40).replace(/\s+/g, ' ')}…`)
+  }
+  if (DRY) { console.log('\n--dry-run：未做任何修改。'); return rl.close() }
+
+  guardRunning()
+  if (!YES && (await ask('\n确认修改？会先自动备份。[y/N] ')).toLowerCase() !== 'y') die('已取消。')
+
+  // 备份
+  const rel = relative(join(session.root, 'sessions'), session.path)
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const bak = rel.startsWith('..') ? `${session.path}.${stamp}.bak` : join(session.root, BACKUP_DIR, `${rel}.${stamp}`)
+  mkdirSync(dirname(bak), { recursive: true })
+  copyFileSync(session.path, bak)
+
+  // 改写
+  const lines = session.lines.slice()
+  for (const h of session.hits) lines[h.line] = JSON.stringify(trimEvent(JSON.parse(lines[h.line]), h.blocks))
+  const text = lines.join('\n')
+  // 自检：重新读回不应再有循环、事件数不变
+  const check = text.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l))
+  if (check.length !== session.lines.filter((l) => l.trim()).length) die('自检失败：事件数变化，未写入。')
+  writeSession(session.path, text)
+  const after = analyze(session.path)
+  console.log(`\n完成。剩余循环 ${after.loops} 段。备份：${bak}\n撤销：node tools/clean-session.mjs --undo`)
+  rl.close()
+}
+
+function collectBackups(dir, root, out) {
+  for (const e of safeDir(dir)) {
+    const p = join(dir, e)
+    const st = statSync(p)
+    if (st.isDirectory()) collectBackups(p, root, out)
+    else {
+      const m = /^(.*)\.\d{4}-\d{2}-\d{2}T[\d-]+Z$/.exec(p)
+      if (m) out.push({ path: p, mtime: st.mtimeMs, target: join(root, 'sessions', relative(join(root, BACKUP_DIR), m[1])) })
+    }
+  }
+}
+
+function guardRunning() {
+  const procs = dshRunning()
+  if (procs.length && !FORCE) die(`检测到 DSH 正在运行（${[...new Set(procs)].join('、')}）。请先完全退出 DSH 再运行；确定无关可加 --force。`)
+}
+
+main().catch((e) => die(e.stack ?? String(e)))