技术

AskAI 划词:一个不让 API Key 进浏览器的 Firefox 扩展,以及 AMO listed 上架踩坑

目录
  1. 一、需求:划词问 AI,但 key 不能进浏览器
  2. 二、扩展本身:几乎没有权限
  3. 三、本机代理:安全边界都在这里
  4. 四、划词 UI:0×0 宿主与 pointer-events
  5. 五、9 种语言,33 个 key
  6. 六、Chromium/Edge:一份代码,两个 manifest
  7. 七、AMO 渠道:listed 与 unlisted 不是一回事
  8. 八、踩坑清单
  9. 九、这次学到的
  10. 附件

环境:Firefox 142+(MV3)、Chromium 157 / Edge、Arch Linux、Python 3(仅标准库)、systemd user service
目标:选中网页文字就能问自己的 AI,答案流式显示;API Key 不能进浏览器,也不能有遥测和账号
结果:Firefox 扩展 1.2.0 已提交 AMO listed(等待审核),界面 9 种语言;同一份代码产出 Chromium/Edge 包并在 Chrome for Testing 157 上通过实测
代价:一次渠道选错、一个新 add-on ID、以及 1.1.0 被 Mozilla 停用

一、需求:划词问 AI,但 key 不能进浏览器

现成的划词扩展不少,但大多数要求把 API Key 填进扩展设置,等于把长期密钥交给一个能读所有网页的 content script。需求里最硬的一条是:

帮我找找 Firefox 插件,划词问 AI、快速响应的那种;没有的话帮我做一个,要确保 key 的安全。

于是架构先定死:浏览器里没有 key。扩展只访问本机回环地址,key 只存在于本机代理的配置文件里。

网页选区
  └─ content.js(按钮/面板)
       └─ background.js(流式转发)
            └─ POST http://127.0.0.1:8787/v1/ask
                 └─ proxy/server.py(持有 key)
                      └─ 任意 OpenAI 兼容上游

这么做有三个连带的结果:

  • 扩展要的权限可以非常少;
  • 用户得自己在本机跑一个代理,这是最劝退人的地方;
  • 上游随便接,DeepSeek、OpenAI、OpenRouter 都行,本地 Ollama 也行。

二、扩展本身:几乎没有权限

manifest.json 的关键部分:

{
  "manifest_version": 3,
  "name": "__MSG_extensionName__",
  "version": "1.2.0",
  "default_locale": "en",
  "options_ui": { "page": "options.html", "open_in_tab": false },
  "browser_specific_settings": {
    "gecko": {
      "id": "askai-selection@serein-213",
      "strict_min_version": "142.0",
      "data_collection_permissions": { "required": ["websiteContent"] }
    }
  },
  "host_permissions": ["http://127.0.0.1:8787/*"],
  "background": { "scripts": ["background.js"] },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"],
    "run_at": "document_idle"
  }]
}

注意这里没有 permissions 字段:没有 storage、tabs、scripting。唯一的主机权限是 http://127.0.0.1:8787/*。扩展也不使用 browser.storage,设置全部由代理读写。

分工:

  • content script:所有页面注入,负责选区按钮与面板;用 shadow DOM 隔离页面 CSS;通过 browser.runtime.connect({ name: "ask" }) 连 background。
  • background:每个面板一个 port;只请求 /v1/ask;解析 SSE 的 meta / delta / done / error;port 断开时 AbortController.abort()。
  • options:GET/PUT /v1/settings。敏感字段只读:
readonly: ["api_key", "base_url", "extra_headers"]

三、本机代理:安全边界都在这里

proxy/server.py 只用 Python 标准库(ThreadingHTTPServer),绑定 127.0.0.1:8787:

路由 作用
GET /health {"ok": true}
POST /v1/ask text/event-stream
GET/PUT /v1/settings 读取/保存非敏感设置

安全上没走「加个 token」的路,直接把能碰到的面都堵上:

  • Host 必须是 127.0.0.1:8787 或 localhost:8787;
  • Origin 只允许 moz-extension:// / chrome-extension://;
  • Content-Type 必须是 application/json;
  • 请求体上限 64 * 1024;
  • 不返回 CORS 头;
  • 上游 key 在所有错误消息里脱敏。

错误也是结构化的:

{"error": "forbidden host"}
{"error": "forbidden origin"}
{"error": "content-type must be application/json"}
{"error": "body too large"}
{"error": "连接上游失败:<ExceptionName>"}
{"error": "上游返回 HTTP <code>"}
{"error": "流中断:<exc>"}

systemd 单元把「只读根 + 只放开配置目录」坐实:

[Service]
Type=simple
ExecStart=/usr/bin/python3 /home/chen/askai/proxy/server.py
Environment="ASKAI_CONFIG=/home/chen/.config/askai/config.json"
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/chen/.config/askai
Restart=on-failure
RestartSec=3

install.sh 负责用 $XDG_CONFIG_HOME 定位配置、建目录 700、写配置 600、生成绝对路径的 unit;set-key.sh 无回显读 key,原子写入后重启服务。

四、划词 UI:0×0 宿主与 pointer-events

最早的版本按钮点不到。最终方案是三层:

host.style.cssText =
  "position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none";
.pill  { position: fixed; display: none; pointer-events: auto; }
.panel { position: fixed; display: none; flex-direction: column; pointer-events: auto; }

