本项目配置了通过VSCode直接运行JavaScript文件到Android设备的功能。这让您可以快速开发和测试JavaScript脚本,无需手动执行命令行工具。
- 确保安装了VSCode
- 确保Android设备已连接并已启用USB调试
- 确保ADB工具可用(已添加到系统路径)
- 确保Android设备上安装了兼容的应用程序
- 在VSCode中打开要运行的JavaScript文件
- 按下
F5键或点击调试菜单中的"开始调试" - 在弹出的输入框中输入以下信息:
- 要执行的JavaScript函数名(如:
showMessage) - 函数参数,使用JSON格式(如:
{"name": "张三", "message": "你好"})
- 要执行的JavaScript函数名(如:
- 执行结果将在终端窗口显示
- 在VSCode中打开要运行的JavaScript文件
- 按下
Ctrl+Shift+B(Windows/Linux)或Cmd+Shift+B(macOS) - 在弹出的输入框中输入函数名和参数,同上
项目中包含了示例脚本 examples/demo_script.js,其中定义了以下函数:
默认函数,简单返回提供的参数。
示例参数:{"message": "测试"}
显示消息和当前时间。
示例参数:{"name": "张三", "message": "欢迎使用"}
执行简单的计算操作。
示例参数:{"a": 10, "b": 5, "operation": "add"}
可用的操作类型:
add:加法subtract:减法multiply:乘法divide:除法
- 确保JavaScript函数中使用
complete()函数返回结果,这是必须的 - 参数必须是有效的JSON格式
- 脚本执行可能需要一些时间,请耐心等待结果
- 如果遇到问题,请检查VSCode的终端输出和Android设备的日志
如果需要更复杂的执行选项,可以直接在命令行使用以下命令:
Windows:
.\tools\adb\execute_js.bat <JS文件路径> <函数名> <JSON参数或@参数文件>
Linux/macOS:
./tools/adb/execute_js.sh <JS文件路径> <函数名> <JSON参数或@参数文件>
例如:
.\tools\adb\execute_js.bat examples\demo_script.js calculate @params.json
补充说明:
@params.json是当前最稳的传参方式,尤其适合 Windows / PowerShell- 如果使用
run_sandbox_script.*或包内的debug_run_sandbox_script并传source_code,代码会按“顶层脚本”执行 - 这类内联脚本里应使用
console.log(...)、emit(...)、complete(...) - 不要直接写
params.xxx或intermediate(...)
This directory contains tool packages that can be loaded by the AI assistant. These packages provide additional functionality to the assistant, allowing it to perform specialized tasks.
Packages can be defined in two formats:
- JavaScript (.js) - Preferred format with full support for Promise-based async execution
- HJSON (.hjson) - Legacy format with limited functionality (maintained for backward compatibility)
A JavaScript package consists of a single JavaScript file with:
- A metadata block at the top of the file
- Tool function definitions that implement the functionality
- Optional exports statements to make the functions available
/*
METADATA
{
"name": "example_package",
"description": "An example package showing how to create tools",
"tools": [
{
"name": "hello_world",
"description": "A simple hello world tool",
"parameters": [
{
"name": "name",
"description": "Name to greet",
"type": "string",
"required": true
}
]
}
],
"category": "FILE_READ"
}
*/
// Tool implementation
async function hello_world(params) {
// Access parameters
const name = params.name || "World";
// Use async/await with other tools
await Tools.System.sleep(1);
// Return a result
complete(`Hello, ${name}!`);
}
// Export the function
exports.hello_world = hello_world;You can also write your packages in TypeScript (.ts) with full type checking for all APIs. TypeScript packages are automatically compiled to JavaScript at runtime.
For tool packages under examples, Kotlin now converts tool params to strong types before invoking the TypeScript/JavaScript runtime, based on each tool's metadata.
- In TypeScript, parameter types should match metadata directly.
- Fields with
"required": falseshould be modeled as optional?. - Do not keep legacy TS-layer coercion such as
string -> number,string -> boolean,JSON string -> array/object, or duplicate "required parameter" checks that only existed to compensate for old permissive passthrough behavior. - Keep only validations that metadata cannot express well, such as enum/domain rules, cross-field constraints, and nested object/array shape checks.
Parameters passed to .ts example packages rely on Kotlin’s metadata-driven conversion. The Kotlin bridge reads each tool’s type/required flags and converts values before they arrive in JavaScript/TypeScript, which means the TS layer should trust the metadata typing and focus on higher-level business rules. Please do not add string→number/boolean/array coercion or re-check required fields that Kotlin already enforces, and treat required: false parameters as optional (?) with their actual primitive types.
/*
METADATA
{
"name": "typescript_example",
"description": "A TypeScript example package",
"tools": [
{
"name": "hello_world",
"description": "A simple hello world tool with TypeScript",
"parameters": [
{
"name": "name",
"description": "Name to greet",
"type": "string",
"required": true
}
]
}
],
"category": "FILE_READ"
}
*/
/**
* Simple hello world function with TypeScript
* @param params Tool parameters with name property
*/
async function hello_world(params: { name: string }): Promise<void> {
// Access parameters with type checking
const name = params.name || "World";
// Use async/await with proper typing
await Tools.System.sleep(1);
// Return a result
complete(`Hello, ${name}!`);
}
// Export the function
exports.hello_world = hello_world;All tool calls now return Promises, allowing for async/await pattern usage:
async function chain_example(params) {
try {
// Chain multiple tool calls with await
const fileList = await Tools.Files.list("/some/path");
const fileContents = await Tools.Files.read("/some/path/file.txt");
// Do work with the results
const result = `Found ${fileList.length} files. First file contents: ${fileContents}`;
complete(result);
} catch (error) {
complete(`Error: ${error.message}`);
}
}The following utility namespaces are available in all package scripts:
list(path)- List files in a directoryread(path)- Read file contentswrite(path, content)- Write content to filedeleteFile(path)- Delete a file or directoryexists(path)- Check if file existsmove(source, target)- Move file from source to targetcopy(source, target)- Copy file from source to targetmkdir(path)- Create a directoryfind(path, pattern)- Find files matching a patterninfo(path)- Get information about a filezip(source, target)- Zip files/directoriesunzip(source, target)- Unzip an archiveopen(path)- Open a file with system handler
httpGet(url)- Perform HTTP GET requesthttpPost(url, data)- Perform HTTP POST requestvisit(query)- Perform web search
exec(command)- Execute a system commandsleep(seconds)- Sleep for specified seconds
Tools.calc(expression)- Calculate mathematical expression_- Lodash-like utility librarydataUtils- Data processing utilities
- Create a new
.jsor.tsfile in this directory - Add a METADATA block at the top with package details
- Define your tool functions
- Export the functions using the CommonJS pattern
- Use the Promise-based API for any asynchronous operations
You can test your package by using the use_package tool in the assistant chat:
<tool name="use_package">
<param name="package_name">your_package_name</param>
</tool>
After the package is loaded, you can use any of its tools:
<tool name="your_package_name:your_tool_name">
<param name="param1">value1</param>
</tool>
Currently, these example scripts have a common issue: they contain duplicate function names across different files, even though the scripts are designed to operate independently. This can cause problems if:
- Multiple scripts are imported into the same project
- The scripts are executed in an environment where name collisions matter
- Future integration of these scripts is planned
Wrap all functions in a namespace object to avoid global namespace pollution:
// Instead of:
function get_history(params) { /* ... */ }
// Use:
const QQTools = {
get_history: function(params) { /* ... */ },
reply: function(params) { /* ... */ }
};
// Then call as:
QQTools.get_history(params);Use the module pattern to encapsulate functions:
const QQIntelligent = (function() {
// Private functions
function close_keyboard() { /* ... */ }
// Public API
return {
get_history: function(params) { /* ... */ },
reply: function(params) { /* ... */ }
};
})();Convert the scripts to proper ES6 modules:
// In qq_intelligent.ts
export function get_history(params) { /* ... */ }
export function reply(params) { /* ... */ }
// In another file that needs these functions
import { get_history, reply } from './qq_intelligent';If modifying the code structure is difficult, prefix all functions with a unique identifier:
function qq_get_history(params) { /* ... */ }
function qq_reply(params) { /* ... */ }Adopting one of these approaches would resolve the function name duplication issue while maintaining the independence of each script.