Einen deterministischen Ausschnitt eines Workspace mit Perspectives exportieren

Auch auf: English, Español, Português, 日本語, Français, 한국어, 简体中文, Italiano, हिन्दी · Alle Anleitungen auf Deutsch

Offenlegung: Wir entwickeln Carbon Forge bei 100monkeys.ai, lesen Sie dies also als Bericht des Herstellers. Einer unserer KI-Agenten hat diese Anleitung aus der öffentlichen Dokumentation (auf Englisch) entworfen, vor allem Perspectives: beam angles through one workspace und dem Abschnitt Perspectives in Source control settings, das Unternehmen hat sie geprüft; diese deutsche Fassung ist eine Übersetzung der englischen Originalanleitung. Die Perspective und die Aufrufe sind die Beispiele der Dokumentation. Wo die Dokumentation eine Frage offenlässt, sagt es der letzte Abschnitt.

Was eine Perspective ist

Die Dokumentation: "A perspective is a named lens through that record. It picks out a part of it, by kind, surface, path, media type, tag or metadata, and answers that part at paths of its own." (Eine Perspective ist eine benannte Linse auf diesen Datensatz. Sie wählt einen Teil davon aus, nach Art, Oberfläche, Pfad, Medientyp, Tag oder Metadaten, und liefert diesen Teil unter eigenen Pfaden.) Und: "Nothing is copied to make one." (Um eine zu erstellen, wird nichts kopiert.) Zwei Eigenschaften zählen für einen Export. Sie ist in ihrer Reichweite nur lesend: "A perspective never discloses. It narrows what the reader already reads and never widens it." (Eine Perspective legt nie etwas offen. Sie engt ein, was die lesende Person schon liest, und erweitert es nie.) Und ihr Download ist deterministisch: "The same ref through the same perspective gives the same bytes." (Dieselbe Ref durch dieselbe Perspective ergibt dieselben Bytes.)

Schritt 1. Die Perspectives auflisten, die der Workspace auflöst

Rufen Sie perspectives.list auf. Jeder Workspace hat eingebaute: all, code, docs, adrs, internal, public (genau das, was eine anonyme Leserin bekommt) und eine tree:<path> pro Code-Tree, mit diesem Tree als Wurzel. Eine Instanz-Administratorin kann instanzweite hinzufügen, und die eigenen des Workspace kommen zuletzt; "The nearest layer wins" (die nächstgelegene Ebene gewinnt). Jede Antwort nennt ihre source und die Quellen, die sie overrides. Passt schon eine eingebaute, springen Sie zu Schritt 3.

Schritt 2. Eine eigene auf der Seite .perspectives schreiben

Die Perspectives eines Workspace stehen auf der reservierten Seite .perspectives, als eingezäunter JSON-Block oder als Tabelle. Das Beispiel der Dokumentation, gekürzt auf eine Perspective:

{
  "perspectives": [
    {
      "name": "api",
      "title": "API service",
      "description": "The api tree's source and README, without generated files.",
      "include": [
        { "kinds": ["tree"], "paths": ["/services/api/src", "/services/api/README*"] }
      ],
      "exclude": [{ "paths": ["*.generated.ts"] }],
      "root": "services/api"
    }
  ]
}

Eine Regel passt, wenn jedes Feld passt, das sie nennt; include nimmt alles, worauf irgendeine Regel passt, und exclude entfernt alles, worauf irgendeine Regel passt, "even when an include rule matched it" (selbst wenn eine include-Regel darauf gepasst hat). Pfade sind Globs im Stil von gitignore und dürfen nicht mit ! beginnen. Ist root gesetzt, wird die Wurzel von jedem Pfad abgeschnitten, sodass diese Perspective src/main.ts und README.md liefert. Code-Trees werden Datei für Datei beurteilt. Vorlagen wie monorepo, service, library oder docs-site können die Seite über perspectives.adopt für Sie schreiben, oder über Adopt unter Settings, Workspace, Source control.

Eine fehlerhafte Zeile wird nicht übersprungen. "When the page cannot be read, every perspective read in the workspace is refused, quoting the page's first bad row, until it is fixed." (Wenn die Seite nicht gelesen werden kann, wird jeder Perspective-Lesezugriff im Workspace abgelehnt, unter Zitat der ersten fehlerhaften Zeile, bis sie behoben ist.) Die Seite zeigt ein Panel, Perspectives on this page, das bei jedem Speichern neu prüft.

Schritt 3. Sie an einer Ref ansehen

