Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.
aggrega import
Mengubah deskripsi sumber asing menjadi draf file penulisan Aggrega
Halaman ini adalah referensi perintah tersebut. Kegunaan impor, serta panduan langkah demi langkah yang membawa sebuah proyek dari sumbernya hingga menjadi build, ada di Impor. File jawaban tempat nilai-nilai yang tidak dapat dimuat sumber mana pun dibaca, serta pertanyaan yang diajukan di terminal, dijelaskan di File jawaban impor.
Sinopsis
aggrega import <file or directory> [flags]Deskripsi
Turn a foreign source description into draft Aggrega authoring files.
The importer reads the source, drafts Aggrega entities from it, and writes thedrafted files beneath the root of the workspace the run resolved, from whicheverfolder the command is run in (creating parent directories as needed). Thetranslation is done by the importer plugin that advertises the source format;import selects it, runs it, and writes what it produces. An importer in theworkspace's catalog has its .wasm read from the places a build reads a pluginfrom — beside its Plugin entity in a catalog folder among them.
The compiler's core importers serve their formats in every workspace, with nocatalog entry. The first import that needs one this machine does not holdfetches it from the workspace's default registry, holds it to the module thecompiler's release publishes, verifies its signature under that registry'strust policy and the host functions it uses, and keeps it in the workspace'scontent cache, so every later import reads it from there and reaches nonetwork for it. Nothing else is written for it: no lockfile, and no record of trustedplugins. A module that does not verify is refused, and nothing is kept. Wherethe module cannot be fetched — the workspace is offline, its registry cannot bereached, or the registry does not hold it — import stops, naming the importerand its version and what puts its module on the machine: running the importonce with the network available, where that would fetch it, or placing themodule beside a Plugin entity of that importer at that version in a catalogfolder.
The catalog an import reads is the workspace's catalog folders. Where theworkspace names none — AGGREGA_CATALOG_DIRS is unset, its configuration listsno catalog_dirs, and it holds no catalog folder at its root — import reads thecatalog its default registry publishes as one signed snapshot, atcatalog/snapshot. A snapshot is fetched once: its signature is verified underthat registry's trust policy, and it is kept in the workspace's content cacheand read there as a catalog folder, held to its digest, with no registry askedfor it again. Which snapshot an import reads: with --upgrade, the newest;otherwise the one the record beside the drafts names, fetched by its digestwhen this machine does not hold it; otherwise the one the workspace lastfetched as the newest; otherwise the newest. The record an import writes namesthe snapshot it read by its digest. Under --offline an import that would haveto fetch one stops, naming what to run. A registry that publishes nosnapshot leaves the import with no catalog, and a warning says so. A workspacethat names a catalog folder imports against it, and nothing is fetched.
The source is a file or a directory. A file is handed to the importer whole. Adirectory is read into named sources: exactly the files the importer's declaredfile patterns match, at any depth, each named by its path inside the directorywritten with forward slashes, in sorted order, and no other file of thedirectory is opened. A directory holding the folder aggrega build writes to —dist/ beneath the workspace root — is read without it: nothing in that folderis recognized or handed to the importer, so a directory you have built isread as the project it holds, and a directory that is that folder, or liesinside it, is read as named. A link inside the directory is never followed outof it: the directory is held to itself wherever it lies, inside the workspace oroutside it, so a link leading out of it — to a directory, or to a file theimporter's patterns match (any importer's, when the format is recognized) — isrefused before anything is read. A link to a directory is never entered, and alink to a file no pattern matches is passed over unread. An importer thatdeclares no file patterns reads one file and refuses a directory, and adirectory holding no file its patterns match is refused too. The files theimporter's attachment names under with: sources reach it beside the directory'sfiles, under their own base names, and a name the two share is refused ratherthan one hiding the other.
A plugins.importer attachment attaches the importer its uri names by identityand version — importer/<name>:<version>, as plugin add importer writes it. Anattached importer that advertises the source format is the one that runs, atthe version its uri names, whatever other importers advertise the format too.Where more than one importer advertises the format and no single one of them isattached, import stops and names the importers it could not choose between. Thecore importers are among them: a workspace whose catalog holds an importer ofanother name for a format a core importer serves attaches the one it wants.Within one name the highest version runs, and an importer the catalog holds atthe name and version of a core importer, with its module beside it, runs inits place. A Plugin entity of a core importer's name with no module beside itis no candidate: the core importer runs in its place at its own version, andat another version the entity stays a candidate only where an attachment namesexactly that version, or where no importer of that name that can runadvertises the format. An attachment'swith: sources and settings are handed to the importer it attaches and to noother, so an importer no attachment names is handed none.
Pass --output-dir to write the drafts beneath another directory instead. Arelative path resolves against the directory you run the command in, as everypath you type does, and a drive named bare on Windows, such as D:, is thecurrent directory on that drive. The directory is resolved before any draft isplaced beneath it, so a draft whose path opens with a separator lands beneathit rather than at the top of the drive. A directory you name outsidethe workspace is used where you named it, and what is written beneath it isheld to it. Wherever the drafts go, a link on the way to one that leads out ofthe workspace — or, beneath a directory you named outside it, out of thatdirectory — is refused, and nothing is written.
Pass --target to draft, beside the importer's drafts, the Manifest the draftedRelease builds against for one provider. The target is a provider capability —the word a Recipe's spec.capability binds to, such as compose or helm. For eachcomponent type and each feature type the drafts need — on the draftedAggregate's components, their connections and its subsystems, on the catalogAggregates it composes, and on the drafted Release's attachments — in the orderthe drafts first declare it, import looks in the workspace's catalog for theRecipes, or for a feature type the feature recipes, that implement the type andbind to that capability: where there is exactly one — several versions of onecount as one — the Manifest maps the type to it by its capability-qualified namewith no version, such as compose/postgres, which the first pull pins in thelockfile at the highest version available; where there are several of differentnames, it maps the one named after the type itself, such as helm/postgres forcore/datastore/postgres; where there is none, or several with none so named, thetype is left unmapped and a warning names it and why, so a build of the draftsstops naming each instance or attachment of it until you add the mapping. Wherethe importer drafts the Manifest itself, to choose the Recipe one instancerenders through or a feature recipe among several, each mapping it wrote thatthe catalog offers for that type and capability is kept, any other is droppedwith a warning, and the types it leaves are mapped as above. The Manifest iswritten as manifest.yaml beside the drafted Release, with the Release's nameand version, and the Release's spec.manifest is set to that name — the commentthe importer wrote in its place is replaced, and nothing else in the Releasechanges. A Release that already names a Manifest is left as it is; where theimport drafts no Release, the Manifest is drafted beside the Aggregate, with itsname and version, and nothing references it. The Manifest and the editedRelease are drafts like the others: recorded, held inside the output directory,and shown by --dry-run. A target no Recipe in the catalog binds to stops theimport before the importer runs, naming the target and the capabilities thecatalog's Recipes bind to, and nothing is written. Without --target no Manifestis drafted and the drafts are the importer's alone — except under --sync, whichreuses the target the earlier import was given.
Beside its drafts, every import that drafts anything writes .aggrega-import.json,the record of what it wrote: the target it was given, where it was given one,the catalog snapshot it read, where it read one, and each drafted file and, in a drafted Aggregate or Release, each key at everydepth, with a digest of the text written there; any other drafted file isrecorded whole. A key's text is its line, its value's lines where its value isnot a mapping of keys, and the comment lines written directly above it at itsown indentation. The record is JSON, so nothing that reads the workspace's YAMLdocuments reads it; keep it beside the drafts for as long as you mean to syncthem.
Some values no source can hold: the image of an application built from yourown code, the email of an owner account, a model the source does not name, thename of a Kubernetes Secret. The drafts write each such value as an emptystring under a comment saying what it is. After drafting, import reads everydrafted document against its own schema and against the catalog schema of eachComponent, Feature and connection it declares, and lists every value stillempty where that schema requires one, or where it declares the key and nothingsupplied it — each described by the schema's own description. The values areanswered from the answers file: --answers names it, and without it import readsthe one the record beside the drafts names, or else import-answers.yaml besidethe source file, or inside the source directory. The answers file holds, undereach drafted file's path, the key path inside that document and its answer as astring, with the schema's description in a comment above each key. Each answeris written into the drafts before anything is written or recorded, so an importof the same source, and --sync, read the same answers and draft the same files.An answer for a key these drafts do not leave empty — one only anothertarget's drafts ask for, say — is kept in the file and not applied, so oneanswers file serves every target: import adds the keys it owes, sets theanswers it is given, and leaves every other key and comment as it is, writingthe file only where that changes it. The record beside the drafts names theanswers file where it is not the one beside the source, and holds no answer.
The answers file never holds a secret. A secret's value — one its schema markssensitive — is answered with where the secret comes from: a variable name, areference such as ${OPENAI_API_KEY}, or the name of a Kubernetes Secret.Anything else is refused, naming the key and never the answer, and nothing iswritten.
Where standard input and standard output are both a terminal, and --dry-run isnot given, import asks one question for each value the answers file leavesunanswered, worded from the schema's description; an empty answer leaves thevalue for later, and a secret's answer that is not a name is refused and askedagain. Every answer is written into the answers file, so a later run asksnothing. Anywhere else — a pipe, continuous integration, the assistant's importtool, the editor — nothing is asked: the drafts keep their empty values, theanswers file is written with every owed key present and empty, each owed valueis named on standard error, and import exits 1 with one sentence saying howmany values are owed and where to write them. Under --dry-run nothing is askedand nothing is written: each owed value is named on standard error, and theexit status is the dry run's own.
When the drafts include a Release, owe nothing, and the importer finished,import pulls that Release's dependencies once the drafts are written, exactlyas aggrega pull --release does, writing its release.lock, so aggrega validateand aggrega build work on the drafts at once. Under --offline nothing is pulled,and import names the aggrega pull to run next. A pull that fails leaves thedrafts written and stops import, naming why and the pull to run once it isfixed.
An import never writes over an Aggregate already at one of its drafted paths:an Aggregate is the document an author goes on editing once it is drafted, soimport stops, naming it and --sync, and writes nothing — under --dry-run too.Every other file already at a drafted path is written over, and a file anearlier import drafted that this one does not draft is left where it is.
--sync brings what an earlier import drafted up to date with the source instead,changing only what the import wrote. A sync given no --target drafts for thetarget the record names, so it drafts the Manifest the earlier import drafted;given one, it drafts for that target and records it in place of the onerecorded. A recorded target no Recipe in the catalog binds to stops the sync asa target you pass does, saying the target is the recorded one. It judges everypart three ways — what the record says the importlast wrote there, what is on disk, and what the source drafts now:
- a part the source left as the import last wrote it stays exactly as it is on disk, whether or not you edited it; - a part the source changed is written anew, where it is on disk as the import last wrote it; - a part the source dropped is removed, where it is as the import last wrote it and holds nothing you added — a drafted file is deleted whole; - a part the source gained is added beside the parts the draft names around it.
Everything else stays byte for byte: a key you added anywhere — a parameter, aFeature, under a drafted Component instance too, another Component, theenvironment a drafted Release leaves for you — a comment not written directlyabove a drafted key, and every file the record does not list. Before anything is written, standard error names each part that drifted,one line each:
added|removed|changed <key> in <file> added|removed|changed <file>
Where the sync would change or remove a part you edited, add a part where youalready wrote one, or remove a part holding something you added, import stops,naming each such part and why, and writes no draft (an answer you typed is keptin the answers file); reconcile them by hand and sync again. A comment you write directly above a drafted key edits that key.An Aggregate at a drafted path that no record lists stops the sync too, sayingso, as does a record that cannot be read. Where the importer reports adiagnostic that stops the import, a sync writes nothing. A sync into a directoryholding no record and nothing at its drafted paths writes the whole draft.
With --sync, --dry-run writes nothing and names the same drift, or stops on thesame conflicts, and the exit status says which: 0 when the drafts are in stepwith the source, 2 when they drifted, and 1 on an error or when the sync isrefused. Standard output carries the files the sync would write, with thecontent it would give them.
On Windows, a draft whose path holds a part Windows cannot hold as written — aname it reserves for a device, such as NUL or aux, with or without an extensionand in any letter case, or a part ending in a full stop or a space — is refusednaming the draft, and nothing is written. On every other platform such a draftis written as it is named.
The source format selects how the importer reads the source. Pass --format toname it explicitly. When --format is omitted, import recognizes the format bythe signatures the importers declare — the workspace catalog's and the coreimporters' alike: each names the syntax a source is read in, the file names itapplies to and the paths its parsed tree must or must not carry. A file isparsed once for each syntax a signature applying to its name reads it in, andthe format of the one importer whose signature matches is the one read. Thesignatures of the Langflow, Flowise and n8n importers, the MCP importer's for aregistry server description and the LangGraph importer's for a configurationnaming its schema, read a file as JSON and name no file, andthe Dify and Agent Framework importers' read it as YAML and name no file, sorecognizing a file imported on its own reads it as JSON and as YAML too. The Dify importerrecognizes an application Dify exports, under any name, by app at its kind andby the application's mode at app.mode and the DSL's version at version.The MCP importer recognizes a client's configuration by its name — .mcp.json,claude_desktop_config.json and .cursor/mcp.json read as JSON, .vscode/mcp.jsonread as JSON with comments, as Visual Studio Code reads it — so such a file underanother name is imported naming --format mcp. The Compose importer reads a file as YAML and recognizes it by the namesCompose reads by default — compose.yaml, compose.yml, docker-compose.yml anddocker-compose.yaml, and their override files compose.override.yml,compose.override.yaml, docker-compose.override.yml anddocker-compose.override.yaml — and an object at services, so a Compose fileunder another name is imported naming --format compose. The CrewAI importerrecognizes a project's declarations by their names: config/agents.yaml andconfig/tasks.yaml, read as YAML, and crew.jsonc holding a list at agents andagents/<name>.jsonc holding a role, read as JSON with comments, as are theirstrict-JSON spellings crew.json and agents/<name>.json, a .json file not beingread where its .jsonc spelling is handed too; it is handed those files and noother, so a crew's program is never read. The LangGraph importer recognizes anapplication's configuration, read as JSON with an object at graphs, by its name,langgraph.json, or, under any name, by https://langgra.ph/schema.json at its$schema; of a directory it is handed that file alone, so neither theapplication's code nor an environment file is ever read, and the environmentfile a configuration names is read, for its variables' names alone, only wherethe importer's with.sources hands it. The Google ADK importer recognizes an application's root agentconfiguration, read as YAML, by its name, root_agent.yaml, and an agent's namewith its instruction or its agent_class; of a directory it is handed eachroot_agent.yaml alone, so neither the application's code nor its environmentfile is ever read, and the configuration a sub_agents entry names is read onlywhere the importer's with.sources hands it. The Agent Framework importerrecognizes a declarative agent, under any name, by Prompt at its kind and anobject at its model, read as YAML; it names no file, so a directory is neverhanded to it, and a declarative agent is imported as a file of its own. A directory isrecognized the same way over the files it holds: each signature is tried against the filesits file names match, and a signature that names no file applies to none ofthem. If no signature matches, import stops, asks for --format and names theformats the importers advertise — or, for a directory, asks for one of itsfiles imported on its own or for a format whose importer declares filepatterns, naming only those; if signatures of more than one format match,it stops and names them. It does not guess. Recognition reads nothing but thesource — of a directory, only the files a signature's file names match — andreaches no network.
Recognition and the importer read the source through the parser theworkspace's catalog serves for its syntax, and, for a syntax the catalogserves no parser for, through the parser the compiler itself carries for it —JSON, JSON with comments and YAML among them — so a workspace whose catalog holds no parser stillrecognizes and imports a source the core importers read. Where the catalogserves a parser for a syntax, the compiler's own plays no part in reading it.The compiler's parsers are part of the binary, so nothing is fetched for one.A syntax neither serves stops the import, naming the syntax no parser serves,and a source its parser refuses stops the import with the parser's reason.
Before the drafted output, import names on standard error the format it readthe source as and the directory the drafted paths are relative to, then anydiagnostics the importer reported, then one line for each source node theimporter mapped, in the importer's order:
mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>
naming the catalog Component or draft it chose for the node, whether it isreferenced or drafted, the match tier, and the score of the best candidate itweighed. A node the importer weighed no candidate for has no score, and its lineends at the tier; a node it made no choice for reads "made no choice for <nodeid> (<node type>)"; then, under --sync, the drift lines. Standard outputcarries only the result — the paths written, and under --sync the pathsremoved, or the drafted files themselves under --dry-run — so it can be pipedunchanged.
--dry-run does everything import does except write: standard output carries onedocument listing each drafted file's path and its content, so the result can bereviewed, parsed or piped before anything reaches disk. Every other behaviour isthe write's — the same importer runs over the same source and reports the samediagnostics — so what a dry run shows is what a write would put on disk, and asource the write would refuse is refused here too.Flag
| Flag | Default | Deskripsi |
|---|---|---|
--answers | — | File jawaban tempat nilai-nilai yang dibiarkan kosong oleh draf dan tidak dapat ditampung oleh sumber mana pun dibaca dan ditulis: di bawah path setiap file yang didrafkan, path kunci di dalamnya beserta jawabannya. Path relatif di-resolve terhadap direktori tempat Anda menjalankan perintah. Tanpa opsi ini, digunakan file jawaban yang disebutkan oleh catatan di samping draf, atau jika tidak ada, import-answers.yaml di samping file sumber, atau di dalam direktori sumber. Jawaban untuk sebuah secret adalah nama asal secret tersebut, bukan secret itu sendiri. |
--dry-run | false | Lakukan semuanya kecuali menulis: kembalikan berkas-berkas draf sebagai konten, dengan menyebutkan berkas tujuan masing-masing, dan jangan membuat atau mengubah apa pun. Semua perilaku lainnya sama dengan penulisan, termasuk menjalankan importer. Tanpa opsi ini, draf ditulis ke disk. |
--format | — | Sebutkan format sumber secara eksplisit, mengesampingkan deteksi berdasarkan tanda tangan importer (misalnya langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk, atau agent-framework) |
--output-dir | — | Direktori tempat berkas-berkas draf ditulis. Jalur relatif diresolusi terhadap direktori tempat Anda menjalankan perintah, dan drive yang disebutkan tanpa jalur di Windows, seperti D:, adalah direktori saat ini pada drive tersebut. Tanpa opsi ini, draf ditulis di bawah akar workspace yang diresolusi oleh eksekusi. |
--sync | false | Perbarui apa yang didrafkan oleh impor sebelumnya agar sesuai dengan sumber, dengan hanya mengubah apa yang ditulis impor, sebagaimana tercantum dalam catatan di samping draf, dan menyebutkan setiap bagian yang menyimpang. Dengan —dry-run, keluar dengan 0 jika selaras, 2 jika menyimpang, 1 jika terjadi kesalahan atau penolakan. |
--target | — | Draf sebuah Manifest untuk kapabilitas provider ini — kata yang menjadi ikatan spec.capability sebuah Recipe, misalnya compose atau helm — dengan memetakan setiap tipe komponen dan tipe fitur yang dibutuhkan draf ke Recipe atau resep fitur untuk kapabilitas itu yang ditawarkan katalog workspace untuknya, yaitu satu-satunya yang ada atau, di antara beberapa, yang dinamai sesuai tipenya, dan arahkan Release yang didrafkan ke Manifest tersebut. Kapabilitas yang tidak menjadi ikatan Recipe mana pun di katalog ditolak sebelum importer berjalan. Tanpa opsi ini, tidak ada Manifest yang didrafkan, kecuali bahwa —sync menggunakan kembali target yang diberikan pada impor sebelumnya. |
--upgrade | false | Baca ulang katalog yang diterbitkan dari keadaan registry saat ini: ambil snapshot katalog terbaru yang diterbitkan registry default ruang kerja, verifikasi, dan impor terhadapnya, dengan menyimpannya sebagai snapshot yang dibaca ruang kerja ini sejak saat itu, menggantikan snapshot yang disimpannya atau yang disebutkan catatan di samping draf. Hanya berpengaruh jika ruang kerja tidak menyebutkan folder katalog apa pun, dan ditolak di bawah —offline |