@memtensor/memos-local-openclaw-plugin 1.0.9-beta.2 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memtensor/memos-local-openclaw-plugin",
-  "version": "1.0.9-beta.2",
+  "version": "1.0.9",
   "description": "MemOS Local memory plugin for OpenClaw — full-write, hybrid-recall, progressive retrieval",
   "type": "module",
   "main": "index.ts",

package/src/skill/ALGORITHMS.md

@@ -0,0 +1,141 @@
+# Skill 反馈驱动重构 — 算法原理
+
+## 1. 纯语义反馈识别
+
+### 模块
+`feedback-signals.ts` → `FeedbackSignalExtractor`
+
+### 输入
+多轮对话 chunks（user + assistant + tool），含 turnId
+
+### 输出
+`FeedbackSignal[]`，每条包含 type、source、evidence、turnId、confidence
+
+### 信号类型
+| Type | 含义 | 示例 |
+|------|------|------|
+| reject | 用户否定当前方案 | "这不是我要的效果" |
+| correction | 用户修正 agent 输出 | "不是这个文件，应该是 config.yaml" |
+| constraint | 用户追加约束 | "而且不能用 root 用户" |
+| success | 用户确认成功 | "可以了，这次对了" |
+| confusion | 用户表达困惑 | "为什么会这样？" |
+| preference | 用户表达偏好 | "我更喜欢用 pnpm" |
+
+### 隐式反馈识别
+不依赖关键词匹配。通过 LLM 理解上下文语义：
+- 用户重述目标 → 可能是隐式 reject
+- 用户频繁追问细节 → 可能是 confusion
+- 用户切换话题但不明确否定 → 可能是 preference
+
+## 2. TaskExperience 提取
+
+### 模块
+`experience-extractor.ts` → `ExperienceExtractor`
+
+### 三级策略
+| Mode | 调用次数 | 输出 |
+|------|----------|------|
+| minimal | 0 次额外 LLM | 不生成经验 |
+| balanced | 1 次 LLM | TaskExperience（含内联 feedbackSignals） |
+| full | 2 次 LLM | 独立 feedbackSignals + TaskExperience |
+
+### 输出 schema
+```json
+{
+  "goal": "用户要做什么",
+  "successCriteria": ["标准1", "标准2"],
+  "failedAttempts": [{
+    "attemptLabel": "短标签",
+    "approachSummary": "尝试了什么",
+    "failureReason": "为什么失败",
+    "replacedBy": "被什么替代"
+  }],
+  "workingApproach": "最终成功的方案",
+  "transferableHeuristics": [{
+    "kind": "avoid|prefer|verify|clarify",
+    "trigger": "触发场景",
+    "rule": "应该/不应该做什么",
+    "why": "原因",
+    "evidence": "证据"
+  }]
+}
+```
+
+### 缓存策略
+- 结果缓存在 `task_experience_cache` 表
+- 同一 task 不重复提取
+- worker 重试安全
+
+## 3. Heuristic 生命周期
+
+### 状态机
+```
+[新提取] → candidate → active → refined → stale → [归档]
+```
+
+### 晋升条件 (candidate → active)
+- `supportTaskCount >= 2`
+- `evidenceCount >= 3`
+- 被 skill 升级流程采纳
+
+### 降级条件 (active → stale)
+- 连续多次召回后被判定为 misleading
+- 被更新版 heuristic 替代
+- 依赖的工具/环境过时
+
+### 去重/合并算法
+对每条新 candidate：
+1. 计算 embedding
+2. 在已有 heuristic 库中做余弦相似度搜索
+3. 相似度 >= 0.85 → 更新已有 heuristic（增加 evidence 和 support count）
+4. 0.60 <= 相似度 < 0.85 → 追加证据到已有 heuristic
+5. 相似度 < 0.60 → 新建 candidate
+
+## 4. Heuristic 召回打分
+
+### 三因子公式
+```
+score = 0.45 × topic_similarity + 0.35 × trigger_signal_similarity + 0.20 × quality_weight
+```
+
+### topic_similarity
+query embedding 与 heuristic embedding 的余弦相似度
+
+### trigger_signal_similarity
+当前对话的 LiveInteractionSignals 与 heuristic trigger 的匹配度。
+LiveInteractionSignals 包括：
+- userDissatisfaction
+- constraintRestatement
+- repeatedFailure
+- acceptanceUnclear
+- sameErrorRepeated
+
+### quality_weight 归一化
+```
+base = 0.5
++ 0.2 if status in (active, refined)
++ 0.15 if supportTaskCount >= 3
++ 0.10 if supportTaskCount >= 5
++ 0.05 if lastValidatedAt within 7 days
+= min(1.0, total)
+```
+
+## 5. 统一 LLM 过滤
+
+memory 和 heuristic 候选合并为统一候选池：
+- 每条带 `candidateType: "memory" | "heuristic"`
+- 告诉 LLM 两类职责不同：memory = 事实证据，heuristic = 行为约束
+- 限制总输出：最多 3 memory + 2 heuristic，或总量 5
+
+### Prompt 注入顺序
+1. Heuristic（行为约束 / 避坑提醒）
+2. Skill summary（方法入口）
+3. Memory evidence（事实证据）
+
+## 6. Context Budget
+
+| 类型 | 上限 | 格式 |
+|------|------|------|
+| heuristic | 2-3 条 | trigger + rule + why（1-2 句） |
+| skill | 1-2 条 | 名称 + 适用场景 + 调用提示 |
+| memory | 2-3 条 | 相关 evidence span |

