构建最小的 Browser AI Observatory
构建并运行最小但有用的 Browser AI Observatory:探测 Prompt API、创建会话、流式传输响应、从事件推导测量、导出证据,并保住仪器边界。
我们已经准备好让浏览器的 AI 生命周期变得可见。
第一个版本会有意保持很小。它不会检视每个页面、拦截任意提示词、调用工具、诊断质量或持久化历史。它做五件事:
- 在 Chrome DevTools 内创建一个面板;
- 报告 Prompt API 是否暴露且可用;
- 创建一个带可见下载进度的浏览器管理语言模型会话;
- 流式传输一个可取消的提示;
- 显示一条划分每个阶段的事件轨迹。
这已经比一个聊天演示更有用。
聊天演示回答的是:“我能拿到一段文本吗?”
我们的第一个观测站回答:
API 暴露了吗?
我们请求了什么能力?
Chrome 报告了什么可用性状态?
模型获取发生了吗?
会话创建花了多久?
离首个输出还有多久?
请求完成、失败还是被取消了?
本章用纯 HTML、CSS 与 JavaScript 构建完整的扩展。不需要打包器。这让浏览器边界保持可见;后续实现可以在架构赢得它们之后再加入 TypeScript 与构建系统。
1. 为什么要构建一个 DevTools 扩展?
工具栏弹窗失去焦点就消失。侧边面板对页面级助手有用,但我们的产品是一件工程仪器。它属于被检视页面的 Elements、Console、Network 与 Performance 面板之旁。
Chrome 允许扩展通过 manifest.json 中的 devtools_page 条目添加一个自定义 DevTools 面板。
由此产生的架构有三个上下文:
flowchart TD
M[Manifest V3 扩展] --> D[DevTools 页面]
D --> P[Observatory 面板]
D --> W[被检视窗口 API]
P --> L[内置 LanguageModel]
对于这第一个切片,DevTools 页面只注册面板。面板拥有自己的 Prompt API 会话与自己的轨迹。
最后一句话很重要。我们尚未声称观察被检视应用发起的 Prompt API 调用。我们构建的是一个位于 DevTools 内部、由扩展拥有的测试控制台。第 4 章将设计接收应用轨迹所需的选择加入桥,而不会假装 DevTools 暴露了它并不具备的事件。
2. 创建扩展骨架
创建这个目录:
browser-ai-observatory/
manifest.json
devtools.html
devtools.js
panel.html
panel.css
panel.js
manifest 有意保持狭窄:
{
"manifest_version": 3,
"name": "Browser AI Observatory",
"version": "0.1.0",
"description": "Inspect and experiment with browser-managed AI from DevTools.",
"devtools_page": "devtools.html"
}
没有 host 权限、content script、后台 service worker 或网络权限。
这不只是极简主义。权限范围是产品信任模型的一部分。扩展可以在不读取用户访问的每个页面的情况下运行自己的本地实验,所以 0.1.0 版本不应请求那项权威性。
DevTools 的引导是一个本地 HTML 页面:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<script src="devtools.js" defer></script>
</head>
<body></body>
</html>
JavaScript 注册我们的面板:
chrome.devtools.panels.create(
"AI Observatory",
"",
"panel.html"
);
只要该 DevTools 窗口保持打开,Chrome 就让 DevTools 页面的一个实例保持存活。面板页面在面板显示时加载。
3. 把面板当作仪器来构建
这个界面需要控件、状态和一条轨迹。它不需要一个聊天人设。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Browser AI Observatory</title>
<link rel="stylesheet" href="panel.css">
<script type="module" src="panel.js"></script>
</head>
<body>
<header>
<div>
<p class="eyebrow">Browser AI Observatory</p>
<h1>Local model trace</h1>
</div>
<output id="status" class="status">Not inspected</output>
</header>
<main>
<section class="card controls" aria-labelledby="runtime-heading">
<h2 id="runtime-heading">Runtime</h2>
<dl class="facts">
<div><dt>API</dt><dd id="api-state">Unknown</dd></div>
<div><dt>Availability</dt><dd id="availability">Unknown</dd></div>
<div><dt>Session</dt><dd id="session-state">None</dd></div>
</dl>
<progress id="download" max="1" value="0" hidden></progress>
<div class="actions">
<button id="inspect">Inspect capability</button>
<button id="create" disabled>Create session</button>
</div>
</section>
<section class="card" aria-labelledby="prompt-heading">
<h2 id="prompt-heading">Prompt</h2>
<label for="prompt">Input</label>
<textarea id="prompt" rows="5">Explain why an availability check and a session are different.</textarea>
<div class="actions">
<button id="run" disabled>Run</button>
<button id="stop" disabled>Stop</button>
</div>
<label for="response">Streamed response</label>
<output id="response" class="response"></output>
</section>
<section class="card trace-card" aria-labelledby="trace-heading">
<div class="section-title">
<h2 id="trace-heading">Trace</h2>
<button id="clear" class="secondary">Clear</button>
</div>
<ol id="trace" class="trace"></ol>
</section>
</main>
</body>
</html>
布局使用语义元素,使扩展在键盘与辅助技术下仍然可用。调试器不会因为它的用户是开发者就被豁免于产品质量。
样式可以保持紧凑:
:root {
color-scheme: light dark;
font: 13px/1.45 system-ui, sans-serif;
--border: color-mix(in srgb, CanvasText 18%, transparent);
--muted: color-mix(in srgb, CanvasText 62%, transparent);
--accent: #5b7cfa;
}
* { box-sizing: border-box; }
body {
margin: 0;
color: CanvasText;
background: Canvas;
}
header, main { padding: 16px; }
header {
display: flex;
align-items: start;
justify-content: space-between;
border-bottom: 1px solid var(--border);
}
h1, h2, p { margin-top: 0; }
h1 { margin-bottom: 0; font-size: 18px; }
h2 { font-size: 14px; }
.eyebrow { margin-bottom: 2px; color: var(--muted); }
main {
display: grid;
grid-template-columns: minmax(280px, 0.8fr) minmax(360px, 1.2fr);
gap: 12px;
}
.card {
padding: 14px;
border: 1px solid var(--border);
border-radius: 8px;
}
.trace-card { grid-column: 1 / -1; }
.facts {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 8px;
}
.facts div { padding: 8px; background: color-mix(in srgb, CanvasText 5%, transparent); }
dt { color: var(--muted); }
dd { margin: 2px 0 0; font-weight: 600; }
textarea, .response, progress { width: 100%; }
textarea { resize: vertical; }
.response {
display: block;
min-height: 120px;
margin-top: 6px;
padding: 10px;
white-space: pre-wrap;
border: 1px solid var(--border);
}
.actions, .section-title {
display: flex;
gap: 8px;
align-items: center;
margin: 10px 0;
}
.section-title { justify-content: space-between; }
button { padding: 6px 10px; }
.status { color: var(--muted); }
.trace {
max-height: 280px;
overflow: auto;
padding-left: 28px;
font-family: ui-monospace, monospace;
}
.trace li { padding: 3px 0; }
.trace time { color: var(--muted); margin-right: 8px; }
CSS 使用系统颜色与 color-scheme,因此面板无需在第一版中做主题检测就能跟随 DevTools 主题。
4. 把事件当作主要输出
在加入模型调用之前,先定义轨迹。
const traceElement = document.querySelector("#trace");
const events = [];
function now() {
return performance.timeOrigin + performance.now();
}
function emit(type, detail = {}) {
const event = Object.freeze({
id: crypto.randomUUID(),
type,
at: now(),
detail,
});
events.push(event);
renderEvent(event);
return event;
}
function renderEvent(event) {
const item = document.createElement("li");
const time = document.createElement("time");
const message = document.createElement("span");
time.dateTime = new Date(event.at).toISOString();
time.textContent = new Date(event.at).toLocaleTimeString();
message.textContent = `${event.type} ${JSON.stringify(event.detail)}`;
item.append(time, message);
traceElement.append(item);
item.scrollIntoView({ block: "nearest" });
}
使用 textContent 而不是 HTML 插入是一项安全属性。错误消息、模型输出以及未来由页面提供的字段都是数据。它们不是受信的标记。
轨迹在面板的生命周期内是只追加的序列。像 “Available” 这样的 UI 事实是该序列的投影。之后我们可以持久化、过滤并回放它,而无需重新设计这条基础记录。
5. 在本章中运行 Observatory
DevTools 扩展是我们正在构建的产品。本章体验是它立即可运行的对应物。
从本章选择 Run with Browser AI 以打开:
/tools/ai/browser-ai-from-first-principles/03-chapter/
该页面执行与扩展相同的核心序列:
检视能力
↓
创建会话
↓
运行流式提示
↓
追加带版本的事件
↓
推导测量
↓
导出轨迹
有一个刻意的差异。本章体验作为顶层网页运行,而扩展运行在 DevTools 面板中。每件仪器只观察它自己拥有的 Prompt API 工作。谁都不能仅仅因为显示了一个事件控制台,就推断自己拦截了别处私密发起的模型调用。
Observatory 摘要是事件流的投影,不是第二份耗时数据来源。五个值从已记录事件推导而来:
| 测量 | 来源事件 |
|---|---|
| 事件数 | 当前事件序列的长度 |
| 会话创建 | session.create.finished.data.durationMs |
| 首个分片 | prompt.finished.data.timeToFirstChunkMs |
| 提示总耗时 | prompt.finished.data.totalMs |
| 结果 | 最近的终结性提示或会话事件 |
这很重要,因为重复的测量逻辑会漂移。如果一个计时器喂给仪表盘、另一个计时器喂给导出,屏幕与证据就可能不一致。通过从事件推导屏幕,回放与实时执行使用同一条计算路径。
缺失的证据保持为缺失。那份已评审的 9 月 2 日轨迹包含十个事件和一次完成的会话创建,但没有完成的提示。因此它的摘要显示会话耗时,而首个分片时间与提示总耗时仍为 —。界面不得估算这些值,也不得从另一次运行借来它们,仅仅为了把卡片填满。
章节专属的 bundle 把可执行行为与解释、证据分开:
03-chapter/context.md 提供给模型的概念
03-chapter/experiment.json 提示词、选项与请求的视图
03-chapter/recorded-trace.json 已评审的纯指标证据
Prompt API 选项在实验室的已注册实验配置档中包含 samplingMode: "most-predictable"。这使该运行与我们在真实 Chrome 构建中遇到的投机解码约束兼容。普通页面不应假定采样控制默认可用;持久的规则是:同一组已记录的选项被提供给可用性检视与会话创建。
真正的 Manifest V3 实现仍位于:
experiments/browser-ai-from-first-principles/browser-ai-observatory/
站点体验不会取代那个扩展。它给每位读者一份本章核心架构的可执行版本,在实时 Browser AI 不可用时提供回放路径,并确立随 Observatory 成长可复用的仪表盘契约。
6. 检视能力
把会话选项定义一次:
const sessionOptions = Object.freeze({
samplingMode: "most-predictable",
expectedInputs: [{ type: "text", languages: ["en"] }],
expectedOutputs: [{ type: "text", languages: ["en"] }],
});
然后接上界面:
const ui = {
status: document.querySelector("#status"),
apiState: document.querySelector("#api-state"),
availability: document.querySelector("#availability"),
sessionState: document.querySelector("#session-state"),
download: document.querySelector("#download"),
inspect: document.querySelector("#inspect"),
create: document.querySelector("#create"),
prompt: document.querySelector("#prompt"),
run: document.querySelector("#run"),
stop: document.querySelector("#stop"),
response: document.querySelector("#response"),
clear: document.querySelector("#clear"),
};
let session = null;
let sessionId = null;
let activeController = null;
ui.inspect.addEventListener("click", inspectCapability);
async function inspectCapability() {
emit("capability.inspect.started", { api: "LanguageModel" });
if (!("LanguageModel" in globalThis)) {
ui.apiState.textContent = "Not exposed";
ui.availability.textContent = "Unavailable";
ui.status.textContent = "Prompt API is not exposed in this context";
ui.create.disabled = true;
emit("capability.inspect.finished", {
exposed: false,
availability: "unavailable",
});
return;
}
ui.apiState.textContent = "Exposed";
try {
const availability = await LanguageModel.availability(sessionOptions);
ui.availability.textContent = availability;
ui.create.disabled = availability === "unavailable";
ui.status.textContent = availabilityMessage(availability);
emit("capability.inspect.finished", { exposed: true, availability });
} catch (error) {
ui.status.textContent = `Inspection failed: ${error.message}`;
emit("capability.inspect.failed", serializeError(error));
}
}
function availabilityMessage(value) {
return {
available: "Ready to create a session",
downloadable: "A model download is required",
downloading: "The model is downloading",
unavailable: "This capability is unavailable",
}[value] ?? `Unknown availability: ${value}`;
}
function serializeError(error) {
return {
name: error?.name ?? "Error",
message: error?.message ?? String(error),
};
}
我们存储错误的 name 与 message,而不是整个错误对象。错误对象在扩展边界之间不能一致地序列化,且堆栈可能包含我们默认不想持久化的本地或扩展专有信息。
7. 创建会话并监视获取
会话创建属于它自己的用户动作。
ui.create.addEventListener("click", createSession);
async function createSession() {
ui.create.disabled = true;
ui.inspect.disabled = true;
ui.sessionState.textContent = "Creating";
ui.status.textContent = "Creating local session";
const startedAt = performance.now();
emit("session.create.started", { options: sessionOptions });
try {
session = await LanguageModel.create({
...sessionOptions,
monitor(monitor) {
ui.download.hidden = false;
monitor.addEventListener("downloadprogress", (event) => {
ui.download.value = event.loaded;
ui.status.textContent = `Downloading ${Math.round(event.loaded * 100)}%`;
emit("model.download.progress", { loaded: event.loaded });
});
},
});
sessionId = crypto.randomUUID();
ui.download.hidden = true;
ui.sessionState.textContent = "Ready";
ui.status.textContent = "Session ready";
ui.run.disabled = false;
emit("session.create.finished", {
sessionId,
durationMs: performance.now() - startedAt,
});
} catch (error) {
session = null;
sessionId = null;
ui.sessionState.textContent = "Failed";
ui.status.textContent = `Session failed: ${error.message}`;
ui.create.disabled = false;
emit("session.create.failed", {
durationMs: performance.now() - startedAt,
error: serializeError(error),
});
} finally {
ui.inspect.disabled = false;
}
}
在热机器上 monitor 可能不会发出进度,因为不需要模型获取。因此事件轨迹把下载当作可选阶段,而不是假定每次创建都要经过它。
我们还把会话创建与下载分开测量。热会话仍有创建成本,而下载到达 1 之后的时间可以揭示单靠进度条所掩盖的准备工作。
8. 流式传输、测量与停止
提示运行器为每个请求创建新的轨迹标识。
ui.run.addEventListener("click", runPrompt);
ui.stop.addEventListener("click", () => activeController?.abort());
async function runPrompt() {
const prompt = ui.prompt.value.trim();
if (!session || !prompt) return;
const traceId = crypto.randomUUID();
const startedAt = performance.now();
let firstChunkAt = null;
let chunks = 0;
let outputChars = 0;
activeController = new AbortController();
ui.run.disabled = true;
ui.stop.disabled = false;
ui.response.textContent = "";
ui.status.textContent = "Generating";
emit("prompt.started", {
traceId,
sessionId,
inputChars: [...prompt].length,
capture: "metrics-only",
});
try {
const stream = session.promptStreaming(prompt, {
signal: activeController.signal,
});
for await (const chunk of stream) {
const chunkAt = performance.now();
firstChunkAt ??= chunkAt;
chunks += 1;
outputChars += [...chunk].length;
ui.response.append(document.createTextNode(chunk));
emit("prompt.chunk", {
traceId,
index: chunks,
chars: [...chunk].length,
elapsedMs: chunkAt - startedAt,
});
}
emit("prompt.finished", {
traceId,
outcome: "completed",
chunks,
outputChars,
timeToFirstChunkMs:
firstChunkAt === null ? null : firstChunkAt - startedAt,
totalMs: performance.now() - startedAt,
});
ui.status.textContent = "Complete";
} catch (error) {
const outcome = error.name === "AbortError" ? "aborted" : "failed";
emit("prompt.finished", {
traceId,
outcome,
chunks,
outputChars,
totalMs: performance.now() - startedAt,
error: outcome === "failed" ? serializeError(error) : null,
});
ui.status.textContent = outcome === "aborted" ? "Stopped" : `Failed: ${error.message}`;
} finally {
activeController = null;
ui.run.disabled = false;
ui.stop.disabled = true;
}
}
提示内容出现在输入框里,是因为用户输入了它。它不会被复制进轨迹。事件记录 capture: "metrics-only" 与一个输入尺寸。
之后我们可以为调试自己应用的开发者加入一个显式的内容捕获模式。它必须是选择加入的设置,在面板中可见,作用域限定于被检视的 origin,并依据清晰的策略再次自动关闭。
清除按钮只重置内存中的视图:
ui.clear.addEventListener("click", () => {
events.length = 0;
traceElement.replaceChildren();
emit("trace.cleared");
});
在这个阶段没有隐藏的持久副本。
9. 加载并测试扩展
使用支持你所测试的 Prompt API 配置的 Chrome 构建。实验性渠道与 flag 会随时间变化,因此把当前 Chrome 文档与你的 EPP 说明当作事实来源,而不要把版本主张硬编码进扩展。
然后:
- 打开
chrome://extensions。 - 启用 Developer mode。
- 选择 Load unpacked。
- 选中
browser-ai-observatory目录。 - 打开一个普通网页。
- 打开 DevTools。
- 选择 AI Observatory。
- 选择 Inspect capability。
要测试生命周期,而不只是答案。
| 测试 | 预期观察 |
|---|---|
| API 未暴露 | 面板报告结构性缺失而不抛错 |
| 能力不可用 | Create 保持禁用 |
| 冷模型 | 下载事件出现在会话完成之前 |
| 热模型 | 可在不假定进度事件的情况下创建会话 |
| 普通提示 | 首个分片与总耗时被记录 |
| 生成中停止 | 结果是 aborted 而非 failed |
| 空提示 | 不发起请求 |
| 清除轨迹 | 现有行消失,一条新的 clear 事件开始该序列 |
如果 API 应当存在却不工作,Chrome 暴露 chrome://on-device-internals 用于模型状态与诊断。我们的面板补充那个浏览器内部视图。它不取代它。
10. 这第一个版本证明了什么
扩展证明:浏览器管理的模型可以参与一个普通扩展界面,而无需应用服务器或模型 API 密钥。
更重要的是,它揭示了一行提示词演示所隐藏的生命周期。
实验应当产生一条形如这样的轨迹:
capability.inspect.started
capability.inspect.finished { availability: "downloadable" }
session.create.started
model.download.progress { loaded: 0.04 }
...
model.download.progress { loaded: 1 }
session.create.finished { durationMs: ... }
prompt.started { capture: "metrics-only" }
prompt.chunk { index: 1, elapsedMs: ... }
...
prompt.finished { outcome: "completed", totalMs: ... }
这条轨迹可以被比较、存储、汇总,并最终被评估。控制台记录做不到这些事。
11. 它没有证明什么
它不证明输出是正确的,也不证明本地推理比远程替代更快。它不证明内容从不离开这台机器;我们只是表明这次模型调用不需要我们自己的模型服务器。
面板也有盲区。它无法观察被检视页面内部私密发起的调用,除非浏览器通过受支持的接口暴露该事实,否则它也识别不出确切的模型版本。轨迹无法在面板关闭后存活,它也尚未把模型响应与页面事件、网络请求、WebMCP 工具或产品结果关联起来。
这些限制不是本章的缺陷。它们是下一章的需求。
结论
我们构建了最小但有用的 Browser AI Observatory。
它是一个真实的 DevTools 扩展,但它最重要的组件不是面板,而是事件模型。面板现在把能力检视、可选的模型获取、会话创建、流式生成、首个输出时间、总时长、取消与操作性失败暴露为彼此不同的事件。
本章现在既解释这个模型,也运行它。它的实时页面从导出的同一批事件推导仪表盘,而回放模式演示了缺失的测量依然缺失。结果是我们的第一章:其散文、可执行体验与扩展源码从三个方向描述同一件仪器。
该实现还守住了一条诚实的边界:它观察扩展自己拥有的工作。它不声称对被检视应用内部的 AI 调用拥有神奇的访问权。
下一章会有意跨过那条边界。我们将设计一个选择加入的插桩桥,把页面数据与扩展控制分开,定义带版本的轨迹信封,并把实验控制台变成一台真正的监视器与调试器的开端。
参考与延伸阅读
- Chrome for Developers, Extend DevTools.
- Chrome for Developers,
chrome.devtools.panels. - Chrome for Developers, The Prompt API.
- Chrome for Developers, Inform users of model download.
- Chrome for Developers, Get started with built-in AI.