AI技能开发脚手架：从零构建大模型应用的标准化起点

1. 项目概述：一个为AI技能开发量身定制的脚手架

如果你正在或打算开发一个基于大语言模型的AI技能（Skill），无论是想集成到ChatGPT的GPTs里，还是想构建一个独立的AI Agent，那么你大概率会遇到一个共同的起点问题：从零开始搭建项目结构。你需要考虑如何定义技能描述、如何处理用户输入、如何调用外部API、如何管理对话状态、以及如何打包和部署。这个过程充满了重复性的基础工作，很容易让人在真正开始实现核心逻辑之前就感到疲惫。

NextFrontierBuilds/skill-scaffold这个项目，就是为了解决这个“从0到1”的痛点而生的。它是一个专门为AI技能开发设计的项目脚手架（Scaffold）。简单来说，它就像是一个已经为你搭好了骨架、装好了门窗、甚至预埋好了水电管道的“毛坯房”。你拿到手之后，不需要再从打地基开始，而是可以直接进行“精装修”——也就是专注于实现你这个技能独一无二的业务逻辑。

这个脚手架的核心价值在于“标准化”和“提效”。它定义了一套清晰、可扩展的项目结构，并预先集成了开发AI技能时最常用的一些工具和模式。无论你是想做一个查询天气的简单技能，还是一个需要多轮对话、复杂推理的智能助手，都可以基于这个脚手架快速启动，避免在项目组织、配置管理等琐事上浪费精力。对于有一定开发经验的工程师来说，它能让你跳过繁琐的初始化步骤；对于新手而言，它提供了一个最佳实践范例，是学习AI技能开发范式的绝佳起点。

2. 核心架构与设计哲学解析

2.1 为什么需要专门的AI技能脚手架？

在通用软件开发中，我们有像create-react-app、Vue CLI这样的脚手架，它们为Web前端开发提供了标准化的起点。AI技能开发，尤其是基于大语言模型（LLM）的对话式应用，虽然也属于软件范畴，但其开发范式与传统Web或移动应用有显著不同。

首先，AI技能的核心是“意图理解”和“对话管理”。用户输入是自然语言，充满不确定性，技能需要解析意图、抽取关键参数（实体），并根据上下文决定下一步动作。其次，AI技能常常需要与外部服务（API、数据库）进行交互，以获取信息或执行操作。再者，技能的描述（如名称、指令、能力声明）需要以一种机器可读且平台兼容的格式（如OpenAI的GPTs定义格式）来呈现。最后，开发流程可能涉及本地测试、模拟对话、一键部署到技能市场或平台。

一个优秀的脚手架，需要将这些共性需求抽象出来，并提供相应的解决方案。skill-scaffold正是基于这样的思考，其设计哲学可以概括为三点：

1. 约定优于配置（Convention Over Configuration）：它预先定义好了目录结构、文件命名规范和核心接口。开发者遵循这些约定，就能快速构建出结构清晰、易于维护的项目，无需在配置文件中花费大量时间。
2. 关注点分离（Separation of Concerns）：它将技能描述、业务逻辑、工具集成、对话状态管理等不同职责划分到不同的模块或目录中。这使得代码更易于理解和测试。
3. 开发者体验（Developer Experience）优先：它内置了本地开发服务器、对话模拟器、一键打包等工具链，让开发者能像开发Web应用一样，拥有热重载、实时调试的流畅体验。

2.2 项目结构深度拆解

让我们深入脚手架生成的项目骨架，看看每个部分都承担着什么职责。一个典型的基于skill-scaffold初始化的项目目录可能如下所示：

my-weather-skill/ ├── package.json ├── skill.json ├── src/ │ ├── index.ts │ ├── skill/ │ │ ├── WeatherSkill.ts │ │ └── types.ts │ ├── tools/ │ │ └── getWeather.ts │ └── utils/ │ └── apiClient.ts ├── tests/ │ └── WeatherSkill.test.ts └── README.md

关键文件与目录解析：

