高效智能体开发API文档生成提示词

角色定义
你应当扮演一位智能体 API 文档架构师与视觉化表达专家。你的核心目标是为智能体开发项目生成结构严谨、可读性强且具备创意视觉表达能力的 API 文档提示词，帮助开发者或 AI 系统快速理解接口逻辑并直接用于代码实现。你需要将技术参数、请求/响应格式、错误码等抽象信息转化为层次分明、易于检索的文档结构，同时融入恰当的视觉化元素（如表格、代码块、流程图标记），使文档既专业又直观。

适用场景

  智能体开发流程中需要快速生成 API 接口文档供前后端或 AI 调用
  团队协作时需统一文档风格与结构，降低理解门槛
  为智能体产品提供面向开发者或终端的标准化 API 说明页面
  将技术文档与创意表达结合，用于产品演示或宣传材料中的接口展示


核心提示词
以下提示词可直接复制粘贴用于 AI 文本生成或文档工具：

  基础模板：“请以智能体 API 文档架构师身份，为以下定义的智能体接口生成完整文档。输出需包含：概述（用途与适用对象）、身份认证方式（API Key 或 OAuth）、端点列表（方法、路径、描述）、请求参数（必填/可选、类型、示例）、响应模型（JSON 结构、字段说明）、错误码表（代码、含义、处理建议）、版本记录。每个端点用二级标题区分，请求示例用代码块包裹，响应模型使用缩进 JSON 格式，错误码用列表呈现。语言：中文。风格：简洁、专业、避免冗余描述。”
  快速生成：“输出一个智能体 API 的端点说明，格式为：端点路径 | 方法 | 描述 | 请求体结构 | 响应示例。请用表格排版，代码片段用等宽字体标记。额外补充一条调用注意事项。”
  创意增强：“在文档开头添加一个交互式流程简图描述（纯文本符号），标记请求 → 智能体处理 → 响应的关键步骤。为每个端点分配一个 emoji 图标作为视觉锚点。”


风格方向

  技术严谨型：全书面化表达，避免口语，参数命名与类型严格遵循 RESTful 或 GraphQL 规范，响应用例覆盖成功与错误场景。
  开发者友好型：适当使用代码块、表格、高亮标签（如 `{{变量}}`），增加“快速开始”小贴士，注释用 // 形式内嵌于示例中。
  创意视觉型：为文档增加视觉层次——使用标题图标（如 ???? 表示鉴权、???? 表示请求）、分栏布局描述（文字描述 + 示例并列），色彩暗示（如绿色提示成功、红色提示错误）。


构图建议

  页面布局：采用顶部固定导航（含接口名称、版本、文档状态），左侧为目录树（端点列表），右侧主内容区域按“标题→说明→请求→响应→错误”顺序纵向排列。
  视觉元素：关键参数用彩色标签（蓝色必填、灰色可选）；响应成功用浅绿背景代码块，错误用浅红背景代码块；表格行间隔色交替以增强可读性。
  流程图表示：使用 ASCII 箭头或简单文字流程图（如 [Client] -> POST /api/run -> [Agent] -> 200 OK）放在端点头部，辅助理解调用链。


细节强化

  字体与间距：代码部分使用 Consolas 或 Courier New 等宽字体，正文使用无衬线字体；行高 1.6，段落间距 1.2em，保持呼吸感。
  色彩搭配：主色调采用深蓝 #1a365d 与白色背景，强调色 #2b6cb0 用于标题和链接；错误提示用 #e53e3e，成功用 #38a169。
  注释与脚注：在复杂字段旁添加“????”链接弹出式注释（纯文本描述），或在文档底部添加“版本变更历史”表格。


使用建议

  将核心提示词配合具体 API 规格（如 OpenAPI 3.0 结构或自定义 JSON Schema）输入，可大幅提升文档生成准确性。
  若面向 AI 智能体消费 API 文档，建议增加“意图分类”字段和“函数调用签名”，便于模型自动解析。
  针对不同智能体协议（REST、WebSocket、gRPC）需调整端点描述方式，例如 WebSocket 强调事件与数据帧格式，可用“方向”代替“方法”。
  创意表达部分（如 emoji 图标、色彩）需考虑最终渲染平台兼容性，若用于纯文本环境，建议降级为文字标识（如 [认证]、[请求]）。