tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tool Usage Patterns

工具使用模式

Efficient and reliable tool utilization.

高效且可靠的工具利用方案。

Instructions

操作指南

1. Tool Selection Matrix

1. 工具选择矩阵

Choose the right tool for the task:

Task	Primary Tool	Fallback
Find file by name	`find_by_name`	`list_dir` recursive
Search code content	`grep_search`	`view_file` + manual
Understand structure	`view_file_outline`	`view_file`
Read specific lines	`view_file` with range	Full file view
Edit single location	`replace_file_content`	`write_to_file`
Edit multiple locations	`multi_replace_file_content`	Sequential edits
Run command	`run_command`	N/A
Web research	`search_web`	`read_url_content`

为任务选择合适的工具：

任务	首选工具	备选方案
按名称查找文件	`find_by_name`	递归调用 `list_dir`
搜索代码内容	`grep_search`	`view_file` + 人工检查
理解文件结构	`view_file_outline`	`view_file`
读取特定行	指定范围的 `view_file`	查看完整文件
单位置编辑	`replace_file_content`	`write_to_file`
多位置编辑	`multi_replace_file_content`	顺序编辑
执行命令	`run_command`	无
网络调研	`search_web`	`read_url_content`

2. Tool Composition

2. 工具组合

Chain tools efficiently:

markdown

undefined

高效串联工具：

markdown

undefined

File Exploration Flow

文件探索流程

```
list_dir
```
→ Get directory structure
```
find_by_name
```
→ Locate specific files
```
view_file_outline
```
→ Understand file structure
```
view_file
```
→ Read specific sections
```
view_code_item
```
→ Deep dive into functions

```
list_dir
```
→ 获取目录结构
```
find_by_name
```
→ 定位特定文件
```
view_file_outline
```
→ 理解文件结构
```
view_file
```
→ 读取特定章节
```
view_code_item
```
→ 深入分析函数

Edit Flow

编辑流程

```
view_file
```
→ Understand current state
Plan changes mentally
```
replace_file_content
```
→ Make targeted edit
```
run_command
```
→ Verify (lint, test)

undefined

```
view_file
```
→ 了解当前状态
构思修改方案
```
replace_file_content
```
→ 执行针对性编辑
```
run_command
```
→ 验证（代码检查、测试）

undefined

3. Parallel Tool Calls

3. 并行工具调用

When tasks are independent:

markdown

undefined

处理独立任务时：

markdown

undefined

✅ Parallelize

✅ 可并行操作

Reading multiple files
Searching different directories
Independent file edits

读取多个文件
搜索不同目录
独立的文件编辑

❌ Don't Parallelize

❌ 不可并行操作

Edit then verify (sequential)
Read then edit same file
Dependent operations

undefined

编辑后验证（需按顺序执行）
读取后编辑同一文件
依赖型操作

undefined

4. Error Handling

4. 错误处理

markdown

undefined

markdown

undefined

Tool Failure Response

工具故障应对方案

Error Type	Response
File not found	Check path, try alternatives
Command failed	Read error, fix issue, retry
Edit conflict	Re-read file, adjust edit
Timeout	Retry with smaller scope
Permission denied	Notify user

错误类型	应对措施
文件未找到	检查路径，尝试替代方案
命令执行失败	读取错误信息，修复问题后重试
编辑冲突	重新读取文件，调整编辑内容
超时	缩小范围后重试
权限不足	通知用户

Retry Strategy

重试策略

First failure: Retry immediately
Second failure: Analyze error
Third failure: Try alternative
Still failing: Ask user

undefined

首次失败：立即重试
二次失败：分析错误原因
三次失败：尝试替代工具
仍失败：询问用户

undefined

5. Tool Efficiency

5. 工具使用效率

markdown

undefined

markdown

undefined

Minimize Tool Calls

减少工具调用次数

❌ Inefficient:

Read file A
Read file B
Read file C (3 sequential calls)

✅ Efficient:

Read files A, B, C in parallel (1 parallel call)

❌ 低效方式：

读取文件A
读取文件B
读取文件C （3次顺序调用）

✅ 高效方式：

并行读取文件A、B、C （1次并行调用）

Read Minimum Necessary