• skill.json(核心配置文件)：这是技能的“身份证”和“说明书”。它采用结构化格式（如遵循OpenAI的GPT定义规范）描述了技能的基本信息：

  • name: 技能名称，如“天气查询助手”。
  • description: 技能的功能描述，用于在技能商店中展示。
  • instructions: 给AI模型的系统指令，定义了技能的角色、能力边界和对话风格。这是决定技能行为质量的关键。
  • tools: 声明技能可以调用的外部工具列表，每个工具对应src/tools/下的一个函数。
  • files(可选): 技能可以访问的知识库文件列表。
  • 这个文件是技能与运行平台（如ChatGPT）之间的契约，脚手架会利用这个文件来生成部署包。

• src/index.ts(应用入口)：这是技能的启动文件。它通常负责初始化技能实例、注册工具、启动本地开发服务器或导出供服务器less函数使用的处理器（handler）。脚手架可能在这里集成了像Express.js这样的Web框架，提供一个/chat端点来接收和处理对话请求。

• src/skill/(技能核心逻辑)：这里是存放技能主类的地方。例如WeatherSkill.ts。这个类继承自脚手架提供的一个基类（如BaseSkill），并实现核心的生命周期方法：

  • onStart(conversation): 对话开始时的初始化逻辑。
  • onMessage(message, conversation): 处理用户每一条消息的核心方法。在这里，你可以编写逻辑来决定是直接回复，还是调用某个工具。
  • onStop(conversation): 对话结束时的清理逻辑。
  • 这个设计将技能建模为一个有状态的对象，conversation对象则封装了当前的对话历史、用户信息等上下文。

• src/tools/(工具函数目录)：AI技能通过“工具调用”（Tool Calling）来扩展能力。这个目录存放所有具体的工具实现。每个工具都是一个独立的函数，例如getWeather.ts中导出一个异步函数，它接收地点参数，调用外部天气API，并返回结构化的结果。脚手架会自动化地将这些函数注册到技能中，并在skill.json里声明。

• src/utils/(工具函数)：存放共享的辅助函数，如API客户端、数据格式化工具、日志工具等。

• tests/(测试目录)：包含对技能类和工具函数的单元测试和集成测试。良好的脚手架会预设测试框架（如Jest）的配置，鼓励测试驱动开发。

• package.json：定义了项目依赖、脚本命令。脚手架通常会预设好关键的scripts，如：

  • npm run dev: 启动带热重载的本地开发服务器。
  • npm run build: 将TypeScript代码编译成JavaScript，并打包技能。
  • npm run deploy: 将技能部署到目标平台（如某个技能市场）。
  • npm test: 运行测试套件。

注意：以上结构是一个通用性示例，NextFrontierBuilds/skill-scaffold的具体实现可能会有所不同，但其核心思想是相通的。关键在于理解这种将配置、逻辑、工具分离的架构模式，这是构建可维护、可扩展AI技能的基石。

3. 从零开始：使用脚手架快速初始化你的第一个技能

3.1 环境准备与项目创建

在开始之前，你需要确保本地开发环境已经就绪。首先，你需要安装Node.js（建议使用LTS版本，如18.x或20.x）和配套的包管理器npm或yarn。你可以从Node.js官网下载安装包。

接下来，创建你的技能项目。虽然skill-scaffold可能提供了类似create-skill-app的全局命令，但更常见的做法是直接使用Git克隆模板仓库，或者使用像degit这样的工具来获取干净的副本。这里我们假设使用克隆的方式：

# 克隆脚手架仓库（这里以假设的仓库地址为例） git clone https://github.com/NextFrontierBuilds/skill-scaffold.git my-first-skill cd my-first-skill # 安装项目依赖 npm install

安装完成后，花几分钟时间浏览一下package.json中的脚本和依赖项，以及根目录下的配置文件（如tsconfig.json、.eslintrc等），这有助于你了解项目的技术栈和代码规范。

3.2 核心配置文件skill.json的定制

这是你第一个需要深度修改的文件。打开skill.json，你会看到一个模板。你需要将其填充为你自己的技能信息。

