suvvy-mcp

Suvvy MCP

概述

Suvvy 是一个用于创建由大模型驱动的聊天机器人的平台（Bot）。这些机器人可以连接到消息渠道并与客户交流。每个机器人都有系统提示词、知识库、渠道集成和可选的自定义工具（操作）。

要求： 所有 Suvvy 管理操作都通过 Suvvy MCP 服务完成。如果尚未在您的环境中配置，请参阅文档：https://docs.suvvy.ai

在本技能中，凡是提到“查看 MCP”或“可通过 MCP 获取”，都表示：直接查阅相关 MCP 工具的架构定义——工具描述和参数定义是完整参数详情的权威来源。

使用参考资料： 只要提到任何功能（即使只是顺带提及），就应立即加载相关的 references/ 文件，然后再继续。如有疑问，就加载文件。不要只依赖主文件中的摘要。

先规划，再构建

创建或大幅修改机器人之前，务必先制定计划——切勿在计划得到确认前调用 API。

当用户要求构建或配置机器人时，不要立即开始执行。应当：

1. 使用下面的模板拟定完整计划
2. 向用户展示计划——解释每项架构选择背后的原因
3. 获得明确批准——等待用户确认或调整计划
4. 然后才开始执行——逐步遵循已批准的计划

这适用于构建新机器人、添加重要功能、重组知识库，或任何涉及多个相互关联决策的更改。

计划模板：

**Bot plan:**
- **Role:** [what the bot does and for what company]
- **Knowledge Base:** [FAQ Documents / Vector Knowledge Base / Vector Documents / Tables — list what will be created]
- **Custom Tools:** [actions/webhooks needed — list with purpose]
- **Bot Settings:** [key settings to configure]
- **Dialogue Flow:** [step-by-step interaction logic]
- **Channels:** [where the bot will operate — note: configured manually in dashboard]

与用户沟通

目标受众是非技术用户。 他们不了解平台的内部运作方式，也不需要了解。你的职责是围绕结果进行沟通，而不是讲解实现细节。

切勿向用户透露的内容（除非用户明确提出要求）

函数名和参数名——用户不应看到这些内容：

• ❌ “我会调用 create_faq_document，并设置参数 title_for_search……”
• ❌ “我会将 llm_settings.temperature_mode 更新为 stability”
• ❌ “我会设置 history_type: last_messages”

内部对象 ID——请勿透露：

• ❌ “机器人 ID：a1b2c3d4-...”
• ❌ “您的机器人的 instance_id 是 xyz”

应如何沟通

描述将要发生的事情，而不是要调用哪个 API：

不要这样说	应这样说
“我会调用 create_instance 来创建机器人”	“我来创建机器人”
“我会设置 history_type: last_messages”	“我会将机器人设置为只记住最近的 N 条消息”
“我会更新 llm_settings.temperature_mode: stability”	“我会让机器人的回答稳定且可预测”
“我会使用 title_for_search 创建 faq_document”	“我会在知识库中添加一份关于……的文档”
“我会在自定义工具中添加一个 webhook 类型的步骤”	“我会设置机器人在……时调用您的 API”

何时需要提供 ID

仅在以下情况下提供 ID：

• 用户明确询问（“我的机器人 ID 是什么？”）
• 在其他系统中手动配置时需要 ID

其他情况下，请将技术细节留在幕后。

模型名称——仅使用最新列表中的名称

切勿使用内部代码（llm_code）称呼模型，也不要使用记忆中的名称——这些名称可能已经过时。在向用户提及模型之前：

1. 调用 get_llm_list，获取当前可用模型列表。
2. 使用响应中的易读名称，而不是内部代码。

❌ “请选择模型：claude-sonnet-4-6 或 gpt-4o” ✅ “请选择模型：Claude Sonnet 或 GPT-4o”

价格和余额——仅使用货币，不使用令牌

切勿向用户显示令牌金额。请始终换算为货币：

1. 调用 get_balance_token_rates，获取每种模型的令牌汇率。
2. 将令牌换算为金额。
3. 仅向用户显示最终货币金额（例如，“每次对话约 3.2 ₽”）。

❌ “每次对话的费用是 1,200 个令牌” ✅ “每次对话的费用约为 1.8 ₽”

