# Phase T.2：工具注册中心

日期：2026-04-04
状态：待开始
依赖：T.1（待完成）

---

## 1. 本阶段目的

建立 Jarvis 的工具注册中心：

- 工具动态发现
- 工具注册与管理
- 工具描述生成
- 调用统计与监控

---

## 2. 工具注册中心架构

### 2.1 核心类

```python
# tools/registry.py
from typing import Dict, List, Optional, Callable
from dataclasses import dataclass, field
from datetime import datetime
import asyncio


@dataclass
class ToolMetadata:
    """工具元数据"""
    name: str
    display_name: str
    description: str
    version: str
    author: Optional[str] = None
    tags: List[str] = field(default_factory=list)
    dependencies: List[str] = field(default_factory=list)
    enabled: bool = True
    registered_at: datetime = field(default_factory=datetime.utcnow)
    
    # 统计
    call_count: int = 0
    error_count: int = 0
    total_duration_ms: int = 0
    
    @property
    def avg_duration_ms(self) -> int:
        if self.call_count == 0:
            return 0
        return self.total_duration_ms // self.call_count
    
    @property
    def error_rate(self) -> float:
        if self.call_count == 0:
            return 0.0
        return self.error_count / self.call_count


class ToolRegistry:
    """工具注册中心"""
    
    def __init__(self):
        self._tools: Dict[str, ToolMetadata] = {}
        self._executors: Dict[str, Callable] = {}
        self._configs: Dict[str, dict] = {}
        self._lock = asyncio.Lock()
    
    # === 注册方法 ===
    
    async def register(
        self,
        manifest_path: str,
        executor: Callable,
        config: Optional[dict] = None,
    ) -> ToolMetadata:
        """注册工具"""
        from tools.schemas.validator import validate_manifest
        import yaml
        
        with open(manifest_path) as f:
            data = yaml.safe_load(f)
        
        manifest = validate_manifest(data)
        
        metadata = ToolMetadata(
            name=manifest.name,
            display_name=manifest.display_name,
            description=manifest.description,
            version=manifest.version,
            author=manifest.author,
            tags=manifest.tags or [],
            dependencies=manifest.dependencies or [],
            enabled=manifest.enabled,
        )
        
        async with self._lock:
            self._tools[manifest.name] = metadata
            self._executors[manifest.name] = executor
            if config:
                self._configs[manifest.name] = config
        
        return metadata
    
    async def unregister(self, name: str) -> bool:
        """注销工具"""
        async with self._lock:
            if name in self._tools:
                del self._tools[name]
                del self._executors[name]
                self._configs.pop(name, None)
                return True
            return False
    
    async def enable(self, name: str) -> None:
        """启用工具"""
        async with self._lock:
            if name in self._tools:
                self._tools[name].enabled = True
    
    async def disable(self, name: str) -> None:
        """禁用工具"""
        async with self._lock:
            if name in self._tools:
                self._tools[name].enabled = False
    
    # === 查询方法 ===
    
    async def get(self, name: str) -> Optional[ToolMetadata]:
        """获取工具元数据"""
        return self._tools.get(name)
    
    async def get_executor(self, name: str) -> Optional[Callable]:
        """获取工具执行器"""
        return self._executors.get(name)
    
    async def get_config(self, name: str) -> dict:
        """获取工具配置"""
        return self._configs.get(name, {})
    
    async def list_all(self) -> List[ToolMetadata]:
        """列出所有工具"""
        return list(self._tools.values())
    
    async def list_enabled(self) -> List[ToolMetadata]:
        """列出已启用的工具"""
        return [t for t in self._tools.values() if t.enabled]
    
    async def list_by_tag(self, tag: str) -> List[ToolMetadata]:
        """按标签筛选工具"""
        return [t for t in self._tools.values() if tag in t.tags]
    
    async def search(self, query: str) -> List[ToolMetadata]:
        """搜索工具"""
        query = query.lower()
        return [
            t for t in self._tools.values()
            if query in t.name.lower()
            or query in t.description.lower()
            or query in t.display_name.lower()
        ]
    
    # === 统计方法 ===
    
    async def record_call(
        self,
        name: str,
        duration_ms: int,
        error: bool = False,
    ) -> None:
        """记录调用"""
        async with self._lock:
            if name in self._tools:
                tool = self._tools[name]
                tool.call_count += 1
                tool.total_duration_ms += duration_ms
                if error:
                    tool.error_count += 1
    
    async def get_stats(self) -> dict:
        """获取统计信息"""
        tools = list(self._tools.values())
        return {
            "total_tools": len(tools),
            "enabled_tools": sum(1 for t in tools if t.enabled),
            "total_calls": sum(t.call_count for t in tools),
            "total_errors": sum(t.error_count for t in tools),
            "avg_error_rate": sum(t.error_rate for t in tools) / len(tools) if tools else 0,
        }
```

