编辑 - AI 小白学 Tool Calling 完全指南

取消

## 一句话总结

**Tool Calling = AI 决定"用什么工具+参数"，代码去执行，结果喂回给 AI 继续回答。**

---

## 为什么需要 Tool Calling？

没有 Tool Calling 的 AI：
> 你：数据库现在有多少条笔记？
> AI：抱歉，我不知道。（训练数据是截止的）

有 Tool Calling 的 AI：
> 你：数据库现在有多少条笔记？
> AI：让我查一下 → 调用 `get_dashboard_stats()` → 拿到结果 → "当前有 9 条笔记"

---

## 核心流程图

```
你（问问题）
    ↓
① AI 收到问题 + 可用的工具清单
    ↓
② AI 决定用哪个工具 → 返回 tool_use（工具名 + 参数）
    ↓                          ← AI 只负责"决定"，不负责"执行"
③ 框架/代码 执行对应的函数 → 拿到结果
    ↓
④ 结果发回给 AI → AI 组织回答
    ↓
你（看到答案）
```

---

## 关键概念

### 1. Tool Definition（工具定义）

每个工具都需要一个描述，告诉 AI 这个工具是干什么的：

```python
get_dashboard_stats.tool_definition = {
    "name": "get_dashboard_stats",          # 工具名
    "description": "获取笔记中心统计信息",    # 什么时候用
    "parameters": {                          # 需要什么参数
        "dry_run": {
            "type": "boolean",
            "description": "True=只预览",
        }
    }
}
```

### 2. tool_use（AI 的返回）

AI 决定用工具时，API 返回的结构：

```json
{
  "type": "tool_use",
  "name": "search_notes",
  "input": {"query": "Agent"}
}
```

### 3. tool_result（执行结果喂回给 AI）

```json
{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "call_123",
    "content": "{"total_notes": 9}"
  }]
}
```

---

## 三个层次

| 层 | 谁写的 | 作用 |
|---|---|---|
| **系统提示词** | Claude Code 团队 | 告诉 AI 有哪些工具可用 |
| **运行框架** | Claude Code 团队 | 实现"收到 tool_use → 执行 → 结果发回"的循环 |
| **API 协议** | Anthropic API 团队 | 定义 tool_use / tool_result 的数据格式 |

> 你只需要定义好**工具函数 + tool_definition**，剩下的循环机制框架自动处理。

---

## 亲手实践：在笔记中心写工具

### 你写的第一个工具：reorder_note_titles()

作用：把笔记标题里的序号按实际排列顺序重排。

```python
def reorder_note_titles(dry_run=True):
    # 1. 查出所有笔记（按显示顺序）
    # 2. 循环重编序号：位置1→"1."，位置2→"2."...
    # 3. dry_run=True 只预览，False 才真正修改
```

安全机制：**默认只预览不修改**（`dry_run=True`），确认后再执行。

### 完整的工具列表

在 `note-center/tools.py` 中定义了 7 个工具：

| 工具 | 作用 |
|---|---|
| `get_recent_notes(limit)` | 获取最近笔记 |
| `search_notes(query)` | 搜索笔记 |
| `get_notes_by_tag(tag_name)` | 按标签筛选 |
| `get_note_by_id(note_id)` | 获取笔记详情 |
| `get_tag_statistics()` | 标签统计 |
| `get_dashboard_stats()` | 总体统计 |
| `reorder_note_titles(dry_run)` | 重排标题序号 |

---

## 和已学概念的关系

```
Skill ── 别人配好的一组工具调用脚本
Agent ── 自动循环 Tool Calling（思考→调工具→拿结果→再思考）
MCP   ── 通过标准协议暴露工具给 AI
         ↑
    Tool Calling = 它们三个的发动机
```

---

## 记住这句话

> AI 只负责"决策"，代码负责"执行"。

预览

编辑内容后实时预览...