# 笔记工作区：远程副本与 Markdown 文件 在线时以远程为共享版本；修改先可靠地写入本机 SQLite，断网后继续保留。后台每 30 秒重连同步，也可在笔记目录的“同步与本地文件”中手动触发。此功能只处理笔记，不同步记忆、知识条目、检索索引或人物设置。 ## 本地文件与 Obsidian “同步与本地文件”显示 DSH 服务器上的 vault 目录。Obsidian 使用“打开文件夹作为仓库”；其他电脑需先挂载服务器目录。它不是浏览器所在电脑的目录。 - 正文导出为普通 UTF-8 Markdown，保留原正文，不插入插件专用 frontmatter。普通文件名和目录结构保留，附件按原文件导出。同步索引和数据库放在 vault 外。 - 文件监听触发检查，每 5 秒扫描兜底；至少两次观察到相同文件状态且稳定 1.5 秒后导入，避免记录写到一半的文件。支持可编辑文本修改、新建 `.md` / `.markdown` 和嵌套目录。隐藏目录（含 `.obsidian`、`.git`）不导入；符号链接或不完整扫描会阻止本轮同步。未变化的文件复用内容指纹，不反复读取正文。 - 中文标题、普通 Markdown 标题、代码块、frontmatter 和相对路径文本可以原样读写。OB 私有插件、`[[双链]]`、Dataview 等语义，以及 DSH 的 `note://` / 专用附件 URL 不做自动转换；不能宣称两套编辑器功能完全一致。 - 外部改名、移动先按设备、inode 和创建时间识别；跨设备或复制后删除，仅在旧笔记与新文件内容指纹唯一时自动关联。保留笔记 ID、历史和 note:// 引用。无法判断的情况暂停导入，可在“同步与本地文件”选择新路径手动关联；不会猜测重名文件。 - 外部删除经过至少 3 次完整扫描、持续至少 30 秒且无未识别新路径后，移入知识库中的“回收站（外部文件）”目录；不会物理删除正文或历史。可在同步窗口恢复，遇到同名不同内容的文件拒绝覆盖。目录删除同时检查子项，网页并发修改或新增内容时保留冲突。 - 首次初始化建立隐藏工作区标识 `.dsh-vault-id`，与 vault 外的索引绑定；已有工作区不会因路径消失而自动重建。根目录挂载/标识异常暂停全部同步；子目录身份异常暂停相应子树。重启、扫描失败后重新计算删除确认时间，不沿用旧计时。 - 原生网页/API/AI 改名和移动会同步变更磁盘路径，目录携带子项一起移动；内容和笔记 ID 不变。原生删除将磁盘副本移到隐藏的 `.dsh-deleted`，同时保存原路径记录，避免旧文件重新导入。目标被占用时保留双方并提示，不覆盖外部文件；通过持久化移动日志恢复中断操作。外部 Markdown 相对链接仍由对应编辑器维护，知识库自己的 note:// 引用不受移动影响。 - 新建二进制附件不会被目录扫描自动上传；请使用网页导入。已导出的二进制附件可被外部软件读取，但不支持外部覆盖回写。 - 文件输出采用不覆盖已有文件的独占安装；上一文件的 inode 留存在相邻 `.dsh-history` 隐藏目录，覆盖窗口内的外部写入也可找回，历史暂不自动清理。 - 文件与应用同时修改时，依据共同历史版本做保守的行级三方合并。只自动合并明确分离的变更区间；重叠、边界插入、多处修改跨越同一范围、缺少基线、无效 UTF-8 或超过 1 MiB 的内容保留冲突。同步窗口可比较双方，选择版本时再次验证指纹，过期确认会拒绝。 - 页面历史标注已知来源（网页、AI、外部文件、应用/API），旧记录不猜来源。来源用于说明调用入口，不是操作者身份认证。同步窗口显示最近文件活动（索引最多保留 500 条，窗口展示最近 30 条）；活动列表不替代正文版本历史。 - 自动识别不足、并发变更或存储故障会保留双方、停止相应操作。新路径可能等待人工确认；文件监听不可用时仍有定期扫描。没有覆盖二进制附件新增、OB 双链重写、各类第三方同步软件的全部行为。 - 文件级互操作已有自动测试；未把未安装的 Obsidian 桌面程序冒充实机验证。 ## 远程同步 客户端与远程服务端都需支持 `note-sync` 协议（插件 2.18.0 起）。远程不支持时明确显示需要升级，不冒险降级为无法去重的旧写接口。 本地模式保留现有库。远程模式按服务器 URL 与凭据指纹隔离副本，并绑定远程数据库实例 ID；更换目标或凭据不会把旧队列上传到新位置。第一次启用远程模式以远程库为起点，不会偷偷上传既有本地库；旧本地笔记及文件仍保留，迁移请显式导入。 本地内容、待同步状态、不可变操作编号保存在同一事务中。远程正文、元数据和操作回执也在同一 SQLite 事务中提交：超时后重试同一个操作，不重复新建。发送后结果未确认时不接受覆盖该笔记的新修改，先确认同步结果。 同步先检查远程版本；两边修改同一笔记时保留冲突，不按时间强制覆盖。冲突窗口展示双方内容，选择版本时再次校验两边版本。此版不自动做正文三方合并。删除核对整棵子树并原子提交；新增子项或引用保护会阻止旧删除。 远程下载先暂存磁盘，再复核完整清单；失败或清单变化不推断删除。历史内容保存在本机版本库中，远程删除也不会清理这些本地历史。同步副本不替代独立的定期备份。 ## 范围与状态 第一版最多 10000 个笔记节点、单文件 64 MiB，超限明确报错，不截断清单。未设置磁盘配额或历史自动清理，需按实际笔记规模安排磁盘空间和备份。 状态区分本机已保存、待同步、在线、授权失效、远程待升级及冲突。分享、关联仍要求远程在线且本地修改已同步；首版不支持离线复制整个目录。工具的新建免确认、修改/删除确认规则保持不变，补同步不会另发 AI 请求或注入会话。 笔记存储 schema 从 3 升到 4。部署前必须备份笔记目录；回滚旧插件必须同时恢复停机快照，不能让旧插件读取新增同步内容。测试使用独立目录和模拟/本机 HTTP 远端，不修改生产笔记正文。