wuyang6
299 lines
5.9 KiB
Markdown
299 lines
5.9 KiB
Markdown
# 03. 工具体系和 Tool Handler
|
||
|
||
|
||
|
||
## 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 要尽量简单，否则不同模型后端可能不兼容。
|