Lecture Workflow

Lecture Workflow 是一个面向课堂学习场景的 Obsidian 桌面端插件，用于把课堂文字、截图和时间线整理为结构化学习笔记。

核心流程：

创建课堂笔记
→ 开始课堂监听
→ 课堂截图 / 实时转写
→ AI 整理当前课堂笔记
→ 预览并写回 Obsidian

快速开始

1. 在 Obsidian 社区插件中安装并启用 Lecture Workflow（桌面版，Obsidian 1.7.2 或更新）。打开设置，选择要使用的功能。
2. **只整理文字：**配置文字服务的 API Key，点击对应的「测试连接」。创建课堂笔记，把文字稿放入「原始文字稿」，再使用「AI 整理当前课堂笔记」。无需安装音频助手。DeepSeek API 说明 · 百炼 API Key 获取方法。
3. **整理文字和截图：**再启用「图片参与整理」，配置视觉服务。开始课堂监听后，把截图复制到系统剪贴板。
4. **转写 Windows 电脑播放的课程声音：**配置 Qwen 实时转写的 API Key 和 Workspace ID，并安装下方的 Windows Audio Companion。查看 Workspace ID 获取方法。打开课堂笔记、开始课堂监听，再到课堂工作台检查系统音频和实时转写状态。设置中的「测试 Qwen 文字连接」不能验证实时转写。

Windows 音频助手（仅网课系统声音需要）：下载 0.1.3 版 Windows x64 ZIP · 查看完整安装步骤。插件 0.1.5 继续使用 0.1.3 版助手，两者兼容，已安装者无需重新下载。0.1.3 版包含所需 .NET 运行环境，无需额外安装；旧 0.1.1 版的运行环境要求见下文。

插件不保存录音。系统音频助手在本机捕获电脑播放的声音；启动实时转写后，插件会将音频发送到你配置的 Qwen 服务，服务可能产生费用。

切换网络与断线恢复

课堂启动收音后，插件会对音频助手的连接中断、心跳超时或音频设备暂时不可用进行自动恢复。云端转写断线时仅重连转写，保留本地收音；助手恢复后会恢复原先启用的转写。重试间隔从 1 秒逐渐增加到 15 秒，最多尝试 8 次；收到网络恢复事件时重新尝试。

手动停止收音、停止转写、结束课堂或卸载插件会取消对应的自动恢复。鉴权、额度不足和配置错误不会反复重试。插件不保存录音，断线期间未转写的声音无法补录；恢复失败时请检查网络后手动重新启动。

V0.1 核心能力

• 创建标准课堂笔记，开始或停止课堂监听。
• 在监听期间检测新复制到系统剪贴板的截图，保存到 Vault 并加入课堂时间线。
• 在 Windows 上配合可选的 Windows Audio Companion 捕获默认系统输出音频。
• 使用 Qwen Realtime ASR 进行课堂实时转写；识别定稿会自动追加到当前课堂笔记的「原始文字稿」。
• 支持纯文字 AI 整理，也支持课堂截图 + transcript 联合整理。
• Qwen Vision 只负责理解课堂截图并生成视觉辅助上下文；Text Provider 负责生成最终结构化 Markdown。
• 保留截图 placeholder，并在最终结果中恢复原始图片引用。
• 使用 timelineContext 保留 transcript 与截图的课堂时序。
• AI 写入前检查笔记和附件冲突，防止覆盖预览期间的外部修改。

安装

Lecture Workflow V0.1 是桌面端插件，最低支持 Obsidian 1.7.2。通过 Community Plugins 安装时，Obsidian 会安装 main.js、manifest.json 和 styles.css。

Windows 系统音频需要额外的 Windows Audio Companion。该 Helper 不属于 Community Plugin 自动安装内容，请按下方说明手动安装。普通文字整理和图片整理不依赖 Helper。

首次使用配置

1. 文字 AI 整理

在 Lecture Workflow 设置中配置 DeepSeek API Key，用于完整文字稿的最终结构化整理。

2. 图片参与整理

如需课堂截图参与 AI 整理，启用「图片参与整理」并配置 Qwen。

Qwen Vision
→ 理解课堂截图
→ 生成视觉辅助上下文

Text Provider
→ 接收完整 transcript + timelineContext + visual evidence
→ 生成最终结构化 Markdown

Qwen Vision 不负责最终完整笔记的生成。

3. Realtime ASR

