AskAI 划词:一个不让 API Key 进浏览器的 Firefox 扩展,以及 AMO listed 上架踩坑
目录
环境: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 做三件事:
- 复制
extension/到build/chromium/; - 删掉
browser_specific_settings; - 把
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 |
九、这次学到的
- 隐私这件事写进文案没用,得做进架构里。扩展没有
permissions、没有storage、唯一的主机权限是回环地址,key 只在代理里——这些用户自己翻源码就能核对。 - 「得自己跑一个本机服务」会劝退一批人,但换来的是 key 不进浏览器。这个代价要在开头就说,别等用户装完才发现。
- 审核比写代码磨人。渠道、版本号、add-on ID、
data_collection_permissions,错任何一项,代码没问题也上不了架。 - 别同时开两个商店。Chromium 包和实测先做扎实,再决定要不要投 Chrome Web Store 和 Edge。
- 还没做完的:1.2.0 仍在审核;10 个 listing 语言没经过母语审校;Firefox 1.2.0 的提交包打在 Chromium shim 加进去之前(shim 在 Firefox 上是空操作,但源码和产物对不上字节)。
附件
- 仓库:serein-213/askai
- 隐私政策:PRIVACY.md