zk-data-agent/frontend/app/public/doc-assets/technical-docs/03-tools.md

03. 工具体系和 Tool Handler

1. 工具体系的职责

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

工具适合承载：

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

2. Tool registry 构成

入口：

src/agent_tools.py:105 default_tool_registry()

它会合并多类工具：

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

关键片段：

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

返回结果是：

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

3. Tool spec 注入模型

在 Agent loop 中：

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

每个工具包含：

name
description
parameters JSON schema
handler

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

4. Tool handler 执行路径

工具执行入口：

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

执行逻辑：

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

5. 文件工具

定义位置：

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 当前明确定位为“小文件工具”：

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 参数概率。

因此系统提示词也要求：

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

6. Python 执行工具

定义位置：

src/agent_tool_specs/execution.py

主要工具：

• python_exec
• python_package
• bash
• sleep

6.1 python_exec

定位：

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

支持两种模式：

code
  一次性 Python 代码。

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

重要约束：

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

6.2 python_package

定位：

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

典型场景：

• pandas
• pyarrow
• openpyxl
• elasticsearch
• urllib3

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

6.3 bash

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

适合：

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

不适合：

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

7. 路径解析和 session 路由

关键实现：

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：

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

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

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

8. data_agent 工具

声明位置：

src/agent_tool_specs/data_agent.py

handler 注册位置：

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. 工具设计原则

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

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

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