首先记住一点，**开发者不再是”写解析器的人”，而是”设计交互协议的人”**。这种角色和思维的转变，是 Agent 开发者的核心竞争力所在，要摒弃一些旧的路径依赖思维，所谓杯满则溢，理解了这一点，很多LLM的“新东西”在理解上才会变得顺理成章。

⚠️注意事项：因为是随笔，过于啰嗦，且模型和微调技术发展迭代较快，部分技术时效性上可能存在偏差，以下也只作主流方向和技术性解读。

现阶段的Agent智能体应用更多是在预设可控的工具的条件下，实现的一种通过大模型参与决策和执行具体预定任务的交互型应用。

关于多智能体的设计考量

从奥卡姆剃刀定律（如无必要，勿增实体）角度以及从经济和实用性的角度来说，尽量选择单智能体，避免多智能体的方案，一个是token的消耗问题，还有一个是低耦合降低应用的复杂度。

一个好的Agent设计首先要考虑的就是具备非侵入性设计，非侵入性设计（Non-intrusive Design）是构建高可用、可持续演进的企业级 Agent 系统的核心原则：薄模型层，厚应用层。
这样做的优点很多：
1.低耦合与迭代空间： 将模型推理与业务逻辑解耦，确保底层模型升级或替换时，无需重构上层应用代码。
2.低成本与高扩展性： 通过配置化而非硬编码或微调来适应新场景，显著降低开发与维护成本，支持快速业务扩展。
3.经济性与基座无关： 避免供应商锁定，支持根据任务难度动态路由至不同性价比的模型，灵活应对价格波动。
4.多智能体协作灵活性： 基于标准协议通信，便于构建松耦合的多智能体网络，支持独立灰度发布、A/B测试及故障隔离。
5.顺应厂商设计哲学： 契合如 Anthropic 等厂商推崇的“上下文工程”与标准工具调用理念，最大化利用模型原生通用能力。
6.可观测性与调试透明： 决策路径、工具参数及思维链显式记录于应用层，像传统软件一样可逐行追踪和定位错误。
7.数据安全与隐私合规： 在应用层实现数据脱敏与过滤，确保敏感信息不直接暴露给模型，满足各国监管部门等合规要求。
8.确定性控制与护栏机制： 在模型输出与执行动作间插入中间件校验（如格式检查、敏感词过滤），确保系统鲁棒性。
9.知识更新实时性： 结合 RAG 技术，知识库变更秒级生效，无需重新训练模型即可回答最新业务问题。
10.长尾场景泛化能力： 保持模型通用推理能力，通过动态组装工具应对未见过的复杂或长尾场景，避免过拟合。
…

随着大语言模型（LLM）能力的飞速发展，AI 智能体（Agent）已经成为连接模型与现实世界的关键桥梁。一个典型的 Agent 不仅要能“思考”，还要能“行动”——调用外部工具获取信息、执行操作，最终完成复杂任务。然而，如何让模型在推理过程中动态地决定调用哪个工具、如何确保调用的顺序与安全性、如何高效地与后端服务交互，这些正是 Agent 开发的核心挑战。

以下将日常开发中的疑问以及难点进行系统化拆解，从最基础的 ReAct 模式开始，逐步深入到 Function Calling、MCP（模型上下文协议）、Skill 等进阶概念，梳理出一套完整的 AI Agent 开发流程，帮助开发者理解从“提示词工程”到“自主智能体”的演进路径。

第一部分：核心概念与技术基础

1.1 ReAct 模式：思考与行动的循环

ReAct（Reason + Act）是让模型具备工具调用能力的最经典范式。它的核心思想是通过提示词引导模型交替进行“推理”和“行动”，形成一个闭环：

• 思考（Thought）：模型根据当前状态分析下一步需要什么信息。
• 行动（Action）：模型输出一个结构化的指令，例如调用某个工具。
• 观察（Observation）：系统执行工具后，将结果反馈给模型，供其继续推理。

一个典型的 ReAct 提示词模板如下：

1
2
3
4
5
6
7

你是一个智能助手，可以调用以下工具：
- get_weather(location: string): 获取指定城市的天气。
- search_hotel(city: string): 搜索某城市的酒店。

请按照以下格式输出：
思考：...（你的推理过程）
行动：工具名[参数]

这种方式的优点是灵活、无需模型原生支持，但缺点是需要开发者自行解析模型输出的文本，且模型可能输出不规范导致解析失败。

1.2 Function Calling：结构化工具调用的演进

为了解决 ReAct 模式的不稳定性，主流模型厂商（如 OpenAI、Anthropic）推出了 Function Calling（又称 Tool Calling）功能。它的核心思想是：在 API 请求中通过 JSON 结构明确描述可用工具，模型在需要时直接返回一个结构化的 JSON 对象，而非混在文本中。

工具描述示例（JSON）：

1
2
3
4
5
6
7
8
9
10
11

{
  "name": "get_weather",
  "description": "获取指定城市的天气",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "城市名称" }
    },
    "required": ["location"]
  }
}

模型返回的调用指令也是结构化的，例如：

1
2
3
4
5
6
7
8

{
  "tool_calls": [{
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"北京\"}"
    }
  }]
}

这种方式的优势在于：

• 解析可靠，无需正则匹配；
• 模型输出更精准，减少幻觉；
• 参数格式明确，便于校验。

1.3 模型如何理解工具描述？

无论是 ReAct 还是 Function Calling，模型接收到的都是一段文本（JSON/YAML/TOML 等格式）。模型并非像传统程序那样“解析” JSON，而是将整个文本切分成 token，利用其在大规模预训练中习得的语义理解能力去“读懂”其中的结构含义。

例如，模型知道 "name" 后面跟着的是工具名，"description" 是对工具功能的解释。这种语义理解能力使得模型能够根据用户问题与工具描述的匹配程度做出调用决策。

这是很多开发者接触LLM和Agent的最常见疑问，习惯了传统结构化的思维开发陷入了一种定式思维，路径依赖下自然总会以为模型开发也要这样做，但现实是：模型本身已经从历史的数据中学习了人类各种定义的数据格式，加上一些模型厂商针对模型这块也做了一些微调和RL强化处理，已经能够理解常用的结构化数据，对模型来说都是转化成token，只需要告诉模型自己需要什么格式的数据即可，模型虽然不是万能的，但你把它当成一个思维引擎来理解，像一些数据的定义(JSON、YAML、Markdown等等)这些岂不是小case?。

如果把LLM当成一种”思维引擎”，开发的范式就变成：

1

需求 → 设计输出格式 → 编写 prompt + 示例 → 调用模型 → 解析 + 校验 + 兜底 → 业务逻辑

1.4 LLM时代核心认知升级（这一点认知的转变非常重要）

传统思维 vs LLM 思维

模型为什么能”天然”理解结构化数据？

1. 训练数据覆盖广：GitHub、技术文档、API 文档里充斥着 JSON/YAML/Markdown
2. Token 本质统一：{"name": "test"} 和 你好 对模型都是 token 序列，无本质区别
3. 指令微调强化：主流模型都经过 function calling、structured output 的专项训练
4. 上下文学习能力：Few-shot 示例能让模型快速对齐你的格式要求。

Few-shot learning（简称：FSL）备注：指模型在‌仅有极少量标注样本（通常每个类别1-5个或任务示例少于10个）‌ 的情况下，高效学习并准确预测新任务的能力。其设计目标不是从零开始训练，而是利用已有知识快速泛化，优点自然是效率高，本质是模拟人类“举一反三”的学习能力。‌‌‌‌

实用建议：如何高效让模型输出结构化数据

1. Prompt 设计技巧

1
2
3
4
5
6
7
8
9
10

### 模糊的请求
"帮我整理用户信息"

### 明确格式 + 示例
"请以 JSON 格式输出，包含字段：name, age, tags。示例：
{
  "name": "秋歌(Jaco Liu)",
  "age": 25,
  "tags": ["developer", "LLM"]
}"

2. 利用模型原生能力

• Function Calling：OpenAI、Anthropic、Qwen 等都支持，让模型”声明”参数而非拼字符串
• JSON Mode / Structured Output：部分 API 提供强制 JSON 输出，减少解析错误
• Schema 约束：用 JSON Schema 描述期望结构，提升输出稳定性

3. 工程兜底策略（重要！）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 伪代码示例
def robust_parse(response, schema, max_retries=3):
    for i in range(max_retries):
        try:
            result = json.loads(response)
            validate_schema(result, schema)  # 业务校验
            return result
        except:
            # 让模型自我修复
            response = llm.generate(
                prompt=f"上次的输出解析失败，请按以下 schema 重新输出：{schema}",
                history=response
            )
    return fallback_handler()  # 降级方案

需要注意的边界！

虽然模型很强大，但也要避免”过度信任”：

• 复杂嵌套/超长结构：可能截断或遗漏字段，建议分步生成
• 强一致性要求：金融/法律场景仍需传统校验层兜底
• 格式幻觉：模型可能输出”看起来像 JSON 但不是”的内容，务必 parse + validate
• 成本考量：重试机制会增加 token 消耗，需权衡鲁棒性与成本

思维转变与升级：从”程序员”到”提示工程师 + 系统架构师”

当把 LLM 当作思维引擎后，开发范式变成：

需求 → 设计输出格式 → 编写 prompt + 示例 → 调用模型 → 解析 + 校验 + 兜底 → 业务逻辑

第二部分：决策机制——模型如何选择工具？

2.1 关键词匹配的局限

早期的简单实现可能依赖关键词匹配：用户输入中出现“天气”就触发天气查询。这种方式在处理同义词、复杂意图或多步推理时无能为力，例如“明天适合穿什么衣服？”隐含了天气查询需求，但并未直接出现“天气”。

2.2 模型分析的原理

现代 Agent 利用模型本身的语义理解能力进行工具选择，过程如下：

1. 意图识别：模型理解用户的真实需求。例如“北京今天会下雨吗？” → 意图是查询天气。
2. 实体抽取：从文本中提取关键参数，如地点“北京”。
3. 工具匹配：模型将用户意图与工具描述进行语义比对，选择最合适的工具，并填充参数。

这一过程完全是模型内在的推理，无需人工规则。

2.3 Function Calling 的工作流程

以最典型的查询当前天气(Weather)为例，完整流程如下：

1. 开发者定义工具：通过 API 将工具描述（JSON）传给模型。
2. 用户输入：用户提出问题。
3. 模型决策：模型判断需要调用 get_weather，并生成参数 {"location": "北京"}。
4. 系统解析：提取工具名和参数。
5. 执行工具：调用后端服务获取真实天气数据。
6. 结果反馈：将结果作为“观察”返回给模型，模型生成最终答案。

