工具系统文档

Agent 框架的工具系统：定义、注册、执行工具调用。

核心概念

三个核心类型

from reson_agent import tool, ToolResult, ToolContext

@tool()
async def my_tool(arg: str, context: Optional[ToolContext] = None) -> ToolResult:
    return ToolResult(
        title="Success",
        output="Result content"
    )

类型	作用	定义位置
`@tool`	装饰器，自动注册工具并生成 Schema	`tools/registry.py`
`ToolResult`	工具执行结果（支持记忆管理）	`tools/models.py`
`ToolContext`	工具执行上下文（依赖注入）	`tools/models.py`

工具的生命周期

1. 定义工具
   ↓ @tool() 装饰器
2. 自动注册到 ToolRegistry
   ↓ 生成 OpenAI Tool Schema（跳过 hidden_params）
3. LLM 选择工具并生成参数
   ↓ registry.execute(name, args)
4. 注入框架参数（hidden_params + inject_params）
   ↓ 调用工具函数
5. 返回 ToolResult
   ↓ 转换为 LLM 消息
6. 添加到对话历史

参数注入机制

工具参数分为三类：

业务参数：LLM 可见，由 LLM 填写（如 query, limit）
隐藏参数：LLM 不可见，框架自动注入（如 context, uid）
注入参数：LLM 可见，框架自动注入默认值或与 LLM 值合并（如 owner, tags）

@tool(
    hidden_params=["context", "owner"],  # 不生成 schema，LLM 看不到
    inject_params={                       # 声明注入规则
        "owner": {"mode": "default", "key": "knowledge_config.owner"},
        "tags":  {"mode": "merge",   "key": "knowledge_config.default_tags"},
        "scopes": {"mode": "merge",  "key": "knowledge_config.default_scopes"},
    }
)
async def knowledge_save(
    task: str,                          # 业务参数：LLM 填写
    content: str,                       # 业务参数：LLM 填写
    types: List[str],                   # 业务参数：LLM 填写
    tags: Optional[Dict] = None,        # 注入参数：LLM 可填，框架合并默认值
    scopes: Optional[List] = None,      # 注入参数：LLM 可填，框架合并默认值
    owner: Optional[str] = None,        # 隐藏参数：LLM 看不到，框架注入
    context: Optional[ToolContext] = None,  # 隐藏参数：LLM 看不到
) -> ToolResult:
    """保存知识到知识库"""
    ...

inject_params 声明格式：

inject_params={
    "param_name": {
        "mode": "default" | "merge",  # 注入模式
        "key": "config_obj.field",    # 从 context 中取值的路径
    }
}

mode: "default"：LLM 未提供时注入框架值
mode: "merge"：框架值与 LLM 值合并。dict 按 key 合并（框架 key 不可被覆盖，LLM 可追加新 key）；list 合并去重

值的来源：通过 key 指定从 context 中取值的路径（如 "knowledge_config.default_tags" 表示 context["knowledge_config"].default_tags）。runner 在调用 execute() 时将配置对象放入 context，框架根据 key 路径自动取值。

注入时机：

Schema 生成时：跳过 hidden_params，不暴露给 LLM
工具执行前：注入 hidden_params 和 inject_params

实现位置：

Schema 生成：agent/tools/schema.py:SchemaGenerator.generate()
参数注入：agent/tools/registry.py:ToolRegistry.execute()

定义工具

最简形式

from reson_agent import tool

@tool()
async def hello(name: str) -> str:
    """向用户问好"""
    return f"Hello, {name}!"

要点：

可以是同步或异步函数
返回值自动序列化为 JSON
所有参数默认对 LLM 可见

带框架参数

@tool(hidden_params=["context", "uid"])
async def search_notes(
    query: str,
    limit: int = 10,
    context: Optional[ToolContext] = None,
    uid: str = ""
) -> str:
    """
    搜索笔记

    Args:
        query: 搜索关键词
        limit: 返回结果数量
    """
    # context 和 uid 由框架注入，LLM 看不到这两个参数
    ...

带参数注入

@tool(
    hidden_params=["context", "owner"],
    inject_params={
        "owner": {"mode": "default", "key": "knowledge_config.owner"},
        "tags":  {"mode": "merge",   "key": "knowledge_config.default_tags"},
        "scopes": {"mode": "merge",  "key": "knowledge_config.default_scopes"},
    }
)
async def knowledge_save(
    task: str,
    content: str,
    types: List[str],
    tags: Optional[Dict] = None,  # LLM 可填，框架合并默认值
    scopes: Optional[List] = None,  # LLM 可填，框架合并默认值
    owner: Optional[str] = None,  # LLM 看不到，框架注入
    context: Optional[ToolContext] = None
) -> ToolResult:
    """
    保存知识

    Args:
        task: 任务描述
        content: 知识内容
        types: 知识类型
        tags: 业务标签（可选，框架合并默认值）
        scopes: 可见范围（可选，框架合并默认值）
    """
    ...

注入规则：

inject_params 的 value 是一个 dict，包含：
- mode: "default"（LLM 未提供则注入）或 "merge"（与 LLM 值合并）
- key: 从 context 中取值的路径（如 "knowledge_config.default_tags"）
参数同时在 hidden_params 中时，LLM 不可见，框架直接注入

带 UI 元数据

