Cursor Origin 与 Cloudflare Artifacts：代码协作平台与 Agent 可编程 Git 存储选型

9月 10, 2026

AI 参与说明（Agent：Grok）：本文在 Perplexity 调研结论基础上，对照 Cursor Origin 与 Cloudflare Artifacts 官方文档整理，并按 Blog 技术文档标准重写；属于 AI 辅助生成内容。资料核验日期为 2026-09-10。Origin 处于 Early Beta，Artifacts 处于 closed beta；接口与限额可能变化，请以官方一手资料为准。完整模型标识与 reasoning effort 未取得可核验的运行记录。

先说结论。

Cursor Origin is Cursor’s git forge: repositories, pull requests, reviews, checks, webhooks, Git HTTPS, and a public REST API modeled after GitHub Apps. Cloudflare Artifacts is versioned, Git-compatible storage built for agents: create, fork, and import repositories from Workers or REST, then hand a remote URL and a short-lived repo-scoped token to any Git client.

两者都“会说 Git”，但不在同一产品层：

开源项目分析 + wiki 生成：公开 HTTPS 仓走 Artifacts import 与 /file；Origin 安装仓走 oit_… 与 tarball。Lovable 式应用生成器：默认租户仓用 Artifacts fork + createToken；需要团队评审或对外开源时，再毕业到 Origin / GitHub。Artifacts 的产品、概念、API 与最佳实践见 Cloudflare Artifacts：产品、概念、API 与最佳实践。

做 Code Review / 分析类 SaaS 时，也不要把 Origin 当成唯一长期存档底座：GitHub / Origin 负责安装授权、webhook 与回写；Artifacts 负责内部 Git 快照与 Agent workspace。

为什么不能把“都会 Git”当成同一产品

Git 规定如何表示历史与交换对象。它不规定：

• 谁能创建一百万个短生命周期仓库
• Pull Request、评审与检查如何变成稳定事件流
• 令牌是否按仓库隔离、是否可由应用代码即时签发
• 协作身份是否落在“组织 / 安装 / 安装范围”上
• 与 GitHub 的镜像关系里，谁才是 source of truth

所以比较应回答：谁在扮演 GitHub 式 forge，谁在扮演可编程的 Agent 存储层。更关键的是：API 的主语是谁，仓库归谁所有。

Origin API、Cursor API 和 GitHub API 在做什么

这三套接口都可以被某个应用调用，但资源所有权不同。不要因为「都有 REST」就把它们当成 Lovable 式 SaaS 的租户存储。

The Origin API uses Bearer credentials through the Origin CLI or an Origin App. Team Admin API keys with the admin:* scope do not authenticate to Origin. Cursor APIs Overview

Cursor Cloud Agents API lets you programmatically launch agents that work on your repositories. It is not a multi-tenant git host. Cloud Agents API

Origin App 看起来像 GitHub App，也确实可以做 Code Review / CI 这类 SaaS：客户管理员安装你的 App，选出仓库，你拿到 oit_… 去读内容和回写。这和 GitHub App 是同一类产品位——客人进入客户的 forge。它不提供「你的应用账户下瞬间创建十万个租户仓并各自发 repo-scoped token」这条控制面。官方写明：Namespace-wide repository listing and repository creation are not part of the partner API. Discover repositories through the installation.

GitHub 也是如此。User token 代表某个开发者；GitHub App 代表装进某个 org 的集成。你可以在客户的仓上做审查、检查、甚至代开 PR，但不能把 GitHub 假设成 Lovable 的默认租户磁盘：仓的生命周期、权限和计费仍绑在客户的 GitHub 身份上，而不是你的产品账户。

Artifacts 反过来：Create tens of millions of repos, fork from any remote, and hand off a URL to any Git client. 官方最佳实践直接按 Agent 数量建仓：If you have 10,000 agents, create 10,000 repos. 构建文档还给出 Platform namespace：一份 CI Workflow 套用到该 Namespace 里每一个客户仓。这才是「SaaS 拥有存储面」。Artifacts changelog Best practices Build and deploy

flowchart TB
  subgraph guest [客人进入客户的 forge]
    CU[Cursor user / team API key]
    OA[Origin App installation]
    GH[GitHub PAT / GitHub App]
    CU --> TeamData[该团队的用量 / Cloud Agent]
    OA --> CustomerOrigin[客户 Origin 里已选仓库]
    GH --> CustomerGitHub[客户 GitHub org 里已选仓库]
  end
  subgraph owner [你的账户拥有存储面]
    CF[Cloudflare API token / Worker binding]
    NS[Artifacts Namespace]
    R1[tenant-a repo]
    R2[session-b repo]
    CF --> NS
    NS --> R1
    NS --> R2
  end

