Rotifer Playground

Rotifer Protocol 的开发环境——构建基因、运行 Arena 竞争、通过 Cloud 共享、模拟代理进化。

状态： v0.8.5——面向基因开发、Arena 竞争和协议实验的公开 Playground。本次公开版本线将已落地的 v0.8.x 能力收口为同一版本口径。详细版本历史请参见 CHANGELOG.md。P2P 实现与 L4 集体免疫仍在规划中——详见下方实现状态。

安装

npm install -g @rotifer/playground

或通过 npx 直接使用：

npx @rotifer/playground init my-project

环境要求： Node.js >= 20.0.0

几秒钟跑通第一个 Agent

rotifer init my-project && cd my-project
rotifer hello --list-templates
rotifer hello

rotifer init 先把本地 Arena 和 Genesis genes 建起来；rotifer hello 则是预设 agent 的主入口：从精选模板里挑一个，立刻创建并运行。

30 秒演示

$ rotifer init my-project

  Rotifer Protocol - Project Initialization
  ───────────────────────────────────────────
✓ Project scaffolding created
ℹ Installing Genesis genes...
✓ 5 Genesis genes installed

  Arena Rankings
  ────────────────
  #   Name                        Domain        F(g)    Fidelity
  ────────────────────────────────────────────────────────────────
  1   genesis-web-search          search        0.87    Native
  2   genesis-code-format         tooling       0.81    Native
  3   genesis-l0-constraint       safety        0.79    Native
  4   genesis-web-search-lite     search        0.77    Native
  5   genesis-file-read           filesystem    0.74    Native
  6   hello-world                 general       0.57    Wrapped

ℹ 6 genes across 5 domain(s) — Arena is alive!
✓ Project ready: my-project

一条命令先把 Arena 跑起来；rotifer hello 再把这些内置基因收口成你的第一个预设 agent。

三幕体验 (ADR-11)

第一幕——Wow（30 秒）

rotifer init my-project && cd my-project

你将看到一个包含 6 个基因的 Arena，按适应度排名。无需任何配置。

第二幕——Aha（5 分钟）

rotifer hello --list-templates     # 查看 Quick Start / Power 模板
rotifer hello                      # 交互式选择模板并立即运行
rotifer agent list                 # 查看生成的 hello-* agent

内置基因在几秒内就能组合成一个可运行的预设 agent。

第三幕——Hooked（30 分钟）

把自己的代码变成基因，再组合成自定义 Agent：

# 先把现有代码包装成基因
rotifer scan genes/                    # 发现候选基因函数
rotifer wrap hello-world               # 包装为基因（生成 Phenotype）
rotifer test hello-world               # 在 L2 沙箱中运行测试（已编译基因走 WASM 沙箱）
rotifer test hello-world --compliance  # 运行结构性合规检查
rotifer arena submit hello-world       # 提交到 Arena（准入评估）
rotifer arena list                     # 查看你的基因排名

# 再用 TypeScript 写一个新基因——同一语言，零学习成本
mkdir genes/my-search && cat > genes/my-search/index.ts << 'EOF'
export function express(input: { query: string }) {
  return { results: [`Found: ${input.query}`], total: 1 };
}
EOF

rotifer wrap my-search --domain search
rotifer compile my-search           # TS → JS → WASM (Javy) → Rotifer IR
rotifer arena submit my-search      # 观察它攀升排名
rotifer arena list --domain search # 与 Genesis 基因对比

# 创建一个拥有基因组的 Agent（支持 Seq, Par, Cond, Try）
rotifer agent create search-bot --genes genesis-web-search my-search
rotifer agent create parallel-bot --genes web-search doc-search --composition Par
rotifer agent list

# 运行 Agent——WASM 沙箱执行优先
rotifer agent run search-bot --input '{"query":"rotifer protocol"}'
rotifer agent run search-bot --no-sandbox  # 强制 Node.js 回退

说明： rotifer compile 自动检测 TypeScript 基因，通过 Javy（QuickJS→WASM）编译为原生 WASM，无需额外工具链。

