AIP Analyst 的 Workshop 微件

AIP Analyst 可以作为 Workshop widget 嵌入，直接在 Workshop 模块中提供 AI 驱动的分析能力。该 widget 支持大量配置选项，用于控制数据访问、工具可用性和用户界面定制。

AIP Analyst widget 可以进行配置，以便为你的用户定制分析体验。配置按若干区域组织，用于控制该 widget 的行为方式以及可用的能力。

Base configuration

基础配置控制 AIP Analyst widget 的基本行为：

• Custom system prompt： 提供具体指令，引导该特定 widget 实例中智能体的行为。可用它来设定分析重点、定义回答风格，或建立领域特定准则。该提示词会追加到默认 AIP Analyst 系统提示词的末尾。这可以是一个静态值，也可以连接到 Workshop 变量以实现动态提示词。
• Select default model： 用特定的 AI 模型覆盖该 widget 的应用默认模型。这确保了你的 Workshop 模块所有用户的行为一致。如果所选模型无法归因到该项目，则会改用回退模型。
• Suggested prompts： 定义一组预置提示词，在聊天为空时显示。这些有助于引导用户提出与你的用例相关的常见问题或分析工作流。提供静态列表，或连接一个 Workshop 变量以根据应用状态改变提示词。

Input configuration

输入配置让你可以预加载上下文并自动触发分析。预加载上下文让用户无需手动搜索即可立即访问相关数据。

• User message： 连接一个 Workshop 变量以自动启动分析。当该变量变化时，会发送一条包含该变量值的用户消息，智能体无需用户干预即开始处理。这使你的 Workshop 应用内能够实现动态、事件驱动的分析。
• Object sets： 向上下文添加一个对象集列表。默认会添加每个对象集的对象类型。在聊天中，这些对象集会按指定顺序命名为 Input 1、Input 2 等。一旦聊天开始，它就会停止监听对象集更新，直到被重置或创建新聊天。
• Notepad documents： 向上下文添加一个 Notepad 文档列表。
• Skills： 添加一个提供给智能体的 AIP skills 列表。skill 名称及其触发条件会被添加到系统提示词中，智能体仅在相关时才加载某个 skill 的完整指令。
• Enable user skills： 让每位用户自己的 skill 库可供智能体使用，并在聊天输入区显示一个 skills 按钮以便他们管理。
• Object types： 向上下文添加一个对象类型列表。
• Functions： 向上下文添加一个 functions 列表。
• Actions： 向上下文添加一个 actions 列表。对于每个 action，你可以设置 Should auto-submit action。启用时，智能体自主提交该 action；禁用时，会显示一个表单供用户提交。
• Workshop modules： 向上下文添加一个 Workshop 模块列表。
• Datasets： 向上下文添加一个数据集列表。
• Media items： 向上下文添加一个媒体集列表。每个媒体集中的单个项必须通过 RID 指定。仅支持 image 或 PDF 类型的媒体集。
• Recent resources context： 在 widget 加载时将用户最近的资源纳入上下文。
• Favorite resources context： 在 widget 加载时将用户收藏的资源纳入上下文。

每个预加载资源都接受一个可选的 Title and description 说明。用它来告诉智能体为什么提供该资源，以及应如何使用它。

Output configuration

输出配置让你能够将分析结果抽取到 Workshop 变量中，以便在应用的其他部分使用：