flowchart TB
  subgraph forge [Code Forge 平面]
    GH[GitHub]
    OR[Cursor Origin]
    PR[Pull Request / Review / Checks]
    WH[Webhooks / Apps]
    OR --> PR
    OR --> WH
    GH -. mirror .-> OR
  end
  subgraph storage [Programmable Git Storage 平面]
    NS[Artifacts Namespace]
    REPO[Per-task / per-user Repo]
    TOK[Repo-scoped Token]
    GIT[Git Smart HTTP]
    NS --> REPO
    REPO --> TOK
    REPO --> GIT
  end
  Agent[Coding Agent / Generator / Reviewer]
  Agent -->|协作、评审、长期真源| forge
  Agent -->|会话仓、租户仓、fork 基线| storage

Cursor Origin：Early Beta 中的 Code Forge

产品定位

官方定义：Origin is Cursor’s git forge for storing and sharing code.

Early beta 已公开能力包括：Create Origin repositories (including from Cursor agents)；标准 Git clone / push / pull；Mirror a GitHub repository；Open, review, and merge pull requests；Browse and search at cursor.com/codebase；Install Origin Apps 并基于 Public API 做集成；Connect automations and cloud agents；Origin CLI。

Access note：Origin code storage is available on Pro, Teams, and Enterprise plans. It is not available on free plans. Access opens in stages. 启用前需认领 codebase name（路径中的 {owner}）；beta 期间认领后不可更改。

怎么调用 Origin Public API

开发者入口不是功能清单，而是三条调用面：

Protocol conventions：JSON 字段 camelCase；时间戳 RFC 3339；Protobuf 64-bit integers（含 PR number）编码为 JSON 字符串；默认值字段仍会出现在响应里，不要把缺失 key 当成默认。路径参数是 ownerSlug / repoName；也可用 _/{repoId} 按稳定 ID 寻址。完整 schema 以页面上的 OpenAPI 为准，见 Origin API。

1. 先拿到能调仓库的 Bearer

Cursor API keys are not Origin Bearer tokens. App 集成必须走 Origin App：

1. 本地生成 Ed25519 密钥，只把 公钥 登记到 cursor.com/codebase/settings/apps。
2. 用私钥签一份约 5 分钟的 App JWT。
3. 管理员打开安装 URL，回调带 installation_receipt JWT；校验后保存 sub（installation ID）。
4. 用 App JWT 兑换 oit_… Installation Access Token。
5. REST 用 Authorization: Bearer oit_…；Git HTTPS 拒绝 Bearer，必须用 Basic。

openssl genpkey -algorithm ED25519 -out origin-app-private.pem
openssl pkey -in origin-app-private.pem -pubout -out origin-app-public.pem

App JWT 的 JOSE header / claims（官方契约；下面 TypeScript 按该契约组装，不是官方 SDK）：

import { SignJWT, importPKCS8 } from "jose";
import { readFile } from "node:fs/promises";

const APP_ID = "app_01..."; // iss 与 kid 都是 App ID
const pem = await readFile("origin-app-private.pem", "utf8");
const privateKey = await importPKCS8(pem, "EdDSA");

const appJwt = await new SignJWT({})
  .setProtectedHeader({ alg: "EdDSA", kid: APP_ID, typ: "JWT" })
  .setIssuer(APP_ID)
  .setAudience("origin-apps")
  .setIssuedAt()
  .setExpirationTime("5m")
  .sign(privateKey);

curl --request POST \
  --url "https://api.cursor.com/v1/origin/app/installations/${INSTALLATION_ID}/access_tokens" \
  --header "Authorization: Bearer ${APP_JWT}" \
  --header "Content-Type: application/json" \
  --data '{
    "scopes": ["repository:contents:read"],
    "repositoryIds": ["repo_01..."]
  }'

响应形状：

{ "token": "oit_2v8xkq4m1c7p9t3w5y0z6r4b", "expiresAt": "2026-08-01T10:30:00Z" }

The token expires after at most 15 minutes and never outlives the app JWT used to mint it. 空的 scopes / repositoryIds 继承整个 installation 授权；非空则只能衰减，不能扩大。卸载 App 或删除 installation 会使未过期的 oit_… 立刻 401。

Wiki / 分析 Agent 的最小安装 scopes：

repository:contents:read

若还要跟 PR、回写 review 或贴 Check Run，再加上：

repository:pull_requests:read
repository:pull_requests:reviews:write
repository:checks:write

repository:metadata:read 会自动附带，不必写进安装 URL。:write 隐含对应 :read。

Partner API 发现仓库只能走 installation，不能按 namespace 扫全站、也不能用 installation token 开仓：

curl --request GET \
  --url "https://api.cursor.com/v1/origin/installation/repos" \
  --header "Authorization: Bearer ${OIT}"

