拓冰网站定制 
AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载core.d.ts是 Operit 包ToolPkg脚本运行环境的基础类型定义文件覆盖工具调用、结果结构、NativeInterface原生桥接以及若干全局工具对象。本文以 docs/doc-src/package-dev/core.md 为骨架结合 examples/types/core.d.ts 的真实声明与 app/src/main/java/com/ai/assistance/operit/core/tools/javascript 下的运行时实现完整讲解toolCall()、complete()、NativeInterface与_/dataUtils的用法读完即可在自己的包脚本中正确使用这些基础能力并理解底层桥接行为。一、core.d.ts在整个类型体系中的位置在 Operit 的包开发类型体系中examples/types/index.d.ts 是总入口它会重导出core.d.ts、results.d.ts、tool-types.d.ts、java-bridge.d.ts、toolpkg.d.ts等全部类型文件并把sendIntermediateResult、getEnv、Tools、Java、Kotlin等对象挂到全局作用域。而core.d.ts负责的是“地基”通用参数与结果类型ToolParams、ToolConfig、BaseResult及各结果子类型全局函数toolCall()与complete()NativeInterface原生桥接命名空间轻量工具对象_与dataUtilsCommonJS 风格的exports对象。也就是说任何包脚本无论调用什么高级模块最终都要经过这层基础能力与 Android 原生运行时对话。二、基础类型参数与结果的契约2.1ToolParamsinterface ToolParams { [key: string]: string | number | boolean | object; }用于描述一次工具调用的参数集合。它是一个宽松的索引签名类型任何普通 JSON 风格的键值对都可以作为工具参数传入。需要说明的是object与array在 TypeScript 中都可以落到这个索引签名里因此嵌套结构也能表达。2.2ToolConfiginterface ToolConfig { type?: string; name: string; params?: ToolParams; onIntermediateResult?: (value: unknown) void; }用于对象形式的toolCall()。注意在 examples/types/core.d.ts 中ToolConfig还额外声明了onIntermediateResult?: (value: unknown) void回调字段用于接收工具的中间结果——这正是“需要中间结果时请使用带onIntermediateResult的重载”这一建议的类型依据。2.3 结果类型族所有结构化结果都继承同一个BaseResultinterface BaseResult { success: boolean; error?: string; }StringResult/BooleanResult/NumberResult三种基本结果在BaseResult之上带两个成员data对应类型的实际数据toString()将结果转换为字符串的便捷方法。ToolResult是把它们联合起来的类型type ToolResult StringResult | BooleanResult | NumberResult | (BaseResult { data: any })最后的BaseResult { data: any }分支保证任何自定义工具结果例如 examples/types/results.d.ts 中定义的HttpResponseData、FileContentData等都能兼容这个联合类型。2.4ToolReturnTypeTexport type ToolReturnTypeT extends string T extends keyof import(./tool-types).ToolResultMap ? import(./tool-types).ToolResultMap[T] : any;ToolReturnTypeT会根据 examples/types/tool-types.d.ts 中的ToolResultMap为toolCall()推导返回类型。ToolResultMap是一张“工具名 → 结果数据类型”的映射表例如read_file: FileContentDatahttp_request: HttpResponseDatalist_files: DirectoryListingDatacalculate: CalculationResultDataexecute_terminal: TerminalCommandResultData当工具名命中映射表时toolCall()的返回值会被精确推导为对应类型未命中的名字则回退为any。这意味着只要工具名正确IDE 就能给出对应结果data字段的补全提示。三、全局函数toolCall()发起工具调用3.1 全部重载core.d.ts中共声明了 6 个重载文档中列出 4 个核心形态examples/types/core.d.ts 中还补充了两个带options的形态toolCallT extends string(toolType: string, toolName: T, toolParams?: ToolParams): PromiseToolReturnTypeT; toolCallT extends string(toolName: T, toolParams?: ToolParams): PromiseToolReturnTypeT; toolCallT extends string(config: ToolConfig { name: T }): PromiseToolReturnTypeT; toolCallT extends string, TIntermediate unknown(toolType: string, toolName: T, toolParams: ToolParams | undefined, options: ToolCallOptionsTIntermediate): PromiseToolReturnTypeT; toolCallT extends string, TIntermediate unknown(toolName: T, toolParams: ToolParams | undefined, options: ToolCallOptionsTIntermediate): PromiseToolReturnTypeT; toolCall(toolName: string): Promiseany;其中ToolCallOptions的定义为export interface ToolCallOptionsTIntermediate unknown { onIntermediateResult?: (value: TIntermediate) void; }最常用的是省略toolType的简写形式const result await toolCall(read_file, { path: /sdcard/a.txt });或者对象形式const result await toolCall({ name: http_request, params: { url: https://example.com } });3.2 异步桥接与并行语义重要文档与源码都明确了两条运行时语义写脚本时必须注意toolCall()运行时走的是异步桥接但 JS 回调的分发仍会回到同一个 QuickJS 运行时线程。也就是说异步等待并不会把脚本切到其他线程执行。Promise.all([...toolCall(...)])只表示“同时等待多个 Promise”不保证底层工具一定并行执行是否真正并行取决于对应工具执行器本身的实现。如果你需要并发效果应确认目标工具执行器是否支持并行而不能仅凭Promise.all推断。在运行时一侧app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsNativeInterfaceDelegates.kt 提供了callToolSync、callToolAsync、callToolAsyncStreaming等底层实现分别对应同步调用、异步回调与流式中间结果回调三种模式app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsEngine.kt 负责把NativeInterface桥接对象暴露给 JS 运行时exposeNativeInterfaceBridgeObject并处理结果回传session.future.complete(...)。3.3 中间结果如果需要中间结果例如长任务逐步输出进度请使用带onIntermediateResult的重载const result await toolCall( long_running_tool, { /* 参数 */ }, { onIntermediateResult: (value) { sendIntermediateResult(value); } } );底层对应的流式入口是NativeInterface.callToolAsyncStreaming(callbackId, intermediateCallbackId, toolType, toolName, paramsJson)在 examples/types/core.d.ts 中同样有声明。四、全局函数complete(result)结束脚本并返回结果completeT(result: T): voidcomplete(result)结束脚本执行并返回结果。文档给出的两条补充说明在实战中非常关键导出函数既可以直接return result也可以显式调用complete(result)两者都是正式接口该契约在 docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.md 中被再次确认。complete(result)适合需要手动结束、或配合 emitter / 异步回调流使用的场景——此时函数体可能已经先返回稍后才由回调触发完成。另外examples/types/core.d.ts 的注释补充了一条约束结果值必须是 JSON 可序列化的Java 桥接实例会被序列化为桥接句柄。这意味着complete()不能直接返回任意 JS 对象以外的运行时对象如函数、非序列化句柄。五、NativeInterface更底层的原生桥接NativeInterface是直接面向 Android 原生层的桥接接口。多数业务代码优先使用Tools.*、toolCall()或全局对象只有在需要桥接级能力时才直接使用它。5.1 工具调用与日志callTool(toolType, toolName, paramsJson)同步调用工具返回代表ToolResult的 JSON 字符串legacy 方法。callToolAsync(callbackId, toolType, toolName, paramsJson)异步调用回调会收到一个ToolResult对象。callToolAsyncStreaming(callbackId, intermediateCallbackId, toolType, toolName, paramsJson)流式异步调用额外提供中间结果回调。logInfo(message)、logError(message)、logDebug(message, data)三类日志输出。脚本通过complete(result)返回执行结果运行时内部的回调方法不属于NativeInterface公共接口。文档中给出的典型日志写法NativeInterface.logInfo(start); NativeInterface.logDebug(payload, JSON.stringify({ ok: true }));5.2 ToolPkg 注册相关NativeInterface还承载了 ToolPkg 各类扩展模块的注册入口参数均为描述对应模块的 JSON 字符串registerToolPkgToolboxUiModule(specJson)注册工具箱 UI 模块registerToolPkgAppLifecycleHook(specJson)注册应用生命周期钩子registerToolPkgMessageProcessingPlugin(specJson)注册消息处理插件registerToolPkgXmlRenderPlugin(specJson)注册 XML 渲染插件registerToolPkgInputMenuTogglePlugin(specJson)注册输入栏开关插件。此外examples/types/core.d.ts 还声明了更多同类注册入口registerToolPkgChatInputHook聊天输入钩子、registerToolPkgChatMessageHook聊天消息钩子、registerToolPkgChatMessageMenuItem聊天消息长按菜单项ToolPkg API 1.0.1 起、registerToolPkgChatRuntimeHook聊天运行时钩子ToolPkg API 1.0.1 起。这些入口与 docs/doc-src/package-dev/toolpkg.md 中讲解的 ToolPkg API 对应是包级扩展能力的桥接层。另外还有一个实用方法getPluginConfigDir(pluginId)返回某个包或 ToolPkg 的持久化配置目录路径位于/sdcard/Download/Operit/plugins/id之下。5.3 图片注册registerImageFromBase64(base64: string, mimeType: string): string; registerImageFromPath(path: string): string;这两个方法会把图片注册到全局图片池并返回一个可嵌入消息的link typeimage id...字符串工具结果或消息里直接拼接该字符串即可引用图片。典型用法const imageLink NativeInterface.registerImageFromPath(/sdcard/demo.png); complete({ imageLink });5.4 错误上报reportError(errorType: string, errorMessage: string, errorLine: number, errorStack: string): void;用于把带类型、消息、行号与堆栈的 JS 错误上报给运行时便于在原生侧统一收集脚本异常。5.5 Java / Kotlin 桥接NativeInterface暴露了一组底层 Java / Kotlin 桥接方法这些方法普遍返回桥接 JSON 字符串需要调用方自行解析javaClassExists(className)检查 Java/Kotlin 类是否存在javaGetApplicationContext()获取应用Context返回{success:boolean,data?:{__javaHandle:string,__javaClass:string},error?:string}形态的桥接 JSONjavaGetCurrentActivity()获取当前前台ActivityjavaNewInstance(className, argsJson)创建实例javaCallStatic(className, methodName, argsJson)调用静态方法javaCallInstance(instanceHandle, methodName, argsJson)调用实例方法javaHasInstanceMethod(instanceHandle, methodName)检查实例是否具有某方法javaGetStaticField/javaSetStaticField/javaGetInstanceField/javaSetInstanceField读写静态与实例字段javaLoadDex(path, optionsJson)、javaLoadJar(path, optionsJson)、javaListLoadedCodePaths()加载并列出外部 dex/jar 代码路径examples/types/core.d.ts。文档还明确了三条与脚本开发者相关的桥接纪律对脚本开发者承诺的高层 Java Bridge 接口统一以 docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.md 为准。那里定义了Java.type/Java.use/Java.importClass/Java.package等入口、构造与调用语法糖new Cls(...)、obj.method(...)、Cls.STATIC_FIELD等、Java.implement/Java.proxy接口实现、callSuspend挂起调用以及 Java ↔ JS 双向类型转换表。Java 实例句柄的解绑属于运行时内部生命周期管理不再提供公开的release/releaseAll脚本接口。Java.implement(...)/Java.proxy(...)产生的 JS 回调对象改为运行时自动解绑旧的脚本侧手动释放接口已移除。同时有两处值得注意的运行时行为obj.methodName()是首选用法运行时会优先把实例成员按方法来解释尽量保证语法糖可用obj.call(methodName, ...)仍然保留主要用于极少数字段/方法同名冲突或底层调试场景。Java.implement(...)创建的 JS 回调实际仍在 QuickJS 运行时线程执行不会把 JS 代码真正迁移到 Java 子线程里运行。这与第 3.2 节“回调分发回到同一 QuickJS 线程”的语义是一致的。六、全局工具对象_、dataUtils与exports6.1_轻量 Lodash 风格子集当前只声明了一个轻量子集共 8 个方法覆盖类型判断与集合遍历export declare const _: { isEmpty(value: any): boolean; isString(value: any): boolean; isNumber(value: any): boolean; isBoolean(value: any): boolean; isObject(value: any): boolean; isArray(value: any): boolean; forEachT(collection: T[] | object, iteratee: (value: any, key: any, collection: any) void): any; mapT, R(collection: T[] | object, iteratee: (value: any, key: any, collection: any) R): R[]; };注意forEach/map的iteratee回调签名为(value, key, collection)同时兼容数组与普通对象因此不需要额外引入 Lodash 即可完成常见的数据加工。6.2dataUtilsparseJson(jsonString: string): any; stringifyJson(obj: any): string; formatDate(date?: Date | string): string;parseJson把 JSON 字符串解析为对象stringifyJson把对象序列化为 JSON 字符串formatDate格式化日期参数可省略缺省时格式化当前时间也接受Date对象或日期字符串。6.3exportsvar exports: { [key: string]: any }用于 CommonJS 风格导出。脚本可以像在 Node.js 中一样把函数或对象挂到exports上供运行时按模块语义引用。七、完整示例7.1 使用toolCall()读取文件并返回const file await toolCall(read_file, { path: /sdcard/demo.txt }); complete(file);7.2 记录日志NativeInterface.logInfo(start); NativeInterface.logDebug(payload, JSON.stringify({ ok: true }));7.3 注册图片到消息const imageLink NativeInterface.registerImageFromPath(/sdcard/demo.png); complete({ imageLink });7.4 组合使用基础能力/// reference path./types/index.d.ts / NativeInterface.logInfo(script start); const json dataUtils.stringifyJson({ a: 1, b: x }); const parsed dataUtils.parseJson(json); const response await toolCall(http_request, { url: https://example.com, method: GET }); if (_.isEmpty(response.data)) { complete({ success: false, error: empty response }); } else { complete({ success: true, status: response.data.statusCode }); }八、与index.d.ts的分工core.d.ts定义的是“基础能力”examples/types/index.d.ts 会在此基础上把更多对象和辅助函数挂到全局作用域例如sendIntermediateResult发送中间结果getEnv/getState/getLang/getCallerName/getChatId/getCallerCardId上下文读取Tools把Files、Net、System、SoftwareSettings、UI、FFmpeg、Tasker、Workflow、Chat、Memory、calc组装成一个命名空间Java/Kotlin高层 Java 桥接Intent/UINode/Android等 Android 相关对象以及OPERIT_DOWNLOAD_DIR、OPERIT_CLEAN_ON_EXIT_DIR常量。脚本开发时通常在顶部用/// reference path./types/index.d.ts /一次性引入全部类型IDE 即可识别全局 API 与结果类型但理解core.d.ts仍是读懂一切的基础。更完整的全局对象说明见 docs/doc-src/package-dev/index.md。九、相关文件速查examples/types/core.d.ts本文讲解的核心类型声明文件本体examples/types/tool-types.d.tsToolResultMap工具名 → 结果类型映射examples/types/index.d.ts类型总入口与全局对象注入docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.mdJava Bridge 接口契约docs/doc-src/package-dev/index.md包开发类型系统总览app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsNativeInterfaceDelegates.ktcallToolSync/callToolAsync/callToolAsyncStreaming等桥接实现app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsEngine.ktNativeInterface桥接对象暴露与脚本结果回传。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐Operit 工作流脚本开发指南Workflow 类型系统与 Tools.Workflow 运行时 API 全解析Operit 工作流脚本开发指南Workflow 类型系统与 Tools.Workflow 运行时 API 全解析 workflow.d.ts 是 OperiAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 脚本运行时开发指南CommonJS 模块系统、Java/Kotlin Bridge 与 compose_dsl 实战Operit 脚本运行时开发指南CommonJS 模块系统、Java/Kotlin Bridge 与 compose_dsl 实战 导读 本文以 app/srAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 示例脚本开发指南VSCode/ADB 真机运行 JavaScript 与 ToolPkg 工具包编写Operit 示例脚本开发指南VSCode/ADB 真机运行 JavaScript 与 ToolPkg 工具包编写 本指南围绕 examples/READMEAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化上一篇华硕主板FanControl传感器识别终极指南从零到精通的5步完整解决方案下一篇D2DX宽屏补丁让经典《暗黑破坏神2》在现代PC上完美重生的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Operit 包开发核心 API 指南：深入解析 `core.d.ts` 与脚本运行时基础能力
AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载core.d.ts是 Operit 包ToolPkg脚本运行环境的基础类型定义文件覆盖工具调用、结果结构、NativeInterface原生桥接以及若干全局工具对象。本文以 docs/doc-src/package-dev/core.md 为骨架结合 examples/types/core.d.ts 的真实声明与 app/src/main/java/com/ai/assistance/operit/core/tools/javascript 下的运行时实现完整讲解toolCall()、complete()、NativeInterface与_/dataUtils的用法读完即可在自己的包脚本中正确使用这些基础能力并理解底层桥接行为。一、core.d.ts在整个类型体系中的位置在 Operit 的包开发类型体系中examples/types/index.d.ts 是总入口它会重导出core.d.ts、results.d.ts、tool-types.d.ts、java-bridge.d.ts、toolpkg.d.ts等全部类型文件并把sendIntermediateResult、getEnv、Tools、Java、Kotlin等对象挂到全局作用域。而core.d.ts负责的是“地基”通用参数与结果类型ToolParams、ToolConfig、BaseResult及各结果子类型全局函数toolCall()与complete()NativeInterface原生桥接命名空间轻量工具对象_与dataUtilsCommonJS 风格的exports对象。也就是说任何包脚本无论调用什么高级模块最终都要经过这层基础能力与 Android 原生运行时对话。二、基础类型参数与结果的契约2.1ToolParamsinterface ToolParams { [key: string]: string | number | boolean | object; }用于描述一次工具调用的参数集合。它是一个宽松的索引签名类型任何普通 JSON 风格的键值对都可以作为工具参数传入。需要说明的是object与array在 TypeScript 中都可以落到这个索引签名里因此嵌套结构也能表达。2.2ToolConfiginterface ToolConfig { type?: string; name: string; params?: ToolParams; onIntermediateResult?: (value: unknown) void; }用于对象形式的toolCall()。注意在 examples/types/core.d.ts 中ToolConfig还额外声明了onIntermediateResult?: (value: unknown) void回调字段用于接收工具的中间结果——这正是“需要中间结果时请使用带onIntermediateResult的重载”这一建议的类型依据。2.3 结果类型族所有结构化结果都继承同一个BaseResultinterface BaseResult { success: boolean; error?: string; }StringResult/BooleanResult/NumberResult三种基本结果在BaseResult之上带两个成员data对应类型的实际数据toString()将结果转换为字符串的便捷方法。ToolResult是把它们联合起来的类型type ToolResult StringResult | BooleanResult | NumberResult | (BaseResult { data: any })最后的BaseResult { data: any }分支保证任何自定义工具结果例如 examples/types/results.d.ts 中定义的HttpResponseData、FileContentData等都能兼容这个联合类型。2.4ToolReturnTypeTexport type ToolReturnTypeT extends string T extends keyof import(./tool-types).ToolResultMap ? import(./tool-types).ToolResultMap[T] : any;ToolReturnTypeT会根据 examples/types/tool-types.d.ts 中的ToolResultMap为toolCall()推导返回类型。ToolResultMap是一张“工具名 → 结果数据类型”的映射表例如read_file: FileContentDatahttp_request: HttpResponseDatalist_files: DirectoryListingDatacalculate: CalculationResultDataexecute_terminal: TerminalCommandResultData当工具名命中映射表时toolCall()的返回值会被精确推导为对应类型未命中的名字则回退为any。这意味着只要工具名正确IDE 就能给出对应结果data字段的补全提示。三、全局函数toolCall()发起工具调用3.1 全部重载core.d.ts中共声明了 6 个重载文档中列出 4 个核心形态examples/types/core.d.ts 中还补充了两个带options的形态toolCallT extends string(toolType: string, toolName: T, toolParams?: ToolParams): PromiseToolReturnTypeT; toolCallT extends string(toolName: T, toolParams?: ToolParams): PromiseToolReturnTypeT; toolCallT extends string(config: ToolConfig { name: T }): PromiseToolReturnTypeT; toolCallT extends string, TIntermediate unknown(toolType: string, toolName: T, toolParams: ToolParams | undefined, options: ToolCallOptionsTIntermediate): PromiseToolReturnTypeT; toolCallT extends string, TIntermediate unknown(toolName: T, toolParams: ToolParams | undefined, options: ToolCallOptionsTIntermediate): PromiseToolReturnTypeT; toolCall(toolName: string): Promiseany;其中ToolCallOptions的定义为export interface ToolCallOptionsTIntermediate unknown { onIntermediateResult?: (value: TIntermediate) void; }最常用的是省略toolType的简写形式const result await toolCall(read_file, { path: /sdcard/a.txt });或者对象形式const result await toolCall({ name: http_request, params: { url: https://example.com } });3.2 异步桥接与并行语义重要文档与源码都明确了两条运行时语义写脚本时必须注意toolCall()运行时走的是异步桥接但 JS 回调的分发仍会回到同一个 QuickJS 运行时线程。也就是说异步等待并不会把脚本切到其他线程执行。Promise.all([...toolCall(...)])只表示“同时等待多个 Promise”不保证底层工具一定并行执行是否真正并行取决于对应工具执行器本身的实现。如果你需要并发效果应确认目标工具执行器是否支持并行而不能仅凭Promise.all推断。在运行时一侧app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsNativeInterfaceDelegates.kt 提供了callToolSync、callToolAsync、callToolAsyncStreaming等底层实现分别对应同步调用、异步回调与流式中间结果回调三种模式app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsEngine.kt 负责把NativeInterface桥接对象暴露给 JS 运行时exposeNativeInterfaceBridgeObject并处理结果回传session.future.complete(...)。3.3 中间结果如果需要中间结果例如长任务逐步输出进度请使用带onIntermediateResult的重载const result await toolCall( long_running_tool, { /* 参数 */ }, { onIntermediateResult: (value) { sendIntermediateResult(value); } } );底层对应的流式入口是NativeInterface.callToolAsyncStreaming(callbackId, intermediateCallbackId, toolType, toolName, paramsJson)在 examples/types/core.d.ts 中同样有声明。四、全局函数complete(result)结束脚本并返回结果completeT(result: T): voidcomplete(result)结束脚本执行并返回结果。文档给出的两条补充说明在实战中非常关键导出函数既可以直接return result也可以显式调用complete(result)两者都是正式接口该契约在 docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.md 中被再次确认。complete(result)适合需要手动结束、或配合 emitter / 异步回调流使用的场景——此时函数体可能已经先返回稍后才由回调触发完成。另外examples/types/core.d.ts 的注释补充了一条约束结果值必须是 JSON 可序列化的Java 桥接实例会被序列化为桥接句柄。这意味着complete()不能直接返回任意 JS 对象以外的运行时对象如函数、非序列化句柄。五、NativeInterface更底层的原生桥接NativeInterface是直接面向 Android 原生层的桥接接口。多数业务代码优先使用Tools.*、toolCall()或全局对象只有在需要桥接级能力时才直接使用它。5.1 工具调用与日志callTool(toolType, toolName, paramsJson)同步调用工具返回代表ToolResult的 JSON 字符串legacy 方法。callToolAsync(callbackId, toolType, toolName, paramsJson)异步调用回调会收到一个ToolResult对象。callToolAsyncStreaming(callbackId, intermediateCallbackId, toolType, toolName, paramsJson)流式异步调用额外提供中间结果回调。logInfo(message)、logError(message)、logDebug(message, data)三类日志输出。脚本通过complete(result)返回执行结果运行时内部的回调方法不属于NativeInterface公共接口。文档中给出的典型日志写法NativeInterface.logInfo(start); NativeInterface.logDebug(payload, JSON.stringify({ ok: true }));5.2 ToolPkg 注册相关NativeInterface还承载了 ToolPkg 各类扩展模块的注册入口参数均为描述对应模块的 JSON 字符串registerToolPkgToolboxUiModule(specJson)注册工具箱 UI 模块registerToolPkgAppLifecycleHook(specJson)注册应用生命周期钩子registerToolPkgMessageProcessingPlugin(specJson)注册消息处理插件registerToolPkgXmlRenderPlugin(specJson)注册 XML 渲染插件registerToolPkgInputMenuTogglePlugin(specJson)注册输入栏开关插件。此外examples/types/core.d.ts 还声明了更多同类注册入口registerToolPkgChatInputHook聊天输入钩子、registerToolPkgChatMessageHook聊天消息钩子、registerToolPkgChatMessageMenuItem聊天消息长按菜单项ToolPkg API 1.0.1 起、registerToolPkgChatRuntimeHook聊天运行时钩子ToolPkg API 1.0.1 起。这些入口与 docs/doc-src/package-dev/toolpkg.md 中讲解的 ToolPkg API 对应是包级扩展能力的桥接层。另外还有一个实用方法getPluginConfigDir(pluginId)返回某个包或 ToolPkg 的持久化配置目录路径位于/sdcard/Download/Operit/plugins/id之下。5.3 图片注册registerImageFromBase64(base64: string, mimeType: string): string; registerImageFromPath(path: string): string;这两个方法会把图片注册到全局图片池并返回一个可嵌入消息的link typeimage id...字符串工具结果或消息里直接拼接该字符串即可引用图片。典型用法const imageLink NativeInterface.registerImageFromPath(/sdcard/demo.png); complete({ imageLink });5.4 错误上报reportError(errorType: string, errorMessage: string, errorLine: number, errorStack: string): void;用于把带类型、消息、行号与堆栈的 JS 错误上报给运行时便于在原生侧统一收集脚本异常。5.5 Java / Kotlin 桥接NativeInterface暴露了一组底层 Java / Kotlin 桥接方法这些方法普遍返回桥接 JSON 字符串需要调用方自行解析javaClassExists(className)检查 Java/Kotlin 类是否存在javaGetApplicationContext()获取应用Context返回{success:boolean,data?:{__javaHandle:string,__javaClass:string},error?:string}形态的桥接 JSONjavaGetCurrentActivity()获取当前前台ActivityjavaNewInstance(className, argsJson)创建实例javaCallStatic(className, methodName, argsJson)调用静态方法javaCallInstance(instanceHandle, methodName, argsJson)调用实例方法javaHasInstanceMethod(instanceHandle, methodName)检查实例是否具有某方法javaGetStaticField/javaSetStaticField/javaGetInstanceField/javaSetInstanceField读写静态与实例字段javaLoadDex(path, optionsJson)、javaLoadJar(path, optionsJson)、javaListLoadedCodePaths()加载并列出外部 dex/jar 代码路径examples/types/core.d.ts。文档还明确了三条与脚本开发者相关的桥接纪律对脚本开发者承诺的高层 Java Bridge 接口统一以 docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.md 为准。那里定义了Java.type/Java.use/Java.importClass/Java.package等入口、构造与调用语法糖new Cls(...)、obj.method(...)、Cls.STATIC_FIELD等、Java.implement/Java.proxy接口实现、callSuspend挂起调用以及 Java ↔ JS 双向类型转换表。Java 实例句柄的解绑属于运行时内部生命周期管理不再提供公开的release/releaseAll脚本接口。Java.implement(...)/Java.proxy(...)产生的 JS 回调对象改为运行时自动解绑旧的脚本侧手动释放接口已移除。同时有两处值得注意的运行时行为obj.methodName()是首选用法运行时会优先把实例成员按方法来解释尽量保证语法糖可用obj.call(methodName, ...)仍然保留主要用于极少数字段/方法同名冲突或底层调试场景。Java.implement(...)创建的 JS 回调实际仍在 QuickJS 运行时线程执行不会把 JS 代码真正迁移到 Java 子线程里运行。这与第 3.2 节“回调分发回到同一 QuickJS 线程”的语义是一致的。六、全局工具对象_、dataUtils与exports6.1_轻量 Lodash 风格子集当前只声明了一个轻量子集共 8 个方法覆盖类型判断与集合遍历export declare const _: { isEmpty(value: any): boolean; isString(value: any): boolean; isNumber(value: any): boolean; isBoolean(value: any): boolean; isObject(value: any): boolean; isArray(value: any): boolean; forEachT(collection: T[] | object, iteratee: (value: any, key: any, collection: any) void): any; mapT, R(collection: T[] | object, iteratee: (value: any, key: any, collection: any) R): R[]; };注意forEach/map的iteratee回调签名为(value, key, collection)同时兼容数组与普通对象因此不需要额外引入 Lodash 即可完成常见的数据加工。6.2dataUtilsparseJson(jsonString: string): any; stringifyJson(obj: any): string; formatDate(date?: Date | string): string;parseJson把 JSON 字符串解析为对象stringifyJson把对象序列化为 JSON 字符串formatDate格式化日期参数可省略缺省时格式化当前时间也接受Date对象或日期字符串。6.3exportsvar exports: { [key: string]: any }用于 CommonJS 风格导出。脚本可以像在 Node.js 中一样把函数或对象挂到exports上供运行时按模块语义引用。七、完整示例7.1 使用toolCall()读取文件并返回const file await toolCall(read_file, { path: /sdcard/demo.txt }); complete(file);7.2 记录日志NativeInterface.logInfo(start); NativeInterface.logDebug(payload, JSON.stringify({ ok: true }));7.3 注册图片到消息const imageLink NativeInterface.registerImageFromPath(/sdcard/demo.png); complete({ imageLink });7.4 组合使用基础能力/// reference path./types/index.d.ts / NativeInterface.logInfo(script start); const json dataUtils.stringifyJson({ a: 1, b: x }); const parsed dataUtils.parseJson(json); const response await toolCall(http_request, { url: https://example.com, method: GET }); if (_.isEmpty(response.data)) { complete({ success: false, error: empty response }); } else { complete({ success: true, status: response.data.statusCode }); }八、与index.d.ts的分工core.d.ts定义的是“基础能力”examples/types/index.d.ts 会在此基础上把更多对象和辅助函数挂到全局作用域例如sendIntermediateResult发送中间结果getEnv/getState/getLang/getCallerName/getChatId/getCallerCardId上下文读取Tools把Files、Net、System、SoftwareSettings、UI、FFmpeg、Tasker、Workflow、Chat、Memory、calc组装成一个命名空间Java/Kotlin高层 Java 桥接Intent/UINode/Android等 Android 相关对象以及OPERIT_DOWNLOAD_DIR、OPERIT_CLEAN_ON_EXIT_DIR常量。脚本开发时通常在顶部用/// reference path./types/index.d.ts /一次性引入全部类型IDE 即可识别全局 API 与结果类型但理解core.d.ts仍是读懂一切的基础。更完整的全局对象说明见 docs/doc-src/package-dev/index.md。九、相关文件速查examples/types/core.d.ts本文讲解的核心类型声明文件本体examples/types/tool-types.d.tsToolResultMap工具名 → 结果类型映射examples/types/index.d.ts类型总入口与全局对象注入docs/doc-src/dev-core/JAVA_BRIDGE_INTERFACE.mdJava Bridge 接口契约docs/doc-src/package-dev/index.md包开发类型系统总览app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsNativeInterfaceDelegates.ktcallToolSync/callToolAsync/callToolAsyncStreaming等桥接实现app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsEngine.ktNativeInterface桥接对象暴露与脚本结果回传。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐Operit 工作流脚本开发指南Workflow 类型系统与 Tools.Workflow 运行时 API 全解析Operit 工作流脚本开发指南Workflow 类型系统与 Tools.Workflow 运行时 API 全解析 workflow.d.ts 是 OperiAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 脚本运行时开发指南CommonJS 模块系统、Java/Kotlin Bridge 与 compose_dsl 实战Operit 脚本运行时开发指南CommonJS 模块系统、Java/Kotlin Bridge 与 compose_dsl 实战 导读 本文以 app/srAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 示例脚本开发指南VSCode/ADB 真机运行 JavaScript 与 ToolPkg 工具包编写Operit 示例脚本开发指南VSCode/ADB 真机运行 JavaScript 与 ToolPkg 工具包编写 本指南围绕 examples/READMEAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化上一篇华硕主板FanControl传感器识别终极指南从零到精通的5步完整解决方案下一篇D2DX宽屏补丁让经典《暗黑破坏神2》在现代PC上完美重生的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考