CellSpec 总览

CellSpec 是 wesgine Cell 的声明式配置，定义 Cell 的所有可配置属性。

分层结构

CellSpec 使用 Go struct embedding 分层：

type CellSpec struct {
    ID string                      // 不可变
    CellCoreSpec                   // 核心配置
    CellAdapterSpec                // 外设配置
    CellSchedulingSpec             // 调度配置
    CellPortableSpec               // 可移植配置
}

Go 嵌入保持向后兼容：spec.Timezone 等价 spec.CellCoreSpec.Timezone。

CellCoreSpec

字段	可变性	说明
`Timezone`	immutable	时区
`Locale`	mutable	语言区域
`Compliance`	mutable	合规类
`Governance`	mutable	治理配置
`EnginePaths`	mutable	引擎保留路径
`RedactorRules`	mutable	脱敏规则

CellAdapterSpec

字段	说明
`Channels`	IM 渠道
`Email`	邮箱账号
`MCPs`	MCP Server
`Cron`	定时任务声明
`HITL`	HITL 配置
`HeadlessBrowser`	Headless 浏览器
`Playwright`	Playwright 自动化
`Desktop`	桌面自动化
`STT`	语音转写
`Plugins`	Plugin Runtime

CellSchedulingSpec

字段	说明
`Quotas`	配额
`CycleDetect`	循环检测配置
`FaultPolicyOverride`	故障策略覆盖
`SkillPolicy`	技能策略
`InboxCap`	Inbox 容量
`Roles`	角色配置

CellPortableSpec

字段	说明
Export/Import 行为	打包/解包配置

Provider 相关字段

字段	说明
`ProviderStrategy`	own_only / shared_only / own_first / shared_first
`PrivateProviders`	Cell 私有 Provider（SecretRef）
`AllowedModels`	允许的模型列表
`LogicalModelGroups`	逻辑模型分组
`DisallowActorProvider`	禁止 Actor 自带 Provider

ProviderStrategy 自动推导

条件	结果
只有私有	`own_only`
只有共享	`shared_only`
两侧都有	必须显式声明
两侧都空	保持 unset

SDK Hooks（json:"-"）

进程内回调，不序列化：

Hook	说明
`ProviderLiveKeyFn`	live-token 回调（wes:/org:）
`HostEnvironment`	宿主环境能力注入
`QualityGate`	质量门回调
`EditPatrol`	编辑巡查回调
`OnStarted`	Cell 启动后回调
`PostRunFn`	Run 结束后回调
`FileSegmenter`	文件分段器
`EditMatchFallback`	编辑匹配 fallback
`ToolExecutorHooks`	工具执行钩子

GetOrCreate 前必须绑齐这些 hook（INV-CELL-08）。

字段可变性标签

type CellSpec struct {
    ID       string `wesgine:"immutable"`
    Timezone string `wesgine:"immutable"`
    Locale   string `wesgine:"mutable"`
    // ...
}

标签	含义
`immutable`	创建后不可变
`mutable`	可通过 UpdateSpec 修改
`restricted`	有条件修改

SpecPatch

部分更新 CellSpec：

hyp.Cells().UpdateSpec(ctx, cellID, SpecPatch{
    Quotas:     &newQuotas,
    Governance: &newGov,
})

SpecPatch 只包含 mutable/restricted 字段。

安全默认值

场景	默认行为
未声明 Governance	`DefaultGovernance()` = `ModeOpen`
未声明 ProviderStrategy	单侧非空自动推导
未声明 Quotas	合理默认配额
未声明 CycleDetect	默认阈值