GET /v1/origin/repos/{ownerSlug} 与 POST /v1/origin/repos/{ownerSlug} 的 Auth 是 User access token（scope namespace:repositories:read / namespace:new_repository:write），不是 oit_…。官方明确：Namespace-wide repository listing and repository creation are not part of the partner API. Discover repositories through the installation.

本机探测可用 CLI（它会自己兑换 user token，不要把 Cursor API key 塞进 Authorization）：

origin auth login
origin api /repos/OWNER_SLUG/REPO_NAME
origin api /repos/OWNER_SLUG/REPO_NAME/git/ref/heads/main

2. 按任务调用仓库端点

下面只列分析 / wiki Agent 会打到的 REST。每条都要 oit_…（另有注明除外）。路径前缀均为 /v1/origin。

解析不可变输入

Resolve a branch name to a commit SHA before indexing. Do not use the branch name as the analysis ID.

curl --request GET \
  --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/git/ref/heads/main" \
  --header "Authorization: Bearer ${OIT}"

{
  "ref": "refs/heads/main",
  "object": { "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4", "type": "commit" }
}

把整棵树交给解析器（优先 tarball）

curl --request GET --location --output repo.tar.gz \
  --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/tarball/${SHA}" \
  --header "Authorization: Bearer ${OIT}"

Get Repo Tarball 需要 repository:contents:read，计 5 点。The first request for a given commit responds 200 with Content-Type: application/gzip and streams the archive. Later requests for the same commit respond 302 with a signed Location valid for 15 minutes. Archive entries sit at the root of the tar, with no wrapping directory. 含 / 的 ref 用 query：/tarball?ref=refs/heads/main。空仓 409，无法 resolve 的 ref 404。

只读若干文件 / 目录（不必整仓）

curl --request POST \
  --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/contents:batchGet" \
  --header "Authorization: Bearer ${OIT}" \
  --header "Content-Type: application/json" \
  --data '{
    "ref": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",
    "paths": ["README.md", "package.json", "docs"]
  }'

Git HTTPS（与 REST 同一把 oit_…，鉴权方式不同）

Read cloneUrl from Get Repo. Both https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git and the legacy /git/ path clone. Clone / fetch / pull 要 contents:read；push 要 contents:write。Git 侧令牌最多约 15 分钟，用完立刻重签，不要写进长期 remote。

git -c credential.helper="!f() { echo username=x-access-token; echo password=${OIT}; }; f" \
  clone "https://origin.cursor.com/${OWNER}/${REPO}.git"

PR 增量与回写（wiki 导出 / review）

Compare 返回 summary，不含 embedded commit list；changed files 走独立分页端点。PR merge 只支持 native Origin repo，镜像仓会被拒绝。

3. Webhook 触发分析

Origin 向注册的 HTTPS URL 发签过名的 POST。用 raw body 校验 webhook-signature（v1ed, + Ed25519），JWKS 在 https://api.cursor.com/v1/origin/keys。至少一次投递；用 webhook-id 去重，先回 2xx 再异步处理。

分析 Agent 常订：

sequenceDiagram
  participant Admin
  participant Origin
  participant App
  participant Worker
  Admin->>Origin: 打开 install URL 并授权仓库
  Origin->>App: callback?installation_receipt=JWT
  App->>Origin: POST /app/installations/{id}/access_tokens
  Origin-->>App: oit_ token + expiresAt
  Origin->>App: webhook pull_request.created
  App->>Worker: 入队 owner/repo/headSha
  Worker->>Origin: GET /git/ref 或直接用 payload SHA
  Worker->>Origin: GET /tarball/{sha}
  Worker->>Worker: 解析符号图 / 生成 wiki

GitHub Mirror 边界

Mirroring copies a GitHub repository into Origin and keeps Origin updated as the GitHub repo changes. GitHub stays the source of truth.

Clone URL 形如 https://origin.cursor.com/{owner}/{repo}.git。对已同步仓库，推送到该 remote 会回落到 GitHub。Attach cloud agents to a mirrored repo 时，那些 Agent 打开的是 GitHub pull requests。

API 文档进一步规定：a mirror is read-only until it becomes a stable outbound mirror。在非稳定出站状态，installation 通常只保留 repository:metadata:read 与 repository:contents:read；PR、review、checks、rulesets 与写操作会 403。mirror.status 不能单独作为是否可写的判断依据，应以实际 403 为准。

Webhook 差异：Origin does not deliver repository.pushed for a repository it mirrors from GitHub. GitHub owns those pushes. 镜像仓的 push 事件仍应以 GitHub webhook 为权威来源。

速率限制

共享 per-principal point budget，滚动一分钟窗口：

