Skip to content

LeoYeAI/agent-master-skills / skills/agi-evolution-model-basic

agi-evolution-model

Verified

基于双环架构的AGI进化模型,通过意向性分析、人格层映射和元认知检测实现持续自我演进;当用户需要智能对话、人格定制或复杂问题求解时使用

FileKindSize
SKILL.mdskill md21.9 KB
_meta.jsonconfig307 B
assets/personality_template.jsonconfig4.1 KB
references/architecture.mdmarkdown50.0 KB
references/c_extension_usage.mdmarkdown3.0 KB
references/capability_boundaries.mdmarkdown4.5 KB
references/cognitive-architecture-insight-module.mdmarkdown11.9 KB
references/cognitive-insight-quick-reference.mdmarkdown7.0 KB
references/cognitive-insight-v2-implementation.mdmarkdown32.7 KB
references/information-flow-main-loop.mdmarkdown20.4 KB
references/information-flow-overview.mdmarkdown12.4 KB
references/information-flow-secondary-loop.mdmarkdown20.4 KB
references/init_dialogue_optimized_guide.mdmarkdown11.1 KB
references/intentionality_architecture.mdmarkdown16.2 KB
references/maslow_needs.mdmarkdown4.4 KB
references/metacognition-check-component.mdmarkdown30.2 KB
references/metacognition-enhancement-guide.mdmarkdown12.6 KB
references/personality_mapping.mdmarkdown5.6 KB
references/stratified-storage-design.mdmarkdown10.6 KB
references/tool_use_spec.mdmarkdown56.3 KB
scripts/advice_pool.pyscript14.9 KB
scripts/cognitive_insight.pyscript20.9 KB
scripts/cognitive_insight_backup.pyscript25.2 KB
scripts/cognitive_insight_help.pyscript12.1 KB
scripts/concept_extraction_extension.pyscript25.3 KB
scripts/data_lifecycle_manager.pyscript13.4 KB
scripts/history_manager.pyscript7.4 KB
scripts/init_dialogue_optimized.pyscript16.4 KB
scripts/intentionality_analyzer.pyscript12.8 KB
scripts/intentionality_classifier.pyscript13.8 KB
scripts/intentionality_collector.pyscript9.7 KB
scripts/intentionality_regulator.pyscript15.1 KB
scripts/intentionality_trigger.pyscript19.9 KB
scripts/learning_stage_tracker.pyscript7.9 KB
scripts/memory_store_pure.pyscript12.0 KB
scripts/metacognition_history.pyscript16.3 KB
scripts/objectivity_evaluator.pyscript16.4 KB
scripts/perception_node.pyscript26.9 KB
scripts/personality_core_pure.pyscript4.4 KB
scripts/personality_customizer.pyscript24.0 KB
scripts/personality_layer_pure.pyscript32.2 KB
scripts/show_help.pyscript4.7 KB
scripts/strategy_selector.pyscript15.5 KB
scripts/test_metacognition_integration.pyscript9.4 KB
scripts/test_perception_node.pyscript9.2 KB
scripts/transcendence_keeper.pyscript11.7 KB

references/tool_use_spec.md

View on GitHub
# Tool Use 接口设计规范

