# 高级会话检索发现与决策

## 用户边界

- 现有检索必须保留，不改输入行为和本地标题/项目/路径/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 并在成功写盘后触发，避免频繁同步重建。

## 跨层数据流

```text
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 移动端。