docs: 新增工具和场景示例文档（6个示例）

## 新增内容

### 工具使用示例（3个）

1. **文件操作工具** - 使用文件系统工具读写文件
   - 5 种文件系统工具详解
   - 配置文件管理、代码重构、日志分析场景
   - 沙箱隔离说明

2. **HTTP 请求工具** - 使用 HTTP 工具调用 REST API
   - GET/POST/PUT/DELETE 请求示例
   - GitHub API 实战演示
   - 带认证的 API 调用
   - 速率限制和错误处理

3. **自定义工具** - 创建和使用自定义工具
   - 天气查询工具
   - 数据库查询工具
   - 计算器工具
   - 开发最佳实践（5个关键点）
   - 异步工具和带状态工具示例

### 实用场景示例（3个）

1. **代码审查** - 使用 Agent 自动审查代码
   - 专业的代码审查提示词
   - 审查报告格式（总体评价、具体问题、改进建议）
   - 多语言代码支持
   - Git 集成示例

2. **数据分析** - 使用 Agent 分析和可视化数据
   - CSV/JSON 数据分析
   - 统计指标计算
   - 数据对比和趋势分析
   - 生成可视化图表

3. **智能客服机器人** - 构建完整的客服机器人系统
   - 知识库查询工具
   - 多轮对话处理
   - 意图识别和情感分析
   - 工单系统集成
   - 完整的对话示例演示

## 特点

- 每个示例 100-200 行代码
- 包含完整可运行代码和输出示例
- 提供实用场景和扩展建议
- 交叉引用其他文档
- 强调最佳实践

总计新增 6 个示例，累计 13 个快速示例

参考 Mastra 项目的实用示例组织方式

Author: wutongci

docs/content/5.examples/3.tools/1.file-operations.md

@@ -0,0 +1,238 @@
+---
+title: 文件操作工具
+description: 使用文件系统工具读写文件
+---
+
+# 文件操作工具示例
+
+展示如何使用内置的文件系统工具进行文件操作。
+
+## 完整代码
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "os"
+
+    "github.com/wordflowlab/agentsdk/pkg/agent"
+    "github.com/wordflowlab/agentsdk/pkg/provider"
+    "github.com/wordflowlab/agentsdk/pkg/sandbox"
+    "github.com/wordflowlab/agentsdk/pkg/store"
+    "github.com/wordflowlab/agentsdk/pkg/tools"
+    "github.com/wordflowlab/agentsdk/pkg/tools/builtin"
+    "github.com/wordflowlab/agentsdk/pkg/types"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // 创建工具注册表
+    toolRegistry := tools.NewRegistry()
+    builtin.RegisterAll(toolRegistry)
+
+    // 创建依赖
+    deps := &agent.Dependencies{
+        ToolRegistry:     toolRegistry,
+        SandboxFactory:   sandbox.NewFactory(),
+        ProviderFactory:  provider.NewMultiProviderFactory(),
+        Store:            store.NewMemoryStore(),
+        TemplateRegistry: agent.NewTemplateRegistry(),
+    }
+
+    // 创建 Agent
+    ag, err := agent.Create(ctx, &types.AgentConfig{
+        TemplateID: "assistant",
+        ModelConfig: &types.ModelConfig{
+            Provider: "anthropic",
+            Model:    "claude-sonnet-4-5",
+            APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
+        },
+        Tools: []string{"filesystem"},  // 只启用文件系统工具
+    }, deps)
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer ag.Close()
+
+    // 测试不同的文件操作
+    tasks := []string{
+        "创建一个 config.json 文件，内容是 {\"app\": \"demo\", \"version\": \"1.0\"}",
+        "读取 config.json 文件的内容",
+        "列出当前目录的所有 .json 文件",
+        "在 config.json 中搜索包含 'demo' 的内容",
+    }
+
+    for i, task := range tasks {
+        fmt.Printf("\n========== 任务 %d ==========\n", i+1)
+        fmt.Printf("请求: %s\n\n", task)
+
+        result, err := ag.Chat(ctx, task)
+        if err != nil {
+            log.Printf("错误: %v", err)
+            continue
+        }
+
+        fmt.Printf("响应: %s\n", result.Message.Content)
+    }
+}
+```
+
+## 可用的文件系统工具
+
+### 1. filesystem_read
+读取文件内容。
+
+```go
+// Agent 会调用
+{
+    "path": "config.json"
+}
+```
+
+### 2. filesystem_write
+写入文件。
+
+```go
+// Agent 会调用
+{
+    "path": "output.txt",
+    "content": "Hello World"
+}
+```
+
+### 3. filesystem_list
+列出目录内容。
+
+```go
+// Agent 会调用
+{
+    "path": ".",
+    "recursive": false
+}
+```
+
+### 4. filesystem_delete
+删除文件。
+
+```go
+// Agent 会调用
+{
+    "path": "temp.txt"
+}
+```
+
+### 5. filesystem_search
+搜索文件内容。
+
+```go
+// Agent 会调用
+{
+    "path": ".",
+    "pattern": "TODO",
+    "file_pattern": "*.go"
+}
+```
+
+## 运行示例
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-xxx"
+go run main.go
+```
+
+## 输出示例
+
+```
+========== 任务 1 ==========
+请求: 创建一个 config.json 文件，内容是 {"app": "demo", "version": "1.0"}
+
+响应: 我已经创建了 config.json 文件，内容如下：
+```json
+{
+  "app": "demo",
+  "version": "1.0"
+}
+```
+
+========== 任务 2 ==========
+请求: 读取 config.json 文件的内容
+
+响应: config.json 文件的内容是：
+```json
+{
+  "app": "demo",
+  "version": "1.0"
+}
+```
+
+========== 任务 3 ==========
+请求: 列出当前目录的所有 .json 文件
+
+响应: 当前目录中的 .json 文件有：
+- config.json (56 bytes)
+- package.json (342 bytes)
+
+========== 任务 4 ==========
+请求: 在 config.json 中搜索包含 'demo' 的内容
+
+响应: 在 config.json 中找到 1 处匹配：
+第 2 行: "app": "demo"
+```
+
+## 实用场景
+
+### 配置文件管理
+
+```go
+result, _ := ag.Chat(ctx, "读取 config.yaml 并将端口从 8080 改为 9000")
+// Agent 会：
+// 1. 读取 config.yaml
+// 2. 修改端口
+// 3. 写回文件
+```
+
+### 代码重构
+
+```go
+result, _ := ag.Chat(ctx, "在所有 .go 文件中将 'oldFunc' 替换为 'newFunc'")
+// Agent 会：
+// 1. 搜索所有 .go 文件
+// 2. 查找 'oldFunc'
+// 3. 逐个替换并保存
+```
+
+### 日志分析
+
+```go
+result, _ := ag.Chat(ctx, "分析 app.log 中的错误信息，统计每种错误的数量")
+// Agent 会：
+// 1. 读取 app.log
+// 2. 提取错误信息
+// 3. 统计和分类
+```
+
+## 沙箱隔离
+
+文件系统工具在沙箱中运行，确保安全：
+
+```go
+ag, err := agent.Create(ctx, &types.AgentConfig{
+    // ...
+    Sandbox: &types.SandboxConfig{
+        Kind:    types.SandboxKindLocal,
+        WorkDir: "./workspace",  // 限制在此目录
+    },
+}, deps)
+
+// Agent 只能访问 ./workspace 目录下的文件
+```
+
+## 相关资源
+
+- [内置工具详解](../../guides/tools/builtin)
+- [Tools API 文档](../../api-reference/tools-api)
+- [Filesystem 中间件](../../guides/middleware/builtin#filesystem)