通用 Skill 开发实战教程：从需求到落地
文章目录
- 🚀 通用 Skill 开发实战教程：从需求到落地
- 第一阶段：需求分析（翻译官思维）
- 1.1 拆解“隐形”参数
- 1.2 确立规则优先级
- 第二阶段：数据策略设计（架构师思维）
- 2.1 明确数据源
- 2.2 规避工具陷阱（关键）
- 2.3 查询模式选择
- 第三阶段：与大模型协作开发（提效核心）
- 3.1 让大模型写第一版草稿
- 3.2 代码审查与逻辑优化
- 3.3 生成测试用例
- 第四阶段：接口实现与规范（工程师思维）
- 4.1 查询前的“三问”
- 4.2 查询语句的“铁律”
- 第五阶段：结果呈现与异常处理（产品思维）
- 5.1 输出标准化
- 5.2 异常分支处理表
- 附录：新人自检清单 (Checklist)
🚀 通用 Skill 开发实战教程：从需求到落地
适用对象：AI 技能开发新人
核心目标：掌握将模糊的自然语言需求转化为结构化、可执行代码逻辑的全过程，并学会利用大模型（LLM）提效。
第一阶段：需求分析（翻译官思维）
用户的一句话需求通常是模糊的，开发者的第一步是将其“翻译”成系统能理解的精确参数。
1.1 拆解“隐形”参数
用户只会说核心诉求（如“帮我查昨天的数据”），但系统执行需要 4 个维度的明确指令。你需要建立一个**“参数补全机制”**：
| 维度 | 用户没说清楚的（模糊） | 系统必须确定的（精确） | 解决方案策略 |
|---|---|---|---|
| 时间 | “昨天”、“上个月” | 具体日期范围 (YYYY-MM-DD) | 基于当前时间进行相对计算 |
| 主体 | “我们供电所”、“那个台区” | 具体的组织/对象编码 | 读取用户上下文或默认配置 |
| 标准 | “异常的”、“有问题的” | 具体的数学判定公式 | 加载业务规则库（阈值/逻辑） |
| 范围 | 未指定 | 查询粒度（按日/按月） | 设定默认值，允许用户覆盖 |
1.2 确立规则优先级
业务规则往往不是单一的，新人必须理解**“规则的层级”**。在代码中，你需要按以下优先级加载配置：
- 会话级规则（最高）：用户本次对话中临时指定的（如：“这次按 5% 算”）。
- 用户级规则（中）：用户个人偏好中保存的长期设置。
- 系统级规则（兜底）：全系统通用的默认标准。
💡 教学提示：告诉新人，永远不要写死阈值，要设计成可配置的逻辑链。
第二阶段：数据策略设计（架构师思维）
在写代码前，先设计数据怎么拿。这是新人最容易犯错的地方，重点在于**“查询策略”与“工具限制”**的博弈。
2.1 明确数据源
列出所有涉及的“表”或“对象”：
- 主表：存放核心指标（必须查）。
- 维表/配置表：存放辅助判定信息（按需查）。
2.2 规避工具陷阱（关键）
大多数底层查询工具（如 MCP、SQL）对逻辑操作符的支持是有限的。
- 陷阱：试图在一个查询中同时满足互斥条件（例如：
A > 10或A < 0）。 - 策略：分治法。
- 如果工具不支持
OR逻辑，必须拆分为多次查询。 - 查询 A：获取满足条件 1 的数据集。
- 查询 B：获取满足条件 2 的数据集。
- 代码层：在内存中合并结果。
- 如果工具不支持
2.3 查询模式选择
- 模式 A（数据库过滤）：如果阈值是固定的，直接在查询条件（Conditions）中写死，让数据库返回结果（效率高）。
- 模式 B（本地计算）：如果判定逻辑复杂（涉及多表关联或动态计算），先查出全量数据，再在代码中进行遍历判定（灵活但慢）。
第三阶段：与大模型协作开发（提效核心）
不要从零开始写代码。将大模型（LLM）视为你的“结对编程伙伴”，让它帮你完成从草稿到优化的全过程。
3.1 让大模型写第一版草稿
当你明确了需求和数据结构后，不要急于动手。将你的分析结果整理成清晰的提示词（Prompt），让大模型生成初始代码。
提示词结构建议：
- 角色设定：“你是一名资深的 Skill 开发工程师。”
- 任务描述：“请帮我编写一个用于查询[具体业务]的 Skill。”
- 输入输出定义：“输入参数包括 A、B、C；输出为一个 JSON 格式的查询列表。”
- 业务规则：“核心判定逻辑是：如果 X 大于 Y，则为异常。”
- 技术约束：“请使用 MCP 查询协议，属性名必须用中文。”
示例：
“请帮我写一个查询技能。需求是找出线损异常的台区。输入是日期和供电所编码。异常分为两种：1. 负损（线损率 < 0）；2. 高损（线损率 > 阈值）。请生成两个独立的 MCP 查询 JSON，分别对应高损和负损。”
3.2 代码审查与逻辑优化
大模型生成的代码是“草稿”，可能存在逻辑漏洞。你需要扮演“审查者”的角色，重点检查以下几点：
- 边界条件：问大模型：“如果查询结果为空怎么办？如果阈值是动态的，你的代码能处理吗？”
- 性能陷阱：问大模型：“这个查询如果数据量达到 10 万条，会不会很慢？有没有优化方案？”
- 安全性：问大模型：“这段代码是否存在注入风险？用户输入的参数是否都经过了校验？”
优化技巧：将大模型的输出复制到你的编辑器中，然后反过来问它：“请解释一下你生成的这段代码的逻辑，特别是第 X 行。” 这能帮你快速理解并发现潜在问题。
3.3 生成测试用例
让大模型帮你思考你没想到的场景。
提示词示例：
“针对刚才编写的查询技能，请列出 5 个必须测试的边界场景，并给出每个场景的输入数据和预期输出。”
大模型可能会给出：
- 场景：查询未来日期。预期：提示“数据未生成”。
- 场景：供电所编码不存在。预期：提示“单位不存在”。
- 场景：高损和负损阈值为 0。预期：正确返回所有非零线损的台区。
第四阶段：接口实现与规范（工程师思维）
编写具体的查询语句（如 JSON 格式的 MCP 调用）时，必须遵守严格的工程规范。
4.1 查询前的“三问”
每次发起请求前，代码逻辑必须自检：
- 属性名对吗？：严禁臆造字段，必须调用元数据接口（如
ontology_list_attributes）确认真实属性名。 - 编码有了吗？：用户输入的是“名称”，数据库需要的是“ID/编码”，必须做转换。
- 权限够吗？：是否通过了身份鉴权？
4.2 查询语句的“铁律”
在编写查询 JSON 时，强制遵守以下规范：
- 语言统一：属性名必须使用系统定义的语言（如全中文），严禁混用英文或数据库物理字段名。
- 结构严谨：条件字段（Conditions）即使为空也必须是数组
[]，绝不能传null或字符串，防止解析报错。 - 防御性编程：
- 时间格式：严格校验
YYYY-MM-DD，月份查询必须补全为YYYY-MM-01。 - 分页限制：必须显式传递
limit参数（如 500），防止默认值过小导致数据截断。
- 时间格式：严格校验
第五阶段：结果呈现与异常处理（产品思维）
代码跑通只是第一步，如何优雅地展示结果和处理错误才是区分新手和熟手的标准。
5.1 输出标准化
不要直接打印原始数据，要进行格式化：
- 数值格式：金额/电量保留 2 位小数，比率带
%，状态码转为人类可读文本。 - 结构化展示：
- 摘要：一句话总结（共发现 X 个，其中 Y 个严重）。
- 列表：关键信息表格化。
5.2 异常分支处理表
新人必须预设以下场景并编写对应的提示语：
| 场景 | 处理逻辑 | 用户提示语示例 |
|---|---|---|
| 无数据 | 检查时间是否太早（T+1延迟） | “数据通常次日生成，建议查询昨天及以前的数据。” |
| 查无此对象 | 名称匹配失败 | “未找到该单位，是否指：[候选列表]？” |
| 结果截断 | 返回数量达到 Limit 上限 | “结果较多，仅展示前 500 条，请缩小查询范围。” |
| 查询失败 | 接口报错 | “系统繁忙，正在重试… 若仍失败请联系管理员。” |
附录：新人自检清单 (Checklist)
在提交代码前，请对照此表打钩：
- 参数解析：是否处理了相对时间（如“昨天”）？
- 规则加载：是否实现了“会话-用户-系统”三级优先级？
- 查询拆分：互斥条件是否拆分成了多次查询？
- AI 协作：是否让大模型生成了初稿并进行了逻辑审查？
- 测试用例：是否让大模型生成了边界测试场景并已通过？
- 属性验证：是否通过元数据接口确认了字段名？
- 格式规范：Conditions 是否为数组？Limit 是否显式指定？
- 边界测试：是否测试了“无数据”和“数据量巨大”的情况？
总结：
开发一个 Skill，本质上是在做**“翻译”（需求转参数）、“拆解”（复杂逻辑转多次查询）和“兜底”**（异常处理）。而学会与大模型协作，则是为你的开发过程装上了“涡轮增压”。掌握这套流程，你就能高效、高质量地开发任何领域的技能。