323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
|
# Phase 6：工具系统重构（Tool System Refactoring）
|
|||
|
|
|
|||
|
|
日期：2026-04-04
|
|||
|
|
状态：待开始
|
|||
|
|
Demo参考：claw-code-main — tools/, StreamingToolExecutor, toolOrchestration
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 阶段目标
|
|||
|
|
|
|||
|
|
建立**分层工具执行架构**，从现有的扁平工具调用进化为具有注册表、编排层、Hook 拦截能力的工具系统。
|
|||
|
|
|
|||
|
|
**与现有系统的区别**：
|
|||
|
|
|
|||
|
|
| 现有 | 目标 |
|
|||
|
|
|------|------|
|
|||
|
|
| Sub-Commander 直接调用 Tools | ToolRegistry → ToolOrchestration → HookExecutor → ToolExecutor → Tools |
|
|||
|
|
| 工具集固定 | 工具注册表支持动态注册 |
|
|||
|
|
| 无流式工具执行 | StreamingToolExecutor 支持流式 |
|
|||
|
|
| 无工具拦截 | PreTool/PostTool Hook 机制 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 架构设计
|
|||
|
|
|
|||
|
|
### 2.1 新的工具执行架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Agent / Sub-Commander │
|
|||
|
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ ToolOrchestration Layer │
|
|||
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
|||
|
|
│ │ ToolRegistry│ │HookExecutor │ │ StreamingToolExecutor │ │
|
|||
|
|
│ │ (注册表) │ │ (拦截层) │ │ (流式执行器) │ │
|
|||
|
|
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ ToolExecutor │
|
|||
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ Built-in │ │ External │ │ MCP │ │ Plugin │ │
|
|||
|
|
│ │ Tools │ │ Tools │ │ Tools │ │ Tools │ │
|
|||
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 核心组件
|
|||
|
|
|
|||
|
|
#### ToolRegistry（工具注册表）
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/agents/tools/registry.py
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class ToolManifest:
|
|||
|
|
"""工具元数据"""
|
|||
|
|
name: str
|
|||
|
|
description: str
|
|||
|
|
category: ToolCategory
|
|||
|
|
parameters: dict # JSON Schema
|
|||
|
|
return_schema: dict
|
|||
|
|
permission_class: PermissionClass # READ/WRITE/EXTERNAL
|
|||
|
|
side_effect_scope: SideEffectScope # NONE/LOCAL_STATE/DB_WRITE/NETWORK
|
|||
|
|
requires_confirmation: bool
|
|||
|
|
is_streaming: bool = False
|
|||
|
|
tags: list[str] = field(default_factory=list)
|
|||
|
|
|
|||
|
|
class ToolRegistry:
|
|||
|
|
"""工具注册表"""
|
|||
|
|
|
|||
|
|
def __init__(self):
|
|||
|
|
self._tools: dict[str, ToolManifest] = {}
|
|||
|
|
self._executors: dict[str, Callable] = {}
|
|||
|
|
self._hooks: dict[str, list[HookConfig]] = defaultdict(list)
|
|||
|
|
|
|||
|
|
def register(
|
|||
|
|
self,
|
|||
|
|
manifest: ToolManifest,
|
|||
|
|
executor: Callable,
|
|||
|
|
hooks: list[HookConfig] | None = None
|
|||
|
|
):
|
|||
|
|
"""注册工具"""
|
|||
|
|
self._tools[manifest.name] = manifest
|
|||
|
|
self._executors[manifest.name] = executor
|
|||
|
|
if hooks:
|
|||
|
|
for hook in hooks:
|
|||
|
|
self._hooks[manifest.name].append(hook)
|
|||
|
|
|
|||
|
|
def get(self, name: str) -> ToolManifest | None:
|
|||
|
|
"""获取工具元数据"""
|
|||
|
|
return self._tools.get(name)
|
|||
|
|
|
|||
|
|
def get_executor(self, name: str) -> Callable | None:
|
|||
|
|
"""获取工具执行器"""
|
|||
|
|
return self._executors.get(name)
|
|||
|
|
|
|||
|
|
def list_by_category(self, category: ToolCategory) -> list[ToolManifest]:
|
|||
|
|
"""按类别列出工具"""
|
|||
|
|
return [t for t in self._tools.values() if t.category == category]
|
|||
|
|
|
|||
|
|
def list_all(self) -> list[ToolManifest]:
|
|||
|
|
"""列出所有工具"""
|
|||
|
|
return list(self._tools.values())
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### HookExecutor（拦截执行器）
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/agents/tools/hook_executor.py
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class HookConfig:
|
|||
|
|
"""Hook 配置"""
|
|||
|
|
name: str
|
|||
|
|
hook_type: HookType # PRE_TOOL_USE / POST_TOOL_USE / TOOL_ERROR / TOOL_SKIP
|
|||
|
|
handler: Callable
|
|||
|
|
filter_names: list[str] | None = None # 只对特定工具生效，None 表示全部
|
|||
|
|
|
|||
|
|
class HookExecutor:
|
|||
|
|
"""工具 Hook 执行器"""
|
|||
|
|
|
|||
|
|
async def pre_execute(self, tool_name: str, arguments: dict) -> HookResult:
|
|||
|
|
"""PreToolUse - 工具执行前拦截"""
|
|||
|
|
hooks = self._get_hooks(tool_name, HookType.PRE_TOOL_USE)
|
|||
|
|
|
|||
|
|
ctx = HookContext(
|
|||
|
|
tool_name=tool_name,
|
|||
|
|
arguments=arguments,
|
|||
|
|
phase=HookPhase.PRE
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
for hook in hooks:
|
|||
|
|
result = await hook.handler(ctx)
|
|||
|
|
if result.action == HookAction.DENY:
|
|||
|
|
return HookResult(
|
|||
|
|
action=HookAction.DENY,
|
|||
|
|
message=result.message,
|
|||
|
|
modified_args=None
|
|||
|
|
)
|
|||
|
|
elif result.action == HookAction.MODIFY:
|
|||
|
|
ctx.arguments = result.modified_args
|
|||
|
|
|
|||
|
|
return HookResult(action=HookAction.ALLOW, modified_args=ctx.arguments)
|
|||
|
|
|
|||
|
|
async def post_execute(
|
|||
|
|
self,
|
|||
|
|
tool_name: str,
|
|||
|
|
arguments: dict,
|
|||
|
|
result: Any
|
|||
|
|
) -> HookResult:
|
|||
|
|
"""PostToolUse - 工具执行后拦截"""
|
|||
|
|
hooks = self._get_hooks(tool_name, HookType.POST_TOOL_USE)
|
|||
|
|
|
|||
|
|
ctx = HookContext(
|
|||
|
|
tool_name=tool_name,
|
|||
|
|
arguments=arguments,
|
|||
|
|
result=result,
|
|||
|
|
phase=HookPhase.POST
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
for hook in hooks:
|
|||
|
|
result = await hook.handler(ctx)
|
|||
|
|
if result.action == HookAction.MODIFY_RESULT:
|
|||
|
|
ctx.result = result.modified_result
|
|||
|
|
|
|||
|
|
return HookResult(action=HookAction.CONTINUE, modified_result=ctx.result)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### StreamingToolExecutor（流式工具执行器）
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/agents/tools/streaming_executor.py
|
|||
|
|
|
|||
|
|
class StreamingToolExecutor:
|
|||
|
|
"""流式工具执行器"""
|
|||
|
|
|
|||
|
|
async def execute_streaming(
|
|||
|
|
self,
|
|||
|
|
tool_name: str,
|
|||
|
|
arguments: dict,
|
|||
|
|
callback: Callable[[dict], Awaitable[None]]
|
|||
|
|
) -> Any:
|
|||
|
|
"""执行流式工具"""
|
|||
|
|
manifest = self.registry.get(tool_name)
|
|||
|
|
if not manifest.is_streaming:
|
|||
|
|
raise ValueError(f"Tool {tool_name} does not support streaming")
|
|||
|
|
|
|||
|
|
executor = self.registry.get_executor(tool_name)
|
|||
|
|
|
|||
|
|
# 使用 aiterator 进行流式执行
|
|||
|
|
async for chunk in executor(**arguments):
|
|||
|
|
event = {"type": "chunk", "data": chunk}
|
|||
|
|
await callback(event)
|
|||
|
|
yield chunk
|
|||
|
|
|
|||
|
|
final_event = {"type": "done", "tool": tool_name}
|
|||
|
|
await callback(final_event)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 新增工具集
|
|||
|
|
|
|||
|
|
### 3.1 文件操作工具
|
|||
|
|
|
|||
|
|
| 工具 | 描述 | 权限级别 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| GlobTool | 按模式匹配文件 | READ |
|
|||
|
|
| GrepTool | 在文件中搜索内容 | READ |
|
|||
|
|
| LintTool | 代码检查 | READ |
|
|||
|
|
| EditTool | 编辑文件 | WRITE |
|
|||
|
|
|
|||
|
|
### 3.2 开发工具
|
|||
|
|
|
|||
|
|
| 工具 | 描述 | 权限级别 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| LSPTool | Language Server Protocol | READ |
|
|||
|
|
| BashTool | 执行 Bash 命令 | EXTERNAL |
|
|||
|
|
| PowerShellTool | 执行 PowerShell | EXTERNAL |
|
|||
|
|
|
|||
|
|
### 3.3 系统工具
|
|||
|
|
|
|||
|
|
| 工具 | 描述 | 权限级别 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| ScheduleCronTool | Cron 定时任务 | WRITE |
|
|||
|
|
| ProcessTool | 进程管理 | EXTERNAL |
|
|||
|
|
|
|||
|
|
### 3.4 协作工具
|
|||
|
|
|
|||
|
|
| 工具 | 描述 | 权限级别 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| TeamAgentTool | 团队 Agent 协作 | EXTERNAL |
|
|||
|
|
| TaskBroadcastTool | 任务广播 | WRITE |
|
|||
|
|
|
|||
|
|
### 3.5 高级工具
|
|||
|
|
|
|||
|
|
| 工具 | 描述 | 权限级别 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| RemoteTriggerTool | 远程触发 | EXTERNAL |
|
|||
|
|
| MCPClientTool | MCP 客户端 | EXTERNAL |
|
|||
|
|
| AskUserQuestionTool | 向用户提问 | READ |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 文件结构变化
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
backend/app/agents/tools/
|
|||
|
|
├── __init__.py # 现有 - 需重构
|
|||
|
|
├── registry.py # 新增 - 工具注册表
|
|||
|
|
├── manifest.py # 新增 - 工具元数据
|
|||
|
|
├── hook_executor.py # 新增 - Hook 执行器
|
|||
|
|
├── hook_config.py # 新增 - Hook 配置
|
|||
|
|
├── streaming_executor.py # 新增 - 流式执行器
|
|||
|
|
├── base.py # 新增 - 基础工具类
|
|||
|
|
│
|
|||
|
|
├── builtins/ # 新增 - 内置工具
|
|||
|
|
│ ├── __init__.py
|
|||
|
|
│ ├── file_tools.py # Glob, Grep, Edit, Lint
|
|||
|
|
│ ├── system_tools.py # Bash, PowerShell, Cron
|
|||
|
|
│ ├── dev_tools.py # LSP, Git
|
|||
|
|
│ └── collaboration_tools.py # Team, Broadcast
|
|||
|
|
│
|
|||
|
|
├── task.py # 现有 - 保留
|
|||
|
|
├── schedule.py # 现有 - 保留
|
|||
|
|
├── search.py # 现有 - 保留
|
|||
|
|
├── forum.py # 现有 - 保留
|
|||
|
|
└── time_reasoning.py # 现有 - 保留
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 迁移计划
|
|||
|
|
|
|||
|
|
### 阶段 6.1：基础设施（1-2周）
|
|||
|
|
- 创建 ToolRegistry 类
|
|||
|
|
- 创建 ToolManifest 数据类
|
|||
|
|
- 迁移现有工具到注册表
|
|||
|
|
|
|||
|
|
### 阶段 6.2：Hook 系统（2-3周）
|
|||
|
|
- 创建 HookExecutor
|
|||
|
|
- 实现 PreTool/PostTool 机制
|
|||
|
|
- 添加内置 Hook（确认危险操作、日志记录）
|
|||
|
|
|
|||
|
|
### 阶段 6.3：流式执行（1-2周）
|
|||
|
|
- 实现 StreamingToolExecutor
|
|||
|
|
- 为支持流式的工具添加 streaming 标志
|
|||
|
|
- 更新 AgentService 集成
|
|||
|
|
|
|||
|
|
### 阶段 6.4：新工具集（2-3周）
|
|||
|
|
- 实现新增的工具类
|
|||
|
|
- 添加完整的工具文档
|
|||
|
|
- 单元测试覆盖
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 验收标准
|
|||
|
|
|
|||
|
|
| 检查点 | 标准 |
|
|||
|
|
|--------|------|
|
|||
|
|
| 工具注册 | 所有现有工具已在 Registry 中注册 |
|
|||
|
|
| Hook 执行 | PreTool/PostTool Hook 能正确拦截 |
|
|||
|
|
| 流式执行 | 标记为 streaming 的工具可流式返回 |
|
|||
|
|
| 新工具 | 新增工具集中每个工具可正常执行 |
|
|||
|
|
| 向后兼容 | 现有 Sub-Commander 工具调用不受影响 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Demo 借鉴
|
|||
|
|
|
|||
|
|
| claw-code 实现 | Jarvis 对应 |
|
|||
|
|
|----------------|------------|
|
|||
|
|
| `src/tools/` | `backend/app/agents/tools/` |
|
|||
|
|
| `StreamingToolExecutor.ts` | `streaming_executor.py` |
|
|||
|
|
| `toolExecution.ts` | `hook_executor.py` |
|
|||
|
|
| `toolHooks.ts` | `hook_config.py` |
|
|||
|
|
| `ToolManifest` | `manifest.py` |
|