## 目录
- [概览](#概览)
- [基础结构](#基础结构)
- [设计原则](#设计原则)
- [标准化输出格式](#标准化输出格式)
- [流式响应(SSE)](#流式响应sse)
- [复杂数据处理](#复杂数据处理)
- [错误处理](#错误处理)
- [可观测性](#可观测性)
- [版本控制与生命周期](#版本控制与生命周期)
- [上下文管理](#上下文管理)
- [行业标准参考](#行业标准参考)
- [最佳实践](#最佳实践)
- [选型建议](#选型建议)
- [趋势与展望](#趋势与展望)
- [在感知节点中的应用](#在感知节点中的应用)

---

## 概览

Tool Use(工具调用)是连接智能体与外部世界的关键接口。本规范定义了感知节点使用的标准化接口,确保工具调用的可靠性和一致性。

### 核心价值

- **标准化**:统一接口格式,降低集成成本
- **可靠性**:参数校验、错误处理、重试策略
- **可扩展**:支持动态工具发现(MCP)
- **兼容性**:兼容主流 AI 平台的规范
- **可观测**:全链路追踪、实时反馈、调试支持

---

## 基础结构

### 工具定义格式

```json
{
  "name": "get_current_weather",
  "description": "获取指定城市的实时天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市名称,如 'Beijing' 或 'San Francisco, CA'"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度单位"
      }
    },
    "required": ["location"],
    "additionalProperties": false
  },
  "strict": true,
  "version": "1.0.0",
  "cacheable": true,
  "estimated_tokens": 200
}
```

### 工具定义扩展字段

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| name | string | 是 | 工具名称,使用 snake_case |
| description | string | 是 | 工具功能描述 |
| parameters | object | 是 | 参数定义(JSON Schema) |
| strict | boolean | 推荐 | 是否开启严格模式(默认 false) |
| version | string | 推荐 | 工具版本号(语义化版本) |
| cacheable | boolean | 否 | 是否支持结果缓存(默认 false) |
| estimated_tokens | number | 否 | 预估返回消耗的 Token 数量 |
| deprecated | boolean | 否 | 是否已废弃(默认 false) |
| sunset_date | string | 否 | 计划废弃日期(ISO 8601 格式) |

### 命名规范

- 使用英文小写+下划线(snake_case)
- 符合正则:`^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$`
- 名称语义清晰,如 `search_product` 优于 `do_stuff`

### 描述撰写原则

| 要素 | 建议 | 示例 |
|------|------|------|
| 功能描述 | 一句话说明用途 | "查询股票实时价格" |
| 参数说明 | 标注类型、格式、取值范围 | "symbol: 股票代码,如 'AAPL'" |
| 边界条件 | 说明限制或异常场景 | "仅支持美股市场,数据延迟15分钟" |

---

## 设计原则

### 单一职责原则

**错误**(多功能聚合):
```python
{
  "name": "query_service",
  "description": "可查天气、股票、新闻..."
}
```

**正确**(拆分为独立工具):
- `get_weather(location)`
- `get_stock_price(symbol)`
- `search_news(keyword)`

### 幂等性设计

- 相同输入参数 → 相同输出结果
- 避免因网络重试导致重复执行副作用

### 参数校验前置

```python
def get_weather(location: str, unit: str = "celsius"):
    # 前置校验
    if not re.match(r'^[A-Za-z\s,]+$', location):
        return {"success": False, "error": "Invalid location format"}
    if unit not in ["celsius", "fahrenheit"]:
        return {"success": False, "error": "Invalid unit"}
    # 业务逻辑...
```

### Strict Mode

**关键配置**:`strict: true` + `additionalProperties: false`

```json
{
  "strict": true,
  "parameters": {
    "additionalProperties": false
  }
}
```

**重要性**:
- ✅ 100% Schema 合规保证
- ✅ 防止模型产生幻觉参数
- ✅ 生产环境标配(2026 年标准)

---

## 标准化输出格式

### 基础响应格式

#### 成功响应

```json
{
  "success": true,
  "status": "success",
  "data": {
    "temperature": 25,
    "condition": "sunny"
  },
  "metadata": {
    "tool_name": "get_weather",
    "execution_time_ms": 127,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123_xyz789"
  }
}
```

#### 错误响应

```json
{
  "success": false,
  "status": "error",
  "error": {
    "code": "CITY_NOT_FOUND",
    "message": "城市'XYZ'未收录",
    "retryable": false
  },
  "metadata": {
    "tool_name": "get_weather",
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123_xyz789"
  }
}
```

### 字段说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| success | bool | 是 | 操作是否成功 |
| status | string | 是 | 状态值:success/error |
| data | object | 条件 | 成功时的返回数据 |
| error | object | 条件 | 失败时的错误信息 |
| metadata | object | 是 | 元数据 |
| metadata.tool_name | string | 是 | 工具名称 |
| metadata.execution_time_ms | number | 否 | 执行耗时(毫秒) |
| metadata.timestamp | string | 是 | 时间戳(ISO 8601) |
| metadata.trace_id | string | 是 | 全链路追踪ID |
| error.code | string | 是 | 错误码 |
| error.message | string | 是 | 错误消息 |
| error.retryable | bool | 否 | 是否可重试(默认 false) |

---

## 流式响应(SSE)

### 概述

对于长时间执行的工具(如网页抓取、大数据查询),使用 Server-Sent Events (SSE) 提供实时进度反馈,避免用户长时间等待。

### SSE 事件基础结构

```
event: <事件类型>
id: <事件ID>
data: <JSON数据>
```

### 事件类型定义

| 事件类型 | 说明 | 触发时机 |
|----------|------|----------|
| `tool_progress` | 工具执行进度 | 长时间任务执行中 |
| `tool_result` | 工具执行成功结果 | 工具执行完成且成功 |
| `tool_error` | 工具执行错误 | 工具执行失败或异常 |
| `tool_retrying` | 重试通知 | 遇到可重试错误时 |

### 事件示例

#### 1. 工具执行进度事件

```sse
event: tool_progress
id: evt_20240305_abc123
data: {
  "progress": 45,
  "message": "正在获取天气数据...",
  "metadata": {
    "tool_name": "get_weather",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

#### 2. 工具执行完成事件

```sse
event: tool_result
id: evt_20240305_def456
data: {
  "success": true,
  "status": "success",
  "data": {
    "temperature": 25,
    "condition": "sunny"
  },
  "metadata": {
    "tool_name": "get_weather",
    "execution_time_ms": 127,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_xyz789"
  }
}
```

#### 3. 工具执行错误事件

```sse
event: tool_error
id: evt_20240305_ghi789
data: {
  "success": false,
  "status": "error",
  "error": {
    "code": "CITY_NOT_FOUND",
    "message": "城市'XYZ'未收录",
    "retryable": false
  },
  "metadata": {
    "tool_name": "get_weather",
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_xyz789"
  }
}
```

#### 4. 重试事件

```sse
event: tool_retrying
id: evt_20240305_jkl012
data: {
  "retry_count": 1,
  "max_retries": 3,
  "error": {
    "code": "TIMEOUT",
    "message": "请求超时,正在重试..."
  },
  "metadata": {
    "tool_name": "get_weather",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

### SSE 字段说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| event | string | 是 | 事件类型:tool_progress/tool_result/tool_error/tool_retrying |
| id | string | 是 | 事件唯一标识,用于断线重连 |
| data | object | 是 | 工具调用结果(遵循基础响应格式) |

### 服务端实现示例(TypeScript)

```typescript
import express from "express";
import { createSession } from "better-sse";

const app = express();

app.get("/tools/:toolName/sse", async (req, res) => {
  const session = await createSession(req, res);
  const { toolName } = req.params;
  const params = req.query;

  try {
    // 1. 推送开始事件
    session.push(JSON.stringify({
      progress: 0,
      message: `开始执行工具: ${toolName}`,
      metadata: {
        tool_name: toolName,
        timestamp: new Date().toISOString()
      }
    }), "tool_progress");

    // 2. 执行工具(模拟进度更新)
    const result = await executeToolWithProgress(toolName, params, (progress, message) => {
      session.push(JSON.stringify({
        progress,
        message,
        metadata: {
          tool_name: toolName,
          timestamp: new Date().toISOString()
        }
      }), "tool_progress");
    });

    // 3. 推送成功结果
    session.push(JSON.stringify({
      success: true,
      status: "success",
      data: result,
      metadata: {
        tool_name: toolName,
        execution_time_ms: 100,
        timestamp: new Date().toISOString(),
        trace_id: generateTraceId()
      }
    }), "tool_result");

  } catch (error) {
    // 4. 推送错误事件
    session.push(JSON.stringify({
      success: false,
      status: "error",
      error: {
        code: error.code || "EXECUTION_ERROR",
        message: error.message
      },
      metadata: {
        tool_name: toolName,
        timestamp: new Date().toISOString(),
        trace_id: generateTraceId()
      }
    }), "tool_error");
  }
});

async function executeToolWithProgress(toolName, params, onProgress) {
  // 模拟长时间执行的任务
  for (let i = 0; i <= 100; i += 20) {
    await new Promise(resolve => setTimeout(resolve, 200));
    onProgress(i, `处理中... ${i}%`);
  }
  
  // 调用实际工具逻辑
  return { result: "data" };
}

function generateTraceId() {
  return `trace_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

app.listen(3000);
```

### 客户端实现示例(JavaScript)

```javascript
class ToolSSEClient {
  constructor(toolName, params) {
    this.toolName = toolName;
    this.params = params;
    this.eventSource = null;
  }

  connect() {
    const url = `/tools/${this.toolName}/sse?${new URLSearchParams(this.params)}`;
    this.eventSource = new EventSource(url);

    // 监听进度事件
    this.eventSource.addEventListener("tool_progress", (e) => {
      const data = JSON.parse(e.data);
      console.log(`进度: ${data.progress}% - ${data.message}`);
      this.onProgress?.(data);
    });

    // 监听成功结果
    this.eventSource.addEventListener("tool_result", (e) => {
      const data = JSON.parse(e.data);
      console.log("工具执行成功:", data);
      this.onResult?.(data);
      this.eventSource.close();
    });

    // 监听错误事件
    this.eventSource.addEventListener("tool_error", (e) => {
      const data = JSON.parse(e.data);
      console.error("工具执行失败:", data);
      this.onError?.(data);
      this.eventSource.close();
    });

    // 监听重试事件
    this.eventSource.addEventListener("tool_retrying", (e) => {
      const data = JSON.parse(e.data);
      console.warn(`重试中 (${data.retry_count}/${data.max_retries}):`, data.error);
      this.onRetrying?.(data);
    });

    this.eventSource.onerror = (e) => {
      console.error("SSE 连接错误:", e);
      this.eventSource.close();
    };
  }

  close() {
    this.eventSource?.close();
  }
}

// 使用示例
const client = new ToolSSEClient("get_weather", { location: "Beijing" });
client.onProgress = (data) => {
  // 更新UI进度
};
client.onResult = (data) => {
  // 处理结果
};
client.onError = (data) => {
  // 处理错误
};
client.connect();
```

### 断线重连机制

利用 SSE 的 `Last-Event-ID` 实现断线重连:

```typescript
app.get("/tools/:toolName/sse", async (req, res) => {
  const lastEventId = req.headers["last-event-id"];
  const session = await createSession(req, res);
  
  // 如果有 lastEventId,从断点恢复
  if (lastEventId) {
    const replayEvents = await getEventsAfter(lastEventId);
    for (const event of replayEvents) {
      session.push(event.data, event.eventType);
    }
  }
  
  // 继续正常流程...
});
```

### 与 MCP 协议的兼容性

MCP 协议本身就支持通过 SSE 传输 JSON-RPC 消息。可以将上述 SSE 事件格式转换为 MCP 消息:

```json
// MCP 进度通知
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progress": 45,
    "message": "正在获取天气数据...",
    "tool_name": "get_weather"
  }
}

// MCP 成功响应
{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "data": { "temperature": 25 },
    "metadata": { "tool_name": "get_weather", "trace_id": "trace_abc123" }
  }
}
```

### 集成建议

1. **渐进式集成**:
   - 先在原有的 HTTP 响应格式基础上增加 SSE 支持
   - 保持原有 API 不变,新增 `/sse` 端点

2. **性能优化**:
   - 对于快速工具(<1s),使用原有 HTTP 响应
   - 对于长时间工具,自动切换到 SSE 模式

3. **监控与日志**:
   - 记录每个 SSE 事件的 trace_id
   - 监控连接时长、事件丢失率

---

## 复杂数据处理

### 分页机制

当工具返回大量数据(如搜索结果、日志列表)时,使用游标分页机制避免上下文溢出。

#### 分页响应格式

```json
{
  "success": true,
  "status": "success",
  "data": {
    "items": [
      { "id": 1, "name": "Item 1" },
      { "id": 2, "name": "Item 2" }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJvZmZzZXQiOjEwfQ==",
      "total_count": 100
    }
  },
  "metadata": {
    "tool_name": "search_items",
    "execution_time_ms": 45,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123"
  }
}
```

#### 分页参数

```json
{
  "parameters": {
    "type": "object",
    "properties": {
      "cursor": {
        "type": "string",
        "description": "分页游标,首次调用不传"
      },
      "limit": {
        "type": "integer",
        "description": "每页数量,默认 10,最大 100",
        "minimum": 1,
        "maximum": 100
      }
    }
  }
}
```

### 文件与二进制数据

工具返回图片、PDF 或音频等二进制数据时,使用 Base64 编码或预签名 URL。

#### 方式1:Base64 编码返回

```json
{
  "success": true,
  "status": "success",
  "data": {
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "content_base64": "JVBERi0xLjQKJdP0g..."
  },
  "metadata": {
    "tool_name": "generate_report",
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123"
  }
}
```

#### 方式2:预签名 URL 返回

```json
{
  "success": true,
  "status": "success",
  "data": {
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "url": "https://storage.example.com/reports/report.pdf?signature=...",
    "expires_at": "2024-01-01T01:00:00Z"
  },
  "metadata": {
    "tool_name": "generate_report",
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123"
  }
}
```

**选择建议:**
- 小文件(<1MB):使用 Base64 编码
- 大文件(≥1MB):使用预签名 URL
- 公开文件:使用直接 URL
- 私有文件:使用预签名 URL

### 大响应截断

如果工具返回内容超过模型的上下文窗口限制,提供截断策略或摘要机制。

#### 截断响应格式

```json
{
  "success": true,
  "status": "success",
  "data": {
    "content": "...[前 2000 字符]...",
    "truncated": true,
    "truncation_info": {
      "original_length": 15000,
      "returned_length": 2000,
      "summary": "该文档包含 15 个章节,主要讨论了..."
    }
  },
  "metadata": {
    "tool_name": "get_document",
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123"
  }
}
```

#### 截断参数

```json
{
  "parameters": {
    "type": "object",
    "properties": {
      "max_length": {
        "type": "integer",
        "description": "最大返回字符数,默认 2000"
      },
      "return_summary": {
        "type": "boolean",
        "description": "截断时是否返回摘要,默认 true"
      }
    }
  }
}
```

---

## 错误处理

### 错误类型

| 错误码 | 含义 | 处理建议 |
|--------|------|---------|
| INVALID_PARAMS | 参数验证失败 | 检查参数类型和格式 |
| RESOURCE_NOT_FOUND | 资源不存在 | 确认资源ID或路径 |
| PERMISSION_DENIED | 权限不足 | 检查授权 |
| TIMEOUT | 执行超时 | 重试或优化 |
| RATE_LIMITED | 超出速率限制 | 延迟后重试 |
| NETWORK_ERROR | 网络错误 | 重试 |
| EXECUTION_ERROR | 执行错误 | 检查日志 |
| QUOTA_EXCEEDED | 配额超限 | 升级计划 |

### 重试策略

```python
# 重试规则
- 网络错误:最多重试 3 次,指数退避
- 超时错误:最多重试 2 次,指数退避
- 速率限制:根据 Retry-After 头延迟重试
- 参数错误:不重试(立即返回)
- 权限错误:不重试(立即返回)
- 配额超限:不重试(立即返回)
```

### 重试实现示例

```python
def call_tool_with_retry(tool_name: str, params: dict, max_retries: int = 3) -> dict:
    """
    带重试的工具调用
    
    重试策略:
    - 网络错误:最多重试 3 次
    - 超时错误:最多重试 2 次
    - 参数错误:不重试
    - 权限错误:不重试
    """
    retry_count = 0
    last_error = None
    
    while retry_count < max_retries:
        try:
            result = execute_tool(tool_name, params)
            
            # 检查是否需要重试
            if not result['success']:
                error_code = result.get('error', {}).get('code')
                
                # 参数错误和权限错误不重试
                if error_code in ['INVALID_PARAMS', 'PERMISSION_DENIED', 'QUOTA_EXCEEDED']:
                    return result
                
                # 超时错误最多重试 2 次
                if error_code == 'TIMEOUT' and retry_count >= 2:
                    return result
                
                # 速率限制错误,根据 Retry-After 延迟
                if error_code == 'RATE_LIMITED':
                    retry_after = result.get('retry_after', 1)
                    time.sleep(retry_after)
                    last_error = result
                    retry_count += 1
                    continue
                
                # 其他错误继续重试
                last_error = result
                retry_count += 1
                time.sleep(2 ** retry_count)  # 指数退避
                continue
            
            return result
        
        except requests.exceptions.RequestException as e:
            # 网络错误重试
            last_error = {
                "success": False,
                "status": "error",
                "error": {
                    "code": "NETWORK_ERROR",
                    "message": str(e)
                }
            }
            retry_count += 1
            time.sleep(2 ** retry_count)
            continue
        
        except Exception as e:
            # 其他错误不重试
            return {
                "success": False,
                "status": "error",
                "error": {
                    "code": "UNKNOWN_ERROR",
                    "message": str(e)
                }
            }
    
    # 重试次数用尽
    return last_error
```

---

## 可观测性

### Trace ID 全链路追踪

所有工具调用必须包含 `trace_id`,用于关联整个 Agent 推理链路。

#### Trace ID 生成规则

```python
import uuid

def generate_trace_id() -> str:
    """生成全链路追踪 ID"""
    return f"trace_{datetime.now().strftime('%Y%m%d')}_{uuid.uuid4().hex[:12]}"
```

#### Trace ID 传递

```python
def execute_tool_with_trace(tool_name: str, params: dict, trace_id: str) -> dict:
    """执行工具并传递 trace_id"""
    # 在 metadata 中包含 trace_id
    params_with_trace = {
        **params,
        "_trace_id": trace_id  # 内部传递
    }
    
    result = execute_tool(tool_name, params_with_trace)
    
    # 确保返回结果包含 trace_id
    result.setdefault('metadata', {})['trace_id'] = trace_id
    
    return result
```

### 调试模式

开发阶段支持返回详细调试信息,生产环境可屏蔽。

#### 调试响应格式

```json
{
  "success": true,
  "status": "success",
  "data": {
    "temperature": 25,
    "condition": "sunny"
  },
  "metadata": {
    "tool_name": "get_weather",
    "execution_time_ms": 127,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123"
  },
  "debug_info": {
    "internal_api_response": {
      "status": 200,
      "body": "..."
    },
    "cache_hit": false,
    "query_duration_ms": 45
  }
}
```

#### 调试参数

```json
{
  "parameters": {
    "type": "object",
    "properties": {
      "debug": {
        "type": "boolean",
        "description": "是否返回调试信息,仅开发环境使用"
      }
    }
  }
}
```

### 延迟监控

记录工具执行的详细耗时信息,用于性能分析。

#### 延迟元数据

```json
{
  "metadata": {
    "tool_name": "get_weather",
    "execution_time_ms": 127,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123",
    "performance": {
      "validation_ms": 2,
      "network_ms": 115,
      "processing_ms": 10
    }
  }
}
```

### 监控指标

建议监控以下指标:

| 指标 | 说明 | 告警阈值 |
|------|------|---------|
| 调用成功率 | 成功调用数 / 总调用数 | < 95% |
| 平均响应时间 | 所有调用的平均耗时 | > 500ms |
| P99 响应时间 | 99% 调用的耗时 | > 2000ms |
| 错误率 | 错误调用数 / 总调用数 | > 5% |
| 重试率 | 重试调用数 / 总调用数 | > 10% |

---

## 版本控制与生命周期

### 工具版本号

使用语义化版本(Semantic Versioning):

- `MAJOR.MINOR.PATCH`
- `MAJOR`:不兼容的 API 变更
- `MINOR`:向下兼容的功能新增
- `PATCH`:向下兼容的问题修复

#### 版本号示例

```json
{
  "name": "get_weather",
  "version": "2.1.0",
  "description": "获取指定城市的实时天气信息",
  "changelog": {
    "2.1.0": "新增空气质量数据",
    "2.0.0": "重命名参数 location 为 city(不兼容变更)",
    "1.2.0": "支持摄氏度和华氏度",
    "1.1.0": "新增天气状况描述",
    "1.0.0": "初始版本"
  }
}
```

### 废弃策略

明确标记工具废弃状态和计划废弃日期。

#### 废弃标记

```json
{
  "name": "get_weather_v1",
  "version": "1.0.0",
  "deprecated": true,
  "sunset_date": "2026-12-31",
  "replacement": "get_weather",
  "migration_guide": "https://docs.example.com/migration/weather-v1-to-v2"
}
```

#### 废弃响应

```json
{
  "success": false,
  "status": "error",
  "error": {
    "code": "TOOL_DEPRECATED",
    "message": "工具 'get_weather_v1' 已废弃,请使用 'get_weather'",
    "replacement": "get_weather",
    "sunset_date": "2026-12-31",
    "migration_guide": "https://docs.example.com/migration/weather-v1-to-v2"
  }
}
```

### 向后兼容性

**原则:**
- 参数变更必须向后兼容
- 新增参数必须提供默认值
- 不得删除已有参数
- 不得改变已有参数的类型

#### 兼容性示例

**✅ 正确(向后兼容):**
```json
// v1.0
{
  "parameters": {
    "properties": {
      "location": { "type": "string" }
    }
  }
}

// v2.0(向后兼容)
{
  "parameters": {
    "properties": {
      "location": { "type": "string" },  // 保留原参数
      "unit": { "type": "string", "default": "celsius" }  // 新增参数带默认值
    }
  }
}
```

**❌ 错误(不兼容):**
```json
// v1.0
{
  "parameters": {
    "properties": {
      "location": { "type": "string" }
    }
  }
}

// v2.0(不兼容)
{
  "parameters": {
    "properties": {
      "city": { "type": "string" }  // 重命名参数
    }
  }
}
```

### 版本迁移

当必须进行不兼容变更时,提供迁移指南。

#### 迁移指南模板

```markdown
## 从 v1.0 迁移到 v2.0

### 变更内容

1. **参数重命名**:`location` → `city`
2. **新增参数**:`country`(必需)
3. **返回字段变更**:`temp` → `temperature`

### 迁移步骤

1. 更新参数名称:
   ```python
   # 旧版本
   params = {"location": "Beijing"}
   
   # 新版本
   params = {"city": "Beijing", "country": "China"}
   ```

2. 更新返回值处理:
   ```python
   # 旧版本
   temp = result["data"]["temp"]
   
   # 新版本
   temperature = result["data"]["temperature"]
   ```

### 兼容性检查

使用迁移检查工具验证:
```bash
python migration_check.py --tool get_weather --from 1.0 --to 2.0
```
```

---

## 上下文管理

### Token 消耗预估

工具定义中应包含预估的 Token 消耗,帮助 Agent 规划上下文窗口。

#### 预估字段

```json
{
  "name": "search_documents",
  "version": "1.0.0",
  "estimated_tokens": {
    "input": 50,
    "output": {
      "min": 200,
      "max": 2000,
      "typical": 500
    }
  }
}
```

#### Token 预估规则

| 数据类型 | 预估规则 |
|---------|---------|
| 纯文本 | 字符数 ÷ 4 |
| JSON | 字符数 ÷ 3.5 |
| 代码 | 字符数 ÷ 2 |
| Markdown | 字符数 ÷ 3.5 |

### 缓存策略

对于幂等性工具,支持结果缓存以减少重复调用。

#### 缓存配置

```json
{
  "name": "get_weather",
  "version": "1.0.0",
  "cacheable": true,
  "cache_ttl": 600,  // 缓存 10 分钟
  "cache_key_params": ["location", "unit"]  // 参与缓存键的参数
}
```

#### 缓存响应

```json
{
  "success": true,
  "status": "success",
  "data": {
    "temperature": 25,
    "condition": "sunny"
  },
  "metadata": {
    "tool_name": "get_weather",
    "execution_time_ms": 0,
    "timestamp": "2024-01-01T00:00:00Z",
    "trace_id": "trace_abc123",
    "cache": {
      "hit": true,
      "cached_at": "2024-01-01T00:00:00Z",
      "ttl_remaining": 300
    }
  }
}
```

#### 缓存实现示例

```python
from functools import lru_cache
import hashlib

def get_cache_key(tool_name: str, params: dict, key_params: list) -> str:
    """生成缓存键"""
    filtered_params = {k: v for k, v in params.items() if k in key_params}
    params_str = json.dumps(filtered_params, sort_keys=True)
    return hashlib.md5(f"{tool_name}:{params_str}".encode()).hexdigest()

class CachedToolExecutor:
    def __init__(self, ttl: int = 600):
        self.ttl = ttl
        self.cache = {}
    
    def execute(self, tool_name: str, params: dict, tool_config: dict) -> dict:
        """执行工具(带缓存)"""
        if not tool_config.get('cacheable'):
            return execute_tool(tool_name, params)
        
        cache_key = get_cache_key(
            tool_name,
            params,
            tool_config.get('cache_key_params', list(params.keys()))
        )
        
        # 检查缓存
        if cache_key in self.cache:
            cached_data, cached_time = self.cache[cache_key]
            if time.time() - cached_time < self.ttl:
                result = cached_data.copy()
                result['metadata']['cache'] = {
                    'hit': True,
                    'cached_at': datetime.fromtimestamp(cached_time).isoformat(),
                    'ttl_remaining': self.ttl - (time.time() - cached_time)
                }
                return result
        
        # 执行工具
        result = execute_tool(tool_name, params)
        
        # 缓存结果
        self.cache[cache_key] = (result, time.time())
        
        return result
```

---

## 行业标准参考

### 主流规范对比(2026 年)

| 规范 | 主导方 | 核心特点 | 适用场景 | 采用率 |
|------|--------|----------|----------|--------|
| **OpenAI Function Calling** | OpenAI | JSON Schema + `strict` 模式 + 并行调用 | GPT 系列应用、兼容生态 | ⭐⭐⭐⭐⭐ |
| **Anthropic Tool Use** | Anthropic | `input_schema` + Client/Server Tools 分离 | Claude 应用、企业 Agent | ⭐⭐⭐⭐⭐ |
| **MCP (Model Context Protocol)** | Anthropic + 社区 | 开放协议 + 动态工具发现 + 解耦架构 | 跨平台 Agent、企业集成 | ⭐⭐⭐⭐ 📈 |

### OpenAI Function Calling(最成熟)

```json
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get weather by location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "City, Country" }
      },
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }
}
```

**关键特性:**
- ✅ `strict: true` + `additionalProperties: false` = 100% schema 合规
- ✅ `parallel_tool_calls: false` 控制并发
- ✅ `tool_choice` 支持 `auto`/`required`/`{"name":"xxx"}` 三级控制

### Anthropic Tool Use(最灵活)

```json
{
  "name": "get_weather",
  "description": "Get weather by location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" }
    },
    "required": ["location"]
  },
  "strict": true
}
```

**独特优势:**
- 🔹 **Client Tools**:自定义逻辑,模型返回 `tool_use` 后由应用执行
- 🔹 **Server Tools**:平台内置(如 `web_search_20250305`),无需实现
- 🔹 **MCP 原生兼容**:`inputSchema` → `input_schema` 一键转换

### MCP Protocol(增长最快 🚀)

```typescript
// MCP Server 工具定义(标准接口)
interface ToolDefinition {
  name: string;
  description?: string;
  inputSchema: Record<string, unknown>;
  annotations?: {
    title?: string;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
  };
}

// 客户端动态发现工具
{
  "method": "tools/list",
  "params": {}
}
// → 返回工具列表,支持热更新
```

**为什么 MCP 在爆发:**
| 优势 | 说明 |
|------|------|
| 🔌 **USB-C for AI** | 统一协议连接任意数据源/工具,无需重复开发 |
| 🔁 **动态注册** | 工具变更无需重启 Agent,支持企业级热部署 |
| 🔐 **权限隔离** | MCP Server 可独立控制访问权限,模型不直接接触敏感数据 |
| 🌐 **生态互通** | Claude、ChatGPT、开源模型均可通过 MCP Client 调用同一套工具 |

> 💡 截至 2026 Q1,MCP 已有 200+ 官方/社区 Server(Notion、Google Calendar、PostgreSQL、Figma 等)

---

## 最佳实践

### 1. Strict Mode 成为生产环境标配

```json
{
  "strict": true,
  "parameters": {
    "additionalProperties": false
  }
}
```

**原因:**
- 2026 年所有主流平台均推荐开启
- Schema 校验从"可选"变"必需"
- 防止模型产生幻觉参数

### 2. 参数校验最佳实践

```python
def validate_parameters(tool_name: str, params: dict, schema: dict) -> tuple[bool, str]:
    """
    参数校验最佳实践
    
    返回:
        (is_valid, error_message)
    """
    try:
        # 1. 检查必需参数
        required = schema.get('required', [])
        for param in required:
            if param not in params:
                return False, f"Missing required parameter: {param}"
        
        # 2. 检查参数类型
        properties = schema.get('properties', {})
        for param_name, param_value in params.items():
            if param_name in properties:
                param_schema = properties[param_name]
                expected_type = param_schema.get('type')
                
                # 类型校验
                if expected_type == 'string' and not isinstance(param_value, str):
                    return False, f"Parameter '{param_name}' must be string"
                elif expected_type == 'integer' and not isinstance(param_value, int):
                    return False, f"Parameter '{param_name}' must be integer"
                elif expected_type == 'number' and not isinstance(param_value, (int, float)):
                    return False, f"Parameter '{param_name}' must be number"
                
                # 枚举值校验
                if 'enum' in param_schema and param_value not in param_schema['enum']:
                    return False, f"Parameter '{param_name}' must be one of {param_schema['enum']}"
        
        # 3. 检查额外参数(if strict mode)
        if schema.get('strict') and schema.get('parameters', {}).get('additionalProperties', False) is False:
            for param_name in params:
                if param_name not in properties:
                    return False, f"Unexpected parameter: {param_name}"
        
        return True, ""
    
    except Exception as e:
        return False, f"Validation error: {str(e)}"
```

### 3. 错误处理最佳实践

```python
def call_tool_with_retry(tool_name: str, params: dict, max_retries: int = 3) -> dict:
    """
    带重试的工具调用
    
    重试策略:
    - 网络错误:最多重试 3 次
    - 超时错误:最多重试 2 次
    - 参数错误:不重试
    - 权限错误:不重试
    """
    retry_count = 0
    last_error = None
    
    while retry_count < max_retries:
        try:
            result = execute_tool(tool_name, params)
            
            # 检查是否需要重试
            if not result['success']:
                error_code = result.get('error', {}).get('code')
                
                # 参数错误和权限错误不重试
                if error_code in ['INVALID_PARAMS', 'PERMISSION_DENIED']:
                    return result
                
                # 超时错误最多重试 2 次
                if error_code == 'TIMEOUT' and retry_count >= 2:
                    return result
                
                # 其他错误继续重试
                last_error = result
                retry_count += 1
                time.sleep(2 ** retry_count)  # 指数退避
                continue
            
            return result
        
        except requests.exceptions.RequestException as e:
            # 网络错误重试
            last_error = {
                "success": False,
                "status": "error",
                "error": {
                    "code": "NETWORK_ERROR",
                    "message": str(e)
                }
            }
            retry_count += 1
            time.sleep(2 ** retry_count)
            continue
        
        except Exception as e:
            # 其他错误不重试
            return {
                "success": False,
                "status": "error",
                "error": {
                    "code": "UNKNOWN_ERROR",
                    "message": str(e)
                }
            }
    
    # 重试次数用尽
    return last_error
```

### 4. 动态工具发现(MCP 模式)

```python
class MCPToolRegistry:
    """MCP 工具注册表"""
    
    def __init__(self):
        self.tools = {}
        self.servers = {}
    
    async def register_server(self, server_url: str):
        """注册 MCP Server"""
        # 连接服务器
        response = await requests.post(
            f"{server_url}/tools/list",
            json={}
        )
        
        # 注册工具
        for tool in response.json()['tools']:
            self.tools[tool['name']] = tool
            self.servers[tool['name']] = server_url
    
    async def call_tool(self, tool_name: str, params: dict) -> dict:
        """调用 MCP 工具"""
        if tool_name not in self.tools:
            return {
                "success": False,
                "error": {
                    "code": "TOOL_NOT_FOUND",
                    "message": f"Tool '{tool_name}' not found"
                }
            }
        
        server_url = self.servers[tool_name]
        
        response = await requests.post(
            f"{server_url}/tools/call",
            json={
                "name": tool_name,
                "arguments": params
            }
        )
        
        return response.json()
```

### 5. 流式响应最佳实践

```python
async def execute_tool_with_streaming(tool_name: str, params: dict) -> AsyncGenerator:
    """
    执行工具并流式返回进度
    
    使用场景:长时间运行的工具(>1s)
    """
    # 生成 trace_id
    trace_id = generate_trace_id()
    
    # 推送开始事件
    yield {
        "event": "tool_progress",
        "id": f"evt_{trace_id}_start",
        "data": {
            "progress": 0,
            "message": f"开始执行工具: {tool_name}",
            "metadata": {
                "tool_name": tool_name,
                "timestamp": datetime.now().isoformat(),
                "trace_id": trace_id
            }
        }
    }
    
    try:
        # 执行工具(模拟进度)
        result = await _execute_with_progress(tool_name, params, trace_id, lambda p, m: {
            "event": "tool_progress",
            "id": f"evt_{trace_id}_progress_{p}",
            "data": {
                "progress": p,
                "message": m,
                "metadata": {
                    "tool_name": tool_name,
                    "timestamp": datetime.now().isoformat(),
                    "trace_id": trace_id
                }
            }
        })
        
        # 推送成功结果
        yield {
            "event": "tool_result",
            "id": f"evt_{trace_id}_result",
            "data": {
                "success": True,
                "status": "success",
                "data": result,
                "metadata": {
                    "tool_name": tool_name,
                    "timestamp": datetime.now().isoformat(),
                    "trace_id": trace_id
                }
            }
        }
    
    except Exception as error:
        # 推送错误事件
        yield {
            "event": "tool_error",
            "id": f"evt_{trace_id}_error",
            "data": {
                "success": False,
                "status": "error",
                "error": {
                    "code": "EXECUTION_ERROR",
                    "message": str(error)
                },
                "metadata": {
                    "tool_name": tool_name,
                    "timestamp": datetime.now().isoformat(),
                    "trace_id": trace_id
                }
            }
        }
```

### 6. 分页处理最佳实践

```python
async def fetch_all_pages(tool_name: str, params: dict, max_items: int = 1000) -> list:
    """
    获取所有分页数据
    
    参数:
        tool_name: 工具名称
        params: 工具参数
        max_items: 最大获取数量(防止无限循环)
    
    返回:
        所有项目的列表
    """
    all_items = []
    cursor = None
    fetched_count = 0
    
    while cursor is not None and fetched_count < max_items:
        # 调用工具
        result = await call_tool(tool_name, {
            **params,
            "cursor": cursor,
            "limit": 100
        })
        
        if not result['success']:
            raise Exception(f"Tool error: {result['error']}")
        
        # 添加项目
        items = result['data']['items']
        all_items.extend(items)
        fetched_count += len(items)
        
        # 检查是否还有更多
        pagination = result['data']['pagination']
        if pagination['has_more']:
            cursor = pagination['next_cursor']
        else:
            cursor = None
    
    return all_items
```

### 7. 可观测性最佳实践

```python
import logging

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('tool_executor')

def execute_tool_with_observability(tool_name: str, params: dict) -> dict:
    """
    执行工具并记录完整可观测性数据
    """
    # 生成 trace_id
    trace_id = generate_trace_id()
    
    # 记录开始
    start_time = time.time()
    logger.info(f"Tool started: {tool_name}", extra={
        "trace_id": trace_id,
        "tool_name": tool_name,
        "params": params
    })
    
    try:
        # 执行工具
        result = execute_tool(tool_name, params)
        
        # 记录成功
        execution_time = (time.time() - start_time) * 1000
        logger.info(f"Tool completed: {tool_name}", extra={
            "trace_id": trace_id,
            "tool_name": tool_name,
            "execution_time_ms": execution_time,
            "success": result['success']
        })
        
        # 添加性能数据
        result['metadata']['performance'] = {
            'total_ms': execution_time
        }
        
        return result
    
    except Exception as error:
        # 记录错误
        execution_time = (time.time() - start_time) * 1000
        logger.error(f"Tool failed: {tool_name}", extra={
            "trace_id": trace_id,
            "tool_name": tool_name,
            "execution_time_ms": execution_time,
            "error": str(error)
        }, exc_info=True)
        
        raise
```

---

## 选型建议

### 场景匹配

```mermaid
graph LR
    A[你的需求] --> B{目标模型?}
    B -->|GPT 系列| C[OpenAI Function Calling]
    B -->|Claude 系列| D[Anthropic Tool Use + MCP]
    B -->|多模型/开源| E[MCP 或自定义]
    
    A --> F{工具复杂度?}
    F -->|简单 API 调用| C
    F -->|动态工具/企业集成| E[MCP]
    F -->|RAG+ 工具| G[自定义集成]
    
    A --> H{开发语言?}
    H -->|Python| I[Python SDK]
    H -->|.NET| J[.NET SDK]
    H -->|任意| K[MCP + 自定义 Client]
```

### 技术选型决策树

| 决策因素 | OpenAI | Anthropic | MCP | 自定义 |
|---------|--------|-----------|-----|--------|
| 易用性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| 灵活性 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 生态支持 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐ |
| 学习成本 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| 跨平台能力 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

---

## 趋势与展望

### 2026 年趋势

1. **Strict Mode 成为标配**
   - 所有主流平台默认开启
   - Schema 校验从"可选"变"必需"

2. **MCP 协议爆发**
   - 生态快速增长(200+ Server)
   - 成为跨平台工具互操作标准

3. **流式响应普及**
   - 长时间工具支持进度推送
   - SSE 成为标准实现方式

4. **可观测性增强**
   - Trace ID 全链路追踪
   - 性能监控成为标配

5. **AI 驱动的工具发现**
   - 自动分析数据源并生成工具定义
   - 智能推荐工具组合

### 未来展望

**2027 年:**
- 工具调用协议标准化(类似 HTTP/HTTPS)
- 跨模型的工具 marketplace
- AI 驱动的自动工具优化

**2028 年:**
- 工具自描述能力(自动生成文档、测试)
- 工具性能自动优化
- 分布式工具调用网络

---

## 在感知节点中的应用

感知节点是 AGI 进化模型的核心组件,负责工具调用和外部交互。

### 感知节点架构

```
┌─────────────────────────────────────┐
│         感知节点 (Perception Node)     │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────────┐  ┌─────────────┐ │
│  │ 工具注册表    │  │ 工具执行器   │ │
│  │ (Registry)   │  │ (Executor)  │ │
│  └──────┬───────┘  └──────┬──────┘ │
│         │                 │        │
│         └────────┬────────┘        │
│                  ▼                 │
│  ┌──────────────────────────────┐ │
│  │  统一接口层 (Tool Interface)   │ │
│  │  - 参数校验                   │ │
│  │  - 错误处理                   │ │
│  │  - 重试策略                   │ │
│  │  - 流式响应                   │ │
│  │  - 可观测性                   │ │
│  └──────────────────────────────┘ │
│                  │                 │
│                  ▼                 │
│  ┌──────────────────────────────┐ │
│  │   外部工具 (External Tools)    │ │
│  │   - API 调用                  │ │
│  │   - 数据库查询                │ │
│  │   - 文件操作                  │ │
│  │   - MCP Server                │ │
│  └──────────────────────────────┘ │
│                                     │
└─────────────────────────────────────┘
```

### 感知节点工具定义示例

```python
# 感知节点工具注册
PERCEPTION_NODE_TOOLS = [
    {
        "name": "get_weather",
        "description": "获取指定城市的实时天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称,如 'Beijing' 或 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位"
                }
            },
            "required": ["location"],
            "additionalProperties": false
        },
        "strict": true,
        "version": "1.0.0",
        "cacheable": True,
        "cache_ttl": 600,
        "estimated_tokens": {
            "input": 50,
            "output": {"typical": 100, "max": 200}
        }
    },
    {
        "name": "search_documents",
        "description": "搜索文档数据库",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "搜索关键词"
                },
                "limit": {
                    "type": "integer",
                    "description": "返回结果数量",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 10
                },
                "cursor": {
                    "type": "string",
                    "description": "分页游标"
                }
            },
            "required": ["query"],
            "additionalProperties": false
        },
        "strict": True,
        "version": "2.1.0",
        "estimated_tokens": {
            "input": 100,
            "output": {"min": 200, "max": 5000, "typical": 1000}
        }
    },
    {
        "name": "generate_report",
        "description": "生成 PDF 报告并返回下载链接",
        "parameters": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "报告标题"
                },
                "content": {
                    "type": "string",
                    "description": "报告内容(Markdown 格式)"
                },
                "format": {
                    "type": "string",
                    "enum": ["pdf", "docx", "html"],
                    "description": "输出格式",
                    "default": "pdf"
                }
            },
            "required": ["title", "content"],
            "additionalProperties": False
        },
        "strict": True,
        "version": "1.2.0",
        "streaming": True,  # 支持流式响应
        "estimated_tokens": {
            "input": 500,
            "output": {"min": 50, "max": 100, "typical": 50}
        }
    }
]
```

### 感知节点工具调用流程

```python
class PerceptionNode:
    """感知节点 - 工具调用统一入口"""
    
    def __init__(self):
        self.registry = ToolRegistry()
        self.executor = ToolExecutor()
        self.cache = ToolCache()
        self.observability = ObservabilityManager()
    
    async def call_tool(self, tool_name: str, params: dict, **options) -> dict:
        """
        调用工具(统一入口)
        
        参数:
            tool_name: 工具名称
            params: 工具参数
            options: 可选参数
                - enable_cache: 是否启用缓存(默认 True)
                - enable_streaming: 是否启用流式响应(默认 True)
                - enable_retry: 是否启用重试(默认 True)
                - debug: 调试模式(默认 False)
        
        返回:
            工具执行结果
        """
        # 1. 获取工具定义
        tool_config = self.registry.get_tool(tool_name)
        if not tool_config:
            return {
                "success": False,
                "status": "error",
                "error": {
                    "code": "TOOL_NOT_FOUND",
                    "message": f"Tool '{tool_name}' not found"
                }
            }
        
        # 2. 生成 trace_id
        trace_id = self.observability.generate_trace_id()
        
        # 3. 参数校验
        is_valid, error_msg = validate_parameters(tool_name, params, tool_config)
        if not is_valid:
            return {
                "success": False,
                "status": "error",
                "error": {
                    "code": "INVALID_PARAMS",
                    "message": error_msg
                },
                "metadata": {
                    "tool_name": tool_name,
                    "timestamp": datetime.now().isoformat(),
                    "trace_id": trace_id
                }
            }
        
        # 4. 检查缓存
        if options.get('enable_cache', True) and tool_config.get('cacheable'):
            cached_result = self.cache.get(tool_name, params, tool_config)
            if cached_result:
                return cached_result
        
        # 5. 执行工具
        start_time = time.time()
        
        try:
            if options.get('enable_streaming', True) and tool_config.get('streaming'):
                # 流式响应
                result_stream = await self.executor.execute_with_streaming(
                    tool_name,
                    params,
                    tool_config,
                    trace_id
                )
                
                # 返回流(异步生成器)
                return result_stream
            
            else:
                # 普通响应
                if options.get('enable_retry', True):
                    result = await self.executor.execute_with_retry(
                        tool_name,
                        params,
                        tool_config,
                        trace_id
                    )
                else:
                    result = await self.executor.execute(
                        tool_name,
                        params,
                        tool_config,
                        trace_id
                    )
                
                # 添加性能数据
                execution_time = (time.time() - start_time) * 1000
                result['metadata']['performance'] = {
                    'total_ms': execution_time
                }
                
                # 缓存结果
                if options.get('enable_cache', True) and tool_config.get('cacheable'):
                    self.cache.set(tool_name, params, result, tool_config)
                
                # 调试信息
                if options.get('debug', False):
                    result['debug_info'] = {
                        'cache_hit': False,
                        'retry_count': 0,
                        'execution_time_ms': execution_time
                    }
                
                return result
        
        except Exception as error:
            # 错误处理
            execution_time = (time.time() - start_time) * 1000
            error_result = {
                "success": False,
                "status": "error",
                "error": {
                    "code": "EXECUTION_ERROR",
                    "message": str(error)
                },
                "metadata": {
                    "tool_name": tool_name,
                    "execution_time_ms": execution_time,
                    "timestamp": datetime.now().isoformat(),
                    "trace_id": trace_id
                }
            }
            
            # 记录错误
            self.observability.log_error(trace_id, tool_name, error)
            
            return error_result
