CellSpec SDK Hooks

wesgine CellSpec 中 SDK Hook 字段的声明式配置。

概述

SDK Hooks 是消费方（wescode / wesclaw / wescraft）在 GetOrCreate 前注入到 CellSpec 的 json:"-" 进程回调，不落盘、不序列化。

HostEnvironment

宿主环境 hook，由消费方提供 IDE/桌面能力：

spec.HostEnvironment = &HostEnvironment{
    Files:  overlayFileProvider,  // Buffer overlay
    Shell:  terminalManager,      // exec 路由
    Editor: editorState,          // 焦点文件/光标
}

wescode 使用此 hook 透明注入 IDE 能力（零 tool schema footprint）。

QualityGate

质量门回调，Run 中 edit/write 后自动验证：

spec.QualityGate = func(ctx context.Context, result EditResult) error {
    // 运行测试、lint 等验证
    return nil
}

用于 wescode 的渐进验证（L0→L2.5）。

EditPatrol

编辑巡逻回调：

spec.EditPatrol = func(ctx context.Context, edit EditEvent) {
    // 追踪编辑事件
}

用于约束满足引擎（CSE）检查。

FileSegmenter

文件分段器，用于智能文件切分：

spec.FileSegmenter = func(path string, content []byte) []Segment {
    // tree-sitter 解析
    return segments
}

wescode 注入 tree-sitter 分段能力。

EditMatchFallback

编辑匹配回退策略：

spec.EditMatchFallback = func(ctx context.Context, req EditRequest) (*EditResult, error) {
    // 三级匹配回退
    return result, nil
}

wescode 的编辑引擎三级匹配。

ToolExecutorHooks

工具执行回调：

spec.ToolExecutorHooks = &ToolExecutorHooks{
    BeforeExec: func(ctx context.Context, tool string, args map[string]any) error {
        return nil
    },
    AfterExec: func(ctx context.Context, tool string, result string) {
        // 记录工具使用
    },
}

OnStarted

Cell 启动后回调：

spec.OnStarted = func(ctx context.Context, cell *Cell) error {
    // 注册自定义工具
    // seed 技能
    return nil
}

在 GetOrCreate 成功后、Cell 可用前执行。

PostRunFn

Run 结束后回调：

spec.PostRunFn = func(ctx context.Context, runID string, outcome RunOutcome) {
    // 记录 Run 结果
    // 更新统计
}

ProviderLiveKeyFn

动态凭据获取回调（有 wes:/org: 时必填）：

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

落盘了 wes:/org:（SourceLive）却不绑 live-key getter → EnsureActive fail-loud（INV-CELL-08）。

AppIdentity

应用身份标识：

spec.AppIdentity = &AppIdentity{
    Name:    "wescode",
    Version: "1.0.0",
}

Hook 绑定时机

所有 Hook 必须在 GetOrCreate 之前绑定到 CellSpec：

// 正确顺序
spec.ProviderLiveKeyFn = liveTokens.Key
spec.HostEnvironment = host
spec.OnStarted = onStarted
cell, err := hyp.Cells().GetOrCreate(ctx, spec) // Hook 在此生效

ActivatePersisted 前不得调用——会用残缺 spec 打开数据面。