package/src/skill/CHANGELOG-DESIGN.md

@@ -0,0 +1,24 @@
+# Skill 反馈驱动重构 — 设计变更记录
+
+## 2026-04-13: 初始实现
+
+### 变更内容
+- 新增 types: FeedbackSignal, FailedAttempt, TaskExperience, SkillHeuristic, HeuristicRecallEvent
+- 新增 SQLite 表: task_feedback_signals, task_failed_attempts, task_experience_cache, skill_heuristics, skill_heuristic_embeddings, heuristic_recall_events
+- 新增模块: feedback-signals.ts, experience-extractor.ts
+- 修改 evaluator.ts: 支持 TaskExperience 输入
+- 修改 generator.ts: 双产物输出 (SKILL.md + heuristics)
+- 修改 upgrader.ts: 携带完整原始证据升级
+- 修改 evolver.ts: 整合 experience → eval → generate/upgrade → heuristic 管线
+- 修改 recall/engine.ts: 双通道召回 (memory + heuristic) + 三因子打分
+- 修改 index.ts: heuristic 召回 + prompt 注入
+- 新增 viewer/html-v2.ts: 新版 viewer 前端
+- 修改 viewer/server.ts: heuristic API 路由 + viewer v2 切换
+- 修改 sharing/types.ts: SkillBundle 增加 heuristics 字段
+
+### 设计决策
+1. **balanced 模式为默认**: 一次 LLM 调用同时产出 feedbackSignals + failedAttempts + heuristics，平衡成本和质量
+2. **heuristic 独立存储**: 不混入 chunks 表，有独立 embedding 和生命周期
+3. **统一 LLM 过滤**: memory 和 heuristic 合并过滤，避免两次 LLM 调用
+4. **注入顺序 heuristic-first**: 让 agent 先看到避坑规则，再看方法和证据
+5. **向后兼容**: 所有新功能默认启用但可关闭，老数据不强制回填

package/src/skill/DESIGN.md

