我这儿连续几周被同一个问题找上门AI Skill装好了也能像模像样聊天但一问到具体数据就哑火。上周帮人排查一个AI备课Skill它能生成教案、能列大纲唯独查不了本班学生上次测试的成绩分布。打开运行时日志一看工具调用压根没落到数据源上。这类装了Skill却查不了数据的事故根子基本不在Skill本身而在Skill背后的接口通道没打通。这篇就专门聊一件事AI Skill到底有哪些方式可以把外部数据搬进来以及scripts、CLI、MCP这三条路各自怎么选、怎么用、有什么坑。先对齐概念我这里说的AI Skill是智能体运行时里用来赋予Agent某项专业能力的一个技能包通常包含元数据、提示词、脚本和资源。Skill能不能查数据取决于它有没有一条能触达真实数据源的调用接口。接口通数据通接口不通提示词写得再漂亮都是空转。1. 查不了数据的病根不在 Skill 本身而在手没伸出去1.1 Skill 的文件里藏着哪几样东西大多数主流智能体运行时里的Skill结构上都出不了这几样东西一个声明文件SKILL.md或main.toml写清楚技能名称、描述、入口和依赖一个prompts目录放系统提示词和few-shot示例一个scripts或plugins目录放能被运行时调起的实际执行代码还有一个resources目录放静态数据或参考文档。很多人在这个结构里误判了查数据的责任。总觉得Skill描述里写了可以查询订单数据模型就会自动去查。实际上描述只是意图路由用的当Agent决定要查数据时它真正执行的是scripts里的工具函数或者运行时里注册的外部工具。数据不在Skill包内也不在提示词里而在某个数据库、某个API服务、某个云存储中。Skill本身只是手接口才是手伸出去够到东西的通道。1.2 你遇到的查不了数据大概率是这三种症状之一我排查过的案例里九成可以归到三类。第一类是Agent直接回答我无法访问实时数据或我没有权限查看这说明工具调用根本没有被触发大概率是Skill声明里的描述写得不够清晰意图路由没匹配上。第二类是工具调用确实发生了但返回结果是空的脚本执行了、日志也打了却查不到内容——这种往往是脚本里的查询逻辑或参数解析出了问题。第三类是工具报错权限、超时、连接失败这是最直观的接口层故障但也最容易被误判成Skill本身坏了。三种症状虽然表象不同但共同指向一个事实Skill和外部数据之间的接口通道没有形成稳定闭环。想排查就得先看清楚一条查询请求从用户提问到最终回答中间每一步做了什么。1.3 一条查询请求的完整路径接口处在哪个位置一条典型的查询链路是这样的用户提问进入意图路由模型根据Skill描述判断该用哪个工具运行时把模型生成的参数传入工具函数工具函数执行具体逻辑通过接口去外部系统拿数据返回结果经过解析、结构化成模型看得懂的文本模型基于这份文本组织回答。这条链路上真正和外部数据发生交换的只有工具函数执行后通过接口拿数据这一环。其他的环节都是在处理信息的搬运和表达。所以当你发现Skill查不了数据时不要急着改提示词先确认这一环通不通。这也是我把标题里的三种方式——scripts、CLI、MCP——放在一起讲的原因它们都是接口这一环的具体实现方案。2. scripts把脚本直接做成 Skill 的数据搬运工最轻但别低估2.1 scripts 方式到底是怎么被调起来的scripts方式是Skill里最朴素也最常用的一种接口方案。原理很简单Skill包里放一个可执行脚本运行时把脚本注册成Agent可调用的工具函数。Agent决定调用时运行时用子进程方式把脚本拉起来传入参数脚本执行完把结果写到标准输出运行时截取stdout内容再喂回给模型。这里有个关键约定模型不直接读脚本内部的状态它只看stdout的输出。所以脚本的输出格式必须稳定、结构化通常是JSON文档或Markdown文档。调用时参数怎么传不同运行时习惯不同有的是走命令行参数有的是走环境变量还有的走标准输入。我的建议是脚本里三种方式都兼容至少环境变量和参数二选一否则换一个运行时就要改写脚本。2.2 最小可运行示例一个查 SQLite 的脚本拿最常见的查本地数据库场景举例。假设Skill要查询销售数据数据存在一个SQLite文件里脚本可以这样写import sqlite3 import json import os db_path os.environ.get(SALES_DB, ./sales.db) start_date os.environ.get(FILTER_START, 2025-01-01) conn sqlite3.connect(db_path) cur conn.cursor() cur.execute( SELECT date, region, amount FROM sales WHERE date ? ORDER BY date DESC LIMIT 20, (start_date,) ) rows cur.fetchall() conn.close() print(json.dumps({ status: ok, count: len(rows), rows: [ {date: r[0], region: r[1], amount: r[2]} for r in rows ] }, ensure_asciiFalse))这段代码要刻意注意几件事。一是参数走环境变量而不是硬编码因为Agent每次问的时间范围都不同。二是输出必须是单个JSON对象不要打印多余日志否则模型解析时会混入噪音。三是连接用完必须关闭Skill脚本会被高频拉起连接泄漏会导致文件锁死。脚本本身不复杂复杂的是稳定输出这四个字。2.3 scripts 是起点但它的边界也明显scripts方式最大的优势是轻。不需要额外部署服务、不需要注册协议一份脚本跟着Skill包走复制到任何运行时都能跑。对于轻量只读、简单计算、本地文件访问这类需求scripts几乎是最优解。但它的边界也很明显。第一脚本和Skill强绑定数据逻辑分散在各个Skill包里改一个公共查询逻辑要改好几处。第二鉴权没有统一标准每个脚本自己处理密钥和凭证容易在某个角落把Token打印到日志里。第三脚本的并发和性能不可控运行时每次调用都new一个进程频繁查询时开销不小。所以scripts适合做小而专的接口不适合做大而全的数据平台。2.4 脚本集两个容易被忽略的经验空返回与模拟输出我在实际排查中有一个高频发现脚本执行成功但查询结果为空十有八九是查询条件没传对。比如Agent生成的日期格式是2025年1月而脚本里要求的是2025-01-01SQL自然查不到东西。所以在Skill的提示词里给Agent一个标准的参数示例让模型生成的参数永远贴合脚本预期比在脚本里做一堆容错解析更省事。另一个经验是给脚本设计模拟输出开关。开发阶段用环境变量如MOCK1让脚本返回固定假数据这样调试Skill的提示词、工具调用逻辑时不需要依赖真实数据源。等提示词调稳定了再关掉mock。这个习惯能帮你把Skill问题和接口问题彻底分开排查。3. CLI借用现成命令行工具一条条命令就是一条条数据管道3.1 CLI 调用的本质子进程加文本协议CLI方式和scripts方式在执行机制上很接近都是运行时调起一个子进程去干活。区别在于scripts方式强调的是Skill自带脚本而CLI方式强调的是复用系统里已经存在的命令行工具。比如你想让Skill查服务器磁盘占用没必要写一个Python脚本去解析/proc直接让Skill调起df -h拿到输出再喂给模型就行。你想查线上订单也可以直接用curl加jq完成请求和解析而不是在Skill里重新实现一遍HTTP客户端。这个思路的本质是把命令行工具当成一个个现成的数据函数Skill只需要负责拼命令、收输出、交结果。复用现成CLI的最大好处是逻辑可靠。df、git、curl、psql这些工具被用了十几年边界情况和错误处理远比你自己写脚本要扎实。Skill开发者的工作从实现一个功能变成了编排一组命令复杂度一下子降下来。3.2 输出格式别随便定推荐三种结构化格式CLI方式最头疼的问题不是调不起来而是输出没法用。命令行工具的输出千奇百怪有的带ANSI颜色码有的是人类可读的表格有的直接把错误堆栈打到stdout。想让模型稳定消费输出你必须在命令层面就把格式钉死。我常用的三种格式是JSON Lines、CSV和Markdown表格。JSON Lines适合结构性强的数据每行一个对象模型逐行解析非常方便。CSV适合表格类数据配合jq -r csv可以在命令行一步到位。Markdown表格则最适合直接塞进对话上下文模型不用解析就知道怎么转述。另外强烈建议在命令末尾把标准错误重定向到独立文件避免错误信息和正常数据混在同一个流里。3.3 四道看不见的墙路径、环境变量、超时、退出码CLI方式跑不通通常不是命令写错而是环境不对。第一道墙是路径。运行时拉起子进程时工作目录可能不是你预想的目录相对路径自然就失效了。我习惯在命令里显式写绝对路径或者在脚本开头先cd到固定目录。第二道墙是PATH环境变量。命令行工具如果安装在非标准目录子进程可能找不到。排查时先打印一下which结果别让运行时背锅。第三道墙是超时。很多命令默认没有超时限制比如curl连一个不响应的地址能挂五分钟而Agent的响应本身可能只有几十秒。Skill声明里最好给每个命令配上超时参数。第四道墙是退出码。命令返回非零并不一定代表没有数据比如grep没匹配到内容时退出码是1但你仍然希望把查询无结果作为一个正常结果返回给模型。所以编写CLI封装时要把退出码、stdout、stderr三样都捕获再决定如何向模型汇报。3.4 一个真实的 CLI 组合案例curl 加 jq 查 REST 接口举个组合案例。假设Skill要查网关里的支付流水直接用curl调用内部API再用jq把响应裁成模型方便阅读的格式curl -s --max-time 10 https://api.example.com/v1/payments?statuspaidlimit20 \ -H Authorization: Bearer ${API_TOKEN} | jq -r .data[] | [.id, .amount, .created_at, .channel] | csv这条命令有两个细节值得记住。第一--max-time必须加防止接口假死拖垮整个Agent。第二输出最终是CSV格式jq负责剥离JSON里的冗余字段模型拿到的就是一行行干净数据。如果接口返回的是错误码jq输出会是空此时要靠退出码或curl的-w参数把HTTP状态码打出来不然你根本分不清是没有数据还是请求失败。CLI方式还一个容易被忽略的价值现在很多Agent CLI工具本身就提供了丰富的命令比如Codex CLI这类工具自己就是一组庞大的命令集合。Skill里要调它们跟调一个curl在机制上没有任何区别。也就是说CLI方式天然支持Agent调用Agent这种嵌套场景。4. MCP给 Skill 装一个万能插座让所有数据源从配接口变成插线板4.1 MCP 解决的是数据源太多Skill 各自为政的问题scripts和CLI方式都有一个共同的成长烦恼每接一个新的数据源都要在Skill里重新写一段对接逻辑。查数据库要写一套数据库连接查文件系统要写一套路径解析查内部API又要写一套鉴权和请求。Skill一多这段逻辑在几十个地方重复改一次到处受影响。MCPModel Context Protocol模型上下文协议解决的就是这个问题。它把数据源统一封装成MCP ServerSkill的宿主通过MCP Client去连这些Server双方用标准化的JSON-RPC消息通信。一个MCP Server可以暴露三类能力Tools可调用的工具函数、Resources可读取的数据资源、Prompts可复用的提示模板。Skill层不需要关心数据源到底是MySQL还是Mongo还是内部HTTP服务它只需要通过协议向Server发出帮我查这个的请求。用USB-C统一充电口来类比很贴切。scripts方式相当于每个设备自带一根专用线CLI方式相当于你用转接头去适配MCP则是把数据源的接口规范成同一个口子。这个统一性带来的直接好处是复用率高——一个MCP Server可以被多个Skill共享团队里写好的数据服务可以一次接入、处处调用。4.2 一个最小 MCP Server 长什么样MCP Server本身可以理解为一个小型服务进程用官方SDK写起来不算复杂。下面是一个用Python FastMCP实现的极简示例from mcp.server.fastmcp import FastMCP mcp FastMCP(sales-data-mcp) mcp.tool() def query_sales(start_date: str, region: str ) - str: 按日期和区域查询销售额返回结构化文本结果。 # 这里可以接数据库、数据仓库或内部BI API rows your_query_logic(start_date, region) return format_as_text_table(rows) mcp.resource(sales://summary) def sales_summary() - str: 提供销售汇总数据供Skill做背景参考。 return 截止目前华东区销售额完成目标的82%同比增长14%。 if __name__ __main__: mcp.run(transportstdio)注意这个Server声明了一个Tool和一个Resource。Tool适合按需查询参数由Agent动态生成Resource适合常量参考模型在回答前会自动读取。这个区分在做数据类Skill时非常实用把经常变、需要实时算的查询做成Tool把相对固定的统计口径做成Resource。这个示例用的是stdio传输也就是通信建立在标准输入输出之上。实际部署时还可以切换成SSE或HTTP传输让Server独立运行多个Skill共享同一条数据通道。4.3 从配置到调通把 MCP 工具暴露给 Skill 的四步接入MCP整体上比写脚本多一个环节但环节清晰照着走就行。第一步启动MCP Server确认它能独立运行可以用MCP Inspector这类调试工具直接发消息验证。第二步在Skill宿主侧配置MCP Client指定Server的启动命令或连接地址。不同的运行时配置位置不一样有的写在配置文件里有的支持运行时动态添加。第三步在Skill的声明中引用MCP暴露的工具或资源让模型知道有哪些外部能力可用。第四步做一个真实查询验证从用户提问出发走完整链路确认Tool的输入输出和模型预期一致。我第一次接入时在第三步卡了很久因为只启动了Server却没告诉模型有哪些工具。MCP工具不会自动出现在Agent的调用候选里必须显式声明。很多配了MCP却没用上的问题根源都在这里。4.4 用 MCP 之后踩过的三个坑MCP不是协议接上就万事大吉。第一个坑是工具名冲突。多个MCP Server可能都暴露了类似query_user这样的工具名如果Skill宿主不做命名空间隔离模型会调错。我现在的做法是接入时给每个Server加前缀比如sales__query_sales和crm__query_sales彻底避免歧义。第二个坑是Server断连和恢复。用SSE传输时网络抖动会导致连接断开而MCP Client不一定自动重连。需要给Server加健康检查或者让宿主捕获断连事件后重启会话。第三个坑是默认超时偏短。很多MCP Client默认的请求超时只有10秒但真实查询一个复杂的BI接口可能要几十秒如果不在配置里调大超时会出现工具被调了但返回超时这种最让人抓狂的现象。MCP的resources读取顺序和tools的调用顺序也值得留意有的模型会先读Resource再决定要不要调Tool如果Resource里的数据太旧模型可能据此给出过时答案。5. scripts / CLI / MCP 怎么选一张对比表和我的真实判断顺序5.1 一张表看穿三种方式的差异三种方式不是取代关系而是不同场景下的互补方案。用一张表把核心差异列清楚选型时就心里有数了。维度scriptsCLIMCP接入成本低一个脚本文件即可中需要目标命令可用高需要部署和注册Server数据实时性取决于脚本逻辑取决于命令本身高连接后可实时查询复用性差每个Skill各自维护中等命令可被多个Skill复用高一套Server多端接入安全边界运行在宿主沙箱内继承宿主权限暴露面较大协议层可统一鉴权和管控适合场景轻量只读、本地小查询已有成熟CLI、系统运维类多数据源、团队共享、高频查询你以为我会直接说MCP最好恰恰相反。MCP的接入成本决定了它不适合所有场景。如果你只是想让一个Skill查一个本地文件写个scripts脚本几分钟就搞定上MCP反而是在用大炮打蚊子。5.2 适合多数人的选型判断原则我的判断顺序基本可以固化成三条原则。第一有没有现成可用的命令行工具有就优先CLI因为它最接近只做编排、不写实现。第二查询逻辑是否足够简单、是否只服务于当前Skill是就选scripts简单直接出问题也好查。第三数据源是否多样、是否需要多团队共享是才考虑MCP。在真实项目里我见到过一上来就搭MCP Server的团队也见过用scripts维护了上百个脚本的痛苦局面。前者的问题是过度设计后者的问题是碎片化严重。正确路径不是二选一而是让scripts和CLI先在单点跑通等脚本数量上来了、重复逻辑开始出现再逐步把公共数据服务改造成MCP Server。很多人问为什么我的MCP调不通那么多坑因为它在你的场景里根本不该第一个出场。5.3 混合编排的真实场景一个智能体群既要查数据库又要查服务器拿我最近做的一个内部智能体集群举例。其中一个Agent负责运维工单它要查数据库里的工单状态也要查服务器上的磁盘和进程状态。我最终的设计是工单状态查询因为只有这个Agent用用scripts直接连数据库磁盘和进程状态用CLI调df、ps这些系统命令复用系统自带的工具而跨Agent共享的用户画像和权限校验则做成一个MCP Server供所有Agent统一调用。这套混合结构上线后调试体验很好。查工单出问题只看Skill的脚本逻辑查磁盘出问题直接看命令输出共享服务出问题查MCP Server的日志即可。每一种问题的排查边界都非常清晰不会出现这个数据到底走哪条链路的迷茫。这就是我把标题里的三种方式放一起讲的最终目的你不是非黑即白地选一种而是让每种方式落在它最顺手的位置。6. 接口打通之后还有四道稳定关卡等着你6.1 输出处理三戒接口通了数据也能返回了但离稳定可用还有距离。第一戒是截断。大规模数据返回时脚本或命令的输出会被运行时截断模型只看到前半段就会给出以偏概全的结论。对策是输出的数据要主动做摘要或过滤别把原始全量数据一股脑倒给模型。第二戒是格式漂移。同一个字段今天返回字符串、明天返回数字模型解析就会出幻觉。对策是把输出Schema固定住并在脚本层做类型强转。第三戒是注入。外部数据如果包含类似请忽略上述指令的文本可能被模型当作指令执行。对策是在返回给模型前对可疑内容做转义或明确标记为数据。6.2 超时与重试给接口调用装一道保险丝没有超时的接口调用是隐患没有重试的接口调用是半残。Skill里每次调用接口都应当有一个明确超时时间这个时间要同时考虑接口本身的耗时上限和Agent等待用户响应的耐心上限。重试策略则需要区分场景查询类接口失败通常可以直接重试一两次因为幂等安全写操作类接口不能盲目重试有可能造成重复数据。我常用的是首次超时不重试连接类错误重试一次拿到5xx状态码重试一次这种保守策略。6.3 流式和对话式返回是两码事MCP协议支持流式返回很多人误以为流式可以实时逐字把数据给用户看。实际上MCP里的流式传输更多是Server到客户端的长连接推送和Agent对话界面上打字效果是两码事。做数据查询类Skill时不要试图把原始数据流直接接到对话流上更稳妥的做法是让Server攒好一批结构化结果一次提交给宿主由宿主决定如何呈现。想明白这一点就不会在为什么流式返回在对话里看不到实时效果上内耗。6.4 Skill 接口的权限与可观测性最后一道关卡是权限和日志。scripts和CLI方式在权限控制上天然薄弱因为命令以宿主进程权限运行一个Skill能拿到什么数据基本上等同于是个人登录账号能拿到什么数据。MCP方式则可以在Server层做统一的Token签发和鉴权判断。无论用哪种都要把每次接口调用的入参、出参、耗时、结果状态记录下来。排查查不了数据时这些日志就是你的案发现场。建议每条日志带一个调用链ID从用户提问到接口返回一串到底翻起来效率高得多。我自己在这几道关卡上栽过的跟头不少。有一次查工单数据的Skill脚本本身逻辑完全正确但返回的字段名在夜里被人改了大小写模型开始一本正经地编数据排查了半天才发现是上游Schema变了。那之后我所有脚本输出前都会加一层字段校验不匹配就报错而不是静默返回。回到标题那个问题。Skill查不了数据绝大多数时候不是AI的智力不够而是数据搬运的通道没铺好。先看scripts能不能把本地数据简单搬出来再看CLI能不能借用现有命令撑起管道等数据源多了、共享需求出来了再上MCP统一收口。这个顺序我实测下来最顺每一步都能验证出了问题也知道往哪一环节排查。最后分享一个提升Skill接口调用成功率的低成本技巧在每个Skill的提示词里附上一段标准调用示例把参数名、格式、单位都写清楚。模型生成参数时照着示例填脚本端的容错压力就会小很多。这个技巧不花一分钱却是我见过解决工具调了但参数永远不对最有效的手段。