feat: Chapter 6 — Complete file operation tools

Demo code:
- Add tools/FileWriteTool/ with auto directory creation, write stats
- Add tools/FileEditTool/ with exact string replacement, uniqueness
  check (matches real Claude Code's Edit approach over unified diff)
- Add tools/GlobTool/ using Bun.Glob with 1000 result limit
- Register all 3 in tools.ts — now 7 tools total:
  Read-only (concurrent): Echo, Read, Grep, Glob
  Read-write (serial): Bash, Write, Edit

Documentation:
- Add "Hands-on: Complete File Operation Tools" to Ch6 (zh-CN/en)
- Explain why Edit uses string replacement over diff

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anthhub

demo/tools.ts

@@ -18,7 +18,10 @@ import { buildTool } from "./Tool.js";
 // ─── 从独立模块导入增强版工具 ──────────────────────────────────────────────────
 import { BashTool } from "./tools/BashTool/index.js";
 import { FileReadTool } from "./tools/FileReadTool/index.js";
+import { FileWriteTool } from "./tools/FileWriteTool/index.js";
+import { FileEditTool } from "./tools/FileEditTool/index.js";
 import { GrepTool } from "./tools/GrepTool/index.js";
+import { GlobTool } from "./tools/GlobTool/index.js";
 
 // ─── 内联工具定义 ──────────────────────────────────────────────────────────────
 
@@ -56,8 +59,11 @@ const EchoTool = buildTool({
 export const allTools: Tool[] = [
   EchoTool,
   FileReadTool,
+  FileWriteTool,
+  FileEditTool,
   BashTool,
   GrepTool,
+  GlobTool,
 ];
 
 /**
@@ -81,4 +87,4 @@ export function getToolsForAPI(): APIToolDefinition[] {
 }
 
 // 导出各个工具（供直接引用或测试）
-export { EchoTool, FileReadTool, BashTool, GrepTool };
+export { EchoTool, FileReadTool, FileWriteTool, FileEditTool, BashTool, GrepTool, GlobTool };

demo/tools/FileEditTool/index.ts

@@ -0,0 +1,76 @@
+/**
+ * tools/FileEditTool/index.ts - 精确编辑工具
+ *
+ * 对应真实 Claude Code: src/tools/FileEditTool/
+ * 核心思路：通过 old_string -> new_string 精确替换，
+ * 而非整文件重写。这样 AI 只需发送 diff，节省 token。
+ *
+ * 真实版本还包含：模糊匹配、缩进修正、冲突检测、
+ * 多处替换确认等。
+ */
+
+import { buildTool } from "../../Tool.js";
+
+export const FileEditTool = buildTool({
+  name: "Edit",
+  description: "通过精确字符串替换编辑文件。指定 old_string（要替换的内容）和 new_string（替换后的内容）。old_string 必须在文件中唯一匹配。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "文件的绝对路径" },
+      old_string: { type: "string", description: "要被替换的原始文本（必须唯一匹配）" },
+      new_string: { type: "string", description: "替换后的新文本" },
+    },
+    required: ["file_path", "old_string", "new_string"],
+  },
+  isReadOnly: false,
+  async call(input) {
+    const filePath = String(input.file_path);
+    const oldString = String(input.old_string);
+    const newString = String(input.new_string);
+
+    try {
+      const file = Bun.file(filePath);
+      const exists = await file.exists();
+      if (!exists) {
+        return { content: `Error: File not found: ${filePath}`, isError: true };
+      }
+
+      const content = await file.text();
+
+      // 检查 old_string 是否存在
+      const index = content.indexOf(oldString);
+      if (index === -1) {
+        return {
+          content: `Error: old_string not found in ${filePath}. Make sure the string matches exactly (including whitespace and indentation).`,
+          isError: true,
+        };
+      }
+
+      // 检查 old_string 是否唯一
+      const secondIndex = content.indexOf(oldString, index + 1);
+      if (secondIndex !== -1) {
+        return {
+          content: `Error: old_string matches multiple locations in ${filePath}. Provide more surrounding context to make it unique.`,
+          isError: true,
+        };
+      }
+
+      // 执行替换
+      const newContent = content.substring(0, index) + newString + content.substring(index + oldString.length);
+      await Bun.write(filePath, newContent);
+
+      // 计算变更统计
+      const oldLines = oldString.split("\n").length;
+      const newLines = newString.split("\n").length;
+      const diffLines = newLines - oldLines;
+      const diffStr = diffLines > 0 ? `+${diffLines}` : diffLines < 0 ? `${diffLines}` : "±0";
+
+      return {
+        content: `Edited ${filePath}: replaced ${oldLines} lines with ${newLines} lines (${diffStr} lines)`,
+      };
+    } catch (e) {
+      return { content: `Error editing file: ${e}`, isError: true };
+    }
+  },
+});

demo/tools/FileWriteTool/index.ts

@@ -0,0 +1,50 @@
+/**
+ * tools/FileWriteTool/index.ts - 文件写入工具
+ *
+ * 对应真实 Claude Code: src/tools/FileWriteTool/
+ * 真实版本还包含：文件备份、权限检查、符号链接安全、
+ * 大文件警告等。我们实现核心写入功能。
+ */
+
+import { buildTool } from "../../Tool.js";
+import { existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+export const FileWriteTool = buildTool({
+  name: "Write",
+  description: "将内容写入指定文件。如果文件不存在会自动创建（包括中间目录）。如果文件已存在会覆盖。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "文件的绝对路径" },
+      content: { type: "string", description: "要写入的完整文件内容" },
+    },
+    required: ["file_path", "content"],
+  },
+  isReadOnly: false,
+  async call(input) {
+    const filePath = String(input.file_path);
+    const content = String(input.content);
+
+    try {
+      // 确保目录存在
+      const dir = dirname(filePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+
+      const existed = existsSync(filePath);
+      await Bun.write(filePath, content);
+
+      const lines = content.split("\n").length;
+      const bytes = new TextEncoder().encode(content).length;
+      const action = existed ? "Updated" : "Created";
+
+      return {
+        content: `${action} ${filePath} (${lines} lines, ${bytes} bytes)`,
+      };
+    } catch (e) {
+      return { content: `Error writing file: ${e}`, isError: true };
+    }
+  },
+});

demo/tools/GlobTool/index.ts

@@ -0,0 +1,53 @@
+/**
+ * tools/GlobTool/index.ts - 文件路径匹配工具
+ *
+ * 对应真实 Claude Code: src/tools/GlobTool/
+ * 用于快速发现文件，如 "**\/*.ts" 找到所有 TypeScript 文件。
+ * 使用 Bun.Glob 实现。
+ */
+
+import { buildTool } from "../../Tool.js";
+import { Glob } from "bun";
+
+export const GlobTool = buildTool({
+  name: "Glob",
+  description: "使用 glob 模式查找匹配的文件路径。如 '**/*.ts' 查找所有 TypeScript 文件。结果按路径排序。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Glob 模式，如 '**/*.ts'、'src/**/*.js'" },
+      path: { type: "string", description: "搜索的根目录，默认当前目录" },
+    },
+    required: ["pattern"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    const pattern = String(input.pattern);
+    const searchPath = String(input.path ?? ".");
+
+    try {
+      const glob = new Glob(pattern);
+      const matches: string[] = [];
+
+      for await (const file of glob.scan({ cwd: searchPath, dot: false })) {
+        matches.push(file);
+        if (matches.length >= 1000) break; // 限制结果数量
+      }
+
+      matches.sort();
+
+      if (matches.length === 0) {
+        return { content: "No files matched the pattern." };
+      }
+
+      let content = matches.join("\n");
+      if (matches.length >= 1000) {
+        content += "\n... [results limited to 1000 files]";
+      }
+
+      return { content: `Found ${matches.length} files:\n${content}` };
+    } catch (e) {
+      return { content: `Error: ${e}`, isError: true };
+    }
+  },
+});

