feat: Chapter 5 — Standalone tool modules with enhanced features

anthhub · claude · anthhub · commit 1e0ec850beeb · 2026-04-03T14:39:03.000+08:00
Demo code:
- Add tools/BashTool/ with timeout, output truncation (50KB limit)
- Add tools/FileReadTool/ with line numbers, offset/limit params
- Add tools/GrepTool/ with file type filtering, result limiting
- Refactor tools.ts to import from standalone modules
- EchoTool remains inline (teaching purpose)

Each tool is now a self-contained module matching real Claude Code's
tools/ directory pattern — independent development, testing, maintenance.

Documentation:
- Add "Hands-on: Standalone Tool Modules" to Ch5 (zh-CN and en)
- Explain self-contained module pattern and enhancement details

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/demo/tools.ts b/demo/tools.ts
@@ -7,22 +7,26 @@
  * QueryEngine 在调用 API 时，将注册表中的工具转换为 API 参数格式；
  * 收到 tool_use 响应时，根据名称在注册表中查找并执行工具。
  *
- * 真实 Claude Code 在此文件中导入 40+ 个工具，
- * 并通过 feature() 宏条件加载。我们先注册几个示例工具。
+ * 第 5 章：工具已迁移到独立的 tools/ 目录中，
+ * 每个工具一个子目录，支持更丰富的参数和更好的错误处理。
  */
 
 import type { Tool, APIToolDefinition } from "./types/index.js";
 import { toolToAPIFormat } from "./types/index.js";
 import { buildTool } from "./Tool.js";
 
