README_ZH.md

🔧ShortcutsBench📱

Read this in English.

快捷指令（Shortcuts）是什么？

快捷指令是由开发者在快捷指令App中，通过用户友好的图形化界面🖼️，利用提供的基本动作构建的工作流🔄。苹果官方称其为“一种可让你使用 App 完成一个或多个任务的快捷方式。”📱

此项目任务清单（持续更新中）📋

所有的数据、数据获取过程、清洗数据时产生的数据、清洗脚本、实验脚本、结果等所有文件，请参见deves_dataset/dataset_src/README.md（英文）或（中文）、deves_dataset/dataset_src_valid_apis/README.md（英文）或中文、和experiments/README.md（英文）或中文

• ShortcutsBench论文正文
• ShortcutsBench论文附录
• 数据获取过程的脚本、数据清洗和处理的脚本、实验代码、实验结果
• 我们为普通用户提供含有双语解释的快捷指令数据：即users_dataset/${website name}/${category name}/README.md（英文）或users_dataset/${website name}/${category name}/README_ZH.md（中文）中列出的快捷指令。一般快捷指令用户可以在我们的仓库中找到适合其工作或生活的快捷指令，导入苹果设备上的快捷指令App使用即可。每条快捷指令包括：
  1. 快捷指令的iCloud链接
  2. 快捷指令的功能描述
  3. 该快捷指令的来源

• 对于快捷指令的研究者：ShortcutsBench提供：（1）快捷指令（即golden的动作序列）；（2）查询（即安排给智能体的任务）；（3）APIs（即智能体可以使用的工具）。

  • 快捷指令

    • 快捷指令数据集未清洗版，即文件1_final_detailed_records_remove_repeat.json，可以依据deves_dataset/dataset_src/README.md（英文）或deves_dataset/dataset_src/README_ZH.md（中文）的描述进行下载，也可以直接从Google云盘或百度网盘获取，解压密码为shortcutsbench

      该文件中快捷指令涉及到的API不一定有相关的API定义文件

    • 快捷指令数据集，即文件1_final_detailed_records_filter_apis.json，可以依据deves_dataset/dataset_src/README.md（英文）或[deves_dataset/dataset_src/README_ZH.md]（中文）的描述进行下载，也可以直接从Google云盘或百度网盘获取，解压密码为shortcutsbench

      该文件中快捷指令涉及到的API均有相关的API定义文件。该文件为对1_final_detailed_records_remove_repeat.json清洗得到。如果一个快捷指令包含没有API定义文件的API，则该快捷指令被移除

    • 快捷指令数据集<=30版，即文件1_final_detailed_records_filter_apis_leq_30.json，可以依据experiments/README.md（英文）或[experiments/README_ZH.md]（中文）的描述进行下载，也可以直接从Google云盘或百度网盘获取，解压密码为shortcutsbench

      考虑到语言模型上下文长度的限制，在ShortcutsBench论文正文中，我们仅评测了长度<=30的快捷指令

  • 查询。我们生成的查询如generated_success_queries.json所示，该文件可从Google云盘或百度网盘获取，解压密码为shortcutsbench

    查询是依据1_final_detailed_records_filter_apis_leq_30.json生成的

  • APIs。我们获取到的API如4_api_json_filter.json所示，该文件可从Google云盘或百度网盘获取，解压密码为shortcutsbench

    4_api_json_filter.json经过我们手动的去重，但依旧存在少量重复文件。直接从App中提取出的未经过处理的文件详见4_api_json.json，该文件可从Google云盘或百度网盘获取，解压密码为shortcutsbench

该项目对您有什么帮助？

苹果开发者大会 WWDC'24在苹果设备上引入了大量AI功能🤖。我们非常关注苹果如何将以ChatGPT为代表的大语言模型与设备结合，为用户带来更智能的体验💡。在这个过程中，快捷指令一定会发挥重要作用！🚀

作为快捷指令用户和爱好者📱

您可以在此数据集中找到您最心仪的快捷指令📱，一键帮你完成各种复杂任务！例如：

• 🏡 日常生活 🤹

  • 节日提醒
  • 百度贴吧签到
  • ......

• 🛍️ 购物党 🛒

  • 购买PUBG Mobile UC
  • 复制淘宝口令
  • ......

• 🧑‍🎓 学生党 🧮

  • 计算器
  • 放空心灵
  • ......

• ⌨️ 文字工作者 🔣

  • 翻译器
  • 制作PDF
  • ......

• 🧑‍🔬 科研工作者 🏫

  • 获取 arXiv bibtex 条目
  • ......

• .....

作为研究者🔬

