← Browser AI From First Principles

附录 A —— Browser AI 现场指南:设置、API、状态、诊断与配置

本书的工作参考:开发设置、API 矩阵、可用性与生命周期状态、配置键、事件词典、诊断、权威性状态与 Lens 速查表。

本附录把散落在整个论证中的契约、状态与流程整合成一份工作参考。散文负责解释;这一节是给键盘用的。

发布快照:2026 年 9 月。 浏览器 flag、origin trial、API 可用性与实验性配置都会变化。下面的 flag 值与外部文档细节复现的是本版被测试的构建。凡本书自己的实验室未观察到的内容,都会照实标注。


A.1 开发设置

表面 设置 / 位置 值 / 动作 目的 稳定性
Chrome flags chrome://flags/#optimization-guide-on-device-model Enabled(实验室配置档) 本地开发的端侧模型支持 实验性,随构建重新核查
Chrome flags chrome://flags/#prompt-api-for-gemini-nano 适用之处启用 本地测试的基础模型 API 访问 实验性,随构建重新核查
WebMCP chrome://flags/#enable-webmcp-testing Enabled 不依赖 origin trial 的本地 WebMCP 开发 实验性,随构建重新核查
扩展 chrome://extensions 开发者模式,加载已解压的扩展 加载 Browser AI Observatory 长期工作流
诊断 chrome://on-device-internals 打开模型状态 检视端侧模型状态与错误 浏览器诊断界面
JavaScript DevTools 中的 LanguageModel.availability(options) 用预期选项运行 创建之前的操作预检 API 契约
Observatory AI Observatory 面板,能力检视 运行检视 捕获完整生命周期,而不是靠猜 本书工具

flag 值遵循本版的实验室运行手册约定,不是一条永久的浏览器契约。


A.2 可用性与生命周期状态

一个层级,在本书的实验室中被观察到:

层 状态 含义 该做什么
Interface not exposed LanguageModel 之类的全局对象缺席 检查浏览器、渠道、上下文、配置
Interface exposed JavaScript 接口存在 继续做操作预检
Capability unavailable 所请求的配置当前无法创建 解释、改换路线或回退
Capability downloadable 所需资源可以被获取 要求可见的用户动作
Capability downloading 获取进行中 显示进度并等待
Capability available 可创建兼容实例 调用 create()
Session creating 浏览器正在准备实例 单独度量创建
Session ready 资源存在 允许操作
Session running 请求活跃 允许取消
Session destroyed 显式的生命周期终点 不要复用
Request completed 运行时成功返回 仍要评估输出
Request aborted 被有意停止 不计为模型失败
Request failed 运行时操作失败 对失败分类
Feature accepted 应用的校验器接受了该输出 使用该结果
Feature rejected 模型完成了,但功能契约失败 修复、重试或弃权

available 不是就绪的会话,操作上的完成不是行为上的接受。


A.3 内置 AI API 矩阵

按本书适配器注册表所实现的全局对象、操作与流式支持:

能力 全局对象 创建 主操作 流式 输出
提示 LanguageModel LanguageModel.create() prompt() promptStreaming() 文本,可受约束
摘要 Summarizer Summarizer.create() summarize() summarizeStreaming() 摘要文本
写作 Writer Writer.create() write() writeStreaming() 新文本
改写 Rewriter Rewriter.create() rewrite() rewriteStreaming() 转换后的文本
校对 Proofreader Proofreader.create() proofread() — 带纠正证据的纠正后文本
检测 LanguageDetector LanguageDetector.create() detect() — 带排序的语言候选
翻译 Translator Translator.create() translate() translateStreaming() 翻译后的文本

代码中被观察到的会话动词:create、prompt、clone、destroy。本版的扩展 worker 执行 prompt;其他操作返回一个显式的不支持标记,而不是静默失败。


A.4 Prompt API 配置速查

键 位置 目的 重要说明
expectedInputs create() 与匹配的可用性检查 声明输入模态与语言 必须与预检选项一致
expectedOutputs create() 与匹配的可用性检查 声明预期输出 视为能力契约
samplingMode 已注册的 Web 实验 语义采样政策 默认在普通页面上不可用
topK 扩展兼容表面 数值采样控制 遗留扩展表面;也是一个具名的兼容替代项
temperature 扩展兼容表面 采样变化 遗留扩展表面;也是一个具名的兼容替代项
monitor create() 观察获取进度 进度事件不证明有新字节被传输
signal 创建与请求操作 取消 把中止与失败分开保留
responseConstraint 实验室表面上的 prompt 操作 用 schema 约束输出 实验室表面;结构仍需要校验

A.5 采样模式

依据当前 Chrome Prompt API 文档(外部,2026 年 9 月——除注明者外未经实验室观察):

samplingMode 意图
most-predictable 最大可预测性
predictable 强可预测
slightly-predictable 轻度可预测
balanced 可预测性与变化的平衡(典型默认值)
slightly-creative 轻度变化
creative 更多变化
most-creative 最大变化

本书实验室默认值: most-predictable。理由: 受控的实验比较,以及与本书实验期间被观察到的运行时相容——包括那条被记录的、把它与 topK: 1 和 temperature: 0 一起指名的投机解码拒绝。不是普适建议: 创意或写作功能可以正当地选择另一个受支持的配置档。


A.6 会话生命周期