• Last object set： 捕获分析过程中产生的最新对象集。你可以选择性地指定一个对象类型，此时该变量会捕获该类型的最后一个对象集。
• Last user message： 抽取用户最近的问题。
• All user messages： 检索会话中用户问题的完整列表。
• Last assistant message： 捕获 AIP Analyst 最近的响应。
• All assistant messages： 抽取智能体生成的所有响应。
• All Vega chart specs： 将所有已解析的 Vega-Lite 图表规范以字符串形式抽取出来，让你能够在 Workshop 模块的其他位置渲染图表。数据内嵌在这些规范中，因此它们是快照而非实时视图。
• All messages： 检索会话中的所有消息（包括工具调用），并可选择包含所配置的输入上下文项。工具使用和工具结果消息的 JSON 结构可能会变化，不提供向后兼容性保证。
• Selected cited object： 捕获最近选中的行内引用所引用的对象。设置此变量会覆盖默认的行内引用行为。
• Selected cited media reference： 捕获最近选中的行内引用的媒体引用。该变量必须是包含 mediaItemRid、mediaSetRid 和 mediaItemReadToken 字段的 struct。设置此变量会覆盖默认的行内引用行为。
• Active tab agent running： 一个布尔值，表示智能体当前是否正在活动标签页中运行。用它来显示加载状态，或在分析进行时禁用输入。

这些输出可以驱动你的 Workshop 模块中的可视化、过滤器或其他逻辑。

Apply actions

你可以配置在响应分析事件时触发的 actions。每个 action 都必须配置好所有必需参数，因为它会严格按照配置执行。两个选项都可以选择性地显示一个 toast 通知，指明该 action 是否成功，该通知还可能允许撤销该 action。

• On user message send： 每次用户发送消息时执行一个 action。Text input value 和 Chat session ID 参数由 widget 提供。该 action 在消息提交之前执行，因此 All user messages 输出此时还不会包含刚提交的消息。
• On agent stopped： 当活动标签页中的智能体停止运行时执行一个 action。Chat session ID 参数由 widget 提供。这对于日志记录、审计或触发后续工作流很有用。该 action 运行期间无法发送新的用户消息。

Tool configuration

工具配置让你可以控制 AIP Analyst 的能力和范围。下面的过滤器适用于所有 Object type search 和 Object search 工具调用。

• Customize default enabled tools： 选择 widget 加载时默认启用哪些工具。将此与 Hide configure tools button 结合使用，可保证 AIP Analyst 只使用你选择的工具。
• Filter to Ontology： 将搜索结果限制在单个 Ontology 内。
• Filter to object type groups： 将搜索结果限制在特定对象类型组内。提供静态列表，或连接一个包含对象类型组 RID 的 Workshop 变量。
• Filter to projects： 将搜索结果限制在特定项目内的实体中。所选文件夹中不是项目的会被忽略。
• Filter to object type statuses： 将搜索结果限制在具有所选状态的对象类型。
• Filter to object type visibilities： 将搜索结果限制在具有所选可见性的对象类型。
• Default semantic search threshold： 设置 object set 工具的语义搜索相似度阈值，为介于 0 和 1 之间的数字。

关于每个范围过滤器的具体行为，请参阅 Analysis settings。

View configuration

视图配置控制用户可见的界面元素，让你能够为特定用例打造精简的体验。

Empty state and input

• Customize empty state： 定制空聊天状态的标题、描述和图片。图片可以是带有自定义颜色的图标，也可以是上传的图像。
• Customize input placeholder： 设置聊天输入框空状态时的占位文本。
• Hide input area： 移除聊天输入字段，防止用户直接在 widget 中发送消息。消息仍然可以通过 User message 输入变量来触发。
• Hide input resources section： 隐藏 widget 空状态中的预加载资源区域。

Header and export

• Hide tab header： 移除聊天标签页标题栏并禁用创建新标签页。这也会禁用聊天分支。
• Hide PDF export button： 移除将聊天导出为 PDF 的选项。如果标签页标题栏被隐藏，导出按钮会转而显示在最底行。
• Hide Quiver export button： 移除将聊天导出到 Quiver 的选项。
• Hide Contour export button： 移除将聊天导出到 Contour 的选项。
• Hide Notepad export button： 移除将聊天导出到 Notepad 的选项。

Chat controls

