Skip to content

v2.7.0

Choose a tag to compare

@Zoroaaa Zoroaaa released this 04 Nov 06:33

Added - AI Agent 全面增强:Planning 层、跨会话记忆、交互体验升级 🧠

核心功能 - Agent 能力增强(4 项重大改进)

1. Planning 层——结构化任务规划(1.1)

  • agentEngine.ts 改动

    • 新增 ExecutionPlan 和 ExecutionPlanStep 接口定义
      interface ExecutionPlan {
        goal: string;
        steps: Array<{
          id: string; // step-1, step-2 ...
          description: string; // 人类可读描述
          toolHint?: string; // 预期使用的工具
          dependsOn?: string[]; // 依赖哪些步骤完成
          status: 'pending' | 'running' | 'done' | 'skipped';
        }>;
        estimatedToolCalls: number;
      }
    • 新增 planPhase() 方法:复杂任务触发时让 LLM 输出结构化 JSON 计划
    • 新增 formatPlanContext() 方法:将计划状态注入每轮执行上下文
    • 每步完成后更新 step.status,超出 maxToolCalls 时优先完成当前步骤再暂停
    • 意图复杂度判断:在 run() 入口处通过关键词 + LLM 快速判断是否为多步任务
  • SSE 新增 chunk 类型

    • { type: 'plan', plan: ExecutionPlan, done: false } — 推送完整执行计划
    • { type: 'plan_step_update', stepId: string, status: string, done: false } — 步骤状态更新
    • 前端可实时渲染执行计划进度条(PlanProgressBar 组件)

2. 跨会话语义记忆系统(1.2)

  • 新增 agentMemory.ts 模块

    • 双存储架构:D1(结构化查询)+ Vectorize(语义检索)
    • 命名空间隔离:memory:{userId} 区别于文件索引的 file:{userId}
    • MemoryFact 类型支持 4 种记忆类型:operation / preference / path / file_ref
  • Memory 写入(对话结束时触发)

    • 用 LLM 从对话全文 + 工具调用记录中提取 3-5 条结构化事实
    • 写入 D1 ai_memories 表:id, userId, sessionId, type, summary, embeddingId, createdAt
    • 使用 @cf/baai/bge-m3 模型生成向量嵌入
  • Memory 召回(每次对话开始时)

    • 在 agentEngine.run() 里 RAG 检索时并行召回 memory(top-3)
    • 召回策略:时间优先 + 向量语义匹配兜底
    • 拼入 system prompt 末尾的 [历史记忆] 区域(低权重)
    • 置信度低时不注入,避免噪音
  • 新增 API

    • GET /api/ai/memories:列出用户记忆条目(支持 type 筛选、分页)
    • DELETE /api/ai/memories/:id:删除单条记忆
  • 前端 AISettings.tsx 新增「记忆管理」Tab

    • 记忆类型筛选(operation/preference/path/file_ref)
    • 分页浏览,单条删除操作
    • 显示总记忆条数和空状态引导

3. 工具定义 Few-shot Examples(1.3)

  • types.ts 扩展 ToolDefinition schema

    • 新增 examples?: Array<{ user_query: string; tool_call: object }> 字段
    • 为高频/易误用工具补充 2-3 个 examples(search_files、smart_search、filter_files、draft_and_create_file、move_file 等)
    • examples 在 prompt-based 路径中注入到 PROMPT_BASED_SYSTEM_PROMPT
  • 工具数量扩展至 100+

    • WRITE_TOOLS 集合包含 40+ 个写操作工具标记
    • 覆盖文件操作、标签管理、分享管理、版本管理、笔记管理、权限管理、存储桶管理等模块

4. 长任务队列打通——批量操作增强(1.4)

  • fileops.ts 新增批量工具

    • batch_move:批量移动文件(超过阈值自动入队)
    • batch_delete:批量删除文件(超过阈值自动入队)
    • BATCH_THRESHOLD = 20(文件数超过此值时触发队列模式)
  • 队列集成

    • 超过阈值时调用 enqueueAgentBatchOperation() 写入任务队列
    • 返回 { status: 'queued', taskId, message, totalFiles, estimatedMinutes }
    • 队列失败时自动降级为同步执行
    • 支持 agent_batch 任务类型的进度追踪

核心功能 - 交互体验提升(3 项)

5. 文件拖拽注入(2.2)

  • AIChat.tsx 改动
    • 新增 onDragOver / onDragLeave / onDrop 事件处理器
    • 用户从文件列表拖拽文件到对话框 → 自动填入 contextFileIds
    • 消息框显示「附带文件:xxx.pdf」Chip 样式
    • 支持多文件拖拽,显示已引用文件列表