@tool(
    display={
        "zh": {
            "name": "搜索笔记",
            "params": {
                "query": "搜索关键词",
                "limit": "结果数量"
            }
        },
        "en": {
            "name": "Search Notes",
            "params": {
                "query": "Search query",
                "limit": "Result limit"
            }
        }
    }
)
async def search_notes(query: str, limit: int = 10, uid: str = "") -> str:
    """搜索用户的笔记"""
    ...

ToolResult 和记忆管理

基础用法

from reson_agent import ToolResult

@tool()
async def read_file(path: str) -> ToolResult:
    content = Path(path).read_text()

    return ToolResult(
        title=f"Read {path}",
        output=content
    )

双层记忆管理

问题：某些工具返回大量内容（如 Browser-Use 的 extract），如果每次都放入对话历史，会快速耗尽 context。

解决：ToolResult 支持双层记忆：

@tool()
async def extract_page_data(url: str) -> ToolResult:
    # 假设提取了 10K tokens 的内容
    full_content = extract_all_data(url)

    return ToolResult(
        title="Extracted page data",
        output=full_content,  # 完整内容（可能很长）
        long_term_memory=f"Extracted {len(full_content)} chars from {url}",  # 简短摘要
        include_output_only_once=True  # output 只给 LLM 看一次
    )

效果：

第一次：LLM 看到 output（完整内容）+ long_term_memory（摘要）
后续：LLM 只看到 long_term_memory（摘要）

对话历史示例：

[User] 提取 amazon.com 的商品价格
[Assistant] 调用 extract_page_data(url="amazon.com")
[Tool]
# Extracted page data

<完整的 10K tokens 数据...>

Summary: Extracted 10000 chars from amazon.com

[User] 现在保存到文件
[Assistant] 调用 write_file(content="...")
[Tool] (此时不再包含 10K tokens，只有摘要)
Summary: Extracted 10000 chars from amazon.com

错误处理

@tool()
async def risky_operation() -> ToolResult:
    try:
        result = perform_operation()
        return ToolResult(
            title="Success",
            output=result
        )
    except Exception as e:
        return ToolResult(
            title="Failed",
            output="",
            error=str(e)
        )

附件和图片

@tool()
async def generate_report() -> ToolResult:
    report_path = create_pdf_report()
    screenshot_data = take_screenshot()

    return ToolResult(
        title="Report generated",
        output="Report created successfully",
        attachments=[report_path],  # 文件路径列表
        images=[{
            "name": "screenshot.png",
            "data": screenshot_data  # Base64 或路径
        }]
    )

ToolContext 和依赖注入

基本概念

工具函数可以声明需要 ToolContext 参数，框架自动注入。需要在 @tool() 装饰器中声明 hidden_params=["context"]，使其对 LLM 不可见。

from reson_agent import ToolContext

@tool(hidden_params=["context"])
async def get_current_state(context: Optional[ToolContext] = None) -> ToolResult:
    return ToolResult(
        title="Current state",
        output=f"Trace ID: {context.trace_id}\nStep ID: {context.step_id}"
    )

ToolContext 字段

class ToolContext(Protocol):
    # 基础字段（所有工具）
    trace_id: str               # 当前 Trace ID
    step_id: str                # 当前 Step ID
    uid: Optional[str]          # 用户 ID

    # 扩展字段（由 runner 注入）
    store: Optional[TraceStore]     # Trace 存储
    runner: Optional[AgentRunner]   # Runner 实例
    goal_tree: Optional[GoalTree]   # 目标树
    goal_id: Optional[str]          # 当前 Goal ID
    config: Optional[RunConfig]     # 运行配置

    # 浏览器相关（Browser-Use 集成）
    browser_session: Optional[Any]      # 浏览器会话
    page_url: Optional[str]             # 当前页面 URL
    file_system: Optional[Any]          # 文件系统访问
    sensitive_data: Optional[Dict]      # 敏感数据

    # 额外上下文
    context: Optional[Dict[str, Any]]   # 额外上下文数据

使用示例

@tool(hidden_params=["context"])
async def analyze_current_page(context: Optional[ToolContext] = None) -> ToolResult:
    """分析当前浏览器页面"""

    if not context or not context.browser_session:
        return ToolResult(
            title="Error",
            error="Browser session not available"
        )

    # 使用浏览器会话
    page_content = await context.browser_session.get_content()

    return ToolResult(
        title=f"Analyzed {context.page_url}",
        output=page_content,
        long_term_memory=f"Analyzed page at {context.page_url}"
    )

创建 ToolContext

Runner 在执行工具时自动创建并注入 context：

# 在 AgentRunner._agent_loop 中
context = {
    "store": self.trace_store,
    "trace_id": trace_id,
    "goal_id": current_goal_id,
    "runner": self,
    "goal_tree": goal_tree,
    "config": config,
}

result = await self.tools.execute(
    tool_name,
    tool_args,
    uid=config.uid or "",
    context=context
)

高级特性

1. 需要用户确认

@tool(requires_confirmation=True)
async def delete_all_notes(uid: str = "") -> ToolResult:
    """删除所有笔记（危险操作）"""
    # 执行前会等待用户确认
    ...

适用场景：

删除操作
发送消息
修改重要设置
任何不可逆操作

2. 可编辑参数

@tool(editable_params=["query", "filters"])
async def advanced_search(
    query: str,
    filters: Optional[Dict] = None,
    uid: str = ""
) -> ToolResult:
    """高级搜索"""
    # LLM 生成参数后，用户可以编辑 query 和 filters
    ...

