shiyue/cc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d9db66ca8fd7233bbc3ecac5790da942cc4ec70d
cc-web/.planning/advanced-conversation-search/findings.md

5.8 KiB
Raw Blame History

高级会话检索发现与决策

用户边界

  • 现有检索必须保留，不改输入行为和本地标题/项目/路径/ID 过滤。
  • 在现有检索框旁增加高级检索按钮。
  • 高级检索参照用户提供的暗色结果页，结合前一轮正文索引分析落地。

视觉论点

在不打扰现有侧栏检索的前提下，打开一层沉静、近乎无边框的检索工作台，用青蓝标题、暖黄命中标记和克制分隔线建立快速扫读节奏。

内容计划

  1. 顶部：返回按钮、长查询输入、清空按钮和回车提示。
  2. 控制：相关优先/最新优先，整词/包含两组切换。
  3. 状态：结果数、耗时、索引构建/错误状态。
  4. 结果：会话标题、项目/角色来源、最多两段摘要、右对齐时间和细分隔线。
  5. 空态：未输入、无结果、索引构建中和查询失败。

交互论点

  • 入口点击后使用 140ms 淡入和轻微上移，形成从侧栏到检索工作台的空间切换。
  • 查询采用约 200ms debounce；旧响应由 requestId 丢弃，结果更新只做轻微透明度过渡。
  • 点击摘要打开原会话，必要时补载历史页，定位后做一次短暂暖色高亮。

参考图量化

  • 源图：733 × 673 RGBA PNG。
  • 顶栏约 58px；左右内容安全区约 46–48px。
  • 控制行位于顶栏下约 22px，采用低对比胶囊，不使用独立卡片。
  • 状态行与第一条结果间距约 18px；结果之间使用 1px 低对比分隔线。
  • 标题使用高饱和青蓝，正文接近中性白，命中使用暖黄底深色字，时间靠右且弱化。
  • 面板是单一连续表面，不叠加卡片阴影；参考图中的圆角仅属于外围窗口，不复制成结果卡片。

参考区域映射

参考区域 目标 DOM CSS 责任 资产
顶部搜索栏 .advanced-search-header 高度、输入基线、返回/清空按钮 无
排序/匹配切换 .advanced-search-toolbar 分段控件、选中态 无
结果统计 #advanced-search-status 弱化状态文案 无
结果列表 #advanced-search-results 连续流、分隔线、滚动 无
命中标题/摘要 .result-title/.result-snippet 青蓝标题、暖黄 mark、截断 无
侧栏入口 #advanced-search-open 紧邻现有输入、独立 tooltip 无

资产台账

  • 原始附件：sessions/_attachments/237582ef-4157-4175-84fa-38629613df7f.png
  • 归档：.trellis/tasks/08-03-advanced-conversation-search/references/source-assets/advanced-search-reference.png
  • SHA-256：39e5b93d26deca64ea88a46b09bed7f7c47d2af733e8f2f857a9d35fc7895692
  • 用途：仅作为视觉对照，不进入产品运行时。

已确认技术基线

  • 当前 session_list 只携带元数据，完整消息按会话加载。
  • 当前可检索 user/assistant 正文约 4.26 MB，内存全量子串扫描约 0.98ms。
  • 项目运行于 Node 18，发布使用 Bun baseline 单文件；首期采用零依赖内存索引和派生缓存。

代码接入基线

  • codebase-memory-mcp 的 home-cc-web 索引 ready（4417 节点、9212 边）。
  • 服务端模块统一使用 CommonJS 工厂函数，可新增 lib/session-search-index.js 并在 server.js 顶部 require。
  • WebSocket 消息 switch 在 load_session/load_history_page/delete_session/rename_session 附近，新增 search_sessions 可保持普通会话列表协议不变。
  • 前端 handleServerMessage 已集中处理 session_info/session_history_chunk，高级检索结果可新增独立 case；openSession(sessionId, options) 已支持 options，适合作为命中定位入口。
  • markSessionMessageElement 已给消息 DOM 写入 data-message-index；历史分页响应包含 historyBaseIndex，可以稳定定位旧消息。
  • saveSession 有大量调用者，索引更新必须按 sessionId debounce 并在成功写盘后触发，避免频繁同步重建。

跨层数据流

sessions/*.json
  → SessionSearchIndex 规范化 user/assistant 文本
  → 内存文档集合 + sessions/_search/index-v1.json 派生缓存
  → search_sessions 请求验证
  → session_search_results 受限摘要
  → 高级检索结果流
  → openSession + load_session(targetMessageIndex)
  → data-message-index 定位与高亮
  • 服务端入口负责 query、limit、sort、matchMode 校验；前端只发送枚举值并丢弃过期 requestId。
  • 原始会话文件是唯一事实来源；缓存损坏只能降级/重建，不能反向覆盖会话。
  • Trellis backend/frontend 细则当前仍为占位模板，本次以现有 CommonJS、集中消息 switch、原生 DOM/CSS 和回归脚本的实际约定为准。

并行审计结论

  • 高级检索面板放在 .chat-main 内并使用局部 absolute overlay；桌面保留侧栏，移动端点击入口后关闭抽屉。不要复用全局 modal overlay。
  • 现有 sessionSearchQuery、syncSessionSearchUi、getSessionSearchText、sessionMatchesSearch、renderSessionList 和原 input/Escape/clear 事件均保持原样；高级检索使用完全独立状态。
  • 搜索缓存的文件签名使用 dev/ino/size/mtimeMs；每次启动对账 root *.json 集合，原子保存导致 inode 变化时自然失效，删除项被 prune。
  • 初次构建和变化扫描分批让出事件循环；查询只访问内存文档，不在请求路径解析全部 JSON。
  • 高级面板 z-index 位于聊天内容之上、全局 modal 之下；结果区自身滚动，避免落进 .messages-wrap 的 overflow 裁切。
  • 精确定位必须返回 sessionId + messageIndex；前端在 renderMessages/prependHistoryMessages 后查找 data-message-index，服务端按 targetMessageIndex 增加首次加载的历史预取块。
  • 修改 style.css/app.js 后同步推进 index.html cache-bust，并覆盖 dark/gilded/wasteland 与 768px 移动端。