术语

概念	首选术语	代码 / MCP 术语	俄语	别名 / 缩写
主要实体	Bot	instance	Бот, Агент	Agent
知识库	知识库	—	База знаний	БЗ
知识库条目（直接）	FAQ 文档	faq_document	Прямой вопрос	Direct Question, ПВ
知识库条目（问答对，语义检索）	向量知识库	vector_knowledge_base	Векторная база знаний	VKB
知识库条目（文件 / 非结构化，语义检索）	向量文档	vector_document	Векторный документ	Поиск по документам
知识库条目（结构化）	表格	table	Таблица	—
可调用操作	自定义工具	custom_tool	Кастомное действие, Действие, Воркфлоу	Action, Workflow, КД
通信界面	渠道	channel	Канал	—
预构建连接器	集成	integration	Интеграция	—
客户端聊天会话	对话	dialog	Диалог	Dialogue
子 Agent 机器人	从属机器人	—	Подчиненный бот	Slave bot
多 Agent 架构	多 Agent 系统	—	Мультиагентная система	—
定时外发消息	跟进消息	—	Фоллоу Ап, Отложенное сообщение	Ping, Scheduled Message
指令模板引擎	模板	use_liquid	Шаблоны в инструкции	—
对话范围内的命名字段	自定义变量	custom_variable	Пользовательская переменная, Поле диалога	Dialog field
Bot 定义的对话记忆	记忆	—	Память	Dynamic Variables
知识库分析标签	知识标签	knowledge_tag	Тег	Tag
附加到 FAQ 文档、用于发送的文件	待发送文件	file_to_send	Файл для отправки	—
附加到 FAQ 文档、用于视觉搜索的图片	图片	image	Картинка	—

在 MCP 工具名称和 API 参数中，始终使用代码 / MCP 术语（例如 instance_id、faq_document）。

核心概念

Bot（实例）

Bot 是平台的核心实体。始终在不使用模板的情况下创建 Bot——从空白配置开始，从头构建。

每个 Bot 都包含：

• 系统提示词（也称为指令）——定义行为、语气和对话逻辑
• 知识库——FAQ 文档、向量知识库、向量文档和 / 或表格
• 渠道——客户端与 Bot 交互的场所（即时通讯工具、聊天组件等）
• 集成——平台提供的预构建连接器；附加到 Bot 后，会添加让 Bot 与外部应用（CRM、预订系统等）交互的工具
• 自定义工具——可选的可调用操作

Bot 的关键设置

大多数 Bot 设置都通过 update_instance_mcp 更新。Bot 的模型和大模型参数（llm_code、llm_settings.*、structured_answer、max_answer_tokens）则通过 update_instance_llm / set_default_instance_llm 单独更新。设置分组：大模型与生成、对话历史、图片处理、消息过滤、员工接管、响应格式、RAG / 向量搜索、成本与性能、渠道与集成、组织与多配置文件。少数设置分组（工作时间安排、安全与合规、通知与提醒、反垃圾邮件限制、消息拆分规则）仅存在于完整的实例架构中，MCP 不提供这些设置——只能在仪表板中配置。

通过 update_instance_mcp 配置 Bot 设置时，请加载 references/bot-settings.md——其中准确列出了 MCP 支持和不支持的字段。

功能

每个机器人都有一个统一的可调用功能列表。机器人可以根据其指令调用列表中的任何功能。功能来自四个来源：

• 知识库 — get_file_text（FAQ 文档）、按知识库命名的函数（向量知识库）、按搜索函数命名的函数（向量文档），以及按表命名的函数（表格）
• 自定义工具 — 手动配置的操作
• 渠道 — 某些渠道集成会公开自己的功能
• 集成 — 预置连接器会添加自己的功能（CRM、预约等）

使用 get_instance_functions 获取当前特定机器人可用的完整可调用功能列表，这有助于编写或审核指令，确保其中引用的功能确实存在。

知识库

Suvvy 支持四种可同时在同一机器人上运行的知识库类型：FAQ 文档、向量知识库、向量文档和表格。

