Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano
Trasparenza: Carbon Forge è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica, soprattutto le sezioni symbols.drift e Governed seams di MCP tools catalog: Semantics e "Drift between prose and code" in The Carbon paradigm, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Tabella e chiamate sono gli esempi della documentazione, e le citazioni sono in inglese con la traduzione accanto. Dove la documentazione lascia aperta una domanda, l'ultima sezione lo dice.
Che cos'è il report
La pagina sul paradigma in una riga: "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree" (la pagina riservata .governed-seams di un workspace dichiara quali pagine governano quali definizioni di un albero di codice). symbols.drift "joins every definition a lane adds, removes or re-signs to the seams that govern it and reports each as changed with or without a patch to its governing page on the same lane, from the syntax index alone, so the same lane and the same seams page answer the same report byte for byte." (collega ogni definizione che una lane aggiunge, rimuove o cambia di firma ai seam che la governano, e riporta ciascuna come modificata con o senza una patch alla sua pagina di governo sulla stessa lane, dal solo indice sintattico, così la stessa lane e la stessa pagina dei seam danno lo stesso report byte per byte.) Nessun modello legge nulla. E un limite da tenere a mente: "The report advises and never refuses a landing." (Il report consiglia e non rifiuta mai un'integrazione.)
Passo 1. Scegliete le definizioni che una pagina descrive
Partite dalle pagine che trarrebbero in inganno chi legge se il codice cambiasse sotto di loro: una pagina di architettura sulla fatturazione, una guida sull'accesso. Trovate le definizioni che descrivono con l'indice semantico:
symbols.search { "tree": "app", "query": "charge", "prefix": true }Le definizioni vengono dalle query di tag di tree-sitter per TypeScript e TSX, JavaScript, Python, Go, Rust, C, C++, C#, Java, Ruby, PHP, Scala e Bash. CSS, HTML, JSON, YAML, TOML e HCL hanno alberi sintattici "but no definitions or references" (ma nessuna definizione o riferimento), quindi un seam su quei file non riporta nulla. I nomi sono "matched by name, not by type checking" (confrontati per nome, non tramite controllo dei tipi).
Passo 2. Scrivete la pagina .governed-seams
Create una pagina al percorso riservato .governed-seams la cui prima tabella Markdown ha l'intestazione tree | glob | symbols | records. L'esempio della documentazione:
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: il percorso di un albero di codice.glob: una regola nella sintassi delle regole di esclusione dell'import sui percorsi dei file dell'albero, che non inizia con!.symbols: nomi di definizioni separati da virgole, oppure*da solo per ogni definizione sotto il glob.records: percorsi di pagine separati da virgole, le pagine che governano quelle definizioni.
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one." (Un seam si dichiara, non si deduce mai: nessun link, tag, chiave di metadati o embedding ne crea uno.) La pagina viene letta dal trunk, "so a lane cannot ungovern its own change." (quindi una lane non può togliere il governo alla propria modifica.) Integratela sul trunk prima del lavoro che deve sorvegliare. Una pagina malformata blocca ogni report finché non viene corretta, con una frase che nomina la riga: The governed seams page .governed-seams is malformed at line <n>, ...
Passo 3. Modificate il codice governato su una lane
Il report legge una lane, quindi la modifica deve stare su una lane: lanes.create, poi trees.apply_patch o trees.put con lane, come mostra Working in lanes. Cambiate la firma di chargeCard, per esempio aggiungendo un parametro.
Passo 4. Leggete il report di drift
symbols.drift { "lane": "agent/7/fix-login" }Aggiungete tree per leggere un solo albero. La risposta:
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }Ogni finding nomina tree, path, symbol e kind, il from_signature sul trunk e il to_signature sulla lane (null dove un lato non lo contiene), records come { path, updated_on_lane }, e callers, il numero di riferimenti al nome sulla lane. La class è il verdetto: seam_changed_without_record quando la lane non ha nessuna patch viva su una pagina di governo. Quella è la vostra documentazione obsoleta, scoperta prima dell'integrazione.
Leggete pending prima di fidarvi di un report vuoto: elenca i file modificati sotto il glob di un seam a cui l'indice "cannot answer yet" (non sa ancora rispondere), e "the report is complete when pending is empty." (il report è completo quando pending è vuoto.) Una lane in conflitto viene rifiutata finché il conflitto non è risolto.
Passo 5. Aggiornate la pagina di governo sulla stessa lane
Modificate architecture/billing con pages.apply_patch e la stessa lane, così pagina e codice aspettano insieme. La guida Integrare una modifica al codice e la sua documentazione in un solo changeset segue questa parte.
Passo 6. Rileggete il report, poi integrate
Eseguite di nuovo symbols.drift. Il finding ora dice seam_changed_with_record, e il suo record mostra updated_on_lane. Conservate il report con la revisione: composition_hash è l'hash della composizione della lane che ha letto, e report_sha256 copre il testo canonico del report, "so a report is bound to the exact change it read." (quindi un report è legato alla modifica esatta che ha letto.) Una patch successiva cambia entrambi. Poi integrate la lane come un solo changeset.
Poiché il report si limita a consigliare, l'obbligo dovete aggiungerlo voi. Uno schema, nostro e non della documentazione: su un trunk protetto, indicate il glob del codice governato in .landing-rules con il responsabile della pagina di governo come approvatore, e fate leggere a quell'approvatore il report di drift per primo.
Cosa la documentazione lascia senza risposta
- Chi può scrivere
.governed-seams. La documentazione rende.landing-rulesriservata agli amministratori; per la pagina dei seam dice solo che viene letta dal trunk "whoever wrote it" (chiunque l'abbia scritta). - Una vista nell'app. La documentazione descrive lo strumento e la sua risposta, non una pagina nel browser che mostri il report.
- Il Markdown è "not parsed yet" (non ancora analizzato), quindi una pagina non può essere essa stessa il lato governato.