深入理解 AI 开发核心概念：Prompt、Agent、MCP、Skill 与 Tools 的协作边界与落地实践-平芜编程栈

1. 五个概念到底谁管什么：从一次代码审查说起

Prompt、Agent、MCP、Skill 与 Tools 这五个词经常被混着用，但它们在系统里承担的责任完全不同。Prompt 是你写给模型的自然语言指令，临时、一次性、不持久；Agent 是能自己规划步骤、循环调用模型和工具的决策系统；Tools 是可被调用的具体函数或接口，有明确入参和返回；MCP 是连接模型与外部数据源的标准协议，解决的是"怎么统一接入"的问题；Skill 则是把 Prompt、Tools、Agent 逻辑打包好的可复用能力，用户一条命令就能触发。

如果你正在搭智能体应用，最容易踩的坑就是职责错位：把本该交给 Tools 的确定性计算写进 Prompt 里让模型"心算"，或者把本该用 Skill 封装的重复流程每次手写一遍 Prompt。我试过在一个代码审查场景里把 diff 解析逻辑塞进提示词，结果模型每次输出的格式都不一样，后来改成 Tools 做解析、Prompt 只负责判断，稳定性立刻上来了。

这篇会给你一套可复制的概念对照表，再用一个最小可跑的配置逐项验证每个概念的实际作用。TaoToken 在这里的角色是统一 Key/API 通道，你只需要一个 Base URL 和一把 Key 就能把模型调用接进来，不用在多个平台之间来回切换。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，后面配置里会具体用到。

先记住一句话：Prompt 是"说什么"，Tools 是"能做什么"，Agent 是"决定做什么和做几步"，MCP 是"怎么接外部世界"，Skill 是"打包好给用户直接用"。下面逐层拆开。

2. 接入前的准备：TaoToken 统一 Key 与 API 通道配置

在验证这五个概念之前，得先有一个能稳定调用的模型通道。TaoToken 提供的是 OpenAI 兼容接口，意味着你现有的 SDK 基本不用改代码，只换 Base URL 和 Key 就行。这一步只做一次，后面所有示例都复用这套配置。

你需要准备的东西很少：一个 TaoToken 账号、一把 API Key、以及你要用的模型 ID。模型 ID 建议先用一个通用对话模型做验证，等流程跑通再换成更强的推理模型。

Base URL 统一用https://taotoken.net/api，注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面创建，创建后只显示一次，记得立刻复制保存。如果你还没建 Key，可以直接去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 创建。

环境变量方式最省事，写进 shell 配置里：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你用 Python，装好 openai 包后这样初始化客户端：

from openai import OpenAI import os client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) resp = client.chat.completions.create( model="你的模型ID", messages=[{"role": "user", "content": "用一句话说明什么是 Prompt"}], ) print(resp.choices[0].message.content)

跑通这段，说明通道没问题。接下来所有概念验证都基于这个 client。注意模型 ID 要和你账号里可用的保持一致，写错会直接报 model not found。

提示：Base URL 末尾不要加/v1，TaoToken 的兼容层已经处理了路径，多加一层会 404。

这一步看起来简单，但它是后面所有验证的前提。通道不稳，你根本分不清是 Prompt 写得不好还是网络在抖。所以先把这层固定住，再往上叠概念。

3. 可复制配置：用一份 settings 把五个概念落到文件里

概念讲再多不如一份能跑的配置。下面这份配置把 Prompt、Tools、MCP、Skill 都落到具体文件里，Agent 逻辑用一段 Python 串起来。你可以直接照抄，改掉模型 ID 和路径即可。

先看目录结构，这样每个概念对应哪个文件一目了然：

ai-demo/ ├── prompts/ │ └── review.txt ├── tools/ │ └── diff_parser.py ├── mcp/ │ └── mcp.json ├── skills/ │ └── review-pr.toml └── agent.py

Prompt 就是一个纯文本文件，prompts/review.txt：

你是一名代码审查助手。根据提供的 diff 内容，判断是否存在以下问题： 1. 空指针风险 2. 资源未释放 3. 边界条件缺失 只输出问题列表，每条一行，格式为：文件:行号 - 问题描述。 如果没有问题，输出：无问题。