多数读与 Create Installation Access Token 为 1 点；较重读（含 Get Commit、List Pull Request Files、Get Repo Tarball）与普通写多为 5 点；Create Repo / Create Commit From Files / Merge Pull Request 为 10 点。超额返回 429 与 Retry-After。

Origin 适合 / 不适合

适合：

• 需要 PR、review、checks、webhook 的流水线
• 需要把权限装进 installation，而不是给每个 Agent 一把万能密钥
• Cursor-native 工作流、浏览器浏览 / 搜索、CLI、origin api
• 把云端 Agent 接到长期代码真源（含 GitHub mirror，但写回语义要分清）

不建议：

• 作为 Code Review SaaS 的唯一、长期稳定代码存档底座（Early Beta + mirror 只读语义 + partner API 不支持无限自助开仓）
• 每个会话新建一个仓库、用完就删
• Worker 内批量 create() 返回 remote + token（这是 Artifacts 的主场）

Cloudflare Artifacts：面向 Agent 的可编程 Git 存储

产品定位

官方一句话：Versioned storage that speaks Git.

Changelog（2026-04-16）与产品博客进一步写：Git-compatible storage built for scale — create tens of millions of repos, fork from any remote, and hand off a URL to any Git client. 它提供版本化文件系统，用于在 Workers、REST API 与任意 Git client 之间交换文件树。

Use Artifacts when you need to:

• Store versioned file trees instead of raw blobs
• Hand off work to Git-aware tools, agents, and automation
• Isolate work in separate repos or branches for safer parallel execution
• Fork from a shared baseline and diff or merge the results later

当前 overview 标注 closed beta（更新于 2026-05-05），需申请开通。2026-04-16 博客曾写 private beta，并称目标约 early May 进入 public beta；2026-09-10 核验时文档仍是 closed beta。

为什么选 Git，而不是新协议

Cloudflare 博客的核心论点：Agents know Git. 它深植于多数模型的训练数据；若发明新协议，就要额外分发 skill / CLI / docs MCP。给 Agent 一个已鉴权的 HTTPS Git remote，摩擦更低。

Git 数据模型也不只服务“源码托管”：配置、session prompts、agent history 都可以按小对象 + commit 历史做 time travel、fork 与 diff。Cloudflare 内部甚至用 per-session Artifacts repo 持久化 sandbox 文件系统与会话历史，以便分享、回溯与 fork 会话。

怎么调用 Artifacts API

同一仓库有三套接口。Workers binding 与 REST 是 Control Plane（建仓、import、发 token）；Git Smart HTTP 与部分 REST content 路由是 Data Plane（读 commits / trees / blobs）。

2026-04-16 changelog 里出现过 https://artifacts.cloudflare.net/v1/api/namespaces/...。现行 REST 文档（更新于 2026-08-13）以 Cloudflare v4 为控制面；Git remote 仍在 *.artifacts.cloudflare.net。集成时以 REST API 与 Get Repo 返回的 remote 为准。

Cloudflare API tokens authenticate REST control-plane routes. Repo tokens authenticate Git operations against the returned remote URL. 两类 token 不能互换。

1. Workers binding（控制面）

{
  "artifacts": [
    { "binding": "ARTIFACTS", "namespace": "default" }
  ]
}

跑 npx wrangler types，把生成的 Artifacts 类型当作当前环境的 source of truth。

Namespace 方法：

Repo handle 方法（先 await artifacts.get(name)）：

const imported = await env.ARTIFACTS.import({
  source: {
    url: "https://github.com/cloudflare/workers-sdk",
    branch: "main",
    depth: 100,
  },
  target: { name: "workers-sdk" },
});
// imported.remote / imported.token（字符串，expiry 写在 ?expires=）

const repo = await env.ARTIFACTS.get("workers-sdk");
const token = await repo.createToken("read", 3600);
// token.plaintext / token.expiresAt

create() / import() / fork() 返回的是 token 字符串；createToken() 返回结构化结果。Save remote and name if you need them later.

2. REST（控制面 + 内容读取）

先设环境变量：

export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ARTIFACTS_NAMESPACE="default"
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export ARTIFACTS_BASE_URL="https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/artifacts/namespaces/${ARTIFACTS_NAMESPACE}"
export ARTIFACTS_ACCOUNT_BASE_URL="https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/artifacts"

Namespace（account 级 base）：

Repo

导入公开 GitHub 仓（分析 / wiki 的主路径）：

curl --request POST "$ARTIFACTS_BASE_URL/repos/react-mirror/import" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://github.com/facebook/react",
    "branch": "main",
    "depth": 100
  }'

{
  "result": {
    "id": "repo_789",
    "name": "react-mirror",
    "default_branch": "main",
    "remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/react-mirror.git",
    "token": "art_v1_fedcba9876543210fedcba9876543210fedcba98?expires=1760007200"
  },
  "success": true,
  "errors": [],
  "messages": []
}

