← Browser AI From First Principles

从提示词演示到 AI 调试器

把 Prompt API 控制台变成应用感知的调试器:可执行的选择加入插桩桥、带版本的事件、脱敏、关联、持久化与显式证据边界。

我们的第一个 DevTools 面板可以运行一个提示并显示其生命周期。

这使它成为一个有用的实验控制台。

这还使它成为不了调试器。

调试器必须帮助解释发生在被检视应用中的失败。它需要把模型活动与应用上下文联系起来,把事件保留足够长的时间以便比较,并区分它观察到的事实与它推导出的推断。它还必须在不悄悄捕获每个提示、响应与用户访问页面的前提下做到这些。

这些要求把我们拉向相反的方向。

我们捕获的数据越多,诊断就越容易。

我们捕获的数据越多,隐私与安全风险就越大。

因此扩展在需要另一个按钮之前,先需要一套架构。

本章设计这套架构,并实现它最小的端到端路径:应用发出一条已消毒的浏览器 AI 事件,被检视页面的桥校验它,一个 content script 把它运过扩展边界,DevTools 面板把它显示为一条外部轨迹。

核心规则是:

可观测性是应用与调试器之间的契约,不是收集一切的许可。


1. 定义调试器能知道什么

Chrome DevTools 扩展拥有有用的 API。它们可以创建面板、识别被检视的标签页、在被检视窗口中执行代码、取回资源,并观察 Network 面板中显示的请求。

这些事实中没有一条意味着:任何页面调用 LanguageModel.prompt() 时 Chrome 都会发布一个通用事件。

有三种我们可以合法支持的观察模式。

模式 事件来源 强项 限制
扩展自有 观测站自身的调用 我们自己调用的完整生命周期 不描述应用
应用插桩 应用通过我们的小 SDK 发出事件 语义丰富且显式 需要开发者集成
页面探针 开发者在被检视页面上下文中显式运行探针 对诊断有用 强大、脆弱,不适合静默的持续捕获

我们将构建第二种模式,作为应用调试的默认路线。

开发中的应用可以导入一个小的插桩辅助件,包裹它已经拥有的 Prompt API 操作。这在有意义的边界上产生可靠事件,而无需 monkey-patch 平台全局对象或从 DOM 变化猜测。

之后我们可能提供一个显式的、仅限开发期的注入模式。它必须保持显式的分离,因为在被检视页面中执行的代码可以访问页面状态,继承更大的风险面。


2. 分开四个平面

观测站需要四个不同的平面。

    flowchart TD
    A[应用 SDK] --> B[页面桥]
    B --> C[扩展传输]
    C --> D[轨迹存储]
    D --> P[DevTools 面板]
  

插桩平面

应用代码决定哪些语义事件存在。它知道某个特定会话属于"摘要选中的评审",或某个响应喂给了一个可见的功能。

传输平面

页面与扩展生活在不同的 JavaScript 世界。一条狭窄的消息桥把已校验的事件信封运过那条边界。

存储平面

可序列化事件按显式的作用域与保留设置被保留。运行时对象、DOM 节点与原始异常实例不进入存储。

呈现平面

DevTools 面板把事件投射为时间线、指标、错误与比较。它不得为了贴合当前可视化而改写底层事件。

这种分离让我们可以改 UI 而不改轨迹,也可以改传输而不要求应用理解扩展内部。


3. 设计带版本的事件信封

第 3 章的轨迹存储了 { id, type, at, detail }。跨上下文事件需要一份更强的契约。

const event = {
  schema: "browser-ai-observatory.event/1",
  id: "019...",
  type: "prompt.finished",
  at: "2026-09-02T11:42:18.219Z",
  source: {
    kind: "application",
    origin: "https://example.test",
    sdkVersion: "0.1.0"
  },
  correlation: {
    pageId: "...",
    sessionId: "...",
    traceId: "..."
  },
  capture: {
    mode: "metrics-only",
    redacted: true
  },
  data: {
    outcome: "completed",
    timeToFirstChunkMs: 214,
    totalMs: 961,
    inputChars: 483,
    outputChars: 892
  }
};

每个字段回答一个不同的问题。

  • schema 告诉消费方如何解析该事件。
  • id 把这条记录与重试或重复区分开。
  • type 描述该事实。
  • at 提供跨上下文的墙钟排序。
  • source 标明是谁主张了该事实。
  • correlation 把页面、会话与提示事件连起来。
  • capture 陈述隐私模式,而不是把它留作隐含。
  • data 装载事件特定的值。