---

## 3. 工具发现机制

### 3.1 自动发现

```python
# tools/discovery.py
from pathlib import Path
from typing import List


class ToolDiscovery:
    """工具自动发现"""
    
    def __init__(self, manifest_dir: Path):
        self.manifest_dir = manifest_dir
    
    def discover(self) -> List[Path]:
        """发现所有 Manifest 文件"""
        manifests = list(self.manifest_dir.glob("**/*.yaml"))
        manifests.extend(self.manifest_dir.glob("**/*.yml"))
        manifests.extend(self.manifest_dir.glob("**/*.json"))
        return manifests
    
    def discover_by_tag(self, tag: str) -> List[Path]:
        """按标签发现"""
        # 读取所有 manifest，筛选标签
        pass
    
    async def hot_reload(self, registry: ToolRegistry) -> None:
        """热重载工具"""
        for manifest_path in self.discover():
            # 重新注册
            pass
```

### 3.2 启动时注册

```python
# tools/loader.py
from pathlib import Path


async def load_all_tools(registry: ToolRegistry) -> None:
    """加载所有工具"""
    manifest_dir = Path(__file__).parent / "manifests"
    
    discovery = ToolDiscovery(manifest_dir)
    
    for manifest_path in discovery.discover():
        tool_name = manifest_path.stem
        
        # 加载 executor
        executor = load_executor(manifest_path)
        
        # 加载配置
        config = load_config(tool_name)
        
        # 注册
        await registry.register(manifest_path, executor, config)


def load_executor(manifest_path: Path) -> Callable:
    """加载工具执行器"""
    import yaml
    
    with open(manifest_path) as f:
        manifest = yaml.safe_load(f)
    
    # 根据运行时类型加载
    runtime = manifest.get("runtime", "python")
    
    if runtime == "python":
        return load_python_executor(manifest)
    elif runtime == "javascript":
        return load_js_executor(manifest)
    else:
        return load_native_executor(manifest)
```

---

## 4. 工具描述生成

### 4.1 AI 友好的工具描述

```python
# tools/description.py
from typing import Dict, List


def generate_tool_description(manifest: dict) -> str:
    """生成 AI 友好的工具描述"""
    lines = [
        f"## {manifest['display_name']}",
        f"{manifest['description']}",
        "",
        "### 可用命令:",
    ]
    
    for cmd in manifest.get("commands", []):
        lines.append(f"#### {cmd['name']}")
        lines.append(cmd["description"])
        lines.append("")
        
        if cmd.get("example"):
            lines.append("**示例:**")
            lines.append(f"```\n{cmd['example']}\n```")
            lines.append("")
    
    return "\n".join(lines)


def generate_tools_for_llm(registry: ToolRegistry) -> str:
    """生成给 LLM 的工具列表"""
    tools = registry.list_enabled()
    
    sections = ["## 可用工具\n"]
    
    for tool in tools:
        manifest = load_manifest(tool.name)
        sections.append(generate_tool_description(manifest))
        sections.append("\n---\n")
    
    return "\n".join(sections)
```

---

## 5. 权限控制

### 5.1 工具权限