由此可以看到，大模型本身存储的主要是一堆权重参数，大模型本身并不具备执行具体任务的能力，它完全依赖于外部工具和数据接口来完成实际操作。

第三部分：构建可靠的 Agent 系统

3.1 安全性设计

将工具暴露给模型可能带来安全风险，必须建立多层防御：

• 最小权限原则：只给模型提供当前任务必需的工具，而非所有工具。
• 工具分级：将工具分为低风险（查询类）和高风险（修改/删除/支付类），高风险操作需用户二次确认。
• 沙箱执行：对于模型生成的代码或敏感操作，应在隔离环境（如 Docker、WebAssembly、Firecracker 微VM）中运行。
• 动态凭证：模型不接触真实密钥，由系统根据上下文动态注入临时凭证。
• 输入输出校验：对模型生成的参数进行格式、范围校验；对工具返回的数据进行脱敏过滤。

3.2 准确性与鲁棒性

• 精心设计工具描述：使用清晰的名称、详细的描述、参数示例，帮助模型准确理解。
• 错误反馈循环：当工具调用失败（如参数非法）时，将错误信息返回给模型，让其重新尝试或修正。
• 多步推理与自我反思：引导模型显式输出思考过程，必要时让模型评估调用结果是否满足需求。

3.3 成本与性能优化

ReAct 和 Function Calling 都会消耗大量 token（特别是历史记录累积）。优化策略包括：

• 滑动窗口：只保留最近几轮对话，丢弃过旧的上下文。
• 摘要历史：用模型将长历史压缩成摘要。
• 分层规划：先用一个强大模型生成执行计划，再由轻量模型按计划调用工具，减少反复调用。
• 微调专用模型：针对固定工具集微调小模型，降低成本。

第四部分：进阶架构——MCP 与 Skill

4.1 MCP：标准化工具接入

MCP（Model Context Protocol）是由 Anthropic 提出的开放协议，旨在解决工具接入的碎片化问题。它定义了工具的标准格式和通信方式，让模型能够以统一的方式调用任何符合 MCP 标准的服务。

MCP 的角色：

• 工具描述标准化：所有工具都通过相同的 JSON 结构描述。
• 协议统一：工具调用请求通过 JSON-RPC 传输，与具体实现语言无关。
• 动态发现：MCP 客户端可以查询可用的工具列表。

在 MCP 架构中，模型返回的 tool_calls 由 MCP Client 转发给对应的 MCP Server 执行，结果再返回给模型。

4.2 Skill：模块化任务流程以及工作原理解构

开发者肯定会有个疑问：既然已经有了MCP能干活了，那为什么还需要Skill呢？ 其实顺着疑问反推就可以大概知道Claude为什么要提出这个“约定”：

• 1.经济性考虑：模块化加载 = 算力最优解。模型上下文的冗余非常大，输入和输出都是token加上反复召回拼接，那就需要开发者精简且只保留需要的关键的部分的提示词，模块化加载提示词几乎是当下最优解，否则堆积拼接一堆用不到的提示词token后果就是浪费太多输入和输出算力，算力成本加上反复召回带来的token的整体消耗，不够经济不环保，这是最直接的原因；
• 2.行为控制：减少自回归的”注意力噪声”，现有模型本身是自回归式的，上下文堆积得越多，干扰和无意义的算力也就越多，会影响最终的生成结果，就像你让模型查天气，没必要也把其他任务也也决策一遍，Skill就是告诉模型怎么专注的干事情，在提示词层面做到减少干扰；
• 3.MCP解决了”怎么调”的工程问题，Skill匹配解决的是”调哪个”的智能决策问题。MCP像是管道，Skill就行阀门，两者不是替代关系是分层的策略思维——只有阀门精准控制，管道中的算力才能高效流向正确的业务终点。

设想一下如果没有Skill的加载机制会导致哪些问题：

归根结底，不是”有了MCP为什么还需要Skill”，而是”只有MCP的话，成本和复杂度扛不住”才有了Skill。
Skill 解决了“模块化”和“执行顺序”的问题，让模型能够遵循业务流程严谨地完成复杂的任务。

这就又引出一个新的问题：skill怎么解决模块化加载的问题？其实原理也很简单，方法也很多，Skill其实并没有规定严格的技术选型，是一种“约定”而非“规范”，还是一开始那句话：不要用结构化的定式思维路径来考虑问题，摒弃一些传统思维就会豁然开朗，优先用最低成本的方式匹配或者组合，原则上只要能达到在保持精准度的基础上最大限度减少大模型的Prompt的拼接总量就是最佳方案。以下是常见的策略：

匹配策略技术选型的问题实践经验：
可以自由组织匹配策略，从业务的角度来说，规则匹配和Embedding检索都能满足绝大部分常见，还能节省大量token消耗。
举个最典型的场景：用户提问里包含“订单”这个词，那就可以直接关键词匹配订单相关的Skill，抓取出来，这样就省去很多其他Skill的提示词，简洁高效。

Skill 作为一个模块化的按需提取加载的“能力包”，包含：

• 元数据：技能的名称和简短描述。
• SKILL.md：核心指令文档，告诉模型在特定任务中应该按什么步骤调用哪些工具。
• 相关资源：示例、参考文档等。

Skill 的运作流程：

1. 系统加载所有技能的元数据（轻量级清单）。
2. 根据用户问题，匹配最相关的技能。
3. 动态加载该技能的 SKILL.md 到上下文。
4. 模型根据技能指引，按顺序生成工具调用。

4.3 MCP 与 Skill 的协同

结合 MCP 和 Skill，一个完整的 Agent 工作流如下：

1. 用户输入：例如“分析特斯拉股票并生成简报”。
2. 技能匹配：系统匹配到 financial_analysis 技能，加载其 SKILL.md。
3. 构建提示词：将用户问题、技能指令、工具列表（来自 MCP）合并后发给模型。
4. 模型决策：模型根据技能指引，依次输出工具调用（如 get_stock_data → calculate_ratios → generate_charts）。
5. MCP 转发：MCP Client 将每次调用转发给对应的 MCP Server。
6. 结果返回：工具执行结果通过 MCP 返回给模型，模型逐步推理并最终生成简报。

第五部分：思维发散

5.1 多模态输入的处理

现代 Agent 需要处理图像、文档等多模态数据。当用户上传图片时，系统通常通过两种方式传递给模型：

• 二进制流：将图片数据作为请求的一部分发送。
• URL：提供图片的在线地址。

模型后端通过视觉编码器（如 ViT）将图像转换为视觉 token，再与文本 token 拼接，利用跨模态注意力机制理解图文关系。这一过程对开发者透明，但需要注意不同模型对图像尺寸、格式的限制。

5.2 模型自主生成工具的可能性

作为开发者会自然有个疑问：“能否让模型自己生成工具函数并执行？”，这正是 Agent 的未来方向之一。
目前已有探索（如代码解释器、ToolMaker），但面临安全性和可控性挑战。解决方案包括：

• 沙箱隔离：生成的代码在受限环境中执行。
• 策略约束：通过类似 Skill 的方式框定权限范围（如只允许生成数据处理类工具）。
• 动态注册：模型生成工具描述后，需经审核才能注册为 MCP 服务。

这相当于让模型从“使用工具”进化为“创造工具”，但必须在严格的安全边界内，重点是限定责任主体，要解决安全和可控的问题。

5.3 Agent 开发的本质：构建 Prompt 的艺术

回顾整个过程会发现：无论采用 ReAct、Function Calling、MCP 还是 Skill，所有工作的最终产出都是一个被精心构造的 Prompt。这个 Prompt 包含了任务描述、工具说明书、执行流程指南，全部以文本形式输入给模型。模型的理解能力决定了 Agent 的成败，而开发者的价值在于通过 Prompt 工程最大化发挥模型的能力。

第六部分：企业数据智能体从思考到执行的反思和挑战：大模型智能体中推理过程的可视化与 RDBMS 数据库操作的安全实践

企业业务落地的关键典型场景之一就是企业数据的处理，Text2SQL几乎是不可绕过的关键部分，接下来讲针对数据处理的技术细节阐述。
⚠️补充说明：为方便理解重点部分，会省去基础安全以及认证相关的细节，围绕Text2SQL（NL2SQL）进行原理解构。Text2SQL的实现方案有很多，以下只提供一种简单可行的思路参考。

数据智能体谜思

随着大语言模型（LLM）能力的不断增强，智能体（Agent）应用正从简单的问答向自主执行复杂任务演进。在这一过程中，模型需要将内在的推理能力与外部工具（如数据库、API）结合，形成“思考-行动-观察”的闭环。然而，如何清晰地呈现模型的推理过程？如何确保自然语言到数据库查询（Text-to-SQL）的准确转换？当操作从查询扩展到数据修改时，又如何守住安全底线？本文将从这三个核心问题出发，循序渐进地探讨大模型智能体在数据库操作场景下的设计原则与最佳实践。

一、双引擎：模型自身推理与 ReAct 模式的关系

1.1 概念界定

• 模型自身推理：指大模型在生成最终答案前，内部产生的思维链（Chain-of-Thought, CoT）。它是模型的“黑盒思考”，通常包含逻辑推导、中间结论、自我质疑等。
• ReAct 模式：一种智能体设计框架，全称“推理+行动”（Reason+Act）。它引导模型交替进行推理和工具调用，并将外部观察结果作为下一轮推理的输入，形成循环。

1.2 两者关系：引擎与方向盘

可以把模型自身推理比作汽车的引擎——它提供动力（理解、生成、逻辑能力），而 ReAct 模式则是方向盘和路线图——它规定了解问题的宏观结构（思考→行动→观察→再思考）。没有引擎，方向盘毫无意义；没有方向盘，引擎只能直线前进，无法应对复杂路况。

在实践中，ReAct 模式通过提示词（prompt）将模型的自由推理引导至预设的轨道上，让模型不仅“想”，还能“做”。

1.3 对话中的呈现策略

为了让用户既了解进度又不被技术细节淹没，我们采用分层呈现原则：

• 内部思维链（模型自身推理）：默认隐藏，放入可折叠的“显示思考过程”面板。这既满足了专业用户的深度需求，也避免了主对话的冗杂。
• 外部行动（ReAct 模式中的工具调用）：实时展示在动态状态面板，例如：“正在搜索天气数据…”、“已调用 SQL 生成器，正在构建查询…”。行动完成后，再在主对话区输出最终整合的回答。