适用场景：

搜索查询
内容创建
需要用户微调的参数

3. 域名过滤（URL Patterns）

场景：某些工具只在特定网站可用，减少无关工具的 context 占用。

@tool(url_patterns=["*.google.com", "www.google.*"])
async def google_advanced_search(
    query: str,
    date_range: Optional[str] = None,
    uid: str = ""
) -> ToolResult:
    """Google 高级搜索技巧（仅在 Google 页面可用）"""
    ...

@tool(url_patterns=["*.github.com"])
async def github_pr_create(
    title: str,
    body: str,
    uid: str = ""
) -> ToolResult:
    """创建 GitHub PR（仅在 GitHub 页面可用）"""
    ...

@tool()  # 无 url_patterns，所有页面都可用
async def take_screenshot() -> ToolResult:
    """截图（所有页面都可用）"""
    ...

支持的模式：

# 通配符域名
"*.google.com"        # 匹配 www.google.com, mail.google.com
"www.google.*"        # 匹配 www.google.com, www.google.co.uk

# 路径匹配
"https://github.com/**/issues"  # 匹配所有 issues 页面

# 多个模式
url_patterns=["*.github.com", "*.gitlab.com"]

使用过滤后的工具：

from reson_agent import get_tool_registry

registry = get_tool_registry()

# 根据 URL 获取可用工具
current_url = "https://www.google.com/search?q=test"
tool_names = registry.get_tool_names(current_url)
# 返回：["google_advanced_search", "take_screenshot"]（不包含 github_pr_create）

# 获取过滤后的 Schema
schemas = registry.get_schemas_for_url(current_url)
# 传递给 LLM，只包含相关工具

效果：

场景	无过滤	有过滤	节省
在 Google 页面	35 工具 (~5K tokens)	20 工具 (~3K tokens)	40%
在 GitHub 页面	35 工具 (~5K tokens)	18 工具 (~2.5K tokens)	50%

4. 敏感数据处理

场景：浏览器自动化需要输入密码、Token，但不想在对话历史中显示明文。

设置敏感数据：

sensitive_data = {
    # 格式 1：全局密钥（适用于所有域名）
    "api_key": "sk-xxxxx",

    # 格式 2：域名特定密钥（推荐）
    "*.github.com": {
        "github_token": "ghp_xxxxx",
        "github_password": "my_secret_password"
    },

    "*.google.com": {
        "google_email": "user@example.com",
        "google_password": "another_secret",
        "google_2fa_bu_2fa_code": "JBSWY3DPEHPK3PXP"  # TOTP secret
    }
}

LLM 输出占位符：

# LLM 决定需要输入密码
{
    "tool": "browser_input",
    "arguments": {
        "index": 5,
        "text": "<secret>github_password</secret>"  # 占位符
    }
}

自动替换：

# 执行工具前，框架自动替换
registry.execute(
    "browser_input",
    arguments={"index": 5, "text": "<secret>github_password</secret>"},
    context={"page_url": "https://github.com/login"},
    sensitive_data=sensitive_data
)

# 实际执行：
# arguments = {"index": 5, "text": "my_secret_password"}

TOTP 2FA 支持：

# 密钥以 _bu_2fa_code 结尾，自动生成 TOTP 代码
sensitive_data = {
    "*.google.com": {
        "google_2fa_bu_2fa_code": "JBSWY3DPEHPK3PXP"
    }
}

# LLM 输出
{
    "text": "<secret>google_2fa_bu_2fa_code</secret>"
}

# 自动替换为当前的 6 位数字验证码
{
    "text": "123456"  # 当前时间的 TOTP 代码
}

完整示例：

from reson_agent import get_tool_registry, ToolContext

# 设置敏感数据
sensitive_data = {
    "*.github.com": {
        "github_token": "ghp_xxxxxxxxxxxxx",
        "github_2fa_bu_2fa_code": "JBSWY3DPEHPK3PXP"
    }
}

# 执行工具（LLM 输出的参数包含占位符）
result = await registry.execute(
    "github_api_call",
    arguments={
        "endpoint": "/user",
        "token": "<secret>github_token</secret>",
        "totp": "<secret>github_2fa_bu_2fa_code</secret>"
    },
    context={"page_url": "https://github.com"},
    sensitive_data=sensitive_data
)

# 实际调用时参数已被替换：
# {
#     "endpoint": "/user",
#     "token": "ghp_xxxxxxxxxxxxx",
#     "totp": "123456"
# }

安全性：

✅ 对话历史中只有 <secret>key</secret> 占位符
✅ 实际密码仅在执行时注入
✅ 域名匹配防止密钥泄露到错误的网站
✅ TOTP 验证码实时生成，无需手动输入

5. 工具使用统计

自动记录：

每个工具调用自动记录：

调用次数
成功/失败次数
平均执行时间
最后调用时间

查询统计：

from reson_agent import get_tool_registry

registry = get_tool_registry()

# 获取所有工具统计
all_stats = registry.get_stats()
print(all_stats)
# {
#     "search_notes": {
#         "call_count": 145,
#         "success_count": 142,
#         "failure_count": 3,
#         "average_duration": 0.32,
#         "success_rate": 0.979,
#         "last_called": 1704123456.78
#     },
#     ...
# }

