@oyasmi/pipiclaw 0.5.1 → 0.5.2

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAOhE,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,kBAAkB,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IACvC,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;IACpD,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;CAC5D;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAE5E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAoBzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAOzE,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,kBAAkB,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IACvC,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;IACpD,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;CAC5D;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAE5E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAoBzF"}

package/dist/tools/index.js

@@ -1,7 +1,7 @@
+import { createSubAgentTool } from "../subagents/tool.js";
 import { createBashTool } from "./bash.js";
 import { createEditTool } from "./edit.js";
 import { createReadTool } from "./read.js";
-import { createSubAgentTool } from "./subagent.js";
 import { createWriteTool } from "./write.js";
 export function createPipiclawBaseTools(executor) {
     return [createReadTool(executor), createBashTool(executor), createEditTool(executor), createWriteTool(executor)];

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgB7C,MAAM,UAAU,uBAAuB,CAAC,QAAkB;IACzD,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACtE,MAAM,SAAS,GAAG,uBAAuB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5D,OAAO;QACN,GAAG,SAAS;QACZ,kBAAkB,CAAC;YAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;YAClD,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;YACxD,cAAc,EAAE;gBACf,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE;aACrG;SACD,CAAC;KACF,CAAC;AACH,CAAC","sourcesContent":["import type { AgentTool } from \"@mariozechner/pi-agent-core\";\nimport type { Api, Model } from \"@mariozechner/pi-ai\";\nimport type { PipiclawMemoryRecallSettings } from \"../context.js\";\nimport type { Executor, SandboxConfig } from \"../sandbox.js\";\nimport type { SubAgentDiscoveryResult } from \"../sub-agents.js\";\nimport { createBashTool } from \"./bash.js\";\nimport { createEditTool } from \"./edit.js\";\nimport { createReadTool } from \"./read.js\";\nimport { createSubAgentTool } from \"./subagent.js\";\nimport { createWriteTool } from \"./write.js\";\n\nexport interface CreatePipiclawToolsOptions {\n\texecutor: Executor;\n\tgetCurrentModel: () => Model<Api>;\n\tgetAvailableModels: () => Model<Api>[];\n\tresolveApiKey: (model: Model<Api>) => Promise<string>;\n\tworkspaceDir: string;\n\tchannelDir: string;\n\tworkspacePath: string;\n\tchannelId: string;\n\tsandboxConfig: SandboxConfig;\n\tgetSubAgentDiscovery: () => SubAgentDiscoveryResult;\n\tgetMemoryRecallSettings: () => PipiclawMemoryRecallSettings;\n}\n\nexport function createPipiclawBaseTools(executor: Executor): AgentTool<any>[] {\n\treturn [createReadTool(executor), createBashTool(executor), createEditTool(executor), createWriteTool(executor)];\n}\n\nexport function createPipiclawTools(options: CreatePipiclawToolsOptions): AgentTool<any>[] {\n\tconst baseTools = createPipiclawBaseTools(options.executor);\n\treturn [\n\t\t...baseTools,\n\t\tcreateSubAgentTool({\n\t\t\texecutor: options.executor,\n\t\t\tgetCurrentModel: options.getCurrentModel,\n\t\t\tgetAvailableModels: options.getAvailableModels,\n\t\t\tresolveApiKey: options.resolveApiKey,\n\t\t\tworkspaceDir: options.workspaceDir,\n\t\t\tchannelDir: options.channelDir,\n\t\t\tgetSubAgentDiscovery: options.getSubAgentDiscovery,\n\t\t\tgetMemoryRecallSettings: options.getMemoryRecallSettings,\n\t\t\truntimeContext: {\n\t\t\t\tworkspacePath: options.workspacePath,\n\t\t\t\tchannelId: options.channelId,\n\t\t\t\tsandbox: options.sandboxConfig.type === \"host\" ? \"host\" : `docker:${options.sandboxConfig.container}`,\n\t\t\t},\n\t\t}),\n\t];\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgB7C,MAAM,UAAU,uBAAuB,CAAC,QAAkB;IACzD,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACtE,MAAM,SAAS,GAAG,uBAAuB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5D,OAAO;QACN,GAAG,SAAS;QACZ,kBAAkB,CAAC;YAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;YAClD,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;YACxD,cAAc,EAAE;gBACf,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE;aACrG;SACD,CAAC;KACF,CAAC;AACH,CAAC","sourcesContent":["import type { AgentTool } from \"@mariozechner/pi-agent-core\";\nimport type { Api, Model } from \"@mariozechner/pi-ai\";\nimport type { PipiclawMemoryRecallSettings } from \"../context.js\";\nimport type { Executor, SandboxConfig } from \"../sandbox.js\";\nimport type { SubAgentDiscoveryResult } from \"../subagents/discovery.js\";\nimport { createSubAgentTool } from \"../subagents/tool.js\";\nimport { createBashTool } from \"./bash.js\";\nimport { createEditTool } from \"./edit.js\";\nimport { createReadTool } from \"./read.js\";\nimport { createWriteTool } from \"./write.js\";\n\nexport interface CreatePipiclawToolsOptions {\n\texecutor: Executor;\n\tgetCurrentModel: () => Model<Api>;\n\tgetAvailableModels: () => Model<Api>[];\n\tresolveApiKey: (model: Model<Api>) => Promise<string>;\n\tworkspaceDir: string;\n\tchannelDir: string;\n\tworkspacePath: string;\n\tchannelId: string;\n\tsandboxConfig: SandboxConfig;\n\tgetSubAgentDiscovery: () => SubAgentDiscoveryResult;\n\tgetMemoryRecallSettings: () => PipiclawMemoryRecallSettings;\n}\n\nexport function createPipiclawBaseTools(executor: Executor): AgentTool<any>[] {\n\treturn [createReadTool(executor), createBashTool(executor), createEditTool(executor), createWriteTool(executor)];\n}\n\nexport function createPipiclawTools(options: CreatePipiclawToolsOptions): AgentTool<any>[] {\n\tconst baseTools = createPipiclawBaseTools(options.executor);\n\treturn [\n\t\t...baseTools,\n\t\tcreateSubAgentTool({\n\t\t\texecutor: options.executor,\n\t\t\tgetCurrentModel: options.getCurrentModel,\n\t\t\tgetAvailableModels: options.getAvailableModels,\n\t\t\tresolveApiKey: options.resolveApiKey,\n\t\t\tworkspaceDir: options.workspaceDir,\n\t\t\tchannelDir: options.channelDir,\n\t\t\tgetSubAgentDiscovery: options.getSubAgentDiscovery,\n\t\t\tgetMemoryRecallSettings: options.getMemoryRecallSettings,\n\t\t\truntimeContext: {\n\t\t\t\tworkspacePath: options.workspacePath,\n\t\t\t\tchannelId: options.channelId,\n\t\t\t\tsandbox: options.sandboxConfig.type === \"host\" ? \"host\" : `docker:${options.sandboxConfig.container}`,\n\t\t\t},\n\t\t}),\n\t];\n}\n"]}