If a repo exists but is still importing or forking, this route can return 409 Conflict with a retriable error message.

Token（只给 Git 用，不能调 REST）

ttl：min 60 秒，max 31,536,000 秒（约 1 年），默认 86,400 秒。scope 默认 write。响应含 id / plaintext / scope / expires_at。

curl --request POST "$ARTIFACTS_BASE_URL/tokens" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"repo":"react-mirror","scope":"read","ttl":3600}'

不经 Git 读内容（wiki 生成可跳过 clone）

curl "$ARTIFACTS_BASE_URL/repos/react-mirror/file?ref=main&path=README.md" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --output README.md

Successful blob, file, and raw responses return file bytes directly instead of JSON. 找不到文件时仍走 v4 envelope，例如 { "success": false, "errors": [{ "code": 10200, "message": "File not found" }] }。

3. Git protocol（数据面）

用 Get Repo / create / import 返回的 remote，不要手拼 host。Git routes accept repo access tokens in two forms：

git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" \
  clone "$ARTIFACTS_REMOTE" artifacts-clone

短时一次性命令可以把 secret 嵌进 URL（先去掉 ?expires=）：

export ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}"
export ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}"
git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone

Token format: art_v1_<40 hex>?expires=<unix_seconds>. read 覆盖 clone / fetch / pull；write 才能 push。Protocol v2 支持 clone/fetch；push 只用 v1 receive-pack。

大仓不必等完整 clone：用 ArtifactFS 做 blobless clone，先拉 tree / refs，再按需 hydrate。它接受任意 Git remote，不限于 Artifacts。

Namespace、隔离与 Git 鉴权

Every repo lives inside one namespace. Repository names are unique within a namespace.

Treat each repository as one unit of work: one agent, session, user task, baseline, or fork target.

Artifacts tokens are repo-scoped. A token minted for one repository does not grant access to another repository, even in the same namespace.

• read: clone / fetch / pull
• write: includes push

限额、定价与底层实现

Limits：

Pricing（Workers Paid；Free 当前不可用）：

Replicas do not add storage charges. Repos remain stored until explicitly deleted.

底层（官方博客）：Artifacts are built on top of Durable Objects. 每个 repo 是可路由的隔离实例；Git server 用 Zig 实现并编译为约 100KB WASM；大对象可落 R2 snapshot，token 跟踪可用 KV。文件对象落在 Durable Object SQLite；大 Git object 跨行分块。

大仓启动：官方开源 ArtifactFS，对任意 Git remote（不限 Artifacts）做 blobless clone，先拉 tree / refs，再按需 hydrate 文件内容，优先 package.json / go.mod 等清单文件。Agent 仍用标准 commit + push，无需学新 API。

事件订阅已于 2026-05-19 进入文档：账户级 cf.artifacts.repo.created|deleted|forked|imported，仓级 pushed|cloned|fetched|token.created|token.revoked。构建指南可用 cf.artifacts.repo.pushed 触发 Workflow，且可省略 repoName 让同一份 CI 覆盖 Namespace 内所有仓。博客里仍列为路线图的能力包括原生 TS / Go / Python SDK 与搜索 API；实现时以已文档化路径为准。产品、限额、最佳实践见 Cloudflare Artifacts：产品、概念、API 与最佳实践。

Artifacts 适合 / 不适合

适合：

• Lovable / v0 式生成器的每用户、每会话仓库
• Agent 从共享基线 fork，提交后 diff / merge
• Code Review SaaS 的内部 Git 快照、可复现分析输入、候选修复分支
• 配置、notebook、会话状态需要 Git 语义，但不需要完整 forge UI
• 控制面必须写在 Worker / 应用代码里

不适合单独承担：

• 团队主仓库的长期评审与权限治理
• 私有 GitHub 仓的安装授权、细粒度权限、撤销清理（仍需 GitHub App / OAuth）
• 把公开开源社区协作直接建在 closed beta 存储层上

鉴权模型对照

flowchart TB
  subgraph originAuth [Origin]
    KEY[Ed25519 App Key]
    JWT[App JWT]
    INST[Installation]
    OIT[oit_ Installation Token]
    KEY --> JWT --> INST --> OIT
    OIT --> REST1[Origin REST]
    OIT --> GIT1[Git HTTPS Basic x-access-token]
  end
  subgraph artAuth [Artifacts]
    CF[Cloudflare API Token]
    BIND[Workers Binding / REST]
    REPO[Repo Handle]
    ART[art_v1_ Repo Token]
    CF --> BIND --> REPO --> ART
    ART --> GIT2[Git Smart HTTP Bearer or Basic]
  end

场景一：开源项目分析 + Wiki 生成 Agent