# 获取单个工具统计
search_stats = registry.get_stats("search_notes")

# 获取 Top 工具
top_tools = registry.get_top_tools(limit=5, by="call_count")
# ['search_notes', 'read_file', 'browser_click', ...]

top_by_success = registry.get_top_tools(limit=5, by="success_rate")
fastest_tools = registry.get_top_tools(limit=5, by="average_duration")

优化工具排序：

# 根据使用频率优化工具顺序
def get_optimized_schemas(registry, current_url):
    # 获取可用工具
    tool_names = registry.get_tool_names(current_url)

    # 按调用次数排序（高频工具排前面）
    all_stats = registry.get_stats()
    sorted_tools = sorted(
        tool_names,
        key=lambda name: all_stats.get(name, {}).get("call_count", 0),
        reverse=True
    )

    # 返回排序后的 Schema
    return registry.get_schemas(sorted_tools)

监控和告警：

# 监控工具失败率
stats = registry.get_stats()
for tool_name, tool_stats in stats.items():
    if tool_stats["call_count"] > 10 and tool_stats["success_rate"] < 0.8:
        logger.warning(
            f"Tool {tool_name} has low success rate: "
            f"{tool_stats['success_rate']:.1%} "
            f"({tool_stats['failure_count']}/{tool_stats['call_count']} failures)"
        )

# 监控执行时间
for tool_name, tool_stats in stats.items():
    if tool_stats["average_duration"] > 5.0:
        logger.warning(
            f"Tool {tool_name} is slow: "
            f"average {tool_stats['average_duration']:.2f}s"
        )

6. 组合使用

完整示例：浏览器自动化工具

@tool(
    requires_confirmation=False,
    editable_params=["query"],
    url_patterns=["*.google.com"],
    display={
        "zh": {"name": "Google 搜索", "params": {"query": "搜索关键词"}},
        "en": {"name": "Google Search", "params": {"query": "Query"}}
    }
)
async def google_search(
    query: str,
    ctx: ToolContext,
    uid: str = ""
) -> ToolResult:
    """
    在 Google 执行搜索

    仅在 Google 页面可用，支持敏感数据注入
    """
    # 使用浏览器会话
    if not ctx.browser_session:
        return ToolResult(title="Error", error="Browser session not available")

    # 敏感数据已在 registry.execute() 中自动处理
    # 例如 query 中的 <secret>api_key</secret> 已被替换

    # 执行搜索
    await ctx.browser_session.navigate(f"https://google.com/search?q={query}")

    # 提取结果
    results = await ctx.browser_session.extract_results()

    return ToolResult(
        title=f"Search results for {query}",
        output=json.dumps(results),
        long_term_memory=f"Searched Google for '{query}', found {len(results)} results",
        include_output_only_once=True
    )

使用：

# 设置环境
registry = get_tool_registry()
sensitive_data = {"*.google.com": {"search_api_key": "sk-xxxxx"}}

# Agent 在 Google 页面时
current_url = "https://www.google.com"

# 获取工具（自动过滤）
tool_names = registry.get_tool_names(current_url)
# 包含 google_search（匹配 *.google.com）

# LLM 决定使用工具（可能包含敏感占位符）
tool_call = {
    "name": "google_search",
    "arguments": {
        "query": "site:github.com <secret>search_api_key</secret>"
    }
}

# 执行（自动替换敏感数据）
result = await registry.execute(
    tool_call["name"],
    tool_call["arguments"],
    context={"page_url": current_url, "browser_session": browser},
    sensitive_data=sensitive_data
)

# 查看统计
stats = registry.get_stats("google_search")
print(f"Success rate: {stats['success_rate']:.1%}")

内置基础工具

参考 opencode 实现的文件操作和命令执行工具

框架提供一组内置的基础工具，用于文件读取、编辑、搜索和命令执行等常见任务。这些工具参考了 opencode 的成熟设计，在 Python 中重新实现。

实现位置：

工具实现：agent/tools/builtin/
适配器层：agent/tools/adapters/
OpenCode 参考：vendor/opencode/ (git submodule)

详细文档：参考 docs/tools-adapters.md

可用工具

工具	功能	参考
`read_file`	读取单个文件（文本 / 图片 / PDF）	opencode read.ts
`read_images`	批量读取图片，支持自动降采样和网格拼图	自研
`edit_file`	智能文件编辑（多种匹配策略）	opencode edit.ts
`write_file`	写入文件（创建或覆盖）	opencode write.ts
`bash_command`	执行 shell 命令	opencode bash.ts
`glob_files`	文件模式匹配	opencode glob.ts
`grep_content`	内容搜索（正则表达式）	opencode grep.ts
`agent`	创建 Agent 执行任务（单任务 delegate / 多任务并行 explore）	自研
`evaluate`	评估目标执行结果是否满足要求	自研
`toolhub_health`	检查 ToolHub 远程工具库服务状态	自研
`toolhub_search`	搜索/发现 ToolHub 远程工具	自研
`toolhub_call`	调用 ToolHub 远程工具（图片参数支持本地文件路径）	自研
`ask_knowledge`	向知识库查询信息（通过 KnowHub Librarian）	自研
`upload_knowledge`	上传调研结果到知识库	自研

`read_file` vs `read_images`

