v1.3 Registry 实现重构 + 第一把真实工具

- Registry 从纯接口升级为完整实现：Register/Execute/路由查找/错误自愈
- 新增 BaseTool 接口，统一工具契约
- 新增 ReadFileTool，首个真实工具实现（路径防穿越 + 截断保护）
- 新增 String() 方法，Registry/Engine 调试可视化
- 新增 ToolCall 执行状态日志
- cmd/claw 切换为真实 Registry + ReadFileTool

README.md

@@ -65,6 +65,31 @@ func main() {
 
 ## 版本历史
 
+### v1.3 — Registry 实现重构与第一把真实工具
+
+#### 变更
+
+- **Registry 完整实现** — 从纯接口升级为 `registryImpl`，基于 `map[string]BaseTool` 实现 O(1) 路由查找、动态注册、错误自愈
+- **BaseTool 接口** — 定义工具的通用契约（`Name()` / `Definition()` / `Execute()`），所有具体工具统一实现
+- **首个真实工具 ReadFileTool** — 支持读取工作区文件，含路径穿越防护和 8000 字节截断
+- **调试可视化** — `AgentEngine` 和 `registryImpl` 实现 `String()` 方法，替代 16 进制内存地址
+- **ToolCall 执行日志** — 每轮工具执行后输出一行状态日志（`📋 ToolCall xxx: ✅ / ❌, 结果: ...`）
+- **cmd/claw 真实化** — 从 mockRegistry 切换到 `tools.NewRegistry()` + `ReadFileTool`
+
+#### 踩坑记录
+
+| 问题 | 原因 | 解决 |
+|---|---|---|
+| `fmt.Println(registry)` 输出 16 进制地址 | Go 默认打印指针/接口类型为内存地址，不展示内容 | 实现 `fmt.Stringer` 接口，自定义 `String()` 方法 |
+| Registry 接口加 `Register` 后旧代码编译失败 | `main.go` 的 mockRegistry 没有实现新增的 `Register` 方法 | 为 mockRegistry 补充空实现 `Register(tool tools.BaseTool) {}` |
+| 修改代码时需要同时兼容旧 mock 和新实现 | demo 代码和正式代码共用同一套接口 | 保留 mock 的兼容性（无操作 Register），新演示代码使用真实实现 |
+
+#### 经验教训
+
+1. **接口先于实现，但实现要跟上** — v1.0 就定义了 `Registry` 接口，但一直没有真实实现，导致 cmd 只能靠 mock 跑。抽象要尽早落地
+2. **工具系统用 map 路由天然适合 Agent** — 大模型输出工具名 → 直接 map key 查找 → O(1) 路由，简单高效，也方便运行时动态挂载工具
+3. **`String()` 是 Go 调试的性价比之王** — 三行代码换来看日志时不用猜内存地址，投入产出比极高
+
 ### v1.2 — 真实模型接入与 Thinking 死循环修复
 
 #### 变更

cmd/claw/main.go

@@ -4,60 +4,35 @@ import (
 	"context"
 	"log"
 	"os"
-	"fmt"
 
 	"go-tiny-claw/internal/engine"
-	"go-tiny-claw/internal/schema"
 	"go-tiny-claw/internal/provider"
+	"go-tiny-claw/internal/tools"
 )
 
-
-// 伪造的工具注册表 (用于测试 Provider 的工具提取能力)
-type mockRegistry struct{}
-
-func (m *mockRegistry) GetAvailableTools() []schema.ToolDefinition {
-    return []schema.ToolDefinition{
-        {
-            Name:        "get_weather",
-            Description: "获取指定城市的当前天气情况。",
-            InputSchema: map[string]interface{}{
-                "type": "object",
-                "properties": map[string]interface{}{
-                    "city": map[string]interface{}{
-                        "type": "string",
-                    },
-                },
-                "required": []string{"city"},
-            },
-        },
-    }
-}
-
-func (m *mockRegistry) Execute(ctx context.Context, call schema.ToolCall) schema.ToolResult {
-    log.Printf("  -> [Mock 工具执行] 获取 %s 的天气中...\n", call.Name)
-    return schema.ToolResult{
-        ToolCallID: call.ID,
-        Output:     "API 返回：今天是晴天，气温 25 度。",
-        IsError:    false,
-    }
-}
-
 func main() {
 
-	fmt.Printf("11111")
 	workDir, _ := os.Getwd()
 
-    // 1. 初始化真实的 Provider大脑 (指向智谱 GLM-4.5)
+	// 1. 初始化真实的 Provider大脑
 	// 这里你可以任意切换 NewZhipuClaudeProvider 或 NewZhipuOpenAIProvider，效果完全一致！
 	llmProvider := provider.DeepseekOpenAIProvider("deepseek-v4-flash")
-    // 2. 注入伪造的工具注册表
-    registry := &mockRegistry{}
 
-    // 3. 实例化并运行引擎，开启 EnableThinking = true (开启慢思考阶段！)
-    eng := engine.NewAgentEngine(llmProvider, registry, workDir, true)
+	// 3. 初始化真实的 Tool Registry
+	registry := tools.NewRegistry()
 
-    // 设定测试任务
-    prompt := "我想去北京跑步，帮我查查天气适合吗？"
+	// 4. 将真实的 ReadFile 工具挂载到注册表中
+	readFileTool := tools.NewReadFileTool(workDir)
+	registry.Register(readFileTool)
+
+	// 5. 实例化核心引擎，由于任务简单，我们关闭思考阶段 (EnableThinking = false) 以加快速度
+	eng := engine.NewAgentEngine(llmProvider, registry, workDir, false)
+
+	log.Printf("registry: %s\n", registry)
+	log.Printf("engine: %s\n", eng)
+
+	// 6. 下发一个必须通过真实工具才能完成的任务
+	prompt := "请调用工具读取一下当前工作区目录下 hello.txt 文件的内容，并用一句话向我总结它说了什么。"
 
 	err := eng.Run(context.Background(), prompt)
 	if err != nil {

internal/engine/loop.go

@@ -29,6 +29,10 @@ func NewAgentEngine(p provider.LLMProvider, r tools.Registry, workDir string, en
 	}
 }
 
+func (e *AgentEngine) String() string {
+	return fmt.Sprintf("AgentEngine{workDir: %s, thinking: %v, registry: %s}", e.WorkDir, e.EnableThinking, e.registry)
+}
+
 // dumpMessages 打印当前上下文中的所有消息 (调试用)
 func dumpMessages(msgs []schema.Message) {
 	for i, msg := range msgs {
@@ -142,6 +146,12 @@ func (e *AgentEngine) Run(ctx context.Context, userPrompt string) error {
 
             result := e.registry.Execute(ctx, toolCall)
 
+            status := "✅ 成功"
+            if result.IsError {
+                status = "❌ 失败"
+            }
+            log.Printf("  -> 📋 ToolCall %s: %s, 结果: %s\n", toolCall.ID, status, result.Output)
+
             if result.IsError {
                 log.Printf("  -> ❌ 工具执行报错: %s\n", result.Output)
             } else {

internal/tools/read_file.go

@@ -0,0 +1,85 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"go-tiny-claw/internal/schema"
+)
+
+// ReadFileTool 实现了读取本地文件内容的工具
+type ReadFileTool struct {
+    // 将引擎的 WorkDir 注入给工具，限制它只能在此目录及其子目录下操作
+    workDir string 
+}
+
+func NewReadFileTool(workDir string) *ReadFileTool {
+    return &ReadFileTool{workDir: workDir}
+}
+
+func (t *ReadFileTool) Name() string {
+    return "read_file"
+}
+
+// Definition 向大模型清晰地描述这个工具的用途和参数格式
+func (t *ReadFileTool) Definition() schema.ToolDefinition {
+    return schema.ToolDefinition{
+        Name:        t.Name(),
+        Description: "读取指定路径的文件内容。请提供相对工作区的路径。",
+        // 遵循 JSON Schema 规范定义参数
+        InputSchema: map[string]interface{}{
+            "type": "object",
+            "properties": map[string]interface{}{
+                "path": map[string]interface{}{
+                    "type":        "string",
+                    "description": "要读取的文件路径，如 cmd/claw/main.go",
+                },
+            },
+            "required": []string{"path"},
+        },
+    }
+}
+
+// readFileArgs 内部定义用于反序列化的结构体
+type readFileArgs struct {
+    Path string `json:"path"`
+}
+
+func (t *ReadFileTool) Execute(ctx context.Context, args json.RawMessage) (string, error) {
+    // 1. 延迟解析：将大模型传过来的 JSON 参数解析为强类型结构体
+    var input readFileArgs
+    if err := json.Unmarshal(args, &input); err != nil {
+        // 返回 error 会被 Registry 捕获并传给大模型，模型会知道自己 JSON 格式写错了
+        return "", fmt.Errorf("参数解析失败: %w", err)
+    }
+
+    // 2. 拼接绝对路径 (注意：生产环境中需要做路径穿越检测防范，防止 ../../etc/passwd)
+    fullPath := filepath.Join(t.workDir, input.Path)
+
+    // 3. 执行物理 IO 操作
+    file, err := os.Open(fullPath)
+    if err != nil {
+        return "", fmt.Errorf("打开文件失败: %w", err)
+    }
+    defer file.Close()
+
+    content, err := io.ReadAll(file)
+    if err != nil {
+        return "", fmt.Errorf("读取文件内容失败: %w", err)
+    }
+
+    // 4. 【核心防线】长度截断保护
+    // 为了防止大模型读取几百 MB 的日志文件导致 Context 瞬间爆炸 (OOM)，
+    // 我们在工具内部直接进行物理截断。
+    const maxLen = 8000
+    if len(content) > maxLen {
+        truncatedMsg := fmt.Sprintf("%s\n\n...[由于内容过长，已被系统截断至前 %d 字节]...", string(content[:maxLen]), maxLen)
+        return truncatedMsg, nil
+    }
+
+    return string(content), nil
+}

internal/tools/registry.go

@@ -2,14 +2,103 @@ package tools
 
 import (
 	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+
 	"go-tiny-claw/internal/schema"
 )
 
-// Registry 定义了工具的注册与分发执行接口
+// BaseTool 是所有具体工具必须实现的通用接口
+type BaseTool interface {
+	// Name 返回工具的全局唯一名称 (大模型通过这个名字调用它)
+	Name() string
+
+	// Definition 返回用于提交给大模型的工具元信息和参数 JSON Schema
+	Definition() schema.ToolDefinition
+
+	// Execute 接收大模型吐出的 JSON 参数，执行具体业务逻辑
+	// 注意：参数是 json.RawMessage，反序列化由各个具体工具内部自行处理
+	Execute(ctx context.Context, args json.RawMessage) (string, error)
+}
+
+// Registry 定义了工具的注册与分发接口
 type Registry interface {
-	// GetAvailableTools 返回当前系统挂载的所有可用工具的 Schema
+	// Register 挂载一个新的工具到系统中
+	Register(tool BaseTool)
+
+	// GetAvailableTools 返回当前系统挂载的所有工具的 Schema，供 Main Loop 交给 Provider
 	GetAvailableTools() []schema.ToolDefinition
 
-	// Execute 实际执行模型请求的工具，并返回结果
+	// Execute 实际路由并执行模型请求的工具调用
 	Execute(ctx context.Context, call schema.ToolCall) schema.ToolResult
 }
+
+// registryImpl 是 Registry 接口的默认实现
+type registryImpl struct {
+	// 使用 map 以工具的 Name 作为 Key 进行快速 O(1) 路由查找
+	tools map[string]BaseTool
+}
+
+func NewRegistry() Registry {
+	return &registryImpl{
+		tools: make(map[string]BaseTool),
+	}
+}
+
+func (r *registryImpl) String() string {
+	var names []string
+	for name := range r.tools {
+		names = append(names, name)
+	}
+	return fmt.Sprintf("Registry{tools: %v}", names)
+}
+
+func (r *registryImpl) Register(tool BaseTool) {
+	name := tool.Name()
+	if _, exists := r.tools[name]; exists {
+		log.Printf("[Warning] 工具 '%s' 已经被注册，将被覆盖。\n", name)
+	}
+	r.tools[name] = tool
+	log.Printf("[Registry] 成功挂载工具: %s\n", name)
+}
+
+func (r *registryImpl) GetAvailableTools() []schema.ToolDefinition {
+	var defs []schema.ToolDefinition
+	for _, tool := range r.tools {
+		defs = append(defs, tool.Definition())
+	}
+	return defs
+}
+
+func (r *registryImpl) Execute(ctx context.Context, call schema.ToolCall) schema.ToolResult {
+	// 1. 路由查找：如果在注册表中找不到该工具，这是模型产生了幻觉，直接向模型抛出错误
+	tool, exists := r.tools[call.Name]
+	if !exists {
+		errMsg := fmt.Sprintf("Error: 系统中不存在名为 '%s' 的工具。", call.Name)
+		return schema.ToolResult{
+			ToolCallID: call.ID,
+			Output:     errMsg,
+			IsError:    true, // 标记为错误，模型看到后会尝试纠正
+		}
+	}
+
+	// 2. 执行工具逻辑：将原始的 JSON 字节流直接丢给具体工具
+	output, err := tool.Execute(ctx, call.Arguments)
+
+	// 3. 封装结果：将执行结果或底层物理错误封装后返回给 Main Loop
+	if err != nil {
+		errMsg := fmt.Sprintf("Error executing %s: %v", call.Name, err)
+		return schema.ToolResult{
+			ToolCallID: call.ID,
+			Output:     errMsg,
+			IsError:    true,
+		}
+	}
+
+	return schema.ToolResult{
+		ToolCallID: call.ID,
+		Output:     output,
+		IsError:    false,
+	}
+}

main.go

@@ -7,6 +7,7 @@ import (
 
 	"go-tiny-claw/internal/engine"
 	"go-tiny-claw/internal/schema"
+	"go-tiny-claw/internal/tools"
 )
 
 // mockProvider 模拟大模型推理
@@ -36,6 +37,8 @@ type mockRegistry struct{}
 
 func (m *mockRegistry) GetAvailableTools() []schema.ToolDefinition { return nil }
 
+func (m *mockRegistry) Register(tool tools.BaseTool) {}
+
 func (m *mockRegistry) Execute(ctx context.Context, call schema.ToolCall) schema.ToolResult {
 	return schema.ToolResult{
 		ToolCallID: call.ID,