# MCP 会话显示隐藏开关计划

## 目标

在侧栏搜索框右侧增加一个图标按钮，用于显示或隐藏由 MCP 创建的会话；正常会话始终可见，并完整覆盖状态记忆、搜索临时显示与运行态例外。

## 当前阶段

阶段 5：交付

## 执行步骤

1. 审查需求与实现计划
2. 补充会话过滤与图标状态的失败回归测试
3. 实现持久化状态与 MCP 会话过滤逻辑
4. 接入搜索框右侧图标及主题响应式样式
5. 运行定向测试并修复问题
6. 执行完整回归与差异审查
7. 清理临时跟踪文件并记录交付

## 阶段

### 阶段 1：需求与计划审查

- [x] 通过逐项访谈确认产品边界
- [x] 定位现有会话列表、搜索、分组和 MCP 标识逻辑
- [x] 完成独立计划审查
- **状态：** complete

### 阶段 2：测试先行

- [x] 为过滤规则、状态例外、搜索覆盖和图标契约补充失败测试
- [x] 运行新增测试并确认修改前失败
- **状态：** complete

### 阶段 3：实现

- [x] 增加本地持久化的显示状态
- [x] 在列表派生数据阶段过滤 MCP 会话
- [x] 接入无文字图标按钮、无障碍状态和主题样式
- **状态：** complete

### 阶段 4：验证

- [x] 运行定向测试、语法检查与完整回归
- [x] 审查变更差异、工作区状态及项目规范符合性
- **状态：** complete

### 阶段 5：交付

- [x] 更新持久计划与 Trellis 记录
- [x] 清理临时 TODO CSV
- **状态：** complete

## 已确认需求

- 过滤对象仅为 `createdFromKind === 'mcp'` 的会话，正常会话始终显示。
- 隐藏模式仍保留当前打开或 `isRunning` 的 MCP 会话；其他 MCP 会话隐藏。
- 搜索时临时恢复全部 MCP 会话参与匹配，清空搜索后恢复隐藏规则。
- 按钮位于搜索框右侧并与高级搜索并排，仅显示一个状态图标。
- 首次默认显示；用户切换结果保存在本机浏览器，刷新和下次打开继续沿用。
- 没有可见会话的项目分组不渲染。

## 技术决策

| 决策 | 理由 |
|---|---|
| 在 `getVisibleSessions()` 之后、搜索匹配之前派生列表可见性 | 保持服务端快照和缓存完整，只影响侧栏展示 |
| 搜索查询非空时绕过 MCP 隐藏过滤 | 满足主动搜索可以找回隐藏会话的需求 |
| 使用单一 `localStorage` 布尔偏好，缺失时按显示处理 | 与首次默认显示和跨刷新记忆一致 |
| 图标按钮维护 `aria-pressed`、动态 `title`/`aria-label` | 只有图标时仍能清晰表达当前状态和点击动作 |
| 将显示偏好纳入列表结构签名或切换时强制失效 | 避免现有结构签名优化跳过重新渲染 |

## 风险与验证重点

- 置顶 MCP 会话也应服从隐藏规则，除非它是当前会话或运行中。
- 当前会话从 MCP 状态切换后，侧栏不能丢失当前定位。
- 新快照把会话从运行中更新为已完成时，隐藏模式应自动移除该条目。
- 所有主题及窄屏布局不得挤压搜索输入框或高级搜索按钮。
- 不引入服务端状态或协议改动。

## 错误记录

| 错误 | 尝试 | 处理 |
|---|---:|---|
| 完整历史分叉不能同时指定 worker 类型 | 1 | 改为 `fork_turns: none` 并在任务中显式提供上下文 |
| `wait_agent` 等待值低于 10 秒下限 | 1 | 改用 10 秒以上等待值 |
| 高级搜索回归要求保留荒原主题精确选择器 | 1 | 恢复 `.session-search-row .advanced-search-open`，新按钮使用独立规则 |
| Firefox 无头渲染图形后端超时且未生成截图 | 1 | 改用软件渲染/Xvfb 再试一次，失败则降级到计算布局与静态契约 |
| 完整回归 Codex App steer 场景等待 WebSocket 消息超时 | 1 | 失败位于既有 server/mock 集成链路，与前端侧栏变更隔离；保留定向回归与审查证据 |