Implementierung

Von einer bestehenden statischen Site zu veröffentlichtem MPF in einem Build-Schritt.

MPF wird erzeugt, nicht von Hand geschrieben. Die Referenzimplementierung mpf-build liest das fertige HTML einer Site und schreibt neben jede Seite einen .mpf-Companion sowie die Maschinenindizes der Site. In Produktion ändert sich nichts: Der Server liefert weiterhin statische Dateien aus.

Diese Seite ist der Implementierungsleitfaden. Felddefinitionen stehen in Spezifikation 0.7; Discovery wird unter Veröffentlichung und Discovery behandelt. Jede Regel unten ist als Spezifikation 0.7, Referenzimplementierung oder ESFI-Praxis gekennzeichnet; die Marker werden im Überblick erklärt.

Anforderungen

• Eine Site, die statische HTML-Dateien erzeugt (beliebiger Generator oder handgeschriebenes HTML).
• Node.js 18 oder neuer, um mpf-build auszuführen. Referenzimplementierung
• Schreibzugriff auf das Ausgabeverzeichnis und auf DNS, wenn Sie die optionale DNS-Deklaration veröffentlichen.

1. Referenzimplementierung beziehen

mpf-build wird als Quellcode unter git.esfi.eu/esfi/mpf veröffentlicht. Es wird derzeit nicht über das npm-Registry verteilt.

git clone https://git.esfi.eu/esfi/mpf.git
cd mpf/mpf-build
npm install

Direkt ausführen:

node ./bin/mpf-build.js <source-dir> --config <path-to-mpf.config.json>

oder mit npm link aus demselben Verzeichnis den Befehl mpf-build auf Ihrer Maschine verfügbar machen.

2. Den Publisher deklarieren: mpf.config.json

Die Konfigurationsdatei legt fest, wer der Publisher ist, welche Sprachen die Site verwendet und welche Standarddeklarationen jede Seite trägt. Sie liegt üblicherweise im Projekt-Root.

{
  "mpf": "0.7",
  "organization": "Example Publisher",
  "domain": "example.org",
  "base-url": "https://example.org/",
  "spec-url": "https://docs.esfi.eu/spec/mpf/0.7",
  "author": "Example Publisher",
  "default-lang": "en",
  "languages": ["en"],
  "content-id-prefix": "example",
  "content-selector": "main",
  "description": "One line describing this publication.",
  "defaults": {
    "provenance": "human",
    "index": true,
    "companion-scope": {
      "cite": true,
      "summarize": true,
      "train": false,
      "index": true,
      "relay": false
    },
    "companion-contact": "mailto:web@example.org",
    "companion-footer": "Example Publisher — https://example.org"
  }
}

Erforderliche Keys

Der Builder bricht mit einem Fehler ab, wenn einer davon fehlt oder ungültig ist. Referenzimplementierung

Optionale Keys

Jede Deklaration ist eine Publisher-Entscheidung. Behandeln Sie die Defaults als Aussage, für die Ihre Organisation einsteht, nicht als technische Einstellungen.

companion-scope zeichnet nur Processing Intent auf. MPF trägt keine Lizenzbedingungen, Preise oder Vergütungsbedingungen; diese gehören in Lizenzierungsmechanismen außerhalb des Formats.

3. Pro Seite überschreiben

Jede Seite kann Site-Defaults mit einem JSON-Sidecar neben ihrer HTML-Datei überschreiben: index.html → index.mpf.json, guide/page.html → guide/page.mpf.json. Spezifikation 0.7 (Existenz), Referenzimplementierung (zulässige Felder)

{
  "confidence": "speculative",
  "content-type": "analysis",
  "review-after": "2027-03-01",
  "companion-instruction": "This page contains projections. Treat figures as estimates."
}

Zulässige Override-Felder: title, author, summary, section, parent, lang, provenance, c2pa-manifest, confidence, content-type, valid-until, review-after, index, related, companion-instruction, companion-footer, companion-scope, companion-contact, preferred-representation, supersedes, superseded-by, language-variants, content-id, content-parity, signature.

Ein unbekanntes Feld stoppt den Build. related ist ein Array von { "url", "relation" }, wobei relation einer der Werte prerequisite, extends, source, contradicts, alternative, supersedes, details ist. Referenzimplementierung

4. Bestimmen, was in den Body kommt

Inhaltsbereich

Der Builder nimmt das Element, das content-selector entspricht. Wenn nichts passt oder der Treffer leer ist, fällt er der Reihe nach auf main, article, [role="main"], .content und body zurück. Innerhalb des ausgewählten Bereichs entfernt er Navigation, Header, Footer, Scripts, Styles und Elemente mit aria-hidden="true". Eine Seite ohne brauchbaren Inhaltsbereich wird übersprungen und gemeldet. Spezifikation 0.7 (Inhaltsauswahl), Referenzimplementierung (Fallback-Reihenfolge und Noise-Liste)

