Evolution API

Evolution API（Level 1.5）将 Rotifer 的公开基因注册表和竞技场数据暴露给外部系统。 它适合用来构建推荐层、监控仪表盘，或围绕 Rotifer 进化基础设施编写自定义工具。

基础 URL

https://api.rotifer.dev/v1

当前访问模型

当前公开端点全部为只读 GET 接口。 每次请求都需要在 X-API-Key 请求头中传入带 read scope 的 API 密钥：

curl -H "X-API-Key: YOUR_KEY" https://api.rotifer.dev/v1/genes

密钥管理

密钥通过 CLI 创建和管理：

rotifer login
rotifer api-key create --name "My Read Key"
rotifer api-key list
rotifer api-key revoke --prefix rk_abcd12

频率限制

频率限制按 API 密钥存储。 默认创建流程使用 30/min，但每个密钥都可以配置自己的每分钟限额。

端点

GET /v1/genes

搜索和发现基因，并返回竞技场排名相关数据。

参数	类型	默认值	说明
domain	string	—	按领域筛选，例如 content.qa
fidelity	string	—	按 Wrapped、Hybrid、Native 筛选
sort	string	fitness	按 fitness、reputation 或 downloads 排序
limit	integer	20	每页结果数，最大 50
offset	integer	0	分页偏移量

示例

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/genes?domain=content.qa&sort=fitness&limit=5"

响应

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "doc-retrieval",
      "domain": "content.qa",
      "fidelity": "Hybrid",
      "description": "Document retrieval with semantic search",
      "fitness_score": 0.92,
      "reputation_score": 0.85,
      "owner": "alice",
      "downloads": 342,
      "arena_rank": 1,
      "arena_history": [
        {
          "fitness_value": 0.92,
          "evaluated_at": "2026-03-24T00:00:00Z",
          "total_calls": 1500
        }
      ]
    }
  ],
  "total": 12,
  "limit": 5,
  "offset": 0
}

GET /v1/genes/{id}/phenotype

获取单个基因的公开表型数据，包含安装指令和兼容性信息。

参数	类型	说明
id	UUID（路径）	基因 UUID

示例

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/genes/550e8400-e29b-41d4-a716-446655440000/phenotype"

响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "doc-retrieval",
  "domain": "content.qa",
  "fidelity": "Hybrid",
  "phenotype": {
    "input": { "type": "object", "properties": { "query": { "type": "string" } } },
    "output": { "type": "object", "properties": { "results": { "type": "array" } } }
  },
  "fitness_score": 0.92,
  "reputation_score": 0.85,
  "install_command": "npx @rotifer/playground install doc-retrieval",
  "compatibility": {
    "min_playground_version": "0.7.0",
    "required_fidelity": "Hybrid"
  }
}

GET /v1/arena/insights

获取某个领域的进化健康指标，可用于监控生态多样性和基因竞争动态。

参数	类型	说明
domain	string（必填）	要分析的领域

示例

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.rotifer.dev/v1/arena/insights?domain=content.qa"

响应

{
  "domain": "content.qa",
  "gene_count": 8,
  "shannon_diversity": 2.322,
  "turnover_rate": 0.2,
  "top_genes": [
    { "name": "doc-retrieval", "fitness": 0.92, "trend": "stable" },
    { "name": "answer-synth", "fitness": 0.87, "trend": "rising" }
  ],
  "avg_fitness": 0.65,
  "total_arena_evaluations": 4200
}

指标说明

指标	说明
shannon_diversity	Shannon 熵 H'。值越高，说明竞争结构越健康。
turnover_rate	近 30 天内 Top-5 基因被替换的比例。
trend	基于近期竞技场评估得到的适应度趋势：rising、stable、declining。

错误响应

所有错误都使用统一格式：

{
  "error": "可读错误信息",
  "code": "MACHINE_READABLE_CODE"
}

HTTP 状态码	Code	说明
400	INVALID_ID / MISSING_PARAM	请求格式错误
401	UNAUTHORIZED	API 密钥无效或缺失
404	NOT_FOUND	资源不存在
405	METHOD_NOT_ALLOWED	仅支持 GET
429	RATE_LIMITED	超出频率限制
502	DB_ERROR	上游数据库错误

协议对齐

API 端点	协议接口	规范章节
GET /v1/genes	GeneRegistry.query() + SemanticDiscovery.discoverByNeed()	§8.2
GET /v1/arena/insights	Arena Data Transparency + ArenaSummary	§9.7.1, §41.2
GET /v1/genes/{id}/phenotype	Phenotype Public tier	§4.2

这些端点按 §25.4 标记为 nonstandard，因为它们是 Cloud Binding 的实现特定接口。