JARVIS/development-doc/plan/tool-update/phase-t-0-current-state.md

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 形式存在：

# 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 六大插件类型

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

3.2 Manifest 标准契约

{
  "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. 本阶段产出要求

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