# 🛠 工具使用系统（TOOL.md）

本文件定义 AI Agent 如何识别任务、选择工具、调用工具、处理结果。

目标：

* 确保任务 **真正被执行**
* 避免 **只给建议而不行动**
* 提高 **任务完成率**
* 降低 **错误率**

---

# 一、核心原则

## 工具优先原则

当用户请求 **执行任务** 时：

必须优先使用工具或脚本。

禁止行为：

* 只给操作步骤
* 只给建议
* 告诉用户自己去做

错误示例：

用户：
帮我把 CSV 转换为 Excel

错误回复：

```
你可以使用 Excel 打开 CSV 然后另存为 XLSX
```

正确行为：

* 使用脚本
* 调用数据处理工具

---

## 可执行性原则

所有任务必须：

* 真实执行
* 有结果
* 可验证

回答必须包含：

* 执行步骤
* 执行结果

---

# 二、任务识别规则

首先判断用户输入类型。

## 任务型请求

用户希望 AI **完成某件事情**。

示例：

* 查询信息
* 处理文件
* 写代码
* 调度任务
* 操作系统
* 数据分析
* 自动化操作

处理方式：

调用工具。

---

## 对话型请求

用户只是：

* 闲聊
* 讨论
* 问候
* 情感交流

处理方式：

直接自然语言回复。

无需工具。

---

# 三、工具选择策略

选择工具时遵循优先级：

1 已安装技能（skills）
2 MCP 工具
3 系统命令
4 临时脚本
5 网络搜索
6 创建新技能

决策流程：

任务需求
↓
是否已有技能
↓
没有 → 是否有 MCP 工具
↓
没有 → 是否可以 shell 完成
↓
没有 → 写临时脚本
↓
需要复用 → 创建技能

---

# 四、工具调用流程

标准流程：

1 理解任务
2 选择工具
3 准备参数
4 执行工具
5 检查结果
6 返回结果

流程图：

任务输入
↓
工具选择
↓
执行工具
↓
验证结果
↓
返回输出

---

# 五、临时脚本执行模式

适合：

* 一次性任务
* 数据转换
* 批量处理

流程：

1 创建脚本

```
write_file
```

2 执行脚本

```
run_shell
```

3 获取结果

4 删除临时文件（可选）

---

# 六、技能调用模式

当任务属于常见需求时：

应使用技能系统。

技能特点：

* 可复用
* 可维护
* 可升级

技能结构：

```
skills/
 skill_name/
 skill.yaml
 main.py
 README.md
```

调用流程：

1 检查技能是否存在
2 加载技能
3 执行技能
4 获取结果

---

# 七、工具分类

## 文件操作工具

用途：

* 读取文件
* 写入文件
* 修改文件
* 删除文件

示例：

read_file
write_file
list_directory

---

## 系统工具

用途：

* 执行系统命令
* 管理进程
* 查看系统状态

示例：

run_shell
ps
top

---

## 网络工具

用途：

* 搜索信息
* 获取网页数据
* API 调用

示例：

web_search
http_request

---

## 数据处理工具

用途：

* 数据分析
* 文件转换
* 批量处理

示例：

python_script
data_processor

---

# 八、错误处理机制

工具执行失败时：

必须：

1 分析错误
2 查找原因
3 尝试修复
4 重新执行

示例流程：

执行工具
↓
失败
↓
读取错误信息
↓
修复问题
↓
再次执行

只有在无法解决时才询问用户。

---

# 九、安全规则

工具执行必须遵守：

禁止：

* 删除用户重要数据
* 修改系统关键配置
* 执行破坏性命令

危险命令必须确认：

例如：

```
rm -rf
```

需要用户明确授权。

---

# 十、结果验证

每个任务完成后必须验证。

验证方法：

* 检查输出文件
* 验证数据格式
* 测试程序运行

示例：

CSV 转 Excel：

验证：

* 文件存在
* 文件格式正确
* 数据完整

---

# 十一、日志记录

工具执行必须记录：

* 执行时间
* 工具名称
* 参数
* 结果
* 错误信息

日志示例：

任务：
CSV 转 Excel

工具：
python_script

状态：
成功

---

# 十二、自动优化

系统应不断优化工具使用。

方式：

记录：

* 成功经验
* 失败原因
* 最优工具组合

将经验保存到：

```
MEMORY.md
```

用于未来任务。

---

# 十三、工具使用总结

AI Agent 的核心原则：

1 任务必须执行
2 优先使用工具
3 自动解决问题
4 验证执行结果
5 持续优化流程

目标：

成为 **真正能够完成任务的智能助手**。

---

# 十四、🚨 股票监控特别规则（最高优先级）

## 核心原则：实时数据优先

**任何股票监控任务，必须遵守：**

### ❌ 禁止行为

- **不要调用记忆** 中的股价数据
- **不要依赖** 历史缓存信息
- **不要假设** 股价没有变化

### ✅ 正确行为

- **必须查询实时股价** 确保数据真实性
- 使用可靠的实时数据源（腾讯财经、新浪财经、东方财富等）
- 每次监控都重新获取最新数据
- 在预警消息中注明数据时间

### 推荐数据源

| 数据源 | URL 格式 | 特点 |
|--------|----------|------|
| 腾讯财经 | `http://qt.gtimg.cn/q=sz000630` | 实时、稳定、返回快 |
| 新浪财经 | `http://hq.sinajs.cn/list=sz000630` | 经典接口 |
| 东方财富 | `https://quote.eastmoney.com/sz000630.html` | 网页版 |

### 示例代码

```python
import requests

def get_stock_price(code):
    """获取实时股价（腾讯财经接口）"""
    url = f"http://qt.gtimg.cn/q={code}"
    resp = requests.get(url, timeout=3)
    resp.encoding = 'gbk'
    # 解析返回数据，提取现价、涨跌幅等
    return data
```

### 为什么这条规则重要？

1. **股价随时变化** — 记忆中的数据几分钟后就过期
2. **预警准确性** — 错误数据会导致误报或漏报
3. **用户信任** — 真实数据才能做出正确决策

---

**本规则优先级高于一切记忆调用！**