# Jarvis Tools 升级计划索引

本目录用于存放 Jarvis 工具系统的分阶段升级规划文档。

## 文档说明

| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、实施顺序 |
| `phase-t-0-current-state.md` | 当前现状、问题、目标架构、VCPToolBox 借鉴 |
| `phase-t-1-manifest-system.md` | Manifest 驱动系统 |
| `phase-t-2-tool-registry.md` | 工具注册中心 |
| `phase-t-3-tool-implementation.md` | 核心工具实现 |
| `phase-t-4-advanced.md` | 高级特性（多运行时/Agent协作） |
| `checklist.md` | 执行清单 |

## 推荐阅读顺序

1. 先读 `phase-t-0-current-state.md`
2. 再按顺序阅读 phase t-1 ~ t-4
3. 实施时严格按阶段推进
4. 参考 `checklist.md` 进行任务追踪

---

## 总体升级原则

1. **Manifest 驱动** - 声明式工具定义，热插拔
2. **标准契约** - 统一的调用格式和返回结构
3. **多运行时** - 支持 Python/JS/原生
4. **类型安全** - Pydantic Schema 验证
5. **可观测性** - 调用日志、耗时统计

---

## 阶段总览图

```
T.0 ──────────────────────────────────────────────────────────────┐
│ 现状与目标                                                           │
│ - 当前工具系统分析                                                     │
│ - 短板识别                                                           │
│ - VCPToolBox 工具系统借鉴                                            │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
T.1 ──────────────────────────────────────────────────────────────┐
│ Manifest 驱动系统                                                    │
│ - 工具 manifest 定义                                                │
│ - 标准化契约                                                       │
│ - Schema 验证                                                      │
│                                                                      │
│ 核心文件: tools/manifests/, tools/schemas/                       │
│ 工作量: 3 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
T.2 ──────────────────────────────────────────────────────────────┐
│ 工具注册中心                                                        │
│ - 工具发现机制                                                      │
│ - 动态注册                                                         │
│ - 工具描述生成                                                     │
│                                                                      │
│ 核心文件: tools/registry.py                                       │
│ 依赖: T.1                                                          │
│ 工作量: 2 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
T.3 ──────────────────────────────────────────────────────────────┐
│ 核心工具实现                                                        │
│ - 文件操作工具                                                      │
│ - 搜索工具                                                         │
│ - 网页抓取工具                                                     │
│ - 任务管理工具                                                     │
│                                                                      │
│ 核心文件: tools/implementations/                                   │
│ 依赖: T.2                                                          │
│ 工作量: 5 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
T.4 ──────────────────────────────────────────────────────────────┐
│ 高级特性                                                            │
│ - 多运行时支持                                                      │
│ - Agent 间协作                                                     │
│ - 定时任务                                                         │
│                                                                      │
│ 核心文件: tools/runtime/, agents/tools/                           │
│ 依赖: T.3                                                          │
│ 工作量: 4 天                                                       │
└────────────────────────────────────────────────────────────────────┘
```

---

## VCPToolBox 工具系统核心借鉴

| 借鉴点 | 实现位置 | 难度 |
|--------|---------|------|
| Manifest 驱动 | T.1 | 🟢 低 |
| 标准化契约 | T.1 | 🟢 低 |
| configSchema 配置 | T.1 | 🟢 低 |
| 工具注册中心 | T.2 | 🟡 中 |
| 动态发现 | T.2 | 🟡 中 |
| 文件操作工具 | T.3 | 🟢 低 |
| 搜索工具 | T.3 | 🟡 中 |
| 网页抓取 | T.3 | 🟡 中 |
| 多运行时支持 | T.4 | 🟡 中 |
| Agent 间协作 | T.4 | 🟡 中 |

---

## 实施顺序

```
T.0 → T.1 → T.2 → T.3 → T.4
  │       │       │       │       │
  │       │       │       │       └── 多运行时/Agent协作
  │       │       │       └── 核心工具
  │       │       └── 注册中心
  │       └── Manifest系统
  └── 现状与目标
```

**注意：** T.1 是基础，后续阶段都依赖 T.1。

---

## 文件变更追踪

| Phase | 新增文件 | 修改文件 |
|-------|---------|---------|
| T.1 | `tools/manifests/*.yaml`, `tools/schemas/` | `pyproject.toml` |
| T.2 | `tools/registry.py`, `tools/base.py` | `services/agent_service.py` |
| T.3 | `tools/implementations/*.py` | `tools/registry.py` |
| T.4 | `tools/runtime/`, `agents/tools/` | `agents/graph.py` |

---

## 与 Agent Phase 1-5 的关系

| Agent Phase | Tools 协作内容 |
|-------------|---------------|
| Phase 1 | Task Schema 追踪工具调用 |
| Phase 2 | 工具可委托给执行 Agent |
| Phase 3 | 动态选择最优工具 |
| Phase 4 | 工具调用可视化 |
| Phase 5 | 多 Agent 工具协作 |
| **Phase T** | **工具系统升级，与 Phase 1-5 协同** |

---

## 注意事项

| 注意事项 | 说明 |
|---------|------|
| T.1 是基础 | T.2-T.4 都依赖 T.1 的 Manifest 系统 |
| 兼容性优先 | 保持现有 Agent 工具调用方式 |
| 安全第一 | 严格权限控制，防止滥用 |
| 测试优先 | 每个工具都要配套测试 |

---

## 总工作量

| Phase | 工作量 |
|-------|--------|
| T.1 | 3 天 |
| T.2 | 2 天 |
| T.3 | 5 天 |
| T.4 | 4 天 |
| **总计** | **14 天** |