Überprüfen und stellen Sie eine Projektänderung wieder her

Trennen Sie gespeicherte Ressourcen vom Commit-Verlauf

Durch das Speichern eines Projekts, einer Zeichnung oder eines Werkzeugwegs wird die SQLite-Arbeitskopie aktualisiert. Durch das Erstellen eines Projekt-Commits werden Snapshots der Arbeitsressourcen in Git-kompatible Objekte erstellt und die aktuelle Zweigreferenz verschoben. Dies sind separate Vorgänge: Eine gespeicherte Zeichnung kann nicht festgeschrieben werden, und ein festgeschriebenes Programm kann ohne Remote-Spiegel lokal bleiben.

Der Verlaufsdienst des Sidecar erstellt eine kanonische JSON-Datei pro Ressource. Der Baum umfasst project.json, Zeichnungen, Komponenten, Werkzeugwege, referenzierte Materialien/Werkzeuge/Maschinenkonfigurationen und Produktionskosten. Workflow-YAML und anderer Nicht-Entitätstext werden live im Repository-Baum gespeichert und nicht in gewöhnlichen Zeichnungsdatensätzen. Eine Änderung an einer Entität erfordert nicht die Behandlung der gesamten Datenbank als undurchsichtiges binäres Diff.

Wählen Sie ein Einweg- oder beabsichtigtes Projekt, bevor Sie den Mutationsbeispielen folgen. Satz PROJECT_ID zu seiner tatsächlichen Kennung und verwenden Sie eine aktuelle Verbindungs-URL/Anwendungsträger. Projektverlauf und Workflow-Endpunkte werden im dokumentiert history-API-Referenz; projektmetadaten-Schreibvorgänge verwenden die projekte-API.

Objekte verwenden das bytegenaue Loose-Object-Format von Git, sodass Commit- und Tree-IDs mit was übereinstimmen git berechnet für den gleichen Inhalt. Filialreferenzen finden Sie unten refs/heads/, und der Standardzweig ist main.

Überprüfen Sie die Identität und den Betriebszustand

Lesezugriff, Commits, Branch-Erstellung, Öffnen von Pull-Requests, Überprüfungen und Workflow-Versand erfordern Zugriff auf das Projekt. Auschecken, Wiederherstellen, Remote-Konfiguration, Push/Pull und Zusammenführen erfordern Betreuerzugriff: den Projekteigentümer oder den ADMIN/MANAGER der Organisation. Ein optionaler Kontositzungsheader wählt den handelnden Benutzer aus; Ohne eine gültige Kontositzung verwendet die Anwendung ihr lokales Profil.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/status"

Die Antwort benennt den Zweig, den nullbaren HEAD und die fehlerhaften Pfade. Dirty bedeutet, dass sich die aktuellen Ressourcendateien von HEAD unterscheiden. Eine nicht leere Liste ist eine nützliche Überprüfungsinformation und kein Speicherfehler. Entscheiden Sie vor dem Verschieben der Arbeitskopie, ob diese Änderungen zu einem Commit gehören oder absichtlich wiederhergestellt/verworfen werden sollen.

Wenn HEAD null ist, zeichnen Sie den ersten Projekt-Commit auf, bevor Sie einen Zweig von HEAD erstellen. Die Branch-API löst einen echten Quell-Commit auf; Es gibt keinen Platzhalter-Commit, von dem aus in einem neuen Projekt verzweigt werden kann.

Erstellen Sie eine Baseline oder zeichnen Sie beabsichtigte Änderungen auf

Ein Commit erfordert eine nicht leere Nachricht und erfasst die aktuellen datenbankgestützten Ressourcen. Überprüfen Sie zuerst fehlerhafte Pfade: Die API stellt keine einzelnen Entitätsdateien bereit. Das optionale Feld „Dateien“ fügt sichere Workflow-Definitionen hinzu, die später beschrieben werden. Es wird nicht ausgewählt, welche Zeichnungsänderungen einbezogen werden sollen.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Record baseline blank"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/commit"

Die Antwort ist ein 201-Commit-Datensatz mit Objekt-ID, übergeordneten IDs, Nachricht und Autoreninformationen. Notieren Sie die OID für einen späteren Vergleich oder eine spätere Wiederherstellung. Ein unveränderter Baum wird mit NothingToCommit abgelehnt, anstatt eine weitere Revision aus demselben Inhalt zu erstellen.

