chore

ARCHITECTURE_IMPROVEMENT.md

@@ -1,137 +0,0 @@
-# 架构改进：移除不必要的 uid 参数
-
-## 问题识别
-
-用户发现了一个架构设计问题：框架在 `agent/tools/registry.py` 中**无条件注入 uid 参数**，导致所有工具函数都必须声明 `uid: str = ""` 参数，即使它们从不使用这个参数。
-
-### 原始实现的问题
-
-```python
-# agent/tools/registry.py (旧代码)
-# 注入 uid - 无条件注入 ❌
-kwargs = {**arguments, "uid": uid}
-
-# 注入 context - 条件注入 ✅
-sig = inspect.signature(func)
-if "context" in sig.parameters:
-    kwargs["context"] = context
-```
-
-**问题**：
-1. ❌ **不一致**：`context` 是条件注入，`uid` 却是无条件注入
-2. ❌ **强制依赖**：所有工具都必须声明 `uid: str = ""`，即使不使用
-3. ❌ **样板代码**：导致大量无用的参数声明和文档
-4. ❌ **违反原则**：违反了"需要什么就传什么"的设计原则
-
-## 解决方案
-
-### 1. 修复框架注入逻辑
-
-将 uid 改为**条件注入**，与 context 保持一致：
-
-```python
-# agent/tools/registry.py (新代码)
-# 准备参数：只注入函数需要的参数
-kwargs = {**arguments}
-sig = inspect.signature(func)
-
-# 注入 uid（如果函数接受） ✅
-if "uid" in sig.parameters:
-    kwargs["uid"] = uid
-
-# 注入 context（如果函数接受） ✅
-if "context" in sig.parameters:
-    kwargs["context"] = context
-```
-
-**优势**：
-- ✅ **一致性**：uid 和 context 都采用条件注入
-- ✅ **灵活性**：工具可以自由选择是否使用 uid
-- ✅ **简洁性**：不需要的工具不必声明 uid 参数
-- ✅ **符合原则**：遵循"需要什么就传什么"的设计原则
-
-### 2. 清理所有 builtin 工具
-
-从所有不使用 uid 的工具中移除了 uid 参数：
-
-#### 修改的文件 (12个)
-
-| 文件 | 修改的函数数量 |
-|------|--------------|
-| `agent/tools/builtin/browser/baseClass.py` | 22 个函数 |
-| `agent/tools/builtin/read.py` | 1 个函数 |
-| `agent/tools/builtin/write.py` | 1 个函数 |
-| `agent/tools/builtin/edit.py` | 1 个函数 |
-| `agent/tools/builtin/bash.py` | 1 个函数 |
-| `agent/tools/builtin/grep.py` | 1 个函数 |
-| `agent/tools/builtin/glob.py` | 1 个函数 |
-| `agent/tools/builtin/search.py` | 2 个函数 |
-| `agent/tools/builtin/goal.py` | 1 个函数 |
-| `agent/tools/builtin/skill.py` | 2 个函数 |
-| `agent/tools/builtin/sandbox.py` | 4 个函数 |
-| **总计** | **37 个函数** |
-
-#### 每个函数的修改
-
-对于每个函数，完成了：
-1. ✅ 从函数签名中移除 `uid: str = ""` 参数
-2. ✅ 从 docstring 中移除 uid 相关的 Args 说明
-3. ✅ 保留其他所有参数和文档不变
-4. ✅ 函数实现逻辑完全未改动
-
-### 3. 验证结果
-
-```bash
-✅ 所有 13 个文件语法检查通过
-✅ 无残留的 uid 参数（grep 检查：0 个匹配）
-```
-
-## 如何使用 uid 参数
-
-如果某个工具**确实需要**使用 uid 参数（例如需要根据用户ID查询数据），只需在函数签名中声明它：
-
-```python
-@tool()
-async def get_user_notes(query: str, uid: str = "") -> ToolResult:
-    """
-    获取用户的笔记
-
-    Args:
-        query: 搜索关键词
-        uid: 用户ID（框架自动注入）
-
-    Returns:
-        ToolResult: 笔记列表
-    """
-    # 使用 uid 查询数据库
-    notes = await db.query_notes(user_id=uid, query=query)
-    return ToolResult(output=notes)
-```
-
-框架会自动检测到 `uid` 参数并注入它。
-
-## 影响范围
-
-### 兼容性
-
-- ✅ **向后兼容**：现有的需要 uid 的工具（如果有的话）仍然可以正常工作
-- ✅ **新工具**：新工具不再需要强制声明 uid 参数
-- ✅ **无破坏性变更**：所有测试应该继续通过
-
-### 代码质量改进
-
-- 📉 **减少样板代码**：移除了 37 个不必要的参数声明
-- 📈 **提高可读性**：函数签名更简洁，只显示真正使用的参数
-- 📈 **提高一致性**：uid 和 context 采用相同的注入模式
-- 📈 **更符合 Python 习惯**：不强制声明未使用的参数
-
-## 总结
-
-这次架构改进：
-
-1. **修复了框架的设计缺陷**：将 uid 从无条件注入改为条件注入
-2. **清理了所有不必要的样板代码**：移除了 37 个函数的 uid 参数
-3. **提高了代码质量**：更简洁、更一致、更符合 Python 习惯
-4. **保持向后兼容**：不影响现有功能
-
-**感谢用户敏锐的观察！** 这个改进使框架更加优雅和易用。

agent/tools/builtin/browser/FILE_OPERATIONS.md