• Hide outline sidebar： 移除分析大纲和 graph 侧边栏。
• Hide configure tools button： 移除工具配置按钮，使 AIP Analyst 只能使用默认启用的工具。
• Hide record audio button： 从输入区域移除音频录制按钮。
• Add context options： 控制 Add context 菜单中可用的选项，例如对象类型、对象集、数据集、媒体集、Notepad 文档或文件上传。通过粘贴 URL、拖放或消息文本加载的上下文不受影响，此设置也不改变 AIP Analyst 可以使用的工具。
• Hide token estimator： 移除 token 用量估算器。
• Hide model selector： 移除 AI 模型选择器，使 AIP Analyst 只能使用默认模型。
• Hide thinking details： 对用户隐藏模型的扩展思考输出。
• Default collapse tools： 默认折叠工具使用消息，只显示工具名称而不显示完整结果。
• Hide upgrade to media set panel： 隐藏提议将上传文件升级为媒体集的提示。

Session lifecycle

• Clear chat on navigation： 当用户离开该页面时清除聊天会话，使每次返回时都开始一个新会话。
• Reset key： 连接一个 Workshop 变量，每当其值变化时就将 widget 重置为一个全新会话。用它来从模块的其他位置触发重置。

Save configuration

启用 Analysis saving 以控制 widget 如何保存和加载分析。如果你的注册禁用了分析保存，配置这些选项时 widget 会显示错误。

• Save location： 定义新创建的分析所存储的文件夹。启用 Require save location 可防止用户更改它；对该文件夹没有权限的用户将无法保存分析。
• Loaded analysis source： 在 widget 中打开某个特定的已保存分析。硬编码一个 Compass 资源，或连接一个 Workshop 变量以根据应用状态加载不同的分析。
• Unsaved analysis header： 设置尚未保存的分析所显示的标题文本。
• Only show analyses created in this module： 将可发现的分析过滤为此 Workshop 模块内创建的那些。如果该 widget 是通过嵌入模块消费的，则改用顶层模块。

Session persistence

默认情况下，只要用户的浏览器标签页保持打开，AIP Analyst widget 就会将草稿聊天状态保存在内存中。这使 widget 在同一个 Workshop 模块内被隐藏后又显示时（例如 widget 被放在标签页或可折叠区域中时），能够保留对话历史、上下文项和工具结果。刷新或关闭浏览器标签页会清除这些未保存的草稿状态。

要在每次隐藏 widget 时重置聊天，请启用视图配置中的 Clear chat on navigation 选项。启用后，当 widget 从页面中移除时，草稿状态会被丢弃，再次显示时会开始一个全新会话。

你也可以通过 Reset key 视图选项以编程方式强制重置——连接一个 Workshop 变量，每当该变量的值变化时，widget 就会重置为一个全新会话。

在为你的 Workshop 模块配置 AIP Analyst widget 时，请考虑以下做法：

• 预加载上下文以获得更快的结果： 在输入配置中添加相关的对象类型、数据集或对象集，可以省去初始搜索时间，并引导用户找到正确的数据。
• 使用自定义系统提示词实现专门分析： 通过在系统提示词中提供领域特定的指令或分析框架，来定制智能体的行为。
• 连接变量以实现自动化工作流： 将 Workshop 变量链接到 user message 输入，以创建动态、事件驱动的分析，从而响应模块其他位置的用户交互。
• 抽取输出以驱动额外逻辑： 使用输出变量将 AIP Analyst 结果纳入其他可视化、过滤器或分析组件。
• 限制范围以实现聚焦分析： 在构建特定用途的应用时应用 Ontology、对象类型组和项目限制，以提高性能并防止访问不相关的数据。
• 精简界面： 在为非技术用户构建引导式体验时，隐藏高级功能和控制项。
• 使用已应用的 actions 实现集成： 配置 On user message send 和 On agent stopped actions 以触发后续工作流，例如记录分析活动或保存结果。
• 提供建议提示词： 定义建议提示词，引导用户提出常见问题并降低开始分析的门槛。