# LearnNote

### 看过的内容，变成自己的笔记。

字幕优先的视频笔记、本地学习资料、可追问的 AI 助手。双击启动脚本，在浏览器工作台里阅读、编辑、回到来源；不用注册 LearnNote 账号。

[下载启动脚本](https://github.com/hurry060215-tech/learnnote-assistant) · [产品与使用流程](https://hurry060215-tech.github.io/learnnote-assistant/) · [安装浏览器扩展](docs/EXTENSION_CONNECTION.md) · [使用帮助](SUPPORT.md)

> **当前源码：本机后端 v0.2.17 / 扩展 v0.2.17。** 修复已保存观众观点超过 500 条时的分页浏览、目录四级标题跳转，以及播放跟随正文被固定工具栏遮挡的问题。[版本说明](docs/RELEASE_0217.md)不代表发布或安装完成；现有安装需更新对应发布包才能获得修复。商店版本独立审核；真实视频原因与模型质量、长字幕延迟波动、四小时真实视频和完整平台验收仍未全部确认，AI 笔记仍需核对。

![LearnNote 阅读工作台](site/assets/learnnote-reader-current.png)

_工作台的界面验收截图，使用演示资料。界面展示不代表真实模型效果。_

## 双击启动，不用命令行

1. **启动本机服务。** Windows 双击 `start-learnnote.bat`；macOS 双击 `start-learnnote.command`。脚本会准备 Python 环境，启动只监听 `127.0.0.1` 的服务，并在健康检查通过后打开默认浏览器工作台。
2. **添加内容。** 粘贴视频网址、选择本地视频，或导入 PDF、Markdown、TXT、HTML。普通链接不要求安装扩展。
3. **选择模型并整理。** 在浏览器设置中保存一次模型连接，工作台和扩展任务共用；Key 只交给本机服务或系统凭据库。确认来源和处理方式后开始，任务页展示进度和记录，完成后阅读总结、编辑正文或导出。

已登录的 B 站或课程页面，可以使用浏览器扩展交接当前页面可访问的字幕与资源。在扩展里查看连接和字幕状态，再发送到本机工作台。**只粘贴网址不会自动获取另一个浏览器的登录态。**

[Chrome 商店](https://chromewebstore.google.com/detail/learnnote-%E5%BD%93%E5%89%8D%E8%A7%86%E9%A2%91%E5%8A%A9%E6%89%8B/mncdchpkpikhacmkbanedpppcddapppe) · [离线安装、启动脚本与连接排查](docs/EXTENSION_CONNECTION.md)

## 从字幕到笔记，每一步清楚可见

| 当前条件                 | 程序做什么                                       | 你得到什么                               |
| ------------------------ | ------------------------------------------------ | ---------------------------------------- |
| 有可用字幕，无需画面分析 | 读取字幕，跳过视频下载和语音转写，再调用文字模型 | 概览、重点、来源时间点；字幕原文独立保留 |
| 没有可用字幕             | 获取媒体，按所选方式转写，再整理                 | 可回看时间点的转写与笔记                 |
| 需要截图或画面理解       | 额外获取视频与必要画面；视觉模型按需处理         | 图文补充和对应来源                       |
| 没有配置文字模型         | 在下载、转写前提示配置，也可改选“仅提取字幕”     | 原文材料，**不是 AI 总结**               |
| 总结服务报错或额度不足   | 显示失败原因，保留已有字幕；修复配置后重试整理   | 不必为了重做总结重复转写                 |
| 导入文档                 | 提取可读原文                                     | 本地阅读、检索、批注；扫描 PDF 需先 OCR  |

任务状态区说明当前步骤、已完成和跳过的步骤。处理记录用于查看耗时、提示和失败原因。需要更深入排查时，在任务的 **更多 → 诊断** 中查看记录；分享前仍应检查并移除私人内容。

本地转写采用 faster-whisper，是可选能力。有字幕或使用远程转写时，无需下载本地模型。需要离线转写时，在 **设置 → 字幕与转写 → 准备本地语音模型** 中检查状态并按需下载；速度与视频时长、模型大小、CPU/GPU 和硬件环境有关。画面 OCR 用于抽帧文字提取，**完整画面字幕 OCR 尚未作为自动回退流程提供**。

**保存字幕原文**保留逐字内容和时间点；**生成总结笔记**会调用文字模型提炼要点、大纲与结论，二者在创建时明确区分。模型输出检查失败时保留原文，并提供直接重试总结的入口，不必重新添加视频。

浏览器扩展可以搜索已取得的原文、按停顿和段落长度展开分组，并点击字幕回到原视频；这些分组不是 AI 生成的主题章节。B 站字幕笔记即使没有下载视频，也可在来源区按需打开官方外链播放器；在线观看视频仍需要网络，并受平台播放权限限制。

侧栏的 **我的** 打开个人主页，查看内容数量、本机 Token 用量与复习入口。用量只记录服务商实际返回的数据，不代表账号余额；未返回用量单独标注。复习使用 FSRS，根据评分与历史记忆表现调整间隔，并在评分前显示预计下次复习时间。

在 **设置 → 外观** 中选择“清晰紧凑”或“大字加粗”，也可以分别调整字体、字号、字重、行距和正文宽度。旧的自定义外观会保留；侧栏的 **复习** 先展示今日计划，再进入卡片练习。

未发送的助手问题按笔记保存为本机草稿，刷新或失败后可以接着写。重新生成前保留上一份生成稿，在“历史版本”中预览、复制或下载，个人修改独立保存。同步暂时中断时，当前内容与编辑输入会保留，并提供重试入口。

正文下方的“个人核对”可以主动记录或撤销“本人已核对”。范围是当前整篇笔记和列出的本机来源版本；编辑、重新生成或来源变化后，旧记录会显示过期。它只记录本机操作，不验证个人身份或事实正确性，也不会去掉原有待核对提示。来源缺失时会明确说明仅是个人阅读核对。学习备份包含这些记录，恢复后需要本人重新核对；本机已有记录和撤销状态优先保留。新版备份使用 v2，仍可导入旧 v1；旧版客户端会拒绝 v2，请使用新版恢复。

生成中的分章草稿使用简短章节状态显示原文字面匹配进度，不在每条概括前重复提示；章节仍是未完成最终校验的草稿，正式笔记的证据检查与导出标记保持原有规则。“更多操作 → 学习工具 → 核对章节概括”可手动预览当前生成章节的结论、选取原文和模型目标，再确认发送一次请求。每批最多 12 条结论，下一批必须重新确认；模型返回“支持 / 矛盾 / 本次原文不足”的判断和引句，不改写笔记、不替代个人核对或事实验证。可能产生模型费用；关闭窗口不撤回已发送请求。个人修改稿和未经核对的画面字幕 OCR 暂不支持此入口。详见[数据流与限制](PRIVACY.md#native-assistant-operations)。

## 读懂内容，也能继续加工

- **正文与来源分开。** 总结用于组织重点，字幕用于核对原话；通过时间点回到视频，不把时间戳当成事实认证。
- **全局助手与显式 Skill。** 可以问怎么操作、检查环境、搜索资料，也可围绕选中内容提问、总结、自测；回复展示使用的 Skill、范围和执行方式。
- **保留自己的理解。** 编辑笔记正文，保存个人补充；原始生成稿与修订稿分别保留。课程、复习卡、学习计划和版本记录继续可用。
- **安全管理课程。** 删除课程默认只移除分组。可在确认页逐项选择永久删除的子任务；其他课程共用、仍在处理、被视频片段依赖或身份无法核对的任务会受保护。独立资料和应用数据目录外的原文件保留。同一完整视频的文字课程任务可跨课程复用，任务与证据 ID 不变；不同分 P、片段、模式及已有的重复任务不会被强行合并。
- **按自己习惯阅读。** 折叠侧栏、查看大纲，调整字体、字号、行距、阅读宽度、主题与密度。原有导出、片段学习、OCR 和诊断入口仍可发现。
- **选择自己的模型。** 可配置文字与视觉服务，使用服务预设或兼容接口；本地模型服务也可连接。模型账号和额度由用户自己的提供商管理。

[全局助手与 Skill](docs/GLOBAL_ASSISTANT.md) · [模型与设置帮助](SUPPORT.md) · [Obsidian 集成](integrations/obsidian-learnnote/README.md)

## 本地优先，有清楚的边界

视频、字幕、笔记、补充和复习记录默认放在本机。LearnNote 没有自有云任务、产品遥测，也不要求产品账号。

下载内容会访问来源网站；选择远程文字、视觉或转写服务时，该服务会接收完成任务所需的内容。本地转写不向模型 API 上传音频，但首次需要下载模型权重。Windows/macOS 的本机服务可用系统凭据库保存 API Key；不要把密钥写入仓库、公开 Issue 或截图。

浏览器扩展在用户触发的工作流中交接当前会话可访问的内容，不录制标签页，不绕过 DRM、账号权限或课程进度。手机窄屏可阅读网页，但默认服务只供本机访问；跨设备同步和独立手机 App 不在当前承诺内。

[隐私说明](PRIVACY.md) · [安全说明](SECURITY.md) · [第三方许可](THIRD_PARTY_NOTICES.md)

## 支持与反馈

Windows 10 / 11 x64 与 macOS 可通过平台启动脚本运行浏览器工作台。支持本地视频、Bilibili、YouTube 和当前会话有权访问的常见媒体资源。站点更新、登录失效或加密播放可能影响获取；可用本地文件继续。

[来源兼容矩阵](docs/SOURCE_COMPATIBILITY_MATRIX.md) · [平台支持](docs/PLATFORM_SUPPORT.md) · [提交问题](https://github.com/hurry060215-tech/learnnote-assistant/issues)

反馈请附输入类型、复现步骤、预期与实际结果，以及已检查的处理记录。安全问题使用[私密漏洞报告](https://github.com/hurry060215-tech/learnnote-assistant/security/advisories/new)，不要公开凭据或未脱敏任务包。

## 参与开发

普通使用双击平台启动脚本即可。开发环境也可以直接运行浏览器工作台：

```powershell
git clone https://github.com/hurry060215-tech/learnnote-assistant.git D:\Projects\learnnote-assistant
cd D:\Projects\learnnote-assistant
.\scripts\first-run-checklist.ps1
.\start-learnnote.bat
```

后端回归：

```powershell
$env:PYTHONPATH = "backend"
.\.venv\Scripts\python.exe -m unittest discover backend/tests
.\.venv\Scripts\python.exe -m unittest discover scripts/tests
```

主工作台在 `web/desk*`，浏览器扩展在 `extension/`，后端在 `backend/app/`，静态官网在 `site/`。旧界面仅作为源码历史回归参考，不进入桌面发行包。

[架构](docs/ARCHITECTURE.md) · [贡献指南](CONTRIBUTING.md) · [发布流程](docs/RELEASING.md) · [产品参考与取舍](docs/PRODUCT_REFERENCE_REVIEW.md)

感谢 [BiliNote](https://github.com/JefferyHcool/BiliNote) 的字幕优先与视频笔记工作流、[Cetle / B 站视频总结](https://api.cetle.cn/) 的字幕与学习工具组织，以及 [Cherry Studio](https://github.com/CherryHQ/cherry-studio) 的多模型客户端交互参考。参考产品结构不意味着这些项目的全部代码采用同一种许可证；来源与复用范围见[参考说明](docs/PRODUCT_REFERENCE_REVIEW.md)。

LearnNote 采用 [Apache License 2.0](LICENSE)。