Esaminare e ripristinare una modifica al progetto

Separa le risorse salvate dalla cronologia impegnata

Il salvataggio di un progetto, disegno o percorso utensile aggiorna la copia di lavoro SQLite. La creazione di un commit del progetto esegue lo snapshot delle risorse di lavoro in oggetti compatibili con Git e sposta il riferimento del ramo corrente. Queste sono operazioni separate: un disegno salvato può essere rimosso e un programma impegnato può rimanere locale senza alcun mirror remoto.

Il servizio di cronologia del sidecar crea un file JSON canonico per risorsa. L'albero include project.json, disegni, componenti, percorsi utensile, materiali/strumenti/configurazioni macchina di riferimento e costi di produzione. Il flusso di lavoro YAML e altri testi non di entità trasportati vivono nell'albero del repository, anziché nei normali record di disegno. Una modifica a un'entità non richiede il trattamento dell'intero database come una differenza binaria opaca.

Scegli un progetto usa e getta o previsto prima di seguire gli esempi mutanti. Impostato PROJECT_ID al suo identificatore reale e utilizzare un URL di connessione/portante dell'applicazione corrente. La cronologia del progetto e gli endpoint del flusso di lavoro sono documentati nel file riferimento API cronologia; le scritture dei metadati del progetto utilizzano il file aPI dei progetti.

Gli oggetti utilizzano il formato loose-object esatto in byte di git, quindi gli ID di commit e albero corrispondono a cosa git calcola per lo stesso contenuto. I riferimenti della filiale vivono sotto refs/heads/e il ramo predefinito è main.

Ispezionare l'identità e lo stato di funzionamento

L'accesso in lettura, i commit, la creazione di rami, l'apertura di richieste pull, le revisioni e l'invio del flusso di lavoro richiedono l'accesso al progetto. Checkout, ripristino, configurazione remota, push/pull e fusione richiedono l'accesso del manutentore: il proprietario del progetto o l'ADMIN/MANAGER dell'organizzazione. Un'intestazione di sessione dell'account opzionale seleziona l'utente che agisce; senza una sessione di account valida l'applicazione utilizza il suo profilo locale.

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

La risposta nomina il ramo, l'HEAD nullable e i percorsi sporchi. Sporco significa che i file di risorse correnti differiscono da HEAD. Un elenco non vuoto rappresenta informazioni utili sulla revisione, non un errore di archiviazione. Prima di spostare la copia di lavoro, decidere se tali modifiche appartengono a un commit o devono essere ripristinate/scartate deliberatamente.

Se HEAD è nullo, registra il primo commit del progetto prima di creare un ramo da HEAD. L'API di ramo risolve un commit di origine reale; non esiste un commit segnaposto da cui diramarsi in un nuovo progetto.

Crea una linea di base o registra le modifiche previste

Un commit richiede un messaggio non vuoto e acquisisce le risorse correnti supportate dal database. Esamina prima i percorsi sporchi: l'API non esegue lo stage di singoli file di entità. Il campo file facoltativo aggiunge definizioni di flusso di lavoro sicure, descritte più avanti; non seleziona quali modifiche al disegno includere.

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"

La risposta è un record di commit 201 con ID oggetto, ID genitore, messaggio e informazioni sull'autore. Registrare il suo OID per un confronto o un ripristino successivo. Un albero invariato viene rifiutato con NothingToCommit anziché produrre un'altra revisione dallo stesso contenuto.

authorKind per impostazione predefinita è utente. I commit originati dall'assistente utilizzano ai e non possono eseguire il commit su main. La politica dell'attore viene applicata dal servizio del progetto; un diverso messaggio sul display non lo bypassa. La creazione di un commit può attivare flussi di lavoro dopo la registrazione del commit. Un successivo flusso di lavoro non riuscito non annulla il commit.

Crea e controlla una proposta

La creazione di un ramo scrive un ref; non cambia il database di lavoro. Il checkout è esplicito e rifiuta modifiche lavorative non vincolate. Le seguenti chiamate creano un ramo dall'HEAD corrente e lo caricano come ramo estratto.

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"

Per iniziare altrove, aggiungi un passaggio dalla revisione alla creazione del ramo. I nomi devono essere riferimenti sicuri: le barre trasversali, ripetute, il suffisso barra/.lock finale e i frammenti di espressioni di riferimento vengono rifiutati. Viene rifiutato anche il riutilizzo di un nome esistente.

Dopo il checkout, salva le modifiche previste al progetto tramite le relative API delle risorse. Per una piccola dimostrazione, aggiorna i metadati del progetto con PUT /api/projects/:id e un nuovo nome, quindi esegui il commit. Il diff risultante cambia project.json; non implica un cambiamento della geometria. In una revisione di una parte reale, salvare il disegno e tutti i percorsi utensile rigenerati prima di confermare.

Leggi le modifiche esatte in fase di revisione

