Orqestria Letöltés
← Belső rendszer fejlesztők adatlapja

Skill · 1.0.0 verzió

Dokumentumformátumok és migráció

Megőrzi a szerkeszthető dokumentum jelentését mentés, formátumváltás és export során, az aktuális szerkesztő számára ismeretlen tartalommal együtt.

document-serialization-migration

Ezt a skillt használó csapattagok

Nézd meg, miben segít

Mikor hasznos?

Akkor használd, ha a dokumentum több szerkesztőverziót túlél vagy gazdag és egyszerűbb formátumok között mozog.

Miben segít neked?

  • Elkülöníti a szerkeszthető forrást a származtatott exporttól.
  • Megőrzi az ismeretlen blokkokat és ellenőrzi a verziózott sémát.
  • Teszteli a determinisztikus migrációt és import-export hűséget.

Például ezt kérheted

Frissíts dokumentumformátumot az újabb szerkesztő blokkjainak megőrzésével. Nyiss ismeretlen diagramblokkot tartalmazó dokumentumot, szerkessz bekezdést és ments. A diagram eredeti adatai változatlanul maradjanak meg az újranyitásig.

Részletes dokumentáció

Itt a skill eredeti útmutatóját, példáit és ellenőrzési szempontjait olvashatod az eredeti nyelven.

Részletek…Összecsukás

Document Serialization & Migration

Use this skill when designing saved document JSON/AST formats, validating persisted editor payloads, migrating legacy document versions, or generating HTML/Markdown/PDF/email exports.

Separate Editable Source Document from Derived Exports

  1. Persist the Structured Source Model, Not Rendered Output:
    • Always save the canonical structured document (schemaVersion, root blocks, attributes, marks) as the authoritative source of truth.
    • Treat rendered HTML, email MJML/table HTML, Markdown, PDF, or plain-text search indexes as derived outputs generated from the structured document. Never try to reconstruct complex editor state by reverse-parsing exported presentation HTML when a structured format exists.
  2. Explicit schemaVersion & Server/Client Validation:
    • Include an explicit integer schemaVersion at the root of every persisted document and local draft.
    • Validate document payloads on load and on server save: verify required node fields, valid block types, allowed nesting, and attribute types.

Safe Schema Evolution & Unknown-Block Preservation

  • Never Silently Drop Unsupported or Newer Block Types:
    • When an older client or partial editor loads a document containing a block type or attribute it does not yet recognize (or a plugin that is disabled), preserve the unknown block's raw data intact in an inert UnsupportedBlock / passthrough wrapper node rather than stripping it on load and deleting the user's content on the next autosave.
  • Deterministic Version Migrations (v1 -> v2 -> v3):
    • Implement pure, idempotent migration functions per version step (migrateV1ToV2(doc)), tested with representative real-world documents.
    • Separate read-time migration from silent write-back: do not mark a newly opened document as dirty or overwrite the server record with a migrated format without explicit version tracking or user edit.

Export Fidelity & Round-Trip Safety

  • When importing/exporting Markdown, HTML, or email templates, document accurately which rich blocks degrade gracefully in target formats (e.g., interactive callouts or multi-column layouts in email clients) and test round-trip serialization (parse(serialize(doc))) for all supported blocks.

Checklist

  • Does every persisted document carry an explicit schemaVersion separate from derived HTML/Markdown/email exports?
  • Are unrecognized or newer block types preserved in a safe passthrough node rather than silently deleted on load/save?
  • Are format migrations pure, step-by-step, and tested against legacy document fixtures?
  • Does loading and migrating a document avoid falsely marking the editor as modified before the user edits?

Csomagban lévő fájlok 1

  • SKILL.md