@@ -0,0 +1,72 @@
+# Skill 反馈驱动重构 — 设计说明
+
+## 方案背景
+
+将 skill 系统从"只总结成功步骤"升级为一套同时沉淀三类资产的系统：
+- **Verified Skill**: 最终验证可复用的操作路径 (SKILL.md)
+- **Failure Heuristics**: 从失败和用户纠偏中提炼出的避坑规则 (SkillHeuristic)
+- **Feedback Signals**: 用户否定、修正、确认成功等高价值监督信号 (FeedbackSignal)
+
+## 三层资产模型
+
+### Skill (技能)
+- 存储：`skills` 表 + 文件系统 (`skills-store/<name>/SKILL.md`)
+- 职责：记录"怎么做" — 可复用的操作步骤、配置、命令
+- 触发：通过 description embedding 在 recall 时被检索
+- 生命周期：`draft → active → archived`
+
+### SkillHeuristic (经验规则)
+- 存储：`skill_heuristics` 表 + `skill_heuristic_embeddings`
+- 职责：记录"别怎么做/什么时候要警惕" — 避坑、验证、偏好规则
+- 触发：通过 embedding 在 recall 时被主动注入 prompt
+- 生命周期：`candidate → active → refined → stale`
+- 与 Skill 关系：多对多（通过 `relatedSkillIds`），可跨 skill 或无关联
+
+### FeedbackSignal (反馈信号)
+- 存储：`task_feedback_signals` 表
+- 职责：原始监督信号，是 heuristic 的证据来源
+- 来源：用户否定、执行错误、助手自检
+- 生命周期：与任务绑定，不独立演化
+
+## 数据流
+
+```
+CaptureMessages → Chunks & Tasks
+                      ↓
+           FeedbackSignalExtractor (feedback-signals.ts)
+                      ↓
+             ExperienceExtractor (experience-extractor.ts)
+                      ↓
+                 TaskExperience
+                   ↙     ↘
+        SkillEvaluator    HeuristicWriter (evolver.ts)
+              ↓                    ↓
+      SkillGenerator/         skill_heuristics 表
+      SkillUpgrader               ↓
+              ↓              RecallEngine.searchHeuristics()
+          SKILL.md                 ↓
+                           Prompt 注入 (heuristic → skill → memory)
+```
+
+## 与现有系统兼容
+
+- 所有新功能通过 `SkillEvolutionConfig` 的新字段控制开关
+- 老数据不回填：`read-time compatible, write-time upgraded`
+- 新表缺失时不影响旧系统启动
+- heuristic 不混入 chunks 表，独立存储和检索
+
+## 配置
+
+新增配置项（均挂在 `skillEvolution` 下）：
+- `experienceExtractionEnabled`: 是否启用经验提炼 (默认 true)
+- `heuristicEnabled`: 是否启用 heuristic 生成 (默认 true)
+- `heuristicRecallEnabled`: 是否启用 heuristic 召回 (默认 true)
+- `experienceMode`: `"minimal" | "balanced" | "full"` (默认 balanced)
+- `heuristicRecallTopK`: 最多召回几条 heuristic (默认 3)
+- `heuristicScoringWeights`: 三因子打分权重
+
+## 关键参考
+
+- Reflexion (Shinn et al., 2023): LLM 自我反思和经验回放
+- Voyager (Wang et al., 2023): 技能库自动扩展
+- 本项目文档: `skill-feedback-redesign.md`

package/src/skill/experience-extractor.ts

