@haivex/sdk

本地 agent 发布到 Cloudflare R2 + Agent Registry 的共享脚本库。

各 agent(computer-agent / browser-agent / host-agent / mobile-agent / 未来新加的)的 scripts/publish.ts 只声明自家差异(build 命令 + externalDeps + bundleEntry),其余 90% 的逻辑(manifest bump / stage / R2 上传 / artifact 登记 / CLI 解析)全在这个包里。

各 agent 接入(模板)

packages/<your-agent>/scripts/publish.ts:

import { publishAgentToR2 } from '@haivex/sdk'
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { execSync } from 'node:child_process'

const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), '..')

execSync('bun scripts/build.ts', { stdio: 'inherit', cwd: rootDir })

await publishAgentToR2({
  rootDir,
  bundleEntry: 'dist/desktop.js',
  externalDeps: ['<你的 native deps>', ...],
})

packages/<your-agent>/package.json 加 dep:

"dependencies": {
  "@haivex/sdk": "workspace:*"
}

packages/<your-agent>/.env:

R2_ACCOUNT_ID=...
R2_BUCKET=haivex-desktop
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_PUBLIC_BASE_URL=https://download.haivex.ai

最省事:cp packages/haivex-desktop/.env packages/<your-agent>/.env(R2 凭据全公司共享一套)。

用法 / CLI

cd packages/<your-agent>
bun scripts/publish.ts                                     # 默认 darwin-arm64,自动 build
bun scripts/publish.ts --platforms=darwin-arm64,darwin-x64
bun scripts/publish.ts --registry=http://localhost:50090   # 切到本地 platform 测试

流程

1. loadAgentEnv()       读 .env,5 个 R2_* fail-fast
2. bumpManifestPatch()  manifest.json patch +1 写回(防止漏改 version)
3. POST /agents/:id/publish  注册 manifest + 创建 version row
4. for each platform:
     a. stagePlatform()   stage dir + bun install --production(拉平台 prebuilts)+ tar.gz
     b. uploadToR2()      R2 直传(流式 + 分片 + 进度条)
     c. POST /agents/:id/artifact  登记 downloadUrl / fileName / fileSize 到 agentVersions.artifacts jsonb
     d. cleanupStage()    清 stage dir

agent-platform 完全不接收 binary,客户端 fetch downloadUrl 直接走 R2 / CDN。

R2 桶分区(haivex-desktop bucket)

bucket 名是历史遗留(早期只放 haivex 客户端 .dmg 时建的),现在是全公司发版产物的统一桶,通过 key prefix 严格分区:

| Key prefix | 用途 | 谁写入 | |---|---|---| | client/<version>/<fileName> | haivex-desktop 客户端安装包(.dmg / .exe / .AppImage) | packages/haivex-desktop/scripts/publish.ts | | agent/<id>/<version>/<id>-<platform>.tar.gz | 本地 agent 发布包(computer-agent / browser-agent / host-agent / ...) | 本包(agentObjectKey()) |

外部下载用自定义域名 https://download.haivex.ai/<key>,bucket 名永远不暴露:

• https://download.haivex.ai/client/1.0.5/Haivex-1.0.5-arm64.dmg
• https://download.haivex.ai/agent/computer-agent/12.0.5/computer-agent-darwin-arm64.tar.gz

新增 prefix 规则(以后加新类资源时):

• 用 <resource-type>/<id?>/<version>/<fileName> 三/四级结构,方便 dashboard 按 prefix 浏览
• prefix 用单数 + 短词(agent / client / dataset),不用复数 / 复合词
• 把新 prefix 写进本表 — 别让别人维护时还要翻 git log 才知道 prefix 含义

公开 API

publishAgentToR2(opts: {
  rootDir: string             // agent 包根
  bundleEntry: string         // 相对 rootDir,如 'dist/desktop.js'
  externalDeps: string[]      // 跟 build.ts EXTERNALS 一致
  platforms?: string[]        // 默认 --platforms CLI / ['darwin-arm64']
  registry?: string           // 默认 --registry CLI / 线上 platform
})

底层模块也都 export 出去(stage / r2 / manifest / env),特殊场景(只想上传不想 bump、自定义 CLI)直接拼装。

不在本包做的事

• build:各 agent 的 scripts/build.ts 不同(EXTERNAL list / 入口 / Bun.build 配置),保留在 agent 自己包里
• codesign / 签名:JS bundle 模式不签名(继承 Haivex.app 的 TCC responsibility,见 a-haivex/CLAUDE.md "Agent 本地分发架构")
• haivex-desktop 客户端发版(出 .dmg/.exe):不在本包,见 packages/haivex-desktop/scripts/publish.ts

桶 / 凭据修改

如果需要换 R2 桶或换账号 —— 不要在各 agent 改 .env,统一改:

1. R2 dashboard 操作(新建桶 / 重绑域名 / 更新 token)
2. 把新凭据 broadcast 到所有 agent 的 .env
3. 如果改了 prefix 规则,在 src/r2.ts 的 agentObjectKey() 改 + 更新本 README 的分区表

不在 .env 之外硬编码任何 R2 字段(包括 bucket / endpoint / publicBaseUrl),保证一处改全公司生效。