506 lines
23 KiB
TypeScript
506 lines
23 KiB
TypeScript
/*
|
||
欢迎来到 TypeScript/JavaScript AI 工具开发终极入门教程 (v2.0 详细版)
|
||
====================================================================
|
||
|
||
本教程为初学者设计，特别是那些熟悉其他脚本语言（如Python）但对TypeScript/JavaScript不熟悉的开发者。
|
||
我们将从最基础的语法开始，一步步带你构建一个功能完整、结构优雅的AI工具，并详细解释每一步背后的“为什么”。
|
||
*/
|
||
|
||
|
||
// =================================================================
|
||
// Part 0: 关于运行环境 (A Note on the Environment)
|
||
// =================================================================
|
||
/*
|
||
在开始之前，你需要知道，你的代码并不是在真空中运行。它在一个特殊的“沙箱”环境中执行。
|
||
这个环境为你预先提供了一些全局可用的函数和对象，最重要的有：
|
||
|
||
1. `complete(result: object)`:
|
||
- 这是你的工具与AI系统沟通的【唯一】桥梁。
|
||
- 当你的工具执行完毕，无论成功还是失败，都必须调用这个函数来返回结果。
|
||
- AI会根据你传入这个函数的对象内容，来决定下一步的行为。
|
||
|
||
2. `exports`:
|
||
- 这是一个特殊的对象，你可以把它看作是你代码文件的“公开接口”。
|
||
- 你需要将你的工具函数“挂载”到 `exports` 对象上，AI才能找到并调用它们。
|
||
- 示例: `exports.myToolName = myToolFunction;`
|
||
|
||
3. `Tools`:
|
||
- 这是一个内置的工具集，提供了很多实用的辅助功能，比如文件读写、网络请求、系统命令等。
|
||
- 我们在本教程中会用到 `Tools.System.sleep()` 来演示异步操作。
|
||
|
||
本教程的所有代码都在一个TypeScript文件（.ts）中。TypeScript是JavaScript的超集，它增加了“类型系统”，
|
||
能帮助我们编写更健壮、更不容易出错的代码。
|
||
*/
|
||
|
||
|
||
// =================================================================
|
||
// Part 1: JavaScript / TypeScript 核心语法快速入门
|
||
// =================================================================
|
||
/*
|
||
本部分将详细介绍编写AI工具必需的JS/TS语法，并为每个知识点提供代码示例。
|
||
*/
|
||
|
||
// --- 1.1 变量声明 (Variables) ---
|
||
/*
|
||
- `const` (常量): 用于声明一个值不会再改变的变量。这是首选的声明方式，能让代码更可预测。
|
||
- `let` (变量): 用于声明一个值将来可能需要被修改的变量。
|
||
*/
|
||
function variable_example() {
|
||
const toolName = "My Greeter Tool"; // 一旦设定，toolName就不能再被赋值
|
||
let executionCount = 0; // executionCount 的值可以改变
|
||
console.log(`工具名称: ${toolName}`);
|
||
|
||
executionCount = executionCount + 1;
|
||
console.log(`这是第 ${executionCount} 次执行。`);
|
||
|
||
// 下面这行代码会报错，因为 toolName 是一个常量
|
||
// toolName = "New Name";
|
||
}
|
||
// variable_example(); // 你可以取消注释来在本地测试这些函数
|
||
|
||
|
||
// --- 1.2 数据类型 (Data Types) ---
|
||
/*
|
||
TypeScript 强制我们思考数据的类型，这极大地减少了运行时错误。
|
||
- `string`: 文本字符串。
|
||
- `number`: 数字（整数或浮点数）。
|
||
- `boolean`: 布尔值 (`true` 或 `false`)。
|
||
- `object`: 对象，键值对的集合，类似于Python的字典。
|
||
- `array`: 数组，有序的数据列表，类似于Python的列表。
|
||
- `any`: 特殊类型，表示“任何类型都可以”。应尽量避免使用，因为它会削弱TypeScript的优势。
|
||
*/
|
||
function data_types_example() {
|
||
// 我们可以明确地为变量注解类型
|
||
const userName: string = "Alice";
|
||
const userAge: number = 30;
|
||
const isActive: boolean = true;
|
||
|
||
// 对象类型注解，描述了一个对象的“形状”
|
||
const userInfo: { name: string; age: number; premium: boolean } = {
|
||
name: "Bob",
|
||
age: 25,
|
||
premium: false
|
||
};
|
||
console.log(`${userInfo.name} 的年龄是 ${userInfo.age}`);
|
||
|
||
// 数组类型注解，`string[]` 表示一个“只包含字符串的数组”
|
||
const permissions: string[] = ["read", "write", "execute"];
|
||
console.log(`用户的第一个权限是: ${permissions[0]}`);
|
||
|
||
// 遍历数组
|
||
permissions.forEach(permission => {
|
||
console.log(`权限: ${permission}`);
|
||
});
|
||
}
|
||
// data_types_example();
|
||
|
||
|
||
// --- 1.3 函数 (Functions) 与 异步操作 (Async Operations) ---
|
||
/*
|
||
- `async function`: 这是定义AI工具函数的标准方式。`async` 关键字表明该函数内部可能包含需要“等待”的操作。
|
||
- `await`: 必须在 `async` 函数内部使用。它会暂停函数的执行，直到其后的异步操作（通常是一个`Promise`）完成，然后返回结果。
|
||
- `Promise<T>`: 代表一个异步操作最终完成（或失败）的结果。`async` 函数的返回值总是一个`Promise`。
|
||
例如 `Promise<string>` 意味着这个异步函数最终会返回一个字符串。
|
||
*/
|
||
async function async_function_example(name: string): Promise<string> {
|
||
console.log(`开始向 ${name} 发送问候...`);
|
||
|
||
// `await` 在这里暂停函数，等待 Tools.System.sleep(1500) 完成
|
||
// 这模拟了一个耗时1.5秒的网络请求或文件操作
|
||
await Tools.System.sleep(1500);
|
||
|
||
const greetingMessage = `你好, ${name}! 异步问候已送达。`;
|
||
console.log(greetingMessage);
|
||
|
||
// async 函数通过 return 返回的值，会被包装在 Promise 中
|
||
return greetingMessage;
|
||
}
|
||
// async_function_example("Charlie");
|
||
|
||
|
||
// --- 1.4 错误处理 (Error Handling) ---
|
||
/*
|
||
- `try...catch`: 这是处理潜在错误的标准方式，对于健壮的工具至关重要。
|
||
- `throw new Error(...)`: 当函数执行不下去时，主动“抛出”一个错误，中断当前`try`块的执行，并被`catch`块捕获。
|
||
*/
|
||
function error_handling_example(input: any) {
|
||
try {
|
||
console.log("尝试处理输入...");
|
||
|
||
// 步骤1: 检查输入是否为非空字符串
|
||
if (typeof input !== 'string' || input.trim() === '') {
|
||
// 如果检查失败，就“抛出”一个错误对象
|
||
throw new Error("输入必须是一个非空的字符串。");
|
||
}
|
||
|
||
// 步骤2: 如果代码能执行到这里，说明没有错误发生
|
||
console.log(`输入有效，内容是: "${input}"`);
|
||
return { success: true, data: input };
|
||
|
||
} catch (error) {
|
||
// 步骤3: 如果`try`块中任何地方抛出了错误，程序会立即跳转到这里
|
||
console.error("发生了一个错误!");
|
||
console.error(`错误详情: ${error.message}`); // error.message 包含了我们抛出时提供的信息
|
||
|
||
// 在实际工具中，这里我们会调用 complete() 来报告失败
|
||
return { success: false, message: error.message };
|
||
}
|
||
}
|
||
// error_handling_example("这是一个有效的输入");
|
||
// error_handling_example(""); // 这个会触发错误
|
||
// error_handling_example(123); // 这个也会触发错误
|
||
|
||
|
||
// =================================================================
|
||
// Part 2: AI工具的本质 与 `complete()` 函数
|
||
// =================================================================
|
||
/*
|
||
如前所述，一个AI工具就是一个函数，它通过 `complete()` 函数与AI系统交互。
|
||
下面是一个最基础的、结构完整的AI工具示例，我们为其中的关键部分添加了注释。
|
||
*/
|
||
async function simple_greeter_tool(params: { user_name: string }) {
|
||
// 典型的工具函数总是在一个大的 try...catch 块中
|
||
try {
|
||
// 1. 从 AI 接收到的参数中解构出需要的值
|
||
const { user_name } = params;
|
||
|
||
// 2. 参数校验：永远不要相信输入！
|
||
if (!user_name) {
|
||
throw new Error("参数 'user_name' 缺失，无法生成问候语。");
|
||
}
|
||
|
||
// 3. 执行核心业务逻辑
|
||
const greeting = `你好, ${user_name}! 欢迎来到AI工具的世界。`;
|
||
|
||
// 4. 调用 complete()，报告成功
|
||
// - success: true 表示工具成功完成了它的任务。
|
||
// - data: 存放工具的执行结果，这是AI最关心的部分。
|
||
complete({
|
||
success: true,
|
||
data: greeting
|
||
});
|
||
|
||
} catch (error) {
|
||
// 5. 如果 try 块中任何地方出错（无论是参数校验还是业务逻辑），都会进入这里
|
||
console.error("simple_greeter_tool 执行失败:", error);
|
||
|
||
// 6. 调用 complete()，报告失败
|
||
// - success: false 告诉AI任务失败了。
|
||
// - message: 存放清晰的错误信息，帮助AI理解失败原因。
|
||
complete({
|
||
success: false,
|
||
message: `工具执行失败: ${error.message}`
|
||
});
|
||
}
|
||
}
|
||
|
||
|
||
// =================================================================
|
||
// Part 3: Metadata 和 函数导出 - 连接AI与代码的桥梁
|
||
// =================================================================
|
||
/*
|
||
我们已经写好了工具函数，但AI如何知道它的存在、功能和用法呢？
|
||
这需要两样东西：
|
||
1. `METADATA` (元数据): 就像是工具的“说明书”。
|
||
2. `exports` (导出): 像是把工具函数“注册”到系统里。
|
||
|
||
--- 3.1 详解 METADATA ---
|
||
文件顶部的 ` METADATA ... ` 注释块就是这份说明书。AI在加载时会解析它。
|
||
- `name`: (string) 工具集的唯一ID。
|
||
- `description`: (string) 对整个工具集的详细描述。
|
||
- `tools`: (array) 一个数组，包含此文件中所有可用的工具。
|
||
- `name`: (string) 单个工具的函数名。这个名字【必须】和后面 `exports` 中使用的名字完全一致。
|
||
- `description`: (string) 对这个工具能做什么的清晰描述。AI会根据这个描述来决定何时调用它。
|
||
- `parameters`: (array) 定义了此工具需要哪些参数。
|
||
- `name`: (string) 参数名。
|
||
- `description`: (string) 对参数用途的描述。
|
||
- `type`: (string) 参数的类型 (e.g., 'string', 'number', 'boolean')。
|
||
- `required`: (boolean) 这个参数是否是必需的。
|
||
*/
|
||
|
||
/* METADATA
|
||
{
|
||
"name": "greeter_tool_v2",
|
||
|
||
"display_name": {
|
||
"zh": "问候工具 V2",
|
||
"en": "Greeting Tool V2"
|
||
},
|
||
"description": { "zh": "一个提供多种问候方式的教学工具集。", "en": "A tutorial tool package that demonstrates multiple greeting methods." },
|
||
"category": "Utility",
|
||
"tools": [
|
||
{
|
||
"name": "greet",
|
||
"description": { "zh": "向指定的人发送一个标准的问候。", "en": "Send a standard greeting to a specified person." },
|
||
"parameters": [
|
||
{
|
||
"name": "user_name",
|
||
"description": { "zh": "要问候的人的名字。", "en": "Name of the person to greet." },
|
||
"type": "string",
|
||
"required": true
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"name": "system_inspector",
|
||
"description": { "zh": "获取设备摘要信息，并在用户的HOME目录下查找符合特定模式的文件。", "en": "Get device summary information and find files matching a pattern under the user's HOME directory." },
|
||
"parameters": [
|
||
{
|
||
"name": "search_pattern",
|
||
"description": { "zh": "用于文件搜索的通配符模式，例如：'*.txt' 或 'documents/*.pdf'。", "en": "Glob pattern for file search, e.g. '*.txt' or 'documents/*.pdf'." },
|
||
"type": "string",
|
||
"required": true
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}*/
|
||
|
||
// --- 3.2 详解 exports ---
|
||
/*
|
||
`exports` 是一个空对象，等待你来填充。
|
||
你必须将你的工具函数赋值给 `exports` 对象的一个属性，属性名必须和 `METADATA` 中定义的工具 `name` 完全一致。
|
||
只有这样，AI才能把“说明书”和“实际的函数实现”关联起来。
|
||
|
||
`exports.greet = simple_greeter_tool;`
|
||
|
||
上面这行代码的意思是：
|
||
“当AI想要调用名为 'greet' 的工具时，请执行 `simple_greeter_tool` 这个函数。”
|
||
(我们将在教程的最后进行统一导出，所以暂时注释掉这行)
|
||
*/
|
||
|
||
|
||
// =================================================================
|
||
// Part 4: IIFE模式 - 隔离作用域，避免代码冲突
|
||
// =================================================================
|
||
/*
|
||
当项目变大，你可能会定义很多辅助函数、变量。如果都放在全局（文件的顶层），很容易与其他工具或系统库产生命名冲突。
|
||
IIFE (Immediately Invoked Function Expression - 立即调用函数表达式) 是解决这个问题的经典JS模式。
|
||
|
||
它的写法是 `(function() { ... })();`
|
||
- `(function() { ... })` 定义了一个匿名函数。
|
||
- 最后的 `()` 表示“立即执行”这个刚刚定义的匿名函数。
|
||
|
||
这样做的好处是创建了一个“私有作用域”。在IIFE内部声明的任何变量或函数，在外部都是不可见的，从而避免了污染全局命名空间。
|
||
我们可以通过 `return` 语句，有选择性地将需要公开的函数暴露出来。
|
||
*/
|
||
|
||
// 使用IIFE模式重构我们的问候工具
|
||
const greeterToolBox = (function () {
|
||
// --- 这里是私有作用域 ---
|
||
|
||
// `version` 和 `logWithTimestamp` 在IIFE外部无法被访问，是我们的内部实现细节。
|
||
const version = "2.0";
|
||
|
||
function logWithTimestamp(message: string) {
|
||
const timestamp = new Date().toLocaleTimeString();
|
||
console.log(`[${timestamp}][v${version}] ${message}`);
|
||
}
|
||
|
||
// 这是我们真正的业务逻辑实现
|
||
async function performGreeting(params: { user_name: string }) {
|
||
try {
|
||
logWithTimestamp(`开始执行问候工具，参数: ${JSON.stringify(params)}`);
|
||
const { user_name } = params;
|
||
if (!user_name) {
|
||
throw new Error("参数 'user_name' 缺失。");
|
||
}
|
||
const greeting = `你好, ${user_name}! (来自IIFE模式 v${version})`;
|
||
complete({ success: true, data: greeting });
|
||
} catch (error) {
|
||
logWithTimestamp(`问候工具失败: ${error.message}`);
|
||
complete({ success: false, message: error.message });
|
||
}
|
||
}
|
||
|
||
// --- 公开接口 ---
|
||
// 通过 return 一个对象，我们将 `performGreeting` 函数以 `greet` 的名字暴露出去。
|
||
return {
|
||
greet: performGreeting
|
||
// 如果有其他工具，可以继续在这里暴露: anotherTool: someInternalFunction
|
||
};
|
||
|
||
})(); // 注意这里，函数被立即执行了
|
||
|
||
// 现在，IIFE已经执行完毕，`greeterToolBox` 变量包含了我们返回的对象。
|
||
// 我们可以这样导出它：
|
||
// `exports.greet = greeterToolBox.greet;`
|
||
|
||
|
||
// =================================================================
|
||
// Part 5: Wrapper模式 - 终极形态，让代码更健壮、更简洁
|
||
// =================================================================
|
||
/*
|
||
观察上面的代码，即使使用了IIFE，`performGreeting` 函数内部仍然有重复的 `try/catch` 和 `complete()` 调用。
|
||
在软件工程中，重复的代码（boilerplate）是维护的噩梦。
|
||
|
||
我们可以创建一个 `wrapper` (包装器) 函数来终结这种重复。
|
||
Wrapper 的职责非常清晰：
|
||
1. 接收一个“核心业务逻辑函数”作为输入。
|
||
2. 在内部建立 `try/catch` 安全网。
|
||
3. 负责调用核心函数，并等待其结果。
|
||
4. 无论成功还是失败，都由它来调用 `complete()` 并返回标准格式的结果。
|
||
|
||
这样，我们编写的工具函数就可以变得非常纯粹：只关心输入、业务处理和输出（通过`return`和`throw`），
|
||
完全不用理会 `try/catch` 和 `complete` 这些模板代码。
|
||
*/
|
||
|
||
// --- 最终的、最推荐的开发模式 ---
|
||
|
||
const finalTool = (function () {
|
||
|
||
// 1. 定义我们的通用 Wrapper 函数
|
||
// 它接收一个核心逻辑函数和其所需的参数。
|
||
async function wrap(coreFunction: (params: any) => Promise<any>, params: any) {
|
||
try {
|
||
// 调用核心业务逻辑，并使用 await 等待其完成
|
||
const result = await coreFunction(params);
|
||
|
||
// 核心逻辑成功返回，Wrapper负责包装成标准成功对象并调用complete
|
||
complete({
|
||
success: true,
|
||
message: "工具执行成功。",
|
||
data: result // 将核心函数的返回值放入data字段
|
||
});
|
||
|
||
} catch (error: any) {
|
||
console.error(`工具 [${coreFunction.name}] 执行时捕获到错误:`, error);
|
||
|
||
// 核心逻辑抛出异常，Wrapper负责捕获并包装成标准失败对象
|
||
complete({
|
||
success: false,
|
||
message: `错误: ${error.message}`, // 将错误信息放入message字段
|
||
error_stack: error.stack // 附带完整的错误堆栈以供调试
|
||
});
|
||
}
|
||
}
|
||
|
||
// =================================================
|
||
// 核心业务逻辑区 (Core Logic Functions)
|
||
// =================================================
|
||
|
||
// 2a. “问候”工具的核心逻辑
|
||
async function greet_core_logic(params: { user_name: string }): Promise<string> {
|
||
if (!params.user_name || params.user_name.trim() === '') {
|
||
throw new Error("user_name 不能为空。");
|
||
}
|
||
const greeting = `你好, ${params.user_name}! 这是一个采用终极Wrapper模式的工具。`;
|
||
return greeting;
|
||
}
|
||
|
||
// 2b. “系统检查器”工具的核心逻辑
|
||
async function inspect_system_core_logic(params: { search_pattern: string }): Promise<object> {
|
||
if (!params.search_pattern) {
|
||
throw new Error("search_pattern 不能为空。");
|
||
}
|
||
|
||
console.log(`开始系统检查，搜索模式: '${params.search_pattern}'`);
|
||
|
||
// 为了让逻辑更清晰，我们一步一步地、顺序地调用工具
|
||
// 1. 首先，获取设备信息
|
||
console.log("正在获取设备信息...");
|
||
const deviceInfo = await Tools.System.getDeviceInfo();
|
||
console.log("设备信息获取成功。");
|
||
|
||
// 2. 然后，查找文件
|
||
console.log(`正在主目录 ('~') 下查找文件，模式: '${params.search_pattern}'`);
|
||
const foundFiles = await Tools.Files.find('~', params.search_pattern);
|
||
console.log("文件查找成功。");
|
||
|
||
// 组合结果并返回一个结构化的对象
|
||
return {
|
||
device: deviceInfo,
|
||
files: foundFiles
|
||
};
|
||
}
|
||
|
||
|
||
// =================================================
|
||
// 导出函数封装区 (Exported Functions)
|
||
// =================================================
|
||
|
||
// 3a. 暴露给AI的“问候”函数
|
||
async function greet_exported_function(params: { user_name: string }) {
|
||
await wrap(greet_core_logic, params);
|
||
}
|
||
|
||
// 3b. 暴露给AI的“系统检查器”函数
|
||
async function inspect_system_exported_function(params: { search_pattern: string }) {
|
||
await wrap(inspect_system_core_logic, params);
|
||
}
|
||
|
||
|
||
// 4. 从IIFE中返回所有需要导出的工具
|
||
return {
|
||
greet: greet_exported_function,
|
||
system_inspector: inspect_system_exported_function
|
||
};
|
||
|
||
})();
|
||
|
||
|
||
// =================================================================
|
||
// Part 6: 使用内置工具集 (Using the Built-in `Tools`)
|
||
// =================================================================
|
||
/*
|
||
沙箱环境提供了一个强大的全局对象 `Tools`，它是你与外部世界交互的主要入口。
|
||
`Tools` 对象被组织成多个模块，每个模块负责一类特定的功能。
|
||
|
||
主要的模块包括：
|
||
- `Tools.System`: 系统级操作。
|
||
- `getDeviceInfo()`: 获取设备信息（型号、操作系统版本等）。
|
||
- `sleep(ms)`: 让工具暂停指定的毫秒数。
|
||
- `exec(command)`: 执行shell命令。
|
||
- `Tools.Files`: 文件系统操作。
|
||
- `read(path)`: 读取文件内容。
|
||
- `write(path, content)`: 写入内容到文件。
|
||
- `find(directory, pattern)`: 在指定目录中查找匹配模式的文件。
|
||
- `remove(path)`: 删除文件或目录。
|
||
- `Tools.Net`: 网络操作。
|
||
- `fetch(url, options)`: 发起HTTP请求，类似于浏览器中的`fetch`。
|
||
- `Tools.UI`: 与设备UI交互（高级功能）。
|
||
- `getScreenshot()`: 获取当前屏幕截图。
|
||
- `findAndClick(text)`: 查找并点击包含特定文本的UI元素。
|
||
- `Tools.Memory`: 记忆管理功能。
|
||
- `query(query)`: 查询记忆库。
|
||
- `create(title, content, ...)`: 创建新记忆。
|
||
- `update(oldTitle, updates)`: 更新记忆。
|
||
- `deleteMemory(title)`: 删除记忆。
|
||
- `link(sourceTitle, targetTitle, ...)`: 链接记忆。
|
||
- `Tools.FFmpeg`: 音视频处理（高级功能）。
|
||
|
||
所有的 `Tools` 函数都是【异步】的，意味着你必须使用 `await` 来调用它们，
|
||
并且调用它们的代码必须位于 `async` 函数内部。
|
||
|
||
在上面的 `Part 5` 中，我们已经为你演示了如何实现一个名为 `system_inspector` 的新工具。
|
||
它完美地展示了：
|
||
1. 如何在核心逻辑函数中调用 `Tools.System.getDeviceInfo()` 和 `Tools.Files.find()`。
|
||
2. 如何按顺序地调用多个异步工具，等待每一个操作完成后再进行下一步。
|
||
3. 如何将这些调用集成到我们健壮的 `Wrapper` 模式中。
|
||
|
||
请回头仔细阅读 `Part 5` 中 `inspect_system_core_logic` 函数的实现，
|
||
它是你学习使用内置 `Tools` 的最佳起点。
|
||
*/
|
||
|
||
|
||
// ==========================================
|
||
// 最终导出 (Final Export)
|
||
// ==========================================
|
||
// 将我们在最终IIFE模式中返回的函数，挂载到exports上。
|
||
// 这里的 `greet` 和 `system_inspector` 必须和METADATA中定义的工具 `name` 完全一致。
|
||
exports.greet = finalTool.greet;
|
||
exports.system_inspector = finalTool.system_inspector;
|
||
|
||
/*
|
||
🎓 恭喜! 你已经学完了从零到一的完整开发流程。
|
||
|
||
现在回顾一下我们构建最终代码形态的旅程：
|
||
1. **基础语法**: 掌握了编写代码的基本工具。
|
||
2. **基础工具+complete()**: 理解了AI工具的本质和与系统的交互方式。
|
||
3. **Metadata+exports**: 学会了如何让AI“发现”并“使用”你的工具。
|
||
4. **IIFE模式**: 学会了如何通过作用域隔离来组织代码，避免命名冲突，使代码更模块化。
|
||
5. **Wrapper模式**: 学会了如何通过分离“业务逻辑”和“模板代码”来编写更简洁、更健壮、更易于维护的工具代码。
|
||
6. **内置工具 `Tools`**: 学会了如何利用系统提供的强大工具与文件、网络和操作系统进行交互。
|
||
|
||
这套“Wrapper + IIFE + Tools”的组合是经过实践检验的最佳实践，强烈建议你在开发自己的工具时采用它。
|
||
*/
|