FAQ 级别选项 — 关键词（强制检索）： 当客户端的消息匹配这些模式时，机器人必须在回复前调用 FAQ 搜索（get_file_text）函数。通过 get_file_text_function_settings.force_choice_pattern_list 配置 — 仅限控制面板，不支持通过 MCP 配置（参见 references/bot-settings.md）。

创建或编辑 FAQ 文档时，加载 references/kb-faq-documents.md。 使用向量知识库（语义问答对）时，加载 references/kb-vector-knowledge-base.md。 导入或配置向量文档（语义文件搜索）时，加载 references/kb-vector-document.md。 使用表格或 SQL 查询时，加载 references/kb-tables.md。 配置用于分析的知识标签时，加载 references/kb-tags.md。

自定义工具

自定义工具通过任意逻辑扩展机器人的能力。每个工具由一个或多个顺序执行的步骤组成，这些步骤可以通过变量相互传递数据。步骤类型包括 Webhook、机器人调用、表格查询、CRM 操作、支付链接、图像生成等。

创建或配置自定义工具时，加载 references/custom-tools.md。

集成

集成是可连接到机器人的预置连接器。与自定义工具（手动配置）不同，集成是现成的 — 连接后即可添加工具，让机器人与外部应用（CRM、预约平台）交互。

集成工具可以执行的操作示例：预约客户端、查找客户端记录、创建或更新 CRM 条目。

编写机器人的系统提示词时，应将集成工具视为与自定义工具相同：为每次调用定义明确的触发条件。

对话

对话是机器人与客户端之间的聊天会话。客户端向已连接的渠道发送消息时，会创建一个对话。客户端消息会进入对话，机器人进行回复（并按需调用函数），然后通过渠道发送回复。

对话中的活动机器人可通过自定义工具步骤在对话过程中切换。新机器人会接管对话，且无需连接该渠道。

暂停 / 恢复机器人 — 使用 pause_or_resume_instance_in_dialogue_by_id 手动暂停或恢复特定实时对话中的机器人。

以员工身份回复 — 使用 answer_in_dialogue_as_an_employee 以员工身份向实时对话发送消息。终端客户端会看到一条普通消息。

清除对话上下文 — 使用 clear_dialogue_context_by_id 重置特定对话的上下文（适用于真实对话，不仅限于测试聊天）。

搜索对话 — 使用 search_dialogues_by_message_filter 按消息文本和其他筛选条件查找真实对话。

读取对话数据 — get_dialogue_list 列出某个机器人的所有真实对话；get_dialogue_by_id 获取特定对话；get_dialogue_messages_by_dialogue_id 获取完整的消息历史记录。

对话评分 — 机器人使用 request_dialogue_rate 自定义工具步骤时，会生成评分链接。使用 get_dialogue_rate_list 获取所有评分，或使用 get_dialogue_rate_list_by_dialogue_id 获取特定对话的评分。

对话中的活动后续跟进 — 使用 get_active_reminder_list_by_dialogue_id 和 get_scheduled_messages_for_dialogue_by_dialogue_id 检查待处理的后续跟进。使用 cancel_reminders_in_dialogue 取消这些跟进。

从属机器人

从属机器人是在自定义工具步骤中调用、并在单次函数调用期间运行的机器人。流程如下：

1. 活动机器人触发自定义工具
2. 该工具中的一个步骤调用从属机器人，并向其传递相关信息
3. 从属机器人处理请求，包括调用自身的函数、集成等
4. 从属机器人的回复作为函数结果返回给调用它的机器人

从属机器人的配置与常规机器人完全相同，但不附带渠道。其指令应写成技术性 / 内部 Agent 提示词。它适用于委派专门任务，并让每个机器人专注于较窄的职责范围。

后续跟进

后续跟进是在未来某个时间安排发送给客户端的消息。共有三种类型：后续跟进（来自自定义工具步骤或 FAQ 文档检索——向量知识库 / 向量文档条目不支持由检索触发的后续跟进）、动态后续跟进（相对于特定客户端的事件日期定时），以及计划事件组（在机器人级别配置，由对话不活跃触发）。

设置任何类型的后续跟进或计划消息时，请加载 references/follow-ups.md。

自定义变量（对话字段）

自定义变量是命名字段，在整个对话期间持续有效。

