wuyang/zk-data-agent

Fork 0

Files

T

wuyang6 3054b3bc6b docs: add technical architecture guide

2026-05-18 19:28:02 +08:00

5.9 KiB

Raw Blame History

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 要尽量简单，否则不同模型后端可能不兼容。

5.9 KiB Raw Blame History Unescape Escape