```

### 感知节点与元认知检测模块的集成

```python
class PerceptionNodeWithMetacognition(PerceptionNode):
    """带元认知检测的感知节点"""
    
    def __init__(self, metacognition_checker):
        super().__init__()
        self.metacognition_checker = metacognition_checker
    
    async def call_tool_with_metacognition(
        self,
        tool_name: str,
        params: dict,
        personality: dict = None,
        **options
    ) -> dict:
        """
        调用工具并进行元认知检测
        
        参数:
            tool_name: 工具名称
            params: 工具参数
            personality: 人格参数(用于客观性评估)
            options: 可选参数
        
        返回:
            工具执行结果(包含元认知检测结果)
        """
        # 1. 调用工具
        result = await self.call_tool(tool_name, params, **options)
        
        # 2. 元认知检测
        if result.get('success'):
            metacognition_result = await self.metacognition_checker.evaluate(
                response=result['data'],
                query=params.get('query', ''),
                personality=personality
            )
            
            # 3. 如果检测到问题,触发纠错
            if metacognition_result['needs_correction']:
                correction = await self.metacognition_checker.suggest_correction(
                    metacognition_result,
                    personality
                )
                
                result['metadata']['metacognition'] = {
                    'checked': True,
                    'needs_correction': True,
                    'correction': correction
                }
            else:
                result['metadata']['metacognition'] = {
                    'checked': True,
                    'needs_correction': False
                }
        
        return result
