@raolin2025/claude-code-node 2.8.18 → 2.8.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.8.18",
+  "version": "2.8.20",
   "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__/small-model.test.js

@@ -20,6 +20,7 @@ import {
   isSmallModelEnabled,
   buildMultiStepPlan,
   buildCombinedGuidance,
+  extractFrameworkAction,
 } from '../core/small-model.js'
 
 // ---- 敷衍输出检测 ----
@@ -227,6 +228,27 @@ test('max_tokens：绝不超过窗口一半（防超窗）', async () => {
   assert.ok(qe2._computeMaxOutputTokens() <= 5000, `max_tokens=${qe2._computeMaxOutputTokens()} 不应超过窗口一半 5000`)
 })
 
+// ---- 框架代执行（extractFrameworkAction）----
+test('框架代执行：识别"阅读+绝对路径"任务为 Read', () => {
+  const a = extractFrameworkAction('阅读D:\\workspace\\miniQMT-trader\\COMPLETION_REPORT.md', {
+    cwd: 'D:\\workspace\\miniQMT-trader',
+  })
+  assert.ok(a, '应识别到框架动作')
+  assert.equal(a.tool, 'Read')
+  assert.equal(a.input.file_path, 'D:\\workspace\\miniQMT-trader\\COMPLETION_REPORT.md')
+})
+
+test('框架代执行：相对路径拼接 cwd', () => {
+  const a = extractFrameworkAction('查看一下 ./PLAN.md', { cwd: 'D:\\workspace\\miniQMT-trader' })
+  assert.ok(a && a.tool === 'Read')
+  assert.equal(a.input.file_path, 'D:\\workspace\\miniQMT-trader\\PLAN.md')
+})
+
+test('框架代执行：非读取任务或无路径返回 null', () => {
+  assert.equal(extractFrameworkAction('你好', { cwd: 'D:\\x' }), null)
+  assert.equal(extractFrameworkAction('运行测试', { cwd: 'D:\\x' }), null)
+})
+
 // ---- _buildRequest 把 system 统一前置（防 llama.cpp 500）----
 test('_buildRequest：把中间 system 统一前置到开头', async () => {
   const { QueryEngine } = await import('../core/query-engine.js')

package/src/core/cli.js

@@ -333,6 +333,7 @@ function parseArgs(argv) {
     maxMessages: 0,
     smallModel: false,
     maxOutputTokens: 0,
+    smallModelMaxTurns: 0,
   }
 
   let i = 2
@@ -351,6 +352,7 @@ function parseArgs(argv) {
       case '--max-messages': args.maxMessages = parseInt(argv[++i], 10); break
       case '--small-model': args.smallModel = true; break
       case '--max-output-tokens': args.maxOutputTokens = parseInt(argv[++i], 10); break
+      case '--small-model-max-turns': args.smallModelMaxTurns = parseInt(argv[++i], 10); break
       case '--stdio': args.stdio = true; break
       case '--with-notify': args.withNotify = true; break
       case '--version':
@@ -374,6 +376,7 @@ Options:
   --max-messages N          Fold history when message count exceeds N (default: 0 = off)
   --small-model             Enable small-model adaptation (tool-call enforcement, filler retry, intent guidance)
   --max-output-tokens N     Override max single-response output tokens (default: computed from window size)
+  --small-model-max-turns N Small-model tool-loop cap (default: 8, prevents infinite loops)
   --with-notify             Start built-in channel listener (Telegram)
                             (replaces cc-notify daemon — no external script needed)
   -h, --help                Show this help
@@ -540,6 +543,8 @@ const systemPrompt = cliArgs.systemPrompt || DEFAULT_SYSTEM_PROMPT
     smallModel: cliArgs.smallModel || config.get('smallModel') || false,
     // 单次输出上限覆盖（默认根据窗口动态计算）
     maxOutputTokens: cliArgs.maxOutputTokens || config.get('maxOutputTokens') || 0,
+    // 小模型工具循环轮数上限（默认 8，防无限循环）
+    smallModelMaxTurns: cliArgs.smallModelMaxTurns || config.get('smallModelMaxTurns') || 0,
   })
   const engine = new QueryEngine(engineConfig)
 

package/src/core/query-engine.js

@@ -22,6 +22,7 @@ import {
   buildCombinedGuidance,
   selectRelevantTools,
   RETRY_GUIDANCE,
+  extractFrameworkAction,
 } from './small-model.js'
 import { CostTracker } from './cost-tracker.js'
 import { EnhancedPermissionChecker } from '../security/enhanced-permission.js'
@@ -53,6 +54,9 @@ export class QueryEngineConfig {
     //   - 工具数量精简 + 意图引导
     // 默认关闭，通过 config.smallModel=true 或 --small-model 开启
     this.smallModel = options.smallModel || false
+    // 小模型模式下的工具循环轮数上限（默认 8）：
+    // 小模型常陷入"写一个又写一个"的无限工具循环，需更小的上限 + 收尾引导
+    this.smallModelMaxTurns = options.smallModelMaxTurns || 8
     // 单次输出上限动态计算：
     //   outputRatio — 输出占窗口比例（默认 1/16），窗口越大输出越大
     //   maxOutputTokens — 输出下限（默认 4096），也可作为硬性覆盖
@@ -228,8 +232,14 @@ export class QueryEngine {
     // 敷衍重试次数（层 A）：模型没调工具只回空话时，追加强引导重试
     let fillerRetries = 0
     const MAX_FILLER_RETRIES = 1
-
-    for (let turn = 0; turn < this.config.maxTurns; turn++) {
+    // 工具循环轮数上限：
+    //   - 小模型模式：用更小的上限（默认 8），避免模型陷入"写一个又写一个"的无限循环
+    //   - 普通模式：用 config.maxTurns
+    const toolLoopLimit = smallModel
+      ? (this.config.smallModelMaxTurns || 8)
+      : this.config.maxTurns
+
+    for (let turn = 0; turn < toolLoopLimit; turn++) {
       // 发送前硬校验：工具结果可能已使上下文超窗，确保 ≤ 窗口（摘要优先 + 滑动窗口裁剪兜底）
       this._ensureFitWindow()
 
@@ -259,6 +269,22 @@ export class QueryEngine {
         intentGuided = true
       }
 
+      // 小模型模式：接近工具循环上限时，注入"总结收尾"引导，防止模型无限循环
+      if (smallModel && turn === toolLoopLimit - 1) {
+        const stopGuidance = `[系统提示] 你已经完成了大部分工作。现在请【停止调用新工具】，把已经完成的内容整理成一段总结回复给用户。如果确实还有关键步骤未完成，只再调用一次工具完成它，然后立即总结。不要再继续无休止地调用工具。`
+        const sysIdx = this.state.messages.findIndex(m => m.role === 'system')
+        if (sysIdx !== -1) {
+          const sysMsg = this.state.messages[sysIdx]
+          this.state.messages[sysIdx] = {
+            ...sysMsg,
+            content: (typeof sysMsg.content === 'string' ? sysMsg.content : '') + '\n\n' + stopGuidance,
+          }
+        } else {
+          this.state.messages.push({ role: 'user', content: stopGuidance })
+        }
+        if (this.config.verbose) console.error(`[small-model] 已到工具循环第 ${turn + 1} 轮（上限 ${toolLoopLimit}），注入收尾引导`)
+      }
+
       const requestMessages = this._buildRequest(this.state.messages)
       const response = await this._callLLM(requestMessages, this.state.messages)
 
@@ -268,16 +294,25 @@ export class QueryEngine {
 
       // 没有工具调用 → 潜在最终回复
       if (!response.toolCalls || response.toolCalls.length === 0) {
-        // 小模型模式：检测敷衍输出（空话/太短/命中占位句），追加强引导重试
-        if (smallModel && fillerRetries < MAX_FILLER_RETRIES && isFillerResponse(response)) {
-          fillerRetries++
-          if (this.config.verbose) {
-            console.error(`[small-model] 检测到敷衍输出（第 ${fillerRetries} 次），追加强引导重试`)
+        // 小模型模式：检测敷衍输出（空话/太短/命中占位句）
+        if (smallModel && isFillerResponse(response)) {
+          // 第一次敷衍 → 追加强引导重试
+          if (fillerRetries < MAX_FILLER_RETRIES) {
+            fillerRetries++
+            if (this.config.verbose) {
+              console.error(`[small-model] 检测到敷衍输出（第 ${fillerRetries} 次），追加强引导重试`)
+            }
+            this.state.messages.push(new AssistantMessage(response.content, [], response.reasoningContent))
+            this.state.messages.push({ role: 'user', content: RETRY_GUIDANCE })
+            continue
+          }
+          // 重试后仍敷衍 → 框架代执行（不依赖模型调工具）
+          const execResult = await this._frameworkExecute(userMessage.content)
+          if (execResult.done) {
+            if (this.config.verbose) console.error(`[small-model] 框架代执行：${execResult.summary}`)
+            // 框架已执行工具并把结果注入对话，继续循环让模型基于结果总结
+            continue
           }
-          // 把模型的空话 + 强制工具调用提醒注入上下文，再让模型重新决策
-          this.state.messages.push(new AssistantMessage(response.content, [], response.reasoningContent))
-          this.state.messages.push({ role: 'user', content: RETRY_GUIDANCE })
-          continue // 继续循环，重新请求模型
         }
 
         finalResponse = response.content
@@ -306,8 +341,9 @@ export class QueryEngine {
       }
     }
 
-    if (!finalResponse && this.state.turnCount >= this.config.maxTurns) {
-      finalResponse = `[达到最大回合数限制 (${this.config.maxTurns})，停止响应]`
+    // 工具循环达到上限但仍未收尾（模型一直调用工具）→ 强制收尾
+    if (!finalResponse) {
+      finalResponse = `[已达到工具循环上限 (${toolLoopLimit})，已停止进一步调用工具。请查看上方工具执行结果，确认任务完成情况。]`
     }
 
     return {
@@ -473,6 +509,47 @@ export class QueryEngine {
     return results
   }
 
+  /**
+   * 框架代执行 — 模型敷衍调不起工具时，框架直接替它执行最合理的工具
+   *
+   * 背景：27B Q3 量化模型工具调用极弱，即使强引导也常只回"研究一下"而不调工具。
+   * 此时框架【绕过模型】，根据指令推断该执行什么工具并直接运行，把真实结果
+   * 注入对话，再让模型基于结果总结——"一句话调用小模型工作"才能成立。
+   *
+   * @param {string} userInput — 用户指令
+   * @returns {Promise<{ done: boolean, summary: string }>}
+   *          done=true 表示框架已执行工具（结果已注入 state.messages）
+   */
+  async _frameworkExecute(userInput) {
+    const action = extractFrameworkAction(userInput, { cwd: this.config.cwd })
+    if (!action) return { done: false, summary: '' }
+
+    // 找到对应的工具
+    const tool = this.config.tools.find(t => t.name === action.tool)
+    if (!tool) return { done: false, summary: '' }
+
+    // 执行工具（直接调用 handler）
+    try {
+      const content = await tool.handler(action.input, { cwd: this.config.cwd, engine: this, readline: this.config.readline })
+
+      // 注入框架代执行结果（作为 user 消息，避免 tool 消息无对应 assistant tool_call 报错）
+      // 说明：框架代执行不是模型发起的工具调用，不能作为 tool 角色（会缺 assistant tool_call），
+      // 因此以 user 消息承载真实结果 + 引导模型基于结果总结。
+      const resultText = typeof content === 'string' ? content : JSON.stringify(content)
+      this.state.messages.push({
+        role: 'user',
+        content: `[框架代执行结果] 框架已替你执行工具 ${tool.name}（参数 ${JSON.stringify(action.input)}），结果如下：\n\n${resultText.slice(0, 8000)}\n\n请基于以上【真实执行结果】，用中文直接回答用户的问题或总结内容。不要再调用工具，直接总结即可。`,
+      })
+
+      const summary = `框架已代执行 ${tool.name}(${JSON.stringify(action.input)})`
+      if (this.config.verbose) console.error(`[small-model] 框架代执行 ${tool.name} 完成`)
+      return { done: true, summary }
+    } catch (err) {
+      if (this.config.verbose) console.error(`[small-model] 框架代执行失败: ${err.message}`)
+      return { done: false, summary: '' }
+    }
+  }
+
   async _callLLM(messages, contextMessages) {
     const apiKey = this.config.apiKey
     const apiBase = this.config.apiBase

package/src/core/small-model.js

@@ -233,6 +233,48 @@ export function buildIntentGuidance(userInput, opts = {}) {
   return `[任务引导] 根据用户指令，建议按此思路用工具推进：${intent.intent}。\n说明：${intent.note}\n可用工具：${intent.toolHint}`
 }
 
+/**
+ * 框架代执行：从用户指令里推断"框架该替模型执行哪个工具动作"
+ *
+ * 背景：27B Q3 量化模型工具调用能力极弱，即使有最强引导也常只回"研究一下"等
+ * 空话而不调工具。此时框架必须【绕过模型】，根据指令直接替它执行最合理的工具，
+ * 把真实结果注入对话，再让模型基于结果总结。
+ *
+ * 当前支持（按优先级）：
+ *   1. 读取文件：指令里含文件路径 + 阅读/查看/打开等动词 → Read(path)
+ *
+ * 后续可扩展：写文件、跑命令、搜索等。
+ *
+ * @param {string} userInput — 用户指令
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] — 当前工作目录（用于解析相对路径）
+ * @returns {{ tool: string, input: object, toolName: string } | null}
+ *          tool = 'Read'/'Write' 等工具名；input 为工具参数；toolName 为展示名
+ */
+export function extractFrameworkAction(userInput, opts = {}) {
+  if (!userInput) return null
+  const cwd = opts.cwd || ''
+
+  // 1. 读取文件任务：含路径 + 读/查看/打开
+  //    匹配绝对路径（Windows: D:\... 或 /... 或 ./...）或文件名
+  const readIntent = /(读|阅读|查看|打开|展示|显示|看看|浏览|看)/i.test(userInput)
+  // 提取路径：优先 Windows 绝对路径 D:\...、Unix /...、相对 ./ 或 ../，或 .md/.txt/.py/.json 文件
+  const pathMatch = userInput.match(/([A-Za-z]:\\[^\s，。；]+|(?:\/|\/\/)[^\s，。；]+|\.{1,2}\/[^\s，。；]+|[\w@.-]+\.(?:md|txt|py|json|log|yaml|yml|toml|ini|cfg|csv|xml))+/i)
+
+  if (readIntent && pathMatch) {
+    let filePath = pathMatch[1].trim()
+    // 去掉开头的 ./ 或 ../
+    filePath = filePath.replace(/^\.\.?[\\/]/, '')
+    // 若是相对路径且给了 cwd，拼成绝对路径
+    if (!/^[A-Za-z]:\\/.test(filePath) && !filePath.startsWith('/') && cwd) {
+      filePath = cwd.replace(/[\\/]+$/, '') + '\\' + filePath
+    }
+    return { tool: 'Read', toolName: 'Read', input: { file_path: filePath } }
+  }
+
+  return null
+}
+
 // 常见计划文档文件名（供多步拆解时定位计划文件）
 const PLAN_FILE_CANDIDATES = [
   'DEVELOPMENT_PLAN.md',