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

本篇技术指南聚焦 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/core.d.ts	NativeInterface 移除 setResult 与 setError
examples/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 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.1 AiChatProps：嵌入宿主 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.2 AdaptiveSidePanelProps：响应式尾随面板

/** 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	—（必填）	展开状态变化回调（窄屏遮罩点击即触发关闭）
defaultWidth	360f	面板初始宽度（dp）
minWidth	280f	面板最小宽度
minContentWidth	320f	内容区最小宽度，宽屏下面板最大宽度受 maxWidth - minContentWidth 约束
breakpoint	600f	宽/窄布局切换的断点（dp），maxWidth >= breakpoint 视为宽屏

实现细节：宽屏（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