fix: Feishu channel agents file_write permission blocked + memory system tests & docs

- Fix 8 Feishu agent handlers to use permission_level="acceptEdits" so file_write tool works without Web UI approval popup (lingxi/renshenguo/suyao/tiantian/orange/main/schedule) - Add P5-P7 memory improvements: offline keyword fallback, team sharing, file-based memory - Add auto_dream_service for daily memory consolidation - Add 99 memory system test cases (basic 18 + advanced 43 + pytest 38) - Add platform capability assessment report and unfinished project checklist Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-14 20:35:12 +08:00
parent a7512a5423
commit 7f4aeb021b
22 changed files with 6191 additions and 68 deletions
--- a/docs/agent-memory-comparison.md
+++ b/docs/agent-memory-comparison.md
@@ -0,0 +1,287 @@
+# Agent 记忆系统对比：天工平台 vs Claude Code
+
+> 最后更新：2026-06-14
+
+---
+
+## 一、天工平台记忆架构
+
+### 1.1 概览
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    天工 Agent 记忆栈                      │
+├─────────────────────────────────────────────────────────┤
+│  三层记忆                                                 │
+│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
+│  │  压缩记忆    │  │  向量语义记忆 │  │  自主学习模式   │  │
+│  │ (Compaction) │  │ (Vector Mem) │  │ (Learning)     │  │
+│  └──────┬──────┘  └──────┬───────┘  └───────┬────────┘  │
+│         │                │                   │           │
+│   LLM 摘要压缩      BGE-M3 Embedding    LLM 模式提取     │
+│   三级策略触发      余弦相似度检索      工具调用学习      │
+│         │                │                   │           │
+│  ┌──────┴──────┐  ┌─────┴──────┐  ┌───────┴────────┐  │
+│  │ persistent  │  │ AgentVector │  │ learning       │  │
+│  │ _memory     │  │ Memory 表   │  │ _patterns 表   │  │
+│  │ (JSON blob) │  │ (向量+元数据)│  │ (模式+频率)    │  │
+│  └─────────────┘  └────────────┘  └────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 1.2 三层记忆详解
+
+#### 压缩记忆 (Compaction Memory)
+
+| 级别 | 触发条件 | 机制 | 效果 |
+|------|---------|------|------|
+| MicroCompact | 窗口 70% | 旧工具结果替换为桩标记 | 回收 30-50% token |
+| FullCompact | 窗口 85% | LLM 摘要替换旧对话片段 | 进一步压缩 |
+| ReactiveCompact | 窗口 95% | API 报错后被动触发 | 最终兜底 |
+
+- 熔断保护：连续压缩失败 3 次自动停止
+- 受保护工具（14 个）：`file_write`, `send_email`, `deploy_push` 等绝不压缩
+- 配置：`CompactionConfig` 可单独设定各阈值
+
+#### 向量语义记忆 (Vector Semantic Memory)
+
+- **Embedding 模型**: `BAAI/bge-m3` (1024 维, 8192 token)
+- **后端**: SiliconFlow (国内直连)
+- **存储**: MySQL `agent_vector_memory` 表
+- **检索**: 余弦相似度 + LLM Rerank（可选）
+- **类型分类**: user / feedback / project / reference
+- **配置**: `vector_memory_enabled`, `vector_memory_top_k`, `vector_memory_rerank`
+
+最近 50 条记忆参与相似度计算，语义检索 top-5 注入 system prompt。
+
+#### 自主学习模式 (Learning Patterns)
+
+- 从工具调用序列中提取使用模式
+- 记录调用成功率和参数偏好
+- 存储到 `learning_patterns` 表
+- 后续类似任务时注入匹配模式
+
+### 1.3 记忆生命周期
+
+```
+用户发消息
+  │
+  ├─→ AgentMemory.initialize(query)
+  │     ├─ 加载 persistent_memory (JSON blob: 用户画像+上下文+历史摘要)
+  │     ├─ 向量检索 AgentVectorMemory (按 query 语义相似度)
+  │     └─ 全局知识库检索 GlobalKnowledge
+  │
+  ├─→ Agent 执行对话...
+  │
+  └─→ AgentMemory.save_context()
+        ├─ _compress_and_summarize() (LLM 提取 user_profile/key_facts/summary/topics)
+        ├─ save_persistent_memory() (写入 MySQL persistent_memory 表)
+        ├─ _save_vector_memory() (embedding → agent_vector_memory 表)
+        └─ _save_compressed_memories() (摘要向量化写入，P1 新增)
+```
+
+### 1.4 记忆配置 (AgentMemoryConfig)
+
+| 配置项 | 默认值 | 说明 |
+|--------|------|------|
+| max_history_messages | 20 | 注入 LLM 上下文的最大消息数 |
+| persist_to_db | true | 会话记忆写入 MySQL |
+| vector_memory_enabled | true | 向量语义检索 |
+| vector_memory_top_k | 5 | 每次检索返回 top 5 |
+| vector_memory_rerank | false | LLM Rerank 精选 |
+| memory_type_filter | null | 按类型过滤 (如 `["user","project"]`) |
+| learning_enabled | true | 自主学习模式 |
+| compaction | null | CompactionConfig 配置 |
+
+---
+
+## 二、Claude Code 记忆架构
+
+### 2.1 概览
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                  Claude Code 记忆栈                        │
+├──────────────────────────────────────────────────────────┤
+│  五层文件记忆 + 三个后台进程                                │
+│                                                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
+│  │CLAUDE.md │  │   Auto   │  │  Team    │  │  Agent   │ │
+│  │ 项目指令  │  │  Memory  │  │  Memory  │  │  Memory  │ │
+│  └──────────┘  └────┬─────┘  └────┬─────┘  └──────────┘ │
+│                      │             │                      │
+│               MEMORY.md       memory/team/                │
+│               + topic/*.md    push/pull sync              │
+│                      │                                   │
+│  ┌───────────────────┴──────────────────────────────┐   │
+│  │           Session Memory (当前会话笔记)             │   │
+│  └──────────────────────────────────────────────────┘   │
+│                                                           │
+│  后台进程：                                                │
+│  ┌────────────────┐  ┌──────────────┐  ┌─────────────┐  │
+│  │ Extract        │  │  Auto Dream  │  │ Kairos Daily│  │
+│  │ Memories       │  │  夜间整合    │  │  Log Mode   │  │
+│  │ (每轮对话后)    │  │ (24h+5会话)  │  │ (append日记) │  │
+│  └────────────────┘  └──────────────┘  └─────────────┘  │
+└──────────────────────────────────────────────────────────┘
+```
+
+### 2.2 五层文件记忆
+
+#### Layer 1: CLAUDE.md 项目指令
+
+- 启动时加载，四层优先级：Managed → User → Project → Local
+- 支持 `@include` 指令组合文件
+- 支持 glob 条件规则 (`paths:` 在 YAML frontmatter)
+- 最大 40,000 字符/文件
+
+#### Layer 2: Auto Memory (自动化持久记忆)
+
+- 存储位置：`~/.claude/projects/<project>/memory/`
+- 四类记忆：**user** / **feedback** / **project** / **reference**
+- 两步保存：(1) 写 `.md` 文件 (含 frontmatter) → (2) 追加索引到 `MEMORY.md`
+- `MEMORY.md` 上限 200 行 / 25KB
+
+#### Layer 3: Team Memory (团队共享)
+
+- `memory/team/` 子目录，独立 `MEMORY.md` 索引
+- push/pull 同步机制：watcher 监听文件变化 → debounce → push 到服务器
+- 路径遍历防护：symlink 解析、realpath 容器检查
+
+#### Layer 4: Agent Memory (Agent 专属)
+
+- 用户/项目/本地三种 scope
+- Agent 创建向导中配置
+
+#### Layer 5: Session Memory (会话笔记)
+
+- 当前对话的运行中笔记
+- token 计数阈值 + 工具调用阈值触发更新
+- GrowthBook 特性开关控制
+
+### 2.3 三个后台进程
+
+#### Extract Memories（每轮对话后）
+
+- 对话结束后 fork 子 Agent，共享父级 prompt cache（零成本上下文）
+- 只读搜索 + 仅可写 memory 目录（沙箱隔离）
+- 上限 5 轮防止无限循环
+
+#### Auto Dream（夜间整合）
+
+- 触发条件：(1) ≥ 24h 距上次整合 (2) ≥ 5 次新会话 (3) 获取锁
+- 回顾会话 transcript，提炼为 topic 文件 + 更新 MEMORY.md
+
+#### Kairos Daily Log Mode（日记模式）
+
+- 长运行 Assistant 会话：append-only 日期日志
+- 夜间 `/dream` 技能提炼日志为结构化记忆
+
+### 2.4 记忆检索：LLM 分类器（非向量搜索）
+
+```
+用户提问
+  │
+  ├─→ 扫描所有记忆文件的 frontmatter (name + description)
+  ├─→ 格式化 manifest → 发送给 Sonnet 模型
+  ├─→ Sonnet 选最相关 5 个文件
+  └─→ 选中文件内容注入上下文
+
+没有 Embedding, 没有向量数据库，纯 LLM 判断 + 文件系统。
+```
+
+---
+
+## 三、核心差异对比
+
+### 3.1 架构理念
+
+| 维度 | 天工平台 | Claude Code |
+|------|---------|-------------|
+| 设计哲学 | 传统 RAG + Agent | 文件系统 + LLM 原生 |
+| 记忆存储 | MySQL 数据库 | Markdown 文件 |
+| 检索方式 | 向量相似度 + LLM Rerank | LLM 读 frontmatter 选文件 |
+| 记忆写入 | 对话中同步，结构化 | 后台子 Agent 异步，自由文本 |
+| 分类体系 | 关键词推断 4 类 | 4 类显式标注 |
+| 记忆整合 | 无（实时覆盖） | Auto Dream 夜间去重合并 |
+| 外部依赖 | Embedding API (SiliconFlow) | **零** |
+| 离线可用 | 否 | 是 |
+
+### 3.2 能力矩阵
+
+| 能力 | 天工 | Claude Code | 说明 |
+|------|:--:|:--:|------|
+| 对话压缩 | ✅ | ✅ | 天工三级策略更细粒度 |
+| 向量语义检索 | ✅ | ❌ | 天工专属优势 |
+| LLM Rerank 检索 | ✅ | ✅ | 天工可选，Claude Code 必选 |
+| 自动记忆提取 | ✅ | ✅ | Claude Code 子 Agent 更智能 |
+| 夜间记忆整合 | ✅ | ✅ | 天工 Auto Dream 已实现 |
+| 记忆类型分类 | ✅ | ✅ | 均支持 4 类 |
+| 后台异步提取 | ✅ | ✅ | 天工已改为 fire-and-forget |
+| 团队共享记忆 | ❌ | ✅ | Claude Code 独有 |
+| 记忆去重 | ✅ | ❌ | 天工 GlobalKnowledge 去重 |
+| 全局知识池 | ✅ | ❌ | 天工独有 |
+| 自主学习模式 | ✅ | ❌ | 天工独有 |
+| 记忆规模上限 | 百万级 | ~200 条 | 天工向量搜索更具扩展性 |
+| 单次检索成本 | 几乎免费 | 1 次 LLM 调用 | 天工更经济 |
+
+### 3.3 优缺点对比
+
+#### 天工平台
+
+| 优点 | 缺点 |
+|------|------|
+| 向量搜索毫秒级响应，可扩展百万级记忆 | 离线关键词匹配精度弱于语义搜索 |
+| LLM Rerank + 向量混合检索，精度高 | — |
+| 全局知识池跨 Agent 共享 + 去重 | — |
+| 后台异步压缩 + Auto Dream 每日整合 | — |
+| 文件式记忆 (MEMORY.md) 离线兜底 | — |
+| 自主学习从工具调用中提取模式 | — |
+| 三级对话压缩 + 熔断保护 | — |
+| 4 类记忆分类 + 关键词自动推断 | — |
+| 团队共享记忆 + 跨 Agent 知识池 | — |
+
+#### Claude Code
+
+| 优点 | 缺点 |
+|------|------|
+| 零外部依赖，完全离线可用 | 检索每次调 LLM，成本高速度慢 |
+| 子 Agent 后台提取记忆，不影响主对话 | 记忆上限受 manifest 长度限制 (~200 条) |
+| 夜间自动整合去重，记忆质量持续提升 | 无向量搜索，长尾记忆可能漏 |
+| 团队共享记忆，多用户协同 | 无全局知识池，跨项目知识难复用 |
+| 自由文本格式，记忆表达灵活 | 文件管理无结构化查询能力 |
+
+---
+
+## 四、天工借鉴 Claude Code 已实施改进
+
+| 优先级 | 改进 | 状态 | 说明 |
+|--------|------|:--:|------|
+| P0 | 记忆分类体系 | ✅ | user/feedback/project/reference 4 类 + 关键词推断 |
+| P1 | 压缩摘要向量化 | ✅ | `_save_compressed_memories()`，压缩结果注入向量索引 |
+| P2 | LLM Rerank 混合检索 | ✅ | 向量粗筛 top-20 → LLM 精选 top-K，可选开关 |
+| P3 | 后台异步记忆提取 | ✅ | `_background_compress_and_save()` fire-and-forget，不阻塞对话 |
+| P4 | Auto Dream 每日整合 | ✅ | 凌晨 3:00 触发，合并相似记忆 + 生成每日摘要 |
+| P5 | 离线鲁棒性 | ✅ | 关键词分词器 + 离线搜索降级，Embedding API 不可用时自动兜底 |
+| P6 | 团队共享记忆 | ✅ | team_id 机制，记忆自动发布到团队池 + 跨 Agent 检索 |
+| P7 | 文件式记忆 MEMORY.md | ✅ | 本地 markdown 存储，YAML frontmatter，数据库不可用时可独立运行 |
+
+### 后续可借鉴
+
+- **push/pull 同步**：团队记忆的跨服务器同步（目前本地共享）
+- **子 Agent 记忆提取**：fork 独立 Agent 做更深度的记忆分析和关联
+
+---
+
+## 五、相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `backend/app/agent_runtime/memory.py` | 天工记忆管理核心（~720 行） |
+| `backend/app/agent_runtime/schemas.py` | 记忆配置模型 |
+| `backend/app/services/embedding_service.py` | Embedding 生成 + 离线关键词兜底 |
+| `backend/app/services/auto_dream_service.py` | Auto Dream 每日记忆整合（新增） |
+| `backend/app/core/compaction.py` | 三级对话压缩引擎 |
+| `D:\cd\claude-code\src\memdir\memdir.ts` | Claude Code 记忆目录管理 |
+| `D:\cd\claude-code\src\services\extractMemories\` | Claude Code 后台记忆提取 |
+| `D:\cd\claude-code\src\services\autoDream\` | Claude Code 夜间记忆整合 |