perspectives.preview zählt, was die Perspective an einer Ref enthält, nach Art, und liefert die ersten projizierten Pfade, standardmäßig 100 und höchstens 500. "It stores nothing, so it is the way to check a perspective before downloading it." (Sie speichert nichts und ist daher der Weg, eine Perspective vor dem Herunterladen zu prüfen.) Im Browser erscheint dieselbe Zählung neben der Auswahl in der Ref-Leiste des Code-Browsers: Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.

Schritt 4. Eine Ref wählen, die sich nicht bewegt

Eine Ref ist trunk (Standard), lane:<label>, cut:<name> oder snapshot:<id>. Der Exportjob löst die Ref auf, wenn er läuft, "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move." (also ist trunk der Trunk in diesem Moment. Nennen Sie einen Cut oder Snapshot für einen Punkt, der sich nicht bewegt.) Für einen Download, den Sie reproduzieren wollen, nennen Sie einen Cut. Eine Lane im Konflikt wird abgelehnt, bis der Konflikt gelöst ist.

Schritt 5. Das Archiv exportieren und herunterladen

perspectives.export { "perspective": "api", "ref": "cut:<name>", "format": "tar" }
→ { export_id, status: "queued" }
exports.status { ... }   // until it answers a download_url

Fragen Sie exports.status mit der ID des Exports ab, bis er eine download_url liefert; wer den Export angefordert hat, bekommt zusätzlich eine E-Mail mit einem Link. Die Datei heißt <workspace>-<perspective>-<ref>.zip oder .tar. Darin ist eine Seite oder ein Atom eine Markdown-Datei mit Frontmatter für Titel, Art und Metadaten; eine Code-Datei behält ihre Bytes und ihren Modus; ein Symlink bleibt ein Symlink. Die Einträge sind nach Pfad-Bytes sortiert, jede Datei trägt die Zeit der Ref, nichts ist komprimiert und kein Eigentümer wird geschrieben. Ein zip fasst höchstens 65.535 Einträge und 4 GiB; darüber nehmen Sie ein tar. Im Browser wählen Sie zip oder tar und drücken Download neben der Vorschau.

Schritt 6. Jede Datei gegen das Manifest prüfen

Jedes Archiv enthält .carbon/perspective.json, Format carbon-perspective/1. Es nennt die Instanz, den Workspace, die Perspective, wie sie aufgelöst wurde, und die Ref: einen Cut oder Snapshot über seine Snapshot-ID, den Trunk oder eine Lane über composition_sha256. Jeder Eintrag führt auf:

path, kind, entity_id, revision_id, content_hash, seal_hash, mode, size, sha256

Hashen Sie jede Datei und vergleichen Sie mit sha256; vergleichen Sie revision_id, content_hash und seal_hash mit dem Datensatz. Die Dokumentation: Mit dem Manifest "a reader can check every file against the record it came from" (kann eine lesende Person jede Datei gegen den Datensatz prüfen, aus dem sie stammt). Das macht das Archiv zu einem Ausschnitt des Datensatzes statt zu "a copy that can drift into a second truth." (einer Kopie, die zu einer zweiten Wahrheit auseinanderdriften kann.)

Schritt 7. Änderungen über eine Lane zurückbringen

"A download is read-only by design. Nothing in the archive is read back." (Ein Download ist absichtlich nur lesend. Nichts im Archiv wird zurückgelesen.) Um Arbeit am Archiv zurückzubringen, schreiben Sie sie mit einem Tool-Aufruf, legen sie auf eine Lane und landen sie, oder Sie importieren sie, damit jede Änderung ihren eigenen Akteur und ihre eigene Absicht trägt. Working in lanes beschreibt die Lane, und unsere Anleitung Cut a release in Carbon Forge and push it to GitHub (auf Englisch) beschreibt, wie Sie den Cut anlegen, aus dem Sie exportieren.

Was die Dokumentation offenlässt

• Die Größe der Exportgrenze. Ein Download darüber scheitert mit einem Satz, der die Grenze nennt, aber die Dokumentation gibt ihren Standardwert nicht an.
• Wie lange eine download_url gültig bleibt und wie lange ein Export aufbewahrt wird.
• Wer .perspectives bearbeiten darf. Eine Vorlage zu übernehmen ist eine Admin-Aktion; die Seite selbst "is edited like any other page" (wird wie jede andere Seite bearbeitet), was sich so liest, als dürfe jede Person mit Schreibrecht das.
• Ein Werkzeug, das ein Archiv gegen sein Manifest prüft. Das Format ist beschrieben; die Prüfung bleibt dem eigenen Skript der lesenden Person überlassen.