-// ─── 内置工具定义 ──────────────────────────────────────────────────────────
-// 第 5 章会将这些移到独立的 tools/ 目录中
-// 目前先在这里定义简单版本，验证注册表机制
+// ─── 从独立模块导入增强版工具 ──────────────────────────────────────────────────
+import { BashTool } from "./tools/BashTool/index.js";
+import { FileReadTool } from "./tools/FileReadTool/index.js";
+import { GrepTool } from "./tools/GrepTool/index.js";
+
+// ─── 内联工具定义 ──────────────────────────────────────────────────────────────
 
 /**
  * EchoTool - 最简单的工具，用于验证工具系统
  *
  * 这不是真实 Claude Code 中的工具，只是教学用的 hello world
+ * 保留内联定义，因为它只用于教学演示。
  */
 const EchoTool = buildTool({
   name: "Echo",
@@ -40,108 +44,6 @@ const EchoTool = buildTool({
   },
 });
 
-/**
- * ReadTool - 读取文件内容（简化版）
- *
- * 对应真实 Claude Code: src/tools/FileReadTool/
- * 第 5 章会实现完整版本（支持行号范围、二进制文件检测等）
- */
-const ReadTool = buildTool({
-  name: "Read",
-  description: "读取指定文件的内容",
-  inputSchema: {
-    type: "object",
-    properties: {
-      file_path: { type: "string", description: "文件的绝对路径" },
-    },
-    required: ["file_path"],
-  },
-  isReadOnly: true,
-  async call(input) {
-    try {
-      const filePath = String(input.file_path);
-      const file = Bun.file(filePath);
-      const content = await file.text();
-      return { content };
-    } catch (e) {
-      return { content: `Error reading file: ${e}`, isError: true };
-    }
-  },
-});
-
-/**
- * BashTool - 执行 shell 命令（简化版）
- *
- * 对应真实 Claude Code: src/tools/BashTool/
- * 第 5 章会实现完整版本（支持超时、工作目录、信号处理等）
- */
-const BashTool = buildTool({
-  name: "Bash",
-  description: "执行 shell 命令并返回输出",
-  inputSchema: {
-    type: "object",
-    properties: {
-      command: { type: "string", description: "要执行的 shell 命令" },
-    },
-    required: ["command"],
-  },
-  isReadOnly: false, // shell 命令可能有副作用
-  async call(input) {
-    try {
-      const proc = Bun.spawn(["sh", "-c", String(input.command)], {
-        stdout: "pipe",
-        stderr: "pipe",
-      });
-      const stdout = await new Response(proc.stdout).text();
-      const stderr = await new Response(proc.stderr).text();
-      const exitCode = await proc.exited;
-
-      let content = stdout;
-      if (stderr) content += `\nSTDERR:\n${stderr}`;
-      if (exitCode !== 0) content += `\nExit code: ${exitCode}`;
-
-      return { content, isError: exitCode !== 0 };
-    } catch (e) {
-      return { content: `Error executing command: ${e}`, isError: true };
-    }
-  },
-});
-
-/**
- * GrepTool - 搜索文件内容（简化版）
- *
- * 对应真实 Claude Code: src/tools/GrepTool/
- * 底层使用 ripgrep，这里简化为调用 grep 命令
- */
-const GrepTool = buildTool({
-  name: "Grep",
-  description: "在文件中搜索匹配的文本模式",
-  inputSchema: {
-    type: "object",
-    properties: {
-      pattern: { type: "string", description: "搜索的正则表达式" },
-      path: { type: "string", description: "搜索的目录或文件路径" },
-    },
-    required: ["pattern"],
-  },
-  isReadOnly: true,
-  async call(input) {
-    try {
-      const pattern = String(input.pattern);
-      const searchPath = String(input.path ?? ".");
-      const proc = Bun.spawn(
-        ["grep", "-rn", "--include=*.ts", "--include=*.js", pattern, searchPath],
-        { stdout: "pipe", stderr: "pipe" }
-      );
-      const stdout = await new Response(proc.stdout).text();
-      await proc.exited;
-      return { content: stdout || "No matches found." };
-    } catch (e) {
-      return { content: `Error: ${e}`, isError: true };
-    }
-  },
-});
-
 // ─── 工具注册表 ──────────────────────────────────────────────────────────────
 
 /**
@@ -153,7 +55,7 @@ const GrepTool = buildTool({
  */
 export const allTools: Tool[] = [
   EchoTool,
-  ReadTool,
+  FileReadTool,
   BashTool,
   GrepTool,
 ];
@@ -179,4 +81,4 @@ export function getToolsForAPI(): APIToolDefinition[] {
 }
 
 // 导出各个工具（供直接引用或测试）
-export { EchoTool, ReadTool, BashTool, GrepTool };
+export { EchoTool, FileReadTool, BashTool, GrepTool };
diff --git a/demo/tools/BashTool/index.ts b/demo/tools/BashTool/index.ts
@@ -0,0 +1,62 @@
+/**
+ * tools/BashTool/index.ts - Shell 命令执行工具
+ *
+ * 对应真实 Claude Code: src/tools/BashTool/
+ * 真实版本还包含：命令安全分析、工作目录切换、信号处理、
+ * 进程组管理、输出截断策略等。我们实现核心功能。
+ */
+
+import { buildTool } from "../../Tool.js";
+
+const MAX_OUTPUT_LENGTH = 50000; // 50KB 输出限制
+
+export const BashTool = buildTool({
+  name: "Bash",
+  description: "在 shell 中执行命令并返回输出。用于运行测试、安装依赖、查看文件列表等。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "要执行的 shell 命令" },
+      timeout: { type: "number", description: "超时时间（毫秒），默认 30000" },
+      description: { type: "string", description: "命令的用途说明（可选）" },
+    },
+    required: ["command"],
+  },
+  isReadOnly: false,
+  async call(input) {
+    const command = String(input.command);
+    const timeout = Number(input.timeout ?? 30000);
+
+    try {
+      const proc = Bun.spawn(["sh", "-c", command], {
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, TERM: "dumb" }, // 禁用颜色转义
+      });
+
+      // 超时处理
+      const timer = setTimeout(() => proc.kill(), timeout);
+
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+      const exitCode = await proc.exited;
+
+      clearTimeout(timer);
+
+      // 格式化输出
+      let content = stdout;
+      if (stderr) content += (content ? "\n" : "") + `STDERR:\n${stderr}`;
+      if (exitCode !== 0) content += `\nExit code: ${exitCode}`;
+
+      // 截断过长输出
+      if (content.length > MAX_OUTPUT_LENGTH) {
+        content = content.substring(0, MAX_OUTPUT_LENGTH) +
+          `\n... [output truncated, ${content.length} total chars]`;
+      }
+
+      return { content: content || "(no output)", isError: exitCode !== 0 };
+    } catch (e) {
+      return { content: `Error executing command: ${e}`, isError: true };
+    }
+  },
+});
diff --git a/demo/tools/FileReadTool/index.ts b/demo/tools/FileReadTool/index.ts
@@ -0,0 +1,55 @@
+/**
+ * tools/FileReadTool/index.ts - 文件读取工具
+ *
+ * 对应真实 Claude Code: src/tools/FileReadTool/
+ * 真实版本还包含：二进制文件检测、图片/PDF 读取、
+ * 编码检测、符号链接解析等。
+ */
+
+import { buildTool } from "../../Tool.js";
+
+export const FileReadTool = buildTool({
+  name: "Read",
+  description: "读取文件内容。支持指定起始行和行数限制。对于大文件，建议使用 offset 和 limit 参数只读取需要的部分。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "文件的绝对路径" },
+      offset: { type: "number", description: "起始行号（从 0 开始，可选）" },
+      limit: { type: "number", description: "读取的最大行数（可选，默认 2000）" },
+    },
+    required: ["file_path"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    const filePath = String(input.file_path);
+    const offset = Number(input.offset ?? 0);
+    const limit = Number(input.limit ?? 2000);
+
+    try {
+      const file = Bun.file(filePath);
+      const exists = await file.exists();
+      if (!exists) {
+        return { content: `Error: File not found: ${filePath}`, isError: true };
+      }
+
+      const text = await file.text();
+      const allLines = text.split("\n");
+      const selectedLines = allLines.slice(offset, offset + limit);
+
+      // 添加行号（模拟 cat -n 格式）
+      const numbered = selectedLines
+        .map((line, i) => `${String(offset + i + 1).padStart(6)}\t${line}`)
+        .join("\n");
+
+      let content = numbered;
+      if (offset + limit < allLines.length) {
+        content += `\n... [${allLines.length - offset - limit} more lines]`;
+      }
+
+      return { content };
+    } catch (e) {
+      return { content: `Error reading file: ${e}`, isError: true };
+    }
+  },
+});
diff --git a/demo/tools/GrepTool/index.ts b/demo/tools/GrepTool/index.ts
@@ -0,0 +1,64 @@
+/**
+ * tools/GrepTool/index.ts - 代码搜索工具
+ *
+ * 对应真实 Claude Code: src/tools/GrepTool/
+ * 真实版本使用 ripgrep (rg) 而非 grep，性能更好。
+ * 这里简化为 grep，后续可替换为 rg。
+ */
+
+import { buildTool } from "../../Tool.js";
+
+export const GrepTool = buildTool({
+  name: "Grep",
+  description: "在文件中搜索匹配的文本模式。支持正则表达式。适合在代码库中查找函数定义、变量引用等。",
+  inputSchema: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "搜索的正则表达式模式" },
+      path: { type: "string", description: "搜索的目录或文件路径，默认当前目录" },
+      include: { type: "string", description: "文件类型过滤（如 '*.ts'）" },
+    },
+    required: ["pattern"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    const pattern = String(input.pattern);
+    const searchPath = String(input.path ?? ".");
+    const include = input.include ? String(input.include) : undefined;
+
+    try {
+      const args = ["grep", "-rn"];
+      if (include) args.push(`--include=${include}`);
+      args.push(pattern, searchPath);
+
+      const proc = Bun.spawn(args, {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+      const exitCode = await proc.exited;
+
+      if (exitCode === 1 && !stderr) {
+        return { content: "No matches found." };
+      }
+      if (exitCode > 1 || stderr) {
+        return { content: `Error: ${stderr}`, isError: true };
+      }
+
+      // 限制输出行数
+      const lines = stdout.split("\n");
+      if (lines.length > 200) {
+        return {
+          content: lines.slice(0, 200).join("\n") +
+            `\n... [${lines.length - 200} more matches]`,
+        };
+      }
+
+      return { content: stdout || "No matches found." };
+    } catch (e) {
+      return { content: `Error: ${e}`, isError: true };
+    }
+  },
+});
diff --git a/docs/en/05-ink-rendering.md b/docs/en/05-ink-rendering.md
diff --git a/docs/zh-CN/05-ink-rendering.md b/docs/zh-CN/05-ink-rendering.md