6. @文件快捷引用(2.2)

  • AIChat.tsx 改动
    • 输入 @ 触发文件搜索下拉框(debounce 300ms)
    • 下拉框展示搜索结果文件列表(名称 + 路径 + 图标)
    • 键盘导航支持(ArrowDown/ArrowUp/Enter 选择)
    • 选择后注入 fileId 到引用列表,消息框显示 Chip
    • 点击 Chip 可移除已引用文件
    • 参考 LobeChat 的 @mention 交互设计

7. 对话消息引用/追问(2.2)

  • AIChat.tsx 改动
    • 新增 quotedMessage state(存储被引用的消息 id/content/role)
    • 右键/长按消息弹出上下文菜单,选择「引用此消息」
    • 引用后输入框顶部显示引用内容预览条(可关闭)
    • 发送时自动拼接 [引用]: 原始消息内容\n\n用户问题 到 finalQuery
    • Agent 可针对历史消息进行追问和上下文延续

核心功能 - 工程优化(3 项)

8. Reasoning 展示优化(2.3)

  • ReasoningSection.tsx 改动
    • 默认折叠,streaming 时自动展开并滚动
    • 完成后保持折叠,标题显示 reasoning 总字数(「思考了 xxx 字」)
    • 视觉上与正文区分:左侧竖线 + 半透明背景

9. 模型熔断器(3.3)

  • 新增 circuitBreaker.ts 模块

    • 三态状态机:closed(正常)→ open(熔断)→ half-open(半开探测)
    • FAILURE_THRESHOLD = 3(连续失败次数阈值)
    • RECOVERY_TIMEOUT_MS = 10 分钟(熔断恢复时间)
    • 错误分类:model_error 触发熔断,network_timeout 不触发
    • 导出函数:classifyError()、isModelAvailable()、recordModelFailure()、recordModelSuccess()、getModelHealthStatus()
  • agentEngine.ts 集成熔断器

    • Native 路径:循环前检查 isModelAvailable(),失败时 recordModelFailure(),成功时 recordModelSuccess()
    • Prompt-Based 路径:同样的 4 个集成点
    • 熔断打开时自动阻止对故障模型的调用

10. 工具定义统一规范(3.1)

  • ToolDefinition schema 标准化
    • 统一必填字段:name / description / parameters / examples(可选)/ category
    • 所有工具补齐 description 和 examples 字段
    • types.ts 中 ToolDefinition 接口与 agentTools/types.ts 保持一致

Fixed - 缺陷修复

  • vectorizeQuery 参数类型对齐:agentEngine.ts 和 agentMemory.ts 中 _vectorizeQuery 参数类型统一为 Record<string, string | number | boolean>
  • Vectorize.query 调用修正:returnMetadata 从 'id' 改为 true,filter 参数添加 as any 类型断言
  • circuitBreaker 集成修复:从完全隔离状态(无任何导入)改为完整集成到 agentEngine.ts 的 native 和 prompt-based 两条路径
  • AISettings X 图标导入:memory tab 新增后补充 lucide-react 的 X 图标导入

Technical Details

  • 新增文件:
    • apps/api/src/lib/ai/agentMemory.ts — 跨会话记忆管理模块
    • apps/api/src/lib/ai/circuitBreaker.ts — 模型调用熔断器
  • 修改文件:
    • apps/api/src/lib/ai/agentEngine.ts — Planning 层、熔断器集成、记忆召回、SSE plan 事件
    • apps/api/src/lib/ai/agentTools/types.ts — ToolDefinition examples 字段
    • apps/api/src/lib/ai/agentTools/fileops.ts — batch_move/batch_delete 工具
    • apps/web/src/pages/AIChat.tsx — 拖拽注入、@mention、消息引用
    • apps/web/src/pages/AISettings.tsx — 记忆管理 Tab
  • 数据库变更:
    • 新增 ai_memories 表(id, userId, sessionId, type, summary, embeddingId, createdAt)

Fixed - 安全性与稳定性修复(22 项 Bug 修复 + 中断处理)🛡️

TypeScript 编译通过 (0 错误),共修改 14 个文件。

🔴 P0 — Critical 安全漏洞(4/4 已修复)

Bug 文件 修复内容
#1 跨用户数据泄露 routes/files.ts, routes/share.ts collectFolderFiles 增加 eq(files.userId, userId) 过滤 + 递归传递,防止用户 A 通过文件夹遍历访问用户 B 的文件
#2 WebDAV OOM 崩溃 routes/webdav.ts DELETE/MOVE/COPY 操作改用 like(files.path, ...) SQL 查询,删除全量加载 + filter(startsWith) 的内存操作模式
#3 时序攻击(密码比对) routes/share.ts 新增 timingSafeEqual() HMAC 常量时间比较函数 + KV 5分钟窗口10次限流(含密码错误计数+成功清除机制)
#4 CSRF 绕过 src/index.ts CORS fallback 从返回 allowedOrigins[0] 改为返回 undefined(拒绝未知 origin,防止跨站请求伪造)

