从提示词演示到 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”。
要测试整条路径:
- 加载未打包的 Browser AI Observatory 扩展;
- 为第 04 章体验打开 DevTools;
- 选择 Observatory 面板;
- 点击 Enable for this site;
- 回到页面并发出那条有效事件;
- 在 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 与通用提示做比较,并在浏览器管理的实现演进时让行为变化变得可见。
参考与延伸阅读
- Chrome for Developers, Extend DevTools.
- Chrome for Developers,
chrome.devtools.inspectedWindow. - Chrome for Developers,
chrome.devtools.network. - Chrome for Developers, Message passing.
- Chrome for Developers, Extension service workers.
- Chrome for Developers, Declare permissions.
- Chrome for Developers, WebMCP tool security.