来源是认识论的一部分。应用发出的计时与浏览器内部的测量不是一回事。面板事后推导的值不是直接观察到的事实。我们将使用 application、observatory、browser-surface、derived 这样的 source.kind 值,而不是把它们混在一条没有标注的时间线里。


4. 用两只钟做两份工作

在一个 JavaScript 上下文内,performance.now() 适合计算时长,因为它是单调的。跨上下文时,各自分离的 performance 时间原点让原始值难以比较。

对于被传输的事件,我们存储:

{
  at: new Date().toISOString(),
  monotonicMs: performance.now()
}

墙钟时间戳支持页面、content script 与扩展面板之间的近似排序。单调值支持同一生产者执行的精确时长计算。

我们不会用页面的 performance.now() 去减面板的 performance.now()。

如果之后需要更紧的跨上下文对齐,我们可以实现一次时钟同步交换并保留其不确定性。第一版无需假装分布式时钟是精确的。


5. 让捕获模式显式化

观测站将支持三种捕获模式:

模式 存储内容 默认用途
metrics-only 耗时、尺寸、状态、结果、选项名 常规开发
metadata 指标,加上开发者提供的任务标签与安全标记 功能诊断
content 开发者选定的提示与响应字段 短暂、显式的调试会话

metrics-only 是默认值。

内容模式必须要求 DevTools 面板中的一个动作,并在激活期间显示持久的可见指示。它应在 DevTools 关闭、被检视标签页切换或短暂保留窗口到期时失效。导出必须是单独一个动作。

脱敏尽可能在传输之前发生:

function summarizeText(text) {
  return {
    chars: [...text].length,
    bytes: new TextEncoder().encode(text).byteLength,
  };
}

function captureText(text, mode) {
  if (mode === "content") {
    return { ...summarizeText(text), text, redacted: false };
  }

  return { ...summarizeText(text), redacted: true };
}

传输层不应收到一个敏感字符串、之后再把它丢掉。最安全的提示是扩展从未见过的那个提示。


6. 构建应用 SDK

SDK 是一个小型事件生产者。它不需要访问 Chrome 扩展 API。

const CHANNEL = "browser-ai-observatory";
const SCHEMA = "browser-ai-observatory.event/1";

export function createObservatory({ captureMode = "metrics-only", tags = {} } = {}) {
  const pageId = crypto.randomUUID();

  function emit(type, { sessionId = null, traceId = null, data = {} } = {}) {
    const envelope = {
      schema: SCHEMA,
      id: crypto.randomUUID(),
      type,
      at: new Date().toISOString(),
      monotonicMs: performance.now(),
      source: {
        kind: "application",
        origin: location.origin,
        sdkVersion: "0.2.0",
      },
      correlation: { pageId, sessionId, traceId },
      capture: { mode: captureMode },
      data: { ...data, tags },
    };

    window.postMessage({ channel: CHANNEL, envelope }, location.origin);
    return envelope;
  }

  return { emit, pageId };
}

消息目标是 location.origin,而不是 "*"。这不对扩展做身份验证,但它避免把事件广播到当前 origin 之外。

应用在第 2 章引入的同样边界上包裹操作:

const observatory = createObservatory({
  tags: { feature: "explain-selection" },
});

const sessionId = crypto.randomUUID();
const createStarted = performance.now();

observatory.emit("session.create.started", { sessionId });

const session = await LanguageModel.create({
  ...sessionOptions,
  monitor(monitor) {
    monitor.addEventListener("downloadprogress", (event) => {
      observatory.emit("model.download.progress", {
        sessionId,
        data: { loaded: event.loaded },
      });
    });
  },
});

observatory.emit("session.create.finished", {
  sessionId,
  data: { durationMs: performance.now() - createStarted },
});

之后我们可以把它打包成 LanguageModel 的一个包装器。从显式调用开始,有助于我们在把它藏进便捷函数之前先验证事件词汇表。


7. 在本章中运行插桩契约

从第 04 章选择 Run with Browser AI 以打开:

/tools/ai/browser-ai-from-first-principles/04-chapter/

这个体验让传输契约变得可执行,而不假装网站与扩展是同一个上下文。

页面构造一条 metrics-only 的 browser-ai-observatory.event/1 信封,并通过 SDK 所用的同源通道发送它:

应用信封
        ↓ window.postMessage
本地契约校验器
        ↓ 当扩展启用时
注入的扩展桥
        ↓ chrome.runtime.sendMessage
按标签页限定的 service worker
        ↓
已附着的 DevTools 面板

点击 Emit valid application event。页面发出一条 feature.validation.finished 事件,包含来源标识、关联标识、捕获模式与已消毒的数据。本地镜像应用桥检查,并报告序列化后的字节大小。

本地接受证明两件事:页面创建了一个信封,且该信封满足镜像实现的契约。它不证明扩展收到了它。因此该体验把最后一个字段留在 Check attached DevTools,而不是把它改成一个令人安心却无证据支持的 “Delivered”。

要测试整条路径:

  1. 加载未打包的 Browser AI Observatory 扩展;
  2. 为第 04 章体验打开 DevTools;
  3. 选择 Observatory 面板;
  4. 点击 Enable for this site;
  5. 回到页面并发出那条有效事件;
  6. 在 DevTools 轨迹中确认该应用来源的事件。

页面无法授予扩展 host 访问权,也无法确认其面板中出现了什么。那些操作留在边界的扩展一侧。

现在点击 Try malformed envelope。页面刻意使用了错误的事件 schema 版本。本地校验器拒绝它。一个已启用的扩展桥会静默拒绝同一条消息,而不是把关于它的不受信诊断转发进应用。

回放按钮演示了另一个否定事实。我们那份已评审的 9 月 2 日轨迹包含扩展自有的能力与会话事件,但没有应用来源的事件。第 04 章标注这个缺失,而不是把早先那次运行改写成一条我们当时尚未捕获的桥的证据。

这是第一个能够参与真实扩展架构的章节体验。没有扩展它依然有用,因为它在本地解释并测试信封契约。安装并显式启用扩展后,它变成一个被插桩的测试页面。


8. 窄窄地跨过页面边界

扩展 content script 通常运行在一个隔离世界(isolated world)中。它们可以与 DOM 交互,但不与页面共享 JavaScript 变量。window.postMessage 桥是运送刻意发布的页面事件的常见方式。

扩展默认不把桥注入每个页面。当前 manifest 请求 scripting 与 session-storage 能力,同时把 host 访问留作可选:

{
  "manifest_version": 3,
  "name": "Browser AI Observatory",
  "version": "0.3.2",
  "description": "Inspect, measure, and debug browser-managed AI from Chrome DevTools.",
  "devtools_page": "devtools.html",
  "background": {
    "service_worker": "service-worker.js",
    "type": "module"
  },
  "permissions": ["scripting", "storage"],
  "optional_host_permissions": ["http://*/*", "https://*/*"]
}

当用户选择 Enable for this site 时,面板为被检视 origin 请求权威性,service worker 把 bridge.js 注入该标签页。这把一次宽泛的安装期主张,转换成一个显式的、按 origin 限定的调试动作。扩展仍然可以在没有 host 访问的情况下检视自己的 Prompt API 会话。

被注入的桥只接受我们带版本的信封:

const CHANNEL = "browser-ai-observatory";
const SCHEMA = "browser-ai-observatory.event/1";
const ALLOWED_TYPES = new Set([
  "capability.inspect.finished",
  "model.download.progress",
  "session.create.started",
  "session.create.finished",
  "session.create.failed",
  "prompt.started",
  "prompt.chunk",
  "prompt.finished",
]);

window.addEventListener("message", (event) => {
  if (event.source !== window) return;
  if (event.origin !== location.origin) return;

  const message = event.data;
  if (!message || message.channel !== CHANNEL) return;

  const envelope = message.envelope;
  if (!isValidEnvelope(envelope)) return;

  chrome.runtime.sendMessage({
    kind: "browser-ai-observatory.event",
    envelope,
  });
});

function isValidEnvelope(value) {
  if (!value || value.schema !== SCHEMA) return false;
  if (typeof value.id !== "string" || value.id.length > 128) return false;
  if (!ALLOWED_TYPES.has(value.type)) return false;
  if (typeof value.at !== "string") return false;
  if (!value.source || value.source.origin !== location.origin) return false;
  if (!value.correlation || typeof value.correlation.pageId !== "string") return false;
  if (!value.data || typeof value.data !== "object") return false;

  const serializedSize = new TextEncoder().encode(JSON.stringify(value)).byteLength;
  return serializedSize <= 256_000;
}

