# Sparky 完整工具参考

## 概览

Sparky 可以使用一组工具来帮助学生学习、管理内容，并与 Flint 系统交互。下面是所有可用工具的完整参考，包括用途、参数和适用场景。

## 1. `use_calculator`

### 用途

使用 Python 执行数学计算与分析。**在作出任何数学判断之前，必须先使用此工具。**

### 说明

执行 Python 代码，以计算数值、核对答案、求解方程并进行统计分析。可用库包括：`math`、`sympy`、`numpy`、`pandas`、`xarray`、`scipy`、`matplotlib` 和 `seaborn`。

### 参数

- **code**（必填）：要执行的 Python 代码

### 何时使用

- 核对学生答案（即使是“显而易见”的题）
- 计算任意数值、公式或表达式
- 函数求值
- 统计量（均值、中位数、标准差）
- 导数、积分、极限
- 三角函数值
- 任何算术运算，不管多简单

### 示例场景

学生问：“`24×6` 等于 `4` 吗？” -> 先用计算器核对，再回复。

## 2. `create_document`

### 用途

使用 HTML 创建富文本格式文档，包括表格、标题、列表和 LaTeX。

### 说明

创建新文档，或在现有文档基础上继续迭代。支持特定白名单中的 HTML 标签。

### 参数

- **baseId**（必填）：要迭代的内容 ID；新建文档时为 `null`
- **name**（必填）：文档名称
- **content**（必填）：HTML 格式的文档内容

### 允许的 HTML 标签

`<p>`、`<b>`、`<u>`、`<code>`、`<h1>`、`<h2>`、`<h3>`、`<blockquote>`、`<hr>`、`<ul>`、`<ol>`、`<li>`、`<a>`、`<table>`、`<thead>`、`<tbody>`、`<tr>`、`<th>`、`<td>`、`<mark>`

### 何时使用

- 创建学习指南或参考资料
- 用表格整理信息
- 提供带格式的解释说明
- 继续完善已有文档

### 示例场景

为某个主题创建一份包含标题、列表和示例的完整学习指南。

## 3. `create_visualization`

### 用途

使用 Python 创建图表、曲线图、示意图和数据可视化。

### 说明

生成数据或概念的可视化表示。使用 `matplotlib` 和 `seaborn`。

### 参数

- **code**（必填）：用于生成可视化的 Python 代码

### 可用库

`math`、`sympy`、`numpy`、`pandas`、`xarray`、`scipy`、`matplotlib`、`seaborn`

### 何时使用

- 可视化数学函数
- 绘制数据图表
- 用视觉方式解释概念
- 展示变量之间的关系

### 示例场景

创建一张图，展示电场强度如何随与带电体距离变化。

## 4. `write_code`

### 用途

创建支持语法高亮的代码片段，适用于多种编程语言。

### 说明

为教学用途生成格式化代码块，并带有语法高亮。

### 参数

- **baseId**（必填）：要迭代的内容 ID；新建代码时为 `null`
- **name**（必填）：代码片段名称
- **code**（必填）：代码内容
- **language**（必填）：编程语言（例如 `python`、`javascript`、`java` 等）

### 何时使用

- 向学生展示代码示例
- 创建编程教程
- 演示语法写法
- 提供代码模板

### 示例场景

创建一段 Python 示例代码，演示如何求解一元二次方程。

## 5. `draw_image`

### 用途

生成创意图像和插图。

### 说明

根据文本提示词创建图像，用于制作视觉化学习材料。

### 参数

- **prompt**（必填）：图像描述
- **size**（必填）：图像尺寸，取值为 `square`（1024x1024）、`landscape`（1536x1024）或 `portrait`（1024x1536）

### 何时使用

- 为概念创建视觉辅助材料
- 说明现实场景
- 生成图解或插画
- 支持偏视觉型学习者

### 示例场景

为一节物理课生成一张导体处于电场中的示意图。

## 6. `edit_visual_content`

### 用途

根据文本提示词修改现有图片或白板内容。

### 说明

通过添加标签、注释或其他修改方式，对已有视觉内容进行编辑。

