如何搭建你自己的OCX扩展注册表：从registry.jsonc到Cloudflare Workers免费部署-平芜编程栈

CLI
开发工具
AI 应用

【免费下载链接】ocx

OpenCode extension manager with portable, isolated profiles. Your setup, anywhere.

项目地址：https://gitcode.com/gh_mirrors/ocx/ocx

OCX 是 OpenCode 的扩展管理器，通过注册表（Registry）分发 skill、agent、plugin 等 AI 组件。本教程带你从一份registry.jsonc清单出发，搭建属于自己的 OCX 扩展注册表，并免费部署到 Cloudflare Workers——让任何人都能用一条ocx add命令安装你的组件。

▲ OCX 快速上手：从注册表安装组件、启动 OpenCode 的完整体验

为什么自己搭一个OCX注册表？

场景	收益
🏢 团队内部分发	把团队沉淀的 skill、agent、command 打包给同事一键安装
🌟 个人组件库	发布品牌化 AI 扩展，沉淀自己的"最佳实践"
💰 零成本	注册表本质是静态 JSON + 文件，Cloudflare Workers 免费额度即可托管
🔒 安全可控	组件经 SHA-256 校验后拷贝到项目的`.opencode/`目录，代码完全归你所有，可自由定制

官方将这种模式概括为Cargo + ShadCN 模型：注册表负责身份与分发，组件以干净的文件名拷入项目，而不是藏在node_modules里。完整背景见 docs/registries/create.mdx。

准备工作：3 分钟完成环境配置

开始前只需准备好 3 样东西：

工具	用途	安装方式
OCX CLI	脚手架 + 构建 + 安装组件	`npm install -g ocx`
Bun	运行构建脚本的运行时	官方安装脚本（OCX 的 npm 包依赖 Bun）
Cloudflare 账号	免费托管静态资源	浏览器注册即可

提示：OCX 支持 macOS、Linux 和 Windows，跨平台体验一致。

注册表的目录结构一览

一个最小可用的注册表项目长这样：

my-registry/ ├── registry.jsonc # 注册表清单（核心文件） ├── files/ # 组件源文件 │ ├── agents/ # AI 角色定义 │ ├── skills/ # 技能模块 │ ├── plugins/ # TypeScript 插件 │ └── commands/ # 自定义命令 ├── dist/ # 构建产物（ocx build 自动生成） └── wrangler.jsonc # Cloudflare Workers 配置

有两种最快的创建方式：

方式一：OCX 脚手架（推荐）

ocx init --registry ./my-registry --namespace my-org --author "你的名字"

方式二：使用仓库内置的 Starter 模板

git clone https://gitcode.com/gh_mirrors/ocx/ocx # 将 ocx/examples/registry-starter/ 复制到你的工作目录即可

Starter 模板已经预置了构建脚本和多平台部署配置，结构可参考 examples/registry-starter/。

读懂核心文件 registry.jsonc

registry.jsonc是整个注册表的"户口档案"。下面是最小可用示例：

{ "$schema": "https://ocx.kdco.dev/schemas/v2/registry.json", "name": "My Registry", "version": "0.0.1", "author": "你的名字", "components": [ { "name": "hello-world", "type": "skill", "description": "An example skill to get you started", "files": ["skills/hello-world/SKILL.md"] } ] }

关键字段速查：

$schema：声明 v2 规范，开启 IDE 自动补全与校验，完整定义见 docs/schemas/registry.schema.json
components[]：组件列表，每项必须包含name、type、description、files
files：支持字符串简写（目标路径自动推断）或对象形式（path+target）

Starter 模板中的完整清单可参考 examples/registry-starter/registry.jsonc。

7 种组件类型

类型	用途	文件格式
`skill`	AI 行为指令（知识模块）	Markdown
`agent`	AI 角色定义	Markdown
`plugin`	扩展 OpenCode 功能	TypeScript
`command`	自定义 TUI 命令	Markdown
`tool`	自定义工具实现	TypeScript
`bundle`	多个组件的集合包	JSON
`profile`	可分享的完整配置	JSON

添加你的第一个组件

以最简单的skill为例，只需两步：

第 1 步：创建files/skills/my-skill/SKILL.md，写清楚"何时使用"和"具体指令"。仓库里有一个可直接参考的示例 examples/registry-starter/files/skills/hello-world/SKILL.md。

第 2 步：在registry.jsonc的components数组中注册它：

{ "name": "my-skill", "type": "skill", "description": "我的第一个技能", "files": ["skills/my-skill/SKILL.md"] }

⚠️ 命名规则：组件名只能用小写字母、数字和连字符（如code-review），最长 64 个字符。

构建与本地验证：ocx build 生成 dist 目录

构建命令就一行：

bun run build # 等价于 bunx ocx build . --out dist

examples/registry-starter/package.json 中已预置好该脚本。构建过程会自动完成 4 件事：

校验registry.jsonc是否符合 schema
生成dist/index.json（注册表索引）和每个组件的packument元数据
把组件文件拷贝到dist/components/
生成可选的发现端点dist/.well-known/ocx.json

构建完成后，可以先在本地起服务预览：

bun run dev # 启动 http://localhost:8787

此时你的本地服务需要暴露 3 个标准端点（详见 docs/registries/protocol.mdx）：

端点	作用
`/index.json`	注册表索引，OCX 安装时首先请求它
`/components/{name}.json`	单个组件的完整元数据
`/components/{name}/{path}`	组件文件原文

免费部署到 Cloudflare Workers

关键配置只有两行。wrangler.jsonc告诉 Cloudflare："把dist/目录作为静态资源发布"：

{ "name": "my-registry", "compatibility_date": "2025-01-01", "assets": { "directory": "./dist" } }

参考 examples/registry-starter/wrangler.jsonc。然后执行：

bun run deploy # 等价于 ocx build + wrangler deploy

部署成功后，你会得到一个形如https://my-registry.<你的子域名>.workers.dev的 URL。Cloudflare Workers 免费层每月提供大量请求额度，个人注册表绰绰有余——全程零费用。

验证上线：一条命令安装你的组件

把 URL 发给朋友，对方只需：

# 方式一：临时访问（不写入配置） ocx add hello-world --from https://my-registry.xxx.workers.dev # 方式二：永久注册注册表（推荐，起个别名即可） ocx registry add https://my-registry.xxx.workers.dev --name myreg ocx add myreg/hello-world

命令细节可查 docs/cli/registry.mdx 和 docs/cli/add.mdx。

▲ 注册表配置完成后，ocx add 别名/组件名即可一键安装

进阶：通过注册表分享 profile 配置

profile类型的组件最强大：它把ocx.jsonc、opencode.jsonc和指令文件打包成一个可分享的配置方案，安装到~/.config/opencode/profiles/<name>/。接收方只需：

ocx profile add my-profile --source myreg/my-profile --global

▲ OCX 支持多 profile 隔离配置，你的注册表可以分发整套 profile

其他免费托管方案

Cloudflare Workers 并非唯一选择，Starter 模板已内置多平台配置：

平台	配置方式
Vercel	预置 examples/registry-starter/vercel.json，连接仓库自动构建
Netlify	预置 examples/registry-starter/netlify.toml
GitHub Pages	构建后直接发布`dist/`目录
任意 HTTP 服务器	把`dist/`当作纯静态目录部署