Worktree
초안 격리, 기준 리비전, OT 병합과 AI SDK의 Agent·사용자 검토 연결 원리를 설명합니다.
Worktree는 Office 콘텐츠를 협업 가능한 초안으로 격리합니다. Agent가 예산이나 기획서를 수정하는 동안 사용자는 원본(trunk)을 계속 편집합니다. 검증·검토 후 초안의 변경을 병합합니다.
Git 작업 디렉터리와 달리 문서 콘텐츠와 변경을 격리합니다. 한 작업에는 통합 문서·문서·프레젠테이션 등 여러 Unit이 포함될 수 있습니다.
격리 원리: 같은 기준에서 독립적으로 진행
기존 Unit의 Worktree를 만들 때 현재 원본 revision을 Baseline(기준) 으로 기록합니다. 초안은 별도 Snapshot, changeset, revision, Presence, Room을 사용하므로 중간 수정은 원본에 쓰이지 않습니다.
| 개념 | 역할 |
|---|---|
| Baseline | 초안이 시작한 원본 버전으로 비교·병합의 기준. |
| Draft head | 초안 제출로 진행되는 최신 확정 버전. |
| Ready head | 검토·병합 범위를 고정한 초안 버전. |
원본과 초안은 독립적으로 진행합니다. revision은 각 제출 순서를 나타내므로 숫자만으로 콘텐츠의 최신 여부를 판단할 수 없습니다. 초안 동기화가 원본 변경을 자동으로 섞지는 않으며 미리보기나 병합 시 조정합니다.
AI SDK가 같은 초안을 연결하는 방식
AI SDK의 Collaboration Runtime은 한 Unit의 스냅샷·변경·버전을 처리합니다. 생성·상태·병합은 Server SDK의 Worktree 서비스가 관리하여 별도 편집 엔진이 필요하지 않습니다.
앱은 worktreeID + unitID를 초안 Snapshot, Submit, WebSocket, Session Ticket URL로 매핑해 Runtime에 전달합니다. 같은 검사·편집 도구가 원본이나 초안을 대상으로 동작합니다.
같은 Unit ID가 원본과 여러 Worktree에 존재할 수 있습니다. 검사·실행·스크린샷·Web 미리보기의 대상을 일치시켜 초안을 읽고 원본에 쓰는 실수를 방지합니다. Web도 해당 협업 설정으로 연결합니다.
| 구성 요소 | 역할 |
|---|---|
| Web SDK | Headless 조작과 브라우저 편집의 공통 엔진. |
| Server SDK | 초안 격리, 변경·버전 저장, 상태, OT 병합. |
| AI SDK | Runtime, Inspection, API 검색, Facade 실행, 시각 검증. |
| 앱 | 모델, 대상 매핑, 신원·권한, 작업·검토 UI. |
Agent 편집에서 전달까지
앱은 Agent별로 독립 Worktree를 배정해 작업을 병렬로 구성할 수 있습니다. 각 Agent가 편집·검증 후 Ready로 표시하면 사용자가 개별 검토합니다. 수정이 필요하면 해당 초안을 Reopen하고 승인한 변경은 최신 원본에 병합합니다.
- 초안을 만들고 작업 Unit을 선택해 Worktree target에 연결하고
pull합니다. - Inspection으로 구조와 데이터를 파악하고 필요하면 API를 검색한 뒤 Facade로 수정합니다.
- 초안에 제출하고 데이터·계산 결과를 다시 읽습니다. 필요하면 스크린샷, Slides는 Layout Lint로 검사하고 문제를 수정합니다.
- Ready로 Unit별 버전을 고정하고 편집을 중지해 검토에 전달합니다.
- 승인 후 Merge합니다. 사용자나 Agent가 더 수정하려면 먼저 Reopen하며 불필요한 초안은 Discard합니다.
| 작업 | 효과 |
|---|---|
runtime.commit() | 초안에만 제출하고 revision을 진행. |
markReady() | 검토 버전 고정, 원본 병합은 하지 않음. |
reopenWorktree() | Ready에서 Draft로 돌아가 편집 허용. |
mergeWorktree() | 고정된 변경을 Unit별로 원본에 병합. |
Commit, Ready, Merge는 별개입니다. Ready 이후에는 누구든 편집 전에 Reopen해야 합니다. 구현은 AI SDK 가이드를 참고하세요.
최신 원본에 변경을 병합하는 원리
기존 Unit은 Baseline부터 Ready head 까지 changeset의 mutation을 모아 원본 Collaboration Service에 제출합니다. 원본이 진행했다면 OT가 이후 변경과 조정하여 새 버전을 확정합니다.
오래된 스냅샷으로 전체를 덮어쓰는 것이 아니라 변경을 적용합니다. 변환·실행이 불가능하면 충돌을 반환하여 앱이 처리합니다. OT가 모든 업무상 의견 차이를 해결하지는 않습니다.
초안에서 새로 만든 Unit은 원본 기준이 없습니다. 병합 시 원본에 만들며 전체 초안 이력을 복사하지 않습니다.
수정 내용과 병합 결과 검토
- 무엇을 바꿨는가: 기준과 Ready 초안의 완전한 콘텐츠를 비교합니다.
- 지금 병합하면 어떻게 되는가: Ready 이후
evaluateUnitMerge()를 호출합니다. 원본이 진행했다면 격리 Runtime이 OT 후보 변경을 현재 원본에 적용해 읽기 전용 미리보기를 만듭니다. changeset 제출이나 실제 데이터 변경은 하지 않습니다.
미리보기는 요청 시점 상태이며 실제 병합은 실행 시점 원본을 기준으로 합니다. 여러 Unit은 단일 원자적 트랜잭션이 아니어서 일부 실패해도 성공 결과는 유지됩니다. 개별 결과를 표시하고 실패 항목을 처리하세요.
통합과 범위
Worktree Client, Service, Endpoint, DB 어댑터를 협업 코어에 결합합니다. 초안은 별도 저장하고 Session Ticket Store는 원본과 공유합니다. 초안 접근과 원본 쓰기는 각각 권한 검사가 필요합니다.
Sheet, Doc, Slide, Canvases, Relational Table을 지원하며 PDF는 제외합니다. 예제, 모듈, Agent 가이드를 참고하세요.
이 가이드는 어떠셨나요?