# Flomo 快速记录 · Obsidian 插件

English README: [README.en.md](./README.en.md)｜发布说明：[RELEASE\_NOTES.md](./RELEASE_NOTES.md)

支持文字、标签、录音、相册、拍照、试听、腾讯云自动转写与补转写，保存后可跳转到对应记录。

## 安装

插件 id 为 `flomo-quick-capture`（v1.4.0 起由 `obsidian-flomo` 调整，以符合社区插件目录要求）。

把 `dist/flomo-quick-capture` 整个文件夹复制到 Vault 的 `.obsidian/plugins/`，重新加载 Obsidian，并在第三方插件中启用 **Flomo 快速记录**。停用原 **Flomo 年度记录计数** 插件，避免重复计数；Templater 可继续用于其他模板。为 `Flomo 快速记录: 快速记录` 配置快捷键，替换原模板的快捷键。

从旧 id 升级时，把 `.obsidian/plugins/obsidian-flomo/data.json` 复制到新插件目录 `flomo-quick-capture` 下即可保留文件夹配置、今日重逢会话与最近回顾列表。腾讯云凭据存于本机 SecretStorage，沿用原键，无需重新填写。

## 开发与发布

执行 `node build.js` 生成 `dist/flomo-quick-capture/`（main.js、manifest.json、styles.css），这三个文件即 GitHub Release 需要上传的附件；Release 的 Tag 必须与 manifest.json 的 version 完全一致且不带 `v`。仓库根目录需包含 README.md、LICENSE 与 manifest.json，随后在 community.obsidian.md 提交插件即可。

## 设置与使用

在设置 → Flomo 快速记录中分别配置笔记、录音、图片文件夹，路径相对于当前 Vault；支持自动创建多级目录。默认沿用 `01.快速记录/flomo-import`、其下的 `record` 和 `images`。修改配置影响以后保存，不移动已有文件；如需补转写旧文件，使用原笔记与录音目录配置。

笔记按 `YYYY年.md` 归档，每条记录使用 `## YYYY-MM-DD HH:mm:ss` 标题。noteCount 统计文档内这种标题的数量，排除代码块；保存、手动编辑、新建、移入目录和启动插件后约 700ms 自动更新，保留其他属性。只处理指定笔记文件夹直属的年度笔记。原有时间索引存在时，新记录保存后也会更新对应年份的条数。

腾讯云 AppID、SecretId、SecretKey 在插件设置填写，沿用原模板的本机 SecretStorage 键。凭据不写入 data.json，手机需要单独设置。可关闭自动转写，仅保存录音。音频发送至腾讯云极速版，需已开通服务及对应额度；MP4/M4A/WebM 等在设备上尝试转换 WAV。录音及转换后的音频大小上限 100MB。请保持应用在前台。

在插件设置中点击「补转写已有录音 → 开始补转写」可处理未完成的录音。快速记录弹窗不再显示补转写按钮。

命令：快速记录、补转写已有录音、重新统计所有年度笔记、恢复未保存记录。

转写失败保留录音；转写结果回填失败时沿用本机恢复缓存。记录保存失败会保留草稿，重新打开快速记录即可恢复。重试可能留下之前失败保存产生的附件副本。

## 开发与验证

使用 Node.js 执行 `node build.js` 生成独立安装包（无 npm 依赖）。`main.js` 为生命周期和设置，`capture.js` 为记录和腾讯云转写，`count.js` 为计数，`paths.js` 为路径处理。样式在 `styles.css`。

执行 `node --test tests/*.test.js`。测试包括 YAML/CRLF/BOM、代码块排除、增删记录、启动及事件回调、避免重复写入，并只读检查现有年度文档。真实麦克风、移动端与腾讯云识别需在 Obsidian 内验证；测试不会调用付费接口。

输入 `#` 可选择当前 Vault 已有标签（正文及属性标签），支持中文、嵌套标签与输入筛选。↑↓ 选择，Enter/Tab 插入，Esc 关闭，也可直接点击；无匹配时可继续输入新标签。

## v1.1.0 草稿与移动端输入

输入后约 600ms 将文字自动保存到本机 IndexedDB；图片与已停止的录音一起保存。关闭或「稍后继续」会先保存，录音中关闭会先停止录音并保存。下次打开或重载插件后自动恢复，底部显示「草稿已恢复」，可点击红色「丢弃草稿」并再次确认。正式笔记写入成功才清除草稿；草稿写入失败只显示「草稿未保存 · 重试」，并保持窗口打开。草稿仅限当前设备、当前 Vault，不通过 iCloud 同步，不包含密钥。系统强制终止时，尚未落盘的输入及仍在录制的音频不能保证恢复。