场景	工具
读取 1 张图片 / 文本 / PDF	`read_file`
批量读取 2 张以上图片	`read_images`
需要 AI 对多张图做对比选择（选图、挑错、横向比较）	`read_images` 且 `layout="grid"`
需要对多张图逐张独立分析	`read_images` 且 `layout="separate"`

read_images 默认 layout="grid" — 多张图拼成一张带索引编号的网格图（1,2,3…），省 token 的同时让 LLM 能在单次注视中做横向对比。拼图和降采样在内部组合使用：先降采样每张缩略图，再拼成整图，最终图片大小约等于一张普通图的开销，而非所有原图的累积。

Grid 模式的 16 张硬上限： grid 模式下单次调用最多 16 张图片。超过会报错，需要分批调用。上限来自于 LLM 内部图片缩放的物理限制——Claude/Qwen-VL 会把图片缩到长边约 1568 像素，当拼图里格子太多时，每格会糊到无法识别。16 张对应 4×4 布局，每格约 300px，缩放后仍能保持约 280px，人物和场景细节仍然可辨。如需处理更多图片，或切换到 layout="separate"（无数量限制但每张图都有独立的结构开销 token）。

自适应布局： grid 模式下根据图片数量动态选择列数和缩略图尺寸，小批量时每张图更清晰：

图片数	布局	每格大小
2 张	2 列	500px
3-4 张	2 列	450px
5-6 张	3 列	400px
7-9 张	3 列	380px
10-12 张	4 列	320px
13-16 张	4 列	300px

关于标签/标题： read_images 的拼图不显示文件名，只显示索引序号——因为本地文件名（如 IMG_1234.jpg）对 LLM 理解内容没有帮助，而索引到原始路径的对照表通过返回文本提供，LLM 可以用"第 3 张"这种引用方式精确指代。对比之下 search_posts / youtube_search 的拼图会显示 label（帖子/视频标题），因为这些是内容型元数据，有实际信息量。这一差异反映在 build_image_grid(labels=...) 参数上：传 None 只画序号，传列表则在每格下方画标题。

网格和降采样的实现在 agent/tools/utils/image.py，search_posts 和 youtube_search 等工具也复用同一套拼图逻辑。

Agent 工具

创建子 Agent 执行任务。通过 task 参数的类型自动区分模式：

task 类型	模式	并行执行	工具权限
`str`（单任务）	delegate	❌	完整（除 agent/evaluate 外）
`List[str]`（多任务）	explore	✅	只读（read_file, grep_content, glob_files, goal）

@tool(description="创建 Agent 执行任务")
async def agent(
    task: Union[str, List[str]],
    messages: Optional[Union[Messages, List[Messages]]] = None,
    continue_from: Optional[str] = None,
    agent_type: Optional[str] = None,
    skills: Optional[List[str]] = None,
    context: Optional[dict] = None,
) -> Dict[str, Any]:

参数说明：

task: 任务描述（字符串=单任务，列表=多任务并行）
messages: 预置消息（None/1D 列表/2D 列表）
continue_from: 继续已有 trace（仅单任务）
agent_type: 子 Agent 类型，决定 preset 和默认 skills（如 "tool_research"）
skills: 附加到 system prompt 的 skill 名称列表，覆盖 preset 默认值
context: 框架自动注入的上下文

messages 参数：

None：无预置消息
Messages（1D 列表）：所有 agent 共享
List[Messages]（2D 列表）：per-agent 独立消息

运行时判断：messages[0] 是 dict → 1D 共享；是 list → 2D per-agent。

agent_type 与 Presets：

通过 agent_type 参数指定预定义的 Agent 配置（工具权限、system prompt、skills 等）
项目可在 presets.json 中定义自定义 preset，支持从 .prompt 文件加载 system prompt
详见 agent/docs/architecture.md 的 "Agent 预设" 章节和 examples/production/ 示例

单任务（delegate）：

适合委托专门任务（如代码分析、文档生成）
完整工具权限，可执行复杂操作
支持 continue_from 参数续跑已有 Sub-Trace

多任务（explore）：

适合对比多个方案（如技术选型、架构设计）
使用 asyncio.gather() 并行执行，显著提升效率
每个任务创建独立的 Sub-Trace，互不干扰
只读权限（文件系统层面），可使用 goal 工具管理计划
不支持 continue_from

Evaluate 工具

评估指定 Goal 的执行结果，提供质量评估和改进建议。

@tool(description="评估目标执行结果是否满足要求")
async def evaluate(
    messages: Optional[Messages] = None,
    target_goal_id: Optional[str] = None,
    continue_from: Optional[str] = None,
    context: Optional[dict] = None,
) -> Dict[str, Any]:

无 criteria 参数——代码自动从 GoalTree 注入目标描述
模型把执行结果和上下文放在 messages 中
target_goal_id 默认为当前 goal_id
只读工具权限
返回评估结论和改进建议

Sub-Trace 结构：

每个 agent/evaluate 调用创建独立的 Sub-Trace
Sub-Trace ID 格式：{parent_id}@{mode}-{序号}-{timestamp}-001
通过 parent_trace_id 和 parent_goal_id 建立父子关系
Sub-Trace 信息存储在独立的 trace 目录中

Goal 集成：

agent/evaluate 调用会将 Goal 标记为 type: "agent_call"
agent_call_mode 记录使用的模式
sub_trace_ids 记录所有创建的 Sub-Trace
Goal 完成后，summary 包含格式化的汇总结果

实现位置：agent/tools/builtin/subagent.py

