# 任务包：让 NAS 的 Obsidian 知识库与用户 Windows 电脑双向同步

## 一句话目标
把 NAS 上的 `/vol1/ai/knowledge-base`（Obsidian 库）接进已有的 Self-hosted LiveSync 同步链，做到：
**NAS 文件夹 ⇄ CouchDB（在 NAS 上）⇄ 用户 Windows 电脑 / 安卓手机**，三端双向实时同步。

## 现状（已完成的部分，不用重做）
- NAS（fnOS，局域网 192.168.1.38，Tailscale 100.114.191.104）上有一个 Docker 容器 `obsidian`：
  - 镜像 `linuxserver/obsidian`（Selkies 远程桌面），Obsidian 1.14.5 简体中文
  - **只接受 HTTPS**：`https://192.168.1.38:3070/` 或 `https://homenas.tail76dbcb.ts.net/`（tailscale serve 已配好 443→127.0.0.1:3071）
  - Basic Auth 账号 `qingru`，密码 `n4uhQx7XknbC`
  - http 的 3071 端口只能本机用（Selkies 会报 requires a secure connection）
- CouchDB 容器已跑：`couchdb-livesync`，端口 5984
  - 管理员 `qingru` / `Livesync_2026_Kq7p`
  - 库：`obsidian_livesync`（给 knowledge-base 用）、`obsidian_livesync_agent`（备用，给 agent-kb）
  - CORS 已开，`require_valid_user=true`
- 两个 Obsidian 库：
  - `/vol1/ai/knowledge-base`（要同步的这个：00-收件箱 / 10-专业 / 20-生活 / 30-项目 / 90-归档 / 文献，69 篇 md + 104MB 文献 PDF）
  - `/vol1/ai/agent-kb`（个人 + 智能体，本次不需要同步）
- 插件 `obsidian-livesync` v1.0.40 已装在两个库的 `.obsidian/plugins/obsidian-livesync/`
  - **注意**：knowledge-base 的 `.obsidian/community-plugins.json` 里被我临时移除了 `obsidian-livesync`（为了压掉一个危险的确认弹窗），**需要加回去**
- 用户 Windows 电脑上的 Obsidian 1.13.7 已经装好插件，并且已经能连通 CouchDB（连接测试绿勾，连接名 `nas`，URI 用 Tailscale 地址）

## 必须遵守的约束
1. **绝对不要点**「用本设备的文件覆盖服务器数据 / Overwrite remote」这类按钮或命令 —— 会清空服务端。已出现过这个弹窗，务必取消。
2. 不要动其他服务（hermes-gateway、dsh、codex-web、minecraft-fc6、nginx 等），只允许重启 `obsidian` 容器。
3. 每台设备的 `deviceAndVaultName` 必须唯一，**不能**和用户 PC 的相同（否则同步互踢、丢改动）。
4. 容器内的 Obsidian **一次只能打开一个库**，只有当前打开的库会跑 LiveSync —— 所以要同步 knowledge-base，必须把它设为默认打开的库。
5. 不要在 `knowledge-base` 里直接删改 `.obsidian/` 之外的东西。

## 已知的坑（都实测踩过）
| 坑 | 说明与对策 |
|---|---|
| 手写 data.json 会被重置 | 插件 `loadSettings()` → `prepareSettingsForLoad()` 走迁移，legacy 扁平字段（couchDB_URI 等）会被丢掉、`remoteType` 空串表示 CouchDB。**要么拿到一份真实可用的 data.json 照着改，要么走界面向导** |
| GitHub 下载慢 | 必须走本机 mihomo 代理：`curl -x http://127.0.0.1:7890`。镜像站只有 24KB/s，直连 15KB/s，代理 166KB/s |
| Docker Hub 拉不动 | 用 `docker.m.daocloud.io/library/<image>`，compose 里已改成这个地址 |
| 容器界面自动化 | 用 `/vol1/ai/obsidian/interact.js`（CDP 点鼠标/敲键盘/截图），用法：`node interact.js http://127.0.0.1:3071/ <base64(账号:密码)> steps.json`，steps 支持 `{"click":[x,y]}` `{"type":"..."}` `{"key":"ctrl+,"}` `{"wait":ms}` `{"shot":"/path.png"}` |
| 弹窗挡操作 | 每次运行 interact.js 都是一次新页面加载，界面状态会重放；遇到模态弹窗先截图判断，再决定点哪个 |
| 库被信任弹窗拦 | 首次在本库启用社区插件会弹「你是否信任这个仓库的作者？」→ 点右侧「信任仓库作者并启用插件」（坐标约 981,596 @1600×1000） |

