跳转到内容

Gene 生命周期命令

初始化新的 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

扫描源代码文件,发现可封装为 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 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

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

终端窗口
rotifer test <gene-name> [选项]

参数:

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

选项:

标志说明
--verbose显示每个测试用例的详细输入/输出
--compliance运行结构性合规检查(沙箱、L0、燃料计量、IR 完整性)
--scaffold根据 phenotype 生成一份起步用的 testsuite.json 后结束,不跑任何测试;已有 testsuite.json 时拒绝覆盖
--json另外把 T1 结果输出成 JSON:requirements、gatePassed 和每个用例的结果。只在 Gene 有 testsuite.json 时输出;其余报告照常以文字输出
--allow-credentials <list>允许外来基因使用你环境变量里的这些凭证,每个只发往对应的 host:KEY@api.example.com,KEY2@other.example.com。不加时,外来基因声明了凭证,命令会在终端里问一次(默认不给),不在终端里运行则以 credentials_not_granted 退出 1

自动执行的测试用例:

  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)

T1 测试集: Gene 目录里有 testsuite.json(规范 §47.5)时,rotifer test 还会把它当作 T1 跑一遍,和 rotifer publish 跑的是同一项检查。没有这个文件时,会提示发布门没有评估。有用例失败时,命令以退出码 1 结束。rotifer test <gene> --scaffold 可以生成一份起步用的测试集。

  • 异步 express(0.37.0 起): T1 会等异步 express 返回,按它最终给出的值判定。以前判的是 Promise 对象,所以以前靠 Promise 对象通过的测试集现在可能不过,以前卡在 Promise 上的现在可能通过。
  • 永远不结束的调用: Gene 的 Promise 永远不结束时,这次调用以退出码 1 失败,报错说明这个 Gene 没有结束。0.37.0 之前,命令会半路停下、退出码 0。rotifer run 和 rotifer agent run 也一样。
  • 没有 IR 的外来基因(0.38.0 起): 从 Cloud 安装或从 ClawHub 包装、还没编译出 IR 的 Gene 不会在 Node.js 下运行,T1 判失败并提示先运行 rotifer compile <gene>;编译后测试集在沙箱里跑。你在本工作区自己写的 Gene 仍在 Node.js 下跑测试集。

示例:

终端窗口
$ 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

直接执行单个 Gene,并按 Gene 的 schema 检查输入和输出。

终端窗口
rotifer run <gene-name> [选项]

参数:

参数必填说明
gene-name是要执行的 Gene 名称

选项:

选项说明
--input <json>输入 JSON 字符串(默认:{"name":"world"})
--verbose显示详细执行输出
--no-sandbox不用 WASM 沙箱运行(仅 Node.js)
--trust-unsigned允许从云端安装或从 ClawHub 包装的基因以 Node.js 执行
--no-validate跳过按 Gene 的 inputSchema / outputSchema 检查输入和输出
--allow-credentials <list>允许外来基因使用这些凭证,每个只发往对应的 host:KEY@api.example.com,KEY2@other.example.com

外来基因:

  • 从 Cloud 安装或从 ClawHub 包装的 Gene,编译过(有 gene.ir.wasm)就在 WASM 沙箱里运行;要以源码在 Node.js 下运行时,run 会拒绝并以退出码 1 结束,除非加 --trust-unsigned,或先用 rotifer compile <gene> 编译。
  • 在沙箱里运行的外来 Gene 声明要用你环境变量里的凭证时,run 在终端里运行前先问一次(默认不给);不在终端里运行则以 credentials_not_granted 退出 1。用 --allow-credentials KEY@host 只为这一条命令放行该凭证,且只发往那个 host。加 --trust-unsigned 时 Gene 改在 Node.js 下运行:run 不会问,Gene 能读到你的全部环境变量。

示例:

终端窗口
rotifer run my-search --input '{"query":"rotifer"}'

将 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


检查 rotifer compile 把 TypeScript 编译成 WASM 所需的工具链:esbuild 和 Javy。

终端窗口
rotifer doctor

不带参数。它先在 PATH 里找 esbuild(再试 npx --no-install esbuild),再找 javy(再试 npx --no-install javy-cli 和 javy),并打印当前生效的 npx 和 node。不会下载任何东西。

示例:

终端窗口
$ rotifer doctor
Rotifer Doctor — TS→WASM toolchain
────────────────────────────────────
esbuild: ok (esbuild)
javy: ok (javy)
active npx: /usr/local/bin/npx
node: /usr/local/bin/node
✓ Toolchain ready — `rotifer compile` can build Native WASM Genes.

缺东西时,它会列出试过哪些位置,并给出修法:npm i -g esbuild javy-cli(javy-cli 这个包装出来的可执行文件叫 javy),再确认装着 rotifer 的那个 Node 前缀排在 PATH 最前面。这种情况下退出码为 1,可以拿来卡 CI 步骤。