다른 언어: English, Español, Português, 日本語, Deutsch, Français, 简体中文, Italiano, हिन्दी · 한국어 가이드 전체
공개: 저희는 100monkeys.ai에서 Carbon Forge를 만들고 있으므로 이 글은 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 공개 문서(영어), 주로 Snapshots 카탈로그 페이지와 Working in lanes를 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 도구 이름, 인수, 인용한 문장은 문서 그대로이며, 인용은 영어로 두고 옆에 번역을 붙였습니다. 문서가 이 호출들에 대한 완성된 JSON 예시를 주지 않으므로 여기에도 싣지 않았습니다. 문서가 답하지 않는 질문은 마지막 절에서 밝힙니다.
스냅숏과 cut이란
스냅숏은 모든 페이지, 아톰, 코드 트리, 라이브러리 항목의 현재 리비전과 열린 레인마다의 살아 있는 패치를 "as one sealed manifest of ids and hashes chained to the previous snapshot."(이전 스냅숏에 이어진, ID와 해시로 된 봉인된 매니페스트 하나로) 기록합니다. 스냅숏에는 "ids and hashes only, never a body or a blob's bytes"(ID와 해시만 있고, 본문이나 blob의 바이트는 절대 없으므로) 만드는 비용이 적습니다. cut은 스냅숏 하나에 붙인 이름이며 "it never moves."(절대 움직이지 않습니다.) 스냅숏과 cut은 추가만 됩니다. "the database refuses to change or remove either while the workspace exists."(워크스페이스가 있는 한 데이터베이스는 둘 중 어느 것도 바꾸거나 지우지 않습니다.)
1단계. 되돌아갈지도 모를 상태를 cut하기
크거나 위험한 변경 전에 name을 주어 snapshots.cut을 호출하세요. 이름은 글자, 숫자, 점, 하이픈, 밑줄 1~128자이며 글자나 숫자로 시작합니다. 문서의 예시는 stable, v0.9, release-2026.10.16입니다. cut은 절대 움직이지 않으므로 이름을 다시 쓰면 거부되며, 거부 메시지는 새 상태에 새 cut으로 이름을 붙이라고 합니다. cut하려면 editor 역할이 필요합니다.
2단계. 나중에 cut 찾기
cuts.list는 워크스페이스의 cut을 최신순으로, 각각이 가리키는 스냅숏과 함께 돌려줍니다. cut을 준 snapshots.get은 스냅숏 하나를 돌려줍니다. 다이제스트, 봉인, 이전 스냅숏, 개수, 그리고 기록된 열린 레인들입니다. 둘 다 viewer 역할로 읽을 수 있습니다.
3단계. cut 이후에 바뀐 것 읽기
cuts.notes는 한 경계 이후부터 다른 경계까지 랜딩된 모든 changeset을 랜딩 순서대로, intent의 첫 단어로 묶어 나열합니다. to는 cut이나 스냅숏 ID여야 하므로, cut을 지금의 워크스페이스와 비교하려면 먼저 이름 없이 snapshots.cut을 호출한 뒤, 여러분의 cut을 from으로, 새 스냅숏의 ID를 to로 넘기세요. 관심 있는 경로를 건드린 changeset만 남기려면 path_glob을 더하세요. 각 changeset에는 intent, 행위자, 랜딩된 레인, 건드린 경로가 있어, 대개 그것만으로 누구의 작업을 되돌리려는지 알 수 있습니다.
4단계. cut이 담고 있는 모습 그대로 엔티티 하나 보기
cut을 준 snapshots.materialize는 cut 매니페스트의 한 페이지를 돌려주며, 각 항목에는 다음 필드가 있습니다.
kind, entity_id, revision_id, content_hash, seal_hash, path, titleentity_id를 더하면 cut이 가리키는 리비전의 그 엔티티를 돌려줍니다. 페이지의 본문과 메타데이터, 아톰의 본문, 트리의 항목, 라이브러리 항목의 해시입니다. "The same snapshot answers the same every time."(같은 스냅숏은 매번 같은 답을 합니다.) 그 뒤 리비전이 영구 삭제된 항목은 purged로 답하고 내용을 담지 않습니다.
5단계. 누가 되돌릴 수 있는지 확인하기
snapshots.revert에는 admin 역할이 필요하고, 토큰 프리셋 중에서는 full에만 들어 있으므로, SCM agent나 SCM release 토큰을 가진 에이전트는 이것을 호출할 수 없습니다. 트렁크가 보호된 워크스페이스에서는, 코드 트리나 라이브러리 항목을 쓰게 되는 되돌리기, 또는 페이지도 보호된 곳에서 페이지나 아톰을 쓰게 되는 되돌리기는 아무것도 쓰기 전에 거부됩니다. workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.
6단계. cut으로 되돌리기
cut과 changeset의 메시지인 intent(1~4,096자)를 주어 snapshots.revert를 호출하세요. "Revert is forward only: nothing is removed or rewritten."(되돌리기는 앞으로만 나아갑니다. 아무것도 지워지거나 다시 쓰이지 않습니다.) 내용이 cut과 다른 엔티티는 모두 cut의 내용을 담은 새 리비전을 하나씩 받고, 이 모두가 봉인된 changeset 하나에 들어갑니다. 복원된 페이지나 아톰 리비전에는 Restored from cut <cut> (R#<revision>)이라는 코멘트가 붙습니다. cut이 경로와 제목을 기록해 두었다면, 이름이 바뀐 페이지는 예전 경로와 제목으로 돌아가고, 떠나는 경로는 계속 그 페이지로 리디렉션됩니다. 그런 다음 되돌린 기준 cut이 표시된 새 스냅숏이 cut됩니다.
7단계. 응답 읽기
응답은 다음 필드를 가진 새 스냅숏입니다.
snapshot, cut, changeset_id, restored, unchanged, extraneous, collisionsrestored의 각 행은 다음과 같습니다.
kind, entity_id, from_revision_id, new_revision_idunchanged는 개수입니다. collisions는 예전 경로를 지금 다른 살아 있는 페이지나 아톰이 차지한 엔티티를 나열하며, 거기서는 "the body and metadata alone are restored, and nothing moves."(본문과 메타데이터만 복원되고 아무것도 이동하지 않습니다.) 아무것도 쓰지 않는 거부가 두 가지 있습니다. 하나는 영구 삭제된 리비전을 가리키는 cut이나 지금 휴지통에 있는 엔티티로, 거부 메시지는 그 엔티티를 먼저 복원하라고 합니다. 다른 하나는 워크스페이스가 이미 일치하는 cut으로, Every entity already holds what cut <cut> names; nothing changes.라는 답이 옵니다.
8단계. 되돌리기가 남겨 둔 것 처리하기
"Entities created after the cut are reported as extraneous and left as they are."(cut 이후에 만들어진 엔티티는 extraneous로 보고되고 그대로 남습니다.) 밤사이 에이전트가 만든 페이지는 되돌린 뒤에도 그대로 있으니, 하나씩 남길지 정하세요. 되돌리기도 다른 것과 같은 changeset이므로 밤사이의 작업과 그 되돌리기가 모두 이력에서 읽히며, 되돌리기를 사이에 두고 cuts.notes를 실행하면 둘 다 보입니다. 워크스페이스 전체가 아니라 랜딩 하나만 되돌리려면 changesets.revert가 changeset 하나를 되돌리며, 이것은 lane을 받으므로 보호된 트렁크에서는 레인에 저장해 거기서 랜딩할 수 있습니다.
cut으로 릴리스에 이름을 붙이고 게시하려면 가이드 Carbon Forge에서 릴리스를 cut하고 GitHub에 push하기를 읽으세요.
문서가 답하지 않는 것
- 보호된 트렁크를 cut으로 되돌리는 방법.
snapshots.revert는lane을 받지 않으며, 문서는 cut 전체를 레인을 통해 되돌리는 과정을 보여 주지 않습니다. extraneous엔티티를 한 번에 지우는 방법. 문서는 그것들을 보고하는 데서 멈춥니다.- 되돌리기 응답의
cut에 무엇이 담기는지. 문서의 설명대로라면 새 스냅숏은 따로 이름 없이 cut되며, 이 호출에서 그 필드는 설명되지 않습니다. - 완성된 예시. 카탈로그는 인수를 모두 밝히지만 이 일곱 도구의 예시 호출이나 응답은 주지 않습니다.