工具适配器

参考 opencode 实现的基础工具，移植到 Python 并集成到框架

设计目标：

参考 opencode 的成熟工具设计（Git Submodule: vendor/opencode/）
Python 实现：基础工具（builtin/）完整复刻，高级工具（advanced/）通过 Bun 调用
保持解耦，便于独立维护和更新

架构设计

vendor/opencode/                       # Git submodule（只读参考）
  └── packages/opencode/src/tool/      # TypeScript 实现

agent/tools/
  ├── builtin/                         # 基础工具（Python 完整实现）
  │   ├── read.py, edit.py, write.py  # 文件操作
  │   ├── bash.py                      # 命令执行
  │   └── glob.py, grep.py             # 文件搜索
  │
  ├── advanced/                        # 高级工具（Bun 适配器）
  │   ├── webfetch.py                  # 网页抓取
  │   └── lsp.py                       # LSP 诊断
  │
  └── adapters/
      ├── base.py                      # 适配器基类
      ├── opencode_bun_adapter.py      # Bun 调用适配器
      └── opencode-wrapper.ts          # TypeScript 桥接

实现策略：

基础工具（高频）：Python 完整实现（~1-5ms，零依赖）
高级工具（低频复杂）：通过 Bun 调用 opencode（~50-100ms，功能完整）

工具清单

基础工具（Python 实现）

工具	实现	功能
`read_file`	`builtin/read.py`	读取文件（文本/图片/PDF），分页支持
`edit_file`	`builtin/edit.py`	文件编辑，9 种智能匹配策略
`write_file`	`builtin/write.py`	文件写入，自动创建目录
`bash_command`	`builtin/bash.py`	命令执行，超时控制
`glob_files`	`builtin/glob.py`	文件模式匹配
`grep_content`	`builtin/grep.py`	内容搜索（ripgrep 优先）

参考源：vendor/opencode/packages/opencode/src/tool/*.ts

关键实现：

edit_file 的 9 种策略：包含 Levenshtein 算法的 BlockAnchorReplacer
bash_command 的环境变量支持
grep_content 的 ripgrep fallback

高级工具（Bun 适配器）

工具	实现	调用方式
`webfetch`	`advanced/webfetch.py`	Bun → opencode（HTML 转 MD）
`lsp_diagnostics`	`advanced/lsp.py`	Bun → opencode（LSP 集成）

依赖：需要 Bun 运行时

桥接：adapters/opencode-wrapper.ts 通过子进程调用 opencode 工具

适配器接口

实现：agent/tools/adapters/base.py:ToolAdapter

核心方法：

adapt_execute() - 执行工具并转换结果为 ToolResult
adapt_schema() - 转换工具 Schema
extract_memory() - 提取长期记忆摘要

Bun 适配器：adapters/opencode_bun_adapter.py:OpenCodeBunAdapter

通过子进程调用 bun run opencode-wrapper.ts <tool> <args>
30 秒超时
JSON 结果解析

更新 opencode 参考

检查更新

# 查看 submodule 状态
git submodule status

# 更新 submodule
cd vendor/opencode
git pull origin main
cd ../..

# 提交更新
git add vendor/opencode
git commit -m "chore: update opencode reference"

同步改进

查看 opencode 变更：
```
cd vendor/opencode
git log --oneline --since="1 month ago" -- packages/opencode/src/tool/
```
1. 对比实现差异：
2. 查看 opencode 的具体改动
3. 评估是否需要同步到 Python 实现
4. 更新 Python 实现：
5. 在 agent/tools/builtin/ 中更新对应工具
6. 更新代码注释中的参考位置
7. 测试验证：
```
pytest tests/tools/builtin/ -v
```

使用示例

from agent.tools.builtin import read_file, edit_file, bash_command
from agent.tools.advanced import webfetch

# 基础工具
result = await read_file(file_path="config.py", limit=100)
result = await edit_file(file_path="config.py", old_string="DEBUG = True", new_string="DEBUG = False")
result = await bash_command(command="git status", timeout=30)

# 高级工具（需要 Bun）
result = await webfetch(url="https://docs.python.org/3/")

工具通过 @tool 装饰器自动注册到 ToolRegistry。

完整示例：examples/tools_complete_demo.py

关键设计

Git Submodule 原则：

vendor/opencode/ 只读，绝不修改
作为参考源，可随时更新：cd vendor/opencode && git pull
基础工具手动同步重要改进，高级工具自动获得更新

高内聚原则：

opencode-wrapper.ts 与 opencode_bun_adapter.py 在同一目录（adapters/）
Wrapper 是适配器的一部分，不是独立脚本

性能权衡：

基础工具（高频）：Python 实现避免子进程开销
高级工具（低频）：Bun 适配器避免重复实现复杂逻辑

tools-adapters.md 4.8 KB Histórico Raw