Improve data skill routing and tool organization

src/agent_tool_specs/execution.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..agent_tool_core import AgentTool, ToolHandler
+from ._builder import resolve_handler
+
+
+def build_execution_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool]:
+    """构建本地命令、Python 执行与短等待工具声明。"""
+
+    return [
+        AgentTool(
+            name='python_exec',
+            description=(
+                '优先用本工具执行小型 Python 代码或项目内 Python 脚本，用于结构化文件分析、'
+                'JSON/JSONL 处理、批量校验、数据抽样和快速计算。默认使用当前用户独立 Python venv；'
+                '不要用 bash 运行 python/python3/.venv/bin/python。不要用本工具安装依赖。'
+                '缺包时应向用户确认后再处理依赖。一次性分析优先传 code；如需写临时文件，'
+                '必须写入环境变量 PYTHON_EXEC_SCRATCHPAD 指向的会话隔离目录，'
+                '不要在项目根目录创建临时 .py 脚本。'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'code': {
+                        'type': 'string',
+                        'description': '要通过 python -c 执行的 Python 代码。code 和 script_path 必须二选一；一次性分析优先使用 code。',
+                    },
+                    'script_path': {
+                        'type': 'string',
+                        'description': '工作区内已有、需要长期复用的 Python 脚本路径。code 和 script_path 必须二选一；不要为一次性分析在项目根目录新建脚本。',
+                    },
+                    'args': {
+                        'type': 'array',
+                        'items': {'type': 'string'},
+                        'description': '传给脚本的命令行参数。仅在 script_path 模式下使用。',
+                    },
+                    'stdin': {
+                        'type': 'string',
+                        'description': '可选标准输入内容。',
+                    },
+                    'timeout_seconds': {
+                        'type': 'number',
+                        'minimum': 1,
+                        'description': '可选超时时间，默认使用当前会话命令超时。',
+                    },
+                    'max_output_chars': {
+                        'type': 'integer',
+                        'minimum': 100,
+                        'description': '可选输出截断长度，默认使用当前会话输出限制。',
+                    },
+                },
+            },
+            handler=resolve_handler(handlers, 'python_exec', 'execution'),
+        ),
+        AgentTool(
+            name='python_package',
+            description=(
+                '在当前用户独立 Python venv 中检查或安装 Python 包。'
+                '用于 python_exec 缺少 pandas、pyarrow、openpyxl 等分析依赖时；'
+                '不要通过 bash 执行 pip，也不要安装到项目 .venv。'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'action': {
+                        'type': 'string',
+                        'enum': ['show', 'install'],
+                        'description': 'show 查看当前 Python 环境和 pip；install 安装 packages。',
+                    },
+                    'packages': {
+                        'type': 'array',
+                        'items': {'type': 'string'},
+                        'description': '要安装的包名或 pip requirement spec，例如 pandas、pyarrow==15.0.0。',
+                    },
+                    'timeout_seconds': {
+                        'type': 'number',
+                        'minimum': 1,
+                        'maximum': 600,
+                        'description': '安装超时时间，默认 120 秒。',
+                    },
+                    'max_output_chars': {
+                        'type': 'integer',
+                        'minimum': 1000,
+                        'maximum': 50000,
+                    },
+                },
+                'required': ['action'],
+            },
+            handler=resolve_handler(handlers, 'python_package', 'execution'),
+        ),
+        AgentTool(
+            name='bash',
+            description=(
+                '运行真实 shell 命令，例如系统命令、进程控制、git 只读检查或用户已确认的依赖安装。'
+                '不要用 bash 执行 python、python3、pip 或 .venv/bin/python；结构化文件分析、'
+                'JSON/JSONL 处理、批量校验、数据抽样和快速计算必须优先使用 python_exec。'
+                'Python 包安装必须优先使用 python_package。'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'command': {'type': 'string'},
+                },
+                'required': ['command'],
+            },
+            handler=resolve_handler(handlers, 'bash', 'execution'),
+        ),
+        AgentTool(
+            name='sleep',
+            description='Pause execution briefly for bounded local wait flows.',
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'seconds': {'type': 'number', 'minimum': 0.0, 'maximum': 5.0},
+                },
+                'required': ['seconds'],
+            },
+            handler=resolve_handler(handlers, 'sleep', 'execution'),
+        ),
+    ]
+