@raolin2025/claude-code-node 2.8.3 → 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` 命令用法
 
@@ -544,8 +551,18 @@ cc-notify 是独立的通知守护进程，**不需要 cc-node 在前台运行**
 /notify 任务完成！       → 通过 Telegram 广播通知
 /status                  → 查看服务状态
 /cancel                  → 取消当前操作
+/help                    → 查看完整帮助（含 AI 编程命令）
+/model gpt-4o            → 切换模型
+/window 128k             → 设置上下文窗口
+/budget                  → 查看 token 预算
+/compact                 → 压缩上下文
+/clear                   → 清空对话
 ```
 
+> 除上述系统命令外，所有 `/help` 列出的 AI 编程命令（`/model`、`/window`、`/budget`、
+> `/compact`、`/clear`、`/sessions`、`/config`、`/cost`、`/cd`、`/tools`、`/stop`、`/allow`
+> 等）都会自动转发给 cc-node 处理，结果回发到 Telegram。`/help <命令>` 可查看详细用法。
+
 ### HTTP API（守护模式可用）
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.8.3",
+  "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/channel/tg-listener.js

@@ -316,15 +316,33 @@ export class TelegramListener {
     this.running = true
     log(`[TG] Starting long polling...`)
 
-    // 设置命令菜单
+    // 设置命令菜单（Telegram 输入框 / 提示，最多 100 个命令）
     try {
       await this.bot.setMyCommands([
+        // —— 系统命令（本进程处理）——
         { command: 'ping', description: '🏓 检查服务状态' },
         { command: 'status', description: '📊 查看 cc-node 状态' },
         { command: 'run', description: '💻 执行 shell 命令（如 /run ls -la）' },
         { command: 'notify', description: '📢 广播通知消息' },
-        { command: 'help', description: '❓ 查看帮助' },
         { command: 'cancel', description: '🚫 取消当前操作' },
+        { command: 'help', description: '❓ 查看帮助' },
+        // —— AI 编程命令（转发给 cc-node）——
+        { command: 'model', description: '🤖 切换模型（如 /model gpt-4o）' },
+        { command: 'models', description: '📋 列出可用模型' },
+        { command: 'window', description: '🧠 查看/设置上下文窗口（如 /window 128k）' },
+        { command: 'budget', description: '💰 查看 token 预算使用' },
+        { command: 'compact', description: '🗜️ 手动压缩上下文' },
+        { command: 'clear', description: '🧹 清空当前对话' },
+        { command: 'session', description: '🗂️ 查看会话信息' },
+        { command: 'sessions', description: '📂 列出所有会话' },
+        { command: 'resume', description: '↩️ 恢复会话（/resume <id>）' },
+        { command: 'config', description: '⚙️ 查看配置（/config model）' },
+        { command: 'cost', description: '💲 查看 API 费用' },
+        { command: 'channel', description: '🔔 管理通知通道' },
+        { command: 'cd', description: '📁 切换工作目录' },
+        { command: 'tools', description: '🛠️ 列出可用工具' },
+        { command: 'stop', description: '⏹️ 停止当前 AI 任务' },
+        { command: 'allow', description: '🔓 工具权限管理' },
       ])
     } catch {}
 
@@ -536,9 +554,13 @@ export class TelegramListener {
 
     switch (cmd) {
       case '/start':
-      case '/help':
         return this._helpText()
 
+      case '/help':
+        // 无参数 → 返回完整帮助；带参数（/help <cmd>）→ 转发给 cc-node 输出详细用法
+        if (!args) return this._helpText()
+        return null // 交由 cli.js processInputLine 处理 /help <cmd> 详细帮助
+
       case '/ping':
         return '🏓 pong! cc-notify is alive.'
 
@@ -592,25 +614,45 @@ export class TelegramListener {
     }
   }
 
-  /** 生成帮助文本 */
+  /** 生成帮助文本（含 cc-notify 系统命令 + cc-node AI 编程命令） */
   _helpText() {
     return [
       '🤖 *cc-notify — AI Code Agent*',
       '',
       '通过 Telegram 远程操控 AI 编程助手。',
+      '直接发消息 → AI 处理；发 / 开头命令 → 执行对应操作。',
       '',
-      '*命令*',
+      '*🔧 系统命令*',
       '• `/ping` — 检查服务状态',
       '• `/status` — 查看详细状态',
       '• `/run <cmd>` — 直接执行 shell 命令',
       '• `/notify <msg>` — 广播通知到所有通道',
       '• `/cancel` — 取消当前操作',
-      '• `/help` — 显示帮助',
+      '',
+      '*🤖 AI 编程命令*（转发给 cc-node 处理）',
+      '• `/model NAME` — 切换模型（如 /model gpt-4o）',
+      '• `/models` — 列出可用模型',
+      '• `/window [N]` — 查看/设置上下文窗口（/window 128k、/window auto）',
+      '• `/budget` — 查看 token 预算使用',
+      '• `/compact` — 手动压缩上下文',
+      '• `/clear` — 清空当前对话',
+      '• `/session` — 查看会话信息',
+      '• `/sessions` — 列出所有会话',
+      '• `/resume <id>` — 恢复历史会话',
+      '• `/config KEY` — 查看配置（如 /config model）',
+      '• `/cost` — 查看 API 费用',
+      '• `/channel` — 管理通知通道',
+      '• `/cd PATH` — 切换工作目录',
+      '• `/tools` — 列出可用工具',
+      '• `/stop` — 停止当前 AI 任务',
+      '• `/allow` — 工具权限管理',
       '',
       '*普通消息*',
-      '直接发送文字消息 → 自动发给 AI 处理',
+      '直接发送文字 → 自动发给 AI 处理',
       '支持发送图片（AI 无法看图，但会作为附件）',
       '',
+      '💡 任意 `/help <命令>` 查看某个命令的详细用法。',
+      '',
     ].join('\n')
   }
 

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)