GET /vcs/log supporta rev, limit e un percorso tracciato opzionale. GET /vcs/diff richiede a e accetta un facoltativo da. Utilizzare OID espliciti per un confronto riproducibile. Codifica i nomi dei rami e i percorsi JSON come valori di query anziché unire la punteggiatura senza escape negli URL.

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"

Le modifiche alle entità includono percorso, tipo di risorsa, stato aggiunto/modificato/eliminato, ID/nome facoltativo e modifiche alle proprietà descritte dai puntatori JSON. Canonical JSON ordina le chiavi degli oggetti in modo ricorsivo preservando l'ordine dell'array. Le modifiche alle proprietà dell'oggetto non sovrapposte possono unirsi strutturalmente; le modifiche simultanee incompatibili dell'array sono conflitti atomici, non riconciliazioni elemento per elemento.

Esamina le prove di produzione come parte del record del percorso utensile: la corrispondenza del codice G e dell'identità dell'artefatto conta più di un nome file familiare. Un commit del progetto acquisisce i dati salvati; non esegue una richiesta di produzione nativa mancante solo perché l'albero contiene testo NC.

Effettuare i controlli eseguibili con il progetto

I file aggiuntivi dell'endpoint di commit pubblico sono limitati a .cadcamfun/workflows/<safe-name>.yml o yaml. Accetta valori di testo, non patch arbitrarie del filesystem. Non è possibile utilizzare questo campo per sostituire il disegno JSON, scrivere script di shell o eliminare un file inviando null.

Una definizione viene impegnata come testo YAML, quindi il corridore la carica da quel riferimento impegnato. L'esempio seguente convalida i file strutturali, richiede NC per percorsi utensile esistenti, controlla la sequenza delle operazioni e tenta la riproduzione per percorsi utensile che trasportano una richiesta di generatore memorizzata.

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

Per eseguirne il commit da uno script, costruisci il corpo JSON con un serializzatore anziché con YAML con escape manuale:

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

Il commit esegue comunque lo snapshot di tutte le risorse attualmente funzionanti. Convalida lo YAML prima di registrarlo: il commit della cronologia può avere esito positivo mentre il flusso di lavoro non valido risultante viene successivamente registrato come esecuzione non riuscita. Il motore di produzione controlla schema, dipendenze, cicli, ID passaggi duplicati e identificatori di usi registrati.

Effettuare controlli e interpretare le loro prove

POST /api/projects/:id/actions/dispatch accetta un riferimento facoltativo ed esegue ogni flusso di lavoro manuale corrispondente al riferimento impegnato. Non è un selettore di nome di flusso di lavoro singolo. Leggi le definizioni nelle azioni/flussi di lavoro e i risultati persistenti nelle azioni/esecuzioni. Per impostazione predefinita, il servizio restituisce le ultime 50 esecuzioni.

Una corsa registra flusso di lavoro, trigger, riferimento, SHA, timestamp, stato ed eventi. I lavori seguono i livelli di dipendenza; i lavori indipendenti possono essere eseguiti contemporaneamente, mentre i passaggi all'interno di un lavoro sono sequenziali. Gli identificatori degli usi sconosciuti falliscono prima dell'esecuzione. Un valore if è successo, fallimento o sempre, non è un'espressione arbitraria. Una dipendenza non riuscita ignora completamente il processo downstream.

Interpretare attentamente gli output del CAM. cam/verify e cam/gcode ispezionare commesso Toolpath.data.request. Richieste mancanti, percorsi utensile non supportati o NC mancanti potrebbero essere segnalati negli output saltati. Un'esecuzione riuscita conVerified=0 non è una prova di verifica. project/require-gcode controlla i percorsi utensile esistenti; un progetto senza percorsi utensile può soddisfarlo in modo vacuo.

L'integrazione automatica del trigger push HTTP attualmente non fornisce percorsi modificati, quindi un filtro dei percorsi push non corrisponde a tali eventi. Utilizza filtri solo per filiale o invio manuale esplicito per questa integrazione. Gli eventi live HTTP iniziati/terminati vengono pubblicati dopo il ritorno dell'esecuzione sincrona; utilizzare le corse salvate per ottenere risultati duraturi.

Aprire, rivedere e unire una proposta

Apri una richiesta pull locale con titolo, head, corpo opzionale e base (principale per impostazione predefinita). Testa e base devono differire, e una base che già contiene la testa non ha nulla da unire. La risposta include un numero locale del progetto utilizzato dalla revisione e dall'unione degli endpoint.

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 restituisce la richiesta, le revisioni e le modifiche. Le recensioni accettano commenti, approvazioni o richieste di modifiche, con percorso/puntatore facoltativo. L'ultimo verdetto di non commento per revisore controlla il blocco delle modifiche alle richieste. Un commento successivo non lo chiarisce; quel revisore deve inviare un verdetto di approvazione aggiornato. L'implementazione non prevede alcun requisito di conteggio delle approvazioni positive quando non rimane alcun verdetto di blocco.

