유지할 파일 선택
이식 가능한 스냅샷을 연결했습니다. 에이전트가 전체 작업 공간에 파일을 작성하지만, 모든 파일을 내구성 있는 저장소에 보관하고 싶지는 않을 수 있습니다.
스냅샷 객체를 생성할 때 policy를 전달합니다. include와 exclude는
함수입니다. 캡처에서 저장할 작업 공간 경로를 결정합니다. 동일한 정책이 자동
저장, 이름이 지정된 저장 및 복원에 적용됩니다.
이 페이지에서는 이미 스냅샷 객체를 생성했다고 가정합니다. 아직 생성하지 않았다면 다시 로드한 후 파일 유지부터 시작하세요.
exclude를 전달하지 않으면 기본 제외가 유지됩니다
include만 또는 redact만 전달하면 기본 제외가 그대로 유지됩니다. 캡처는
계속해서 .env, .git, node_modules를 건너뜁니다.
exclude를 전달하면 해당 함수가 기본 제외를 대체합니다.
먼저 defaultSandboxSnapshotPolicy()를 복사합니다. 그런 다음 해당 규칙을
유지하면서 자체 규칙을 추가합니다.
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
include(path: string) {
return path === 'src' || path.startsWith('src/')
},
}
이 작업 공간의 프로젝션 마커는 보호된 상태로 유지됩니다. 사용자 지정 정책으로 해당 마커를 캡처하거나 복원할 수 없습니다.
정책 전달
memorySandboxSnapshots 또는 createSandboxSnapshots에 policy를 전달합니다.
withSandbox에서도 동일한 객체를 사용합니다.
import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withPersistence } from '@tanstack/ai-persistence'
import {
defaultSandboxSnapshotPolicy,
defineSandbox,
defineWorkspace,
InMemorySandboxInstanceStore,
memorySandboxSnapshots,
withSandbox,
} from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
const instances = new InMemorySandboxInstanceStore()
const sandbox = defineSandbox({
id: 'app-builder',
provider: dockerSandbox({ image: 'node:22' }),
workspace: defineWorkspace({ source: { type: 'none' } }),
lifecycle: { reuse: 'thread' },
})
const defaults = defaultSandboxSnapshotPolicy()
const snapshots = await memorySandboxSnapshots({
sandbox,
instances,
policy: {
...defaults,
include(path: string) {
return path === 'src' || path.startsWith('src/')
},
},
})
const result = chat({
threadId: 'app-thread',
adapter: grokBuildText('composer-2.5'),
messages: [{ role: 'user', content: 'Create a landing page.' }],
middleware: [
withPersistence(snapshots.persistence),
withSandbox(sandbox, { instances, snapshots }),
],
})
void result
snapshots.save에는 파일 목록이 없습니다. 스냅샷 객체의 policy를 변경하여
파일 집합을 변경합니다.
include와 exclude의 동작 방식
각 경로는 src/app.ts와 같은 작업 공간 기준 문자열입니다. kind는
file 또는 dir입니다.
- 프로젝션 마커를 건너뜁니다.
exclude(path, kind)가 true를 반환하면 해당 경로를 건너뜁니다. 디렉터리의 경우 그 아래의 전체 트리를 건너뜁니다.- 파일의 경우
include(path, 'file')가 true를 반환해야 합니다.include를 생략하면 제외되지 않은 모든 파일을 저장합니다. - 그런 다음 캡처가 상위 디렉터리를 순회하므로 중첩된 파일도 일치할 수 있습니다.
exclude가 우선합니다. include: () => true를 사용해도 exclude가 거부한
경로를 유지할 수 없습니다.
캡처는 정책이 건너뛴 파일을 읽지 않습니다.
파일 하나 유지
해당 경로에 대해서만 true를 반환합니다. 캡처는 여전히 상위 디렉터리를 순회합니다.
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
include(path: string) {
return path === 'src/app.ts'
},
}
일부 파일 유지
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const keep = new Set(['package.json', 'src/app.ts', 'src/index.ts'])
const policy = {
...defaults,
include(path: string) {
return keep.has(path)
},
}
폴더 하나 유지
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
include(path: string) {
return path === 'src' || path.startsWith('src/')
},
}
접미사로 파일 유지
순회가 중첩된 파일에 도달할 수 있도록 디렉터리를 허용합니다. 그런 다음 접미사를 일치시킵니다.
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
include(path: string, kind: 'file' | 'dir') {
return kind === 'dir' || path.endsWith('.ts')
},
}
추가 폴더 하나 건너뛰기
기본 exclude를 유지한 다음 자체 폴더를 추가합니다.
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
exclude(path: string, kind: 'file' | 'dir') {
if (defaults.exclude?.(path, kind)) return true
return path === 'dist' || path.startsWith('dist/')
},
}
모든 깊이에서 폴더 이름을 건너뛰려면 경로 세그먼트를 일치시킵니다.
import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'
const defaults = defaultSandboxSnapshotPolicy()
const policy = {
...defaults,
exclude(path: string, kind: 'file' | 'dir') {
if (defaults.exclude?.(path, kind)) return true
return path.split('/').includes('dist')
},
}
정책으로 필터링되지 않는 항목
파일 정책은 작업 공간 파일과 빈 디렉터리에만 적용됩니다.
- 체크포인트는 여전히 스레드의 전체 대화를 저장합니다.
- 체크포인트는 여전히 스레드의 생성된 모든 아티팩트를 복사합니다.
시크릿, 기본 제외 및 복원 안전성은 스냅샷에 저장되는 항목을 참조하세요.
복원
복원에는 동일한 정책이 사용됩니다. 정책에 포함되지 않은 파일은 대상 디스크에 남습니다. 복원은 해당 파일을 삭제하지 않습니다.
자동 복원은 여전히 최신 체크포인트를 새로운 비공개 샌드박스에 씁니다. 실행이 재개된 활성 샌드박스에는 쓰지 않습니다.