Repository navigation
v2.7.0
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 改动
- 新增
quotedMessagestate(存储被引用的消息 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 个集成点
- 熔断打开时自动阻止对故障模型的调用
- Native 路径:循环前检查
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 对话流式输出被中断(卡死或手动停止)时,已输出的内容会消失。
根因分析:
- API 层
chatStream函数在中断时未正确处理AbortError - 前端组件中断时缺少明确的
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 项)
- 文件列表排序移至 SQL:从 JS 内存
.sort()改为 SQLORDER BY,配合分页消除 D1 截断导致的排序不完整 - AI 任务队列背压控制:
aiTaskQueue.ts新增 per-user 并发槽位上限,防止批量索引打满 Workers AI Rate Limit - cleanup.ts 分批处理:硬删除从全局扫描改为分批处理(每批 100 条),避免文件多时 cron 超时
- WebDAV 原子化 storageUsed:与 tasks.ts 统一使用
updateUserStorage()原子方法,消除读旧值竞态 - 向量索引断点续传:批量索引记录最后处理位置,中断后可从断点恢复
🆕 新增功能(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 功能
- 文件夹大小统计: