AI Skill查不了数据？一篇讲透scripts/CLI/MCP三种接口调用方式

装了个 AI Skill 却查不了数据？一篇讲透 Skill 调用接口的三种方式（scripts / CLI / MCP）

这段时间我陆续试了十几个AI Skill,从Claude Skills到Codex Skills再到各种自建技能包,发现一个特别普遍的现象:很多人装好了Skill,看着SKILL.md里写得头头是道,结果一问它“帮我查下数据库里的订单数”,它要么答非所问,要么直接说“我没有权限访问”。问题从来不在模型本身,而是Skill和外部世界之间根本就没打通。Skill说白了是一份给模型看的使用说明,它本身不联网、不读库、不执行命令,真正要让AI查得到数据,你必须给它配一条能触达外部系统的“通道”。这篇文章就把这条通道彻底讲透:Skill调用接口的主流方式就三种——scripts脚本、CLI命令行、MCP协议,分别适合什么场景、怎么配置、有什么坑,我会按实际操作顺序一个个拆开讲。无论你是在折腾本地文档整理、想接内部数据库,还是准备做一次正经的智能体二次开发,这篇都能给你省下不少弯路。

1. 为什么装了Skill却查不了数据

1.1 Skill不是什么“插件”,而是一份给模型看的说明书

先理清一个最关键的概念。不少人的误区是把Skill当成传统软件里的“插件”或者“数据连接器”,觉得装上去之后AI就能直接操作外部系统了。但实际上,Skill的本质是一段被注入到模型上下文里的结构化文本,通常包含一个SKILL.md主文件,里面写清楚这个技能“什么时候用、怎么用、要用什么参数、最终输出什么格式”,旁边可能还附带一个scripts目录,放着辅助脚本。

模型的执行逻辑是这样的:你提出需求,模型在上下文里看到SKILL.md,知道“有个脚本可以做这件事”,于是尝试构造一个执行指令,由Skill的Runtime或宿主应用去真正启动脚本。模型本身只是一个“发号施令”的大脑,它并不具备直接读取文件、访问数据库的能力,所有数据进出都必须通过宿主环境帮你完成的那一步调用。

这就像你拿到一份米其林菜谱,菜谱写得再详细,锅也不会自己热起来。你必须按照菜谱去拧燃气灶、倒油、下锅——Skill就是菜谱,而调用接口就是那个燃气灶旋钮。你拧的是哪种旋钮、旋钮连着什么管道,直接决定了AI到底能不能“做菜”。

1.2 三种调用接口的方式到底是什么

既然Skill本身不能直接碰数据,那总得有几种办法让它“伸出手去”抓数据。当前生态里最常见的就三条路:

• scripts方式:你提前写好Python、Shell或其他语言的脚本,把脚本路径和调用方法写进SKILL.md。模型按说明调用脚本,脚本去读文件、查接口,再把结果打回给模型。
• CLI方式:不额外写脚本,直接让模型调用机器上已有的命令行工具,比如git log、kubectl get pods、gh issue list、codex exec这类。Skill充当一个“怎么用命令”的提示词,模型构造命令行并执行。
• MCP方式:通过Model Context Protocol标准协议,让AI客户端动态发现一组工具。MCP Server把工具清单和参数结构告诉模型,模型按JSON Schema去调用,数据和结果都走结构化通道。

这三条路不是互相替代的关系,而是从“轻量定制”到“标准接入”的层层递进。scripts解决的是“本地逻辑怎么被AI调用”,CLI解决的是“现有命令行工具怎么复用”,MCP解决的则是“跨AI客户端、跨系统的工具标准化”。很多人之所以卡在第一步,就是因为混淆了这三者的边界,结果该用脚本的地方去写MCP Server,该用MCP的地方还在手工拼命令行,折腾一晚上都是白费。

2. scripts方式:最朴素也最容易跑通的接入法

2.1 scripts到底解决了什么问题

scripts是三种方式里最容易理解的一种:我们把数据读取、处理、转换的逻辑写成一个独立脚本,然后让Skill的SKILL.md告诉模型“这个脚本在什么场景下调用、需要传什么参数、输出是什么格式”。模型根据用户的实际问题选择合适的脚本并触发执行。

我见过最典型的案例是“用Python让AI自动整理本地文档”:一堆散落在文件夹里的Markdown、TXT、CSV,AI不可能直接去遍历目录,但一个Python脚本可以轻松做到。比如写一个scan_files.py,接收目录路径和关键词两个参数,遍历文件、匹配内容、输出结构化的列表。SKILL.md里写清楚用法后,用户只要说“帮我整理下D盘哪个项目里的TODO”,模型就会自动调用脚本去搜文件,再对着脚本输出的结果做归纳总结。

scripts方式的优势显而易见:逻辑完全由你控制,不依赖AI对命令行语法的记忆,脚本内部想怎么处理数据都行,还能做编码转换、异常兜底、去重等复杂操作。对AI来说,脚本是一个“黑盒工具”,它只负责传参和接收输出,不关心细节,这反而大大降低了出错率。实测下来,只要参数设计得够直观,脚本调用基本能稳定复现。

2.2 从零写一个可被Skill调用的数据查询脚本

要让AI能顺畅地调用脚本,脚本本身必须设计得“对模型友好”。我自己写Skill脚本时,基本会遵循一套固定套路:用sys.argv接收参数、结果输出到标准输出stdout、错误信息输出到stderr、最终结果尽量用JSON格式输出。为什么强调JSON?因为模型的文本解析能力再强,面对一堆排版随意的文字也容易断错句,而JSON结构天然清晰,模型一眼就能看到{"status": "success", "data": [...]}里的关键字段。

下面是一个最简化的“读取CSV并查询记录”的脚本示例,你几乎可以照抄:

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """按关键词过滤CSV文件,输出前N条结果""" import sys import json import csv def main(): if len(sys.argv) < 2: print(json.dumps({"error": "缺少文件路径参数"}, ensure_ascii=False)) sys.exit(1) file_path = sys.argv[1] keyword = sys.argv[2] if len(sys.argv) > 2 else "" limit = int(sys.argv[3]) if len(sys.argv) > 3 else 10 try: with open(file_path, newline='', encoding='utf-8') as f: rows = list(csv.DictReader(f)) except FileNotFoundError: print(json.dumps({"error": f"文件不存在: {file_path}"}, ensure_ascii=False)) sys.exit(1) if keyword: rows = [ row for row in rows if keyword.lower() in json.dumps(row, ensure_ascii=False).lower() ] result = rows[:limit] print(json.dumps({"total": len(rows), "data": result}, ensure_ascii=False, indent=2)) if __name__ == "__main__": main()

脚本写完后放进Skill目录的scripts/下,然后在SKILL.md里补上这样一段说明:

当你需要从CSV文件中查询数据时,可以使用scripts/query_csv.py。 调用命令:python scripts/query_csv.py <文件路径> [关键词] [限制条数]脚本会输出JSON格式结果,包含total和data字段。请基于返回结果中data数组里的内容回答用户问题。

这里有个细节值得强调:脚本工作目录和用户当前目录可能不一致,所以文件路径建议用绝对路径,或者让模型先通过pwd或环境变量确认基准目录。我一开始没注意这点,结果AI总是传相对路径,脚本报“文件不存在”,查了半天才发现是路径基准问题。

2.3 scripts方式最容易踩的四个坑

scripts看着简单,踩坑的机会也不少。我把自己反复栽过的地方列出来,你避着走就行。

第一是环境依赖问题。脚本里写的python,在用户的机器上未必指向你开发时的那个Python解释器,尤其是Windows环境经常存在多个Python版本并存的情况。更稳的做法是在SKILL.md里写明使用完整路径或venv下的解释器,比如D:\pyth\.venv\Scripts\python.exe,或者脚本开头用#!/usr/bin/env python3配合执行权限。

第二是编码问题。Windows下控制台默认编码可能是GBK,而脚本里用UTF-8读文件,一不小心就是乱码或者UnicodeDecodeError。我的习惯是所有脚本都显式指定encoding='utf-8',并且输出JSON时加ensure_ascii=False。

第三是输出格式不收敛。如果脚本打印一大堆杂七杂八的日志,模型会被带偏,不知道该拿哪部分当结果。建议一切正式结果走JSON,日志类信息要么关闭,要么输出到stderr。

第四是超时控制。某些数据查询脚本面对大文件可能跑很久,模型或宿主端如果没有超时限制,整个会话会一直卡着。实际操作中,我会在脚本内部对大文件做分块读取,并且限定最大处理行数,宁可返回一个“数据量过大,请缩小范围”的提示,也不让脚本无限跑下去。

3. CLI方式:让AI直接指挥现成的命令行工具

3.1 CLI方式为什么值得学

如果说scripts是“自己造轮子”,那CLI方式就是“直接让AI开现成的车”。现实场景中,大量能力早就以命令行工具的形式存在:git管理代码、docker管理容器、kubectl操作集群、gh管理GitHub Issue、codex cli执行AI任务、gitlab cli操作仓库。与其为每个工具写一套Python脚本,不如直接让Skill告诉模型“有这些命令可用,遇到什么场景用哪条”,模型负责构造命令行并解析执行结果。

这种方法有一个明显的优点:你不需要重新实现逻辑,工具本身已经足够成熟。尤其是那些交互复杂的工具,你写脚本去封装,哪怕封装一个月也覆盖不全它的全部功能,但直接用CLI,等于把整个工具的全部能力都开放给了AI。缺点也很明显:命令行参数复杂,模型容易记错或漏传;命令输出是给人看的,不是给机器解析的,有些工具的输出里还带着颜色控制符,AI解析起来很痛苦。

我自己的经验是,CLI方式适合“能复用的成熟工具”,比如git log --oneline -n 5这种简单命令,模型基本不会用错。一旦命令参数超过三四个,或者涉及多步组合,最好还是写一个wrapper脚本把复杂度吃掉。

3.2 用wrapper脚本把复杂CLI命令封装成一键调用

直接让模型面对一长串命令行,等于让一个新手拿着十几种调料全凭感觉炒菜,翻车概率实在太高。更稳的做法是,我们自己写一个很薄的wrapper脚本,把那些高风险的复杂命令封装起来,只暴露少数几个参数给模型。

举个例子,假设我们想让AI查询Git仓库最近提交记录,并且希望按作者过滤。如果直接让模型执行git log --author="xxx" --oneline -n 20,它很可能把--author的引号写漏掉,或者把-n放错位置。但如果我们写一个git_log.sh,接收两个参数,那模型几乎不会出错:

#!/bin/bash # usage: ./git_log.sh <最多条数> [作者] LIMIT="${1:-10}" AUTHOR="${2:-}" if [ -n "$AUTHOR" ]; then git log --oneline -n "$LIMIT" --author="$AUTHOR" else git log --oneline -n "$LIMIT" fi

然后在SKILL.md里这样写:

当用户需要查询Git提交历史时,执行bash scripts/git_log.sh 条数 [作者]。 输出格式为“提交号 提交说明”,请直接解读,不需要展示整个commit详情。

这样一来,模型面对的接口一下子从“复杂命令”变成了“两个简单参数”,调用成功率大幅提升。我更推荐在SKILL.md里给出“接口签名”式的说明,格式可以参考函数文档:先说明脚本用途,再列出每个参数的意义,最后附一个调用示例。模型看到示例后,绝大多数情况下都能照着做。

3.3 CLI方式的安全、兼容性和输出解析问题

让AI自由构造命令行,最大的风险是命令注入。模型有可能受到用户输入中的恶意指令影响,构造出诸如git log; rm -rf /之类的危险命令。虽然大多数宿主端做了命令白名单或沙箱,但你在自己的Skill里还是应该收敛命令范围。我的一般原则是:禁止在SKILL.md里出现任何“让用户自由输入shell命令”的描述,所有可以通过wrapper封装的命令一律封装,只在极少数情况下才允许直接使用一条经过验证的完整命令。

兼容性方面,CLI命令在不同平台上的差异非常明显。git还好,跨平台表现一致;但很多自定义CLI在Windows上需要通过.exe或cmd /c执行,在Linux/macOS上则是直接bash。如果Skill要在多平台使用,SKILL.md里必须描述清楚“不同平台用什么方式调用”,或者干脆用Python的subprocess跨平台调用工具,再返回统一格式的结果。

输出解析这块,命令行工具的输出是为了给人看设计的,不是给AI吃的数据。比如docker ps的输出有对齐的列,grep出来的结果可能带颜色转义符。我的处理方式是:在wrapper脚本里用sed或Python清洗一下输出,去掉ANSI颜色码,再把结果转为JSON。实测下来,清洗后的输出让模型的理解准确度提升了一个档次。

3.4 CLI调用失败的常见快速排查

结合我自己和身边同事踩过的坑,CLI调用最常见的失败场景可以按症状查原因:

• 报command not found:工具没装或不在PATH里,需要确认工具的安装路径。
• 报403:大部分是凭证或网络策略问题,检查工具自身的认证配置、token是否过期,不要交互式输入token,尽量通过环境变量注入。
• 输出乱码或编码错误:Windows控制台的默认编码问题,在wrapper里强制utf-8输出。
• 命令被截断:通常是参数中包含了空格或特殊符号,不要手动拼接命令串,用数组形式传参(如subprocess.run(["git", "log", ...]))。
• 命令无权限:有些CLI需要root或管理员权限,确保Skill宿主运行环境有对应权限。

4. MCP:让AI动态发现工具的标准协议

4.1 MCP到底改变了什么

MCP的全称是Model Context Protocol,即模型上下文协议,由Anthropic提出并推动为开放标准。它解决的是scripts和CLI都没解决好的一个痛点:AI怎么知道“你有哪些工具可以用”?scripts方式里,工具列表写死在SKILL.md里,模型只知道你写在文档里的那些脚本;CLI方式里,模型面对的是任意命令行,能不能用对全靠提示词写得好不好。而MCP里,工具通过协议动态暴露:一个MCP Server启动后,AI客户端通过tools/list消息就能拿到全部工具的名字、描述、参数JSON Schema;需要用时,AI发送tools/call消息,Server执行并返回结构化结果。

用USB-C来类比特别合适:以前每个设备都有自己的充电口,你就得给每种设备配一根线;现在有了统一接口标准,一根线走天下。MCP就是AI工具调用领域里的USB-C。热词里出现的playwright mcp、chrome devtools mcp、unity mcp、同花顺mcp等,都是这个生态里的具体成员,分别把浏览器自动化、前端调试、游戏引擎、金融行情数据这些能力变成了AI客户端可以直接调用的标准工具。

4.2 MCP的工作流程与核心概念

MCP的架构里有两个角色:MCP Server(提供工具的一方)和MCP Client(调用工具的一方)。当前主流AI客户端,比如Claude Desktop、Cursor、Codex CLI、Trae等,都内置了MCP Client能力。它们连接Server后,整个调用链路是这样的:

1. Server启动时加载工具列表,每个工具对应一个函数,函数的参数通过JSON Schema描述。
2. Client向Server发送initialize和tools/list,拿到全部工具的定义。
3. 模型根据用户问题,挑选合适的工具,自己按照Schema生成参数。
4. Client向Server发送tools/call,带上工具名和参数。
5. Server执行函数,把结果以结构化内容返回给Client,由模型继续解读。

这套机制和scripts/CLI最大的区别是:AI不需要从文档里“死记”工具怎么用,而是实时去Server“问”出工具怎么用。这意味着新增工具、修改参数都不需要改提示词,Server端一变,所有连接它的AI客户端立刻就能感知。对开发者来说,MCP把“工具接入AI”这件事从一个“文档解释工作”变成了“接口暴露工作”,这是质的区别。

4.3 用Python快速搭建一个MCP Server

搭建一个MCP Server并没有想象中复杂。使用官方的mcpPython SDK,几行代码就能把一个普通函数暴露成AI可调用的工具。我用FastMCP接口写过一个“查询库存”的Server,示例代码如下:

from mcp.server.fastmcp import FastMCP mcp = FastMCP("inventory") @mcp.tool() def query_stock(sku: str) -> str: """根据商品SKU查询当前可售库存数量""" # 这里可以替换成真实的数据库查询或HTTP接口调用 stock_map = { "SKU001": 120, "SKU002": 45, "SKU003": 0, } count = stock_map.get(sku, -1) if count < 0: return f"SKU {sku} 不存在" return f"SKU {sku} 当前库存: {count} 件" mcp.run()

运行起来后,在支持MCP的AI客户端里配置这个Server。以JSON配置文件为例:

{ "mcpServers": { "inventory": { "command": "python", "args": ["/path/to/inventory_server.py"], "env": {} } } }

配置完成后,AI客户端会自动发现query_stock这个工具。用户问“SKU001还有多少货”,模型就会调用工具并读出结果。整个过程中你没有写任何一行“告诉模型怎么用”的提示词,工具描述完全由query_stock的docstring和类型注解自动生成。这也是MCP最吸引人的地方:工具的发现、调用、结果解析全部标准化,不再依赖提示词技巧。

4.4 MCP Server内部完全可以复用scripts和CLI

这里想多说一点我个人的架构心得:MCP和scripts/CLI不是互斥的,而是可以分层的。你可以把MCP当作最外层对AI的统一入口,内部实现继续用Python脚本或CLI。比如前面提到的库存查询,真正的数据可能来自一个内部数据库脚本,也可能来自一个已存在的CLI命令。那我们就在MCP Server的query_stock函数内部去调用那个脚本或CLI,再把结果包装成字符串返回给AI。好处是:外部接口稳定,内部实现随便换;新AI客户端接入成本低;而你已经写过的scripts也不会浪费。

这种“对外MCP、对内scripts/CLI”的模式,在开发团队里特别实用。比如有个数据平台已经有一套>