快速入门

本指南将带你走完完整的 Rotifer 基因生命周期——从项目初始化到运行多基因 Agent 管道。

前提条件

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

v0.3 新功能： rotifer compile 现在自动将 TypeScript 基因编译为 Native WASM（通过 Javy）。无需额外的 Rust/WASM 工具链！

安装

npm install -g @rotifer/playground

或通过 npx 直接使用：

npx @rotifer/playground init my-project

第 1 步：初始化项目

rotifer init my-project
cd my-project

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

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

第 2 步：扫描候选函数

rotifer scan genes/

扫描器检测已导出的函数并报告其与基因标准的兼容性。

第 3 步：将函数包装为基因

创建一个简单函数：

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 步：在 L2 沙箱中测试

rotifer test hello-world

测试运行器会动态导入 express()，从 schema 生成输入，验证输出，并在存在编译后的 WASM 时验证 IR 完整性。

第 5 步：编译为 Rotifer IR

rotifer compile hello-world

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

index.ts → esbuild（类型剥离）→ Javy（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 查看每步的中间输入和输出。

第 10 步：通过 Cloud 共享 (v0.4)

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

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

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

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

完成后退出登录：

rotifer logout

下一步

编写 Native 基因 — 用 TypeScript 编写，rotifer compile 自动通过 Javy 编译为 WASM——或用 Rust 手动优化 WASM
通过 Cloud 共享 — rotifer publish 共享基因，rotifer install 使用他人的基因
探索组合 — Seq、Par、Cond、Try、Transform 操作符（参见 templates/composition/）
迁移 MCP Tool — 参见 examples/mcp-migration/ 了解迁移前后的对比
阅读规范 — 协议规约 v2.9