这是校验,不是页面诚实的证明。页面中运行的任何脚本都可以模仿消息格式。事件来源仍是 application;观测站绝不能把它标注为浏览器背书(browser-attested)。

一旦轨迹能够影响自动化诊断,这个区分就变得不可或缺。


9. 把事件路由到被检视的面板

content script 不能假定 DevTools 面板是打开的。面板也不能直接监听页面全局对象。service worker 可以充当扩展的传输枢纽。

把它加进 manifest:

"background": {
  "service_worker": "service-worker.js",
  "type": "module"
}

该 worker 为打开的 DevTools 面板维护端口,并按标签页转发事件:

const panelsByTab = new Map();

chrome.runtime.onConnect.addListener((port) => {
  if (port.name !== "observatory-panel") return;

  let tabId = null;

  port.onMessage.addListener((message) => {
    if (message.kind !== "panel.attach") return;
    tabId = message.tabId;
    const ports = panelsByTab.get(tabId) ?? new Set();
    ports.add(port);
    panelsByTab.set(tabId, ports);
  });

  port.onDisconnect.addListener(() => {
    if (tabId === null) return;
    const ports = panelsByTab.get(tabId);
    ports?.delete(port);
    if (ports?.size === 0) panelsByTab.delete(tabId);
  });
});

chrome.runtime.onMessage.addListener((message, sender) => {
  if (message.kind !== "browser-ai-observatory.event") return;
  if (sender.tab?.id === undefined) return;

  for (const port of panelsByTab.get(sender.tab.id) ?? []) {
    port.postMessage(message);
  }
});

面板使用 DevTools API 提供的 tab ID 附着:

const port = chrome.runtime.connect({ name: "observatory-panel" });

port.postMessage({
  kind: "panel.attach",
  tabId: chrome.devtools.inspectedWindow.tabId,
});

port.onMessage.addListener((message) => {
  if (message.kind !== "browser-ai-observatory.event") return;
  appendExternalEvent(message.envelope);
});

service worker 是一个路由器,不是内存状态的永久拥有者。Manifest V3 的 worker 可能在空闲时停止。任何必须存活的东西都属于扩展存储、IndexedDB,或一次显式导出。


10. 少存,并且有意地存

持久化对比较有用。它也正是一次临时的调试观察变成长久数据资产的地方。

0.2.0 版本可以在浏览器会话活跃期间用 chrome.storage.session 存储轨迹事件。之后,一个显式的 “Keep this trace” 动作可以把选定的运行复制到 chrome.storage.local 或导出 JSON。

async function appendSessionEvent(tabId, envelope) {
  const key = `trace:${tabId}`;
  const current = await chrome.storage.session.get(key);
  const events = current[key] ?? [];
  events.push(envelope);

  const bounded = events.slice(-2000);
  await chrome.storage.session.set({ [key]: bounded });
}

这个上界防止一次意外的无尽流消耗无界存储。生产版本还应当批量写入,而不是独立持久化每个分片。

保留策略成为轨迹元数据的一部分:

{
  "retention": {
    "scope": "browser-session",
    "maxEvents": 2000,
    "contentExpiresAt": null
  }
}

如果启用了内容捕获,contentExpiresAt 必须有值。


11. 把模型行为与应用行为关联起来

光凭耗时几乎无法解释一个 AI 功能是否奏效。

假设一个本地模型在 420 毫秒内响应。这在操作上是健康的。如果响应未通过验证、应用把它丢弃,那么产品结果失败了。

应用应当能够用同一个 trace ID 添加结果事件:

observatory.emit("feature.validation.finished", {
  traceId,
  sessionId,
  data: {
    validator: "summary-shape/1",
    accepted: false,
    reasonCodes: ["missing_required_section"],
  },
});

于是一次运行包含两个不同的真相:

操作结果:completed
行为结果:rejected

这正是工具开始与"可靠 AI 系统"这一更大工作相连的地方。一次成功的模型调用是一个传输事实。接受是一个应用决策。

观测站应当把二者并排显示,绝不把它们折叠成一个绿色对勾。


