@@ -4,8 +4,6 @@ Assistant Tool 是 Scripting 应用中为智能助手(Assistant)提供系统
44
55本文以一个示例工具「Request Current Location」为基础,介绍 Assistant Tool 的完整实现流程,包括工具创建、配置文件说明、执行逻辑实现以及各类函数的详细说明。
66
7- ---
8-
97## 一、工具创建流程
108
1191 . 打开任意脚本项目,在文件管理界面点击“添加 Assistant Tool”按钮。
@@ -16,8 +14,6 @@ Assistant Tool 是 Scripting 应用中为智能助手(Assistant)提供系统
1614- ` assistant_tool.json ` :描述工具的元数据和参数信息。
1715- ` assistant_tool.tsx ` :实现工具的执行逻辑。
1816
19- ---
20-
2117## 二、配置文件 assistant_tool.json
2218
2319该文件用于声明工具的基本信息和行为配置。以下是示例内容及字段说明:
@@ -38,19 +34,17 @@ Assistant Tool 是 Scripting 应用中为智能助手(Assistant)提供系统
3834
3935### 字段说明:
4036
41- | 字段 | 类型 | 说明 |
42- | ------------------ | ------- | -------------------------------- |
43- | ` displayName ` | string | 工具在界面中显示的名称 |
44- | ` id ` | string | 工具唯一标识符,不能重复 |
45- | ` description ` | string | 工具功能描述 |
46- | ` icon ` | string | 使用的 SF Symbols 图标名 |
47- | ` color ` | string | 工具主色调 |
48- | ` parameters ` | array | 工具需要的参数(为空表示无输入) |
49- | ` requireApproval ` | boolean | 是否需要用户批准 |
50- | ` autoApprove ` | boolean | 是否支持 Assistant 自动批准 |
51- | ` scriptEditorOnly ` | boolean | 工具是否仅能在脚本编辑器中使用 |
52-
53- ---
37+ | 字段 | 类型 | 说明 |
38+ | | - | -- |
39+ | ` displayName ` | string | 工具在界面中显示的名称 |
40+ | ` id ` | string | 工具唯一标识符,不能重复 |
41+ | ` description ` | string | 工具功能描述 |
42+ | ` icon ` | string | 使用的 SF Symbols 图标名 |
43+ | ` color ` | string | 工具主色调 |
44+ | ` parameters ` | array | 工具需要的参数(为空表示无输入) |
45+ | ` requireApproval ` | boolean | 是否需要用户批准 |
46+ | ` autoApprove ` | boolean | 是否支持 Assistant 自动批准 |
47+ | ` scriptEditorOnly ` | boolean | 工具是否仅能在脚本编辑器中使用 |
5448
5549## 三、执行逻辑 assistant_tool.tsx 实现示例
5650
@@ -111,8 +105,6 @@ testRequestLocationExecuteFn(
111105);
112106```
113107
114- ---
115-
116108## 四、AssistantTool 注册函数详解
117109
118110### 1. ` registerApprovalRequest `
@@ -135,8 +127,6 @@ function registerApprovalRequest<P>(
135127
136128返回的测试函数可用于在脚本编辑器中模拟触发批准请求。
137129
138- ---
139-
140130### 2. ` registerExecuteToolWithApproval `
141131
142132注册一个需要用户批准的执行函数。
@@ -175,8 +165,6 @@ type UserActionForApprovalRequest = {
175165- ` success ` : 是否执行成功。
176166- ` message ` : 返回给 Assistant 的执行成功或失败的信息。
177167
178- ---
179-
180168### 3. ` registerExecuteTool `
181169
182170注册一个不需要用户批准的工具逻辑。
@@ -187,8 +175,6 @@ function registerExecuteTool<P>(executeFn: AssistantToolExecuteFn<P>): Assistant
187175
188176** 适用场景** :如操作无敏感性、不涉及设备权限时,可使用此方式。
189177
190- ---
191-
192178### 4. 测试函数使用
193179
194180每个注册函数会返回对应的测试函数,可在脚本中运行:
@@ -205,8 +191,6 @@ testExecuteFn(
205191testExecuteToolFn ({ ... params });
206192```
207193
208- ---
209-
210194## 五、脚本编辑器接口说明(ScriptEditorProvider)
211195
212196当工具设置为 ` scriptEditorOnly: true ` 时,系统提供 ` ScriptEditorProvider ` 接口,允许访问脚本项目的文件系统与语法信息。
@@ -220,8 +204,6 @@ testExecuteToolFn({ ...params });
220204
221205适用于如格式化脚本、批量修改内容等编辑类工具。
222206
223- ---
224-
225207## 六、执行与用户体验流程
226208
2272091 . Assistant 在会话中判断是否需要调用某个工具。
@@ -230,8 +212,6 @@ testExecuteToolFn({ ...params });
230212 - 用户点击“允许”后执行工具逻辑。
2312133 . 执行结果通过 ` message ` 字段返回给 Assistant,并可呈现给用户。
232214
233- ---
234-
235215## 七、无需批准的工具实现方式
236216
237217当不需要显示批准提示时,可直接使用 ` registerExecuteTool ` 注册逻辑函数:
@@ -248,8 +228,6 @@ AssistantTool.registerExecuteTool<MyParams>(async (params) => {
248228
249229将 ` assistant_tool.json ` 中的 ` requireApproval ` 字段设置为 ` false ` 即可。
250230
251- ---
252-
253231## 八、小结
254232
255233Assistant Tool 是 Scripting 应用提供的可扩展能力模块,支持用户授权、文件操作、系统调用等多种场景。开发流程主要包括:
0 commit comments