```python
# tools/permissions.py
from enum import Enum
from typing import Set


class ToolPermission(str, Enum):
    """工具权限"""
    EXECUTE = "tool:execute"
    CONFIGURE = "tool:configure"
    ENABLE = "tool:enable"
    DISABLE = "tool:disable"


class ToolPermissionChecker:
    """工具权限检查"""
    
    def __init__(self):
        self._user_permissions: Dict[str, Set[ToolPermission]] = {}
        self._tool_roles: Dict[str, Set[str]] = {}  # tool_name -> required_roles
    
    def set_user_permissions(
        self,
        user_id: str,
        permissions: Set[ToolPermission],
    ) -> None:
        """设置用户权限"""
        self._user_permissions[user_id] = permissions
    
    def set_tool_roles(
        self,
        tool_name: str,
        required_roles: Set[str],
    ) -> None:
        """设置工具所需角色"""
        self._tool_roles[tool_name] = required_roles
    
    def can_execute(self, user_id: str, tool_name: str) -> bool:
        """检查用户是否可以执行工具"""
        # 检查全局权限
        if ToolPermission.EXECUTE in self._user_permissions.get(user_id, set()):
            return True
        
        # 检查工具特定角色
        required_roles = self._tool_roles.get(tool_name, set())
        if not required_roles:
            return True
        
        # TODO: 检查用户是否有所需角色
        return False
```

---

## 6. 集成到 Agent

### 6.1 LangChain 集成

```python
# tools/langchain_adapter.py
from typing import List, Optional
from langchain.tools import BaseTool
from pydantic import BaseModel


class LangChainToolAdapter:
    """LangChain 工具适配器"""
    
    def __init__(self, registry: ToolRegistry):
        self.registry = registry
    
    def to_langchain_tools(self) -> List[BaseTool]:
        """转换为 LangChain 工具"""
        tools = []
        
        for metadata in self.registry.list_enabled():
            executor = self.registry.get_executor(metadata.name)
            config = self.registry.get_config(metadata.name)
            
            tool = self._create_tool(metadata, executor, config)
            tools.append(tool)
        
        return tools
    
    def _create_tool(
        self,
        metadata: ToolMetadata,
        executor: Callable,
        config: dict,
    ) -> BaseTool:
        """创建单个 LangChain 工具"""
        # 根据 manifest 创建工具
        pass
```

---

## 7. 实现步骤

| 步骤 | 任务 | 优先级 |
|------|------|--------|
| 1 | 实现 ToolRegistry 类 | 🟢 高 |
| 2 | 实现 ToolDiscovery | 🟢 高 |
| 3 | 实现工具描述生成 | 🟡 中 |
| 4 | 实现权限检查 | 🟡 中 |
| 5 | 实现 LangChain 适配器 | 🟡 中 |
| 6 | 集成到 Agent | 🟢 高 |
| 7 | 单元测试 | 🟡 中 |

---

## 8. 核心文件变更

| 文件 | 变更 |
|------|------|
| `tools/registry.py` | 新增 |
| `tools/discovery.py` | 新增 |
| `tools/description.py` | 新增 |
| `tools/permissions.py` | 新增 |
| `tools/langchain_adapter.py` | 新增 |
| `tools/__init__.py` | 更新导出 |

---

## 9. 工作量估算

| 任务 | 工作量 |
|------|--------|
| ToolRegistry | 0.5 天 |
| ToolDiscovery | 0.5 天 |
| 描述生成 | 0.3 天 |
| 权限检查 | 0.3 天 |
| LangChain 适配 | 0.3 天 |
| 集成 | 0.5 天 |
| 单元测试 | 0.5 天 |
| **总计** | **2.5 天** |

---

## 10. 验收标准

- [ ] ToolRegistry 可正确注册/注销工具
- [ ] ToolDiscovery 可发现所有 Manifest
- [ ] 工具描述生成正确
- [ ] 权限检查正常工作
- [ ] LangChain 工具可正常转换
- [ ] Agent 可使用注册的工具
- [ ] 单元测试通过