摘要：

上周解决了 RAG 可观测与摘要去 mindmap 后，产品形态仍停留在「导入 → 一篇 Markdown」——缺少模块化复习与视频时间轴联动。本周计划实现：（1）note.content_struct JSON 列 + StructuredSummarizeService 三阶段编排（modules / timeline / segments）；（2）POST /api/ai/stream/structured-summarize SSE，Import 三源写入结构化载荷；（3）前端 StructuredNoteView：全文总结 / 原文细读 / 时间线 Tab，B 站 iframe 小窗拖动与面板双栏学习侧栏；（4）字幕 cue 时间轴解析、HighlightTimeResolver 修正亮点时间、videoDurationSec 对齐真实片长。

一、结项背景：从“笔记工具”到“学习工作站”

SmartNotes 之前已具备：B 站/文件/粘贴三源导入、Map-Reduce 摘要、RAG 私域问答、思维导图 Agent、LLM 用量与 RAG 检索统计。但联调与自用反馈集中在一个差距——

导入结果仍是「扁平 Markdown」，用户复习长视频时需要自己在正文里找章节、找时间点，体验感较差。

因此第本周结项冲刺目标：

1. 结构化笔记落库：摘要、亮点、术语、时间线、原文分段写入 JSON，与 content_md 并存；
2. 学习阅读 UI：有 content_struct 的笔记默认进入 Tab 化阅读，可一键切回编辑器；
3. B 站视频联动：嵌入播放器 + 自定义进度条 + 章节跳转（t= 参数）；

二、数据层：content_struct 与来源字段

2.1 表结构

在 note 表新增 JSON 列：

```sql
ALTER TABLE `note`
    ADD COLUMN `content_struct` JSON NULL
    COMMENT '结构化笔记：modules/timeline/segments' AFTER `content_md`;
```

note 表同时读写 source_type（BILIBILI / PDF / TXT / MANUAL）与 source_ref（BV 号或文件名），供前端决定是否展示 B 站播放器。

2.2 StructuredNoteDocument 载荷

字段	含义
version	schema 版本，当前为 1
modules	abstract、highlights、reflections、terms、tags
timeline	[{ startSec, title, summary }] 章节时间线
segments	[{ startSec, endSec, title, summary, transcript }] 原文细读分段
videoDurationSec	视频总秒数（来自字幕 cue 或 B 站 view 接口 duration）

content_md 仍由 StructuredNoteRenderer 从 JSON 渲染，保证「导出 Markdown / 全文搜索」链路不断。

三、后端：StructuredSummarizeService 三阶段编排

3.1 入口

POST /api/ai/stream/structured-summarize

请求体 AiStructuredImportDTO：text（清洗正文）+ cues（可选 SubtitleCueDTO 列表）+ sourceType / sourceRef。

SSE 事件：meta → progress(modules|timeline|segments) → section(完整 JSON) → delta(content_md 伪流式) → done。

3.2 编排逻辑

阶段一 modules：有 cues 时用 SubtitleCueUtil.buildTimestampedScript 生成 [mm:ss] 前缀稿，LLM 按 STRUCTURED_MODULES_SYSTEM 输出 JSON（摘要/亮点/思考/术语/标签）。

阶段二 timeline（仅当有 cues）：TIMELINE_SYSTEM 划分 4–8 章，startSec 必须对应稿中时间点。

阶段三 segments：SubtitleSegmentBuilder 按 cue 聚合原文分段；endSec 取最后一条 cue 的真实 toSec。

后处理 HighlightTimeResolver：若 LLM 把 highlights.timeSec 全填 0，则用 cue 文本模糊匹配 + timeline 索引回填，保证时间芯片可点击跳转。

3.3 B 站字幕增强

BilibiliFetchService 解析 player.subtitle.subtitles，优先 zh-CN / zh-Hans / ai-zh / zh，无中文时回退第一条轨。

SubtitleCueUtil.parseFromSubtitleJson 解析 body[].from/to → SubtitleCue 列表。

View 接口读取 duration 写入 SubtitleFetchResult.videoDurationSec，导入时落入 content_struct，供前端进度条总时长对齐真实片长。

四、前端：StructuredNoteView 学习阅读

4.1 Tab 结构

- 全文总结：modules 摘要、亮点（带时间芯片）、思考题、术语、标签；
- 原文细读：segments 卡片，展示分段 transcript；
- 时间线：章节列表，点击 seekTo(startSec)。

HomeView 检测 editorStore.hasStructuredNote：有 struct 默认「学习阅读」，顶栏可切「编辑模式」。

4.2 B 站视频双模式

模式	行为
小窗 PiP	可拖动、可缩放；章节模式 16:9 高度；全屏折叠章节自由 W×H
面板 Panel	左栏 iframe + 自定义进度条；右栏学习侧栏：进度圆环、当前章节、全部章节列表

iframe URL 使用 player.bilibili.com，跳转通过 t= 秒参数；跨域无法读取真实 playhead，采用 playbackSec 秒级 ticker 驱动圆环与当前章节高亮（手动 seek 后重置）。

4.3 Import 体验优化

- 笔记标题：直接使用视频标题 / 文件名，不再追加「导入笔记」后缀；
- ImportPanel 内嵌 MainLayout，LandingView 作为产品入口页；
- 结构化 SSE 写入 contentStruct + contentMd + summary 一并持久化。

五、项目结项小结

SmartNotes 从中期RAG 雏形到后续三源导入，第十三周可观测与摘要提质，本周完成结构化 + 视频联动的产品闭环，对应了任务书中全媒体知识提炼与Agent 编排的核心要求：

- 多 Agent：提炼 / 排版 / 出题 / 思维导图 / 结构化三阶段 / RAG 问答，Prompt 独立、场景可统计；
- 多模态入口：B 站字幕 cue、PDF/txt/md、粘贴文本；
- 可复习形态：不仅是 Markdown 存档，而是带时间轴的学习阅读；
 

结项后设想的维护方向：字幕语言选择、YouTube 等非 B 站源、向量检索升级 RAG。

感谢组员在笔记 CRUD、Explorer UI、RAG 会话与前端美化上的并行交付；智汇笔记 SmartNotes 至此完成课程目标内的全链路闭环。