package/docs/memory-audit.md

@@ -0,0 +1,330 @@
+# Pipiclaw Memory 子系统深度审计报告
+
+> **Date**: 2026-04-02
+> **Scope**: `src/memory/` 全部文件 + 相关调用方
+> **Version**: v0.5.1 post-refactoring (commit c4dc08b)
+
+---
+
+## Executive Summary
+
+Pipiclaw 的三层记忆系统（SESSION / MEMORY / HISTORY）在实际使用中存在两个根本性问题：**"写不进去"** 和 **"读不出来"**。Consolidation 仅在 compaction/new-session 时触发，导致 MEMORY.md 和 HISTORY.md 几乎不更新；召回评分被 base priority 主导，token overlap 对最终排序影响极小，导致召回本质上是按来源类型排序而非按相关性排序。中文场景下问题尤为突出。
+
+---
+
+## 一、现状观察
+
+| 文件 | 更新频率 | 用户感知 |
+|------|---------|---------|
+| SESSION.md | 频繁、及时 | 正常 |
+| MEMORY.md | 偶尔 | 不足 |
+| HISTORY.md | 极少 | 几乎无 |
+
+---
+
+## 二、核心问题诊断
+
+### 问题 1：Consolidation 触发时机过窄
+
+**根因链**：
+
+```
+MEMORY.md/HISTORY.md 更新 ← runInlineConsolidation()
+  ← 仅在 session_before_compact 和 session_before_switch(reason="new") 时触发
+    ← compaction 由 SDK 在上下文窗口满时触发
+    ← new-session 仅在频道首次激活时触发
+```
+
+对于钉钉场景，用户通常是短问答（1-3 轮），上下文窗口永远不会满，compaction 永远不触发。这意味着：
+
+- **HISTORY.md**：几乎永远不会收到新的 history block
+- **MEMORY.md**：几乎永远不会收到新的 memory entries
+- 只有 SESSION.md 因为有独立的 `enqueueSessionMemoryUpdate()` 路径而能正常更新
+
+**关键代码** (`src/memory/lifecycle.ts`)：
+```typescript
+// consolidation 仅在这两个事件中触发
+case "session_before_compact":
+case "session_before_switch":  // 且 reason === "new"
+  await runInlineConsolidation(options);
+```
+
+### 问题 2：召回评分被 base priority 主导
+
+**评分构成** (`src/memory/recall.ts:scoreCandidate`)：
+
+```
+base priority:    40 ~ 120（占绝对主导）
+title overlap:    每匹配一个 token +10（标题通常很短，0~30）
+content overlap:  每匹配一个 token +3（0~15）
+path overlap:     每匹配一个 token +6（0~12）
+recency boost:    0 ~ 8
+```
+
+**实际效果**：一个完全不相关但来源是 session 的候选（score=100+）总是排在一个高度相关但来源是 history 的候选（score=40+几个 overlap）前面。**召回本质上是按来源类型排序，不是按相关性排序**。
+
+**候选优先级梯度** (`src/memory/candidates.ts`)：
+
+```
+channel-session "current state" = 120
+channel-session "next steps"    = 115
+channel-session "errors"        = 110
+channel-session "constraints"   = 108
+channel-session "user intent"   = 105
+channel-session (other)         = 100
+channel-memory (constraints)    = 88
+channel-memory (decisions)      = 86
+channel-memory (open loops)     = 84
+channel-memory (default)        = 80
+workspace-memory                = 60
+channel-history                 = 40
+```
+
+session 到 history 的 priority 差距达 60-80 分，token overlap 几乎不可能弥补。
+
+### 问题 3：中文分词质量低
+
+当前实现用字符级 n-gram（bigram + trigram），没有词级分词：
+
+```
+"如何优化记忆系统"
+→ bigrams:  ["如何", "何优", "优化", "化记", "记忆", "忆系", "系统"]
+→ trigrams: ["如何优", "何优化", "优化记", "化记忆", "记忆系", "忆系统"]
+```
+
+问题：
+- 产生大量无意义的跨词 n-gram（如"何优"、"化记"），增加噪音匹配
+- 短查询（2-3 字）只产生 1-2 个 token，overlap 信号极弱
+- 无法处理同义词/近义词（如"bug"和"缺陷"）
+
+### 问题 4：Background maintenance 阈值过于保守
+
+| 维护操作 | 当前阈值 | 实际达到难度 |
+|---------|---------|------------|
+| Memory cleanup | ≥8,000 字符 OR ≥6 个 update 块 | 需要 6 次 consolidation，而 consolidation 本身就很少触发 |
+| History folding | ≥16,000 字符 OR ≥8 个 block，且总 block>4 | 几乎不可能达到 |
+
+### 问题 5：Inline consolidation 的 LLM 可靠性
+
+当前用一次 LLM 调用同时产生 `memoryEntries` 和 `historyBlock`。问题：
+- LLM 在短对话时倾向于返回空的 `historyBlock`
+- `hasMeaningfulMessages()` 要求 ≥2 条有意义消息，否则整个 consolidation 被跳过
+- Rerank 超时仅 5 秒，内容截断到 300 字符，信息损失大
+
+---
+
+## 三、优化方案
+
+### 方案 A：新增空闲超时 consolidation 触发（P0）
+
+**核心思路**：不再仅依赖 compaction/new-session，在对话"自然结束"时也触发 consolidation。
+
+**实现方式**：在 `MemoryLifecycle` 中新增基于空闲超时的触发：
+
+```typescript
+// lifecycle.ts 新增
+const IDLE_CONSOLIDATION_TIMEOUT_MS = 60_000; // 对话空闲60秒后触发
+
+private idleTimer: ReturnType<typeof setTimeout> | null = null;
+private turnsSinceLastConsolidation = 0;
+
+// 在 noteCompletedAssistantTurn() 中调用
+private scheduleIdleConsolidation(): void {
+  this.clearIdleTimer();
+  this.idleTimer = setTimeout(() => {
+    void this.runIdleConsolidation();
+  }, IDLE_CONSOLIDATION_TIMEOUT_MS);
+}
+
+private clearIdleTimer(): void {
+  if (this.idleTimer) {
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+}
+
+private async runIdleConsolidation(): Promise<void> {
+  if (this.turnsSinceLastConsolidation < 2) return;
+  await runInlineConsolidation(this.buildConsolidationOptions());
+  await runBackgroundMaintenance(this.buildConsolidationOptions());
+  this.turnsSinceLastConsolidation = 0;
+}
+```
+
+**为什么有效**：钉钉场景下用户问完问题就离开，60 秒内没有新消息说明对话结束，此时触发 consolidation 可以可靠地将本轮对话的关键信息写入 MEMORY.md 和 HISTORY.md。
+
+**预期效果**：HISTORY.md 和 MEMORY.md 从几乎不更新变为每轮对话结束后都更新。
+
+---
+
+### 方案 B：重新平衡召回评分（P0）
+
+**核心思路**：归一化 token overlap 分数，使其与 base priority 在同一量级。
+
+```typescript
+function scoreCandidate(queryTokens: string[], candidate: MemoryCandidate): number {
+  // 1. base priority 压缩到 0-20 范围（原始 40-120 → 归一化）
+  const normalizedPriority = (candidate.priority / 120) * 20;
+
+  // 2. token overlap 归一化到 0-50 范围
+  const titleOverlap = computeNormalizedOverlap(queryTokens, candidate.title);
+  const contentOverlap = computeNormalizedOverlap(queryTokens, candidate.content);
+  const pathOverlap = computeNormalizedOverlap(queryTokens, candidate.path);
+  const relevanceScore = titleOverlap * 25 + contentOverlap * 15 + pathOverlap * 10;
+
+  // 3. recency boost 保持 0-8
+  const recencyBoost = computeRecencyBoost(candidate.timestamp);
+
+  return normalizedPriority + relevanceScore + recencyBoost;
+}
+
+function computeNormalizedOverlap(queryTokens: string[], text: string): number {
+  if (queryTokens.length === 0) return 0;
+  const haystack = new Set(tokenize(text));
+  let matches = 0;
+  for (const token of queryTokens) {
+    if (haystack.has(token)) matches++;
+  }
+  return matches / queryTokens.length; // 归一化到 0-1
+}
+```
+
+**效果**：一个 history 候选如果与查询高度匹配（relevanceScore ≈ 40），可以超过一个不相关的 session 候选（normalizedPriority ≈ 17，relevanceScore ≈ 0）。
+
+---
+
+### 方案 C：改进中文分词（P1）
+
+#### C1：轻量级词表分词（推荐）
+
+引入常见中文词表做正向最大匹配，作为 n-gram 的补充：
+
+```typescript
+// 内置一个高频词表（约 2000-3000 个技术 + 通用词）
+import { COMMON_WORDS } from "./chinese-words.js";
+
+function tokenizeHanPart(part: string): string[] {
+  const tokens: string[] = [];
+  // 正向最大匹配分词
+  const words = forwardMaxMatch(part, COMMON_WORDS);
+  tokens.push(...words.filter(w => w.length >= 2));
+  // 保留 bigram 作为兜底（但移除 trigram 以减少噪音）
+  const chars = Array.from(part);
+  for (let i = 0; i <= chars.length - 2; i++) {
+    tokens.push(chars.slice(i, i + 2).join(""));
+  }
+  return tokens;
+}
+```
+
+#### C2：提升 Rerank 质量
+
+```typescript
+// recall.ts 修改
+const RERANK_CONTENT_CLIP = 800;              // 从 300 提升到 800
+const MEMORY_RECALL_RERANK_TIMEOUT_MS = 8_000; // 从 5s 提升到 8s
+```
+
+建议 **C1 + C2 组合使用**。
+
+---
+
+### 方案 D：降低 maintenance 阈值（P1）
+
+```typescript
+// consolidation.ts
+// 当前 → 建议
+const MEMORY_CLEANUP_LENGTH_THRESHOLD = 8_000;  // → 4_000
+const MEMORY_UPDATE_BLOCK_THRESHOLD = 6;         // → 3
+const HISTORY_LENGTH_THRESHOLD = 16_000;          // → 6_000
+const HISTORY_BLOCK_THRESHOLD = 8;                // → 4
+const HISTORY_RECENT_BLOCKS_TO_KEEP = 4;          // → 2
+```
+
+**理由**：方案 A 实施后 consolidation 频率显著提升，MEMORY.md 和 HISTORY.md 增长加快，需要更积极的清理/折叠。
+
+---
+
+### 方案 E：Recall 默认配置调优（P1）
+
+```typescript
+// channel-runner.ts 中的 recall 调用参数
+// 当前 → 建议
+maxCandidates: 8,       // → 12（给 reranker 更多候选）
+maxInjected: 3,         // → 5（注入更多上下文）
+maxChars: 3500,         // → 5000（允许更长的回忆文本）
+rerankWithModel: false, // → true（默认开启 LLM rerank）
+```
+
+**注意**：开启默认 rerank 会增加约 1 次 sidecar LLM 调用/轮，但对提升召回质量非常值得。
+
+---
+
+### 方案 F：独立 MEMORY 和 HISTORY 的更新路径（P2）
+
+将 memoryEntries 提取做成确定性规则 + LLM 混合：
+
+```typescript
+// 确定性提取：从 assistant 回复中提取结构化信息
+function extractDeterministicMemoryEntries(messages: Message[]): string[] {
+  const entries: string[] = [];
+  // 提取用户明确要求记住的内容（"记住..."、"以后..."）
+  // 提取关键决策点（"决定用..."、"选择..."）
+  // 提取纠正/偏好表达（"不要..."、"应该..."）
+  return entries;
+}
+```
+
+对 historyBlock 的 prompt 强化：
+
+```typescript
+const INLINE_CONSOLIDATION_SYSTEM_PROMPT = `...
+- historyBlock MUST NOT be empty. Even for short conversations,
+  summarize what was discussed in 1-2 sentences.
+...`;
+```
+
+---
+
+## 四、优先级总览
+
+| 优先级 | 方案 | 预期效果 | 实施复杂度 |
+|-------|------|---------|-----------|
+| **P0** | A: 空闲触发 consolidation | HISTORY/MEMORY 从几乎不更新 → 每轮对话都更新 | 中 |
+| **P0** | B: 评分重新平衡 | 召回从按来源排序 → 按相关性排序 | 低 |
+| **P1** | C: 中文分词改进 | 中文召回准确率显著提升 | 中 |
+| **P1** | D: 降低 maintenance 阈值 | MEMORY/HISTORY 及时整理 | 低 |
+| **P1** | E: Recall 默认配置调优 | 更多相关上下文被注入 | 低 |
+| **P2** | F: 独立更新路径 | HISTORY 可靠产出 | 高 |
+
+---
+
+## 五、实施建议
+
+### 第一阶段（立即）
+1. 实施方案 A（空闲触发）+ 方案 B（评分平衡）— 解决"写不进去"和"读不出来"两个根本问题
+2. 实施方案 D（降低阈值）— 配合方案 A 的效果
+
+### 第二阶段（跟进）
+3. 实施方案 C（中文分词）+ 方案 E（配置调优）— 进一步提升召回质量
+4. 为所有方案补充测试用例
+
+### 第三阶段（可选）
+5. 实施方案 F（独立路径）— 提升 consolidation 可靠性
+6. 添加 sidecar LLM 调用的 token 追踪（可观测性）
+
+---
+
+## 附录：关键文件参照
+
+| 文件 | 行数 | 涉及方案 |
+|------|------|---------|
+| `src/memory/lifecycle.ts` | 294 | A |
+| `src/memory/recall.ts` | 280 | B, C, E |
+| `src/memory/consolidation.ts` | 328 | A, D, F |
+| `src/memory/candidates.ts` | 170 | B |
+| `src/memory/session.ts` | 290 | — |
+| `src/memory/files.ts` | 193 | — |
+| `src/agent/channel-runner.ts` | 495 | E |
+| `src/sidecar-worker.ts` | 138 | — |
+

