浏览器插件安装引导 PRD

用户问题

• 用户提了一个正常需求，agent 干到一半停下来，用户不知道发生了什么。
• 一句 Not connected 这类笼统提示无法区分没装、装错浏览器、装了但页面没刷新，用户会反复卡在同一步。
• 用户去装插件时注意力已经离开对话；回来还要再点一次按钮，会觉得系统没记住他刚做过的事。
• 用户没看到提示、点了拒绝、点了安装却没回来，这些都是常态；今天这些路径都会变成悬案。

本版目标

• 工具执行前探测依赖，缺失时抬起一张停靠式引导卡，不先制造一次可见失败。
• 依赖状态区分未安装与浏览器不匹配，并给不同的下一步；第二次失败进入内容不同的排障态。
• 检测到依赖就绪时自动续跑原任务，用户不需要回来点确认。
• 退出分两类：Skip／发新消息／超时把卡片折成可展开的 mini 条，× 才是彻底关闭且需二次确认。依赖事后就绪且意图仍在时反向唤醒。

范围边界

• 本版覆盖两道平行的门：安装 Operator 扩展、开启 user scripts 权限。两者互不为前置，交互骨架共用，差异见第 8 节。
• 这是产品文档，描述用户看到什么、系统该有什么行为。OpenClaw 是我们的运行底座，本文只在第 13 节集中列出对它的能力需求；正文不受它当前实现限制。
• 依赖探测能力由我们自己的扩展提供，产品侧只消费探测结果。
• 本 PRD 以浏览器能力为具体场景，机制对任何「操作前需要用户先完成外部一步」的能力通用。
• 面向英文客户，所有产品文案为英文；本文档为中文，正文引用按钮时一律写真实英文串。第 8 节是文案定稿口径。

非目标

• 不做插件本体的安装器、更新器或版本协商。
• 不做跨设备的依赖状态同步；每台设备各自探测、各自显示。
• 不在本版自建等待机制来绕开运行时的等待上限；该上限是待补能力，见第 13 节。

阅读方式

• 产品评审先读用户故事和故事状态原型，确认每条异常路径都有终点。
• 设计评审用完整交互原型走一遍全部用户故事，重点看状态之间的过渡文案。
• 开发实现从用户故事映射到 FR、OP、AC，再看字段映射和显示规则；运行时能力的边界看第 13 节。

两个出口，一个镜子

• Skip 是「先收起来」，折成 mini 条随时展开；× 是「拿走」，需二次确认且本会话不再出现。
• 设置页是状态镜子加指路牌，不拥有开关——真正的开关在浏览器里（装／卸扩展、开／关权限）。
• 产品侧因此没有「永久关闭能力」这回事，任何一次退出都不会让能力变成不可达。

保留在主路径

• 停靠式引导卡：目标说明、缺失项、安装按钮、已装好按钮、跳过。
• 依赖三态区分及各自的下一步动作。
• 依赖就绪自动续跑，并把卡片塌缩成一行摘要。
• 依赖就绪时的反向唤醒（限最近一次意图）。
• 跳过后的降级方案或干净收尾。
• 动作区从左到右按权重递增排列：Skip（弱）靠最左，次要动作居中，主按钮贴最右。手机上主按钮落在拇指热区，误触成本最高的「Skip」落在最难碰到的一侧。
• 动作行最多三个控件，且必须在 360px 视口下保持单行。卡片上不放永久性动作——那是另一类决定，属于设置页；塞进来还会挤爆这一行并把主按钮甩到左下角。
• 非交互 run 的能力状态位与通知。

从主路径隐藏

• 工具名、内部请求 ID、决策枚举值等内部标识不出现在用户文案中。
• 不展示审批剩余秒数倒计时，避免制造时间压力；到期直接换态。
• 不展示「一直允许」这个决策——安装是一次性动作，不存在持续授权语义。
• 不在首次引导里堆排障内容；排障只在第二次出现。
• 不为引导单独开一个设置页；常驻入口就是扩展 options 页里的 Browser control 分组。

依赖状态

ready = 已安装且可用，不出现引导。

absent = 当前浏览器未安装插件。