```

---

## 附录

### A. 完整错误码列表

| 错误码 | 说明 | HTTP 状态码 | 可重试 |
|--------|------|------------|--------|
| INVALID_PARAMS | 参数验证失败 | 400 | 否 |
| TOOL_NOT_FOUND | 工具不存在 | 404 | 否 |
| RESOURCE_NOT_FOUND | 资源不存在 | 404 | 否 |
| PERMISSION_DENIED | 权限不足 | 403 | 否 |
| UNAUTHORIZED | 未授权 | 401 | 否 |
| TIMEOUT | 执行超时 | 504 | 是 |
| RATE_LIMITED | 速率限制 | 429 | 是 |
| NETWORK_ERROR | 网络错误 | 503 | 是 |
| EXECUTION_ERROR | 执行错误 | 500 | 否 |
| TOOL_DEPRECATED | 工具已废弃 | 410 | 否 |
| QUOTA_EXCEEDED | 配额超限 | 429 | 否 |

### B. 工具定义模板

```json
{
  "name": "tool_name",
  "description": "Tool description in one sentence",
  "parameters": {
    "type": "object",
    "properties": {
      "param_name": {
        "type": "string|number|integer|boolean|array|object",
        "description": "Parameter description",
        "enum": ["option1", "option2"],
        "default": "default_value",
        "minimum": 0,
        "maximum": 100
      }
    },
    "required": ["param_name"],
    "additionalProperties": false
  },
  "strict": true,
  "version": "1.0.0",
  "cacheable": true,
  "cache_ttl": 600,
  "cache_key_params": ["param_name"],
  "streaming": false,
  "estimated_tokens": {
    "input": 100,
    "output": {
      "min": 200,
      "max": 2000,
      "typical": 500
    }
  },
  "deprecated": false,
  "sunset_date": "2026-12-31",
  "replacement": "new_tool_name"
}
```

### C. 参考资源

- [OpenAI Function Calling 官方文档](https://platform.openai.com/docs/guides/function-calling)
- [Anthropic Tool Use 官方文档](https://docs.anthropic.com/en/docs/tool-use)
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [JSON Schema 规范](https://json-schema.org/)
- [SSE (Server-Sent Events) 规范](https://html.spec.whatwg.org/multipage/server-sent-events.html)

---

## 总结

本规范涵盖了 Tool Use 接口设计的所有关键方面:

✅ **标准化**:统一的工具定义、响应格式、错误处理
✅ **可靠性**:参数校验、重试策略、幂等性设计
✅ **可扩展**:MCP 协议、动态工具发现、版本管理
✅ **兼容性**:兼容 OpenAI、Anthropic 等主流平台
✅ **可观测**:Trace ID、流式响应、性能监控
✅ **企业级**:分页、缓存、文件处理、版本控制

通过遵循本规范,可以构建出高质量、可维护、可扩展的工具调用系统。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall