给 AI 看的设置教程（AI 改 data.json 必读）

笔记同步助手 · 2026年5月9日 ·Obsidian 教程

ObsidianAI设置教程

给 AI 看的设置教程（AI 改 data.json 必读）

这页是写给 AI 助手（Claude / ChatGPT / Gemini / 豆包 / DeepSeek 等）看的。 如果你是用户，请把这页 URL 发给 AI 后再请它帮你改设置。

如果你是 AI：用户请你改笔记同步助手插件设置，但你没有完整看过这页文档时，请先把本页内容读完再下手。曾经因为 AI 凭”听起来合理”自创字段（如 after:{{{lastSyncTime}}}）导致用户同步整体失效，请严格按本页约束修改。

1. 配置文件位置

笔记同步助手把所有设置写在 vault 里这个 JSON 文件：

<用户的 Obsidian Vault 根目录>/.obsidian/plugins/notehelper/data.json

vault 根目录就是用户在 Obsidian 里”打开/创建保管库”时选的那个目录
.obsidian 是隐藏目录（Windows 默认隐藏，Mac 用 Cmd+Shift+.）
插件 ID 固定是 notehelper，不要写成 obsidian-notehelper 或 notehelper-plugin

编辑流程（强制）：

关掉 Obsidian 或确认插件设置面板没打开 —— 防止 Obsidian 内存里的旧设置回写覆盖你
用普通文本/JSON 编辑工具修改 data.json
保存文件，确保仍是合法 JSON（key 加双引号、不要尾逗号）
让用户重新打开 Obsidian，进 设置 → 第三方插件 → 笔记同步助手 肉眼检查改动是否生效
让用户点一次左侧”同”图标做一次同步验证 —— 改完后第一次同步不报错且能落盘新文章，才算改对了

⚠️ 不要用插件 UI 的输入框做”代理”，直接改 JSON 文件最准确。但 UI 里的 自定义查询 / 筛选器 这两个输入框有副作用（每次按键都会清空 syncAt 和 deviceSyncCursors[deviceId]），改 data.json 不会触发这些副作用 —— 你需要自己判断是否应当一并清空。

2. 字段总表

以下表格按插件设置面板的分组列出所有 AI 可以改的字段。没有列出的字段不要动（比如 version intervalId 是插件内部状态）。

2.1 密钥与端点

key	类型	默认	说明 / 约束
`apiKey`	string	`""`	用户的密钥。绝对不要凭空生成。用户没明示新密钥时不要改，保持原值。
`endpoint`	string	`"https://obsidian.notebooksyncer.com/api/graphql"`	GraphQL 服务端地址。只在用户明确换私有部署时改，否则保持默认。

2.2 查询（控制同步范围）⚠️ 高危区

key	类型	可选值	默认	说明
`filter`	string	只能是 `"ALL"`	`"ALL"`	当前服务端只支持 `ALL`。不要写 `"HIGHLIGHTS"` `"ARCHIVED"` `"LIBRARY"` —— 旧版枚举，已不在 UI 里出现。
`customQuery`	string	见下方白名单	`""`	AI 最容易写错的字段，详见 §3.1
`syncAt`	string (ISO)	任意 ISO 时间戳，或 `""`	`""`	上次同步时间游标。改它会影响下次拉哪些文章
`initialSyncCompleted`	boolean	`true` / `false`	`false`	首次同步是否已完成。和 `syncAt`、`customQuery` 联动，详见 §3.2
`deviceSyncCursors`	object	`{ "<deviceId>": "<ISO>" }`	`{}`	每台设备独立的同步游标，优先级高于 `syncAt`。改 `syncAt` 时通常也要同步改对应 deviceId 的值

2.3 同步频率（按设备独立）

key	类型	可选值	默认	说明
`deviceAutoSync`	object	`{ "<deviceId>": { "frequency": <int>, "syncOnStart": <bool> } }`	`{}`	每台设备独立的自动同步配置，是当前生效的字段
`deviceAutoSync.<id>.frequency`	int (秒)	`0` 或 `>= 15`	`0`	`0` = 关闭定时同步；其他必须 ≥ 15。常用：`60` / `300` / `1800`
`deviceAutoSync.<id>.syncOnStart`	boolean	`true` / `false`	`false`	启动 Obsidian 时自动同步一次
`deviceAutoSyncMigrated`	boolean	`true` / `false`	`false`	不要动，是顶层 `frequency`/`syncOnStart` 已迁移到 `deviceAutoSync` 的标志
`frequency`	int	—	`0`	遗留字段，已迁移到 `deviceAutoSync`。可以保留但不要把它当作”当前频率”读
`syncOnStart`	boolean	—	`false`	遗留字段，同上
`intervalId`	int	—	`0`	不要动，运行时 `setInterval` 句柄

