CellSpec SDK Hook 详解

wesgine 的 CellSpec 包含多个 json:"-" 标记的 SDK Hook 字段，这些字段不持久化，由消费方在 GetOrCreate 之前绑定。

Hook 字段一览

Hook	类型	用途
`OnStarted`	`func(cell)`	Cell 启动完成后回调
`PostRunFn`	`func(cell, result)`	每次 Run 结束后回调
`HostEnvironment`	`HostEnv`	宿主环境能力注入（文件覆盖、终端路由）
`AppIdentity`	`AppID`	应用标识注入（名称、版本）
`FileSegmenter`	`Segmenter`	自定义文件分段策略
`EditMatchFallback`	`Matcher`	编辑匹配降级策略
`ToolExecutorHooks`	`Hooks`	工具执行前后拦截
`QualityGate`	`Gate`	输出质量验证门控
`EditPatrol`	`Patrol`	编辑合规巡查
`ProviderLiveKeyFn`	`func(name) key`	实时密钥获取（`wes:` / `org:` provider）

ProviderLiveKeyFn（INV-CELL-08）

最关键的 Hook。当 CellSpec 中存在 source: live 的 Provider 时，此函数必须在 GetOrCreate 前绑定：

liveTokens := &providerid.LiveTokenSource{}
spec.ProviderLiveKeyFn = liveTokens.Key

// 登录后绑定 JWT accessor
liveTokens.Bind(auth.IdentityAccessToken, auth.ValidAccessToken)

cell, err := hyp.Cells().GetOrCreate(ctx, spec) // 内部 EnsureActive 会检查

缺失此 Hook → EnsureActive fail-loud 拒绝启动 Cell。

HostEnvironment

消费方注入宿主设备能力：

spec.HostEnvironment = &deviceagent.Host{
    Files:  overlayFileProvider,  // 编辑器 buffer 覆盖 read 工具
    Shell:  terminalRouter,       // exec 路由（静默/验证/交互）
    Editor: editorState,          // 焦点文件、光标位置
}

wescode：注入 IDE buffer overlay + 终端三分类路由
wesclaw：注入 Device Agent MCP 能力
wescraft：注入文件智能索引能力

QualityGate

允许消费方在 Agent 产出结果后进行质量验证：

wescode：L0 编译检查、L1 lint 检查、L2 测试验证
其他产品可自定义验证逻辑
验证失败 → Agent 收到反馈可修正

EditPatrol

编辑巡查在 Agent 执行 write/edit 操作后自动触发：

检查格式合规
检查内容一致性
发现问题 → 注入纠正指令

Hook 绑定时机

NewHypervisor(config)
    ↓
hyp.Start(ctx)          // 只挂身份骨架
    ↓
spec.ProviderLiveKeyFn = ...  // ★ 在这里绑定所有 Hook
spec.HostEnvironment = ...
spec.OnStarted = ...
    ↓
hyp.Cells().GetOrCreate(ctx, spec)  // EnsureActive 检查 Hook

禁止在 GetOrCreate 之后再绑定 Hook——那时 Cell 已启动，Hook 不会生效。