An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
文档标题与寻址
关联问题:Support / in document titles、Improve content preservation when converting headings to documents、Improve document titles, notebook names, and plugin compatibility
本文规定文档标题、层级定位、可读路径、接口及迁移的目标行为。当前开发实现和发布条件分别说明,不能将开发分支能力视为已发布能力。当前重命名与路径索引的更新机制见 文档重命名与路径索引。
当前实现范围
开发分支已实现统一标题读取、按身份组织的文档元数据及源提交恢复标记,并提供 getDocPaths、resolveDocPath、getDocCreateTarget、planDocCreate 和 createDocByParent 契约。内置新建、引用新建、日记、数据库新建和速记使用身份创建或共享创建计划;导出先按文档身份分配文件名,再使用同一映射生成内部链接。源文档仍保留原有 ID、标题表示及适用的 .sy 规格,不在升级时批量改写。
创建计划采用固定 ID,已确认提交的祖先不会再次创建。桌面与移动端共用失败处理:响应不明或后续处理失败时保留计划,用户确认并按身份核对后才继续;关闭或锁定笔记本清除相应标题和模板缓存。本地速记使用仅含身份和摘要的恢复记录,核对实际源中的块身份后才清理输入,未确认的结果保留原速记并停止自动重放。
管理员读取笔记本配置时可获取 documentCapabilities,用于报告结构化接口支持、标题能力和索引状态;可用性仍受现有授权边界约束。原生整本导入继续重映射笔记本和锚点 ID,部分导入保留目标配置;加密目标载荷保持认证、改密及备份恢复边界。
所有笔记本统一采用结构化标题规则,不提供模式开关,不再执行模式 1 迁移或维护能力下界。含 ASCII / 的新写入标题使用 Spec 6,旧字符串接口按候选祖先链判断兼容性。所有设备仍须统一升级;默认支持不代替发行包、旧数据、性能及跨端验收。行级标题扩展约束不变。
目标与范围
文档使用 ID 确定身份和所属层级,标题用于表达内容,可读路径用于展示。创建、移动和引用不得依赖从展示文本反向解析文档身份。完成相关入口迁移与兼容验证后,文档标题可以包含半角斜杠 /,并与原有全角斜杠 / 保持区别。
行级标题与双向转换、笔记本名称保留 / 以及第三方插件实际版本适配由 #20837 跟踪。标题表示、纯文本提取、显示和身份必须分离;未来富文本标题需要独立格式及编辑设计,不能让当前纯文本索引覆盖未知来源。
方案覆盖桌面端、浏览器端、移动端、内核接口和插件可见数据,并遵守普通笔记本与加密笔记本各自的访问边界。笔记本名称作为独立显示字段参与路径展示;笔记本名称的字符限制与富文本支持需要单独评估配置格式和旧客户端兼容,不能由文档标题规则自动推导。
方案决策
| 项目 | 采用的方案 |
|---|---|
| 文档定位 | 笔记本 ID 与文档 ID;创建使用独立的父文档身份与标题 |
| 寻址规则 | 所有笔记本统一采用结构化标题;配置中的版本 2 仅作诊断标记 |
| 插件兼容 | 接受依赖旧 hPath 规则的插件适配;先交付替代接口及迁移说明,再启用新字符 |
| 旧字符串寻址 | 按候选真实祖先链判断;干净路径保留兼容,斜杠或空标题冲突明确拒绝 |
| 可读路径 | 保留标题原文并按层级拼接展示;不编码 /,不把 / 或 %2F 解码 |
| 索引 | 保留现有 hpath 列,新增文档级内部元数据;不为每个内容块保存完整标题段数组 |
| 标题源 | 首版继续使用普通标题;预留带版本的行级内容及单向纯文本派生 |
| 发布策略 | 直接发布默认支持 / 的功能版本;同一份数据的所有客户端统一升级,不与旧版混用;富文本标题单独实现 |
/A/B 既可能表示两级文档,也可能来自单标题。旧查询只在本次候选的所有祖先标题非空且不含 / 时返回结果;冲突返回明确错误。按 ID 操作及结构化替代接口继续可用,不能把显示路径当作稳定身份。
基础解耦不需要新增第三方服务、网络传输或依赖。实现继续遵守仓库及现有依赖的授权要求;若后续选择新依赖,应另行核查其许可。主要成本是调用方迁移、索引重建和跨版本验证。标题及祖先链的缓存、日志和错误响应继续受加密笔记本边界约束,不能因增加结构化字段扩大数据可见范围。
标题、身份与路径
当前数据来源
当前文档标题保存在文档根节点的 IAL title 中,.sy 文件及目录使用 ID 命名。tree.HPath、blocks.hpath 和 blocktrees.hpath 由文档及其祖先标题派生。标题写入仍经过 normalizeDocTitle,其中会移除半角斜杠;只修改界面输入限制不足以支持该字符。
当前部分逻辑将 hPath 用于按名称定位、创建文档、计算层级或提取标题。这些用途需要逐项迁移,不能仅将 hPath 改名为显示字段。可逆编码可以解决特定字符串协议中的分隔符歧义,但仍需要格式版本与兼容规则;本方案通过分离职责减少内部对该协议的依赖。
目标模型
下表中的名称表示概念,不直接规定新增接口字段或存储字段的名称。
| 概念 | 内容与用途 | 约束 |
|---|---|---|
| 文档身份 | 笔记本 ID 与文档 ID | 按实际归属校验访问范围;不能用标题替代 |
| 父文档身份 | 目标笔记本及父文档 ID,或显式笔记本根位置 | 创建和移动时校验父文档仍存在且属于目标笔记本 |
| ID 数据路径 | ID 组成的目录路径与 .sy 文件名 |
用于存储及子树查询;移动后可能变化,不能作为永久身份 |
| 标题源内容 | 当前为 IAL title,未来可扩展为带版本的行级内容 |
每种格式必须有明确的权威来源及读取规则 |
| 纯文本标题 | 从标题源内容提取的普通文本 | 用于文本搜索、排序及兼容输出,不含 HTML 或搜索高亮标记 |
| 结构化祖先链 | 按层级排列的文档 ID 及对应标题信息 | 保留段边界,笔记本名称单独保存,不从展示字符串恢复 |
| 标题段数组 | 从明确位置开始逐级匹配或创建文档的输入 | 只消除分隔符歧义,不保证名称唯一 |
| 可读路径 | 面包屑、提示或复制路径所需的展示内容 | 可以使用不同展示形式,不承担文档寻址或源数据恢复 |
| 旧路径协议 | 现有接口及插件的 hPath、hpath 字符串 |
仅对经过祖先链验证的干净候选保留兼容 |
| 导出相对路径 | 导出任务为文档分配的文件位置 | 由导出映射确定,与标题及界面可读路径分开 |
当前前端搜索配置的 idPath 是多个搜索范围字符串组成的数组,其中每项可以包含笔记本 ID 和文档 ID 路径;它不是单条路径的逐级 ID 数组。迁移时必须保持现有配置的解释方式。块树中的 parent_id 表示块节点的父节点,也不能直接当作文档的父文档 ID 使用。
下面两种结构可以显示为相同的 /A/B,但必须保留不同的文档身份和祖先链:
| 标题段 | 文档结构 |
|---|---|
["A/B"] |
根目录下一个标题为 A/B 的文档 |
["A", "B"] |
标题为 A 的文档及其标题为 B 的子文档 |
面包屑应使用结构化层级呈现边界。复制出的纯文本路径只用于阅读;用于定位的链接和引用必须携带 ID。同一父文档下的同名文档允许存在,不能因为标题段相同而合并身份。
标题读取与文档元数据
内核建立统一的标题读取边界,输出 format、text、empty 和源内容版本。首版只支持 format: "plain",从 IAL title 及既有 custom-sy-title-empty 属性读取;该属性与标题中的实际文字必须分别保留。旧文档的占位标题不批量重写,空标题的界面提示不作为新的名称匹配依据。未来富文本来源通过同一边界提供纯文本,不要求修改寻址调用方。
在普通 blocktree.db 及各加密笔记本对应的块树数据库中新增内部表 document_metadata,每篇文档一行。现有 blocktrees 列顺序保持不变,避免改变已有扫描和插件查询的列布局。
| 字段 | 含义 |
|---|---|
box_id、id |
联合主键,分别为笔记本 ID 和文档 ID |
parent_id |
父文档 ID;逻辑根位置为 SQL NULL,区别于块树节点的 parent_id |
title_text、title_empty |
由源标题提取的文字及空标题标志 |
title_format、source_spec |
标题表示及源文档版本 |
revision |
身份、位置、标题源内容和空标题状态的版本摘要 |
建立 (box_id, parent_id, title_text, id) 索引,用于当前父文档下的精确名称查询。名称匹配使用原始 Unicode 文本的区分大小写比较,不做宽窄字符、百分号编码或 Unicode 归一化转换;搜索可继续采用自己的分词和大小写规则。空标题不能作为未知父文档的自动匹配条件,必须指定父 ID。
document_metadata 是可重建的内部索引,不新增公开 SQL 表承诺。定位使用块树数据库中的当前元数据,插件可通过结构化读取接口取得父 ID、标题和深度。现有内容库文档行的 content 继续保存标题的纯文本表示,hpath 继续作为可读路径副本。
文档元数据与块树文档行在同一数据库事务中更新。新增、重命名、移动、删除、复制、导入和同步重建都必须更新或清理对应行。标题缓存以笔记本及文档身份为键,并使用版本摘要校验;不得跨笔记本借用同名文档的数据。
结构化路径输出
DocumentPath 包含 notebook、id、parentID、path、title、segments、depth、displayPath 和 revision。title 为 {format, text, empty},segments 按从根到当前文档的顺序包含 {id, text, empty}。displayPath 以 / 开头并用 / 连接各段,空段数组显示为 /,仅作展示;笔记本名称单独返回或由调用方取得,不混入段数组。这里的 title 是标题摘要,不能作为未来富文本源内容的完整副本回写。
普通根文档的 depth 为 1,parentID 为 null。启用笔记本文档功能时,笔记本文档本身的 depth 为 0、segments 为空,普通根文档仍为第一级;它不额外增加物理目录。创建时传入笔记本文档 ID 与显式根位置等价,沿用现有逻辑根映射。根位置的子文档名称查询排除笔记本文档自身,避免把它误当成普通根文档。
路径版本摘要使用有明确字段边界的版本化序列化,覆盖祖先 ID、标题版本及当前位置,不能只使用秒级更新时间。直接按父 ID 创建可以跟随父文档的最新位置;需要保持预览结果时提交 expectedParentRevision,祖先改名或位置变化会使该值失效。摘要只用于一致性检查,不作为跨权限边界的访问凭证。
行级标题的扩展约束
标题读取应提供明确的源内容、纯文本提取和展示边界。当前实现可以继续保存普通字符串,但寻址、层级计算、创建目标解析和文件名分配不得绑定到 IAL 字符串的具体存储形式,也不得把标题交给文件路径清理函数处理。
将来支持粗体、斜体、行内代码等元素时,应复用已有行级内容模型及解析、渲染能力,并为文档标题定义明确的格式标识或版本。旧标题中的 **文本**、反引号和链接语法仍是原有字面内容,不能仅因升级而被自动解释为富文本。具体采用行级 Markdown、节点结构或其他表示,由独立的富文本标题设计确定。
新格式必须指定唯一的标题源内容。为兼容保留的纯文本标题只能是其派生值,源内容与派生值必须一致保存和恢复,不能成为互相覆盖的两个可写来源。旧接口不能将富文本标题的纯文本回写并静默丢弃格式;不支持相应格式的写入必须拒绝,正文编辑也必须保留标题源内容或明确拒绝保存。
富文本标题的纯文本提取需要定义空白、换行、行内公式、链接文本、空标题和长度限制的规则。仅样式不同的两个标题可以得到相同纯文本,身份与引用仍由 ID 区分。搜索、排序和导出文件名不能将 Markdown 标记或渲染 HTML 当作标题文字;导出正文中的标题可以按目标格式保留行级内容。
普通标题按文本渲染,使用现有转义或文本节点机制,不能因支持新字符而直接拼接为 HTML。富文本标题复用经过校验的节点及渲染模型;DocumentPath 的纯文本摘要与可编辑源内容使用不同读取边界,写入按格式区分,防止展示数据覆盖源格式。
块引用、动态锚文本、链接、标签和资源需要进一步定义依赖更新、点击行为、引用及资源归属、循环引用处理、复制与导入时的 ID 重映射,以及加密边界。本方案保留这些能力的表示空间,不表示所有行级元素都会同时开放。后续富文本标题实现还必须覆盖输入法、选区、撤销、移动端交互、历史、同步和导出。
标题块与文档转换
当前 Heading2Doc 通过 headingDocParagraph 将文档名无法完整表达的行内节点移入正文段落,包括图片、链接、样式以及被规范化或截断的原文字。基础解耦必须保留这一行为;允许标题中的 / 后,仅因斜杠替换而产生的保留段落可以不再需要,但不能因此丢弃其他内容。文档标题的文本提取与原节点内容保留分别判断。
将 #19235 作为后续行级标题的双向转换验收:支持的行级元素连同资源引用进入标题源内容;暂不支持的元素继续保留在正文。反向转换或合并回正文时,保留节点内容、资源归属和引用关系,并按明确规则恢复标题层级。相同纯文本不证明正文段落是标题副本,不能据此删除用户内容。若提供自动合并,须记录可校验的转换来源及内容版本;无法确认或用户已编辑时保留内容,不能盲目去重。现有普通文档不自动将首段迁入标题。
本次解耦的验收必须确认:增加一种标题表示时,寻址和层级规则无须改变;现有普通标题的字面内容保持不变;消费者通过约定的标题读取边界获取内容,不能各自猜测标题语法。
创建与路径模板
按身份创建
已知父文档时,创建请求表达目标笔记本、父文档 ID 或根位置、独立标题及正文。内核在实际写入前按当前身份解析 ID 数据路径,并重新校验归属、可写状态、父文档有效性和加密笔记本操作租约。跨笔记本移动可能改变归属,过期的笔记本参数必须报错,不能退回其他笔记本或同名文档查找。
直接创建不附带预览版本时,父文档改名或在同一笔记本内移动后仍按该 ID 的当前位置创建。带有 expectedParentRevision 的请求、创建预览及模板文档树计划则必须校验相关标题和位置版本,变化时返回 planChanged,由调用方重新预览。两种行为由请求明确区分,不能仅因文档 ID 未变就认定预览仍有效。
父身份解析、最终校验和源文档提交必须处于与重命名、移动、删除共用的变更协调范围内,避免校验后父位置变化。沿用现有事务队列和锁顺序,不在持有队列执行所需锁时等待队列完成。请求取消、关闭笔记本或锁定不能留下可继续使用的过期租约。
当前 createDocWithMd 的 parentID 仍可能因 hPath 不匹配而回退到名称解析,且已有回归测试要求保留这一行为。新协议另设严格按父 ID 创建的入口,不通过修改旧参数含义实现。迁移后的内部调用直接传递结构化目标,禁止先拼回 hPath 再调用旧解析器。
普通新建、日记复用和往既有文档追加内容是不同操作。调用方必须表达是否允许复用目标,不能通过一次按标题搜索隐式决定写入对象。迁移应保留原有模板应用、属性写入、排序、消息推送和同步落盘要求;例如成功后清理源数据的速记流程,必须先确认目标写入成功。
新协议的标题校验
新创建接口要求显式传入 title: {format: "plain", text: string}。省略 title、传入 null 或未知 format 均为错误;text: "" 表示空标题,沿用 custom-sy-title-empty 和既有存储占位机制。读取时同时返回实际纯文本与 empty,编辑器根据标志恢复空输入,不把本地化占位文字当作用户标题。
标题保留 512 个 Unicode 码点上限及现有不可见字符、私用区限制,保留组合 Emoji 所需的 ZWJ。新接口拒绝超长、禁止字符、首尾空白和独立的 .、..,返回 invalidTitle;允许标题内的 /,不截断或替换输入后悄悄保存。
结构化标题模式不执行文件路径清理、宽窄转换、百分号解码或 Unicode 归一化。/、/、%2F、连续斜杠以及 A/../B 均保留原文,层级只由父身份决定。普通新建允许同父同名,返回新 ID,不隐式覆盖或复用已有文档。
按标题段解析
需要按名称逐级创建时,输入包含明确的起点和标题段数组。已知祖先 ID 时直接使用该身份;未知祖先逐级在当前父文档下匹配。无匹配时按操作规则创建,有多个匹配时返回歧义及授权范围内的候选身份,不得任取第一项。通用解析器不跨同名父文档搜索后代来猜测用户意图。
结构化标题段中的 / 不拆分层级,.、.. 不执行导航。向上一级、从笔记本根开始和以当前文档为起点需要独立表达。空段数组表示起点自身,空字符串不能用来自动匹配空标题父文档;最终创建的空标题仍可显式提交。是否允许创建缺失祖先,由调用方的 onMissingParent 策略决定。
名称匹配结果与父路径版本是不同的提交条件。nameConditions 记录 {parentID, title, expectedID}:parentID 为父文档 ID 或逻辑根的 null,非空 title 按统一纯文本规则精确匹配;expectedID: null 表示仍不存在同名子文档,文档 ID 则表示唯一匹配仍为该文档。省略 expectedID 无效。条件最多 128 项,只能涉及本次目标所在笔记本、其实际祖先链及最终父级,不能用来枚举无关位置。笔记本文档 ID 先规范化为逻辑根,查询排除笔记本文档自身及空标题占位值。
创建缺失祖先必须提交相应的不存在条件,并保留此前按名称匹配祖先的唯一身份条件。内核在与创建、重命名、移动、删除共用的协调范围内重新查询,并保持到源文档及元数据提交完成;任一条件不成立返回 planChanged,调用方重新解析,不自动复用刚出现的同名文档。两个调用方同时创建同名祖先时,至多一个满足原不存在条件。普通最终文档创建可以省略名称条件,继续允许同父同名,不给标题添加唯一索引。expectedParentRevision 不能代替这些条件。
提交、部分失败与重试
首版不提供跨文件原子创建。创建计划在写入前检查可预知的标题、深度、歧义、模板及权限错误,分配固定 ID 并记录祖先身份和版本;提交时重新校验。并发同名变化必须重新规划,不能悄悄改用另一篇文档。
通用多级创建按文档分别提交;已有模板文档树仍保留父文档编辑与子文档创建共用的事务及撤销分组,不能因迁移定位逻辑而拆成互不相关的用户操作。成功响应要求源文档及本次必需的正文、属性修改已同步持久化,文档元数据已可读取;搜索全文索引可按现有机制异步更新。模板、脚注、数学内容、剪藏来源、标签、排序及刷新通知按原业务语义执行,不能因拆分定位逻辑而丢失。
写入途中失败时保留已落盘文档。错误数据区分 commitState: "none"、"committed"、"unknown",并返回可确认的文档 ID、失败阶段及已完成步骤;committed 仅表示源文档已提交,不表示所有后续动作成功。落盘状态无法确认时必须返回 unknown,不得声称未写入。多级业务同时保留原计划及已完成 ID,向用户提供继续处理的位置。
调用方在发送前保存所分配的 ID。响应丢失或结果未知时,先完成必要的索引恢复,再按原 ID 核对源文档和目标,不重新分配 ID。重复提交已有 ID 返回 documentIDConflict,不覆盖文档,也不把“ID 已存在”直接认定为同一次成功请求。首版不承诺自动幂等重放;模板或追加正文等有副作用的步骤不得未经核对再次执行。
恢复只处理未完成步骤,不自动删除已经成功创建的父文档。源数据清理等不可重复的后续操作,仅在业务所需步骤全部成功后进行;部分成功和单纯收到文档 ID 都不足以触发速记源数据删除。
模板文档树正常完成后,撤销和重做保持父文档修改与本次创建文档的原有分组及 ID 重映射语义。部分失败时,恢复与撤销记录必须依据实际完成步骤,不能操作未提交的文档;重做使用已保存的计划快照,不重新执行时间敏感的模板。已有文档或已创建文档发生后续修改时,沿用事务冲突检查,不能以清理失败计划为由删除这些修改。无法确认副作用是否完成时停止自动续作并展示已确认结果,不把索引恢复标记当作业务成功凭据。
模板版本
旧字符串保存路径继续使用原有解释规则,包括绝对与相对路径、..、末尾 /、空模板、跨笔记本上下文,以及显式名称替换末段的行为。新建语法必须有可识别的版本,不能自动将已有配置按新规则重解释。
旧模板由兼容编译器按原语法求值并生成结构化计划;新标题独立传递。相对导航使用文档 ID 和父关系。变量内的 / 在旧语法中仍分层,只有显式改用新模板后才保留为单段。
所有内置创建业务使用严格结构化计划,不任取同名祖先。公开旧创建接口保留有效且匹配的 parentID 消歧及无冲突时的既有回退;同名集合无法唯一定位时返回 pathAmbiguous。
docCreateTarget、refCreateTarget、dailyNoteTarget 与旧模板字段并存,所有笔记本均可使用。对象带 version: 2,指定笔记本、起点、向上层数、祖先段、最终标题和缺失策略;全局旧模板及继承规则继续保留,保存路径语法与正文模板语法分别解释。
{
"version": 2,
"notebook": "20210808180117-6v0mkxr",
"anchor": {"kind": "notebookRoot"},
"up": 0,
"parents": ["Daily notes", "{{now | date \"2006-01\"}}"],
"title": "{{now | date \"2006-01-02\"}}",
"onMissingParent": "create"
}
anchor 另支持 {kind: "context"} 与 {kind: "document", id: string}。context 必须能解析为目标笔记本内的当前文档,不能在跨笔记本时猜测起点;缺少上下文返回错误。up 为非负整数,越过逻辑根时失败。parents 可为空,onMissingParent 必须为 create 或 error;调用方显式提供标题时直接替代 title 的求值结果。最终文档的复用政策由日记等业务决定,不放入通用路径模板。
新模板在渲染前确定段边界,各标题段独立求值。变量值为 A/B 时仍是一个标题段;先渲染成单个字符串再 split("/") 不符合协议。一次创建的各段使用同一份上下文和时间快照,日记按指定日历日期提供 now,避免跨日期或上下文变化。
新对象生效时是相应业务的唯一权威配置;旧字段原样回传可以接受,修改为冲突值必须拒绝。移除新对象后恢复旧模板求值,寻址规则仍不变。未配置新对象时保留已有继承顺序;跨笔记本目标继续检查源格式及权限。
由配置生成的预览保存配置来源笔记本、业务用途、有效配置版本及已求值上下文。提交时使用 expectedTarget: {notebook, purpose, revision} 校验配置,其中 notebook 是读取配置的来源笔记本,可能不同于创建请求的目标笔记本。版本覆盖生效目标、参与继承的配置及选中的正文模板路径;无关设置不使预览失效。内核在配置更新与文档变更共同遵守的协调范围内重新解析有效配置,校验版本和目标笔记本后提交;配置变化返回 planChanged,即使父路径未变也不能继续。模板正文预览另保存已渲染内容及依赖快照,不能用配置版本代替正文快照校验。
业务入口迁移
| 入口 | 保持的业务行为与迁移重点 |
|---|---|
| 普通新建及块引用新建 | 已知父 ID 直接创建;新标题独立传递,生成的引用保存文档 ID |
| 日记按钮及快捷键 | 未指定日期,按当天求值后的命名和路径模板复用目标;原日记改名或移动后不再匹配目标时,可另建日记 |
| 日期引用及指定日期接口 | 先按目标笔记本中的日记日期属性复用;多个匹配时优先选择模板目标,否则按 ID 升序选择;无日期匹配时再复用或创建模板目标 |
| 速记 | 明确追加目标或新建目标;目标持久化成功后才清理来源 |
| 数据库新建条目 | 保留属性值、绑定关系和排序;创建计划保存最终文档 ID |
| 模板文档树 | 保留预览、ID 重映射、插入顺序及整组撤销和重做;提交校验路径、名称与配置条件并展示部分完成结果 |
| MCP 与内置 Agent | 文档工具优先使用笔记本及 parentID,空字符串表示根;旧路径复用祖先链判定,单目标同名歧义返回错误 |
| 桌面、浏览器和移动端 | 分别检查菜单、快捷键、对话框及事件处理;共享工具函数迁移不能代替各端验证 |
日记保留两种入口的业务边界:createDailyNote 省略 date、传空字符串或 null 时沿用普通按钮的模板目标策略;显式传入日期(包括今天)及 getDailyNoteInfo 按日期属性查找。改名或移动后的原日记仍可被日期入口复用,但普通按钮可能创建新的模板目标;该目标同样带有当天日期属性后,日期入口会优先选择它。两种入口复用已有日记时均不重新应用正文模板。多个同日期匹配保留上述选择顺序,不改为一律报错;模板目标匹配使用结构化身份链比较。
搜索与派生索引
结构化祖先链提供统一数据来源,界面展示、旧协议输出、纯文本检索和导出分别使用适合各自用途的转换规则。统一的是标题与层级的来源,不要求所有消费者共用同一个字符串序列化结果。
文档深度、父子关系和子树范围根据 ID 数据路径或明确的文档关系计算。不得通过 hPath 中斜杠的数量、path.Base(hPath)、path.Clean(hPath) 或按深度截取展示字符串推导结构。索引中的文档标题从标题源内容提取;恢复读取也必须使用相同的数据边界。
搜索范围过滤与路径文字匹配分开。前者使用文档身份或 ID 数据路径,后者匹配标题的纯文本表示及祖先文字,不进行 / 与 / 之间的替换。返回内容中的搜索高亮标记和 HTML 是展示结果,不能回写成标题源内容,也不能在补充文档标题时覆盖已有匹配高亮。
首版保留 blocks.hpath、blocktrees.hpath 及现有批量更新机制,新增前述文档级元数据作为结构化查询来源。完整祖先链按文档组装,可使用有界缓存,不为每个内容块复制完整标题段数组。插件仍能读取字符串列,但只能把它们当作显示和文字检索数据。
RefreshDocHPaths 通过 ID 子树和元数据重建祖先标题,不再按深度切割旧 hPath。updateRootContent 从统一标题读取结果取得文档标题,不使用 path.Base。稳态下重命名父文档不为取得标题而读取每篇后代的完整 .sy;缺失或失效元数据进入恢复流程,不能以旧显示路径补齐。
重命名仍会使展示路径、祖先文字检索和相关缓存失效。源文档保存、文档元数据更新、后台批次校验与中断恢复必须保持有序,排队中的旧树不能写回过期标题或路径。按 ID 寻址消除了标题对身份的影响,不等于可以删除所有重命名更新任务。
导入与导出
跨笔记本移动与恢复
移动、复制、原生导入及历史恢复在首次写入前检查完整操作集合,包括全部后代、源格式、标题表示、目标深度和加密边界。无法读取的格式必须拒绝,不改写标题、不删除来源;Spec 冲突由源版本保护,不能用已撤销的模式记录代替检查。
支持的历史源仍可读取和恢复;需要新标题能力的新写入采用相应 Spec。不因客户端升级而统一改写文档,也不为通过检查降低已有规格。
已就绪元数据可用于检查完整子树,导入和历史使用对应的已认证源快照;缺失或过期索引先恢复,不用旧 hPath 推断能力。预检记录整个操作集合的身份、成员及标题和位置版本,提交在变更协调范围内复核,防止预检后后代改名或新增。可预知的不兼容必须在任何写入前拒绝;实际 I/O 失败沿用部分提交记录及恢复规则,不承诺跨文件原子移动。普通与加密笔记本之间、不同加密笔记本之间的既有隔离规则保持不变。
文件名与链接映射
导出先为每个文档身份分配唯一的相对文件路径,再用同一份映射写文件及生成文档间链接。映射必须处理标题中的斜杠、非法文件名字符、同名文档、大小写不敏感冲突、长度限制和跨笔记本同名;文件覆盖检查与链接生成不能各自临时决定文件名。
分配器先按 ID 关系确定导出目录,再独立转换每个文件名。兼容已有无冲突文件名;遇到保留名称、空名称、.、..、尾部空格或点等情况时使用安全名称,冲突时附加稳定的文档 ID,必要时再加笔记本 ID。按目标文件系统规则比较大小写和名称,截断时保留唯一后缀及扩展名。所有名称分配完成后再次校验相对路径唯一性及目标目录边界,随后写文件和链接。标题中的 / 只影响单个文件名转换,不产生新目录。
标题中的 .、.. 和路径分隔符只能参与文件名转换,不能越出导出目录。纯文本标题和目标格式支持的富文本标题用于文档内容;导出的文件名可以经过必要转换,但不能反过来作为标题的唯一恢复来源。要求无损重导入的格式必须保存原始标题及对应身份的元数据;普通 Markdown 文件名不能单独承担这一保证。
首版原生导出和备份继续以源文档保存标题及版本,不为了 Markdown 导出新增一种通用源格式。普通 Markdown 导出可以在正文保留标题,但不因此承诺无损恢复全部标题元数据;若后续提供带清单的往返格式,需单独定义其版本及导入规则。
导入以源文件路径和来源标识建立到新文档 ID 的映射,链接解析使用该映射,不使用 hPath 作为唯一键。同名来源、相对链接、标题锚点和无法唯一定位的链接沿用明确的冲突处理。Obsidian 等已有导入流程中的源路径映射应继续使用,迁移其标题及可读路径生成部分即可。
结构化接口契约
以下路径和字段为本方案拟定的新增契约,均使用 POST 和 JSON 请求。首版新增读取接口要求工作空间管理员权限,写入接口另要求可写状态;不自动向发布访问者开放祖先枚举能力。现有发布页面继续遵守已有逐文档可见性检查,增加结构化展示数据时也必须经过同等过滤。加密笔记本从解析、查询到响应写出均保持有效操作租约。
按 ID 批量读取
/api/filetree/getDocPaths 接收 notebook 和 ids,其中 ids 为 1 至 128 个文档 ID;超限失败,不静默截断。按首次出现顺序去重,返回 {documents: DocumentPath[], missingIDs: string[]}。不存在、不属于目标笔记本或不能作为文档读取的 ID 放入 missingIDs,不跨笔记本补查;无权访问整个笔记本时直接失败。
每个 DocumentPath 的标题和祖先链来自同一可验证版本。响应顺序与去重后的输入顺序一致,缺失项单独列出。索引未就绪、源格式不支持及认证失败属于错误,不伪装成文档不存在。批量读取不承诺不同文档之间的全局快照,调用方保存各项 revision,提交预览时重新验证。
按标题段解析
/api/filetree/resolveDocPath 接收 notebook、start 与 segments。start 为 {kind: "root"} 或 {kind: "document", id: string},segments 为独立标题字符串数组。接口只解析,不创建。空数组返回起点;非空数组按精确名称逐级查找,不解析字符串中的导航字符。
结果包含 status、start、resolved、nextIndex、candidates、candidatesTruncated 和 nameConditions。start 返回起点身份及版本,resolved 和 candidates 使用 DocumentPath;nextIndex 是下一待处理段的零基索引。status: "resolved" 表示全部命中,"missing" 表示从该段开始没有文档,"ambiguous" 表示该段存在多个候选。候选按 ID 排序,最多返回 128 个,并用 candidatesTruncated 表示仍有更多结果;达到上限仍必须报告歧义,调用方改用明确父 ID,不能从截断结果中默认选择第一项。
nameConditions 包含已经唯一匹配的各段条件;缺失结果再包含首个缺失段的不存在条件,歧义结果不为歧义段生成成功条件。空段数组返回空条件数组。解析的链和条件来自同一可验证快照,提交时仍须重新检查。插件创建首个缺失祖先后按原起点及完整的原始段数组重新解析,使后续条件引用已确认的父 ID;不能把一次缺失结果当成对整条尚不存在路径的预留。
解析最多接受 128 段,每段遵守标题长度限制,实际创建仍执行用户的文档深度限制。空字符串段失败,名称为空的已有父文档需按 ID 选定。笔记本根作为解析结果时使用明确的根位置,不伪造文档 ID;根版本覆盖笔记本身份及相关配置,不因无关子文档变化而失效。作为根位置别名的笔记本文档 ID 也使用根版本校验。错误和候选不得泄露其他笔记本的标题。
按父 ID 创建
/api/filetree/createDocByParent 的最小请求如下;目标索引必须就绪,且满足原有授权要求。
{
"notebook": "20210808180117-6v0mkxr",
"parentID": "20261015090000-abcdefg",
"id": "20261015100000-hijklmn",
"title": {"format": "plain", "text": "卷01·第一章/第二节"},
"markdown": ""
}
| 字段 | 约束 |
|---|---|
notebook |
必填,目标笔记本 ID |
parentID |
必填;文档 ID 或表示笔记本根位置的 null,不接受空串作为根位置 |
id |
必填,由调用方预先生成并保存的有效新文档 ID;已存在时不覆盖 |
title |
必填,首版仅接受普通标题对象;空字符串与缺省值不同 |
markdown |
必填,允许空字符串 |
expectedParentRevision |
可选,提交预览时用于校验父路径版本;根位置使用解析接口返回的根版本 |
nameConditions |
可选,至多 128 项名称匹配条件;创建缺失祖先必传,不存在条件对应本次创建的非空标题与父级 |
expectedTarget |
可选,包含来源 notebook、purpose 和配置 revision;从保存路径配置生成的预览提交必须携带 |
tags、withMath、clippingHref |
可选,复用现有 Markdown 创建流程对应的处理规则 |
sorts、sortTargetID、sortPosition |
可选,保持排序校验;相对排序目标必须仍是同一父级下的文档,冲突排序方式报错 |
docCreateTemplatePath、listDocTree |
可选,沿用现有正文模板与文档树刷新语义 |
接口拒绝额外提交的 path、hPath 等目标字段,避免两个位置来源互相覆盖。父文档不匹配时直接失败,不能退回名称寻址。成功返回 {id, document: DocumentPath};客户端直接使用返回 ID 打开、引用或追加内容。
名称条件、父路径版本和配置版本分别校验,不能相互替代;缺省条件表示直接按已知身份创建,不承诺保持先前按名称或配置得到的预览。条件均不是授权凭据,内核仍验证权限、归属和租约。多级计划每次提交前校验其适用条件,失败时返回本次及此前步骤的真实提交状态,不重选父文档。
业务错误使用 code: -1,data.reason 提供稳定原因;msg 用于人类阅读,不作为插件分支条件。下表汇总本方案涉及的原因,各创建、移动、导入或恢复接口仅声明适用的错误变体,并保留相应提交状态和恢复信息。认证、角色、锁定及通用请求校验错误继续使用相应中间件契约,不强行改写所有既有错误格式。
| 原因 | 含义及调用方处理 |
|---|---|
invalidTitle |
标题格式、字符或长度无效,修改输入后提交 |
parentUnavailable |
父文档不存在或不属于目标笔记本,不跨笔记本查找 |
planChanged |
位置、标题版本、名称匹配或配置等预览依赖变化,重新解析并确认目标 |
documentIDConflict |
ID 已存在,核对原请求结果,不覆盖或直接换 ID 重试 |
legacyPathUnsupported |
仅有祖先含斜杠或空标题的候选,改用结构化接口 |
pathAmbiguous |
干净与不兼容候选碰撞,或单目标存在多个干净候选,显式指定身份 |
indexUnavailable |
结构化元数据未就绪,等待恢复,不回退到显示路径 |
unsupportedTitleFormat |
客户端或接口不能处理标题格式,升级或改用对应格式接口 |
targetModeUnsupported |
源文档格式校验失败;保留来源,按错误详情检查规格或表示,修复或升级后重新规划移动 |
writeFailed |
写入或后续处理失败,依据 commitState 及阶段恢复 |
读取有效创建目标
/api/filetree/getDocCreateTarget 接收当前 notebook 与 purpose: "document" | "reference" | "dailyNote",复用各业务现有的配置优先级,返回生效的 target、docCreateTemplatePath 和配置 revision。target 为带 version 的联合类型:旧模板返回 {version: 1, notebook, path},新模板返回上文完整的版本 2 对象。返回字段 docCreateTemplatePath 表示该业务的有效正文模板:普通新建按现有继承规则选择,日记取 DailyNoteTemplatePath,块引用新建保持当前不自动应用正文模板的行为并返回空字符串。接口只读取配置,不执行模板、不猜测当前文档或当前日期;调用方随后提供上下文生成计划,并将来源、用途及 revision 放入提交条件。
旧 getDocCreateSavePath 和 getRefCreateSavePath 在有效配置为旧模板时保持原响应;相应新对象生效时返回 code: -1、data: {reason: "structuredTemplateRequired"}。判断依据是配置来源及业务,不从显示路径猜测配置,也不读取已撤销的寻址模式。
规划配置中的创建目标
/api/filetree/planDocCreate 接收 notebook、purpose 和最终文档的固定 id;可选 contextID 提供当前文档,省略或 null 表示没有当前文档;可选 title 覆盖最终标题,placement 为 configured 或 child,reuse 控制是否允许复用已有最终文档。它只求值和校验,不写入文档。一次计划中的时间模板使用同一时间快照,返回最终标题、目标笔记本、可选的 existingID,以及包含固定 ID、父身份、名称条件和配置版本的有序 steps。
调用方依次提交每个 createDocByParent 请求,用上一项成功响应的路径版本更新下一项的父版本。提交后以返回 ID 为准;错误按提交状态处理,不能重新生成一组 ID 并盲目重放。单次计划不是跨文件事务,计划期间的成功校验也不代替每次提交时的复核。
能力探测
管理员读取 getNotebookConf 时获得只读 documentCapabilities,包含 structuredPaths、literalSlash、titleFormats、indexState 和 revision。structuredPaths 声明 ID 与标题段接口支持;literalSlash 只在索引就绪时为 true。indexState 报告 missing、building、ready 或 error。所有笔记本使用相同的结构化规则。
能力读取不写入迁移或下界记录;revision 是能力声明的版本摘要,不是某篇文档的路径版本。桌面、浏览器和移动端输入使用相同标题规则,不依赖运行时寻址模式开关。关闭、锁定、发布访问及请求租约继续执行原有规则,能力信息不授予额外权限。
契约及声明维护
实现遵循 内核接口类型契约:在 kernel/apicontract/ 定义声明,使用 contractHandler 绑定,生成类型并同步 Petal 维护声明及变更记录。新增接口的详细规则放在对应契约注释中。已有接口行为受影响时检查并同步中、英、日 API 文档中的既有条目,不自动把新接口追加到 API 参考文档,也不向契约维护指南添加本特性的接口说明。
接口与插件兼容
旧 getIDsByHPath 先在同一元数据快照检查就绪状态和 pending,再查询本次显示路径候选,并按真实祖先链分类。每一层标题均非空、不带空标题标志且不含 ASCII / 时为干净候选;链上任一斜杠、实际空文本或空标题占位均为不兼容候选。属性实体仅在源读取时解码一次,不能重复解码元数据。祖先缺行、循环、身份或路径版本不一致、SQL 失败均返回 indexUnavailable,空结果也须先证明索引就绪。
| 干净候选 | 不兼容候选 | 查询结果 |
|---|---|---|
| 有 | 无 | 返回所有干净 ID |
| 有 | 有 | pathAmbiguous |
| 无 | 有 | legacyPathUnsupported |
| 无 | 无 | 空数组 |
错误使用 code: -1 及稳定的 data.reason,候选字段为 cleanIDs 和 unsupportedIDs,空列表可省略。候选 ID 仍受发布访问过滤和加密响应租约保护。旧成功结果保持数组或文档 ID 类型,不能要求调用方匹配错误文字。
createDocWithMd 在首次源写入前检查全部父路径前缀,不能遇到缺失的早期前缀就漏掉后续冲突;斜杠或空标题候选始终返回 pathAmbiguous。多个干净父级也返回该错误,有效且匹配的 parentID 可以按真实祖先链消歧,不能绕过不兼容候选。CLI 和 MCP 的单目标定位使用相同判定;没有明确身份时不能任取干净候选。根位置保留既有含义。
未知位置优先使用 resolveDocPath 的独立标题段,创建使用 createDocByParent 的父 ID 和独立标题,多层创建使用 planDocCreate。索引重建期间旧接口也会返回 indexUnavailable;调用方等待恢复,不能回退到未经证明的显示字符串或 SQL 前缀推断。
版本、加密与恢复
统一升级与旧版混用风险
模式 1 已撤销,所有笔记本按结构化规则解释,现有文档、ID、密文及密钥不需要迁移或批量改写。配置保存不再生成寻址版本标记,现有标记被忽略,并在下一次普通配置保存时省略;缺失配置和笔记本目录不会使能力读取触发 syscall 错误或重新创建数据。
新写入的标题包含 ASCII / 时必须声明至少 Spec 6。保留独立的规格检测、重复属性与实体解码校验、未知标题表示及未来 Spec 拒绝。支持的历史低 Spec 斜杠源仍可读取和恢复,原始新写入必须满足规格要求;普通文档保留正文所需规格,不因升级统一变为 Spec 6,也不降低原版本。
升级前停止访问同一工作空间和同步数据的全部客户端,将桌面、移动端和服务端统一升级后再恢复使用;离线旧设备也必须先升级。旧版本不读取这些模式记录,Spec 6 也不能保护同一本中仍为旧 Spec 的全部文档,因此撤销无效下界不表示支持旧版混用。已有 v3.8.9-alpha.4 隔离源码验证只证明直接 Spec 6 读取被拒、旧 Spec 仍可读取及旧编辑快照可覆盖来源,未覆盖全部旧端操作或完整混用同步。旧客户端只能使用经过验证的独立导出副本或恢复到独立工作空间的升级前备份,不能覆盖原配置后继续同步。
已撤销的记录与启动清理
能力读取、导入、同步、快照及设置备份不再读取或生成能力下界、模式迁移记录和设置中的 documentAddressing 字段;旧设置中的该字段被忽略。同步及恢复仍在应用前检查源 Spec、规范路径及原有认证边界。
启动时幂等清理本机 conf/document-addressing.json 和 conf/document-addressing-recovery/,目录缺失视为成功,删除失败仅记录警告,不能阻断挂载;只读模式跳过清理。笔记本内部 .siyuan/document-addressing.json 不再读取或新建,现存文件保持原样,避免产生同步删除。加密恢复密钥和源恢复任务不属于此次清理范围。
索引与任务恢复
document_metadata 使用独立的派生索引版本及笔记本状态 missing、building、ready、error。新建表后从源文档和 ID 位置构建,不从旧 hPath 推测段边界。构建期间记录增量变更并在切换前追平;只有全量扫描和增量校验完成,才将对应代次标记为 ready。
结构化和旧路径接口需要的元数据未就绪时均返回 indexUnavailable。恢复必须认证实际源,不能补建不存在的父源文件,也不能用派生索引覆盖损坏源。
更新顺序为源文档持久化、同一块树数据库事务内更新文档元数据和对应文档行、提交后续 hpath 批次。源文件与数据库、块树库与内容库之间不宣称原子事务。任一步骤中断都保留恢复标记;重新启动或解锁后先验证源版本及当前 ID 位置,再继续派生更新。快照版本、移动或删除检测使排队中的旧树失效,不能恢复旧标题。
现有 temp/queue/hpath-refresh.queue 只保存笔记本 ID、文档 ID 和 ID 数据路径。迁移不得将标题段、富文本标题或正文写入这个全局明文队列。并发重命名、移动、删除、同步及普通索引重建仍需校验任务是否过期,不能误清理尚未完成的加密笔记本恢复任务。
为防止源文件已写入而恢复任务尚未登记时崩溃,变更前先持久化仅含身份的待核对标记,或使用已有能覆盖该窗口的持久事务记录;相关实现必须用故障注入证明可恢复。任务完成后再清理标记,重复恢复应得到同一派生结果。加密笔记本未解锁时保留任务,不能为了清空队列而跳过认证。
加密兼容
已有加密数据是兼容基线,遵循 加密笔记本 的认证读取、隔离及恢复要求。标题源内容、纯文本标题和祖先链都属于受保护的文档内容;读取、缓存和响应必须处于对应笔记本的授权范围及操作租约内,锁定后按现有生命周期清理。
docCreateTarget、refCreateTarget、dailyNoteTarget 在加密笔记本中按受保护配置保存,不能直接作为明文字段落入 BoxConf。当前 BoxCrypt.Metadata 的加密载荷只包含图标及排序;新方案为该载荷定义独立的 version: 2,保留 icon、sort、sortMode,并以 documentTargets 保存三个可选目标对象。现有无 version 的载荷按版本 1 认证读取,普通配置保存继续兼容旧载荷;写入新对象时才生成版本 2,以后移除对象也不退回旧载荷版本。该版本与 BoxCrypt.Spec、目标对象的 version 和 .sy 版本分别解释。
已解锁时,配置读取器在租约内将目标对象投影到授权管理接口;写盘前必须从明文配置副本清除这些对象,只保存认证密文。锁定后清除相应明文缓存,状态及配置响应不返回这些对象;非管理员同样不能读取它们。省略或被过滤的字段不是删除请求,锁定时的普通配置保存保持既有密文原样,新增或修改目标对象必须先解锁。新载荷读取、改密重新包络、导入导出、历史配置及备份恢复覆盖旧版本样本;未知载荷版本和认证失败拒绝解读或覆盖,不能因结构体不认识字段而丢弃新配置。
重建派生索引之前必须认证源密文并验证文档格式。未知格式、损坏和认证失败必须保留原始数据并返回错误,不能回退到明文、跨笔记本查询或未认证的旧索引。普通索引重建不代表加密源数据已经通过认证。
配置载荷的版本化扩展沿用现有认证加密容器、siyuan/box-metadata 子密钥用途及笔记本绑定 AAD,不修改加密信封、AAD 语义或密钥派生。后续若涉及这些格式,必须另有显式版本、认证迁移和中断恢复设计,并保留匹配的密钥与备份材料。不得重新生成 MasterSalt、丢弃密钥或要求用户重建已有加密笔记本来规避兼容问题。文档、历史、备份和同步快照中的受支持格式必须持续可恢复。
实施拆分与开放条件
| 阶段 | 交付内容 | 完成条件 |
|---|---|---|
| A:兼容保护 | 候选祖先链冲突识别、源版本保护及历史样本 | 同步及快照应用前验证来源,所有写入与修复入口安全拒绝不支持的源格式或规格;不要求单独发布保护版本 |
| B:内部解耦 | 统一标题读取、文档元数据、ID 层级计算、路径刷新及恢复 | 普通标题行为不变;结构不再从显示字符串推导,加密索引可认证重建 |
| C:接口与调用方 | 新读取、解析、条件创建接口,版本 2 模板及加密载荷,内置业务及各端迁移 |
名称与配置并发条件、新旧契约通过验证,部分失败及撤销可恢复,日记等业务行为保持 |
| D:开放新字符 | 统一结构化规则及索引恢复、旧接口拒绝规则、插件迁移说明、跨笔记本操作及导入导出验证 | 普通构建默认支持 /;完整子树预检、索引恢复及全部发布条件通过后才完成对外发布验收 |
| E:行级标题 | 独立的源格式、编辑及渲染设计 | 保持本方案身份接口,完成格式及旧写入保护后另行交付 |
阶段 A 至 D 为同一功能版本的实现与验证拆分,不保留独立的旧寻址模式;开发分支已默认开放新字符,对外发布验收仍要求 A 至 D 的相关条件全部成立。阶段 E 不作为基础解耦的前置依赖,也不能在 A 至 D 中重新引入只接受永久纯文本来源的假设。
开放条件包括:所有内置消费者已迁移;替代接口和插件适配文档已发布;当前实现的 Spec 及写入前拒绝检查通过验证;普通与加密索引迁移可中断恢复;导入导出不会因显示路径冲突覆盖文件;桌面、浏览器和移动端行为一致;四种语言的用户指南说明默认行为、插件影响、全部设备统一升级及混用后果。对旧数据及旧协议的回归不构成与旧客户端混用的支持承诺。
实施已分配 .sy 规格 6;功能版本发布时附上已有性能测量与兼容测试结果,并如实说明验证限制。不以先发布保护版本或登记其版本号作为本议题的验收前置条件;功能版本的兼容性声明须由实际发行包及其能力验证支持。这些是发布证据,不是重新悬置身份、模板、插件边界或失败语义的决策。不能以完成文档、通过隔离测试或一次索引重建代替全部功能验收。
验证与验收
行为矩阵
| 范围 | 必须覆盖的场景 |
|---|---|
| 标题内容 | /、/、连续斜杠、%2F、.、..、空标题、Unicode 和长度边界;原字符不发生未经约定的转换 |
| 身份与层级 | 单标题 A/B 与两级 A、B,同父同名、不同父同名、重复 ID 的归属校验、根位置及笔记本文档 |
| 创建与并发 | 直接按 ID 跟随父位置及带版本请求拒绝过期预览;同名祖先并发创建、匹配集合及配置变化;父文档删除、跨笔记本移动、关闭或锁定;响应丢失、部分提交、固定 ID 冲突及多级恢复 |
| 模板 | 旧语法全部边界及旧模板语法及有效父 ID 消歧、新语法逐段渲染、变量包含 /、相对操作、同一时间快照、配置继承及正文模板选择、日记与速记等入口、模板文档树整组撤销和重做 |
| 搜索与展示 | 原始标题字符检索、祖先文字检索、ID 范围过滤、标题高亮、面包屑段边界、复制文字与 ID 链接 |
| 索引与恢复 | 深层子树、父子连续重命名、旧编辑快照、批次中断、重启、移动、删除、同步及普通与加密索引迁移 |
| 导入导出及跨笔记本操作 | 重名、非法文件名、大小写冲突、路径越界、相对链接、跨笔记本引用、标题元数据及无损往返承诺;移动、复制和恢复预检全部后代,拒绝时不产生部分写入 |
| 旧接口与插件 | 干净旧路径兼容;真实祖先链冲突拒绝;两个旧目标读取接口拒绝失效配置,不依赖旧目标的诊断版本;SQL 显示字符串碰撞、结构化替代接口、能力缺失与请求失败的区别 |
| 旧数据兼容与加密 | 支持的历史格式及配置载荷样本、旧同步来源的预检与拒绝、固定版本、缺失及 pending 索引拒绝、只读启动清理跳过、认证失败、锁定期间的缓存和响应、历史及备份恢复、密钥材料保留;不承诺新旧客户端混用 |
| 行级元素扩展 | 现有 Markdown 样式文字保持字面含义;标题表示变化不影响身份与层级;纯文本相同不合并文档;格式与纯文本来源单向派生;#19235 的图片及链接双向转换保留、资源引用和防重复要求 |
| 跨端与性能 | 桌面、浏览器和移动端创建及重命名;大子树下的前台延迟、数据库批次时间、内存、CPU 和磁盘读写 |
关键回归用例
保留 TestCreateDocsByHPathUsesParentIDForDuplicateHPath 和 TestCreateDocsByHPathKeepsHPathFallbackForDifferentParent,证明旧兼容入口没有被新规则悄悄替换。另为新入口覆盖父标题变化后仍使用原 ID、父跨笔记本移动后拒绝、同名父文档不会被误选,以及带版本提交返回 planChanged。
同时建立根文档 A/B、根文档 A 及其子文档 B、根文档 A/B、根文档 A%2FB。前两者允许相同显示路径,但 ID、segments、depth、子树范围和导出链接必须各自正确;后两者不得被转换成前两者。增加重复斜杠、点段、空标题、大小写差异和相同纯文本不同标题格式的样本。
两个请求同时解析缺失祖先并提交同一不存在条件,验证只成功一次,另一次返回 planChanged;普通同名最终文档仍可分别创建。已匹配祖先出现第二个同名文档时,唯一身份条件失败。配置预览后改变目标笔记本、继承配置或正文模板路径,即使父路径版本相同也须拒绝;重命名与配置更新发生在最后校验和提交之间的竞争也需覆盖。
构造普通根标题但后代含 / 或未知标题表示的子树,验证移动、复制、导入和恢复在源写入前检查全部后代、源规格与认证;预检后变化仍须被发现,不能降低规格或绕过加密边界。
验证旧配置和历史快照恢复、缺失配置、已撤销记录的忽略与启动清理;索引未就绪必须拒绝路径定位及创建。使用受支持的普通和加密历史样本,检查未知源格式保护、认证失败、目标配置无明文落盘和锁定后的缓存清理,保留备份及改密恢复覆盖。
TestDocumentAddressingCheckoutSourcePreflight 使用实际仓库快照,覆盖缺少模式标记的未来规格、未知标题表示、现存不兼容源及模式检查优先级;拒绝时同批新增、替换和删除均不开始,源字节、时间及快照来源保持不变。TestDocumentAddressingCheckoutSourceRemoval 区分部分删除与整本删除;TestDocumentAddressingCheckoutPreservesOpaqueEncryptedSource 使用历史密文样本验证无需解锁的原字节传输,并检查配置及恢复材料不变。路径回归覆盖反斜杠、重复目标,以及 Windows 的尾点、尾空格和默认数据流别名,不能让实际落盘目标绕过来源检查。另保留 BOM、合法斜杠标题、一般损坏源恢复和附件 .sy 的回归,避免来源保护扩大为不兼容的文件操作限制。
保留 TestHeadingDocParagraph 与 TestHeadingDocParagraphTextMark,基础解耦继续覆盖图片、链接和原标题内容进入正文的行为;阶段 E 再验证支持的节点进入标题源内容及双向转换,不按纯文本相等删除用户段落。模板文档树覆盖整组撤销和重做、部分提交、重做时的名称或 ID 冲突及创建后用户编辑,不能只测试新建成功。
实际 HTTP 回归检查严格请求类型、必填与 null 区别、返回顺序、候选截断、错误数据、管理员与可写保护、加密响应租约及发布访问拒绝。旧接口的兼容回归与新接口回归分开断言,避免用新预期覆盖旧行为。前端验证旧模板配置往返、新模板逐段求值、同一时间快照、部分成功提示以及移动端入口。
故障注入至少覆盖源文档落盘前后、元数据事务前后、内容索引批次中断、成功响应丢失及锁定发生在响应输出期间。使用受支持历史格式的真实样本验证读取、导出、历史、备份及恢复,同时验证能力受限读取器拒绝不支持的模式和格式;仅测试当前版本生成的文件不能证明向后兼容。受限读取器回归用于验证检查边界,不要求发布该读取器,也不承诺任意历史客户端具备相同保护。
性能与资源
同一环境比较基线和实现,使用 1,000 与 10,000 篇文档、宽子树及深度 7 的层级,并额外覆盖用户开启更深层级的情况;分别测试普通与已解锁加密笔记本。记录批量路径读取、父文档重命名、移动、首次重建和增量恢复的前台延迟、后台耗时、内存、数据库大小及 .sy 读取次数,报告中位数和高分位结果。
前台创建和读取不得因新增元数据而扫描整个笔记本;已就绪的父重命名不得逐篇读取后代正文。索引构建允许按文档数量扫描源数据,但须有进度和恢复点。缓存有明确上限,锁定时清除相应标题;不把每个内容块的整条祖先链常驻内存。既有 hpath 对内容块的后台更新成本单独记录,不把含调度等待的总耗时当作数据库耗时,也不宣称解耦会消除全部子树更新。
性能报告必须说明相对基线的变化及原因;具体耗时取决于设备、正文大小和加密开销,本草案不填写未测量的收益或固定毫秒承诺。明显回归先分析查询次数、事务批次及重复源读取,再决定缓存优化,不以改变标题语义换取性能。
实现阶段的检查
行为测试进入现有前端及内核测试发现范围;新 Go 契约用例名称保留 Contract。实施 API 改动后,在 app/ 执行 pnpm run api:generate --petal ../../petal、pnpm run api:check --petal ../../petal、pnpm run lint 及相关前端测试;在 kernel/ 执行 go test ./apicontract/... 和覆盖受影响 API、模型、文件系统、块树及 SQL 的回归测试。发布前由现有完整测试入口覆盖 pnpm test 与 go test -tags "fts5 sqlcipher" ./... -count=1。
新增祖先链、旧路径创建、CLI、MCP 和契约回归位于现有 Go 测试发现范围。执行带 fts5 sqlcipher 的相关包测试,保留 Spec 6、历史普通与加密样本、未知源格式、同步及恢复覆盖;不保留模式 1 覆盖构建或已删除机制的桩。文档另检查双语一致性、示例、链接及差异。
相关代码
| 范围 | 入口 |
|---|---|
| 创建、重命名、标题规范化及按名称解析 | model/file.go、model/path.go |
| 接口、模式配置与契约 | api/filetree.go、api/notebook.go、apicontract/filetree_remaining.go、conf/box.go |
| 源文档与只读路径恢复 | filesys/tree.go、filesys/hpath.go |
| 路径刷新、恢复队列与文档索引 | treenode/blocktree.go、treenode/hpath.go、model/hpath_refresh.go、sql/queue.go |
| 搜索及层级计算 | model/search.go、sql/block_query.go、search/config.ts |
| 新建入口与保存路径解析 | util/newFile.ts、util/configuredDocument.ts、mobile/util/initFramework.ts |
| 模板、数据库新建及速记 | model/template_doc_tree.go、model/attribute_view_new_item.go、model/shortcuts.go |
| 日记复用及旧创建回归 | model/daily_note.go、model/file_test.go |
| MCP 与内置 Agent 文档目标 | mcp/tools/document.go、mcp/tools/inbox.go、agent/agent.go |
| 导入与导出 | model/import.go、model/import_obsidian.go、model/export.go |
| 可复用的富文本来源校验模式 | treenode/table_cell_rich.go |
| 标题块与文档转换 | model/heading.go、model/heading_doc_test.go |
| 配置加密及同步应用 | model/box_conf_crypto.go、model/repository.go、model/sync_checkout.go |
| 文档版本 | treenode/tree.go、.sy 文件结构 |