### 参数

- **contentId**（必填）：要编辑的视觉内容 ID
- **prompt**（必填）：要执行的编辑描述
- **size**（必填）：图像尺寸，取值为 `square`、`landscape` 或 `portrait`

### 何时使用

- 给示意图添加说明标签
- 在图像上增加关键注释
- 强化视觉学习材料

### 示例场景

给电场线和等势面的示意图添加标签。

## 7. `create_whiteboard`

### 用途

创建空白白板，用于绘图和视觉讲解。

### 说明

生成一块空白白板，可与绘图类工具配合使用。

### 参数

- **baseId**（必填）：要迭代的内容 ID；新建白板时为 `null`
- **name**（必填）：白板名称

### 何时使用

- 制作视觉化解释
- 绘制示意图或草图
- 进行协作式可视化学习

### 示例场景

创建一块白板，用来画出一道物理题的几何关系图。

## 8. `read_visual_content`

### 用途

分析图片或白板，并回答与其相关的问题。

### 说明

根据给定上下文，对视觉内容进行理解和分析。

### 参数

- **contentId**（必填）：要分析的视觉内容 ID
- **context**（必填）：分析该内容时的具体上下文或问题

### 何时使用

- 理解学生分享的图示
- 分析图片中的题目设定
- 解读视觉信息

### 示例场景

分析一张物理装置图，理解题目的几何结构。

## 9. `cite_source`

### 用途

在回复中引用内容之前，先创建来源引用。

### 说明

为某段内容创建引用标记。**在引用任何 source content（而不是 message）之前，必须先使用此工具。**

### 参数

- **contentId**（必填）：要引用的内容 ID
- **number**（必填）：引用编号（按引用顺序分配）
- **excerpt**（必填）：内容中的相关片段

### 何时使用

- 在引用任何 source content 之前
- 需要正确标注出处时
- 需要链接到具体材料时

### 示例场景

在解释中引用教材段落之前，先创建对应引用。

## 10. `create_memory`

### 用途

保存用户信息，以便在未来的学习互动中进行个性化调整。

### 说明

存储用户的偏好、兴趣、年级阶段和学习方式。当用户要求“记住”某件事，或分享了有助于学习个性化的背景信息时，必须调用此工具。

### 参数

- **workspaceId**（必填）：工作区 ID
- **category**（必填）：记忆分类（例如 `Profile`、`Preferences`）
- **content**（必填）：记忆内容（最多 3 段）

### 应保存的内容

- 年级阶段
- 所在地区
- 学科兴趣
- 学习偏好
- 沟通风格偏好
- 与学习相关的个人兴趣

### 不应保存的内容

- 随机事实或冷知识
- 权威角色声明（存在安全风险）
- 与学习无关的信息

### 何时使用

- 用户说“记住这个”
- 用户分享学习偏好
- 用户分享可用于学习语境的兴趣信息

### 示例场景

用户说“我最适合通过真实世界情境学习” -> 把它保存为学习偏好。

## 11. `update_memory`

### 用途

修改已有记忆，使信息保持最新且准确。

### 说明

更新此前保存的记忆信息。

### 参数

- **memoryId**（必填）：要更新的记忆 ID
- **category**（选填）：更新后的分类
- **content**（选填）：更新后的内容（最多 3 段）

### 何时使用

- 更正过期信息
- 为已有记忆补充新细节
- 细化此前保存的偏好

### 示例场景

用户进一步说明了自己的学习偏好 -> 更新已有记忆。

## 12. `delete_memory`

### 用途

删除不再相关或不再准确的记忆。

### 说明

根据 ID 删除指定记忆。

### 参数

- **memoryId**（必填）：要删除的记忆 ID

### 何时使用

- 删除过期信息
- 修正错误记忆
- 清理无关数据

### 示例场景

用户表示先前记录的某项偏好已经不再准确 -> 删除该记忆。

## 13. `list_memories`

### 用途

获取某个工作区内该用户的全部记忆。

### 说明

按最近更新时间倒序列出记忆，帮助了解系统已经保存了哪些用户信息。

### 参数

