Gene 生命周期命令
rotifer init
Section titled “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 Arenarotifer scan
Section titled “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
Section titled “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.0rotifer test
Section titled “rotifer test”对 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 |
自动执行的测试用例:
- 模式验证 — Phenotype 符合 Gene 标准
- Express 函数 — 导出了可调用的
express()函数 - 输入/输出一致性 — 输出匹配
outputSchema - 错误处理 — 无效输入时优雅失败
- 空值检查 —
express()返回非空数据 - 沙箱执行 — 已编译 Gene 通过 WASM 沙箱执行;未编译 Gene 回退到 Node.js 并提示警告
- 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.9100rotifer run
Section titled “rotifer run”直接执行单个 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"}'rotifer compile
Section titled “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— 序列化 Phenotyperotifer.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 doctor
Section titled “rotifer doctor”检查 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 步骤。