# 03. 工具体系和 Tool Handler

![工具体系和 Tool Handler](assets/03-tools.png)

## 1. 工具体系的职责

Tool 是执行层。模型只能“请求调用工具”，不能直接执行工具。
后端根据工具名找到 handler，校验参数，执行动作，并把结果写回 session。

工具适合承载：

- 稳定文件读写。
- Python 执行。
- Python 包安装。
- 数据格式转换和校验。
- review 状态机。
- 外部系统访问。
- 需要权限、取消、路径约束或审计的动作。

## 2. Tool registry 构成

入口：

```text
src/agent_tools.py:105 default_tool_registry()
```

它会合并多类工具：

```text
build_file_tools(...)
build_execution_tools(...)
LSP / web_fetch / search / account / config / task / team / workflow 等
Skill 工具
data_agent 工具
```

关键片段：

```text
src/agent_tools.py:107 build_file_tools
src/agent_tools.py:116 build_execution_tools
src/agent_tools.py:1012 AgentTool(name='Skill')
src/agent_tools.py:1033 build_data_agent_tools
```

返回结果是：

```python
return {tool.name: tool for tool in tools}
```

## 3. Tool spec 注入模型

在 Agent loop 中：

```text
src/agent_runtime.py:552
tool_specs = [tool.to_openai_tool() for tool in self.tool_registry.values()]
```

每个工具包含：

```text
name
description
parameters JSON schema
handler
```

模型看到的是 name、description、parameters。handler 不暴露给模型，只在后端执行。

## 4. Tool handler 执行路径

工具执行入口：

```text
src/agent_tools.py:60 execute_tool(...)
src/agent_tools.py:76 execute_tool_streaming(...)
```

执行逻辑：

```text
1. 从 tool_registry 取 tool。
2. 找不到则返回 Unknown tool。
3. bash 走 streaming。
4. 其他工具调用 tool.execute(arguments, context)。
5. 工具结果序列化回模型和前端。
```

## 5. 文件工具

定义位置：

```text
src/agent_tool_specs/files.py
```

主要工具：

- `list_dir`
- `read_file`
- `write_file`
- `edit_file`
- `notebook_edit`
- `glob_search`
- `grep_search`

### 5.1 `write_file` 的边界

`write_file` 当前明确定位为“小文件工具”：

```text
src/agent_tool_specs/files.py
  Write or append a SMALL UTF-8 file inside the workspace.
```

适合：

- 短 Markdown。
- 少量配置。
- 小 JSON。
- 少量 JSONL。
- 小 CSV。

不适合：

- 长 Python 脚本。
- 大 JSON。
- JSONL 数据集。
- 长 CSV。
- 大段包含引号和换行的内容。

原因是模型生成工具参数时，需要把内容嵌入 JSON 参数。长文本、引号、换行会显著增加非法 JSON 参数概率。

因此系统提示词也要求：

```text
复杂写文件优先用 python_exec 通过 pathlib/json/csv 写入。
```

## 6. Python 执行工具

定义位置：

```text
src/agent_tool_specs/execution.py
```

主要工具：

- `python_exec`
- `python_package`
- `bash`
- `sleep`

### 6.1 `python_exec`

定位：

```text
结构化文件分析、JSON/JSONL 处理、批量校验、数据抽样、快速计算。
```

支持两种模式：

```text
code
  一次性 Python 代码。

script_path
  调用项目或 Skill 内已有脚本。
```

重要约束：

- 不用 `bash python ...`。
- 不在 `python_exec.code` 里用 subprocess 二次调用 Python 脚本。
- 临时文件写入 `PYTHON_EXEC_SCRATCHPAD`。
- 交付产物写入 session/output。

### 6.2 `python_package`

定位：

```text
给当前用户独立 Python venv 安装缺失包。
```

典型场景：

- `pandas`
- `pyarrow`
- `openpyxl`
- `elasticsearch`
- `urllib3`

设计上避免安装到项目 `.venv` 或系统 Python。

### 6.3 `bash`

`bash` 是兜底工具，不是默认 Python 执行方式。

适合：

- git 只读检查。
- 系统命令。
- 进程控制。
- 用户确认后的依赖安装或服务管理。

不适合：

- Python 数据分析。
- JSON/CSV 转换。
- 包安装。

## 7. 路径解析和 session 路由

关键实现：

```text
src/agent_tools.py:1589 _data_agent_output_path(...)
src/agent_tools.py:1624 _data_agent_session_output_root(...)
src/agent_tools.py:1630 _resolve_path(...)
src/agent_tools.py:1658 _session_logical_path(...)
src/agent_tools.py:1685 _execution_cwd(...)
```

逻辑路径会被映射到当前 session：

```text
output/...     -> session/output/...
outputs/...    -> session/output/...
scratchpad/... -> session/scratchpad/...
scratch/...    -> session/scratchpad/...
input/...      -> session/input/...
inputs/...     -> session/input/...
```

`python_exec` 的执行 cwd 优先是当前会话 scratchpad：

```text
src/agent_tools.py:1685 _execution_cwd(...)
```

## 8. data_agent 工具

声明位置：

```text
src/agent_tool_specs/data_agent.py
```

handler 注册位置：

```text
src/agent_tools.py:1033 build_data_agent_tools(...)
```

主要工具分两类：

### 8.1 前链路和 review 状态机

- `data_agent_load_input_sources`
- `data_agent_render_source_context`
- `data_agent_extract_case_evidence`
- `data_agent_prepare_generation_goal`
- `data_agent_confirm_generation_goal`
- `data_agent_prepare_generation_plan`
- `data_agent_show_generation_plan`
- `data_agent_update_generation_plan`
- `data_agent_confirm_generation_plan`

这类工具当前仍属于平台工具，因为它们维护 pending/confirmed 状态，以及产品数据生成的 review 门禁。

### 8.2 历史格式转换工具

- `data_agent_normalize_dataset_draft`
- `data_agent_validate_dataset_records`
- `data_agent_export_dataset_records`
- `data_agent_export_training_jsonl`
- `data_agent_export_planning_eval_csv`

这部分能力已经逐步迁移到 `skills/product-data/scripts/`，平台工具更多是历史兼容和适配层。

## 9. 工具设计原则

当前工具体系的技术取舍：

```text
模型负责决策。
工具负责执行。
Skill 负责流程经验。
脚本负责可迁移确定性能力。
```

工具描述要足够明确，否则模型会选错工具；参数 schema 要尽量简单，否则不同模型后端可能不兼容。