如需将课堂语音实时转成文字，需要完成 Qwen Realtime ASR 配置。实时识别的定稿会自动追加到当前课堂笔记的「原始文字稿」，插件不保存录音。

4. Custom OpenAI-compatible（高级）

这是面向熟悉兼容 API 的用户提供的高级配置，普通用户无需配置。只有在你主动填写并选择 Custom OpenAI-compatible Provider、随后使用相应 AI 功能时，插件才会把请求发送到你填写的 Base URL / compatible endpoint，并使用你自己填写的 API Key。Lecture Workflow 无法替第三方兼容服务保证其隐私或数据处理政策；使用前请自行确认目标服务可信。

完成 Provider 配置后，可使用对应的「测试连接」确认配置有效。如果只使用文字 AI 整理，无需配置图片理解和实时转写。

[!WARNING] API Key 保存在本地插件配置 data.json 中，当前未加密；请勿分享或提交至 Git。

课堂截图

启动课堂监听后，可以切换到网课或其他学习页面，使用你习惯的截图工具进行截图。请确保截图结果会复制到系统剪贴板，Lecture Workflow 会自动检测监听期间新复制的图片并加入当前课堂时间线。

插件只读取监听期间新复制的图片，不读取剪贴板文字，也不会自动上传图片。截图快捷键由你使用的截图工具或操作系统设置决定。只有在你主动发起图片 AI 整理并确认图片后，选中的截图才会发送给配置的第三方 Provider。

Windows Audio Companion

Windows Audio Companion 是 Windows 用户在需要直接获取系统音频时使用的可选组件。V0.1 不会自动下载、安装、解压或更新 Helper。

请从 Lecture Workflow 官方 GitHub Release 下载 0.1.3 版助手 ZIP（兼容插件 0.1.5）。0.1.3 版可直接下载 Windows x64 Helper：

lecture-workflow-windows-helper-win-x64-v0.1.3.zip

Obsidian 默认的 Vault 配置目录名称通常是 .obsidian。如果你修改过 Vault 的配置目录名称，请在下列路径中使用实际配置目录；示例中的 .obsidian 不是强制固定名称。

安装前完全退出 Obsidian，然后将 ZIP 中的内容解压到：

<Vault>/.obsidian/plugins/lecture-workflow/

最终 EXE 必须直接位于：

<Vault>/.obsidian/plugins/lecture-workflow/companion/windows/LectureWorkflow.AudioCompanion.Windows.exe

正确目录结构：

lecture-workflow/
├── main.js
├── manifest.json
├── styles.css
└── companion/
    └── windows/
        ├── LectureWorkflow.AudioCompanion.Windows.exe
        └── 其他 Helper 运行文件

不要形成重复的双层目录，例如：

companion/windows/lecture-workflow-windows-helper-win-x64-v0.1.3/LectureWorkflow.AudioCompanion.Windows.exe

0.1.3 Helper 为 Windows x64 自包含构建，包含所需 .NET 运行环境，无需额外安装。旧 0.1.1 Helper 为 framework-dependent 构建，仍需要兼容的 Microsoft.NETCore.App 10.0 与 Microsoft.AspNetCore.App 10.0 x64 shared framework；只安装「.NET 10 Desktop Runtime」不足以满足旧版要求。

删除课堂时间线中的截图后，插件会同时清理没有其他内容的时间戳条目。已遗留的空条目可通过命令「清理已删除截图的空时间戳」清理；条目中手动添加的文字和其他图片会保留。

安装完成后：

1. 重新启动 Obsidian 或重新加载 Lecture Workflow。
2. 开始课堂监听；插件会在课堂会话建立后尝试启动 Helper。
3. 在电脑上播放课程声音，打开课堂工作台，确认「系统音频助手」显示正在捕获且音量有变化；如果仍为 0%，检查 Windows 默认输出设备和播放音量。
4. 如果之前启动失败，可在工作台中重新启动系统音频。
5. 要验证实时转写，再确认 Qwen 配置和「实时转写」状态，并查看是否出现识别文字。仅看到助手连接成功不代表转写已经工作。

Helper ZIP 应保留正式 dotnet publish 输出的全部必需运行依赖，不只限于 resolver 检查的最小文件清单。PDB、源码、日志和测试产物不应进入正式 ZIP。

日常使用

