@raolin2025/claude-code-node 2.8.4 → 2.8.5

package/README.md

@@ -134,12 +134,19 @@ cc-node 会自动感知当前所用模型的**上下文窗口长度**，并在
 > 探测结果**不落盘**，每次启动重新探测；只有 `/window N` 手动指定才会持久化（方案 A）。
 > 探测不精确时，用 `/window N` 手动纠正即可。
 
-### 自动压缩机制
+### 自动压缩机制（滑动窗口）
 
-- 当已用 token 达到窗口的 **80%** 时自动触发压缩（`autoCompact`）。
-- 压缩策略：保留最近 4 轮完整对话，早期历史压缩为摘要（用户意图、用到的工具、关键结果），
-  并将过长工具结果截断，目标压到窗口的 60%。
-- **发送前硬校验**：每次发请求前估算消息量，超窗先压缩再发，作为最终兜底保险。
+上下文**永不超出窗口**，采用"摘要优先 + 滑动窗口裁剪兜底"的双层策略：
+
+1. **摘要式压缩**（信息量更高）：当已用 token 达到窗口 **80%** 时，把早期对话压缩为摘要
+   （保留最近 4 轮 + 用户意图/工具/关键结果），目标压到窗口的 60%。
+2. **滑动窗口精确裁剪**（兜底，保证永不超窗）：每次新消息加入 / 工具结果返回 / 发送前，
+   若上下文仍超窗，则从**最早的消息**逐条挤出，**最新信息始终保留在末尾**，直到总 token
+   ≤ 窗口上限。system 提示永不裁剪；极端情况（单条消息超窗）仍保留 system + 最近一条，
+   保证至少能发出请求。
+
+> 正是这个滑动窗口机制解决了"上下文满了之后新信息无法输入"的问题——窗口满时自动
+> 挤出最早的对话，让最新消息总能拼接进去。
 
 ### `/window` 命令用法
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.8.4",
+  "version": "2.8.5",
   "description": "Node.js AI Code Agent CLI - Zero dependencies, pure JavaScript, security hardened, multi-channel notifications, Telegram & QQ Bot remote programming, rich media upload, multi-account management",
   "type": "module",
   "main": "src/core/index.js",

package/src/__tests__/compact-window.test.js

@@ -0,0 +1,115 @@
+/**
+ * 滑动窗口裁剪 (trimToWindow) 测试
+ *
+ * 验证核心滑动窗口语义：
+ *   - 未超窗不动；
+ *   - 超窗时从【最早】消息精确裁剪（最新信息保留在末尾）；
+ *   - system 提示永不裁剪；
+ *   - 极端情况（单条消息超窗）仍保留 system + 最近一条；
+ *   - 裁剪后总 token 一定 ≤ 窗口上限。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { trimToWindow, compactMessages } from '../core/compact.js'
+import { TokenBudget } from '../core/token-budget.js'
+
+/** 构造一个固定窗口的 TokenBudget */
+function makeBudget(maxTokens, reservedForOutput = 10) {
+  return new TokenBudget({ maxTokens, reservedForOutput })
+}
+
+/** 构造消息：system + n 轮 user/assistant */
+function makeMessages(n, { pad = 10, sysContent = 'SYS' } = {}) {
+  const msgs = [{ role: 'system', content: sysContent }]
+  for (let i = 0; i < n; i++) {
+    msgs.push({ role: 'user', content: `user msg ${i}` + ' '.repeat(pad) })
+    msgs.push({ role: 'assistant', content: `assistant reply ${i}` + ' '.repeat(pad) })
+  }
+  return msgs
+}
+
+test('滑动窗口：未超窗时消息原样保留', () => {
+  const tb = makeBudget(10000)
+  const msgs = makeMessages(2)
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  assert.equal(r.trimmed, false)
+  assert.equal(r.removed, 0)
+  assert.equal(r.messages.length, msgs.length)
+})
+
+test('滑动窗口：超窗时从最早消息精确裁剪', () => {
+  const tb = makeBudget(100)
+  const msgs = makeMessages(10) // 21 条
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  assert.equal(r.trimmed, true)
+  assert.ok(r.removed > 0)
+  // 裁剪后总 token ≤ 窗口上限（减去输出预留）
+  assert.ok(tb.estimateMessages(r.messages) <= tb.maxTokens - tb.reservedForOutput)
+  // 消息数变少
+  assert.ok(r.messages.length < msgs.length)
+})
+
+test('滑动窗口：最新消息始终保留在末尾', () => {
+  const tb = makeBudget(100)
+  const msgs = makeMessages(10)
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  const last = r.messages[r.messages.length - 1]
+  assert.equal(last.role, 'assistant')
+  assert.ok(last.content.includes('assistant reply 9'), '最后一条应为最新回复')
+})
+
+test('滑动窗口：system 提示永不裁剪', () => {
+  const tb = makeBudget(100)
+  const msgs = makeMessages(10)
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  assert.equal(r.messages[0].role, 'system')
+  assert.equal(r.messages[0].content, 'SYS')
+})
+
+test('滑动窗口：裁剪后保留最近连续对话（无空洞）', () => {
+  const tb = makeBudget(100)
+  const msgs = makeMessages(10)
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  // 检查裁剪后 body 部分是连续的 user/assistant 对
+  const body = r.messages.slice(1) // 去掉 system
+  for (let i = 0; i < body.length; i++) {
+    if (i % 2 === 0) assert.equal(body[i].role, 'user', `第 ${i} 条应为 user`)
+    else assert.equal(body[i].role, 'assistant', `第 ${i} 条应为 assistant`)
+  }
+})
+
+test('滑动窗口：极端情况（单条消息超窗）仍保留 system + 最近一条', () => {
+  const tb = makeBudget(50) // 窗口很小
+  // 构造：每条消息都较大，导致任何单条都可能超窗
+  const msgs = [
+    { role: 'system', content: 'SYS' },
+    { role: 'user', content: 'a'.repeat(100) },
+    { role: 'assistant', content: 'b'.repeat(100) },
+  ]
+  const r = trimToWindow(msgs, { tokenBudget: tb, maxTokens: tb.maxTokens })
+  // 至少保留 system + 最后一条
+  assert.equal(r.messages[0].role, 'system')
+  assert.ok(r.messages.length >= 2)
+  assert.equal(r.messages[r.messages.length - 1].content, 'b'.repeat(100))
+})
+
+test('滑动窗口：自动估算（无 tokenBudget 时用 estimateTokens）', () => {
+  const msgs = makeMessages(10, { pad: 50 })
+  const r = trimToWindow(msgs, { maxTokens: 50 })
+  // 没有 tokenBudget，用内置 estimateTokens，仍能裁剪
+  assert.equal(r.trimmed, true)
+  assert.ok(r.messages.length < msgs.length)
+  // system 保留
+  assert.equal(r.messages[0].role, 'system')
+})
+
+test('摘要式压缩 compactMessages 仍可用（信息量更高路径）', () => {
+  const tb = makeBudget(200, 0)
+  const msgs = makeMessages(8, { pad: 30 })
+  const r = compactMessages(msgs, { maxTokens: 120 })
+  // 摘要式：保留最近 4 轮 + 早期摘要
+  assert.ok(r.length > 0)
+  assert.ok(r.length < msgs.length, '摘要应减少消息数')
+  // 摘要作为 system 上下文插入
+  assert.equal(r[0].role, 'system')
+})

