TickDB SKILL 协议详解：如何让 AI 助手理解你的行情查询

"工具的定义，决定了 AI 能做什么。"

你用过 AI 助手查询股票价格吗？问一句"苹果现在多少钱"，AI 直接返回了答案——但这个过程发生了什么？

大多数用户不会去想。但作为技术人，你一定好奇过：AI 怎么知道该调用哪个接口？怎么理解"现在"对应的是实时价格而不是收盘价？怎么知道"苹果"的代码是 AAPL.US？

答案藏在一个不起眼的文件里：skill.md。

这不是什么神秘协议，也不是 AI 公司闭门造车的产物。它是一套让 AI 理解"自己能做什么、怎么做"的公开规范。而理解这套规范，你就能让任何 AI 助手精准操控你的行情数据。

本文拆解 skill.md 的设计逻辑、Function Calling 的定义方式，以及 AI 解析它的完整流程。

一、为什么 AI 听不懂你的行情需求

在理解 SKILL 协议之前，先看看问题出在哪里。

1.1 自然语言的歧义陷阱

人类说"查一下苹果"，AI 可能理解成：

苹果公司股票（AAPL.US）
苹果期货（AP.OANDA）
苹果汁期货（OJ.FUTURES）
苹果种植产业链相关公司

这种歧义在通用对话中无伤大雅，但在金融场景里，歧义等于错误。一次误调用可能让量化策略用错数据基准，后果不堪设想。

1.2 参数格式的鸿沟

用户说"我要最近一个月的日线数据"，AI 需要理解：

时间范围：最近一个月 → 具体起止日期
数据粒度：日线 → interval: "1d"
标的：未明确 → 需要追问或推断

如果 AI 不知道 tickdb.ai 支持哪些标的、哪些时间粒度，它只能瞎猜。

1.3 认证信息的黑箱

AI 无法凭空知道你的 API Key 存在哪里、以什么格式传递。如果每次对话都要手动复制粘贴凭证，AI 助手的价值大打折扣。

这三个问题的解法，是一个结构化的"能力清单"——让 AI 在对话前就明确知道：它有哪些工具可用、每个工具接受什么参数、返回什么格式。

这就是 skill.md 的职责。

二、skill.md 是什么

skill.md 是 TickDB 提供的 SKILL 协议实现文件，位于 https://tickdb.ai/skill.md。

你可以把它理解成 AI 助手的"工具说明书"。当 AI 加载这个文件，它就获得了调用 TickDB 行情 API 的完整能力描述：

有哪些函数可以调用
每个函数接受什么参数
返回的数据是什么结构
认证信息如何传递
API 基础地址是什么

这与 OpenAI 的 Function Calling 规范高度兼容，但做了额外的金融场景适配。

2.1 协议设计理念

SKILL 协议遵循三个核心原则：

原则	含义	实现方式
声明式	只描述"能做什么"，不规定"怎么做"	YAML 格式的函数定义
自包含	AI 加载后无需额外上下文	包含 API 地址、认证方式
金融级	适应行情数据的特殊语义	标的符号规范、时间粒度枚举

2.2 文件位置与加载方式

https://tickdb.ai/skill.md

AI 助手的 ClawHub 平台在安装 TickDB SKILL 时，会自动拉取这个文件并解析。加载成功后，AI 就具备了调用 TickDB API 的完整能力。

三、协议规范详解

3.1 文件结构概览

一个完整的 skill.md 文件包含以下顶级字段：

version: "1.0"
description: "TickDB Market Data API"
api_base: "https://api.tickdb.ai/v1"
auth:
  type: "header"
  key: "X-API-Key"
functions:
  - name: "get_kline"
    description: "获取K线历史数据"
    parameters: {...}
    returns: {...}
  - name: "get_realtime"
    description: "获取实时行情"
    parameters: {...}
    returns: {...}

逐层拆解。

3.2 version：版本号

version: "1.0"

SKILL 协议的版本标识。AI 根据版本号决定解析方式。1.0 是当前稳定版本，兼容 ClawHub 平台的所有主流 AI 助手。

3.3 description：能力描述

description: "TickDB Market Data API - 美股、港股、数字货币、外汇、贵金属、指数的实时行情与历史K线数据"

这是 AI 看到的第一句话，决定了它对整个 SKILL 的第一印象。好的描述应该包含：

数据类型（实时、历史）
覆盖的资产类别
核心能力

