워크스페이스 경계
워크스페이스는 프로젝트 루트가 표시하는 디렉터리 트리입니다. 구성의 workspace:
블록이 있는 루트, --workspace-root가 지정하는 루트, 편집기가 연 폴더, 또는 어시스턴트의
서버가 시작된 기준 폴더가 여기에 해당합니다. Aggrega가 스스로 읽고 쓰는 모든 것은 그 트리 안으로 제한되며,
사용자나 워크스페이스 구성이 그 바깥의 위치를 지정한 경우만 예외입니다. 트리 안의 심볼릭 링크는
머신의 어느 곳이든 가리킬 수 있으므로, 링크가 트리 안에 있다는 이유만으로 워크스페이스의 일부로 간주되지는
않습니다. 중요한 것은 링크가 어디로 이어지는가입니다.
이 페이지는 규칙 전체를 설명합니다. 각 인터페이스의 페이지인 명령줄, 언어 서버, 어시스턴트 도구에서는 각자의 요청이 이 규칙을 어떻게 따르는지 설명합니다.
워크스페이스 안에 있는 것
경로 중 존재하는 가장 깊은 부분이 링크를 따라갔을 때 워크스페이스 루트이거나 그 아래에 있으면, 그 경로는 워크스페이스 안에 있습니다 — 루트 자체의 링크도 같은 방식으로 따라가므로, 워크스페이스 자신의 링크를 통해 도달한 워크스페이스도 그 아래의 모든 것을 그대로 포함합니다.
링크를 통해 연 루트는 그 링크가 가리키는 워크스페이스입니다. 연 폴더 자체가 링크이든 그 위의 링크를 통해 도달한 것이든, Aggrega는 링크가 가리키는 워크스페이스에서와 정확히 같은 것을 나열하고 읽고 씁니다 — 그 Releases, 문서, lockfile을 — 그리고 그 안의 모든 링크를 같은 방식으로 판단합니다. 응답의 모든 경로는 여전히 주어진 그대로의 루트를 기준으로 표기됩니다 — 편집기가 연 폴더, 입력한 --workspace-root, 셸이 현재 작업 중이라고 알려 주는 디렉터리 — 따라서 표시되는 내용은 작업 중인 경로와 일치합니다.
이 하나의 해석이 모든 종류의 경로에 적용됩니다.
- 경로를 결정하는 것은 표기 방식이 아니라 경로가 이르는 곳입니다.
./shared/app.yaml은 모든 부분이 워크스페이스 안에 쓰여 있더라도,shared가 다른 곳의 디렉터리를 가리키는 링크이면 바깥에 있습니다. 요청 매개변수는 여전히 자체적인 표기 방식을 요구할 수 있으며(예: 루트 기준 상대 경로), 그 경우 해당 페이지에 그렇게 명시되어 있습니다. 이는 매개변수에 관한 규칙이지 경계에 관한 규칙이 아닙니다. - 아직 존재하지 않는 경로는 그 경로에 이르는 디렉터리로 판단합니다. 바깥으로 이어지는 링크인
dist아래에 빌드가 생성하려는 파일은 쓰이기 전부터 바깥에 있습니다. - 아무 곳으로도 이어지지 않거나 루프를 도는 링크는 존재하는 것이 아닙니다. 대신 그 링크를 담은 디렉터리로 판단하며, 링크가 원래 가리키려던 곳을 알아내기 위해 아무것도 따라가지 않습니다. 그런 링크가 파일이 생성될 바로 그 위치에 있으면, 파일이 실제로 놓일 곳이 그곳이므로 링크가 가리키는 위치도 함께 확인합니다.
- 워크스페이스 안의 다른 곳을 가리키는 링크는 평소대로 따라갑니다. 바깥으로 이어지는 링크만 막힙니다.
이 규칙은 경로가 디스크에서 어디로 이어지는지만 판단합니다. 어떤 값도 읽지 않으며 이름으로부터 아무것도 추론하지 않습니다.
밖으로 이어지는 링크가 하는 일
밖으로 이어지는 경로가 어떻게 처리되는지는 그 경로의 종류에 따라 달라집니다. 결과는 세 가지입니다.
읽지 않은 것으로 나열됨
Aggrega가 워크스페이스에 들어 있는 것을 나열할 때, 밖으로 이어지는 링크는 읽지 않으며 목록에 그 사실이 표시됩니다. 편집기가 선택지로 제시하는 Releases, 엔터티 인덱스와 편집기가 그 인덱스에서 가져오는 자동 완성 및 후보, 어시스턴트의 list-releases와 list-entities는 워크스페이스 밖의 디렉터리를 검색하지 않고 워크스페이스 밖의 파일을 읽지 않습니다. 그 파일이 무엇을 선언하든 마찬가지입니다. 따라서 편집기가 그런 링크 아래에 보여 주는 엔터티는 워크스페이스 자체의 것으로 나열되지 않습니다. Release 목록과 엔터티 목록은 그런 링크를 모두 링크가 이어지는 곳이 아니라 워크스페이스 안에서 링크 자체가 있는 위치로 표시합니다. 언어 서버에서는 unreadLinkedDirs와 unreadLinkedFiles, 어시스턴트 도구에서는 unread_linked_dirs와 unread_linked_files입니다. 구성의 catalog_dirs에 나열된 디렉터리나 그 아래의 디렉터리, 또는 구성이 지정하는 Release로 가는 링크는 표시되지 않습니다. 아래 예외에서 설명하듯이, 구성이 그 위치에 도달했기 때문입니다. 나열된 디렉터리는 그 아래의 모든 것과 함께 읽힙니다. 밖으로 이어지는 링크인 .gitignore도 읽지 않으므로, 머신의 다른 곳에 있는 파일이 워크스페이스의 어떤 문서를 검색할지 결정하는 일은 없습니다. 밖으로 이어지는 링크인 워크스페이스 구성 파일도 읽지 않은 파일 가운데 표시됩니다. 이 목록들은 아무것도 구성되지 않은 상태로 읽은 그 워크스페이스에 대해 여전히 응답하지만, 구성이 결정하는 모든 요청은 아래 워크스페이스 자체의 구성에서 설명하듯이 중단됩니다.
거부됨
요청이 지정하는 경로는, 호출자가 그 경로를 직접 입력하는 머신 소유자가 아닌 경우 거부됩니다. 아래 예외를 제외하면, 편집기가 aggrega serve에 보내는 요청에서 서버가 읽거나 쓰도록 지정하는 모든 경로와, 어시스턴트가 HTTP로 연결된 서버에 지정하는 모든 경로는 워크스페이스 안으로 이어져야 합니다. 밖으로 이어지는 경로는 아무것도 읽거나 쓰지 않은 채 거부되며, 각 인터페이스의 페이지에서 설명하듯이 거부 메시지에 해당 매개변수가 표시됩니다. 문서 편집은 명령줄을 포함한 모든 인터페이스에서 이와 같이 거부됩니다. 문서 편집은 안쪽에 머뭅니다를 참조하십시오.
중단됨
작업이 스스로의 판단으로 밖으로 이어지는 링크를 통해 읽거나 쓰게 되는 경우, 작업이 중단됩니다. 이들은 사용자가 지정한 경로가 아니라 제품이 스스로 산출하는 경로이며, 그런 경로를 조용히 건너뛰면 빌드의 의미가 달라질 수 있습니다. 따라서 각 경우 작업을 중단하고, 링크와 그 링크가 이어지는 곳을 표시하며, 링크가 가리키는 위치는 원래 상태 그대로 둡니다.
- 조회가 읽는 것 — 카탈로그 디렉터리 아래의 문서, 또는 자신의
Aggregate나 Manifest를 식별자로 지정하는 Release 옆의 문서, 또는 자신이 확장하는 Manifest를 그런 방식으로 지정하는 Manifest 옆의 문서입니다. 작업에 지정된 Release나 Manifest는 이러한 문서에 포함되지 않습니다. 그것은 지정된 위치에서 읽혔습니다. 링크를 통해 지정된 Release 또는 Manifest를 참조하십시오.
그런 링크를 건너뛴 조회는 뒤쪽 디렉터리에 있는 같은 이름의 다른 엔터티를
대신 해석할 수 있으므로, 빌드, 풀, 검증, 카탈로그를 읽는 검사, 하나의 Release 또는 카탈로그 전체에 대한 린트, 그리고 Release를 빌드, 미리 보기, 그래프 작성, 검증, 린트 또는 설명하는 편집기와 어시스턴트의 요청은 모두 무언가가 해석되거나 검사되기 전에 중단됩니다.
E0321. - Release의 lockfile — 빌드, 풀, 검증, 린트,
검사,
aggrega cache prune, 그리고 편집기와 어시스턴트의 요청이 해석의 기준으로 삼는 고정 버전을 얻기 위해 Release 옆에서 읽힙니다. lockfile은 쓰이는 위치와 마찬가지로 읽히는 위치에서도 그대로 보호되므로, 밖으로 이어지는 링크인 lockfile은 머신의 다른 곳에 보관된 고정 버전을 빌려주는 대신 각 작업을 중단시킵니다.E0321. - 엔터티 옆에서 읽는 파일 — 고정하거나 게시하는 엔터티의 디렉터리에 있는 다른 문서로,
다른 엔터티가 그 디렉터리를 공유하는지 판단하기 위해 읽습니다. 그리고 카탈로그 디렉터리의 Plugin 엔터티가 로드되는 빌드된
.wasm입니다. 각 파일은 엔터티 자체 문서가 읽힌 디렉터리 안에서만 읽힙니다. 즉 워크스페이스, 그 밖에 지정한 카탈로그 디렉터리, 또는 그 밖에 지정한 문서의 디렉터리입니다. 따라서 밖으로 이어지는 링크인 파일은aggrega pin,aggrega push(드라이 런 포함), 고정을 수행하는 풀, 그리고 편집기와 어시스턴트의 고정 및 게시를 중단시키며(읽지 않은 문서가 방해가 되는 엔터티일 수 있습니다), 머신의 다른 곳에 보관된 바이트를 실행하는 대신 플러그인을 로드하는 빌드나 풀을 중단시킵니다.E0321. - 아티팩트 캐시 — Aggrega가
artifact_cache_dir아래의 캐시에서 읽는 모든 것입니다. 캐시된 엔터티, 플러그인 또는 라이브러리와 그 옆의 매니페스트, 소스 아카이브와 그 메타데이터, 고정된 외부 입력, 서명 번들과 레지스트리의 로컬 검색 인덱스, 그리고aggrega cache status,aggrega cache prune,aggrega cache clear가 나열하는 모든 워크스페이스 항목이 여기에 해당합니다. 캐시는 캐시가 쓰이는 위치인 캐시 디렉터리 안에서만 읽히므로, 그 안에서 해당 디렉터리 밖으로 이어지는 링크는(워크스페이스의 다른 곳으로 이어지든 그 밖의 어디로 이어지든) 빌드, 풀, 검증, 검색, 세 가지 캐시 명령 각각, 그리고 캐시를 읽는 편집기와 어시스턴트의 요청을 중단시킵니다. 캐시가 소유하지 않은 곳에 보관된 바이트를 넘겨주지 않기 위해서이며, 기록된 다이제스트와 대조해 확인된 콘텐츠도 포함됩니다. 다이제스트는 바이트가 무엇인지를 알려 줄 뿐, 어디에서 읽어도 되는지는 알려 주지 않기 때문입니다.aggrega inspect가 출력하는 지원 중단 안내는 아무것도 결정하지 않으므로 제외됩니다. prune 또는 clear는 그런 링크인 캐시 자체의 디렉터리나, 그 자체가 워크스페이스 밖으로 이어지는 링크인 캐시 디렉터리를 만나면, 그것을 해당 작업이 수행하게 될 삭제로 취급하여 무엇이든 나열하기 전에E0320으로 중단합니다.E0321. - 소스가 가져오는 저장소 — 풀이
git-repository소스를 위해 아카이브하는 체크아웃입니다. 체크아웃은 그 자체로 하나의 디렉터리이므로, 저장소에 포함된 링크는 가리키는 대상이 저장소 안에 있을 때만 그 대상으로 아카이브됩니다. 저장소 밖으로 이어지는 링크는 풀을 실행하는 머신의 어떤 파일에든 도달할 수 있으므로, 링크와 그 링크가 이어지는 곳을 표시하며 아무것도 캐시하지 않은 채 풀을 중단시킵니다.module_subdir자체가 그런 링크인 경우도 포함됩니다.E0321. 풀이 중단되면 체크아웃이 사라지므로, 메시지는 저장소 안에서의 링크 위치와 소스가 지정하는 저장소 및 리비전으로 링크를 표시합니다. 작성된 그대로 저장소 위로 올라가는module_subdir는 저장소를 가져오기 전에 거부되므로, 체크아웃 옆의 어떤 것도 읽히지 않습니다.E0307. - 가져오는 디렉터리의 파일 —
aggrega import, 어시스턴트의 가져오기 도구, 세션의aggrega/import는 디렉터리가 주어지면 그 디렉터리에서 임포터의 파일 패턴이 선택하는 파일을 읽습니다. 이 디렉터리는 어디에 있든 그 자체로 하나의 루트입니다. 가져오는 디렉터리를 참조하십시오. 따라서 그 파일 중 디렉터리 밖으로 이어지는 링크나, 디렉터리 밖으로 이어지는 디렉터리로의 링크가 있으면 디렉터리의 파일을 하나라도 읽기 전에 그 링크를 명시하며 가져오기가 중단됩니다:E0321. - 워크스페이스 자체의 구성 — 루트부터 명령이 실행되는 디렉터리까지의 모든
.aggrega-config.yaml과, 그 옆에 있는 파이프라인의.aggrega-config-append-ci.yaml입니다. 구성을 읽는 모든 명령, 언어 서버, 어시스턴트의 도구는 무엇보다 먼저 구성을 읽으므로, 이 파일 중 하나가 밖으로 이어지는 링크이면 남은 것으로 만든 구성으로 실행하게 두지 않고 그 시점에서 각각을 중단합니다:E0321. 구성을 읽지 않는aggrega명령 —version,help,completion,explain,get-schema, 시작 문서 초안을 작성하는scaffold,skills list,plugin run-local,plugin sync,auth token,logout— 은 링크를 지목하는 경고와 함께 평소대로 실행됩니다.scaffold --example은 기본 레지스트리와 서명 정책을 위해 구성을 읽으며, 구성을 읽는 다른 모든 주체와 마찬가지로 그 시점에서 중단됩니다. 언어 서버와 자체 스트림으로 통신하는 어시스턴트 서버는 이런 워크스페이스에서도 시작되어 그 안의 내용을 나열할 수 있습니다. Release 목록과 엔터티 목록은 카탈로그 디렉터리를 비롯해 아무것도 구성되지 않은 상태로 읽어 응답하며, 그 파일을 읽지 않은 링크 중 하나로 명시합니다. 구성이 결정하는 그 밖의 모든 요청 — 빌드, 미리보기, 그래프, 검증, 린트, 설명, 유효 구성, 기본 Release — 은 링크를 명시하며E0321로 중단되고, HTTP로 수신하도록 요청받은 어시스턴트 서버도 마찬가지입니다. 그 주소와 인증은 구성이 설정했을 것이기 때문입니다. - 작업이 쓰거나 제거하는 것 — 빌드의 출력 디렉터리, 그 경계 디렉터리와 그곳에 쓰이는 모든 파일, 트레이스; Release의 lockfile과 그 옆의 플러그인 신뢰 기록;
entity.lock; 명령이 쓰는 워크스페이스 구성 파일; 아티팩트 캐시와, pull이 채우거나aggrega cache clear와aggrega cache prune이 비우는 그 각 부분; 가져오기가 쓰는 초안과aggrega plugin gen-catalog가 쓰는 Plugin 엔터티; 그리고 편집기가 기본 Release를 기록하는.aggrega/active-release마커로, 언어 서버가 편집기 대신 씁니다. 링크인dist가 있으면 “출력 다시 빌드”가 기기의 다른 곳에 있는 디렉터리를 삭제하는 일이 될 수 있습니다:E0320. - 문서가 경로로 명시하는 것 — 문서가 작성하는 참조를 참조하십시오:
E0324. - 엔터티가 선언하는 콘텐츠 — 경로가 엔터티 자체 디렉터리 밖으로 이어지는 링크인 디렉터리를 지나는
source:또는$import:로, 그렇지 않으면 게시 시 엔터티 내부의 이름으로 포함될 것입니다:E0304.
이 규칙은 작업을 시작한 주체가 명령줄, 편집기, 어느 전송 방식의 어시스턴트이든 똑같이 적용됩니다. 해당 경로는 호출자의 것이 아니라 워크스페이스와 제품의 것이기 때문입니다.
문서가 작성하는 참조
Release와 Manifest는 경로로 다른 파일을 지정할 수 있습니다. ./… 또는 ../… 형태로 작성된 Release의 aggregate:와 manifest:, Release의 extends:, 경로로 작성된 Manifest의 extends:, 그리고 Release의 parameters: { $import: … }가 이에 해당합니다. 워크스페이스 안의 문서는 이 방식으로 워크스페이스 안의 파일에만 도달합니다 — 작성된 그대로 밖으로 올라가는 경로는 거부되며, 작성된 그대로는 안에 머물지만 도중에 밖으로 이어지는 링크를 만나는 경로도 거부됩니다. 어느 경우든 지정된 파일에서는 아무것도 읽지 않습니다.
복제한 워크스페이스에는 그 작성자의 참조가 담겨 있으므로, 직접 지정하는 경로만 제한하고 문서가 이어서 가리키는 곳은 무엇이든 따라간다면 경계는 ../ 하나만으로 벗어날 수 있게 됩니다. 문서가 다른 곳에 보관된 엔터티를 필요로 하는 경우에는 파일 대신 엔터티를 이름으로 지정하고(aggregate: payments), 워크스페이스 구성에 그 엔터티를 담은 카탈로그 디렉터리를 나열합니다. 이름은 따라가는 것이 아니라 조회하는 것이므로 여기서 거부되는 일이 없습니다.
워크스페이스 밖에 있지만 직접 지정했기 때문에 허용된 Release나 Manifest는 자신의 디렉터리 안의 파일에만 도달합니다 — 예외는 지정한 디렉터리까지만 도달하며 그 이상은 도달하지 않습니다를 참조하십시오.
예외, 그리고 각각이 예외인 이유
다음 부류에 속하는 경로는 워크스페이스 안이든 밖이든 그 경로가 가리키는 곳에서 그대로 인정됩니다. 각각은 장소의 목록이 아니라 경로의 한 부류이며, 각각 고유한 이유로 예외가 됩니다.
- 워크스페이스 구성이 명명하는 것. 구성의 카탈로그 디렉터리(워크스페이스용 또는
workspace.releases아래 Release용catalog_dirs와catalog_dirs_append),workspace.releases아래에 키로 지정된 Release 파일,build.authoring_release, 플러그인 첨부의 로컬.wasm과 그with.sources아래의 파일,mcp.tls.cert_file,mcp.tls.key_file,mcp.authorization.jwks_file, 레지스트리의 고정된 신뢰 루트, 그리고 워크스페이스 루트 밖으로 올라가는artifact_cache_dir입니다. 구성에서 경로를 명명하는 것은 워크스페이스가 자신의 밖에 도달하는 의도된 방법입니다: 경로는 한 번 기록되고, 프로젝트와 함께 보관되며, 프로젝트를 검토하는 누구나 읽을 수 있습니다. 워크스페이스의 관례적인catalog디렉터리는 구성이 이를 나열하거나--catalog로 전달할 때 명명된 것으로 간주됩니다. 또는 이 디렉터리가 이어지는 위치를 어떤 표기로든, 혹은 그 위치보다 위의 디렉터리를 구성이 나열하거나 전달할 때도 마찬가지이며, 이 경우 그곳에 있는 것을 명명한 디렉터리를 통해 한 번 읽습니다. 단지 그곳에 있기 때문에 읽히는 경우 이 디렉터리는 워크스페이스 자체의 콘텐츠이므로, 워크스페이스 밖으로 이어지는 링크인catalog는 그것이나 그것이 이어지는 곳을 명명하기 전까지 읽히지 않습니다. - 명령줄에 입력한 경로.
aggrega build --release ../other/release.yaml,--catalog /srv/shared-catalog,--output-dir, 검증, 린트, 고정 또는 게시할 파일: 각각은 가리키는 곳에서 그대로 사용됩니다. 단, 아래의 문서 편집은 예외입니다. 명령이 실행되는 머신은 사용자의 것이며 입력할 수 있는 모든 것을 이미 읽고 쓸 수 있으므로, 사용자를 특정 디렉터리에 묶어 두어도 얻는 것이 없습니다. - 어시스턴트가 프로세스 자체의 스트림을 통해 지정하는 경로. 사용자의 머신에서
aggrega mcp를 실행한 클라이언트는 사용자 권한으로 실행되며, 보통 그 호스트가 자체 파일 및 셸 도구를 제공하므로, 클라이언트가 지정하는 경로는 사용자가 직접 입력한 것처럼 인정됩니다. The two assistant transports(두 가지 어시스턴트 전송 방식)를 참조하십시오. - 제품의 머신 전역 저장소: 전역 구성 파일, 컴파일된 모듈 저장소, 플러그인 디스크립터 캐시, 문서 번들, 레지스트리 자격 증명 저장소입니다. 이들은 어떤 워크스페이스가 아니라 머신에 속하므로, 어떤 워크스페이스도 이를 보유하지 않습니다.
- 대화 상자에서 선택하여 그 위치에서 읽는 파일 또는 디렉터리. 편집기는 레지스트리 등록의 키 파일이나 신뢰
루트,
aggrega/import가 변환하는 설명(파일 또는 임포터가 그 안의 파일을 읽는 디렉터리), 그리고aggrega/pluginGenCatalog가 옆의 오버레이와 함께 엔터티를 생성하는 모듈을 절대 경로로 보냅니다. 각각은 사람이 어디에 보관하든 직접 선택한 것입니다. 이들은 읽기만 됩니다. 요청이 쓰는 어떤 것도 이렇게 선택된 경로로 가지 않습니다. 이렇게 선택된 디렉터리는 임포트하는 모든 디렉터리와 마찬가지로 그 자신 안으로 제한됩니다. - 편집기가 열어 둔 문서. 문서의 검증, 진단 요청 또는 삭제, 호버, 완성, 해석, 그리고 문서 안의 참조와 구현 찾기는 편집기가 보낸 내용으로 응답되므로, 문서를 지정하는 경로에서는 어떤 파일도 읽히지 않으며, 그 경로는 가리키는 곳 때문에 거부되는 일이 없습니다. 디스크에서 문서를 실제로 읽는 요청은 위에서 설명한 거부되는 종류에 해당합니다.
명령줄에 입력한 경로와 머신 전역 저장소는 전혀 판정되지 않습니다. 나머지는 그 경로를 우연히 담고 있는 요청이 아니라 경로의 부류에 따라 허용됩니다.
예외는 지정한 디렉터리까지만 미치며 그 이상은 미치지 않습니다
워크스페이스 밖에서 지정한 디렉터리는 그 아래에서 읽거나 쓰는 모든 것에 대해 그 자체로 하나의 루트입니다. 디렉터리 자체는 지정한 그대로 사용되며(링크인 디렉터리는 가리키는 곳까지 따라갑니다), 그 아래에서 디렉터리 밖으로 이어지는 링크는 워크스페이스 안의 링크와 똑같이 취급됩니다. 즉, 목록에서는 읽히지 않으며 조회나 쓰기를 중단시킵니다. 따라서 워크스페이스 밖에 나열한 카탈로그 디렉터리, aggrega plugin gen-catalog나 aggrega import에 전달한 출력 디렉터리, 그리고 워크스페이스 밖으로 올라가는
artifact_cache_dir는 각각 그 아래에 있는 것을 자신 안으로 제한합니다. 지정한 디렉터리가 워크스페이스 안에 있으면 워크스페이스가 루트가 됩니다. 단, 임포트하는 디렉터리는 예외이며, 이는 어디에 있든
그 자체로 하나의 루트입니다.
지정한 디렉터리는 그 아래에 무엇이 놓이기 전에 실행 중인 폴더를 기준으로 해석됩니다.
aggrega import에 상대 경로로 입력하여 전달한 출력 디렉터리는 명령을 실행하는 폴더 안의 해당 이름의 폴더이며, Windows에서 드라이브만 지정한 경우(D:)는 그 드라이브의 현재 폴더입니다. 디렉터리는 먼저 전체 경로로 바뀌고 모든 파일은 그 전체 경로 아래에 놓이므로, 이름이 구분자로 시작하는 파일(예: \notes.txt)은 드라이브의 최상위가 아니라 지정한 디렉터리 안에 놓이며, 명령이 보고하는 디렉터리가 실제로 쓰인 디렉터리입니다.
워크스페이스 밖에서 지정한 Release나 Manifest는 같은 규칙을 파일에 적용한 것입니다: 그 자신의 디렉터리가 루트이므로, 그것이 경로로 지정하는 것과 그 extends: 체인이 이어지는 모든 Release가 지정하는 것은 그 디렉터리 안에 머물러야 합니다. Aggregate 및 Manifest 옆에 보관된 Release는 어디에서든 빌드됩니다. 일반적인 releases/ 레이아웃에 있으며 ../aggregates/app.yaml을 지정하는 Release는 대신 자신의 워크스페이스에서 빌드됩니다.
링크를 통해 지정한 Release 또는 Manifest
링크를 통해 지정한 Release는 링크가 가리키는 곳에서 읽히고, 지정한 곳에서 해석됩니다.
release.yaml이 다른 곳에 보관된 파일에 대한 링크일 때 --release release.yaml로 입력하거나, workspace.releases 아래에 또는 build.authoring_release로 그렇게 지정하면, Release는 링크가 가리키는 곳에서 읽힙니다. 그 Release가 식별자나 경로로 지정하는 Aggregate와 Manifest는 링크 옆, 즉 Release를 지정한 디렉터리에서 찾으며, 그 디렉터리의 루트로 제한됩니다. 루트는 워크스페이스이거나, 디렉터리가 워크스페이스 밖에 있으면 그 디렉터리 자체입니다. lockfile도 링크가 가리키는 곳이 아니라 링크 옆에서 읽고 씁니다. Release 자체는 자신의 조회가 옆에서 만나는 문서에 포함되지 않으므로 그 조회를 중단시키지 않습니다. 그러나 그 옆에 보관된, 밖으로 이어지는 링크인 다른 Release는 여전히 중단시킵니다. 링크를 통해 단독으로 검사하는 Manifest도 같은 방식으로 읽히고 해석됩니다.
아티팩트 캐시 디렉터리는 어디에 있든 그 자체로 하나의 루트입니다. 캐시가 보유하는 모든 것은 캐시 디렉터리 안에서만 쓰이고, 읽히고, 제거되므로, 캐시 자체 디렉터리 중 하나나 그 안의 파일이 캐시 디렉터리 밖으로 이어지는 링크이면 워크스페이스 안의 다른 곳을 가리키더라도 차단되며, 캐시 디렉터리 안의 다른 곳을 가리키는 링크는 따라갑니다. 캐시 디렉터리 자체의 위치는 그 값의 표기 방식으로 판단합니다. 기본값 .aggrega/cache를 포함하여 워크스페이스 루트 안으로 작성되면, 이는 워크스페이스 자체의 디렉터리입니다. 워크스페이스 안의 다른 곳에 대한 링크인 캐시 디렉터리는 따라가며, 워크스페이스 밖으로 이어지는 것은 읽기와 쓰기 모두에서 거부됩니다. 밖으로 올라가도록 작성되면(../shared-cache), 이는 구성이 지정하는 디렉터리이며 가리키는 곳에서 읽고 씁니다.
가져오는 디렉터리
가져오는 디렉터리는 어디에 있든 그 자체로 하나의 루트입니다 — 워크스페이스 바깥에서와 마찬가지로 워크스페이스 안에서도 그러하며, 이 점이 워크스페이스 안에서 지정하는 다른 모든 디렉터리와 다릅니다.
aggrega import, 어시스턴트의 가져오기 도구, 세션의 aggrega/import는 디렉터리의 각 파일을 그 디렉터리 안에서의 위치로 임포터에 넘기므로, 넘기는 내용은 디렉터리 안에서만 읽힙니다. 판단 대상은 가져오기가 무언가를 가져올 대상입니다. 즉 임포터의 패턴이 선택하는 파일에 대한 링크 — 형식이 지정되지 않고 인식되는 경우에는 어느 임포터의 패턴이든 — 와, 결코 들어가지 않는 디렉터리에 대한 링크입니다. 이 중 디렉터리 바깥으로 이어지는 링크는 워크스페이스 안의 다른 곳으로 이어지더라도 어떤 파일도 읽기 전에 거부되며, 디렉터리 안의 다른 곳에 있는 파일에 대한 선택된 링크는 링크 자신의 이름으로, 가리키는 곳에서 읽힙니다. 어떤 패턴도 선택하지 않는 파일에 대한 링크는 판단되지도 읽히지도 않습니다. 디렉터리 자체는 지정한 그대로 사용되며, 링크인 디렉터리는 가리키는 곳까지 따라갑니다.
문서 편집은 안에 머뭅니다
aggrega edit-document, 언어 서버의 문서 편집과 삽입 지점, 그리고 어시스턴트의
edit-document와 insertion-point는 워크스페이스가 포함하는 문서에만 작용합니다. 워크스페이스 바깥의 문서는 작성된 그대로든 워크스페이스 바깥으로 이어지는 링크를 통해서든 모든 경로에서 아무것도 읽거나 쓰지 않은 채 거부됩니다 — 지정한 경로가 다른 경우에는 존중되는 곳에서도 마찬가지입니다.
두 가지 어시스턴트 전송 방식
aggrega mcp는 같은 도구를 두 가지 방식으로 제공하며, 호출하는 쪽이 다르기 때문에 두 방식의 경계도 다릅니다.
- 프로세스 자체의 스트림을 통하는 경우, 클라이언트가 사용자의 컴퓨터에서 서버를 실행한 것이므로 호출은
사용자가 명령줄에 입력하는 것과 같습니다. 경로 인수는 절대 경로일 수 있고 워크스페이스 밖에 있을 수 있으며,
호출은 자체
workspace_root와catalog_dirs를 지정할 수 있고, 별도 프로세스에서aggrega명령을 실행하는 도구도 제공됩니다. 지정한 그대로 존중되는 것은 호출이 지정한 경로뿐입니다. 그 뒤 작업이 스스로 읽고 쓰는 것은 터미널에서와 똑같이 제한됩니다. 목록 조회는 밖으로 나가는 링크를 따라 읽지 않고, 문서가 작성한 참조는 워크스페이스를 벗어나지 않으며, 쓰기는 링크된 출력 디렉터리나 캐시 디렉터리를 거치지 않습니다. 워크스페이스 내용은 어시스턴트가 요청하는 것을 유도할 수 있으므로, 이 도구가 사용자 파일에 접근하는 유일한 수단인 호스트에서도 클론한 워크스페이스의 문서가 어시스턴트로 하여금 워크스페이스 밖의 경로를 지정해 읽거나 쓰게 만들 수 있습니다. 사용자에게 먼저 묻지 않고 어시스턴트가 할 수 있는 일에서 어시스턴트가 요청 없이 어디까지 할지 설정합니다. - HTTP를 통하는 경우, 호출하는 쪽은 서버가 실행되는 컴퓨터의 소유자가 아닙니다. 워크스페이스는
서버가 시작될 때 지정된 워크스페이스이며 서버가 실행되는 동안 고정됩니다. 모든 경로 인수는 그 안으로 제한되고 위와 같이 판단됩니다.
workspace_root나catalog_dirs를 지정하거나 호스트에 보관된 서명 키를 선택하는 호출은 거부되며,aggrega명령을 실행하는 도구는 제공되지 않습니다. 거부 메시지는 해당 인수를 밝히고 상대 값은 전송된 그대로 인용하지만, 워크스페이스 루트도, 경로가 이어졌을 위치도 밝히지 않습니다.
거부되거나 중단될 때
| 표시되는 내용 | 해야 할 일 |
|---|---|
| 목록이 읽지 않은 항목 가운데 링크를 명시함 | 링크를 링크가 가리키는 대상의 사본으로 바꿉니다. 또는 다른 곳에 보관된 엔터티라면 링크가 가리키는 디렉터리를 catalog_dirs 아래에 나열하고, 다른 곳에 보관된 Release라면 workspace.releases 아래에 또는 build.authoring_release로 지정합니다. |
E0321, 카탈로그 디렉터리나 Release의 디렉터리 밖으로 나가는 링크를 통한 읽기 | 카탈로그 디렉터리 아래의 링크를 통해 접근하는 대신, 링크가 가리키는 디렉터리를 카탈로그 디렉터리로 나열하거나 --catalog로 전달합니다. 또는 링크를 사본으로 바꿉니다. 링크가 관례상의 catalog 자체라면 catalog 또는 그것이 가리키는 디렉터리를 나열하거나, 둘 중 하나를 --catalog로 전달합니다. |
Release의 lockfile에 대한 E0321 | 링크를 제거하고 Release를 다시 pull합니다. 그러면 그 옆에 새 lockfile이 작성됩니다. lockfile은 다른 위치를 가질 수 없습니다. |
엔터티 옆 파일에 대한 E0321 | 링크를 파일 자체로 바꿉니다. 엔터티인 문서는 별도의 디렉터리로 옮기고, 빌드된 .wasm은 그에 대한 링크가 아니라 파일 자체를 Plugin 엔터티 옆에 둡니다. |
구성 파일에 대한 E0321 | 링크를 워크스페이스 안에 보관한 사본으로 바꿉니다. 워크스페이스 간에 공유하는 구성은 --config 또는 AGGREGA_CONFIG로 전역 구성 파일로 지정하여 읽으며, 각 워크스페이스 자체 파일보다 아래에 놓입니다. |
아티팩트 캐시에 대한 E0321 | 링크를 제거합니다. pull하면 캐시가 다시 채워집니다. 캐시를 다른 곳에 두려면 링크하는 대신 artifact_cache_dir를 워크스페이스 루트 기준 상대 경로(../shared-cache)로 작성한 해당 디렉터리로 설정합니다. |
가져온 저장소의 링크에 대한 E0321 | 링크는 소스가 지정하는 저장소에 커밋되어 있으며, 메시지는 그 저장소 안의 위치로 링크를 명시합니다. 그곳에서 링크를 변경하고(저장소 내부를 가리키게 하거나 파일 자체를 커밋), 변경 사항이 포함된 리비전을 지정합니다. |
가져오는 디렉터리의 링크에 대한 E0321 | 파일에 대한 링크가 아니라 파일 자체를 디렉터리에 두거나, 링크가 가리키는 디렉터리를 가져옵니다. 가져오는 디렉터리는 어디에 있든 그 내부에서만 읽힙니다. |
module_subdir에 대한 E0307 | 저장소 안의 디렉터리를 지정합니다. 값은 저장소 최상위 아래로 내려갈 수는 있지만 그 위로 올라갈 수는 없습니다. |
E0320, 링크를 통한 쓰기 또는 제거 | 메시지가 명시한 링크를 제거하거나, 메시지가 명시한 디렉터리 안의 어딘가를 가리키도록 한 뒤 작업을 다시 실행합니다. 엔터티 파일의 내용은 이 오류의 원인이 아닙니다. |
E0324, 밖으로 나가는 참조 | 다른 곳에 보관된 Aggregate는 metadata.name으로 지정하고 그 카탈로그 디렉터리를 나열합니다. Manifest, extends:가 지정하는 Release, parameters 파일은 워크스페이스 안에 두거나, 외부에서 지정한 문서라면 그 문서 자체의 디렉터리에 둡니다. 또는 두 문서를 모두 담은 디렉터리에서 워크스페이스를 엽니다. |
E0304, 링크를 통한 콘텐츠 | 링크를 엔터티 자체 디렉터리 안에 있는, 링크가 가리키는 대상의 사본으로 바꿉니다. |
| 밖으로 나가는 경로 때문에 거부된 language-server 요청 | 워크스페이스 안의 경로를 루트 기준 상대 경로로 보냅니다. 워크스페이스 밖에 보관된 Release에 접근하려면 구성에서 workspace.releases 아래에 또는 build.authoring_release로 지정하고, 요청에서는 그것을 가리키는 워크스페이스 안의 링크, 즉 Release 목록이 제시하는 위치를 지정합니다. |
| 경로 때문에 거부된 HTTP를 통한 어시스턴트 호출 | 서버가 제공하는 워크스페이스의 루트 기준 상대 경로를 보냅니다. 거부 응답이 절대 경로의 상대 표기를 제시하면 그것을 보냅니다. |
| 거부된 문서 편집 | 워크스페이스에 포함된 문서를 편집합니다. 다른 곳의 문서를 가리키는 링크를 통해서는 편집되지 않습니다. |
참고 항목
- 구성 — 위의 각 설정을 어디에 작성하는지, 그리고 그 안의 상대 경로가 어떻게 해석되는지.
aggrega serve및aggrega mcp— 각 요청과 도구, 그리고 그 매개변수 중 어느 것이 경로를 지정하는지.- 치명적 중단 — 위의 각 조건에 대한 전체 항목.