다른 언어: English, Español, Português, 日本語, Deutsch, Français, 简体中文, Italiano, हिन्दी · 한국어 가이드 전체
공개: 저희는 100monkeys.ai에서 Carbon Forge를 만들고 있으므로 이 글은 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 공개 문서(영어), 주로 Perspectives: beam angles through one workspace와 Source control settings의 Perspectives 절을 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 퍼스펙티브와 호출은 문서에 실린 예시 그대로입니다. 문서가 답하지 않은 질문은 마지막 절에서 밝힙니다.
퍼스펙티브란 무엇인가
문서의 설명: "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."(퍼스펙티브는 그 기록을 들여다보는 이름 붙은 렌즈입니다. 종류, 표면, 경로, 미디어 타입, 태그, 메타데이터로 기록의 일부를 골라 그 부분을 자기만의 경로로 내놓습니다.) 그리고 "Nothing is copied to make one."(퍼스펙티브를 만들려고 무언가를 복사하지는 않습니다.) 내보내기에는 두 가지 성질이 중요합니다. 범위 면에서 읽기 전용입니다. "A perspective never discloses. It narrows what the reader already reads and never widens it."(퍼스펙티브는 결코 새로 공개하지 않습니다. 읽는 사람이 이미 읽는 범위를 좁힐 뿐 넓히지 않습니다.) 그리고 다운로드는 결정적입니다. "The same ref through the same perspective gives the same bytes."(같은 ref를 같은 퍼스펙티브로 보면 같은 바이트가 나옵니다.)
1단계. 워크스페이스가 해석하는 퍼스펙티브 나열하기
perspectives.list를 호출하세요. 모든 워크스페이스에는 기본 제공 퍼스펙티브가 있습니다. all, code, docs, adrs, internal, public(익명 독자가 받는 것과 정확히 같음), 그리고 코드 트리마다 그 트리를 루트로 하는 tree:<path> 하나씩입니다. 인스턴스 관리자는 인스턴스 전체용을 추가할 수 있고, 워크스페이스 자체의 것이 마지막에 옵니다. "The nearest layer wins"(가장 가까운 층이 이깁니다). 각 응답은 자기 source와 자기가 overrides하는 출처를 밝힙니다. 기본 제공 퍼스펙티브로 충분하면 3단계로 건너뛰세요.
2단계. .perspectives 페이지에 직접 작성하기
워크스페이스의 퍼스펙티브는 예약된 페이지 .perspectives에 펜스로 감싼 JSON 블록이나 표로 들어 있습니다. 문서의 예시를 퍼스펙티브 하나로 줄이면:
{
"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"
}
]
}규칙은 그 규칙이 지정한 모든 필드가 맞을 때 맞습니다. include는 어느 규칙이든 맞는 것을 모두 담고, exclude는 어느 규칙이든 맞는 것을 모두 빼는데, "even when an include rule matched it"(include 규칙이 맞았더라도) 뺍니다. 경로는 gitignore 방식의 glob이며 !로 시작할 수 없습니다. root를 설정하면 모든 경로에서 루트가 잘려 나가므로, 이 퍼스펙티브는 src/main.ts와 README.md를 내놓습니다. 코드 트리는 파일 단위로 판정됩니다. monorepo, service, library, docs-site 같은 템플릿이 perspectives.adopt를 통해, 또는 Settings, Workspace, Source control 아래의 Adopt로 페이지를 대신 써 줄 수 있습니다.
잘못된 행은 건너뛰지 않습니다. "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."(페이지를 읽을 수 없으면, 고칠 때까지 워크스페이스의 모든 퍼스펙티브 읽기가 페이지의 첫 번째 잘못된 행을 인용하며 거부됩니다.) 페이지에는 저장할 때마다 다시 검사하는 Perspectives on this page 패널이 보입니다.
3단계. ref에서 미리 보기
perspectives.preview는 퍼스펙티브가 어떤 ref에서 담고 있는 것을 종류별로 세고, 투영된 경로의 앞부분을 기본 100개, 최대 500개까지 돌려줍니다. "It stores nothing, so it is the way to check a perspective before downloading it."(아무것도 저장하지 않으므로, 내려받기 전에 퍼스펙티브를 확인하는 방법입니다.) 브라우저에서는 코드 브라우저의 ref 막대에 있는 선택기 옆에 같은 집계가 나타납니다. Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.
4단계. 움직이지 않는 ref 고르기
ref는 trunk(기본값), lane:<label>, cut:<name>, snapshot:<id> 중 하나입니다. 내보내기 작업은 실행될 때 ref를 해석하므로 "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move."(trunk는 그 순간의 trunk입니다. 움직이지 않는 지점이 필요하면 cut이나 snapshot을 지정하세요.) 재현하고 싶은 다운로드라면 cut을 지정하세요. 충돌 중인 lane은 충돌이 해결될 때까지 거부됩니다.
5단계. 아카이브를 내보내고 내려받기
perspectives.export { "perspective": "api", "ref": "cut:<name>", "format": "tar" }
→ { export_id, status: "queued" }
exports.status { ... } // until it answers a download_urldownload_url을 돌려줄 때까지 내보내기 ID로 exports.status를 조회하세요. 요청한 사람은 링크가 담긴 이메일도 받습니다. 파일 이름은 <workspace>-<perspective>-<ref>.zip 또는 .tar입니다. 안에서 페이지나 atom은 제목, 종류, 메타데이터를 frontmatter로 가진 Markdown 파일이고, 코드 파일은 바이트와 모드를 유지하며, 심볼릭 링크는 심볼릭 링크로 남습니다. 항목은 경로 바이트 순으로 정렬되고, 모든 파일은 ref의 시각을 가지며, 아무것도 압축되지 않고 소유자는 기록되지 않습니다. zip은 최대 65,535개 항목과 4 GiB까지 담으며, 그보다 크면 tar를 쓰세요. 브라우저에서는 zip이나 tar를 고르고 미리 보기 옆의 Download를 누릅니다.
6단계. 각 파일을 매니페스트와 대조하기
모든 아카이브에는 carbon-perspective/1 형식의 .carbon/perspective.json이 들어 있습니다. 여기에는 인스턴스, 워크스페이스, 해석된 그대로의 퍼스펙티브, 그리고 ref가 적힙니다. cut이나 snapshot은 snapshot ID로, trunk나 lane은 composition_sha256으로 적힙니다. 각 항목에는 다음이 있습니다.
path, kind, entity_id, revision_id, content_hash, seal_hash, mode, size, sha256각 파일을 해시해 sha256과 비교하고, revision_id, content_hash, seal_hash를 기록과 비교하세요. 문서에 따르면 매니페스트가 있으면 "a reader can check every file against the record it came from"(읽는 사람이 모든 파일을 그것이 나온 기록과 대조할 수 있습니다). 그래서 아카이브는 "a copy that can drift into a second truth."(두 번째 진실로 갈라져 나갈 수 있는 사본)가 아니라 기록의 일부가 됩니다.
7단계. 변경은 lane을 통해 되돌려 놓기
"A download is read-only by design. Nothing in the archive is read back."(다운로드는 설계상 읽기 전용입니다. 아카이브의 어떤 것도 다시 읽어 들이지 않습니다.) 아카이브에서 한 작업을 되돌려 놓으려면 도구 호출로 쓰고, lane에 올려 랜딩하거나, 가져오기를 해서 각 변경이 자기 행위자와 의도를 갖게 하세요. lane은 Working in lanes가, 내보낼 cut을 만드는 방법은 저희 가이드 Cut a release in Carbon Forge and push it to GitHub(영어)가 다룹니다.
문서가 답하지 않은 것
- 내보내기 한도의 크기. 한도를 넘는 다운로드는 한도를 밝히는 문장과 함께 실패하지만, 문서는 기본값을 밝히지 않습니다.
download_url이 얼마나 오래 유효한지, 내보내기가 얼마나 오래 보관되는지.- 누가
.perspectives를 편집할 수 있는지. 템플릿 채택은 관리자 작업이지만, 페이지 자체는 "is edited like any other page"(다른 페이지처럼 편집됩니다)라고 되어 있어 편집 권한이 있는 누구나로 읽힙니다. - 아카이브를 매니페스트와 대조하는 도구. 형식은 나와 있지만, 대조는 읽는 사람의 스크립트에 맡겨져 있습니다.