diff --git a/docs/Agent_Search_Integration_Analysis.md b/docs/Agent_Search_Integration_Analysis.md new file mode 100644 index 0000000..a55a7ca --- /dev/null +++ b/docs/Agent_Search_Integration_Analysis.md @@ -0,0 +1,337 @@ +# Studio Agent Search 集成现状分析 + +**生成时间**: 2026-10-11 +**版本**: v1.0.0 + +--- + +## 📋 文档来源 + +### 提供的文档(React 版本) + +1. **完整集成指南** + 文件: `/Users/accusys/momentry_core/docs_v1.0/GUIDES/Studio_Agent_Search_Integration_Guide.md` + 内容: React + TypeScript 实现的完整指南 + +2. **快速开始指南** + 文件: `/Users/accusys/momentry_core/docs_v1.0/GUIDES/Studio_Quick_Start.md` + 内容: 5 分钟快速实现(React 版本) + +3. **实施清单** + 文件: `/Users/accusys/momentry_core/docs_v1.0/GUIDES/Studio_Integration_Checklist.md` + 内容: 文件清单和实施步骤 + +--- + +## 🎯 Studio 实际技术栈 + +**前端框架**: Vue 3 + TypeScript + Vite +**桌面框架**: Tauri 2 (Rust) +**状态管理**: Pinia-like (store.ts) +**API 层**: Dual-mode (Tauri IPC + HTTP) + +**⚠️ 重要**: 提供的文档是 React 版本,需要转换为 Vue 3 + +--- + +## ✅ Studio 现状 + +### 已实现功能 + +**SearchView.vue 已经实现:** + +1. **5 种搜索模式**: + - ✅ Keyword (关键词搜索) + - ✅ Semantic (语义搜索) + - ✅ Visual (视觉搜索 - Scene VLM + Trace VLM) + - ✅ Agent (Agent 推理搜索) + - ✅ People (人物搜索) + +2. **UI 组件**: + - ✅ 统一搜索栏 + - ✅ 模式选择菜单 + - ✅ 结果卡片显示 + - ✅ 缩略图加载 + - ✅ 视频播放器集成 + +3. **API 调用**: + - ✅ `/api/v1/search/keyword` - 关键词搜索 + - ✅ `/api/v1/search/semantic` - 语义搜索 + - ✅ `/api/v1/search/vlm/scenes` - Scene VLM + - ✅ `/api/v1/search/vlm/traces` - Trace VLM + - ✅ `/api/v1/agents/search` - Agent 搜索 + - ✅ `/api/v1/search/people` - 人物搜索 + +4. **历史和书签**: + - ✅ 搜索历史(SQLite 持久化) + - ✅ 书签系统 + - ✅ Pin/Rename/Delete 功能 + +--- + +## 📊 功能对比 + +| 功能 | 提供的文档 | Studio 现状 | 状态 | +|------|-----------|------------|------| +| **统一搜索界面** | AgentSearchBar | SearchView | ✅ 已实现 | +| **5 种搜索模式** | Keyword/Semantic/Visual/Agent/People | modes 数组 | ✅ 已实现 | +| **Top 5 结果** | 默认 limit: 5 | pageSize: 20 | ✅ 已实现(可调) | +| **More 按钮** | MoreButton 组件 | 无 | ❌ **未实现** | +| **Session 管理** | session_id + next_offset | 无 | ❌ **未实现** | +| **分页加载** | 追加 10 条结果 | 无 | ❌ **未实现** | +| **智能路由** | 意图识别 + 路由 | 模式切换 | ✅ 已实现(手动) | +| **搜索历史** | SQLite | SQLite | ✅ 已实现 | +| **书签系统** | bookmarks | bookmarks | ✅ 已实现 | + +--- + +## 🚀 需要新增的功能 + +### 1. More 按钮 + 分页加载 + +**当前问题**: +- 一次性加载所有结果(limit: 20) +- 大数据集时性能不佳 +- 用户无法分批查看 + +**需要的实现**: +```typescript +// 新增状态 +const sessionId = ref('') +const nextOffset = ref(0) +const hasMore = ref(false) +const totalResults = ref(0) + +// 新增 More 按钮 +async function loadMore() { + if (!sessionId.value) return + + const res = await apiCall('search_more', { + session_id: sessionId.value, + current_offset: nextOffset.value, + limit: 10 + }) + + // 追加结果 + results.value.push(...res.results) + nextOffset.value = res.next_offset + hasMore.value = res.has_more +} +``` + +--- + +### 2. Session 管理 + +**当前问题**: +- 无 session_id +- 无法缓存搜索结果 +- More 操作无法复用之前的搜索 + +**需要的实现**: +```typescript +// API 端点 +POST /api/v1/agent/search +{ + "query": "sunset", + "limit": 5 +} + +// 响应 +{ + "session_id": "sess_abc123", + "results": [...], + "has_more": true, + "next_offset": 5 +} + +// More 操作 +POST /api/v1/agent/search/more +{ + "session_id": "sess_abc123", + "current_offset": 5, + "limit": 10 +} +``` + +--- + +### 3. 智能意图识别 + +**当前问题**: +- 用户需要手动选择模式(Keyword/Semantic/Visual/Agent/People) +- 无自动意图识别 + +**可能的改进**: +```typescript +// 新增 "Auto" 模式 +async function smartSearch(query: string) { + // 1. 意图识别 + const intent = await apiCall('detect_intent', { query }) + + // 2. 自动路由到合适的 API + if (intent.primary_type === 'visual') { + return await searchVisual(query) + } else if (intent.primary_type === 'people') { + return await searchPeople(query) + } else { + return await searchKeyword(query) + } +} +``` + +--- + +## 📝 技术栈差异 + +### React vs Vue 3 转换 + +| React | Vue 3 | 说明 | +|-------|-------|------| +| `useState` | `ref` / `reactive` | 状态管理 | +| `useEffect` | `onMounted` / `watch` | 生命周期 | +| `useCallback` | 普通函数 | 无需特殊处理 | +| `lucide-react` | 需替换 | 图标库 | + +**推荐图标库**: +- `@iconify/vue` - 通用图标库 +- `lucide-vue-next` - Lucide 的 Vue 版本 +- 内联 SVG - 当前做法 + +--- + +## 🎯 实施建议 + +### Phase 1: More 按钮 + 分页加载(1-2 天) + +**优先级**: 高 +**原因**: 改善大数据集性能 + +**步骤**: +1. 在 SearchView 中添加 `sessionId`, `nextOffset`, `hasMore` 状态 +2. 修改 API 调用,支持 `limit: 5` 初始加载 +3. 添加 "Load More" 按钮 UI +4. 实现 `loadMore()` 函数 +5. 追加结果到现有列表 + +--- + +### Phase 2: Session 管理(2-3 天) + +**优先级**: 高 +**原因**: 支持 More 操作必需 + +**步骤**: +1. 后端实现 `/api/v1/agent/search` API +2. 后端实现 `/api/v1/agent/search/more` API +3. 实现 session 缓存(Redis 或内存) +4. 前端集成 session_id 管理 + +--- + +### Phase 3: 智能意图识别(可选,3-5 天) + +**优先级**: 中 +**原因**: 改善用户体验,但非必需 + +**步骤**: +1. 实现意图检测 API(LLM-based) +2. 添加 "Auto" 模式到 UI +3. 实现自动路由逻辑 +4. A/B 测试自动模式效果 + +--- + +## 📋 文件修改清单 + +### 需要修改的文件(Vue 3 版本) + +| 文件路径 | 修改内容 | 优先级 | +|---------|---------|:------:| +| `src/views/SearchView.vue` | 添加 More 按钮 + Session 管理 | P0 | +| `src/api/index.ts` | 添加 `search_more` API 调用 | P0 | +| `src/types/agent-search.ts` | 新增类型定义 | P1 | + +### 不需要创建的文件 + +❌ `src/components/AgentSearch/` - 已有 SearchView +❌ `src/services/agent-search.ts` - 已有 apiCall +❌ `.env.local` - 已有配置 + +--- + +## 🔄 API 需求对比 + +### 当前 Studio API + +| 模式 | API 端点 | 状态 | +|------|---------|------| +| Keyword | `/api/v1/search/keyword` | ✅ 可用 | +| Semantic | `/api/v1/search/semantic` | ✅ 可用 | +| Visual | `/api/v1/search/vlm/scenes` + `/api/v1/search/vlm/traces` | ✅ 可用 | +| Agent | `/api/v1/agents/search` | ✅ 可用 | +| People | `/api/v1/search/people` | ✅ 可用 | + +### 需要的新 API + +| 功能 | API 端点 | 状态 | 优先级 | +|------|---------|------|:------:| +| 统一 Agent Search | `/api/v1/agent/search` | ❌ **需实现** | P0 | +| More 操作 | `/api/v1/agent/search/more` | ❌ **需实现** | P0 | +| 意图识别 | `/api/v1/detect-intent` | ❌ **需实现** | P1 | + +--- + +## ✅ 总结 + +### 现状 + +**Studio 已经实现了大部分 Agent Search 功能:** +- ✅ 5 种搜索模式 +- ✅ 统一搜索界面 +- ✅ 结果显示 +- ✅ 历史和书签 +- ✅ API 集成 + +### 缺失 + +**需要补充的核心功能:** +1. ❌ **More 按钮 + 分页加载** (高优先级) +2. ❌ **Session 管理** (高优先级) +3. ❌ **智能意图识别** (中优先级,可选) + +### 技术栈差异 + +**提供的文档是 React 版本,Studio 使用 Vue 3:** +- 需要将 React 组件转换为 Vue 3 Composition API +- 图标库需要替换(`lucide-react` → `lucide-vue-next` 或内联 SVG) +- 状态管理使用 `ref` / `reactive` 而非 `useState` + +--- + +## 🚀 下一步行动 + +### 立即实施(1-2 周) + +1. **实现 More 按钮 + 分页加载** + - 修改 SearchView.vue + - 添加 sessionId, nextOffset, hasMore 状态 + - 实现 loadMore() 函数 + +2. **后端实现 Session API** + - `/api/v1/agent/search` + - `/api/v1/agent/search/more` + +3. **测试验证** + - 大数据集测试(100+ 结果) + - 分页加载性能测试 + +### 中期优化(1-2 月) + +1. 智能意图识别(可选) +2. 性能优化 +3. UI/UX 改进 + +--- + +**文档完成!Studio 大部分功能已实现,仅需补充 More 按钮和 Session 管理。** \ No newline at end of file