authorKind der Standardwert ist „Benutzer“. Vom Assistenten stammende Commits verwenden ai und können nicht auf main festgeschrieben werden. Die Akteurrichtlinie wird vom Projektdienst durchgesetzt. Eine andere Anzeigemeldung umgeht es nicht. Das Erstellen eines Commits kann Workflows auslösen, nachdem der Commit aufgezeichnet wurde. Ein nachfolgender fehlgeschlagener Workflow macht dieses Commit nicht rückgängig.

Erstellen Sie ein Angebot und prüfen Sie es

Beim Erstellen eines Zweigs wird eine Referenz geschrieben. Die Arbeitsdatenbank wird nicht gewechselt. Das Auschecken ist explizit und lehnt nicht festgeschriebene Arbeitsänderungen ab. Die folgenden Aufrufe erstellen einen Zweig aus dem aktuellen HEAD und laden ihn als ausgecheckten Zweig.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"name":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/branches"

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"branch":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/checkout"

Um woanders zu beginnen, fügen Sie eine From-Revision zur Zweigerstellung hinzu. Namen müssen sichere Refs sein: Durchquerung, wiederholte Schrägstriche, ein abschließender Schrägstrich/.lock-Suffix und Ref-Ausdrucksfragmente werden abgelehnt. Auch die Wiederverwendung eines bestehenden Namens wird abgelehnt.

Speichern Sie nach dem Auschecken die beabsichtigten Projektänderungen über ihre Ressourcen-APIs. Aktualisieren Sie für eine kleine Demonstration die Projektmetadaten mit PUT /api/projects/:id und einem neuen Namen und übernehmen Sie sie dann. Der resultierende Diff ändert project.json; es bedeutet keine Geometrieänderung. Speichern Sie bei einer Revision eines echten Teils die Zeichnung und alle neu generierten Werkzeugwege, bevor Sie sie übernehmen.

Lesen Sie die genauen Änderungen, die derzeit überprüft werden

GET /vcs/log unterstützt Rev, Limit und einen optionalen verfolgten Pfad. GET /vcs/diff erfordert to und akzeptiert ein optionales from. Verwenden Sie explizite OIDs für einen reproduzierbaren Vergleich. Kodieren Sie Zweignamen und JSON-Pfade als Abfragewerte, anstatt Satzzeichen ohne Escapezeichen in URLs einzubinden.

curl --fail-with-body --get \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --data-urlencode "from=main" \
  --data-urlencode "to=proposal/blank-label" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/diff"

Zu den Entitätsänderungen gehören Pfad, Ressourcentyp, hinzugefügter/geänderter/gelöschter Status, optionale ID/Name und durch JSON-Zeiger beschriebene Eigenschaftsänderungen. Canonical JSON sortiert Objektschlüssel rekursiv und behält dabei die Array-Reihenfolge bei. Nicht überlappende Änderungen an Objekteigenschaften können strukturell zusammengeführt werden. Inkompatible gleichzeitige Array-Bearbeitungen sind atomare Konflikte, keine Element-für-Element-Abstimmungen.

Überprüfen Sie Fertigungsnachweise als Teil der Werkzeugwegaufzeichnung: Die Übereinstimmung von G-Code und Artefaktidentität ist wichtiger als ein bekannter Dateiname. Ein Projekt-Commit erfasst gespeicherte Daten; Es wird keine fehlende native Fertigungsanforderung ausgeführt, nur weil der Baum NC-Text enthält.

Führen Sie mit dem Projekt ausführbare Prüfungen durch

Die zusätzlichen Dateien des öffentlichen Commit-Endpunkts sind beschränkt .cadcamfun/workflows/<safe-name>.yml oder Yaml. Es akzeptiert Textwerte, keine willkürlichen Dateisystem-Patches. Sie können dieses Feld nicht verwenden, um JSON-Zeichnungen zu ersetzen, Shell-Skripte zu schreiben oder eine Datei durch Senden von Null zu löschen.

Eine Definition wird als YAML-Text festgeschrieben, dann lädt der Läufer sie aus dieser festgeschriebenen Referenz. Das folgende Beispiel validiert Strukturdateien, erfordert NC für vorhandene Werkzeugwege, prüft die Operationssequenz und versucht eine Wiedergabe für Werkzeugwege, die eine gespeicherte Generatoranforderung enthalten.

