# 拾光插件介绍与使用手册

> 适用对象：希望把文字、照片、视频、录音、文件、灵感与生活片段长期沉淀到 Obsidian 的用户。  
> 插件名称：**拾光**  
> 当前定位：一个本地优先的生活时间线、Inbox 采集、多媒体相册、语音转写与星云漫游回忆系统。

---

## 1. 插件简介

**拾光** 是一款面向 Obsidian 的生活记录插件。它把文字、图片、视频、录音、普通文件、标签、喜欢、评论、语音转写、Markdown 导出和相册漫游整合到一个独立视图中。

它的核心理念是：

> **先收进来，稍后再整理。**

一张照片、一段录音、一个临时想法、一张票据、一次旅行、一段工作灵感，或者任何值得保存的日常片段，都可以先被快速收进来。之后再通过时间线、日历、资源库、星云漫游、搜索和标签进行回看与整理。

---

## 2. 核心功能概览

| 功能 | 说明 |
| --- | --- |
| 时间线记录 | 按日期组织所有生活记录，支持文字、图片、视频、录音和文件混合展示。 |
| Inbox 快速采集 | 在侧栏快速输入文字、粘贴图片、添加附件、拍照、录音和打标签。 |
| 新增/编辑记录 | 记录支持日期、标签、正文、图片、视频、录音、普通文件。 |
| 批量导入图片 | 可一次导入多张图片，并按图片修改时间或导入时间生成记录。 |
| 日历视图 | 以月历方式查看每天是否有记录、是否有媒体，并可跳回时间线。 |
| 资源库视图 | 集中浏览图片、视频、录音、文件和喜欢的纯文字片段。 |
| 星云漫游 | 把照片变成星点，在螺旋星系、星云盘面、宇宙视角中漫游回忆。 |
| 拾光漫步 | 以沉浸式胶片/轮播方式播放照片记忆，支持全屏和键盘控制。 |
| 搜索与筛选 | 支持正文、日期、标签、评论、文件名、语音转写文本搜索。 |
| 喜欢与评论 | 每条记录可喜欢、评论、删除评论，用于二次整理。 |
| 语音转文字 | 可调用本地或局域网 HTTP 接口转写录音，并参与搜索。 |
| Markdown 导出 | 可选择记录并导出为 Markdown 文件，包含媒体链接、评论和转写内容。 |
| 本地优先存储 | 媒体文件保存在 Obsidian 仓库内，便于同步和长期保存。 |
| CLI/Agent 支持 | 提供本地 CLI，方便 Agent 采集、搜索、评论、点赞、转写和导出。 |

---

## 3. 安装与构建

如果拿到的是发布包，将以下文件放入 Obsidian 仓库插件目录：

```text
.obsidian/plugins/Momento/
  manifest.json
  main.js
  styles.css
```

然后在 Obsidian 中进入：

```text
设置 -> 第三方插件
```

启用 **拾光**。

如果拿到的是源代码，需要先构建：

```bash
npm install
npm run build
```

构建完成后再把 `manifest.json`、`main.js`、`styles.css` 放入插件目录。

---

## 4. 插件入口

启用后可以通过三种方式使用拾光：

1. 点击左侧 Ribbon 图标 **打开拾光**。
2. 在命令面板执行 `打开拾光`。
3. 在命令面板执行 `新增拾光记录` 或 `批量导入图片`。

当前命令包括：

| 命令 | 用途 |
| --- | --- |
| 打开拾光 | 打开主视图。 |
| 新增拾光记录 | 直接打开新增记录弹窗。 |
| 批量导入图片 | 一次选择多张图片并生成记录。 |

---

## 5. 主视图结构

拾光主视图顶部包含：

- `+`：新增记录。
- 视图切换：时间线、日历、资源库、漫游。
- 刷新按钮：重新加载数据。
- Inbox 入口：移动端或窄屏下快速打开采集区。
- 更多菜单：刷新、批量导入图片、随机漫游、选择导出。

