必须明确定义技能输入边界,按文档/API/逻辑类划分类型,用YAML声明inputs.yaml字段及约束,且在skill.py中通过Pydantic或手动校验确保输入合法。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

在超级麦吉中为AI Agent编写一个可运行、可复用的技能(Skill),必须明确其输入边界——不是随便丢一段文字就能触发,而是要让系统精准识别何时该调用这个技能、传入什么结构化数据才能执行成功。
确认技能类型与输入本质
先判断你要写的技能属于哪一类:是处理文档的(如“从PDF提取合同关键条款”),还是调用外部API的(如“查实时汇率并填入表格”),或是纯逻辑编排的(如“按优先级自动排序待办事项”)。不同类别的技能,输入字段的语义和约束完全不同。
文档类技能必须接收【file_id 或 file_url】,不能只写“上传文件”——超级麦吉不支持运行时弹窗选文件,所有文件必须已存在于工作区并被赋予唯一ID。
API类技能必须声明【required_headers 和 required_params】,漏掉 Authorization 或必填 query 参数会导致401/400错误且无友好提示。
定义输入Schema:用YAML写清楚字段名、类型、是否必填
在技能根目录下新建 inputs.yaml,内容格式严格如下:
```yaml
title: 合同风险点扫描
description: 输入合同文本,返回高亮风险条款及法律依据
inputs:
- name: contract_text
type: string
required: true
description: 原始合同全文,UTF-8编码,长度≤50000字符
- name: jurisdiction
type: string
required: false
default: "中华人民共和国"
enum: ["中华人民共和国", "香港特别行政区", "新加坡"]
```
注意:enum值必须全量列出,不能写“等常见法域”——超级麦吉解析器会直接报错退出。
type只接受 string / number / boolean / array / object 五种,不支持 date 或 file ——文件要用 file_id 字符串代替。
验证输入合法性:在skill.py入口处做硬校验
方法一:用Pydantic v2定义InputModel类
```python
from pydantic import BaseModel, Field
class ContractScanInput(BaseModel):
contract_text: str = Field(..., min_length=10, max_length=50000)
jurisdiction: str = Field(default="中华人民共和国", pattern=r"^(中华人民共和国|香港特别行政区|新加坡)$")
```
方法二:手动if校验(适合轻量技能)
```python
def validate_inputs(inputs):
if not isinstance(inputs.get("contract_text"), str) or len(inputs["contract_text"]) raise ValueError("contract_text must be a non-empty string of at least 10 chars")
if inputs.get("jurisdiction") not in ["中华人民共和国", "香港特别行政区", "新加坡"]:
raise ValueError("jurisdiction must be one of the allowed values")
```
这一步不能省——超级麦吉不会自动拦截非法输入,错误会穿透到大模型层,生成不可控结果。
绑定输入与执行上下文:三步完成数据注入
第一步:在 skill.py 的 main() 函数开头,调用 get_input() 获取原始输入字典;
第二步:用上一步定义的 Pydantic 模型或校验函数清洗转换,得到结构化 input_obj;
第三步:将 input_obj 属性逐个注入到后续调用链中——比如把 input_obj.contract_text 传给 NLP 分析模块,把 input_obj.jurisdiction 作为检索向量库的 metadata 过滤条件。
不要在中间步骤里再临时拼接字符串读取输入字段,容易因 key 名 typo 导致 NoneType 错误且难以调试。


















