Rotifer Playground

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

状态： v0.26.x——基因现在能真正拒绝格式错误的输入，而不是崩溃或者答非所问地硬着头皮回答。发布一个基因会强制执行规范 §47.5 T1（ADR-333）：至少一条用例它必须正确处理、一条它必须拒绝——崩溃一律判失败，不崩溃的拒绝判通过，返回了答案的只有在声明了 expectedOutput/expectedSchema 且匹配时才判通过，返回答案却什么都没声明则判失败——外加 10 组生成输入，全部必须产出符合结构的输出。拒绝现在有了正规通道，不再靠猜：基因返回一个恰好只含 __rotifer_error 一个键的对象，宿主据此报告 INVALID_INPUT（ADR-334）——这个错误码规范 §4.2 从一开始就定义了，此前却从未被产出过。rotifer test --scaffold <gene> 会写出一份起步用的测试套件。这道门堵上了一个真实缺陷：此前发布的基因声明为 Native 保真度，却完全没有编译产物——rotifer install 能成功，但随后 rotifer run 会报「未找到可执行内容」。我们自己发布的 Native 基因里有 13 个正处于这种状态，现已全部修复并重新发布；遇到同类声明不符时，rotifer install/rotifer compile 现在会明确说出来，而不是报告成功。详细版本历史请参见 CHANGELOG.md。自动节点发现、跨公网连接与 L4 集体免疫是后续里程碑——详见下方实现状态。

安装

npm install -g @rotifer/playground

或通过 npx 直接使用：

npx -y @rotifer/playground@latest init my-agent

环境要求： Node.js >= 20.0.0

几秒钟跑通第一个 Agent

rotifer init my-agent && cd my-agent
rotifer hello --template quality-advisor

rotifer init 先把本地 Arena 和 Genesis genes 建起来；rotifer hello --template quality-advisor 则是推荐的首次预设 Agent 入口。

30 秒演示

$ rotifer init my-agent

  Rotifer Protocol - Agent Workspace Initialization
  ───────────────────────────────────────────
✓ Agent workspace 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!
✓ Agent workspace ready: my-agent

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

三幕体验 (ADR-11)

第一幕——Wow（30 秒）

rotifer init my-agent && cd my-agent

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

第二幕——Aha（5 分钟）

rotifer hello --template quality-advisor # 运行推荐的预设 Agent
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 [workspace-name] | 初始化新的 Rotifer Agent 工作区 | | rotifer hello [--template <id>] | 在 Rotifer Agent 工作区内从精选模板创建并运行一个预设 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 | 列出当前 Agent 工作区中的本地基因 | | 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 基因

每个新 Agent 工作区预装五个基因：

| 基因 | 领域 | 保真度 | 说明 | |------|------|--------|------| | 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 | 内核层 | ~40% | L0Gate 预执行检查（域、资源上限、文件系统），覆盖全部执行路径，含基因组内的每一步与 Node.js 降级路径；审计日志 | 逐基因权限策略、网络检查、伦理边界、状态锚定、信任根 | | L1 | 合成层 | ~70% | WASM 沙箱（wasmtime）、IR 编译器、Javy TS→WASM、NAPI 桥接 | Synthesizer 接口、完整 WASI 能力协商 | | L2 | 校准层 | ~40% | Schema 验证、沙箱测试、--compliance 检查 | 静态分析、受控试运行 | | L3 | 竞争与交换层 | ~85% | Arena 排名、F(g) 乘法模型、R(g) 声誉、Cloud Registry、实验性 P2P 节点（局域网基因公告，默认关闭） | 自动节点发现、跨公网 P2P、热加载、退役 | | L4 | 集体免疫层 | 0% | — | 威胁广播、紧急回滚、跨节点共识 | | 代数 | 组合代数 | ~90% | Rust 五算子全实现；CLI 支持 Seq/Par/Cond/Try | DataFlowGraph |

关键限制： L4 依赖成熟的 L3 P2P 网络。P2P 现已可运行，但仍属实验性、默认关闭，尚缺自动节点发现与跨公网连接。完整 L4 目标为 v1.x。

协议合规性

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

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

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

路线图

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

• 下一步 — 自动节点发现与跨公网 P2P 连接
• v1.0 — 稳定版：L0-L3 完整、经济体系上线、安全审计
• v1.x — L4 集体免疫

社区

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

参与贡献

开发指南请参见 CONTRIBUTING.md。

许可证

Apache-2.0 + Rotifer Safety Clause

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

轮虫协议，生生不息。