1. 在 Obsidian 中打开或创建课堂笔记。
2. 从左侧 Lecture Workflow 菜单选择「开始课堂监听」。
3. 使用你习惯的工具截图，或在 Windows Helper 已安装且 Qwen ASR 已配置时使用实时转写。
4. 打开课堂工作台查看运行状态。
5. 课堂结束后停止监听，然后选择「AI 整理当前课堂笔记」。
6. 检查预览，确认结果完整且没有冲突后再写入。

数据与隐私

• API Key 仅保存在当前 Vault 的插件配置 data.json 中，当前未加密。
• 后台截图监听不读取剪贴板文字，不自动上传截图。
• 只有在用户主动执行相应功能时，插件才会向第三方 AI 服务发起请求。
• DeepSeek 用作 Text Provider；AI 整理时，用户确认的文字与上下文会发送给 DeepSeek，以生成最终结构化笔记。
• 启用图片 AI 整理后，经用户确认的图片会发送给 Qwen Vision 或用户主动选择的其他 Vision Provider，用于课堂截图视觉理解；图片不会上传到公共图床。
• 启用 Realtime ASR 后，实时 PCM 会发送给配置的 Qwen Realtime ASR 服务；插件不保存录音。
• 只有用户主动配置并选择 Custom OpenAI-compatible Provider 时，相关请求才会发送到用户填写的 Base URL。用户应自行确认该第三方兼容服务可信及其隐私政策可接受。
• Windows Audio Companion 只通过 localhost 与插件通信，在本机实时处理系统音频；Helper 不保存录音，也不会自行上传音频。
• Lecture Workflow V0.1 不包含客户端遥测，不保存录音，不会自动安装 Helper。

V0.1 能力边界

• Text Provider 结构化输出上限：8192 tokens。
• Qwen Vision 视觉证据输出上限：2048 tokens。
• 单次最多选择 10 张图片，设置范围为 1–10。
• 默认 Provider 请求超时：150 秒。
• 正常生成后如果结构校验失败，最多进行一次格式 repair，不会无限重试。
• finishReason=length 不会自动 repair；预览保留可复制结果，但不允许写入不完整内容。用户可主动重新生成。
• Provider 返回 context-limit 时，插件不会静默截断 transcript。

实际可处理的文字稿长度还受到模型上下文窗口、输出长度和第三方 API 状态影响。对于超长课程，建议先检查预览结果是否完整。更详细的已验证边界见 docs/v0.1-capability-boundaries.md。

Troubleshooting

未检测到 Windows Audio Companion

• 确认 Helper 版本与插件版本一致。
• 确认 EXE 直接位于 companion/windows/，没有多一层 ZIP 目录。
• 如使用旧 0.1.1 版，确认所需的 .NET 10 与 ASP.NET Core 10 x64 shared framework 已安装；0.1.3 自包含版本无此要求。
• 重新加载插件后再开始课堂监听，并在课堂工作台检查状态。

截图未加入时间线

确认课堂监听已启动，并确认截图工具会把图片复制到系统剪贴板。

实时转写未启动

先在 Lecture Workflow 设置中完成 Qwen 实时转写配置，并播放课程声音。文字服务的「测试连接」不能验证实时语音识别。开始课堂监听后，在工作台启动实时转写。

Qwen 实时转写超时或任务失败

工作台会显示失败阶段与可识别的原因。在「实时转写 → 详细状态」点击「复制报错详情」，可获取服务错误码、HTTP/网络状态及失败时的音频与发送情况，不含密钥、配置或识别文字。连接和任务启动分别最多等待 30 秒；这与文字服务的请求超时设置不同。

Qwen 服务端超时、本地连接超时和本地音频发送超时是不同问题。请按 实时转写排错说明 检查，并保留报错详情后再重新启动转写。

AI 结果不完整

检查预览中的完整性提示。如果结果因 finishReason=length、超时或 context-limit 失败，请根据提示主动重新生成或缩短文字稿。

开发与协议

• Windows Audio Companion 的普通用户安装与开发说明：companion/windows/README.md
• Audio Companion wire protocol：docs/audio-companion-protocol.md
• V0.1 能力边界：docs/v0.1-capability-boundaries.md

Feedback and contributions

• Found a bug? Open a Bug report.
• Have an idea? Open a Feature request.
• Want to contribute code? See CONTRIBUTING.md.

License

Lecture Workflow 使用 MIT License。随项目包含或分发的第三方组件遵循各自的许可证，详见 Third-party notices。