wrong-browser = 在其他浏览器中检测到，但当前会话所在浏览器没有。

插件装完即可用，没有配对或授权步骤，因此不存在「已安装但连不上」这一类状态。

用户决策

继续 = 放行本次调用。按钮文案随状态变化：Install、Already installed、Try again、Continue setup、Open settings。

跳过 = 阻断本次调用，文案固定 Skip。

卡片上没有第三种决策。

终态

answered = 依赖就绪并放行，任务继续。

denied = 用户跳过或隐式跳过。

expired = 超过 等待上限，核心 fail closed。

unavailable = 非交互 run，无法抬起引导。

抑制层级

只有两层，且只作用于「要不要弹卡」，从不影响能力本身。

run 级 = 同一轮内多个工具需要同一依赖，只引导一次。

会话级 = 任一脱身路径之后，本会话不再自动弹；下次新会话恢复。

没有账号级：产品侧不拥有开关，真正的开关在浏览器里。用户反复要求做浏览器的事，我们就反复告诉他还差什么——那是回答，不是骚扰。

渲染方式

引导卡由我们自己渲染，运行时只提供待决请求的结构化数据与放行/阻断通道。

推荐把它当成独立于聊天流的一层来画——安装引导本质不是一条聊天消息。

文案、布局、按钮全部由产品定义，不受运行时默认渲染约束。

文案原则

• 先说用户的目标，再说缺什么；不要以系统的问题开头。
• 禁用词：error、failed、unavailable、required、blocked；不使用错误色。
• 用第一人称的 agent 口吻（I'll pick up right where I left off），不用系统播报口吻。
• 不暴露工具名、内部请求 ID、决策枚举值或 plugin id。
• 首次引导必须承诺装完自动继续，因为这直接决定用户是否愿意离开去装。
• 超时文案必须可续，不能读起来像结案。
• 按钮用动词开头的祈使短语，最多两词；不用 OK / Yes / No 这类无信息量标签。
• 不要把文案绑死在单一用途上。同一道门服务多个工具（读页面、点击、填表、抽取…），标题若写「要读取页面」，换个工具就成了错的。任务上下文由紧邻的 agent 消息提供，卡片只负责说清缺什么。
• 跳转类动作要在标签上说清去哪儿。设置页两个按钮都会离开 Sider（去商店 / 去 chrome://extensions）。写 Enable 会读成「点一下就开了」，用户点完发现开了个新标签页，会觉得被骗了一下——所以写 Open Chrome settings。
• 用真实产品名，不用泛称。叫 Sider Operator，不叫「browser extension」——用户点安装后落地的商店页写的就是这个名字，对不上会让他怀疑装错了东西。
• 按钮文案有宽度预算：卡片在 360px 视口下内容区只有 306px，动作行三个控件合计不得超过它。标题已给出上下文时优先用单动词（Install 而不是 Install extension）。

超时话术写法

• 它进入的是模型上下文，不是用户界面；写成给模型的指令，且与产品文案同为英文。
• 参考：Sider Operator is not installed yet. Do not apologize and do not retry. Tell them you'll continue once they say it's set up, and that they can also set it up in Settings, then stop.
• 超时也是一条脱身路径，所以这段话必须包含设置页指引——否则静置离开的用户是四条路径里唯一没被告知的。
• 不设它时超时是 timed_out 失败，模型多半会道歉或反复重试。
• 设了它超时会转成 veto，文本原样成为模型看到的原因。

场景：装完自动继续

• 用户点安装后注意力已经转移到商店标签页，此时再要求他回来点确认，会读起来像系统没记住他刚做过的事。
• 探测到就绪即放行，卡片塌缩为一行摘要，agent 直接给出原任务结果。
• agent 的下一条消息必须完成原任务，不能只说「好的，插件装好了」就停止。
• 自动放行的安全前提：这是能力开通门，用户的安装动作即为同意。真正的敏感操作审批不适用本规则。

场景：用户一直没操作

