diff --git a/README.md b/README.md
index e69de29..5e82243 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,68 @@
+# 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
+
+## 快速开始
+
+```go
+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` 包的数据结构可灵活扩展消息格式和工具定义
+
+## License
+
+MIT
diff --git a/main.go b/main.go
index 8918222..6263e13 100644
--- a/main.go
+++ b/main.go
@@ -1,21 +1,59 @@
 package main
 
 import (
-	"fmt"
+	"context"
+	"log"
+	"os"
+
+	"go-tiny-claw/internal/engine"
+	"go-tiny-claw/internal/schema"
 )
 
-//TIP <p>To run your code, right-click the code and select <b>Run</b>.</p> <p>Alternatively, click
-// the <icon src="AllIcons.Actions.Execute"/> icon in the gutter and select the <b>Run</b> menu item from here.</p>
+// mockProvider 模拟大模型推理
+type mockProvider struct {
+	turn int
+}
 
-func main() {
-	//TIP <p>Press <shortcut actionId="ShowIntentionActions"/> when your caret is at the underlined text
-	// to see how GoLand suggests fixing the warning.</p><p>Alternatively, if available, click the lightbulb to view possible fixes.</p>
-	s := "gopher"
-	fmt.Printf("Hello and welcome, %s!\n", s)
+func (m *mockProvider) Generate(ctx context.Context, msgs []schema.Message, _ []schema.ToolDefinition) (*schema.Message, error) {
+	m.turn++
+	if m.turn == 1 {
+		return &schema.Message{
+			Role:    schema.RoleAssistant,
+			Content: "让我来看看当前目录下有什么文件。",
+			ToolCalls: []schema.ToolCall{
+				{ID: "call_123", Name: "bash", Arguments: []byte(`{"command": "ls -la"}`)},
+			},
+		}, nil
+	}
+	return &schema.Message{
+		Role:    schema.RoleAssistant,
+		Content: "我看到了文件列表，里面包含 main.go，任务完成！",
+	}, nil
+}
 
-	for i := 1; i <= 5; i++ {
-		//TIP <p>To start your debugging session, right-click your code in the editor and select the Debug option.</p> <p>We have set one <icon src="AllIcons.Debugger.Db_set_breakpoint"/> breakpoint
-		// for you, but you can always add more by pressing <shortcut actionId="ToggleLineBreakpoint"/>.</p>
-		fmt.Println("i =", 100/i)
+// mockRegistry 模拟工具执行
+type mockRegistry struct{}
+
+func (m *mockRegistry) GetAvailableTools() []schema.ToolDefinition { return nil }
+
+func (m *mockRegistry) Execute(ctx context.Context, call schema.ToolCall) schema.ToolResult {
+	return schema.ToolResult{
+		ToolCallID: call.ID,
+		Output:     "-rw-r--r--  1 user group  234 Oct 24 10:00 main.go\n",
+		IsError:    false,
+	}
+}
+
+func main() {
+	workDir, _ := os.Getwd()
+
+	p := &mockProvider{}
+	r := &mockRegistry{}
+
+	eng := engine.NewAgentEngine(p, r, workDir)
+
+	err := eng.Run(context.Background(), "帮我检查当前目录的文件")
+	if err != nil {
+		log.Fatalf("引擎崩溃: %v", err)
 	}
 }