架构

playground/
├── crates/
│   ├── rotifer-core/        Rust: 类型、沙箱、Arena、代数、适应度、存储
│   └── rotifer-napi/        napi-rs 桥接: Rust ↔ Node.js FFI
├── src/                     TypeScript CLI 与支撑模块
│   ├── commands/            CLI 命令模块
│   ├── cloud/               Cloud Binding 客户端（auth、API、types）
│   └── utils/               配置、显示、NAPI 绑定、IR 编译器
├── genes/                   随仓库提供的 gene 目录
├── supabase/                Cloud Binding 自托管指南
├── templates/               基因 + 组合脚手架模板
└── tests/                   单元测试 + E2E 测试

分层

| 层 | 技术栈 | 职责 | |----|--------|------| | CLI | TypeScript + commander.js | 用户界面、命令路由、显示 | | Bridge | napi-rs (cdylib) | Rust 到 Node.js 的 FFI 绑定 | | Core | Rust + wasmtime | WASM 沙箱（Direct + WASI）、Arena 引擎、Algebra 执行器、Fitness 计算、SQLite 存储 |

CLI 命令

运行 rotifer --help 查看按模块分组的命令列表。下面列出最常用的本地、Cloud、Arena 与 Agent 工作流命令：

| 命令 | 说明 | |------|------| | rotifer init [gene-name] | 初始化新的 Rotifer 基因项目 | | rotifer hello [--template <id>] | 在 Rotifer 项目内从精选模板创建并运行一个预设 agent | | rotifer scan [path] | 扫描候选基因和本地技能 | | rotifer wrap <gene-name> | 将函数或 SKILL.md 包装为基因 | | rotifer test [gene-name] | 在沙箱中测试基因 | | rotifer compile [gene-name] | 将基因编译为 Rotifer IR（WASM） | | rotifer run <gene-name> | 直接执行单个本地基因 | | rotifer list | 列出当前项目中的本地基因 | | rotifer login | 登录 Rotifer Cloud | | rotifer logout | 从 Rotifer Cloud 登出 | | rotifer publish [gene-name] | 将基因发布到 Rotifer Cloud | | rotifer search [query] | 在 Rotifer Cloud 中搜索基因 | | rotifer install <gene-ref> | 从 Rotifer Cloud 安装基因 | | rotifer info <gene-ref> | 查看基因详情（本地或 Cloud） | | rotifer stats <gene-ref> | 查看基因下载统计 | | rotifer compare [gene-refs...] | 按声誉与下载量对比 2-5 个基因 | | rotifer reputation [gene-ref] | 查看基因与创作者声誉分数 | | rotifer versions <owner> <gene-name> | 查看某个基因的版本链 | | rotifer arena submit <gene-name> | 将基因提交到 Arena 竞争 | | rotifer arena list | 列出 Arena 排名 | | rotifer arena watch <domain> | 实时观察 Arena 排名 | | rotifer agent create <agent-name> | 用基因组创建 Agent | | rotifer agent list | 列出全部 Agent | | rotifer agent run <agent-name> | 执行 Agent 的基因组管线 | | rotifer vg [path] | 对基因代码执行 V(g) 安全扫描 | | rotifer network | P2P 基因网络命令 | | rotifer self-update | 检查并升级 Rotifer 包 | | rotifer config | 管理全局 Rotifer 配置 | | rotifer whoami | 显示当前认证状态 |

Genesis 基因

每个新项目预装五个基因：

| 基因 | 领域 | 保真度 | 说明 | |------|------|--------|------| | genesis-web-search | search | Native | 完整的网络搜索，返回多个结果 | | genesis-web-search-lite | search | Native | 轻量级单结果搜索 | | genesis-file-read | filesystem | Native | 读取本地文件（L0 沙箱限制） | | genesis-code-format | tooling | Native | 格式化源代码（JSON、TS 等） | | genesis-l0-constraint | safety | Native | L0 沙箱约束检查器 |

