CellSpec 迁移指南

SpecPatch 的使用方法、字段可变性约束、热更新行为、Compliance 变更影响和降级态 secret 保护。

CellSpec 字段可变性

CellSpec 字段通过 wesgine:"immutable|mutable|restricted" tag 标注可变性。

immutable 字段（创建后不可变）

字段	说明
`ID`	Cell 标识符
`Timezone`	时区

修改 immutable 字段 → 需要删除并重新创建 Cell。

mutable 字段（可通过 SpecPatch 热更新）

字段	说明
`Locale`	语言区域
`Governance`	治理策略
`Quotas`	配额
`ProviderStrategy`	Provider 策略
`AllowedModels`	允许的模型
`DenyPaths`	禁止访问路径

restricted 字段（需要特定条件）

某些字段的变更需要 Cell Stop 后重新 Start 才能生效。

使用 SpecPatch

SDK 方式

err := hyp.Cells().UpdateSpec(ctx, "dept-legal", wesgine.SpecPatch{
    Governance: &newGovernance,
    Quotas:     &newQuotas,
})

HTTP 方式

PATCH /admin/cells/{id}
Content-Type: application/json

{
  "governance": {
    "mode": "locked",
    "deny_paths": ["/etc/secrets"],
    "network_policy": "internal_only"
  },
  "quotas": {
    "max_concurrent_runs": 5
  }
}

Compliance 变更的影响范围

Compliance 只决定什么

决定	示例
`RedactorRules`	自动脱敏规则
`GuardrailsRequired`	是否需要 guardrails

Compliance 不决定什么

不决定	由谁管理
`DenyPaths`	preset 注入 + 显式 `CellSpec.DenyPaths`
`GovernMode`	preset 映射 + 可独立覆盖

INV-GOV-COMPLIANCE-02：UpdateSpec(Compliance:) 热切只 swap RedactorRules，不增删 DenyPaths。创建时用 preset 注入的 DenyPaths 在降级/升级后保持稳定。

预设映射

预设	Mode	NetworkPolicy	Redactor
`StandardPreset()`	open	allow	无
`RegulatedPreset()`	locked	internal_only	按场景
`ReadonlyPreset()`	locked	deny	无

治理策略热更新

PUT /cells/{cellID}/config/governance
Content-Type: application/json

{
  "mode": "locked",
  "deny_paths": ["/credentials", "/var/secrets"],
  "network_policy": "internal_only"
}

Governance 变更立即生效，无需重启 Cell。

降级态 Secret 保护（INV-PERSIST-07）

当 spec.key 丢失时，引擎降级挂载 Cell，记录 degradedSecrets 台账。

写入保护

降级态下的写入被三扇门保护：

门	行为
`persistCellSpec`	拒绝，除非本次写入填回所有台账点名的字段
`Cells().Create`	纯 INSERT，够不到已存在的行
`convergePersistedSpec`	原样保留 `SealedOriginals`

写入请求 → 检查 degradedSecrets[spec.ID]
  ↓ 台账有记录
  检查本次写入是否把每个点名字段带非空值填回
  ↓ 未填回
  返回 ErrDegradedSecretOverwrite (409)

恢复流程

恢复 {DataDir}/secrets/spec.key
通过 API 重新配置 Provider（带非空 API Key）
写入成功 → 台账自动清除

关键：写成功后必须重算台账——漏了这步，重填凭据后下一次不相干的编辑仍被拒。

Cell 重启

POST /admin/cells/{id}/restart

重启会重新执行 Cell Boot（含 schema 迁移、Seed 播种等），但保留所有持久化数据。

故障重置

POST /admin/cells/{id}/reset-faults

重置 Cell 的故障计数器，恢复正常调度。

常见迁移场景

场景	操作
升级治理等级	`PATCH /admin/cells/{id}` 更新 Governance
调整配额	`PATCH /admin/cells/{id}` 更新 Quotas
切换 Provider 策略	`PATCH /admin/cells/{id}` 更新 ProviderStrategy
改时区	删除 Cell + 重新创建（immutable）
恢复丢失密钥	恢复 spec.key + 重新配置 Provider