SiYuan 工作区文件系统布局详解目录即数据、文件名即 ID 的存储架构【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本指南以仓库 docs/WORKSPACE.md及其中文版 docs/WORKSPACE.zh-CN.md为骨架结合 kernel 源码Go核验而成回答一个核心问题SiYuan 工作区在磁盘上到底长什么样。读完本文你将掌握笔记本/文档/附件的落盘约定、父子文档同名配对规则、两类conf.json的区别、HPath人类可读路径的派生原理以及离线直接操作文件系统时必须遵守的五条铁律——这些知识对数据迁移、备份、二次开发与 AI Agent 落盘集成都至关重要。一句话本质自描述的目录树SiYuan 工作区是一棵自描述的目录树笔记本、文档、附件都以可读的文件/目录形式存在于磁盘上。文件名即 ID目录结构即文档层级。系统并没有用二进制数据库去记录文档在哪——文件系统本身就是唯一真相来源single source of truth内核启动时只需遍历目录即可还原全部笔记本与文档结构。这一设计带来的直接推论是内核的启动与索引完全依赖于目录枚举任何对文件系统的直接改动都会立即反映到文档树、面包屑与搜索中因此理解布局规则比理解任何单个配置文件都更重要。工作区速查树总览一个典型工作区如F:\SiYuan\的顶层结构如下workspace root/ e.g. F:\SiYuan\ ├── conf/ │ ├── conf.json # ★工作区总配置(appearance/system/sync/editor...) │ ├── ca.crt / cert.pem / key.pem # TLS 证书 │ └── windowState.json ├── data/ # DataDir — 所有笔记本数据的根 │ ├── .siyuan/ # 工作区级隐藏配置(*ignore 规则等) │ ├── assets/ # ★全局附件(图片/音视频/文件) │ ├── templates/ # 全局模板(.md) │ ├── widgets/ # 挂件 │ ├── plugins/ # 插件 │ ├── emojis/ # 自定义 emoji │ ├── snippets/ # 代码片段(CSS/JS) │ ├── public/ # 静态资源 │ ├── storage/ # 运行时索引/缓存/数据库 │ └── boxID/ # ★笔记本(目录名 笔记本 ID) │ ├── .siyuan/ │ │ ├── conf.json # ★笔记本配置(BoxConf:name/icon/closed...) │ │ └── sort.json # 自定义排序映射 {docID: order} │ ├── docID.sy # 文档(JSON 树;文件名 文档 rootID) │ └── docID/ # ★该文档的子文档目录(同名配对) │ ├── childID.sy │ └── childID/ ... # 任意深度嵌套 ├── repo/ # 数据仓库(快照/同步) ├── history/ # 编辑历史归档 └── temp/ # 临时/导出文件下文将逐层拆解这张图背后的规则与源码证据。工作区根合法性的判定与固定子目录工作区根由用户自行选定例如 Windows 上的F:\SiYuan\。判定一个目录是否为合法工作区规则非常轻量conf/conf.json存在且内容包含kernelVersion字段。这一判定在源码 kernel/util/path.go 的IsWorkspaceDir中实现——它直接读取conf/conf.json并做字符串包含检查而kernelVersion字段定义于 kernel/conf/system.go 的System结构体中。工作区根下的固定子目录及用途子目录用途conf/工作区级配置 TLS 证书data/所有笔记本数据本文档核心repo/数据快照仓库用于同步/历史history/编辑历史归档temp/临时/导出文件corrupted/损坏数据隔离区内核自动迁入其中corrupted/目录由内核在检测到异常数据时自动使用无需用户手动维护。仓库中的 guide 目录如 app/guide 下的.sy文档本身也是以同一套工作区布局存放的真实示例可直接对照验证。data/顶层布局保留目录与笔记本混排data/的第一层是两类条目混排保留资源目录.siyuan/、assets/、templates/、widgets/、plugins/、emojis/、snippets/、public/、storage/。笔记本目录每个是一个以笔记本 ID 命名的文件夹。保留文件名清单AI 落盘时务必避开源码 kernel/util/file.go 中的IsReservedFilename定义了哪些名字不可用作笔记本或文档名func IsReservedFilename(baseName string) bool { return assets baseName || templates baseName || widgets baseName || emojis baseName || .siyuan baseName || strings.HasPrefix(baseName, .) }即assets/templates/widgets/emojis/.siyuan以及任意以.开头的名字都不能作为笔记本名或文档名。任何自动化工具或 Agent 向data/落盘时必须首先避开这些名字否则会与系统保留目录冲突。笔记本的判定规则ListNotebooks实现于 kernel/model/box.go枚举data/时对每个目录依次判定跳过保留名调用IsReservedFilename必须是目录非文件目录名必须符合 NodeID 格式ast.IsNodeIDPattern满足以上三条 → 该目录名就是box.ID笔记本 ID。从源码可见该函数还会在conf.json缺失时通过readNotebookCryptBackup检查加密备份以确认是否为加密笔记本——这说明笔记本判定规则同时兼顾了普通与加密两种场景。RemoveBoxkernel/model/mount.go同样以IsReservedFilename作为前置保护禁止删除保留目录。笔记本内部布局核心父子文档同名配对这是整个布局最关键的约定文档A的磁盘表示 A.sy文件 A/目录后者仅在 A 有子文档时存在。A 的子文档全部放在A/目录里子文档若有自己的子文档则再嵌套A/B/目录任意深度。真实示例来自find输出与仓库 app/guide 下的目录结构完全同构20221126104620-m06prws/ # 父文档 A 的目录 20221126104620-m06prws.sy # 父文档 A 本体 20221126104620-m06prws/20230928134805-z11t56h.sy # A 的子文档 B 20221126104620-m06prws/20230928134805-z11t56h/ # B 的子目录孙子层 20221126104620-m06prws/20230928134805-z11t56h/20240304105333-v7g5j1s.sy代码佐证展开子文档Lskernel/model/box.go 中传入.sy路径后先去掉.sy后缀得到before检查同名目录是否存在存在则把p改为该目录并列出其子项。子文档深度GetChildDocDepthkernel/util/path.go 同样以去后缀后的同名目录为起点filelock.Walk遍历计算最大深度。⚠️ 这意味着移动/改名一个有子文档的文档必须同步移动它的同名目录否则子文档会失联orphaned。笔记本元数据boxID/.siyuan/conf.json每个笔记本目录下有一个.siyuan/隐藏目录内含两个文件文件用途conf.json笔记本配置BoxConfsort.json文档自定义排序映射{docID: order}BoxConf结构体定义于 kernel/conf/box.go字段含义如下字段类型含义namestring笔记本显示名称sortint排序权重iconstring图标emoji hex 码如1f3af或自定义图标文件名closedbool是否处于关闭状态refCreateSaveBoxstring块引用时新建文档的目标笔记本refCreateSavePathstring块引用时新建文档的目标路径docCreateSaveBoxstring新建文档的目标笔记本docCreateSavePathstring新建文档的目标路径dailyNoteSavePathstring新建日记的存储路径支持模板dailyNoteTemplatePathstring新建日记的模板路径sortModeint排序方式⚠️笔记本 ID 不在conf.json里——ID 就是笔记本目录名本身见上文 §3 的判定规则二者是解耦的改名conf.json中的name只会改变显示名而目录名才是身份标识。读写位置由GetConf/SaveConf完成路径硬编码为DataDir/boxID/.siyuan/conf.json。工作区总配置workspace/conf/conf.json务必区分两个同名conf.json文件位置作用域conf/conf.json工作区根工作区级总配置appearance / langs / system / editor / sync / repo 等全局段boxID/.siyuan/conf.json笔记本内仅该笔记本BoxConf实测conf/conf.json约 42KB包含 UI 外观、账号、同步、AI、闪卡等全部工作区级设置其system.kernelVersion字段还是判定工作区合法性的依据见上文。工作区级隐藏配置data/.siyuan/data/.siyuan/与笔记本内的.siyuan/作用域不同前者保存的是工作区级的规则与状态文件用途syncignore同步忽略规则gitignore 风格searchignore搜索忽略embeddingignoreAI embedding 忽略indexignore建立索引忽略refsearchignore反链搜索忽略publishAccess.json发布访问控制filesys_status_check/文件系统一致性检查状态这些规则文件被内核各处实际读取例如syncignore由 kernel/model/sync.go 的getSyncIgnoreLines读取文件不存在时自动创建searchignore/refsearchignore由 kernel/model/search.go 按需加载用于控制全文搜索与反链搜索的排除范围indexignore由 kernel/sql/upsert.go 读取决定哪些路径不进入索引embeddingignore由 kernel/model/embedding.go 加载为匹配器命中该规则的内容块会被标记为embeddingIgnoredByConf忽略类型 2不生成向量。这里没有conf.json——工作区总配置在工作区根的conf/conf.json二者位置不要混淆。附件assets两套并存SiYuan 的附件存储分两套工作区级全局data/assets/——主用。命名规则形如原名-docID后缀.ext如640-20240927104411-0jh7x96.webp后缀即来源文档 ID 的截断可追溯附件归属。文档内以assets/xxx相对路径引用。笔记本级notebook/assets/——主要用于内置 guide 笔记本普通用户笔记本一般没有。附件链接前缀的合法性有严格白名单仅assets/、emojis/、plugins/、public/、widgets/这几个前缀被识别为合法附件链接其余前缀不会被当作附件处理。ID 与路径的关系ID 格式笔记本 IDYYYYMMDDHHMMSS-xxxxxx14 位时间戳 - 6 位随机。文档 IDYYYYMMDDHHMMSS-xxxxxxx14 位时间戳 - 7 位随机。前 14 位即创建时间由TimeFromIDkernel/util/path.go直接截取ID 过短时它会回退为当前时间兜底。随机字符集为[a-z0-9]。文件名 ID硬约束文档的.sy文件名去.sy后缀 文档 rootID。笔记本的目录名 笔记本 ID。内核强制文件名 ID root.ID不一致时会自动订正。文档绝对路径文档在磁盘上的绝对路径 data/boxID/相对路径其中相对路径形如/20221126104620-m06prws/20230928134805-z11t56h.sy以/开头POSIX 风格。从路径反取文档 IDGetTreeIDkernel/util/path.go极为简单即filepath.Base(路径)去掉.sy后缀。因此路径与 ID 之间可以无损互转。HPath人类可读路径如何派生HPath即界面文档树中显示的面包屑路径并不存储而是在加载文档时现场计算。以LoadTreeByData为代表的加载流程相关逻辑见 kernel/filesys/tree.go 的 HPath 拼接部分把文档自身的相对路径按/拆分去掉开头空段和结尾自身段得到各级父文档的 ID 段对每个父 ID 拼出父ID.sy用DocIAL()kernel/filesys/tree.go流式只读Properties不解析整棵树读出该父文档的title若 title 为空则回退为Untitled把各级 title 用/串起来末尾接当前文档 title得到形如/父标题/子标题/当前标题的 HPath若某个父.sy缺失内核会自动补建一个Untitled父文档对应 issue #7376。这就是目录结构即数据的根本原因移动或重命名文件/目录会直接改变文档的 HPath 与面包屑——因为 HPath 完全派生自目录链不存在任何独立的路径数据库需要同步。直接操作文件系统的注意事项与 SY-FORMAT.zh-CN.md以及 SY-FORMAT.md的立场一致修改数据优先走 HTTP API / MCP / CLI由内核负责索引同步。直接操作文件系统仅适用于批量离线迁移、冷初始化等场景。直接落盘时务必遵守☐ 笔记本/文档命名符合 NodeID 格式且避开保留名assets/templates/widgets/emojis/.siyuan及任意.开头。☐ 文档.sy文件名 文档 rootID。☐ 有子文档的文档必须配套同名目录移动父文档时连带移动同名目录。☐ 笔记本的名称/图标/关闭状态写在boxID/.siyuan/conf.json不在.sy里。☐ 改动后通常需要重建索引否则搜索/块引用/面包屑会失效。与 SY-FORMAT 的关系文件系统层 vs AST 层文档范畴回答的问题本文档WORKSPACE文件系统层一个工作区在磁盘上长什么样笔记本/文档/附件怎么组织SY-FORMATAST 层一个.sy文件内部的 JSON 树长什么样有哪些节点类型/字段两者互补WORKSPACE 告诉你.sy文件放在哪、叫什么名、与谁同目录SY-FORMAT 告诉你.sy文件里面写什么。若要完整掌握 SiYuan 的数据格式建议两篇配合阅读。实战小结理解这套布局后你可以放心完成以下操作手动备份/迁移单个笔记本整体复制boxID/目录即可通过目录名判断文档层级关系用data/.siyuan/*ignore规则控制同步/搜索/AI 索引范围以及在进行离线批量迁移时严格按文件名即 ID 同名目录配对的约定落盘再让内核重建索引完成接管。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SiYuan 工作区文件系统布局详解：目录即数据、文件名即 ID 的存储架构
SiYuan 工作区文件系统布局详解目录即数据、文件名即 ID 的存储架构【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本指南以仓库 docs/WORKSPACE.md及其中文版 docs/WORKSPACE.zh-CN.md为骨架结合 kernel 源码Go核验而成回答一个核心问题SiYuan 工作区在磁盘上到底长什么样。读完本文你将掌握笔记本/文档/附件的落盘约定、父子文档同名配对规则、两类conf.json的区别、HPath人类可读路径的派生原理以及离线直接操作文件系统时必须遵守的五条铁律——这些知识对数据迁移、备份、二次开发与 AI Agent 落盘集成都至关重要。一句话本质自描述的目录树SiYuan 工作区是一棵自描述的目录树笔记本、文档、附件都以可读的文件/目录形式存在于磁盘上。文件名即 ID目录结构即文档层级。系统并没有用二进制数据库去记录文档在哪——文件系统本身就是唯一真相来源single source of truth内核启动时只需遍历目录即可还原全部笔记本与文档结构。这一设计带来的直接推论是内核的启动与索引完全依赖于目录枚举任何对文件系统的直接改动都会立即反映到文档树、面包屑与搜索中因此理解布局规则比理解任何单个配置文件都更重要。工作区速查树总览一个典型工作区如F:\SiYuan\的顶层结构如下workspace root/ e.g. F:\SiYuan\ ├── conf/ │ ├── conf.json # ★工作区总配置(appearance/system/sync/editor...) │ ├── ca.crt / cert.pem / key.pem # TLS 证书 │ └── windowState.json ├── data/ # DataDir — 所有笔记本数据的根 │ ├── .siyuan/ # 工作区级隐藏配置(*ignore 规则等) │ ├── assets/ # ★全局附件(图片/音视频/文件) │ ├── templates/ # 全局模板(.md) │ ├── widgets/ # 挂件 │ ├── plugins/ # 插件 │ ├── emojis/ # 自定义 emoji │ ├── snippets/ # 代码片段(CSS/JS) │ ├── public/ # 静态资源 │ ├── storage/ # 运行时索引/缓存/数据库 │ └── boxID/ # ★笔记本(目录名 笔记本 ID) │ ├── .siyuan/ │ │ ├── conf.json # ★笔记本配置(BoxConf:name/icon/closed...) │ │ └── sort.json # 自定义排序映射 {docID: order} │ ├── docID.sy # 文档(JSON 树;文件名 文档 rootID) │ └── docID/ # ★该文档的子文档目录(同名配对) │ ├── childID.sy │ └── childID/ ... # 任意深度嵌套 ├── repo/ # 数据仓库(快照/同步) ├── history/ # 编辑历史归档 └── temp/ # 临时/导出文件下文将逐层拆解这张图背后的规则与源码证据。工作区根合法性的判定与固定子目录工作区根由用户自行选定例如 Windows 上的F:\SiYuan\。判定一个目录是否为合法工作区规则非常轻量conf/conf.json存在且内容包含kernelVersion字段。这一判定在源码 kernel/util/path.go 的IsWorkspaceDir中实现——它直接读取conf/conf.json并做字符串包含检查而kernelVersion字段定义于 kernel/conf/system.go 的System结构体中。工作区根下的固定子目录及用途子目录用途conf/工作区级配置 TLS 证书data/所有笔记本数据本文档核心repo/数据快照仓库用于同步/历史history/编辑历史归档temp/临时/导出文件corrupted/损坏数据隔离区内核自动迁入其中corrupted/目录由内核在检测到异常数据时自动使用无需用户手动维护。仓库中的 guide 目录如 app/guide 下的.sy文档本身也是以同一套工作区布局存放的真实示例可直接对照验证。data/顶层布局保留目录与笔记本混排data/的第一层是两类条目混排保留资源目录.siyuan/、assets/、templates/、widgets/、plugins/、emojis/、snippets/、public/、storage/。笔记本目录每个是一个以笔记本 ID 命名的文件夹。保留文件名清单AI 落盘时务必避开源码 kernel/util/file.go 中的IsReservedFilename定义了哪些名字不可用作笔记本或文档名func IsReservedFilename(baseName string) bool { return assets baseName || templates baseName || widgets baseName || emojis baseName || .siyuan baseName || strings.HasPrefix(baseName, .) }即assets/templates/widgets/emojis/.siyuan以及任意以.开头的名字都不能作为笔记本名或文档名。任何自动化工具或 Agent 向data/落盘时必须首先避开这些名字否则会与系统保留目录冲突。笔记本的判定规则ListNotebooks实现于 kernel/model/box.go枚举data/时对每个目录依次判定跳过保留名调用IsReservedFilename必须是目录非文件目录名必须符合 NodeID 格式ast.IsNodeIDPattern满足以上三条 → 该目录名就是box.ID笔记本 ID。从源码可见该函数还会在conf.json缺失时通过readNotebookCryptBackup检查加密备份以确认是否为加密笔记本——这说明笔记本判定规则同时兼顾了普通与加密两种场景。RemoveBoxkernel/model/mount.go同样以IsReservedFilename作为前置保护禁止删除保留目录。笔记本内部布局核心父子文档同名配对这是整个布局最关键的约定文档A的磁盘表示 A.sy文件 A/目录后者仅在 A 有子文档时存在。A 的子文档全部放在A/目录里子文档若有自己的子文档则再嵌套A/B/目录任意深度。真实示例来自find输出与仓库 app/guide 下的目录结构完全同构20221126104620-m06prws/ # 父文档 A 的目录 20221126104620-m06prws.sy # 父文档 A 本体 20221126104620-m06prws/20230928134805-z11t56h.sy # A 的子文档 B 20221126104620-m06prws/20230928134805-z11t56h/ # B 的子目录孙子层 20221126104620-m06prws/20230928134805-z11t56h/20240304105333-v7g5j1s.sy代码佐证展开子文档Lskernel/model/box.go 中传入.sy路径后先去掉.sy后缀得到before检查同名目录是否存在存在则把p改为该目录并列出其子项。子文档深度GetChildDocDepthkernel/util/path.go 同样以去后缀后的同名目录为起点filelock.Walk遍历计算最大深度。⚠️ 这意味着移动/改名一个有子文档的文档必须同步移动它的同名目录否则子文档会失联orphaned。笔记本元数据boxID/.siyuan/conf.json每个笔记本目录下有一个.siyuan/隐藏目录内含两个文件文件用途conf.json笔记本配置BoxConfsort.json文档自定义排序映射{docID: order}BoxConf结构体定义于 kernel/conf/box.go字段含义如下字段类型含义namestring笔记本显示名称sortint排序权重iconstring图标emoji hex 码如1f3af或自定义图标文件名closedbool是否处于关闭状态refCreateSaveBoxstring块引用时新建文档的目标笔记本refCreateSavePathstring块引用时新建文档的目标路径docCreateSaveBoxstring新建文档的目标笔记本docCreateSavePathstring新建文档的目标路径dailyNoteSavePathstring新建日记的存储路径支持模板dailyNoteTemplatePathstring新建日记的模板路径sortModeint排序方式⚠️笔记本 ID 不在conf.json里——ID 就是笔记本目录名本身见上文 §3 的判定规则二者是解耦的改名conf.json中的name只会改变显示名而目录名才是身份标识。读写位置由GetConf/SaveConf完成路径硬编码为DataDir/boxID/.siyuan/conf.json。工作区总配置workspace/conf/conf.json务必区分两个同名conf.json文件位置作用域conf/conf.json工作区根工作区级总配置appearance / langs / system / editor / sync / repo 等全局段boxID/.siyuan/conf.json笔记本内仅该笔记本BoxConf实测conf/conf.json约 42KB包含 UI 外观、账号、同步、AI、闪卡等全部工作区级设置其system.kernelVersion字段还是判定工作区合法性的依据见上文。工作区级隐藏配置data/.siyuan/data/.siyuan/与笔记本内的.siyuan/作用域不同前者保存的是工作区级的规则与状态文件用途syncignore同步忽略规则gitignore 风格searchignore搜索忽略embeddingignoreAI embedding 忽略indexignore建立索引忽略refsearchignore反链搜索忽略publishAccess.json发布访问控制filesys_status_check/文件系统一致性检查状态这些规则文件被内核各处实际读取例如syncignore由 kernel/model/sync.go 的getSyncIgnoreLines读取文件不存在时自动创建searchignore/refsearchignore由 kernel/model/search.go 按需加载用于控制全文搜索与反链搜索的排除范围indexignore由 kernel/sql/upsert.go 读取决定哪些路径不进入索引embeddingignore由 kernel/model/embedding.go 加载为匹配器命中该规则的内容块会被标记为embeddingIgnoredByConf忽略类型 2不生成向量。这里没有conf.json——工作区总配置在工作区根的conf/conf.json二者位置不要混淆。附件assets两套并存SiYuan 的附件存储分两套工作区级全局data/assets/——主用。命名规则形如原名-docID后缀.ext如640-20240927104411-0jh7x96.webp后缀即来源文档 ID 的截断可追溯附件归属。文档内以assets/xxx相对路径引用。笔记本级notebook/assets/——主要用于内置 guide 笔记本普通用户笔记本一般没有。附件链接前缀的合法性有严格白名单仅assets/、emojis/、plugins/、public/、widgets/这几个前缀被识别为合法附件链接其余前缀不会被当作附件处理。ID 与路径的关系ID 格式笔记本 IDYYYYMMDDHHMMSS-xxxxxx14 位时间戳 - 6 位随机。文档 IDYYYYMMDDHHMMSS-xxxxxxx14 位时间戳 - 7 位随机。前 14 位即创建时间由TimeFromIDkernel/util/path.go直接截取ID 过短时它会回退为当前时间兜底。随机字符集为[a-z0-9]。文件名 ID硬约束文档的.sy文件名去.sy后缀 文档 rootID。笔记本的目录名 笔记本 ID。内核强制文件名 ID root.ID不一致时会自动订正。文档绝对路径文档在磁盘上的绝对路径 data/boxID/相对路径其中相对路径形如/20221126104620-m06prws/20230928134805-z11t56h.sy以/开头POSIX 风格。从路径反取文档 IDGetTreeIDkernel/util/path.go极为简单即filepath.Base(路径)去掉.sy后缀。因此路径与 ID 之间可以无损互转。HPath人类可读路径如何派生HPath即界面文档树中显示的面包屑路径并不存储而是在加载文档时现场计算。以LoadTreeByData为代表的加载流程相关逻辑见 kernel/filesys/tree.go 的 HPath 拼接部分把文档自身的相对路径按/拆分去掉开头空段和结尾自身段得到各级父文档的 ID 段对每个父 ID 拼出父ID.sy用DocIAL()kernel/filesys/tree.go流式只读Properties不解析整棵树读出该父文档的title若 title 为空则回退为Untitled把各级 title 用/串起来末尾接当前文档 title得到形如/父标题/子标题/当前标题的 HPath若某个父.sy缺失内核会自动补建一个Untitled父文档对应 issue #7376。这就是目录结构即数据的根本原因移动或重命名文件/目录会直接改变文档的 HPath 与面包屑——因为 HPath 完全派生自目录链不存在任何独立的路径数据库需要同步。直接操作文件系统的注意事项与 SY-FORMAT.zh-CN.md以及 SY-FORMAT.md的立场一致修改数据优先走 HTTP API / MCP / CLI由内核负责索引同步。直接操作文件系统仅适用于批量离线迁移、冷初始化等场景。直接落盘时务必遵守☐ 笔记本/文档命名符合 NodeID 格式且避开保留名assets/templates/widgets/emojis/.siyuan及任意.开头。☐ 文档.sy文件名 文档 rootID。☐ 有子文档的文档必须配套同名目录移动父文档时连带移动同名目录。☐ 笔记本的名称/图标/关闭状态写在boxID/.siyuan/conf.json不在.sy里。☐ 改动后通常需要重建索引否则搜索/块引用/面包屑会失效。与 SY-FORMAT 的关系文件系统层 vs AST 层文档范畴回答的问题本文档WORKSPACE文件系统层一个工作区在磁盘上长什么样笔记本/文档/附件怎么组织SY-FORMATAST 层一个.sy文件内部的 JSON 树长什么样有哪些节点类型/字段两者互补WORKSPACE 告诉你.sy文件放在哪、叫什么名、与谁同目录SY-FORMAT 告诉你.sy文件里面写什么。若要完整掌握 SiYuan 的数据格式建议两篇配合阅读。实战小结理解这套布局后你可以放心完成以下操作手动备份/迁移单个笔记本整体复制boxID/目录即可通过目录名判断文档层级关系用data/.siyuan/*ignore规则控制同步/搜索/AI 索引范围以及在进行离线批量迁移时严格按文件名即 ID 同名目录配对的约定落盘再让内核重建索引完成接管。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
