193 lines
6.6 KiB
Markdown
193 lines
6.6 KiB
Markdown
# 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 文档能够在这个认知基础上展开
|