package/src/core/compact.js

@@ -169,3 +169,71 @@ export function autoCompact(messages, tokenBudget, options = {}) {
 
   return { compacted: false, messages }
 }
+
+/**
+ * 滑动窗口裁剪 — 保证上下文永不超出窗口
+ *
+ * 与摘要式压缩（compactMessages）不同，本函数采用"精确裁剪"：
+ *   1. 计算当前消息总 token；
+ *   2. 若超出窗口上限，从【最早】的消息逐条裁剪（最新信息始终保留在末尾）；
+ *   3. 直到总 token ≤ 窗口，保证新信息能拼接到末尾。
+ *
+ * 约束：
+ *   - system 提示（首条 system 消息）永不裁剪，作为稳定上下文保留；
+ *   - 极端情况（单条非 system 消息就超窗）：仍保留 system + 最近的一条，
+ *     其余裁剪，保证至少能发出请求（宁可截断信息也不报错/无法输入）。
+ *
+ * @param {Array} messages — 完整消息列表
+ * @param {object} options
+ * @param {number} options.maxTokens — 窗口上限（token）
+ * @param {number} options.reservedForOutput — 为输出预留的 token（默认 8192）
+ * @param {object} options.tokenBudget — 可选的 TokenBudget 实例（用其 estimateMessages）
+ * @returns {{ trimmed: boolean, messages: Array, removed: number }}
+ */
+export function trimToWindow(messages, options = {}) {
+  const budget = options.tokenBudget
+  const maxTokens = options.maxTokens || 160_000
+  const reservedForOutput = options.reservedForOutput || (budget ? budget.reservedForOutput : 8192)
+  const limit = maxTokens - reservedForOutput
+
+  const estimate = (msgs) => budget
+    ? budget.estimateMessages(msgs)
+    : estimateTokens(msgs.map(m => typeof m.content === 'string' ? m.content : JSON.stringify(m.content)).join(''))
+
+  // 先计算总 token
+  let total = estimate(messages)
+  if (total <= limit) {
+    return { trimmed: false, messages, removed: 0 }
+  }
+
+  // 分离 system 提示（首条 system 永不裁剪）与普通消息
+  const systemMsgs = []
+  const body = []
+  for (const m of messages) {
+    if (m.role === 'system' && systemMsgs.length === 0) {
+      systemMsgs.push(m)
+    } else {
+      body.push(m)
+    }
+  }
+
+  // 从头部逐条裁剪（最新信息保留在末尾），直到 ≤ 上限
+  let removed = 0
+  while (body.length > 0) {
+    // 极端保护：至少保留最后一条非 system 消息（system + 最近 1 条总能发出去）
+    if (body.length === 1) break
+    body.shift() // 挤掉最早的消息
+    removed++
+    total = estimate([...systemMsgs, ...body])
+    if (total <= limit) break
+  }
+
+  const result = [...systemMsgs, ...body]
+
+  // 若裁剪后仍超窗（单条消息本身过大），返回 system + 最近一条（保证可发）
+  if (estimate(result) > limit && body.length === 1) {
+    return { trimmed: removed > 0, messages: result, removed }
+  }
+
+  return { trimmed: removed > 0, messages: result, removed }
+}

