附录 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: 每条主张都要通过校验,否则它没有发生