También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: construimos Carbon Forge en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo Perspectives: beam angles through one workspace y la sección Perspectives de Source control settings, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. La perspectiva y las llamadas son los ejemplos de la propia documentación, y las citas van en inglés con la traducción al lado. Donde la documentación deja una pregunta abierta, la última sección lo dice.

Qué es una perspectiva

La documentación: "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." (Una perspectiva es una lente con nombre a través de ese registro. Escoge una parte, por tipo, superficie, ruta, tipo de medio, etiqueta o metadatos, y la responde en rutas propias.) Y: "Nothing is copied to make one." (No se copia nada para crear una.) Dos propiedades importan para una exportación. Es de solo lectura por alcance: "A perspective never discloses. It narrows what the reader already reads and never widens it." (Una perspectiva nunca revela. Estrecha lo que el lector ya lee y nunca lo amplía.) Y su descarga es determinista: "The same ref through the same perspective gives the same bytes." (La misma ref a través de la misma perspectiva da los mismos bytes.)

Paso 1. Lista las perspectivas que resuelve el espacio de trabajo

Llama a perspectives.list. Todo espacio de trabajo tiene perspectivas integradas: all, code, docs, adrs, internal, public (exactamente lo que se sirve a un lector anónimo) y una tree:<path> por árbol de código, con raíz en ese árbol. Un administrador de la instancia puede añadir perspectivas para toda la instancia, y las del propio espacio de trabajo van al final; "The nearest layer wins" (gana la capa más cercana). Cada respuesta nombra su source y las fuentes a las que overrides. Si una integrada ya sirve, salta al paso 3.

Paso 2. Escribe la tuya en la página .perspectives

Las perspectivas del espacio de trabajo viven en la página reservada .perspectives, como un bloque JSON delimitado o una tabla. El ejemplo de la documentación, reducido a una perspectiva:

{
  "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"
    }
  ]
}

Una regla coincide cuando coinciden todos los campos que nombra; include toma todo lo que coincide con alguna regla, y exclude quita todo lo que coincide con alguna regla, "even when an include rule matched it" (aunque una regla include lo haya tomado). Las rutas son globs al estilo gitignore y no pueden empezar por !. Con root fijado, la raíz se quita de cada ruta, así que esta perspectiva responde src/main.ts y README.md. Los árboles de código se juzgan archivo por archivo. Plantillas como monorepo, service, library o docs-site pueden escribir la página por ti con perspectives.adopt, o con Adopt en Settings, Workspace, Source control.

Una fila mala no se salta. "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." (Cuando la página no se puede leer, se rechaza toda lectura por perspectiva en el espacio de trabajo, citando la primera fila mala de la página, hasta que se corrija.) La página muestra un panel, Perspectives on this page, que vuelve a comprobar en cada guardado.

Paso 3. Previsualízala en una ref

perspectives.preview cuenta lo que contiene la perspectiva en una ref, por tipo, y responde las primeras rutas proyectadas, 100 por defecto y como mucho 500. "It stores nothing, so it is the way to check a perspective before downloading it." (No guarda nada, así que es la forma de comprobar una perspectiva antes de descargarla.) En el navegador, el mismo recuento aparece junto al selector en la barra de refs del navegador de código: Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.

Paso 4. Elige una ref que no se mueva

Una ref es trunk (por defecto), lane:<label>, cut:<name> o snapshot:<id>. El trabajo de exportación resuelve la ref cuando se ejecuta, "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move." (así que trunk es el trunk en ese momento. Nombra un corte o un snapshot para un punto que no se mueva.) Para una descarga que quieras reproducir, nombra un corte. Una lane en conflicto se rechaza hasta que se resuelva el conflicto.

Paso 5. Exporta y descarga el archivo

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

Consulta exports.status con el id de la exportación hasta que responda una download_url; quien la pidió también recibe un correo con un enlace. El archivo se llama <workspace>-<perspective>-<ref>.zip o .tar. Dentro, una página o un átomo es un archivo Markdown con frontmatter para su título, tipo y metadatos; un archivo de código conserva sus bytes y su modo; un enlace simbólico sigue siendo un enlace simbólico. Las entradas se ordenan por los bytes de la ruta, cada archivo lleva la hora de la ref, nada se comprime y no se escribe propietario. Un zip admite como mucho 65.535 entradas y 4 GiB; más allá, usa tar. En el navegador, elige zip o tar y pulsa Download junto a la previsualización.

Paso 6. Comprueba cada archivo contra el manifiesto

Todo archivo exportado lleva .carbon/perspective.json, con formato carbon-perspective/1. Nombra la instancia, el espacio de trabajo, la perspectiva tal como se resolvió y la ref: un corte o snapshot por su id de snapshot, el trunk o una lane por composition_sha256. Cada entrada lista:

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

Calcula el hash de cada archivo y compáralo con sha256; compara revision_id, content_hash y seal_hash con el registro. La documentación: con el manifiesto, "a reader can check every file against the record it came from" (un lector puede comprobar cada archivo contra el registro del que salió). Eso es lo que hace del archivo una porción del registro y no "a copy that can drift into a second truth." (una copia que puede derivar hasta convertirse en una segunda verdad).

Paso 7. Devuelve los cambios por una lane

"A download is read-only by design. Nothing in the archive is read back." (Una descarga es de solo lectura por diseño. Nada del archivo se vuelve a leer.) Para devolver el trabajo hecho sobre el archivo, escríbelo con una llamada a herramienta, ponlo en una lane e intégrala, o impórtalo, para que cada cambio lleve su propio actor e intención. Working in lanes explica la lane, y nuestra guía Corta una versión en Carbon Forge y súbela a GitHub explica cómo hacer el corte desde el que exportas.

Lo que la documentación deja sin responder

El tamaño del límite de exportación. Una descarga que lo supera falla con una frase que nombra el límite, pero la documentación no dice su valor por defecto.
Cuánto tiempo sigue siendo válida una download_url y cuánto se guarda una exportación.
Quién puede editar .perspectives. Adoptar una plantilla es una acción de administrador; la página en sí "is edited like any other page" (se edita como cualquier otra página), lo que se lee como cualquier editor.
Una herramienta para comprobar un archivo contra su manifiesto. El formato está descrito; la comprobación queda en manos del script de cada lector.

Exporta una porción determinista de un espacio de trabajo con perspectivas