这种设计使用户能感知智能体的工作进度，同时保持对话的简洁性。

二、Text-to-SQL：从自然语言到数据库查询的智能转换

2.1 核心挑战

将自然语言转换为 SQL 查询（Text-to-SQL）是数据库智能体的核心能力，但也面临四大挑战：

• 自然语言的歧义性：“上个月卖得最好的产品”——“上个月”是自然月还是过去30天？“最好”是按销售额还是销售量？
• Schema 的复杂性：大型数据库可能有数百张表，字段命名可能不直观（如 prod_cd 代表产品代码）。模型需准确映射到正确的表和字段。
• SQL 语法的精确性：多表 JOIN 条件、聚合函数、WHERE 子句的逻辑关系必须准确无误，否则会导致语法错误或逻辑错误。
• 数据安全与权限：生成的 SQL 必须符合用户权限，避免越权查询或注入攻击。

2.2 ReAct 模式如何提升准确性

ReAct 模式通过“推理-行动-观察”循环，将 Text-to-SQL 分解为多个可控步骤：

2.2.1 多步推理分解复杂查询

模型内部先进行显式推理：

用户想查“上个月每个品类的销售额” → 需要先确定“上个月”的时间范围 → 找到“销售额”字段（可能在订单明细表）→ 按品类分组聚合。

2.2.2 工具调用：按需获取 Schema 信息

模型不必记忆整个数据库结构，而是通过工具动态查询：

• 行动：调用 get_table_schema("products") 查看 products 表字段。
• 观察：发现字段 category_id 和 category_name，从而确定如何关联类别表。

2.2.3 生成 SQL 后的验证与反思

模型生成 SQL 后，进入验证阶段：

• 行动：调用 validate_sql_syntax(sql) 检查语法。
• 观察：若报错，则反思错误原因，修正后重新生成。
• 甚至可以执行 EXPLAIN 或采样查询，提前发现问题。

2.2.4 结合用户反馈修正

当执行结果不符合预期时，模型主动引导用户补充信息，进入下一轮推理。

2.3 对话中的呈现技巧

• 展示生成的 SQL：以可折叠的代码块呈现，并标注“这是我理解的查询，即将执行的 SQL：”。允许高级用户编辑 SQL 后重新执行。
• 分步推理展示（可选）：提供“显示思考过程”折叠面板，展示模型的多步推理，增加透明度。
• 结果解释：执行后附上一句解释，帮助用户理解数据与问题的对应关系。若结果为空，说明可能原因并提出建议。

三、安全升级：当 RDBMS 操作从“读”扩展到“写”

对于查询（SELECT），即使 SQL 出错，最坏结果也只是查不到数据；但对于写操作（INSERT/UPDATE/DELETE），一旦出错可能导致数据污染、误删甚至业务瘫痪。因此，写操作必须采用更为严格的安全方案。

3.1 核心原则：读写分离，人机协同

⚠️注意事项：其实AI业务绝大部分都是 Read 读为主，写在AI场景下可能会产生大量碎片化的数据，以下只针对企业特定场景下的AI数据写入的场景作实践分析（如用于生产环境请严格自行做好安全评估）。

绝不让模型直接执行写操作 SQL。模型应扮演“智能解析器”角色，负责理解意图和提取参数，而最终执行权由受控的后端代码和人工审批流程掌控。

3.2 分层安全方案

3.2.1 架构隔离：只读账号

为模型分配的数据库账号默认只有 SELECT 权限，从物理上杜绝写操作。写操作必须通过专门的后端 API 进行。

3.2.2 自然语言转“参数化命令”

不让模型拼接 SQL，而是让模型输出结构化的意图 JSON：

1
2
3
4
5

{
  "action": "update_order_status",
  "order_id": "12345",
  "new_status": "已发货"
}

后端接收到 JSON 后，通过预编译的、参数化的 SQL 执行修改。这样 SQL 结构固定，模型只能影响参数值，大大降低了风险。

3.2.3 预览与二次确认

对于高风险操作，执行前生成修改前后的数据对比，要求用户点击“确认修改”后才真正提交。这属于关键的人机协同环节。

3.2.4 事务与“试运行”

利用数据库事务特性：

• 开启事务（BEGIN）
• 执行写操作
• 让用户或程序校验结果（例如预览受影响数据）
• 若不符则回滚（ROLLBACK），确认无误后提交（COMMIT）

3.2.5 多人审批流

对于极敏感操作（如删除用户、批量调价），接入正式审批流程，需主管或管理员审批通过后，后端才执行。

3.2.6 审计日志

记录所有由模型触发的数据库操作，包括操作人、自然语言原文、生成的 SQL/JSON、执行时间、影响行数等，便于追溯和审计。

3.3 写操作安全流程示例（仅供一般性参考，关键执行可引入人工审计）

1. 意图识别：模型判断用户请求为“修改订单状态”。
2. 参数抽取：模型输出 JSON 意图，而非 SQL。
3. 权限校验：后端检查当前用户是否有修改该订单的权限。
4. 预览与确认：生成修改前后对比，要求用户二次确认。
5. 安全执行：后端通过参数化 API 执行更新。
6. 结果通知：执行成功，通知用户，并记录审计日志。

通过这一流程，模型实现了智能解析，而安全底线由可控的后端和人工把关共同守护。

心得感悟

大模型智能体的魅力在于将强大的内在推理能力与外部工具结合，从而完成复杂任务。

在企业级RDBMS数据库操作典型场景中，我们通过 ReAct 模式将模型推理结构化，通过分层呈现让用户理解智能体的工作过程，通过读写分离与审批机制确保数据安全。

未来，随着模型能力的提升和工具的成熟，我们可以期待：

• 更精细的权限控制：基于自然语言的动态权限判断（即：动态安全可控的信任）。
• 多轮交互修正：模型与用户在数据操作过程中进行深度协作。
• 可视化数据操作：不仅返回文本结果，还能通过图表、仪表盘等形式呈现数据，提升用户体验。

其实Agent从技术开发的角度来说没什么太多神秘的东西，行业迄今造了那么多规范和概念，核心围绕一点：系统化告诉大模型需求，发挥大模型的 “思维引擎” 能力尝试去理解人类的需求，仅此而已。

从思考到执行，每一步都需要精心设计。只有当推理透明、行动可控、安全到位时，大模型智能体才能真正成为值得信赖的数据助手。但要切记一点：不要为了模型而模型，绝大部分任务的执行还是要靠传统业务的健壮性支撑。

AI不是万能药，这是AI难以彻底替代程序员的核心原因之一，工具毕竟是服务于人的，远离互联网上的眼球流量经济聒噪，将更多精力放在AI工程化上才是普通程序员避免焦虑的最佳方式之一。

AI Agent 的开发是一个从“让模型能调用工具”到“让模型会规划任务”的演进过程。从 ReAct 的简单循环，到 Function Calling 的工程化交互，再到 MCP 和 Skill 带来的标准化与模块化，每一步都在让智能体更加自主、可靠、高效。

未来，随着模型能力的提升和安全机制的发展，Agent 将能够动态创造工具、自主适应新环境，成为真正的通用问题解决者。而开发者需要持续关注 Prompt 设计的艺术与工程实践的平衡，多总结模型在通用性设计上的规律和考量，在释放模型潜力的同时守住安全与可控的底线。

交流联系方式: ljq@GitHub
微信 WeChat：labsec
邮箱 Email: ljqlab@163.com

在 Go 语言的生态系统中，数据库访问层的选择一直是一个充满争议的话题。早期，GORM 凭借其“魔法”般的便捷性迅速占领了市场。然而，随着微服务架构的演进和对性能、可维护性要求的提高，越来越多的团队开始重新审视 ORM（对象关系映射）带来的代价。

一、ORM 本身的困境：魔法还是负担？

在 Go 语言哲学中，”Explicit is better than implicit”（显式优于隐式）是一条金科玉律。然而，传统的 ORM 如 GORM 往往违背了这一原则：

1. 运行时错误：字段名拼写错误、SQL 语法问题往往在运行时才暴露，缺乏编译期检查。
2. 性能开销：大量使用反射（Reflection）来映射结构体和数据库行，带来不必要的 CPU 和内存消耗。
3. 黑盒 SQL：ORM 生成的 SQL 难以预测，复杂查询优化困难，DBA 审查 SQL 变得痛苦。
4. 学习成本：开发者需要学习 ORM 特有的 API（如 Where, Preload, Scopes），而不是标准的 SQL。

sqlc 的出现，正是为了解决这些问题。 它不是一个运行时库，而是一个编译器。它读取开发者编写的 SQL 查询语句，分析数据库 Schema，然后生成类型安全、 idiomatic（地道）的 Go 代码。

二、为什么 sqlc 代表未来？

1. 编译期类型安全 (Type Safety)

这是 sqlc 最大的杀手锏。如果开发者的数据库表中有一个 int4 字段，生成的 Go 代码中对应字段就是 int32。如果开发者试图传入 string，代码将无法通过编译。如果开发者修改了数据库 Schema 但忘记更新查询，sqlc generate 会直接报错。这将大量的数据库错误左移到了开发阶段。

2. 零反射，高性能

sqlc 生成的代码使用标准的 database/sql 或 pgx 接口，直接扫描行数据到结构体。没有反射，没有动态构建查询的开销，性能几乎等同于手写原生 SQL。

3. 开发者写的 SQL 就是开发者运行的 SQL

没有隐藏的 JOIN，没有自动生成的 WHERE 条件。开发者完全掌控 SQL 语句，方便进行索引优化、执行计划分析（EXPLAIN）和 DBA 审查。

4. 维护即文档

query.sql 文件本身就是最好的文档。新加入的开发者可以直接阅读 SQL 文件了解业务逻辑，而不需要在 Go 代码和 ORM 文档之间来回切换。

5. 来看sqlc的设计基本构成：