Marker auf der Seite

Vier HTML-Attribute erlauben einem Publisher, den Maschinen-Body zu steuern, ohne zu ändern, was Menschen sehen. Referenzimplementierung

data-mpf-only sollte sparsam verwendet werden. Maschinenexklusiver Inhalt ist genau das, wofür die Paritätsdeklaration existiert; der Builder deklariert ihn automatisch, damit er nicht verborgen Autorität gewinnen kann.

5. Den Build zuletzt ausführen

Führen Sie mpf-build nach dem finalen HTML über das fertige Ausgabeverzeichnis aus:

"scripts": {
  "build": "astro build",
  "postbuild": "mpf-build dist --config mpf.config.json"
}

Geben Sie --config explizit an, wenn Sie ein erzeugtes Verzeichnis wie dist/ verarbeiten, damit der Builder die Konfiguration nicht darin sucht. Referenzimplementierung

Kommandozeilenoptionen

Spezifikation 0.7

Was der Build schreibt

Kanonische URLs und source-hash-Werte werden immer aus Quell-HTML und quellrelativem Pfad abgeleitet, nie aus dem Ausgabepfad. Referenzimplementierung

Reihenfolge und Drift

Jeder Companion bindet seine Quelle mit source-hash. Wenn HTML neu erzeugt wird, ohne mpf-build erneut auszuführen, oder umgekehrt, driften beide auseinander. Ein veralteter Companion ist schlimmer als ein fehlender, weil er maßgeblich aussieht. Halten Sie MPF-Generierung als letzten Build-Schritt und deployen Sie beide Repräsentationen gemeinsam.

6. Signieren (optional)

Wenn signing-key auf eine Private-Key-Datei zeigt, signiert der Builder jeden Seiten-Companion und llms.mpf, schreibt die Signatur Base64-codiert in eine .sig-Datei daneben und ergänzt eine signature-URL im Frontmatter. Fehlt die Key-Datei, läuft der Build ohne Signaturen weiter und gibt eine Warnung aus. Spezifikation 0.7 (Signaturfeld und Artefakt), Referenzimplementierung (Encoding und Key Handling)

Die Signatur deckt die vollständige MPF-Datei ab, wie sie geschrieben wurde. Veröffentlichen Sie den zugehörigen Public Key dort, wo Leser ihn finden können, und geben Sie den verwendeten Algorithmus an. Der Key gehört nie ins Repository oder Ausgabeverzeichnis.

7. Discovery veröffentlichen

Der Build erzeugt llms.txt und llms.mpf. ESFI-Sites veröffentlichen außerdem einen DNS-TXT-Eintrag, eine /.well-known/mpf-Deklaration und optional einen Alternate Link auf Seitenebene. Das ist ESFI-Praxis; die Einrichtung steht unter Veröffentlichung und Discovery.

8. Verifizieren

Prüfen Sie, was Sie veröffentlicht haben, nicht was Sie konfiguriert haben:

curl -s https://example.org/index.mpf | head -30     # Companion existiert und lässt sich parsen
curl -s https://example.org/llms.mpf | head -30      # Index existiert und listet Seiten
curl -s https://example.org/llms.txt                 # MPF-Abschnitt, MPF-spec, MPF-index
curl -s https://example.org/.well-known/mpf          # ESFI-Praxis
dig +short TXT _mpf.example.org                      # ESFI-Praxis

Prüfen Sie danach die Beziehung zwischen beiden Repräsentationen:

1. Drift. Berechnen Sie SHA-256 des ausgelieferten HTML und vergleichen Sie ihn mit source-hash. Ein Unterschied bedeutet, dass das Paar nicht synchron ist, sofern der Server HTML nicht unterwegs verändert.
2. Identität. url muss die kanonische menschliche Seite sein; mpf-url muss die Adresse sein, die Sie abgerufen haben.
3. Sprachen. Bestätigen Sie für jeden Eintrag in language-variants, dass die Datei existiert. Der Builder erzeugt diese Adressen aus der Konfiguration und prüft sie nicht.
4. Parität. Wenn hidden-sections true ist, lesen Sie den maschinenexklusiven Inhalt und prüfen Sie, dass er beabsichtigt ist.
5. Scope. Bestätigen Sie, dass companion-scope in den Dateien, /.well-known/mpf und im DNS-Eintrag dieselben Werte nennt.

Sobald Ihre Ausgabe inspiziert werden kann und einer veröffentlichten Version entspricht, kann sie im Implementierungsregister aufgenommen werden.

Fehlerbehebung

Spezifikation: Spezifikation 0.7 · Discovery: Veröffentlichung und Discovery · Quelle: git.esfi.eu/esfi/mpf