快速使用

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

# 读取文件
result = await read_file(file_path="config.py", limit=100)
print(result.output)

# 编辑文件（智能匹配）
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,
    description="Check git status"
)

核心特性

Read Tool 特性：

二进制文件检测
分页读取（offset/limit）
行长度和字节限制
图片/PDF 支持

Edit Tool 特性：

多种智能匹配策略：
- SimpleReplacer - 精确匹配
- LineTrimmedReplacer - 忽略行首尾空白
- WhitespaceNormalizedReplacer - 空白归一化
自动生成 unified diff
唯一性检查（防止错误替换）

Bash Tool 特性：

异步执行
超时控制（默认 120 秒）
工作目录设置
输出截断（防止过长）

更新 OpenCode 参考

内置工具参考 vendor/opencode/ 中的实现，通过 git submodule 管理：

# 更新 opencode 参考
cd vendor/opencode
git pull origin main
cd ../..
git add vendor/opencode
git commit -m "chore: update opencode reference"

# 查看最近变更
cd vendor/opencode
git log --oneline --since="1 month ago" -- packages/opencode/src/tool/

更新后，检查是否需要同步改进到 Python 实现。

集成 Browser-Use

适配器模式

将 Browser-Use 的 25 个工具适配为你的工具系统：

from browser_use import BrowserSession, Tools as BrowserUseTools
from reson_agent import tool, ToolResult, ToolContext

class BrowserToolsAdapter:
    """Browser-Use 工具适配器"""

    def __init__(self):
        self.session = BrowserSession(headless=False)
        self.browser_tools = BrowserUseTools()

    async def __aenter__(self):
        await self.session.__aenter__()
        return self

    async def __aexit__(self, *args):
        await self.session.__aexit__(*args)

    def register_all(self, registry):
        """批量注册所有 Browser-Use 工具"""
        for action_name, registered_action in self.browser_tools.registry.actions.items():
            self._adapt_action(registry, action_name, registered_action)

    def _adapt_action(self, registry, action_name, registered_action):
        """适配单个 Browser-Use action"""

        @tool()
        async def adapted_tool(args: dict, ctx: ToolContext) -> ToolResult:
            # 构建 Browser-Use 需要的 special context
            special_context = {
                'browser_session': self.session,
                'page_url': ctx.page_url,
                'file_system': ctx.file_system,
            }

            # 执行 Browser-Use action
            result = await registered_action.function(
                params=registered_action.param_model(**args),
                **special_context
            )

            # 转换 ActionResult -> ToolResult
            return ToolResult(
                title=action_name,
                output=result.extracted_content or '',
                long_term_memory=result.long_term_memory,
                include_output_only_once=result.include_extracted_content_only_once,
                error=result.error,
                attachments=result.attachments or [],
                images=result.images or [],
                metadata=result.metadata or {}
            )

        # 注册到你的 registry
        registry.register(adapted_tool, schema=generate_schema(registered_action))

使用示例

from reson_agent import AgentRunner

async def main():
    async with BrowserToolsAdapter() as browser:
        # 创建 Agent
        agent = AgentRunner(
            task="在 Amazon 找最便宜的 iPhone 15",
            tools=[],  # 空列表
        )

        # 批量注册浏览器工具
        browser.register_all(agent.tool_registry)

        # 现在 Agent 有 25 个浏览器工具 + 其他工具
        result = await agent.run()

Context 占用分析

工具类型	数量	Token 占用	占比（200K）
Browser-Use 工具	25	~4,000	2%
你的自定义工具	10	~1,000	0.5%
总计	35	~5,000	2.5%

结论：完全可接受，且 Prompt Caching 会优化后续调用。

最佳实践

1. 工具命名

# 好：清晰的动词 + 名词
@tool()
async def search_notes(...): ...

@tool()
async def create_document(...): ...

# 不好：模糊或过长
@tool()
async def do_something(...): ...

@tool()
async def search_and_filter_notes_with_advanced_options(...): ...

2. 返回结构化数据

# 好：返回 ToolResult 或结构化字典
@tool()
async def get_weather(city: str) -> ToolResult:
    data = fetch_weather(city)
    return ToolResult(
        title=f"Weather in {city}",
        output=json.dumps(data, indent=2)
    )

# 不好：返回纯文本
@tool()
async def get_weather(city: str) -> str:
    return "The weather is sunny, 25°C, humidity 60%"  # 难以解析

3. 错误处理

# 好：捕获异常并返回 ToolResult
@tool()
async def risky_operation() -> ToolResult:
    try:
        result = dangerous_call()
        return ToolResult(title="Success", output=result)
    except Exception as e:
        logger.error(f"Operation failed: {e}")
        return ToolResult(title="Failed", error=str(e))

# 不好：让异常传播（会中断 Agent 循环）
@tool()
async def risky_operation() -> str:
    return dangerous_call()  # 可能抛出异常

4. 记忆管理

# 好：大量数据用 include_output_only_once
@tool()
async def fetch_all_logs() -> ToolResult:
    logs = get_last_10000_logs()  # 很大
    return ToolResult(
        title="Fetched logs",
        output=logs,
        long_term_memory=f"Fetched {len(logs)} log entries",
        include_output_only_once=True  # 只给 LLM 看一次
    )

# 不好：大量数据每次都传给 LLM
@tool()
async def fetch_all_logs() -> str:
    return get_last_10000_logs()  # 每次都占用 context