2.4 文件夹与文件名（支持 Mustache 模板）

字段值里的 {{{xxx}}} 是 Mustache 三花括号变量，渲染时会被替换。支持的变量详见模板变量完全指南，常用：{{{title}}} {{{date}}} {{{dateSaved}}} {{{yearSaved}}} {{{monthSaved}}} {{{daySaved}}} {{{author}}} {{{siteName}}} {{{originalUrl}}} {{{labels}}}。

key	类型	默认	说明
`folder`	string	`"笔记同步助手/{{{date}}}"`	文章文件夹路径模板
`folderDateFormat`	string (Luxon)	`"yyyy-MM-dd"`	`folder` 里 `{{{date}}}` 的日期格式
`filename`	string	`"{{{title}}}"`	文章文件名模板
`filenameDateFormat`	string (Luxon)	`"yyyy-MM-dd"`	`filename` 里日期变量的格式
`attachmentFolder`	string	`"笔记同步助手/attachments"`	普通附件存储路径
`messageFolder`	string	`""`	合并消息文件夹路径，留空则回退到 `folder`
`singleFileName`	string	`"同步助手_{{{date}}}"`	合并模式下单文件的文件名模板
`singleFileDateFormat`	string (Luxon)	`"yyyy-MM-dd"`	`singleFileName` 里日期格式

2.5 合并模式

key	类型	可选值	默认	说明
`mergeMode`	string	`"none"` / `"messages"` / `"all"`	`"messages"`	`none`=每篇独立；`messages`=助手消息按日合并、文章独立（推荐）；`all`=同名文章和消息都合并
`messageSortOrder`	string	`"desc"` / `"asc"`	`"desc"`	合并文件里消息的排序，仅 `mergeMode != "none"` 时生效

2.6 图片处理

key	类型	可选值	默认	说明
`imageMode`	string	`"local"` / `"remote"` / `"disabled"`	`"local"`	`local`=下载到本地；`remote`=保留外链；`disabled`=注释掉图片不显示
`enablePngToJpeg`	boolean	`true` / `false`	`false`	仅 `imageMode="local"` 时生效，PNG 转 JPEG 节省空间（丢透明）
`jpegQuality`	int	`0` ~ `100`（步进 5）	`85`	仅 `enablePngToJpeg=true` 时生效
`imageDownloadRetries`	int	`>= 0`	`3`	图片下载失败重试次数
`imageAttachmentFolder`	string	—	`"笔记同步助手/images"`	图片本地存储文件夹，支持模板变量
`imageUploadRelay`	string	`"none"` / `"iaup"` / `"iutk"` / `"ciup"`	`"none"`	桌面端可选，把本地图片接力给三方上传插件。`iaup`=Image auto upload；`iutk`=Image Upload Toolkit；`ciup`=Obsidian Image Uploader (Creling)

2.7 内容处理

key	类型	可选值	默认	说明
`escapeHashtags`	boolean	`true` / `false`	`false`	把正文里的 `#标签` 转义成 `\#标签`，防止干扰 Obsidian 标签体系

2.8 日记链接

仅 enableDiaryLinks=true 时下面这些字段才被读，但保留它们的值不会有副作用。

key	类型	可选值	默认	说明
`enableDiaryLinks`	boolean	`true` / `false`	`false`	总开关
`autoCreateDiaryNote`	boolean	`true` / `false`	`false`	自动创建当天日记。开启时 `diaryFolder` / `diaryDateFormat` 由 Daily Notes / Periodic Notes 插件接管
`diaryFolder`	string	—	`"Daily Notes"`	日记文件夹路径
`diaryDateFormat`	string (Luxon)	—	`"yyyy-MM-dd"`	日记文件名日期格式。固定文本要单引号转义，例：`"'日记' yyyy-MM-dd"`
`diaryAnchor`	string	—	`"notehelper-links"`	日记锚点标识（HTML 注释里的字符串，要在日记模板里成对出现）
`diaryLinkType`	string	`"all"` / `"messages"` / `"articles"`	`"all"`	链接哪些内容到日记
`diaryLinkPrefix`	string	—	`"- "`	双链前缀，常见 Markdown 列表项
`diaryLinkMaxLength`	int	`>= 0`	`0`	双链显示文字最大字符数，`0` = 不限制