name: Review checks
on:
  manual: true
  pullRequest:
    branches: [main]
jobs:
  inspect:
    steps:
      - id: structure
        uses: project/validate
      - uses: project/require-gcode
      - uses: cam/sequence
      - id: replay
        uses: cam/verify

Um es aus einem Skript zu übernehmen, erstellen Sie den JSON-Körper mit einem Serialisierer, anstatt YAML manuell zu maskieren:

const body = {
  message: "Add committed review checks",
  files: { ".cadcamfun/workflows/review.yml": await Bun.file("review.yml").text() }
}
const encoded = JSON.stringify(body)

Der Commit erstellt weiterhin Snapshots aller aktuellen Arbeitsressourcen. Validieren Sie die YAML, bevor Sie sie aufzeichnen: Der Verlaufs-Commit kann erfolgreich sein, während der resultierende ungültige Workflow später als fehlgeschlagene Ausführung aufgezeichnet wird. Die Produktions-Engine prüft Schema, Abhängigkeiten, Zyklen, doppelte Schritt-IDs und registrierte Verwendungskennungen.

Versenden Sie Schecks und interpretieren Sie deren Beweise

POST /api/projects/:id/actions/dispatch akzeptiert eine optionale Referenz und führt jeden manuellen Workflow aus, der mit dieser festgeschriebenen Referenz übereinstimmt. Es handelt sich nicht um einen Einzel-Workflow-Namen-Selektor. Lesen Sie Definitionen bei Aktionen/Workflows und persistente Ergebnisse bei Aktionen/Läufen. Der Dienst gibt standardmäßig die letzten 50-Ausführungen zurück.

Ein Lauf zeichnet Workflow, Trigger, Ref, SHA, Zeitstempel, Status und Ereignisse auf. Jobs folgen Abhängigkeitsstufen; Unabhängige Jobs können gleichzeitig ausgeführt werden, während Schritte innerhalb eines Jobs sequentiell sind. Unbekannte Verwendungskennungen schlagen vor der Ausführung fehl. Ein if-Wert ist Erfolg, Misserfolg oder immer, kein willkürlicher Ausdruck. Eine fehlgeschlagene Abhängigkeit überspringt ihren Downstream-Job vollständig.

Interpretieren Sie die CAM-Ausgaben sorgfältig. cam/verify und cam/gcode inspizieren begangen Toolpath.data.request. Fehlende Anforderungen, nicht unterstützte Werkzeugwege oder fehlende NC können in übersprungenen Ausgaben gemeldet werden. Eine erfolgreiche Ausführung mit „verified=0“ ist kein Verifizierungsbeweis. project/require-gcode prüft vorhandene Werkzeugwege; Ein Projekt ohne Werkzeugwege kann dies völlig erfüllen.

Die automatische HTTP-Push-Trigger-Integration liefert derzeit keine geänderten Pfade, sodass ein Push-Pfadfilter diese Ereignisse nicht berücksichtigt. Verwenden Sie für diese Integration Nur-Zweig-Filter oder einen expliziten manuellen Versand. Gestartete/beendete HTTP-Live-Ereignisse werden veröffentlicht, nachdem die synchrone Ausführung zurückgekehrt ist. Verwenden Sie gespeicherte Läufe für dauerhafte Ergebnisse.

Öffnen, überprüfen und führen Sie ein Angebot zusammen

Öffnen Sie eine lokale Pull-Anfrage mit Titel, Kopf, optionalem Text und Basis (standardmäßig Haupt). Kopf und Basis müssen unterschiedlich sein, und eine Basis, die bereits den Kopf enthält, hat nichts zu verschmelzen. Die Antwort enthält eine projektlokale Nummer, die von Überprüfungs- und Zusammenführungsendpunkten verwendet wird.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"title":"Review blank label","head":"proposal/blank-label","base":"main","body":"Metadata change and committed checks."}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/pulls"

GET /pulls/:number gibt die Anfrage, Überprüfungen und Änderungen zurück. Bewertungen akzeptieren Kommentare, Genehmigungen oder Anforderungsänderungen mit optionalem Pfad/Zeiger. Das letzte Nicht-Kommentar-Urteil pro Prüfer steuert den Request-Changes-Block. Ein späterer Kommentar klärt es nicht; Dieser Prüfer muss ein aktualisiertes Genehmigungsurteil einreichen. Für die Implementierung ist keine positive Genehmigungsanzahl erforderlich, wenn kein Sperrurteil vorliegt.