3.4 auth：认证配置

auth:
  type: "header"
  key: "X-API-Key"

认证配置告诉 AI 如何携带凭证：

字段	可选值	说明
`type`	`header` / `query` / `bearer`	凭证传递方式
`key`	字符串	Header 参数名或 Query 参数名

对于 TickDB，API Key 通过 HTTP Header 的 X-API-Key 字段传递。AI 在构造请求时，会自动从用户环境变量或配置中读取 Key 并注入。

3.5 functions：函数定义列表

这是协议的核心。每个函数是一个独立的能力单元。

四、Function Calling 的定义方式

4.1 单个函数的完整结构

functions:
  - name: "get_kline"
    description: "获取指定交易品种的K线历史数据"
    category: "market_data"
    parameters:
      type: "object"
      properties:
        symbol:
          type: "string"
          description: "交易品种代码，如 AAPL.US、TSLA.US、BTC.USDT"
          examples: ["AAPL.US", "BTC.USDT"]
        interval:
          type: "string"
          description: "K线周期"
          enum: ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]
          examples: ["1h", "1d"]
        start_time:
          type: "integer"
          description: "开始时间戳（毫秒）"
        end_time:
          type: "integer"
          description: "结束时间戳（毫秒）"
        limit:
          type: "integer"
          description: "返回数据条数，最大1000"
          default: 100
      required: ["symbol", "interval"]
    returns:
      type: "object"
      properties:
        code:
          type: "integer"
          description: "响应码，0表示成功"
        data:
          type: "array"
          description: "K线数据数组，每项包含时间、开盘、收盘、最高、最低、成交量"

逐字段解读。

4.2 name：函数名

函数名是 AI 调用时的唯一标识符。命名规范：

全小写 + 下划线分隔（遵循 Python 习惯）
动词优先，体现操作语义
避免与通用词汇冲突

TickDB 常用的函数命名：

函数名	功能
`get_kline`	获取 K 线历史数据
`get_realtime`	获取实时行情
`get_depth`	获取订单簿深度
`get_symbols`	获取可用交易品种列表
`subscribe_depth`	订阅订单簿实时推送（WebSocket）

4.3 description：功能描述

描述是 AI 理解函数用途的关键入口。好的描述应该：

说明函数能做什么（而非怎么做）
包含领域术语，增强专业性
标注重要边界条件

# 不好的描述
description: "获取K线数据"

# 好的描述
description: "获取指定交易品种的K线历史数据，支持1分钟到1周的周期。适用于策略回测和技术分析。注意：返回的是已结束周期的K线数据，实时行情请使用 get_realtime"

4.4 category：能力分类

category: "market_data"

分类帮助 AI 在多函数场景下快速筛选。TickDB 的函数分类：

分类	包含函数	AI 使用建议
`market_data`	get_kline, get_realtime, get_depth	数据查询类
`market_scan`	get_symbols, search_symbols	标的发现类
`websocket`	subscribe_depth, subscribe_trade	实时推送类

4.5 parameters：参数规范

parameters 遵循 JSON Schema 规范，这是 AI 领域的事实标准。

必填参数 vs 可选参数

required: ["symbol", "interval"]

required 数组列出必填参数。AI 在调用前必须确保这些参数有值，否则会向用户追问。

参数类型与枚举

interval:
  type: "string"
  enum: ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]

enum 约束参数的可选值。AI 看到这个约束，就知道用户说"周线"应该映射到 "1w" 而非 "7d"。

示例值引导

symbol:
  type: "string"
  description: "交易品种代码"
  examples: ["AAPL.US", "TSLA.US", "BTC.USDT"]

examples 字段给出典型值。当用户说"帮我查苹果"时，AI 有参考上下文知道应该用 AAPL.US。

参数描述的陷阱

# 容易产生歧义的描述
symbol:
  type: "string"
  description: "股票代码"

# 金融场景友好的描述
symbol:
  type: "string"
  description: "交易品种代码，格式为 代码.交易所。如 AAPL.US（苹果，美股）、0700.HK（腾讯，港股）、BTC.USDT（比特币，币安）"

金融场景中，标的符号有严格规范。描述必须包含格式说明和典型示例。

4.6 returns：返回值规范

returns:
  type: "object"
  properties:
    code:
      type: "integer"
      description: "响应状态码，0表示成功，非0表示异常"
    data:
      type: "array"
      description: "业务数据载荷"
    message:
      type: "string"
      description: "错误信息，当 code 非0时返回"

