mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-03-28 22:33:05 +08:00
f0e8ba1d8f
* feat: init session manger * feat: persist selected app to localStorage - Save app selection when switching providers - Restore last selected app on page load * feat: persist current view to localStorage - Save view selection when switching tabs - Restore last selected view on page load * styles: update ui * feat: Improve macOS Terminal activation and refactor Kitty launch to use command with user's default shell. * fix: session view * feat: toc * feat: Implement FlexSearch for improved session search functionality. * feat: Redesign session manager search and filter UI for a more compact and dynamic experience. * refactor: modularize session manager by extracting components and utility functions into dedicated files. * feat: Enhance session terminal launching with support for iTerm2, Ghostty, WezTerm, and Alacritty, including UI and custom configuration options. * feat: Conditionally render terminal selection and resume session buttons only on macOS.
269 lines
9.2 KiB
Markdown
269 lines
9.2 KiB
Markdown
# 会话管理（Session Manager）需求文档（PRD / Markdown）
|
||
|
||
> 目标：对 **Codex / Claude Code** 的本地会话记录进行可视化管理，并提供“一键复制 / 一键终端恢复”能力。
|
||
> 范围：**v1 仅 macOS**，但必须预留多平台扩展入口。
|
||
|
||
---
|
||
|
||
## 1. 背景与问题
|
||
|
||
开发者同时使用 Codex CLI、Claude Code 时，常见痛点：
|
||
- 会话记录落在本地不同位置，**难以发现/检索**
|
||
- 找到会话后，恢复命令需要记忆或翻历史，**恢复成本高**
|
||
- 恢复时经常忘了当时的工作目录，导致命令在错误目录运行
|
||
- 希望在常用终端（macOS Terminal、kitty 等）中直接恢复，提高效率
|
||
|
||
---
|
||
|
||
## 2. 目标与非目标
|
||
|
||
### 2.1 Goals（v1 必达）
|
||
1. 扫描并展示本机所有 Codex / Claude Code 会话：列表 + 详情（会话内容）
|
||
2. 支持恢复会话：
|
||
- 复制恢复命令（按钮）
|
||
- 复制会话目录（按钮，若能获取/推断）
|
||
- 可选：直接在终端执行恢复（macOS Terminal、kitty；可扩展）
|
||
3. 仅 macOS 支持，但代码结构需支持未来扩展 Windows/Linux
|
||
|
||
### 2.2 Non-Goals（v1 不做）
|
||
- 不新增/依赖云端 API；默认不上传任何内容
|
||
- 不承诺解析所有 provider 的全部内部格式（尽量兼容、可配置、可降级）
|
||
- 不做复杂的团队协作/分享/同步（后续版本再考虑）
|
||
|
||
---
|
||
|
||
## 3. 用户画像与使用场景
|
||
|
||
### 3.1 典型用户
|
||
- 高频使用多个 AI 编程工具的工程师/技术负责人/PM
|
||
- 多项目、多分支并行，频繁“中断—恢复—继续推进”
|
||
|
||
### 3.2 核心场景（Top）
|
||
1. **找回会话**：我记得一个会话讨论过某段逻辑 → 搜索关键词 → 打开详情
|
||
2. **快速恢复**：我想继续昨天的会话 → 复制恢复命令 / 一键在终端恢复
|
||
3. **回到正确目录**：恢复前先复制目录或自动 cd 到目录
|
||
|
||
---
|
||
|
||
## 4. 产品形态与信息架构
|
||
|
||
### 4.1 信息架构
|
||
- Session Manager
|
||
- 会话列表（List）
|
||
- 会话详情（Detail）
|
||
- 设置（Settings）
|
||
- Provider 配置（路径/启用禁用）
|
||
- 终端集成（默认终端、权限提示、降级策略）
|
||
- 索引与隐私选项（是否缓存、缓存大小、敏感信息遮罩）
|
||
|
||
---
|
||
|
||
## 5. 功能需求（Functional Requirements）
|
||
|
||
### 5.1 会话发现与索引（Discovery & Indexing）
|
||
**FR-1** 扫描本地会话数据源，生成统一的 Session 列表
|
||
- 支持 Provider：Codex、Claude Code（可扩展）
|
||
- 支持全量扫描 + 增量更新
|
||
- 支持缺失/异常文件的容错（不中断 UI）
|
||
|
||
**FR-2** 本地索引（Cache/DB）
|
||
- 用于加速列表加载与搜索
|
||
- 索引字段至少包含：sessionId、provider、lastActiveAt、projectDir(可空)、summary(可空)、filePath(可空)
|
||
|
||
**FR-3** 数据源路径探测（可配置 + 多候选）
|
||
- 默认使用常见路径；允许用户在 Settings 覆盖
|
||
- 若无法探测到 provider 安装/数据目录：在 UI 显示未启用/不可用状态，但不报错崩溃
|
||
|
||
---
|
||
|
||
### 5.2 会话列表（List）
|
||
**FR-4** 列表展示字段（建议最小集）
|
||
- Provider（Codex / Claude）
|
||
- Session 标识（id/short id）
|
||
- 最近活跃时间（lastActiveAt）
|
||
- 目录（projectDir，若未知显示 “Unknown”）
|
||
- 摘要（summary：最后一条/首条截断或规则生成）
|
||
|
||
**FR-5** 列表交互
|
||
- 搜索（跨会话，关键词匹配 transcript/summary/目录）
|
||
- 过滤：Provider、是否有目录、时间范围
|
||
- 排序：最近活跃（默认）、最早、按目录
|
||
|
||
**FR-6** 空态/异常态
|
||
- 未发现任何会话：给出“如何启用/设置路径”的指引
|
||
- 发现会话但无法解析内容：列表仍可显示基本信息，并在详情页提示“解析失败”
|
||
|
||
---
|
||
|
||
### 5.3 会话详情（Detail）
|
||
**FR-7** 会话内容展示
|
||
- 时间线展示消息（role：user/assistant/tool 等）
|
||
- 支持在当前会话内搜索 + 高亮
|
||
- 展示元信息：
|
||
- provider、sessionId、创建/最近活跃时间
|
||
- projectDir（可空）
|
||
- 原始文件路径（可选显示，便于 debug）
|
||
|
||
**FR-8** 性能策略
|
||
- 默认按需加载（打开详情才加载全文）
|
||
- 对超长 transcript 支持分页/虚拟列表（防止卡顿）
|
||
|
||
---
|
||
|
||
### 5.4 恢复能力（Resume / Restore）
|
||
#### 5.4.1 复制恢复命令（必做）
|
||
**FR-9** “复制恢复命令”按钮
|
||
- 根据 provider 生成恢复命令（模板可配置）
|
||
- 点击后写入剪贴板，并 toast 提示成功
|
||
|
||
> 说明：不同版本 CLI 命令可能略有差异，建议将命令模板做成可配置项（Settings），默认提供推荐模板。
|
||
|
||
#### 5.4.2 复制会话目录（尽量做）
|
||
**FR-10** “复制会话目录”按钮
|
||
- 当 projectDir 可得时启用；不可得时置灰，并提示原因（无法推断目录）
|
||
- 复制内容为可直接 `cd` 的绝对路径（或原样）
|
||
|
||
#### 5.4.3 一键终端恢复（可选但强烈建议）
|
||
**FR-11** “在终端恢复”按钮（或下拉菜单）
|
||
- 默认目标：macOS Terminal
|
||
- 支持 kitty（v1 要求）
|
||
- 执行策略：
|
||
- `cd "<projectDir>" && <resumeCommand>`（若 projectDir 为空则仅执行 resumeCommand）
|
||
- 失败降级：
|
||
- 无权限/终端不可用 → 自动降级为“仅复制命令”，并提示用户如何修复（例如开启 Automation 权限、kitty remote control）
|
||
|
||
**FR-12** 终端目标选择与记忆
|
||
- 下拉选择：Terminal / kitty /（预留 iTerm2）/ 仅复制
|
||
- 记住上次选择作为默认
|
||
|
||
---
|
||
|
||
## 6. 平台与扩展性设计（macOS v1 + Future-proof）
|
||
|
||
### 6.1 Provider Adapter 抽象（必须）
|
||
统一接口（示例）：
|
||
- `detect(): boolean`
|
||
- `scanSessions(): SessionMeta[]`
|
||
- `loadTranscript(sessionId): Message[]`
|
||
- `getResumeCommand(sessionId): string`
|
||
- `getProjectDir(sessionId): string | null`
|
||
|
||
### 6.2 Terminal Launcher 抽象（必须）
|
||
- `launch(command: string, cwd?: string, targetTerminal: TerminalKind): Result`
|
||
- macOS v1 实现：TerminalLauncherMac
|
||
- Future：TerminalLauncherWindows / TerminalLauncherLinux
|
||
|
||
### 6.3 Path Resolver（必须）
|
||
- `resolveProviderDataPaths(providerId): string[]`
|
||
- v1 返回 macOS 默认候选；允许 Settings 覆盖
|
||
|
||
---
|
||
|
||
## 7. 隐私与安全（Privacy & Security）
|
||
|
||
**默认原则：全本地、只读、不上传。**
|
||
- transcript 默认不出网
|
||
- 本地索引默认仅存必要字段（可选：是否缓存全文内容）
|
||
- 提供“敏感信息遮罩”（可选）：
|
||
- 简单正则：token/key/password 等
|
||
- 提示用户：会话内容可能包含敏感信息，导出/复制时注意
|
||
|
||
---
|
||
|
||
## 8. 非功能需求（Non-Functional Requirements）
|
||
|
||
### 8.1 性能
|
||
- 首次打开：列表可在 1s 内展示（允许先展示缓存，再后台增量刷新）
|
||
- 搜索：在 1k 会话量级可用（建立索引或增量缓存）
|
||
- 详情页：打开后 300ms 内渲染骨架屏，内容流式/分段加载
|
||
|
||
### 8.2 稳定性
|
||
- 任一 provider 数据源损坏不影响整体（隔离失败）
|
||
- 扫描过程可中断/可重试
|
||
|
||
### 8.3 可观测性（可选）
|
||
- 本地日志：扫描耗时、解析失败原因、终端启动失败原因（便于 debug）
|
||
|
||
---
|
||
|
||
## 9. 关键数据结构（建议）
|
||
|
||
### 9.1 SessionMeta
|
||
- `providerId: "codex" | "claude" | string`
|
||
- `sessionId: string`
|
||
- `title?: string`
|
||
- `summary?: string`
|
||
- `projectDir?: string | null`
|
||
- `createdAt?: number`
|
||
- `lastActiveAt?: number`
|
||
- `sourcePath?: string`
|
||
|
||
### 9.2 Message
|
||
- `role: "user" | "assistant" | "tool" | "system" | string`
|
||
- `content: string`
|
||
- `ts?: number`
|
||
- `raw?: any`（保留原始字段，便于兼容未来格式）
|
||
|
||
---
|
||
|
||
## 10. 交互流程（UX Flows）
|
||
|
||
### 10.1 Flow A：搜索并查看
|
||
1) 打开 Session Manager → 看到列表
|
||
2) 输入关键词搜索 → 命中会话
|
||
3) 点击会话 → 进入详情 → 浏览内容 / 在会话内搜索
|
||
|
||
### 10.2 Flow B：复制恢复命令
|
||
1) 列表或详情页点击“复制恢复命令”
|
||
2) toast 成功 → 用户粘贴到终端执行
|
||
|
||
### 10.3 Flow C：一键终端恢复
|
||
1) 详情页点击“在终端恢复”（默认 Terminal）
|
||
2) 系统打开终端新窗口/新 tab
|
||
3) 自动执行：`cd projectDir && resumeCommand`
|
||
4) 失败 → toast 提示，并提供“复制命令”降级路径
|
||
|
||
---
|
||
|
||
## 11. 边界情况与降级策略
|
||
|
||
- 无法获取 projectDir：仍可恢复（只执行 resume），目录按钮置灰
|
||
- 无法解析 transcript：列表仍显示，详情提示“无法解析”，可提供“打开原始文件路径”
|
||
- CLI 命令模板不匹配：允许 Settings 自定义模板；默认模板可更新
|
||
- 终端权限问题（Automation）：提示用户在系统设置中开启对应权限，并允许降级为复制命令
|
||
- kitty 未开启 remote control：提示如何配置，降级为复制命令
|
||
|
||
---
|
||
|
||
## 12. 里程碑与交付（建议）
|
||
|
||
### M1（核心可用）
|
||
- Provider 扫描：Codex / Claude
|
||
- 列表 + 详情（可读）
|
||
- 复制恢复命令
|
||
- 复制目录（若可得）
|
||
|
||
### M2（效率提升）
|
||
- 跨会话搜索、过滤/排序
|
||
- 增量索引与文件监听（可选）
|
||
- “在 macOS Terminal 恢复”
|
||
|
||
### M3（终端覆盖与可扩展）
|
||
- “在 kitty 恢复”
|
||
- 终端目标下拉与记忆
|
||
- 插件化接口/扩展点文档
|
||
|
||
---
|
||
|
||
## 13. 后续功能候选（Backlog / Ideas）
|
||
|
||
- 收藏/Pin 会话
|
||
- 会话标签（项目/主题/状态）
|
||
- 会话摘要（本地生成）
|
||
- Fork 会话继续（避免污染原会话）
|
||
- 导出 Markdown/JSONL
|
||
- 按项目聚合（Repo 视图）
|
||
- 会话清理/归档（磁盘管理）
|
||
|
||
---
|