即:宿主是 0×0、永不吃事件;按钮和面板自己开 pointer-events: auto;层级拉到最大。1.0.4 的发布说明只有一句:

修复划词按钮、停止/复制/关闭按钮无法点击。

这类 bug 的难点不在 CSS,而在「注入层 + shadow DOM + 页面自身事件」三者叠加,改完必须逐按钮点一遍。

五、9 种语言,33 个 key

1.2.0 的主要功能就是 i18n:

  • default_locale: "en";
  • _locales/ 下 9 个语言:en、zh_CN、zh_TW、de、es、fr、ja、ko、ru;
  • 每个语言包 33 个 key,覆盖设置页、面板按钮/状态、错误提示;
  • manifest 的 name / description 用 __MSG_*__。

新增语言只需要复制 en/messages.json 翻 33 个 key,不用改代码。

AMO listing 填了 19 个 locale:界面支持的 9 个之外,还有 pt-BR、it、pl、tr、uk、nl、sv-SE、cs、hu、ro。后 10 个是让助手翻的,没找母语的人看过。

六、Chromium/Edge:一份代码,两个 manifest

build-chromium.sh 做三件事:

  1. 复制 extension/ 到 build/chromium/;
  2. 删掉 browser_specific_settings;
  3. 把 background 改成 service_worker,输出 dist/askai-<version>-chromium.zip。

代码里一行 shim 兼容两边的 API:

const browser = globalThis.browser ?? globalThis.chrome;

Chrome for Testing 157 实测通过:

  • 扩展加载、service worker 正常;
  • 划词 → 面板 → 流式 MOCK-OK;
  • 请求带 Origin: chrome-extension://...,代理放行;
  • 设置页 /v1/settings 正常;
  • Alt+Shift+A 可用;
  • 35 秒无 token 慢流,service worker 未被回收。

限制也明确:品牌版 Chrome/Edge 137+ 会忽略 --load-extension,自动化只能用 Chrome for Testing;普通用户要在 chrome://extensions 手动加载 build/chromium。Chrome Web Store 和 Edge Add-ons 都还没提交。

七、AMO 渠道:listed 与 unlisted 不是一回事

这部分花的时间最多,坑也最密。

  • sign.sh 走的是自发布:
npx --yes web-ext@10.8.0 sign \
  --source-dir extension \
  --channel unlisted \
  --artifacts-dir dist
  • 但要在 AMO 搜索里出现,必须走 listed,且渠道是 add-on/version 级属性,不能事后随便改。
  • 版本号跨渠道唯一。于是 1.0.7 用与 1.0.6 完全相同的代码重新提交,只为占住 listed 渠道。
  • 旧 add-on 的渠道历史上已经乱了,最终在 1.1.0 直接换新 ID askai-selection@serein-213,重新走 listed。
  • 结果:1.1.0 被 Mozilla 停用;1.2.0 以新版本 6695329 提交,状态「等待审核」。提交完成页写得很清楚:

此版本在 addons.mozilla.org 发布后,您将会收到确认邮件。请注意,可能需要 24 小时才能正式发布;若此附加组件需人工审核,则需更长时间。

还有一个容易漏的字段:Firefox 新提交要求 data_collection_permissions。本扩展只声明 websiteContent,因为选区文本确实会发给用户自己的上游。

八、踩坑清单

现象 根因 修法
划词按钮、停止/复制/关闭点不到 注入层命中区域 / pointer-events / 层级 0×0 宿主 + none,按钮/面板 auto,z-index 最大
面板提示「连不上本地代理」 8787 未启动或端口不对 systemctl --user start askai;curl /health
设置保存失败 request_options 非 JSON 对象、温度/max_tokens 越界、Origin/Content-Type 校验 代理返回 400/403/415;设置页显示本地化错误
systemd 起不来 配置目录不存在、ProtectHome=read-only、ReadWritePaths 不对 install.sh 建目录并写绝对路径;旧版用 --force
提交后公开页/搜索不显示 版本仍在「等待审核」;unlisted 本来就不公开 看「状态和版本」,等审核
__MSG_*__ 不生效 / AMO 报数据收集缺失 缺 default_locale / _locales / data_collection_permissions 补齐 9 个语言包与 websiteContent 声明
品牌 Chrome 不加载扩展 Chrome 137+ 忽略 --load-extension 手动加载 build/chromium,或用 Chrome for Testing

九、这次学到的

  1. 隐私这件事写进文案没用,得做进架构里。扩展没有 permissions、没有 storage、唯一的主机权限是回环地址,key 只在代理里——这些用户自己翻源码就能核对。
  2. 「得自己跑一个本机服务」会劝退一批人,但换来的是 key 不进浏览器。这个代价要在开头就说,别等用户装完才发现。
  3. 审核比写代码磨人。渠道、版本号、add-on ID、data_collection_permissions,错任何一项,代码没问题也上不了架。
  4. 别同时开两个商店。Chromium 包和实测先做扎实,再决定要不要投 Chrome Web Store 和 Edge。
  5. 还没做完的:1.2.0 仍在审核;10 个 listing 语言没经过母语审校;Firefox 1.2.0 的提交包打在 Chromium shim 加进去之前(shim 在 Firefox 上是空操作,但源码和产物对不上字节)。

附件