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

• AI Agent
• 人工智能
• 大模型
• AI 应用
• 工具调用
• 本地部署
• MCP Clients
• Agent 记忆

本篇技术指南聚焦 Operit（Android 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/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 type="image" 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; }): Promise<string>;

四个参数字段中，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 object；
• type空值回落为"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 中runtime="compose_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.kt：renderAiChatNode将节点渲染为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，其行为与各参数默认值如下：

实现细节：宽屏（isWideLayout）下采用Row布局，内容区占剩余权重，面板区可通过居中的 24dp 拖拽手柄（detectDragGestures）实时调整宽度，并在minWidth与maxWidth之间收敛；窄屏下面板覆盖在内容之上，并叠加半透明遮罩（Color.Black.copy(alpha = 0.18f)），点击遮罩触发onOpenChanged(false)关闭。

5.3 节点工厂注册

两个节点均通过类型工厂导出（compose-dsl.d.ts）：

AiChat: ComposeNodeFactory<AiChatProps>; AdaptiveSidePanel: ComposeNodeFactory<AdaptiveSidePanelProps>;

六、静态双向核对：类型集合与实现集合的完全对齐

任务执行约束为"不运行编译、构建或测试命令"，验证完全依赖静态核对，核对清单与完成标准记录在 docs/TODO/kt_ts_bridge_alignment_20260809/3_StaticVerification.md：

1. core.d.ts的NativeInterface不包含没有 Kotlin 实现的旧成员——每个成员均能在 Kotlin@JavascriptInterface中找到实现，setResult与setError未出现在公开类型或开发文档；
2. JsTools.kt注入的浏览器截图方法与network.d.ts的Net成员比对——browserTakeScreenshot的四个参数字段与 Kotlin 参数归一化逻辑一致；
3. compose-dsl.d.ts新增节点与 Kotlin Compose DSL 节点分发比对——AiChat与AdaptiveSidePanel均有 TS 类型和 Kotlin 渲染路径，类型工厂与 Kotlin 渲染节点各 88 个，双向集合无差异；
4. 文档与类型文件差异审查——过时名称不再出现在公开类型声明或开发者文档中；
5. 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 Clients
• Agent 记忆