• 审批时限硬上限 10 分钟且 fail closed，这是协议常量，不通过修改核心来绕开。
• 到期与 Skip 同一个出口，只是摘要措辞不同；agent 的收尾话术必须可续。
• agent 收尾由 超时话术 驱动，读起来是「装完告诉我」，不是道歉或报错。
• 用户之后随时装好，反向唤醒会把这件事重新提起来。

抑制与恢复规则

• run 级：同一轮只引导一次。只作用于弹卡，不影响能力。
• 会话级：任一脱身路径之后本会话不再自动弹；下次新会话恢复。
• 没有账号级。产品侧没有关闭能力的开关，设置页只映射浏览器里的真实状态。
• 依赖状态从就绪变为缺失是新原因，清除该门的会话抑制——用户本会话跳过过一次，不该导致他后来主动开了又被关掉时收不到提示。
• 设置页始终显示两项的真实状态并提供引导入口，不受任何抑制层影响。
• 不做定时暂停档。会话级已经覆盖「现在别烦我」；再加一档会让三个出口互相混淆，用户分不清自己刚才选了哪个。

预防优于拦截

• 设置页 Browser control 分组常驻显示「Browser extension not installed」并提供主动安装入口。
• 首次开启相关能力时就引导安装，而不是等到用了才拦。
• 本 PRD 的引导卡是安全网，最好的结果是它一次都不出现。
• 默认关闭的能力必须在同一次改动里给出具名的开启路径，这是仓库既有规则，不是本 PRD 的额外要求。

必须通过

• 引导抬起前不产生任何可见的工具失败记录。
• 卡片停靠在输入框上方，不使用聊天气泡，也不使用模态框。
• 依赖状态在文案和主按钮上真正分开，不合并成一句 Not connected；卡片里不出现配对码、授权码之类插件不需要的步骤。
• 探测到就绪时自动放行，不要求用户回来点第二次。
• 「Install」和「Already installed」是两个按钮，点安装不等于放行。
• 动作区从左到右为 Skip → 次要动作 → 主按钮；主按钮贴右，「Skip」贴左，且 DOM 顺序与视觉顺序一致。
• 360px 视口下每个状态的动作行都是单行，主按钮始终贴右。
• 点「Already installed」必须重新探测，不得盲目放行。
• 第二次提示进入排障态，内容与首次不同。
• 「Skip」和 × 结果不同：Skip 最小化，× 彻底关闭。mini 条上也有 ×，触屏上必须常驻可见。
• 用户发新消息等同跳过，新消息不被吞成对引导的回答。
• 超时不渲染为错误态，文案可续，并折成 mini 条。
• 暂缓折成 mini 条，关闭需二次确认并留下指向设置页的一行；两者结果不同。
• 依赖事后就绪且意图仍在时反向唤醒；意图已过期则静默。
• Skip 与 × 是两件事：前者最小化成可展开的 mini 条，后者彻底关闭并留下设置页指引。
• 设置页两个按钮都是跳转（商店 / chrome://extensions），不是就地开关；两行在就绪时保留展示且不给按钮。
• 非交互 run 落到能力状态位与通知，不静默吞掉。
• 恢复待处理引导前校验背后 run 存活。
• 同一引导多端只保持一份，一端解决后其他端收起。
• 不展示倒计时，不展示工具名、内部请求 ID 或决策枚举值。

需要重点看代码

• 依赖探测是否在工具执行前完成，而不是失败之后才补。
• 超时是否走产品定义的可续话术，而不是运行时的默认失败文案。
• 卡片是否只暴露「继续」和「跳过」两种决策，没有混入持续授权。
• 自动放行前是否真的重新探测过，而不是复用上一次的探测结果。
• 工具 execute 开头是否再探测一次——放行不代表依赖真的就绪。
• 隐式暂缓是否先阻断本次调用再放行消息，避免两条线并行。
• run / 会话两层抑制标记的写入与清除时机。
• 恢复流程是否校验 run 存活，僵尸审批是否被正确标记为过期。
• 多端场景下 「请求已解决」事件 是否被所有渲染端消费。
• 非交互路径下工具返回的失败文本是否可读、是否指明下一步。
• 无人值守的运行 的判定是否覆盖 cron、heartbeat 和非交互 CLI。

必须当场对齐

