docs: add technical architecture guide

2026-05-18 19:28:02 +08:00
parent c4b935692c
commit 3054b3bc6b
53 changed files with 6692 additions and 2234 deletions
@@ -0,0 +1,298 @@
+# 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 要尽量简单，否则不同模型后端可能不兼容。