go-tiny-claw/README.md

go-tiny-claw

一个轻量级的 AI Agent 引擎，基于 Go 语言实现标准的 ReAct（Reasoning + Acting） 循环模式。

项目背景

go-tiny-claw 受 Claude / OpenAI 的 Agent 概念启发，旨在提供一个简洁、可扩展的微型 Agent 框架核心。它定义了 Agent 与大模型交互的标准契约，让开发者可以快速搭建自己的 AI 助手应用。

核心架构

┌─────────────────────────────────────────────┐
│                AgentEngine                   │
│  ┌──────────┐    ┌──────────┐               │
│  │LLMProvider│    │ Registry │               │
│  └─────┬────┘    └─────┬────┘               │
│        │               │                    │
│        ▼               ▼                    │
│  大模型推理服务     本地工具执行              │
└─────────────────────────────────────────────┘

模块说明

包	说明
internal/engine	AgentEngine — 核心驱动，实现 ReAct 主循环
internal/provider	LLMProvider 接口 — 与大模型通信的统一契约
internal/schema	核心数据结构定义（Message、ToolCall、ToolResult）
internal/tools	Registry 接口 — 工具的注册与分发执行

ReAct 循环流程

1. 系统初始化 Context，注入用户指令
2. 向大模型发起推理请求（含可用工具列表）
3. 模型返回文本回复和/或工具调用请求
4. 如果模型未请求工具调用 → 任务完成，退出循环
5. 执行模型请求的工具，获取 Observation
6. 将 Observation 追加到上下文，回到步骤 2

快速开始

package main

import (
    "context"
    "go-tiny-claw/internal/engine"
    "go-tiny-claw/internal/schema"
)

func main() {
    provider := &mockProvider{}
    registry := &mockRegistry{}
    eng := engine.NewAgentEngine(provider, registry, "/path/to/workdir")
    eng.Run(context.Background(), "你的指令")
}

扩展

• 替换 Provider: 实现 LLMProvider 接口即可接入任意大模型（OpenAI、Claude、本地模型等）
• 注册工具: 实现 Registry 接口即可挂载自定义工具集（bash、文件操作、代码搜索等）
• 自定义 Schema: 基于 schema 包的数据结构可灵活扩展消息格式和工具定义

版本历史

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 死循环修复

变更

• 接入真实大模型 — 新增 OpenAIProvider 和 ClaudeProvider，分别基于 OpenAI V3 SDK 和 Anthropic SDK 连接 Deepseek API，替换原有的 Mock Provider
• Deepseek thinking 模式适配 — 修正 reasoning_content 字段丢失导致的 API 400 错误，在 schema.Message 中新增字段并在请求中回传
• Thinking 死循环修复 — 过渡指令只在首轮插入，防止模型每轮重复调用工具
• 最大轮数保护 — 新增 maxTurns = 10 上限，防止意外死循环
• 调试输出 — 新增 dumpMessages 和 dumpTools，每轮打印上下文消息和工具列表

踩坑记录

问题	原因	解决
API 400: reasoning_content must be passed back	Deepseek thinking 模式返回了 reasoning_content 字段，回传请求时未携带	从响应 RawJSON 中提取该字段，用 param.Override 注入原始 JSON 回传
模型在 Phase 2 不调用工具	Phase 1 的思考内容作为 Assistant 消息追加后，模型认为对话已结束	在思考后插入一条 User 角色过渡指令："根据推理，使用工具完成任务"
引擎死循环跑到 maxTurns	过渡指令每轮都插入，模型每轮都被要求调用工具	过渡指令只在 turnCount == 1 时插入，后续轮次模型根据观察结果自行判断

经验教训

1. 上下文即状态 — Agent 的所有行为都由上下文驱动。插入一条消息就能改变模型行为，不需要改代码逻辑
2. 非标准 API 字段需手动处理 — 大模型厂商的扩展字段（如 reasoning_content）不在 SDK 类型中，需要从 RawJSON 手动提取并用注入方式回传
3. 过渡指令的作用域很重要 — "使用工具"这种指令适合在首轮引导，重复出现会导致模型无法自行判断任务是否完成

v1.1 — 慢思考模式 (Thinking Phase)

将 ReAct 循环从单阶段升级为双阶段架构：

• Phase 1 (Thinking) — 剥夺工具访问权，强制模型先进行纯文本推理规划
• Phase 2 (Action) — 恢复工具挂载，模型顺着推理结果执行精准的工具调用
• 新增 EnableThinking 开关，兼容旧模式

v1.0 — ReAct 循环基础

实现标准的单阶段 ReAct 循环：思考 → 调工具 → 观察 → 继续，直到任务完成。

License

MIT