ContextQMD
Back to Cc Switch

会话管理（Session Manager）需求文档（PRD / Markdown）

session-manager.md

3.14.19.2 KB
Original Source

会话管理（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 视图）
  • 会话清理/归档（磁盘管理）