返回值规范帮助 AI 正确解析响应：

判断请求是否成功（检查 code）
提取业务数据（从 data 字段）
处理异常情况（读取 message）

五、AI 如何解析 skill.md

加载 skill.md 只是第一步。AI 需要经历完整的解析、理解、决策流程，才能正确响应用户的行情查询。

5.1 解析流程图

用户输入 → 意图识别 → 函数匹配 → 参数提取 → 请求构造 → API调用 → 响应解析 → 结果呈现

5.2 第一步：意图识别

当用户说"我想看看英伟达最近一周的走势"，AI 需要判断：

用户想要的是什么类型的数据？
这个需求是否能被当前 SKILL 满足？

# AI 内部判断逻辑（简化）
user_intent = "查看英伟达股票近期走势"
matched_categories = ["market_data"]
confidence = 0.92  # 高置信度匹配

识别结果：用户需要市场数据，置信度 92%。进入下一步。

5.3 第二步：函数匹配

AI 从 functions 列表中筛选候选函数：

函数	匹配度	原因
`get_kline`	92%	提供历史K线，匹配"走势"语义
`get_realtime`	35%	实时价格，"走势"语义弱
`get_depth`	10%	订单簿数据，语义不相关

选择 get_kline。

5.4 第三步：参数提取与补全

AI 解析用户输入，映射到函数参数：

参数	用户输入	AI 解析结果
`symbol`	"英伟达"	"NVDA.US"
`interval`	"走势"（隐含）	"1d"（日线）
`start_time`	"最近一周"	当前时间戳 - 7天
`end_time`	"最近一周"	当前时间戳
`limit`	未提及	默认 100

关键问题：AI 如何知道"英伟达"对应 "NVDA.US"？

答案是 examples 字段的隐式学习。AI 见过 AAPL.US（苹果）的例子，学会了"公司名 → 股票代码"的映射模式。当遇到新公司时，它会调用 search_symbols 函数做标的搜索，而不是瞎猜。

5.5 第四步：请求构造

AI 根据 auth 配置构造 HTTP 请求：

import os
import requests

# 从环境变量读取 API Key
api_key = os.environ.get("TICKDB_API_KEY")

# 构造请求
response = requests.get(
    "https://api.tickdb.ai/v1/market/kline",
    headers={"X-API-Key": api_key},
    params={
        "symbol": "NVDA.US",
        "interval": "1d",
        "start_time": 1700000000000,  # 示例时间戳
        "end_time": 1700600000000,
        "limit": 100
    },
    timeout=(3.05, 10)
)

注意到 timeout=(3.05, 10) 了吗？这是 AI 自动添加的超时保护。skill.md 规范了请求方式，AI 在实现时会自动应用工程最佳实践。

5.6 第五步：响应解析与结果呈现

AI 解析 get_kline 的返回数据：

{
  "code": 0,
  "data": [
    {
      "time": 1700352000000,
      "open": 495.20,
      "high": 502.30,
      "low": 493.80,
      "close": 500.15,
      "volume": 45230000
    },
    ...
  ]
}

AI 根据 returns 规范理解：

code: 0 → 请求成功
data 数组 → K线数据列表
每项包含时间、OHLC、成交量

最终呈现给用户：

英伟达（NVDA.US）近一周日线走势：

最新收盘价：$500.15

周涨幅：+3.2%

日均成交量：4523万股
（附K线图）

六、实战：完整的 skill.md 示例

以下是 TickDB get_realtime 函数的完整定义，可以作为你理解 SKILL 协议的参考范本：

