minimal-agent 0.10.0 → 0.12.0

package/src/context/snipCompact.ts

@@ -0,0 +1,163 @@
+/**
+ * ============================================================
+ *  src/context/snipCompact.ts —— 轻量"砍头"压缩（Path 3）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 主项目 services/compact/snipCompact.ts 的设计：
+ *  纯规则、零 LLM 调用，直接砍掉最老的 N% 消息，用作 LLM 压缩失败时
+ *  的兜底（"穷人的压缩"）。
+ *
+ *  压缩强度光谱：
+ *    micro  —— 工具结果级别（SHA-1 + 长度截断，每条消息内部）
+ *    snip   —— 对话级别（按比例砍最老消息，无 LLM）   ← 本文件
+ *    auto   —— LLM 全量重写摘要（9 段式模板）
+ *
+ *  设计要点：
+ *    1. system 消息（messages[0]）永远不动
+ *    2. 默认 < 10 条历史不动（除非 force=true）
+ *    3. 砍头时严格保护 tool_call / tool_result 配对：切口落在 tool
+ *       消息上会自动向后微调，避免造成"孤儿 tool"导致 API 400
+ *    4. 替换为一条 user marker 消息，告诉模型"前面有 N 条被自动删除"
+ * ============================================================
+ */
+
+import type { Message } from '../types.js';
+import { countMessagesTokens } from './tokenCounter.js';
+
+// ==================== 配置常量 ====================
+
+const DEFAULT_SNIP_PERCENT = 0.2;
+const DEFAULT_MIN_KEEP = 5;
+const DEFAULT_MAX_SNIP = 50;
+/** 小于这个总长度时除非 force 不动 */
+const DEFAULT_THRESHOLD = 10;
+
+// ==================== 类型定义 ====================
+
+export interface SnipOptions {
+  /** 强制执行（默认 false：历史 < 10 条不动） */
+  force?: boolean;
+  /** 砍掉的比例，0~1，默认 0.2 */
+  snipPercent?: number;
+  /** 最少保留多少条非 system 消息，默认 5 */
+  minMessagesToKeep?: number;
+  /** 最多砍多少条，默认 50 */
+  maxMessagesToSnip?: number;
+}
+
+export interface SnipResult {
+  /** 压缩后的新数组（不修改原数组） */
+  messages: Message[];
+  /** 实际删掉了多少条 */
+  messagesRemoved: number;
+  /** 估算释放了多少 token */
+  tokensFreed: number;
+}
+
+// ==================== 核心函数 ====================
+
+/**
+ * 砍掉最老的 N% 消息，用一条 user marker 消息替代。
+ *
+ * 切口保护：如果按比例算出的切点落在 tool 消息上，会自动向后微调
+ * 直到切点不在 tool 上——避免造成孤儿 tool（其父 assistant.tool_calls
+ * 被砍掉而它自己被保留，OpenAI 协议下 API 会 400 "tool id not found"）。
+ */
+export function snipCompactIfNeeded(
+  messages: Message[],
+  options: SnipOptions = {},
+): SnipResult {
+  const force = options.force ?? false;
+  const snipPercent = options.snipPercent ?? DEFAULT_SNIP_PERCENT;
+  const minKeep = options.minMessagesToKeep ?? DEFAULT_MIN_KEEP;
+  const maxSnip = options.maxMessagesToSnip ?? DEFAULT_MAX_SNIP;
+
+  if (messages.length === 0) {
+    return { messages: [], messagesRemoved: 0, tokensFreed: 0 };
+  }
+
+  // 拆出 system 消息（只可能在 index 0；最多一条）
+  const systemMsg = messages[0].role === 'system' ? messages[0] : null;
+  const rest = systemMsg ? messages.slice(1) : messages.slice();
+
+  // 阈值检查（< 10 条且非 force → 不动）
+  if (!force && rest.length < DEFAULT_THRESHOLD) {
+    return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+  }
+
+  // 算应该砍多少条
+  const byPercent = Math.floor(rest.length * snipPercent);
+  const proposedSnipCount = Math.min(
+    byPercent,
+    maxSnip,
+    Math.max(0, rest.length - minKeep),
+  );
+
+  if (proposedSnipCount <= 0) {
+    return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+  }
+
+  // 切点保护：避免落在 tool 消息上造成孤儿
+  const actualCut = findHeadCutpoint(rest, proposedSnipCount);
+
+  if (actualCut === 0 || actualCut >= rest.length) {
+    return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+  }
+
+  const snipped = rest.slice(0, actualCut);
+  const remaining = rest.slice(actualCut);
+  const tokensFreed = countMessagesTokens(snipped);
+
+  const marker: Message = {
+    role: 'user',
+    content:
+      `[已自动删除最早的 ${actualCut} 条对话以节省 token（约释放 ${tokensFreed.toLocaleString()} tokens）。` +
+      `如需完整历史请用 /new 重启会话或 /compact 触发 LLM 摘要压缩。]`,
+  };
+
+  return {
+    messages: [...(systemMsg ? [systemMsg] : []), marker, ...remaining],
+    messagesRemoved: actualCut,
+    tokensFreed,
+  };
+}
+
+/**
+ * 找到一个安全的"砍头切点"：从 proposedCut 开始向后扫描，
+ * 跳过所有会留下孤儿 tool 的位置。
+ *
+ * 算法（与 compact.ts 的 findTailWithCompleteToolChains 互补）：
+ *   1. 扫描 messages[cut:]（即"保留区"），收集 assistant.tool_calls.id
+ *      到 knownIds Set 中（向前扫描，每遇到 assistant 就累加）
+ *   2. 遇到 tool 消息且其 tool_call_id 不在 knownIds → 这是孤儿
+ *      → 把切点向后推一位（即 cut++）并重新扫描
+ *   3. 直到保留区中所有 tool 消息都有父级，或 cut 越界
+ *
+ * 复杂度：O(N²) 最坏（N 个消息），实际 N 通常 < 100、扩展次数 < 5 → 极快
+ */
+export function findHeadCutpoint(
+  messages: Message[],
+  proposedCut: number,
+): number {
+  let cut = Math.max(0, Math.min(proposedCut, messages.length));
+
+  // 反复扫描直到切点稳定
+  while (cut < messages.length) {
+    const knownIds = new Set<string>();
+    let foundOrphan = false;
+
+    for (let i = cut; i < messages.length; i++) {
+      const msg = messages[i];
+      if (msg.role === 'assistant' && msg.tool_calls) {
+        for (const tc of msg.tool_calls) knownIds.add(tc.id);
+      } else if (msg.role === 'tool' && !knownIds.has(msg.tool_call_id)) {
+        foundOrphan = true;
+        break;
+      }
+    }
+
+    if (!foundOrphan) return cut;
+    cut++;
+  }
+
+  return cut;
+}