12. 构建有用的轨迹视图

下一个面板投影应当按提示轨迹分组事件,而不是渲染一张无差别的事件列表。

轨迹 功能 可用性 会话 首个输出 总计 运行时 验证
7a1… explain-selection available warm 214 ms 961 ms completed accepted
9f3… summarize-page available reused 188 ms 744 ms completed rejected
c82… explain-error downloading cold — 18.4 s aborted not run

每个单元格都应当可追溯到某个事件,或被显式标注为推导值。

例如:

function derivePromptSummary(events) {
  const started = events.find((event) => event.type === "prompt.started");
  const finished = events.find((event) => event.type === "prompt.finished");
  const validation = events.find(
    (event) => event.type === "feature.validation.finished"
  );

  return {
    source: "derived",
    traceId: started?.correlation.traceId,
    runtimeOutcome: finished?.data.outcome ?? "running",
    totalMs: finished?.data.totalMs ?? null,
    accepted: validation?.data.accepted ?? null,
  };
}

该投影可以被重算。源事件保持不变。


13. 现在就定义产品边界

Browser AI Observatory 正在变成两个相关的工具:

监控器

监控器回答在能力、获取、会话、提示与应用验证事件之间发生了什么。

调试器

调试器通过过滤相关事件、比较成功与不成功的轨迹、在显式启用时暴露输入/输出捕获,并把操作状态与行为验证连起来,帮助解释一次运行为何失败。

之后会出现第三个角色。

智能体检查器

当我们加入 WebMCP 时,该工具将显示已发现的工具、schema、被选中的调用、参数、权限决策、结果与验证。它会把不受信的工具描述与输出同受信的控制指令显式分开。

这是同一套连续的架构:

浏览器 AI 生命周期
        ↓
提示轨迹
        ↓
应用结果
        ↓
工具发现与动作
        ↓
智能体运行

从事件标识与来源标签起步,意味着当系统变得智能体化时,我们无需重建底座。


14. 开篇组的完成定义

当我们可以演示以下全部内容时,第一个构建就完成了:

  • DevTools 面板在没有 host 访问的情况下加载;
  • 扩展能够检视并行使自己的 Prompt API 能力;
  • 模型下载与会话创建作为分开的阶段出现;
  • 流式请求可以被停止;
  • metrics-only 捕获是默认值;
  • 一个被插桩的测试页面可以发出带版本的事件;
  • content script 拒绝格式错误或超大的信封;
  • service worker 只把事件路由到附着于匹配标签页的面板;
  • 操作性完成与应用接受保持为分开的字段;
  • 关闭面板并不意味着内存中的 service worker 会保留状态;
  • 界面精确声明内容捕获何时处于激活状态;
  • 不声称应用事件是浏览器背书的。

这些是可测试的属性。它们给我们的基础比一张原型图更强,比一台想象中的通用调试器更窄。


结论

一个真正的 AI 调试器始于对证据诚实。

扩展直接观察它自己拥有的调用。它通过显式 SDK 接收应用事件,把它们运过一条狭窄、已校验的桥,并标注来源、关联标识与捕获模式。它只按声明的保留规则持久化,并把操作性完成与行为性接受分开。

这套架构给了我们那个将随书一起成长的监控器/调试器应用。

本章现在参与那套架构。没有扩展时,它验证公开的信封契约。显式启用扩展后,它变成一个真实的被插桩应用,其事件可在 DevTools 中被确认。页面在任何一点都不会把本地校验升级为浏览器背书的送达。

开篇组现在已经走过了四层:

浏览器作为模型宿主
        ↓
能力生命周期
        ↓
可用的 DevTools 实验控制台
        ↓
被插桩的 AI 监控器与调试器

下一组可以开始测试模型本身。我们将设计可重复的提示 fixture、测量冷与热的性能、检视会话上下文、把任务 API 与通用提示做比较,并在浏览器管理的实现演进时让行为变化变得可见。


参考与延伸阅读

  1. Chrome for Developers, Extend DevTools.
  2. Chrome for Developers, chrome.devtools.inspectedWindow.
  3. Chrome for Developers, chrome.devtools.network.
  4. Chrome for Developers, Message passing.
  5. Chrome for Developers, Extension service workers.
  6. Chrome for Developers, Declare permissions.
  7. Chrome for Developers, WebMCP tool security.