rotifer-protocol/rotifer-playground

Rotifer Playground

CI
npm
License: Apache-2.0
Node.js
Protocol
Discord

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  会写出一份起步用的测试套件。这道门堵上了一个真实缺陷：此前发布的基因声明为 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 ] | 在 Rotifer Agent 工作区内从精选模板创建并运行一个预设 agent |
| rotifer scan [path] | 扫描候选基因和本地技能 |
| rotifer wrap  | 将函数或 SKILL.md 包装为基因 |
| rotifer test [gene-name] | 在沙箱中测试基因 |
| rotifer compile [gene-name] | 将基因编译为 Rotifer IR（WASM） |
| rotifer run  | 直接执行单个本地基因 |
| rotifer list | 列出当前 Agent 工作区中的本地基因 |
| rotifer login | 登录 Rotifer Cloud |
| rotifer logout | 从 Rotifer Cloud 登出 |
| rotifer publish [gene-name] | 将基因发布到 Rotifer Cloud |
| rotifer search [query] | 在 Rotifer Cloud 中搜索基因 |
| rotifer install  | 从 Rotifer Cloud 安装基因 |
| rotifer info  | 查看基因详情（本地或 Cloud） |
| rotifer stats  | 查看基因下载统计 |
| rotifer compare [gene-refs...] | 按声誉与下载量对比 2-5 个基因 |
| rotifer reputation [gene-ref] | 查看基因与创作者声誉分数 |
| rotifer versions   | 查看某个基因的版本链 |
| rotifer arena submit  | 将基因提交到 Arena 竞争 |
| rotifer arena list | 列出 Arena 排名 |
| rotifer arena watch  | 实时观察 Arena 排名 |
| rotifer agent create  | 用基因组创建 Agent |
| rotifer agent list | 列出全部 Agent |
| rotifer agent run  | 执行 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 的对比 |

开发
bash
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 约束层，或明确披露对其的修改。

轮虫协议，生生不息。