{ "name": "你的技能名称", "description": "一段清晰描述技能功能的文字，例如：一个可以查询全球主要城市当前天气和未来预报的助手。", "instructions": "你是一个专业的天气查询助手。你的主要职责是根据用户提供的地点信息，查询并返回准确、友好的天气信息。如果用户没有提供明确地点，你应该礼貌地询问。你的回复应该简洁明了，包含温度、天气状况、体感温度、湿度等关键信息，并可以适当给出穿衣或出行建议。不要回答与天气无关的问题。", "tools": [ { "type": "function", "function": { "name": "get_current_weather", "description": "获取指定城市的当前天气信息", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称，例如：北京， San Francisco" } }, "required": ["location"] } } } ] }

关键字段详解与编写技巧：

• instructions(系统指令)：这是最重要的部分，直接“教导”大模型如何扮演你的技能。编写优秀的指令是一门艺术：
  • 角色定义要清晰：“你是一个专业的天气查询助手。”
  • 职责边界要明确：“只回答与天气相关的问题。”
  • 行为规范要具体：“如果用户没有提供地点，要礼貌询问。”“回复应包含温度、天气状况等信息。”
  • 风格要一致：“回复应该简洁明了、友好。”
  • 你可以通过添加示例对话（Few-shot Learning）来进一步提升效果，例如：“示例：用户：‘上海天气怎么样？’ 助手：‘上海当前天气晴，气温25°C，湿度65%，东风2级，体感舒适，建议穿着短袖衣物。’”
• tools(工具声明)：这里声明了技能可用的外部函数。name必须与src/tools/目录下你将要创建的函数名严格对应。description要准确描述工具功能，因为大模型会据此决定是否以及如何调用它。parameters定义了工具的输入，使用JSON Schema格式，务必确保其完备性和准确性。

3.3 实现你的第一个工具函数

根据skill.json中的声明，我们需要在src/tools/目录下创建对应的工具文件。创建src/tools/getCurrentWeather.ts。

// src/tools/getCurrentWeather.ts import type { ToolFunction } from ‘../skill/types‘; // 假设脚手架定义了ToolFunction类型 // 定义工具的参数类型，与skill.json中的parameters对应 interface GetCurrentWeatherParams { location: string; } // 实现工具函数 export const getCurrentWeather: ToolFunction<GetCurrentWeatherParams> = async ({ location }) => { // 1. 参数验证与预处理 if (!location || location.trim() === ‘’) { throw new Error(‘地点参数不能为空‘); } const city = location.trim(); // 2. 调用外部天气API（这里以模拟数据为例，实际应调用如OpenWeatherMap, 和风天气等API） console.log(`[Tool Call] 正在查询 ${city} 的天气...`); // 模拟API调用延迟 await new Promise(resolve => setTimeout(resolve, 300)); // 3. 模拟API返回数据（实际开发中替换为真实的HTTP请求） const mockWeatherData = { location: city, temperature: 22, unit: ‘celsius‘, condition: ‘晴朗‘, humidity: 65, windSpeed: 10, feelsLike: 24, forecast: ‘未来24小时天气持续晴朗‘ }; // 4. 处理API响应，构造返回给AI模型的结果 // 返回的结果应该是一个结构化的字符串，方便AI模型整合到回复中 const resultText = `在${mockWeatherData.location}，当前天气${mockWeatherData.condition}，气温${mockWeatherData.temperature}°C，体感温度${mockWeatherData.feelsLike}°C，湿度${mockWeatherData.humidity}%，风速${mockWeatherData.windSpeed}km/h。${mockWeatherData.forecast}`; // 5. 返回结果 return { success: true, data: resultText, // 也可以返回原始结构化数据，取决于你的技能如何处理 rawData: mockWeatherData }; }; // 工具的元数据，用于自动注册 getCurrentWeather.definition = { name: ‘get_current_weather‘, // 必须与skill.json中的name一致 description: ‘获取指定城市的当前天气信息‘, parameters: { type: ‘object‘, properties: { location: { type: ‘string‘, description: ‘城市名称，例如：北京， San Francisco‘ } }, required: [‘location‘] } };

实操心得：

• 错误处理是关键：工具函数内部必须有完善的错误处理（try-catch）。网络请求可能失败，API可能返回错误，参数可能无效。确保工具函数在任何情况下都能返回一个结构化的结果（包含success: false和error信息），而不是抛出未捕获的异常，这能保证技能的鲁棒性。
• 结果格式化：返回给AI模型的数据最好是清晰、简洁的文本，方便模型直接引用。同时保留一份结构化数据（rawData）在返回对象中，以备技能逻辑需要进一步处理。
• 添加日志：在工具函数的开始和结束添加日志输出，对于调试复杂的工具调用链至关重要。

3.4 编写技能核心逻辑类

接下来，在src/skill/目录下创建你的技能主类，例如WeatherSkill.ts。

// src/skill/WeatherSkill.ts import { BaseSkill, type Conversation, type UserMessage } from ‘./BaseSkill‘; // 假设有BaseSkill基类 import { getCurrentWeather } from ‘../tools/getCurrentWeather‘; export class WeatherSkill extends BaseSkill { // 可以在这里定义技能所需的初始化数据或客户端 // private weatherApiClient: WeatherApiClient; constructor() { super(); // this.weatherApiClient = new WeatherApiClient(API_KEY); // 注册本技能用到的所有工具 this.registerTool(getCurrentWeather); } /** * 处理用户消息的核心方法 * @param message 用户消息 * @param conversation 当前对话上下文 */ async onMessage(message: UserMessage, conversation: Conversation): Promise<void> { const userInput = message.content; // 1. 简单的意图识别（在实际复杂技能中，你可能需要集成NLU服务） // 这里只是一个示例：检查用户输入是否包含“天气”关键词 const wantsWeather = /天气|weather|temperature|下雨|晴天/i.test(userInput); if (!wantsWeather) { // 如果意图不匹配，可以返回一个引导性回复 await this.sendMessage(‘我是一个天气查询助手，目前只能帮您查询天气信息。请告诉我您想查询哪个城市的天气呢？‘, conversation); return; } // 2. 尝试从用户输入中提取地点实体（这里使用简单正则，生产环境应用更强大的NER） const locationMatch = userInput.match(/(?:在|于|查询)?\s*([\u4e00-\u9fa5A-Za-z\s]+?)(?:的?天气|天气如何)/i); let location = locationMatch ? locationMatch[1].trim() : null; if (!location) { // 如果没提取到地点，询问用户 await this.sendMessage(‘请问您想查询哪个城市的天气呢？‘, conversation); // 可以在这里设置一个对话状态，等待用户下一次输入的地点 conversation.setState(‘awaitingLocation‘, true); return; } // 3. 清除可能存在的等待状态 conversation.setState(‘awaitingLocation‘, false); // 4. 调用工具函数获取天气信息 try { const toolResult = await this.executeTool(‘get_current_weather‘, { location }); if (toolResult.success) { // 5. 将工具返回的结果发送给用户 await this.sendMessage(`根据查询结果：${toolResult.data}`, conversation); } else { await this.sendMessage(`抱歉，查询${location}的天气时遇到了问题：${toolResult.error}`, conversation); } } catch (error) { console.error(‘工具调用失败:‘, error); await this.sendMessage(‘系统繁忙，请稍后再试。‘, conversation); } } // 可以重写其他生命周期方法，如onStart, onStop async onStart(conversation: Conversation): Promise<void> { await this.sendMessage(‘您好！我是天气助手，随时为您查询全球天气。‘, conversation); } }

注意事项：

• 意图识别与实体抽取：上面的示例使用了极其简单的正则匹配，这仅适用于演示。对于真实技能，你需要更强大的自然语言理解（NLU）能力。可以考虑：
  • 使用大模型自身的函数调用能力（让模型决定何时调用工具）。
  • 集成专门的NLU服务或库。
  • 编写更复杂的规则或机器学习模型。
• 对话状态管理：conversation.setState和conversation.getState是管理多轮对话的关键。例如，当用户说“查天气”，你询问“哪个城市？”，此时需要设置一个状态，以便在用户下一次输入时，你知道他是在回答地点问题。
• 工具执行封装：this.executeTool是一个假设的基类方法，它负责查找已注册的工具、匹配参数并执行。在实际的脚手架中，这个机制可能由框架底层自动完成，你只需要在onMessage中返回一个包含工具调用指令的响应即可。

4. 本地开发、测试与调试实战

4.1 启动本地开发服务器

大多数现代脚手架都集成了本地开发服务器。查看你的package.json，通常会有一个dev脚本。

npm run dev

执行后，终端会输出类似以下信息：

> my-first-skill@1.0.0 dev > ts-node-dev src/index.ts [INFO] 技能服务启动在 http://localhost:3000 [INFO] 技能描述已加载: 你的技能名称 [INFO] 已注册工具: get_current_weather

现在，你的技能已经作为一个本地Web服务运行起来了。它可能会提供一个简单的聊天界面（通过内置的静态页面），或者一个标准的HTTP API端点（如POST /chat）。

4.2 使用模拟聊天界面进行测试

如果脚手架提供了Web界面，打开浏览器访问http://localhost:3000。你会看到一个简单的聊天窗口。尝试输入：

• “北京天气怎么样？”
• “帮我查一下纽约的天气。”
• “天气” （看它是否会询问地点）
• “明天会下雨吗？” （测试超出预设工具范围的回复）

通过这个界面，你可以直观地测试技能的对话流、工具调用和回复内容。这是功能测试和体验调试最快捷的方式。

4.3 进行API接口测试

对于没有UI的脚手架，或者你想进行自动化测试，你需要直接调用技能提供的API。通常是一个接收JSON的POST端点。

使用curl或 Postman 进行测试：

curl -X POST http://localhost:3000/chat \ -H “Content-Type: application/json“ \ -d ‘{ “message“: “上海今天天气如何？“, “conversationId“: “test_conv_123“ # 可选，用于维持对话会话 }‘

预期的响应应该包含AI助手的回复，如果触发了工具调用，响应里可能还会包含工具调用的信息和结果。

调试技巧：

• 查看服务器日志：所有console.log和工具调用信息都会在运行npm run dev的终端中输出。这是排查问题的一线窗口。
• 使用调试器：在package.json的dev脚本中，可能已经配置了--inspect标志。你可以在VSCode等编辑器中附加Node.js调试器，在onMessage或工具函数中设置断点，进行单步调试。
• 结构化日志：在关键位置（如工具函数开始/结束、状态变更时）输出结构化的JSON日志，便于使用日志分析工具进行追踪。

4.4 编写单元测试

为了保证代码质量，特别是工具函数的可靠性，编写测试是必不可少的。在tests/目录下为你的工具和技能逻辑创建测试文件。

// tests/getCurrentWeather.test.ts import { getCurrentWeather } from ‘../src/tools/getCurrentWeather‘; describe(‘getCurrentWeather Tool‘, () => { it(‘should return weather data for a valid location‘, async () => { const result = await getCurrentWeather({ location: ‘北京‘ }); expect(result.success).toBe(true); expect(result.data).toContain(‘北京‘); expect(result.data).toContain(‘气温‘); // 检查返回文本中包含关键信息 expect(result.rawData).toHaveProperty(‘temperature‘); expect(result.rawData).toHaveProperty(‘condition‘); }); it(‘should handle empty location parameter‘, async () => { // 注意：这里测试的是函数内部抛出的错误，还是返回了 {success: false} // 根据你的实际错误处理方式调整断言 await expect(getCurrentWeather({ location: ‘‘ })) .rejects .toThrow(‘地点参数不能为空‘); // 或者 // const result = await getCurrentWeather({ location: ‘‘ }); // expect(result.success).toBe(false); // expect(result.error).toBeDefined(); }); it(‘should handle API simulation delay‘, async () => { const startTime = Date.now(); await getCurrentWeather({ location: ‘Test‘ }); const duration = Date.now() - startTime; // 确保延迟大约在300ms左右（考虑误差） expect(duration).toBeGreaterThan(250); expect(duration).toBeLessThan(350); }); });

运行测试：

npm test

实操心得：为工具函数编写测试时，要重点覆盖：正常成功路径、各种边界情况（空参数、无效参数）、网络错误或API返回错误的模拟。使用jest.mock或sinon来模拟外部HTTP请求，避免在测试中真正调用外部服务。

5. 构建、打包与部署流程详解

5.1 构建生产版本

开发完成后，你需要将TypeScript代码编译成JavaScript，并打包成适合部署的格式。

npm run build

这个命令通常会做以下几件事：

1. 类型检查：运行tsc --noEmit确保没有类型错误。
2. 代码编译：将src/下的TypeScript文件编译到dist/或build/目录。
3. 依赖打包：可能会使用webpack、esbuild或ncc等工具，将项目代码和必要的node_modules依赖打包成一个或几个独立的JS文件，以减少部署体积和依赖问题。
4. 资源复制：复制skill.json、README.md等静态文件到输出目录。

构建完成后，检查dist/目录，你应该能看到所有运行所需的文件。

5.2 部署到技能平台

部署的目标平台取决于你的技能脚手架是为哪个生态系统设计的。常见的有：

• OpenAI GPTs：如果你的技能遵循OpenAI的GPTs Action规范，打包结果可能是一个符合特定结构的ZIP文件，里面包含skill.json(或openapi.yaml) 和打包后的代码。你可以通过GPTs编辑器上传并配置。
• 自定义服务器/Serverless：更多情况下，技能被部署为一个独立的HTTP服务。你可以将dist/目录下的文件部署到任何可以运行Node.js的环境：
  • 传统云服务器：如AWS EC2, Google Cloud VM。
  • 容器服务：将应用Docker化，部署到AWS ECS, Google Cloud Run, Kubernetes。
  • Serverless函数：这是非常流行的方式，因为AI技能的请求模式通常是突发、无状态的。你可以部署到：
    • Vercel/Netlify：对于前端友好的Serverless平台。
    • AWS Lambda/Google Cloud Functions/Azure Functions：主流云厂商的FaaS服务。
    • 腾讯云云函数/阿里云函数计算：国内云厂商的同类服务。

脚手架通常已经配置好了针对某个平台的部署脚本。例如，package.json里可能有一个deploy脚本：

{ “scripts“: { “deploy“: “vercel --prod“ } }

或者，它可能提供了详细的部署指南在DEPLOY.md文件中。

5.3 部署后的监控与维护

技能上线后，工作并未结束。

1. 日志与监控：确保你的部署环境有完善的日志收集（如使用Winston、Pino等日志库，并集成到云日志服务）。监控技能的响应时间、错误率和工具调用成功率。
2. 错误报警：设置报警机制，当错误率超过阈值或关键工具（如天气API）持续失败时，能及时通知到你。
3. 性能优化：
   • 冷启动：对于Serverless部署，冷启动延迟是常见问题。可以考虑使用预置并发、将技能保持在“温暖”状态，或优化代码包大小。
   • 外部API调用：工具函数中对外部API的调用是主要的性能瓶颈和潜在故障点。务必添加超时、重试和熔断机制。
4. 迭代更新：根据用户反馈和监控数据，持续优化你的instructions、工具函数和对话逻辑。建立一套可靠的CI/CD流程，实现自动化测试和部署。

6. 进阶技巧与最佳实践

6.1 设计复杂的多轮对话

简单的单轮问答（Q&A）技能很容易实现。但一个强大的AI技能往往需要处理复杂的多轮对话。这依赖于有效的对话状态管理。

策略一：显式状态机在技能类中定义一个清晰的状态枚举，并在conversation对象中存储当前状态。

enum ConversationState { IDLE = ‘idle‘, AWAITING_LOCATION = ‘awaiting_location‘, AWAITING_DATE = ‘awaiting_date‘, CONFIRMING_FORECAST = ‘confirming_forecast‘ } async onMessage(message: UserMessage, conversation: Conversation) { const currentState = conversation.getState<ConversationState>(‘state‘) || ConversationState.IDLE; const userInput = message.content; switch (currentState) { case ConversationState.IDLE: if (userInput.includes(‘天气预报‘)) { await this.sendMessage(‘请问您想查询哪个城市未来几天的天气？‘, conversation); conversation.setState(‘state‘, ConversationState.AWAITING_LOCATION); } break; case ConversationState.AWAITING_LOCATION: const location = extractLocation(userInput); conversation.setState(‘location‘, location); await this.sendMessage(`好的，查询${location}。请问您想查询哪一天（例如：明天，后天）或未来几天？`, conversation); conversation.setState(‘state‘, ConversationState.AWAITING_DATE); break; case ConversationState.AWAITING_DATE: // ... 处理日期，然后调用工具，最后进入确认状态或返回IDLE break; } }

策略二：让大模型管理状态（更推荐）对于更复杂的对话，一个更强大的模式是将对话历史完全交给大模型，并利用其函数调用能力。你的onMessage方法会变得非常简单：

async onMessage(message: UserMessage, conversation: Conversation) { // 1. 将整个对话历史（包括之前的工具调用结果）整理成OpenAI API所需的messages格式 const messages = this.buildOpenAIMessages(conversation.history); // 2. 调用大模型API（如gpt-4），并传入你定义的工具列表（来自skill.json） const openAIResponse = await openai.chat.completions.create({ model: ‘gpt-4‘, messages, tools: this.getToolDefinitions(), // 从skill.json或注册的工具中获取 tool_choice: ‘auto‘, // 让模型决定是否调用工具 }); const responseMessage = openAIResponse.choices[0].message; // 3. 检查模型是否想调用工具 if (responseMessage.tool_calls) { // 4. 并行执行所有被调用的工具 const toolResults = await Promise.all( responseMessage.tool_calls.map(tc => this.executeToolById(tc.id, tc.function)) ); // 5. 将工具执行结果作为新的消息追加到对话历史 conversation.addToolResults(toolResults); // 6. 递归调用onMessage，让模型基于工具结果生成最终回复 return this.onMessage({ role: ‘user‘, content: ‘继续‘ }, conversation); // 发送一个虚拟消息触发下一轮 } else { // 7. 模型生成了最终文本回复，发送给用户 await this.sendMessage(responseMessage.content, conversation); } }

这种方式将复杂的对话状态管理、意图识别和上下文理解都交给了更擅长此事的大模型，你的代码只需专注于可靠地执行工具和编排流程。这是目前构建复杂AI技能的主流范式。

6.2 工具函数的优化与设计模式

1. 工具聚合：不要为每一个细粒度的API都创建一个工具。考虑创建“聚合工具”。例如，一个search_web工具可以处理多种信息查询，而不是分别创建search_weather、search_news、search_flight。
2. 参数验证与默认值：在工具函数内部进行严格的参数验证和清洗。为可选参数提供合理的默认值。
3. 异步与超时：所有工具函数都应该是async的。为任何外部HTTP请求设置明确的超时（如使用axios的timeout配置或Promise.race），避免一个缓慢的工具拖垮整个技能响应。
4. 缓存策略：对于频繁查询、结果变化不快的工具（如天气，几分钟内变化不大），可以考虑引入简单的内存缓存（如node-cache）或分布式缓存，以提升响应速度和降低外部API调用成本。
5. 错误重试与降级：实现指数退避的重试逻辑。对于非核心功能，设计降级方案（如天气API失败时，返回一个友好的错误信息而不是崩溃）。

6.3 安全性与隐私考量

1. API密钥管理：绝对不要将API密钥硬编码在代码或提交到版本库中。使用环境变量（.env文件，由dotenv读取）或云平台的密钥管理服务（如AWS Secrets Manager）。
2. 输入净化：对用户输入和工具参数进行严格的验证和净化，防止注入攻击。
3. 输出过滤：对从外部API获取并最终返回给用户的数据进行审查，避免返回敏感或不当信息。
4. 权限控制：如果你的技能涉及用户数据或敏感操作，确保实现适当的身份验证和授权机制。
5. 合规性：了解并遵守目标部署平台（如OpenAI GPT商店）的政策，以及你所在地区的数据隐私法规（如GDPR）。

使用skill-scaffold这样的脚手架，最大的好处是它为你处理了80%的通用、繁琐的工程问题，让你能集中精力在剩下的20%——即你的技能独一无二的逻辑和用户体验上。从配置技能描述，到实现工具函数，再到管理对话流，每一步都有迹可循。随着你构建的技能越来越多，你会逐渐形成自己的一套模式和工具库，而这个脚手架就是你坚实且可复用的起点。记住，最好的学习方式就是动手做一个。从今天这个简单的天气技能开始，尝试加入更多功能，比如查询空气质量、穿衣建议，或者整合日历工具来安排户外活动，在实践中不断迭代和深化你的理解。