• 研究自动化工作流的构建：快捷指令本质上是由一系列API调用（动作）构成的工作流，这些API由苹果和第三方App提供🔍
• 研究低代码编程：快捷指令包含分支、循环、变量赋值等代码特征，同时拥有用户友好的图形化界面🖥️
• 研究基于API的智能体：让大语言模型根据用户查询（任务）自主决定是否、何时以及如何使用API🔧
• 研究利用快捷指令微调大语言模型，促进大语言模型与手机、电脑、智能手表的紧密结合，实现“基于大语言模型的操作系统”的愿景📈
• ......

🌟ShortcutsBench对比现有基于API的智能体数据集的优势🌟

ShortcutsBench 在 API 的真实性、丰富性和复杂性，查询和相应动作序列的有效性，参数值的准确填充，从系统或用户获取信息的意识，以及整体规模方面具有显著优势。

据我们所知，ShortcutsBench 是首个基于真实 API 的大规模智能体基准，考虑了 API、查询及相应的动作序列。ShortcutsBench 提供了丰富的真实 API、不同难度和任务类型的查询、高质量的人类注释动作序列（由快捷方式开发者提供），以及来自真实用户需求的查询。此外，它还提供了精确的参数值填充，包括原始数据类型、枚举类型以及使用之前动作的输出作为参数值，并评估智能体在请求系统或用户必要信息方面的意识。再者，ShortcutsBench 中 API、查询及相应动作序列的规模可与由 LLM 创建或现有数据集修改的基准和数据集相媲美甚至更优。ShortcutsBench 与现有基准/数据集的总体对比见下表。

如果这个项目对您有帮助，请给我们一个Star吧⭐️！感谢支持！🙏

关键词：快捷指令, 苹果, WWDC'24, Siri, iOS, macOS, watchOS, 工作流, API调用, 低代码编程, 智能体, 大语言模型

快捷指令使用指南（面向用户）📱

搜索您想要的快捷指令🔍

在本仓库中，users_dataset/${website name}/${category name}/README.md文件用于记录该类别的所有快捷指令的元信息，包括名称、描述、iCloud下载链接等。每一个README.md文件的结构如下：

### Name: Wine Shops # 快捷指令名称
- URL: https://www.icloud.com/shortcuts/78ffd18288fd4da286bfd570993ea46e # 快捷指令iCloud链接
- Source: https://shortcutsgallery.com # 快捷指令来源商店
- Description: Look for Wine shop near by you # 快捷指令功能描述

使用快捷键Ctrl + F，根据快捷指令的名称关键词直接在浏览器中进行检索🔎。您也可以访问快捷指令搜集站搜索您想要的快捷指令🌐。

导入搜索到的快捷指令📥

在苹果设备上，点击URL中的iCloud链接后，快捷指令将会自动打开并导入到您的快捷指令App中📲。

下载快捷指令源文件

除了使用iCloud链接逐一下载快捷指令，您也直接从以下链接获取完整数据：

• 百度网盘
• Google云盘

数据源与链接 🌐

数据源	元数据位置	云盘链接
Matthewcassinelli	在本仓库的位置	Google云盘链接 | 百度网盘链接
Routinehub	在本仓库的位置	Google云盘链接 | 百度网盘链接
MacStories	在本仓库的位置	Google云盘链接 | 百度网盘链接
ShareShortcuts	在本仓库的位置	Google云盘链接 | 百度网盘链接
ShortcutsGallery	在本仓库的位置	Google云盘链接 | 百度网盘链接
iSpazio	在本仓库的位置	Google云盘链接 | 百度网盘链接
捷径库	在本仓库的位置	Google云盘链接 | 百度网盘链接
少数派	在本仓库的位置	Google云盘链接 | 百度网盘链接
捷径范	在本仓库的位置	Google云盘链接 | 百度网盘链接
柯基捷径库	在本仓库的位置	Google云盘链接 | 百度网盘链接
iOS快捷指令库	在本仓库的位置	Google云盘链接 | 百度网盘链接

快捷指令源文件简介

网盘中的快捷指令源数据以以下目录结构组织：

users_dataset/
├── matthewcassinelli.com_sirishortcuts_library_free # 网站名称
│   ├── file1
│   ├── file2
│   └── file3

或

users_dataset/
├── jiejingku.net # 网站名称
│   ├── category1 # 类别 
│   │   ├── file1 # 每一个具体的快捷指令
│   │   └── file2
│   ├── category2
│   │   └── file3

每个文件代表一个快捷指令。文件名由快捷指令名称简单处理后生成，处理代码如下：

file_name = re.sub(r'[^a-zA-Z0-9]', '_', name)

我们提供的快捷指令源文件为JSON格式，而从苹果设备中导出的快捷指令为iCloud链接（以链接形式分享）或是受到苹果加密的快捷指令文件（以.shortcut为后缀）。

若您希望将某个快捷指令源文件导入快捷指令App，请在macOS上进行以下操作：

