← Artifacts / artifacts / concepts

Doporučené postupy pro Artifacts

Artifacts funguje nejlépe, když práci izolujete, přístup omezíte na nezbytné minimum, metadata udržujete oddělená a úložiště záměrně rozdělujete.

Tyto vzory použijte ke strukturování repozitářů pro agenty, automatizaci a sdílené systémy.

Vytvořte jeden repozitář pro každou jednotku autonomní práce. Pokud máte 10,000 agenty vytvořte 10,000 repozitáře.

Díky tomu zůstávají změny, chyby a životní cyklus úklidu jednotlivých agentů oddělené. Zároveň to zabraňuje tomu, aby se jeden sdílený repozitář stal ohniskem konfliktů, rozsáhlých diffů a náhodných přepsání.

Tento vzor použijte, když potřebujete:

• izolovat práci jednoho agenta od práce druhého agenta
• předat repozitář jedné relaci nebo uživatelské aplikaci
• samostatně kontrolovat, slučovat, archivovat nebo mazat práci

Větve používejte pouze tehdy, když spolupracovníci sdílejí stejný životní cyklus a potřebují pracovat na stejném repozitáři. Jeden sdílený repozitář nepoužívejte jako frontu pro mnoho autonomních agentů.

Názvy repozitářů jsou v rámci jmenného prostoru jedinečné. Pokud několik agentů potřebuje izolované kopie stejného základního repozitáře v jednom jmenném prostoru, nepoužívejte opakovaně krátký sdílený název, například docs-site.

Do názvu repozitáře zahrňte stabilní identifikátory, například název agenta, session ID, user ID nebo workflow ID. Název jako ${agentName}-${sessionId}-${repoName} je bezpečnější než ${repoName} protože to zabraňuje kolizím a usnadňuje úklid.

Tento příklad před vytvořením repozitáře nejprve vygeneruje jeho jedinečný název.

async function createRepoCopy(env, agentName, sessionId, repoName) {
	const uniqueRepoName = `${agentName}-${sessionId}-${repoName}`;

	return env.ARTIFACTS.create(uniqueRepoName);
}

interface Env {
	ARTIFACTS: Artifacts;
}

async function createRepoCopy(
	env: Env,
	agentName: string,
	sessionId: string,
	repoName: string,
) {
	const uniqueRepoName = `${agentName}-${sessionId}-${repoName}`;

	return env.ARTIFACTS.create(uniqueRepoName);
}

Nové repozitáře zakládejte na ověřeném základu, pokud agenti potřebují stejné výchozí soubory, prompty nebo strukturu aplikace. Forkování z kontrolovaného repozitáře je bezpečnější než ruční kopírování souborů do každého nového repozitáře.

Díky tomu zůstává výchozí stav konzistentní a následné diffy se snáze kontrolují. Zároveň vám to umožňuje sloučit zpět jen ty výsledky, které chcete.

Tento příklad vytvoří fork zkontrolovaného základního repozitáře do repozitáře specifického pro danou relaci.

async function forkFromBaseline(env, sessionId) {
	const baseline = await env.ARTIFACTS.get("starter-repo");
	const forked = await baseline.fork(`starter-repo-${sessionId}`, {
		description: `Fork for session ${sessionId}`,
		defaultBranchOnly: true,
		readOnly: false,
	});

	return {
		name: forked.name,
		remote: forked.remote,
	};
}

interface Env {
	ARTIFACTS: Artifacts;
}

async function forkFromBaseline(env: Env, sessionId: string) {
	const baseline = await env.ARTIFACTS.get("starter-repo");
	const forked = await baseline.fork(`starter-repo-${sessionId}`, {
		description: `Fork for session ${sessionId}`,
		defaultBranchOnly: true,
		readOnly: false,
	});

	return {
		name: forked.name,
		remote: forked.remote,
	};
}

Tokeny Artifacts jsou vázané na konkrétní repozitář. Upřednostněte read tokeny pro klonování, indexování, kontrolu a načítání.

Použijte write tokeny pouze pro agenta nebo systém, který musí provést push změn. Tokenům nastavte krátkou životnost a pro každou relaci agenta vydejte nový token.

Tento příklad používá Workers binding k vytvoření krátkodobého tokenu pro čtení repozitáře.

Předpokládejte, že volající je již ověřený a autorizovaný, než tato trasa vrátí token.

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const repoName = url.searchParams.get("repo") ?? "starter-repo";

		const repo = await env.ARTIFACTS.get(repoName);
		const token = await repo.createToken("read", 900);

		return Response.json({
			repo: repoName,
			scope: token.scope,
			expiresAt: token.expiresAt,
			token: token.plaintext,
		});
	},
};

interface Env {
	ARTIFACTS: Artifacts;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const repoName = url.searchParams.get("repo") ?? "starter-repo";

		const repo = await env.ARTIFACTS.get(repoName);
		const token = await repo.createToken("read", 900);

		return Response.json({
			repo: repoName,
			scope: token.scope,
			expiresAt: token.expiresAt,
			token: token.plaintext,
		});
	},
} satisfies ExportedHandler<Env>;

Použijte stejný vzor pro write tokeny až poté, co váš Worker autorizuje relaci, která musí provést push změn.

Nevydávejte jeden dlouhodobý zápisový token pro všechny agenty. Vygenerujte co nejužší token na co nejkratší možnou dobu.

Použijte git notes ↗ k připojení promptů, výstupů modelu, ID běhů nebo dalších metadat harness ke commitu, aniž byste změnili objekt commitu nebo pracovní strom.

Díky tomu můžete Artifacts používat jako verzovaný souborový systém pro práci agentů i jako zdroj pravdy pro váš agentní harness. Soubory zůstávají zaměřené na výsledný produkt práce, zatímco poznámky k commitům uchovávají okolní kontext spouštění.

Tento příklad uloží uživatelský prompt a shrnutí asistenta k aktuálnímu commitu a poté poznámku znovu načte.

git notes add -m 'user: Add a best-practices section for unique repo names.' HEAD
git notes append -m 'assistant: Added naming guidance and a code example.' HEAD
git notes show HEAD

Pokud synchronizujete repozitáře mezi systémy, mějte na paměti, že poznámky (notes) se nacházejí na samostatných referencích (refs). Odesílání a načítání refs/notes/* se zbytkem dat repozitáře, pokud chcete, aby tato metadata zůstala u repozitáře.

Namespace používejte k oddělení provozních hranic. Oddělení repozitářů izoluje jednotky práce, zatímco oddělení namespace izoluje vlastnictví, prostředí a vzorce provozu.

Jakmile využití vzroste, nedržte všechny repozitáře v jednom výchozím jmenném prostoru. Jmenné prostory rozdělte, pokud potřebujete jasnější vlastnictví nebo více prostoru pro škálování v rámci omezení rychlosti požadavků pro každý jmenný prostor.

Jakmile se jeden jmenný prostor stane vytíženým, rozdělte nové repozitáře do dalších jmenných prostorů, místo abyste dál rozšiřovali jeden sdílený jmenný prostor.