快速入门

本指南覆盖 Rotifer 的前三层首次体验：先初始化项目，再通过 rotifer hello 跑通一个预设 Agent，最后把你自己的代码包装成 Gene，并组合成自定义 Agent。

前提条件

Node.js >= 20.0.0
npm >= 9
（可选）Rust 工具链 — 仅在使用 NAPI 桥接进行 Native WASM 编译时需要

rotifer compile 自动将 TypeScript 基因编译为 Native WASM（通过 IR 编译器）。无需额外的 Rust/WASM 工具链！

安装

npm install -g @rotifer/playground

或通过 npx 直接使用：

npx @rotifer/playground init my-project
cd my-project
npx @rotifer/playground hello

中国大陆用户安装说明

出于供应链安全考虑，Rotifer 官方仅推荐使用 npm 官方源：

npm install -g @rotifer/playground --registry=https://registry.npmjs.org

如果网络较慢：

优先重试官方源，而不是切换到第三方镜像
可直接使用 npx @rotifer/playground init my-project 初始化，再执行 npx @rotifer/playground hello，减少全局安装步骤
如需配置企业代理，请确保其上游仍指向 registry.npmjs.org

说明： 当前不再推荐将 cnpm 或 npmmirror 作为默认安装路径，因为这会引入额外的供应链信任方。

第 1 步：初始化项目

rotifer init my-project
cd my-project

项目将包含五个 Genesis 基因，已在活跃的 Arena 中预排名：

my-project/
├── rotifer.json
├── genes/
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── playground.db

第 2 步：运行第一个预设 Agent

rotifer hello --list-templates
rotifer hello
rotifer agent list

rotifer hello 是当前最快的上手路径。它直接复用 rotifer init 已安装的基因，从精选模板中创建并运行一个 hello-* Agent。

Quick Start 模板零配置即可运行；Power 模板可能需要 API Key 或特定领域环境。

第 3 步：创建你的第一个 Gene

如果你想开始构建自己的能力单元，可以先把一个简单函数包装成 Gene：

mkdir -p genes/hello-world

编写 genes/hello-world/index.ts：

interface Input { name: string; }
interface Output { greeting: string; }

export async function express(input: Input): Promise<Output> {
  return {
    greeting: `你好，${input.name}！欢迎来到 Rotifer Protocol。`,
  };
}

包装它：

rotifer wrap hello-world

这将生成 phenotype.json — 基因的元数据，描述其领域、模式和保真度。

第 4 步：在沙箱中测试

rotifer test hello-world
rotifer test hello-world --compliance

测试运行器执行基因——已编译基因通过 WASM 沙箱运行（带燃料计量和 L0 门控检查）；未编译基因回退到 Node.js import() 并提示警告。它从 schema 生成输入、验证输出、并验证 IR 完整性。添加 --compliance 可运行结构性合规检查。

如果你处理的是已有目录而不是手写一个新 Gene，先运行 rotifer scan genes/ 发现可包装的导出函数，通常是最快的路径。

第 5 步：编译为 Rotifer IR

rotifer compile hello-world

如果基因目录中有 index.ts 或 index.js 文件且没有预编译的 gene.wasm，编译器会自动运行：

index.ts → esbuild（类型剥离）→ IR 编译器（QuickJS→WASM）→ Rotifer IR（自定义段注入）

你也可以直接提供预编译的 WASM：

rotifer compile hello-world --wasm path/to/hello.wasm

IR 编译器会将 Rotifer 自定义段（版本、表型、约束、计量）注入 WASM 二进制。

第 6 步：提交到 Arena

rotifer arena submit hello-world

Arena 运行准入评估：测试基因，计算适应度 F(g) 和安全分 V(g)，两者通过阈值后注册。

第 7 步：查看排名

rotifer arena list

按领域过滤：

rotifer arena list --domain search

第 8 步：创建自定义 Agent

Agent 组装一个基因组 — 从 Arena 中选择基因的组合。

rotifer agent create greeter-bot --genes hello-world genesis-code-format

或从某个领域自动选择排名靠前的基因：

rotifer agent create search-agent --domain search --top 2

第 9 步：运行自定义 Agent

执行基因组作为顺序管道——每个基因的输出作为下一个基因的输入：

rotifer agent run greeter-bot --input '{"name":"World"}'

使用 --verbose 查看每步的中间输入和输出。

中国大陆网络说明

Rotifer 的 Cloud 功能（rotifer login、rotifer publish、rotifer arena --cloud）依赖 Supabase API。由于 Supabase 服务器位于海外，中国大陆用户可能遇到：

连接超时：API 请求延迟较高（200-800ms），偶尔超时
GitHub OAuth 缓慢：rotifer login 需要访问 GitHub，可能需要稍等
基因上传/下载较慢：大体积基因（>1MB）的上传下载可能需要更长时间

临时解决方案：

CLI 已内置请求重试机制，超时后会自动重试
本地功能（init、scan、wrap、compile、test、arena submit）完全离线可用，不受网络影响
如有稳定的代理网络环境，配置 HTTPS_PROXY 环境变量即可：
Terminal window
```
export HTTPS_PROXY=http://127.0.0.1:7890
```

长期计划：rotifer.cloud 将提供中国大陆优化的 API 端点，届时延迟问题将彻底解决。

第 10 步：通过 Cloud 共享

使用 GitHub 登录，发布你的基因，让其他创作者安装使用：

rotifer login                    # GitHub OAuth（自动打开浏览器）
rotifer publish hello-world      # 上传到云端注册表
rotifer search                   # 浏览所有已发布的基因
rotifer install <gene-ref>        # 安装其他人的基因

提交到 Cloud Arena 进行全球竞争：

rotifer arena submit hello-world --cloud   # 提交到云端 Arena
rotifer arena list --cloud                 # 查看全球排名
rotifer arena watch search --cloud         # 实时排名更新

完成后退出登录：

rotifer logout

下一步

尝试更多预设 Agent — 运行 rotifer hello --list-templates，探索 Quick Start / Power 模板
编写 Native 基因 — 用 TypeScript 编写，rotifer compile 自动编译为 WASM——或用 Rust 手动优化 WASM
通过 Cloud 共享 — rotifer publish 共享基因，rotifer install 使用他人的基因
探索组合 — Seq、Par、Cond、Try、Transform 操作符（参见 templates/composition/）
迁移 MCP Tool — 参见 examples/mcp-migration/ 了解迁移前后的对比
阅读规范 — 协议规约