Merge pull request #499 from Cai-Tang-www/feat/issue-488-hook-core-origin-main

feat(runtime/hooks): 实现 #488 的 P0 Hook Core 基础设施

Author: phantom5099

internal/runtime/hooks/context.go

@@ -0,0 +1,96 @@
+package hooks
+
+import "reflect"
+
+// HookContext 是 hook 执行时可见的通用上下文快照。
+type HookContext struct {
+	RunID     string
+	SessionID string
+	Metadata  map[string]any
+}
+
+// Clone 返回 HookContext 的安全副本，避免元数据被跨 hook 共享修改。
+func (c HookContext) Clone() HookContext {
+	if len(c.Metadata) == 0 {
+		return c
+	}
+	cloned := c
+	cloned.Metadata = make(map[string]any, len(c.Metadata))
+	for key, value := range c.Metadata {
+		cloned.Metadata[key] = cloneMetadataValue(value)
+	}
+	return cloned
+}
+
+func cloneMetadataValue(value any) any {
+	if value == nil {
+		return nil
+	}
+	original := reflect.ValueOf(value)
+	cloned := deepCloneValue(original)
+	return cloned.Interface()
+}
+
+func deepCloneValue(value reflect.Value) reflect.Value {
+	if !value.IsValid() {
+		return value
+	}
+
+	switch value.Kind() {
+	case reflect.Pointer:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		pointer := reflect.New(value.Type().Elem())
+		pointer.Elem().Set(deepCloneValue(value.Elem()))
+		return pointer
+	case reflect.Interface:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		elem := deepCloneValue(value.Elem())
+		out := reflect.New(value.Type()).Elem()
+		out.Set(elem)
+		return out
+	case reflect.Map:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		clonedMap := reflect.MakeMapWithSize(value.Type(), value.Len())
+		iter := value.MapRange()
+		for iter.Next() {
+			key := deepCloneValue(iter.Key())
+			val := deepCloneValue(iter.Value())
+			clonedMap.SetMapIndex(key, val)
+		}
+		return clonedMap
+	case reflect.Slice:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		clonedSlice := reflect.MakeSlice(value.Type(), value.Len(), value.Len())
+		for i := 0; i < value.Len(); i++ {
+			clonedSlice.Index(i).Set(deepCloneValue(value.Index(i)))
+		}
+		return clonedSlice
+	case reflect.Array:
+		clonedArray := reflect.New(value.Type()).Elem()
+		for i := 0; i < value.Len(); i++ {
+			clonedArray.Index(i).Set(deepCloneValue(value.Index(i)))
+		}
+		return clonedArray
+	case reflect.Struct:
+		clonedStruct := reflect.New(value.Type()).Elem()
+		clonedStruct.Set(value)
+		for i := 0; i < value.NumField(); i++ {
+			target := clonedStruct.Field(i)
+			if !target.CanSet() {
+				continue
+			}
+			target.Set(deepCloneValue(value.Field(i)))
+		}
+		return clonedStruct
+	default:
+		return value
+	}
+}

internal/runtime/hooks/context_test.go