POST /pulls/:number/merge erfordert Betreuerzugriff. KI-Akteure können nicht mit Hauptakteuren verschmelzen. Wenn die Basis ausgecheckt ist, benötigt der Dienst eine saubere Arbeitskopie und wendet den zusammengeführten Snapshot auf die Datenbank an. Wenn ein anderer Zweig ausgecheckt wird, aktualisiert er die Basisreferenz, ohne die aktuelle Arbeitsdatenbank zu ersetzen. Zusammenführungen können einen schnellen Vorlauf durchführen oder ein Zusammenführungs-Commit erstellen. Überprüfen Sie die Abstammung, anstatt zwei Elternteile anzunehmen.

Zusammengeführte Pull-Request-Diffs verwenden den aufgezeichneten Merge-Commit und behalten die Überprüfungsansicht nach dem Verschieben der Refs bei. Lokale Pull-Requests sind Anwendungsüberprüfungsdatensätze, nicht automatisch GitHub-Pull-Requests.

Stellen Sie Inhalte wieder her, ohne den Verlauf neu zu schreiben

POST /vcs/restore benötigt eine Version und optionale Pfade. Es erfordert Betreuerzugriff und eine saubere Arbeitskopie und erstellt einen neuen Commit, der den früheren Inhalt enthält. Der Zweig wird nicht zurückgesetzt und dazwischenliegende Commits werden nicht gelöscht. Der Dienst wendet dann den neuen HEAD auf die Arbeitsdatenbank an.

{
  "rev": "earlier-commit-oid",
  "paths": ["drawings/actual-drawing-id.json"]
}

Ersetzen Sie den Pfad durch eine tatsächlich verfolgte Ressource und überprüfen Sie zunächst deren Diff. Durch das Weglassen von Pfaden wird der vollständige frühere Baum wiederhergestellt. Dadurch können mehrere verwandte Ressourcen ersetzt oder entfernt werden. Schnappschüsse des gesamten Projekts enthalten auch referenzierte Bibliothekselemente und Kosten, sodass wiederhergestellte Werkzeugwege Abhängigkeiten beibehalten können. Die Wiederherstellung der Ressourcenversion und die Wiederherstellung des Projektverlaufs haben unterschiedliche Bereiche.

Überprüfen Sie nach dem Wiederherstellen der Fertigungsquelle, ob die gespeicherte native Ausgabe noch mit der beabsichtigten Zeichnungsrevision übereinstimmt. Eine Verlaufsoperation bewahrt das frühere Artefakt; es wandelt dieses Artefakt nicht in Beweise für eine neu modifizierte Zeichnung um.

Spiegeln Sie engagierte Geschichte und stellen Sie Konflikte wieder her

Ein GitHub-Spiegel ist optional. Setzen Sie remote mit PUT /vcs/remote auf eine Eigentümer-/Repo-Zeichenfolge oder null, um die Verbindung zu trennen. Push und Pull verwenden für diesen Aufruf das GitHub-Token des Benutzers in x-github-token. Es wird nicht im Projekt-JSON gespeichert. Für diese HTTP-Vorgänge ist Betreuerzugriff erforderlich.

Push lädt erreichbare Objekte hoch und weigert sich, nicht abgerufene Remote-Commits zu überschreiben. Pull erfordert eine saubere Arbeitskopie, ruft den Remote-Zweig ab und führt ihn zusammen. Ein struktureller JSON-Konflikt identifiziert Pfade und Zeiger, ohne einen teilweisen Repository-Merge-Commit zu schreiben. Überprüfen Sie beide Seiten, finden Sie eine bewusste Lösung und versuchen Sie es erneut, anstatt eine Seite der anderen aufzuzwingen.

HTTP 409 bedeutet normalerweise einen Dirty-State- oder Merge-Konflikt; 403 kann eine Betreuer- oder AI-Haupteinschränkung bedeuten; 404 kann ein unzugängliches Projekt oder eine unbekannte Revision bedeuten; 400 deckt ungültige Namen, leere Nachrichten oder keine Änderungen ab. Ein Datenbankfehler ist einem Serverspeicherfehler zugeordnet. Behalten Sie die OIDs und die Fehlermeldung bei, wenn Sie eine Nichtübereinstimmung diagnostizieren.