• 产品要的是「工具执行前拦住、阻塞到用户决定」。运行时已具备这个能力，细节和缺口见第 13 节。
• 渲染端由自定义 channel 全权负责；OpenClaw 只提供视图模型和决策通道，按钮文案不构成约束。
• 等待时长应由产品决定。运行时当前有固定上限，属于待补能力（第 13 节）；在补齐前用可续的超时文案兜底，上限值不进用户文案。
• 定时任务等非交互 run 完全无法弹卡，这是核心行为，必须由能力状态位和通知兜底。
• 插件装完即可用，没有配对或授权步骤；探测只需回答装没装、装在哪个浏览器。
• 状态区分是产品必须项，不是优化项；合并成一句 Not connected 会让用户卡死。
• 自动续跑是本设计的关键，不是加分项；把它降级为「用户回来点一下」会显著劣化体验。

容易误解的点

• 「继续」 不代表依赖真的就绪，它只是放行；工具 execute 必须自己再探测一次。
• 「Skip」只是这一次不用。产品里没有「永久关闭」这个东西——用户真想停用，是去浏览器里卸载扩展或关掉权限。
• 设置页不是控制面板，是状态镜子加指路牌——它不能开关任何东西。
• 跳过不是终点：摘要行指向设置页，用户再问一次也会重新引导。
• 审批记录持久化，但等待中的工具调用不持久化——记录活着不等于任务还能续上。
• 超时不是错误；把它渲染成失败会让用户以为系统坏了。
• 超时话术 进的是模型上下文，不是用户界面；写给模型看，不是写给用户看。
• 引导卡的最佳状态是一次都不出现；设置页 Browser control 分组和 onboarding 的常驻入口和它同等重要。

建议开发拆分

• Slice 1：依赖探测 + 工具执行前抬起引导 + 超时话术；工具真正执行前再探测一次。
• Slice 2：订阅待决请求，渲染首次引导卡，接通「继续」与「跳过」。
• Slice 3：等待态轮询探测与自动续跑，卡片塌缩与时间线摘要行。
• Slice 4：排障态与文案矩阵。
• Slice 5：反向唤醒（限最近一次意图）与两层抑制。
• Slice 6：恢复校验、多端同步、非交互路径的状态位与通知。
• Slice 7：QA 补齐，按 AC-1 到 AC-16 覆盖全部异常路径。

开放问题

• OQ-1：等待态的探测轮询节奏，需要前端和扩展侧对齐，避免在长时间等待中产生过多请求。
• OQ-4：wrong-browser 状态的可探测性依赖具体实现，需要确认能否稳定区分于 absent。配对状态已确认不存在后，它是仅剩的第二个状态；若它也探测不出来，首次引导就只有一种形态，状态区分完全落到「首次引导 vs 排障态」这一层，FR-3 需要相应收窄。
• OQ-6：能否从扩展程序化打开 chrome://extensions/?id=<id>（chrome.tabs.create）？官方文档没有明确说明。**需要扩展团队实测**——能打开则主按钮为 Open settings；打不开则退化为 Copy link 加两步图文说明，卡片会变高，需要重新量 360px。
• OQ-7：user scripts 权限门的目标扩展是我们自己的扩展还是 Operator，需要在实现前确认，它决定深链里填哪个 extension id。
• OQ-5：最小支持宽度定在 360px，所有卡片状态在此宽度下动作行单行。需要产品确认 320px 是否要一并支持。

由我们自己实现的部分

• 两类依赖的探测，以及探测结果的状态枚举。
• 引导卡、反向唤醒、设置页 Browser control 分组的全部渲染与交互。
• run / 会话两层抑制标记的读写。
• 等待态的轮询节奏与自动放行判定。
• 设置页两行的状态映射与引导入口。

外部依据

• Chrome for Developers：Enabling chrome.userScripts is changing——138+ 每扩展开关、版本迁移、官方探测写法。
• chrome.userScripts API 参考。
• 深链可导航性无官方结论，见 OQ-6，需实测。
• Sider Operator 商店页：chromewebstore.google.com/detail/sider-operator——安装主按钮的落地目标，文案里的产品名须与该页一致。