2.9 高级选项（前置元数据 / 模板）⚠️ 易写错

key	类型	默认	说明
`frontMatterVariables`	string[]	`[]`	简易模式：用变量名数组（如 `["title","author","date_saved"]`）让插件自动生成 YAML。白名单见 §3.3
`frontMatterTemplate`	string (YAML 模板)	见 §3.4	高级模式：完整 YAML 模板字符串。配置后会覆盖 `frontMatterVariables`。错误模板会让笔记 frontmatter 整段变成 `omnivore_error`
`template`	string (Mustache)	见插件 `DEFAULT_TEMPLATE`	文章正文渲染模板，常见值 `"{{{content}}}"`
`dateSavedFormat`	string (Luxon)	`"yyyy-MM-dd HH:mm:ss"`	模板里 `{{{dateSaved}}}` 的日期格式
`wechatMessageTemplate`	string (Mustache)	`"---\n#### {{{heading}}}\n## 📅 {{{dateSaved}}}\n{{{content}}}"`	助手消息（同步助手_yyyyMMdd_xxx 这类）的简洁模板
`enableDebugLog`	boolean	`false`	开启浏览器控制台调试日志

3. 危险红线（一定要看）

3.1 `customQuery` 必须用白名单语法

服务端的查询解析器只认识 4 种 prefix：in: / has: / updated: / sort:。其它 token（包括但不限于 after: before: tag: q: keyword:）会被当成全文关键词做模糊搜索，命中数通常为 0，导致同步看似成功但 0 落盘。

白名单可选值（直接照抄即可）：

用户意图	`customQuery` 写法
同步所有文章（默认）	`"in:all"` 或留空 `""`（留空时插件按 `filter` 自动回填）
只要带高亮的	`"in:all has:highlights"`
只要归档的	`"in:archive"`
只要未归档库里的	`"in:library"`

严禁的写法：

❌ "after:{{{lastSyncTime}}}" —— 服务端不认 after:，且 customQuery 不会被 Mustache 渲染，会原样发给服务端
❌ 在 customQuery 里写任何 {{{xxx}}} 模板变量 —— 会被当成全文关键词的字面字符串
❌ 自创任何 key:value 形式的 filter
❌ 复制思源版 / 其它产品的查询语法过来 —— 它们各自语法不通用

如果用户描述的需求白名单覆盖不了（比如”只要 5 月以后的”），改 syncAt 字段而不是改 customQuery。

3.2 改了 `customQuery` / `filter` 通常要顺手清空游标

通过 UI 改这两个字段时，插件会自动清空 syncAt initialSyncCompleted deviceSyncCursors[<currentDeviceId>]，让用户从头同步。直接改 data.json 不会触发这个自动清空。判断规则：

用户意图是”换个查询条件，从头拉一遍”：改 customQuery 后，把 syncAt 改成 ""、initialSyncCompleted 改成 false、清空 deviceSyncCursors 里对应 deviceId 的值
用户意图是”我只是想修正之前的错误 customQuery，不想重拉”：保留 syncAt 和 deviceSyncCursors 不动

3.3 `frontMatterVariables` 白名单

只允许这些值（其它会被插件过滤丢弃，等于没填）：

title, author, tags, date_saved, date_published, omnivore_url,
site_name, original_url, description, note, type, date_read,
words_count, read_length, state, date_archived, image

支持别名：metadata::alias 形式，例如 "date_saved::date" 让 frontmatter 里出现 date: 而不是 date_saved:。

3.4 `frontMatterTemplate` 必须产出合法 YAML

错误模板会让插件 YAML 解析失败，落盘的 frontmatter 只剩 id 和 omnivore_error，用户字段全丢。

当前默认模板（推荐基线）：