当前主视图支持四种模式：

| 模式 | 适合用途 |
| --- | --- |
| 时间线 | 日常浏览、编辑、评论、喜欢、导出。 |
| 日历 | 按月份回看记录频率和日期分布。 |
| 资源库 | 集中查找照片、视频、录音、文件。 |
| 漫游 | 以星云、星系和胶片方式回看照片。 |

---

## 6. 新增与编辑记录

点击顶部 `+` 或命令 `新增拾光记录` 后，会打开记录弹窗。

可填写和添加：

- 日期。
- 标签。
- 正文内容。
- 图片。
- 视频。
- 录音。
- 普通文件附件。

保存后记录会出现在时间线中。双击时间线中的记录卡片可以重新编辑。

### 6.1 添加媒体

资源区域支持：

| 操作 | 说明 |
| --- | --- |
| 添加附件 | 选择任意文件。 |
| 添加图片 | 选择一张或多张图片。 |
| 随手拍 | 在支持的设备上调用相机拍照。 |
| 录音 | 调用麦克风录制音频。 |
| 粘贴图片 | 在正文输入区直接粘贴剪贴板图片。 |

插件会按文件类型保存到不同字段：

| 类型 | 字段 |
| --- | --- |
| 图片 | `images` |
| 视频 | `videos` |
| 录音/音频 | `audios` |
| 其他文件 | `files` |

常见音频格式：`mp3`、`wav`、`m4a`、`aac`、`flac`、`webm`、`ogg`。  
常见视频格式：`mp4`、`webm`、`ogg`、`mov`、`avi`、`mkv`。

### 6.2 录音

点击麦克风按钮开始录音。录音过程中会显示状态和时长。再次点击或停止后，录音会作为音频文件加入当前记录。

保存记录后，如果设置中开启了 **保存录音后自动转写**，插件会在后台调用语音转文字接口。

---

## 7. Inbox 快速采集

Inbox 用于快速收集尚未整理的内容，适合：

- 临时想法。
- 待办事项。
- 灵感。
- 截图。
- 票据。
- 路上的随手拍。
- 会议录音。

在时间线侧栏找到 **Inbox 采集**，可以输入文字，也可以添加附件、图片、拍照、录音和标签。

快捷保存：

```text
Ctrl + Enter
Command + Enter
```

保存后会生成一条新记录，并默认带有 `Inbox` 标签。

---

## 8. 批量导入图片

通过命令面板或更多菜单执行：

```text
批量导入图片
```

可一次选择多张图片。每张图片会生成一条记录。

批量导入受以下设置影响：

| 设置 | 说明 |
| --- | --- |
| 默认时间模式 | 使用图片 `lastModified` 时间，或使用当前导入时间。 |
| 默认标签 | 导入记录自动添加的标签，可用逗号分隔多个标签。 |
| 默认文字 | 导入记录自动填入的正文内容，可留空。 |

默认标签为 `inbox`。

---

## 9. 时间线模式

时间线是默认视图，按日期展示记录。

支持：

- 按日期分组。
- 图片、视频、录音、文件混合展示。
- 图片灯箱预览。
- 视频播放。
- 录音播放与转写。
- 文件链接打开。
- 喜欢记录。
- 添加和删除评论。
- 双击编辑记录。
- 删除记录及关联媒体。
- 选择记录并导出 Markdown。
- 按日期跳转。

侧栏包含：

- 搜索框。
- 类型筛选。
- 标签筛选。
- 日期导航。
- 统计信息。
- Inbox 采集区。

可筛选类型：

| 筛选 | 说明 |
| --- | --- |
| 全部 | 显示所有记录。 |
| 图片 | 只看含图片的记录。 |
| 视频 | 只看含视频的记录。 |
| 录音 | 只看含录音的记录。 |
| 文件 | 只看含普通文件的记录。 |
| 文字 | 只看不含媒体的文字记录。 |
| 喜欢 | 只看已喜欢的记录。 |