package/src/context/tokenCounter.ts

@@ -0,0 +1,106 @@
+/**
+ * ============================================================
+ *  src/context/tokenCounter.ts —— Token 估算
+ * ------------------------------------------------------------
+ *  我们用一个**粗略估算**（chars / 4）作为 token 数。
+ *
+ *  为何不用 tiktoken / @anthropic-ai/tokenizer？
+ *    - 真实 tokenizer 对每个模型都不同，且会增加几 MB 的依赖
+ *    - 我们只用估算来决定"要不要触发压缩"，误差 ±20% 完全可以接受
+ *    - chars/4 对英文很准；对中文偏低（中文 1 char ≈ 1 token）
+ *
+ *  如何换成精确版？
+ *    1. npm i tiktoken
+ *    2. 把 countTokens() 实现替换为 tiktoken 调用
+ *    3. 不改外部签名即可
+ * ============================================================
+ */
+
+import type { ChatContentPart, Message, Tool } from '../types.js';
+
+/**
+ * 粗略估算一段文本的 token 数。
+ *
+ * 经验值：
+ *   - GPT 系列英文: 1 token ≈ 4 chars
+ *   - 中文：1 char ≈ 1~1.5 tokens（因此本函数对中文低估）
+ *
+ * 我们选保守的 chars/4 + 中文加权：
+ *   ASCII 部分按 /4，非 ASCII（主要是中文）按 *1.0。
+ */
+export function countTextTokens(text: string): number {
+  if (!text) return 0;
+  let asciiChars = 0;
+  let nonAsciiChars = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 128) asciiChars++;
+    else nonAsciiChars++;
+  }
+  return Math.ceil(asciiChars / 4) + nonAsciiChars;
+}
+
+/**
+ * 估算「工具 schema」本身占的 token。每轮请求都会把 ALL_TOOLS 的
+ * name + description + parameters JSON 发给 LLM，但 countMessagesTokens 只数历史消息、
+ * 漏了这部分 → 系统性低估。自动压缩判定阈值时必须把它加上才准。
+ *
+ * 每个工具的 token 组成：
+ *   - 8 token 固定开销（type/function 包裹等结构体）
+ *   - name 字段的文本 token
+ *   - description 字段的文本 token（支持字符串或函数两种形式）
+ *   - parameters JSON 序列化后的文本 token
+ */
+export function estimateToolsTokens(tools: Tool[]): number {
+  let total = 0;
+  for (const t of tools) {
+    total += 8; // 每个工具的结构固定开销（type/function 包裹）
+    total += countTextTokens(t.name);
+    // description 可以是静态字符串，也可以是注入运行时信息的函数
+    const desc = typeof t.description === 'function' ? t.description() : t.description;
+    total += countTextTokens(desc);
+    total += countTextTokens(JSON.stringify(t.parameters));
+  }
+  return total;
+}
+
+function estimateContentPartTokens(part: ChatContentPart): number {
+  if (part.type === 'text') return countTextTokens(part.text);
+  if (part.type === 'image_url') {
+    const detail = part.image_url.detail ?? 'default';
+    if (detail === 'low') return 600;
+    if (detail === 'high') return 9000;
+    return 3000;
+  }
+  // v1 未正式暴露视频入口；保守估算，防压缩阈值低估。
+  return 15_000;
+}
+
+/** 估算整段历史的 token 数（包含 role / 工具调用结构的开销） */
+export function countMessagesTokens(messages: Message[]): number {
+  let total = 0;
+  for (const m of messages) {
+    // 每条消息至少有 ~4 token 的固定开销（role + 边界标记）
+    total += 4;
+
+    if (typeof m.content === 'string') {
+      total += countTextTokens(m.content);
+    } else if (Array.isArray(m.content)) {
+      for (const part of m.content) total += estimateContentPartTokens(part);
+    } else if (m.content === null) {
+      // assistant 的 content 可以是 null（只有 tool_calls 时）
+    }
+
+    if (m.role === 'assistant' && m.tool_calls) {
+      for (const tc of m.tool_calls) {
+        total += 8; // tool_call 结构开销
+        total += countTextTokens(tc.function.name);
+        total += countTextTokens(tc.function.arguments);
+      }
+    }
+    if (m.role === 'tool') {
+      total += countTextTokens(m.tool_call_id);
+    }
+  }
+  return total;
+}

package/src/context/workspaceIndex.js

@@ -299,7 +299,7 @@ function mergeSession(workspace, session) {
             return -1;
         if (b.id === 'default')
             return 1;
-        return a.id.localeCompare(b.id);
+        return b.updatedAt - a.updatedAt;
     });
 }
 async function legacyRecovery() {
@@ -579,7 +579,7 @@ async function mutate(fn) {
                     return -1;
                 if (b.id === 'default')
                     return 1;
-                return a.id.localeCompare(b.id);
+                return b.updatedAt - a.updatedAt;
             });
         }
         index.workspaces.sort((a, b) => a.displayName.localeCompare(b.displayName, 'zh-CN'));