CodeInsights TimeLine Support

[zcxGGmu]

背景

参考 https://github.com/Kocoro-lab/Shannon

CodeInsights 目前已经具备较强的实时事件基础链路（AgentEventBus -> IPC -> 渲染层 atoms），但仍缺少一个类似 Shannon 右侧面板的**执行时间线（Execution Timeline）**能力：

• 运行时实时展示关键执行节点
• 将原始事件投影为可读的时间线语义
• 刷新/重启后可回放历史时间线

本 Issue 用于跟踪 RV-Insights 的 Timeline 全链路支持（主进程 + 渲染进程）。

目标

• 为 Agent 会话增加独立 Timeline 能力。
• 严格遵守 RV-Insights 现有约束：
  • 渲染层状态管理仅使用 Jotai
  • 本地优先持久化（JSON/JSONL），不引入本地数据库
  • 尽量不破坏现有消息流和 ToolActivity 渲染逻辑
• 同时支持：
  • 执行中的实时 Timeline 更新
  • 刷新/重开后的历史回放

非目标（Phase 1）

• 不迁移为 Redis/SSE 服务端架构
• MVP 阶段不引入重型可视化引擎（雷达动画可放到二期）
• 不重写现有 AgentMessages 工具活动渲染

方案概览

flowchart LR
  A["AgentOrchestrator 输出 AgentStreamPayload"] --> B["AgentEventBus 中间件"]
  B --> C["TimelineNormalizer\n(payload -> TimelineEvent[])"]
  C --> D["TimelineStore (JSONL 追加)"]
  C --> E["IPC 事件: agent:timeline:event"]
  D --> F["IPC 查询: agent:get-timeline-events"]
  E --> G["Renderer Jotai Timeline Atoms"]
  F --> G
  G --> H["右侧面板: Files | Timeline"]

Loading

设计原则：

• Timeline 语义在主进程统一归一化（单一事实来源）
• 渲染层只负责订阅、筛选与展示
• 本地可持久化 + 可回放

详细技术方案

1) Shared Timeline 领域模型

在 shared 层新增类型（可放在 packages/shared/src/types/agent.ts 或独立文件）：

• TimelineEvent
• TimelineStatus: running | completed | failed | waiting
• TimelineCategory: workflow | agent | tool | task | system

建议字段：

• id, sessionId, seq, ts
• type, status, title, detail?
• source: sdk_message | rv_event
• dedupeKey?, raw?

2) 主进程归一化层（Normalizer）

新增 agent-timeline-normalizer.ts：

输入：AgentStreamPayload
输出：TimelineEvent[]

推荐映射示例：

• assistant.tool_use -> TOOL_INVOKED (running)
• user.tool_result -> TOOL_COMPLETED / TOOL_FAILED
• system.task_started -> TASK_STARTED
• system.task_notification -> TASK_COMPLETED / TASK_FAILED / TASK_STOPPED
• result.success -> WORKFLOW_COMPLETED
• result.error_* -> WORKFLOW_FAILED
• rv permission / ask_user / retry -> 等待/重试类节点

降噪建议：

• 丢弃 prompt_suggestion
• tool_progress 按 toolUseId 进行节流（例如 1s）
• 避免 token/text delta 级别高频刷屏

3) 主进程持久化（JSONL）

新增 agent-timeline-store.ts，提供 append/list 能力。

建议路径：

• ~/.rv-insights/agent-sessions/{sessionId}.timeline.jsonl

行为要求：

• JSONL 追加写入
• 每个会话单调递增 seq
• 轻量去重（id 或 dedupeKey + status）
• 支持按 limit/排序读取

并在会话删除时同步清理 timeline 文件。

4) IPC / Preload 扩展

新增 IPC 通道：

• agent:get-timeline-events
• agent:timeline:event

新增 preload API：

• getAgentTimelineEvents(sessionId, options?)
• onAgentTimelineEvent(callback)

5) 渲染层 Jotai Timeline 状态

新增 atoms：

• agentTimelineEventsMapAtom
• currentAgentTimelineEventsAtom
• agentTimelinePanelTabMapAtom（files | timeline）
• 可选 agentTimelineFilterAtom

规则：

• 基于 id 去重
• 每个会话内存上限（如仅保留最近 1000 条）

6) 右侧面板整合

保留现有文件面板能力，新增 Timeline 模式：

• Files（现有）
• Timeline（新增）

建议新增组件：

• TimelinePanel.tsx
• TimelineList.tsx
• TimelineItem.tsx
• TimelineEventDetails.tsx

MVP 时间线项字段：

• 状态图标（运行/完成/失败/等待）
• 简短可读标题
• 时间戳
• 可展开详情

分阶段里程碑

M0：类型 + IPC 脚手架

• 增加 shared timeline 类型
• 增加 IPC 常量与 preload 占位

M1：主进程数据链路

• Normalizer + Store
• EventBus 中间件接入
• 历史查询 API
• 会话删除清理

M2：渲染层 MVP

• Timeline atoms + 实时订阅 + 历史回放加载
• SidePanel 增加 Files/Timeline 切换
• Timeline 列表与详情

M3（可选）：可视化增强

• 轻量活动可视化（雷达风格）

M4：加固与兼容

• 旧会话兼容回退策略
• 文档与测试补齐

验收标准

• 执行过程中 Timeline 能实时更新。
• 刷新/重开后 Timeline 可从本地持久化正确回放。
• 右侧面板 Files/Timeline 切换不影响现有文件功能。
• 高频噪声事件被节流/过滤，时间线可读。
• 删除会话时同步删除 timeline 持久化文件。

风险与规避

• 事件噪声导致 UI 压力：节流 progress、内存上限、默认过滤低价值事件。
• 事件顺序漂移：主进程统一分配 seq。
• 语义不一致：归一化逻辑集中在主进程，前端不重复映射。
• 与 ToolActivity 功能重叠：明确定位为“跨轮次执行脉络”，而非工具细节替代。