functions:
  - name: "get_realtime"
    description: "获取交易品种的实时行情数据，包括最新价格、24小时成交量、买卖档位等。适用于需要即时市场报价的场景，如盘中监控、实时告警。"
    category: "market_data"
    parameters:
      type: "object"
      properties:
        symbol:
          type: "string"
          description: "交易品种代码。格式：代码.交易所后缀。常见格式：\n- 美股：XXX.US（如 AAPL.US, TSLA.US）\n- 港股：XXX.HK（如 0700.HK, 9988.HK）\n- 数字货币：XXX.USDT（如 BTC.USDT, ETH.USDT）\n- 外汇：XXX.XXX（如 EUR.USD）\n- 贵金属：XAU.XXX（如 XAU.USD）\n- 指数：XXX.IDX（如 US500.IDX）"
          examples: ["AAPL.US", "BTC.USDT", "EUR.USD", "XAU.USD"]
        include_depth:
          type: "boolean"
          description: "是否包含订单簿深度数据（买卖档位）。默认false。开启后会增加响应大小，建议仅在需要订单簿分析时开启。"
          default: false
      required: ["symbol"]
    returns:
      type: "object"
      description: "实时行情响应"
      properties:
        code:
          type: "integer"
          description: "响应码。0表示成功，非0表示失败。"
          examples: [0, 2002, 3001]
        message:
          type: "string"
          description: "响应消息。成功时为'success'，失败时为错误描述。"
        data:
          type: "object"
          description: "行情数据载体"
          properties:
            symbol:
              type: "string"
              description: "交易品种代码"
            price:
              type: "number"
              description: "最新成交价"
            volume_24h:
              type: "number"
              description: "24小时成交量"
            change_24h:
              type: "number"
              description: "24小时涨跌幅（百分比）"
            bid:
              type: "number"
              description: "买一价（当 include_depth=true 时）"
            ask:
              type: "number"
              description: "卖一价（当 include_depth=true 时）"
            depth:
              type: "array"
              description: "订单簿深度（当 include_depth=true 时），包含买卖各5档数据"

七、多轮对话中的 SKILL 能力

SKILL 协议的另一个价值在于支持多轮对话中的状态保持。

7.1 场景：迭代式行情分析

用户：帮我看看苹果最近一个月走势
AI：查询 AAPL.US 近一个月日线数据，返回K线图和分析

用户：切换成小时线看看
AI：复用 symbol 参数，仅修改 interval 为 "1h"，重新查询

用户：加上微软对比一下
AI：识别这是新标的，加入 MSFT.US，构造多标的数据请求

关键机制：上下文记忆。AI 在多轮对话中会保留：

已识别的用户意图
之前调用的函数和参数
上下文中的标的列表

symbol 参数在第一轮已确认为 AAPL.US，后续对话可以直接复用，无需用户重复指定。

7.2 追问与澄清

当用户输入模糊时，AI 会主动追问：

用户：帮我看看最近的波动情况
AI：您说的"波动情况"可以有两种理解：
1. 查看特定品种的日内波动（需要告诉我哪只股票或数字货币）
2. 查看市场整体波动率指标（如 VIX）

请问您想了解哪种情况？

symbol 在 required 中声明，AI 检测到缺失时会向用户追问，而非硬编码一个默认值。

八、SKILL 协议的技术优势

维度	传统 API 调用	SKILL 协议
认证方式	开发者手动配置	AI 自动读取环境变量
参数映射	开发者硬编码	AI 从自然语言推断
错误处理	代码 if-else	AI 理解错误码后主动告知用户
多轮对话	需要 session 管理	AI 自动维护上下文
标的发现	开发者查文档	AI 调用 search_symbols 自动探索

核心优势：把 API 调用的不确定性降到最低。AI 不再是"能调就调，调错就报错"的工具，而是能理解意图、主动纠错、智能补全的行情助手。

九、结语

skill.md 看起来只是一个 YAML 文件，但它解决了一个根本问题：让 AI 理解它能做什么，以及怎么做。

当你给 AI 装上 TickDB SKILL，它就获得了：

完整的行情数据能力清单
标准化的函数定义和参数规范
自动化的认证和错误处理
多轮对话中的上下文保持

这不是魔法，是协议的力量。

如果你在 ClawHub 平台使用 AI 助手，搜索安装 tickdb-market-data SKILL，即刻拥有这个能力。如果你需要更深度的定制——比如添加私有数据源、修改参数约束、集成内部风控逻辑——可以联系 [email protected] 了解 SKILL 协议的企业级扩展方案。

下一步行动

如果你想在 AI 助手中体验 TickDB：

打开 ClawHub，搜索 tickdb-market-data
一键安装，无需配置（API Key 在首次使用时引导配置）
直接对话："帮我看看英伟达最近一周的走势"

如果你想深入了解 SKILL 协议规范，访问 tickdb.ai/skill.md 查看完整的协议文档。

如果你需要将 TickDB 接入自己的 AI 应用，参考 SKILL 协议实现文档，使用 OpenAI Function Calling 格式对接。

本文基于 TickDB SKILL 协议 v1.0 编写。协议规范可能随产品迭代更新，请以官方文档为准。