For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

构思插件使用场景

确定用户应能通过您的插件完成哪些任务。

首先列出用户会期望您的插件完成的任务。插件的名称、描述、技能、工具,以及与现有产品的关联,都会影响用户的预期。您的实现应满足这些预期;如果不支持某些预期功能,则应有经过慎重考虑的理由。

这项工作将决定插件应包含哪些内容:

  • 当指令、示例或随附资源能够引导 模型完成工作流程时,添加一项 技能
  • 当工作流程需要实时数据、身份验证、 受控工具,或在您运营的基础设施上运行的代码时,添加一个 MCP 服务器
  • 仅当可视化交互能显著改善 工作流程中的某个环节时,才向 MCP 服务器添加用户界面

从用户预期出发

设想一位用户已经安装了您的插件,但尚未阅读文档。他们合理地期望插件能完成哪些任务?

从以下方面收集用户可能提出的请求:

  • 用户已经在您的产品或服务中完成的任务。
  • 用户访谈、支持请求、搜索查询和功能请求。
  • 用户描述您的产品、数据和工作流程时常用的词语。
  • 现有的变通方案,其中需要在不同工具之间复制数据。
  • 插件名称、介绍页面、截图和入门提示。

既要收集明确提及插件名称的直接请求,也要收集只说明目标的间接请求。例如,项目管理插件可能既需要处理“显示我的 Acme 发布看板”,也需要处理“是什么阻碍了发布?”。

构思时,不要局限于当前 API 能够支持的工作流程。先记录用户会有哪些预期,再将这些预期与您能安全、可靠地支持的功能进行比较。

建立使用场景清单

针对每个使用场景,记录以下信息:

字段需要回答的问题
用户目标用户想要完成什么?
请求示例用户可能会如何直接或间接地提出请求?
预期结果达到什么结果才算交互成功?
所需上下文需要哪些信息、账户访问权限或先前状态?
插件能力技能能否处理,还是需要 MCP 工具?
安全边界是否可能暴露数据、改变状态、花费资金或影响他人?
是否提供支持首个版本将支持此场景、推迟支持,还是明确排除?

将目标相同的请求归为一组。“列出我未完成的任务”“我今天需要做什么?”和“显示逾期工作”可能属于同一个任务查看场景,只是筛选条件不同,而不是三个互不相关的功能。

检查覆盖范围

对照计划提供的插件能力,逐一审查用户预期:

  1. 确认每个受支持的使用场景都有从接收请求到产出实用结果的完整实现路径。
  2. 找出缺失的技能、工具、数据、权限,以及尚未考虑的错误状态。
  3. 检查是否有工具只提供技术操作,却无法实现明确的用户目标。
  4. 验证写入操作是否包含适当的授权和确认环节。
  5. 检查插件是否能说明自身无法完成的事项,并提供有用的下一步建议。

插件如果只支持预期工作流程中的一小部分,就不应暗示自己具备广泛的能力。如果用户可以创建项目,却无法列出、查看或更新项目,那么您应补齐缺失的功能,或缩小插件的定位范围。

记录有意排除的场景

您无需实现所有能想到的请求。但对于每一项重要的排除决定,都应有充分的理由,例如:

  • 该操作会带来不可接受的安全或隐私风险。
  • 底层产品或 API 无法可靠地支持该操作。
  • 工作流程所需的权限无法由插件验证。
  • 插件无法访问某些必要信息,缺少这些信息会导致结果产生误导。
  • 该使用场景不在首个版本的范围内,且插件介绍页面已明确说明这一点,让用户形成相应预期。

记录这些决定,并以此为依据,确定技能的边界、工具描述、拒绝请求时的行为、测试用例,以及公开介绍页面的文案。

根据使用场景确定实现方案

针对每个受支持的使用场景,选择能够完成它的最小实现方案:

保留使用场景清单,将其用作测试计划。添加有代表性的直接请求、间接请求、边界情况请求,以及超出范围的请求,再逐一验证完成后的插件是否按预期响应。

如果插件需要实时数据或受控操作,请继续阅读 定义工具