docs/en/06-service-layer.md

@@ -11,6 +11,7 @@
 7. [Analytics Service](#analytics-service)
 8. [Hands-on: Streaming API Client](#hands-on-streaming-api-client)
 9. [Key Takeaways & What's Next](#key-takeaways--whats-next)
+10. [Hands-on: Complete File Operation Tools](#hands-on-complete-file-operation-tools)
 
 ---
 
@@ -721,4 +722,98 @@ Chapter 7 covers the **Permission System** — how Claude Code decides whether a
 
 ---
 
+## Hands-on: Complete File Operation Tools
+
+> **This section is another major upgrade to the demo.** We add three file operation tools — FileWriteTool, FileEditTool, and GlobTool — giving mini-claude full file read/write and search capabilities.
+
+### Project Structure Update
+
+```
+demo/
+├── tools/
+│   ├── BashTool/
+│   │   └── index.ts
+│   ├── FileReadTool/
+│   │   └── index.ts
+│   ├── GrepTool/
+│   │   └── index.ts
+│   ├── FileWriteTool/
+│   │   └── index.ts       # ← New: create/overwrite files
+│   ├── FileEditTool/
+│   │   └── index.ts       # ← New: precise string replacement
+│   └── GlobTool/
+│       └── index.ts       # ← New: file path matching
+├── tools.ts               # Updated: register new tools
+├── query.ts
+├── main.ts
+├── Tool.ts
+├── context.ts
+├── services/api/
+├── utils/
+│   └── messages.ts
+└── types/
+```
+
+### Three New Tools Explained
+
+| Tool | Function | Key Design |
+|------|----------|------------|
+| FileWriteTool (Write) | Create/overwrite files | Auto-creates intermediate directories; reports line count and byte size |
+| FileEditTool (Edit) | Precise string replacement | old_string must match uniquely; saves tokens compared to full file rewrite |
+| GlobTool (Glob) | File path matching | Uses Bun.Glob; results capped at 1000 |
+
+**FileWriteTool** accepts `file_path` and `content` parameters, writing content to the specified path. If parent directories don't exist, they are created recursively (`mkdir -p` semantics). After writing, it returns line count and byte size so the model can confirm the operation result.
+
+**FileEditTool** accepts `file_path`, `old_string`, and `new_string` parameters, finding `old_string` in the file and replacing it with `new_string`. The core constraint is that **old_string must match uniquely in the file** — if it matches zero times or multiple times, the tool returns an error. This design prevents replacements at wrong locations.
+
+**GlobTool** accepts `pattern` and an optional `path` parameter, matching file paths using glob patterns. It uses the `Bun.Glob` API internally, with results capped at 1000 files to prevent excessive token consumption.
+
+### Why String Replacement Instead of Diff?
+
+This is a design choice worth reflecting on. Traditional file editing tools might use unified diff format, but Claude Code chose the old_string → new_string string replacement approach for several reasons:
+
+- **AI generates precise old_string → new_string more reliably than unified diff** — the model only needs to copy the original text to modify and write the replacement, without computing correct line numbers and hunk headers
+- **Unique match checking prevents edits at wrong locations** — if old_string appears multiple times in the file, the tool refuses to execute and returns an error, forcing the model to provide more context for precise targeting
+- **Real Claude Code uses the same approach** — this isn't a simplification, but a production-validated optimal solution
+
+### Tool Landscape
+
+mini-claude now has 7 tools, categorized by read/write characteristics:
+
+```
+Read-only tools (can run concurrently): Echo, Read, Grep, Glob
+Read-write tools (must run serially):   Bash, Write, Edit
+```
+
+Read-only tools don't modify filesystem state and can safely run concurrently. Read-write tools may change the filesystem and must run serially to avoid race conditions. This classification becomes critical in Chapter 7's permission system — read-write tools require user confirmation, while read-only tools can execute automatically.
+
+### Running the Demo
+
+```bash
+cd demo && bun run main.ts
+```
+
+Try these interactions to verify the new tools:
+
+```
+you> Create a hello.txt file with content "Hello, World!"
+you> Change "World" to "Claude" in hello.txt
+you> Find all .ts files in the current directory
+```
+
+### Mapping to Real Claude Code
+
+| Demo File | Real File | What's Simplified |
+|-----------|-----------|-------------------|
+| `tools/FileWriteTool/index.ts` | `src/tools/FileWriteTool/` | No permission checks, no symlink protection |
+| `tools/FileEditTool/index.ts` | `src/tools/FileEditTool/` | No replace_all mode, no syntax validation |
+| `tools/GlobTool/index.ts` | `src/tools/GlobTool/` | No gitignore filtering, no sort-by-mtime |
+| `tools.ts` (registers 7 tools) | `src/tools.ts` | No lazy loading, no feature flag filtering |
+
+### Next Chapter Preview
+
+Chapter 7 will implement the permission system, ensuring dangerous operations (like `rm -rf`, writing to system files) require user confirmation. Read-write tools will be strictly controlled, while read-only tools can execute freely.
+
+---
+
 *Source references: `src/services/api/client.ts`, `src/services/api/withRetry.ts`, `src/QueryEngine.ts`, `src/query.ts`, `src/services/compact/compact.ts`, `src/services/compact/autoCompact.ts`, `src/services/tokenEstimation.ts`, `src/cost-tracker.ts`, `src/services/analytics/index.ts`, `src/services/analytics/growthbook.ts`*