@raolin2025/claude-code-node 2.8.12 → 2.8.14

package/README.md

@@ -68,6 +68,7 @@ cc-node --resume session-1747000000000-abc123
 | `--verbose` | `-v` | 详细输出 | `false` |
 | `--no-stream` | | 禁用流式响应 | `false` |
 | `--max-messages` | | 消息条数上限，超过则折叠早期历史为摘要（解决本地小模型"条数过多变傻"） | `0`（关闭） |
+| `--small-model` | | 小模型适配模式（强制工具调用 + 敷衍重试 + 意图引导 + 工具精简） | `false` |
 | `--stdio` | | **JSON-RPC 服务器模式**（供桥接层/外部客户端接入，见下） | |
 | `--help` | `-h` | 显示帮助 | |
 
@@ -176,6 +177,29 @@ cc-node 会自动感知当前所用模型的**上下文窗口长度**，并在
 
 > 切换模型（`/model`）后会自动重新探测窗口。`/budget` 也会显示当前窗口与 80% 触发阈值。
 
+### 🤖 小模型适配模式（--small-model）
+
+> 专为 **本地小模型**（如 27B Q3 量化）设计，让编程工具在弱模型下也能可靠工作。
+> 默认关闭，通过 `--small-model` 或 `config.smallModel=true` 开启。
+
+小模型的核心弱点是"规划 + 工具调用 + 自我纠错"不稳定——常只回 `Solved by sharing best practices.`
+这类空话、不调工具，或多轮往返后"丢"了目标。该模式把智能从"模型端"转移到"框架端"：
+
+| 层 | 机制 | 作用 |
+|----|------|------|
+| **A · 兜底** | 强化 system prompt | 明确告诉模型"必须调用工具完成任务，不能只回文字" |
+| **A · 兜底** | 敷衍输出检测 + 重试 | 检测到空话/太短/无工具调用时，追加强引导重试一次 |
+| **A · 兜底** | 工具数量精简 | 按用户指令意图只暴露核心工具子集，降低选择负担 |
+| **B · 替代** | 意图识别 + 引导 | 用规则把"写文档/找文件/跑命令/改代码"映射到明确工具，注入任务引导 |
+
+```bash
+cc-node --api-base http://127.0.0.1:18080/v1 --model ./local-model.gguf \
+  --with-notify --small-model --max-messages 80
+```
+
+> **配合 `--max-messages N`**：两者互补——`--max-messages` 解决"条数过多"，
+> `--small-model` 解决"模型不会自主调工具"。小模型场景建议一起开启。
+
 ---
 
 ## 🛠️ 内置工具（10 个）
@@ -341,6 +365,7 @@ cc-node --api-base http://localhost:11434/v1
   "maxTurns": 100,
   "maxBudgetTokens": 128000,
   "maxMessages": 80,