图片入口统一为「添加图片」，直接打开系统图片选择器；相册、相机的具体选项由系统提供。移动端根据 visualViewport 可视高度避让键盘，固定底部操作区，中间内容可滚动。标签列表悬浮于光标附近，自动选择上方或下方，不占据正文布局；支持中文输入法组合输入和键盘选择。

浏览器集成测试 `node tests/browser.cjs` 需要 Playwright 和 Chrome；可通过 `FLOMO_PLAYWRIGHT_PATH`、`FLOMO_CHROME_PATH` 指定路径。测试使用独立的临时浏览器数据和模拟 Vault，不调用腾讯云；覆盖页面重载后的文字及 Blob 恢复、丢弃、失败重试、正式写入失败保留草稿、键盘可视高度及标签弹层不造成布局变化。实际 iOS/Android 键盘还需真机确认。

## v1.1.1 录音操作

录音停止后，工具栏的「开始录音」变为「重录」「删除」，播放器下方不再单独显示移除按钮。删除后恢复「开始录音」。重录成功才替换当前录音；权限被拒绝或录音中断时保留原录音，避免误丢失。恢复录音草稿时同样显示重录和删除。

## v1.1.3 手机布局修复

工具栏移除负边距并限制为容器宽度，增加按钮内侧留白，消除裁切及横向滚动。手机弹窗覆盖主题的位置与变换规则。键盘避让同时响应 visualViewport、原生 keyboardWillShow/Hide 事件，以及 Obsidian 的 --keyboard-height；采用最小可见边界，避免原生通知与视口缩小重复扣除键盘高度。手机同步 main.js、styles.css、manifest.json 后需重新加载插件，版本应显示 1.1.3。

## 附件清理（v1.2.0）

打开「设置 → Flomo 快速记录 → 附件清理 → 扫描与预览」，点击「扫描附件」。仅扫描配置的录音、图片目录内，由插件生成的 recording- 和 image- 媒体文件，不处理普通附件、原 flomo 导入附件和隐藏目录。

扫描会核对整个 Vault 内的 Markdown、Canvas、Base 等文本引用，并按文件实际内容识别重复副本。候选显示路径、大小和重复副本信息，可点「预览」查看文件。仅列出未找到文本引用的附件，默认全部不勾选；被引用、正在转写或有待回填结果的附件会保护。

逐项勾选后点击「移入回收站」，再点击「确认移入回收站」。每个文件清理前都会重新核对引用和文件状态，新出现引用或发生变化的文件会跳过。文件移入 Vault 的隐藏 .trash 文件夹，可从该位置找回，不永久删除。外部应用、PDF 等二进制文档中的引用不在扫描范围，仍请先预览。

快速记录、保存或转写进行中不能清理。扫描不会修改任何文件；实际清理完成后会显示移入、跳过和失败数量。

## 今日重逢（v1.3.1）

v1.3.2 修复弹窗标题重复显示：保留 Obsidian 原生标题栏，内容区仅显示副标题与进度。

v1.3.3 移除卡片内重复的「在年度笔记中打开 ↗」链接，点击卡片即可跳转。

命令面板运行「Flomo 快速记录：今日重逢」，从年度笔记的记录中随机抽取几条，一屏一条逐条浏览：日期与「X 天前」、正文全文（自动隐藏图片与录音嵌入行）、标签、首图缩略图和含录音标记。点击卡片跳转定位到原记录，弹窗保持打开、浏览位置不变，可用「上一条 / 下一条」继续；看完最后一条点「完成」进入完成页，可「再来一批」或关闭。

每天看到的是同一批旧时光：当天的批次与浏览进度（第几条、是否完成）保存在插件设置中，关闭后再打开会接着上次的进度看，不会重新抽样。到「每日批次刷新时间」后的下一次打开才生成新的一批。默认 09:00 刷新，可改为 00:00 / 06:00 / 12:00，设为 00:00 即按自然日刷新；凌晨刷新时刻之前打开，仍接着昨天的批次，标题日期也显示回顾日，语义自洽。

设置中可配置每次条数（3–5 条，默认 3）和范围（全部年份或近一年，按记录日期过滤）。开新批次时会优先避开最近回顾过的约 50 条记录，候选不足时自动放宽允许重复。回顾只读取笔记，不修改任何文件；批次与进度不写入笔记，仅保存在插件 data.json 中。