看到一份已经为测试版创建好的“最佳实践”文档，总是令人愉悦： https://t.co/aQK5cRckgn

Artifacts 最佳实践 · Cloudflare Artifacts 文档

来源：https://developers.cloudflare.com/artifacts/concepts/best-practices/ 当你隔离工作、严格限定访问范围、保持元数据分离、并刻意分区存储时，Artifacts 的效果最佳。

使用这些模式为代理、自动化以及共享系统构建仓库结构。

按隔离原则组织仓库

为每个代理、会话或应用创建一个仓库

为每个自主工作单元创建一个仓库。如果你有 10,000 个代理，就创建 10,000 个仓库。

这样可以将每个代理的变更、失败和清理生命周期隔离开来。也能避免将一个共享仓库变成冲突、巨大差异和意外覆盖的热点。

在需要以下场景时使用此模式：

• 将一个代理的工作与另一个代理的工作隔离
• 将仓库移交给单个会话或用户应用
• 独立地审查、合并、归档或删除工作

仅当协作者共享相同的生命周期且需要在同一个仓库上工作时，才使用分支。不要将一个共享仓库用作多个自主代理的队列。

使用唯一名称

仓库名称在命名空间内是唯一的。如果多个代理需要在同一个命名空间中获得相同基线仓库的隔离副本，不要重复使用简短的共享名称，例如 docs-site。

在仓库名称中包含稳定的标识符，例如代理名称、会话 ID、用户 ID 或工作流 ID。像 ${agentName}-${sessionId}-${repoName} 这样的名称比 ${repoName} 更安全，因为它可以避免冲突，并使清理更容易。

以下示例在创建仓库之前生成了唯一的仓库名称。

• JavaScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5725)
• TypeScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5726)

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

从稳定的基线派生

当代理需要相同的启动文件、提示或应用结构时，从可信的基线开始创建新仓库。从经过审查的仓库派生，比手动将文件复制到每个新仓库更安全。

这样能保持起始点的一致性，并使下游差异更容易审查。同时也允许你只合并回你期望的结果。

以下示例将一个经过审查的基线仓库派生为特定会话的仓库。

• JavaScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5727)
• TypeScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5728)

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, };}

严格限定访问范围

授予最小权限的仓库令牌

Artifacts 令牌是仓库范围的。克隆、索引、审查和检索时，优先使用 read 令牌。

仅对必须推送更改的代理或系统使用 write 令牌。为令牌设置短生命周期，并为每个代理会话重新发放新令牌。

以下示例使用 Workers 绑定 (https://developers.cloudflare.com/artifacts/api/workers-binding/) 为仓库发放一个短期的读取令牌。

假设在此路由返回令牌之前，调用者已经通过身份验证并被授权。

• JavaScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5729)
• TypeScript (https://developers.cloudflare.com/artifacts/concepts/best-practices/#tab-panel-5730)

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, }); },};

在 Worker 授权必须推送更改的会话之后，才使用相同的模式发放 write 令牌。

不要向每个代理发放一个长期有效的写入令牌。尽可能在最短时间内发放最小权限的令牌。

使用 git notes 记录提示和模型输出

使用 git notes↗ (https://git-scm.com/docs/git-notes) 将提示、模型输出、运行 ID 或其他工具元数据附加到提交中，而无需更改提交对象或工作树。

这样你就可以将 Artifacts 同时用作代理工作的版本化文件系统，以及代理工具的唯一真实来源。你的文件将专注于工作产品，而提交注释则保留周围的执行上下文。

以下示例将用户提示和助手摘要存储在当前提交上，然后读取注释。

git notes add -m '用户：添加关于唯一仓库名称的最佳实践部分。' HEADgit notes append -m '助手：添加了命名指南和代码示例。' HEADgit notes show HEAD

如果在系统之间同步仓库，请记住注释位于单独的引用上。如果希望元数据随仓库一起传递，请将 refs/notes/* 与其余仓库数据一起推送和拉取。

有意地划分命名空间

分离环境、团队和高频率工作负载

使用命名空间来分离操作边界。仓库隔离用于隔离工作单元，而命名空间隔离则隔离所有权、环境和流量模式。

一旦使用量增长，不要将所有仓库都放在一个默认命名空间中。当需要更清晰的所有权或希望在每个命名空间的请求速率限制 (https://developers.cloudflare.com/artifacts/platform/limits/) 内有更多扩展空间时，拆分命名空间。

当一个命名空间变热时，将新仓库分片到其他命名空间中，而不是继续扩展单个共享命名空间。