@talknote/h5-bridge

TalkNote App 内嵌 WebView 的第三方 H5 SDK。封装 App 注入的 window.vibeNoteBridge，提供带类型、可测试的语义化 API。

• TypeScript 源码与完整 .d.ts
• ESM、CommonJS、CDN UMD 三种入口
• 发布包运行时依赖为 0
• Father 仅用于开发构建，不进入 H5 运行时
• 仅依赖当前 iOS / Android 注入的 window.vibeNoteBridge（不再兼容旧 TalkNoteBridge）

安装

npm install @talknote/h5-bridge

yarn add @talknote/h5-bridge

安装 AI Skill（可选）

npm install 不会自动修改当前项目。需要让 Codex 和 Claude Code 获得 TalkNote H5 Bridge 专用工作流时，显式执行：

npx talknote-h5-bridge install-skill

命令会同时安装：

• Codex：.agents/skills/talknote-h5-bridge/
• Claude Code：.claude/skills/talknote-h5-bridge/

如果同名 Skill 已存在，命令会直接覆盖，但不会修改其他 Skill。升级 npm 包后需重新执行该命令才能更新两端 Skill。

使用

ES Module

import TalkNoteH5Bridge, { TalkNoteBridgeError } from '@talknote/h5-bridge';

const userInfo = await TalkNoteH5Bridge.getUserInfo();
renderUserProfile(userInfo);

CommonJS

const TalkNoteH5Bridge = require('@talknote/h5-bridge');

TalkNoteH5Bridge.goBack();

CDN

<script src="https://cdn.jsdelivr.net/npm/@talknote/h5-bridge/dist/umd/talknote-h5-bridge.min.js"></script>
<script>
  if (window.TalkNoteH5Bridge.isAvailable()) {
    window.TalkNoteH5Bridge.getLocaleInfo().then(updateLocaleUI);
  }
</script>

CDN 全局对象是 window.TalkNoteH5Bridge。SDK 不会覆盖客户端注入的 window.vibeNoteBridge。

环境检测

原生能力只在 TalkNote App 支持的内嵌 WebView 中可用。系统浏览器中应提供降级逻辑：

if (!TalkNoteH5Bridge.isAvailable()) {
  showOpenInAppGuide();
  return;
}

getUserInfo 与 getRequestBaseInfo 已内置 PC/浏览器兜底：当检测不到 vibeNoteBridge（getCapabilities().source === 'none'）时，这两个方法会从浏览器 localStorage 读取 accessToken 作为令牌返回，不再抛 BRIDGE_UNAVAILABLE；其余能力在 PC 端仍不可用，需引导在 App 内打开。

isAvailable() 只表示存在 vibeNoteBridge。调用具体能力前使用 supports()（内部走 canIUse）；getCapabilities() 可用于诊断：

if (!TalkNoteH5Bridge.supports('saveFileToSystem')) {
  showUpgradeAppGuide();
  return;
}

const capabilities = TalkNoteH5Bridge.getCapabilities();

协议机器可读事实源是 contract/bridge-contract.json。

常用能力

导航

TalkNoteH5Bridge.navigateTo({
  key: 'MembershipScreen',
  mode: 'push',
  props: { from: 'third-party-h5' },
});

TalkNoteH5Bridge.goBack();
TalkNoteH5Bridge.goToRoot({ tab: 'home' });
TalkNoteH5Bridge.setPopGestureEnabled(false);

获取请求基础信息

const { baseUrl, headers = {} } = await TalkNoteH5Bridge.getRequestBaseInfo();

const response = await fetch(`${baseUrl}/your/api`, {
  headers: {
    ...headers,
    'Content-Type': 'application/json',
  },
});

选图 / 文件

const result = await TalkNoteH5Bridge.pickImages({
  selectionLimit: 9,
  mediaTypes: 'Images',
});
if (result.canceled) return;

const docs = await TalkNoteH5Bridge.documentPicker({
  type: ['application/pdf'],
  multiple: false,
});

保存远程文件到系统

if (!TalkNoteH5Bridge.supports('saveFileToSystem')) {
  showUpgradeAppGuide();
  return;
}

const result = await TalkNoteH5Bridge.saveFileToSystem({
  url: 'https://example.com/report.pdf',
  fileName: 'report.pdf',
  mimeType: 'application/pdf',
});
if (result.canceled) return;

保存图片到相册

await TalkNoteH5Bridge.saveImageToLibrary({ url: 'https://example.com/photo.jpg' });

实名认证

const result = await TalkNoteH5Bridge.openAlipayRealNameAuth({ authUrl });
if (!result.opened) {
  // handle
}

实时转写 / 翻译

录音期间把实时 PCM 喂给 ASR 服务，实时回传转写/翻译结果（录音需单独用 startVoiceRecording 控制）。

if (!TalkNoteH5Bridge.supports('startRealtimeTranscription')) {
  throw new Error('当前客户端不支持实时转写');
}

// 1. 先订阅事件，避免漏掉 connecting 状态
const offResult = TalkNoteH5Bridge.onTranscriptionResult(e => {
  console.log(e.data.isFinal ? '句末' : '中间', e.data.text, e.data.translations);
});
const offStatus = TalkNoteH5Bridge.onTranscriptionStatus(e => console.log('状态', e.data.status));
const offError = TalkNoteH5Bridge.onTranscriptionError(e => console.error(e.data.code, e.data.message));

// 2. 开启录音 + 转写通道（wsUrl 必须为 ws/wss；headers 敏感，请勿打印）
await TalkNoteH5Bridge.startVoiceRecording();
await TalkNoteH5Bridge.startRealtimeTranscription({
  wsUrl,
  targetLanguages: ['english'],
});

// 3. 会话中切换翻译语言（可选）
await TalkNoteH5Bridge.updateRealtimeTranscriptionLanguages({ targetLanguages: ['japanese'] });

// 4. 停止
await TalkNoteH5Bridge.stopRealtimeTranscription();
await TalkNoteH5Bridge.stopVoiceRecording();
offResult();
offStatus();
offError();

事件

const unsubscribe = TalkNoteH5Bridge.onWebViewScreenFocus(event => {
  console.log(event.data.timestamp);
});
// 页面卸载时
unsubscribe();

也可用通用 on('keyboardShow', handler) / off。

错误处理

import TalkNoteH5Bridge, { TalkNoteBridgeError } from '@talknote/h5-bridge';

try {
  await TalkNoteH5Bridge.getUserInfo();
} catch (error) {
  if (error instanceof TalkNoteBridgeError) {
    // UNSUPPORTED_CAPABILITY | BRIDGE_UNAVAILABLE | BRIDGE_TIMEOUT | ...
    console.error(error.code, error.message);
  }
}

扩展调用

客户端新增能力而 SDK 尚未升级时：

TalkNoteH5Bridge.send('newOneWayCommand', { value: 1 });

const result = await TalkNoteH5Bridge.invoke('newAsyncCommand', { value: 1 }, { timeout: 10000 });

开发

cd packages/h5Bridge
npm run generate:contract
npm run verify

文档

• API.md
• AI-CODING.md
• llms.txt