5. 工具粒度

# 好：单一职责，细粒度
@tool()
async def search_notes(query: str) -> ToolResult: ...

@tool()
async def get_note_detail(note_id: str) -> ToolResult: ...

@tool()
async def update_note(note_id: str, content: str) -> ToolResult: ...

# 不好：功能过多，难以使用
@tool()
async def manage_notes(
    action: Literal["search", "get", "update", "delete"],
    query: Optional[str] = None,
    note_id: Optional[str] = None,
    content: Optional[str] = None
) -> ToolResult:
    # 太复杂，LLM 容易用错
    ...

6. 文档和示例

@tool()
async def search_notes(
    query: str,
    filters: Optional[Dict[str, Any]] = None,
    sort_by: str = "relevance",
    limit: int = 10,
    uid: str = ""
) -> ToolResult:
    """
    搜索用户的笔记

    使用语义搜索查找相关笔记，支持过滤和排序。

    Args:
        query: 搜索关键词（必需）
        filters: 过滤条件，例如 {"type": "markdown", "tags": ["work"]}
        sort_by: 排序方式，可选 "relevance" | "date" | "title"
        limit: 返回结果数量，默认 10，最大 100

    Returns:
        ToolResult 包含搜索结果列表

    Example:
        搜索包含 "项目计划" 的工作笔记：
        {
            "query": "项目计划",
            "filters": {"tags": ["work"]},
            "limit": 5
        }
    """
    ...

跨框架使用（CLI / MCP）

工具设计为可跨 Agent 框架使用（本框架 Agent、Claude Code、其他 LLM IDE 等），遵循以下原则：

无状态工具 → 自包含 CLI：每个工具文件可独立运行，零外部依赖
有状态工具组（浏览器、沙箱等需要持久 session） → MCP server：使用标准协议管理 session
禁止中间态：不造私有协议；简单就 CLI，复杂就 MCP

判断标准

问题	答案	选择
工具调用之间是否有进程内状态需要保持？（浏览器 session、数据库连接、缓存）	否	CLI
同上	是	MCP
是否需要 Claude Desktop、Cursor 等客户端原生识别？	需要	MCP

无状态 CLI 工具规范

一个工具想同时作为 Agent tool（@tool 注册）和 CLI 工具使用，需要满足以下要求：

1. 文件末尾添加自包含的 if __name__ == "__main__" 块

参数解析、asyncio.run、结果输出这些 CLI 样板代码直接内联在工具文件里，不要抽取到共享 cli.py 模块——这样每个工具文件可以独立迁移到其他项目。

# 示例：agent/tools/builtin/toolhub.py 末尾
if __name__ == "__main__":
    import sys, asyncio, os, uuid

    COMMANDS = {"health": toolhub_health, "search": toolhub_search, "call": toolhub_call}

    def _parse_args(argv):
        kwargs = {}
        for arg in argv:
            if arg.startswith("--") and "=" in arg:
                k, v = arg.split("=", 1)
                k = k.lstrip("-").replace("-", "_")
                try: v = json.loads(v)
                except: pass
                kwargs[k] = v
        return kwargs

    # trace_id 三级回退：CLI 参数 > 环境变量 > 自动生成
    cmd = sys.argv[1]
    kwargs = _parse_args(sys.argv[2:])
    trace_id = kwargs.pop("trace_id", None) or os.getenv("TRACE_ID") or f"cli-{uuid.uuid4().hex[:8]}"
    set_trace_context(trace_id)

    result = asyncio.run(COMMANDS[cmd](**kwargs))
    # 输出 JSON（注意 double-encoding 问题）
    ...

2. 输出统一为 JSON 格式

{
  "trace_id": "...",
  "output": "...",  // 原生 dict/list/str，不要预先 json.dumps
  "error": "...",   // 可选
  "metadata": {...}  // 可选
}

3. trace_id 三级回退策略

对于需要会话语义（同一 trace_id 内多次调用共享状态）的工具（librarian、toolhub 的图片输出目录等）：

CLI 参数 --trace_id=xxx（显式）
环境变量 TRACE_ID（同一 shell session 共享）
自动生成 cli-{random}（兜底）

外部 Agent 只需 export TRACE_ID=session-xxx 一次，后续所有 CLI 调用自动归到同一会话。

4. 二进制产出写文件，JSON 返回路径

像 read_images 这种产出图片/大文件的工具，CLI 模式下不要把 base64 塞进 stdout（刷屏 + 调用方还要解码）。应该：

要求用户显式传 --out=<path> 指定输出路径
把文件写到 <path>
JSON 响应里返回 out_path 供调用方用 Read 工具查看

5. 避免双重 JSON 编码

如果工具内部已经 json.dumps() 把 result dict 塞进了 ToolResult.output，CLI 层再 json.dumps(result.output) 会产生双重转义（"output": "{\"model\": ..." 这种反人类形式）。CLI 层要在输出前检测并解码：

output_value = result.output
if isinstance(output_value, str):
    stripped = output_value.lstrip()
    if stripped.startswith(("{", "[")):
        try:
            output_value = json.loads(output_value)
        except (json.JSONDecodeError, ValueError):
            pass  # 非 JSON 文本，保持原样

Skill 安装规范

CLI 工具对外暴露给 Claude Code（或其他支持 skill 的客户端）时，需要配套写一个 SKILL.md：