基因组合（Algebra）

基因可以使用 Rotifer Algebra 进行组合：

| 操作符 | 说明 | 示例 | |--------|------|------| | Seq | 顺序管道 | 搜索 → 格式化 | | Par | 并行执行并合并 | Search + Search-Lite，取先返回者 | | Cond | 条件分支 | 若 query.length > 100 → Lite，否则 → Full | | Try | 容错 | 主基因 + 降级备选 | | Transform | 映射/转换 | 内部基因 → 映射基因 |

JSON 示例参见 templates/composition/。

示例

examples/ 目录包含参考实现和实验：

| 目录 | 说明 | |------|------| | examples/mcp-migration/ | 如何将 MCP Tool 迁移为 Rotifer Gene | | examples/api-apocalypse/ | API 容错实验——基线 Agent 与 Rotifer 域故障转移 Agent 的对比 |

开发

git clone https://github.com/rotifer-protocol/rotifer-playground.git
cd rotifer-playground

# TypeScript CLI
npm install
npm run build          # 构建到 dist/
npm test               # 运行 TypeScript 测试套件（Vitest）
npm run lint           # 对 src/ 做类型检查和 lint

# Rust Core（需要 Rust 工具链）
cargo check -p rotifer-core
cargo test -p rotifer-core

# 完整演示
bash demo.sh

实现状态

本项目处于 alpha 阶段。下表展示了当前各 URAA 层级的真实实现状态。

| URAA 层级 | 规范名称 | 完成度 | 已可用 | 规划中 | |-----------|---------|--------|--------|--------| | L0 | 内核层 | ~35% | L0Gate 预执行检查（域、资源、网络、文件系统）；审计日志 | 伦理边界、状态锚定、信任根 | | L1 | 合成层 | ~95% | WASM 沙箱（wasmtime）、IR 编译器、Javy TS→WASM、NAPI 桥接 | 完整 WASI 能力协商 | | L2 | 校准层 | ~40% | Schema 验证、沙箱测试、--compliance 检查 | 静态分析、受控试运行 | | L3 | 竞争与交换层 | ~60% | Arena 排名、F(g) 乘法模型、R(g) 声誉、Cloud Registry | P2P HLT 广播（仅 stub）、热加载、退役 | | L4 | 集体免疫层 | 0% | — | 威胁广播、紧急回滚、跨节点共识 | | 代数 | 组合代数 | ~90% | Rust 五算子全实现；CLI 支持 Seq/Par/Cond/Try | DataFlowGraph |

关键限制： L4 依赖 L3 的 P2P 网络（当前为 stub）。完整 L4 目标版本为 v0.9+。

协议合规性

目标规范：Rotifer Protocol Specification（Frozen）。详细层级覆盖请参见实现状态。

| 深度 | 组件 | 备注 | |------|------|------| | 完整 | Phenotype、AlgebraExpr、Fitness F(g)、Arena | 核心基因生命周期 | | 可用 | WASM Sandbox、L0 Gate、Reputation R(g) | L0 ~35%，持续扩展 | | 简化 | Agent Lifecycle、Gene Lifecycle、RotiferBinding | MVP 子集 | | 占位/规划 | P2P HLT、Formal Verification、Cross-Binding Consistency、ZK Proofs、L4 Immunity | 路线图条目 |

基于实现反馈的变更通过 ADR 流程提出。

路线图

详细发布历史请参见 CHANGELOG.md。接下来的里程碑：

• v0.9 — P2P 网络（元数据发现）、经济体系设计
• v1.0 — 稳定版：L0-L3 完整、经济体系上线、安全审计

社区

• Discord — 加入讨论
• GitHub Discussions — 问题与提案

参与贡献

开发指南请参见 CONTRIBUTING.md。

许可证

Apache-2.0 + Rotifer Safety Clause

本项目使用 Apache License 2.0，附加 Rotifer Safety Clause——要求任何部署必须保留 L0 约束层，或明确披露对其的修改。

轮虫协议，生生不息。