仅读取必要内容

❌ Wasteful:

View entire 1000-line file

✅ Efficient:

View outline first
Read only relevant sections (lines 50-100)

undefined

❌ 浪费操作：

查看整个1000行的文件

✅ 高效方式：

先查看文件大纲
仅读取相关章节（如第50-100行）

undefined

6. Command Execution

6. 命令执行

markdown

undefined

markdown

undefined

Safe Command Practices

安全命令实践

Always Safe (SafeToAutoRun: true)

始终安全（SafeToAutoRun: true）

```
ls
```
,
```
dir
```
,
```
cat
```
,
```
type
```
```
npm run lint
```
,
```
npm run build
```
```
git status
```
,
```
git diff
```
```
npx tsc --noEmit
```

```
ls
```
,
```
dir
```
,
```
cat
```
,
```
type
```
```
npm run lint
```
,
```
npm run build
```
```
git status
```
,
```
git diff
```
```
npx tsc --noEmit
```

Requires Approval (SafeToAutoRun: false)

需要审批（SafeToAutoRun: false）

```
npm install <package>
```
```
rm
```
,
```
del
```
, file deletion
```
git push
```
,
```
git commit
```
Database operations
Network requests

undefined

```
npm install <package>
```
```
rm
```
,
```
del
```
等文件删除命令
```
git push
```
,
```
git commit
```
数据库操作
网络请求

undefined

7. Search Strategies

7. 搜索策略

markdown

undefined

markdown

undefined

Finding Code

代码查找方法

Know exact text:
```
grep_search
```
with literal
Know pattern:
```
grep_search
```
with regex
Know file name:
```
find_by_name
```
Exploring:
```
list_dir
```
+
```
view_file_outline
```

知道确切文本：使用字面量的
```
grep_search
```
知道匹配模式：使用正则的
```
grep_search
```
知道文件名：
```
find_by_name
```
探索性查找：
```
list_dir
```
+
```
view_file_outline
```

Search Tips

搜索技巧

Use specific queries
Include file type filters
Start broad, narrow down
Check multiple directories

undefined

使用精准查询
包含文件类型过滤
从宽泛到精准逐步缩小范围
检查多个目录

undefined

8. File Edit Best Practices

8. 文件编辑最佳实践

markdown

undefined

markdown

undefined

Edit Accuracy

编辑准确性

Always view file first
Use exact line numbers
Copy target content precisely
Verify edit was successful

始终先查看文件
使用准确的行号
精准复制目标内容
验证编辑是否成功

Common Edit Errors

常见编辑错误

Error	Cause	Fix
Target not found	Wrong content	Re-copy from file
Multiple matches	Content not unique	Use line range
Wrong location	Stale line numbers	Re-read file

undefined

错误	原因	修复方案
未找到目标内容	内容错误	从文件中重新复制
多个匹配结果	内容不唯一	使用行范围
编辑位置错误	行号已过期	重新读取文件

undefined

tools

Original

Translation

Tool Usage Patterns

工具使用模式

Instructions

操作指南

1. Tool Selection Matrix

1. 工具选择矩阵

2. Tool Composition

2. 工具组合

File Exploration Flow

文件探索流程

Edit Flow

编辑流程

3. Parallel Tool Calls

3. 并行工具调用

✅ Parallelize

✅ 可并行操作

❌ Don't Parallelize

❌ 不可并行操作

4. Error Handling

4. 错误处理

Tool Failure Response

工具故障应对方案

Retry Strategy

重试策略

5. Tool Efficiency

5. 工具使用效率

Minimize Tool Calls

减少工具调用次数

Read Minimum Necessary

仅读取必要内容

6. Command Execution

6. 命令执行

Safe Command Practices

安全命令实践

Always Safe (SafeToAutoRun: true)

始终安全（SafeToAutoRun: true）

Requires Approval (SafeToAutoRun: false)

需要审批（SafeToAutoRun: false）

7. Search Strategies

7. 搜索策略

Finding Code

代码查找方法

Search Tips

搜索技巧

8. File Edit Best Practices

8. 文件编辑最佳实践

Edit Accuracy

编辑准确性

Common Edit Errors

常见编辑错误

References

参考资料