Tools 是一个普通 Python 函数，tools/diff_parser.py：

def parse_diff(diff_text: str) -> list[dict]: """把 unified diff 拆成结构化变更块""" blocks = [] current = None for line in diff_text.splitlines(): if line.startswith("+++ "): current = {"file": line[4:], "changes": []} blocks.append(current) elif current is not None and (line.startswith("+") or line.startswith("-")): if not line.startswith(("+++", "---")): current["changes"].append(line) return blocks

MCP 配置用标准 JSON，mcp/mcp.json，这里以接入一个本地文件系统 MCP Server 为例：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"], "env": {} } } }

Skill 用 TOML 描述，skills/review-pr.toml：

name = "review-pr" description = "审查指定 PR 的代码质量" prompt_file = "prompts/review.txt" tools = ["parse_diff"] mcp_servers = ["filesystem"] model = "你的模型ID"

Agent 逻辑在agent.py里，负责把上面这些串起来：

import json from openai import OpenAI from tools.diff_parser import parse_diff client = OpenAI(base_url="https://taotoken.net/api", api_key="你的key") def run_review(diff_text: str) -> str: blocks = parse_diff(diff_text) prompt = open("prompts/review.txt", encoding="utf-8").read() user_content = prompt + "\n\n变更内容：\n" + json.dumps(blocks, ensure_ascii=False) resp = client.chat.completions.create( model="你的模型ID", messages=[{"role": "user", "content": user_content}], ) return resp.choices[0].message.content if __name__ == "__main__": sample = open("sample.diff", encoding="utf-8").read() print(run_review(sample))

这份配置里，Prompt 是review.txt，Tools 是parse_diff，MCP 是mcp.json，Skill 是review-pr.toml，Agent 是run_review这个循环入口。每个概念都有物理落点，不再是抽象名词。

注意：MCP Server 的command和args要按你实际安装的包来写，路径./workspace是相对启动目录的，写错会连不上。

配置写完后，先别急着跑 Agent，按下一节逐项验证每个概念是否真的生效。

4. 逐项验证：从 Prompt 到 Skill 的成功结果对照

验证要一个一个来，混在一起跑出了问题你根本不知道是哪层坏了。下面按 Prompt → Tools → MCP → Skill → Agent 的顺序，每步都有预期结果。

第一步验证 Prompt。直接调模型，只给提示词不给工具：

resp = client.chat.completions.create( model="你的模型ID", messages=[{"role": "user", "content": open("prompts/review.txt").read() + "\n\n变更内容：\n+ int x = null; x.toString();"}], ) print(resp.choices[0].message.content)

预期输出类似Main.java:1 - 存在空指针风险。如果模型输出一堆解释性文字而不是规定格式，说明 Prompt 约束不够，回去加"只输出"这类硬约束。这一步验证的是：Prompt 单独就能引导模型产出结构化结果。

第二步验证 Tools。单独调用parse_diff，不经过模型：

from tools.diff_parser import parse_diff print(parse_diff("+++ b/a.py\n+print(1)\n-print(2)\n"))

预期输出[{'file': 'b/a.py', 'changes': ['+print(1)', '-print(2)']}]。这一步验证的是：Tools 是确定性代码，输入输出可预测，不依赖模型。如果这里结果不对，别怀疑模型，直接查函数逻辑。

第三步验证 MCP。用 MCP 客户端连上mcp.json里配置的 server，列出可用资源：

npx -y @modelcontextprotocol/inspector --config mcp/mcp.json

预期能在 inspector 界面里看到 filesystem server 暴露的资源和工具列表。这一步验证的是：MCP 把外部文件系统以标准协议暴露出来了，模型侧不用关心底层是本地还是远程。如果连不上，先确认npx能正常执行、包名拼写正确。

第四步验证 Skill。Skill 的本质是配置聚合，你可以用一个简单的加载器读 TOML 并检查字段是否齐全：

import tomllib with open("skills/review-pr.toml", "rb") as f: skill = tomllib.load(f) assert skill["prompt_file"] and skill["tools"] and skill["model"] print("Skill 配置完整：", skill["name"])

预期输出Skill 配置完整：review-pr。这一步验证的是：Skill 把 Prompt、Tools、MCP、模型 ID 打包成一个可复用单元，用户只需要记住review-pr这个名字。

