OpenCode 学习笔记 02：核心工具 - AI 如何操作代码

AI Agent 的能力 = 工具的能力。工具越强，Agent 越强。

本篇目标

实现 6 个核心工具，让 Agent 能真正操作代码：

---

一、edit 工具 - 模糊匹配的艺术

1.1 为什么需要模糊匹配？

LLM 生成的代码经常有细微差异：

LLM 想替换:          实际文件:
"  const x = 1"      "    const x = 1"   ← 缩进不同
"function foo()"     "function foo() "   ← 尾部空格

如果只用精确匹配，很多替换会失败。

1.2 OpenCode 的 9 种匹配策略

OpenCode 的 edit.ts 有 9 种 Replacer，按优先级尝试：

1.3 核心算法：Levenshtein 距离

OpenCode 使用 Levenshtein 距离（编辑距离）计算相似度：

"hello" → "hallo"  距离 = 1（改1个字符）
"hello" → "helo"   距离 = 1（删1个字符）
"hello" → "helloo" 距离 = 1（加1个字符）

相似度计算：

similarity = 1 - (levenshtein距离 / 最大长度)

当相似度 > 阈值时，认为匹配成功。

1.4 BlockAnchorReplacer 详解

这是最聪明的策略，用于处理中间内容变化的情况：

要替换的代码:
┌─────────────────────┐
│ function foo() {    │ ← 首行锚点
│   // old code       │
│   return 1;         │
│ }                   │ ← 尾行锚点
└─────────────────────┘

实际文件中:
┌─────────────────────┐
│ function foo() {    │ ← 首行匹配 ✓
│   // different code │ ← 中间模糊匹配
│   return 2;         │
│ }                   │ ← 尾行匹配 ✓
└─────────────────────┘

流程：

1. 找到首行完全匹配的位置
2. 向下搜索尾行匹配
3. 计算中间内容的相似度
4. 相似度 > 阈值则替换

1.5 tiny-agent 简化实现

我们实现 4 种核心策略：

1. 精确匹配
2. 行 trim 匹配
3. 缩进灵活匹配
4. 首尾锚点匹配

覆盖 80% 的场景。

---

二、搜索工具如何配合找代码？

2.1 四种搜索工具的分工

2.2 搜索场景示例

场景：找到 UserService 的所有使用

Step 1: glob "*.ts" → 找到所有 TypeScript 文件
Step 2: grep "UserService" → 找到引用位置
Step 3: read 相关文件 → 查看上下文

场景：理解某个 API 如何工作

Step 1: codesearch "React useState hook" → 找到文档和示例
Step 2: grep "useState" path:src/ → 找到项目中的使用
Step 3: read 具体文件 → 学习用法

2.3 grep 使用示例

# 找函数定义
grep "function fetchUser"

# 找所有 import
grep "import.*from"

# 找 TODO 注释
grep "TODO|FIXME"

---

三、OpenCode 的高级功能（未实现）

以下是 OpenCode 的功能介绍，tiny-agent 暂未实现。

3.1 Exa API - 为 AI 设计的搜索

Exa 是专为 AI 设计的搜索引擎 API，和 Google 的区别：

OpenCode 用 Exa 实现两个工具：

3.2 LSP - 语言服务器协议

LSP（Language Server Protocol）是微软发明的协议，IDE 通过它获得智能功能：

┌─────────┐         ┌──────────────────┐
│  编辑器  │ ←LSP协议→ │   语言服务器      │
│ (Cursor) │         │ (ts-server/gopls)│
└─────────┘         └──────────────────┘

OpenCode 怎么用？

写入文件后自动检查错误，如果有语法问题就让 AI 修复：

写入代码 → LSP 检查 → 发现错误 → AI 自动修复

3.3 为什么我们不实现？

LSP 复杂的原因：OpenCode 的 lsp/ 目录有 ~1000 行代码专门处理。

这些是生产级功能，理解核心概念后可以自行添加。

---

四、bash 工具 - 如何处理危险命令？

4.1 OpenCode 的命令解析

OpenCode 使用 Tree-sitter 解析 bash 命令：

git commit -m "fix" && rm -rf ./temp

解析为：

[
  { "command": "git", "args": ["commit", "-m", "fix"] },
  { "command": "rm", "args": ["-rf", "./temp"] }
]

4.2 权限分级

4.3 tiny-agent 简化实现

我们使用简单的模式匹配：

const dangerousPatterns = [
  /rm\s+-rf\s+\/(?!\w)/,  // rm -rf /
  /mkfs/,                  // 格式化磁盘
  /dd\s+if=.*of=\/dev/,   // 直接写设备
]

生产环境需要更完善的权限系统。

---

五、工具组合：完整的代码修改流程

用户: "修复 fetchUser 函数的空指针问题"

Step 1: grep "fetchUser" → 找到定义位置
        结果: src/api/user.ts:23

Step 2: read src/api/user.ts → 查看代码
        发现: 没有 null 检查

Step 3: edit src/api/user.ts → 添加 null 检查
        oldString: "return data.user"
        newString: "return data?.user ?? null"

Step 4: bash "npm test" → 验证修复
        结果: All tests passed ✓

---

六、总结

工具清单

关键理解

1. 模糊匹配很重要

   • LLM 输出不精确，需要容错
   • OpenCode 有 9 种匹配策略
   • Levenshtein 距离计算相似度

2. 搜索工具各有分工

   • glob: 文件级定位
   • grep: 行级定位
   • codesearch: 语义级搜索
   • LSP: 符号级跳转

3. 外部信息获取

   • websearch: Exa API 网络搜索
   • codesearch: 代码文档搜索
   • webfetch: 直接获取网页

4. 安全很重要

   • Tree-sitter 解析命令
   • 分级权限控制
   • 危险命令拦截

---

代码仓库

完整代码：external/tiny-agent/

cd external/tiny-agent
make dev

You: 把 add 函数的返回类型改成 number
AI: [read] 查看文件
    [edit] 修改代码（缩进灵活匹配）
    ✅ 编辑成功