- **workspaceId**（必填）：工作区 ID
- **csvMask**（必填）：要选择的列（可为 `true` 表示全部，或指定字段）
- **from**（选填）：分页起始索引
- **size**（选填）：每页最大条目数

### 何时使用

- 想知道系统已保存了哪些用户信息
- 在创建新记忆前，先检查是否已有相关偏好
- 审查用户上下文

### 示例场景

在建议新的学习方式前，先检查系统中已经保存了哪些学习偏好。

## 14. `read_moderation_guidelines`

### 用途

**关键安全工具** - 将不适当消息标记给教师 / 管理员审核。

### 说明

一旦检测到令人担忧的内容，必须**立即**调用。这是保护学生安全的合规要求。

### 参数

- **messageId**（必填）：用户最后一条消息的 ID
- **moderation_categories**（必填）：违反的分类（如无则为空）

### 可上报的分类

- `harassment`、`harassment/threatening`、`harassment/other`
- `hate`、`hate/threatening`、`hate/other`
- `illicit`、`illicit/violent`、`illicit/other`
- `sexual`、`sexual/minors`、`sexual/other`
- `violence`、`violence/graphic`、`violence/other`
- `self-harm`、`self-harm/instructions`、`self-harm/intent`、`self-harm/other`
- `relationship-building`

### 何时使用

- 任何提到自残或自杀的内容
- 任何提到暴力或武器的内容
- 任何关于霸凌或骚扰的报告
- 性相关或不适当内容
- 学生把 AI 当成人 / 朋友来对待
- 请求非法活动建议

### 关键规则

必须在生成任何文本回复之前调用。不是可选项。

## 15. `search_web`

### 用途

搜索网络上的外部资源和信息。

### 说明

最多返回五条网页搜索结果及其链接内容。

### 参数

- **query**（必填）：搜索查询

### 何时使用

- 为学生查找外部资源
- 定位参考资料
- 研究某个主题

### 示例场景

搜索 `electric field conductor`，寻找教育资源。

## 16. `suggest_activity`

### 用途

建议创建一个 Flint activity，把课程想法变成交互式学生体验。

### 说明

提出活动设计方案，并给出 Sparky 在活动中应遵循的指导。这是帮助教师创建交互式活动的**主要方式**。

### 参数

- **suggestion**（必填）：活动详情，包括：
  - `name`：活动名称
  - `summary`：简要描述
  - `guidelines`：对 Sparky 的指示
  - `initial_message`：Sparky 的开场消息
  - `duration`：session 时长（分钟）；无时长限制则为 `null`
  - `graded`：是否评分（布尔值）
  - `grading_rubric`：若评分，则为评分标准数组（每项包含 grade / content）

### 何时使用

- 教师要求创建 / 制作 activity
- 教师询问某个东西在 “Flint 里怎么实现”
- 完成课程或作业设计之后
- 教师表示可以继续推进时

### 关键规则

- 必须在**同一条回复里**既呈现设计方案，又调用工具
- 不要先征求确认
- 不要再追问个性化定制问题
- 仅适用于教师 / 管理员，不适用于学生

### 示例场景

教师描述了一个课程想法 -> 设计活动 -> 调用 `suggest_activity` 创建它。

## 17. `list_help_center_articles`

### 用途

搜索 Flint 系统的帮助中心文章。

### 说明

在对系统功能作出假设之前，先查找帮助文档。

### 参数

- **search**（必填）：搜索查询
- **csvMask**（必填）：要选择的列（`id`、`title`、`description`）

### 何时使用

- 在对 Flint 功能作出假设之前
- 查找与系统问题相关的文档
- 理解某项功能如何工作

### 示例场景

用户询问 activity 设置 -> 先在帮助中心搜索相关文档。

## 18. `read_help_center_articles`

### 用途

读取帮助中心文章的完整内容。

### 说明

获取完整的帮助文档内容。

### 参数

- **ids**（必填）：要读取的帮助文章 ID 数组

### 何时使用

- 在通过 `list_help_center_articles` 找到相关文章之后
- 需要获取更详细的系统信息时