@@ -1,201 +0,0 @@
-# Browser-Use 文件操作指南
-
-## 概述
-
-browser-use 的文件系统工具已迁移到使用 `agent.tools.builtin` 中更强大的实现。
-
-## 文件目录说明
-
-### 浏览器专用目录
-- **路径**: `.browser_use_files/` (在当前工作目录下)
-- **用途**: 存储浏览器会话产生的临时文件
-  - 浏览器下载的文件
-  - 上传到浏览器的文件
-  - 页面截图
-  - 浏览器任务生成的数据
-
-### 项目文件
-- **路径**: 项目根目录及其子目录
-- **用途**: 代码、配置、文档等项目文件
-- **工具**: 使用 builtin 文件工具操作
-
-## 文件工具对比
-
-| 功能 | Browser-Use (已移除) | Builtin (推荐使用) | 增强功能 |
-|------|---------------------|-------------------|---------|
-| 读取文件 | `read_file(file_name)` | `read_file(file_path, offset, limit)` | ✅ 分页读取<br>✅ 图片/PDF支持<br>✅ 二进制检测 |
-| 写入文件 | `write_file(file_name, content, append)` | `write_file(file_path, content, append)` | ✅ Diff预览<br>✅ 追加模式 |
-| 编辑文件 | `replace_file(file_name, old_str, new_str)` | `edit_file(file_path, old_string, new_string, replace_all)` | ✅ 9种智能匹配<br>✅ Diff预览 |
-
-## 使用示例
-
-### 1. 写入文件（覆盖模式）
-
-```python
-from agent.tools.builtin.write import write_file
-
-# 保存浏览器抓取的数据
-await write_file(
-    file_path=".browser_use_files/products.json",
-    content='{"products": [...]}',
-    append=False  # 覆盖写入
-)
-```
-
-### 2. 写入文件（追加模式）
-
-```python
-# 持续抓取数据并追加到文件
-for page in range(1, 10):
-    data = await scrape_page(page)
-    await write_file(
-        file_path=".browser_use_files/data.jsonl",
-        content=f"{data}\n",
-        append=True  # 追加写入
-    )
-```
-
-### 3. 读取文件
-
-```python
-from agent.tools.builtin.read import read_file
-
-# 读取之前保存的数据
-result = await read_file(
-    file_path=".browser_use_files/products.json"
-)
-print(result.output)
-
-# 分页读取大文件
-result = await read_file(
-    file_path=".browser_use_files/large_data.txt",
-    offset=1000,  # 从第1000行开始
-    limit=500     # 读取500行
-)
-```
-
-### 4. 编辑文件
-
-```python
-from agent.tools.builtin.edit import edit_file
-
-# 替换配置文件中的值
-await edit_file(
-    file_path="config.json",
-    old_string='"api_key": "old_key"',
-    new_string='"api_key": "new_key"',
-    replace_all=False  # 只替换唯一匹配
-)
-
-# 替换所有匹配项
-await edit_file(
-    file_path="data.txt",
-    old_string="http://",
-    new_string="https://",
-    replace_all=True  # 替换所有
-)
-```
-
-### 5. 在浏览器任务中使用
-
-```python
-from agent.tools.builtin.browser.baseClass import (
-    navigate_to_url,
-    extract_content,
-    done
-)
-from agent.tools.builtin.write import write_file
-from agent.tools.builtin.read import read_file
-
-async def scrape_task():
-    # 1. 导航到目标网站
-    await navigate_to_url("https://example.com/products")
-
-    # 2. 提取内容
-    result = await extract_content(
-        query="提取所有产品的名称、价格和链接"
-    )
-
-    # 3. 保存到浏览器专用目录
-    await write_file(
-        file_path=".browser_use_files/products.json",
-        content=result.output
-    )
-
-    # 4. 读取验证
-    saved = await read_file(
-        file_path=".browser_use_files/products.json"
-    )
-
-    # 5. 标记任务完成
-    await done(
-        text="已提取并保存产品数据",
-        success=True,
-        files_to_display=[".browser_use_files/products.json"]
-    )
-```
-
-## 智能匹配示例
-
-Builtin 的 `edit_file` 支持9种智能匹配策略，比简单的字符串替换更灵活：
-
-```python
-# 即使缩进不同也能匹配
-await edit_file(
-    file_path="script.py",
-    old_string="""
-def foo():
-    print("hello")
-    """,
-    new_string="""
-def foo():
-    print("world")
-    """
-)
-
-# 支持空白归一化匹配
-await edit_file(
-    file_path="config.txt",
-    old_string="key  =   value",  # 多个空格
-    new_string="key = new_value"  # 会正确匹配并替换
-)
-```
-
-## 最佳实践
-
-1. **浏览器临时文件**: 使用 `.browser_use_files/` 目录
-   ```python
-   await write_file(".browser_use_files/temp_data.json", data)
-   ```
-
-2. **项目文件**: 使用相对或绝对路径
-   ```python
-   await write_file("output/results.csv", csv_data)
-   await edit_file("config.yaml", old_val, new_val)
-   ```
-
-3. **大文件处理**: 使用分页读取
-   ```python
-   # 每次读取2000行
-   offset = 0
-   while True:
-       result = await read_file("large.txt", offset=offset, limit=2000)
-       if not result.metadata.get("truncated"):
-           break
-       offset += 2000
-   ```
-
-4. **数据追加**: 使用append模式
-   ```python
-   # 持续写入日志
-   await write_file("logs.txt", f"{timestamp}: {message}\n", append=True)
-   ```
-
-## 注意事项
-
-- ✅ Builtin工具支持绝对路径和相对路径
-- ✅ 自动创建父目录
-- ✅ 提供详细的diff预览
-- ✅ 支持UTF-8编码
-- ⚠️ 二进制文件建议使用Python标准库直接操作
-- ⚠️ 大文件（>50KB）会被截断显示，但完整内容会保存在metadata中