目标：在线代码浏览与分析，以及 DeepWiki / CodeWiki 一类从仓库生成知识库。功能列表由调用面决定：能 resolve SHA、能把树读出来、能订阅更新，就能做 wiki；没有 installation / webhook，就只能做一次性公开仓快照。

分析结果绑定：

tenantId / upstreamRepoId / commitSha / analysisVersion

不要用 branch 名当分析 ID。

路径 A：公开 HTTPS remote（不必装 Origin App，也不必装 GitHub App）

公开 GitHub / GitLab URL 直接走 Artifacts import，或本机 / Sandbox git clone。私有仓这条路不通，import 文档要求公开 HTTPS Git remote。GitHub App 只在需要私有仓授权、webhook 或回写 PR / check 时才值得装。

要 钉死某个版本 时，分析 ID 用 owner/repo@commitSha，不要用浮动 branch / tag。官方 import 的 branch 字段只文档化为 Branch to import，不要把 tag 名当作已保证参数。步骤：

1. git ls-remote 或 GitHub UI 得到 40 位 SHA。
2. 只要文件树、一次离线分析：下 GitHub source archive（https://github.com/owner/repo/archive/<SHA>.tar.gz），公开仓匿名可下。Source code archives
3. 要给 Agent 长期复用、可 fork：Artifacts import 含该 commit 的 branch，等 status: ready 后 GET .../commit/:sha 确认，再 checkout --detach <SHA> 或 GET /file?ref=<SHA>&path=...。浅 depth 可能不含旧 release。
4. 不要为此把仓 mirror 进 Origin。

可执行步骤与通过标准见 Cloudflare Artifacts：产品、概念、API 与最佳实践 的「归档公开 GitHub 的某个版本」。

Worker：

const imported = await env.ARTIFACTS.import({
  source: { url: "https://github.com/facebook/react", branch: "main", depth: 100 },
  target: { name: `wiki-${tenantId}-react` },
});

或 REST：

curl --request POST "$ARTIFACTS_BASE_URL/repos/wiki-react/import" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://github.com/facebook/react","branch":"main","depth":100}'

导入可能 409（仍在 importing）。list() / REST list 的 status 为 ready 后再读：

# 历史 → 选定 commit
curl "$ARTIFACTS_BASE_URL/repos/wiki-react/log?ref=main&limit=1" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# 单文件（wiki 封面、README、目录）
curl "$ARTIFACTS_BASE_URL/repos/wiki-react/file?ref=${SHA}&path=README.md" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# 需要完整工作树时再 Git
curl --request POST "$ARTIFACTS_BASE_URL/tokens" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"repo":"wiki-react","scope":"read","ttl":3600}'

git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" \
  clone "$ARTIFACTS_REMOTE" /tmp/wiki-react

索引、摘要草稿、失败重试痕迹另 create() / fork() 一个任务仓（write token 短 TTL），任务结束 DELETE .../repos/:name。Wiki 正文默认写 D1 / R2，不自动 push 回上游。

路径 B：用户把仓装进 Origin App

团队已在 Origin 上 native 托管，或 Sync from GitHub 成 mirror 时走这条。Partner 侧不能 POST /repos/{ownerSlug} 自助开仓，只能消费 installation 里已有的仓。

# 1. App JWT 兑换 oit_
curl --request POST \
  --url "https://api.cursor.com/v1/origin/app/installations/${INSTALLATION_ID}/access_tokens" \
  --header "Authorization: Bearer ${APP_JWT}" \
  --header "Content-Type: application/json" \
  --data '{"scopes":["repository:contents:read"]}'

# 2. 发现授权仓库（含 mirror）
curl --url "https://api.cursor.com/v1/origin/installation/repos" \
  --header "Authorization: Bearer ${OIT}"

# 3. 读 cloneUrl / defaultBranch
curl --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}" \
  --header "Authorization: Bearer ${OIT}"

# 4. resolve SHA
curl --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/git/ref/heads/main" \
  --header "Authorization: Bearer ${OIT}"

# 5. 整树进解析器
curl --request GET --location --output repo.tar.gz \
  --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/tarball/${SHA}" \
  --header "Authorization: Bearer ${OIT}"

增量 wiki（只更新改动文件）用 compare，不要反复下整包：

curl --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}/compare/${BASE}...${HEAD}/files" \
  --header "Authorization: Bearer ${OIT}"

触发：订阅 pull_request.created / head_ref.pushed。repository.pushed 对 GitHub inbound mirror 不会送达，那种仓继续接 GitHub push webhook，再用 Origin POST ...:syncMirror 等到 SHA 可见：

curl --request POST \
  --url "https://api.cursor.com/v1/origin/repos/${OWNER}/${REPO}:syncMirror" \
  --header "Authorization: Bearer ${OIT}" \
  --header "Content-Type: application/json" \
  --data '{"ref":"refs/heads/main","sha":"'"${SHA}"'","wait":true}'