package/src/core/query-engine.js

@@ -14,7 +14,7 @@
 import crypto from 'crypto'
 import { UserMessage, AssistantMessage, ToolCall, ToolResult, SessionState } from '../types/index.js'
 import { parseStream, parseNonStreamResponse } from './streaming.js'
-import { autoCompact } from './compact.js'
+import { autoCompact, trimToWindow } from './compact.js'
 import { CostTracker } from './cost-tracker.js'
 import { EnhancedPermissionChecker } from '../security/enhanced-permission.js'
 import { isLocalLlmServer, buildAuthHeaders } from '../utils/index.js'
@@ -85,14 +85,9 @@ export class QueryEngine {
     const userMsg = new UserMessage(userInput, images)
     this.state.messages.push(userMsg)
 
-    // M3: 自动上下文压缩
-    if (this.tokenBudget) {
-      const { compacted, messages } = autoCompact(this.state.messages, this.tokenBudget)
-      if (compacted) {
-        this.state.messages = messages
-        if (this.config.verbose) console.error('[compact] Context compressed to fit token budget')
-      }
-    }
+    // M3: 自动上下文压缩 + 滑动窗口兜底
+    // 新消息已 push，确保上下文 ≤ 窗口（摘要优先，超窗则从最早消息精确裁剪）
+    this._ensureFitWindow()
 
     try {
       const result = await this._runToolLoop(userMsg)
@@ -102,6 +97,46 @@ export class QueryEngine {
     }
   }
 
+  /**
+   * 确保上下文 ≤ 窗口（滑动窗口语义）
+   *
+   * 处理顺序：
+   *   1. 估算当前消息总 token；
+   *   2. 若未超窗 → 不做任何事；
+   *   3. 若超窗 → 先尝试摘要式压缩（保留最近 N 轮 + 早期摘要，信息量更高）；
+   *   4. 摘要后仍超窗（或摘要未触发）→ 滑动窗口精确裁剪：从最早消息挤出，
+   *      保证最新信息（含刚加入的用户消息）保留在末尾，上下文永不超出窗口。
+   */
+  _ensureFitWindow() {
+    if (!this.tokenBudget) return
+    const limit = this.tokenBudget.maxTokens - this.tokenBudget.reservedForOutput
+    const est = this.tokenBudget.estimateMessages(this.state.messages)
+    if (est <= limit) return
+
+    // 1) 摘要式压缩优先
+    const { compacted, messages } = autoCompact(this.state.messages, this.tokenBudget, {
+      maxTokens: Math.floor(this.tokenBudget.maxTokens * 0.6),
+    })
+    if (compacted) {
+      const reEst = this.tokenBudget.estimateMessages(messages)
+      if (reEst <= limit) {
+        this.state.messages = messages
+        if (this.config.verbose) console.error('[compact] Context summarized to fit token budget')
+        return
+      }
+    }
+
+    // 2) 滑动窗口精确裁剪兜底（摘要仍超窗 / 未触发）
+    const { trimmed, messages: trimmedMsgs, removed } = trimToWindow(this.state.messages, {
+      tokenBudget: this.tokenBudget,
+      maxTokens: this.tokenBudget.maxTokens,
+    })
+    if (trimmed) {
+      this.state.messages = trimmedMsgs
+      if (this.config.verbose) console.error(`[compact] Sliding-window trimmed ${removed} oldest messages to fit window`)
+    }
+  }
+
   /**
    * 工具调用循环 — 核心逻辑
    *
@@ -112,19 +147,8 @@ export class QueryEngine {
     let finalResponse = ''
 
     for (let turn = 0; turn < this.config.maxTurns; turn++) {
-      // 发送前硬校验：估算即将发送的消息是否超出窗口，超限则先压缩（最终兜底，防止溢出）
-      if (this.tokenBudget) {
-        const est = this.tokenBudget.estimateMessages(this.state.messages)
-        if (est > this.tokenBudget.maxTokens - this.tokenBudget.reservedForOutput) {
-          const { compacted, messages } = autoCompact(this.state.messages, this.tokenBudget, {
-            maxTokens: Math.floor(this.tokenBudget.maxTokens * 0.6),
-          })
-          if (compacted) {
-            this.state.messages = messages
-            if (this.config.verbose) console.error('[compact] Pre-send hard check: compressed to stay within window')
-          }
-        }
-      }
+      // 发送前硬校验：工具结果可能已使上下文超窗，确保 ≤ 窗口（摘要优先 + 滑动窗口裁剪兜底）
+      this._ensureFitWindow()
 
       const requestMessages = this._buildRequest(this.state.messages)
       const response = await this._callLLM(requestMessages, this.state.messages)