# DSH Session Log 可视化 — 产品重新定位 > 核心问题: 当前方案是"事件查看器"，普通人看不懂。如果要面向更多用户，需要从"展示技术事件"转为"讲述执行故事"。 --- ## 一、问题本质 **当前定位**: 技术调试工具 — 把 9285 条 JSON 事件用颜色标注展示出来。 **用户看到的**: 一堆 `reasoning-chunks`、`tool/call:read`、`approval/asked` 这样的技术术语，即使树形折叠后，依然是"代码视角"。 **应该变成什么**: 即使是不懂编程的人，也能在 30 秒内看懂： - 用户提了什么需求 - AI 做了哪些事（用大白话说） - 花了多长时间、调用了哪些工具 - 中间有没有被审批拦截 - 最终产出了什么 --- ## 二、三层渐进式信息架构 不要试图在一个界面里同时服务开发者和普通用户。用**三层渐进式**设计：从故事概览到技术细节，每层吸引不同人群。 ### 第一层: 执行摘要卡片（面向所有人） 打开会话后**第一眼看到的不是日志列表**，而是一张摘要卡片： ``` ┌─────────────────────────────────────────────────────┐ │ │ │ 📋 解析 sessionlog 并可视化 │ │ │ │ 用户需求 │ │ "请根据 requirement 进行完善后编写解析 session │ │ log 的内容..." │ │ │ │ ─── 执行过程 ─── │ │ AI 共进行了 2 轮对话，197 个步骤 │ │ 耗时 15 分 23 秒 │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ 📖 读取 │ │ ✏️ 写入 │ │ 🔍 搜索 │ │ │ │ 89次 │ │ 45次 │ │ 32次 │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ─── 审批 ─── │ │ 38 次审批请求，全部通过 ✅ │ │ │ │ ─── 产出 ─── │ │ ✏️ 修改了 REQUIREMENTS.md (15KB) │ │ 📄 新建了 UI_IMPROVEMENT.md (8KB) │ │ 📁 新建了 decoded-sessions/ 目录 │ │ │ │ ─── Token 消耗 ─── │ │ 输入 125K | 输出 89K | 推理 234K │ │ │ │ [查看完整执行时间线 ↓] │ │ [查看技术事件列表 ↓] │ │ │ └─────────────────────────────────────────────────────┘ ``` **设计原则**: 这一层不出现任何技术术语。没有 `seq`、`callId`、`reasoning-chunks`。工具用图标+中文名（读取/写入/搜索/执行命令），不是原始的 `read`/`write`/`grep`/`pwsh`。 ### 第二层: 执行故事线（面向产品经理/技术管理者） 用户点击"查看完整执行时间线"后进入。这不是事件列表，而是**叙事式时间线**： ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 15:45 用户发送需求 ───────────────────────────────────────────── │ "请根据 requirement 进行完善后编写..." │ │ 15:45 AI 开始分析 │ ───────────────────────────────────────── │ │ AI 推理: "用户要求我分析 session log 的 │ │ 数据结构并编写解析代码..." │ │ │ │ 15:46 AI 读取了 REQUIREMENTS.md │ │ ───────────────────────────────────── │ │ │ 获取了 293 行需求文档内容 │ │ │ │ │ 15:47 AI 读取了 session.json │ │ ───────────────────────────────────── │ │ │ 获取了 4441 行会话日志 │ │ │ │ │ 15:48 AI 分析数据结构 │ │ ───────────────────────────────────── │ │ │ 发现了 22 种事件类型，整理了字段结构 │ │ │ │ │ 15:50 ⚠️ 请求审批: 写入文件 │ │ ───────────────────────────────────── │ │ │ 原因: 需要写入工作目录外的文件 │ │ │ ✅ 用户批准 │ │ │ │ │ 15:50 AI 写入了 REQUIREMENTS.md │ │ ───────────────────────────────────── │ │ │ 更新了需求文档，补充了 27 种事件类型 │ │ │ 和颜色方案 │ │ │ 15:52 AI 完成第一轮回复 │ ───────────────────────────────────────── │ │ "需求文档已创建，包含完整字段清单..." │ │ 15:52 用户追加需求 │ ───────────────────────────────────────── │ │ "文件解压位置也帮我修改掉..." │ │ │ │ 15:53 AI 更新文档 │ │ ───────────────────────────────────── │ │ │ 解压全部 14 个会话到 D 盘 │ │ │ 分析了全部 27 种事件类型 │ │ │ 补充了 14 组颜色方案 │ │ │ │ 15:58 AI 完成第二轮回复 │ ───────────────────────────────────────── │ │ "需求文档已更新完成..." │ 15:58 会话结束 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **设计原则**: - 用叙事语言描述，不是事件类型名。"AI 读取了 REQUIREMENTS.md"而不是"tool/call: read arguments: {file_path: ...}" - 推理过程折叠为 1-2 句话摘要，点击可展开完整推理 - 审批用图标（⚠️ 请求 → ✅ 批准 / ❌ 拒绝），不显示技术字段 - 时间线用竖线连接，体现流程顺序 - 文件操作用文件名+大小，不显示 JSON 参数 ### 第三层: 技术事件详情（面向开发者） 用户在故事线中点击某个节点，或直接点击"查看技术事件列表"才进入。这才是之前的树形列表 + 详情面板。 **入口方式**: - 故事线中每个节点可点击 → 展开技术详情 - 或底部有"技术视图"按钮 → 切换到完整事件列表 **这层的用户**: 开发者、调试者。他们需要看原始 seq、callId、完整 JSON 参数。 --- ## 三、关键设计转变 ### 转变 1: 从"事件列表"到"故事叙述" | 维度 | 当前（事件列表） | 改为（故事叙述） | |------|------------------|------------------| | 组织方式 | 按 seq 顺序平铺 | 按 turn→step 叙事 | | 推理展示 | 3199 条分片逐条列出 | 合并为 1-2 句话摘要 | | 工具调用 | `tool/call: read, arguments: {file_path: "..."}` | "AI 读取了 REQUIREMENTS.md" | | 审批 | `approval/asked, data.reason: "..."` | "⚠️ 请求审批: 写入文件 — 需要写入工作区外" | | 结果 | `tool/result, data.message.content: [...]` | "获取了 293 行内容" | | 目标用户 | 开发者 | 所有人 | ### 转变 2: 推理过程从"流式分片"到"摘要+展开" reasoning-chunks 占 34% 数据量但用户不需要看每个分片。应该： 1. **默认**: 每个步骤的推理合并为 1-2 句话摘要（可由 AI 自动生成，或取前 100 字） 2. **点击展开**: 显示完整推理文本（分片合并后的全文） 3. **不展开**: 不显示分片级别的统计信息（多少 chunks、多少 chars、多少 ms） ### 转变 3: 工具调用从"技术参数"到"人类语言" | 工具名 | 技术展示 | 人类语言展示 | |--------|----------|-------------| | `read` | `arguments: {"file_path": "D:\\...\\REQUIREMENTS.md"}` | 📖 读取了 REQUIREMENTS.md | | `write` | `arguments: {"file_path": "...", "content": "..."}` | ✏️ 修改了 REQUIREMENTS.md (15KB) | | `glob` | `arguments: {"pattern": "**/*"}` | 🔍 搜索了所有文件 | | `grep` | `arguments: {"pattern": "session", "path": "..."}` | 🔍 搜索了 "session" 关键词 | | `pwsh` | `arguments: {"command": "npm install..."}` | ⚙️ 执行了命令: npm install... | | `edit` | `arguments: {"file_path": "...", "old_string": "...", "new_string": "..."}` | ✏️ 编辑了 REQUIREMENTS.md 第 45 行 | ### 转变 4: 文件操作追踪（新增功能） 从 tool/call + tool/result 中提取所有文件操作，单独展示为"文件变更记录"： ``` ─── 文件变更记录 ─── 📄 REQUIREMENTS.md ✏️ 修改 (15:50) 293行 → 450行 ✏️ 修改 (15:53) 450行 → 520行 📄 UI_IMPROVEMENT.md ✨ 新建 (15:55) 8KB 📁 decoded-sessions/ ✨ 新建 (15:48) 14个子文件 ``` ### 转变 5: 审批从"字段配对"到"决策故事" ``` ─── 审批记录 ─── 15:50 ⚠️ 写入文件 REQUIREMENTS.md 原因: 需要写入工作区外文件 ✅ 已批准 (等待 5.6 秒) 15:52 ⚠️ 执行命令 npm install 原因: 安装依赖需要网络访问 ✅ 已批准 (等待 3.2 秒) ``` --- ## 四、用户旅程设计 ### 场景 A: 普通用户查看（30 秒了解全貌） 1. 打开会话 → 直接看到**执行摘要卡片** 2. 从摘要卡片了解：做了什么、花了多久、用了什么工具、产出了什么 3. 满足了，关掉。不需要进入更深层 ### 场景 B: 技术管理者查看（3 分钟了解过程） 1. 打开会话 → 看摘要卡片 2. 点击"查看完整执行时间线" → 看**故事线** 3. 快速浏览叙事时间线，了解 AI 的决策路径 4. 在感兴趣的节点（比如某次审批、某个工具调用）点击展开技术详情 5. 满足了，关掉 ### 场景 C: 开发者调试（深入分析） 1. 打开会话 → 看摘要卡片（快速了解） 2. 点击"查看技术事件列表" → 进入**完整事件树形列表** 3. 使用筛选、搜索定位特定事件 4. 查看原始 JSONL 数据 --- ## 五、实现建议 ### 5.1 数据转换层 在 JSONL 解析和前端展示之间增加一个**转换层**，将技术事件转为叙述节点： ``` 原始 JSONL → 解析器 → 27种事件对象 → 叙述转换器 → 故事节点 → 前端渲染 ``` **叙述转换器**的核心逻辑: 1. **合并 chunks**: 将同一 step 内的 reasoning-chunks/text-chunks/tool-call-chunks/assistant/chunk 合并 2. **配对事件**: tool/call + tool/result → 一个"工具操作"节点；approval/asked + approval/decided → 一个"审批"节点 3. **人类语言映射**: tool name → 中文动词 + 图标（read→📖读取, write→✏️写入...） 4. **摘要生成**: 推理文本取前 100 字作为摘要；工具结果提取关键信息（行数、文件大小、是否成功） 5. **文件变更提取**: 从所有 write/edit 工具调用中提取文件变更记录 6. **审批故事化**: 将审批请求的原因简化为人类可读文本 ### 5.2 页面路由 ``` / → 会话列表 /session/:id → 执行摘要卡片（第一层） /session/:id/timeline → 执行故事线（第二层） /session/:id/events → 技术事件列表（第三层） ``` ### 5.3 技术栈不变 仍然是 Python + HTML/CSS/JS，只是前端从"单一列表页"变为"三层渐进式"页面。后端 API 需要增加叙述转换层。 --- ## 六、总结 | 维度 | 当前方案 | 改进方案 | |------|---------|---------| | 核心定位 | 事件查看器 | 执行故事叙述器 | | 首屏内容 | 9285 条事件列表 | 一张摘要卡片 | | 信息组织 | 按 seq 平铺 | 三层渐进式（摘要→故事线→技术详情） | | 推理展示 | 3199 条分片 | 合并为每步 1-2 句摘要 | | 工具展示 | `tool/call: read, arguments: {...}` | 📖 读取了 REQUIREMENTS.md | | 目标用户 | 开发者 | 所有人（摘要）→ 管理者（故事线）→ 开发者（技术详情） | | 核心价值 | 能看 | 能懂 |