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: Expand document addressing design https://github.com/siyuan-note/siyuan/issues/19938
Daniele74538d582c5
diff --git a/docs/DOCUMENT-ADDRESSING.md b/docs/DOCUMENT-ADDRESSING.mdindex 75b5f93aaa..8902dcee00 100644--- a/docs/DOCUMENT-ADDRESSING.md+++ b/docs/DOCUMENT-ADDRESSING.md@@ -4,7 +4,7 @@Related issue: [Improve hPath by separating display text from document addressing](https://github.com/siyuan-note/siyuan/issues/19938)-This design draft defines the responsibilities of document titles, hierarchy resolution, and readable paths, together with compatibility requirements for enabling new title capabilities. The target behavior is not fully implemented. See [Document rename and path indexes](DOCUMENT-HPATH.md) (Chinese) for the current rename and index update mechanism.+This is an implementation design draft defining document titles, hierarchy addressing, readable paths, APIs, and migration behavior. The new fields, endpoints, and version mechanisms below are proposed contracts, not capabilities already supported by the current release. See [Document rename and path indexes](DOCUMENT-HPATH.md) (Chinese) for the current rename and index update mechanism.## Goals and scope@@ -14,6 +14,23 @@ Future support for inline elements in document titles is a required extension caThe 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.+### Design decisions++| Area | Selected approach |+| --- | --- |+| Document addressing | Notebook and document IDs; creation takes a parent identity and a separate title |+| Compatibility modes | Explicitly enable structured title mode per notebook; existing notebooks default to compatibility mode |+| Plugins | Accept adaptation of plugins that depend on legacy `hPath` rules; deliver replacement APIs and migration guidance before enabling new characters |+| Legacy string addressing | Preserve existing behavior in compatibility mode; reject legacy string lookup and creation in structured title mode |+| 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 |++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.++The foundational separation requires no new external service, network transmission, or dependency. Implementation continues under the repository's and existing dependencies' licenses; selecting a new dependency later requires its own license review. The main costs are consumer migration, index rebuilding, and cross-version verification. Title and ancestor caches, logs, and errors remain subject to encrypted-notebook boundaries; structured fields must not expand data visibility.+## Titles, identity, and paths### Current data sources@@ -36,7 +53,7 @@ The names below describe concepts rather than prescribe new API or storage field| Structured ancestor chain | Document IDs and corresponding title information in hierarchy order | Preserves segment boundaries; keeps notebook names separate; never reconstructed from display strings || Title segment array | Input for matching or creating documents level by level from an explicit location | Removes delimiter ambiguity, but does not make names unique || Readable path | Presentation for breadcrumbs, tooltips, or copied paths | May have different display forms; does not provide addressing or source recovery |-| Legacy path protocol | Existing `hPath`, `hpath`, and related fields used by APIs and plugins | Maintained through compatibility adapters; field semantics cannot be replaced in place |+| Legacy path protocol | Existing `hPath`, `hpath`, and related fields used by APIs and plugins | Preserve existing behavior in compatibility mode; apply the explicit display and rejection rules below in structured title mode || Export relative path | File location assigned to a document by an export operation | Determined by an export mapping, separately from titles and UI paths |The current frontend search configuration's `idPath` is an array of search scope strings. Each entry can contain a notebook ID and a document ID path; it is not an array of successive IDs for one path. Migration must preserve the interpretation of existing configurations. Similarly, blocktree `parent_id` identifies a block node's parent and cannot be reused directly as a document's parent document ID.@@ -50,6 +67,34 @@ The following structures can both display as `/A/B`, but must retain different dBreadcrumbs should present boundaries using the structured hierarchy. A copied plain-text path is for reading; links and references used for navigation must carry IDs. Documents with the same title under the same parent are allowed, and matching title segments must not merge their identities.+### Title access and document metadata++The kernel establishes a shared title reader returning `format`, `text`, `empty`, and the source version. The first implementation supports only `format: "plain"`, reading IAL `title` and the existing `custom-sy-title-empty` attribute; the flag and stored title text remain distinct. Existing placeholder titles are not rewritten in bulk, and empty-title UI hints do not become new lookup keys. Future rich sources provide plain text through the same boundary without requiring addressing consumers to change.++Add an internal `document_metadata` table with one row per document to ordinary `blocktree.db` and each encrypted notebook's corresponding block-tree database. Keep the existing `blocktrees` column order unchanged to avoid changing existing scanners and plugin query layouts.++| Field | Meaning |+| --- | --- |+| `box_id`, `id` | Composite primary key: notebook ID and document ID |+| `parent_id` | Parent document ID, with SQL `NULL` for the logical root; distinct from block-node `parent_id` |+| `title_text`, `title_empty` | Text derived from the title source and its empty-title flag |+| `title_format`, `source_spec` | Title representation and source document version |+| `revision` | Version digest covering identity, location, title source, and empty-title state |++An index on `(box_id, parent_id, title_text, id)` supports exact name lookup under the current parent. Matching is case-sensitive on original Unicode text, without width conversion, percent decoding, or Unicode normalization; search retains its own tokenization and case rules. An empty title cannot automatically identify an unknown parent; use its ID.++`document_metadata` is a rebuildable internal index, not a new public SQL table contract. Addressing uses current metadata in the block-tree database; plugins obtain parent IDs, titles, and depth through structured reads. Document rows in the existing content database continue storing plain-text titles in `content` and readable path copies in `hpath`.++Update document metadata and the block-tree document row in the same database transaction. Creation, rename, move, deletion, copying, import, and sync rebuilds must update or remove the corresponding rows. Title caches are keyed by notebook and document identity and validated with version digests; same-named documents in another notebook are never substitutes.++### Structured path output++`DocumentPath` contains `notebook`, `id`, `parentID`, `path`, `title`, `segments`, `depth`, `displayPath`, `revision`, and `addressingVersion`. `title` is `{format, text, empty}`; `segments` contains `{id, text, empty}` entries from the root through the current document. `displayPath` starts with `/` and joins segments with `/`, displaying `/` for an empty array, for presentation only. The notebook name is returned separately or obtained by the caller, not inserted into the segment array. Here, `title` is a summary, not a complete copy of a future rich source that can be written back.++An ordinary root document has `depth: 1` and `parentID: null`. With notebook documents enabled, the notebook document has `depth: 0` and empty `segments`; ordinary root documents remain at level one, with no additional physical directory. Passing the notebook document ID as a creation parent is equivalent to the explicit root, retaining the existing logical-root mapping. Root child-name queries exclude the notebook document itself so it cannot be mistaken for an ordinary root document.++Path revisions use versioned serialization with unambiguous field boundaries, covering ancestor IDs, title revisions, and current location, not just second-resolution modification times. Direct creation by parent ID may follow the parent's current location. A caller requiring a preview to remain valid submits `expectedParentRevision`; ancestor renames or location changes invalidate it. Digests check consistency and do not grant access across authorization boundaries.+## Extension requirements for inline titlesTitle access must expose clear boundaries for source content, plain-text extraction, and presentation. The current implementation can continue storing ordinary strings, but addressing, depth calculations, creation target resolution, and filename allocation must not depend on the specific IAL string representation or pass title content to filesystem path normalization functions.@@ -60,6 +105,8 @@ The new format must specify one authoritative title source. A plain-text title rPlain-text extraction for rich titles needs rules for whitespace, line breaks, inline math, link text, empty titles, and length limits. Two titles differing only in style can produce the same plain text; IDs still distinguish identity and references. Search, sorting, and export filenames must not treat Markdown markup or rendered HTML as title text. Titles within exported content can preserve inline elements supported by the destination format.+Render ordinary titles as text through existing escaping or text-node mechanisms, not direct HTML concatenation enabled by new characters. Rich titles reuse validated nodes and renderers. The plain-text summary in `DocumentPath` and the editable source have separate read boundaries, with format-specific writes preventing presentation data from overwriting the source format.+Block references, dynamic anchor text, links, tags, and assets need additional rules for dependency updates, click behavior, reference and asset ownership, cycles, ID remapping during copying and import, and encryption boundaries. This design preserves representation space for those capabilities without committing to enabling every inline element at once. The later rich title implementation must also cover input methods, selection, undo, mobile interaction, history, sync, and export.Acceptance of this decoupling must establish that adding a title representation does not change addressing or hierarchy rules, that existing ordinary titles retain their literal content, and that consumers obtain titles through the defined access boundary instead of guessing title syntax independently.@@ -68,27 +115,80 @@ Acceptance of this decoupling must establish that adding a title representation### Creation by identity-When the parent document is known, a creation request should express the target notebook, parent document ID or root location, title, and body. Immediately before writing, the kernel resolves the data path from current identity and revalidates ownership, writability, parent validity, and the encrypted-notebook operation lease. A cross-notebook move can change ownership; a stale notebook parameter must fail rather than trigger a fallback lookup in another notebook.+When the parent document is known, a creation request expresses the target notebook, parent document ID or root location, separate title, and body. Immediately before writing, the kernel resolves the ID data path from current identity and revalidates ownership, writability, parent validity, and the encrypted-notebook operation lease. A cross-notebook move can change ownership; a stale notebook parameter must fail rather than trigger a fallback lookup in another notebook or a same-named document.-Renames, moves, deletion, or sync changes between a creation preview or template document-tree plan and its application must be detected using a version value or equivalent snapshot covering changes relevant to the plan. The operation must request a new preview or reject application. An unchanged document ID alone does not establish that the plan is still valid.+Direct creation without a preview revision follows the same parent's current location after a rename or a move within the notebook. Requests carrying `expectedParentRevision`, creation previews, and template document-tree plans validate the relevant title and location revisions, returning `planChanged` when they differ so the caller can preview again. The request distinguishes these behaviors; an unchanged document ID alone does not establish that a preview remains valid.++Parent resolution, final validation, and source-document commit must share mutation coordination with rename, move, and deletion so the parent cannot change location between validation and commit. Reuse the existing transaction queue and lock order; do not wait for the queue while holding a lock it needs to execute. Cancellation, notebook closure, and locking must not leave a stale operation lease usable.++Currently, `createDocWithMd` can fall back from `parentID` to name resolution when `hPath` does not match, and a regression test requires that behavior. The new protocol adds a separate strict parent-ID endpoint rather than changing the old parameter's meaning. Migrated internal consumers pass structured targets directly, never reassembling an `hPath` and passing it to the old parser.Ordinary creation, daily note reuse, and appending to an existing document are different operations. Callers must express whether a target may be reused instead of implicitly selecting a write target through a title search. Migration must retain template application, attribute writes, sorting, notifications, and synchronous persistence requirements. For example, shorthand workflows that remove source data after success must first confirm that the destination was written successfully.+### Title validation in the new protocol++The new creation endpoint requires an explicit `title: {format: "plain", text: string}`. An omitted `title`, `null`, or an unknown `format` is an error. `text: ""` means an empty title, retaining `custom-sy-title-empty` and the existing storage placeholder mechanism. Reads return both the actual plain text and `empty`; editors restore empty input from the flag instead of treating a localized placeholder as a user title.++The first implementation retains the limit of 512 Unicode code points and existing restrictions on invisible and private-use characters, preserving ZWJ needed by combined emoji. The new endpoint returns `invalidTitle` for excessive length, prohibited characters, and surrounding whitespace rather than silently truncating, trimming, or replacing them. A UI that deliberately cleans input shows the resulting title before submission. In compatibility mode the new endpoint rejects `/` and standalone `.` or `..`; structured title mode allows them as ordinary text. Existing legacy normalization behavior remains unchanged in compatibility mode.++Structured title mode performs no filesystem path cleaning, width conversion, percent decoding, or Unicode normalization. `/`, `/`, `%2F`, repeated slashes, and `A/../B` remain literal text; only parent identity determines hierarchy. Ordinary creation permits duplicate titles under the same parent, returning a new ID without implicitly overwriting or reusing an existing document.+### Resolution by title segments-Creating a hierarchy by name requires an explicit starting location and a title segment array. Use known ancestor identities directly; resolve unknown ancestors one level at a time under the current parent. Create an absent match according to the operation's rules. Multiple matches produce an ambiguity error and candidate identities within the authorized scope, never an arbitrary first match. Whether an ordinary creation's final segment permits a duplicate title is defined separately from reuse of an existing document.+Creating a hierarchy by name requires an explicit starting location and a title segment array. Use known ancestor identities directly; resolve unknown ancestors one level at a time under the current parent. Create an absent match according to the operation's rules. Multiple matches produce ambiguity and candidate identities within the authorized scope, never an arbitrary first match. The generic resolver does not search descendants across same-named parents to guess user intent.++A `/` within a structured title segment does not create another level, and `.` or `..` does not navigate. Moving up a level, starting from the notebook root, and anchoring at the current document require separate representations. An empty segment array means the starting location itself. An empty string cannot automatically match an empty-title parent, while creation can explicitly submit an empty final title. The caller's `onMissingParent` policy determines whether missing ancestors may be created.++### Commits, partial failures, and retries++The first implementation does not add a general atomic multi-file creation API. Kernel workflows use creation plans; plugins compose the resolver and single-document creation endpoint. Before writing, a plan validates predictable title, depth, ambiguity, template, and authorization errors and assigns a fixed ID to each document to be created. Matched ancestors retain their identities and revisions. Recheck matches and revisions during execution; concurrently introduced same-named candidates require replanning instead of silently selecting another document.++Each creation step commits independently. A success response requires synchronous persistence of the source document and required body and attribute changes, with readable document metadata; full-text indexing can remain asynchronous. Preserve the workflow's template, footnote, math, clipping-source, tag, sorting, and refresh-notification behavior when separating addressing.++Keep documents already persisted when a later step fails. Error data distinguishes `commitState: "none"`, `"committed"`, and `"unknown"` and includes confirmed document IDs, the failed stage, and completed steps. `committed` means the source document was committed, not that all subsequent actions succeeded. If persistence cannot be determined, return `unknown` rather than claiming no write occurred. Multi-level workflows retain the original plan and completed IDs and show where processing can continue.-A `/` within a structured title segment no longer creates another level. Text such as `.` and `..` cannot act as navigation; a value disallowed by title validation produces a title error. Moving up a level, starting from the notebook root, and anchoring at the current document require separate representations. Empty segment arrays, empty titles, and omitted titles must also remain distinct rather than being inferred from trailing slashes or UI placeholders.+Callers retain allocated IDs before sending requests. After a lost response or unknown outcome, complete any necessary index recovery, then verify the source document and target by the original ID without allocating another ID. Submitting an existing ID returns `documentIDConflict`; it does not overwrite the document or interpret existence alone as proof of a successful identical request. The first implementation does not promise automatic idempotent replay. Side effects such as template application or body appends must not be repeated without verification.-Multi-level creation must define failure and retry behavior. Validate predictable input errors and ambiguity before writing. If writing fails partway through, preserve documents already created, return the creation results that can be confirmed, and let callers recover from them. A retry must neither overwrite a same-named document nor treat a lost success response as a reason to create another document. Define operation identifiers and retry semantics with the API contract; do not claim unimplemented atomicity across files.+Recovery handles only unfinished steps and does not automatically delete successfully created parent documents. Non-repeatable follow-up actions such as clearing source data require all necessary workflow steps to succeed. Partial success or merely receiving a document ID cannot trigger deletion of shorthand source data.### Template versionsLegacy string save paths retain their current interpretation, including absolute and relative paths, `..`, trailing `/`, empty templates, cross-notebook context, and an explicit name replacing the final segment. New syntax must have an identifiable version and must not automatically reinterpret existing configurations.-New templates should determine the starting location, navigation operations, ancestor segments, and final title boundaries before rendering, then evaluate each title segment separately. A variable whose value is `A/B` remains one title segment. Rendering a single string and subsequently calling `split("/")` cannot satisfy this requirement. All segments in one creation use the same context and time snapshot to avoid date or context changes between evaluations.+The compatibility compiler evaluates legacy templates using their original grammar and produces structured creation plans. A separately supplied new title remains separate and is not joined back into a path string. Relative anchors and upward navigation use the current document ID and parent relationships, never a split of its display path into legacy segments. This internal adapter does not call public string-addressing endpoints disabled by the new mode, so existing daily-note configurations still work. A `/` produced by a variable within a legacy template continues to create a level; it remains one segment only after an explicit switch to the new template format. Compatibility compilation preserves grammar, not arbitrary selection of a same-named parent; unknown ancestors still require ambiguity checks.-Daily notes, document creation from block references, shorthands, new database items, and template document trees must share the same target resolution conventions while retaining their own reuse and commit rules. Both desktop and mobile entry points require verification; migrating shared utilities alone does not establish compatibility across all interfaces.+New configuration uses `docCreateTarget`, `refCreateTarget`, and `dailyNoteTarget` alongside the original string save-path fields. Initially, these objects are available only in the configuration of notebooks with mode `2` enabled. Global settings retain legacy string templates and existing inheritance rules, avoiding configuration unknown to old clients before notebook activation. 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+{+ "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` also supports `{kind: "context"}` and `{kind: "document", id: string}`. `context` must resolve to the current document within the destination notebook; do not guess an anchor across notebooks, and fail when context is missing. `up` is a nonnegative integer and fails if it goes above the logical root. `parents` can be empty; `onMissingParent` must be `create` or `error`. An explicit caller-supplied title replaces the result of evaluating `title`. Workflows such as daily notes determine reuse of the final document; the generic path template does not.++New templates establish segment boundaries before rendering and evaluate each title segment separately. A variable whose value is `A/B` remains one title segment; rendering a single string and then calling `split("/")` violates the protocol. All segments use the same context and time snapshot. Daily notes supply `now` from the requested calendar date to prevent date or context changes during evaluation.++When a new object exists, it is the sole authoritative configuration for that creation target; the old string is retained only as the original configuration. Changing the old field to a different value returns an explicit configuration conflict instead of silently overriding the new object; sending the unchanged old value remains acceptable. Explicitly removing the new object re-enables the legacy template without downgrading the notebook to compatibility mode. Without a new object, retain the existing notebook/global configuration precedence. Cross-notebook targets still validate titles under the destination mode; an enabled source cannot bypass destination restrictions.++### Workflow migration++| Entry point | Preserved behavior and migration focus |+| --- | --- |+| Ordinary creation and creation from block references | Create directly under known parent IDs; pass titles separately and retain document IDs in generated references |+| Daily notes | Reuse by the daily-note date attribute first; retain template-target preference for multiple matches and ID ordering otherwise; do not reapply body templates to existing notes |+| Shorthands | Distinguish appending to an explicit target from creating a new target; clear the source only after destination persistence succeeds |+| New database items | Preserve attribute values, bindings, and sorting; retain the final document ID in the creation plan |+| Template document trees | Preserve previews, ID remapping, and insertion order; validate preview revisions on commit and expose partial completion |+| Desktop, browser, and mobile | Inspect menus, shortcuts, dialogs, and handlers separately; shared utility migration does not replace platform verification |++Daily-note reuse is an explicit existing business rule. The generic resolver's ambiguity policy must not turn every multiple-date match into an error; template-target preference compares structured identity chains instead.## Search and derived indexes@@ -98,7 +198,9 @@ Document depth, parent-child relationships, and subtree scope derive from ID datSearch scope filtering is separate from path text matching. Scope uses document identities or ID data paths. Text matching uses the plain-text title representation and ancestor text without replacing `/` with `/` or vice versa. Search highlight markers and HTML in results are presentation output; they cannot become title source content, and adding document titles to results must not overwrite existing match highlighting.-Initially, `blocks.hpath`, `blocktrees.hpath`, and the existing batch update mechanism can remain, avoiding a combined protocol migration and unverified storage optimization. Actual queries and performance measurements should determine whether to use document-level title metadata, add dedicated hierarchy fields, or assemble paths on demand. The design does not presume that each content block needs a copy of the full title segment array.+The first implementation retains `blocks.hpath`, `blocktrees.hpath`, and the existing batch update mechanism, adding the document metadata described above as the source for structured queries. Assemble ancestor chains per document with bounded caching, without copying full title arrays onto every content block. Plugins can still read string columns, but in the new mode they are display and text-search data only.++`RefreshDocHPaths` reconstructs ancestor titles from the ID subtree and metadata instead of slicing old `hPath` values by depth. `updateRootContent` obtains the document title from the shared title reader instead of `path.Base`. In steady state, renaming a parent does not read every descendant's full `.sy` file just to obtain its title. Missing or invalid metadata enters recovery rather than being filled from old display paths.Renames still invalidate display paths, ancestor text search data, and related caches. Source saves, document metadata updates, background batch validation, and interruption recovery must remain ordered, and queued old trees must not restore stale titles or paths. ID-based addressing removes the effect of titles on identity; it does not eliminate every rename update task.@@ -106,43 +208,144 @@ Renames still invalidate display paths, ancestor text search data, and related cExport first assigns a unique relative file path to each document identity, then uses the same mapping to write files and generate inter-document links. The mapping must handle slashes in titles, invalid filename characters, duplicate names, case-insensitive collisions, length limits, and duplicate names across notebooks. Overwrite checks and link generation cannot independently choose filenames while processing individual items.+The allocator determines export directories from ID relationships, then converts each filename independently. Preserve existing unambiguous filenames; use safe names for reserved or empty names, `.`, `..`, trailing spaces or dots, and similar cases. Append a stable document ID on collision and the notebook ID if also necessary. Compare names under the destination filesystem's case and naming rules, retaining the unique suffix and extension when truncating. After allocating all names, recheck uniqueness and destination-directory boundaries before writing files and links. A `/` within a title affects only its filename conversion and never creates a directory.+The title content `.`, `..`, and path separators may only participate in filename conversion and must not escape the export directory. Plain-text titles and rich titles supported by the destination format provide document content. Export filenames can undergo necessary conversion, but cannot become the sole source for restoring titles. Formats promising lossless reimport must preserve original title and corresponding identity metadata; ordinary Markdown filenames alone cannot provide that guarantee.+Initially, native exports and backups continue preserving title sources and versions in source documents; Markdown export does not introduce a new general source format. Ordinary Markdown exports can retain titles in the body without promising lossless restoration of all title metadata. A later manifest-based round-trip format would require its own version and import rules.+Import maps source file paths and source identifiers to new document IDs, and resolves links through that mapping rather than using `hPath` as a unique key. Duplicate source names, relative links, heading anchors, and ambiguous links follow explicit conflict rules. Existing source path mappings in importers such as Obsidian should remain in use; their title and readable-path generation can migrate independently.-## API and plugin compatibility+## Structured API contracts++The following paths and fields are proposed new contracts using `POST` with JSON requests. Initially, new read endpoints require workspace administrator access; write endpoints additionally require writable access. They do not automatically expose ancestor enumeration to published-page visitors. Existing published pages retain document-level visibility checks, and any added structured presentation data needs equivalent filtering. Encrypted-notebook operations retain valid leases through resolution, queries, and response serialization.++### Batch reads by ID++`/api/filetree/getDocPaths` accepts `notebook` and `ids`, where `ids` contains 1 to 128 document IDs; excess input fails instead of being silently truncated. Deduplicate in first-occurrence order and return `{documents: DocumentPath[], missingIDs: string[]}`. IDs that are absent, outside the requested notebook, or not readable as documents enter `missingIDs`, with no fallback lookup in another notebook. Denied access to the whole notebook fails the request.++Each `DocumentPath` contains titles and ancestors from one verifiable revision. Results follow deduplicated input order, with missing entries listed separately. An unavailable index, unsupported source format, or authentication failure is an error, not a missing document. Batch reads do not promise a global snapshot across documents; callers retain individual `revision` values and revalidate on preview submission.++### Resolution by title segments++`/api/filetree/resolveDocPath` accepts `notebook`, `start`, and `segments`. `start` is `{kind: "root"}` or `{kind: "document", id: string}`; `segments` is an array of independent title strings. The endpoint only resolves, never creates. An empty array returns the starting location; otherwise, lookup proceeds one level at a time by exact name without interpreting navigation characters inside strings.++Results contain `status`, `start`, `resolved`, `nextIndex`, `candidates`, and `candidatesTruncated`. `start` returns the starting identity and revision; `resolved` and `candidates` use `DocumentPath`. `nextIndex` is the zero-based index of the next segment. `status: "resolved"` means all segments matched; `"missing"` means no document exists from that segment onward; `"ambiguous"` means that segment has multiple candidates. Return at most 128 candidates ordered by ID, setting `candidatesTruncated` if more exist. Reaching the limit still reports ambiguity: callers must use an explicit parent ID, never default to the first truncated candidate.++Resolution accepts at most 128 segments, each within the title length limit; actual creation still enforces the user's document depth restriction. Empty string segments fail; existing empty-title parents require ID selection. A root result uses an explicit root location, not an invented document ID. Root revisions cover notebook identity and relevant configuration, without invalidation by unrelated child changes. The notebook document ID, when used as a root alias, also uses root revision validation. Errors and candidates must not expose another notebook's titles.++### Creation by parent ID++The minimal request for `/api/filetree/createDocByParent` follows. This example requires structured title mode on the destination notebook.-Record the compatibility meaning of legacy fields for each use case. Keeping a field typed as `string` does not establish compatibility. Add structured information through new fields or explicit protocol versions, preserving each legacy API's input, nullability, response variants, authorization, and operation lease contract.+```json+{+ "notebook": "20210808180117-6v0mkxr",+ "parentID": "20261015090000-abcdefg",+ "id": "20261015100000-hijklmn",+ "title": {"format": "plain", "text": "卷01·第一章/第二节"},+ "markdown": ""+}+```-| Use case | Migration constraint |+| Field | Constraint || --- | --- |-| Reading and operating on documents by ID | Preserve identity and authorization semantics; identify whether added title or hierarchy data is plain text |-| `getIDsByHPath` and legacy string creation inputs | Retain the legacy grammar; `/` inside a title must not be mistaken for legacy hierarchy and select the wrong document |-| Path outputs such as `getHPathByID` and `getFullHPathByID` | Record notebook-name inclusion, machine parsing expectations, and round-trip requirements with legacy resolution inputs |-| `Criterion.hPath`, `SearchPath`, and search results | Distinguish saved criteria, display paths, search scopes, and highlighted presentation content |-| Paths in databases, templates, asset relinking, and history diffs | Determine each field's purpose and migrate to an explicit identity or presentation representation |-| `blocks.hpath` and `blocktrees.hpath` in plugin SQL | Maintain plugin-visible semantics; do not directly change string columns into arrays or silently change hierarchy rules |+| `notebook` | Required destination notebook ID |+| `parentID` | Required document ID or `null` for the notebook root; an empty string does not mean root |+| `id` | Required valid new document ID allocated and retained by the caller; never overwrite an existing ID |+| `title` | Required; initially accepts only a plain title object; empty text differs from omission |+| `markdown` | Required; an empty string is valid |+| `expectedParentRevision` | Optional validation of the parent path revision when submitting a preview; use the resolver's root revision for a root target |+| `tags`, `withMath`, `clippingHref` | Optional, retaining the corresponding Markdown creation behavior |+| `sorts`, `sortTargetID`, `sortPosition` | Optional, preserving sort validation; relative targets must still be sibling documents, and conflicting sort specifications fail |+| `docCreateTemplatePath`, `listDocTree` | Optional, retaining existing body-template and document-tree refresh semantics |++Reject additional targeting fields such as `path` and `hPath` to avoid competing location sources. A parent mismatch fails directly without falling back to name resolution. Success returns `{id, document: DocumentPath}`; clients use the returned ID to open, reference, or append to the document.++Business errors use `code: -1` with a stable `data.reason`. `msg` is for human readers, not plugin branching. Contract declarations retain error data carrying commit state and recovery information. Authentication, role, locking, and general request-validation failures continue using their middleware contracts rather than replacing every existing error format.++| Reason | Meaning and caller action |+| --- | --- |+| `invalidTitle` | Invalid title representation, characters, or length; correct the input |+| `parentUnavailable` | Parent absent or outside the target notebook; do not search another notebook |+| `planChanged` | Location, title revision, or preview dependencies changed; resolve and confirm the target again |+| `documentIDConflict` | ID exists; verify the original outcome without overwriting or immediately retrying with a new ID |+| `legacyPathUnsupported` | Legacy string addressing is disabled for the notebook; use the new API |+| `indexUnavailable` | Structured metadata is not ready; wait for recovery without falling back to display paths |+| `unsupportedTitleFormat` | Client or endpoint cannot handle the title format; upgrade or use an endpoint supporting that format |+| `writeFailed` | A write or later processing failed; recover using `commitState` and the reported stage |++### Reading the effective creation target++`/api/filetree/getDocCreateTarget` accepts the current `notebook` and `purpose: "document" | "reference" | "dailyNote"`. It reuses each workflow's existing configuration precedence and returns the effective `target`, `docCreateTemplatePath`, and configuration `revision`. `target` is a union tagged by `version`: legacy templates return `{version: 1, notebook, path}`, while new templates return the complete version `2` object above. The endpoint only reads configuration; it neither evaluates templates nor guesses the current document or date. Callers supply context when generating the plan afterward.++Legacy `/api/filetree/getDocCreateSavePath` retains its response while the effective configuration is a legacy template. When a new object is active, it returns `code: -1`, `data: {reason: "structuredTemplateRequired"}` instead of returning the obsolete old path. Declare that error variant on the legacy contract. Both built-in consumers and plugins use the new reader to avoid reimplementing configuration inheritance independently.++### Capability discovery and activation++Add an optional read-only `documentCapabilities` object to `data` in `/api/notebook/getNotebookConf`, retaining existing `box`, `name`, `conf`, and access filtering. It contains `addressingVersion`, `structuredPaths`, `literalSlash`, `titleFormats`, `indexState`, `minimumReaderVersion`, and `revision`. `structuredPaths` means the server implements the new protocol; `indexState` indicates this notebook's readiness. These are distinct. Initially, `titleFormats` is `["plain"]`; `literalSlash` is `true` only in mode `2` with a ready index.++`revision` is the configuration revision relevant to activation, not an individual document's path revision. 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.++`/api/notebook/enableStructuredTitles` accepts `notebook` and `expectedRevision`. It checks the configuration revision, index state, and local client compatibility, persists mode `2`, and returns current `documentCapabilities`. If already enabled with a matching revision, it may return the current state. The endpoint cannot prove that every offline sync client has upgraded; the activation UI explains the minimum version and plugin adaptation requirements, and the user explicitly enables the mode. General configuration updates cannot bypass this activation flow, and old requests omitting new fields cannot reset the mode to `1`.++### Contract and declaration maintenance++Implementation follows [Kernel API type contracts](API-CONTRACTS.md): define declarations in `kernel/apicontract/`, bind with `contractHandler`, generate types, and synchronize maintained Petal declarations and its changelog. Detailed new endpoint behavior belongs in the corresponding contract comments. When existing endpoint behavior changes, inspect and synchronize existing entries in the Chinese, English, and Japanese API references. Do not automatically add new endpoints to those references or add feature-specific endpoint descriptions to the contract maintenance guide.++## API and plugin compatibility++Mode `1` is compatibility mode; mode `2` is explicitly enabled structured title mode. An old notebook without the field reads as `1`. The mode determines availability of legacy protocols, not a guess based on whether a particular request happens to contain `/`.++| Use case | Compatibility mode `1` | Structured title mode `2` | Plugin migration |+| --- | --- | --- | --- |+| Reads, moves, and deletion by ID | Preserve existing contracts | Preserve identity, authorization, and response variants | Keep using IDs; reread location after moves |+| Rename by ID and creation using ID data paths | Preserve existing title rules | Plain titles can retain `/`; still validate mode and title format | Pass title and location separately; do not overwrite unknown rich formats with plain text |+| `getIDsByHPath` | Preserve legacy name-path grammar | Reject throughout the notebook with `legacyPathUnsupported` | Use known IDs directly, or `resolveDocPath` for unknown locations |+| `createDocWithMd` | Preserve legacy grammar and `parentID` fallback | Reject throughout the notebook, even with `parentID` supplied | Use `createDocByParent` without a string path |+| `getHPathByID`, `getHPathByPath` | Preserve existing output | Join original ancestor titles for display only | Use `getDocPaths` for structure |+| `getFullHPathByID` | Preserve notebook-name inclusion and nullability | Still display the notebook name; no reverse addressing | Display notebook names separately from document segments |+| `blocks.hpath`, `blocktrees.hpath` | Preserve column types and existing behavior | Remain strings that can contain indistinguishable title slashes | Query subtrees with ID `path`, read titles from document-row `content`, and obtain parents and depth through structured APIs |+| `Criterion.hPath`, `SearchPath`, search results | Preserve existing configuration and highlighting semantics | Display text remains searchable; scope and hierarchy use IDs | Do not resubmit highlighted text or displayed paths as locations |+| Legacy save-path templates | Run with original grammar | Compile internally into structured plans | Explicitly use version `2` templates when `/` in a variable must remain within one segment |+| `getDocCreateSavePath` | Preserve legacy configuration results | Preserve results for old templates; return `structuredTemplateRequired` for new templates | Use `getDocCreateTarget` for the effective versioned configuration |-Compatibility entry points retain existing behavior for data representable by existing title rules. When data using new title capabilities cannot round-trip losslessly through a legacy path string, legacy addressing and write entry points must return an explicit unsupported or ambiguity error instead of guessing the target or silently replacing characters. A per-interface compatibility matrix must determine how legacy read results and SQL columns present such data before enabling the capability. Until those decisions are made, new title writes remain restricted.+Do not change legacy field types, remove old APIs, or encode mode `2` display paths to present them as compatible addresses. Different structures can display the same string in the new mode, so SQL equality on `hpath` can also match both. Plugins that count separators, take the final segment, or query subtrees by display prefixes must adapt; that is the compatibility cost of enabling the capability.-Existing `/`, `%2F`, and similar title content are literal data. Do not infer whether a user once applied an encoding convention. If a particular external channel needs reversible encoding, it must define a version and a separate adapter boundary; that encoding must not become internal document identity or title source content.+Legacy string endpoints gain an explicit mode `2` error variant: `code: -1`, `data: {reason: "legacyPathUnsupported"}`. Declare this variant on the existing contracts and retain its error data. Existing success, null, and error responses in mode `1` stay unchanged. Merely changing error prose and requiring plugins to match localized text is insufficient.-Actual HTTP API additions and changes follow [Kernel API type contracts](API-CONTRACTS.md). Record behavior, defaults, limits, and compatibility in contract declarations, and synchronize the corresponding maintained Petal declarations and changelog. Generated types do not substitute for semantic compatibility review. Deprecating legacy fields requires an explicit replacement and transition policy; they cannot be removed immediately when new title characters are enabled.+Existing `/`, `%2F`, and similar title content remain literal data without inferred historical encoding. An external channel needing reversible encoding must use a separate version and adapter boundary, never internal identity or title sources.++Plugins migrate through capability discovery, reading known targets by ID, resolving unknown ancestors structurally, creating by parent ID, and operating on returned IDs. Publish this matrix and minimal examples with the replacement APIs; migrate built-in consumers before opening mode `2`. The server cannot identify every plugin SQL query and its later use, so it cannot promise to prevent all plugin misuse of display strings automatically.## Versions, encryption, and recovery### Mixed-version access-Even if `.sy` continues storing a string title, older clients can remove `/` during normalization or interpret title text as hierarchy while constructing `hPath`. Rebuilding indexes alone cannot address those behaviors. Before enabling new characters, define the minimum compatible client, sync access restrictions, and any necessary document format version protection, and verify editing, import, history restore, and backup restore entry points.+Notebook configuration adds `documentAddressingVersion`: absent or `1` means compatibility mode, and `2` means structured title mode. This is independent of encryption-envelope versions and must not reuse `BoxCrypt.Spec`. Enabling the mode does not rewrite existing document titles or IDs in bulk; it changes subsequent operation eligibility and representation rules for new content.++Even if `.sy` continues storing a string title, older clients can remove `/` or interpret title text as hierarchy. Release in two steps: first a protective version that recognizes notebook capability markers and safely rejects unsupported modes, then a feature version that allows enabling mode `2`. The protective version rejects unsupported modes before mounting, indexing, repairing, editing, or applying sync changes; it must not modify data before requesting an upgrade.++Documents actually using new title capabilities adopt a new `DocumentTitleSpec`. Allocate its numeric value against the `.sy` versions in use at implementation time, rather than reserving a number in this draft. Enabling a notebook does not rewrite every document that does not use the capability. Future rich representations also need explicit format versions, and tolerant parsing must never overwrite unknown content.-Existing `Spec` checks provide a starting point for evaluating version protection, but cannot be assumed to run in every released client and every entry point. Do not claim compatibility with an older version without establishing safe rejection or correct reads. Future rich titles also require an explicit format version and protection against tolerant parsing that overwrites unknown content. Existing ordinary titles and supported older formats remain readable.+Version protection covers full reads, attribute-only reads, read-only path recovery, import, history, backups, and sync. Currently, the non-strict `readDocIAL` branch does not execute the same `CheckSpecJSON` validation as the strict branch; checking only ordinary editor loads is insufficient. A source version requiring mode `2` in a mode `1` notebook produces a mode conflict first. Import continues only after explicit activation, never by silently cleaning titles to fit the old mode.++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 by new fields and are outside the safe mixed-version promise. All sync devices must upgrade before activation. Offline device state cannot be proven and must be explained. If a supported version still has a path that rewrites data, keep the capability disabled rather than substituting documentation for necessary protection.++Mode `2` has no direct 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-activation 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.### Index and task recovery-Derived index migration needs an explicit version and coverage for full rebuilds, incremental updates, and recovery after interruption. Recovery uses source documents and current ID locations; it must not guess titles from old `hPath` values or recreate missing parent source files automatically. Update derived state only after confirming valid source data, preserving recoverable tasks and source files on failure.+`document_metadata` uses an independent derived-index version and per-notebook states `missing`, `building`, `ready`, and `error`. Build the new table from source documents and ID locations, not segment boundaries guessed from old `hPath` values. Record incremental changes during construction and catch up before switching; mark the corresponding generation `ready` only after the full scan and incremental validation complete.++In compatibility mode, existing functionality retains its behavior during rebuilding, while new structured endpoints return `indexUnavailable` if required data is not ready. Mode `2` cannot fall back to old name addressing when indexes are corrupt. Recover through existing source-read paths and hold structured writes until required metadata is ready. Do not automatically recreate missing parent source files or replace corrupt source data with old titles from an index.++Update in order: persist the source document, update metadata and the corresponding document row within one block-tree database transaction, then submit subsequent `hpath` batches. There is no claimed atomic transaction between source files and databases or between block-tree and content databases. Preserve recovery markers across interruption at any step. After restart or unlock, verify source revisions and current ID locations before resuming derived updates. Revision, move, and deletion checks invalidate queued old trees so they cannot restore stale titles.The existing `temp/queue/hpath-refresh.queue` stores only notebook IDs, document IDs, and ID data paths. Migration must not add title segments, rich titles, or body text to this global plaintext queue. Concurrent renames, moves, deletion, sync, and ordinary index rebuilds still need stale-task checks and must not discard unfinished encrypted-notebook recovery tasks.+To cover a crash after the source write but before recovery work is registered, persist an identity-only pending-verification marker before mutation, or use an existing durable transaction record proven to cover that window. Fault injection must establish recoverability. Clear the marker only after completion; repeated recovery produces the same derived result. Keep tasks for locked encrypted notebooks instead of skipping authentication just to empty the queue.+### Encryption compatibilityExisting encrypted data is the compatibility baseline, subject to the authenticated-read, isolation, and recovery requirements in [Encrypted notebooks](ENCRYPTED-NOTEBOOK.md). Title sources, plain-text titles, and ancestor chains are protected document content. Reads, caches, and responses must remain within the notebook's authorization scope and operation lease, with cleanup on lock following the existing lifecycle.@@ -151,42 +354,76 @@ Derived indexes can be rebuilt only after authenticating source ciphertext and vInternal decoupling does not require changes to encryption envelopes, AAD, or key derivation. Any later change to those formats requires a separate explicit version, authenticated migration, and interruption recovery design that retains matching keys and backup material. Never regenerate `MasterSalt`, discard keys, or require users to recreate existing encrypted notebooks to avoid incompatibility. Supported formats in documents, history, backups, and sync snapshots must remain recoverable.-## Implementation dependencies+## Implementation stages and activation gates++| Stage | Deliverables | Completion criteria |+| --- | --- | --- |+| A: Compatibility protection | Notebook capability markers, unknown-mode and source-version protection, existing behavior fixtures | Protective version released; unsupported modes safely rejected at every write and repair entry point |+| 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 create APIs, version `2` templates, built-in workflow and platform migration | New and old contracts verified; partial failures recoverable; daily-note and other business behavior retained |+| D: New characters | Mode activation, legacy API rejection rules, plugin migration guidance, import/export and cross-version verification | Allow explicit user activation of `/` only after all gates pass |+| 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. New characters require 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.++Activation 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 activation, plugin impact, and sync-device requirements.-1. Establish boundaries for title access and structured hierarchy, with consistent identity-based ownership validation and creation target resolution; retain existing title input rules and external protocols at this point-2. Migrate creation, templates, search, indexes, import, export, desktop consumers, and mobile consumers, covering duplicate titles, concurrent changes, and recovery-3. Enable `/` in titles only after completing the legacy API and SQL compatibility matrix, template versioning, mixed-client protection, and acceptance checks; synchronize plugin declarations and the user guide in all four bundled languages-4. Decide cache and index layout optimizations from measurements; design and implement rich titles separately under the extension requirements above+Implementation still needs actual release version numbers, an available `.sy` version allocation, performance measurements, and compatibility test results. These are release evidence, not unresolved decisions about identity, templates, plugin boundaries, or failure semantics. Proposed endpoints and fields must become verifiable contracts; finishing this document or rebuilding an index once is not feature acceptance.-Before enabling new characters, decisions remain necessary for legacy path output and SQL representations of new titles, final structured creation and template contracts, partial-creation retry semantics, and the minimum client version and protection mechanism. Each decision must be reflected in the relevant interface or format definition and regression cases. Editing this document or rebuilding indexes does not satisfy those requirements.+## Verification and acceptance-## Verification+### Behavior matrix| Area | Required scenarios || --- | --- || Title content | `/`, `/`, repeated slashes, `%2F`, `.`, `..`, empty titles, Unicode, and length boundaries; no uncontracted character conversion || Identity and hierarchy | One title `A/B` versus two levels `A`, `B`; duplicate titles under the same or different parents; ownership checks for duplicate IDs; root locations and notebook documents |-| Creation and concurrency | Parent rename, move, deletion, close, or lock; invalidated previews; partial multi-level creation and retries; ordinary creation versus reuse |+| Creation and concurrency | Direct ID creation following parent location versus revisioned requests rejecting stale previews; parent deletion, cross-notebook moves, closure, or locking; lost responses, partial commits, fixed-ID conflicts, and multi-level recovery || Templates | All legacy syntax boundaries, segment-by-segment rendering, variables containing `/`, relative operations, one time snapshot, and daily note, shorthand, and related entry points || Search and presentation | Original title character search, ancestor text search, ID scope filtering, title highlights, breadcrumb boundaries, copied text, and ID links || 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 and export | Duplicate names, invalid filenames, case collisions, path escape, relative links, cross-notebook references, title metadata, and lossless round-trip guarantees |-| Legacy APIs and plugins | Field meanings, nullability and response variants, SQL hierarchy assumptions, legacy string round-trips, explicit failures for new titles, and replacement entry points |+| Legacy APIs and plugins | Unchanged mode `1` responses; notebook-wide legacy-addressing rejection in mode `2`; SQL display collisions, structured replacements, and missing capabilities distinguished from request errors || Older clients and encryption | Supported historical format fixtures, mixed-version sync, 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 || 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 |-Performance evaluation compares against current rename, query, and index mechanisms, reporting foreground response and background work separately rather than treating elapsed time including scheduling waits as database time. Behavior regressions belong in existing frontend and kernel test discovery. Before enabling a new format, use actual supported older-format fixtures to verify reads, export, history, backup, and recovery.+### Essential regression cases++Retain `TestCreateDocsByHPathUsesParentIDForDuplicateHPath` and `TestCreateDocsByHPathKeepsHPathFallbackForDifferentParent` to prove that new rules have not silently replaced the legacy compatibility entry point. Separately test the new endpoint following the same parent ID after a rename, rejecting a parent moved to another notebook, never selecting a same-named parent, and returning `planChanged` for stale revisioned requests.++Create a root document `A/B`, a root document `A` with child `B`, a root document `A/B`, and a root document `A%2FB` together. The first two may share a display path, but must retain correct IDs, `segments`, `depth`, subtree scope, and export links. Neither of the latter two may be converted into the former structures. Add repeated slashes, dot segments, empty titles, case differences, and different title formats with identical plain text.++Actual 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.++### Performance and resources++Compare the baseline and implementation in the same environment using 1,000 and 10,000 documents, wide subtrees, and depth 7, with additional coverage for the option allowing deeper documents. Test ordinary and unlocked encrypted notebooks separately. Measure batch path reads, parent renames, moves, initial rebuilds, and incremental recovery, recording foreground latency, background duration, memory, database size, and `.sy` read counts, including median and high-percentile results.++Foreground creation and reads must not scan the entire notebook because of new metadata. Renaming a parent with ready metadata must not read each descendant's body. Index construction can scan source documents but needs progress and recovery points. Caches have explicit limits and clear corresponding titles on lock; do not retain every content block's entire ancestor chain in memory. Measure existing background content-block `hpath` updates separately, without treating scheduling delays as database time or claiming separation eliminates all subtree updates.++Reports explain changes relative to the baseline. Duration depends on hardware, body size, and encryption costs; this draft provides no unmeasured speedup or fixed millisecond promise. Investigate query counts, transaction batches, and repeated source reads before selecting cache optimizations for substantial regressions; do not trade title semantics for performance.++### Implementation checks++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`.++Change CI filters or maintenance guides only if existing discovery would miss new tests. These are implementation acceptance requirements, not functional tests already executed for this design document. Documentation changes themselves verify bilingual consistency, examples, links, and diff formatting.## Related code| Area | Entry points || --- | --- || Creation, rename, title normalization, and name resolution | [`model/file.go`](../kernel/model/file.go), [`model/path.go`](../kernel/model/path.go) |+| APIs, mode configuration, and contracts | [`api/filetree.go`](../kernel/api/filetree.go), [`api/notebook.go`](../kernel/api/notebook.go), [`apicontract/filetree_remaining.go`](../kernel/apicontract/filetree_remaining.go), [`conf/box.go`](../kernel/conf/box.go) || Source documents and read-only path recovery | [`filesys/tree.go`](../kernel/filesys/tree.go), [`filesys/hpath.go`](../kernel/filesys/hpath.go) |-| Path refresh, recovery queues, and document indexes | [`treenode/hpath.go`](../kernel/treenode/hpath.go), [`model/hpath_refresh.go`](../kernel/model/hpath_refresh.go), [`sql/queue.go`](../kernel/sql/queue.go) |+| Path refresh, recovery queues, and document indexes | [`treenode/blocktree.go`](../kernel/treenode/blocktree.go), [`treenode/hpath.go`](../kernel/treenode/hpath.go), [`model/hpath_refresh.go`](../kernel/model/hpath_refresh.go), [`sql/queue.go`](../kernel/sql/queue.go) || Search and hierarchy calculations | [`model/search.go`](../kernel/model/search.go), [`sql/block_query.go`](../kernel/sql/block_query.go), [`search/config.ts`](../app/src/search/config.ts) || Creation entry points and save path parsing | [`util/newFile.ts`](../app/src/util/newFile.ts), [`util/parseNewDocTarget.ts`](../app/src/util/parseNewDocTarget.ts), [`mobile/util/initFramework.ts`](../app/src/mobile/util/initFramework.ts) || Templates, new database items, and shorthands | [`model/template_doc_tree.go`](../kernel/model/template_doc_tree.go), [`model/attribute_view_new_item.go`](../kernel/model/attribute_view_new_item.go), [`model/shortcuts.go`](../kernel/model/shortcuts.go) |+| Daily-note reuse and legacy creation regressions | [`model/daily_note.go`](../kernel/model/daily_note.go), [`model/file_test.go`](../kernel/model/file_test.go) || Import and export | [`model/import.go`](../kernel/model/import.go), [`model/import_obsidian.go`](../kernel/model/import_obsidian.go), [`model/export.go`](../kernel/model/export.go) |+| Reusable rich-source validation pattern | [`treenode/table_cell_rich.go`](../kernel/treenode/table_cell_rich.go) || Document versions | [`treenode/tree.go`](../kernel/treenode/tree.go), [`.sy` file structure](SY-FORMAT.md) |diff --git a/docs/DOCUMENT-ADDRESSING.zh-CN.md b/docs/DOCUMENT-ADDRESSING.zh-CN.mdindex 20fd714370..a2aa226f9e 100644--- a/docs/DOCUMENT-ADDRESSING.zh-CN.md+++ b/docs/DOCUMENT-ADDRESSING.zh-CN.md@@ -4,7 +4,7 @@关联问题:[Improve hPath by separating display text from document addressing](https://github.com/siyuan-note/siyuan/issues/19938)-本文为设计草案,规定文档标题、层级定位和可读路径的职责,以及开放标题新能力前必须满足的兼容要求。文中目标行为尚未全部实现;当前重命名与路径索引的更新机制见 [文档重命名与路径索引](DOCUMENT-HPATH.md)。+本文为实施设计草案,规定文档标题、层级定位、可读路径、接口及迁移的目标行为。下文新增的字段、接口和版本机制均为拟实现契约,不表示当前版本已经支持。当前重命名与路径索引的更新机制见 [文档重命名与路径索引](DOCUMENT-HPATH.md)。## 目标与范围@@ -14,6 +14,23 @@方案覆盖桌面端、浏览器端、移动端、内核接口和插件可见数据,并遵守普通笔记本与加密笔记本各自的访问边界。笔记本名称作为独立显示字段参与路径展示;笔记本名称的字符限制与富文本支持需要单独评估配置格式和旧客户端兼容,不能由文档标题规则自动推导。+### 方案决策++| 项目 | 采用的方案 |+| --- | --- |+| 文档定位 | 笔记本 ID 与文档 ID;创建使用独立的父文档身份与标题 |+| 新旧模式 | 按笔记本显式启用结构化标题模式;已有笔记本默认保持兼容模式 |+| 插件兼容 | 接受依赖旧 `hPath` 规则的插件适配;先交付替代接口及迁移说明,再启用新字符 |+| 旧字符串寻址 | 兼容模式保留原有行为;结构化标题模式明确拒绝旧字符串定位与创建入口 |+| 可读路径 | 保留标题原文并按层级拼接展示;不编码 `/`,不把 `/` 或 `%2F` 解码 |+| 索引 | 保留现有 `hpath` 列,新增文档级内部元数据;不为每个内容块保存完整标题段数组 |+| 标题源 | 首版继续使用普通标题;预留带版本的行级内容及单向纯文本派生 |+| 发布顺序 | 兼容保护和结构化能力先发布,完成迁移验证后开放 `/`,富文本标题单独实现 |++兼容边界按笔记本划定,避免根据某次请求猜测调用者的标题意图。例如 `/A/B` 可以指两级文档,也可能是单个标题的展示结果,旧请求没有足够信息区分两者。结构化标题模式启用后,该笔记本内即使某篇文档仍使用普通标题,旧字符串寻址入口也会返回明确错误;按 ID 操作和普通文字展示继续可用。这是插件需要适配的明确范围,不承诺所有旧插件零修改运行。++基础解耦不需要新增第三方服务、网络传输或依赖。实现继续遵守仓库及现有依赖的授权要求;若后续选择新依赖,应另行核查其许可。主要成本是调用方迁移、索引重建和跨版本验证。标题及祖先链的缓存、日志和错误响应继续受加密笔记本边界约束,不能因增加结构化字段扩大数据可见范围。+## 标题、身份与路径### 当前数据来源@@ -36,7 +53,7 @@| 结构化祖先链 | 按层级排列的文档 ID 及对应标题信息 | 保留段边界,笔记本名称单独保存,不从展示字符串恢复 || 标题段数组 | 从明确位置开始逐级匹配或创建文档的输入 | 只消除分隔符歧义,不保证名称唯一 || 可读路径 | 面包屑、提示或复制路径所需的展示内容 | 可以使用不同展示形式,不承担文档寻址或源数据恢复 |-| 旧路径协议 | 现有接口及插件使用的 `hPath`、`hpath` 等字段 | 通过兼容适配维护,不能原地替换字段语义 |+| 旧路径协议 | 现有接口及插件使用的 `hPath`、`hpath` 等字段 | 兼容模式维持原有行为;结构化标题模式采用后文明确的显示及拒绝规则 || 导出相对路径 | 导出任务为文档分配的文件位置 | 由导出映射确定,与标题及界面可读路径分开 |当前前端搜索配置的 `idPath` 是多个搜索范围字符串组成的数组,其中每项可以包含笔记本 ID 和文档 ID 路径;它不是单条路径的逐级 ID 数组。迁移时必须保持现有配置的解释方式。块树中的 `parent_id` 表示块节点的父节点,也不能直接当作文档的父文档 ID 使用。@@ -50,6 +67,34 @@面包屑应使用结构化层级呈现边界。复制出的纯文本路径只用于阅读;用于定位的链接和引用必须携带 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` 和 `addressingVersion`。`title` 为 `{format, text, empty}`,`segments` 按从根到当前文档的顺序包含 `{id, text, empty}`。`displayPath` 以 `/` 开头并用 `/` 连接各段,空段数组显示为 `/`,仅作展示;笔记本名称单独返回或由调用方取得,不混入段数组。这里的 `title` 是标题摘要,不能作为未来富文本源内容的完整副本回写。++普通根文档的 `depth` 为 `1`,`parentID` 为 `null`。启用笔记本文档功能时,笔记本文档本身的 `depth` 为 `0`、`segments` 为空,普通根文档仍为第一级;它不额外增加物理目录。创建时传入笔记本文档 ID 与显式根位置等价,沿用现有逻辑根映射。根位置的子文档名称查询排除笔记本文档自身,避免把它误当成普通根文档。++路径版本摘要使用有明确字段边界的版本化序列化,覆盖祖先 ID、标题版本及当前位置,不能只使用秒级更新时间。直接按父 ID 创建可以跟随父文档的最新位置;需要保持预览结果时提交 `expectedParentRevision`,祖先改名或位置变化会使该值失效。摘要只用于一致性检查,不作为跨权限边界的访问凭证。+## 行级标题的扩展约束标题读取应提供明确的源内容、纯文本提取和展示边界。当前实现可以继续保存普通字符串,但寻址、层级计算、创建目标解析和文件名分配不得绑定到 IAL 字符串的具体存储形式,也不得把标题交给文件路径清理函数处理。@@ -60,6 +105,8 @@富文本标题的纯文本提取需要定义空白、换行、行内公式、链接文本、空标题和长度限制的规则。仅样式不同的两个标题可以得到相同纯文本,身份与引用仍由 ID 区分。搜索、排序和导出文件名不能将 Markdown 标记或渲染 HTML 当作标题文字;导出正文中的标题可以按目标格式保留行级内容。+普通标题按文本渲染,使用现有转义或文本节点机制,不能因支持新字符而直接拼接为 HTML。富文本标题复用经过校验的节点及渲染模型;`DocumentPath` 的纯文本摘要与可编辑源内容使用不同读取边界,写入按格式区分,防止展示数据覆盖源格式。+块引用、动态锚文本、链接、标签和资源需要进一步定义依赖更新、点击行为、引用及资源归属、循环引用处理、复制与导入时的 ID 重映射,以及加密边界。本方案保留这些能力的表示空间,不表示所有行级元素都会同时开放。后续富文本标题实现还必须覆盖输入法、选区、撤销、移动端交互、历史、同步和导出。本次解耦的验收必须确认:增加一种标题表示时,寻址和层级规则无须改变;现有普通标题的字面内容保持不变;消费者通过约定的标题读取边界获取内容,不能各自猜测标题语法。@@ -68,27 +115,80 @@### 按身份创建-已知父文档时,创建请求应表达目标笔记本、父文档 ID 或根位置、标题及正文。内核在实际写入前按当前身份解析数据路径,并重新校验归属、可写状态、父文档有效性和加密笔记本操作租约。跨笔记本移动可能改变归属,过期的笔记本参数必须报错,不能退回其他笔记本查找。+已知父文档时,创建请求表达目标笔记本、父文档 ID 或根位置、独立标题及正文。内核在实际写入前按当前身份解析 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 时直接使用该身份;未知祖先逐级在当前父文档下匹配。无匹配时按操作规则创建,有多个匹配时返回歧义错误及授权范围内的候选身份,不得任取第一项。普通新建的最后一段是否允许同名,与复用既有文档的规则分别定义。+需要按名称逐级创建时,输入包含明确的起点和标题段数组。已知祖先 ID 时直接使用该身份;未知祖先逐级在当前父文档下匹配。无匹配时按操作规则创建,有多个匹配时返回歧义及授权范围内的候选身份,不得任取第一项。通用解析器不跨同名父文档搜索后代来猜测用户意图。++结构化标题段中的 `/` 不拆分层级,`.`、`..` 不执行导航。向上一级、从笔记本根开始和以当前文档为起点需要独立表达。空段数组表示起点自身,空字符串不能用来自动匹配空标题父文档;最终创建的空标题仍可显式提交。是否允许创建缺失祖先,由调用方的 `onMissingParent` 策略决定。++### 提交、部分失败与重试++首版不新增通用的跨文件原子创建接口。内核业务使用创建计划,插件通过解析接口及单文档创建接口组合操作。计划在写入前校验所有可预知的标题、深度、歧义、模板及权限错误,并为待创建的每篇文档分配固定 ID;已匹配祖先记录身份和版本。执行时重新检查匹配和版本,并发出现同名候选时要求重新规划,不能悄悄改用另一篇文档。++每个创建步骤独立提交。成功响应要求源文档及本次必需的正文、属性修改已同步持久化,文档元数据已可读取;搜索全文索引可按现有机制异步更新。模板、脚注、数学内容、剪藏来源、标签、排序及刷新通知按原业务语义执行,不能因拆分定位逻辑而丢失。++写入途中失败时保留已落盘文档。错误数据区分 `commitState: "none"`、`"committed"`、`"unknown"`,并返回可确认的文档 ID、失败阶段及已完成步骤;`committed` 仅表示源文档已提交,不表示所有后续动作成功。落盘状态无法确认时必须返回 `unknown`,不得声称未写入。多级业务同时保留原计划及已完成 ID,向用户提供继续处理的位置。-结构化标题段中的 `/` 不再拆分层级。`.`、`..` 等文本不能被当作导航操作;若标题校验不允许某个值,应返回标题错误。向上一级、从笔记本根开始和以当前文档为起点需要独立表达。空段数组、空标题及缺省标题也必须区分,不能依赖末尾斜杠或界面占位文字推断。+调用方在发送前保存所分配的 ID。响应丢失或结果未知时,先完成必要的索引恢复,再按原 ID 核对源文档和目标,不重新分配 ID。重复提交已有 ID 返回 `documentIDConflict`,不覆盖文档,也不把“ID 已存在”直接认定为同一次成功请求。首版不承诺自动幂等重放;模板或追加正文等有副作用的步骤不得未经核对再次执行。-多级创建必须明确失败和重试语义。请求先校验可预知的输入和歧义;写入途中失败时保留已成功创建的文档,返回可确认的创建结果并允许调用方据此恢复。重试不能覆盖同名文档,也不能把成功创建后响应丢失误当作需要再次新建;操作标识及重试协议在接口定义时一并确定,不宣称跨文件创建具有未实现的原子性。+恢复只处理未完成步骤,不自动删除已经成功创建的父文档。源数据清理等不可重复的后续操作,仅在业务所需步骤全部成功后进行;部分成功和单纯收到文档 ID 都不足以触发速记源数据删除。### 模板版本旧字符串保存路径继续使用原有解释规则,包括绝对与相对路径、`..`、末尾 `/`、空模板、跨笔记本上下文,以及显式名称替换末段的行为。新建语法必须有可识别的版本,不能自动将已有配置按新规则重解释。-新模板应在渲染前就确定起点、导航操作、祖先段和最终标题的边界,各标题段独立求值。变量值为 `A/B` 时,它仍是一个标题段;先渲染成单个字符串再 `split("/")` 无法满足要求。一次创建的各段使用同一份上下文和时间快照,避免求值时跨日期或上下文变化。+旧模板由兼容编译器按原语法求值,再输出结构化创建计划;另行传入的新标题保持独立,不重新拼入路径字符串。相对起点和向上导航使用当前文档 ID 及父关系,不能先把当前文档的显示路径拆成旧模板段。该内部适配不调用被新模式禁用的公开字符串寻址接口,因此已有日记等配置仍可工作。旧模板内变量产生 `/` 时继续按旧语法分层,只有显式改用新模板后才保留为单段。兼容编译保留语法,不保留任意选取同名父文档的做法;未知祖先仍执行歧义检查。-日记、块引用新建文档、速记、数据库新建条目和模板文档树必须采用同一套目标解析约定,同时保留各自的复用与提交规则。桌面端与移动端的入口都需要验证,不能仅迁移共享工具函数后便认定全部界面已兼容。+新配置分别使用 `docCreateTarget`、`refCreateTarget`、`dailyNoteTarget`,与原保存路径字符串字段并存。首版仅在已启用模式 `2` 的笔记本配置中开放这三个对象,全局配置继续保留旧字符串模板及现有继承规则,避免未经笔记本启用便引入旧客户端无法识别的配置。对象必须带 `version: 2`,指定目标笔记本、起点、向上层数、祖先段、最终标题和缺失祖先策略;各段继续复用现有保存路径模板求值器。示例中的 `{{now | date ...}}` 是保存路径模板语法,不能与正文模板语法混淆。++```json+{+ "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`,避免跨日期或上下文变化。++新对象存在时,它是相应创建目标的唯一权威配置;旧字符串仅保留为原配置记录。修改旧字段为不同值时必须返回明确的配置冲突,不能静默覆盖新对象;原样回传旧字段仍可接受。显式移除新对象后可重新使用旧模板,但不会将笔记本降回兼容模式。未配置新对象时沿用现有笔记本及全局配置选择顺序。跨笔记本的目标仍按目标笔记本模式校验标题,不能因为来源已启用模式 `2` 而绕过目标限制。++### 业务入口迁移++| 入口 | 保持的业务行为与迁移重点 |+| --- | --- |+| 普通新建及块引用新建 | 已知父 ID 直接创建;新标题独立传递,生成的引用保存文档 ID |+| 日记 | 先按日记日期属性复用;多个匹配时保留现有模板目标优先、否则按 ID 排序的规则,已有日记不重新应用正文模板 |+| 速记 | 明确追加目标或新建目标;目标持久化成功后才清理来源 |+| 数据库新建条目 | 保留属性值、绑定关系和排序;创建计划保存最终文档 ID |+| 模板文档树 | 保留预览、ID 重映射和插入顺序,提交校验预览版本并展示部分完成结果 |+| 桌面、浏览器和移动端 | 分别检查菜单、快捷键、对话框及事件处理;共享工具函数迁移不能代替各端验证 |++日记的既有复用策略是明确的业务规则,不因通用解析器拒绝歧义而改成所有同日期情况均报错;模板目标优先匹配改为结构化身份链比较。## 搜索与派生索引@@ -98,7 +198,9 @@搜索范围过滤与路径文字匹配分开。前者使用文档身份或 ID 数据路径,后者匹配标题的纯文本表示及祖先文字,不进行 `/` 与 `/` 之间的替换。返回内容中的搜索高亮标记和 HTML 是展示结果,不能回写成标题源内容,也不能在补充文档标题时覆盖已有匹配高亮。-初期可以保留 `blocks.hpath` 和 `blocktrees.hpath` 及现有批量更新机制,避免同时引入协议迁移与未经验证的存储优化。是否改为文档级标题元数据、增加独立层级字段或按需组装,由实际查询和性能结果决定;不预设为每个内容块复制完整标题段数组。+首版保留 `blocks.hpath`、`blocktrees.hpath` 及现有批量更新机制,新增前述文档级元数据作为结构化查询来源。完整祖先链按文档组装,可使用有界缓存,不为每个内容块复制完整标题段数组。插件仍能读取字符串列,但新模式下只能把它们当作显示和文字检索数据。++`RefreshDocHPaths` 通过 ID 子树和元数据重建祖先标题,不再按深度切割旧 `hPath`。`updateRootContent` 从统一标题读取结果取得文档标题,不使用 `path.Base`。稳态下重命名父文档不为取得标题而读取每篇后代的完整 `.sy`;缺失或失效元数据进入恢复流程,不能以旧显示路径补齐。重命名仍会使展示路径、祖先文字检索和相关缓存失效。源文档保存、文档元数据更新、后台批次校验与中断恢复必须保持有序,排队中的旧树不能写回过期标题或路径。按 ID 寻址消除了标题对身份的影响,不等于可以删除所有重命名更新任务。@@ -106,43 +208,144 @@导出先为每个文档身份分配唯一的相对文件路径,再用同一份映射写文件及生成文档间链接。映射必须处理标题中的斜杠、非法文件名字符、同名文档、大小写不敏感冲突、长度限制和跨笔记本同名;文件覆盖检查与链接生成不能各自临时决定文件名。+分配器先按 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`。`start` 返回起点身份及版本,`resolved` 和 `candidates` 使用 `DocumentPath`;`nextIndex` 是下一待处理段的零基索引。`status: "resolved"` 表示全部命中,`"missing"` 表示从该段开始没有文档,`"ambiguous"` 表示该段存在多个候选。候选按 ID 排序,最多返回 128 个,并用 `candidatesTruncated` 表示仍有更多结果;达到上限仍必须报告歧义,调用方改用明确父 ID,不能从截断结果中默认选择第一项。++解析最多接受 128 段,每段遵守标题长度限制,实际创建仍执行用户的文档深度限制。空字符串段失败,名称为空的已有父文档需按 ID 选定。笔记本根作为解析结果时使用明确的根位置,不伪造文档 ID;根版本覆盖笔记本身份及相关配置,不因无关子文档变化而失效。作为根位置别名的笔记本文档 ID 也使用根版本校验。错误和候选不得泄露其他笔记本的标题。++### 按父 ID 创建++`/api/filetree/createDocByParent` 的最小请求如下。示例要求目标笔记本已启用结构化标题模式。-旧字段的兼容含义必须按使用场景登记,不能仅保持字段类型为 `string` 就视为兼容。新增结构化信息使用新字段或明确的协议版本,旧接口原有输入、空值、返回变体、授权和操作租约保持各自契约。+```json+{+ "notebook": "20210808180117-6v0mkxr",+ "parentID": "20261015090000-abcdefg",+ "id": "20261015100000-hijklmn",+ "title": {"format": "plain", "text": "卷01·第一章/第二节"},+ "markdown": ""+}+```-| 使用场景 | 迁移约束 |+| 字段 | 约束 || --- | --- |-| 按 ID 读取与操作文档 | 保持身份与授权语义,增加标题或层级信息时明确其是否为纯文本 |-| `getIDsByHPath` 及旧字符串创建入口 | 保留旧语法;不能将标题内的 `/` 当成原有层级并命中错误文档 |-| `getHPathByID`、`getFullHPathByID` 等路径输出 | 分别记录是否含笔记本名称、是否供机器解析,以及与旧定位入口的往返要求 |-| `Criterion.hPath`、`SearchPath` 及搜索结果 | 区分保存的条件、显示路径、搜索范围和含高亮的展示内容 |-| 数据库、模板、资源重定位及历史差异中的路径 | 逐项确认字段用途,迁移到明确的身份或展示表示 |-| 插件 SQL 中的 `blocks.hpath`、`blocktrees.hpath` | 作为插件可见语义维护,不能直接将字符串列改成数组或静默改变层级规则 |+| `notebook` | 必填,目标笔记本 ID |+| `parentID` | 必填;文档 ID 或表示笔记本根位置的 `null`,不接受空串作为根位置 |+| `id` | 必填,由调用方预先生成并保存的有效新文档 ID;已存在时不覆盖 |+| `title` | 必填,首版仅接受普通标题对象;空字符串与缺省值不同 |+| `markdown` | 必填,允许空字符串 |+| `expectedParentRevision` | 可选,提交预览时用于校验父路径版本;根位置使用解析接口返回的根版本 |+| `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` | 目标笔记本禁用旧字符串寻址,改用新接口 |+| `indexUnavailable` | 结构化元数据未就绪,等待恢复,不回退到显示路径 |+| `unsupportedTitleFormat` | 客户端或接口不能处理标题格式,升级或改用对应格式接口 |+| `writeFailed` | 写入或后续处理失败,依据 `commitState` 及阶段恢复 |++### 读取有效创建目标++`/api/filetree/getDocCreateTarget` 接收当前 `notebook` 与 `purpose: "document" | "reference" | "dailyNote"`,复用各业务现有的配置优先级,返回生效的 `target`、`docCreateTemplatePath` 和配置 `revision`。`target` 为带 `version` 的联合类型:旧模板返回 `{version: 1, notebook, path}`,新模板返回上文完整的版本 `2` 对象。接口只读取配置,不执行模板、不猜测当前文档或当前日期;调用方随后提供上下文生成计划。++旧 `/api/filetree/getDocCreateSavePath` 在生效配置仍为旧模板时保持原响应;新对象生效时返回 `code: -1`、`data: {reason: "structuredTemplateRequired"}`,不返回已经失效的旧路径。该错误变体在旧契约中明确声明。新增读取入口同时服务内置调用方和插件,避免各自重复实现配置继承规则。++### 能力探测与启用++在 `/api/notebook/getNotebookConf` 的 `data` 中增加可选只读对象 `documentCapabilities`,保留现有 `box`、`name`、`conf` 和权限过滤。对象包含 `addressingVersion`、`structuredPaths`、`literalSlash`、`titleFormats`、`indexState`、`minimumReaderVersion` 和 `revision`。`structuredPaths` 表示服务端实现了新协议,`indexState` 表示该笔记本是否可用;两者不能混为一谈。首版 `titleFormats` 为 `["plain"]`,`literalSlash` 仅在模式 `2` 且索引就绪时为 `true`。++`revision` 是启用流程相关的配置版本;它不等同于某篇文档的路径版本。能力声明不授予访问权限,关闭或锁定笔记本时仍执行原有访问限制;状态读取不得暴露标题或受保护的模板内容。旧服务端没有该对象时,插件只能使用旧能力。鉴权、锁定或网络请求失败不能被当作“服务端不支持”,更不能据此回退后继续写入。++`/api/notebook/enableStructuredTitles` 接收 `notebook` 与 `expectedRevision`,核查当前配置版本、索引状态和客户端本地兼容能力后持久化模式 `2`,返回最新 `documentCapabilities`。已经启用且版本匹配时可直接返回当前状态。此接口不能证明所有离线同步客户端都已升级;启用界面需要说明最低版本和插件适配要求,由用户明确启用。通用配置更新不能绕过此流程切换模式,省略新字段的旧请求也不能将模式重置为 `1`。++### 契约及声明维护++实现遵循 [内核接口类型契约](API-CONTRACTS.zh-CN.md):在 `kernel/apicontract/` 定义声明,使用 `contractHandler` 绑定,生成类型并同步 Petal 维护声明及变更记录。新增接口的详细规则放在对应契约注释中。已有接口行为受影响时检查并同步中、英、日 API 文档中的既有条目,不自动把新接口追加到 API 参考文档,也不向契约维护指南添加本特性的接口说明。++## 接口与插件兼容++模式 `1` 为兼容模式;模式 `2` 为显式启用的结构化标题模式。没有模式字段的旧笔记本按 `1` 读取。模式决定旧协议是否可用,不根据某一次请求是否恰好包含 `/` 猜测。++| 使用场景 | 兼容模式 `1` | 结构化标题模式 `2` | 插件迁移方式 |+| --- | --- | --- | --- |+| 按 ID 读取、移动及删除 | 保持现有契约 | 保持身份、权限及返回变体 | 继续使用 ID,移动后重新读取当前位置 |+| 按 ID 重命名及 ID 数据路径创建 | 保持现有标题规则 | 普通标题可保留 `/`,仍验证模式和标题格式 | 标题与位置分开传递;未知富文本格式不能用纯文本覆盖 |+| `getIDsByHPath` | 保留原名称路径语法 | 整个笔记本拒绝,返回 `legacyPathUnsupported` | 已知 ID 直接使用;未知位置调用 `resolveDocPath` |+| `createDocWithMd` | 保留旧语法及 `parentID` 回退行为 | 整个笔记本拒绝,即使传入 `parentID` | 改用 `createDocByParent`,不提交字符串路径 |+| `getHPathByID`、`getHPathByPath` | 保留现有输出 | 按祖先标题原文拼接,只可显示 | 获取结构时改用 `getDocPaths` |+| `getFullHPathByID` | 保留含笔记本名称的输出及空值规则 | 仍显示笔记本名称,不能反向定位 | 笔记本名称与文档段分别展示 |+| `blocks.hpath`、`blocktrees.hpath` | 保留列类型及原行为 | 仍是字符串,可能包含无法区分的标题斜杠 | 子树查询使用 ID `path`,标题读取文档行 `content`,父级及深度通过结构化接口取得 |+| `Criterion.hPath`、`SearchPath`、搜索结果 | 保留既有配置和高亮语义 | 显示文字仍可检索,范围与层级使用 ID | 不把高亮文本或路径显示值重新提交为位置 |+| 旧保存路径模板 | 原语法运行 | 通过内部兼容编译器生成结构化计划 | 需要变量中的 `/` 保持单段时显式使用版本 `2` 模板 |+| `getDocCreateSavePath` | 保留旧配置结果 | 旧模板仍返回原结果,新模板返回 `structuredTemplateRequired` | 通过 `getDocCreateTarget` 读取生效的带版本配置 |-对原有标题可表达的数据,兼容入口继续维持既有行为。包含新标题能力的数据不能保证经过旧路径字符串无损往返时,旧寻址与写入入口必须返回明确的不支持或歧义错误,不得猜测目标或静默替换字符。旧读取结果和 SQL 列如何呈现这类数据,需要在开放该能力前形成逐项兼容矩阵;未确定时继续限制新标题的写入。+不改变旧字段的数据类型,不删除旧 API,也不把模式 `2` 的显示路径编码后伪装成可兼容地址。新模式下两个不同结构可以显示为相同字符串;SQL 的等值 `hpath` 查询也可能返回两种结构。继续按分隔符计数、取末段或做前缀子树查询的插件必须适配,这是启用能力的兼容成本。-现有标题中的 `/`、`%2F` 等均按字面数据处理,不能推测用户是否曾采用某种转义。若特定对外通道需要可逆编码,必须定义版本和独立适配边界,不能把该编码重新引入内部文档身份或标题源内容。+旧字符串接口在模式 `2` 下新增明确的错误变体:`code: -1`、`data: {reason: "legacyPathUnsupported"}`。该变体需在原接口契约中声明并保留错误数据;模式 `1` 下既有成功、空值及错误返回保持不变。不能只改错误文案却让插件通过匹配本地化文字判断能力。-实际新增或修改 HTTP 接口时遵循 [内核接口类型契约](API-CONTRACTS.zh-CN.md),在契约声明中记录行为、默认值、限制和兼容规则,并同步 Petal 中对应的维护声明及变更记录。生成类型不能代替语义兼容评审。弃用旧字段需要明确替代方式和过渡规则,不能与开放新标题字符同时直接删除。+现有标题中的 `/`、`%2F` 等均按字面数据处理,不推测历史编码意图。若特定对外通道需要可逆编码,必须使用独立版本和适配边界,不能把该编码引入内部身份或标题源内容。++插件迁移顺序为能力探测、按 ID 读取目标、按结构化规则解析未知祖先、按父 ID 创建、使用返回 ID 操作。发布替代接口时同时提供上述迁移矩阵和最小示例;开放模式 `2` 前完成内置调用方迁移。服务端无法识别所有插件 SQL 及其后续用途,不能宣称会自动阻止全部插件误用显示字符串。## 版本、加密与恢复### 混合版本访问-即使 `.sy` 仍保存字符串标题,旧客户端也可能在规范化时移除 `/`,或在构建 `hPath` 时把标题文字当作层级。仅重建索引不能解决这些行为。开放新字符前,必须确定最低兼容客户端、同步访问限制和必要的文档格式版本保护,并验证编辑、导入、历史恢复及备份恢复入口。+笔记本配置新增 `documentAddressingVersion`,缺省或 `1` 为兼容模式,`2` 为结构化标题模式。该字段与加密信封版本独立,不能复用 `BoxCrypt.Spec`。新旧模式不批量改写已有文档标题或 ID;开启能力只改变后续操作准入和新内容的表示规则。++即使 `.sy` 仍保存字符串标题,旧客户端也可能移除 `/`,或把标题文字当作层级。发布分两步:先发布理解笔记本能力标记、能够安全拒绝未知模式的保护版本,再发布允许启用模式 `2` 的功能版本。保护版本在挂载、索引、修复、编辑及同步应用入口拒绝处理不支持的模式,不能先修改数据再提示升级。++真正使用新标题能力的文档采用新的 `DocumentTitleSpec`;具体数值在实现时按当时已使用的 `.sy` 版本分配,不在草案中预占某个数字。未使用新能力的文档不因笔记本启用而全部改写。未来富文本表示还需对应的明确格式版本,未知内容不得被容错解析后覆盖。-现有 `Spec` 检查可以作为评估版本保护的基础,但不能假定所有已发布客户端和全部入口都会执行检查。未证明能够安全拒绝或正确读取的旧版本,不得宣称与新标题兼容。未来富文本标题同样必须有显式格式版本,并防止未知内容被容错解析后覆盖;已有普通标题和受支持的旧格式继续可读。+版本保护必须覆盖完整读取、仅属性读取、只读路径恢复、导入、历史、备份及同步。当前 `readDocIAL` 的非严格分支不会执行与严格分支相同的 `CheckSpecJSON` 检查,不能仅在普通编辑加载处添加检查就认为完整受保护。源文档版本要求模式 `2` 而配置仍为 `1` 时,先报告模式冲突;导入只能在明确选择启用后继续,不能偷偷清理标题以适配旧模式。++最低兼容版本由真实发布版本的读写及拒绝测试确定。保护版本之前忽略能力标记的客户端无法由新字段自动约束,不在安全混用承诺内。启用前要求所有同步设备升级;系统无法证明离线设备状态,应明确说明这一限制。如果已支持版本仍存在会改写数据的路径,保持新能力关闭,不能以文档提示代替必要保护。++模式 `2` 启用后不提供直接改回 `1` 的开关。即使当前标题已不含 `/`,历史和备份仍可能包含新格式。回退客户端只能使用经验证的兼容导出副本,或恢复启用前的完整备份到独立工作空间;不能将旧配置覆盖回原工作空间并继续同步。若未来提供降级转换,应另行设计转换清单、冲突处理和恢复机制,保留原数据。### 索引与任务恢复-派生索引迁移应有明确版本,并覆盖完整重建、增量更新及中断后的恢复。恢复以源文档和当前 ID 位置为依据,不能从旧 `hPath` 猜测标题,也不能因缺失父文档而自动补建源文件。重建只在确认源数据有效后更新对应派生状态,失败时保留可恢复的任务与源文件。+`document_metadata` 使用独立的派生索引版本及笔记本状态 `missing`、`building`、`ready`、`error`。新建表后从源文档和 ID 位置构建,不从旧 `hPath` 推测段边界。构建期间记录增量变更并在切换前追平;只有全量扫描和增量校验完成,才将对应代次标记为 `ready`。++兼容模式下旧功能在重建期间保持既有行为,新结构化接口在需要的数据未就绪时返回 `indexUnavailable`。模式 `2` 下不能因索引损坏回退到旧名称定位;按现有源读取路径恢复,结构化写入等待必需元数据就绪。不存在的父源文件不能自动补建,损坏源文件不能靠索引中的旧标题覆盖。++更新顺序为源文档持久化、同一块树数据库事务内更新文档元数据和对应文档行、提交后续 `hpath` 批次。源文件与数据库、块树库与内容库之间不宣称原子事务。任一步骤中断都保留恢复标记;重新启动或解锁后先验证源版本及当前 ID 位置,再继续派生更新。快照版本、移动或删除检测使排队中的旧树失效,不能恢复旧标题。现有 `temp/queue/hpath-refresh.queue` 只保存笔记本 ID、文档 ID 和 ID 数据路径。迁移不得将标题段、富文本标题或正文写入这个全局明文队列。并发重命名、移动、删除、同步及普通索引重建仍需校验任务是否过期,不能误清理尚未完成的加密笔记本恢复任务。+为防止源文件已写入而恢复任务尚未登记时崩溃,变更前先持久化仅含身份的待核对标记,或使用已有能覆盖该窗口的持久事务记录;相关实现必须用故障注入证明可恢复。任务完成后再清理标记,重复恢复应得到同一派生结果。加密笔记本未解锁时保留任务,不能为了清空队列而跳过认证。+### 加密兼容已有加密数据是兼容基线,遵循 [加密笔记本](ENCRYPTED-NOTEBOOK.zh-CN.md) 的认证读取、隔离及恢复要求。标题源内容、纯文本标题和祖先链都属于受保护的文档内容;读取、缓存和响应必须处于对应笔记本的授权范围及操作租约内,锁定后按现有生命周期清理。@@ -151,42 +354,76 @@本方案的内部解耦不要求更改加密信封、AAD 或密钥派生。后续若涉及这些格式,必须另有显式版本、认证迁移和中断恢复设计,并保留匹配的密钥与备份材料。不得重新生成 `MasterSalt`、丢弃密钥或要求用户重建已有加密笔记本来规避兼容问题。文档、历史、备份和同步快照中的受支持格式必须持续可恢复。-## 实施依赖+## 实施拆分与开放条件++| 阶段 | 交付内容 | 完成条件 |+| --- | --- | --- |+| A:兼容保护 | 笔记本能力标记、未知模式及源版本保护、旧行为回归样本 | 已发布保护版本;未知模式在所有写入与修复入口安全拒绝 |+| B:内部解耦 | 统一标题读取、文档元数据、ID 层级计算、路径刷新及恢复 | 普通标题行为不变;结构不再从显示字符串推导,加密索引可认证重建 |+| C:接口与调用方 | 新读取、解析、创建接口,版本 `2` 模板,内置业务及各端迁移 | 新旧契约通过验证,部分失败可恢复,日记等业务行为保持 |+| D:开放新字符 | 模式启用入口、旧接口拒绝规则、插件迁移说明、导入导出和跨版本验证 | 全部开放条件满足后才允许用户显式启用 `/` |+| E:行级标题 | 独立的源格式、编辑及渲染设计 | 保持本方案身份接口,完成格式及旧写入保护后另行交付 |++阶段 B、C 可以在保留旧标题限制时先行交付;新字符的开放必须等待 A 至 D 所需条件全部成立。阶段 E 不作为基础解耦的前置依赖,也不能在 A 至 D 中重新引入只接受永久纯文本来源的假设。++开放条件包括:所有内置消费者已迁移;替代接口和插件适配文档已发布;已验证最低客户端版本及混合版本拒绝;普通与加密索引迁移可中断恢复;导入导出不会因显示路径冲突覆盖文件;桌面、浏览器和移动端行为一致;四种语言的用户指南说明启用方式、插件影响和同步设备要求。-1. 建立标题读取与结构化层级边界,统一按文档身份校验归属和创建目标;此时保留现有标题输入规则及对外协议-2. 迁移创建、模板、搜索、索引、导入导出和桌面及移动端消费者,补齐同名文档、并发修改与恢复行为-3. 完成旧接口及 SQL 兼容矩阵、模板版本、混合客户端保护和验收后,再开放标题中的 `/`;同步插件声明及四种语言的用户指南-4. 根据实测结果决定缓存和索引布局优化;富文本标题在上述扩展约束下独立设计与实现+实施时还需登记实际发布版本号、分配未冲突的 `.sy` 版本号,并附上性能测量与兼容测试结果。这些是发布证据,不是重新悬置身份、模板、插件边界或失败语义的决策。本文中的接口和字段需落实为可验证契约,不能以完成文档或一次索引重建代替功能验收。-开放新字符前仍需确定旧路径输出及 SQL 对新标题的具体表示、结构化创建与模板的最终契约、部分创建的重试协议、最低客户端版本及保护机制。上述决策必须落实到对应接口或格式定义和回归用例,不能以修改本文或完成索引重建代替。+## 验证与验收-## 验证范围+### 行为矩阵| 范围 | 必须覆盖的场景 || --- | --- || 标题内容 | `/`、`/`、连续斜杠、`%2F`、`.`、`..`、空标题、Unicode 和长度边界;原字符不发生未经约定的转换 || 身份与层级 | 单标题 `A/B` 与两级 `A`、`B`,同父同名、不同父同名、重复 ID 的归属校验、根位置及笔记本文档 |-| 创建与并发 | 父文档重命名、移动、删除、关闭或锁定;预览失效、多级创建部分失败和重试;普通新建与复用语义 |+| 创建与并发 | 直接按 ID 跟随父位置及带版本请求拒绝过期预览;父文档删除、跨笔记本移动、关闭或锁定;响应丢失、部分提交、固定 ID 冲突及多级恢复 || 模板 | 旧语法全部边界、新语法逐段渲染、变量包含 `/`、相对操作、同一时间快照、日记与速记等入口 || 搜索与展示 | 原始标题字符检索、祖先文字检索、ID 范围过滤、标题高亮、面包屑段边界、复制文字与 ID 链接 || 索引与恢复 | 深层子树、父子连续重命名、旧编辑快照、批次中断、重启、移动、删除、同步及普通与加密索引迁移 || 导入导出 | 重名、非法文件名、大小写冲突、路径越界、相对链接、跨笔记本引用、标题元数据及无损往返承诺 |-| 旧接口与插件 | 旧字段含义、空值和返回变体、SQL 层级假设、旧字符串往返、新标题的明确失败及替代入口 |+| 旧接口与插件 | 模式 `1` 旧返回不变;模式 `2` 整个笔记本拒绝旧寻址;SQL 显示字符串碰撞、结构化替代接口、能力缺失与请求失败的区别 || 旧客户端与加密 | 支持的历史格式样本、混合版本同步、认证失败、锁定期间的缓存和响应、历史及备份恢复、密钥材料保留 || 行级元素扩展 | 现有 Markdown 样式文字保持字面含义;标题表示变化不影响身份与层级;纯文本相同不合并文档;格式与纯文本来源单向派生 || 跨端与性能 | 桌面、浏览器和移动端创建及重命名;大子树下的前台延迟、数据库批次时间、内存、CPU 和磁盘读写 |-性能评估需要与现有重命名、查询和索引机制比较,分别记录前台响应与后台处理,不能以含调度等待的总耗时代替数据库耗时。行为回归应纳入现有前端和内核测试发现范围;新格式启用前使用受支持旧格式的实际样本验证读取、导出、历史、备份和恢复。+### 关键回归用例++保留 `TestCreateDocsByHPathUsesParentIDForDuplicateHPath` 和 `TestCreateDocsByHPathKeepsHPathFallbackForDifferentParent`,证明旧兼容入口没有被新规则悄悄替换。另为新入口覆盖父标题变化后仍使用原 ID、父跨笔记本移动后拒绝、同名父文档不会被误选,以及带版本提交返回 `planChanged`。++同时建立根文档 `A/B`、根文档 `A` 及其子文档 `B`、根文档 `A/B`、根文档 `A%2FB`。前两者允许相同显示路径,但 ID、`segments`、`depth`、子树范围和导出链接必须各自正确;后两者不得被转换成前两者。增加重复斜杠、点段、空标题、大小写差异和相同纯文本不同标题格式的样本。++实际 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`。++只有既有发现机制不能覆盖新用例时才调整持续集成筛选或维护指南。以上是实施验收要求,并非本设计文档已执行的功能测试;文档修改本身检查双语一致性、示例、链接及差异格式。## 相关代码| 范围 | 入口 || --- | --- || 创建、重命名、标题规范化及按名称解析 | [`model/file.go`](../kernel/model/file.go)、[`model/path.go`](../kernel/model/path.go) |+| 接口、模式配置与契约 | [`api/filetree.go`](../kernel/api/filetree.go)、[`api/notebook.go`](../kernel/api/notebook.go)、[`apicontract/filetree_remaining.go`](../kernel/apicontract/filetree_remaining.go)、[`conf/box.go`](../kernel/conf/box.go) || 源文档与只读路径恢复 | [`filesys/tree.go`](../kernel/filesys/tree.go)、[`filesys/hpath.go`](../kernel/filesys/hpath.go) |-| 路径刷新、恢复队列与文档索引 | [`treenode/hpath.go`](../kernel/treenode/hpath.go)、[`model/hpath_refresh.go`](../kernel/model/hpath_refresh.go)、[`sql/queue.go`](../kernel/sql/queue.go) |+| 路径刷新、恢复队列与文档索引 | [`treenode/blocktree.go`](../kernel/treenode/blocktree.go)、[`treenode/hpath.go`](../kernel/treenode/hpath.go)、[`model/hpath_refresh.go`](../kernel/model/hpath_refresh.go)、[`sql/queue.go`](../kernel/sql/queue.go) || 搜索及层级计算 | [`model/search.go`](../kernel/model/search.go)、[`sql/block_query.go`](../kernel/sql/block_query.go)、[`search/config.ts`](../app/src/search/config.ts) || 新建入口与保存路径解析 | [`util/newFile.ts`](../app/src/util/newFile.ts)、[`util/parseNewDocTarget.ts`](../app/src/util/parseNewDocTarget.ts)、[`mobile/util/initFramework.ts`](../app/src/mobile/util/initFramework.ts) || 模板、数据库新建及速记 | [`model/template_doc_tree.go`](../kernel/model/template_doc_tree.go)、[`model/attribute_view_new_item.go`](../kernel/model/attribute_view_new_item.go)、[`model/shortcuts.go`](../kernel/model/shortcuts.go) |+| 日记复用及旧创建回归 | [`model/daily_note.go`](../kernel/model/daily_note.go)、[`model/file_test.go`](../kernel/model/file_test.go) || 导入与导出 | [`model/import.go`](../kernel/model/import.go)、[`model/import_obsidian.go`](../kernel/model/import_obsidian.go)、[`model/export.go`](../kernel/model/export.go) |+| 可复用的富文本来源校验模式 | [`treenode/table_cell_rich.go`](../kernel/treenode/table_cell_rich.go) || 文档版本 | [`treenode/tree.go`](../kernel/treenode/tree.go)、[`.sy` 文件结构](SY-FORMAT.zh-CN.md) |