# 工具适配器

> 参考 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](https://bun.sh/) 运行时

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

### CLI 工具（pip 安装）

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

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

```python
# 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()
```

**使用示例**：
```python
# 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 参考

### 检查更新

```bash
# 查看 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 变更**：
   ```bash
   cd vendor/opencode
   git log --oneline --since="1 month ago" -- packages/opencode/src/tool/
   ```

2. **对比实现差异**：
   - 查看 opencode 的具体改动
   - 评估是否需要同步到 Python 实现

3. **更新 Python 实现**：
   - 在 `agent/tools/builtin/` 中更新对应工具
   - 更新代码注释中的参考位置

4. **测试验证**：
   ```bash
   pytest tests/tools/builtin/ -v
   ```

---

## 使用示例

```python
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 适配器避免重复实现复杂逻辑