暴露、创建、就绪、使用、clone、destroy、失败——见第 09 章第 6 节的表格。应用规则:把创建与推理分开度量、对用量与配额做快照、用 clone() 而不是重新提示来分叉实验、以显式的 destroy() 收尾,并记录销毁为何发生。


A.7 Observatory 事件词典

本书每条轨迹都对照一份封闭词表做校验。规范生命周期事件:

事件 含义
capability.inspect.started 能力检视开始
capability.inspect.finished 观察到暴露与可用性
capability.inspect.failed 检视本身失败
model.download.progress 浏览器发出了获取进度
session.create.started 创建尝试开始
session.create.finished 会话对应用可用
session.create.failed 创建失败
session.snapshot 观察到用量、配额与资源状态
session.cloned 从既有会话创建了分支
session.destroyed 资源被显式终止
prompt.started 模型请求开始
prompt.chunk 观察到流式输出
prompt.finished 完成、失败或中止
fixture.evaluated 执行了机器可检查的评估
feature.validation.finished 应用层的接受或拒绝

协调、权威性、政策与上下文事件:

事件 含义
coordinator.job.received 协调器接受了任务
coordinator.job.queued 任务在等待 worker
coordinator.worker.selected 空闲 worker 匹配了能力
coordinator.lease.issued 工作被租出,绝不复制
coordinator.job.started 执行开始(对已绑定的任务,在此消费权威性)
coordinator.job.completed 结果被捕获
coordinator.job.failed 错误被捕获
authority.effect.normalized 精确效应被规范化
authority.grant.bound 带摘要签发了一次性 grant
authority.grant.consumed grant 被消费一次
authority.grant.expired grant 未使用即过期
policy.compile.finished 可携带政策被编译或被拒绝
policy.decision.finished 连同规则与可逆性的决策被记录
policy.run.finished 政策评估完成,外部效应被计数
context.manifest.loaded 站点上下文通过校验
context.unit.extracted 带来源的有界单元被准入
context.unit.excluded 省略连同原因被记录
structured.candidate.received 提议进入准入
structured.validation.finished 各道门的结果被记录

A.8 捕获与隐私模式

默认是 metrics-only 捕获:记录大小与结果,不保留提示词或页面文本。内容捕获是显式且可见的。私密单元默认被排除,且不能越过外部提供方边界;排除会连带原因,而不是静默失败。


A.9 结构化输出校验门

解析、schema、领域、政策、权威性,然后是有界修复——见第 16 章第 11 节的表格。模型可以提议一个结构化动作;只有确定性政策与适当的人类权威性才准入它执行。


A.10 WebMCP 速查

实时表面是 document.modelContext.registerTool(definition, { signal }),经由 AbortController 撤回。注册需要 origin trial 或 testing flag、一个安全的顶层上下文,以及一个被暴露的全局对象;本书的探针记录 available 或 absent,而不是假定。在被测试的配置档中被观察到:WebMCP 缺席——顶点演示从不依赖它的存在。


A.11 权威性状态

一份 grant 在一个 SHA-256 摘要之下绑定一个规范化效应——origin、工具、参数、政策版本——带 TTL 且一次性使用。生命周期:bound、在协调器 START 边界恰好消费一次,或 expired。重放在执行之前被拒绝;变更因摘要不匹配被拒绝。政策请求权威性;它绝不制造权威性。


A.12 诊断决策表

症状 先查什么 再查什么 可能的层
LanguageModel undefined 浏览器、渠道、上下文 flag 与配置 暴露
availability() 返回 unavailable 传入的确切选项 硬件、存储、语言支持 能力
downloadable 可见的用户动作 获取 monitor 模型获取
downloading 永不完成 chrome://on-device-internals 重启、存储压力 获取
available 但 create() 失败 创建选项 采样与配置档兼容性 会话配置
会话成功,没有答案 提示轨迹 中止与错误事件 请求
Prompt 完成,结果错误 fixture 与评估器 带捕获证据的轨迹 行为
昨天可用,今天不可用 模型与浏览器状态 存储、更新、构建 浏览器管理的生命周期
WebMCP 全局对象缺席 origin trial 与 testing flag 浏览器构建 WebMCP 暴露
工具可见,选错了工具 选择 fixture 描述、schema、结果 智能体行为

A.13 Lens 模式

见第 24 章第 2 节的对比表。各一行:理解模式阐释,探索模式检索有界证据,治理模式可逆地应用用户政策,行动模式经由准入、政策、权威性与协调器边界提议并执行。


A.14 每次实验该记录什么

选区与输入、提供方与数据路由、带来源的证据、政策版本与决策、效应的权威性状态、worker 与执行脉络、被校验的轨迹——要充分到一个陌生人也能回放这次运行、并对发生了什么得出同样的判断。


A.15 塑封卡片

UNDERSTAND 解释            EXPLORE 检索有界证据
GOVERN 政策、可逆          ACT 提议,绝不自我授权

模型可以: 感知、分类、生成、排序、提议
模型不可以: 授予权威性、更改政策、绕过准入、
  两次消费一份 grant、捏造来源、把不确定性
  变成确定性

AVAILABILITY: absent < exposed < downloadable < available
SESSION: create, run, clone, destroy — 分别度量
GRANT: 精确效应、一次、会过期 — 在 START 被消费
TRACE: 每条主张都要通过校验,否则它没有发生