An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
TypeScript agentic-aiai-agentknowledge-baselocal-firstmarkdownmcpmindmapnote-takingself-hostedsiyuanworkspace
:memo: Clarify coordinated upgrades and older-client risks https://github.com/siyuan-note/siyuan/issues/19938
Daniele54d5d853bd6
diff --git a/app/guide/20210808180117-6v0mkxr/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101225-k254i8g.sy b/app/guide/20210808180117-6v0mkxr/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101225-k254i8g.syindex ff90a0bafd..3aae95f0ad 100644--- a/app/guide/20210808180117-6v0mkxr/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101225-k254i8g.sy+++ b/app/guide/20210808180117-6v0mkxr/20200923234011-ieuun1p/20210808180303-6yi0dv5/20200924101225-k254i8g.sy@@ -6,7 +6,7 @@"id": "20200924101225-k254i8g","title": "Content Block Type","type": "doc",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -1474,7 +1474,7 @@"HeadingLevel": 2,"Properties": {"id": "20210104091538-a55chyw",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3298,7 +3298,7 @@"HeadingLevel": 3,"Properties": {"id": "20210104091538-clx67q4",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3364,12 +3364,12 @@"Type": "NodeParagraph","Properties": {"id": "20261023112115-9dsprn2",- "updated": "20261023112115"+ "updated": "20261024005543"},"Children": [{"Type": "NodeText",- "Data": "Before using this title capability, upgrade all sync devices to supported versions and check plugin compatibility. Migration runs automatically and resumes after interruption. Do not reopen the same workspace with an older version that lacks compatibility protection."+ "Data": "Before opening the workspace with the new version, quit older SiYuan versions on every device, upgrade every device that accesses this workspace or syncs its data to a version that supports the new title format, and check plugin compatibility. Do not open the workspace or resume syncing until all devices have been upgraded. Devices that are temporarily offline must also be upgraded before accessing or syncing this data. Migration runs automatically and resumes after interruption. After upgrading, do not use older versions to open, edit, restore, or sync the same data. An older version may reject documents using the new title format (Spec 6) but still read and write documents that retain an earlier format. It may also write back a stale editor copy from an open page, overwriting newer titles or content and syncing the overwritten data to other devices. Some documents being blocked does not mean the data is protected."}]},diff --git a/app/guide/20210808180117-czj9bvb/20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.sy b/app/guide/20210808180117-czj9bvb/20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.syindex fee72cb8fb..ab6997d1d5 100644--- a/app/guide/20210808180117-czj9bvb/20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.sy+++ b/app/guide/20210808180117-czj9bvb/20200812220555-lj3enxa/20210808180320-fqgskfj/20200905090211-2vixtlf.sy@@ -6,7 +6,7 @@"id": "20200905090211-2vixtlf","title": "内容块类型","type": "doc",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -1507,7 +1507,7 @@"HeadingLevel": 2,"Properties": {"id": "20210104090624-9qgquxh",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3380,7 +3380,7 @@"HeadingLevel": 3,"Properties": {"id": "20210104090624-5abfwla",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3446,12 +3446,12 @@"Type": "NodeParagraph","Properties": {"id": "20261023112115-q33vi92",- "updated": "20261023112115"+ "updated": "20261024005543"},"Children": [{"Type": "NodeText",- "Data": "使用新标题能力前,请将所有同步设备升级到受支持版本,并确认插件兼容。迁移自动完成,中断后会继续恢复。请勿使用缺少兼容保护的旧版本重新打开同一工作空间。"+ "Data": "使用新版打开工作空间前,请先退出所有设备上的旧版思源,并将访问同一工作空间或同步其数据的所有设备统一升级到支持新版标题格式的版本,同时确认插件兼容。全部设备升级完成前,请勿打开工作空间或恢复同步;暂时离线的设备也必须先升级,再访问或同步这些数据。迁移自动完成,中断后会继续恢复。升级后,请勿再用旧版本打开、编辑、恢复或同步同一数据。旧版本可能拒绝打开采用新版标题格式(Spec 6)的文档,但仍可能读写保留旧格式的文档,也可能将已打开页面中的旧编辑缓存写回,覆盖新标题或内容,并通过同步传播到其他设备。不能因为部分文档无法打开,就认为数据已受到保护。"}]},diff --git a/app/guide/20211226090932-5lcq56f/20211226115423-d5z1joq/20211226115825-mhcslw2/20211226120147-ib6yy3i.sy b/app/guide/20211226090932-5lcq56f/20211226115423-d5z1joq/20211226115825-mhcslw2/20211226120147-ib6yy3i.syindex 4e72423f7e..46c5e2d1f2 100644--- a/app/guide/20211226090932-5lcq56f/20211226115423-d5z1joq/20211226115825-mhcslw2/20211226120147-ib6yy3i.sy+++ b/app/guide/20211226090932-5lcq56f/20211226115423-d5z1joq/20211226115825-mhcslw2/20211226120147-ib6yy3i.sy@@ -6,7 +6,7 @@"id": "20211226120147-ib6yy3i","title": "內容區塊類型","type": "doc",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -1503,7 +1503,7 @@"HeadingLevel": 2,"Properties": {"id": "20211226120227-esm6f20",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3298,7 +3298,7 @@"HeadingLevel": 3,"Properties": {"id": "20211226120227-ub34qwj",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3365,12 +3365,12 @@"Type": "NodeParagraph","Properties": {"id": "20261023112115-6k97ybe",- "updated": "20261023112115"+ "updated": "20261024005543"},"Children": [{"Type": "NodeText",- "Data": "使用新標題功能前,請將所有同步裝置升級至受支援版本,並確認外掛相容。移轉自動完成,中斷後會繼續復原。請勿使用缺少相容保護的舊版本重新開啟同一工作空間。"+ "Data": "使用新版開啟工作空間前,請先結束所有裝置上的舊版思源,並將存取同一工作空間或同步其資料的所有裝置統一升級至支援新版標題格式的版本,同時確認外掛相容。所有裝置升級完成前,請勿開啟工作空間或恢復同步;暫時離線的裝置也必須先升級,再存取或同步這些資料。移轉自動完成,中斷後會繼續復原。升級後,請勿再用舊版本開啟、編輯、還原或同步同一資料。舊版本可能拒絕開啟採用新版標題格式(Spec 6)的文檔,但仍可能讀寫保留舊格式的文檔,也可能將已開啟頁面中的舊編輯快取寫回,覆蓋新標題或內容,並透過同步傳播到其他裝置。不能因為部分文檔無法開啟,就認為資料已受到保護。"}]},diff --git a/app/guide/20240530133126-axarxgx/20240530101000-4qitucx/20240530101000-gvtksyj/20240530101000-35bbvcx.sy b/app/guide/20240530133126-axarxgx/20240530101000-4qitucx/20240530101000-gvtksyj/20240530101000-35bbvcx.syindex 3aa6e340ff..918fcf7f77 100644--- a/app/guide/20240530133126-axarxgx/20240530101000-4qitucx/20240530101000-gvtksyj/20240530101000-35bbvcx.sy+++ b/app/guide/20240530133126-axarxgx/20240530101000-4qitucx/20240530101000-gvtksyj/20240530101000-35bbvcx.sy@@ -7,7 +7,7 @@"id": "20240530101000-35bbvcx","title": "コンテンツブロックの種類","type": "doc",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -1564,7 +1564,7 @@"Properties": {"ID": "20240530101000-rjjxxn8","id": "20240530101000-p035stn",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3517,7 +3517,7 @@"HeadingLevel": 3,"Properties": {"id": "20240530101000-gtx9sbs",- "updated": "20261023133001"+ "updated": "20261024005543"},"Children": [{@@ -3612,12 +3612,12 @@"Type": "NodeParagraph","Properties": {"id": "20261023112115-sb4a5iu",- "updated": "20261023112115"+ "updated": "20261024005543"},"Children": [{"Type": "NodeText",- "Data": "新しいタイトル機能を使用する前に、すべての同期端末を対応バージョンに更新し、プラグインの互換性を確認してください。移行は自動で行われ、中断後も復旧を継続します。互換性保護のない古いバージョンで同じワークスペースを開かないでください。"+ "Data": "新しいバージョンでワークスペースを開く前に、すべての端末で古いバージョンの SiYuan を終了し、同じワークスペースにアクセスする端末やそのデータを同期する端末をすべて、新しいタイトル形式に対応したバージョンに更新してください。プラグインの互換性も確認し、全端末の更新が完了するまでワークスペースを開いたり同期を再開したりしないでください。一時的にオフラインになっている端末も、これらのデータへのアクセスや同期の前に更新が必要です。移行は自動で行われ、中断後も復旧を継続します。更新後は、古いバージョンで同じデータを開いたり、編集・復元・同期したりしないでください。古いバージョンは新しいタイトル形式(Spec 6)のドキュメントを開けなくても、旧形式のままのドキュメントを読み書きできる場合があります。また、すでに開いていた画面に残る古い編集内容を書き戻し、新しいタイトルや内容を上書きして、その結果をほかの端末へ同期するおそれがあります。一部のドキュメントが開けないことは、データが保護されているという意味ではありません。"}]},diff --git a/app/src/types/api/index.d.ts b/app/src/types/api/index.d.tsindex eac8df267b..ab253c9fb9 100644--- a/app/src/types/api/index.d.ts+++ b/app/src/types/api/index.d.ts@@ -5406,7 +5406,7 @@ export interface APIPOSTRoutes {* 可选父路径 revision 与至多 128 项名称条件在源提交前分别校验;条件只能涉及目标祖先和最终父级。* ID 冲突不覆盖、不自动更换;错误 data 包含稳定 reason、commitState、阶段及已完成步骤。* 已落盘但排序或正文模板失败时保留源文档并返回其 ID,调用方不得把该错误当作未创建而重复提交。- * 功能版本默认保留标题中的 /,该文档写入 Spec 6;普通文档不因迁移统一升级,保护版本仍拒绝 /。+ * 普通构建默认保留标题中的 /,该文档写入 Spec 6;普通文档不因迁移统一升级,内部兼容模式 1 仍拒绝 /。* 加密笔记本使用原有认证写入与响应租约;自动模式迁移不改变密文格式或密钥材料。*/"/api/filetree/createDocByParent": {@@ -5692,7 +5692,7 @@ export interface APIPOSTRoutes {* 标题不作 Unicode 归一化、宽窄转换或百分号解码;同父同名返回 ambiguous,不任取候选。* candidates 按 ID 排序且最多 128 项,candidatesTruncated 标记截断;nameConditions 保留唯一及缺失条件。* 空段数组返回起点,根位置的 resolved 为 null,start.id 为 null;笔记本文档 ID 规范化为逻辑根。- * 索引未就绪返回 indexUnavailable;功能版本默认保留段内 /,保护版本仍遵守兼容模式限制。+ * 索引未就绪返回 indexUnavailable;普通构建默认保留段内 /,内部兼容模式 1 仍遵守原有标题限制。*/"/api/filetree/resolveDocPath": {request: ResolveDocPathRequestInput;@@ -6299,8 +6299,8 @@ export interface APIPOSTRoutes {* responses also contain documentCapabilities: structuredPaths advertises the ID/segment APIs,* not permission to open a closed or locked notebook. Ordinary builds migrate to mode 2* automatically without a user setting or special build flags. literalSlash requires consistent- * mode records and ready indexes. minimumReaderVersion remains null while protective-release- * verification is pending; this informational field does not control feature activation.+ * mode records and ready indexes. minimumReaderVersion stays null until the minimum compatible+ * feature release is verified; it neither controls activation nor permits mixing with older clients.* Revision covers configuration, confirmed capability and recovery records, not a document path.* Malformed capability records fail the request; authentication, locking and network failures must* never be interpreted as an absent capability object or as permission to retry a legacy write.diff --git a/docs/API.ja.md b/docs/API.ja.mdindex 461e9f2a37..9b30df5147 100644--- a/docs/API.ja.md+++ b/docs/API.ja.md@@ -298,7 +298,7 @@ if (response.code === 0 && response.data) {### ノートブック設定を取得-管理者向けレスポンスには、読み取り専用の `documentCapabilities` オブジェクトが含まれる場合があります。アドレス指定モード、構造化 API、タイトル機能、インデックス状態、検証済みの最低読み取りバージョンを示します。通常のビルドでは、設定の切り替えや追加のビルド引数なしに、既定で自動移行されます。`literalSlash` にはモード `2`、整合したモード記録、準備済みインデックスが必要です。保護リリースの検証が完了するまで `minimumReaderVersion` は `null` ですが、新モードの既定の有効化には影響しません。既存の権限によるフィルタリングは維持されます。+管理者向けレスポンスには、読み取り専用の `documentCapabilities` オブジェクトが含まれる場合があります。アドレス指定モード、構造化 API、タイトル機能、インデックス状態、検証済みの最低互換機能バージョンを示します。通常のビルドでは、設定の切り替えや追加のビルド引数なしに、既定で自動移行されます。`literalSlash` にはモード `2`、整合したモード記録、準備済みインデックスが必要です。この機能に対応する最低バージョンの配布版が検証されるまで、`minimumReaderVersion` は `null` です。このフィールドは情報の提供のみを目的とし、機能の有効化を制御せず、古いクライアントとの混在利用を許可するものでもありません。使用前に、すべての同期端末をこの機能に対応するバージョンへ更新してください。既存の権限によるフィルタリングは維持されます。* `/api/notebook/getNotebookConf`* パラメータ@@ -331,7 +331,7 @@ if (response.code === 0 && response.data) {}```-管理者への応答には、読み取り専用の省略可能な `documentCapabilities` オブジェクトも含まれます。`structuredPaths` は ID とパス要素の API への対応を示し、閉じたノートブックやロック中のノートブックへのアクセス権限は付与しません。`literalSlash` はモード `2` でモード記録が整合し、インデックスが準備済みの場合に `true` です。保護バージョンの検証が完了するまで `minimumReaderVersion` は `null` で、この値は機能の有効化を制御しません。旧サーバーにこのオブジェクトがない場合とリクエストの失敗は区別し、失敗後に従来のパス API で書き込みを再試行しないでください。+管理者への応答には、読み取り専用の省略可能な `documentCapabilities` オブジェクトも含まれます。`structuredPaths` は ID とパス要素の API への対応を示し、閉じたノートブックやロック中のノートブックへのアクセス権限は付与しません。`literalSlash` はモード `2` でモード記録が整合し、インデックスが準備済みの場合に `true` です。この機能に対応する最低バージョンの配布版が検証されるまで、`minimumReaderVersion` は `null` です。このフィールドは情報の提供のみを目的とし、機能の有効化を制御せず、古いクライアントとの混在利用を許可するものでもありません。使用前に、すべての同期端末をこの機能に対応するバージョンへ更新してください。旧サーバーにこのオブジェクトがない場合とリクエストの失敗は区別し、失敗後に従来のパス API で書き込みを再試行しないでください。### ノートブック設定を保存diff --git a/docs/API.md b/docs/API.mdindex 724cb8f251..37644fb1d1 100644--- a/docs/API.md+++ b/docs/API.md@@ -303,7 +303,7 @@ The close endpoint validates the notebook ID without trimming whitespace. Typed### Get notebook configuration-Administrator responses may also include the read-only `documentCapabilities` object. It reports addressing mode, structured API support, title capabilities, index state, and the verified minimum reader release. Ordinary builds migrate notebooks automatically by default, without a user setting or extra build flags; `literalSlash` requires mode `2`, consistent records, and ready indexes. `minimumReaderVersion` remains `null` until the protective release is verified; it does not disable the default mode. Existing permission filtering still applies.+Administrator responses may also include the read-only `documentCapabilities` object. It reports addressing mode, structured API support, title capabilities, index state, and the verified minimum compatible feature release. Ordinary builds migrate notebooks automatically by default, without a user setting or extra build flags; `literalSlash` requires mode `2`, consistent records, and ready indexes. `minimumReaderVersion` remains `null` until the minimum compatible feature release is verified; this informational field neither controls activation nor permits mixing with older clients. All sync devices must upgrade to versions supporting this feature before use. Existing permission filtering still applies.* `/api/notebook/getNotebookConf`* Parameters@@ -336,7 +336,7 @@ Administrator responses may also include the read-only `documentCapabilities` ob}```-Administrator responses also include the optional read-only `documentCapabilities` object. `structuredPaths` advertises the ID and segment APIs; it does not grant access to closed or locked notebooks. `literalSlash` is `true` in mode `2` with consistent mode records and ready indexes. `minimumReaderVersion` is `null` until a protective release is verified and does not control feature activation. An absent object on an older server differs from a failed request; failures must not trigger a fallback write through legacy path APIs.+Administrator responses also include the optional read-only `documentCapabilities` object. `structuredPaths` advertises the ID and segment APIs; it does not grant access to closed or locked notebooks. `literalSlash` is `true` in mode `2` with consistent mode records and ready indexes. `minimumReaderVersion` remains `null` until the minimum compatible feature release is verified; this informational field neither controls activation nor permits mixing with older clients. All sync devices must upgrade to versions supporting this feature before use. An absent object on an older server differs from a failed request; failures must not trigger a fallback write through legacy path APIs.### Save notebook configurationdiff --git a/docs/API.zh-CN.md b/docs/API.zh-CN.mdindex 4e430bb2de..30d52c0779 100644--- a/docs/API.zh-CN.md+++ b/docs/API.zh-CN.md@@ -303,7 +303,7 @@ if (response.code === 0 && response.data) {### 获取笔记本配置-管理员响应还可包含只读的 `documentCapabilities` 对象,用于报告寻址模式、结构化接口支持、标题能力、索引状态及已验证的最低读取版本。普通构建默认自动迁移笔记本,无需设置开关或额外编译参数;`literalSlash` 要求模式 `2`、模式记录一致且索引就绪。保护版本尚未验证时,`minimumReaderVersion` 为 `null`,不影响新模式默认启用。既有权限过滤保持不变。+管理员响应还可包含只读的 `documentCapabilities` 对象,用于报告寻址模式、结构化接口支持、标题能力、索引状态及已验证的最低兼容功能版本。普通构建默认自动迁移笔记本,无需设置开关或额外编译参数;`literalSlash` 要求模式 `2`、模式记录一致且索引就绪。最低兼容功能发行版尚未验证时,`minimumReaderVersion` 为 `null`;该字段仅提供信息,不控制功能启用,也不表示允许与旧客户端混用。使用前须将所有同步设备统一升级到支持本次功能的版本。既有权限过滤保持不变。* `/api/notebook/getNotebookConf`* 参数@@ -336,7 +336,7 @@ if (response.code === 0 && response.data) {}```-管理员响应还包含可选只读对象 `documentCapabilities`。`structuredPaths` 表示服务端支持 ID 与路径段接口,不授予关闭或锁定笔记本的访问权限。`literalSlash` 在模式 `2`、模式记录一致且索引就绪时为 `true`;保护版本验证完成前,`minimumReaderVersion` 为 `null`,该字段不控制功能启用。旧服务端缺少此对象与请求失败含义不同,不能在请求失败后回退到旧路径接口继续写入。+管理员响应还包含可选只读对象 `documentCapabilities`。`structuredPaths` 表示服务端支持 ID 与路径段接口,不授予关闭或锁定笔记本的访问权限。`literalSlash` 在模式 `2`、模式记录一致且索引就绪时为 `true`。最低兼容功能发行版尚未验证时,`minimumReaderVersion` 为 `null`;该字段仅提供信息,不控制功能启用,也不表示允许与旧客户端混用。使用前须将所有同步设备统一升级到支持本次功能的版本。旧服务端缺少此对象与请求失败含义不同,不能在请求失败后回退到旧路径接口继续写入。### 保存笔记本配置diff --git a/docs/DOCUMENT-ADDRESSING.md b/docs/DOCUMENT-ADDRESSING.mdindex 5aeaf0892e..1d767b7aba 100644--- a/docs/DOCUMENT-ADDRESSING.md+++ b/docs/DOCUMENT-ADDRESSING.md@@ -12,15 +12,15 @@ The development branch implements a shared title reader, document metadata organCreation plans retain fixed IDs and never recreate confirmed ancestors. Desktop and mobile share failure handling: an uncertain response or a failure after source commit retains the plan until the user approves an identity check and continuation. Closing or locking a notebook clears its title and template caches. Local shorthands keep a recovery record containing only identities and digests, verify block identities in the actual source before consuming the input, and preserve unresolved input without automatically replaying the operation.-The structured-title feature release defaults to mode `2`, without a user setting or manual activation endpoint. The development branch implements automatic mode migration and interruption recovery, `DocumentTitleSpec = "6"`, literal slash reads and writes, and notebook-wide rejection of legacy string addressing. The frontend initializes title input rules from a read-only runtime capability. Ordinary builds default to mode `2` without additional build flags. `minimumReaderVersion` only reports a verified compatible release; leaving it unset does not disable the new mode. Actual protective-release, mixed-version, performance, and platform acceptance remain required release evidence and cannot be inferred from default activation. Inline-title extension requirements remain unchanged.+The structured-title feature release defaults to mode `2`, without a user setting or manual activation endpoint. The development branch implements automatic mode migration and interruption recovery, `DocumentTitleSpec = "6"`, literal slash reads and writes, and notebook-wide rejection of legacy string addressing. The frontend initializes title input rules from a read-only runtime capability. Ordinary builds default to mode `2` without additional build flags. All clients accessing the same workspace or synchronized data must upgrade together to a version supporting mode `2` and Spec `6`; mixing them with older clients is unsupported. A separate transitional protective release is not required. Existing-data compatibility, format and capability rejection, migration recovery, performance, and platform acceptance remain required; default activation does not establish their completion. Inline-title extension requirements remain unchanged.-Administrator notebook configuration reads expose `documentCapabilities`, distinguishing structured APIs, the effective addressing mode, and index state. `minimumReaderVersion` stays `null` until a real protective release has been verified; malformed capability records return an error. Whole-notebook native import remaps notebook and anchor IDs in configured targets, while partial import preserves the destination configuration. Encrypted targets retain authenticated locked saves, password rewrapping, and backup recovery.+Administrator notebook configuration reads expose `documentCapabilities`, distinguishing structured APIs, the effective addressing mode, and index state. The `minimumReaderVersion` field is retained and currently returns `null`; this neither disables the feature nor permits mixed use with older clients. A future value must identify an actual feature release verified to support the required capabilities. Malformed capability records return an error. Whole-notebook native import remaps notebook and anchor IDs in configured targets, while partial import preserves the destination configuration. Encrypted targets retain authenticated locked saves, password rewrapping, and backup recovery.## Goals and scopeDocument IDs determine identity and hierarchy membership; titles express content; readable paths provide presentation. Creation, moves, and references must not recover document identity by parsing display text. Once the affected entry points have migrated and compatibility has been verified, document titles can contain the ASCII slash `/` while remaining distinct from existing fullwidth slashes `/`.-Future support for inline elements in document titles is a required extension capability of this design. Addressing, title presentation, plain-text extraction, and storage representation must remain separate. The design must not permanently constrain titles to a single plain-text string interpreted directly by every consumer. A complete rich title format, editing interactions, and the supported element set are outside the current scope. Issue #20837 tracks inline titles and bidirectional conversion, literal `/` in notebook names, and verification of actual third-party plugin versions; older-client protection and acceptance for this release remain in #19938.+Future support for inline elements in document titles is a required extension capability of this design. Addressing, title presentation, plain-text extraction, and storage representation must remain separate. The design must not permanently constrain titles to a single plain-text string interpreted directly by every consumer. A complete rich title format, editing interactions, and the supported element set are outside the current scope. Issue #20837 tracks inline titles and bidirectional conversion, literal `/` in notebook names, and verification of actual third-party plugin versions; format and capability checks, existing-data compatibility, and acceptance for this release remain in #19938.The design covers desktop, browser, mobile, kernel APIs, and plugin-visible data, subject to the respective access boundaries of ordinary and encrypted notebooks. Notebook names participate in path presentation as separate display fields. Their character restrictions and rich text support require a separate assessment of configuration formats and older clients; document title rules do not automatically apply to notebook names.@@ -35,7 +35,7 @@ The design covers desktop, browser, mobile, kernel APIs, and plugin-visible data| Readable paths | Join original ancestor title text for display; do not encode `/` or decode `/` or `%2F` || Indexes | Retain existing `hpath` columns and add internal document metadata; do not store full title segment arrays on every content block || Title sources | Keep ordinary titles in the first implementation, with an extension boundary for versioned inline content and one-way plain-text derivation |-| Release order | Release compatibility protection and structured capabilities first, enable `/` after migration verification, and implement rich titles separately |+| Upgrade policy | Stop all clients accessing the same workspace or synchronized data, upgrade every device to a version supporting mode `2` and Spec `6`, and resume only with those versions; implement rich titles separately |The compatibility boundary is the notebook, avoiding guesses about a caller's title intent from individual requests. For example, `/A/B` can describe two levels or display one literal title; the legacy request cannot distinguish them. Once structured title mode is enabled, legacy string addressing fails explicitly throughout that notebook, even for documents whose titles remain ordinary. ID-based operations and ordinary text display remain available. This is the defined plugin adaptation boundary, not a promise that all old plugins work unchanged.@@ -181,7 +181,7 @@ The compatibility compiler evaluates legacy templates using their original grammLegacy workflows and string templates in mode `1` retain existing duplicate-name selection and `parentID` fallback behavior. Internal identity-based implementations must pass legacy regressions rather than silently returning ambiguity errors because they share a strict resolver. New structured APIs apply strict ambiguity checks in both modes. Built-in mode `2` workflows use strict plans even for legacy templates and never select an arbitrary same-named parent; describe that behavior change in feature-release migration guidance. A cross-notebook target used through the new protocol remains strict even when the destination uses mode `1`.-New configuration uses `docCreateTarget`, `refCreateTarget`, and `dailyNoteTarget` alongside the original string save-path fields. These objects are available in the configuration of notebooks automatically migrated to mode `2` by the feature release. Global settings retain legacy string templates and existing inheritance rules, keeping global configuration compatible with the protective release. Each object requires `version: 2`, specifying the destination notebook, anchor, number of upward steps, ancestor segments, final title, and missing-parent policy. Each segment reuses the existing save-path template evaluator. The example's `{{now | date ...}}` syntax is for save-path templates and must not be confused with body-template syntax.+New configuration uses `docCreateTarget`, `refCreateTarget`, and `dailyNoteTarget` alongside the original string save-path fields. These objects are available in the configuration of notebooks automatically migrated to mode `2` by the feature release. Global settings retain legacy string templates and existing inheritance rules so existing configurations remain usable after upgrading. Each object requires `version: 2`, specifying the destination notebook, anchor, number of upward steps, ancestor segments, final title, and missing-parent policy. Each segment reuses the existing save-path template evaluator. The example's `{{now | date ...}}` syntax is for save-path templates and must not be confused with body-template syntax.```json{@@ -333,7 +333,7 @@ The caller submits each `createDocByParent` request in order, updating the next### Capability discovery and automatic migration-Add an optional read-only `documentCapabilities` object to `data` in `/api/notebook/getNotebookConf`, retaining existing `box`, `name`, `conf`, and access filtering. It contains `addressingVersion`, `modeState`, `structuredPaths`, `literalSlash`, `titleFormats`, `indexState`, `minimumReaderVersion`, and `revision`. `modeState` is `legacy`, `structured`, `conflict`, or `recovering`. `structuredPaths` means the server implements the new protocol, and `indexState` describes derived-index state; neither replaces mode state. Administrator responses include this object; other roles retain existing configuration filtering. `minimumReaderVersion` is `null` until the actual protective release has been verified, then contains its version string. This field does not control feature activation. Initially, `titleFormats` is `["plain"]`; `literalSlash` is `true` only in mode `2` with `modeState: "structured"` and a ready index.+Add an optional read-only `documentCapabilities` object to `data` in `/api/notebook/getNotebookConf`, retaining existing `box`, `name`, `conf`, and access filtering. It contains `addressingVersion`, `modeState`, `structuredPaths`, `literalSlash`, `titleFormats`, `indexState`, `minimumReaderVersion`, and `revision`. `modeState` is `legacy`, `structured`, `conflict`, or `recovering`. `structuredPaths` means the server implements the new protocol, and `indexState` describes derived-index state; neither replaces mode state. Administrator responses include this object; other roles retain existing configuration filtering. `minimumReaderVersion` is retained as nullable compatibility metadata and currently returns `null`. Any future version string must be backed by verification of an actual feature release supporting mode `2` and Spec `6`; assigning one is not a prerequisite for closing this issue. This field does not control feature activation, and `null` does not mean older clients may access or synchronize the data safely. Initially, `titleFormats` is `["plain"]`; `literalSlash` is `true` only in mode `2` with `modeState: "structured"` and a ready index.`revision` summarizes mode records and recovery state. It is neither an individual document's path revision nor a user activation token. Capability declarations grant no access; closed or locked notebooks retain existing restrictions, and status reads expose neither titles nor protected template content. When an older server omits the object, plugins use only legacy capabilities. Authorization, locking, and network errors must not be interpreted as unsupported capabilities or trigger fallback writes.@@ -345,7 +345,7 @@ Implementation follows [Kernel API type contracts](API-CONTRACTS.md): define dec## API and plugin compatibility-Mode `1` is the protective release's compatibility mode; mode `2` is the structured title mode automatically adopted by the feature release. Old notebook records without a higher requirement read as `1`, then migrate automatically to `2` before source access in the feature release. Missing fields cannot lower an established capability floor. The mode determines availability of legacy protocols, not a guess based on whether a particular request contains `/`.+Mode `1` denotes legacy compatibility; mode `2` is the structured title mode automatically adopted by the feature release. Retaining mode `1` semantics supports legacy data interpretation and limited-reader regression tests, not a separate transitional release plan or permission to mix older clients with upgraded data. Old notebook records without a higher requirement read as `1`, then migrate automatically to `2` before source access in the feature release. Missing fields cannot lower an established capability floor. The mode determines availability of legacy protocols, not a guess based on whether a particular request contains `/`.| Use case | Compatibility mode `1` | Structured title mode `2` | Plugin migration || --- | --- | --- | --- |@@ -370,11 +370,13 @@ Plugins migrate through capability discovery, reading known targets by ID, resol## Versions, encryption, and recovery-### Mixed-version access+### Coordinated upgrades and older-client risksNotebook configuration stores the internal compatibility marker `documentAddressingVersion`: an absent field or `1` denotes legacy records, and `2` denotes structured-title records. Effective mode also considers the capability floors and recovery records below. This is not a user setting, is independent of encryption-envelope versions, and must not reuse `BoxCrypt.Spec`. The feature release migrates records automatically without rewriting existing document titles or IDs in bulk.-Even if `.sy` continues storing a string title, older clients can remove `/` or interpret title text as hierarchy. External release compatibility requires two steps: first a protective version recognizing notebook capability and recovery markers and safely rejecting unsupported modes, then a feature version defaulting to mode `2`. Ordinary development builds already default to mode `2`, independently of minimum-version metadata. The protective version rejects unsupported modes before mounting, indexing, repairing, editing, or applying sync changes; it must not modify data before requesting an upgrade.+This release uses a coordinated upgrade across all devices, without a separate transitional protective release. Before upgrading, stop every client accessing the same workspace or synchronized data, including desktop, mobile, and server instances. Upgrade all of them to a version supporting mode `2` and Spec `6` before resuming access or synchronization. An offline device still running an older client must remain disconnected from this data until it is upgraded. The application cannot prove the state of offline devices, so release notes and user guides must state this requirement explicitly.++Ordinary development builds already default to mode `2`, independently of minimum-version metadata. Keep notebook mode, capability-floor, recovery-record, and document-specification checks at all applicable read, write, mount, index, repair, import, history, backup, sync, and recovery entry points. A reader implementing these checks must reject unsupported capabilities before processing or replacing source data. These checks preserve data within the supported implementation; they cannot retrofit protection into an older client that ignores the records.Documents actually using new title capabilities adopt `DocumentTitleSpec = "6"`: normal writes raise `Spec` to at least `6` when the title contains ASCII `/`. Ordinary titles retain the specification required by their body features. A client upgrade, mode migration, or ordinary formatting must not raise every document to `6` or lower an existing version. Future rich representations also need explicit format versions; tolerant parsing must never overwrite unknown content.@@ -386,9 +388,9 @@ Tree writes validate both the replacement and the current on-disk source. AuthenRaw file endpoints apply the same source-format checks to paths composed of notebook and document IDs; uploads, copies, and moves into those paths cannot bypass them. Validate the complete batch before creating destination directories or copying any files. Actual document copies use the validated source bytes and recheck the current destination under the file lock. Concurrent changes or I/O failures after preflight can leave completed copies; batch rollback is not promised. Files ending in `.sy` inside ordinary asset and plugin directories retain raw-file semantics, and encrypted notebooks remain inaccessible through raw file endpoints.-Determine the minimum compatible version through read, write, and rejection tests against actual releases. Clients predating the protective release that ignore capability markers cannot be constrained automatically and are outside the safe mixed-version promise. Before using the feature release, all sync devices must run at least the protective release. Offline device state cannot be proven; release notes and user guides must explain this limit. Incomplete protection prevents a claim of release readiness or safe mixed-version use; documentation or a user switch cannot substitute for protection.+Mixing older clients with upgraded data can produce inconsistent behavior rather than a reliable refusal to open: some Spec `6` documents may be rejected while documents retaining an older specification remain readable or writable. An older editing snapshot may overwrite newer source data; old title normalization or path parsing may remove a literal `/` or treat it as hierarchy. Synchronization may then propagate those incorrect changes to upgraded devices. This can cause lost edits or incorrect titles and paths, requiring recovery from history or backups. These are reasons to stop using older clients against the same data, not a promise that every older operation will fail safely.-An isolated probe of the published `v3.8.9-alpha.4` source rejects direct reads of Spec 6 documents but can still read legacy-specification documents in mode `2` or write a stale editing snapshot. That release cannot be recorded as verified protection, and the result does not support a blanket claim that older versions cannot open the data. Local protective candidate builds and regressions establish behavior of the tested source, not of an actual release package. After publishing the protective version, verify the package, source, and compiled capabilities, then validate ordinary and encrypted data compatibility, mode rejection, stale writes, sync, and recovery before recording `minimumReaderVersion` and completing release acceptance for this issue.+An isolated probe of the published `v3.8.9-alpha.4` source verified rejection of direct Spec `6` reads, continued reads of legacy-specification documents in mode `2`, and a stale editing snapshot overwriting source data. It did not establish the behavior of every old-version operation or a complete mixed-device sync scenario; the additional normalization, hierarchy, and propagation consequences above are risks, not reported results of that probe. Local mode `1` overlay builds are limited-reader regressions of the current source, not candidates for a planned transitional release, and they do not verify an actual release package. Preserve checks and regression coverage for ordinary and encrypted legacy data, unsupported modes and formats, stale writes, sync, and recovery. Keep `minimumReaderVersion` nullable until an actual feature release has been verified; neither a separate protective release nor assignment of that field is required to close this issue.Automatic migration to mode `2` has no switch back to `1`. Even after current titles no longer contain `/`, history and backups can retain new formats. Older clients may use a verified compatible export copy or a complete pre-upgrade backup restored into a separate workspace; do not overwrite the original workspace with old configuration and continue syncing. Any future downgrade converter requires its own conversion manifest, conflict policy, and recovery design while preserving original data.@@ -400,13 +402,13 @@ The local record uses `{version: 1, notebooks: {"<notebookID>": 2}}`, omitting nSettings export remains an archive containing one JSON file. When confirmed capability requirements exist, that JSON carries a top-level `documentAddressing` field with the same structure as the local record. Import validates and merges the maximum requirement per identity before adopting ordinary settings; an older backup without this field does not clear the local record, and invalid or unknown record versions fail before settings are adopted. This field only transfers backup information: restoration keeps it in `conf/document-addressing.json`, outside ordinary `conf.json`, and includes no titles, content, or keys. Raw file APIs must not overwrite, rename, or delete the local record. Notebook writes and copies preflight incoming configuration and all destinations; sort recovery preserves original files and pending recovery records for unsupported modes.-The protective release recognizes both configuration and capability floor records, rejecting unsupported modes before processing source files. Sync application and snapshot restoration check affected notebooks' capability requirements before replacing configuration or files. Once mode `2` is confirmed, incoming old configuration, missing new fields, or deletion of a capability record cannot lower the effective mode; restore configuration projections and floor records before reopening access. If checks can occur only after files are persisted, or the dependency cannot expose required configuration before application, stage A is incomplete. Complete sync and recovery entry points first; index rebuilding does not substitute for pre-application protection.+Readers recognize both configuration and capability floor records, rejecting modes beyond their supported capabilities before processing source files. Sync application and snapshot restoration check affected notebooks' capability requirements before replacing configuration or files. Once mode `2` is confirmed, incoming old configuration, missing new fields, or deletion of a capability record cannot lower the effective mode; restore configuration projections and floor records before reopening access. If checks can occur only after files are persisted, or the dependency cannot expose required configuration before application, stage A is incomplete. Complete sync and recovery entry points first; index rebuilding does not substitute for pre-application protection.Mode markers do not replace document-source checks. Before any file in a sync or snapshot batch is written or removed, validate incoming ordinary document sources and refuse to overwrite or partially delete existing sources identified during preflight as requiring unsupported specifications, title representations, or title capabilities. Missing mode markers must not allow incompatible sources to be persisted before indexing detects them. This check follows the existing recovery process; it does not make ordinary snapshot restoration an atomic transaction isolated from arbitrary external file changes. Valid history may still restore generally corrupted ordinary documents, whole-notebook deletion retains its existing semantics, and `.sy` files inside asset or plugin directories are not interpreted as documents. Locked encrypted notebooks continue transferring original ciphertext under the existing protocol without requiring an unlock for title preflight. Repository chunk verification does not authenticate notebook contents; ciphertext authentication and source-format checks remain within the existing protected read and recovery boundaries.Deleting an entire notebook retains existing semantics; do not recreate it merely to restore a capability record. Keep the locally confirmed floor for that identity and apply it when the same identity is restored. Native imports of whole notebooks validate the source identity and capability record before allocating or reusing the destination identity under existing import rules, then bind the floor to that destination identity. Identity remapping must not lower the source notebook's confirmed mode. Importing selected documents into an existing notebook instead checks the complete operation set described above without copying the source notebook's mode configuration.-Automatic migration first persists `{version: 1, notebook, phase: "records"}` in `conf/document-addressing-recovery/<notebookID>.json`, then writes the local floor, notebook floor, and configuration mode marker in that order, and finally removes the recovery record. After interruption, the next access continues the same migration without retracting a written requirement. The protective release also interprets valid recovery records as requiring at least mode `2`. Preserve unknown configuration fields and opaque encrypted payload values, without scanning or rewriting `.sy` files. Raw file APIs cannot overwrite the recovery directory.+Automatic migration first persists `{version: 1, notebook, phase: "records"}` in `conf/document-addressing-recovery/<notebookID>.json`, then writes the local floor, notebook floor, and configuration mode marker in that order, and finally removes the recovery record. After interruption, the next access continues the same migration without retracting a written requirement. Readers must interpret valid recovery records as requiring at least mode `2`, including when checking rejection with a limited reader. Preserve unknown configuration fields and opaque encrypted payload values, without scanning or rewriting `.sy` files. Raw file APIs cannot overwrite the recovery directory.The feature release automatically repairs missing mode projections and outdated configuration without recreating deleted notebooks. Mode migration and index rebuilding remain separate: metadata migration needs no ready index and neither authenticates nor rewrites document ciphertext. Subsequent source reads and index construction must still authenticate source content under existing authorization and encrypted-notebook leases. Report `modeState: "structured"` only after records are consistent and indexes are ready. If an existing notebook has lost its configuration file, retain the confirmed mode without creating a replacement configuration. Encrypted backup recovery must still authenticate the original key and payload and cannot save the notebook as plaintext. Capabilities remain `recovering` until configuration is restored.@@ -440,17 +442,17 @@ The versioned configuration-payload extension retains the existing authenticated| Stage | Deliverables | Completion criteria || --- | --- | --- |-| A: Compatibility protection | Notebook capability floors and conflict detection, unknown-mode and source-version protection, existing behavior fixtures | Protective release shipped; modes checked before sync and snapshot application, unsupported modes safely refused at every write and repair entry point |+| A: Compatibility protection | Notebook capability floors and conflict detection, unknown-mode and source-version protection, existing behavior fixtures | Modes checked before sync and snapshot application; unsupported modes and formats safely refused at applicable read, write, and repair entry points; existing data remains readable and recoverable || B: Internal separation | Shared title access, document metadata, ID hierarchy calculations, path refresh, and recovery | Ordinary titles retain behavior; structure is no longer derived from display strings; encrypted indexes rebuild from authenticated sources || C: APIs and consumers | New read, resolve, and conditional-create APIs, version `2` templates and encrypted payloads, built-in workflow and platform migration | Name and configuration conditions and old/new contracts verified; partial failures and undo recoverable; daily-note and other business behavior retained || D: New characters | Default structured mode and automatic recovery, legacy API rejection, plugin migration guidance, cross-mode operations, and import/export checks | Ordinary builds support `/` by default; whole-subtree preflight, mode recovery, and all release criteria must pass to complete external release acceptance || E: Inline titles | Separate source-format, editing, and rendering design | Retain this design's identity APIs and deliver separately after format and old-writer protection |-Stages B and C may ship while retaining legacy title restrictions. The development branch enables new characters by default; external release acceptance still requires all relevant conditions in A through D. Stage E is not a prerequisite for the foundational separation, but A through D must not reintroduce assumptions that titles will permanently have plain-text sources.+Stages A through D are implementation and acceptance groups, not a requirement to publish separate transitional releases. The development branch enables new characters by default; external release acceptance still requires their relevant conditions and the coordinated-upgrade instructions above. Stage E is not a prerequisite for the foundational separation, but A through D must not reintroduce assumptions that titles will permanently have plain-text sources.-Release gates include migrated built-in consumers, released replacement APIs and plugin guidance, verified minimum client versions and mixed-version rejection, interruptible ordinary and encrypted index migration, exports that do not overwrite files due to display-path collisions, consistent desktop/browser/mobile behavior, and user guides in all four bundled languages covering default behavior, plugin impact, and sync-device requirements.+Release gates include migrated built-in consumers, replacement APIs and plugin guidance shipped with the feature, verified existing-data compatibility and format/capability rejection, interruptible ordinary and encrypted index migration, exports that do not overwrite files due to display-path collisions, consistent desktop/browser/mobile behavior, and user guides in all four bundled languages covering default behavior, plugin impact, coordinated upgrades, and the consequences of older-client mixed use. Safe mixed use with older clients is not a supported release scenario.-The implementation allocates `.sy` specification `6`. Release still requires the actual protective release number, performance measurements, and compatibility results. These are release evidence, not unresolved decisions about identity, templates, plugin boundaries, or failure semantics. Completing documentation, passing isolated tests, or rebuilding an index once does not establish full feature acceptance.+The implementation allocates `.sy` specification `6`. Performance measurements, compatibility results, and platform acceptance remain release evidence. No separate protective-release number or non-null `minimumReaderVersion` is required for this issue's completion. Any later assignment of a feature-release version must be supported by verification of the actual release and its capabilities. Completing documentation, passing isolated tests, or rebuilding an index once does not establish full feature acceptance.## Verification and acceptance@@ -466,7 +468,7 @@ The implementation allocates `.sy` specification `6`. Release still requires the| Indexes and recovery | Deep subtrees, successive parent and child renames, stale edit snapshots, interrupted batches, restart, moves, deletion, sync, and ordinary and encrypted index migration || Import/export and cross-mode operations | Duplicate names, invalid filenames, case collisions, path escape, relative links, cross-notebook references, title metadata, and lossless round-trip guarantees; moves, copies, and recovery preflight every descendant, with no partial writes on rejection || Legacy APIs and plugins | Unchanged mode `1` responses; notebook-wide legacy-addressing rejection in mode `2`; both legacy target readers reject obsolete configuration even when its destination still uses mode `1`; SQL display collisions, structured replacements, and missing capabilities distinguished from request errors |-| Older clients and encryption | Supported historical source and configuration payload fixtures; mixed-version sync, capability floors never decreasing, mode conflict recovery without a ready index, authentication failure, caches and responses during lock, history and backup recovery, and retained key material |+| Legacy data, limited readers, and encryption | Supported historical source and configuration payload fixtures; limited-reader rejection regressions, stale-record and snapshot handling in sync, capability floors never decreasing, mode conflict recovery without a ready index, authentication failure, caches and responses during lock, history and backup recovery, and retained key material || Inline extension capability | Existing Markdown-like title text remains literal; representation changes do not affect identity or hierarchy; identical plain text does not merge documents; formatted source derives plain text in one direction; #19235 image/link round trips preserve content and asset references without duplication || Platforms and performance | Creation and rename on desktop, browser, and mobile; foreground latency, database batch time, memory, CPU, and disk I/O for large subtrees |@@ -488,7 +490,7 @@ Retain `TestHeadingDocParagraph` and `TestHeadingDocParagraphTextMark` so foundaActual HTTP regressions verify strict request types, required fields versus `null`, result ordering, truncated candidates, error data, administrator and writable access, encrypted response leases, and published-visitor rejection. Assert old compatibility behavior separately from new endpoints instead of replacing legacy expectations. Frontend tests cover old template configuration round-trips, new segment evaluation, one time snapshot, partial-success presentation, and mobile entry points.-Fault injection covers at least the boundaries before and after source persistence, before and after metadata transactions, interrupted content-index batches, lost success responses, and locking during response serialization. Use real fixtures from supported historical formats for reads, export, history, backup, and recovery, and verify safe rejection of new formats by the protective release. Testing only files generated by the current version does not establish backward compatibility.+Fault injection covers at least the boundaries before and after source persistence, before and after metadata transactions, interrupted content-index batches, lost success responses, and locking during response serialization. Use real fixtures from supported historical formats for reads, export, history, backup, and recovery, and verify rejection of unsupported formats with limited-reader regressions. These regressions do not make older released clients safe to mix with upgraded data. Testing only files generated by the current version does not establish backward compatibility.### Performance and resources@@ -502,7 +504,7 @@ Reports explain changes relative to the baseline. Duration depends on hardware,Behavior tests enter existing frontend and kernel discovery; new Go contract tests retain `Contract` in their names. After API implementation, run `pnpm run api:generate --petal ../../petal`, `pnpm run api:check --petal ../../petal`, `pnpm run lint`, and relevant frontend tests from `app/`. From `kernel/`, run `go test ./apicontract/...` and regressions covering affected APIs, models, filesystem, block-tree, and SQL behavior. Before release, existing complete test entry points cover `pnpm test` and `go test -tags "fts5 sqlcipher" ./... -count=1`.-CI runs `go test -tags "fts5 sqlcipher" ./documentaddressing ./filesys ./model ./api ./cli/cmd -run '^TestStructuredTitles' -count=1` with ordinary build defaults for automatic migration, structured source reads and writes, and actual HTTP contracts, without injecting a test version. Explicit compatibility fixtures cover old-reader mode rejection, while ordinary builds continue verifying rejection of unknown future modes and source formats. These complete acceptance requirements do not claim all checks have run. Documentation changes additionally verify bilingual consistency, examples, links, and diff formatting.+CI runs `go test -tags "fts5 sqlcipher" ./documentaddressing ./filesys ./model ./api ./cli/cmd -run '^TestStructuredTitles' -count=1` with ordinary build defaults for automatic migration, structured source reads and writes, and actual HTTP contracts, without injecting a test version. Explicit compatibility fixtures cover limited-reader mode rejection, while ordinary builds continue verifying rejection of unknown future modes and source formats. Local mode `1` overlays test that limited-reader boundary without changing ordinary build defaults or creating a transitional-release requirement. These complete acceptance requirements do not claim all checks have run. Documentation changes additionally verify bilingual consistency, examples, links, and diff formatting.## Related codediff --git a/docs/DOCUMENT-ADDRESSING.zh-CN.md b/docs/DOCUMENT-ADDRESSING.zh-CN.mdindex 5ede984dcf..1af218d050 100644--- a/docs/DOCUMENT-ADDRESSING.zh-CN.md+++ b/docs/DOCUMENT-ADDRESSING.zh-CN.md@@ -12,15 +12,15 @@创建计划采用固定 ID,已确认提交的祖先不会再次创建。桌面与移动端共用失败处理:响应不明或后续处理失败时保留计划,用户确认并按身份核对后才继续;关闭或锁定笔记本清除相应标题和模板缓存。本地速记使用仅含身份和摘要的恢复记录,核对实际源中的块身份后才清理输入,未确认的结果保留原速记并停止自动重放。-管理员读取笔记本配置时可获取 `documentCapabilities`,区分结构化接口、实际寻址模式和索引状态。未验证真实保护版本时,`minimumReaderVersion` 返回 `null`,不会伪造最低版本;能力记录损坏时明确报错。原生整本导入会同步重映射目标配置中的笔记本和锚点 ID,部分文档导入保留目标笔记本配置。加密目标载荷保持锁定保存、改密及备份恢复的认证边界。+管理员读取笔记本配置时可获取 `documentCapabilities`,区分结构化接口、实际寻址模式和索引状态。未登记经真实发行包验证的最低可读功能版本时,`minimumReaderVersion` 返回 `null`,不会伪造最低版本,也不表示允许与旧版混用;能力记录损坏时明确报错。原生整本导入会同步重映射目标配置中的笔记本和锚点 ID,部分文档导入保留目标笔记本配置。加密目标载荷保持锁定保存、改密及备份恢复的认证边界。-结构化标题功能版本默认采用模式 `2`,不提供用户开关或手动启用接口。开发分支已实现自动模式迁移与中断恢复、`DocumentTitleSpec = "6"`、标题斜杠读写及旧字符串接口的整本拒绝;前端通过只读运行时能力决定标题输入规则。普通构建默认采用模式 `2`,无需额外编译参数。`minimumReaderVersion` 仅报告经验证的兼容版本,留空不阻止新模式启用。真实保护版本、混合版本、性能及各端验收仍是发布前需要补齐的证据,不能由默认启用推断已经完成。行级标题扩展约束保持不变。+结构化标题功能版本默认采用模式 `2`,不提供用户开关或手动启用接口。开发分支已实现自动模式迁移与中断恢复、`DocumentTitleSpec = "6"`、标题斜杠读写及旧字符串接口的整本拒绝;前端通过只读运行时能力决定标题输入规则。普通构建默认采用模式 `2`,无需额外编译参数。发布采用所有设备统一升级、不与旧版混用的策略,不再要求先发布单独的过渡保护版本。`minimumReaderVersion` 仅报告经验证的兼容版本,留空不阻止新模式启用。功能版本的发行包核对、旧数据兼容、性能及各端验收仍按实际验证结果记录,不能由默认启用推断已经完成。行级标题扩展约束保持不变。## 目标与范围文档使用 ID 确定身份和所属层级,标题用于表达内容,可读路径用于展示。创建、移动和引用不得依赖从展示文本反向解析文档身份。完成相关入口迁移与兼容验证后,文档标题可以包含半角斜杠 `/`,并与原有全角斜杠 `/` 保持区别。-未来文档标题支持行级元素是本方案必须保留的扩展能力。寻址、标题显示、纯文本提取和存储表示必须分离,不能将标题永久限定为一个供所有模块直接解释的纯文本字符串。本次不定义完整的富文本标题格式、编辑器交互或元素支持清单。行级标题与双向转换、笔记本名称保留 `/`,以及第三方插件实际版本的适配验证由 #20837 继续跟踪;旧客户端保护与本轮发布验收仍属于 #19938。+未来文档标题支持行级元素是本方案必须保留的扩展能力。寻址、标题显示、纯文本提取和存储表示必须分离,不能将标题永久限定为一个供所有模块直接解释的纯文本字符串。本次不定义完整的富文本标题格式、编辑器交互或元素支持清单。行级标题与双向转换、笔记本名称保留 `/`,以及第三方插件实际版本的适配验证由 #20837 继续跟踪;Spec 与笔记本模式检查、统一升级说明及本轮功能验收仍属于 #19938。方案覆盖桌面端、浏览器端、移动端、内核接口和插件可见数据,并遵守普通笔记本与加密笔记本各自的访问边界。笔记本名称作为独立显示字段参与路径展示;笔记本名称的字符限制与富文本支持需要单独评估配置格式和旧客户端兼容,不能由文档标题规则自动推导。@@ -35,7 +35,7 @@| 可读路径 | 保留标题原文并按层级拼接展示;不编码 `/`,不把 `/` 或 `%2F` 解码 || 索引 | 保留现有 `hpath` 列,新增文档级内部元数据;不为每个内容块保存完整标题段数组 || 标题源 | 首版继续使用普通标题;预留带版本的行级内容及单向纯文本派生 |-| 发布顺序 | 兼容保护和结构化能力先发布,完成迁移验证后开放 `/`,富文本标题单独实现 |+| 发布策略 | 直接发布默认支持 `/` 的功能版本;同一份数据的所有客户端统一升级,不与旧版混用;富文本标题单独实现 |兼容边界按笔记本划定,避免根据某次请求猜测调用者的标题意图。例如 `/A/B` 可以指两级文档,也可能是单个标题的展示结果,旧请求没有足够信息区分两者。结构化标题模式启用后,该笔记本内即使某篇文档仍使用普通标题,旧字符串寻址入口也会返回明确错误;按 ID 操作和普通文字展示继续可用。这是插件需要适配的明确范围,不承诺所有旧插件零修改运行。@@ -181,7 +181,7 @@模式 `1` 的旧业务入口及旧字符串模板保留既有同名选择和 `parentID` 回退行为;内部实现改用身份后仍须通过旧行为回归,不能因共享严格解析器而悄悄改成歧义错误。新结构化接口在两个模式中均执行严格歧义检查。模式 `2` 的内置业务使用严格计划,即使输入来自旧模板也不得任取同名父文档;功能版本的迁移说明须说明这一行为变化。跨笔记本目标使用新协议时同样保持严格规则,不因目标为模式 `1` 而恢复任取行为。-新配置分别使用 `docCreateTarget`、`refCreateTarget`、`dailyNoteTarget`,与原保存路径字符串字段并存。功能版本在自动迁移为模式 `2` 的笔记本配置中开放这三个对象,全局配置继续保留旧字符串模板及现有继承规则,保持与保护版本兼容。对象必须带 `version: 2`,指定目标笔记本、起点、向上层数、祖先段、最终标题和缺失祖先策略;各段继续复用现有保存路径模板求值器。示例中的 `{{now | date ...}}` 是保存路径模板语法,不能与正文模板语法混淆。+新配置分别使用 `docCreateTarget`、`refCreateTarget`、`dailyNoteTarget`,与原保存路径字符串字段并存。功能版本在自动迁移为模式 `2` 的笔记本配置中开放这三个对象,全局配置继续保留旧字符串模板及现有继承规则,保留已有配置语义。对象必须带 `version: 2`,指定目标笔记本、起点、向上层数、祖先段、最终标题和缺失祖先策略;各段继续复用现有保存路径模板求值器。示例中的 `{{now | date ...}}` 是保存路径模板语法,不能与正文模板语法混淆。```json{@@ -333,7 +333,7 @@### 能力探测与自动迁移-在 `/api/notebook/getNotebookConf` 的 `data` 中增加可选只读对象 `documentCapabilities`,保留现有 `box`、`name`、`conf` 和权限过滤。对象包含 `addressingVersion`、`modeState`、`structuredPaths`、`literalSlash`、`titleFormats`、`indexState`、`minimumReaderVersion` 和 `revision`。`modeState` 为 `legacy`、`structured`、`conflict` 或 `recovering`;`structuredPaths` 表示服务端实现了新协议,`indexState` 表示派生索引状态,均不代替模式状态。管理员响应包含该对象,其他角色保持原有配置过滤。保护版本尚未验证时 `minimumReaderVersion` 为 `null`;确认真实最低版本后才返回版本字符串,该字段不控制功能是否启用。首版 `titleFormats` 为 `["plain"]`,`literalSlash` 仅在模式 `2`、`modeState: "structured"` 且索引就绪时为 `true`。+在 `/api/notebook/getNotebookConf` 的 `data` 中增加可选只读对象 `documentCapabilities`,保留现有 `box`、`name`、`conf` 和权限过滤。对象包含 `addressingVersion`、`modeState`、`structuredPaths`、`literalSlash`、`titleFormats`、`indexState`、`minimumReaderVersion` 和 `revision`。`modeState` 为 `legacy`、`structured`、`conflict` 或 `recovering`;`structuredPaths` 表示服务端实现了新协议,`indexState` 表示派生索引状态,均不代替模式状态。管理员响应包含该对象,其他角色保持原有配置过滤。未登记经真实发行包验证的最低可读功能版本时 `minimumReaderVersion` 为 `null`;该字段只提供版本信息,不控制功能是否启用,也不授予旧版混用能力。首版 `titleFormats` 为 `["plain"]`,`literalSlash` 仅在模式 `2`、`modeState: "structured"` 且索引就绪时为 `true`。`revision` 是模式记录及恢复状态的版本摘要,不等同于某篇文档的路径版本,也不用于用户启用流程。能力声明不授予访问权限,关闭或锁定笔记本时仍执行原有访问限制;状态读取不得暴露标题或受保护的模板内容。旧服务端没有该对象时,插件只能使用旧能力。鉴权、锁定或网络请求失败不能被当作“服务端不支持”,更不能据此回退后继续写入。@@ -345,7 +345,7 @@## 接口与插件兼容-模式 `1` 为保护版本使用的兼容模式;模式 `2` 为功能版本自动采用的结构化标题模式。旧笔记本记录缺失且没有更高能力记录时,其源记录按 `1` 解释,功能版本在源访问前自动迁移到 `2`;缺省字段不能覆盖已有能力下界。模式决定旧协议是否可用,不根据某一次请求是否恰好包含 `/` 猜测。+模式 `1` 为旧规则的兼容模式;模式 `2` 为功能版本自动采用的结构化标题模式。旧笔记本记录缺失且没有更高能力记录时,其源记录按 `1` 解释,功能版本在源访问前自动迁移到 `2`;缺省字段不能覆盖已有能力下界。模式决定旧协议是否可用,不根据某一次请求是否恰好包含 `/` 猜测。保留模式 `1` 的读取和回归覆盖用于旧数据兼容,不表示计划发布单独的过渡版本。| 使用场景 | 兼容模式 `1` | 结构化标题模式 `2` | 插件迁移方式 || --- | --- | --- | --- |@@ -370,11 +370,13 @@## 版本、加密与恢复-### 混合版本访问+### 统一升级与旧版混用风险笔记本配置保存内部兼容标记 `documentAddressingVersion`:字段缺省或 `1` 表示兼容记录,`2` 表示结构化标题记录;有效模式还须结合后文的能力下界与恢复记录,不能只读取这个字段。该标记不是用户配置项,与加密信封版本独立,不能复用 `BoxCrypt.Spec`。功能版本自动迁移记录,不批量改写已有文档标题或 ID。-即使 `.sy` 仍保存字符串标题,旧客户端也可能移除 `/`,或把标题文字当作层级。对外发布的兼容要求分两步:先发布理解笔记本能力及恢复标记、能够安全拒绝未知模式的保护版本,再发布默认采用模式 `2` 的功能版本。开发分支普通构建已默认采用模式 `2`,这一默认值不依赖最低版本元数据。保护版本在挂载、索引、修复、编辑及同步应用入口拒绝处理不支持的模式,不能先修改数据再提示升级。+直接发布默认采用模式 `2` 的功能版本,不单独发布过渡保护版本,也不支持新旧客户端共同访问同一工作空间或同步数据。升级前停止所有相关客户端的使用和同步,将全部设备统一升级到支持模式 `2` 与 Spec 6 的功能版本后,再恢复访问和同步;离线设备也必须先升级,不能稍后用旧版上线。普通构建默认采用模式 `2`,这一默认值不依赖最低版本元数据。当前实现继续在挂载、索引、修复、编辑及同步应用入口检查笔记本模式和源格式,拒绝不支持的能力,不能先修改数据再提示升级。++混用的后果不限于旧版打不开文档。具有规格检查的旧版可能拒绝 Spec 6 文档,却继续读写同一本中保留旧 Spec 的文档;未识别新模式的旧版还可能按旧规则清理标题中的 `/` 或把标题文字当作层级。已经打开的旧编辑页面可能将缓存快照写回,覆盖新版保存的标题或正文;这些错误改动还可能经同步传播到其他设备,造成修改丢失、标题或路径异常,并需要从历史或备份恢复。不能以某篇旧 Spec 文档仍可打开来判断混用安全,也不能将拒绝读取部分文档等同于整个笔记本受到保护。真正使用新标题能力的文档采用 `DocumentTitleSpec = "6"`:标题包含 ASCII `/` 时,正常写入将文档 `Spec` 至少提升到 `6`。普通标题仍按正文所需规格保存,不能因升级客户端、迁移模式或普通格式化而全部提升到 `6`,也不降低已有版本。未来富文本表示还需对应的明确格式版本,未知内容不得被容错解析后覆盖。@@ -386,9 +388,9 @@原始文件接口中的笔记本及文档 ID 路径同样受源格式检查保护,不能通过上传、复制或移入文件绕过。整批预检在创建目标目录及首次复制前完成,实际文档复制使用已经校验的读取字节,并在文件锁内重新检查目标源;检查后的并发变化或 I/O 失败仍可能留下已完成的复制,不承诺整批回滚。普通附件和插件目录下的 `.sy` 文件保持原始文件语义,加密笔记本仍禁止通过原始文件接口读写。-最低兼容版本由真实发布版本的读写及拒绝测试确定。保护版本之前忽略能力标记的客户端无法由新字段自动约束,不在安全混用承诺内。使用功能版本前要求所有同步设备至少升级到保护版本;系统无法证明离线设备状态,发布说明及用户指南须说明这一限制。如果保护仍存在缺口,不能宣称已达到对外发布或安全混用条件,也不能以文档提示或用户开关代替必要保护。+兼容判定依据为文档 Spec 和笔记本有效模式,两者均须在相关读写、同步与恢复入口执行;不混用旧版不构成删除这些检查的理由。已发布且忽略模式标记或缺少写入前检查的旧客户端,无法被新增字段追溯约束,系统也无法证明离线设备已经升级。发布说明及用户指南必须明确全设备统一升级和混用可能损坏数据的后果,不承诺旧版一定被安全拦截。`minimumReaderVersion` 如需登记,须以实际功能发行包的读写与兼容测试为依据;暂为 `null` 不表示支持旧客户端,也不再以过渡保护版本发布或登记其版本号作为本议题关闭条件。-已发布 `v3.8.9-alpha.4` 源码的隔离验证表明:它拒绝直接读取 Spec 6 文档,但仍可能读取模式 `2` 中保留旧规格的文档,或将旧编辑快照写回。因此,该版本不能登记为已验证的保护版本,也不能概括为“旧版本一定无法打开”。本地保护候选构建及其回归只证明相应源码的行为,不代替真实发行包验证;实际保护版本发布后,须核对发行包、源码与构建能力,再验证普通及加密数据的兼容读取、模式拒绝、旧缓存写入、同步和恢复,才登记 `minimumReaderVersion` 并完成本议题的发布验收。+已发布 `v3.8.9-alpha.4` 源码的隔离验证表明:它拒绝直接读取 Spec 6 文档,但仍能读取模式 `2` 中保留旧规格的文档,并将旧编辑快照写回。这些已验证行为说明不能概括为“旧版本一定无法打开”;标题清理、层级误解及错误同步传播是混用风险,不能将其写成该探针已逐项验证的结果。本地临时模式 `1` 构建及回归用于验证能力受限读取器的拒绝行为,不代表一个已发布或必须发布的过渡版本。功能版本仍需遵守常规发行包核对与发布验证,维护者负责发布。自动迁移到模式 `2` 后不提供改回 `1` 的开关。即使当前标题已不含 `/`,历史和备份仍可能包含新格式。回退客户端只能使用经验证的兼容导出副本,或恢复升级前的完整备份到独立工作空间;不能将旧配置覆盖回原工作空间并继续同步。若未来提供降级转换,应另行设计转换清单、冲突处理和恢复机制,保留原数据。@@ -400,13 +402,13 @@设置导出仍为包含一个 JSON 文件的压缩包,有已确认的能力下界时,在该 JSON 顶层附加 `documentAddressing`,内容与本机记录同构。导入在采用普通设置之前校验并逐身份合并最高要求;旧设置缺少此字段时不清除本机记录,损坏或未知版本在采用设置前报错。该字段只用于备份传递,恢复后仍独立保存在 `conf/document-addressing.json`,不写入普通 `conf.json`,也不包含标题、正文或密钥。原始文件接口不得直接覆盖、重命名或删除本机记录;笔记本写入及复制须预检待写配置和整批目标,排序恢复须保留不支持模式的原文件及恢复记录。-保护版本同时识别配置及能力下界记录;不支持的模式在实际处理源文件前拒绝。同步应用和快照恢复先核对受影响笔记本的能力要求,再替换配置或文件。已确认模式 `2` 时,传入旧配置、缺少新字段或删除能力记录都不能降低有效模式;恢复配置投影和下界记录后再开放访问。若只能在文件落盘后检查,或依赖层不能在应用前提供所需配置数据,阶段 A 尚未完成,须先补齐同步和恢复入口,不能以重建索引代替前置保护。+模式检查同时识别配置及能力下界记录;不支持的模式在实际处理源文件前拒绝。同步应用和快照恢复先核对受影响笔记本的能力要求,再替换配置或文件。已确认模式 `2` 时,传入旧配置、缺少新字段或删除能力记录都不能降低有效模式;恢复配置投影和下界记录后再开放访问。若只能在文件落盘后检查,或依赖层不能在应用前提供所需配置数据,阶段 A 尚未完成,须先补齐同步和恢复入口,不能以重建索引代替前置保护。模式标记不能代替文档源检查。同步和快照恢复在整批文件写入或删除前,检查待应用的普通文档源,并拒绝以旧快照覆盖或部分删除预检时已确认使用不支持规格、标题表示或标题能力的现存源;即使来源缺少模式标记,也不能先落盘再依赖索引发现错误。该检查沿用现有恢复过程,不将普通快照恢复变为可隔离任意外部文件修改的原子事务。合法历史源仍可恢复一般损坏的普通文档,整本删除保留既有语义,附件及插件目录中的 `.sy` 不解释为文档。锁定加密笔记本仍按既有协议传输原始密文字节,不为标题预检要求解锁,也不把仓库分块校验当作笔记本内容认证;密文的认证及源格式检查继续在原有受保护读取和恢复边界内完成。删除整个笔记本仍按现有语义执行,不为补齐能力记录而重新创建已删除的笔记本;本机保留该身份的已确认下界,恢复同一身份时继续生效。完整笔记本的原生导入先校验源身份与能力记录,再按既有导入规则分配或复用目标身份,并将能力下界绑定到目标身份;不得借身份重映射降低源笔记本已确认的模式。向既有笔记本导入部分文档则按前述完整操作集合检查,不直接复制源笔记本的模式配置。-自动迁移先在 `conf/document-addressing-recovery/<notebookID>.json` 持久化 `{version: 1, notebook, phase: "records"}`,再依次写入本机下界、笔记本下界及配置中的模式标记,最后删除该恢复记录。任一步骤中断后,下次访问继续同一迁移,不撤回已写入的模式要求;保护版本也必须将有效恢复记录视为至少需要模式 `2`。配置的未知字段及加密载荷原值保留,不扫描或批量重写 `.sy` 文件,原始文件接口不能覆盖该恢复目录。+自动迁移先在 `conf/document-addressing-recovery/<notebookID>.json` 持久化 `{version: 1, notebook, phase: "records"}`,再依次写入本机下界、笔记本下界及配置中的模式标记,最后删除该恢复记录。任一步骤中断后,下次访问继续同一迁移,不撤回已写入的模式要求;模式检查必须将有效恢复记录视为至少需要模式 `2`。配置的未知字段及加密载荷原值保留,不扫描或批量重写 `.sy` 文件,原始文件接口不能覆盖该恢复目录。普通构建在已有模式记录缺失或配置落后时自动补齐,已删除的笔记本不能因恢复而重建。已有笔记本的配置文件缺失时,仅保留已确认模式,不生成替代配置;加密备份恢复仍须认证原密钥及载荷,不能保存为普通笔记本。配置恢复前能力状态保持 `recovering`。模式迁移与索引重建分开:元数据迁移不依赖就绪索引,也不认证或改写文档密文;后续源读取和索引构建仍必须在原授权及加密租约内先认证源内容。只有模式记录一致且索引就绪时才对外报告 `modeState: "structured"`。@@ -440,17 +442,17 @@| 阶段 | 交付内容 | 完成条件 || --- | --- | --- |-| A:兼容保护 | 笔记本能力下界及冲突识别、未知模式及源版本保护、旧行为回归样本 | 已发布保护版本;同步及快照应用前验证模式,所有写入与修复入口安全拒绝未知模式 |+| A:兼容保护 | 笔记本能力下界及冲突识别、未知模式及源版本保护、旧行为回归样本 | 同步及快照应用前验证模式和来源,所有写入与修复入口安全拒绝不支持的模式或规格;不要求单独发布保护版本 || B:内部解耦 | 统一标题读取、文档元数据、ID 层级计算、路径刷新及恢复 | 普通标题行为不变;结构不再从显示字符串推导,加密索引可认证重建 || C:接口与调用方 | 新读取、解析、条件创建接口,版本 `2` 模板及加密载荷,内置业务及各端迁移 | 名称与配置并发条件、新旧契约通过验证,部分失败及撤销可恢复,日记等业务行为保持 || D:开放新字符 | 默认采用新模式及自动恢复、旧接口拒绝规则、插件迁移说明、跨模式操作及导入导出验证 | 普通构建默认支持 `/`;完整子树预检、模式恢复及全部发布条件通过后才完成对外发布验收 || E:行级标题 | 独立的源格式、编辑及渲染设计 | 保持本方案身份接口,完成格式及旧写入保护后另行交付 |-阶段 B、C 可以在保留旧标题限制时先行交付;开发分支已默认开放新字符,对外发布验收仍要求 A 至 D 的相关条件全部成立。阶段 E 不作为基础解耦的前置依赖,也不能在 A 至 D 中重新引入只接受永久纯文本来源的假设。+阶段 A 至 D 为同一功能版本的实现与验证拆分,不要求先交付单独的模式 `1` 版本;开发分支已默认开放新字符,对外发布验收仍要求 A 至 D 的相关条件全部成立。阶段 E 不作为基础解耦的前置依赖,也不能在 A 至 D 中重新引入只接受永久纯文本来源的假设。-开放条件包括:所有内置消费者已迁移;替代接口和插件适配文档已发布;已验证最低客户端版本及混合版本拒绝;普通与加密索引迁移可中断恢复;导入导出不会因显示路径冲突覆盖文件;桌面、浏览器和移动端行为一致;四种语言的用户指南说明默认行为、插件影响和同步设备要求。+开放条件包括:所有内置消费者已迁移;替代接口和插件适配文档已发布;当前实现的 Spec、模式及写入前拒绝检查通过验证;普通与加密索引迁移可中断恢复;导入导出不会因显示路径冲突覆盖文件;桌面、浏览器和移动端行为一致;四种语言的用户指南说明默认行为、插件影响、全部设备统一升级及混用后果。对旧数据及旧协议的回归不构成与旧客户端混用的支持承诺。-实施已分配 `.sy` 规格 `6`;发布前仍需登记实际保护版本号,并附上性能测量与兼容测试结果。这些是发布证据,不是重新悬置身份、模板、插件边界或失败语义的决策。不能以完成文档、通过隔离测试或一次索引重建代替全部功能验收。+实施已分配 `.sy` 规格 `6`;功能版本发布时附上已有性能测量与兼容测试结果,并如实说明验证限制。不再以先发布保护版本或登记其版本号作为本议题的验收前置条件,`minimumReaderVersion` 保留为经实际发行包验证后登记的信息字段。这些是发布证据,不是重新悬置身份、模板、插件边界或失败语义的决策。不能以完成文档、通过隔离测试或一次索引重建代替全部功能验收。## 验证与验收@@ -466,7 +468,7 @@| 索引与恢复 | 深层子树、父子连续重命名、旧编辑快照、批次中断、重启、移动、删除、同步及普通与加密索引迁移 || 导入导出及跨模式操作 | 重名、非法文件名、大小写冲突、路径越界、相对链接、跨笔记本引用、标题元数据及无损往返承诺;移动、复制和恢复预检全部后代,拒绝时不产生部分写入 || 旧接口与插件 | 模式 `1` 旧返回不变;模式 `2` 整个笔记本拒绝旧寻址;两个旧目标读取接口拒绝失效配置,即使旧目标仍为模式 `1`;SQL 显示字符串碰撞、结构化替代接口、能力缺失与请求失败的区别 |-| 旧客户端与加密 | 支持的历史格式及配置载荷样本、混合版本同步、能力下界不降级、无就绪索引的模式冲突恢复、认证失败、锁定期间的缓存和响应、历史及备份恢复、密钥材料保留 |+| 旧数据兼容与加密 | 支持的历史格式及配置载荷样本、旧同步来源的预检与拒绝、能力下界不降级、无就绪索引的模式冲突恢复、认证失败、锁定期间的缓存和响应、历史及备份恢复、密钥材料保留;不承诺新旧客户端混用 || 行级元素扩展 | 现有 Markdown 样式文字保持字面含义;标题表示变化不影响身份与层级;纯文本相同不合并文档;格式与纯文本来源单向派生;#19235 的图片及链接双向转换保留、资源引用和防重复要求 || 跨端与性能 | 桌面、浏览器和移动端创建及重命名;大子树下的前台延迟、数据库批次时间、内存、CPU 和磁盘读写 |@@ -488,7 +490,7 @@实际 HTTP 回归检查严格请求类型、必填与 `null` 区别、返回顺序、候选截断、错误数据、管理员与可写保护、加密响应租约及发布访问拒绝。旧接口的兼容回归与新接口回归分开断言,避免用新预期覆盖旧行为。前端验证旧模板配置往返、新模板逐段求值、同一时间快照、部分成功提示以及移动端入口。-故障注入至少覆盖源文档落盘前后、元数据事务前后、内容索引批次中断、成功响应丢失及锁定发生在响应输出期间。使用受支持历史格式的真实样本验证读取、导出、历史、备份及恢复,同时验证保护版本安全拒绝新格式;仅测试当前版本生成的文件不能证明向后兼容。+故障注入至少覆盖源文档落盘前后、元数据事务前后、内容索引批次中断、成功响应丢失及锁定发生在响应输出期间。使用受支持历史格式的真实样本验证读取、导出、历史、备份及恢复,同时验证能力受限读取器拒绝不支持的模式和格式;仅测试当前版本生成的文件不能证明向后兼容。受限读取器回归用于验证检查边界,不要求发布该读取器,也不承诺任意历史客户端具备相同保护。### 性能与资源@@ -502,7 +504,7 @@行为测试进入现有前端及内核测试发现范围;新 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`。-持续集成直接以普通构建运行 `go test -tags "fts5 sqlcipher" ./documentaddressing ./filesys ./model ./api ./cli/cmd -run '^TestStructuredTitles' -count=1`,覆盖自动迁移、新模式读写及真实 HTTP 契约,不再注入测试版本号。旧读取器的模式拒绝由显式兼容测试夹具覆盖,未知未来模式与源格式的拒绝继续在默认构建中验证。以上完整验收要求不等于已全部执行,文档修改另检查双语一致性、示例、链接及差异格式。+持续集成直接以普通构建运行 `go test -tags "fts5 sqlcipher" ./documentaddressing ./filesys ./model ./api ./cli/cmd -run '^TestStructuredTitles' -count=1`,覆盖自动迁移、新模式读写及真实 HTTP 契约,不再注入测试版本号。能力受限读取器的模式拒绝由显式兼容测试夹具覆盖,未知未来模式与源格式的拒绝继续在默认构建中验证。本地模式 `1` 临时覆盖构建验证受限读取器的检查边界,不改变普通构建默认值,也不要求发布过渡版本。以上完整验收要求不等于已全部执行,文档修改另检查双语一致性、示例、链接及差异格式。## 相关代码diff --git a/kernel/apicontract/contracts.go b/kernel/apicontract/contracts.goindex 05804dec3d..64383b9bfd 100644--- a/kernel/apicontract/contracts.go+++ b/kernel/apicontract/contracts.go@@ -136,8 +136,8 @@ var (// responses also contain documentCapabilities: structuredPaths advertises the ID/segment APIs,// not permission to open a closed or locked notebook. Ordinary builds migrate to mode 2// automatically without a user setting or special build flags. literalSlash requires consistent- // mode records and ready indexes. minimumReaderVersion remains null while protective-release- // verification is pending; this informational field does not control feature activation.+ // mode records and ready indexes. minimumReaderVersion stays null until the minimum compatible+ // feature release is verified; it neither controls activation nor permits mixing with older clients.// Revision covers configuration, confirmed capability and recovery records, not a document path.// Malformed capability records fail the request; authentication, locking and network failures must// never be interpreted as an absent capability object or as permission to retry a legacy write.@@ -1075,7 +1075,7 @@ var GetDocPaths = define[GetDocPathsRequest, DocumentPathsResult]("getDocPaths",// 标题不作 Unicode 归一化、宽窄转换或百分号解码;同父同名返回 ambiguous,不任取候选。// candidates 按 ID 排序且最多 128 项,candidatesTruncated 标记截断;nameConditions 保留唯一及缺失条件。// 空段数组返回起点,根位置的 resolved 为 null,start.id 为 null;笔记本文档 ID 规范化为逻辑根。-// 索引未就绪返回 indexUnavailable;功能版本默认保留段内 /,保护版本仍遵守兼容模式限制。+// 索引未就绪返回 indexUnavailable;普通构建默认保留段内 /,内部兼容模式 1 仍遵守原有标题限制。var ResolveDocPath = define[ResolveDocPathRequest, ResolveDocPathResult]("resolveDocPath", "/api/filetree/resolveDocPath", AuthenticatedAccess|AdminAccess, JSONBody, ResponseOptions{DataOnError: true}, "POST")// CreateDocByParent 在显式父文档 ID 或 null 根位置创建固定 ID 文档,不接收 path/hPath 或名称回退。@@ -1083,7 +1083,7 @@ var ResolveDocPath = define[ResolveDocPathRequest, ResolveDocPathResult]("resolv// 可选父路径 revision 与至多 128 项名称条件在源提交前分别校验;条件只能涉及目标祖先和最终父级。// ID 冲突不覆盖、不自动更换;错误 data 包含稳定 reason、commitState、阶段及已完成步骤。// 已落盘但排序或正文模板失败时保留源文档并返回其 ID,调用方不得把该错误当作未创建而重复提交。-// 功能版本默认保留标题中的 /,该文档写入 Spec 6;普通文档不因迁移统一升级,保护版本仍拒绝 /。+// 普通构建默认保留标题中的 /,该文档写入 Spec 6;普通文档不因迁移统一升级,内部兼容模式 1 仍拒绝 /。// 加密笔记本使用原有认证写入与响应租约;自动模式迁移不改变密文格式或密钥材料。var CreateDocByParent = define[CreateDocByParentRequest, CreateDocByParentResult]("createDocByParent", "/api/filetree/createDocByParent", AuthenticatedAccess|AdminAccess|WritableAccess, StructJSONBody, ResponseOptions{DataOnError: true}, "POST")