Herkunft der Quelle: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts, und http/vcs.ts; workflow-Schema/Runner in packages/workflow/src und Sidecar workflow-runner.ts/workflow-steps.ts.

Wie Bewertungen über eine Zusammenführung entscheiden

1. Öffnen Sie eine Pull-Anfrage aus einem Feature-Zweig (ein KI-Akteur muss eine verwenden ai/* zweig) hinein main.
2. Gutachter reichen ein comment, approve, oder request-changes, optional in einer Datei verankert path und ein JSON pointer.
3. Zum Zeitpunkt der Zusammenführung übernimmt der Dienst das letzte nicht kommentierende Urteil jedes Prüfers. Wenn einer von ihnen ist request-changes, schlägt die Zusammenführung mit fehl blocked: „Ein Rezensent hat Änderungen angefordert.“
4. Wenn der Basiszweig ausgecheckt ist, muss seine Arbeitskopie sauber sein.
5. Die Zusammenführung erfolgt in drei Richtungen pro JSON-Eigenschaft. Konflikte werden mit ihren Pfaden und Zeigern zurückgegeben, und es wird nichts festgeschrieben.
6. Arbeitsabläufe mit on.pullRequest übereinstimmung mit dem Basiszweiglauf, wenn die Pull-Anfrage geöffnet wird, sodass ihre Ergebnisse während der Überprüfung verfügbar sind.

Rezepte wiederherstellen

// Bring back one drawing as it was three commits ago
const old = repo.log()[3].oid
repo.restorePaths(old, ["drawings/d1.json"], me, "Restore plate outline")

// Make the whole tree equal to an older commit (a new commit on top)
repo.revertTo(old, me)               // message defaults to "Restore <rev>"

// Who changed a toolpath, most recent first
repo.fileLog("toolpaths/op1.json").map((e) => e.message)

Bei beiden Wiederherstellungsvorgängen wird ein neues Commit hinzugefügt, sodass der ältere Status selbst rückgängig gemacht werden kann und der Verlauf weiterhin gemeinsam genutzt werden kann. Das Wiederherstellen einer Werkzeugwegdatei ohne das Material oder Werkzeug, auf das sie verweist, kann zu fehlenden Referenzen führen. Stellen Sie diese Bibliotheksdateien im selben Aufruf wieder her.

Eine komplette Review-Sitzung, festgehalten

Jede Antwort unten wurde von einem laufenden Sidecar eines neuen Projekts erfasst (IDs gekürzt). Pfade sind relativ zu /api/projects/{id}/.

# fresh project with one drawing
GET  vcs/status
{"branch":"main","head":null,"dirty":["drawings/2f315a02-….json","project.json"]}

POST vcs/commit       {"message":"Baseline"}
{"oid":"8bdded63…","parents":[],"message":"Baseline\n","author":{"name":"Local user",…}}

POST vcs/branches     {"name":"thicker"}
{"current":"main","branches":{"main":"8bdded63…","thicker":"8bdded63…"}}

POST vcs/checkout     {"branch":"thicker"}
{"branch":"thicker","head":"8bdded63…","dirty":[]}

PUT  /api/drawings/{id}  {"name":"Plate 12mm"}
GET  vcs/status
{"branch":"thicker","head":"8bdded63…","dirty":["drawings/2f315a02-….json"]}

POST vcs/commit       {"message":"Rename plate"}
{"oid":"a6869011…","parents":["8bdded63…"],…}

GET  vcs/diff?from=main&to=thicker
[{"path":"drawings/2f315a02-….json","kind":"drawings","id":"2f315a02-…","name":"Plate 12mm",
  "status":"modified","changes":[
    {"pointer":"/name","before":"Plate","after":"Plate 12mm"},
    {"pointer":"/updatedAt","before":"…09:20.069Z","after":"…09:20.168Z"}]}]

POST pulls            {"title":"Thicker plate","head":"thicker","base":"main"}
{"number":1,"state":"open","authorKind":"user","mergeCommit":null,…}

POST pulls/1/reviews  {"verdict":"approve","body":"Looks good"}
{"verdict":"approve","body":"Looks good","path":null,"pointer":null,…}

POST pulls/1/merge
{"number":1,"state":"merged","mergeCommit":"a6869011…",…}

POST pulls/1/merge    (again)
{"_tag":"BadRequest","message":"Pull request is not open"}

Überprüfungs- und Abfragefelder

In 3D