跳转到内容
Rotifer Protocol

开发者 FAQ

CLI 与环境搭建

Section titled “CLI 与环境搭建”
如何安装 CLI？
Terminal window
npm install -g @rotifer/playground

或免安装直接运行：

Terminal window
npx @rotifer/playground init my-project

前置要求： Node.js >= 20.0.0，npm >= 9。

如何创建第一个 Gene？
Terminal window
# 1. 初始化项目
rotifer init my-project && cd my-project


# 2. 编写 Gene 逻辑
# 编辑 genes/my-gene/index.ts:
# export async function express(input) { return { result: ... }; }


# 3. 封装（生成 phenotype.json）
rotifer wrap my-gene --domain search


# 4. 编译为 WASM（可选，获得 Native 保真度）
rotifer compile my-gene


# 5. 测试
rotifer test my-gene

查看快速入门指南了解完整流程。

如何发布到 Cloud Registry？
Terminal window
# 1. 通过 GitHub OAuth 登录
rotifer login


# 2. 发布你的 Gene
rotifer publish my-gene

发布后，你的 Gene 会出现在 Gene 目录中，可通过 rotifer search 被其他开发者发现。

如何搜索和安装 Gene？
Terminal window
# 按关键词搜索
rotifer search "grammar"


# 从 Cloud Registry 安装 Gene
rotifer install grammar-checker

安装后的 Gene 会放在项目的 genes/ 目录下，即可使用。

运行 Gene

Section titled “运行 Gene”
如何运行一个 Gene？

Native Gene 有三种运行方式：

1. 通过 Agent 管道（推荐）：

Terminal window
# 创建一个 Agent，装配基因组
rotifer agent create content-checker --genes grammar-checker readability-analyzer


# 运行管道
rotifer agent run content-checker --input '{"text":"要检查的文本"}' --verbose

2. 在 TypeScript 中直接导入：

import { express as grammarCheck } from "./genes/grammar-checker/index.js";


const result = await grammarCheck({ text: "Check this text." });
console.log(result.score, result.issues);

3. Fan-out 并行组合 —— 多个 Gene 分析同一份输入，最后合并结果。参见 tests/demo/content-pipeline-demo.ts 示例。

Wrapped Gene 能执行吗？

不能。 Wrapped Gene 没有 express() 函数——仅包含元数据（phenotype.json）和描述文件（SKILL.md）。

要让 Wrapped Gene 变为可执行，需编写 index.ts 文件并实现 express() 函数，将其升级为 Native。

Seq 管道组合怎么工作？

当一个 Agent 拥有多个 Gene 时，它们按顺序执行（Seq 组合）：

输入 → Gene 1 → 输出₁ → Gene 2 → 输出₂ → Gene 3 → 最终输出

每个 Gene 的输出成为下一个 Gene 的输入。相邻 Gene 必须有兼容的 schema。

Terminal window
rotifer agent create my-pipeline --genes step1 step2 step3
rotifer agent run my-pipeline --input '{"data": "..."}'
Gene 之间输入输出 schema 不匹配怎么办？

管道会在运行时失败。解决方案：

  1. 确保 schema 兼容 —— 设计 Gene 时让相邻的 I/O schema 对齐
  2. 编写适配器 Gene —— 创建一个小型 Gene 将一种 schema 转换为另一种
  3. 使用 fan-out 组合 —— 如果多个 Gene 独立分析同一份输入，改为并行运行

Skill → Gene 迁移

Section titled “Skill → Gene 迁移”
如何迁移现有的 MCP Tool 为 Gene？

迁移是渐进增强，而非推倒重来：

Terminal window
# 1. 扫描项目中可迁移的 Skill
rotifer scan --skills


# 2. 一键封装为 Gene
rotifer wrap my-tool --from-skill --domain search


# 3. （可选）实现 express() 升级为 Native
# 编辑 genes/my-tool/index.ts


# 4. 编译和测试
rotifer compile my-tool
rotifer test my-tool

可复用的部分： 核心业务逻辑、inputSchema/outputSchema、组合模式（Workflow/Chain → Genome DataFlowGraph）。

故障排查

Section titled “故障排查”
rotifer publish 报 409 错误怎么办？

409 Conflict 表示 Cloud Registry 中已有同名同版本的 Gene。

修复： 在 Gene 的 phenotype.json 中升级版本号，然后重新发布：

{
  "version": "0.2.0"
}
Terminal window
rotifer publish my-gene
如何创建账号 / 登录？
Terminal window
rotifer login

这会在浏览器中打开 GitHub OAuth 授权流程。授权后，会话令牌存储在本地 ~/.rotifer/auth.json。

rotifer compile 失败——应该检查什么？

常见原因：

  1. 缺少 Javy 运行时 —— rotifer compile 需要 Javy 二进制文件，确保已安装并在 PATH 中。
  2. TypeScript 错误 —— index.ts 必须能干净编译。运行 npx tsc --noEmit 检查。
  3. 缺少 express() 导出 —— 编译器需要 export async function express(input) 作为入口点。
rotifer agent run 报错 “Gene has no source file”

Gene 目录必须包含以下文件之一：index.ts、index.js 或 index.mjs。检查：

Terminal window
ls genes/my-gene/

如果只有 phenotype.json 和 SKILL.md，说明该 Gene 是 Wrapped（不可执行）。你需要编写 index.ts 并实现 express() 函数。

Cloud Registry 是开源的吗？

API 网关设计和数据库模型已在协议规范中文档化。基础设施运行在托管服务（Supabase）上。REST API 公开可访问，可用于搜索和安装 Gene。