package/docs/memory-optimization-round2.md

@@ -0,0 +1,319 @@
+# Memory 子系统第二轮优化计划
+
+> **Date**: 2026-04-02
+> **Base**: 第一轮优化后 (commit 845de82)
+> **Input**: memory-audit.md 审计报告 + 第一轮优化质量评估
+
+---
+
+## 一、第一轮优化回顾
+
+### 已落地（保留不动）
+
+| 方案 | 实施质量 | 说明 |
+|------|---------|------|
+| 空闲触发 consolidation | A | 60s idle timer + snapshot + 自动重调度，设计精良 |
+| 中文分词改进 | A | 正向最大匹配 + bigram 兜底 + 130 词表 |
+| Rerank 参数提升 | A | timeout 8s, content clip 800 |
+| 降低 maintenance 阈值 | A | memory 5K/4块, history 8K/5块/保留3 |
+| Query Intent Detection | A | 6 种意图，中英双语，超出审计建议的创新 |
+| Consolidation prompt 强化 | B- | 仅加了"prefer"措辞，未加 few-shot |
+
+### 未落地或需改进
+
+| 方案 | 状态 | 本轮处理 |
+|------|------|---------|
+| Recall 默认配置调优 | 未实施 | 本轮实施 |
+| 评分算法仍有 priority 主导倾向 | 部分改善 | 本轮精炼 |
+| Intent seeding 可能注入无关候选 | 新发现 | 本轮修复 |
+| 运算符优先级不清晰 | 新发现 | 本轮修复 |
+| 中文词表覆盖不足 | 新发现 | 本轮扩充 |
+| 排序逻辑重复 | 新发现 | 本轮提取 |
+
+---
+
+## 二、本轮优化内容
+
+### 2.1 [P0] 首轮强制注入 MEMORY.md（新策略）
+
+**动机**：当前召回依赖 token overlap + intent matching，但 session 首轮对话中用户可能只说了一句模糊的话（如"你好"、"帮我看看那个问题"），几乎不会命中任何 memory 候选。LLM 在冷启动时对频道上下文完全遗忘。
+
+**策略**：在每个 session 的第一轮对话中，无条件将 MEMORY.md 的前 3K 字符拼入 prompt，独立于召回机制。
+
+**实现要点**：
+
+1. 在 `ChannelRunner` 中新增 `isFirstUserTurn` 状态标记：
+
+```typescript
+// channel-runner.ts
+private isFirstUserTurn = true;
+
+// 在 run() 方法中，recall 之后：
+if (this.isFirstUserTurn) {
+  const memorySnapshot = await this.buildFirstTurnMemorySnapshot();
+  if (memorySnapshot) {
+    promptText = `${memorySnapshot}\n\n${promptText}`;
+  }
+  this.isFirstUserTurn = false;
+}
+```
+
+2. 构建注入文本：
+
+```typescript
+private async buildFirstTurnMemorySnapshot(): Promise<string> {
+  const memoryPath = getChannelMemoryPath(this.channelDir);
+  const raw = await readOptionalFile(memoryPath);
+  if (!raw.trim()) return "";
+
+  // 如果 recall 已返回 channel-memory 候选，跳过注入避免重复
+  // （由调用方判断，此处只负责构建文本）
+
+  const clipped = clipText(raw, 3000, { headRatio: 1.0 }); // 纯取头部
+  return [
+    "<channel_memory_snapshot>",
+    "Below is the first 3K of this channel's durable memory (MEMORY.md).",
+    "Use it as background context for this conversation.",
+    "",
+    clipped,
+    "</channel_memory_snapshot>",
+  ].join("\n");
+}
+```
+
+3. 与 recall 去重：如果 recall 结果已包含 `channel-memory` 来源的候选，则跳过强制注入。
+
+**优势**：
+- 解决冷启动遗忘问题，LLM 从第一句话就"记得"频道核心上下文
+- 实现极简（约 20 行），几乎零风险
+- MEMORY.md 头部经过 cleanup LLM 整理，天然是高价值信息（Identity/Preferences/Constraints）
+- 与 recall 互补而非冲突：recall 解决"针对具体问题找相关记忆"，强制注入解决"确保基础上下文始终在场"
+
+**风险与缓解**：
+- Token 预算占用约 1K-1.5K tokens — 钉钉短问答场景中上下文窗口充裕，影响可忽略
+- 与 recall 结果重复 — 通过检查 recall 是否已返回 channel-memory 候选来去重
+
+---
+
+### 2.2 [P0] 实施 Recall 默认配置调优
+
+**动机**：第一轮审计明确建议但未实施。当前默认值过于保守。
+
+**改动位置**：`src/agent/channel-runner.ts` 中的 `recallRelevantMemory()` 调用参数，以及 `src/context.ts` 中的 `PipiclawMemoryRecallSettings` 默认值。
+
+| 参数 | 当前值 | 目标值 | 理由 |
+|------|-------|-------|------|
+| maxCandidates | 8 | 12 | 给 reranker 更多候选，提升选择质量 |
+| maxInjected | 3 | 5 | 注入更多上下文，覆盖更多相关信息 |
+| maxChars | 3500 | 5000 | 允许更长的回忆文本 |
+| rerankWithModel | false | true | 默认开启 LLM rerank，显著提升中文召回质量 |
+
+---
+
+### 2.3 [P1] 评分算法精炼
+
+**问题**：当前 priority 范围 4-18，lexical 最高约 96。session（priority=18）和 history（priority=4）差距 14 分。当 query 与两个候选的词汇匹配度相同时，session 始终胜出。真正的"相关性优先"尚未实现。
+
+**方案**：改为乘法加权，structural 作为调节因子而非独立加分项。
+
+```typescript
+function scoreCandidate(...): ScoredCandidate | null {
+  // ... 计算 lexicalScore 和 structuralScore 同现有逻辑 ...
+
+  if (matchedTokens.size === 0 && exactBoost === 0 && intentBoost === 0) {
+    return null;
+  }
+
+  // 乘法加权：lexical 为主，structural 为调节
+  // structural 最高约 34（priority 18 + intent 10 + recency 6）
+  // 乘数范围约 1.0 ~ 1.34
+  const score = lexicalScore * (1 + structuralScore / 100);
+
+  return { candidate, score, lexicalMatchCount: matchedTokens.size, intentBoost };
+}
+```
+
+**效果**：
+- 当 lexical = 0 时，score = 0 — 无词汇匹配的候选不会仅靠 structural 上位
+- 当 lexical 相同时，structural 提供约 0-34% 的微调 — session 仍有优势但不再碾压
+- 当 history 候选 lexical 远高于 session 候选时，history 可以反超
+
+**注意**：`seedIntentCandidates()` 中 intentBoost > 0 但 lexicalMatchCount = 0 的候选，在乘法模式下 score 会变为 0。需要调整 seeding 逻辑（见 2.4）。
+
+---
+
+### 2.4 [P1] 约束 Intent Seeding
+
+**问题**：`seedIntentCandidates()` 可注入 lexicalMatchCount=0 的候选。在 2.3 改为乘法加权后，这些候选 score 为 0，会被自然淘汰。但即使不改为乘法，纯 intent 注入也可能挤掉更相关的候选。
+
+**方案**：对 intent seeding 增加最低门槛。
+
+```typescript
+function seedIntentCandidates(
+  request: RecallRequest,
+  candidates: MemoryCandidate[],
+  existing: ScoredCandidate[],
+  intents: Set<QueryIntent>,
+  queryTokens: string[],  // 新增参数
+): ScoredCandidate[] {
+  // ...
+  for (const { candidate, intentBoost } of intentCandidates) {
+    // 至少需要 1 个 query token 匹配，才允许 intent 注入
+    const matched = collectMatchingQueryTokens(
+      queryTokens,
+      [candidate.title, candidate.searchText ?? candidate.content],
+    );
+    if (matched.size === 0) continue;
+
+    seeded.push({ ... });
+  }
+  // ...
+}
+```
+
+**效果**：意图匹配 + 至少 1 个词汇匹配 = 允许注入。纯意图匹配但内容完全无关 = 不注入。
+
+---
+
+### 2.5 [P1] 扩充中文词表
+
+**问题**：当前 130 词中包含较多 pipiclaw 内部术语（"召回排序"、"排序失真"、"主导权重"），缺少大量通用技术词汇。
+
+**方案**：
+
+1. **移除**过于特定的内部术语（约 20 个），如"排序失真"、"主导权重"、"轻量词表"等
+2. **新增**通用技术词汇（约 200 个），覆盖以下领域：
+
+```
+基础设施: 服务器、数据库、缓存、队列、网络、集群、容器、网关、负载均衡
+编程概念: 函数、变量、接口、类型、模块、组件、依赖、注入、继承、多态
+开发流程: 需求、设计、实现、测试、部署、发布、回滚、监控、告警、日志
+Web/API:  请求、响应、认证、授权、会话、路由、中间件、过滤器、拦截器
+数据:     查询、索引、事务、迁移、备份、恢复、同步、异步、并发、锁
+工具:     编辑器、终端、浏览器、调试器、编译器、构建、打包、压缩
+```
+
+3. 目标词表规模约 300 个，保持文件 < 300 行
+
+---
+
+### 2.6 [P1] 修复代码质量问题
+
+#### 2.6.1 运算符优先级明确化
+
+**位置**：`src/memory/lifecycle.ts:109-113`
+
+```typescript
+// 当前（行为正确但意图不清晰）
+if (
+  canTriggerThresholdRefresh &&
+  this.turnsSinceSessionUpdate >= settings.minTurnsBetweenUpdate ||
+  (canTriggerThresholdRefresh && this.toolCallsSinceSessionUpdate >= settings.minToolCallsBetweenUpdate)
+)
+
+// 修改为
+if (
+  canTriggerThresholdRefresh &&
+  (this.turnsSinceSessionUpdate >= settings.minTurnsBetweenUpdate ||
+   this.toolCallsSinceSessionUpdate >= settings.minToolCallsBetweenUpdate)
+)
+```
+
+#### 2.6.2 提取排序比较器
+
+**位置**：`src/memory/recall.ts:487-501`
+
+```typescript
+function compareScoredCandidates(a: ScoredCandidate, b: ScoredCandidate): number {
+  return (
+    b.score - a.score ||
+    b.lexicalMatchCount - a.lexicalMatchCount ||
+    b.candidate.priority - a.candidate.priority ||
+    a.candidate.title.localeCompare(b.candidate.title)
+  );
+}
+
+// 使用
+const scored = filteredCandidates.map(...).filter(...).sort(compareScoredCandidates);
+const shortlist = seedIntentCandidates(...).sort(compareScoredCandidates).slice(...);
+```
+
+---
+
+### 2.7 [P2] Consolidation prompt 强化
+
+**问题**：当前 prompt 对 historyBlock 仅用"prefer"措辞，LLM 在短对话时仍可能返回空值。
+
+**方案**：添加 few-shot 示例到 system prompt。
+
+```
+Rules:
+...
+- historyBlock: concise Markdown summarizing the conversation chunk for later recovery.
+- For any conversation with at least one meaningful user question and assistant answer,
+  you MUST return a non-empty historyBlock with at least one bullet summarizing the exchange.
+- Prefer short bullets and short paragraphs.
+
+Example output for a short Q&A conversation:
+{
+  "memoryEntries": ["User prefers dark mode in the dashboard"],
+  "historyBlock": "- User asked how to toggle dashboard theme; confirmed dark mode preference."
+}
+```
+
+---
+
+### 2.8 [P2] Sidecar Token 追踪
+
+**问题**：memory 系统通过 sidecar 发起的 LLM 调用（session memory update、inline consolidation、memory cleanup、history folding、LLM rerank）没有 token 使用量统计，无法评估实际 API 开销。
+
+**方案**：
+
+1. `runSidecarTask` 返回值中增加 `usage?: { inputTokens: number; outputTokens: number }`
+2. `MemoryLifecycle` 中累计追踪每类操作的 token 消耗
+3. 在 background maintenance 日志中输出累计 token 消耗
+
+---
+
+## 三、实施顺序
+
+```
+Phase 1（核心功能）
+  2.1  首轮强制注入 MEMORY.md
+  2.2  Recall 默认配置调优
+  2.6  代码质量修复（运算符优先级 + 排序提取）
+
+Phase 2（评分优化）
+  2.3  评分乘法加权
+  2.4  Intent seeding 约束
+  2.5  中文词表扩充
+
+Phase 3（可靠性）
+  2.7  Consolidation prompt 强化
+  2.8  Sidecar token 追踪
+```
+
+---
+
+## 四、验证标准
+
+### 功能验证
+
+- [ ] 首轮对话发送模糊消息（如"你好"），prompt 中应包含 `<channel_memory_snapshot>` 标签
+- [ ] 第二轮对话不再包含强制注入内容
+- [ ] 当 recall 已返回 channel-memory 候选时，跳过强制注入
+- [ ] rerankWithModel 默认启用，中文查询自动触发 rerank
+
+### 评分验证
+
+- [ ] history 候选在 lexical 高度匹配时可以排在不相关 session 候选之前
+- [ ] lexical = 0 的候选不会仅靠 structural 上位（乘法加权后）
+- [ ] intent seeding 不会注入与 query 零词汇匹配的候选
+
+### 回归验证
+
+- [ ] 全部现有测试通过
+- [ ] 新增首轮注入的单元测试
+- [ ] 新增 scoreCandidate 乘法加权的单元测试
+- [ ] 新增中文短查询（2-3 字）的召回集成测试
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oyasmi/pipiclaw",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "An AI assistant runtime for coding and team workflows, with DingTalk AI Cards, sub-agents, memory, and scheduled events.",
 	"type": "module",
 	"bin": {