---

## 10. 日历模式

日历模式以月历展示记录分布。

特点：

- 有记录的日期会显示数量标记。
- 有图片的日期会显示缩略图。
- 视频、录音、文件会以简短标记显示。
- 点击日期可跳转到时间线对应位置。
- 支持上月、下月、今天跳转。

适合查看记录频率、旅行日期、成长节点和某个月的生活密度。

---

## 11. 资源库模式

资源库集中展示所有媒体和文件。

可浏览：

- 图片。
- 视频。
- 录音。
- 普通文件。
- 已喜欢的纯文字记录片段。

支持：

- 类型筛选。
- 标签筛选。
- 喜欢筛选。
- 关键词搜索。
- 图片灯箱预览。
- 视频播放。
- 录音播放和转写。
- 删除媒体文件并同步更新记录。

资源库使用分批加载，媒体较多时也会逐步渲染，避免一次性加载过重。

---

## 12. 漫游模式

漫游模式只使用含图片的记录。它会把所有照片解析成照片星点，并按时间、月份和标签组织成可漫游的视觉空间。

顶部提供：

- 搜索框。
- 形态切换按钮。
- `拾光漫步` 入口。
- 全屏按钮。

底部提供月份时间轴：

- 点击月份可突出该月照片。
- 点击 `全部记忆` 可恢复全部照片。
- 全屏时底部时间轴会自动弱化，悬停后显示。

### 12.1 三种星云形态

形态切换按钮会在以下三种形态之间循环：

| 形态 | 效果 |
| --- | --- |
| 螺旋星系 | 彩色星点按螺旋星系分布，适合整体漫游。 |
| 星云盘面 | 灰白星尘形成扁平银河漩涡，图片以彩色星点点缀其中。 |
| 宇宙视角 | 图片沿空间通道展开，适合穿梭式查看。 |

星云盘面的设计逻辑：

- 背景星尘形成灰白螺旋银河。
- 图片在远处表现为彩色星点。
- 靠近图片星点后才显示真实缩略图。
- 点击星点或缩略图会打开照片详情。

### 12.2 照片详情

点击漫游中的照片后，会打开详情弹窗，包含：

- 大图预览。
- 日期。
- 标签。
- 原记录正文，支持 Markdown 渲染。
- 跳转到对应时间线记录。

### 12.3 拾光漫步

点击 `拾光漫步` 可进入沉浸式照片播放。

支持：

- 胶片式底部缩略图轨道。
- 自动播放/暂停。
- 左右方向键切换。
- 空格播放/暂停。
- `Esc` 退出或退出全屏。
- 纯净全屏查看。

---

## 13. 搜索与筛选

搜索会覆盖以下内容：

- 正文。
- 日期。
- 标签。
- 文件名。
- 评论。
- 语音转写文本。

搜索在时间线、资源库和漫游中都有对应入口。时间线和资源库还提供类型、标签、喜欢等筛选方式。

---

## 14. 喜欢、评论与删除

每条记录支持：

- 喜欢：用于标记重要回忆、精选照片或需要回看的内容。
- 评论：用于补充想法、复盘、家人补充说明或整理备注。
- 删除评论：可删除单条评论。
- 删除记录：删除记录时会尝试把关联媒体移动到系统回收站。

资源库中删除某个媒体文件时，会同步从对应记录字段中移除该媒体。

---

## 15. 语音转文字

拾光支持调用本地或局域网 HTTP 接口进行录音转写。

默认接口：

```text
http://127.0.0.1:8765/transcribe
```

请求方式：

```http
POST /transcribe
Content-Type: application/octet-stream
X-Filename: voice_123456.webm
X-Language: zh
```

请求体为原始音频二进制。

支持返回：

```json
{
  "text": "转写文本"
}
```

或：

```json
{
  "transcript": "转写文本"
}
```

或：