flowchart TD    subgraph Input ["输入层"]        A["SQL 查询文件
query.sql"]        B["数据库 Schema
DDL 语句"]        C["配置文件
sqlc.yaml"]    end    subgraph Core ["核心引擎"]        D["Parser
SQL 语法分析"]        E["Analyzer
类型推断 & 验证"]        F["Generator
代码模板引擎"]    end    subgraph Output ["输出产物"]        G["models.go
结构体定义"]        H["query.sql.go
查询实现"]        I["db.go
Querier 接口"]    end    subgraph Eco ["生态集成"]        J["数据库驱动
pgx / database/sql"]        K["迁移工具
golang-migrate"]        L["测试支持
Interface Mock"]    end    subgraph Phil ["设计哲学"]        M["零 ORM"]        N["编译期类型安全"]        O["零反射高性能"]    end    A --> D    B --> D    C --> F    D --> E    E --> F    F --> G    F --> H    F --> I    H --> J    I --> J    K -.-> B    L -.-> I    Core --> Phil    M --> Core    N --> Core    O --> Core    style Input fill:#e1f5fe,stroke:#01579b,stroke-width:2px;    style Core fill:#fff3e0,stroke:#e65100,stroke-width:2px;    style Output fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;    style Eco fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;    style Phil fill:#ffebee,stroke:#b71c1c,stroke-width:2px;

三、实战：构建一个类型安全的用户服务

接下来，我们将通过一个典型的用户管理场景（CRUD），演示如何使用 Go + Postgres + sqlc 构建应用。

1. 环境准备

确保开发者安装了以下工具：

• Go (1.20+)
• Docker (用于运行 Postgres)
• sqlc (go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest)

2. 初始化项目结构

1
2
3

mkdir sqlc-demo && cd sqlc-demo
go mod init sqlc-demo
mkdir db query schema

3. 定义数据库 Schema

在 schema/users.sql 中定义我们的表结构：

1
2
3
4
5
6
7
8

-- schema/users.sql
CREATE TABLE users (
    id         BIGSERIAL PRIMARY KEY,
    username   VARCHAR(50) NOT NULL UNIQUE,
    email      VARCHAR(100) NOT NULL UNIQUE,
    age        INT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

4. 编写 SQL 查询

在 query/user.sql 中编写原生 SQL。注意 sqlc 的注释语法，用于指示操作类型。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

-- name: CreateUser :one
INSERT INTO users (username, email, age)
VALUES ($1, $2, $3)
RETURNING *;

-- name: GetUser :one
SELECT * FROM users
WHERE id = $1;

-- name: ListUsers :many
SELECT * FROM users
ORDER BY id
LIMIT $1 OFFSET $2;

-- name: UpdateUser :one
UPDATE users
SET username = $2, email = $3, age = $4
WHERE id = $1
RETURNING *;

-- name: DeleteUser :exec
DELETE FROM users
WHERE id = $1;

• :one 表示查询返回单行。
• :many 表示查询返回多行。
• :exec 表示不返回数据（如 DELETE, UPDATE 无 RETURNING）。

5. 配置 sqlc

创建 sqlc.yaml 配置文件。这是控制代码生成的核心。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

version: "2"
sql:
  - schema: "schema"
    queries: "query"
    engine: "postgresql"
    gen:
      go:
        package: "db"
        out: "db"
        sql_package: "pgx/v5"  # 推荐使用 pgx，性能优于 database/sql
        emit_json_tags: true   # 生成 json tag，方便 API 序列化
        emit_prepared_queries: false
        emit_interface: true   # 生成接口，方便 Mock 测试
        emit_empty_slices: true

6. 生成 Go 代码

运行生成命令：

1

sqlc generate

此时，db 目录下会生成 models.go (数据模型), query.sql.go (查询实现), 和 db.go (事务管理)。

生成的代码长什么样？（节选）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// db/models.go
type User struct {
ID        int64     `json:"id"`
Username  string    `json:"username"`
Email     string    `json:"email"`
Age       int32     `json:"age"`
CreatedAt time.Time `json:"created_at"`
}

// db/query.sql.go
const getUser = `-- name: GetUser :one
SELECT id, username, email, age, created_at FROM users WHERE id = $1
`

func (q *Queries) GetUser(ctx context.Context, id int64) (User, error) {
    // ... 标准 pgx 扫描代码，无反射
}

7. 业务层集成

现在，我们编写 main.go 来连接数据库并调用生成的代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

// main.go
package main

import (
"context"
"fmt"
"log"
"time"

"sqlc-demo/db"

"github.com/jackc/pgx/v5/pgxpool"
)

func main() {
ctx := context.Background()

// 1. 连接数据库 (请根据实际情况修改 DSN)
connStr := "postgres://postgres:password@localhost:5432/sqlc_demo?sslmode=disable"
pool, err := pgxpool.New(ctx, connStr)
if err != nil {
log.Fatalf("Unable to connect to database: %v\n", err)
}
defer pool.Close()

// 2. 初始化 sqlc Queries
queries := db.New(pool)

// 3. CRUD 演示

// Create
user, err := queries.CreateUser(ctx, db.CreateUserParams{
Username: "gopher",
Email:    "gopher@go.dev",
Age:      5,
})
if err != nil {
log.Fatalf("Create failed: %v", err)
}
fmt.Printf("Created User: %+v\n", user)

// Get
fetchedUser, err := queries.GetUser(ctx, user.ID)
if err != nil {
log.Fatalf("Get failed: %v", err)
}
fmt.Printf("Fetched User: %+v\n", fetchedUser)

// Update
updatedUser, err := queries.UpdateUser(ctx, db.UpdateUserParams{
ID:       user.ID,
Username: "master_gopher",
Email:    user.Email,
Age:      6,
})
if err != nil {
log.Fatalf("Update failed: %v", err)
}
fmt.Printf("Updated User: %+v\n", updatedUser)

// List
users, err := queries.ListUsers(ctx, db.ListUsersParams{
Limit:  10,
Offset: 0,
})
if err != nil {
log.Fatalf("List failed: %v", err)
}
fmt.Printf("Total Users: %d\n", len(users))

// Delete
err = queries.DeleteUser(ctx, user.ID)
if err != nil {
log.Fatalf("Delete failed: %v", err)
}
fmt.Println("User deleted successfully")
}

8. 运行与验证

1. 启动 Postgres: docker run --name pg -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres
2. 执行 Schema: 使用 psql 或 DBeaver 运行 schema/users.sql。
3. 运行程序: go run main.go

开发者将看到控制台输出完整的 CRUD 流程，且所有数据结构都是强类型的。

四、进阶最佳实践

在实际生产环境中，使用 sqlc 还需要注意以下几点：

1. 数据库迁移 (Migrations)

sqlc 不负责数据库迁移。建议配合 golang-migrate 或 atlas 使用。

• 流程：编写迁移文件 -> 执行迁移 -> 运行 sqlc generate。
• CI/CD 中应确保 Schema 是最新的，否则生成会失败。

2. 事务处理

sqlc 生成的 Queries 结构体可以绑定到 *pgxpool.Pool 或 *pgx.Tx。
在需要事务时，手动开启事务，将 Tx 传给 db.New(tx)，这样所有的查询都会在同一个事务中执行。

1
2
3
4
5
6
7
8
9

tx, err := pool.Begin(ctx)
if err != nil { return err }
defer tx.Rollback(ctx)

qtx := db.New(tx)
// 使用 qtx 进行多次操作
err = qtx.CreateUser(...)
err = qtx.UpdateUser(...)
tx.Commit(ctx)

3. 处理 NULL 值

Postgres 中的 NULL 在 Go 中需要特殊处理。sqlc 支持配置 override，将 SQL 的 NULL 类型映射为 sql.NullString 或指针类型（如 *string）。推荐使用指针类型，更符合现代 Go 习惯。

1
2
3
4
5
6

overrides:
  go:
    - column: "users.email"
      go_type:
        type: "string"
        pointer: true

4. 单元测试

由于 sqlc.yaml 中开启了 emit_interface: true，生成的 Querier 接口使得 Mock 测试变得非常容易。开发者可以轻松实现该接口来测试业务逻辑，而无需连接真实数据库。

五、零 ORM 的代价与思考

虽然 sqlc 很强大，但它并非银弹。

优点总结：

• ✅ 编译期捕获 SQL 错误。
• ✅ 性能优异，无反射。
• ✅ SQL 可控，易于优化。
• ✅ 代码即文档。

潜在挑战：

• ⚠️ 样板代码：虽然生成了代码，但文件数量会增加。
• ⚠️ 动态查询困难：对于条件极其动态的搜索（如几十个可选过滤条件），拼接 SQL 会比 ORM 的 Where 链式调用繁琐（虽然 sqlc 支持 sqlc.arg 和 sqlc.narg 来处理可选参数，但有限度）。
• ⚠️ 学习曲线：团队需要熟悉 SQL 和 sqlc 的特定语法。

结论：
sqlc 代表的 “Zero ORM” 架构，本质上是 回归 SQL 本质。它承认 Go 是一门显式语言，承认 SQL 是关系型数据库最强大的交互方式。

对于追求高性能、高可靠性、且团队具备一定 SQL 能力的 Go 后端项目，sqlc 是目前最佳的数据库访问层选择。它消除了 ORM 的“魔法”，留下了工程的“确定性”。在微服务架构日益复杂的今天，这种确定性，恰恰是最宝贵的资产。

参考资料：

• sqlc 官方文档：https://docs.sqlc.dev/
• pgx 驱动选型：https://github.com/jackc/pgx

六、关于Postgres驱动的选型

Posgres官方建议：lib/pq 项目 README 明确写道：”We recommend using pgx which is actively maintained”（我们推荐使用 actively maintained 的 pgx），官方也是只提供基本的功能支持。

##jackc/pgx vs 其他 PostgreSQL Go 驱动库对比

📦 pgx 简介

jackc/pgx 是一个纯 Go 编写的 PostgreSQL 驱动和工具包，具有低层级、高性能的特点，同时暴露了 PostgreSQL 特有的功能。

🔍 核心区别对比

pgx vs lib/pq（最常用对比）

🚀 pgx 的核心优势

1. 双模式使用

1
2
3
4
5
6
7

// 模式1：使用 database/sql 兼容接口（迁移成本低）
import _ "github.com/jackc/pgx/v5/stdlib"
db, _ := sql.Open("pgx", "postgres://...")

// 模式2：使用原生 pgx 接口（性能最佳）
import "github.com/jackc/pgx/v5"
conn, _ := pgx.Connect(context.Background(), "postgres://...")

2. PostgreSQL 专属功能支持

• ✅ COPY 协议：批量导入速度比 INSERT 快 10-100 倍
• ✅ LISTEN/NOTIFY：实时消息推送
• ✅ 二进制格式编码：JSON/JSONB 编解码更快
• ✅ 批量查询（Batch）：减少网络往返
• ✅ 自动语句缓存：首次执行后复用执行计划

3. 高级类型映射

1
2
3
4
5
6
7

// 自动映射 PostgreSQL 数组 → Go slice
var tags []string
conn.QueryRow(ctx, "SELECT ARRAY['go','postgres']").Scan(&tags)

// inet/cidr → netip.Addr
var addr netip.Addr
conn.QueryRow(ctx, "SELECT '192.168.1.1'::inet").Scan(&addr)

4. 可观测性支持

• 内置 tracing 接口，支持 OpenTelemetry、X-Ray 等
• 可插拔日志适配器（zap、logrus、slog 等）

🤔 如何选择？

选择 pgx 原生接口 ✅

• 项目专用于 PostgreSQL
• 需要高性能或 PostgreSQL 特有功能
• 不依赖其他要求 database/sql 的库

选择 pgx + stdlib 适配器 ✅

• 现有代码使用 database/sql
• 需要平滑迁移，逐步采用 pgx 特性
• 团队对 pgx 原生 API 不熟悉

仍用 lib/pq ⚠️

• 项目需要支持多种数据库（MySQL/Postgres 等）
• 代码深度依赖 database/sql 且无迁移计划
• 极简依赖场景（但 pgx 也是纯 Go，无 CGO）

📊 性能对比（参考 jackc/go_db_bench）

1
2
3

pgx native interface:     ~1.0x (基准)
pgx via database/sql:     ~1.2x 
lib/pq via database/sql:  ~1.8-2.5x 慢于 pgx native

数据来源：jackc/go_db_bench

🤔 心得感悟

驱动选型：如果开发者正在使用或计划使用 PostgreSQL，pgx 是目前 Go 生态中最推荐的驱动。
既兼容标准库便于迁移，又能通过原生接口释放 PostgreSQL 的全部能力。lib/pq 虽仍可用，但已进入维护模式，新项目建议优先选择 pgx(截至2026年)。

先把结论说清楚：

Skills 的本质是“工程化的提示词扩展”，而不是直接执行的代码。
它通过一个标准化的目录（至少包含 SKILL.md）把：

• 领域知识
• 工作流程（SOP）
• 工具调用方式
  封装起来，在需要的时候“按需注入”给大模型。

AI 技能的成熟度，不取决于模型概率有多高，而取决于我们能在多大程度上用规则去驾驭这种概率。

Skills可以这么理解：

• Function Calling / MCP：让模型有“手脚”（能调用数据库、HTTP、脚本）
• Skills：给模型一整套“工作手册 + 流程图”（遇到某类任务，怎么分步骤搞定、用哪些工具）

所以，Skills 不自己跑业务逻辑，而是告诉“大模型：你该怎么干这件事”。
模型在推理过程中读取 SKILL.md 里的指令、示例、约束，然后自己生成调用工具/写代码/出报告等操作。

2. Skills 文件结构与三级渐进式加载

一个典型 Skill（以“电商”场景为例）目录：

1
2
3
4
5
6
7
8

ecommerce/
├── SKILL.md          # 必须存在：YAML 元数据 + Markdown 指令
├── scripts/          # 可选：脚本/代码片段（Python/Go 等）
│   ├── inventory.py
│   ├── order_processing.py
│   └── payment_gateway.py
└── reference/        # 可选：长文档、接口说明等
    └── api_spec.md

2.1 SKILL.md 长什么样？

典型结构（简化版）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
name: ecommerce
description: >-
  Handle e-commerce operations including product search, order placement,
  inventory checking, and payment processing. Use this skill when the user
  wants to browse products, add to cart, check availability or purchase.
# 还可以有 allowed-tools / denied-tools / tags 等字段
---

# E-commerce Operations Guide

## When to use this skill
- 用户提到“买/下单/购物车/商品推荐”
- 用户要查询订单、支付状态等

## High-level workflow
1. 识别用户意图（浏览 / 加购 / 下单 / 支付）
2. 如需读取/修改数据，调用相应工具（如 MCP + DB）
3. 严格按下面 SOP 执行，必要时多轮确认

## Product search
from scripts.inventory import search_products
results = search_products("laptop", min_price=500, max_price=1500)

## Order creation
from scripts.order_processing import create_order
order = create_order(user_id, [product_id1, product_id2], [1, 2])

上面这段 Markdown 不会被执行，而是在 Skill 被激活时整体注入到对话上下文中，成为大模型的“当前任务说明书”。

2.2 三层渐进式加载机制（省 Token 的关键）

1. Level 1：元数据层（永远加载）

   • 每个 SKILL.md 顶部的 YAML：name + description（几十 token）
   • Agent 启动时，一次性加载所有技能的“目录信息”，形成一个“技能列表”

2. Level 2：指令层（被判定相关时才加载）

   • 当模型根据描述判断：某个 skill 和当前任务有关
   • 系统才会读取该 skill 的 SKILL.md 正文，把详细流程/规则注入上下文

3. Level 3：资源层（按需加载）

   • 在 SKILL.md 内再引用 scripts/*.py、reference/*.md 等
   • 只有当模型确认为需要某个脚本/长文档时，系统才会再读这些文件部分内容注入

这样可以：

• 不把所有流程和文档一次性塞进提示词
• 又能保证在“真正需要时”，模型拥有足够的细节

3. 整体流程：Skills 与大模型的交互是一次还是多次？

答案：通常是多次交互，特别是复杂任务，会形成一个类似 ReAct 的“思考-行动-反馈”循环。

3.1 用 Mermaid 8.13.8 画出完整流程

下面这张图符合 Mermaid 8.13.8 语法，描绘了“用户一次请求，从 Skill 匹配到工具调用再到多轮交互”的流程：

flowchart TD    subgraph "系统初始化"        A["扫描所有 Skills 目录"] --> B["加载各 Skill 的 YAML 元数据 (name+description)"]        B --> C["构建技能索引 (按名称/领域/触发词)"]    end    subgraph "接收请求"        U["用户发起请求"] --> D["LLM 初次推理：理解意图"]        D --> E{"是否需要某个 Skill?"}    end    subgraph "Skill 选择与加载"        E -- "否" --> F["直接按通用能力回答\n(普通对话/无特殊流程)"]        E -- "是" --> G["根据元数据匹配相关 Skill 列表"]        G --> H["加载命中的 SKILL.md 正文\n(二级：详细指令/流程/SOP)"]    end    subgraph "Skill 驱动执行"        H --> I["LLM 读取 Skill 指令\n规划具体子任务"]        I --> J{"是否需要调用外部工具/MCP?"}        J -- "否" --> K["仅靠 LLM 推理生成答案\n(写文档/生成代码草稿等)"]        J -- "是" --> L["LLM 生成工具调用指令\n(如调用库存查询/创建订单)"]        L --> M["宿主程序执行工具/MCP 请求\n如 DB/HTTP/脚本"]        M --> N["拿到工具执行结果\n(库存/价格/订单号等)"]        N --> O["LLM 结合 Skill 规则\n+ 工具返回结果继续推理"]    end    subgraph "多轮迭代"        O --> P["生成当前轮回复\n(例如问用户确认/给出中间结果)"]        P --> Q{"任务是否已完成？"}        Q -- "否" --> D        Q -- "是" --> R["给出最终结果\n结束本轮会话"]    end    %% 样式    classDef process fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;    classDef decision fill:#fff7e6,stroke:#fa8c16,stroke-width:2px;    classDef toolCall fill:#f6ffed,stroke:#52c41a,stroke-width:2px;    classDef skill fill:#fcf4ff,stroke:#722ed1,stroke-width:2px;    class A,B,C,U,D,F,R,P process;    class E,J,Q decision;    class G,H,I,O skill;    class L,M,N toolCall;

可以看出：

• 简单问答：可能只有 1 次 LLM 调用
• 有 Skill 参与但不调工具：一般 1–2 次
• 有 Skill + 工具调用（典型电商：查商品+下单+支付）：
  常见是 多轮：2–4 次（含确认、错误重试）

4. 与 MCP 的关系：谁管“流程”，谁管“执行”

简单一句话概括：

• MCP = 手和眼：标准化接数据库、HTTP、文件系统等外部世界
• Skills = 脑中的流程图和规范书：告诉大模型在某类任务下按什么步骤，用哪些工具、遵守什么规则

在电商例子里：

• MCP 工具：
  • inventory_db：查库存
  • order_db：写订单
  • payment_api：调支付接口
• ecommerce Skill：
  • 定义“下单”要经历：确认商品 → 检查库存 → 计算总价 → 生成订单 → 发起支付 → 返回结果
  • 定义异常处理：库存不足/支付失败时如何沟通、是否推荐替代品等

5. 电商典型场景：从 Skill → 代码 → LLM 交互的完整链路

下面给出一个思路清晰、可直接改造为真实工程的 DEMO：

• Python：负责“电商后端逻辑” + 示例调用
• Go：同场景的强类型版本
• SKILL.md：告诉 LLM 如何“驾驶”这套逻辑

5.1 Python Demo：电商 Skill 的后端实现

5.1.1 库存管理 inventory.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# scripts/inventory.py
import sqlite3
from typing import List, Dict


class InventoryManager:
    def __init__(self, db_path: str = 'inventory.db'):
        self.conn = sqlite3.connect(db_path)
        self.create_tables()

    def create_tables(self):
        cursor = self.conn.cursor()
        cursor.execute("""
        CREATE TABLE IF NOT EXISTS products (
            id INTEGER PRIMARY KEY,
            name TEXT NOT NULL,
            description TEXT,
            price REAL NOT NULL,
            stock INTEGER NOT NULL
        )
        """)
        self.conn.commit()

    def add_product(self, name: str, description: str, price: float, stock: int) -> int:
        cursor = self.conn.cursor()
        cursor.execute(
            "INSERT INTO products (name, description, price, stock) VALUES (?, ?, ?, ?)",
            (name, description, price, stock),
        )
        self.conn.commit()
        return cursor.lastrowid

    def search_products(self, query: str,
                        min_price: float | None = None,
                        max_price: float | None = None) -> List[Dict]:
        cursor = self.conn.cursor()
        sql = "SELECT * FROM products WHERE name LIKE ?"
        params: list = [f"%{query}%"]

        if min_price is not None:
            sql += " AND price >= ?"
            params.append(min_price)
        if max_price is not None:
            sql += " AND price <= ?"
            params.append(max_price)

        cursor.execute(sql, params)
        rows = cursor.fetchall()
        columns = [d[0] for d in cursor.description]
        return [dict(zip(columns, row)) for row in rows]

    def check_inventory(self, product_ids: List[int], quantities: List[int]) -> bool:
        cursor = self.conn.cursor()
        for pid, qty in zip(product_ids, quantities):
            cursor.execute("SELECT stock FROM products WHERE id = ?", (pid,))
            row = cursor.fetchone()
            if not row or row[0] < qty:
                return False
        return True

    def deduct_stock(self, product_ids: List[int], quantities: List[int]) -> None:
        cursor = self.conn.cursor()
        for pid, qty in zip(product_ids, quantities):
            cursor.execute(
                "UPDATE products SET stock = stock - ? WHERE id = ?",
                (qty, pid),
            )
        self.conn.commit()

5.1.2 订单处理 order_processing.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# scripts/order_processing.py
import sqlite3
from datetime import datetime
from typing import List, Dict

from scripts.inventory import InventoryManager


class OrderManager:
    def __init__(self,
                 inventory_db_path: str = 'inventory.db',
                 orders_db_path: str = 'orders.db'):
        self.inventory = InventoryManager(inventory_db_path)
        self.orders_conn = sqlite3.connect(orders_db_path)
        self.create_tables()

    def create_tables(self):
        c = self.orders_conn.cursor()
        c.execute("""
        CREATE TABLE IF NOT EXISTS orders (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            user_id INTEGER NOT NULL,
            total_amount REAL NOT NULL,
            status TEXT NOT NULL,
            created_at TEXT NOT NULL
        )
        """)
        c.execute("""
        CREATE TABLE IF NOT EXISTS order_items (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            order_id INTEGER NOT NULL,
            product_id INTEGER NOT NULL,
            quantity INTEGER NOT NULL,
            price REAL NOT NULL
        )
        """)
        self.orders_conn.commit()

    def _get_product_price(self, product_id: int) -> float:
        c = self.inventory.conn.cursor()
        c.execute("SELECT price FROM products WHERE id = ?", (product_id,))
        row = c.fetchone()
        if not row:
            raise ValueError(f"Product {product_id} not found")
        return row[0]

    def create_order(self, user_id: int,
                     product_ids: List[int],
                     quantities: List[int]) -> Dict:
        if not self.inventory.check_inventory(product_ids, quantities):
            raise ValueError("Some products are out of stock")

        total_amount = 0.0
        for pid, qty in zip(product_ids, quantities):
            price = self._get_product_price(pid)
            total_amount += price * qty

        now = datetime.utcnow().isoformat()
        c = self.orders_conn.cursor()
        c.execute(
            "INSERT INTO orders (user_id, total_amount, status, created_at) "
            "VALUES (?, ?, ?, ?)",
            (user_id, total_amount, 'pending', now),
        )
        order_id = c.lastrowid

        for pid, qty in zip(product_ids, quantities):
            price = self._get_product_price(pid)
            c.execute(
                "INSERT INTO order_items (order_id, product_id, quantity, price) "
                "VALUES (?, ?, ?, ?)",
                (order_id, pid, qty, price),
            )

        self.orders_conn.commit()
        # 扣减库存
        self.inventory.deduct_stock(product_ids, quantities)

        return {
            "id": order_id,
            "user_id": user_id,
            "total_amount": total_amount,
            "status": "pending",
            "created_at": now,
        }

5.1.3 支付模拟 payment_gateway.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

# scripts/payment_gateway.py
import random
import sqlite3
from datetime import datetime
from typing import Dict


class PaymentGateway:
    def __init__(self, db_path: str = 'payments.db'):
        self.conn = sqlite3.connect(db_path)
        self.create_tables()

    def create_tables(self):
        c = self.conn.cursor()
        c.execute("""
        CREATE TABLE IF NOT EXISTS payments (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            order_id INTEGER NOT NULL,
            amount REAL NOT NULL,
            status TEXT NOT NULL,
            payment_method TEXT NOT NULL,
            transaction_id TEXT NOT NULL,
            created_at TEXT NOT NULL
        )
        """)
        self.conn.commit()

    def process_payment(self, order_id: int,
                        amount: float,
                        payment_method: str = "credit_card") -> Dict:
        # 模拟第三方支付：5% 概率失败
        transaction_id = f"txn_{random.randint(100000, 999999)}"
        status = "success" if random.random() > 0.05 else "failed"

        c = self.conn.cursor()
        now = datetime.utcnow().isoformat()
        c.execute(
            "INSERT INTO payments (order_id, amount, status, payment_method, "
            "transaction_id, created_at) VALUES (?, ?, ?, ?, ?, ?)",
            (order_id, amount, status, payment_method, transaction_id, now),
        )
        self.conn.commit()

        return {
            "order_id": order_id,
            "amount": amount,
            "status": status,
            "payment_method": payment_method,
            "transaction_id": transaction_id,
        }

5.1.4 一次完整“下单”流程（模拟 LLM 触发结果）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# demo_ecommerce.py
from scripts.inventory import InventoryManager
from scripts.order_processing import OrderManager
from scripts.payment_gateway import PaymentGateway

if __name__ == "__main__":
    # 1. 初始化库存
    inv = InventoryManager()
    # （示例简单起见，不清库；真实场景请先清空或迁移）
    p1 = inv.add_product("MacBook Pro", "Apple laptop", 1299.99, 10)
    p2 = inv.add_product("Dell XPS", "Windows laptop", 1199.99, 5)

    print("=== 搜索产品 ===")
    results = inv.search_products("laptop", min_price=1000, max_price=1500)
    for r in results:
        print(r)

    # 2. 创建订单
    print("\n=== 创建订单 ===")
    om = OrderManager()
    order = om.create_order(user_id=1, product_ids=[p1, p2], quantities=[1, 2])
    print("订单信息:", order)

    # 3. 发起支付
    print("\n=== 支付 ===")
    pg = PaymentGateway()
    payment = pg.process_payment(order["id"], order["total_amount"], "credit_card")
    print("支付结果:", payment)

在真正的 Agent 里，这一整套调用顺序由 Skill 指令 + LLM 推理自动决定，开发者主要负责：

• 把 SKILL.md 写清楚（输入/输出/流程）
• 把 scripts/*.py 写好（保证工具可被 LLM 调用）

5.2 Go Demo：同场景的强类型实现

在 Go 侧，我们做一件一样的事情：

• 用 inventory.go 管库存
• 用 order_processing.go 管订单
• 用 payment_gateway.go 模拟支付
• 用 main.go 串联一个端到端流程，仿真 “Skill 驱动 LLM 决策后的执行路径”。

以下只摘出重点结构，方便你迁移到自己的工程。

5.2.1 inventory.go 核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

package main

import (
    "database/sql"
    "fmt"

    _ "github.com/mattn/go-sqlite3"
)

type InventoryManager struct {
    DB *sql.DB
}

func NewInventoryManager(dbPath string) (*InventoryManager, error) {
    db, err := sql.Open("sqlite3", dbPath)
    if err != nil { return nil, err }

    _, err = db.Exec(`
        CREATE TABLE IF NOT EXISTS products (
            id INTEGER PRIMARY KEY,
            name TEXT NOT NULL,
            description TEXT,
            price REAL NOT NULL,
            stock INTEGER NOT NULL
        )
    `)
    if err != nil { return nil, err }

    return &InventoryManager{DB: db}, nil
}

func (im *InventoryManager) AddProduct(name, description string,
    price float64, stock int) (int64, error) {

    stmt, err := im.DB.Prepare(`
        INSERT INTO products (name, description, price, stock)
        VALUES (?, ?, ?, ?)
    `)
    if err != nil { return 0, err }
    defer stmt.Close()

    result, err := stmt.Exec(name, description, price, stock)
    if err != nil { return 0, err }
    return result.LastInsertId()
}

func (im *InventoryManager) CheckInventory(productID int64,
    quantity int) (bool, error) {

    var stock int
    err := im.DB.QueryRow(
        `SELECT stock FROM products WHERE id = ?`,
        productID,
    ).Scan(&stock)
    if err != nil { return false, err }
    return stock >= quantity, nil
}

5.2.2 order_processing.go 核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

type OrderManager struct {
    OrdersDB    *sql.DB
    InventoryDB *sql.DB
}

func NewOrderManager(invPath, ordersPath string) (*OrderManager, error) {
    invDB, err := sql.Open("sqlite3", invPath)
    if err != nil { return nil, err }
    ordersDB, err := sql.Open("sqlite3", ordersPath)
    if err != nil { return nil, err }

    // 创建 orders/order_items 表略
    // ...

    return &OrderManager{InventoryDB: invDB, OrdersDB: ordersDB}, nil
}

func (om *OrderManager) CreateOrder(userID int64,
    productIDs []int64, quantities []int) (*Order, error) {

    // 1. 检查库存并计算总价
    // 2. 事务中写入 orders + order_items
    // 3. 扣减库存
    // 4. 返回订单结构体
    // 代码略，逻辑与 Python 版本一致
    return &Order{/*...*/}, nil
}

5.2.3 payment_gateway.go 核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

type PaymentGateway struct {
    DB *sql.DB
}

func NewPaymentGateway(dbPath string) (*PaymentGateway, error) {
    db, err := sql.Open("sqlite3", dbPath)
    if err != nil { return nil, err }
    // 创建 payments 表略
    return &PaymentGateway{DB: db}, nil
}

func (pg *PaymentGateway) ProcessPayment(orderID int64,
    amount float64, method string) (*Payment, error) {

    // 使用 rand 模拟成功/失败，插入 payments 表
    // 返回 Payment 结构体
    return &Payment{/*...*/}, nil
}

5.2.4 main.go 串联

1
2
3
4
5
6
7
8
9
10
11
12
13
14

func main() {
    inv, _ := NewInventoryManager("inventory.db")
    // 清空旧数据略
    id1, _ := inv.AddProduct("MacBook Pro", "Apple laptop", 1299.99, 10)
    id2, _ := inv.AddProduct("Dell XPS", "Windows laptop", 1199.99, 5)

    om, _ := NewOrderManager("inventory.db", "orders.db")
    order, _ := om.CreateOrder(1, []int64{id1, id2}, []int{1, 2})
    fmt.Printf("Created order: %+v\n", order)

    pg, _ := NewPaymentGateway("payments.db")
    payment, _ := pg.ProcessPayment(order.ID, order.TotalAmount, "credit_card")
    fmt.Printf("Payment result: %+v\n", payment)
}

