📦 Rotifer Agent — 从 Gene 构建 Agent 的全流程架构指南

将用户意图分解为能力单元，从生态系统中选择 Genes，组合 Genome，创建并验证 Agent。

Prerequisites

此技能需要 Rotifer CLI：

npx @rotifer/playground --version

或使用 MCP Server 进行 IDE 集成：

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

---

层级结构: Gene（原子逻辑）→ Genome（组合）→ Agent（可运行实体）

---

Phase 1: Intent Decomposition

将用户目标分解为独立的能力单元（每个单元映射到一个 Gene）。

步骤:

• 与用户确认 Agent 的输入和预期输出
• 将任务分解为 2-6 个能力单元，每个单元满足 Gene 三原则（功能内聚、自足接口、独立可评估）
• 为每个单元标注领域（例如 content.grammar、security.audit）
• 在进入 Phase 2 前与用户确认分解方案

输出格式:

#	Capability unit	Domain	Input	Output
1	Grammar check	content.grammar	text	issues[], score
2	Readability analysis	content.readability	text	grade, suggestions[]

---

Phase 2: Gene Selection

将现有 Genes 匹配到每个能力单元。

rotifer list
rotifer arena list --domain 

选型优先级:

Priority	Source	Command
1	Arena 排名最高的本地 Gene	rotifer arena list --domain
2	云端注册表	rotifer install
3	不存在，需要创建	进入 Phase 3

向用户展示候选 Genes 的 F(g) 适应度和保真度，让他们确认选择。

---

Phase 3: Gap Filling

如果能力单元没有现有 Gene：

Approach	When to use	Action
Create Wrapped Gene	有可包装的外部 API / Skill	路由到 gene-dev 技能
Create Native Gene	纯计算，无外部依赖	路由到 gene-dev 技能
Adjust decomposition	能力单元粒度不正确	返回 Phase 1
Merge units	两个单元耦合过密，拆分导致接口尴尬	合并为一个 Gene

所有 Genes 准备就绪后，进入 Phase 4。

---

Phase 4: Genome Composition

根据能力单元之间的关系选择组合策略。

Composition Strategy Decision Table

Strategy	Semantics	Use when	Example
Seq(A, B, C)	Pipeline: A → B → C	前一个输出作为下一个输入	Check → Fix → Format
Par(A, B)	Parallel: run simultaneously	独立任务，合并结果	Grammar check + Readability analysis
Cond(p, A, B)	Branch: if p then A else B	输入特征决定路径	Chinese → Chinese proofing / English → English proofing
Try(A, B)	Fallback: A fails → B	主路径不可靠	Main API → Backup API
TryPool(A, B, C)	Race: all try, first success wins	多个等效实现	Multiple translation services racing

Par Merge Strategies

使用 Par 时，指定 --par-merge：

Strategy	Behavior	Use when
first	Take the first completed result	Racing scenario
concat	Concatenate all results (array)	Results are complementary
merge	Deep-merge objects	Same structure, merge fields

Seq Schema Compatibility Warning

已知限制: Seq 组合需要前一个 Gene 的 outputSchema 与下一个 Gene 的 inputSchema 兼容。当前版本不会自动验证——模式不匹配会导致运行时错误。

>

建议: 在创建 Seq 组合前，手动比较相邻 Genes 的 inputSchema/outputSchema（在 phenotype.json 中）以确认字段名和类型匹配。

Nested Composition

组合策略可以嵌套：

Seq(
  Par(grammar-checker, readability-analyzer),
  tone-analyzer
)

对应 CLI：

rotifer agent create doc-qa \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Seq

当前 CLI 仅支持顶层组合策略。嵌套组合需要手动编辑 .rotifer/agents/.json。

---

Phase 5: Agent Creation

在确认组合方案后执行创建。

Manual Gene Selection

rotifer agent create  \
  --genes    \
  --composition  \
  --par-merge 

Auto-select Genes (by domain ranking)

rotifer agent create  \
  --domain  \
  --top  \
  --composition 

创建后，验证 Agent 配置文件 .rotifer/agents/.json 是否正确。

---

Phase 6: Test Run

rotifer agent run  --input '{"text": "Test input content"}'

验证清单:

• 输出结构是否符合预期 schema？
• 是否所有 Genes 都执行了？（检查日志）
• Seq 组合中 schema 传递是否正确？
• Par 合并结果是否完整？
• 错误路径（Try/TryPool）是否正确降级？

如果结果不满意，进入 Phase 7。

---

Phase 7: Iterative Optimization

Problem	Optimization
某个 Gene 输出质量较差	rotifer arena list --domain 寻找替代品
Seq 中间结果缺少字段	检查 schema 兼容性，考虑插入适配器 Gene
Par 合并结果混乱	切换 --par-merge 策略
延迟过高	Seq → Par（如果 Genes 独立）
整体低于预期	路由到 rotifer-arena 技能进行 Genes 对比评估

---

Scenario Examples

Scenario 1: Document Quality Agent

目标: 输入文本，输出语法问题 + 可读性分数 + 语气分析。

分解:

#	Capability	Gene	Domain
1	Grammar check	grammar-checker	content.grammar
2	Readability analysis	readability-analyzer	content.readability
3	Tone analysis	tone-analyzer	content.tone

组合: 三个都接受 text 输入，无依赖 → Par + concat。

rotifer agent create doc-quality \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Par \
  --par-merge concat
rotifer agent run doc-quality --input '{"text": "Document content to check..."}'

Scenario 2: Code Review Agent

目标: 输入代码文件，输出安全漏洞 + 复杂度报告 + 文档建议。

#	Capability	Gene	Domain
1	Security audit	security-auditor	security.audit
2	Complexity analysis	code-complexity	code.analysis
3	Documentation generation	docs-writer	content.docs

组合: 安全审计和复杂度分析可以并行运行，文档生成依赖两者 → Seq(Par(1,2), 3)。

rotifer agent create code-review \
  --genes security-auditor code-complexity docs-writer \
  --composition Seq
rotifer agent run code-review --input '{"code": "...", "language": "typescript"}'

注意：Par(security-auditor, code-complexity) 的合并输出必须与 docs-writer 的 inputSchema 兼容。需要手动验证。

Scenario 3: Search & Summarize Agent

目标: 输入搜索查询，搜索 → 总结 → 格式化输出。

#	Capability	Gene	Domain
1	Web search	genesis-web-search	search.web
2	Text summarization	text-summarizer	content.summarize
3	Markdown formatting	markdown-formatter	content.format

组合: 严格串行流水线 → Seq。

rotifer agent create search-digest \
  --genes genesis-web-search text-summarizer markdown-formatter \
  --composition Seq
rotifer agent run search-digest --input '{"query": "Rotifer Protocol agent framework"}'

注意 Seq schema 链：genesis-web-search 的输出字段名必须匹配 text-summarizer 的 inputSchema。在创建前运行 cat genes/*/phenotype.json | jq '.inputSchema, .outputSchema' 进行验证。

---

Related Skills

Skill	Relationship	When to route
gene-dev	Gene 创建/开发	Phase 3 缺口填补
rotifer-arena	Gene 对比与评估	Phase 7 替换表现不佳的 Genes
genome	Genome 质量分析	Agent 创建后进行整体评估

---

Constraints

• Agent 配置文件存储在 .rotifer/agents/.json，不应提交到 Git
• 单个 Agent 应包含 2-6 个 Genes；超过 6 个建议拆分为多个 Agents
• Seq schema 兼容性是已知限制——创建前务必手动验证
• 嵌套组合需要手动编辑 JSON；CLI 仅支持顶层策略