Mirror 在变成 stable outbound 之前，installation 只保有 metadata:read + contents:read。PR / review / checks 写回会 403。GitHub Issues / Actions 也不在 Origin 上。

用户授权把 wiki 开回文档仓时，native Origin 才走：

POST /git/refs  →  POST /git/commits:createFromFiles  →  POST /pulls

镜像仓这条写路径不可用，应开 GitHub PR。

两条路径怎么拼

sequenceDiagram
  participant User
  participant Origin
  participant Artifacts
  participant Agent
  alt 公开 HTTPS URL
    User->>Artifacts: POST /repos/:name/import
    Artifacts-->>Agent: remote + token
    Agent->>Artifacts: GET /file 或 git clone
  else Origin installation
    User->>Origin: 安装 App 并选仓库
    Origin->>Agent: webhook
    Agent->>Origin: POST /access_tokens
    Agent->>Origin: GET /tarball/{sha}
    opt 需要可复现任务仓
      Agent->>Artifacts: create or fork
    end
  end
  Agent->>Agent: 绑定 tenantId / repoId / commitSha

第一阶段可以没有 Artifacts：Origin tarball 或公开 GitHub archive 直接进解析器。多轮 Agent、共享索引、长期文档分支再 import / create。Artifacts import() 得到的是 Artifacts 侧新仓库，不等于接管上游 PR、checks 或 webhook。

场景二：Lovable 式应用生成器的代码管理

目标：用户描述需求 → Agent 生成可运行应用 → 可继续改、可预览、可导出。

推荐主平面：Artifacts

实际调用顺序：

const template = await env.ARTIFACTS.get("app-template");
const project = await template.fork(`user-${userId}-app`, {
  defaultBranchOnly: true,
  readOnly: false,
});
const writeTok = await (await env.ARTIFACTS.get(project.name)).createToken("write", 3600);
// 把 project.remote + writeTok.plaintext 交给 Sandbox / coding Agent

REST 等价：POST .../repos/app-template/fork，再 POST .../tokens 且 scope: "write"。Agent 用 Git Smart HTTP push；预览运行时另签一把短 TTL read token。需要毕业到 Origin 时，改用 user access token 调 POST /v1/origin/repos/{ownerSlug}（这不是 partner / installation 路径），或推到 GitHub。

1. 模板基线：只读模板仓（readOnly 或只发 read token）。
2. 每次生成：fork(template) 或 create() 后写入初始提交，返回 remote + write token 给编码 Agent / Sandbox。
3. 多轮修改：同一用户项目固定一个 Artifacts repo；会话级分支隔离，合并后再签发新的短时 token。
4. 导出 / 开源：用户要把项目变成长期协作仓库时，再导出到 Origin 或 GitHub。

flowchart TB
  TPL[Template repo read-only]
  FORK[Artifacts fork per user project]
  AGENT[Coding Agent + Sandbox]
  PREVIEW[Preview runtime]
  EXPORT[Graduate to Origin or GitHub]
  TPL --> FORK --> AGENT
  FORK --> PREVIEW
  FORK --> EXPORT

Origin 仍有位置：团队模板正式版、付费用户“升级为正式项目”、CI 与人工评审。但默认租户存储应选 Artifacts，更符合其控制面与规模叙事。

Code Review / 分析 SaaS 的推荐拼法

若产品要“存档 GitHub 代码 + 浏览 + AI 分析 + 回写 review”，不要二选一，而要分层：

flowchart TB
  APP[GitHub App / Cursor Origin App]
  GW[Worker API Gateway]
  DB[(D1 / Postgres)]
  Q[Queues / Workflows]
  SNAP[Snapshot Worker]
  ART[Artifacts Git snapshot]
  R2[R2 large artifacts]
  AI[Sandbox / AI Agent]
  IDX[(Vector index)]
  OUT[Checks / PR comments]
  APP --> GW
  GW --> DB
  GW --> Q --> SNAP
  SNAP --> ART
  SNAP --> R2
  SNAP --> AI --> IDX
  AI --> OUT

职责划分：

• GitHub App / Origin App：安装授权、仓库选择、接收 webhook、读取真实 PR / diff、回写 review / check。
• Artifacts：内部 Git 快照、用户 patch、Agent 候选分支、可复现分析输入。
• R2：tarball、依赖缓存、AST / 索引中间产物、SARIF、LLM 原始输出、patch bundle。
• D1 / Postgres：租户、installation、repo mapping、commit / run、finding、计费与审计。
• 向量库：按 tenant_id + repo_id + commit_sha + path 检索；不作为代码原始档案。