```json
{
  "segments": [
    { "text": "第一段" },
    { "text": "第二段" }
  ]
}
```

也可以直接返回纯文本。

转写结果会保存到记录的 `audioTranscripts` 字段，并显示在录音卡片下方，同时参与搜索和导出。

---

## 16. Markdown 导出

在时间线的更多菜单中选择：

```text
选择导出
```

进入选择模式后，可以选择单条或多条记录并导出为 Markdown。

导出内容包含：

- 导出时间。
- 记录数量。
- 日期。
- 标签。
- 喜欢数。
- 创建时间。
- 正文内容。
- 图片链接。
- 视频链接。
- 录音链接。
- 普通文件链接。
- 语音转写文本。
- 评论。

导出文件默认保存到：

```text
拾光导出/
```

导出完成后会自动打开生成的 Markdown 文件。

---

## 17. 设置项

进入：

```text
设置 -> 第三方插件 -> 拾光设置
```

当前设置包括：

| 设置 | 默认值 | 说明 |
| --- | --- | --- |
| 媒体存储文件夹 | `life-media` | 图片、视频、录音、文件保存到仓库内的相对路径。 |
| 排列顺序 | 最新的在前 | 时间线倒序或正序。 |
| 自动写入对应日期的日记 | 关闭 | 新增、编辑或批量导入记录后，同步到记录日期对应的 Markdown 日记。 |
| 日记路径模板 | `YYYY-MM-DD.md` | 支持 `YYYY`、`MM`、`DD`，例如 `日记/YYYY-MM-DD.md`。 |
| 随机漫游 | 关闭 | 可随机跳转到一条历史记录，首次打开时间线时也可自动漫游。 |
| 批量导入默认时间模式 | 图片修改/创建时间 | 批量导入时使用图片时间或导入时间。 |
| 批量导入默认标签 | `inbox` | 批量导入图片自动添加的标签。 |
| 批量导入默认文字 | 空 | 批量导入图片自动填入的正文。 |
| 语音转文字接口 | `http://127.0.0.1:8765/transcribe` | 本地或局域网转写接口。 |
| 保存录音后自动转写 | 关闭 | 新增含录音记录后自动调用转写接口。 |
| 场景标签列表 | 旅行、学习、日常、健康、工作、票据、重要 | 新增记录、Inbox 和筛选器中使用的常用标签。 |

设置页底部会显示当前记录总数和媒体/文件总数。

### 17.1 媒体路径安全

媒体文件夹必须是仓库内相对路径。

推荐：

```text
life-media
assets/life-media
attachments/shiguang
```

不建议：

```text
C:/Users/xxx/Desktop
/Users/xxx/Desktop
../media
```

如果路径为空、为绝对路径、包含 `..` 或非法片段，插件会自动回退到 `life-media`。

---

## 18. 文件与数据存储

插件数据通过 Obsidian 插件数据机制保存，主要包含：

- 设置。
- `entries` 记录列表。
- 标签。
- 喜欢数。
- 评论。
- 语音转写文本。

媒体文件默认保存到：

```text
life-media
```

如果该目录不可写，插件会依次尝试：

1. Obsidian 默认附件路径。
2. 仓库根目录。

删除记录或媒体时，插件会优先移动到系统回收站，而不是直接永久删除。

---

## 19. CLI 与 Agent 用法

拾光提供本地 CLI，适合 Agent 自动采集、搜索、评论、点赞、转写和导出。

CLI 路径：

```text
cli/shiguang.js
```

常用命令：

```powershell
node cli/shiguang.js doctor --data "<vault>\.obsidian\plugins\Momento\data.json" --vault "<vault>" --json
```

快速记录：

```powershell
node cli/shiguang.js capture "今天整理了会议纪要" --tag "工作,会议" --data "<data.json>" --json
```

搜索：

```powershell
node cli/shiguang.js search "会议" --tag "工作" --data "<data.json>" --json
node cli/shiguang.js list --date "2026-05-26" --type audio --data "<data.json>" --json
```