@@ -0,0 +1,191 @@
+import { v4 as uuid } from "uuid";
+import type { SqliteStore } from "../storage/sqlite";
+import type { Task, Chunk, TaskExperience, FeedbackSignal, FailedAttempt, TransferableHeuristic, ExperienceMode, PluginContext } from "../types";
+import { DEFAULTS } from "../types";
+import { FeedbackSignalExtractor } from "./feedback-signals";
+import { buildSkillConfigChain, callLLMWithFallback } from "../shared/llm-call";
+
+const EXPERIENCE_PROMPT = `You are a task experience extraction expert. Analyze the completed task record and extract structured experience data.
+
+Focus on:
+1. What was the goal and how was success defined?
+2. What approaches were tried and failed? WHY did they fail?
+3. What was the final working approach?
+4. What user feedback drove direction changes?
+5. What transferable lessons/heuristics can be extracted for future similar tasks?
+
+For transferable heuristics, each should be:
+- "avoid": Something to NOT do (backed by real failure evidence)
+- "prefer": A better approach discovered through trial-and-error
+- "verify": A check that should be performed to prevent known failure modes
+- "clarify": A question that should be asked early to avoid going down wrong paths
+
+Task title: {TITLE}
+Task summary:
+{SUMMARY}
+
+Conversation highlights:
+{CONVERSATION}
+
+{FEEDBACK_SECTION}
+
+Reply with JSON only, strictly following this schema:
+{
+  "goal": "What the user wanted to achieve",
+  "successCriteria": ["criterion1", "criterion2"],
+  "failedAttempts": [
+    {
+      "attemptLabel": "short label",
+      "approachSummary": "what was tried",
+      "failureReason": "why it failed",
+      "replacedBy": "what replaced it or null"
+    }
+  ],
+  "workingApproach": "The final approach that worked",
+  "transferableHeuristics": [
+    {
+      "kind": "avoid|prefer|verify|clarify",
+      "trigger": "when/what situation triggers this heuristic",
+      "rule": "what to do or not do",
+      "why": "reason based on real evidence",
+      "evidence": "brief quote from conversation"
+    }
+  ]
+}`;
+
+export class ExperienceExtractor {
+  private feedbackExtractor: FeedbackSignalExtractor;
+
+  constructor(
+    private store: SqliteStore,
+    private ctx: PluginContext,
+  ) {
+    this.feedbackExtractor = new FeedbackSignalExtractor(ctx);
+  }
+
+  async extract(task: Task, chunks: Chunk[]): Promise<TaskExperience | null> {
+    const mode = this.ctx.config.skillEvolution?.experienceMode ?? DEFAULTS.experienceMode;
+    if (mode === "minimal") return null;
+
+    const cached = this.store.getCachedTaskExperience(task.id);
+    if (cached) {
+      this.ctx.log.debug(`ExperienceExtractor: using cached experience for task ${task.id}`);
+      return cached;
+    }
+
+    const chain = buildSkillConfigChain(this.ctx);
+    if (chain.length === 0) {
+      this.ctx.log.warn("ExperienceExtractor: no LLM config, skipping");
+      return null;
+    }
+
+    let feedbackSignals: FeedbackSignal[] = [];
+    if (mode === "full") {
+      feedbackSignals = await this.feedbackExtractor.extract(task.id, chunks);
+      for (const signal of feedbackSignals) {
+        this.store.insertFeedbackSignal(signal);
+      }
+    }
+
+    const conversationText = this.buildConversation(chunks);
+    const feedbackSection = feedbackSignals.length > 0
+      ? `\nPre-extracted feedback signals:\n${JSON.stringify(feedbackSignals.map(s => ({ type: s.type, source: s.source, evidence: s.evidence, confidence: s.confidence })), null, 2)}`
+      : "";
+
+    const prompt = EXPERIENCE_PROMPT
+      .replace("{TITLE}", task.title)
+      .replace("{SUMMARY}", task.summary.slice(0, 4000))
+      .replace("{CONVERSATION}", conversationText.slice(0, 12000))
+      .replace("{FEEDBACK_SECTION}", feedbackSection);
+
+    try {
+      const raw = await callLLMWithFallback(chain, prompt, this.ctx.log, "ExperienceExtractor", {
+        maxTokens: 3000, temperature: 0.1, timeoutMs: 90_000, openclawAPI: this.ctx.openclawAPI,
+      });
+
+      const experience = this.parseExperience(raw, task.id, feedbackSignals);
+      if (!experience) return null;
+
+      if (mode === "balanced" && experience.feedbackSignals.length > 0) {
+        for (const signal of experience.feedbackSignals) {
+          this.store.insertFeedbackSignal(signal);
+        }
+      }
+
+      for (const attempt of experience.failedAttempts) {
+        this.store.insertFailedAttempt(attempt);
+      }
+
+      this.store.cacheTaskExperience(task.id, experience);
+      this.ctx.log.info(`ExperienceExtractor: extracted experience for task "${task.title}" — ${experience.failedAttempts.length} failed attempts, ${experience.transferableHeuristics.length} heuristics`);
+      return experience;
+    } catch (err) {
+      this.ctx.log.warn(`ExperienceExtractor failed: ${err}`);
+      return null;
+    }
+  }
+
+  private buildConversation(chunks: Chunk[]): string {
+    return chunks
+      .filter(c => c.role !== "system")
+      .map(c => {
+        const role = c.role === "user" ? "User" : c.role === "assistant" ? "Assistant" : c.role === "tool" ? "Tool" : c.role;
+        const content = c.role === "tool" ? c.content.slice(0, 800) : c.content;
+        return `[${role}]: ${content}`;
+      })
+      .join("\n\n");
+  }
+
+  private parseExperience(raw: string, taskId: string, preSignals: FeedbackSignal[]): TaskExperience | null {
+    const match = raw.match(/\{[\s\S]*\}/);
+    if (!match) return null;
+    try {
+      const obj = JSON.parse(match[0]);
+      const now = Date.now();
+
+      const failedAttempts: FailedAttempt[] = (obj.failedAttempts || []).map((a: any) => ({
+        id: uuid(),
+        taskId,
+        attemptLabel: a.attemptLabel || "unknown",
+        approachSummary: a.approachSummary || "",
+        failureReason: a.failureReason || "",
+        failureSignalIds: [],
+        replacedBy: a.replacedBy || null,
+        createdAt: now,
+      }));
+
+      const inlineSignals: FeedbackSignal[] = (obj.feedbackSignals || []).map((s: any) => ({
+        id: uuid(),
+        taskId,
+        type: s.type || "reject",
+        source: s.source || "user",
+        evidence: s.evidence || "",
+        turnId: s.turnId || "",
+        confidence: s.confidence || 0.5,
+        createdAt: now,
+      }));
+
+      const heuristics: TransferableHeuristic[] = (obj.transferableHeuristics || []).map((h: any) => ({
+        kind: h.kind || "avoid",
+        trigger: h.trigger || "",
+        rule: h.rule || "",
+        why: h.why || "",
+        evidence: h.evidence || "",
+      }));
+
+      return {
+        id: uuid(),
+        taskId,
+        goal: obj.goal || "",
+        successCriteria: Array.isArray(obj.successCriteria) ? obj.successCriteria : [],
+        failedAttempts,
+        workingApproach: obj.workingApproach || "",
+        feedbackSignals: preSignals.length > 0 ? preSignals : inlineSignals,
+        transferableHeuristics: heuristics,
+        createdAt: now,
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/skill/feedback-signals.ts

@@ -0,0 +1,181 @@
+import { v4 as uuid } from "uuid";
+import type { Chunk, FeedbackSignal, FeedbackType, FeedbackSource, PluginContext } from "../types";
+import { buildSkillConfigChain, callLLMWithFallback } from "../shared/llm-call";
+
+const FEEDBACK_EXTRACTION_PROMPT = `You are a feedback signal extraction expert. Analyze the following multi-turn conversation and identify feedback signals.
+
+A feedback signal is any indication from the user, execution results, or the assistant's own checks about the quality/direction of the current approach.
+
+Signal types:
+- "reject": User explicitly or implicitly rejects the current approach/output
+- "correction": User provides a correction to the agent's work
+- "constraint": User adds new constraints or requirements not previously mentioned
+- "success": User confirms the solution works or expresses satisfaction
+- "confusion": User expresses confusion or asks for clarification about agent's approach
+- "preference": User states a preference (tool choice, style, methodology)
+
+Signal sources:
+- "user": Signal comes from user messages
+- "execution": Signal comes from error outputs, test failures, runtime errors
+- "assistant_self_check": Assistant self-identifies issues in its own output
+
+Rules:
+- Look at semantic context, not just keywords. A user restating their goal may be an implicit "reject" of the current direction.
+- Each signal must include the exact evidence text (verbatim quote or close paraphrase).
+- Prioritize implicit signals: user NOT saying "wrong" but demonstrating dissatisfaction through rephrasing goals.
+- One message can produce multiple signals.
+- Only extract signals with confidence >= 0.5.
+
+Conversation:
+{CONVERSATION}
+
+Reply with a JSON array only, no extra text:
+[
+  {
+    "type": "reject|correction|constraint|success|confusion|preference",
+    "source": "user|execution|assistant_self_check",
+    "evidence": "exact quote or close paraphrase from conversation",
+    "turnId": "the turn ID where this signal appears",
+    "confidence": 0.0-1.0
+  }
+]
+
+If no meaningful signals found, return: []`;
+
+const VALID_FEEDBACK_TYPES = new Set<FeedbackType>([
+  "reject", "correction", "constraint", "success", "confusion", "preference",
+]);
+
+const VALID_FEEDBACK_SOURCES = new Set<FeedbackSource>([
+  "user", "execution", "assistant_self_check",
+]);
+
+interface RawSignal {
+  type: string;
+  source: string;
+  evidence: string;
+  turnId: string;
+  confidence: number;
+}
+
+export class FeedbackSignalExtractor {
+  constructor(private ctx: PluginContext) {}
+
+  async extract(taskId: string, chunks: Chunk[]): Promise<FeedbackSignal[]> {
+    const chain = buildSkillConfigChain(this.ctx);
+    if (chain.length === 0) {
+      this.ctx.log.warn("FeedbackSignalExtractor: no LLM config, skipping");
+      return [];
+    }
+
+    const conversationText = this.buildConversation(chunks);
+    if (conversationText.length < 100) return [];
+
+    const prompt = FEEDBACK_EXTRACTION_PROMPT.replace(
+      "{CONVERSATION}",
+      conversationText.slice(0, 15_000),
+    );
+
+    try {
+      const raw = await callLLMWithFallback(
+        chain,
+        prompt,
+        this.ctx.log,
+        "FeedbackSignalExtractor",
+        { maxTokens: 2000, temperature: 0.1, timeoutMs: 60_000, openclawAPI: this.ctx.openclawAPI },
+      );
+      return this.parseSignals(raw, taskId);
+    } catch (err) {
+      this.ctx.log.warn(`FeedbackSignalExtractor failed: ${err}`);
+      return [];
+    }
+  }
+
+  /** Lightweight extraction for live interaction signals (used during recall, not full extraction). */
+  async extractLiveSignals(recentChunks: Chunk[]): Promise<string[]> {
+    const chain = buildSkillConfigChain(this.ctx);
+    if (chain.length === 0) return [];
+
+    const text = recentChunks
+      .filter((c) => c.role === "user" || c.role === "assistant")
+      .slice(-8)
+      .map((c) => `[${c.role}]: ${c.content.slice(0, 500)}`)
+      .join("\n");
+
+    if (text.length < 50) return [];
+
+    const prompt = `Analyze the recent conversation turns below and identify which interaction signals are present. Output ONLY the signal names that are present from this list:
+- userDissatisfaction
+- constraintRestatement
+- repeatedFailure
+- acceptanceUnclear
+- sameErrorRepeated
+
+Conversation:
+${text.slice(0, 4000)}
+
+Reply with a JSON array of signal names only: ["signal1", "signal2"]
+If none present, reply: []`;
+
+    try {
+      const raw = await callLLMWithFallback(
+        chain,
+        prompt,
+        this.ctx.log,
+        "LiveSignalExtractor",
+        { maxTokens: 200, temperature: 0, timeoutMs: 15_000, openclawAPI: this.ctx.openclawAPI },
+      );
+      const match = raw.match(/\[[\s\S]*\]/);
+      if (!match) return [];
+      return JSON.parse(match[0]).filter((s: unknown) => typeof s === "string");
+    } catch {
+      return [];
+    }
+  }
+
+  private buildConversation(chunks: Chunk[]): string {
+    return chunks
+      .filter((c) => c.role !== "system")
+      .map((c) => {
+        const role =
+          c.role === "user" ? "User" :
+          c.role === "assistant" ? "Assistant" :
+          c.role === "tool" ? "Tool" :
+          c.role;
+        const content = c.role === "tool" ? c.content.slice(0, 800) : c.content;
+        return `[${role}] (turn=${c.turnId}): ${content}`;
+      })
+      .join("\n\n");
+  }
+
+  private parseSignals(raw: string, taskId: string): FeedbackSignal[] {
+    const match = raw.match(/\[[\s\S]*\]/);
+    if (!match) return [];
+    try {
+      const arr: unknown = JSON.parse(match[0]);
+      if (!Array.isArray(arr)) return [];
+      const now = Date.now();
+      return (arr as RawSignal[])
+        .filter(
+          (s) =>
+            s.confidence >= 0.5 &&
+            VALID_FEEDBACK_TYPES.has(s.type as FeedbackType) &&
+            s.evidence,
+        )
+        .map((s) => ({
+          id: uuid(),
+          taskId,
+          type: s.type as FeedbackType,
+          source: (VALID_FEEDBACK_SOURCES.has(s.source as FeedbackSource)
+            ? s.source
+            : "user") as FeedbackSource,
+          evidence: s.evidence,
+          turnId: s.turnId || "",
+          confidence: s.confidence,
+          createdAt: now,
+        }));
+    } catch {
+      return [];
+    }
+  }
+}