이 페이지는 기계 번역되었습니다. 영어 원문 읽기.
aggrega import
외부 소스 설명을 Aggrega 작성 파일 초안으로 변환
이 페이지는 명령의 참조 문서입니다. 가져오기의 용도와 프로젝트를 소스에서 빌드까지 진행하는 단계별 안내는 가져오기에 있습니다. 어떤 소스도 담을 수 없는 값을 읽어 오는 응답 파일과 터미널에서 묻는 질문은 가져오기 응답 파일에 설명되어 있습니다.
개요
aggrega import <file or directory> [flags]설명
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.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--answers | — | 초안이 비워 두고 어떤 소스도 담을 수 없는 값을 읽고 쓰는 답변 파일입니다. 초안으로 작성된 각 파일의 경로 아래에 그 안의 키 경로와 답변을 둡니다. 상대 경로는 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 이 플래그가 없으면 초안 옆의 기록이 지정하는 답변 파일을, 그렇지 않으면 소스 파일 옆 또는 소스 디렉터리 안의 import-answers.yaml을 사용합니다. 시크릿의 답변은 시크릿을 가져오는 위치의 이름이며, 결코 시크릿 자체가 아닙니다. |
--dry-run | false | 쓰기를 제외한 모든 작업을 수행합니다. 초안 파일을 각 파일의 대상 파일명과 함께 내용으로 반환하며, 아무것도 생성하거나 수정하지 않습니다. 임포터 실행을 포함한 그 밖의 모든 동작은 쓰기 때와 같습니다. 이 플래그가 없으면 초안이 디스크에 기록됩니다. |
--format | — | 소스 형식을 명시적으로 지정하여 임포터 시그니처에 의한 감지를 재정의합니다(예: langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk 또는 agent-framework) |
--output-dir | — | 초안 파일이 기록될 디렉터리입니다. 상대 경로는 명령을 실행한 디렉터리를 기준으로 해석되며, Windows에서 D:처럼 드라이브 이름만 지정하면 해당 드라이브의 현재 디렉터리를 뜻합니다. 이 플래그가 없으면 초안은 실행 시 확인된 워크스페이스의 루트 아래에 기록됩니다. |
--sync | false | 이전 가져오기로 작성된 초안을 소스에 맞게 최신 상태로 갱신합니다. 초안 옆의 기록에 나열된 대로 가져오기가 작성한 부분만 변경하며, 어긋난 각 부분을 알려 줍니다. —dry-run과 함께 사용하면 일치할 때 0, 어긋났을 때 2, 오류 또는 거부 시 1로 종료합니다. |
--target | — | 이 provider 기능(Recipe의 spec.capability가 바인딩되는 단어, 예: compose 또는 helm)에 대한 Manifest를 작성합니다. 초안에 필요한 각 컴포넌트 유형과 피처 유형을 워크스페이스의 카탈로그가 해당 유형에 제공하는 그 기능의 Recipe 또는 피처 레시피(하나뿐이면 그것, 여러 개 중에서는 해당 유형의 이름을 딴 것)에 매핑하고, 초안 Release가 이 Manifest를 가리키도록 합니다. 카탈로그의 어떤 Recipe도 바인딩되지 않는 기능은 임포터가 실행되기 전에 거부됩니다. 이 플래그가 없으면 Manifest가 작성되지 않지만, —sync는 이전 가져오기에 지정된 대상을 재사용합니다. |
--upgrade | false | 현재 레지스트리 상태에서 게시된 카탈로그를 다시 읽습니다. 워크스페이스의 기본 레지스트리가 게시하는 최신 카탈로그 스냅샷을 받아 와 검증하고 그에 대해 가져오며, 이후 이 워크스페이스가 읽는 스냅샷으로서 보유 중인 스냅샷이나 초안 옆의 기록이 지정하는 스냅샷 대신 보관합니다. 워크스페이스가 카탈로그 폴더를 지정하지 않은 경우에만 효과가 있으며, —offline에서는 거부됩니다 |