在真实 Skill 场景里，Go 服务可以以 HTTP / MCP Server 方式暴露出来，SKILL.md 里写清楚“如何调用它”，然后由 Agent 按流程自动组织调用。

6. 对初学者的实践建议

1. 先写一个简单 Skill
   比如：blog-post-writer，只写 SKILL.md，不接工具。感受一下 Skill 只是“结构化 prompt”。

2. 再写一个有脚本的 Skill
   如“批量重命名文件”、“简单报表统计”，在 scripts/ 里写 Python，然后在 SKILL.md 中示例如何调用。

3. 最后再上电商这类多步骤流程
   引入：

   • 多表数据
   • 多工具（DB + HTTP）
   • 多轮确认（地址确认、支付方式选择等）

4. 始终记住：Skill 不等于代码执行
   Skill 更像是：“给 AI 的 SOP + Playbook”
   代码只是被 Skill 引导的大模型在合适时机去调用的一部分。

接下来一步步拆分，按「一步步」拆解，让你能把 Skill 文件、MCP 工具声明和实际 JSON 往返串成一个完整心智模型：

一、完整 SKILL.md 文本（电商 Skill 示例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

---
name: ecommerce
version: 1.0
author: Agent Engineer
license: MIT
description: >-
  电商操作技能包，用于处理用户商品搜索、订单创建、支付处理等流程。
  该技能通过标准化接口调用后端服务，确保用户体验一致。
  用户触发关键词：购物、下单、购买、商品、订单、支付