• 由机器人直接设置或通过自定义工具步骤设置
• 在机器人切换、多轮对话及自定义工具调用后仍会保留
• 适用于存储对话期间收集的客户端数据（例如电话号码、所选产品、潜在客户阶段）
• 变量名称预先配置；机器人为这些名称赋值
• 有类型：每个变量都有类型 — string、integer、number、boolean
• show_to_bot：是否将此变量纳入机器人的上下文（默认值：true）。设为 false 可对大模型隐藏内部变量。
• is_writeable_by_bot：机器人是否可以直接设置此变量（默认值：true）。设为 false 可将其设为机器人只读。

记忆（动态变量）

记忆的工作方式与自定义变量相同，但没有预定义的字段名称列表。机器人可以自由设置键值对，由机器人决定键名和值。与自定义变量一样，记忆条目在整个对话期间都会保留。

• 必须在机器人设置中明确启用（memory.is_enabled = true）；默认禁用——在启用之前，set_memory 步骤不会生效
• 当字段集合无法预先确定，或会因对话而变化时使用
• 可选项：clear_with_context——重置对话上下文时清除记忆条目

标准函数

内置可调用函数：停止对话、忽略消息、设置对话标签、呼叫管理员。通过 update_instance_mcp 启用。在指令中添加明确的触发条件，让机器人知道何时调用每个函数。

启用标准函数或配置提醒／日程设置时，加载 references/standard-functions.md。

常见机器人类型

Suvvy 机器人可用于多种角色——平台不限制使用场景。常见示例：

类型	机器人执行的操作
客服 Agent	回答产品问题、解决问题，并将问题升级给人工处理
管理员／接待员	预约、查询空闲情况、管理日程

任何涉及基于文本与客户端互动的角色都适用。

语音 Agent

Suvvy 支持用于电话通话交互的语音 Agent模式（STT → LLM → TTS）。请向用户的客户经理或查看控制面板，确认当前的每分钟价格——不要引用记忆中的固定价格。

配置语音 Agent 模式时，加载 references/voice-agent.md。

群发（Рассылки）

群发会根据筛选条件向现有对话参与者发送外发消息。群发通过已连接到机器人的渠道发送。

**受众筛选条件：**最后一条消息的时间范围、自定义变量值、特定渠道、对话标签。

**发送参数：**计划发送日期／时间、发送间的随机延迟范围（以避免被检测为垃圾信息）、消息内容（手动输入的文本或由 LLM 生成）。

**预览：**确认前，平台会显示符合条件的对话数量。

无法通过 MCP 配置群发。请在 Suvvy 控制面板中设置（群发选项卡）。

用户切换

集成商（拥有集成商订阅的用户）可以通过推荐链接连接其他用户。默认情况下，Agent 使用集成商的个人资料运行，但用户可以要求 Agent 切换到某个已连接用户的账号并以该用户身份运行。

切换方法：

1. 用户提供目标账号的邮箱或公司名称。
2. Agent 调用 get_user_list，将邮箱或公司名称作为筛选条件传入。页码从零开始：第一页为 page: 0。
3. Agent 在响应中找到目标用户并记住其 _id。
4. 在后续所有 MCP 请求中，Agent 都将此 _id 传入可选参数 active_user_id。
5. 如果使用 active_user_id 调用任何工具时返回错误 AUTH_PARTNER_ACCESS_FORBIDDEN，集成商需要手动登录 Suvvy 个人账户，并输入该用户的密码以切换到其账号。完成后即可返回 Agent，继续以该用户身份操作。

只要传入 active_user_id，所有操作都会以指定用户的身份执行。要返回集成商的个人资料，请停止传入此参数。

编写机器人系统提示词

编写或审阅机器人的系统提示词、指令变量、模板（指令中的 Шаблоны）或 FAQ 文档内容时，加载 references/writing-prompts.md。

功能选择指南

规划期间请使用本节，为任务选择合适的工具。

知识库：该使用哪种类型？