+  "smallModel": true,
   "permissionMode": "ask",
   "tools": {
     "bash": { "timeout": 120 },
@@ -360,6 +385,10 @@ cc-node --api-base http://localhost:11434/v1
 > **`maxMessages`**：消息条数上限（可选，默认关闭/`0`）。当上下文消息条数超过该值时，
 > 自动折叠早期历史为摘要（保留 Main goal + 最近 4 轮完整对话），解决本地小模型
 > "条数过多、token 不高却变傻"的问题。等价于 `--max-messages N`。
+>
+> **`smallModel`**：小模型适配模式（可选，默认关闭/`false`）。开启后启用强制工具调用
+> 引导、敷衍输出检测重试、意图识别 + 工具精简，让弱模型（如 27B Q3 量化）也能可靠
+> 完成编程任务。等价于 `--small-model`。
 
 [![npm version](https://img.shields.io/npm/v/@raolin2025/claude-code-node.svg)](https://www.npmjs.com/package/@raolin2025/claude-code-node) [![GitHub](https://img.shields.io/badge/GitHub-bg1avd%2Fclaude--code--node-blue)](https://github.com/bg1avd/claude-code-node) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.8.12",
+  "version": "2.8.14",
   "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

@@ -0,0 +1,147 @@
+/**
+ * 小模型适配层 (small-model.js) 测试
+ *
+ * 验证：
+ *   - 敷衍输出检测（isFillerResponse）：空话/太短/命中占位句识别
+ *   - 意图识别（detectIntent）：写文件/找文件/跑命令/改代码等映射
+ *   - 意图引导（buildIntentGuidance）：生成注入的引导文本
+ *   - 工具精简（selectRelevantTools）：按意图筛选核心工具
+ *   - system prompt 强化（buildSmallModelSystemPrompt）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  isFillerResponse,
+  detectIntent,
+  buildIntentGuidance,
+  selectRelevantTools,
+  buildSmallModelSystemPrompt,
+  SMALL_MODEL_SYSTEM_PROMPT,
+  isSmallModelEnabled,
+} from '../core/small-model.js'
+
+// ---- 敷衍输出检测 ----
+test('敷衍检测：命中空话占位句', () => {
+  assert.equal(isFillerResponse({ content: 'Solved by sharing best practices.', toolCalls: [] }), true)
+  assert.equal(isFillerResponse({ content: 'Done. This is the kind of mistake that costs real money.', toolCalls: [] }), true)
+  assert.equal(isFillerResponse({ content: 'Let me think about this.', toolCalls: [] }), true)
+})
+
+test('敷衍检测：空回复/太短', () => {
+  assert.equal(isFillerResponse({ content: '', toolCalls: [] }), true)
+  assert.equal(isFillerResponse({ content: '  ', toolCalls: [] }), true)
+  assert.equal(isFillerResponse({ content: 'ok', toolCalls: [] }), true)
+  assert.equal(isFillerResponse({ content: '好的', toolCalls: [] }), true)
+})
+
+test('敷衍检测：有工具调用不算敷衍', () => {
+  assert.equal(isFillerResponse({ content: 'ok', toolCalls: [{ id: '1' }] }), false)
+})
+
+test('敷衍检测：正常实质回答不算敷衍', () => {
+  const content = '我已经分析了项目结构，发现3个主要模块需要重构，分别是订单、行情和风控模块，建议先处理订单模块。'
+  assert.equal(isFillerResponse({ content, toolCalls: [] }), false)
+})
+
+// ---- 意图识别 ----
+test('意图识别：写文档任务', () => {
+  const r = detectIntent('做好开发计划文档')
+  assert.ok(r, '应识别到意图')
+  assert.ok(r.toolHint.includes('Write'), '应提示用 Write 工具')
+  const r2 = detectIntent('把你的计划写入文档')
+  assert.ok(r2 && r2.toolHint.includes('Write'))
+})
+
+test('意图识别：阅读文档是读取任务（不误判为写）', () => {
+  const r = detectIntent('阅读DEVELOPMENT_PLAN.md文档')
+  assert.ok(r, '应识别到意图')
+  assert.ok(r.toolHint.includes('Read'), '应提示用 Read')
+  assert.ok(!r.toolHint.includes('Write'), '读取任务不应提示 Write')
+})
+
+test('意图识别：找文件任务', () => {
+  const r = detectIntent('查找src目录下的文件')
+  assert.ok(r && r.toolHint.includes('Glob'))
+  assert.ok(r.toolHint.includes('Grep'))
+})
+
+test('意图识别：跑命令任务', () => {
+  const r = detectIntent('运行一下测试')
+  assert.ok(r && r.toolHint.includes('Bash'))
+})
+
+test('意图识别：改代码任务', () => {
+  const r = detectIntent('修复这个bug')
+  assert.ok(r && r.toolHint.includes('Edit'))
+})
+
+test('意图识别：联网搜索任务', () => {
+  const r = detectIntent('搜索一下最新的量化交易资料')
+  assert.ok(r && r.toolHint.includes('WebSearch'))
+})
+
+test('意图识别：无匹配返回 null', () => {
+  assert.equal(detectIntent('你好'), null)
+  assert.equal(detectIntent(''), null)
+})
+
+// ---- 意图引导 ----
+test('意图引导：生成注入文本', () => {
+  const g = buildIntentGuidance('做好开发计划文档', { enable: true })
+  assert.ok(g, '应生成引导')
+  assert.ok(g.includes('Write'), '引导应包含工具建议')
+  assert.ok(g.includes('任务引导'), '应有引导标记')
+})
+
+test('意图引导：未启用或未匹配返回 null', () => {
+  assert.equal(buildIntentGuidance('做好开发计划文档', { enable: false }), null)
+  assert.equal(buildIntentGuidance('你好', { enable: true }), null)
+})
+
+// ---- 工具精简 ----
+const fakeTools = [
+  { name: 'Bash', description: 'd' },
+  { name: 'Read', description: 'd' },
+  { name: 'Edit', description: 'd' },
+  { name: 'Write', description: 'd' },
+  { name: 'Glob', description: 'd' },
+  { name: 'Grep', description: 'd' },
+  { name: 'WebSearch', description: 'd' },
+  { name: 'WebFetch', description: 'd' },
+  { name: 'GitTool', description: 'd' },
+  { name: 'NpmPublish', description: 'd' },
+]
+
+test('工具精简：按意图保留相关工具', () => {
+  const reduced = selectRelevantTools(fakeTools, '做好开发计划文档', { enable: true })
+  assert.ok(reduced.length < fakeTools.length, '应精简工具数量')
+  assert.ok(reduced.some(t => t.name === 'Write'), '应保留 Write')
+  // 不相关的如 NpmPublish 不应保留
+  assert.ok(!reduced.some(t => t.name === 'NpmPublish'), '不应保留无关工具')
+})
+
+test('工具精简：未启用返回全部', () => {
+  assert.equal(selectRelevantTools(fakeTools, 'xx', { enable: false }), fakeTools)
+})
+
+test('工具精简：无明确意图时返回核心文件工具', () => {
+  const reduced = selectRelevantTools(fakeTools, '你好', { enable: true })
+  assert.ok(reduced.length <= 6, '应只保留核心工具')
+  assert.ok(reduced.some(t => t.name === 'Bash'))
+})
+
+// ---- system prompt 强化 ----
+test('system prompt 强化：追加工具使用铁律', () => {
+  const base = 'You are cc-node.'
+  const enhanced = buildSmallModelSystemPrompt(base)
+  assert.ok(enhanced.includes(base), '应保留基础 prompt')
+  assert.ok(enhanced.includes('工具调用 Agent'), '应包含工具调用强化引导')
+  assert.ok(enhanced.includes(SMALL_MODEL_SYSTEM_PROMPT), '应追加强化 prompt')
+})
+
+// ---- 开关判断 ----
+test('小模型开关判断', () => {
+  assert.equal(isSmallModelEnabled({ smallModel: true }), true)
+  assert.equal(isSmallModelEnabled({ smallModel: false }), false)
+  assert.equal(isSmallModelEnabled(undefined), false)
+})

package/src/core/cli.js

@@ -331,6 +331,7 @@ function parseArgs(argv) {
     resume: null,
     noStream: false,
     maxMessages: 0,
+    smallModel: false,
   }
 
   let i = 2
@@ -347,6 +348,7 @@ function parseArgs(argv) {
       case '--verbose': case '-v': args.verbose = true; break
       case '--no-stream': args.noStream = true; break
       case '--max-messages': args.maxMessages = parseInt(argv[++i], 10); break
+      case '--small-model': args.smallModel = true; break
       case '--stdio': args.stdio = true; break
       case '--with-notify': args.withNotify = true; break
       case '--version':
@@ -368,6 +370,7 @@ Options:
   -v, --verbose             Verbose mode
   --no-stream               Disable streaming
   --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)
   --with-notify             Start built-in channel listener (Telegram)
                             (replaces cc-notify daemon — no external script needed)
   -h, --help                Show this help
@@ -530,6 +533,8 @@ const systemPrompt = cliArgs.systemPrompt || DEFAULT_SYSTEM_PROMPT
     configStore: config,
     // 消息条数上限（折叠早期历史，解决本地小模型"条数过多变傻"）；0 = 关闭
     maxMessages: cliArgs.maxMessages || config.get('maxMessages') || 0,
+    // 小模型适配模式（强制工具调用 + 敷衍重试 + 意图引导 + 工具精简）
+    smallModel: cliArgs.smallModel || config.get('smallModel') || false,
   })
   const engine = new QueryEngine(engineConfig)
 

package/src/core/query-engine.js

@@ -15,6 +15,14 @@ import crypto from 'crypto'
 import { UserMessage, AssistantMessage, ToolCall, ToolResult, SessionState } from '../types/index.js'
 import { parseStream, parseNonStreamResponse } from './streaming.js'
 import { compactMessages, trimToWindow, foldHistoryByCount, trimToolResults } from './compact.js'
+import {
+  isSmallModelEnabled,
+  buildSmallModelSystemPrompt,
+  isFillerResponse,
+  buildIntentGuidance,
+  selectRelevantTools,
+  RETRY_GUIDANCE,
+} from './small-model.js'
 import { CostTracker } from './cost-tracker.js'
 import { EnhancedPermissionChecker } from '../security/enhanced-permission.js'
 import { isLocalLlmServer, buildAuthHeaders } from '../utils/index.js'
@@ -39,6 +47,12 @@ export class QueryEngineConfig {
     this.maxMessages = options.maxMessages || 0
     // 发送前常驻工具结果截断长度（字符），防止超长工具结果堆积（0 表示不截断）
     this.maxToolResultChars = options.maxToolResultChars || 6000
+    // 小模型适配模式（让弱模型可靠工作）：
+    //   - 强化 system prompt（强制工具调用）
+    //   - 敷衍输出检测 + 重试
+    //   - 工具数量精简 + 意图引导
+    // 默认关闭，通过 config.smallModel=true 或 --small-model 开启
+    this.smallModel = options.smallModel || false
     this.permissionMode = options.permissionMode || 'ask'
     this.verbose = options.verbose || false
     // API 配置 — 通用 OpenAI 兼容协议
@@ -74,6 +88,8 @@ export class QueryEngine {
     this.tokenBudget = this.config.tokenBudget || null
     // 最近一次 processMessage 是否已通过流式回调/直写把正文输出（供调用方避免重复打印 response）
     this.lastStreamed = false
+    // 当前正在处理的用户输入（小模型模式用于按意图精简工具集）
+    this.currentUserInput = ''
   }
 
   /**
@@ -89,6 +105,7 @@ export class QueryEngine {
     this.state.turnCount++
     this.lastStreamed = false  // 本轮是否已流式输出正文
     this.abortController = new AbortController()
+    this.currentUserInput = userInput  // 记录当前用户指令（小模型模式按意图精简工具）
     const userMsg = new UserMessage(userInput, images)
     this.state.messages.push(userMsg)
 
@@ -200,11 +217,40 @@ export class QueryEngine {
    */
   async _runToolLoop(userMessage) {
     let finalResponse = ''
+    const smallModel = isSmallModelEnabled(this.config)
+    // 小模型模式：首轮注入意图引导（层 B），帮助模型锁定该用哪些工具
+    let intentGuided = false
+    // 敷衍重试次数（层 A）：模型没调工具只回空话时，追加强引导重试
+    let fillerRetries = 0
+    const MAX_FILLER_RETRIES = 1
 
     for (let turn = 0; turn < this.config.maxTurns; turn++) {
       // 发送前硬校验：工具结果可能已使上下文超窗，确保 ≤ 窗口（摘要优先 + 滑动窗口裁剪兜底）
       this._ensureFitWindow()
 
+      // 小模型模式：首轮若识别到明确意图，把引导【追加到首条 system 消息】。
+      // 注意：不能 push 一条新的 system 消息到中间——llama.cpp/Jinja 严格要求
+      // system 消息必须在对话开头，中间插 system 会报 "System message must be at the beginning" (500)。
+      if (smallModel && !intentGuided && this.state.messages.length > 0) {
+        const guidance = buildIntentGuidance(userMessage.content, { enable: true })
+        if (guidance) {
+          // 找到第一条 system 消息，把引导拼接进去（保持 system 全在开头）
+          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' + guidance,
+            }
+          } else {
+            // 没有 system 消息 → 作为 user 引导插入（跟随在最新 user 之后作为新 user）
+            this.state.messages.push({ role: 'user', content: guidance })
+          }
+          if (this.config.verbose) console.error('[small-model] 已注入意图引导（并入首条 system）：' + guidance.slice(0, 60) + '...')
+        }
+        intentGuided = true
+      }
+
       const requestMessages = this._buildRequest(this.state.messages)
       const response = await this._callLLM(requestMessages, this.state.messages)
 
@@ -212,8 +258,20 @@ export class QueryEngine {
         throw new Error('操作已取消')
       }
 
-      // 没有工具调用 → 最终回复
+      // 没有工具调用 → 潜在最终回复
       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} 次），追加强引导重试`)
+          }
+          // 把模型的空话 + 强制工具调用提醒注入上下文，再让模型重新决策
+          this.state.messages.push(new AssistantMessage(response.content, [], response.reasoningContent))
+          this.state.messages.push({ role: 'user', content: RETRY_GUIDANCE })
+          continue // 继续循环，重新请求模型
+        }
+
         finalResponse = response.content
         this.state.messages.push(new AssistantMessage(response.content, [], response.reasoningContent))
         break
@@ -257,9 +315,12 @@ export class QueryEngine {
   _buildRequest(messages) {
     const request = []
 
-    // 系统提示
+    // 系统提示（小模型模式：追加强制工具调用引导）
     if (this.config.systemPrompt) {
-      request.push({ role: 'system', content: this.config.systemPrompt })
+      const sysContent = isSmallModelEnabled(this.config)
+        ? buildSmallModelSystemPrompt(this.config.systemPrompt)
+        : this.config.systemPrompt
+      request.push({ role: 'system', content: sysContent })
     }
 
     // 历史消息 — 转换为 OpenAI 兼容格式
@@ -390,7 +451,16 @@ export class QueryEngine {
     }
 
     // 构建工具定义
-    const tools = this.config.tools.map(t => ({
+    // 小模型模式：按用户指令意图精简工具集，减少模型的选择负担（层 A）
+    let effectiveTools = this.config.tools
+    if (isSmallModelEnabled(this.config)) {
+      const reduced = selectRelevantTools(this.config.tools, this.currentUserInput, { enable: true })
+      effectiveTools = reduced
+      if (this.config.verbose && reduced.length !== this.config.tools.length) {
+        console.error(`[small-model] 按意图精简工具：${this.config.tools.length} → ${reduced.length}（${reduced.map(t => t.name).join(', ')}）`)
+      }
+    }
+    const tools = effectiveTools.map(t => ({
       type: 'function',
       function: { name: t.name, description: t.description, parameters: t.parameters },
     }))

package/src/core/small-model.js

@@ -0,0 +1,250 @@
+/**
+ * 小模型适配层 — 让 cc-node 在弱模型（如 27B Q3 量化）下也能可靠工作
+ *
+ * 背景：
+ *   小模型的核心弱点是"规划 + 工具调用 + 自我纠错"不稳定——常出现：
+ *     - 看不懂指令，只回 "Solved by sharing best practices." 等敷衍空话，不调工具；
+ *     - 一次请求里塞 16 个工具定义让它选择困难，乱调或漏调；
+ *     - 多轮工具往返后"丢"了原始目标。
+ *   本模块把智能从"模型端"转移到"框架端"，提供两层适配：
+ *
+ *   【层 A — 兜底（防呆）】：
+ *     - 强化 system prompt：明确告诉模型"必须调用工具完成任务，不能只回文字"；
+ *     - 敷衍输出检测：识别无工具调用 + 无实质内容的空话，返回需要重试的信号；
+ *     - 工具数量精简：按任务场景只暴露核心工具子集，减少选择负担。
+ *
+ *   【层 B — 替代（框架接管规划）】：
+ *     - 意图识别：用关键词规则把常见任务（写文件/找文件/跑命令/查代码）映射到
+ *       明确的工具动作，不完全依赖模型自主规划；
+ *     - 提供一个"计划"数据结构，框架可据此按序执行。
+ *
+ * 注意：本模块默认【不启用】。通过 config.smallModel=true 或 --small-model 开启。
+ */
+
+// ---- 敷衍/空话输出特征（层 A）----
+// 小模型在"没读懂、没调工具"时输出的占位句/空话模式。
+// 命中这些且【本轮无工具调用】时，判定为敷衍输出，触发重试。
+const FILLER_PATTERNS = [
+  /^\s*solved/i,
+  /^\s*done\b/i,
+  /by sharing best practices/i,
+  /this is the kind of mistake/i,
+  /next action/i,
+  /^\s*ok\b/i,
+  /^\s*okay\b/i,
+  /^\s*got it/i,
+  /^\s*understood/i,
+  /^\s*no problem/i,
+  /^\s*let me think/i,
+  /^\s*sure\b/i,
+  /^\s*yes\b/i,
+  /^\s*right\b/i,
+  /^\s*hmm/i,
+]
+
+// 有"实质内容"的最小长度（去掉空白/填充后）
+const MIN_SUBSTANTIVE_CHARS = 20
+
+/**
+ * 判断一次模型回复是否属于"敷衍输出"（无工具调用 + 空话/过短）
+ *
+ * 用途：小模型模式下，当模型没调工具却回了句空话时，判定为"没干活"，
+ *       触发框架重试（并在重试时追加强引导）。
+ *
+ * @param {object} response — _callLLM 的返回 { content, toolCalls, ... }
+ * @param {object} [opts]
+ * @param {number} [opts.minChars=20] — 判定"实质内容"的最小有效字符数
+ * @returns {boolean} true 表示敷衍输出（应重试）
+ */
+export function isFillerResponse(response, opts = {}) {
+  const minChars = opts.minChars || MIN_SUBSTANTIVE_CHARS
+  // 有工具调用 → 在干活，不是敷衍
+  if (response.toolCalls && response.toolCalls.length > 0) return false
+  const content = (response.content || '').trim()
+  if (!content) return true // 空回复 = 敷衍
+  // 去掉空白后的有效字符数
+  const substantive = content.replace(/\s+/g, '').replace(/[，。！？,.!?、；;：:]/g, '')
+  if (substantive.length < minChars) return true // 太短 = 敷衍
+  // 命中空话模式
+  for (const pat of FILLER_PATTERNS) {
+    if (pat.test(content)) return true
+  }
+  return false
+}
+
+// ---- 小模型强化 system prompt（层 A）----
+// 追加到基础 system prompt 之后的强工具引导。对小模型是决定性的：
+// 大模型能"猜"到要调工具，小模型必须被明确告知。
+export const SMALL_MODEL_SYSTEM_PROMPT = `
+## 工具使用铁律（对你至关重要）
+你是一个【工具调用 Agent】，不是一个聊天机器人。用户给你的是一个【任务】，你必须通过调用工具来完成任务，绝对不能只回复文字。
+
+遵守以下规则：
+1. **每次收到用户任务，第一反应是"该调用哪个工具"，而不是"该怎么用文字回答"。**
+2. 如果任务需要读取/查看/搜索文件，调用 Glob / Grep / Read。
+3. 如果任务需要创建/修改文件，调用 Write / Edit。
+4. 如果任务需要运行命令，调用 Bash。
+5. 如果任务需要联网，调用 WebFetch / WebSearch。
+6. **调用工具时，必须提供完整、正确的参数**（绝对路径、完整内容、具体命令）。
+7. 调用工具后，根据工具返回结果继续，直到任务真正完成。
+8. 除非任务只是简单问答（不需要任何工具），否则【禁止】不调用工具就回复。
+9. 禁止输出 "Solved by..."、"\u201cDone\u201d"、"Let me think" 等空话——这些不是完成任务。
+10. 如果一次要做多件事，一次调用一个工具，逐步推进，不要试图一次性解决。
+
+记住：**你的价值在于调用工具把事做完，而不是说漂亮话。**
+`
+
+/**
+ * 生成小模型模式下的完整 system prompt（基础 prompt + 强化引导）
+ * @param {string} basePrompt — 基础 system prompt
+ * @returns {string}
+ */
+export function buildSmallModelSystemPrompt(basePrompt) {
+  return basePrompt + SMALL_MODEL_SYSTEM_PROMPT
+}
+
+// ---- 重试追加强引导（层 A）----
+// 当模型敷衍输出触发重试时，往对话里注入一条"强制工具调用"的用户级提醒，
+// 让模型看到"我刚才敷衍了，现在必须调工具"。
+export const RETRY_GUIDANCE = `[系统提示] 你刚才没有调用任何工具就回复了，这不算完成任务。请立即重新审视任务，调用合适的工具（Write/Edit/Read/Grep/Glob/Bash 等）真正完成任务。不要再输出空话。`
+
+// ---- 意图识别 + 框架动作映射（层 B）----
+// 小模型模式下，框架用关键词规则把常见任务映射到明确的工具动作，
+// 作为"计划"注入，引导模型按序执行（而非让模型自由发挥）。
+//
+// 每个意图规则：
+//   pattern: 触发正则
+//   plan: 建议的工具调用序列（按序执行）
+//   note: 给模型的动作说明
+
+const INTENT_RULES = [
+  {
+    // 读/查看/阅读文档或文件 → 读取任务（优先于写规则，避免"阅读XX文档"被误判为写）
+    pattern: /(读|阅读|查看|打开|展示|显示|看看|浏览).*(文档|文件|内容|md|readme|代码|计划)/i,
+    plan: ['Read（读文件内容）'],
+    note: '这是读取任务，用 Read 读取目标文件内容并理解。',
+    toolHint: 'Read, Glob',
+  },
+  {
+    // 写文档/文件/计划/代码：覆盖"写/创建/生成/更新/保存/做好...文档/计划"等
+    pattern: /(写|创建|生成|更新|保存|做好|做一份|制定|起草|撰写|输出|整理|编写).*(文档|文件|计划|方案|说明|md|readme|代码|函数|模块|接口)/i,
+    plan: ['Grep/Glob（先看现状）', 'Write/Edit（写内容）'],
+    note: '先搜索确认目标文件是否存在/已有内容，再用 Write 或 Edit 写入。',
+    toolHint: 'Write, Edit, Glob, Grep',
+  },
+  {
+    // 明确提到"文档/文件"但未命中动词 → 归为写文件任务（"做...开发计划文档"）
+    pattern: /(文档|计划文档|开发计划|方案文档|说明文档|md文件).*(写好|完成|制作|做|实现|产出)?$/i,
+    plan: ['Write/Edit（写内容）'],
+    note: '这是一个要产出文档/计划的写作任务，直接 Write 或 Edit 写入目标文件。',
+    toolHint: 'Write, Edit',
+  },
+  {
+    pattern: /(找|搜索|查|列出|看看|查看|浏览).*(文件|代码|函数|目录|项目|结构)/i,
+    plan: ['Glob（找文件）', 'Grep（搜内容）', 'Read（读文件）'],
+    note: '用 Glob 找文件路径，用 Grep 搜内容，用 Read 读文件内容。',
+    toolHint: 'Glob, Grep, Read',
+  },
+  {
+    pattern: /(跑|运行|执行|测试|调试|编译|构建).*(命令|脚本|程序|测试|npm|node|python|项目|build)/i,
+    plan: ['Bash（运行命令）'],
+    note: '用 Bash 运行命令/脚本/测试，并读取输出。',
+    toolHint: 'Bash',
+  },
+  {
+    pattern: /(改|修|修复|编辑|更新|优化|重构).*(文件|代码|bug|问题|错误|逻辑|接口|函数)/i,
+    plan: ['Read（读当前内容）', 'Edit（精确修改）'],
+    note: '先 Read 查看当前内容，再用 Edit 精确修改指定位置。',
+    toolHint: 'Read, Edit',
+  },
+  {
+    pattern: /(联网|搜索|查一下|网页|网络|资料|信息|最新|资讯)/i,
+    plan: ['WebSearch（搜索）', 'WebFetch（抓网页）'],
+    note: '用 WebSearch 搜索，用 WebFetch 抓取具体网页内容。',
+    toolHint: 'WebSearch, WebFetch',
+  },
+  {
+    pattern: /(git|提交|push|pull|commit|pr|github|版本)/i,
+    plan: ['Bash（git 命令）', 'GitTool（PR 管理）'],
+    note: '用 Bash 执行 git 命令，或用 GitTool 管理 GitHub PR。',
+    toolHint: 'Bash, GitTool',
+  },
+]
+
+/**
+ * 根据用户指令识别意图，返回框架建议的动作计划
+ *
+ * @param {string} userInput — 用户指令
+ * @returns {{ matched: boolean, intent: string, note: string, toolHint: string } | null}
+ */
+export function detectIntent(userInput) {
+  if (!userInput) return null
+  for (const rule of INTENT_RULES) {
+    if (rule.pattern.test(userInput)) {
+      return {
+        matched: true,
+        intent: rule.plan.join(' → '),
+        note: rule.note,
+        toolHint: rule.toolHint,
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 生成注入到消息里的"意图引导 system 提示"（层 B）
+ *
+ * 当检测到明确意图时，往上下文中插入一条引导，告诉模型该用哪些工具，
+ * 降低小模型的决策负担。
+ *
+ * @param {string} userInput
+ * @param {object} [opts]
+ * @param {boolean} [opts.enable=true] — 是否启用意图引导
+ * @returns {string|null} 引导文本；未匹配或未启用返回 null
+ */
+export function buildIntentGuidance(userInput, opts = {}) {
+  if (opts.enable === false) return null
+  const intent = detectIntent(userInput)
+  if (!intent) return null
+  return `[任务引导] 根据用户指令，建议按此思路用工具推进：${intent.intent}。\n说明：${intent.note}\n可用工具：${intent.toolHint}`
+}
+
+/**
+ * 精简工具列表（层 A）— 小模型一次看太多工具会混乱
+ *
+ * 从完整工具列表里，按用户指令筛选出最相关的核心工具子集。
+ * 这样模型的工具选择负担小，更不容易乱调/漏调。
+ *
+ * @param {Array} allTools — 完整 ToolDef 列表
+ * @param {string} userInput — 用户指令
+ * @param {object} [opts]
+ * @param {boolean} [opts.enable=true] — 是否启用精简
+ * @returns {Array} 精简后的工具列表
+ */
+export function selectRelevantTools(allTools, userInput, opts = {}) {
+  if (opts.enable === false) return allTools
+  if (!allTools || allTools.length === 0) return allTools
+
+  const intent = detectIntent(userInput)
+  // 未识别到明确意图 → 返回核心工具（不塞满 16 个）
+  const coreNames = intent
+    ? intent.toolHint.split(',').map(s => s.trim())
+    : ['Bash', 'Read', 'Edit', 'Write', 'Glob', 'Grep']
+
+  // 核心工具优先，保留指定工具；若一个都没命中则退回首屏核心集
+  const selected = allTools.filter(t => coreNames.includes(t.name))
+  if (selected.length === 0) {
+    return allTools.filter(t => ['Bash', 'Read', 'Edit', 'Write', 'Glob', 'Grep'].includes(t.name))
+  }
+  return selected
+}
+
+/**
+ * 小模型模式开关判断
+ * @param {object} engineConfig — QueryEngineConfig 实例
+ * @returns {boolean}
+ */
+export function isSmallModelEnabled(engineConfig) {
+  return !!(engineConfig && engineConfig.smallModel)
+}