示意数据模型（实现可按栈调整，关键是绑定 immutable commit）：

type RepositorySource = "github" | "cursor-origin" | "artifact";

interface CodeSnapshot {
  id: string;
  tenantId: string;
  source: RepositorySource;
  upstreamRepoId: string;
  commitSha: string;
  artifactNamespace: string | null;
  artifactRepo: string | null;
  contentState: "queued" | "ready" | "deleted" | "failed";
}

interface ReviewRun {
  id: string;
  tenantId: string;
  snapshotId: string;
  trigger: "push" | "pull_request" | "manual";
  provider: "github" | "cursor-origin";
  headCommitSha: string;
  status: "queued" | "running" | "completed" | "failed";
  model: string;
  promptVersion: string;
}

MVP 顺序

1. 先做 GitHub App：install、selected repositories、pull_request / push webhook、compare 或 shallow clone、回写 Check Run 或 PR comment。
2. 初期只保存必要快照：PR head / base commit、增量 diff、关联文件、分析结果。
3. 需要多轮 Agent、修复 patch、可复现 review 或长期分支分析时，再引入 Artifacts。
4. 用 tenant/repo/commit 或 tenant/repo/review-run 命名，配合 retention 与删除队列。
5. 私有代码使用短 TTL、repo-scoped token；不要在日志、R2 metadata 或 Git remote 配置里保存明文 token。
6. 最后加 Cursor Origin adapter：native Origin repo 可完整支持 PR / checks / review；GitHub mirror 优先从 GitHub 接 webhook 与写回。

选型清单

1. 仓库是给人协作的，还是给 Agent / 会话隔离的？
2. 是否需要 PR、review、checks、安装级权限？
3. 是否需要应用代码在一秒内创建仓库并返回 remote + token？
4. 仓库数量是几十个长期项目，还是海量短生命周期任务？
5. 是否必须运行在 Cloudflare Worker 控制面，并与 Sandbox / Containers 同区编排？
6. 若涉及 GitHub 真源，mirror 是否足够，还是必须保留 Issues / Actions / webhook 在 GitHub？

经验规则：

• 是 forge 协作 → Origin（或继续 GitHub）；Artifacts 只做旁路工作区。
• 是生成器租户仓 / Agent 任务仓 / 可复现快照 → Artifacts；需要对外开源或团队评审时再毕业到 Origin / GitHub。
• 两者都有 → 双平面：Origin / GitHub 持有真源与协作，Artifacts 持有瞬时工作副本。

边界、风险与反模式

• Origin is Early Beta; review the OpenAPI specification when updating an integration.
• Artifacts is closed beta; access must be enabled on the Cloudflare account.
• Do not confuse Cursor API keys with Origin installation tokens.
• Do not treat Artifacts repo tokens as account-wide credentials.
• Mirror and plan eligibility rules on Origin can make a repository look present while writes still return 403.
• Artifacts marketing scale（“tens of millions of repos”）是产品叙事；设计应对齐 documented limits、pricing 与账户开通状态。
• 反模式：用 Origin 承载每会话临时盘，却缺少批量创建控制面。
• 反模式：用 Artifacts 充当团队主仓库 + 评审流程，却缺少 forge 事件与安装级权限模型。
• 反模式：把第三方博客或未核验转述写进生产契约；第三方页面只可作线索，事实以官方文档为准。

参考资料

• Origin（核验 2026-09-10）
• Origin API（含 OpenAPI、端点与 webhook；核验 2026-09-10）
• Origin API Changelog
• Origin CLI origin api
• Mirror a GitHub repository
• Cursor APIs Overview
• Cloudflare Artifacts：产品、概念、API 与最佳实践（站内专题，核验 2026-09-10）
• Artifacts
• Repositories
• How Artifacts works
• Workers binding
• REST API（现行控制面：Cloudflare v4；更新于 2026-08-13）
• Git protocol
• ArtifactFS
• Limits
• Pricing
• Artifacts now in beta changelog
• Artifacts: versioned storage that speaks Git
• Cloudflare Artifacts product page

Context7 核查说明：通过 /cloudflare/cloudflare-docs 核对了 Artifacts Workers binding、import()、createToken TTL（60 秒至约 1 年）、v4 REST base URL、content 路由（/file /log /tree）、limits 与 Git Bearer / http.extraHeader 示例。Origin 未作为独立 Context7 库收录；App JWT claims、Installation Access Token、tarball、contents:batchGet、partner 开仓限制与 webhook 事件以 Origin API 2026-09-10 页面为准。changelog 中的 artifacts.cloudflare.net/v1/api 只作历史线索，不以它为现行 REST 契约。Perplexity 线程提供了问题框架与架构草案；正文只保留经官方文档或 Context7 可回证的事实，以及明确标注为架构建议的部分。