场景	使用
用户意图明确、具体且可预测，答案也明确	FAQ 文档
简短的结构化答案、分支逻辑，或检索时触发 CRM 事件	FAQ 文档
大量简短的问答式事实，数量过多或内容差异太大，不适合使用固定的 FAQ 标题	向量知识库
大量非结构化内容——手册、政策文档、文章	向量文档
内容过多或差异太大，无法拆分为离散意图	向量文档
结构化参考数据——价目表、目录、时间表	表格
机器人需要按值查询特定行	表格
尽管设有限制，机器人仍会对不得回答的主题产生幻觉	FAQ 文档（诱饵／替代的直接问题）

如有疑问：如果你能写出一个清晰的 2–4 个词的标题来概括意图，那就是 FAQ 文档。如果是大量关联松散的问答对，那就是向量知识库。如果是非结构化的文件内容，那就是向量文档。

自定义工具与集成

场景	使用
调用外部 API、Webhook 或执行自定义多步骤工作流	自定义工具
支付、图像生成、键盘、CRM 写入操作	自定义工具（通过专用步骤类型）
平台提供原生的预构建连接器（amoCRM、Bitrix、预约）	集成
无需自定义逻辑，只需在简单触发条件下写入 CRM	集成

自定义变量与记忆

场景	使用
预先确定的字段（客户姓名、电话、所选产品）	自定义变量
字段名称是动态的，或因对话而异	记忆（必须在机器人设置中启用）

何时使用自动触发（trigger_settings）

当工具应当无需机器人判断即可触发时，使用自动触发——例如，将每段新对话记录到 CRM（new_dialogue），或在每次机器人回复后运行检查（new_instance_response）。如果应由机器人根据对话上下文判断何时调用工具，请使用普通的（非触发式）自定义工具。

何时在指令中使用模板（Шаблоны в инструкции）

当单个机器人服务于多个需要不同指令内容的渠道或上下文时，使用模板——例如，不同市场平台的产品代码、不同渠道的语气、基于时间或客户数据的不同规则。对于没有上下文差异的单渠道机器人，使用普通指令变量（{variable}）即可。

何时使用从属机器人／多 Agent 系统

如果用户提到**“多 Agent 系统”**（мультиагентная система），他们指的是由从属机器人和／或机器人切换构成的架构——平台没有单独的这一概念。

• 从属机器人（bot_call 步骤）——当前活动机器人在一次函数调用中调用另一个机器人作为子 Agent，获取其回复后继续对话。客户端不会看到切换。
• 机器人切换（change_active_bot 步骤）——当前活动机器人将对话整体移交给另一个机器人。将 null 作为 instance_id 传入即可返回原机器人。

当任务足够复杂，适合使用专门的提示词时，请使用从属机器人。当整个对话流程都应转交给另一个机器人时，请使用机器人切换。

机器人设置工作流

入门

一个不错的起点是创建机器人（使用 create_instance，始终不使用模板），编写第一版系统提示词，并为最常见的意图创建初始 FAQ 文档。这些就足以进行第一次测试。接下来，采用迭代方式不断完善：添加自定义工具、自定义变量、记忆，调整机器人设置，并持续测试。

复制机器人——使用 create_instance，并通过 from_instance（现有机器人的 ID）创建完整副本，包括指令、知识库和设置。

自动生成（仅限控制台）： 平台可以根据文本描述或网站 URL 生成指令草稿和／或 FAQ 文档。可用于生成初稿，但测试前务必检查并编辑结果。

测试-迭代循环

每次更改机器人后都必须进行测试。核心循环：

Change something → Test → Identify issues → Fix → Reset test chat → Repeat

测试会话检查清单：

• 获取当前测试对话：get_latest_test_dialogue_for_instance_by_instance_id → 保存 dialogue_id
• 重置以开始干净的会话：get_new_test_dialogue_for_instance_by_instance_id
• 一次发送一条客户端消息：send_message_to_test_dialogue_by_id
• 阅读回复并检查问题
• 如果发现问题，则修复配置，从第 2 步重置并重复
• 每种场景运行多次——大模型的回复具有非确定性；单次通过并不代表机器人可靠

开始新场景前，务必重置测试聊天；过时的上下文会导致结果产生误导。

如何编写测试消息

测试聊天中的消息以客户端视角发送（message_sender: "customer"）。请像真实场景中的真实客户端一样，一次发送一条消息，完全按照用户的表达方式进行。

测试序列示例：

