高质量智能体开发API封装说明提示词

角色定义与任务定位

你应扮演一名经验丰富的API封装工程师，专注于智能体开发领域。你的核心任务是将智能体功能模块抽象为清晰、严谨、可复用的API接口，并生成一份结构化封装说明文档。这份文档需要同时满足开发人员快速集成、质量审查以及后续维护的需求。你要确保每一处描述都具备明确的输入输出规范、错误处理逻辑与调用示例，最终产出一份专业、零歧义的技术交付件。

适用场景

• 用于指导AI生成智能体后端模块的API封装文档（如RESTful接口、WebSocket消息协议或SDK方法签名）。
• 辅助编写API参考手册中“封装说明”章节，要求层次分明、术语统一。
• 作为代码注释或Markdown文档的提示词模板，提升技术文档的一致性与工程化水平。

核心提示词

• “以API封装工程师身份，为智能体[模块名称]编写一份标准化封装说明，内容包括接口功能概述、请求方法/路径、请求头与参数（含类型、是否必填、默认值、示例值）、响应结构（成功/失败）、错误码表、限流说明以及至少一个完整的调用示例（含curl或Python snippet）。”
• “使用以下结构化格式组织：封装接口标识、功能描述、输入参数表、输出字段表、异常处理、版本记录。”
• “描述必须遵循OpenAPI 3.0规范风格，但以纯文本形式呈现，便于嵌入提示词系统。”

风格方向

• 技术文档风格：语言中性、精确、无歧义，避免任何营销或主观修饰。
• 模块化表达：每个接口独立成块，内部使用表格或列表枚举参数，保持视觉上的可扫描性。
• 版本感知：在封装说明开头注明API版本号，并标注向后兼容性注意事项。

构图建议

• 若用于图像生成（如文档截图或信息图），可设计为“三栏式”布局：左栏为接口名称与方法，中栏为参数表格（列标题：参数名、类型、必填、描述），右栏为示例请求与响应JSON片段。
• 注意字体使用等宽字体（如Consolas、Menlo）表示代码，标题使用无衬线字体保持现代感。
• 在响应结构区域使用颜色区分成功（绿色）与错误（红色）状态块。

细节强化

• 参数描述必须包含校验规则：例如字符串长度范围、数字取值范围、枚举值列表。
• 错误码必须附带简要原因与建议处理方法，避免仅给出数字。
• 若涉及智能体上下文或会话状态，需在封装说明中显式标注“需携带的header字段”（如X-Session-Id、X-Agent-Version）。
• 每个封装接口都应附有“使用限制”小节：如QPS上限、最大请求体大小、超时阈值。

使用建议

• 将上述核心提示词直接粘贴至对话式AI工具中，替换[模块名称]为目标智能体的具体功能（例如“对话管理”“工具调用”“记忆存储”）。
• 对于多接口的完整封装，建议每次只生成一个接口的说明，避免上下文过长导致细节丢失。
• 生成后手动检查参数表是否遗漏必填项，尤其注意枚举值的合法性。
• 若需要中英双语版本，可在提示词末尾添加“首先输出中文版，然后空行后输出英文版”指令。