POST /pulls/:number/merge richiede l'accesso del manutentore. Gli attori dell'IA non possono fondersi nel main. Se la base viene estratta, il servizio richiede una copia di lavoro pulita e applica lo snapshot unito al database. Se viene estratto un altro ramo, aggiorna il riferimento di base senza sostituire il database di lavoro corrente. Le unioni possono avanzare velocemente o creare un commit di unione; ispezionare l'ascendenza piuttosto che presumere due genitori.

Le differenze delle richieste pull unite utilizzano il commit di unione registrato, preservando la visualizzazione di revisione dopo lo spostamento dei riferimenti. Le richieste pull locali sono record di revisione dell'applicazione, non richieste pull automatiche di GitHub.

Ripristina i contenuti senza riscrivere la cronologia

POST /vcs/restore accetta una rev e percorsi opzionali. Richiede l'accesso del manutentore e una copia funzionante pulita e crea un nuovo commit contenente il contenuto precedente. Non reimposta il ramo all'indietro e non cancella i commit intermedi. Il servizio applica quindi il nuovo HEAD al database di lavoro.

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

Sostituisci il percorso con una risorsa tracciata reale e controlla prima la sua differenza. L'omissione dei percorsi ripristina l'intero albero precedente; che può sostituire o rimuovere più risorse correlate. Le istantanee dell'intero progetto comportano anche elementi di libreria di riferimento e costi in modo che i percorsi utensile ripristinati possano mantenere le dipendenze. Il ripristino della versione della risorsa e il ripristino della cronologia del progetto hanno ambiti diversi.

Dopo aver ripristinato l'origine di produzione, controlla se l'output nativo salvato corrisponde ancora alla revisione del disegno prevista. Un'operazione di cronologia preserva l'artefatto precedente; non trasforma quell'artefatto in prova per un disegno appena modificato.

Rispecchia la cronologia impegnata e recupera i conflitti

Un mirror GitHub è facoltativo. Imposta remote su una stringa proprietario/repo con PUT /vcs/remote o null per scollegarlo. Push e pull utilizzano il token GitHub dell'utente in x-github-token per quella chiamata; non viene salvato nel progetto JSON. Per queste operazioni HTTP è richiesto l'accesso come manutentore.

Il push carica oggetti raggiungibili e rifiuta di sovrascrivere i commit remoti non estratti. Pull richiede una copia funzionante pulita, recupera il ramo remoto e unisce. Un conflitto JSON strutturale identifica percorsi e puntatori senza scrivere un commit di unione del repository parziale. Ispeziona entrambe le parti, crea una risoluzione deliberata e riprova invece di forzare una parte rispetto all'altra.

HTTP 409 di solito significa stato sporco o conflitto di unione; 403 può significare un manutentore o una restrizione principale dell'AI; 404 può significare progetto inaccessibile o revisione sconosciuta; 400 copre nomi non validi, messaggi vuoti o nessuna modifica. Un errore del database viene associato a un errore di archiviazione del server. Conservare gli OID e il messaggio di errore durante la diagnosi di una mancata corrispondenza.

Provenienza della fonte: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts, e http/vcs.ts; schema/runner del flusso di lavoro in packages/workflow/src e sidecar workflow-runner.ts/workflow-steps.ts.

Come le recensioni decidono una fusione

1. Aprire una richiesta pull da un ramo di funzionalità (un attore AI deve utilizzare un file ai/* ramo) in main.
2. I revisori inviano comment, approve, o request-changes, facoltativamente ancorato a un file path e un JSON pointer.
3. Al momento della fusione, il servizio prende l'ultimo verdetto di mancato commento di ciascun revisore. Se qualcuno di loro lo è request-changes, l'unione fallisce con blocked: "Un revisore ha richiesto modifiche".
4. Se il ramo base viene estratto, la sua copia di lavoro deve essere pulita.
5. L'unione è a tre vie per proprietà JSON. I conflitti vengono restituiti con i relativi percorsi e puntatori e non viene eseguito alcun commit.
6. Flussi di lavoro con on.pullRequest corrispondente all'esecuzione del ramo di base quando viene aperta la richiesta pull, in modo che i relativi risultati siano disponibili durante la revisione.

Ripristina ricette

// 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)

Entrambe le operazioni di ripristino aggiungono un nuovo commit, quindi lo stato precedente può essere annullato e la cronologia rimane condivisibile. Il ripristino di un file del percorso utensile senza il materiale o lo strumento a cui fa riferimento può lasciare riferimenti pendenti; ripristinare i file della libreria nella stessa chiamata.

Una sessione di revisione completa, catturata

Ogni risposta di seguito è stata catturata da un sidecar in esecuzione su un nuovo progetto (id abbreviato). I percorsi sono relativi a /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"}

Esaminare e interrogare i campi

Nel 3D