iblai-vibe-agent-screenshare

用途

iblai-vibe-agent-screenshare 用于向 Next.js 应用添加智能体的 Screen（屏幕共享）标签页，定义智能体在语音通话中用户共享屏幕时的行为。该标签页的作用范围是单个智能体：所有配置都存放在该智能体的通话配置（每个智能体一行）上，因此对调用该智能体的所有用户生效。

主要能力

该标签页包含一个能力开关，用于开启或关闭屏幕共享，以及两张提示词卡片：

Instructions during screen sharing：屏幕共享期间使用的系统提示词。
What the agent says when screen sharing starts：主动开场白。

编辑任一卡片会打开共享的富文本提示词编辑器（EditPromptModal，与 Prompts 标签页使用的是同一个）。编辑器中的保存将文本写回卡片，标签页的保存才会真正提交。开关关闭时，卡片仍然可见但置灰且不可交互，标题会提示“Turn it on to let people share their screen during a call and edit these prompts.”。开关会立即保存。

使用方式

前置条件

已设置认证（/iblai-vibe-auth 或 vibe-starter）。
AgentSettingsProvider 已包装路由（/iblai-vibe-agent §1）。
@iblai/iblai-js@^2.36.2（解析到 @iblai/web-containers 1.41.1，其中包含标签页内开关）。可用 pnpm why @iblai/web-containers 检查。
一个真实的智能体 UUID。需向用户询问，切勿自行编造。
该智能体已开启语音通话（/iblai-vibe-agent-voice）：屏幕共享发生在语音通话内，且始终处于 Live conversation 模式。
需要组织管理员才能保存：通话配置没有智能体级别的权限，因此对于智能体编辑者，开关会弹回，保存时会显示“Couldn't save screen sharing prompts”。

第 1 步：检查环境

在项目根目录查找 iblai.env，其中应包含 PLATFORM、DOMAIN 和 TOKEN。如果缺失，告知用户：

"You need an iblai.env with your platform configuration. Download the template and fill in your values: curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env"

第 2 步：挂载 AgentScreenShareTab

// app/(app)/agents/[mentorId]/screenshare/page.tsx
"use client";

import { AgentScreenShareTab } from "@iblai/iblai-js/web-containers/next";

export default function AgentScreenSharePage() {
  return (
    <div className="flex h-full flex-col bg-white">
      <AgentScreenShareTab />
    </div>
  );
}

该标签页从 AgentSettingsProvider 读取 tenantKey、mentorId 和 username，并自行完成获取和保存。无需传入任何 props。

若要以不同方式渲染卡片上的提示词（例如使用你已传给 AgentPromptsTab 的渲染器以 Markdown 渲染），可传入 renderPromptContent：

import { AgentScreenShareTab } from "@iblai/iblai-js/web-containers/next";

<AgentScreenShareTab
  renderPromptContent={(content) => (
    <p className="text-sm whitespace-pre-wrap text-gray-700">{content}</p>
  )}
/>;

第 3 步：自定义标签（可选）

该标签页使用默认的面向智能体的文案（AGENT_SCREENSHARE_TAB_LABELS，通过 SDK 的 i18n 本地化）。传入部分 labels 对象可更改任意字符串：

import { AgentScreenShareTab } from "@iblai/iblai-js/web-containers/next";

<AgentScreenShareTab
  labels={{
    header: { title: "Screen sharing" },
    fields: { proactivePrompt: { label: "Opening line" } },
  }}
/>;

标签分组（ScreenShareTabLabels）：header（title、description）、capability（title——开关的可访问名称、description、offHint）、disabledHint、fields.systemPrompt 和 fields.proactivePrompt（各含 label、placeholder）、saveButton、savingButton 以及 toasts（saved、error）。

第 4 步：使用 MCP 工具进行自定义

get_component_info("AgentScreenShareTab")
get_component_info("AgentSettingsProvider")

AgentScreenShareTab Props

从 @iblai/iblai-js/web-containers/next 导入。

Prop	类型	必填	说明
labels	DeepPartial<ScreenShareTabLabels>	否	覆盖用户可见字符串
renderPromptContent	(content: string) => ReactNode	否	将每个提示词渲染为富内容。默认为纯文本
tenantKey	string	否	身份覆盖。回退到 AgentSettingsProvider
mentorId	string	否	身份覆盖（智能体 UUID）。回退到 AgentSettingsProvider
username	string	否	身份覆盖。回退到 AgentSettingsProvider

保存机制

操作	请求
加载	智能体设置中嵌入 call_configuration；若不存在，标签页列出 call-configurations/?mentor=<uuid>
开关开/关	PATCH call-configurations/{id}/，字段为 enable_video；若尚无记录，则 POST call-configurations/（mentor、mode: "realtime"、language: "en"、enable_video）
保存	PATCH call-configurations/{id}/（若无记录则 POST），字段为 screensharing_system_prompt 和 screensharing_proactive_prompt

若请求失败，开关会回滚。在提示词发生变化之前，保存按钮保持禁用。

平台数据

Hook	用途
useGetMentorSettingsQuery	智能体设置，包括嵌入的 call_configuration
useGetCallConfigurationsQuery	当设置中不含通话配置时的回退列表
useCreateCallConfigurationMutation、useUpdateCallConfigurationMutation	创建/修补记录

REST 对应项：/iblai-api-agent-voice（通话配置：enable_video、screensharing_system_prompt、screensharing_proactive_prompt）。

第 5 步：验证

在告知用户工作已就绪之前，运行 /iblai-vibe-ops-test：

pnpm build——必须以零错误通过。
pnpm test——vitest 必须通过。
按 /iblai-vibe-ops-test 的说明在浏览器中访问 /agents/<uuid>/screenshare：开关和两张提示词卡片应渲染；编辑开场白、保存、重新加载——文本应持久化；查看控制台；检查手机宽度。

适用场景

适用于需要为智能体配置屏幕共享行为的 Next.js 应用，尤其是希望在语音通话中用户共享屏幕时，让智能体遵循特定系统提示词并以特定开场白回应的场景。

限制

按智能体而非按用户：每个智能体一个通话配置；所有调用者获得相同的提示词。
默认系统提示词：新的通话配置以平台的屏幕指导提示词开始，因此第一张卡片很少为空。
仅限 Live conversation：屏幕共享忽略 Voice 标签页的 Voice Call 子标签页上设置的通话风格，始终进行流式传输。
共享 provider：在布局层级挂载一次 AgentSettingsProvider（/iblai-vibe-agent §1）；不要为每个标签页单独包装。
对等依赖：sonner 和 @iblai/iblai-web-mentor（pnpm add sonner @iblai/iblai-web-mentor）。
品牌指南：BRAND.md。

常见设置（品牌、约定、环境文件、验证）：参见 docs/skill-setup.md。

技能介绍

用途