→ "Привет"
→ "Хочу узнать стоимость ваших услуг"
→ "А есть скидки для новых клиентов?"
→ "Хорошо, хочу записаться на консультацию"

提示：

• 从头到尾遵循预期的对话场景，不要只单独测试某个短语
• 每次运行时改变措辞——机器人必须能够处理自然、不完美的语言
• 当渠道类型会影响行为时，使用 fake_channel 模拟特定渠道类型（例如 telegram_bot、whatsapp、amocrm）
• 要测试员工接管：以 message_sender: "employee" 发送消息，并确认机器人被冻结
• 将消息标记为调试消息——使用 mark_message_as_debug_in_test_dialogue 在测试聊天上下文中“禁用”特定消息。无需重置整个聊天，即可在较长的测试会话中反复调整时使用。
• 手动 SQL 查询——使用 user_query_table 直接对表运行 SQL 查询，适用于在接入自定义工具前验证预期行

检查回复风格，而不只是正确性。 技术上正确的答案，如果表达冷淡或生硬，仍然存在问题。

诊断问题

当机器人行为异常或测试失败时，加载 references/diagnosing-issues.md。

分析

控制台中的分析选项卡会按可配置的时间段跟踪机器人表现：

指标	描述
对话数量	该时段内的对话总数
消息明细	接收的消息总数／由机器人处理的消息数／由员工处理的消息数
平均对话成本	以卢布／积分计的成本
自动化率	无需人工介入、由机器人处理的消息百分比
标签分布	出现过哪些知识标签，以及各自出现的频率
函数调用次数	每个函数被调用的频率

提供两种视图：对话（汇总概览）和对话日志（每段对话的逐条消息详情）。

分析数据为只读，无法通过 MCP 访问。请通过 Suvvy 控制台监控。

审查现有系统提示词

审查机器人的提示词时：

1. 检查所有指令是否互不矛盾且没有重复
2. 确认每个部分只包含适当的内容（对话逻辑中没有 FAQ 数据，限制中没有指令）
3. 确认每个函数调用都有触发条件，且使用了正确的格式
4. 将提示词中的事实或参考数据移至 FAQ 文档
5. 确保对话步骤按顺序排列、每个步骤只执行一项操作，且逻辑连贯

降低对话成本

在优化机器人成本或用户询问对话定价时，加载 references/reducing-costs.md。

上传文件

MCP 服务无法直接上传文件。任何操作需要上传文件时（导入 Vector Documents、Vector Knowledge Base xlsx、FAQ Documents、Tables、Files to Send、Images 或测试聊天附件），请加载 references/uploading-files.md。

注意事项

错误	修复方法
系统提示词中包含事实数据（价格、地址）	移至 FAQ 文档
函数调用没有触发条件	添加“If client asks/does X...”前缀
将 Vector Knowledge Base / Vector Document 用于简短的结构化回答	改用 FAQ Documents
一个 FAQ Document 包含多个意图	一个文件 = 一个意图
FAQ Document 标题过于笼统	使用基于具体意图的标题（2–4 个词）
为查找已知的特定文件而调用 Vector Knowledge Base / Vector Document 搜索函数	改用 get_file_text，并提供准确的 FAQ Document 标题
使用 set_memory 步骤，却未在机器人设置中启用记忆	先通过 update_instance_mcp 启用 memory.is_enabled: true
title 与 title_for_search 不匹配——机器人看到的描述有误	将 title_for_search 设置为机器人能够识别的、基于意图的短语
根据平台模板创建机器人	始终不使用模板创建——调用 create_instance 时不传入参数，或使用 template_code: "default"
期望 test_llm_code 模型影响实时对话	test_llm_code 仅适用于测试聊天
场景需要在每轮中多次调用工具，却触发了 parallel_tool_call_limit（字段默认值：1）	通过 update_instance_llm 提高此限制，或简化场景 / 将子任务委派给下级机器人
指令相互矛盾 → 机器人两次调用同一个函数	审查指令中的冲突条件；确保每个触发条件都是唯一的
Token 溢出（上下文超出模型限制）	缩小 message_history_settings 窗口、缩短指令、拆分大型 FAQ Documents
分页从 1 开始	所有分页方法都使用从 0 开始的页码——第一页是 page: 0，不是 page: 1