创作者 FAQ

在找概念性问题？

“Gene 是什么？”、“和 MCP 有什么区别？”、“Arena 是什么？“等问题请查看主站 FAQ。 本页面聚焦创作者操作和技术排障。

---

CLI 与环境搭建

如何安装 CLI？

npm install -g @rotifer/playground

或免安装直接运行：

npx @rotifer/playground init my-project
cd my-project
npx @rotifer/playground hello

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

如果你想在初始化后立刻跑通一次体验，直接执行 rotifer hello（或 npx @rotifer/playground hello）即可启动一个预设 Agent。

如何创建第一个 Gene？

# 1. 初始化项目
rotifer init my-project && cd my-project

# 2. 最快的首次体验（推荐）
rotifer hello

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

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

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

# 6. 测试
rotifer test my-gene

rotifer hello 不是创建 Gene 的必需步骤，但它是确认项目、Genesis genes 和 Agent 流程都正常工作的最快路径，然后你再开始构建自己的能力。

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

如何发布到 Cloud Registry？

# 1. 通过 GitHub OAuth 登录
rotifer login

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

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

如何搜索和安装 Gene？

# 按关键词搜索
rotifer search "grammar"

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

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

---

运行 Gene

如何运行一个 Gene？

Native Gene 有三种运行方式：

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

# 创建一个 Agent，装配 Genome
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。

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 独立分析同一份输入，改为并行运行

如何创建一个 Agent？

Agent 是 Gene 的载体——它定义了一组 Gene 的执行顺序（Genome）。

# 创建 Agent，装配多个 Gene
rotifer agent create my-agent --genes gene-a gene-b gene-c

# 查看 Agent 的 Genome 配置
rotifer agent info my-agent

# 运行 Agent
rotifer agent run my-agent --input '{"text":"Hello world"}' --verbose

Agent vs Gene 的关系：

• Gene 是原子能力单元（一个函数）
• Agent 是 Gene 的组合体——决定哪些 Gene 按什么顺序运行
• 一个 Agent 可以装配 1-N 个 Gene，Gene 之间通过 schema 串联

查看 Agent 管道指南 了解更多。

---

Hybrid Gene

什么是 Hybrid Gene？

Hybrid Gene 结合了 WASM 安全性和受控的网络访问。它可以通过**网络网关（Network Gateway）**调用外部 API（LLM、数据库、Embedding），网关强制执行：

• 域名白名单 — 仅允许预声明的域名
• 速率限制 — 每分钟请求次数上限
• 超时 — 单次请求超时强制中止
• 响应大小上限 — 超过限制时截断

查看 Hybrid Gene 开发指南了解完整流程。

如何创建 Hybrid Gene？

rotifer init my-gene --fidelity Hybrid

这会生成包含 network 配置块的 phenotype.json。编辑 allowedDomains 声明你的 Gene 需要访问的 API：

{
  "network": {
    "allowedDomains": ["api.openai.com"],
    "maxTimeoutMs": 30000,
    "maxResponseBytes": 1048576,
    "maxRequestsPerMin": 10
  }
}

在 express() 函数中使用 ctx.gatewayFetch 代替全局 fetch：

export async function express(input, ctx?) {
  const res = await ctx.gatewayFetch("https://api.openai.com/v1/...", { ... });
  return { result: await res.json() };
}

rotifer publish 报 E0055 或 E0056 错误怎么办？

E0055 — Hybrid Gene 的 network.allowedDomains 为空或缺失。每个 Hybrid Gene 必须声明至少一个域名。

修复： 在 phenotype.json 中添加域名：

"network": { "allowedDomains": ["api.example.com"] }

E0056 — allowedDomains 中某个域名是 localhost 或私有 IP（如 localhost、127.0.0.1、192.168.x.x），已发布的 Gene 禁止使用这些域名。

修复： 从 allowedDomains 中移除私有/localhost 域名。

可以使用通配符域名吗？

可以。使用 *.domain.com 允许所有子域名：

"allowedDomains": ["*.supabase.co"]

这会匹配 abc.supabase.co 和 supabase.co，但不会匹配无关域名。

如何在 Hybrid Gene 中管理 API Key？

永远不要硬编码 API Key。 使用环境变量：

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY not set");

运行前设置环境变量：

OPENAI_API_KEY=sk-... rotifer agent run my-agent --input '{}'

如果 Gene 调用了不在 allowedDomains 中的域名会怎样？

网络网关会立即拦截请求，抛出 DOMAIN_BLOCKED 错误。请求不会发出 — 没有任何网络流量离开本机。

---

Skill → Gene 迁移

如何迁移现有的 MCP Tool 为 Gene？

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

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

# 2. 一键封装为 Gene
rotifer wrap my-tool --from-skill ./SKILL.md --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）。

---

故障排查

rotifer publish 报 409 错误怎么办？

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

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

{
  "version": "0.2.0"
}

rotifer publish my-gene

如何更新已发布的 Gene 版本？

已发布的 Gene 版本是不可变的——你不能覆盖已有版本，必须发布新版本。

# 1. 修改代码后，升级版本号
# 编辑 phenotype.json: "version": "0.2.0"

# 2. 重新发布
rotifer publish my-gene

版本策略建议：

• Patch（0.1.0 → 0.1.1）——bug 修复，行为不变
• Minor（0.1.0 → 0.2.0）——新功能，向后兼容
• Major（0.1.0 → 1.0.0）——破坏性变更（outputSchema 改变）

新版本发布后，Arena 会重新评估适应度。旧版本仍可安装（通过 rotifer install [email protected]），但默认安装最新版。

如何创建账号 / 登录？

rotifer login

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

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

常见原因：

1. IR 编译器未安装 —— rotifer compile 需要 IR 编译器运行时，确保已安装并在 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。检查：

ls genes/my-gene/

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

Cloud Registry 是开源的吗？

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

---

没有找到你要的答案？

• 主站 FAQ —— 协议概念性问题
• GitHub Discussions —— 技术问题和功能建议
• Discord —— 实时交流和帮助