位置： ~/.claude/skills/<name>/SKILL.md（用户全局）或项目级 .claude/skills/<name>/SKILL.md

格式：

---
name: <skill-name>
description: <一句话，描述用途和触发时机。这是 Claude Code 决定何时加载该 skill 的唯一依据>
---

# <Skill Name>

<简短一段话介绍工具>

## 用法

```bash
python <绝对路径>/tool.py <子命令> --key=value

--key=... 参数说明
关键约束（如数量上限）

<调用后怎么解读输出，典型 workflow>


**尺寸原则：** SKILL.md **越短越好**。它每次触发时都会进入 context 占据 token。和 `agent/docs/tools.md` 的职责区分：

| 文件 | 读者 | 触发 | 长度 |
|------|------|------|------|
| `SKILL.md` | **运行时的 Claude Code**（动态加载） | 每次匹配自动加载到 context | **短**（20 行以内为佳） |
| `agent/docs/tools.md` | **开发者**（静态阅读） | 从不自动加载 | 长，可以详细展开原理、设计取舍 |

SKILL.md 只写"调用这个工具所需的最小信息集"，原理和细节放到 docs。

**当前已安装的 skill**（`~/.claude/skills/`）：
- `toolhub/` — 搜索和调用 ToolHub 远程 AI 工具
- `knowhub/` — 查询和上传 KnowHub 知识库
- `stitch-images/` — 批量图片拼成网格供 Read 一次查看

### ToolHub 图片管线

`toolhub_call` 内置完整的图片处理管线，无需单独的上传/下载工具：

- **输入**：`params` 中的图片参数（`image`、`image_url`、`mask_image`、`pose_image`、`images`）可直接传本地文件路径，系统自动上传
- **输出**：生成的图片自动保存到 `outputs/` 目录，返回结果中 `saved_files` 包含本地路径

### MCP 集成（有状态工具组）

对于需要维持 session 的工具组，使用 MCP server。两种注册方式：

**1. 使用现成的 MCP server**（推荐）

例如浏览器工具直接用 browser-use 原生 MCP：

```json
// .mcp.json（项目根目录；不要写在 settings.json，Claude Code 不会从那里读 mcpServers）
{
  "mcpServers": {
    "browser-use": {
      "command": "/Users/sunlit/.pyenv/versions/3.13.1/bin/python",
      "args": ["-m", "browser_use.skill_cli.main", "--mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "BROWSER_USE_LLM_MODEL": "qwen-plus"
      }
    }
  }
}

注意事项：

command 必须用绝对路径，不要用 pyenv shim（shim 在 Claude Code 子进程里无法正确解析）
MCP server 配置放 .mcp.json，不是 ~/.claude/settings.json（后者只管 permissions/outputStyle 等）
第三方包的 LLM 配置如果 Pydantic schema 吞字段（比如 browser-use 的 LLMEntry 不支持 base_url），可以通过环境变量绕过（如 OPENAI_BASE_URL 是 OpenAI SDK 原生环境变量）

2. 为自研有状态工具组写 MCP server

当你有一组需要共享 session 的自研工具时，用 mcp Python SDK 写一个 server，每个工具作为 @app.tool() 暴露。server 进程内维护 session 状态。避免造私有 stdio 协议。

总结

特性	状态	说明
基础注册	✅ 已实现	`@tool()` 装饰器
Schema 生成	✅ 已实现	自动从函数签名生成
双层记忆	✅ 已实现	`ToolResult` 支持 long_term_memory
依赖注入	✅ 已实现	`ToolContext` 提供上下文
UI 元数据	✅ 已实现	`display`, `requires_confirmation`, `editable_params`
域名过滤	✅ 已实现	`url_patterns` 参数 + URL 匹配器
敏感数据	✅ 已实现	`<secret>` 占位符 + TOTP 支持
工具统计	✅ 已实现	自动记录调用次数、成功率、执行时间

核心设计原则：

简单优先：最简工具只需要一个装饰器
按需扩展：高级特性可选
类型安全：充分利用 Python 类型注解
灵活集成：支持各种工具库（Browser-Use, MCP 等）
可观测性：内建统计和监控能力
跨框架：无状态工具自包含 CLI，有状态工具走 MCP 标准协议

tools.md 43 KB История Исходник

工具系统文档

目录

核心概念

三个核心类型

工具的生命周期

参数注入机制

定义工具

最简形式

带框架参数

带参数注入

带 UI 元数据

ToolResult 和记忆管理

基础用法

双层记忆管理

错误处理

附件和图片

ToolContext 和依赖注入

基本概念

ToolContext 字段

使用示例

创建 ToolContext

高级特性

1. 需要用户确认

2. 可编辑参数

3. 域名过滤（URL Patterns）

4. 敏感数据处理

5. 工具使用统计

6. 组合使用

内置基础工具

可用工具

read_file vs read_images

Agent 工具

Evaluate 工具

快速使用

核心特性

更新 OpenCode 参考

集成 Browser-Use

适配器模式

使用示例

Context 占用分析

最佳实践

1. 工具命名

2. 返回结构化数据

3. 错误处理

4. 记忆管理

5. 工具粒度

6. 文档和示例

跨框架使用（CLI / MCP）

判断标准

无状态 CLI 工具规范

Skill 安装规范

总结

tools.md 43 KB

История Исходник

`read_file` vs `read_images`