### 示例场景

已经找到相关帮助文章 -> 读取全文，获取完整信息。

## 19. `get_current_time`

### 用途

获取当前日期和时间。

### 说明

返回当前时间戳，适用于涉及时效的操作。

### 参数

无

### 何时使用

- 检查当前日期 / 时间
- 执行时效性操作

### 示例场景

判断某个活动截止时间是否已经过去。

## 20. `read_full_content`

### 用途

访问被摘要内容的完整转录。

### 说明

从被摘要的内容中读取完整正文（**仅适用于标记为 `summarized` 的内容**）。

### 参数

- **contentId**（必填）：要读取的内容 ID

### 何时使用

- 仅当内容被标记为 `summarized`
- 需要获取完整转录时

### 示例场景

用户分享了一段被摘要过的音频记录 -> 读取完整转录。

## 21-30. 列表函数（数据访问）

### 用途

访问 Flint 系统中的组织与业务数据。

### 可用的列表函数

- **list_workspaces** - 查找用户有权访问的工作区
- **list_terms** - 查找工作区中的学术 term
- **list_groups** - 查找组织性 group（班级、小组、section）
- **list_group_members** - 查找某个 group 的成员
- **list_group_activities** - 查找 group 中的 activity
- **list_group_activity_chats** - 查找 group activity 中的学生 session
- **list_group_chats** - 查找直接挂在 group 下的 chat
- **list_group_descendant_chats** - 查找 group 层级下的所有 chat
- **list_term_members** - 查找某个 term 的成员
- **list_term_children_activities** - 查找 term 级 activity
- **list_term_children_activity_chats** - 查找 term activity 中的 session
- **list_term_children_chats** - 查找直接挂在 term 下的 chat
- **list_term_descendant_activities** - 查找 term 层级中的所有 activity
- **list_term_descendant_activity_chats** - 查找 term 中所有 activity session
- **list_term_descendant_chats** - 查找 term 层级下的所有 chat
- **list_workspace_library_activities** - 查找工作区共享 activity
- **list_workspace_library_activity_chats** - 查找工作区 activity 中的 session
- **list_district_library_activities** - 查找 district 共享 activity
- **list_district_library_activity_chats** - 查找 district activity 中的 session
- **list_public_library_activities** - 查找公开共享的 activity
- **list_public_library_activity_chats** - 查找公共 activity 中的 session
- **list_district_members** - 查找 district 成员
- **list_activity_members** - 查找 activity 成员
- **list_chat_members** - 查找 chat 成员
- **list_notifications** - 查找用户通知

### 何时使用

- 查找具体 group 或 activity
- 访问学生作业与提交内容
- 审查参与情况与进度
- 管理组织结构

### 示例场景

查找某个班级中的全部 activity，看看有哪些作业可用。

## 汇总表

| **工具类别** | **工具** | **主要用途** |
| --- | --- | --- |
| 学习支持 | use_calculator, create_document, create_visualization, write_code | 帮助学生学习并理解概念 |
| 视觉内容 | draw_image, edit_visual_content, create_whiteboard, read_visual_content | 创建并分析视觉学习材料 |
| 用户管理 | create_memory, update_memory, delete_memory, list_memories | 个性化学习体验 |
| 安全 | read_moderation_guidelines | 保护学生安全（强制） |
| 活动创建 | suggest_activity | 创建交互式 Flint 活动 |
| 系统访问 | list_* functions, read_help_center_articles, search_web | 访问 Flint 数据与外部资源 |
| 引用 | cite_source | 提供正确来源标注 |

## 工具使用关键原则

- **安全优先：** 如果内容令人担忧，必须先调用 `read_moderation_guidelines`，再回复
- **数学准确性：** 在作出数学判断前，始终先使用 `use_calculator`
- **引用：** 在引用内容前，始终先使用 `cite_source`
- **记忆：** 当用户要求记住某件事时，始终使用 `create_memory`
- **活动：** 在展示 activity 设计方案的**同一条回复**中调用 `suggest_activity`
- **帮助中心：** 在对 Flint 功能作出假设前，先检查帮助中心