Copilot Skills 是怎么把一个 Python 脚本变成 AI 可调用的智能功能的？

GitHub Copilot Skills 的开发全流程是一个从环境准备、技能设计、编码实现到测试部署的完整闭环。它旨在将复杂的、重复性的或领域特定的任务封装成可复用的“技能”，供 Copilot Agent 在对话中按需调用，从而显著提升开发效率和代码质量。下面将通过一个实战示例——“API 接口测试数据生成器”，来详细拆解每个步骤。 ### 一、环境准备与项目初始化首先，确保你的开发环境已就绪，并初始化一个支持 Skills 的项目。 1. **环境要求**： * **VS Code**：最新稳定版。 * **GitHub Copilot**：已安装并登录有效的 Copilot 订阅。 * **Git**：用于版本管理（可选但推荐）。 2. **项目初始化**：在 VS Code 中打开你的项目目录（或新建一个），通过 Copilot Chat 面板（快捷键 `Ctrl+Alt+I`）输入 `/init` 命令。这将在项目根目录下生成 `.github/copilot-instructions.md` 文件，用于定义项目级的 Copilot 行为规范 [ref_1]。 3. **创建 Skills 目录**：手动创建存放技能的目录。这是 Skills 机制的核心。 ```bash # 在项目根目录下执行 mkdir -p .github/skills ``` 至此，你的基础项目结构应如下所示： ``` your-project/ ├── .github/ │ ├── copilot-instructions.md # 项目级指令 │ └── skills/ # Skills 存放目录 └── (其他项目文件) ``` ### 二、技能规划与设计在动手编码前，清晰的规划是成功的关键。我们的示例技能命名为 `api-test-data-generator`。 | 设计维度 | 具体内容 | 说明 | | :--- | :--- | :--- | | **技能名称** | `api-test-data-generator` | 使用 kebab-case，清晰描述功能。 | | **核心目标** | 根据给定的 API 接口 JSON Schema（OpenAPI 规范片段），自动生成结构合规、类型匹配的模拟测试数据。 | 解决手动编写测试数据耗时且易错的问题。 | | **触发场景** | 当用户在 Copilot Chat 中询问如何为某个接口生成测试数据、提供示例请求体，或直接提及技能名时触发。 | 触发描述将直接写入技能的 `description` 字段。 | | **输入** | 一段 JSON 格式的 API 请求体 Schema 定义。 | 例如：`{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer", "minimum": 18}}}` | | **输出** | 符合该 Schema 约束的、填充了合理模拟值的 JSON 对象。 | 例如：`{"name": "John Doe", "age": 25}` | | **所需资源** | 一个 Python 脚本，用于解析 Schema 并生成数据；Skill 的描述文档 (`SKILL.md`)。 | 脚本处理确定性逻辑，文档指导 Copilot 如何与用户交互。 | ### 三、技能开发实战接下来，我们创建技能的具体文件。 1. **创建技能目录结构**： ```bash mkdir -p .github/skills/api-test-data-generator/scripts ``` 2. **编写核心脚本 (`scripts/generator.py`)**：这是技能的“引擎”，负责实际的逻辑处理。 ```python #!/usr/bin/env python3 """ API 测试数据生成器 - 核心脚本根据提供的 JSON Schema 生成模拟数据。用法： python generator.py '<json_schema_string>' 示例： python generator.py '{"type": "object", "properties": {"id": {"type": "integer"}}}' 参考：[ref_1] 中关于创建可执行脚本的指南。 """ import sys import json import random import datetime def generate_from_schema(schema): """ 根据 JSON Schema 生成模拟数据。 """ if not isinstance(schema, dict): return None data_type = schema.get("type", "object") # 处理基本类型 [ref_5] if data_type == "string": # 简单示例：根据 format 或 enum 生成字符串 if "enum" in schema: return random.choice(schema["enum"]) elif schema.get("format") == "email": return f"user{random.randint(1, 1000)}@example.com" elif schema.get("format") == "date-time": return datetime.datetime.now().isoformat() + "Z" else: return f"SampleString{random.randint(100, 999)}" elif data_type == "integer": min_val = schema.get("minimum", 0) max_val = schema.get("maximum", 100) return random.randint(min_val, max_val) elif data_type == "number": min_val = schema.get("minimum", 0.0) max_val = schema.get("maximum", 100.0) return round(random.uniform(min_val, max_val), 2) elif data_type == "boolean": return random.choice([True, False]) elif data_type == "object": result = {} properties = schema.get("properties", {}) for prop_name, prop_schema in properties.items(): result[prop_name] = generate_from_schema(prop_schema) return result elif data_type == "array": items_schema = schema.get("items", {}) # 默认生成 1-3 个元素的数组 array_length = random.randint(1, 3) return [generate_from_schema(items_schema) for _ in range(array_length)] return None def main(): if len(sys.argv) < 2: print("错误：请提供 JSON Schema 字符串作为参数。") print("用法: python generator.py '<json_schema>'") sys.exit(1) try: # 解析输入的 JSON Schema [ref_6] input_schema = json.loads(sys.argv[1]) generated_data = generate_from_schema(input_schema) if generated_data is None: print("无法根据提供的 Schema 生成数据。") sys.exit(1) # 输出格式化的 JSON print(json.dumps(generated_data, indent=2)) except json.JSONDecodeError as e: print(f"JSON 解析错误: {e}") sys.exit(1) except Exception as e: print(f"生成数据时发生错误: {e}") sys.exit(1) if __name__ == "__main__": main() ``` 3. **编写技能描述文件 (`SKILL.md`)**：这是技能的“大脑”，告诉 Copilot 何时以及如何使用这个技能。**`description` 字段至关重要，它直接决定了技能的触发条件** [ref_1][ref_6]。 ````markdown --- name: api-test-data-generator description: 根据用户提供的 JSON Schema（OpenAPI 片段）为 API 接口生成模拟测试数据。当用户询问“为这个schema生成测试数据”、“给我一个示例请求体”或提及“生成测试数据”、“api-test-data-generator”时使用此技能。输入应为有效的 JSON Schema 对象字符串。 --- # API 测试数据生成器本技能用于自动化生成符合 JSON Schema 定义的 API 接口测试数据，提升接口测试和原型开发效率。 ## 快速开始用户只需在 Copilot Chat 中提供一段 JSON Schema，本技能即可生成对应的模拟数据。 **示例对话：** > 用户: “为这个 schema 生成测试数据：`{\"type\": \"object\", \"properties\": {\"username\": {\"type\": \"string\"}, \"active\": {\"type\": \"boolean\"}}}`” > Copilot (调用本技能后): “根据提供的 Schema，生成的测试数据如下： ```json { "username": "SampleString123", "active": true } ``` 你可以直接用于 API 测试。” ## 工作流程 1. **接收输入**：Copilot 从用户对话中提取 JSON Schema 字符串。 2. **调用脚本**：Copilot 在后台执行 `scripts/generator.py`，并将 Schema 字符串作为参数传入。 3. **处理与生成**：脚本解析 Schema，根据类型定义生成合理的模拟值。 4. **返回结果**：Copilot 将脚本输出的 JSON 结果格式化后呈现给用户。 ## 脚本参考核心脚本为 `scripts/generator.py`。 * **输入**：一个命令行参数，即 JSON Schema 字符串。 * **输出**：标准输出 (stdout) 为生成的 JSON 数据。 * **错误处理**：如输入非 JSON 或 Schema 无效，会返回错误信息。你可以在终端独立测试该脚本： ```bash cd .github/skills/api-test-data-generator python scripts/generator.py '{\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}' ``` ## 常见模式 * **生成嵌套对象**：支持 `object` 和 `array` 类型的嵌套。 * **处理约束**：支持 `minimum`/`maximum` (对于数字)、`enum` (对于字符串) 等常见约束。 * **格式模拟**：对 `format` 为 `email`、`date-time` 的字符串进行简单模拟。 ## 错误处理 * **无效 JSON**：脚本会捕获 JSON 解析错误并提示用户。 * **未知类型**：如果遇到无法处理的 `type`，会返回 `null`。 * 建议用户提供尽可能完整的 Schema 以获得更准确的模拟数据。 ```` ### 四、测试与验证技能开发完成后，必须进行充分测试。 1. **静态检查**： * 确保 `SKILL.md` 的 YAML Frontmatter 格式正确，`name` 和 `description` 字段完整 [ref_5]。 * 确保脚本路径正确且可执行。 2. **独立测试脚本**： ```bash # 在技能目录下直接运行脚本，验证核心逻辑 python .github/skills/api-test-data-generator/scripts/generator.py '{"type": "object", "properties": {"name": {"type": "string"}, "score": {"type": "number", "minimum": 0, "maximum": 100}}}' ``` 预期应输出如 `{ "name": "SampleString456", "score": 78.34 }` 的结果。 3. **在 Copilot Chat 中集成测试**： * 在 VS Code 中重新打开项目或重启 Copilot，使其加载新技能。 * 输入 `/skills` 命令，确认 `api-test-data-generator` 出现在技能列表中 [ref_1]。 * **触发测试**：在 Copilot Chat 中，使用你在 `description` 中描述的场景进行提问。例如：“帮我为这个用户注册接口的 Schema 生成一些测试数据。” 然后粘贴一段 Schema。观察 Copilot 是否能够正确调用技能并返回生成的 JSON。 ### 五、部署、管理与进阶 1. **部署与共享**： * **项目级使用**：技能目录已在 `.github/skills/` 下，项目成员克隆仓库后即可自动使用 [ref_2]。 * **全局级使用（高级）**：你可以使用 `npx skills` 工具或创建符号链接，将技能安装到 `~/.copilot/skills/` 目录，使其在所有项目可用 [ref_2][ref_3]。 * **团队共享**：将技能目录提交到团队内部的 Git 仓库，作为团队资产。可以通过 GitHub Actions 自动化同步到成员的全局目录 [ref_2]。 2. **技能管理**： * 使用 `/skills` 命令界面可以方便地查看、重命名或禁用技能 [ref_1]。 * 技能的更新只需修改 `SKILL.md` 或脚本文件，Copilot 会自动感知。 3. **进阶优化**： * **增强脚本**：为 `generator.py` 添加更复杂的模拟逻辑（如更真实的姓名、地址生成库）。 * **添加 `references/`**：如果技能逻辑复杂，可以创建 `references/api-spec.md` 等文件，在 `SKILL.md` 中链接，提供更详细的背景知识 [ref_1]。 * **错误反馈**：让脚本返回更结构化的错误信息，方便 Copilot 向用户解释。通过以上从零到一的流程，你不仅创建了一个实用的 API 测试数据生成技能，更掌握了 Copilot Skills 开发的核心方法论：**以 `SKILL.md` 为交互界面，以脚本为执行引擎，通过清晰的职责描述触发 AI 协作**。你可以将此模式复制到任何你想自动化的开发任务中，如代码审查、SQL生成、部署脚本执行等，不断扩充你和团队的 AI 增强工具箱 [ref_4][ref_6]。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

下一篇不用Python的话，Fragstats怎么批量算多个TIFF文件的景观指数？