Agent/docs/tools-adapters.md

工具适配器

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

---

⚠️ 第三方工具接入规范

工具分类原则：

类型	实现方式	目录结构	示例
高频&简单工具	Python 原生实现	agent/tools/builtin/	read_file, edit_file, bash_command
复杂&低频工具	第三方仓库 + 适配器	vendor/ + agent/tools/adapters/ + agent/tools/advanced/	webfetch, lsp_diagnostics
CLI 命令行工具	pip 安装到虚拟环境	requirements.txt + bash_command 调用	browser-use

接入流程：

1. 简单工具：直接在 builtin/ 实现

   • 参考第三方设计（如 opencode）
   • Python 完整实现
   • 通过 @tool 装饰器注册

2. 复杂工具：通过适配器调用

   • 第三方仓库 → vendor/（Git Submodule，只读）
   • 适配器/桥接 → agent/tools/adapters/
   • 工具注册 → agent/tools/advanced/

3. CLI 工具：通过 bash_command 调用

   • 添加到 requirements.txt
   • pip 安装到项目虚拟环境
   • 通过 bash_command 工具调用 CLI
   • 在 skills/ 中提供使用指导

设计目标：

• 参考 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 优先）
skill	builtin/skill.py	加载技能文档
list_skills	builtin/skill.py	列出可用技能

参考源：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 工具

CLI 工具（pip 安装）

工具	安装方式	调用方式
browser-use	pip install browser-use	bash_command 调用 CLI

依赖检查：自动检测并提示缺失的依赖

# 1. 加载 skill 时自动检查（会提示缺失的依赖）
await skill(skill_name="browser-use")
# 输出包含：⚠️ Setup Required - pip install browser-use / uvx browser-use install

# 2. 手动检查依赖（使用 skill 自带的配置工具）
from agent.skills.browser_use import check_browser_use
await check_browser_use()
# 返回详细的依赖状态

# 3. 自动安装 Chromium（可选，需要下载 200-300MB）
from agent.skills.browser_use import install_browser_use_chromium
await install_browser_use_chromium()

使用示例：

# Agent 加载使用指南
await skill(skill_name="browser-use")

# 通过 bash_command 调用 CLI
await bash_command(command="browser-use open https://example.com")
await bash_command(command="browser-use state")
await bash_command(command="browser-use click 5")

Skill 文档：agent/skills/browser_use/browser-use.md 提供完整的 CLI 使用指南

---

适配器接口

实现：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"

同步改进

1. 查看 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 适配器避免重复实现复杂逻辑