三层回退恢复机制（L0写前留档/L1恢复梯子/L2离线回滚）+ guard 父守护

- L0: files 插件写受保护系统路径(/etc 等)前自动留档，AbstractBeforeWrite 到 data/file_baseline - L1: failback 受限 worker 执行恢复梯子 probe→还原DNS/proxy→还原LLM配置+ReloadFromConfig→probe，N轮有界 - L2: tracker changeset 持久化原文 blob，guard 离线 RollbackFromDisk 回滚 agentfs；SystemSnapshot 支撑 - guard 父守护: 心跳 IPC(PING/ACK unix socket, 文件心跳回退)、失败计数、退出码协议(42/43/44)、最后手段 - 发行版路径适配: system.protected_paths/network_paths 可注入，默认面向主流 Linux - Windows 兼容: guard.go/failback.go 加 //go:build linux, guard_windows.go 提供 no-op 桩 - 修复: guard.yaml last_resort 键冲突、changeset Content 不落盘导致离线回滚丢原文 Build 全绿, vet 干净, system/recovery/ipc/tracker 单元测试全过
2026-10-03 07:43:58 +00:00 · 2026-08-05 16:00:08 +08:00
parent fc614477ed
commit d08ed3312e
28 changed files with 3675 additions and 167 deletions
--- a/internal/config/registry.go
+++ b/internal/config/registry.go
@ -2,7 +2,10 @@ package config

 import (
 	"database/sql"
+	"encoding/json"
 	"fmt"
+	"log"
+	"os"
 	"path/filepath"
 	"sort"
 	"strconv"
@ -28,10 +31,11 @@ type ConfigDef struct {
 }

 type ConfigRegistry struct {
-	mu     sync.RWMutex
-	db     *sql.DB
-	dbPath string
-	defs   map[string]*ConfigDef
+	mu          sync.RWMutex
+	db          *sql.DB
+	dbPath      string
+	defs        map[string]*ConfigDef
+	llmSnapFile string
 }

 func NewConfigRegistry(dbPath string) *ConfigRegistry {
@ -265,6 +269,9 @@ func (r *ConfigRegistry) Get(key string) (interface{}, error) {
 func (r *ConfigRegistry) Set(key string, value interface{}) error {
 	r.mu.Lock()
 	defer r.mu.Unlock()
+	if strings.HasPrefix(key, "core.llm.") {
+		r.writeLLMSnapshotLocked()
+	}
 	_, err := r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`, key, fmt.Sprint(value))
 	if err == nil && strings.HasPrefix(key, "core.llm.sources.") {
 		rest := strings.TrimPrefix(key, "core.llm.sources.")
@ -303,6 +310,107 @@ func (r *ConfigRegistry) Delete(key string) error {
 	return err
 }

+// SnapshotCoreLLM 捕获全部 core.llm.* 键值（LLM 源密度快照），供写前留档。
+// 返回值是 key→value 的不可变拷贝；写入 guard 配置恢复的基线。
+func (r *ConfigRegistry) SnapshotCoreLLM() map[string]string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return r.listPrefixLocked("core.llm.")
+}
+
+// SetLLMSnapshotFile 设定写前留档文件：此后任意写入 core.llm.* 键时，
+// 先把当前 llm 配置整体快照到该文件（guard 恢复的外部基线）。
+func (r *ConfigRegistry) SetLLMSnapshotFile(path string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if path != "" {
+		r.writeLLMSnapshotToFileLocked(path)
+	}
+	r.llmSnapFile = path
+}
+
+// writeLLMSnapshotLocked 调用方须持有写锁；若已配置快照文件则写入当前 llm 快照。
+func (r *ConfigRegistry) writeLLMSnapshotLocked() {
+	if r.llmSnapFile == "" {
+		return
+	}
+	r.writeLLMSnapshotToFileLocked(r.llmSnapFile)
+}
+
+func (r *ConfigRegistry) writeLLMSnapshotToFileLocked(path string) {
+	snap := r.listPrefixLocked("core.llm.")
+	if err := SaveLLMSnapshot(path, snap); err != nil {
+		log.Printf("[config] save llm snapshot %s: %v", path, err)
+	}
+}
+
+// RestoreCoreLLM 精确还原到快照状态：快照里有的键回写旧值，
+// 当前存在但快照里没有的 core.llm.* 键删除（保持与快照一致）。
+func (r *ConfigRegistry) RestoreCoreLLM(snap map[string]string) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	current := r.listPrefixLocked("core.llm.")
+	seen := make(map[string]bool, len(snap))
+	for k, v := range snap {
+		seen[k] = true
+		if _, err := r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`, k, v); err != nil {
+			return err
+		}
+	}
+	for k := range current {
+		if seen[k] {
+			continue
+		}
+		if _, err := r.db.Exec(`DELETE FROM config WHERE key = ?`, k); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// SaveLLMSnapshot 把 LLM 快照持久化到文件（guard 恢复的外部基线）。
+func SaveLLMSnapshot(path string, snap map[string]string) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(snap, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, data, 0600)
+}
+
+// LoadLLMSnapshot 从文件读回 LLM 快照。
+func LoadLLMSnapshot(path string) (map[string]string, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	snap := make(map[string]string)
+	if err := json.Unmarshal(data, &snap); err != nil {
+		return nil, err
+	}
+	return snap, nil
+}
+
+// listPrefixLocked 调用方须持有锁；返回 prefix 开头的全部键值。
+func (r *ConfigRegistry) listPrefixLocked(prefix string) map[string]string {
+	out := make(map[string]string)
+	rows, err := r.db.Query(`SELECT key, value FROM config WHERE key LIKE ? ORDER BY key`, prefix+"%")
+	if err != nil {
+		return out
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var k, v string
+		if err := rows.Scan(&k, &v); err == nil {
+			out[k] = v
+		}
+	}
+	return out
+}
+
 func (r *ConfigRegistry) Dump() map[string]interface{} {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
@ -464,6 +572,7 @@ func (r *ConfigRegistry) seedCoreDefs(dataDir string) {
 	reg(ConfigDef{Key: "core.daemon.heartbeat_interval", Default: "15s", Type: "duration", DisplayName: "心跳间隔", Description: "Agent 心跳检查间隔", Category: "daemon"})
 	reg(ConfigDef{Key: "core.daemon.check_interval", Default: "30s", Type: "duration", DisplayName: "检查间隔", Description: "网络状态检查间隔", Category: "daemon"})
 	reg(ConfigDef{Key: "core.daemon.log_level", Default: "info", Type: "select", DisplayName: "日志级别", Description: "日志输出级别", Options: []string{"debug", "info", "warn", "error"}, Category: "daemon"})
+	reg(ConfigDef{Key: "core.defaults.llm_endpoints", Default: "", Type: "string", DisplayName: "探活端点", Description: "健康检查的 LLM 探活端点，逗号分隔；留空自动取 LLM 源 base_url", Category: "daemon"})

 	reg(ConfigDef{Key: "core.llm.provider", Default: "deepseek", Type: "string", DisplayName: "默认提供商", Description: "默认 LLM 提供商名称，需匹配 sources 中的定义", Category: "llm"})
 	reg(ConfigDef{Key: "core.llm.model", Default: "deepseek-v4-flash", Type: "string", DisplayName: "默认模型", Description: "默认 LLM 模型名称", Category: "llm"})
@ -698,6 +807,23 @@ func (r *ConfigRegistry) ToConfig() *types.Config {

 	cfg.Plugin.Dir = read("core.plugin.dir", cfg.Plugin.Dir)

+	// 探活端点：优先显式配置，缺省取 LLM 源 base_url（去重），保证健康检查有实际目标
+	if eps := read("core.defaults.llm_endpoints", ""); eps != "" {
+		for _, ep := range strings.Split(eps, ",") {
+			if ep = strings.TrimSpace(ep); ep != "" {
+				cfg.Defaults.LLMEndpoints = append(cfg.Defaults.LLMEndpoints, ep)
+			}
+		}
+	} else {
+		seen := make(map[string]bool)
+		for _, src := range cfg.LLM.Sources {
+			if src.BaseURL != "" && !seen[src.BaseURL] {
+				seen[src.BaseURL] = true
+				cfg.Defaults.LLMEndpoints = append(cfg.Defaults.LLMEndpoints, src.BaseURL)
+			}
+		}
+	}
+
 	cfg.InputProcessing.Image.FallbackProvider = read("core.input_processing.image.fallback_provider", cfg.InputProcessing.Image.FallbackProvider)
 	cfg.InputProcessing.Image.FallbackModel = read("core.input_processing.image.fallback_model", cfg.InputProcessing.Image.FallbackModel)
 	cfg.InputProcessing.Image.DescribePrompt = read("core.input_processing.image.describe_prompt", cfg.InputProcessing.Image.DescribePrompt)
--- a/internal/config/registry_test.go
+++ b/internal/config/registry_test.go
@ -220,3 +220,73 @@ func TestGetHelpers(t *testing.T) {
 		t.Fatalf("GetBool fallback: expected true, got %v", got)
 	}
 }
+
+func TestSnapshotRestoreCoreLLM(t *testing.T) {
+	r := NewConfigRegistry("")
+	defer r.Close()
+
+	r.Set("core.llm.sources.main.base_url", "https://a")
+	r.Set("core.llm.sources.main.model", "m1")
+	r.Set("core.llm.sources.main.api_key", "k1")
+
+	snap := r.SnapshotCoreLLM()
+	if len(snap) != 3 {
+		t.Fatalf("expected 3 keys, got %d: %v", len(snap), snap)
+	}
+
+	// 模拟写坏
+	r.Set("core.llm.sources.main.base_url", "https://broken")
+	r.Set("core.llm.sources.main.api_key", "hacked")
+	r.Set("core.llm.sources.extra.model", "intruder")
+
+	if err := r.RestoreCoreLLM(snap); err != nil {
+		t.Fatalf("RestoreCoreLLM: %v", err)
+	}
+	got := r.SnapshotCoreLLM()
+	if len(got) != 3 {
+		t.Fatalf("after restore expected 3 keys, got %d: %v", len(got), got)
+	}
+	for k, v := range snap {
+		if got[k] != v {
+			t.Errorf("key %s: want %q got %q", k, v, got[k])
+		}
+	}
+}
+
+func TestLLMSnapshotFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "llm_snapshot.json")
+	snap := map[string]string{"core.llm.sources.main.base_url": "https://a", "core.llm.sources.main.model": "m1"}
+	if err := SaveLLMSnapshot(path, snap); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+	got, err := LoadLLMSnapshot(path)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if got["core.llm.sources.main.base_url"] != "https://a" || got["core.llm.sources.main.model"] != "m1" {
+		t.Fatalf("round-trip mismatch: %v", got)
+	}
+}
+
+func TestSetLLMSnapshotFile(t *testing.T) {
+	r := NewConfigRegistry("")
+	defer r.Close()
+	r.Set("core.llm.sources.main.base_url", "https://orig")
+	r.Set("core.llm.sources.main.model", "m0")
+
+	path := filepath.Join(t.TempDir(), "llm_pre.json")
+	r.SetLLMSnapshotFile(path)
+	// 再次写入：写前自动留档应记录当前值 orig/m0，随后才被覆盖
+	r.Set("core.llm.sources.main.base_url", "https://broken")
+
+	got, err := LoadLLMSnapshot(path)
+	if err != nil {
+		t.Fatalf("Load snapshot: %v", err)
+	}
+	if got["core.llm.sources.main.base_url"] != "https://orig" {
+		t.Fatalf("write-ahead snapshot should record pre-write value, got %q", got["core.llm.sources.main.base_url"])
+	}
+	if got["core.llm.sources.main.model"] != "m0" {
+		t.Fatalf("snapshot missing untouched key model: %v", got)
+	}
+}