# Phase T.0：Tools 现状与目标

日期：2026-04-04
状态：已完成
借鉴来源：VCPToolBox Plugin 系统

---

## 1. 本阶段目的

本文件用于统一背景认知，明确：

- Jarvis 当前工具系统处于什么水平
- 主要短板是什么
- 为什么要升级
- 升级后的目标形态是什么
- VCPToolBox 给我们什么启发

---

## 2. 当前 Jarvis Tools 架构

### 2.1 核心流程

```
Agent 决策 → 工具调用 → LLM API → 返回结果
```

### 2.2 当前工具实现

Jarvis 当前的工具以 LangChain Tools 形式存在：

```python
# agents/tools/
├── base.py           # 工具基类
├── file_tools.py     # 文件操作
├── search_tools.py   # 搜索
└── web_tools.py      # 网页相关
```

### 2.3 当前工具列表

| 工具 | 功能 | 实现方式 |
|------|------|---------|
| `read_file` | 读取文件 | Python |
| `write_file` | 写入文件 | Python |
| `run_python` | 执行代码 | Python |
| `search_knowledge` | 知识库检索 | LangChain |
| `search_web` | 联网搜索 | API |

### 2.4 当前问题

| 问题 | 影响 |
|------|------|
| 硬编码工具 | 新增工具需改代码 |
| 无 manifest | 无法热插拔 |
| 无标准化契约 | 调用格式不统一 |
| 无配置分离 | 敏感信息易泄露 |
| 无类型安全 | 验证缺失 |
| 无权限控制 | 安全隐患 |

---

## 3. VCPToolBox 工具系统分析

### 3.1 六大插件类型

```javascript
const PLUGIN_TYPES = {
    static: "静态占位符，自动注入系统提示词",
    synchronous: "同步执行，stdio 协议",
    asynchronous: "异步执行，后台处理",
    service: "持续运行服务",
    hybridservice: "混合服务（Agent间通讯）",
    messagePreprocessor: "消息预处理"
};
```

### 3.2 Manifest 标准契约

```javascript
{
  "manifestVersion": "1.0.0",
  "name": "PluginName",
  "displayName": "中文显示名",
  "description": "功能描述",
  "pluginType": "synchronous",
  "version": "1.0.0",
  
  "entryPoint": {
    "type": "nodejs",
    "command": "node Plugin.js",
    "timeout": 300000
  },
  
  "communication": {
    "protocol": "stdio",
    "timeout": 300000
  },
  
  "configSchema": {
    "API_KEY": {
      "type": "string",
      "description": "API 密钥"
    }
  },
  
  "capabilities": {
    "invocationCommands": [
      {
        "commandIdentifier": "CommandName",
        "description": "详细描述+调用格式示例",
        "example": "调用示例"
      }
    ]
  }
}
```

### 3.3 核心设计理念

1. **声明式** - 工具通过 manifest 声明，框架自动发现
2. **标准化** - 统一的调用协议（stdio/websocket）
3. **可配置** - configSchema 声明配置项
4. **可观测** - 调用日志、超时控制
5. **安全隔离** - 沙箱执行、权限控制

### 3.4 关键文件

| 文件 | 作用 |
|------|------|
| `Plugin.js` | 插件加载与执行引擎 |
| `plugin-manifest.json` | 插件声明契约 |
| `config.env` | 插件配置 |
| `routes/` | API 路由层 |

---

## 4. 目标架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Tool Manifests                          │
│  - YAML/JSON 声明式定义                                     │
│  - 版本管理                                                 │
│  - Schema 验证                                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Tool Registry                             │
│  - 动态发现                                                 │
│  - 权限控制                                                 │
│  - 调用统计                                                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Tool Executor                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Python RT   │  │   JS RT     │  │  Native RT  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                    Tool Output                               │
│  - 类型化返回                                               │
│  - 错误处理                                                │
│  - 调用日志                                                │
└─────────────────────────────────────────────────────────────┘
```

---

## 5. 借鉴点映射

| VCPToolBox 借鉴点 | Jarvis 实现位置 | 优先级 |
|-------------------|---------------|--------|
| Manifest 驱动 | `tools/manifests/` | 🟢 高 |
| 标准化契约 | `tools/schemas/` | 🟢 高 |
| configSchema | `tools/base.py` | 🟢 高 |
| 工具注册中心 | `tools/registry.py` | 🟡 中 |
| 动态发现 | `tools/discovery.py` | 🟡 中 |
| 调用日志 | `tools/logging.py` | 🟡 中 |
| 超时控制 | `tools/executor.py` | 🟡 中 |
| 多运行时 | `tools/runtime/` | 🟡 中 |

---

## 6. 本阶段产出要求

- [x] 团队对 Jarvis 当前工具系统和目标方向达成一致
- [x] VCPToolBox 工具系统借鉴点已映射到具体 Phase
- [x] 后续 phase 文档能够在这个认知基础上展开