@@ -0,0 +1,175 @@
+package hooks
+
+import (
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestHookContextCloneDeepCopyMetadata(t *testing.T) {
+	t.Parallel()
+
+	original := HookContext{
+		RunID:     "run-1",
+		SessionID: "session-1",
+		Metadata: map[string]any{
+			"slice": []any{"a", map[string]any{"k": "v"}},
+			"map":   map[string]any{"nested": []string{"x", "y"}},
+		},
+	}
+
+	cloned := original.Clone()
+	metadataSlice, ok := cloned.Metadata["slice"].([]any)
+	if !ok {
+		t.Fatalf("slice metadata type = %T, want []any", cloned.Metadata["slice"])
+	}
+	nestedMap, ok := metadataSlice[1].(map[string]any)
+	if !ok {
+		t.Fatalf("nested map type = %T, want map[string]any", metadataSlice[1])
+	}
+	nestedMap["k"] = "changed"
+
+	clonedMap, ok := cloned.Metadata["map"].(map[string]any)
+	if !ok {
+		t.Fatalf("map metadata type = %T, want map[string]any", cloned.Metadata["map"])
+	}
+	nestedSlice, ok := clonedMap["nested"].([]string)
+	if !ok {
+		t.Fatalf("nested slice type = %T, want []string", clonedMap["nested"])
+	}
+	nestedSlice[0] = "changed"
+
+	originalSlice := original.Metadata["slice"].([]any)
+	originalNestedMap := originalSlice[1].(map[string]any)
+	if got := originalNestedMap["k"]; got != "v" {
+		t.Fatalf("original nested map value = %v, want v", got)
+	}
+	originalMap := original.Metadata["map"].(map[string]any)
+	originalNestedSlice := originalMap["nested"].([]string)
+	if got := originalNestedSlice[0]; got != "x" {
+		t.Fatalf("original nested slice value = %q, want x", got)
+	}
+}
+
+func TestHookContextCloneDeepCopyStructFields(t *testing.T) {
+	t.Parallel()
+
+	type nested struct {
+		Flag bool
+	}
+	type metaPayload struct {
+		Attrs map[string]string
+		Items []int
+		Ref   *nested
+	}
+
+	original := HookContext{
+		Metadata: map[string]any{
+			"struct": metaPayload{
+				Attrs: map[string]string{"k": "v"},
+				Items: []int{1, 2, 3},
+				Ref:   &nested{Flag: true},
+			},
+		},
+	}
+
+	cloned := original.Clone()
+	payload, ok := cloned.Metadata["struct"].(metaPayload)
+	if !ok {
+		t.Fatalf("struct metadata type = %T, want metaPayload", cloned.Metadata["struct"])
+	}
+
+	payload.Attrs["k"] = "changed"
+	payload.Items[0] = 99
+	payload.Ref.Flag = false
+	cloned.Metadata["struct"] = payload
+
+	originPayload := original.Metadata["struct"].(metaPayload)
+	if got := originPayload.Attrs["k"]; got != "v" {
+		t.Fatalf("original Attrs[k] = %q, want v", got)
+	}
+	if got := originPayload.Items[0]; got != 1 {
+		t.Fatalf("original Items[0] = %d, want 1", got)
+	}
+	if got := originPayload.Ref.Flag; got != true {
+		t.Fatalf("original Ref.Flag = %v, want true", got)
+	}
+}
+
+func TestHookContextCloneNoMetadata(t *testing.T) {
+	t.Parallel()
+
+	original := HookContext{RunID: "run-1", SessionID: "session-1"}
+	cloned := original.Clone()
+	if cloned.RunID != original.RunID || cloned.SessionID != original.SessionID {
+		t.Fatalf("Clone() basic fields mismatch: got %+v, want %+v", cloned, original)
+	}
+	if cloned.Metadata != nil {
+		t.Fatalf("Clone().Metadata = %#v, want nil", cloned.Metadata)
+	}
+}
+
+func TestCloneMetadataValueNil(t *testing.T) {
+	t.Parallel()
+
+	if got := cloneMetadataValue(nil); got != nil {
+		t.Fatalf("cloneMetadataValue(nil) = %#v, want nil", got)
+	}
+}
+
+func TestDeepCloneValueEdgeCases(t *testing.T) {
+	t.Parallel()
+
+	invalid := deepCloneValue(reflect.Value{})
+	if invalid.IsValid() {
+		t.Fatalf("deepCloneValue(invalid).IsValid() = true, want false")
+	}
+
+	var nilPtr *int
+	clonedNilPtr := deepCloneValue(reflect.ValueOf(nilPtr))
+	if !clonedNilPtr.IsNil() {
+		t.Fatalf("cloned nil pointer should be nil")
+	}
+
+	var nilMap map[string]int
+	clonedNilMap := deepCloneValue(reflect.ValueOf(nilMap))
+	if !clonedNilMap.IsNil() {
+		t.Fatalf("cloned nil map should be nil")
+	}
+
+	var nilSlice []int
+	clonedNilSlice := deepCloneValue(reflect.ValueOf(nilSlice))
+	if !clonedNilSlice.IsNil() {
+		t.Fatalf("cloned nil slice should be nil")
+	}
+
+	// 走到 interface nil 分支。
+	nilIfaceValue := reflect.New(reflect.TypeOf((*any)(nil)).Elem()).Elem()
+	clonedNilIface := deepCloneValue(nilIfaceValue)
+	if !clonedNilIface.IsNil() {
+		t.Fatalf("cloned nil interface should be nil")
+	}
+
+	arr := [2]map[string]int{
+		{"a": 1},
+		{"b": 2},
+	}
+	clonedArr := deepCloneValue(reflect.ValueOf(arr)).Interface().([2]map[string]int)
+	clonedArr[0]["a"] = 99
+	if arr[0]["a"] != 1 {
+		t.Fatalf("array nested map shared, got %d, want 1", arr[0]["a"])
+	}
+
+	// time.Time 的内部字段不可 set，可覆盖 struct 分支中的 CanSet=false 路径。
+	valueWithTime := struct {
+		When time.Time
+	}{
+		When: time.Now(),
+	}
+	clonedWithTime := deepCloneValue(reflect.ValueOf(valueWithTime)).Interface().(struct {
+		When time.Time
+	})
+	if !clonedWithTime.When.Equal(valueWithTime.When) {
+		t.Fatalf("cloned struct with time mismatch")
+	}
+}

internal/runtime/hooks/errors.go

@@ -0,0 +1,20 @@
+package hooks
+
+import (
+	"errors"
+	"fmt"
+)
+
+var (
+	// ErrHookAlreadyExists 表示注册了重复 hook ID。
+	ErrHookAlreadyExists = errors.New("hook already exists")
+	// ErrHookNotFound 表示待删除 hook 不存在。
+	ErrHookNotFound = errors.New("hook not found")
+	// ErrInvalidHookSpec 表示 HookSpec 未通过校验。
+	ErrInvalidHookSpec = errors.New("invalid hook spec")
+)
+
+// wrapInvalidSpec 将参数化错误统一包装为 ErrInvalidHookSpec。
+func wrapInvalidSpec(format string, args ...any) error {
+	return fmt.Errorf("%w: %s", ErrInvalidHookSpec, fmt.Sprintf(format, args...))
+}

internal/runtime/hooks/events.go

@@ -0,0 +1,37 @@
+package hooks
+
+import (
+	"context"
+	"time"
+)
+
+// HookEventType 标识 hook 事件类型。
+type HookEventType string
+
+const (
+	// HookEventStarted 表示 hook 执行开始事件。
+	HookEventStarted HookEventType = "hook_started"
+	// HookEventFinished 表示 hook 执行结束事件（pass/block）。
+	HookEventFinished HookEventType = "hook_finished"
+	// HookEventFailed 表示 hook 执行失败事件。
+	HookEventFailed HookEventType = "hook_failed"
+)
+
+// HookEvent 描述 hook 执行过程中的结构化事件。
+type HookEvent struct {
+	Type       HookEventType
+	HookID     string
+	Point      HookPoint
+	Scope      HookScope
+	Kind       HookKind
+	Mode       HookMode
+	Status     HookResultStatus
+	StartedAt  time.Time
+	DurationMS int64
+	Error      string
+}
+
+// EventEmitter 抽象 hook 事件发射器，避免依赖 runtime.Service。
+type EventEmitter interface {
+	EmitHookEvent(ctx context.Context, event HookEvent) error
+}