给 AI 看的设置教程
笔记同步助手把所有设置写在 vault 里这个 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，请保持原样不要动；如果发现这页过时了，反馈给客服更新文档。
原文：https://www.bijitongbu.site/tutorials/ai-settings-guide/ · 笔记同步助手