author: {{{author}}}
source: {{{siteName}}}
url: {{{originalUrl}}}
saved: {{{dateSaved}}}
tags: [笔记同步助手{{#labels}}, {{{name}}}{{/labels}}]

常见错误模板：

❌ tags: [笔记同步助手]{{#labels}}[{{{name}}}]{{/labels}} —— 多 label 时渲染成 [a][b][c]，YAML 把整行当一个字符串
❌ 标量值里有 : 但没加引号 —— 例如 title: {{{title}}} 当 title 含冒号时整行解析失败。用 title: "{{{title}}}" 安全得多
❌ 行尾遗留 Mustache 标签未闭合（{{#labels}} 没配对 {{/labels}}）

改完模板后，强烈建议让用户去模板调试模拟器用真实数据预览一次，确认没有 omnivore_error 提示。

3.5 `imageUploadRelay` 改之前要看用户装了哪个图床插件

iaup / iutk / ciup 三个值都需要用户已经安装并启用对应的第三方插件，且仅在桌面端工作。设了但插件没装的话，本地化能成但接力步骤会跳过。如果用户没明确说装了哪个，保留 "none" 比瞎猜安全。

4. 改完以后必须做的检查

让用户做（你只能改文件，无法操作 Obsidian UI）：

重启 Obsidian 或重新加载插件
进 设置 → 第三方插件 → 笔记同步助手，肉眼对照改动是否在 UI 上反映出来
点一下左侧”同”字图标做一次同步
确认：
- 通知没有报错
- 新笔记按预期路径/文件名/模板落盘
- 控制台（开发者工具 → Console）没有 omnivore_error 之类的告警

如果同步后 0 篇文章被处理但用户云空间确实有新内容，九成是 §3.1 的 customQuery 写错了，回头检查这个字段。

5. 一个安全的改动模板

下面是一个最小可工作的 data.json 片段，可以作为修复严重错配后的”已知好”基线（拼回用户原 data.json 时只改下面这几个字段，其它保留）：

{
  "filter": "ALL",
  "customQuery": "in:all",
  "syncAt": "",
  "initialSyncCompleted": false,
  "deviceSyncCursors": {},
  "endpoint": "https://obsidian.notebooksyncer.com/api/graphql",
  "mergeMode": "messages",
  "imageMode": "local",
  "frontMatterTemplate": "author: {{{author}}}\nsource: {{{siteName}}}\nurl: {{{originalUrl}}}\nsaved: {{{dateSaved}}}\ntags: [笔记同步助手{{#labels}}, {{{name}}}{{/labels}}]"
}

这个组合的语义是：从头拉所有文章、消息按日合并、图片下载到本地、frontmatter 用官方默认模板。

6. 相关教程（推荐 AI 也读一下）

模板变量完全指南 —— 所有可用 Mustache 变量
前置元数据 / 笔记属性模板配置 —— frontMatterTemplate 的写法和踩坑
路径配置教程 —— folder / filename 模板的实际效果
合并消息模式 —— mergeMode 的效果对比
同步不成功排查教程 —— 改完后同步还有问题时的诊断流程

这页本身就是 Single Source of Truth，未来插件版本可能新增字段。如果用户的 data.json 里有本页没列的 key，请保持原样不要动；如果发现这页过时了，反馈给客服更新文档。

给 AI 看的设置教程（AI 改 data.json 必读）

1. 配置文件位置

2. 字段总表

2.1 密钥与端点

2.2 查询（控制同步范围）⚠️ 高危区

2.3 同步频率（按设备独立）

2.4 文件夹与文件名（支持 Mustache 模板）

2.5 合并模式

2.6 图片处理

2.7 内容处理

2.8 日记链接

2.9 高级选项（前置元数据 / 模板）⚠️ 易写错

3. 危险红线（一定要看）

3.1 customQuery 必须用白名单语法

3.2 改了 customQuery / filter 通常要顺手清空游标

3.3 frontMatterVariables 白名单

3.4 frontMatterTemplate 必须产出合法 YAML

3.5 imageUploadRelay 改之前要看用户装了哪个图床插件

4. 改完以后必须做的检查

5. 一个安全的改动模板

6. 相关教程（推荐 AI 也读一下）

3.1 `customQuery` 必须用白名单语法

3.2 改了 `customQuery` / `filter` 通常要顺手清空游标

3.3 `frontMatterVariables` 白名单

3.4 `frontMatterTemplate` 必须产出合法 YAML

3.5 `imageUploadRelay` 改之前要看用户装了哪个图床插件