🟠 P1 — High 严重问题(6/6 已修复)

Bug 文件 修复内容
#5 Token 泄露(缓存) routes/preview.ts Query Token 认证路径增加 Cache-Control: private, no-store, no-cache, must-revalidate,防止 CDN/代理层缓存敏感认证信息
#6 sortBy SQL 注入 routes/files.ts 新增 ALLOWED_SORT_FIELDS 白名单 + switch 安全映射(替代动态 files[sortBy] 字段访问)
#7 整文件内存 OOM routes/share.ts 流式下载改为 s3Get() → 直接透传 Response body,不再 fetchFileContent 全量读入内存
#8 TOCTOU 竞态条件 routes/share.ts 下载计数改用 原子 CAS:UPDATE ... WHERE id=? AND (limit IS NULL OR count < limit),单条 SQL 完成检查+递增
#10 WebDAV 暴力破解 routes/webdav.ts 新增 IP 维度 KV 速率限制:每 IP 5分钟内最多 10 次失败,超限返回 HTTP 429
#11 直链滥用 routes/directLink.ts 新增 IP+Token 维度速率限制(60次/分钟)+ Cache-Control 改为 private 防止缓存

🟡 P2 — Medium 中等问题(6/6 已修复)

| Bug | 文件 | 修复内容 |
| ---------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------- |
| #15 广播过滤器错误 | routes/admin.ts | active 用户过滤从错误的 eq(users.role, 'user') 修正为 eq(users.emailVerified, true) |
| #16 重复错误码 | packages/shared/src/constants/errorCodes.ts | TOKEN_EXPIRED 从重复的 A001 改为唯一码 A006 |
| #17 类型安全 | routes/files.ts, routes/admin.ts | any[] 替换为 Array<ReturnType<typeof isNull> | ReturnType<typeof eq>> 等具体类型 |
| #21 权限映射重复 | lib/permissionService.ts | 提取模块级常量 PERMISSION_LEVELS,消除两处重复定义 |
| #22 缩略图参数无效 | routes/preview.ts | width/height 增加 clamp(16, 2048) 边界校验 + Cache-Control 改为 private + 标注 X-Thumbnail-Note |

🔵 P3 — Low 低优先级(2/2 已修复)

Bug 文件 修复内容
#18 ESM require 冗余 lib/fileService.ts 移除冗余 require('./fileContentHelper')(顶部已有 ESM import)
#20 魔术数字 routes/auth.ts 10737418240 提取为命名常量 DEFAULT_STORAGE_QUOTA_BYTES = 10 * 1024 * 1024 * 1024

🔄 AI 对话中断恢复(流式输出稳定性)

问题:当 AI 对话流式输出被中断(卡死或手动停止)时,已输出的内容会消失。

根因分析:

  1. API 层 chatStream 函数在中断时未正确处理 AbortError
  2. 前端组件中断时缺少明确的 aborted 状态标记

修复内容:

层级 文件 修复内容
API 层 services/api.ts 请求开始前检查 signal.aborted;流式读取循环中检查中断信号及时取消 reader;统一抛出标准 DOMException('AbortError')
类型定义 components/ai/types.ts 新增 aborted?: boolean 字段标记消息是否被中断
前端组件 pages/AIChat.tsx 中断时保留已输出内容(content: m.content || '');设置 aborted: true 标记;显示"输出已中断"提示;被中断消息显示"重新生成"按钮

效果:

  • ✅ 已输出的内容完整保留
  • ✅ 显示明确的中断状态提示
  • ✅ 用户可点击"重新生成"继续对话
  • ✅ 消息列表展示 mentionedFiles 引用文件 Chip

⚡ 已修复 — 额外稳定性问题(7 项)

# 问题 严重程度 位置 修复方案
1 storageUsed 竞态条件 🔴 高危 tasks.ts, downloads.ts 统一调用原子方法 updateUserStorage(),三处先读后写全部替换为 MAX(0, COALESCE(...) + delta) 原子写法
2 文件列表无分页 🔴 高危 files.ts L568 新增 SQL ORDER BY + .limit().offset() 分页,前端传 page/limit 参数,消除 D1 1000 行截断和内存排序
3 softDelete 不释放 storageUsed 🟡 中危 fileService.ts 软删除时立即扣减 storageUsed,不再等待 cron 硬删除
4 JWT 无 refresh token 🟡 中危 认证系统 新增 refresh token 路由,KV session TTL 与 JWT 解耦,支持静默续期
5 Analytics 全量扫描 🟡 中危 analytics.ts 存储分析改为 SQL GROUP BY mime_type, SUM(size) 聚合,消除全量拉取
6 分享上传绕过配额 🟡 中危 share.ts 上传路径 上传时增加 owner 的 storageUsed + uploadSize > storageQuota 校验
7 LIKE 搜索未转义特殊字符 🔵 低危 files.ts L664 搜索词中 % 和 _ 字符自动转义为 \% 和 \_