第五步验证 Agent。跑agent.py，喂一个真实 diff：

python agent.py

预期输出一份按文件分组的问题列表。这一步验证的是：Agent 把前面四层串起来，完成了"解析 → 提示 → 调用模型 → 返回结果"的完整链路。如果前面四步都过了，这一步基本不会出问题；如果这步挂了，回去看是哪一层的输出格式对不上。

把五步的结果并排看，你会发现每层职责非常清晰：Prompt 管格式，Tools 管解析，MCP 管接入，Skill 管打包，Agent 管编排。这就是协作边界。

5. 常见报错排查：401、local proxy failed 与 reading choices 怎么解

配置跑不通时，报错信息往往指向具体某一层。下面这几个是我在接入过程中遇到频率最高的，按报错原文对照排查。

401 Unauthorized或invalid api key：这是 Key 层的问题，和 Prompt、Agent 无关。先确认环境变量TAOTOKEN_API_KEY真的被读到了，Python 里可以print(os.environ.get("TAOTOKEN_API_KEY")[:8])看前几位。如果为空，说明 shell 配置没生效，重新 source 一下。如果 Key 有值还报 401，去控制台确认这把 Key 没被删除或过期，必要时重新创建一把。

local proxy failed或连接超时：这类报错通常出现在 Base URL 写错或网络出口受限时。先检查base_url是不是https://taotoken.net/api，有没有手滑写成https://taotoken.net/api/v1。再确认你的运行环境能正常访问外网 HTTPS。如果是在容器里跑，检查容器网络策略是否放行了 443 端口。

reading 'choices'或KeyError: 'choices'：这个报错说明请求发出去了、也回来了，但返回体里没有choices字段。常见原因是模型 ID 写错，服务端返回了一个错误对象而不是正常补全结果。打印完整响应体看一眼：

resp = client.chat.completions.create(...) print(resp.model_dump())

如果里面是error字段，按错误信息改模型 ID。另一种可能是你把流式和非流式搞混了，流式返回的是迭代器，不能直接取choices。

OAuth相关报错：如果你用的是 Claude Code 这类工具，报 OAuth 失败通常是认证方式没选对。这类工具支持用 API Key 方式接入，配置里把 Base URL 指向https://taotoken.net/api，Key 填 TaoToken 的 Key，模型 ID 填你账号可用的模型。三件套缺一不可，只填 Key 不填 Base URL 会走默认端点，自然认证失败。

MCP 相关报错server not found或spawn npx ENOENT：说明 MCP Server 启动命令找不到。确认本机装了 Node.js 和 npx，npx --version能输出版本号。如果是在 Windows 上，command可能要写成npx.cmd。路径参数用绝对路径更稳，相对路径在不同工作目录下会解析到不同位置。

排查的核心思路是：先定位报错属于哪一层，再只改那一层的配置，不要一次改多个地方。改完重跑对应那一步的验证代码，确认单层通过再往上走。

6. 把通道固定下来：后续验证与长期编码的接入选择

五层概念验证完之后，你会发现真正需要长期维护的其实只有两样东西：Prompt 和 Skill 配置，因为这两样承载业务逻辑；Tools 和 MCP 相对稳定，Agent 编排逻辑改动也不频繁。而模型通道这层，最好一次配好就别再动。

TaoToken 在这里的价值就是把通道固定住：一个 Base URL、一把 Key、一个模型 ID，三件套写进配置后，你的 Agent、Skill、MCP 全都复用这套凭证。后面想换模型做对比，只改模型 ID 那一行，其他代码不用动。

如果你只是想把模型对话能力接进现有应用做验证，可以直接用模型对话入口试效果：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你在搭长期运行的编码 Agent，需要更稳定的调用配额和更完整的接入文档，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入过程中遇到协议细节问题，文档页有完整的参数说明：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

回到概念本身，最后给你一个判断口诀：需要模型"理解并生成"的，写进 Prompt；需要"确定性执行"的，做成 Tools；需要"接外部系统"的，走 MCP；需要"用户一键触发"的，封装成 Skill；需要"多步自主决策"的，交给 Agent。五者各司其职，边界清晰，你的智能体应用才不会越写越乱。