• 将JSON文件格式转换为PLIST文件格式📑。

  import xml.etree.ElementTree as ET
  
  def parse_element(element):
    """
    递归解析XML元素，返回字典和列表。
    """
    if element.tag == 'dict':
        return {element[i].text: parse_element(element[i+1]) for i in range(0, len(element), 2)}
    elif element.tag == 'array':
        return [parse_element(child) for child in element]
    elif element.tag == 'true':
        return True
    elif element.tag == 'false':
        return False 
    elif element.tag == 'integer':
        return int(element.text)
    elif element.tag == 'string':
        return element.text
    elif element.tag == 'real':
        return float(element.text)
    else:
        raise ValueError("Unsupported tag: " + element.tag)
  
  tree = ET.parse(file_path)
  root_element = tree.getroot()
  parsed_data = parse_element(root_element[0])
  data = parsed_data
  
  save_path = "./"
  with open(save_path, 'w') as f:
      json.dump(data, f, indent=4)

• 对该PLIST文件进行签名🔏，即shortcuts sign --mode anyone --input $input_file --output $output_file，$input_file和$output_file换成实际的文件路径。
• 将签名后的文件导入快捷指令App📲。

ShortcutsBench数据集构建指南📚

我们在论文正文中详细阐述了ShortcutsBench的构建流程，详情请参见我们的论文，以下补充一些细节。

如何使用快捷指令？如何分享快捷指令？如何查看快捷指令的源文件？

1. 导入快捷指令到快捷指令App。

   可以通过在苹果设备上点击iCloud链接将快捷指令导入快捷指令app从而作为普通用户使用该快捷指令。

2. 分享快捷指令。

   • 可以通过macOS或iOS上的快捷指令App的Share将该快捷指令转换成iCloud链接进行分享。
   • 可以通过macOS上的快捷指令App的Share将该快捷指令以源文件的形式分享，分享得到的快捷指令以.shortcut为文件名后缀。注意：分享的源文件为苹果加密过后的源文件，无法直接使用python的plist包解析。

3. 解密单个或多个快捷指令。 如希望对某个快捷指令进行解密，可以使用如下快捷指令对别的快捷指令进行解密，解密后的文件为plist格式的文件。

   • Get Plist，解析单个shortcut为plist格式的文件
   • Get Plist Loop，解析快捷指令App中的所有shortcut为plist格式的文件并保存

   为了方便阅读，您可以选择将该plist格式的文件转化为json格式的文件，我们提供的shortcut源文件均为json格式。

4. 如何大规模的获取快捷指令源头文件？

   相比使用Get Plist和Get Plist Loop从快捷指令中解析出快捷指令，为了更快捷高效的大量获取快捷指令的源文件，我们遵循了以下两个步骤：

   1. 获取形如https://www.icloud.com/shortcuts/${unique_id}。
   2. 从https://www.icloud.com/shortcuts/api/records/${unique_id}。
   3. 从上一步骤中获得的数据cur_dict中（可转化为json格式），拿到快捷指令源文件的下载链接cur_dict["fields"]["shortcut"]["value"]["downloadURL"]，再次请求该下载链接下载快捷指令的源文件。注意：该下载链接会很快过期，您需要尽快使用该链接。

   直接下载得到的源文件为plist文件格式，你可以选择将plist格式的文件专户为json格式的文件。

   以下代码（已简化）展示了上述所有过程，最终的response_json即为json格式的快捷指令源文件:

   response = requests.get(f"https://www.icloud.com/shortcuts/api/records/{unique_id}")
   
   cur_dict = response.json()
   downloadURL = cur_dict["fields"]["shortcut"]["value"]["downloadURL"]
   new_response = requests.get(downloadURL)
   # 使用plist包转换为json存储在response_json中
   response_json = biplist.readPlistFromString(new_response.content)

许可声明 📜

本项目中的所有代码和数据集均依据Apache License 2.0进行许可。这意味着您可以自由地使用、复制、修改和分发本项目的内容，但需遵守以下条件：

• 版权声明：必须在项目的所有副本中保留原始版权声明和许可证声明。
• 状态声明：如果对代码进行了修改，必须在任何修改文件中标明所做的更改。
• 商标使用：本许可不授予使用项目商标、服务标志或商品名称的权利。

完整的许可证文本请见LICENSE。

此外，您还需遵守本项目数据来源，各个快捷指令分享站的许可协议。

引用

如果您觉得有用，请考虑引用我们的工作：

@misc{
    shen2024shortcutsbenchlargescalerealworldbenchmark,
    title={ShortcutsBench: A Large-Scale Real-world Benchmark for API-based Agents}, 
    author={Haiyang Shen and Yue Li and Desong Meng and Dongqi Cai and Sheng Qi and Li Zhang and Mengwei Xu and Yun Ma},
    year={2024},
    eprint={2407.00132},
    archivePrefix={arXiv},
    primaryClass={cs.SE},
    url={https://arxiv.org/abs/2407.00132}, 
}