⚡ 性能优化(5 项)

  1. 文件列表排序移至 SQL:从 JS 内存 .sort() 改为 SQL ORDER BY,配合分页消除 D1 截断导致的排序不完整
  2. AI 任务队列背压控制:aiTaskQueue.ts 新增 per-user 并发槽位上限,防止批量索引打满 Workers AI Rate Limit
  3. cleanup.ts 分批处理:硬删除从全局扫描改为分批处理(每批 100 条),避免文件多时 cron 超时
  4. WebDAV 原子化 storageUsed:与 tasks.ts 统一使用 updateUserStorage() 原子方法,消除读旧值竞态
  5. 向量索引断点续传:批量索引记录最后处理位置,中断后可从断点恢复

🆕 新增功能(6 项)

优先级 功能 实现说明
🔴 高 文件夹大小统计 文件夹详情展示递归计算的占用空间大小,前端 FileDetailPanel 显示
🔴 高 增量向量索引 监听文件上传事件自动触发向量索引,新文件立即可被 AI 搜索到
🟡 中 Zip 打包下载文件夹 前端新增入口调用 zipStream.ts,支持文件夹打包下载
🟡 中 文件维度访问日志 文件详情面板新增访问记录 Tab,展示谁在何时访问了该文件
🟢 低 标签全局管理页 AISettings / 标签管理页面,支持标签合并、重命名、批量删除
🟢 低 AI 对话导出(Markdown/PDF) 对话历史支持一键导出为 Markdown 或 PDF 格式

Technical Details(Bug 修复部分)

  • 安全修复文件:
    • apps/api/src/routes/files.ts — 跨用户数据泄露修复(userId 过滤)+ sortBy SQL 注入防护(白名单映射)
    • apps/api/src/routes/share.ts — 时序攻击防护(timingSafeEqual)+ 流式下载 OOM 修复 + TOCTOU 原子计数
    • apps/api/src/routes/webdav.ts — OOM 修复(SQL 查询替代全量加载)+ 暴力破解限流
    • apps/api/src/routes/preview.ts — Token 缓存泄漏修复 + 缩略图参数校验
    • apps/api/src/routes/directLink.ts — 直链滥用限流
    • apps/api/src/routes/admin.ts — 广播过滤器修正
    • apps/api/src/index.ts — CSRF 绕过修复(CORS fallback)
    • packages/shared/src/constants/errorCodes.ts — 错误码去重
    • apps/api/src/lib/fileService.ts — ESM require 冗余移除
    • apps/api/src/lib/permissionService.ts — 权限常量提取
    • apps/api/src/routes/auth.ts — 魔术数字命名常量化
  • AI 中断恢复文件:
    • apps/web/src/services/api.ts — AbortError 标准处理 + signal 检查
  • apps/web/src/components/ai/types.ts — aborted 字段类型定义
  • apps/web/src/pages/AIChat.tsx — 中断状态保留 + UI 提示 + 重新生成按钮
  • 额外稳定性修复文件:
    • apps/api/src/routes/tasks.ts — storageUsed 竞态条件修复(3处原子方法替换)
    • apps/api/src/routes/downloads.ts — storageUsed 竞态条件修复(原子方法替换)
    • apps/api/src/lib/fileService.ts — softDelete 立即扣减 storageUsed + LIKE 搜索转义
    • apps/api/src/routes/auth.ts — refresh token 路由新增
    • apps/api/src/routes/analytics.ts — SQL GROUP BY 聚合替代全量扫描
    • apps/api/src/routes/share.ts — 上传路径增加 owner storageUsed 配额校验
    • apps/api/src/lib/ai/aiTaskQueue.ts — per-user 并发槽位背压控制 + 断点续传
    • apps/api/src/lib/cleanupService.ts — 分批处理硬删除
  • 新功能文件:
    • 文件夹大小统计:lib/fileService.ts 新增递归计算方法 + 前端 FileDetailPanel 展示
    • 增量向量索引:文件上传事件监听器自动触发索引
    • Zip 打包下载:前端入口 + zipStream.ts 集成
    • 文件访问日志:文件详情面板新增 Tab
    • 标签全局管理页:AISettings 新增标签管理模块
    • AI 对话导出:对话历史导出为 Markdown/PDF 功能