评论和喜欢：

```powershell
node cli/shiguang.js comment add "<entry-id>" "下次提前准备材料" --data "<data.json>" --json
node cli/shiguang.js like "<entry-id>" --data "<data.json>" --json
```

添加媒体：

```powershell
node cli/shiguang.js media add "<entry-id>" "D:\media\meeting.m4a" --type audio --vault "<vault>" --data "<data.json>" --json
```

转写录音：

```powershell
node cli/shiguang.js transcribe "<entry-id>" --vault "<vault>" --data "<data.json>" --json
```

导出 Markdown：

```powershell
node cli/shiguang.js export markdown --entry "<entry-id>" --out "<vault>\拾光\导出\会议整理.md" --data "<data.json>" --json
```

> 注意：CLI 会直接写入插件 `data.json`。如果 Obsidian 正打开拾光界面，避免同时编辑同一条记录。CLI 写入后可点击拾光界面的刷新按钮重新加载数据。

Skill 说明位于：

```text
shiguang-skill/SKILL.md
```

CLI 回归测试：

```powershell
npm run test:cli
```

---

## 20. 推荐工作流

### 20.1 日常记录

1. 打开拾光。
2. 使用 Inbox 快速收集想法、截图、录音或照片。
3. 晚上在时间线中补充标签和说明。
4. 喜欢重要记录。
5. 周末用日历或星云漫游回看。

### 20.2 照片整理

1. 使用批量导入图片。
2. 让插件按图片时间生成记录。
3. 在资源库中集中查看图片。
4. 在漫游模式中用星云盘面或螺旋星系浏览照片。
5. 进入拾光漫步播放精选照片。

### 20.3 语音灵感

1. 在 Inbox 或新增记录中录音。
2. 保存记录。
3. 手动点击转写，或开启自动转写。
4. 后续通过关键词搜索录音内容。
5. 将转写内容整理为正式笔记。

### 20.4 旅行复盘

1. 每天导入照片和票据。
2. 添加 `旅行` 标签。
3. 用时间线按天回看。
4. 用资源库筛选照片、视频和文件。
5. 选择记录导出为 Markdown 游记。

---

## 21. 常见问题

### Q1：为什么附件保存失败？

可能原因：

- 媒体文件夹路径不是仓库内相对路径。
- 当前设备或同步目录不可写。
- 文件为空。
- 文件名包含非法字符。

建议把媒体文件夹设为：

```text
life-media
```

### Q2：为什么无法打开摄像头？

可能原因：

- 当前设备不支持摄像头调用。
- 系统或 Obsidian 未授权摄像头。
- 桌面端环境不支持当前拍照方式。

插件会在无法拍照时回退到图片选择。

### Q3：为什么录音失败？

可能原因：

- 麦克风权限未开启。
- 当前设备不支持 `MediaRecorder`。
- 系统或 Obsidian 阻止录音。

请检查系统麦克风权限和 Obsidian 权限。

### Q4：为什么语音转写失败？

可能原因：

- 未配置接口地址。
- 本地转写服务未启动。
- 接口返回格式不符合要求。
- 网络不可达。
- 音频格式不被后端服务支持。

### Q5：为什么搜索不到录音内容？

只有已经完成转写的录音，其转写文本才会参与搜索。请先点击录音卡片中的转写按钮，或开启 **保存录音后自动转写**。

### Q6：为什么漫游模式里没有内容？

漫游模式只读取含图片的记录。如果没有图片记录，会显示空状态。请先新增或批量导入照片。

### Q7：删除记录会删除附件吗？

会尝试删除。删除方式是移动到系统回收站，而不是直接永久删除。

---

## 22. 一句话总结

**拾光把 Obsidian 扩展成一个本地优先的生活记忆系统：能快速采集，能长期沉淀，能按时间线整理，也能把照片变成可以漫游的星河。**