## 推荐做法（二选一，A 更稳）

### 方案 A：用用户 PC 上那份配置（推荐，确定性最高）
1. 让用户提供 `C:\Users\<用户名>\AppData\Roaming\obsidian\plugins\obsidian-livesync\data.json`
2. 复制一份，改两个字段：
   - `deviceAndVaultName` → `"NAS-网页版"`
   - 若有 `additionalSuffixOfDatabaseName` / `deviceId` 之类设备标识，也要换成本机特有值
   - URI 建议改成 NAS 本机可达的地址（`http://127.0.0.1:5984` 或 `http://100.114.191.104:5984` 都行）
3. 写到 `/vol1/ai/knowledge-base/.obsidian/plugins/obsidian-livesync/data.json`
4. 把 `obsidian-livesync` 加回 `/vol1/ai/knowledge-base/.obsidian/community-plugins.json`
5. `chown -R 1000:1001 /vol1/ai/knowledge-base/.obsidian`
6. 把容器默认库切成 knowledge-base：`python3 /vol1/ai/agent-kb-tools/switch-vault.py --revert`
7. `docker restart obsidian`，等 40 秒，然后按下面「验证」做

### 方案 B：在容器界面里走向导
1. 切默认库到 knowledge-base，重启容器
2. 用 interact.js 打开设置（`Ctrl+,`）→ 左侧搜索框输入 `livesync` → 点 `Self-hosted LiveSync`
3. 点「重新运行引导向导 / 快速设置」→ 选 **CouchDB** → 填：
   - URI `http://127.0.0.1:5984`
   - 用户名 `qingru`
   - 密码 `Livesync_2026_Kq7p`
   - 数据库名 `obsidian_livesync`
4. 保存 → 回首页打开「启用 LiveSync」→ 不要把任何「覆盖远端」选项勾上
5. 若弹出配置诊断/修复向导：点「确定/修复」按它建议的处理，但**拒绝一切覆盖远端的操作**

## 验证（必须全过才算完成）
1. `curl -s -u qingru:Livesync_2026_Kq7p http://127.0.0.1:5984/obsidian_livesync` → `doc_count` 从 0 增长到 **> 69**
2. 在 `/vol1/ai/knowledge-base/` 新建 `同步测试.md`（写入带当天日期的一行字），等 60 秒，再查一次 doc_count 应再增加
3. 让用户在 Windows 的 Obsidian 里确认能看到 `同步测试.md`（这就是双向通的证据）
4. 反向：让用户在电脑上改一个字，等 60 秒，在 NAS 上 `cat` 该文件确认内容变了
5. 收尾：删掉 `同步测试.md`（两端都要消失）

## 完成后要留痕（本项目硬规则）
- 记忆库：`python3 /vol1/ai/agent-kb-tools/kb.py add "<对话标题>" --turn N --project Obsidian知识库 --text "..."`（轮次标题会自动带 `YYYY-MM-DD HH:MM`）
- 流程库：`python3 /vol1/ai/agent-kb-tools/kb.py flow "接-Obsidian库接自托管LiveSync（NAS⇄PC双向）" --cat 部署 --project Obsidian知识库`，然后把文件补成五段（什么时候用 / 前提 / 命令 / 坑表 / 验证），frontmatter 必须有 `created` 与 `updated`

## 如果方案 A/B 都失败
备用方案：装 **Syncthing**（NAS 用 Docker，Windows 用官方客户端），直接对 `/vol1/ai/knowledge-base` ↔ 用户 PC 库目录做文件夹级双向同步；同时把 LiveSync 在 knowledge-base 里彻底禁用，避免两套同步打架。这条路不依赖 Obsidian 插件，成功率最高，代价是手机端要另装 Syncthing（安卓有）。
