Gene 生命周期命令

rotifer init

初始化新的 Rotifer Agent 工作区，包含创世 Gene 和 Arena（竞技场）预览。

rotifer init [工作区名称]

参数：

参数	必填	说明
工作区名称	否	Agent 工作区目录名称（默认为 my-agent）

选项：

标志	说明
--domain <域>	默认 Gene（基因）域（默认：general）
--fidelity <级别>	示例 Gene 保真度：Wrapped | Hybrid | Native（默认：Wrapped）
--no-genesis	跳过创世 Gene 安装

生成的 Agent 工作区结构：

my-agent/
├── rotifer.json          # Agent workspace configuration
├── genes/                # Gene source directory
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── playground.db     # Local Arena database

示例：

$ rotifer init my-agent
# Creates ./my-agent with Genesis genes and local Arena state

$ cd my-agent && rotifer arena list
# Show Genesis Gene rankings in Arena

---

rotifer scan

扫描源代码文件，发现可封装为 Gene 的候选函数。

rotifer scan [路径]

参数：

参数	必填	说明
路径	否	扫描路径（默认为 .）

选项：

标志	说明
--skills	扫描 SKILL.md 文件而非源函数
--skills-path <目录>	使用 --skills 时，指定扫描目录（默认：[路径] 或 .cursor/skills）

支持的语言： TypeScript（.ts、.js）、Rust（.rs）

检测模式：

• export function name()
• export async function name()
• export const name =
• pub fn name() / pub async fn name()

示例：

$ rotifer scan src/tools/
  Scanning src/tools/search.ts...

  Found 3 candidate functions:
  ┌────┬──────────────┬──────────────────────┬──────┐
  │ #  │ Name         │ File                 │ Line │
  ├────┼──────────────┼──────────────────────┼──────┤
  │ 1  │ webSearch    │ src/tools/search.ts  │ 12   │
  │ 2  │ fileRead     │ src/tools/file.ts    │ 8    │
  │ 3  │ codeFormat   │ src/tools/format.ts  │ 5    │
  └────┴──────────────┴──────────────────────┴──────┘

---

rotifer wrap

将函数封装为 Rotifer Gene，生成 Phenotype（表型）和适配代码。

rotifer wrap <gene-name> --domain <域> [选项]

参数：

参数	必填	说明
gene-name	是	Gene 名称

选项：

标志	说明
-d, --domain <域>	功能域（如 search.web、file.read）
--fidelity <级别>	保真度级别（默认：Wrapped）
--from-skill <路径>	从 SKILL.md 文件创建 Gene（路径指向 SKILL.md 或其目录）
--from-clawhub <slug>	从 ClawHub 技能创建 Gene（自动下载并转换）

生成的文件：

genes/<gene-name>/
├── phenotype.json    # Phenotype metadata (domain, mode, fidelity)
├── index.ts          # Express function wrapper
└── shim.ts           # Compatibility shim

示例：

$ rotifer wrap my-search --domain search.web
  ✓ Gene 'my-search' wrapped successfully

  Domain:    search.web
  Fidelity:  Wrapped
  Version:   0.1.0

---

rotifer test

对 Gene 执行沙箱测试，验证模式和行为。

rotifer test <gene-name> [选项]

参数：

参数	必填	说明
gene-name	是	要测试的 Gene 名称

选项：

标志	说明
--verbose	显示每个测试用例的详细输入/输出
--compliance	运行结构性合规检查（沙箱、L0、燃料计量、IR 完整性）

自动执行的测试用例：

1. 模式验证 — Phenotype 符合 Gene 标准
2. Express 函数 — 导出了可调用的 express() 函数
3. 输入/输出一致性 — 输出匹配 outputSchema
4. 错误处理 — 无效输入时优雅失败
5. 空值检查 — express() 返回非空数据
6. 沙箱执行 — 已编译 Gene 通过 WASM 沙箱执行；未编译 Gene 回退到 Node.js 并提示警告
7. IR 验证 — WASM 模块包含所有必需的自定义段

使用 --compliance 时，额外运行 6 项结构性检查：

• C1: 沙箱执行验证（sandbox_type == “wasm”）
• C2: 燃料消耗验证（fuel_consumed > 0）
• C3: L0Gate 预执行检查通过
• C4: Phenotype 字段完整性（Gene Standard）
• C5: F(g) 可计算性（所有输入指标可获取）
• C6: IR 段完整性（自定义 WASM sections）

示例：

$ rotifer test my-search
  Testing 'my-search'...

  ✓ Phenotype schema valid
  ✓ express() returned successfully
  ✓ Output matches outputSchema
  ✓ Error handling works correctly

  All 4 tests passed ✓
  Fitness: F(g) = 0.8234  V(g) = 0.9100

---

rotifer compile

将 Gene 编译为 Rotifer IR（带自定义段的 WASM）。

rotifer compile [gene-name] [选项]

参数：

参数	必填	说明
gene-name	否	Gene 名称（省略时自动检测）

选项：

标志	说明
--check	仅验证，不生成产物
--wasm <路径>	预编译 .wasm 文件路径，封装为 IR
--lang <ts|wasm>	强制编译模式（默认自动检测）

编译管线：

TypeScript 源码
    ↓ esbuild（打包 + 压缩）
WASI 兼容 JavaScript
    ↓ IR 编译器（QuickJS → WASM）
原始 WASM 模块
    ↓ Rotifer IR 注入器
gene.ir.wasm（带自定义段）

注入的自定义段：

• rotifer.version — 协议版本
• rotifer.phenotype — 序列化 Phenotype
• rotifer.constraints — L0 约束元数据
• rotifer.metering — 燃料/资源限制

示例：

$ rotifer compile my-search
  Compiling 'my-search'...

  Pipeline: TypeScript → esbuild → IR compiler → IR
  ✓ Compilation successful

  IR Hash:  a3f2b1...c4d5
  Size:     142.3 KB
  Sections: version, phenotype, constraints, metering

输出： genes/<gene-name>/gene.ir.wasm