Operit 桥接接口对齐：core.d.ts 类型声明、Compose DSL 节点与开发文档同步实践

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点击查看免费下载本篇技术指南聚焦 OperitAndroid AI Agent 与 AI 聊天应用中 Kotlin 桥接层与 TypeScript 声明之间的对齐工作补全浏览器截图接口的Tools.Net.browserTakeScreenshot类型声明、为 Compose DSL 新增AiChat与AdaptiveSidePanel两个渲染节点并清理NativeInterface中无 Kotlin 实现的残留声明。读完本文你将理解 Operit 脚本运行时公共类型声明 ↔ Kotlin 实现双向对账的完整方法论并掌握如何从 examples/types/index.d.ts 获得正确的脚本类型提示。一、任务背景桥接层的两类接口来源Operit 的脚本运行时ToolPkg / 辅助包工具运行在 Android 端其 Kotlin 侧通过两条路径向 JS 暴露能力JsEngine的JavascriptInterface内部桥接方法由 ToolPkg 与运行时自行包装调用属于内部实现细节不属于面向脚本开发者的公开接口JsTools注入的Tools.*命名空间方法例如向Tools.Net注入的浏览器会话方法这是脚本作者直接调用的入口。问题正出在这两者与 TypeScript 声明之间的错位examples/types/network.d.ts缺少 Kotlin 已注入的Tools.Net.browserTakeScreenshot导致脚本作者无法获得该接口的类型提示examples/types/core.d.ts保留了没有 Kotlin 实现的setResult与setError声明Compose DSL 也缺少已确认需要公开的AiChat与AdaptiveSidePanel节点。详见任务索引 docs/TODO/kt_ts_bridge_alignment_20260809/index.md。二、修改范围与预期结果本次对齐工作更新三个类型文件并同步开发文档文件变更内容examples/types/core.d.tsNativeInterface移除setResult与setErrorexamples/types/network.d.ts新增Net.browserTakeScreenshot声明examples/types/compose-dsl.d.ts新增AiChat与AdaptiveSidePanel节点类型与工厂预期结果脚本作者能从 examples/types/index.d.ts 获得浏览器截图、嵌入聊天和自适应侧栏的类型提示且不会再看到没有 Kotlin 实现的旧桥接方法。三、清理NativeInterface移除无运行时实现的残留声明NativeInterface是core.d.ts中面向脚本开发者的直接调用 Android 的命名空间见 core.d.ts。其设计原则是公开类型只描述脚本开发者可直接使用的桥接方法而JsEngine中其余未声明的JavascriptInterface方法是 ToolPkg 或运行时内部桥接不应复制进core.d.ts。对齐后setResult与setError已从公开声明中移除其余公共声明均映射到 Kotlin 的JavascriptInterface实现包括callTool/callToolAsync/callToolAsyncStreaming同步与异步工具调用logInfo/logError/logDebug日志上报一系列registerToolPkg*注册接口工具箱 UI 模块、App 生命周期钩子、消息处理插件、XML 渲染插件、输入菜单开关插件、聊天输入/消息钩子、聊天消息长按菜单项、聊天运行时钩子等java*系列 Java/Kotlin 桥接方法javaLoadDex、javaLoadJar、javaCallStatic、javaCallInstance、javaGetApplicationContext等registerImageFromBase64/registerImageFromPath将图片注册进全局图片池并返回link typeimage id...标签串。清点过程记录在 docs/TODO/kt_ts_bridge_alignment_20260809/1_NativeBridgeInventory.md。四、补全Tools.Net.browserTakeScreenshot类型声明4.1 TypeScript 侧声明network.d.ts 中新增的声明如下/** * Capture the current browser page or a snapshot element as an image. * Supplying ref requires its matching snapshot element description. */ function browserTakeScreenshot(options: { type?: string; element?: string; ref?: string; fullPage?: boolean; }): Promisestring;四个参数字段中type指定截图输出格式element与ref用于截取快照中的单个元素二者必须成对出现fullPage控制是否整页截图。返回值为 JSON 字符串Promise 包裹。4.2 Kotlin 侧参数归一化逻辑Kotlin 注入实现位于 app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsTools.kt其对参数做了与声明一致的归一化处理只接受一个 options 对象否则抛错browserTakeScreenshot only accepts one options objecttype空值回落为png默认值element与ref必须成对提供ref而未提供element时抛错element is required when ref is provided反之亦然fullPage经!!强转为布尔值最终通过toolCall(browser_take_screenshot, params)转发给底层浏览器会话工具对应实现见 StandardBrowserSessionTools.kt。这使得运行时与 TypeScript 中的browserTakeScreenshot具有完全一致的参数与返回值语义。五、Compose DSL 新增AiChat与AdaptiveSidePanel节点Compose DSL 是 ToolPkg 中runtimecompose_dsl模块使用的声明式 UI 语言。本次为 compose-dsl.d.ts 新增两个节点5.1AiChatProps嵌入宿主 AI 聊天界面/** Embeds the host AI chat surface without its workspace panel. */ export interface AiChatProps extends ComposeCommonProps {}对应 Kotlin 渲染路径位于 ToolPkgComposeDslScreen.ktrenderAiChatNode将节点渲染为AIChatScreen(embedded true)即以嵌入式模式挂载宿主 AI 聊天界面不含工作区面板使脚本可以在自定义页面内直接嵌入完整聊天能力。5.2AdaptiveSidePanelProps响应式尾随面板/** Controls a responsive trailing panel around the supplied screen content. */ export interface AdaptiveSidePanelProps extends ComposeCommonProps { open: boolean; side: ComposeChildren; onOpenChanged: (open: boolean) void; defaultWidth?: number; minWidth?: number; minContentWidth?: number; breakpoint?: number; }Kotlin 实现位于 ToolPkgComposeDslScreen.kt其行为与各参数默认值如下参数默认值行为说明open—必填面板是否展开onOpenChanged—必填展开状态变化回调窄屏遮罩点击即触发关闭defaultWidth360f面板初始宽度dpminWidth280f面板最小宽度minContentWidth320f内容区最小宽度宽屏下面板最大宽度受maxWidth - minContentWidth约束breakpoint600f宽/窄布局切换的断点dpmaxWidth breakpoint视为宽屏实现细节宽屏isWideLayout下采用Row布局内容区占剩余权重面板区可通过居中的 24dp 拖拽手柄detectDragGestures实时调整宽度并在minWidth与maxWidth之间收敛窄屏下面板覆盖在内容之上并叠加半透明遮罩Color.Black.copy(alpha 0.18f)点击遮罩触发onOpenChanged(false)关闭。5.3 节点工厂注册两个节点均通过类型工厂导出compose-dsl.d.tsAiChat: ComposeNodeFactoryAiChatProps; AdaptiveSidePanel: ComposeNodeFactoryAdaptiveSidePanelProps;六、静态双向核对类型集合与实现集合的完全对齐任务执行约束为不运行编译、构建或测试命令验证完全依赖静态核对核对清单与完成标准记录在 docs/TODO/kt_ts_bridge_alignment_20260809/3_StaticVerification.mdcore.d.ts的NativeInterface不包含没有 Kotlin 实现的旧成员——每个成员均能在 KotlinJavascriptInterface中找到实现setResult与setError未出现在公开类型或开发文档JsTools.kt注入的浏览器截图方法与network.d.ts的Net成员比对——browserTakeScreenshot的四个参数字段与 Kotlin 参数归一化逻辑一致compose-dsl.d.ts新增节点与 Kotlin Compose DSL 节点分发比对——AiChat与AdaptiveSidePanel均有 TS 类型和 Kotlin 渲染路径类型工厂与 Kotlin 渲染节点各 88 个双向集合无差异文档与类型文件差异审查——过时名称不再出现在公开类型声明或开发者文档中git diff --check未发现空白错误。七、脚本作者视角如何获得并利用类型提示对齐完成后在脚本中即可获得完整类型提示// 浏览器截图ref 与 element 必须成对 const shot await Tools.Net.browserTakeScreenshot({ type: png, ref: …, element: …, fullPage: false }); // 嵌入宿主 AI 聊天界面不含工作区面板 AiChat({ /* 常规 Compose 公共属性 */ }, [ // 内容 ]); // 自适应侧栏宽屏拖拽调宽窄屏遮罩关闭 AdaptiveSidePanel( { open: true, onOpenChanged: (open) { /* 更新 open 状态 */ }, defaultWidth: 320, minWidth: 280, minContentWidth: 240, breakpoint: 600, side: [ /* 侧栏内容 */ ] }, [ /* 主内容 */ ] );同时可放心NativeInterface中出现的每个方法都有 Kotlin 实现兜底不会出现有声明无实现的幽灵接口。八、关联文档索引任务总览docs/TODO/kt_ts_bridge_alignment_20260809/index.md桥接接口清点docs/TODO/kt_ts_bridge_alignment_20260809/1_NativeBridgeInventory.md静态双向核对docs/TODO/kt_ts_bridge_alignment_20260809/3_StaticVerification.md类型入口examples/types/index.d.ts 与 examples/types/core.d.ts、examples/types/network.d.ts、examples/types/compose-dsl.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点击查看免费下载相关推荐Operit Kotlin 与 TypeScript 桥接接口对齐NativeInterface 清理、Tools.Net 浏览器截图与 Compose DSL 节点声明实战Operit Kotlin 与 TypeScript 桥接接口对齐NativeInterface 清理、Tools.Net 浏览器截图与 Compose DSAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit Kotlin 与 TypeScript 桥接接口对齐NativeInterface 公开接口清点与类型声明修复实战Operit Kotlin 与 TypeScript 桥接接口对齐NativeInterface 公开接口清点与类型声明修复实战 导读 本文围绕 OperitAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化TypeScript 声明合并与类型扩展同名声明合并与接口继承的完整实战指南TypeScript 声明合并与类型扩展同名声明合并与接口继承的完整实战指南 导读 在 TypeScript 的类型系统中合并Merging与扩展文档教程上一篇C3C编译器项目代码风格指南解析下一篇Brave浏览器深度解析隐私优先的现代浏览器架构设计与安全机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考