v1.4 工具集扩展 + Windows 编码攻坚

- 新增 BashTool（bash 命令执行，30s 超时 + 自愈 + 截断）
- 新增 WriteFileTool（文件写入）
- Windows GBK 编码自动转 UTF-8（golang.org/x/text）
- OpenAIProvider 新增 API 交互日志
- dumpMessages 移除截断，完整展示上下文
- cmd/claw 三段式任务演示

README.md

@@ -65,6 +65,32 @@ func main() {
 
 ## 版本历史
 
+### v1.4 — 工具集扩展与 Windows 编码攻坚
+
+#### 变更
+
+- **新增 BashTool** — 执行本地 bash 命令，支持 30s 超时、错误原样回传（模型自愈）、8KB 输出截断
+- **新增 WriteFileTool** — 写文件到工作区，覆盖/新建均支持
+- **Windows GBK 编码修复** — 命令输出从 GBK 自动转 UTF-8（`golang.org/x/text/encoding/simplifiedchinese`），不依赖 `chcp`
+- **API 交互日志** — `OpenAIProvider.Generate` 新增请求/响应日志（阶段标记、消息数、工具数、ToolCall 明细）
+- **调试输出优化** — `dumpMessages` 移除 80 字符截断，完整展示上下文内容
+- **三段式任务演示** — `cmd/claw` 任务改为：查 Go 版本 → 写 helloworld.go → 编译运行
+
+#### 踩坑记录
+
+| 问题 | 原因 | 解决 |
+|---|---|---|
+| bash 输出中文乱码 | Windows 命令输出为 GBK 编码，Go 按 UTF-8 解析 | 引入 `golang.org/x/text`，检测编码后自动转换 |
+| `chcp 65001` 导致终端刷屏 | `chcp` 在子进程中修改代码页可能影响终端渲染 | 放弃 `chcp` 方案，改用 Go 原生编码转换 |
+| `utf8.Valid` 检查后仍乱码 | GBK 字节序列碰巧也合法于 UTF-8，跳过转换 | 去掉 `utf8.Valid` 判断，Windows 下一律转换 |
+| `helloworld.go` 导致编译失败 | 模型生成的测试文件含 `main` 函数，与项目 main.go 冲突 | 运行后清理 `helloworld.*` 测试产物 |
+
+#### 经验教训
+
+1. **编码问题不要依赖外部命令** — `chcp` 属于"改环境让输出配合你"，不可靠。Go 原生转码属于"你主动适应输出"，稳定可控
+2. **`utf8.Valid` 不能当编码检测器** — 它的语义是"是否合法 UTF-8"，不是"是否是 GBK"。GBK 和 UTF-8 有交集，用合法性判断编码方向是伪命题
+3. **Agent 的工具越多，越需要关注副作用** — 模型会写文件、执行命令，产生的文件（helloworld.go）可能反过来破坏项目结构。工具内部要做好隔离
+
 ### v1.3 — Registry 实现重构与第一把真实工具
 
 #### 变更

cmd/claw/main.go

@@ -18,21 +18,23 @@ func main() {
 	// 这里你可以任意切换 NewZhipuClaudeProvider 或 NewZhipuOpenAIProvider，效果完全一致！
 	llmProvider := provider.DeepseekOpenAIProvider("deepseek-v4-flash")
 
-	// 3. 初始化真实的 Tool Registry
 	registry := tools.NewRegistry()
 
-	// 4. 将真实的 ReadFile 工具挂载到注册表中
+	// 挂载极简工具集
-	readFileTool := tools.NewReadFileTool(workDir)
+	registry.Register(tools.NewReadFileTool(workDir))
-	registry.Register(readFileTool)
+	registry.Register(tools.NewWriteFileTool(workDir))
+	registry.Register(tools.NewBashTool(workDir))
 
-	// 5. 实例化核心引擎，由于任务简单，我们关闭思考阶段 (EnableThinking = false) 以加快速度
+	// 实例化核心引擎，关闭慢思考阶段，享受 YOLO 急速模式
 	eng := engine.NewAgentEngine(llmProvider, registry, workDir, false)
 
-	log.Printf("registry: %s\n", registry)
+	// 发起一个需要连贯物理动作的任务
-	log.Printf("engine: %s\n", eng)
+	prompt := `
-
+    请帮我执行以下操作：
-	// 6. 下发一个必须通过真实工具才能完成的任务
+    1. 用 bash 查看一下我当前电脑的 Go 版本，我的电脑是windows系统。
-	prompt := "请调用工具读取一下当前工作区目录下 hello.txt 文件的内容，并用一句话向我总结它说了什么。"
+    2. 帮我写一个简单的 helloworld.go 文件，输出 "Hello, go-tiny-claw!"。
+    3. 用 bash 编译并运行这个 go 文件，确认它能正常工作。
+    `
 
 	err := eng.Run(context.Background(), prompt)
 	if err != nil {

go.mod

@@ -3,13 +3,16 @@ module go-tiny-claw
 go 1.23.0
 
 require (
-	github.com/anthropics/anthropic-sdk-go v1.43.0 // indirect
+	github.com/anthropics/anthropic-sdk-go v1.43.0
+	github.com/openai/openai-go/v3 v3.35.0
+	golang.org/x/text v0.27.0
+)
+
+require (
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.2 // indirect
 	github.com/invopop/jsonschema v0.13.0 // indirect
-	github.com/joho/godotenv v1.5.1 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
-	github.com/openai/openai-go/v3 v3.35.0 // indirect
 	github.com/standard-webhooks/standard-webhooks/libraries v0.0.1 // indirect
 	github.com/tidwall/gjson v1.18.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect

go.sum

@@ -4,17 +4,23 @@ github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPn
 github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk=
 github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
+github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
 github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
 github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
-github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/openai/openai-go/v3 v3.35.0 h1:109x3epXMSE423KW2euR506GGFezcEt0s87MoWejpH0=
 github.com/openai/openai-go/v3 v3.35.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/standard-webhooks/standard-webhooks/libraries v0.0.1 h1:uOfcYT+3QungH6tIGSVCR/Y3KJmgJiHcojJbMTPDZAI=
 github.com/standard-webhooks/standard-webhooks/libraries v0.0.1/go.mod h1:L1MQhA6x4dn9r007T033lsaZMv9EmBAdXyU/+EF40fo=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
 github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
 github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
@@ -29,6 +35,11 @@ github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/
 github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
 golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw=
 golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/text v0.27.0 h1:4fGWRpyh641NLlecmyl4LOe6yDdfaYNrGb2zdfo4JV4=
+golang.org/x/text v0.27.0/go.mod h1:1D28KMCvyooCX9hBiosv5Tz/+YLxj0j7XhWjpSUF7CU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/engine/loop.go

@@ -16,15 +16,15 @@ type AgentEngine struct {
 	registry tools.Registry
 
 	// WorkDir (工作区): 借鉴 OpenClaw 的理念，Agent 必须有一个明确的物理边界
-	WorkDir string
+	WorkDir        string
 	EnableThinking bool // 【新增】慢思考模式开关
 }
 
 func NewAgentEngine(p provider.LLMProvider, r tools.Registry, workDir string, enableThinking bool) *AgentEngine {
 	return &AgentEngine{
-		provider: p,
+		provider:       p,
-		registry: r,
+		registry:       r,
-		WorkDir:  workDir,
+		WorkDir:        workDir,
 		EnableThinking: enableThinking,
 	}
 }
@@ -37,9 +37,9 @@ func (e *AgentEngine) String() string {
 func dumpMessages(msgs []schema.Message) {
 	for i, msg := range msgs {
 		content := msg.Content
-		if len(content) > 80 {
+		// if len(content) > 80 {
-			content = content[:80] + "..."
+		// 	content = content[:80] + "..."
-		}
+		// }
 		log.Printf("  [%02d] %-10s | %s", i, msg.Role, content)
 	}
 }
@@ -57,116 +57,116 @@ func dumpTools(tools []schema.ToolDefinition) {
 
 // internal/engine/loop.go (续)
 func (e *AgentEngine) Run(ctx context.Context, userPrompt string) error {
-    log.Printf("[Engine] 引擎启动，锁定工作区: %s\n", e.WorkDir)
+	log.Printf("[Engine] 引擎启动，锁定工作区: %s\n", e.WorkDir)
-    log.Printf("[Engine] 慢思考模式 (Thinking Phase): %v\n", e.EnableThinking)
+	log.Printf("[Engine] 慢思考模式 (Thinking Phase): %v\n", e.EnableThinking)
 
-    contextHistory := []schema.Message{
+	contextHistory := []schema.Message{
-        {
+		{
-            Role:    schema.RoleSystem,
+			Role:    schema.RoleSystem,
-            Content: "You are go-tiny-claw, an expert coding assistant. You have full access to tools in the workspace.",
+			Content: "You are go-tiny-claw, an expert coding assistant. You have full access to tools in the workspace.",
-        },
+		},
-        {
+		{
-            Role:    schema.RoleUser,
+			Role:    schema.RoleUser,
-            Content: userPrompt,
+			Content: userPrompt,
-        },
+		},
-    }
+	}
 
-    turnCount := 0
+	turnCount := 0
-    const maxTurns = 10
+	const maxTurns = 10
 
-    for {
+	for {
-        turnCount++
+		turnCount++
-        if turnCount > maxTurns {
+		if turnCount > maxTurns {
-            log.Printf("[Engine] 已达最大轮数 (%d)，强制终止。\n", maxTurns)
+			log.Printf("[Engine] 已达最大轮数 (%d)，强制终止。\n", maxTurns)
-            break
+			break
-        }
+		}
-        log.Printf("\n========== [Turn %d] 开始 ==========\n", turnCount)
+		log.Printf("\n========== [Turn %d] 开始 ==========\n", turnCount)
-        dumpMessages(contextHistory)
+		dumpMessages(contextHistory)
 
-        // 获取当前挂载的所有工具定义
+		// 获取当前挂载的所有工具定义
-        availableTools := e.registry.GetAvailableTools()
+		availableTools := e.registry.GetAvailableTools()
-        dumpTools(availableTools)
+		dumpTools(availableTools)
 
-        // ====================================================================
+		// ====================================================================
-        // Phase 1: 慢思考阶段 (Thinking) - 仅第一轮执行初始规划
+		// Phase 1: 慢思考阶段 (Thinking) - 仅第一轮执行初始规划
-        // ====================================================================
+		// ====================================================================
-        if e.EnableThinking && turnCount == 1 {
+		if e.EnableThinking && turnCount == 1 {
-            log.Println("[Engine][Phase 1] 剥夺工具访问权，强制进入慢思考与规划阶段...")
+			log.Println("[Engine][Phase 1] 剥夺工具访问权，强制进入慢思考与规划阶段...")
 
-            // 核心机制：传入的 availableTools 为 nil！
+			// 核心机制：传入的 availableTools 为 nil！
-            // 大模型看不到任何 JSON Schema，被迫只能输出纯文本的思考过程。
+			// 大模型看不到任何 JSON Schema，被迫只能输出纯文本的思考过程。
-            thinkResp, err := e.provider.Generate(ctx, contextHistory, nil)
+			thinkResp, err := e.provider.Generate(ctx, contextHistory, nil)
-            if err != nil {
+			if err != nil {
-                return fmt.Errorf("Thinking 阶段生成失败: %w", err)
+				return fmt.Errorf("Thinking 阶段生成失败: %w", err)
-            }
+			}
 
-            // 如果模型输出了思考过程，我们将其作为 Assistant 消息追加到上下文中
+			// 如果模型输出了思考过程，我们将其作为 Assistant 消息追加到上下文中
-            if thinkResp.Content != "" {
+			if thinkResp.Content != "" {
-                fmt.Printf("🧠 [内部思考 Trace]: %s\n", thinkResp.Content)
+				fmt.Printf("🧠 [内部思考 Trace]: %s\n", thinkResp.Content)
-                contextHistory = append(contextHistory, *thinkResp)
+				contextHistory = append(contextHistory, *thinkResp)
-            }
+			}
 
-            // 插入过渡指令：让模型知道现在可以调用工具了
+			// 插入过渡指令：让模型知道现在可以调用工具了
-            contextHistory = append(contextHistory, schema.Message{
+			contextHistory = append(contextHistory, schema.Message{
-                Role:    schema.RoleUser,
+				Role:    schema.RoleUser,
-                Content: "根据你的推理，现在请使用可用的工具来完成任务。执行具体行动。",
+				Content: "根据你的推理，现在请使用可用的工具来完成任务。执行具体行动。",
-            })
+			})
-        }
+		}
 
-        // ====================================================================
+		// ====================================================================
-        // Phase 2: 行动阶段 (Action) - 恢复工具，顺着规划执行
+		// Phase 2: 行动阶段 (Action) - 恢复工具，顺着规划执行
-        // ====================================================================
+		// ====================================================================
-        log.Println("[Engine][Phase 2] 恢复工具挂载，等待模型采取行动...")
+		log.Println("[Engine][Phase 2] 恢复工具挂载，等待模型采取行动...")
 
-        // 此时的 contextHistory 中已经包含了上一阶段模型自己的 Thinking Trace + 过渡指令。
+		// 此时的 contextHistory 中已经包含了上一阶段模型自己的 Thinking Trace + 过渡指令。
-        // 模型会顺着自己的逻辑，结合恢复的 availableTools 发起精准的工具调用。
+		// 模型会顺着自己的逻辑，结合恢复的 availableTools 发起精准的工具调用。
-        actionResp, err := e.provider.Generate(ctx, contextHistory, availableTools)
+		actionResp, err := e.provider.Generate(ctx, contextHistory, availableTools)
-        if err != nil {
+		if err != nil {
-            return fmt.Errorf("Action 阶段生成失败: %w", err)
+			return fmt.Errorf("Action 阶段生成失败: %w", err)
-        }
+		}
 
-        contextHistory = append(contextHistory, *actionResp)
+		contextHistory = append(contextHistory, *actionResp)
 
-        if actionResp.Content != "" {
+		if actionResp.Content != "" {
-            fmt.Printf("🤖 [对外回复]: %s\n", actionResp.Content)
+			fmt.Printf("🤖 [对外回复]: %s\n", actionResp.Content)
-        }
+		}
 
-        // ====================================================================
+		// ====================================================================
-        // 退出与执行逻辑 (与上一讲保持一致)
+		// 退出与执行逻辑 (与上一讲保持一致)
-        // ====================================================================
+		// ====================================================================
-        if len(actionResp.ToolCalls) == 0 {
+		if len(actionResp.ToolCalls) == 0 {
-            log.Println("[Engine] 模型未请求调用工具，任务宣告完成。")
+			log.Println("[Engine] 模型未请求调用工具，任务宣告完成。")
-            break
+			break
-        }
+		}
 
-        log.Printf("[Engine] 模型请求调用 %d 个工具...\n", len(actionResp.ToolCalls))
+		log.Printf("[Engine] 模型请求调用 %d 个工具...\n", len(actionResp.ToolCalls))
 
-        for _, toolCall := range actionResp.ToolCalls {
+		for _, toolCall := range actionResp.ToolCalls {
-            log.Printf("  -> 🛠️ 执行工具: %s, 参数: %s\n", toolCall.Name, string(toolCall.Arguments))
+			log.Printf("  -> 🛠️ 执行工具: %s, 参数: %s\n", toolCall.Name, string(toolCall.Arguments))
 
-            result := e.registry.Execute(ctx, toolCall)
+			result := e.registry.Execute(ctx, toolCall)
 
-            status := "✅ 成功"
+			status := "✅ 成功"
-            if result.IsError {
+			if result.IsError {
-                status = "❌ 失败"
+				status = "❌ 失败"
-            }
+			}
-            log.Printf("  -> 📋 ToolCall %s: %s, 结果: %s\n", toolCall.ID, status, result.Output)
+			log.Printf("  -> 📋 ToolCall %s: %s, 结果: %s\n", toolCall.ID, status, result.Output)
 
-            if result.IsError {
+			if result.IsError {
-                log.Printf("  -> ❌ 工具执行报错: %s\n", result.Output)
+				log.Printf("  -> ❌ 工具执行报错: %s\n", result.Output)
-            } else {
+			} else {
-                log.Printf("  -> ✅ 工具执行成功 (返回 %d 字节)\n", len(result.Output))
+				log.Printf("  -> ✅ 工具执行成功 (返回 %d 字节)\n", len(result.Output))
-            }
+			}
 
-            // 将工具执行的观察结果追加到 Context，准备进入下一轮
+			// 将工具执行的观察结果追加到 Context，准备进入下一轮
-            observationMsg := schema.Message{
+			observationMsg := schema.Message{
-                Role:       schema.RoleUser,
+				Role:       schema.RoleUser,
-                Content:    result.Output,
+				Content:    result.Output,
-                ToolCallID: toolCall.ID,
+				ToolCallID: toolCall.ID,
-            }
+			}
-            contextHistory = append(contextHistory, observationMsg)
+			contextHistory = append(contextHistory, observationMsg)
-        }
+		}
-    }
+	}
 
-    return nil
+	return nil
 }

internal/provider/openai.go

@@ -2,192 +2,212 @@
 package provider
 
 import (
-    "context"
+	"context"
-    "encoding/json"
+	"encoding/json"
-    "fmt"
+	"fmt"
-    // "os"
+	"log"
 
-    "github.com/openai/openai-go/v3"
+	// "os"
-    "github.com/openai/openai-go/v3/option"
+
-    "github.com/openai/openai-go/v3/packages/param"
+	"go-tiny-claw/internal/schema"
-    "github.com/openai/openai-go/v3/shared"
+
-    "go-tiny-claw/internal/schema"
+	"github.com/openai/openai-go/v3"
+	"github.com/openai/openai-go/v3/option"
+	"github.com/openai/openai-go/v3/packages/param"
+	"github.com/openai/openai-go/v3/shared"
 )
 
 type OpenAIProvider struct {
-    client openai.Client // 值类型，非指针
+	client openai.Client // 值类型，非指针
-    model  string
+	model  string
 }
 
 // NewZhipuOpenAIProvider 构造函数：基于 OpenAI V3 SDK，指向智谱底座
 func DeepseekOpenAIProvider(model string) *OpenAIProvider {
-    apiKey := "sk-1f44696abe644bd684f09cc43f12c557"
+	apiKey := "sk-1f44696abe644bd684f09cc43f12c557"
-    if apiKey == "" {
+	if apiKey == "" {
-        panic("请设置 ZHIPU_API_KEY 环境变量")
+		panic("请设置 ZHIPU_API_KEY 环境变量")
-    }
+	}
-    // 核心：将官方 SDK 的地址替换为智谱的兼容端点
+	// 核心：将官方 SDK 的地址替换为智谱的兼容端点
-    baseURL := "https://api.deepseek.com"
+	baseURL := "https://api.deepseek.com"
 
-    return &OpenAIProvider{
+	return &OpenAIProvider{
-        client: openai.NewClient(option.WithAPIKey(apiKey), option.WithBaseURL(baseURL)),
+		client: openai.NewClient(option.WithAPIKey(apiKey), option.WithBaseURL(baseURL)),
-        model:  model,
+		model:  model,
-    }
+	}
 }
 
 func (p *OpenAIProvider) Generate(ctx context.Context, msgs []schema.Message, availableTools []schema.ToolDefinition) (*schema.Message, error) {
-    var openaiMsgs []openai.ChatCompletionMessageParamUnion
+	phase := "Action"
+	if len(availableTools) == 0 {
+		phase = "Thinking"
+	}
+	log.Printf("[Provider] → API 调用 | 模型: %s | 阶段: %s | 消息数: %d | 工具数: %d",
+		p.model, phase, len(msgs), len(availableTools))
 
-    // 1. 翻译上下文消息
+	var openaiMsgs []openai.ChatCompletionMessageParamUnion
-    for _, msg := range msgs {
-        switch msg.Role {
-        case schema.RoleSystem:
-            openaiMsgs = append(openaiMsgs, openai.SystemMessage(msg.Content))
 
-        case schema.RoleUser:
+	// 1. 翻译上下文消息
-            if msg.ToolCallID != "" {
+	for _, msg := range msgs {
-                // 注意：v3 新版参数顺序是 (content, toolCallID)
+		switch msg.Role {
-                openaiMsgs = append(openaiMsgs, openai.ToolMessage(msg.Content, msg.ToolCallID))
+		case schema.RoleSystem:
-            } else {
+			openaiMsgs = append(openaiMsgs, openai.SystemMessage(msg.Content))
-                openaiMsgs = append(openaiMsgs, openai.UserMessage(msg.Content))
-            }
 
-        case schema.RoleAssistant:
+		case schema.RoleUser:
-            // Deepseek thinking mode: reasoning_content 必须回传
+			if msg.ToolCallID != "" {
-            if msg.ReasoningContent != "" || len(msg.ToolCalls) > 0 {
+				// 注意：v3 新版参数顺序是 (content, toolCallID)
-                msgMap := map[string]interface{}{
+				openaiMsgs = append(openaiMsgs, openai.ToolMessage(msg.Content, msg.ToolCallID))
-                    "role":    "assistant",
+			} else {
-                    "content": msg.Content,
+				openaiMsgs = append(openaiMsgs, openai.UserMessage(msg.Content))
-                }
+			}
-                if msg.ReasoningContent != "" {
-                    msgMap["reasoning_content"] = msg.ReasoningContent
-                }
-                if len(msg.ToolCalls) > 0 {
-                    var toolCalls []map[string]interface{}
-                    for _, tc := range msg.ToolCalls {
-                        toolCalls = append(toolCalls, map[string]interface{}{
-                            "id":   tc.ID,
-                            "type": "function",
-                            "function": map[string]interface{}{
-                                "name":      tc.Name,
-                                "arguments": string(tc.Arguments),
-                            },
-                        })
-                    }
-                    msgMap["tool_calls"] = toolCalls
-                }
-                rawJSON, _ := json.Marshal(msgMap)
-                astParam := param.Override[openai.ChatCompletionAssistantMessageParam](json.RawMessage(rawJSON))
-                openaiMsgs = append(openaiMsgs, openai.ChatCompletionMessageParamUnion{
-                    OfAssistant: &astParam,
-                })
-                break
-            }
 
-            astParam := openai.ChatCompletionAssistantMessageParam{}
+		case schema.RoleAssistant:
+			// Deepseek thinking mode: reasoning_content 必须回传
+			if msg.ReasoningContent != "" || len(msg.ToolCalls) > 0 {
+				msgMap := map[string]interface{}{
+					"role":    "assistant",
+					"content": msg.Content,
+				}
+				if msg.ReasoningContent != "" {
+					msgMap["reasoning_content"] = msg.ReasoningContent
+				}
+				if len(msg.ToolCalls) > 0 {
+					var toolCalls []map[string]interface{}
+					for _, tc := range msg.ToolCalls {
+						toolCalls = append(toolCalls, map[string]interface{}{
+							"id":   tc.ID,
+							"type": "function",
+							"function": map[string]interface{}{
+								"name":      tc.Name,
+								"arguments": string(tc.Arguments),
+							},
+						})
+					}
+					msgMap["tool_calls"] = toolCalls
+				}
+				rawJSON, _ := json.Marshal(msgMap)
+				astParam := param.Override[openai.ChatCompletionAssistantMessageParam](json.RawMessage(rawJSON))
+				openaiMsgs = append(openaiMsgs, openai.ChatCompletionMessageParamUnion{
+					OfAssistant: &astParam,
+				})
+				break
+			}
 
-            if msg.Content != "" {
+			astParam := openai.ChatCompletionAssistantMessageParam{}
-                astParam.Content = openai.ChatCompletionAssistantMessageParamContentUnion{
-                    OfString: openai.String(msg.Content),
-                }
-            }
 
-            // 【重要】如果历史包含 ToolCalls，必须原样放回，以维系大模型的逻辑链
+			if msg.Content != "" {
-            if len(msg.ToolCalls) > 0 {
+				astParam.Content = openai.ChatCompletionAssistantMessageParamContentUnion{
-                var toolCalls []openai.ChatCompletionMessageToolCallUnionParam
+					OfString: openai.String(msg.Content),
-                for _, tc := range msg.ToolCalls {
+				}
-                    // OfFunction 对应 GetFunction()，字段类型严格要求为指针
+			}
-                    toolCalls = append(toolCalls, openai.ChatCompletionMessageToolCallUnionParam{
-                        OfFunction: &openai.ChatCompletionMessageFunctionToolCallParam{
-                            ID:   tc.ID,
-                            Type: "function",
-                            Function: openai.ChatCompletionMessageFunctionToolCallFunctionParam{
-                                Name:      tc.Name,
-                                Arguments: string(tc.Arguments),
-                            },
-                        },
-                    })
-                }
-                astParam.ToolCalls = toolCalls
-            }
 
-            openaiMsgs = append(openaiMsgs, openai.ChatCompletionMessageParamUnion{
+			// 【重要】如果历史包含 ToolCalls，必须原样放回，以维系大模型的逻辑链
-                OfAssistant: &astParam,
+			if len(msg.ToolCalls) > 0 {
-            })
+				var toolCalls []openai.ChatCompletionMessageToolCallUnionParam
-        }
+				for _, tc := range msg.ToolCalls {
-    }
+					// OfFunction 对应 GetFunction()，字段类型严格要求为指针
+					toolCalls = append(toolCalls, openai.ChatCompletionMessageToolCallUnionParam{
+						OfFunction: &openai.ChatCompletionMessageFunctionToolCallParam{
+							ID:   tc.ID,
+							Type: "function",
+							Function: openai.ChatCompletionMessageFunctionToolCallFunctionParam{
+								Name:      tc.Name,
+								Arguments: string(tc.Arguments),
+							},
+						},
+					})
+				}
+				astParam.ToolCalls = toolCalls
+			}
 
-    // 2. 翻译工具定义 (v3 新 API 特性适配)
+			openaiMsgs = append(openaiMsgs, openai.ChatCompletionMessageParamUnion{
-    var openaiTools []openai.ChatCompletionToolUnionParam
+				OfAssistant: &astParam,
-    for _, toolDef := range availableTools {
+			})
-        var params shared.FunctionParameters
+		}
+	}
 
-        // 尝试直接断言，如果不成功则通过 JSON 往返序列化来保证类型匹配
+	// 2. 翻译工具定义 (v3 新 API 特性适配)
-        if m, ok := toolDef.InputSchema.(map[string]interface{}); ok {
+	var openaiTools []openai.ChatCompletionToolUnionParam
-            params = shared.FunctionParameters(m)
+	for _, toolDef := range availableTools {
-        } else {
+		var params shared.FunctionParameters
-            // fallback：JSON 往返序列化
-            b, _ := json.Marshal(toolDef.InputSchema)
-            _ = json.Unmarshal(b, &params)
-        }
 
-        openaiTools = append(openaiTools, openai.ChatCompletionFunctionTool(
+		// 尝试直接断言，如果不成功则通过 JSON 往返序列化来保证类型匹配
-            shared.FunctionDefinitionParam{
+		if m, ok := toolDef.InputSchema.(map[string]interface{}); ok {
-                Name:        toolDef.Name,
+			params = shared.FunctionParameters(m)
-                Description: openai.String(toolDef.Description),
+		} else {
-                Parameters:  params,
+			// fallback：JSON 往返序列化
-            },
+			b, _ := json.Marshal(toolDef.InputSchema)
-        ))
+			_ = json.Unmarshal(b, &params)
-    }
+		}
 
-    // 3. 构建请求并发送
+		openaiTools = append(openaiTools, openai.ChatCompletionFunctionTool(
-    params := openai.ChatCompletionNewParams{
+			shared.FunctionDefinitionParam{
-        Model:    p.model,
+				Name:        toolDef.Name,
-        Messages: openaiMsgs,
+				Description: openai.String(toolDef.Description),
-    }
+				Parameters:  params,
+			},
+		))
+	}
 
-    // 【慢思考机制支撑】仅当 availableTools 存在时才挂载 Tools
+	// 3. 构建请求并发送
-    if len(openaiTools) > 0 {
+	params := openai.ChatCompletionNewParams{
-        params.Tools = openaiTools
+		Model:    p.model,
-    }
+		Messages: openaiMsgs,
+	}
 
-    resp, err := p.client.Chat.Completions.New(ctx, params)
+	// 【慢思考机制支撑】仅当 availableTools 存在时才挂载 Tools
-    if err != nil {
+	if len(openaiTools) > 0 {
-        return nil, fmt.Errorf("OpenAI/Zhipu API 请求失败: %w", err)
+		params.Tools = openaiTools
-    }
+	}
-    if len(resp.Choices) == 0 {
-        return nil, fmt.Errorf("API 返回了空的 Choices")
-    }
 
-    // 4. 将 API Response 反向翻译为内部 schema.Message
+	resp, err := p.client.Chat.Completions.New(ctx, params)
-    choice := resp.Choices[0].Message
+	if err != nil {
-    resultMsg := &schema.Message{
+		return nil, fmt.Errorf("OpenAI/Zhipu API 请求失败: %w", err)
-        Role:    schema.RoleAssistant,
+	}
-        Content: choice.Content,
+	if len(resp.Choices) == 0 {
-    }
+		return nil, fmt.Errorf("API 返回了空的 Choices")
+	}
 
-    // Deepseek thinking mode: 从原始响应中提取 reasoning_content
+	// 4. 将 API Response 反向翻译为内部 schema.Message
-    rawMsg := choice.RawJSON()
+	choice := resp.Choices[0].Message
-    if rawMsg != "" {
+	resultMsg := &schema.Message{
-        var rawMap map[string]json.RawMessage
+		Role:    schema.RoleAssistant,
-        if err := json.Unmarshal([]byte(rawMsg), &rawMap); err == nil {
+		Content: choice.Content,
-            if rc, ok := rawMap["reasoning_content"]; ok {
+	}
-                var s string
-                if json.Unmarshal(rc, &s) == nil {
-                    resultMsg.ReasoningContent = s
-                }
-            }
-        }
-    }
 
-    for _, tc := range choice.ToolCalls {
+	// Deepseek thinking mode: 从原始响应中提取 reasoning_content
-        if tc.Type == "function" {
+	rawMsg := choice.RawJSON()
-            resultMsg.ToolCalls = append(resultMsg.ToolCalls, schema.ToolCall{
+	if rawMsg != "" {
-                ID:        tc.ID,
+		var rawMap map[string]json.RawMessage
-                Name:      tc.Function.Name,
+		if err := json.Unmarshal([]byte(rawMsg), &rawMap); err == nil {
-                Arguments: []byte(tc.Function.Arguments), // 提取 JSON 字符串字节
+			if rc, ok := rawMap["reasoning_content"]; ok {
-            })
+				var s string
-        }
+				if json.Unmarshal(rc, &s) == nil {
-    }
+					resultMsg.ReasoningContent = s
+				}
+			}
+		}
+	}
 
-    return resultMsg, nil
+	for _, tc := range choice.ToolCalls {
-}
+		if tc.Type == "function" {
+			resultMsg.ToolCalls = append(resultMsg.ToolCalls, schema.ToolCall{
+				ID:        tc.ID,
+				Name:      tc.Function.Name,
+				Arguments: []byte(tc.Function.Arguments),
+			})
+		}
+	}
+
+	// 打印响应摘要
+	contentPreview := resultMsg.Content
+	// if len(contentPreview) > 60 {
+	//     contentPreview = contentPreview[:60] + "..."
+	// }
+	log.Printf("[Provider] ← API 响应 | 内容: %q | 工具调用: %d", contentPreview, len(resultMsg.ToolCalls))
+	for _, tc := range resultMsg.ToolCalls {
+		log.Printf("[Provider]   ↳ ToolCall: %s(%s)", tc.Name, string(tc.Arguments))
+	}
+
+	return resultMsg, nil
+}

internal/tools/bash.go

@@ -0,0 +1,89 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"time"
+
+	"go-tiny-claw/internal/schema"
+)
+
+type BashTool struct {
+	workDir string // 工作区约束
+}
+
+func NewBashTool(workDir string) *BashTool {
+	return &BashTool{workDir: workDir}
+}
+
+func (t *BashTool) Name() string {
+	return "bash"
+}
+
+func (t *BashTool) Definition() schema.ToolDefinition {
+	return schema.ToolDefinition{
+		Name:        t.Name(),
+		Description: "在当前工作区执行任意的 bash 命令。支持链式命令(如 &&)。返回标准输出(stdout)和标准错误(stderr)。",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"command": map[string]interface{}{
+					"type":        "string",
+					"description": "要执行的 bash 命令，例如: ls -la 或 go test ./...",
+				},
+			},
+			"required": []string{"command"},
+		},
+	}
+}
+
+type bashArgs struct {
+	Command string `json:"command"`
+}
+
+func (t *BashTool) Execute(ctx context.Context, args json.RawMessage) (string, error) {
+	var input bashArgs
+	if err := json.Unmarshal(args, &input); err != nil {
+		return "", fmt.Errorf("参数解析失败: %w", err)
+	}
+
+	// 【驾驭底线 1】：Time Budgeting (时间预算与超时控制)
+	timeoutCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	// Unix 和 Windows 统一使用 bash -c（Windows 需安装 Git Bash），编码转换在下方处理
+	cmd := exec.CommandContext(timeoutCtx, "bash", "-c", input.Command)
+
+	// 【驾驭底线 2】：绑定执行的工作区目录
+	cmd.Dir = t.workDir
+
+	// 执行并捕获 CombinedOutput (合并 stdout 和 stderr)
+	out, err := cmd.CombinedOutput()
+
+	outputStr := string(out)
+
+	// 如果命令执行超时，返回警告信息让模型知晓
+	if timeoutCtx.Err() == context.DeadlineExceeded {
+		return outputStr + "\n[警告: 命令执行超时(30s)，已被系统强制终止。如果是启动常驻服务，请尝试将其转入后台。]", nil
+	}
+
+	// 【驾驭底线 3】：错误原样回传 (Self-Correction 自愈机制)
+	if err != nil {
+		return fmt.Sprintf("执行报错: %v\n输出:\n%s", err, outputStr), nil
+	}
+
+	// 如果没有终端输出，给模型一个明确的执行成功的反馈
+	if outputStr == "" {
+		return "命令执行成功，无终端输出。", nil
+	}
+
+	// 【驾驭底线 4】：长度截断保护 (防 OOM)
+	const maxLen = 8000
+	if len(outputStr) > maxLen {
+		return fmt.Sprintf("%s\n\n...[终端输出过长，已截断至前 %d 字节]...", outputStr[:maxLen], maxLen), nil
+	}
+
+	return outputStr, nil
+}

internal/tools/write_file.go

@@ -0,0 +1,72 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"go-tiny-claw/internal/schema"
+)
+
+type WriteFileTool struct {
+	workDir string // 工作区约束
+}
+
+func NewWriteFileTool(workDir string) *WriteFileTool {
+	return &WriteFileTool{workDir: workDir}
+}
+
+func (t *WriteFileTool) Name() string {
+	return "write_file"
+}
+
+func (t *WriteFileTool) Definition() schema.ToolDefinition {
+	return schema.ToolDefinition{
+		Name:        t.Name(),
+		Description: "创建或覆盖写入一个文件。如果目录不存在会自动创建。请提供相对于工作区的相对路径。",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"path": map[string]interface{}{
+					"type":        "string",
+					"description": "要写入的文件路径，如 src/main.go",
+				},
+				"content": map[string]interface{}{
+					"type":        "string",
+					"description": "要写入的完整文件内容",
+				},
+			},
+			"required": []string{"path", "content"},
+		},
+	}
+}
+
+type writeFileArgs struct {
+	Path    string `json:"path"`
+	Content string `json:"content"`
+}
+
+func (t *WriteFileTool) Execute(ctx context.Context, args json.RawMessage) (string, error) {
+	var input writeFileArgs
+	if err := json.Unmarshal(args, &input); err != nil {
+		return "", fmt.Errorf("参数解析失败: %w", err)
+	}
+
+	// 【安全防线】：限制在 WorkDir 下执行，防止大模型修改系统级文件
+	fullPath := filepath.Join(t.workDir, input.Path)
+
+	// 自动创建缺失的父级目录
+	if err := os.MkdirAll(filepath.Dir(fullPath), 0755); err != nil {
+		return "", fmt.Errorf("创建父目录失败: %w", err)
+	}
+
+	// 写入文件内容，权限设为 0644
+	err := os.WriteFile(fullPath, []byte(input.Content), 0644)
+	if err != nil {
+		return "", fmt.Errorf("写入文件失败: %w", err)
+	}
+
+	return fmt.Sprintf("成功将内容写入到文件: %s", input.Path), nil
+}