CellSpec 参考

CellSpec 是创建和配置 Cell 的声明式规范。

基本结构

{
  "id": "dept-legal",
  "timezone": "Asia/Shanghai",
  "locale": "zh-CN",
  "governance": { ... },
  "provider_strategy": "shared_only",
  "private_providers": [ ... ],
  "channels": [ ... ],
  "quotas": { ... }
}

核心字段

元数据

字段	类型	可变	说明
`id`	string	不可变	Cell 唯一标识
`timezone`	string	不可变	时区，如 `Asia/Shanghai`
`locale`	string	可变	语言，如 `zh-CN`
`compliance`	string	可变	合规类别：`standard` / `pii-strict` / `financial` / `healthcare`

Provider 配置

字段	说明
`provider_strategy`	Provider 选择策略
`private_providers`	Cell 私有 Provider 列表（BYOK）
`allowed_models`	允许使用的模型列表

Provider Strategy 四种模式：

策略	说明
`own_only`	只用 Cell 私有 Provider
`shared_only`	只用共享池
`own_first`	优先私有，回退共享
`shared_first`	优先共享，回退私有

治理配置

{
  "governance": {
    "mode": "open",
    "deny_paths": ["/etc", "/root"],
    "network_policy": "allow"
  }
}

详见治理模型。

外设声明

CellSpec 支持声明式装配以下外设：

字段	外设	说明
`channels`	IM 渠道	企业微信、飞书、钉钉
`email`	邮箱	IMAP + SMTP
`mcps`	MCP 服务器	外部工具连接
`cron`	定时任务	周期性执行
`playwright`	浏览器自动化	用户浏览器
`desktop`	桌面自动化	系统操作
`headless_browser`	无头浏览器	服务端抓取
`stt`	语音转写	Whisper
`plugins`	插件	JSON-RPC 子进程

配额

{
  "quotas": {
    "max_concurrent_runs": 3,
    "tokens_per_minute": 100000,
    "tokens_per_day": 5000000,
    "max_im_channels": 10,
    "max_mcp_servers": 20,
    "max_cron_jobs": 50,
    "max_email_accounts": 5,
    "max_skills_installed": 100
  }
}

创建 Cell

通过 Admin API

curl -X POST http://localhost:9091/admin/cells \
  -H "Content-Type: application/json" \
  -d @cellspec.json

通过 Go SDK

cell, err := hyp.Cells().GetOrCreate(ctx, wesgine.CellSpec{
    ID:               "dept-legal",
    Timezone:         "Asia/Shanghai",
    Locale:           "zh-CN",
    ProviderStrategy: "shared_only",
    Governance:       governance.StandardPreset(),
})

更新 CellSpec

运行中的 Cell 可以热更新部分字段：

curl -X PATCH http://localhost:9091/admin/cells/dept-legal \
  -H "Content-Type: application/json" \
  -d '{"quotas": {"max_concurrent_runs": 5}}'

不可变字段（id、timezone）创建后不能修改。

密钥管理

Provider 的 API Key 通过 SecretRef 声明：

来源	说明
`inline`	明文传入，引擎 AES-256-GCM 加密存储
`env`	从环境变量读取
`live`	运行时由应用层动态提供

{
  "api_key_ref": {
    "source": "inline",
    "value": "sk-..."
  }
}

inline 密钥存储在加密的 hypervisor.db 中，密钥文件 spec.key 独立存放。