浏览器 AI 桥接包（@quantdo/tv-ai-bridge）

本包在图表页面中建立 WebSocket 连接，将网关下发的工具调用交给宿主注入的执行器。它负责注册页面、关联请求与结果、断线重连以及连接状态回调；不依赖 TradingView、MCP SDK、DOM 或 tv-demo。页面可将它与 @quantdo/tv-tool-core 和可选的 @quantdo/tv-ai-orchestrator 组合使用。

项目文档与问题反馈：GitHub · quantdo-tradingview-mcp · Issues。

安装

npm install @quantdo/tv-ai-bridge@^0.2.0

当前只提供 ESM 入口；随包提供 Bridge API 与页面接入。

接入方式

宿主先创建具有异步 execute(name, args) 方法的 executor，再创建 Bridge。当前 Demo 使用 tv-tool-core 与 tv-ai-orchestrator 组合执行器；Bridge 不自行创建它们。下面示例的 executor 与 onStatus 页面展示由宿主实现。

import { createTvAiBridge } from "@quantdo/tv-ai-bridge";

function getOrCreateTabCode() {
  const key = "mytv-ai-tab-id";
  const saved = sessionStorage.getItem(key);
  if (saved && /^\d{4}$/.test(saved)) return saved;
  const random = new Uint32Array(1);
  crypto.getRandomValues(random);
  const code = String(random[0] % 10000).padStart(4, "0");
  sessionStorage.setItem(key, code);
  return code;
}

function rotateTabCode() {
  const previous = getOrCreateTabCode();
  let next;
  do {
    sessionStorage.removeItem("mytv-ai-tab-id");
    next = getOrCreateTabCode();
  } while (next === previous);
  return next;
}

const bridge = createTvAiBridge({
  url: "ws://127.0.0.1:8787/browser",
  tools: executor,
  title: () => document.title,
  pageUrl: () => location.href,
  tabId: getOrCreateTabCode,
  onTabConflict: rotateTabCode,
  onStatus: ({ state, text }) => {
    console.log(state, text);
  },
});

bridge.connect();
// 页面卸载或不再需要连接时：bridge.disconnect();

示例中的 executor 由宿主注入，tabId 由宿主保存；当前 Demo 将四位数字字符串展示为 tabCode，刷新同一标签页时复用，前导零不能丢。用户重置访问码后，宿主先生成并保存新码，再调用 bridge.setTabId(newCode)；旧码随即失效。重复打开的标签页若发生码冲突，onTabConflict 会生成并保存新码。示例仅用于本机路由，不是生产认证方案。

Bridge 会为底层连接生成随机 sessionId，仅用于内部传输关联，不应展示给 AI，也不能把四位访问码当作生产级认证。外部 AI 每次调用 MCP 工具仍需明确携带 tabCode。

状态与事件

• onStatus 返回连接中、已连接、执行中、断开或错误状态；页面如何显示由宿主决定。
• 默认每五秒检查图表上下文、标题与页面 URL；内容未变化时不重复注册。contextRefreshMs 可设为正数调整间隔，设为 0 关闭轮询。
• reportAnalysisEvent({ eventType, analysisId, state, currentStep, totalSteps, step?, error? }) 可把异步分析步骤和失败事件报告给本地网关，用于诊断。Bridge 不解释或保存分析计划。
• disconnect() 停止连接与重连；它不是删除图形、分析对象或页面访问码的操作。

开发验证

cd tv-ai-bridge
npm install
npm test
npm pack --dry-run
npm run release:check

npm test 包含 TypeScript 构建及注册、冲突、重连、路由和上下文刷新测试。prepack 在真实打包前构建，release:check 检查三个包的实际 tarball 安装、ESM 导入、类型和浏览器打包。当前使用 MIT 许可证；完整 API 见 docs/API.md。

边界

本包不处理 MCP HTTP、用户认证、权限或页面 UI。默认本地服务地址只是 Demo 配置；目前四位 tabCode 只适用于本机测试。公网接入必须先完成正式认证、权限控制、TLS/WSS 和会话隔离。