allowed-tools:
  - search_products
  - check_inventory
  - create_order
  - process_payment
  - get_order_status
denied-tools: []
log-level: INFO
---

# E-commerce Skill 详细文档

## 1. 技能概述

本技能提供完整的电商操作流程，包括：
- 商品搜索与浏览
- 库存实时检查
- 订单创建与状态管理
- 在线支付处理
- 订单状态查询

当模型判断当前对话与「购物 / 下单 / 商品 / 订单 / 支付」相关时，应优先参考本技能中的流程与规范，并通过允许的工具完成操作。

## 2. 使用指南

### 2.1 触发条件

当用户请求满足以下任一条件时自动激活本技能：

- 包含「买」「购买」「下单」「购物车」「商品」「订单」「支付」等关键词
- 询问商品价格、库存、规格
- 要求创建订单或跟踪订单状态
- 要求完成支付或查询支付结果

### 2.2 执行总流程（高层）

用户请求 → 意图识别 → 技能匹配（ecommerce）→
（A）仅说明性问题 → 直接回答
（B）需要操作类动作 → 按 SOP 调用工具 →
工具结果合并 → 生成用户可读回复

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

当属于（B）操作类问题时，一般遵循以下顺序：

1. 明确用户意图（搜索 / 加购 / 下单 / 查询订单 / 支付等）
2. 如涉及真实数据操作，必须通过 MCP 工具完成（例如搜索商品、检查库存、创建订单、发起支付）
3. 每调用一次工具，都要结合工具返回结果和 Skill 中的规则，生成下一步动作（继续工具调用或向用户提问）
4. 所有面向用户的最终结论必须基于最新的工具结果，而不是模型自行假设

## 3. 详细 SOP（标准操作流程）

### 3.1 商品搜索流程

适用：用户希望浏览、筛选或对比商品。

```python
# 1. 从用户描述中抽取：
#    - 搜索关键词（如 "笔记本电脑"）
#    - 价格区间（min_price / max_price）
#    - 其他偏好（如 品牌、尺寸），可先体现在 query 文本中

# 2. 调用 search_products 工具：
#    - 必填：query
#    - 可选：min_price, max_price, sort_by
# 3. 根据返回结果：
#    - 按价格或相关性排序（如工具已排序则保持）
#    - 最多向用户展示 3~5 个候选商品
#    - 每个商品展示：名称、价格、库存简要、关键卖点
# 4. 向用户询问下一步：
#    - 让用户选择具体商品（用 product_id 或名称）
#    - 或者继续筛选（比如调整预算、品牌等）

3.2 下单流程

适用：用户已明确要购买的商品和数量。

流程概要：

1

用户确认购买 → 检查商品库存 → 创建订单 → 发起支付 → 返回结果

具体步骤：

1. 确认商品与数量
   • 如果用户没有给出清晰数量，默认数量为 1，但要在回复中明确说明并征求确认。
2. 库存检查
   • 使用 check_inventory 工具，对每个商品做检查：
     • 若任一商品库存不足：
       • 告知用户哪款商品不足、当前库存是多少
       • 不创建订单
       • 可建议降低数量或推荐其他商品（可再次调用 search_products）
3. 创建订单
   • 库存无问题时，调用 create_order 工具：
     • 携带用户 ID（由系统上下文提供）和商品清单
   • 根据返回的 order_id、total_amount 等，向用户确认订单已创建，状态通常为 pending（待支付）。
4. 支付流程
   • 询问用户是否立即支付以及支付方式（如「信用卡 / 支付宝 / 微信」）
   • 用户确认后，使用 process_payment 工具：
     • 传入 order_id 和 amount（使用订单返回的总金额）
   • 根据支付结果返回用户友好描述：
     • 成功：提供订单号、支付方式、交易号
     • 失败：给出失败原因，并建议重试或更换方式

3.3 订单查询流程

适用：用户想知道某个订单的状态。

1. 从用户问题中抽取订单号 order_id。
2. 使用 get_order_status 工具查询。
3. 将状态（如 pending / paid / shipped / completed / cancelled）翻译成自然语言，告知用户当前进度和下一步。

3.4 支付场景话术示例

1
2
3
4
5
6
7

# 支付成功：
# 「您的支付已成功，订单号是 {order_id}，交易号 {transaction_id}。
#   我们会尽快为您发货，请留意物流通知。」

# 支付失败：
# 「当前支付失败，原因：{message}。
#   您可以稍后重试，或者更换其他支付方式（如信用卡 / 支付宝 / 微信）。」

4. 工具调用规范（与 MCP 工具对应）

4.1 search_products

1
2
3
4
5
6
7
8
9

{
  "name": "search_products",
  "parameters": {
    "query": "string, 必填, 搜索关键词",
    "min_price": "number, 可选, 最小价格",
    "max_price": "number, 可选, 最大价格",
    "sort_by": "string, 可选, 排序方式：price_asc, price_desc, relevance"
  }
}

4.2 check_inventory

1
2
3
4
5
6
7

{
  "name": "check_inventory",
  "parameters": {
    "product_id": "integer, 必填, 商品ID",
    "quantity": "integer, 必填, 数量"
  }
}

4.3 create_order

1
2
3
4
5
6
7

{
  "name": "create_order",
  "parameters": {
    "user_id": "integer, 必填, 用户ID",
    "items": "array, 必填, 商品列表: [{\"product_id\": 1, \"quantity\": 2}]"
  }
}

4.4 process_payment

1
2
3
4
5
6
7
8

{
  "name": "process_payment",
  "parameters": {
    "order_id": "integer, 必填, 订单ID",
    "amount": "number, 必填, 金额",
    "method": "string, 可选, 支付方式: credit_card, alipay, wechat"
  }
}

4.5 get_order_status

1
2
3
4
5
6

{
  "name": "get_order_status",
  "parameters": {
    "order_id": "integer, 必填, 订单ID"
  }
}

5. 错误处理约定

• 库存不足：
  「商品 {product_id} 库存不足，当前库存为 {stock}，无法满足本次下单数量。」
• 支付失败：
  「支付失败，原因：{message}。建议您稍后重试或更换支付方式。」
• 系统错误 / 超时：
  「服务暂时不可用，请稍后再试。如果多次失败，可以联系客服处理。」

6. 典型对话示例（自然语言视角）

用户：我想买一台笔记本电脑，预算1000-1500元
AI：正在为您搜索符合条件的笔记本电脑…（工具：search_products）
AI：找到以下商品：…
AI：您想购买哪一款？或者需要我帮您下单？
用户：我要买 MacBook Pro，加到购物车
AI：正在检查库存…（工具：check_inventory）
AI：库存充足，是否立即下单？
用户：是的
AI：正在创建订单…（工具：create_order）
AI：订单创建成功，订单号是 #12345，请支付
AI：正在处理支付…（工具：process_payment）
AI：支付成功，您的订单已确认！

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

---

## 二、MCP 工具声明（与 Skill 一一对应）

下面是电商 Skill 对应的一组 MCP 工具声明（可以理解为「后端 API 规范」）。这里用接近 JSON Schema 的风格来写，方便直接落到 MCP / function calling 系统中。

```json
{
  "tools": [
    {
      "name": "search_products",
      "description": "根据关键词搜索商品，支持价格范围和排序",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "搜索关键词，如\"笔记本电脑\""
          },
          "min_price": {
            "type": "number",
            "description": "最低价格"
          },
          "max_price": {
            "type": "number",
            "description": "最高价格"
          },
          "sort_by": {
            "type": "string",
            "enum": ["price_asc", "price_desc", "relevance"],
            "description": "排序方式"
          }
        },
        "required": ["query"],
        "additionalProperties": false
      },
      "response_format": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": { "type": "integer" },
                "name":       { "type": "string"  },
                "price":      { "type": "number"  },
                "stock":      { "type": "integer" },
                "description":{ "type": "string"  }
              }
            }
          },
          "total": { "type": "integer" }
        }
      }
    },
    {
      "name": "check_inventory",
      "description": "检查特定商品的库存情况",
      "parameters": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "integer",
            "description": "商品ID"
          },
          "quantity": {
            "type": "integer",
            "description": "所需数量"
          }
        },
        "required": ["product_id", "quantity"],
        "additionalProperties": false
      },
      "response_format": {
        "type": "object",
        "properties": {
          "product_id": { "type": "integer" },
          "available":  { "type": "boolean" },
          "stock":      { "type": "integer" },
          "message":    { "type": "string"  }
        }
      }
    },
    {
      "name": "create_order",
      "description": "创建新订单",
      "parameters": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "integer",
            "description": "用户ID"
          },
          "items": {
            "type": "array",
            "description": "商品列表",
            "items": {
              "type": "object",
              "properties": {
                "product_id": { "type": "integer" },
                "quantity":   { "type": "integer" }
              }
            }
          }
        },
        "required": ["user_id", "items"],
        "additionalProperties": false
      },
      "response_format": {
        "type": "object",
        "properties": {
          "order_id":     { "type": "integer" },
          "status":       { "type": "string"  },
          "total_amount": { "type": "number"  },
          "items":        { "type": "array"   }
        }
      }
    },
    {
      "name": "process_payment",
      "description": "处理支付请求",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "integer",
            "description": "订单ID"
          },
          "amount": {
            "type": "number",
            "description": "支付金额"
          },
          "method": {
            "type": "string",
            "default": "credit_card"
          }
        },
        "required": ["order_id", "amount"],
        "additionalProperties": false
      },
      "response_format": {
        "type": "object",
        "properties": {
          "transaction_id": { "type": "string" },
          "status":         { "type": "string" },
          "message":        { "type": "string" }
        }
      }
    },
    {
      "name": "get_order_status",
      "description": "查询订单状态",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "integer",
            "description": "订单ID"
          }
        },
        "required": ["order_id"],
        "additionalProperties": false
      },
      "response_format": {
        "type": "object",
        "properties": {
          "order_id": { "type": "integer" },
          "status":   { "type": "string"  },
          "detail":   { "type": "string"  }
        }
      }
    }
  ]
}

