从 CHANGELOG 读懂 artifacts-viewerCloudflare Artifacts 只读仓库浏览器的版本演进与架构实现【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdkartifacts-viewer 是 vibesdk 仓库中独立发布的 npm 包提供一套面向 Cloudflare Artifacts 的只读仓库浏览方案服务端代理路由器、类型化 HTTP 客户端与无样式 React 组件。本文以该包 CHANGELOG.md 的版本记录为主线逐版拆解从 0.0.1 到 0.0.5 的功能演进并结合包内源码与完整 README.md 说明每一项变更背后的架构决策与实战用法读完你可以掌握该包的安装、挂载、权限控制、缓存、客户端与 React 组件全链路也能理解一个面向公有云 API 的只读代理在真实演进中的取舍逻辑。版本脉络总览在深入代码之前先用一张表把 CHANGELOG 记录的五个版本串起来后续小节逐一展开版本主题核心变更0.0.1路由与缓存的奠基新增routeArtifactRequest只读 HTTP 路由器覆盖 Cloudflare Artifacts 的 7 个官方只读操作新增createCacheApiAdapter与createKvCacheAdapter只缓存内容寻址读取0.0.2发布管线验证端到端验证发布流程路由器与缓存适配器无功能性改动0.0.3架构转向移除 Artifacts binding 派发全部读取改走官方 REST API新增类型化客户端与 React 组件表面0.0.4可安装性修复package.json 中的 catalog 协议范围在发布时被解析使包可在工作区之外安装0.0.5状态渲染插槽新增renderStatus可为加载/空/错误三态替换默认标记并携带可访问性语义对应发布包的导出入口定义在 package.jsonartifacts-viewer服务端路由器、artifacts-viewer/client类型化客户端、artifacts-viewer/reactReact 组件与 hooks、artifacts-viewer/server/cache缓存适配器与artifacts-viewer/styles.css结构性样式。0.0.1 —— 只读路由器与缓存适配器的奠基CHANGELOG 的 0.0.1 条目记录了包的两个地基routeArtifactRequest与两个缓存适配器。这一版同时确立了包的五个入口点其中 client 与 React 表面尚未实现not implemented yet是典型的先立服务端、再补前端的演进顺序。routeArtifactRequest只代理七种读操作routeArtifactRequest是一个无 React、平台中立的路由函数实现位于 router.ts。它只依赖Request、Response、Headers、URL与fetch因此可以运行在 Cloudflare Workers、Node、Deno 或 Bun 上function routeArtifactRequest( request: Request, options: ArtifactRouterOptions, ): PromiseResponse | null;返回值的设计值得注意当请求路径落在挂载点apiPath之外时返回null调用方可以自然回退到自己的路由一旦请求进入挂载点内所有结果都是Response——包括未知子路径返回的 404。源码注释明确说明了这一边界策略Owning the namespace outright is what makes the boundary predictable彻底拥有命名空间边界行为才可预测。七种只读操作的路径与用途如下路径与 Cloudflare 命名空间相对路径 1:1 对齐但accountId与namespace刻意不出现在浏览器可见 URL 中挂载路由用途GET {apiPath}/repos/{repo}仓库元数据GET {apiPath}/repos/{repo}/log?reflimitoffset提交日志GET {apiPath}/repos/{repo}/commit/{hash}单个提交GET {apiPath}/repos/{repo}/tree/{hash}单个目录层级GET {apiPath}/repos/{repo}/blob/{hash}按哈希取文件字节GET {apiPath}/repos/{repo}/file?refpath按路径取文件字节GET {apiPath}/repos/{repo}/raw/{ref}/{path}以浏览器安全的内容类型取文件字节除此之外什么都不可达写入、仓库创建、token 端点一律不代理。这在 routes.ts 中有更细的实现证据——路由表只识别repos集合下的这七种形状且allowedMethods硬编码为[GET]非 GET 方法对真实路由返回 405 并带Allow头而不是误报 404。路由匹配的细节也值得关注路径匹配发生在段边界segment boundary所以/artifacts不会误伤/artifacts-internal段先解码后校验避免%2e%2e绕过..检查decodeURIComponent抛出的URIError被捕获后转为 400 而非 500防止调用方可控字符串引发服务器错误。缓存适配器只缓存内容寻址读取0.0.1 引入的两个缓存适配器位于 cache-adapters.ts统一实现ArtifactsCacheAdapter接口type ArtifactsCacheAdapter { get(key: string): PromiseResponse | undefined; set(key: string, response: Response): Promisevoid; };createCacheApiAdapter({ cache, baseUrl })包装 Workers Cache API推荐的生产后端。它支持流式读写大 blob 不会常驻内存baseUrl必须是 Worker 真正服务的 origin因为 Cache API 按 URL 键控且限定于所在 zone。createKvCacheAdapter({ kv })包装 Workers KV结构化声明ArtifactsKvNamespace类型而非直接依赖KVNamespace使发布后的类型定义无需安装cloudflare/workers-types即可使用。缓存的关键约束在 cache.ts 中体现只有内容寻址读取commit、tree、blob会被缓存因为它们的值在语义上永不失效repository、log、file、raw这类引用寻址ref-addressed读取从不缓存因此整个模块没有任何 TTL 概念也没有陈旧窗口需要推理。内容寻址响应被标记为public, max-age31536000, immutable一年不可变。缓存键由namespace:repoName:operation:hash拼接变量部分均做encodeURIComponent防止值内包含分隔符伪造不同键。适配器允许抛错但 router.ts 中的safeCacheGet/safeCacheSet会捕获异常并回调onCacheError——缓存是优化绝不能让慢请求变成失败请求。0.0.2 —— 发布管线验证CHANGELOG 明确说明 0.0.2 Verify the release pipeline end to end. No functional changes端到端验证发布管线无功能性改动。这一版本没有新增 API但对仓库维护者而言意义在于从这一版开始包的构建、检查与发布脚本被验证可用。从 package.json 可以看到其发布脚本为prepublishOnly: vp run build构建工具采用vite-plusvp pack并声明sideEffects: [**/*.css]保证样式导入不会被 tree-shaking 移除。0.0.3 —— 告别 Binding 派发全面转向官方 REST API0.0.3 是架构上最重要的一次转向CHANGELOG 记录了原因与两个新增表面。为什么移除 Artifacts bindingCHANGELOG 原文给出了精确的技术理由binding 的 repository handle 是一个 RPC stub其元数据属性metadata properties无法被读取导致通过 binding 服务的仓库读取返回空载荷empty payload。因此这一版彻底移除了ArtifactRouterOptions.binding与ArtifactsBinding/ArtifactsRepositoryHandle类型所有读取改走官方 REST API。当前源码中 REST 派发集中在 upstream.ts这是全包唯一持有 API token 的模块上游基地址为https://api.cloudflare.com/client/v4路径按accounts/{accountId}/artifacts/namespaces/{namespace}/repos/{repo}/...逐段构造每个段独立编码防止组件内的/悄然加深路径层级出站请求从零构建只带Accept与Authorization: Bearer {token}两个头调用方的Authorization、Cookie及其他入站头全部被丢弃从机制上杜绝了凭据连带泄漏blob/file操作发送Accept: application/octet-streamraw发送Accept: */*以便上游挑选浏览器安全的内容类型其余发送application/json响应头只通过白名单转发Content-Type、Content-Length、Content-Disposition、ETag、Last-Modified且 body 按引用透传、从不缓冲多 MB 的 blob 得以流式到达客户端。路由器本地生成的错误也统一包装成 Cloudflare v4 信封{ result, success, errors }见 responses.ts使客户端无论面对本地错误还是上游错误都只需一个解析器本地错误码直接复用 HTTP 状态码保持自描述。新增 typed HTTP client 与 React 表面0.0.3 同时补齐了 CHANGELOG 预告的两大入口artifacts-viewer/client框架无关、不依赖 Worker 全局对象。createArtifactsClient({ apiPath?, fetch? })创建客户端实例client.ts提供七个方法加一个同步辅助方法返回getRepository({ repoName, signal? })ArtifactsRepositorygetLog({ repoName, ref?, limit?, offset?, signal? })ArtifactsCommitMetadata[]readCommit({ repoName, hash, signal? })ArtifactsCommitMetadatareadTree({ repoName, hash, signal? })ArtifactsTreeEntry[]readBlob({ repoName, hash, signal? })ResponsereadFile({ repoName, ref, path, signal? })ResponsegetRawUrl({ repoName, ref, path })string同步每个异步方法都返回结果联合{ ok: true; value } | { ok: false; error }而非抛异常错误按network/not-found/http/malformed分类。二进制读取直接交还Response不做缓冲或 base64 编码。JSON 载荷在边界处逐字段收窄field-by-field narrowing不使用类型断言仓库元数据也完成了 snake_case 到 camelCase 的归一化。ArtifactsTreeEntry的type支持tree | blob | symlink | gitlink | exec其中exec/symlink按 blob 处理gitlink是子模块指针、在当前仓库无内容、渲染为惰性行。artifacts-viewer/react提供ArtifactRepoViewer双栏浏览器侧边栏树 内容面板、ArtifactFileTree懒展开侧边栏树、ArtifactDirectoryView单目录平铺列表、ArtifactFileView单文件视图含 Raw/Download 与内容渲染、CodeView对已有内容做语法高亮。在ArtifactRepoViewer中内容面板在选中文件时显示文件、在根目录以下的任意目录显示列表而根目录本身留空——侧边栏已经列出它重复展示会读起来冗余ArtifactDirectoryView没有这条规则直接使用时列出传入的任意树。0.0.4 —— 让发布包在工作区之外可安装0.0.4 的变更只有一句但解决了真实痛点Ship package.json with catalog protocol ranges resolved so the published package installs outside this workspace发布时解析 catalog 协议范围使包可在本工作区之外安装。这是 pnpm workspace 的典型问题catalog:协议见 package.json 中的pierre/diffs: catalog:只在 workspace 内部有效直接发布会让外部npm install artifacts-viewer因无法解析catalog:而失败。此版在发布产物中将其解析为具体版本范围依赖项只保留一个pierre/diffsreact与react-dom声明为 peer 依赖^18.2.0 || ^19.0.0。0.0.5 —— renderStatus可插拔的状态渲染最新版本 0.0.5 引入了renderStatus——一个部分插槽映射partial slot map用于替换ArtifactRepoViewer、ArtifactFileTree、ArtifactDirectoryView、ArtifactFileView上的默认加载、空与错误标记。判别联合上下文与三个渲染器每个渲染器接收一个判别联合ArtifactStatusContext同一个函数可以按面板分别响应type ArtifactStatusContext | { scope: repository; repoName: string } | { scope: tree; repoName: string; path: string } | { scope: file; repoName: string; path: string; name: string }; type ArtifactEmptyKind empty | binary | oversized; type ArtifactStatusRenderers { loading?: (context: ArtifactStatusContext) ReactNode; empty?: (context: ArtifactStatusContext, kind?: ArtifactEmptyKind) ReactNode; error?: (context: ArtifactStatusContext, error: ArtifactsClientError) ReactNode; };kind只在文件上有值——仓库或目录的身份已由context.scope表达。这同时也是本地化文案的入口默认每个面板渲染英文pLoading repository…、This directory is empty.、Binary file (12.4 KiB).等renderStatus替换这些标记即完成 i18nArtifactRepoViewer client{client} repoNamewebsite renderStatus{{ loading: (context) Spinner label{context.scope} /, empty: (context, kind) Notice kind{kind} scope{context.scope} /, error: (context, error) Notice tonedanger{error.message}/Notice, }} /实现上status.tsx有三个值得记住的行为映射是部分的渲染器返回undefined包括你根本没命名它时保留默认标记返回null则什么都不渲染。插槽语义存活自定义输出仍被包裹在对应插槽元素中data-artifacts-viewer-slot、aria-busy、rolealert、data-kind依旧存在并可被选择器命中、被屏幕阅读器播报无需重复编写。可组合renderStatus同时被四个组件接受自己拼装这些组件时同样生效。代码视图刻意不在renderStatus覆盖范围内它等待的是高亮器而非网络且已有renderCodeFallback负责那个占位场景。请求流从两次往返到永久缓存把 CHANGELOG 的版本脉络与 README.md 的Request flow一节结合可以看到渲染一个仓库的完整数据流browser your server Cloudflare ┌──────────────────┐ ┌──────────────────────┐ ┌──────────────┐ │ArtifactRepoViewer│ │ routeArtifactRequest │ │ Artifacts │ │ ↓ │─────▶│ · validates │─────▶│ REST API │ │ ArtifactsClient │ │ · adds API token │ │ │ └──────────────────┘ │ · optional cache │ └──────────────┘ GET /artifacts/… └──────────────────────┘ Bearer token渲染一个仓库先花两次往返随后全部进入内容寻址模式getLog({ limit: 1 }) → commits[0].treeHash (ref 省略 默认分支) readTree(commit.treeHash) → 根目录条目此后每次导航都由 git 哈希寻址——目录用readTree(entry.hash)、文件用readBlob(entry.hash)——响应不可变可以永久缓存。这也是 router.ts 中步骤顺序承重的原因beforeRequest授权钩子在缓存查询之前执行缓存命中永远不可能绕过访问控制。授权、响应行为与 CORS授权beforeRequest接收{ request, read, operation }其中read是已完整校验的判别联合repoName、hash、ref、path可直接用于策略决策返回Response即短路拒绝。注意 README 有明确警告路由器默认放行所有请求暴露端点前必须自行加beforeRequest策略否则任何能触达该端点的人都能读取命名空间下任意合法仓库名。响应行为挂载点外 →null挂载点内未知路由 → 404已知路由错误方法 → 405 带Allow头参数畸形 → 400且不上游发送任何内容。CORS不处理由调用方在调用后自行添加响应头OPTIONS会返回 405委托前应先拦截预检if (request.method OPTIONS) return myPreflight(request);。挂载到 Worker 的完整示例// worker/index.ts import { routeArtifactRequest } from artifacts-viewer; import { createCacheApiAdapter } from artifacts-viewer/server/cache; export default { async fetch(request, env, ctx) { const handled await routeArtifactRequest(request, { accountId: env.ARTIFACTS_ACCOUNT_ID, namespace: env.ARTIFACTS_NAMESPACE, apiToken: env.ARTIFACTS_API_TOKEN, beforeRequest: async ({ request, read }) { const user await getSessionUser(request); if (user null || !user.repositories.includes(read.repoName)) { return new Response(Forbidden, { status: 403 }); } }, cache: createCacheApiAdapter({ cache: caches.default, baseUrl: new URL(request.url).origin, }), waitUntil: (promise) { ctx.waitUntil(promise); }, }); return handled ?? new Response(Not found, { status: 404 }); }, } satisfies ExportedHandlerEnv;ArtifactRouterOptions完整选项表选项类型说明accountIdstring必填namespacestring必填apiTokenstring必填需具备 Artifacts 读权限的 Cloudflare API tokenapiPathstring默认/artifacts段边界匹配fetchtypeof fetch可选注入点用于测试与追踪beforeRequestArtifactBeforeRequestHook授权钩子返回Response即拒绝cacheArtifactsCacheAdapter仅对内容寻址读取生效waitUntil(p: Promiseunknown) void让缓存写入在响应结束后继续存活onCacheError(error: unknown) void缓存失败在此上报绝不抛出waitUntil的存在有明确的实现理由如果同步等待缓存写入大 body 会死锁——clone在原响应被消费前无法排空而原响应要等函数返回后才被消费。因此写入交给ctx.waitUntil保持存活。若 Worker 同时托管静态资源需在wrangler.jsonc中让 API 先于资源处理器命中// wrangler.jsonc { assets: { not_found_handling: single-page-application, run_worker_first: [/artifacts/*], }, }客户端与 hooks客户端实例应在模块作用域创建并复用——hooks 把client当作依赖每次渲染新建实例会导致无限重新请求import { createArtifactsClient } from artifacts-viewer/client; import { ArtifactRepoViewer } from artifacts-viewer/react; import artifacts-viewer/styles.css; const client createArtifactsClient(); export function Repository() { return ArtifactRepoViewer client{client} repoNamemy-repository /; }React hooks 返回判别状态联合没有isLoading布尔值type ArtifactQueryStateT | { status: idle } | { status: loading } | { status: success; data: T } | { status: error; error: ArtifactsClientError };Hook返回useArtifactRepository(client, repoName)ArtifactsRepositoryuseArtifactLog(client, { repoName, ref?, limit?, offset? })ArtifactsCommitMetadata[]useArtifactHeadCommit(client, repoName, ref?)ArtifactsCommitMetadata \| nulluseArtifactTree(client, repoName, treeHash \| null)ArtifactsTreeEntry[]useArtifactBlob(client, { repoName, name, hash, maxInlineBytes? })ArtifactBlobRenderuseArtifactQuery(run, deps)任意值其余 hooks 的基元hooks 层没有缓存、没有请求去重依赖变化或组件卸载即通过AbortSignal取消。缓存属于你自己的数据层——传入一个查缓存的fetch或包装 client。useArtifactHeadCommit对空仓库解析为null且 README 特别提醒不要用lastPushAt判断空仓库因为 Artifacts API 在该字段上始终返回null。useArtifactBlob产生渲染分类type ArtifactBlobRender | { kind: empty } | { kind: text; contents: string } | { kind: image; contentType: string } | { kind: binary; sizeBytes: number } | { kind: oversized };组件完全可组合hooks 全部公开可以整体替换标记层ArtifactRepoViewer内部持有当前选中状态。README 给出了最小自建树组件的例子用useArtifactTree渲染一个ul。ArtifactRepoViewer的 props 中有一个易踩的命名细节prop 叫gitRef而不是ref因为 React 保留了ref。样式、语法高亮与行为限制结构性样式与选择器钩子artifacts-viewer/styles.css只做结构不做主题主布局值全部暴露为自定义属性如--artifacts-viewer-sidebar-width默认16rem、--artifacts-viewer-pane-height默认none、--artifacts-viewer-mono-font默认monospace等选择器刻意使用:where()保持低优先级普通应用规则无需!important即可覆盖。公开插槽与部件携带稳定属性data-artifacts-viewer-slotroot、toolbar、sidebar、tree、treeItem、content、directory、directoryItem、file、loading、empty、error与data-artifacts-viewer-partheader、name、icon、actions、raw、download、code、code-pending、code-fallback、code-highlight、image。状态属性方面data-selected是裸属性bare attribute选择器应写[data-selected]而非[data-selectedtrue]。布局由容器查询驱动两个面板在根元素自身宽度小于40rem时折叠为单列而不是以视口宽度为准。语法高亮与预加载文本文件经pierre/diffs包装 Shiki渲染通过动态import()加载不会进入首屏 bundleArtifactRepoViewer挂载时即主动开始拉取该 chunk。高亮未就绪前绝不展示未高亮文本——占位与文件共享同一网格单元不会发生布局跳动。三个状态依次为PreparingrenderCodeFallback或默认加载文案data-artifacts-viewer-partcode-pending→ Ready高亮文件code-highlight→ Unavailable纯pre文本code-fallback仅在预加载报告高亮不可初始化时可达。renderCodeFallback是渲染 prop接收{ name, contents }contents是解码后的文件内容因此骨架屏可以按真实行数定高。preloadCodeView是函数而非 prop预热懒 chunk、共享 Shiki 引擎、主题以及给定文件名时该文件的语法ArtifactRepoViewer挂载时已调用它你还可以更早调用——路由进入时或行悬停时li onPointerEnter{() void preloadCodeView({ theme, name: entry.name })}它按主题与语法集合记忆化重复调用零成本返回booleanfalse表示高亮不可用即上面的纯文本态可达。主题必须通过选项传入因为pierre/diffs渲染进开放的 Shadow DOM普通 CSS 无法触达内部ArtifactRepoViewer client{client} repoNamemy-repository pierreDiffsOptions{{ theme: { light: github-light, dark: vesper }, themeType: system, }} /theme接受 Shiki 主题名或{ light, dark }对themeType为system默认/light/darkunsafeCSS可注入 Shadow DOM 原始 CSS但跨 Pierre 版本不稳定。选项对象需保持引用稳定或 memoize避免代码视图反复重渲染。行为限制Limits and behaviour大文件maxInlineBytes默认 512 KiB。响应声明的Content-Length更大则 body 永不下载否则流式读取并在越过上限的瞬间取消。无论哪种路径状态都变为oversizedRaw/Download 链接仍可用。图片按扩展名识别apng、avif、bmp、gif、ico、jfif、jpeg、jpg、png、svg、webp永不经过 client 下载直接以img src从 raw URL 渲染SVG 保持在图片语境绝不内联。文本 vs 二进制用严格 UTF-8 解码加首 8 KiB NUL 字节扫描判定而非扩展名列表判定失败的归为binary绝不进入高亮器。Raw/Download URL固定到提交哈希而非分支名即使会话中有人 push链接依然可解析且可缓存。树展开按路径键控而非树哈希两条路径下的相同子树可独立展开。可访问性侧边栏是嵌套 disclosure 按钮的nav而非roletree——完整 WAI-ARIA 树键盘导航未实现宣称该角色反而更糟行是真按钮或提供buildHref时是真锚点。明确不在范围内CHANGELOG 之外的 README 也划清了边界Markdown 渲染.md目前以高亮纯文本显示、diff 查看与提交历史 UI、分支切换Artifacts REST API 无 ref 列举操作枚举分支需要 Git protocol v2ls-refs只能向gitRef传已知分支或省略取默认分支、以及任何写入操作均不在当前范围内。从版本演进看设计主线把五个版本的 CHANGELOG 连起来读可以清晰看到 artifacts-viewer 的三条设计主线也方便你在自己的项目中复用同样的判断最小代理面只暴露七种只读操作写入与凭据端点绝不代理入站请求头全部丢弃、出站头从零构建、响应头白名单转发token 只存在于 upstream.ts 一个模块。把不可变当缓存依据只缓存内容寻址读取并标记一年不可变全模块零 TTL、零陈旧窗口授权钩子永远先于缓存执行。渐进式补全前端0.0.1 先立服务端与缓存0.0.3 才补 client 与 React 表面0.0.5 再开放状态插槽——每一版都解决上一版暴露的真实问题binding 空载荷、catalog 协议无法外部安装、默认状态无法本地化。如果你正要把 Cloudflare Artifacts 的仓库浏览能力集成进自己的产品例如像 vibesdk 这类以 Cloudflare 全栈为基础的应用可以直接复用 apps/example 作为参考实现安装artifacts-viewernpm install artifacts-viewerreact/react-dom需^18.2.0 || ^19.0.0按上文挂载路由、渲染组件并将apiPath在客户端与路由器两端保持一致。包目前处于 1.0 之前README 建议锁定精确版本号使用。【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 CHANGELOG 读懂 artifacts-viewer：Cloudflare Artifacts 只读仓库浏览器的版本演进与架构实现
从 CHANGELOG 读懂 artifacts-viewerCloudflare Artifacts 只读仓库浏览器的版本演进与架构实现【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdkartifacts-viewer 是 vibesdk 仓库中独立发布的 npm 包提供一套面向 Cloudflare Artifacts 的只读仓库浏览方案服务端代理路由器、类型化 HTTP 客户端与无样式 React 组件。本文以该包 CHANGELOG.md 的版本记录为主线逐版拆解从 0.0.1 到 0.0.5 的功能演进并结合包内源码与完整 README.md 说明每一项变更背后的架构决策与实战用法读完你可以掌握该包的安装、挂载、权限控制、缓存、客户端与 React 组件全链路也能理解一个面向公有云 API 的只读代理在真实演进中的取舍逻辑。版本脉络总览在深入代码之前先用一张表把 CHANGELOG 记录的五个版本串起来后续小节逐一展开版本主题核心变更0.0.1路由与缓存的奠基新增routeArtifactRequest只读 HTTP 路由器覆盖 Cloudflare Artifacts 的 7 个官方只读操作新增createCacheApiAdapter与createKvCacheAdapter只缓存内容寻址读取0.0.2发布管线验证端到端验证发布流程路由器与缓存适配器无功能性改动0.0.3架构转向移除 Artifacts binding 派发全部读取改走官方 REST API新增类型化客户端与 React 组件表面0.0.4可安装性修复package.json 中的 catalog 协议范围在发布时被解析使包可在工作区之外安装0.0.5状态渲染插槽新增renderStatus可为加载/空/错误三态替换默认标记并携带可访问性语义对应发布包的导出入口定义在 package.jsonartifacts-viewer服务端路由器、artifacts-viewer/client类型化客户端、artifacts-viewer/reactReact 组件与 hooks、artifacts-viewer/server/cache缓存适配器与artifacts-viewer/styles.css结构性样式。0.0.1 —— 只读路由器与缓存适配器的奠基CHANGELOG 的 0.0.1 条目记录了包的两个地基routeArtifactRequest与两个缓存适配器。这一版同时确立了包的五个入口点其中 client 与 React 表面尚未实现not implemented yet是典型的先立服务端、再补前端的演进顺序。routeArtifactRequest只代理七种读操作routeArtifactRequest是一个无 React、平台中立的路由函数实现位于 router.ts。它只依赖Request、Response、Headers、URL与fetch因此可以运行在 Cloudflare Workers、Node、Deno 或 Bun 上function routeArtifactRequest( request: Request, options: ArtifactRouterOptions, ): PromiseResponse | null;返回值的设计值得注意当请求路径落在挂载点apiPath之外时返回null调用方可以自然回退到自己的路由一旦请求进入挂载点内所有结果都是Response——包括未知子路径返回的 404。源码注释明确说明了这一边界策略Owning the namespace outright is what makes the boundary predictable彻底拥有命名空间边界行为才可预测。七种只读操作的路径与用途如下路径与 Cloudflare 命名空间相对路径 1:1 对齐但accountId与namespace刻意不出现在浏览器可见 URL 中挂载路由用途GET {apiPath}/repos/{repo}仓库元数据GET {apiPath}/repos/{repo}/log?reflimitoffset提交日志GET {apiPath}/repos/{repo}/commit/{hash}单个提交GET {apiPath}/repos/{repo}/tree/{hash}单个目录层级GET {apiPath}/repos/{repo}/blob/{hash}按哈希取文件字节GET {apiPath}/repos/{repo}/file?refpath按路径取文件字节GET {apiPath}/repos/{repo}/raw/{ref}/{path}以浏览器安全的内容类型取文件字节除此之外什么都不可达写入、仓库创建、token 端点一律不代理。这在 routes.ts 中有更细的实现证据——路由表只识别repos集合下的这七种形状且allowedMethods硬编码为[GET]非 GET 方法对真实路由返回 405 并带Allow头而不是误报 404。路由匹配的细节也值得关注路径匹配发生在段边界segment boundary所以/artifacts不会误伤/artifacts-internal段先解码后校验避免%2e%2e绕过..检查decodeURIComponent抛出的URIError被捕获后转为 400 而非 500防止调用方可控字符串引发服务器错误。缓存适配器只缓存内容寻址读取0.0.1 引入的两个缓存适配器位于 cache-adapters.ts统一实现ArtifactsCacheAdapter接口type ArtifactsCacheAdapter { get(key: string): PromiseResponse | undefined; set(key: string, response: Response): Promisevoid; };createCacheApiAdapter({ cache, baseUrl })包装 Workers Cache API推荐的生产后端。它支持流式读写大 blob 不会常驻内存baseUrl必须是 Worker 真正服务的 origin因为 Cache API 按 URL 键控且限定于所在 zone。createKvCacheAdapter({ kv })包装 Workers KV结构化声明ArtifactsKvNamespace类型而非直接依赖KVNamespace使发布后的类型定义无需安装cloudflare/workers-types即可使用。缓存的关键约束在 cache.ts 中体现只有内容寻址读取commit、tree、blob会被缓存因为它们的值在语义上永不失效repository、log、file、raw这类引用寻址ref-addressed读取从不缓存因此整个模块没有任何 TTL 概念也没有陈旧窗口需要推理。内容寻址响应被标记为public, max-age31536000, immutable一年不可变。缓存键由namespace:repoName:operation:hash拼接变量部分均做encodeURIComponent防止值内包含分隔符伪造不同键。适配器允许抛错但 router.ts 中的safeCacheGet/safeCacheSet会捕获异常并回调onCacheError——缓存是优化绝不能让慢请求变成失败请求。0.0.2 —— 发布管线验证CHANGELOG 明确说明 0.0.2 Verify the release pipeline end to end. No functional changes端到端验证发布管线无功能性改动。这一版本没有新增 API但对仓库维护者而言意义在于从这一版开始包的构建、检查与发布脚本被验证可用。从 package.json 可以看到其发布脚本为prepublishOnly: vp run build构建工具采用vite-plusvp pack并声明sideEffects: [**/*.css]保证样式导入不会被 tree-shaking 移除。0.0.3 —— 告别 Binding 派发全面转向官方 REST API0.0.3 是架构上最重要的一次转向CHANGELOG 记录了原因与两个新增表面。为什么移除 Artifacts bindingCHANGELOG 原文给出了精确的技术理由binding 的 repository handle 是一个 RPC stub其元数据属性metadata properties无法被读取导致通过 binding 服务的仓库读取返回空载荷empty payload。因此这一版彻底移除了ArtifactRouterOptions.binding与ArtifactsBinding/ArtifactsRepositoryHandle类型所有读取改走官方 REST API。当前源码中 REST 派发集中在 upstream.ts这是全包唯一持有 API token 的模块上游基地址为https://api.cloudflare.com/client/v4路径按accounts/{accountId}/artifacts/namespaces/{namespace}/repos/{repo}/...逐段构造每个段独立编码防止组件内的/悄然加深路径层级出站请求从零构建只带Accept与Authorization: Bearer {token}两个头调用方的Authorization、Cookie及其他入站头全部被丢弃从机制上杜绝了凭据连带泄漏blob/file操作发送Accept: application/octet-streamraw发送Accept: */*以便上游挑选浏览器安全的内容类型其余发送application/json响应头只通过白名单转发Content-Type、Content-Length、Content-Disposition、ETag、Last-Modified且 body 按引用透传、从不缓冲多 MB 的 blob 得以流式到达客户端。路由器本地生成的错误也统一包装成 Cloudflare v4 信封{ result, success, errors }见 responses.ts使客户端无论面对本地错误还是上游错误都只需一个解析器本地错误码直接复用 HTTP 状态码保持自描述。新增 typed HTTP client 与 React 表面0.0.3 同时补齐了 CHANGELOG 预告的两大入口artifacts-viewer/client框架无关、不依赖 Worker 全局对象。createArtifactsClient({ apiPath?, fetch? })创建客户端实例client.ts提供七个方法加一个同步辅助方法返回getRepository({ repoName, signal? })ArtifactsRepositorygetLog({ repoName, ref?, limit?, offset?, signal? })ArtifactsCommitMetadata[]readCommit({ repoName, hash, signal? })ArtifactsCommitMetadatareadTree({ repoName, hash, signal? })ArtifactsTreeEntry[]readBlob({ repoName, hash, signal? })ResponsereadFile({ repoName, ref, path, signal? })ResponsegetRawUrl({ repoName, ref, path })string同步每个异步方法都返回结果联合{ ok: true; value } | { ok: false; error }而非抛异常错误按network/not-found/http/malformed分类。二进制读取直接交还Response不做缓冲或 base64 编码。JSON 载荷在边界处逐字段收窄field-by-field narrowing不使用类型断言仓库元数据也完成了 snake_case 到 camelCase 的归一化。ArtifactsTreeEntry的type支持tree | blob | symlink | gitlink | exec其中exec/symlink按 blob 处理gitlink是子模块指针、在当前仓库无内容、渲染为惰性行。artifacts-viewer/react提供ArtifactRepoViewer双栏浏览器侧边栏树 内容面板、ArtifactFileTree懒展开侧边栏树、ArtifactDirectoryView单目录平铺列表、ArtifactFileView单文件视图含 Raw/Download 与内容渲染、CodeView对已有内容做语法高亮。在ArtifactRepoViewer中内容面板在选中文件时显示文件、在根目录以下的任意目录显示列表而根目录本身留空——侧边栏已经列出它重复展示会读起来冗余ArtifactDirectoryView没有这条规则直接使用时列出传入的任意树。0.0.4 —— 让发布包在工作区之外可安装0.0.4 的变更只有一句但解决了真实痛点Ship package.json with catalog protocol ranges resolved so the published package installs outside this workspace发布时解析 catalog 协议范围使包可在本工作区之外安装。这是 pnpm workspace 的典型问题catalog:协议见 package.json 中的pierre/diffs: catalog:只在 workspace 内部有效直接发布会让外部npm install artifacts-viewer因无法解析catalog:而失败。此版在发布产物中将其解析为具体版本范围依赖项只保留一个pierre/diffsreact与react-dom声明为 peer 依赖^18.2.0 || ^19.0.0。0.0.5 —— renderStatus可插拔的状态渲染最新版本 0.0.5 引入了renderStatus——一个部分插槽映射partial slot map用于替换ArtifactRepoViewer、ArtifactFileTree、ArtifactDirectoryView、ArtifactFileView上的默认加载、空与错误标记。判别联合上下文与三个渲染器每个渲染器接收一个判别联合ArtifactStatusContext同一个函数可以按面板分别响应type ArtifactStatusContext | { scope: repository; repoName: string } | { scope: tree; repoName: string; path: string } | { scope: file; repoName: string; path: string; name: string }; type ArtifactEmptyKind empty | binary | oversized; type ArtifactStatusRenderers { loading?: (context: ArtifactStatusContext) ReactNode; empty?: (context: ArtifactStatusContext, kind?: ArtifactEmptyKind) ReactNode; error?: (context: ArtifactStatusContext, error: ArtifactsClientError) ReactNode; };kind只在文件上有值——仓库或目录的身份已由context.scope表达。这同时也是本地化文案的入口默认每个面板渲染英文pLoading repository…、This directory is empty.、Binary file (12.4 KiB).等renderStatus替换这些标记即完成 i18nArtifactRepoViewer client{client} repoNamewebsite renderStatus{{ loading: (context) Spinner label{context.scope} /, empty: (context, kind) Notice kind{kind} scope{context.scope} /, error: (context, error) Notice tonedanger{error.message}/Notice, }} /实现上status.tsx有三个值得记住的行为映射是部分的渲染器返回undefined包括你根本没命名它时保留默认标记返回null则什么都不渲染。插槽语义存活自定义输出仍被包裹在对应插槽元素中data-artifacts-viewer-slot、aria-busy、rolealert、data-kind依旧存在并可被选择器命中、被屏幕阅读器播报无需重复编写。可组合renderStatus同时被四个组件接受自己拼装这些组件时同样生效。代码视图刻意不在renderStatus覆盖范围内它等待的是高亮器而非网络且已有renderCodeFallback负责那个占位场景。请求流从两次往返到永久缓存把 CHANGELOG 的版本脉络与 README.md 的Request flow一节结合可以看到渲染一个仓库的完整数据流browser your server Cloudflare ┌──────────────────┐ ┌──────────────────────┐ ┌──────────────┐ │ArtifactRepoViewer│ │ routeArtifactRequest │ │ Artifacts │ │ ↓ │─────▶│ · validates │─────▶│ REST API │ │ ArtifactsClient │ │ · adds API token │ │ │ └──────────────────┘ │ · optional cache │ └──────────────┘ GET /artifacts/… └──────────────────────┘ Bearer token渲染一个仓库先花两次往返随后全部进入内容寻址模式getLog({ limit: 1 }) → commits[0].treeHash (ref 省略 默认分支) readTree(commit.treeHash) → 根目录条目此后每次导航都由 git 哈希寻址——目录用readTree(entry.hash)、文件用readBlob(entry.hash)——响应不可变可以永久缓存。这也是 router.ts 中步骤顺序承重的原因beforeRequest授权钩子在缓存查询之前执行缓存命中永远不可能绕过访问控制。授权、响应行为与 CORS授权beforeRequest接收{ request, read, operation }其中read是已完整校验的判别联合repoName、hash、ref、path可直接用于策略决策返回Response即短路拒绝。注意 README 有明确警告路由器默认放行所有请求暴露端点前必须自行加beforeRequest策略否则任何能触达该端点的人都能读取命名空间下任意合法仓库名。响应行为挂载点外 →null挂载点内未知路由 → 404已知路由错误方法 → 405 带Allow头参数畸形 → 400且不上游发送任何内容。CORS不处理由调用方在调用后自行添加响应头OPTIONS会返回 405委托前应先拦截预检if (request.method OPTIONS) return myPreflight(request);。挂载到 Worker 的完整示例// worker/index.ts import { routeArtifactRequest } from artifacts-viewer; import { createCacheApiAdapter } from artifacts-viewer/server/cache; export default { async fetch(request, env, ctx) { const handled await routeArtifactRequest(request, { accountId: env.ARTIFACTS_ACCOUNT_ID, namespace: env.ARTIFACTS_NAMESPACE, apiToken: env.ARTIFACTS_API_TOKEN, beforeRequest: async ({ request, read }) { const user await getSessionUser(request); if (user null || !user.repositories.includes(read.repoName)) { return new Response(Forbidden, { status: 403 }); } }, cache: createCacheApiAdapter({ cache: caches.default, baseUrl: new URL(request.url).origin, }), waitUntil: (promise) { ctx.waitUntil(promise); }, }); return handled ?? new Response(Not found, { status: 404 }); }, } satisfies ExportedHandlerEnv;ArtifactRouterOptions完整选项表选项类型说明accountIdstring必填namespacestring必填apiTokenstring必填需具备 Artifacts 读权限的 Cloudflare API tokenapiPathstring默认/artifacts段边界匹配fetchtypeof fetch可选注入点用于测试与追踪beforeRequestArtifactBeforeRequestHook授权钩子返回Response即拒绝cacheArtifactsCacheAdapter仅对内容寻址读取生效waitUntil(p: Promiseunknown) void让缓存写入在响应结束后继续存活onCacheError(error: unknown) void缓存失败在此上报绝不抛出waitUntil的存在有明确的实现理由如果同步等待缓存写入大 body 会死锁——clone在原响应被消费前无法排空而原响应要等函数返回后才被消费。因此写入交给ctx.waitUntil保持存活。若 Worker 同时托管静态资源需在wrangler.jsonc中让 API 先于资源处理器命中// wrangler.jsonc { assets: { not_found_handling: single-page-application, run_worker_first: [/artifacts/*], }, }客户端与 hooks客户端实例应在模块作用域创建并复用——hooks 把client当作依赖每次渲染新建实例会导致无限重新请求import { createArtifactsClient } from artifacts-viewer/client; import { ArtifactRepoViewer } from artifacts-viewer/react; import artifacts-viewer/styles.css; const client createArtifactsClient(); export function Repository() { return ArtifactRepoViewer client{client} repoNamemy-repository /; }React hooks 返回判别状态联合没有isLoading布尔值type ArtifactQueryStateT | { status: idle } | { status: loading } | { status: success; data: T } | { status: error; error: ArtifactsClientError };Hook返回useArtifactRepository(client, repoName)ArtifactsRepositoryuseArtifactLog(client, { repoName, ref?, limit?, offset? })ArtifactsCommitMetadata[]useArtifactHeadCommit(client, repoName, ref?)ArtifactsCommitMetadata \| nulluseArtifactTree(client, repoName, treeHash \| null)ArtifactsTreeEntry[]useArtifactBlob(client, { repoName, name, hash, maxInlineBytes? })ArtifactBlobRenderuseArtifactQuery(run, deps)任意值其余 hooks 的基元hooks 层没有缓存、没有请求去重依赖变化或组件卸载即通过AbortSignal取消。缓存属于你自己的数据层——传入一个查缓存的fetch或包装 client。useArtifactHeadCommit对空仓库解析为null且 README 特别提醒不要用lastPushAt判断空仓库因为 Artifacts API 在该字段上始终返回null。useArtifactBlob产生渲染分类type ArtifactBlobRender | { kind: empty } | { kind: text; contents: string } | { kind: image; contentType: string } | { kind: binary; sizeBytes: number } | { kind: oversized };组件完全可组合hooks 全部公开可以整体替换标记层ArtifactRepoViewer内部持有当前选中状态。README 给出了最小自建树组件的例子用useArtifactTree渲染一个ul。ArtifactRepoViewer的 props 中有一个易踩的命名细节prop 叫gitRef而不是ref因为 React 保留了ref。样式、语法高亮与行为限制结构性样式与选择器钩子artifacts-viewer/styles.css只做结构不做主题主布局值全部暴露为自定义属性如--artifacts-viewer-sidebar-width默认16rem、--artifacts-viewer-pane-height默认none、--artifacts-viewer-mono-font默认monospace等选择器刻意使用:where()保持低优先级普通应用规则无需!important即可覆盖。公开插槽与部件携带稳定属性data-artifacts-viewer-slotroot、toolbar、sidebar、tree、treeItem、content、directory、directoryItem、file、loading、empty、error与data-artifacts-viewer-partheader、name、icon、actions、raw、download、code、code-pending、code-fallback、code-highlight、image。状态属性方面data-selected是裸属性bare attribute选择器应写[data-selected]而非[data-selectedtrue]。布局由容器查询驱动两个面板在根元素自身宽度小于40rem时折叠为单列而不是以视口宽度为准。语法高亮与预加载文本文件经pierre/diffs包装 Shiki渲染通过动态import()加载不会进入首屏 bundleArtifactRepoViewer挂载时即主动开始拉取该 chunk。高亮未就绪前绝不展示未高亮文本——占位与文件共享同一网格单元不会发生布局跳动。三个状态依次为PreparingrenderCodeFallback或默认加载文案data-artifacts-viewer-partcode-pending→ Ready高亮文件code-highlight→ Unavailable纯pre文本code-fallback仅在预加载报告高亮不可初始化时可达。renderCodeFallback是渲染 prop接收{ name, contents }contents是解码后的文件内容因此骨架屏可以按真实行数定高。preloadCodeView是函数而非 prop预热懒 chunk、共享 Shiki 引擎、主题以及给定文件名时该文件的语法ArtifactRepoViewer挂载时已调用它你还可以更早调用——路由进入时或行悬停时li onPointerEnter{() void preloadCodeView({ theme, name: entry.name })}它按主题与语法集合记忆化重复调用零成本返回booleanfalse表示高亮不可用即上面的纯文本态可达。主题必须通过选项传入因为pierre/diffs渲染进开放的 Shadow DOM普通 CSS 无法触达内部ArtifactRepoViewer client{client} repoNamemy-repository pierreDiffsOptions{{ theme: { light: github-light, dark: vesper }, themeType: system, }} /theme接受 Shiki 主题名或{ light, dark }对themeType为system默认/light/darkunsafeCSS可注入 Shadow DOM 原始 CSS但跨 Pierre 版本不稳定。选项对象需保持引用稳定或 memoize避免代码视图反复重渲染。行为限制Limits and behaviour大文件maxInlineBytes默认 512 KiB。响应声明的Content-Length更大则 body 永不下载否则流式读取并在越过上限的瞬间取消。无论哪种路径状态都变为oversizedRaw/Download 链接仍可用。图片按扩展名识别apng、avif、bmp、gif、ico、jfif、jpeg、jpg、png、svg、webp永不经过 client 下载直接以img src从 raw URL 渲染SVG 保持在图片语境绝不内联。文本 vs 二进制用严格 UTF-8 解码加首 8 KiB NUL 字节扫描判定而非扩展名列表判定失败的归为binary绝不进入高亮器。Raw/Download URL固定到提交哈希而非分支名即使会话中有人 push链接依然可解析且可缓存。树展开按路径键控而非树哈希两条路径下的相同子树可独立展开。可访问性侧边栏是嵌套 disclosure 按钮的nav而非roletree——完整 WAI-ARIA 树键盘导航未实现宣称该角色反而更糟行是真按钮或提供buildHref时是真锚点。明确不在范围内CHANGELOG 之外的 README 也划清了边界Markdown 渲染.md目前以高亮纯文本显示、diff 查看与提交历史 UI、分支切换Artifacts REST API 无 ref 列举操作枚举分支需要 Git protocol v2ls-refs只能向gitRef传已知分支或省略取默认分支、以及任何写入操作均不在当前范围内。从版本演进看设计主线把五个版本的 CHANGELOG 连起来读可以清晰看到 artifacts-viewer 的三条设计主线也方便你在自己的项目中复用同样的判断最小代理面只暴露七种只读操作写入与凭据端点绝不代理入站请求头全部丢弃、出站头从零构建、响应头白名单转发token 只存在于 upstream.ts 一个模块。把不可变当缓存依据只缓存内容寻址读取并标记一年不可变全模块零 TTL、零陈旧窗口授权钩子永远先于缓存执行。渐进式补全前端0.0.1 先立服务端与缓存0.0.3 才补 client 与 React 表面0.0.5 再开放状态插槽——每一版都解决上一版暴露的真实问题binding 空载荷、catalog 协议无法外部安装、默认状态无法本地化。如果你正要把 Cloudflare Artifacts 的仓库浏览能力集成进自己的产品例如像 vibesdk 这类以 Cloudflare 全栈为基础的应用可以直接复用 apps/example 作为参考实现安装artifacts-viewernpm install artifacts-viewerreact/react-dom需^18.2.0 || ^19.0.0按上文挂载路由、渲染组件并将apiPath在客户端与路由器两端保持一致。包目前处于 1.0 之前README 建议锁定精确版本号使用。【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考