可以看到：

• SKILL.md 里「工具调用规范」是人看的说明书；
• MCP 工具声明是机器可读的 JSON Schema；
• 两者字段一一对齐，就构成了「Skill 描述 ↔ 实际可调用工具接口」的桥梁。

三、实际运行时的 JSON 往返示例（逐步拆解模型如何决定调用什么）

下面用一个完整购买流程，把「对话 JSON」和「决策逻辑」一步步拆开，让你看到模型是如何在 Skill 指导下选工具、调用工具、再组织话术的。

3.1 完整 JSON 对话流

场景：用户想买一台预算在 1000–1500 元的笔记本，筛选后下单并完成支付。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

[
  {
    "role": "system",
    "content": "你是一个电商助手，使用ecommerce技能。所有商品搜索、订单、支付操作必须通过调用对应工具完成。工具列表和参数格式见技能文档。"
  },
  {
    "role": "user",
    "content": "我想买一台笔记本电脑，预算在1000-1500元之间，有什么推荐吗？"
  },
  {
    "role": "assistant",
    "content": null,
    "function_call": {
      "name": "search_products",
      "arguments": {
        "query": "笔记本电脑",
        "min_price": 1000,
        "max_price": 1500,
        "sort_by": "price_asc"
      }
    }
  },
  {
    "role": "function",
    "name": "search_products",
    "content": {
      "results": [
        {
          "product_id": 101,
          "name": "Lenovo ThinkPad E14",
          "price": 1299.0,
          "stock": 15,
          "description": "14英寸商务本，Intel i5处理器"
        },
        {
          "product_id": 102,
          "name": "Dell Inspiron 15",
          "price": 1399.0,
          "stock": 8,
          "description": "15英寸轻薄本，AMD Ryzen5"
        },
        {
          "product_id": 103,
          "name": "HP Pavilion 14",
          "price": 1199.0,
          "stock": 20,
          "description": "14英寸全能本，Intel i5"
        }
      ],
      "total": 3
    }
  },
  {
    "role": "assistant",
    "content": "为您找到以下笔记本电脑（预算1000-1500元）：\n\n1. **Lenovo ThinkPad E14** - 1299元，库存15\n   14英寸商务本，Intel i5处理器\n2. **Dell Inspiron 15** - 1399元，库存8\n   15英寸轻薄本，AMD Ryzen5\n3. **HP Pavilion 14** - 1199元，库存20\n   14英寸全能本，Intel i5\n\n请问您想购买哪一款？或者需要了解更多信息？"
  },
  {
    "role": "user",
    "content": "我要购买Lenovo ThinkPad E14，加到购物车"
  },
  {
    "role": "assistant",
    "content": null,
    "function_call": {
      "name": "check_inventory",
      "arguments": {
        "product_id": 101,
        "quantity": 1
      }
    }
  },
  {
    "role": "function",
    "name": "check_inventory",
    "content": {
      "product_id": 101,
      "available": true,
      "stock": 15,
      "message": "库存充足，可购买"
    }
  },
  {
    "role": "assistant",
    "content": "Lenovo ThinkPad E14库存充足。是否立即为您下单？"
  },
  {
    "role": "user",
    "content": "是的，下单"
  },
  {
    "role": "assistant",
    "content": null,
    "function_call": {
      "name": "create_order",
      "arguments": {
        "user_id": 999,
        "items": [
          {
            "product_id": 101,
            "quantity": 1
          }
        ]
      }
    }
  },
  {
    "role": "function",
    "name": "create_order",
    "content": {
      "order_id": 2024001,
      "status": "pending",
      "total_amount": 1299.0,
      "items": [
        {
          "product_id": 101,
          "quantity": 1,
          "price": 1299.0
        }
      ]
    }
  },
  {
    "role": "assistant",
    "content": null,
    "function_call": {
      "name": "process_payment",
      "arguments": {
        "order_id": 2024001,
        "amount": 1299.0,
        "method": "credit_card"
      }
    }
  },
  {
    "role": "function",
    "name": "process_payment",
    "content": {
      "transaction_id": "txn_20240228_123456",
      "status": "success",
      "message": "支付成功"
    }
  },
  {
    "role": "assistant",
    "content": "订单创建成功！订单号是 **#2024001**，支付已确认。\n\n**订单详情：**\n- 商品：Lenovo ThinkPad E14\n- 数量：1\n- 总价：1299元\n- 支付方式：信用卡\n- 交易ID：txn_20240228_123456\n\n商品预计3个工作日内送达，感谢您的购买！"
  }
]

3.2 一步步拆解：模型是怎么「决定」调用什么的？

可以按时间线来看模型在做什么，每一步背后都在「执行 SKILL.md 里的 SOP + 工具声明」。

步骤 1：系统初始化

• JSON：

  1 2 3 4

  { "role": "system", "content": "你是一个电商助手，使用ecommerce技能。所有商品搜索、订单、支付操作必须通过调用对应工具完成。工具列表和参数格式见技能文档。" }

• 含义：
  • 告诉模型现在处于「电商助手」角色。
  • 告诉它必须使用 ecommerce Skill 中定义的工具来做操作类任务。
  • Skill 的 YAML 元数据（name/description/allowed-tools）已经在系统内部加载，这个 system 提示是对其的简化表达。

步骤 2：用户提出需求

• JSON：

  1 2 3 4

  { "role": "user", "content": "我想买一台笔记本电脑，预算在1000-1500元之间，有什么推荐吗？" }

• 模型根据 Skill 中的「触发条件」判断：
  • 含有「买」「预算」等词 → 命中电商 Skill。
  • Skill 指南里写明「商品搜索流程」要调用 search_products 工具。

步骤 3：模型按 Skill 规划，调用 search_products

• JSON：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  { "role": "assistant", "content": null, "function_call": { "name": "search_products", "arguments": { "query": "笔记本电脑", "min_price": 1000, "max_price": 1500, "sort_by": "price_asc" } } }

• 对应 Skill 中的流程：
  • 从用户语句抽取 query=笔记本电脑，min_price=1000, max_price=1500。
  • Skill 约定「商品搜索流程第 2 步：调用 search_products」。
  • MCP 工具声明提供了 search_products 的参数 JSON Schema，模型根据这个 Schema 组织参数。

步骤 4：工具执行并回填结果

• JSON：

  1 2 3 4 5 6 7 8

  { "role": "function", "name": "search_products", "content": { "results": [...], "total": 3 } }

• 这里是宿主程序（agent runtime）调用实际后端（DB / 服务）后，把结构化结果塞回对话流。
• 模型此时「看到的上下文」中已经包含了真实商品列表。

步骤 5：模型格式化商品列表，继续对话

• JSON：

  1 2 3 4

  { "role": "assistant", "content": "为您找到以下笔记本电脑（预算1000-1500元）：\n\n1. **Lenovo ThinkPad E14** - 1299元，库存15\n..." }

• 对应 Skill 中「搜索流程第 3 步」：
  • 「最多展示 3~5 个商品，并简要说明」。
  • 这里没有再调用工具，只是对已有结果做自然语言组织。

步骤 6：用户选择具体商品

• JSON：

  1 2 3 4

  { "role": "user", "content": "我要购买Lenovo ThinkPad E14，加到购物车" }

• 模型结合：
  • Skill 「下单流程：用户确认购买 → 检查库存 → 创建订单 → 发起支付」；
  • 刚才 search_products 的候选列表（其中有 Lenovo ThinkPad E14 对应的 product_id=101），
  • 推断要执行下一步 SOP：「检查库存」。

步骤 7：模型调用 check_inventory

• JSON：

  1 2 3 4 5 6 7 8 9 10 11

  { "role": "assistant", "content": null, "function_call": { "name": "check_inventory", "arguments": { "product_id": 101, "quantity": 1 } } }

• 决策依据：
  • Skill 的「下单流程」明确要求「先检查库存」；
  • MCP 工具声明告诉模型 check_inventory 的参数格式。
  • 用户只说「加到购物车」没说数量，Skill 中可以约定「未指明就默认 1 件，并在后续说明」，所以这里数量为 1。

步骤 8：库存检查结果返回

• JSON：

  1 2 3 4 5 6 7 8 9 10

  { "role": "function", "name": "check_inventory", "content": { "product_id": 101, "available": true, "stock": 15, "message": "库存充足，可购买" } }

步骤 9：模型根据结果询问是否下单

• JSON：

  1 2 3 4

  { "role": "assistant", "content": "Lenovo ThinkPad E14库存充足。是否立即为您下单？" }

• 对应 Skill 约定：
  • 库存充足时，不要直接自动下单，要确认一次（避免误操作）。

步骤 10：用户确认下单

• JSON：

  1 2 3 4

  { "role": "user", "content": "是的，下单" }

步骤 11：模型调用 create_order

• JSON：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  { "role": "assistant", "content": null, "function_call": { "name": "create_order", "arguments": { "user_id": 999, "items": [ { "product_id": 101, "quantity": 1 } ] } } }

• 决策依据：
  • SOP：「库存检查通过 → 创建订单」。
  • MCP 声明里 create_order 要求 user_id 和 items 数组，模型从对话上下文/系统上下文取到当前用户 id（这里假设为 999）。

步骤 12：订单创建结果

• JSON：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

  { "role": "function", "name": "create_order", "content": { "order_id": 2024001, "status": "pending", "total_amount": 1299.0, "items": [ { "product_id": 101, "quantity": 1, "price": 1299.0 } ] } }

步骤 13：模型调用 process_payment

• JSON：

  1 2 3 4 5 6 7 8 9 10 11 12

  { "role": "assistant", "content": null, "function_call": { "name": "process_payment", "arguments": { "order_id": 2024001, "amount": 1299.0, "method": "credit_card" } } }

• 决策依据：
  • Skill 支付流程规定「订单创建成功 → 请求支付方式 → 调用 process_payment」。
  • 这里 Demo 中简化为系统已经默认选择了 credit_card，在真实应用中应该多一轮与用户确认支付方式的对话。
  • amount 来自 create_order 的 total_amount 字段。