插件内置 AI¶
简单方案,等拍板。 下面每个「🔴 要你拍」都是会改变工作量或产品形态的选择。
🔴🔴 2026-09-18 二次拍板:自带 Key 直连(v0.13.1,推翻下面那节)¶
Tony 的原话:
「垃圾 新增才能选模型 新增选择厂家 填写 key 然后同步最新模型以及测试添加, 而且提示词也应该多个,帮我对抗完善逻辑 对抗」 「插件里用,当然是插件里填写 key 了 你啥逻辑?乱搞吗」 「你做完 留好填写 key key 名称 以及模型参数的地方 可以选择模型测试」
我把前一天的需求理解反了¶
他昨晚说「没有新增api和key」,我读成「不要 key 输入框」, 于是做成走平台代付、还立了一道闸禁止 key 输入框 —— 方向完全相反。
⇒ 下面那节「2026-09-18 Tony 拍板」记录的「砍掉自带 key、只走平台代付」作废, 保留仅为留痕。现在的形态是自带 Key 直连,平台代付那条这一刀没做。
落地形态(v0.13.1)¶
AI 账号(可多个) —— 五步流程,顺序在 UI 上标了号:
| 厂家 | baseUrl | 鉴权 | 格式 |
|---|---|---|---|
| DeepSeek | api.deepseek.com |
Bearer | OpenAI |
| 智谱 GLM | open.bigmodel.cn/api/paas/v4 |
Bearer | OpenAI |
| Gemini | generativelanguage.googleapis.com/v1beta |
x-goog-api-key 头 |
Gemini(单独适配) |
| 其它 | 用户自填 | Bearer | OpenAI |
- 同步模型:拿 Key 去厂商拉真实清单;失败降级到兜底清单 + 明说没同步成功
- 测试:发真的最小聊天请求(只拉到模型列表不代表这个模型能用)
- 两步都能跳过,但列表标「未测试」—— 不挡人,也不假装验过
- 模型参数:温度 / 最大输出长度,留空=用厂商默认
- 同一家可配多把 Key(不同项目/额度),名字区分,随时切换
提示词(多个):内置三个对应采集前后三环节(分类推演 / 关键词扩展 / 匹配度判断), 可增删改,且每个都有执行入口(推演对话框里选用哪个)。
安全边界重划 —— 放开的和守住的是两件事¶
| 之前 | 现在 | |
|---|---|---|
| 用户填自己的 Key | 禁止 | ✅ 这就是需求 |
| 开发者写死 Key 进代码/配置/产物 | 禁止 | ❌ 继续禁止 |
删掉两条与新需求冲突的旧闸(「UI 不许有 key 输入框」「不许直连厂商域名」),
补 tests/ai-key-never-leaves.test.ts:保护的实质不变(Key 不该扩散),变的是在哪层生效。
对抗审找出的三个 P0(都已修,逐条是真的)¶
- https 校验放错了层 —— 只在表单(
validateAccount),而「同步模型」不经过它 ⇒ 填 http 地址点同步,Key 以明文Authorization: Bearer发出去。 ⇒ 挪到网络发送边界,所有出站自动覆盖。 「什么时候校验」比「校验什么」更容易错:安全校验属于边界,不属于某个界面流程。 - Key 进 URL —— Gemini 原本走
?key=。dshf 实测x-goog-api-key头可用 ⇒ 没有任何理由把 Key 放 query(DevTools Network 可见、失败请求留痕、 别的带 webRequest 权限的扩展也读得到)。 - 错误回显可能含 Key —— 厂商/网关可能把 Authorization 原样吐回来,
而 detail 会渲染进 Alert、DOM 里也看得见。⇒ 所有出口过
scrubSecret。
仍未验证(最该先测的)¶
三家端点按公开文档写,dshf 实测了路由存在(401 证明), 但没有任何一家的 Key,没跑通过真实调用。 填一把 Key 点「测试」即可验掉这整块 —— 比任何审查都准。
🟢 2026-09-18 Tony 拍板 + 第一刀已落地(v0.12.0)¶
⚠️ 本节已被上面那节推翻(我理解反了需求),保留仅为留痕。
Tony 的原话:
「设置里加上AI的功能,单独的一个tab 没有新增api和key,默认内置 DeepSeek glm Gemini 等主流ai的接口, 另外就是提示词,比如帮客户推演产品推演分类的(后续接到输入关键词那,用户输入产品然后推演地图哪些分类适合这个品, 然后采集的速配),我希望你先简单搞一个(记得对抗完善)」
这句话拍掉了本文最大的那个待定项¶
原方案是两条供给并存:自带 key(客户端直连厂商)+ 平台代付(走服务器)。 「没有新增 api 和 key」= 砍掉自带 key 那条,只走平台代付。
⇒ 下面这些内容随之作废,保留在文中只为留痕(别照着实现):
| 作废的内容 | 为什么 |
|---|---|
| 「用户填自己的 key」「key 存 chrome.storage.local」 | 不再有 key 输入框 |
| 第三节整节(key 与模型 / 云同步带 key / 导出置空) | 没有 key 要管了,这些风险一并消失 |
| 「调用方式:直接 fetch 厂商 API,不需要中转」 | 与平台代付矛盾;直连必然要带 key |
| 商业化里「自带 key 卖功能」那半 | 只剩「平台代付卖点数」 |
顺带说一句:砍掉自带 key 让这个功能更安全也更简单 —— 原方案那一整节关于「key 怎么加密同步、导出要不要带」的复杂度全部归零。
第一刀已实现(v0.12.0)¶
做的是本文「① 关键词分析」的一个更具体的形态:产品 → Google Maps 分类推演。
| 文件 | 职责 |
|---|---|
src/utils/ai/providers.ts |
内置模型清单(单一事实源,无 baseUrl/apiKey 字段) |
src/utils/ai/prompts.ts |
提示词模板 + 渲染 + 输出解析(纯函数,零副作用) |
src/utils/ai/ai-normalize.ts |
设置修正(纯函数) |
src/utils/ai/ai-settings.ts |
读写(只有这个文件碰 storage) |
src/utils/ai/ai-client.ts |
调用层,走 umiRequest,失败翻译成人话 |
src/sections/settings/view/ai-settings-view.tsx |
设置页 AI tab |
模型清单选了 A(硬编码)而不是本文押的 C(服务端拉):
第一刀没有服务端,硬编码是唯一能跑的;清单在一个文件里,换模型改一处。
等 /api/ext/ai/models 就绪再切 C —— 那时它只是把 AI_PROVIDERS 的来源换掉。
端点对齐本文第二节:/api/ext/ai/chat(不是我一开始写的 /api/ai/chat)。
🔴 服务端还没有这个端点¶
所以扩展侧必须优雅降级:404/501 明确告诉用户「AI 功能还没在服务端开通」,
而不是甩一个 status code 404。这条有行为测试守
(tests/ai-client-failure-modes.test.ts:404/501/401/403/网络断/空响应各一条)。
核心提示词(本功能的全部价值所在)¶
你是 Google Maps 商家采集的选品顾问。用户要推广的产品是:{{product}}
请推演出**最可能采购或经销这个产品**的本地商家类型,用于在 Google Maps 上搜索。
要求:
1. 输出 8-15 个 **Google Maps 上真实存在的商家分类名**(英文),不要自造分类
2. 按「采购可能性」从高到低排序
3. 每个分类给一句中文说明:这类商家为什么会买
4. 排除明显不相关的分类
5. **只输出 JSON**,不要任何解释文字
四条要求都不是凑数的,各自防一种失败(有测试逐条钉住):
| 要求 | 不写会怎样 |
|---|---|
| 真实存在的分类名 | 模型爱自造 "Eco Garden Boutique" 这种好听但搜不到任何东西的分类 |
| 英文 | Maps 的分类体系是英文的,中文搜不到或搜到另一批店 |
| 只输出 JSON | 模型天生爱加「好的,我来帮您分析:」,那种输出没法解析成关键词 |
| 按采购可能性排序 | 用户采集配额有限,得先跑最可能的几个 |
这一刀没做的(下一刀)¶
- 接到关键词输入框 —— Tony 说的「后续接到输入关键词那」。
现在推演结果只能复制出来,还没有一键填进采集任务。
接口已经留好:
parseCategories()返回的category字段就是搜索词。 - 本文的「② 匹配度识别」—— 那是 3-5 天的批处理工程,与本刀无关。
一句话¶
内置 DeepSeek / GLM,用户填自己的 key,干两件事: ① 帮他想目标关键词 ② 判断采到的商家跟他的产品配不配。
对抗审返工(v0.12.1)—— 两路各自实跑,找出 2 个 P0¶
terra 判 NO-GO(P0×2 / P1×4),dshf 判 GO-WITH-CHANGES(P0×2 / P1×5)。 逐条核实全部成立,都修了。dshf 把闸和 helper 原样复制到 /tmp 实跑,证据很硬。
P0-①:超时完全缺失 —— 唯一能把界面钉死的缺陷¶
umi-request 默认 timeout=0(dist/index.js:662、:711)。
dshf 实测:后端不响应时请求永远 pending ⇒
设置页和任务对话框的按钮永久停在「推演中」,用户只能关页面。
⇒ 传 timeout: 60_000,并把超时和「网络断了」分成两种 reason
(下一步动作不同:换个快模型 vs 检查网络)。
60 秒不是拍脑袋:推理型模型出 10 来个分类确实要几十秒,设太短会砍掉正常请求。
P0-②:密钥闸能被绕过(dshf 实跑 4 个绕过全绿)¶
它把本闸和 codeOnly 原样复制到 /tmp/aiprobe 跑,
结果四个探针全绿而 src 里躺着两把可用 key:
| 绕过 | 为什么躺过去 |
|---|---|
src/leak.json |
walk() 只收 .ts/.tsx/.js 系,.json 不扫,而 Vite 会把被 import 的 JSON 内联进产物 |
public/keys.json |
闸只扫 src/,public/ 原样拷进产物,运行时 fetch(chrome.runtime.getURL(…)) 即可用 |
'sk-' + 'abc…' 拼接 |
正则要求连续 ≥16 字符 |
.env + import.meta.env.VITE_* / wxt.config.ts 的 vite.define |
构建期内联,源码里零字面量 |
⇒ 扫描域扩到四处:src/ 代码 + src/&public/ 的数据文件 + 构建配置与 .env + 构建产物。
🔴 最后那条才是兜底的:构建期注入用「扫源码」永远防不住(源码里真的没有),
不管从哪注入,最终都得落在 dist 里。
⚠️ 诚实标注上界:运行时拼接挡不住 —— 'sk-' + x 在源码和产物里都不是连续串。
这是静态扫描的固有限制,不是没写好。
P1:两条 UI 死路(两路各自独立判出同样两条)¶
| 死路 | 症状 | 修法 |
|---|---|---|
| 读设置失败 | 永久停在「正在读取…」,既不显示错误也没有重试 | 加失败态 + 「重试」+「用默认设置继续」 |
| 提示词被清空 | 渲染出空串 ⇒ 被「空输入」拦下 ⇒ 提示「先填一下产品名再试」,而用户明明填了 | 推演前先判模板,给真实原因和恢复路径 |
共同形态:代码知道真实原因,但告诉用户的是另一回事。
P1:parseCategories 会「假装成功」¶
[{"category":{}}]→"[object Object]"⇒ 非空、过了 filter、成了一个搜不到任何东西的关键词[{"category":[1,2]}]→"1,2"- 条数与长度都无上限 ⇒ dshf 实测 20 万条原样进
setState
⇒ 改成只认字符串(不做 String() 强转)+ 条数上限 40 + 单条长度上限 80 + 清控制字符。
P1:bad-model 文案与实现不符¶
文案写「已帮你切回默认模型,请重试」,而实现只返回一句话、UI 从不调 fallbackSelection()
⇒ 重试必然同一个错。声称做了而没做,比不做更糟 —— 用户会照着它重试,然后一直失败。
🔴 v0.13.4 订正:这一条已被结构性消除,不是「修好了」而是「前提没了」。 Tony 指出模型选择该属于使用方(提示词/功能各自绑定),
defaultModelId整个删掉 ⇒ 没有「默认模型」可退回。resolveModelRef()改为明确不回退: 模型被停用就点名说是哪个、让用户自己去勾或换,而不是替他挑一个。 静默换模型的代价是用户发现账单/效果不对却查不出原因 —— 比直接报错更难排查。
P1:提示词的 few-shot 锚点把所有产品带偏¶
两路都以「工业用不锈钢阀门,出口中东」为例判的。骨架没问题,坏在细节:
- 示例是园艺域(Garden Center / 种植照明)—— 全场唯一的 few-shot 锚点, 会给任何产品都带上零售/园艺偏向 ⇒ 换成占位符
- 缺「不带城市/国家/品牌/型号」⇒
"Plumbing Supply Store Dubai"会和扩展自己的地区设置打架 - 缺「排除同行/制造商」⇒ 模型极爱给
"Valve Manufacturer",那是竞争对手,白烧采集配额 - 缺「覆盖终端/渠道/工程三类买家」⇒ 只想着终端会漏掉最大的采购方
- 缺 why 字数上限与「必须完整 JSON」⇒ 输出可能被截断成解析不了的半截
变异验证(11 个构造 + 5 个密钥绕过,全部真红)¶
超时被拿掉、HTML 响应退回报「没返回内容」、content 非字符串退回强转、超大内容不挡、
bad-model 文案退回「已帮你切换」、category 退回 String() 强转、条数上限拿掉、
提示词退回园艺锚点、死路①失败仍只显示 loading、死路①没有「用默认继续」、死路②不判模板为空;
外加 dshf 实跑过的 4 个密钥绕过 + 构建产物兜底。
两路都点到但我改不动的一条¶
「必须先解决的是服务端端点」 —— 扩展侧代码管不到后端。 已在文档和 UI 文案里写明「扩展这边已经准备好了」。
🔴 先说最要紧的一点:这两件事的工程量差一个数量级¶
| ① 关键词分析 | ② 匹配度识别 | |
|---|---|---|
| 调用次数 | 一次几百 token,用户点一下 | 每个商家一次 |
| 你现在的数据量 | —— | 3,582 个商家 |
| 失败了会怎样 | 重点一下 | 跑到一半断了,前面白跑 |
| 成本 | 忽略不计 | 用户自己的 key,但一次全量要算清楚 |
| 工程量 | 半天 | 3-5 天 |
它们该分两刀做,而不是一个「AI 功能」。
① 关键词分析(建议先做这个)¶
入口:创建任务的对话框里,关键词输入框旁边一个「AI 帮我想」。
流程:用户填「我卖什么」(比如「工业用不锈钢阀门,主要出口中东」) → AI 返回 15-30 个关键词组合,带为什么(哪些是买家会搜的、哪些是同行会搜的) → 用户勾选 → 直接进关键词框。
为什么这个先做:它是一次性、同步、可重试的调用,没有任何状态管理。 而且它作用在采集之前 —— 关键词选错,后面采多少都是白采。
⚠️ 它的价值高度依赖 prompt 质量,而 prompt 要懂外贸。这部分我需要你给几个真实例子 (你自己会怎么给一个新业务员讲「这个产品该搜什么词」),我照着写 prompt。
② 匹配度识别(这个要设计)¶
不是「接个 API」的问题,是个批处理工程:
要解决的四件事:
- 批量打包:一次请求塞 N 个商家(名字 + 分类 + 官网标题/描述),让 AI 一次返回 N 个判断
- 只判有必要的:没官网、没邮箱的商家判了也用不上 ⇒ 先过滤
- 可中断、可续跑:跑到一半关浏览器,下次接着跑(不重判已判过的)
- 结果落库:新增字段
aiMatchScore+aiMatchReason,列表可排序/筛选
🔴 要你拍:判断依据给到什么程度
| 方案 | 给 AI 的信息 | 准确度 | 代价 |
|---|---|---|---|
| A | 商家名 + Google 分类 | 低("ABC Trading Co" 看不出卖什么) | 最省 |
| B | A + 官网标题/描述(已有) | 中 | 省 |
| C | B + 官网正文摘要 | 高 | 要先抓正文(你已有整页 Markdown) |
我押 B 起步:官网标题/描述本来就在抓,零额外成本;不够准再升 C。
🔴 要你拍:匹配度是什么形态
- 0-100 分?(好排序,但分数含义模糊)
- 三档「高/中/低」+ 一句理由?(好理解,但不好排序)
- 我押三档 + 理由 —— 你实际要做的决策是「这批要不要发」,不是「排个序」。
🔴 二、两条供给:自带 key 或用来发信点数(Tony 2026-09-17 定)¶
原方案只写了「用户自带 key」。Tony 补的一条改变了架构: 没 key / key 余额不够时,用来发信的额度,扣点数。
这是个好设计 —— 它把「先去 DeepSeek 注册充值」这道上手门槛拆掉了, 同时创造了一个消费场景。但它不是在原方案上加个开关,是两套调用链:
| 自带 key | 平台代付(扣点数) | |
|---|---|---|
| 调用路径 | 客户端直连厂商 API | 客户端 → 你的服务器 → 厂商 |
| 你的成本 | 0 | 真金白银的 token 费 |
| 你的流量 | 0 | 全部 |
| 计量 | 不需要 | 必须(按 token 还是按次?) |
🔴 为什么平台代付必须走你的服务器:平台的 key 绝不能下发到客户端。
扩展的代码任何人都能读(这一点昨天刚因为 web_accessible_resources 过宽栽过一次)——
key 一旦进了扩展包,等于公开。
⇒ 需要在 SPEC-017 那批端点里再加一个:
/api/ext/ai/chat 代理调用(扣点),body 带 {model, messages, purpose}
/api/ext/ai/models 模型清单(见下)
/api/ext/ai/quota 剩余点数 + 本月用量
🔴 要你拍:怎么计量
| 方案 | 说明 | 用户能不能预估 |
|---|---|---|
| 按次 | 一次关键词分析 = 1 点;一批匹配度(20 个商家)= 1 点 | ✅ 能,简单 |
| 按 token | 精确对应你的成本 | ❌ 用户看不懂,容易投诉 |
我押按次:你的成本可以用「单次上限 token 数」封顶,而用户能一眼算清楚。 按 token 计费的产品,客服工单里永远有「为什么这次扣得多」。
三、key 与模型¶
key 存哪:chrome.storage.local,和其它设置一起。
🔴 「云同步」和「导出文件」是两件事,key 的处置相反(v0.10.195 订正)¶
初版方案写的是「key 不该带走」—— 那句话只对导出文件成立。 Tony 指出他要的是「换台电脑登录以后所有的都能同步」,那是云同步,两者风险完全不同:
| 设置导出成文件 | 云同步到账号 | |
|---|---|---|
| 去哪 | 一个 JSON 躺在硬盘上 | 加密传到用户自己的账号 |
| 谁能拿到 | 任何拿到这个文件的人(转发、误发、进网盘) | 能登录这个账号的人 |
| 用途 | 备份 / 给别人抄一份配置 | 换机还原 ← 要的就是全量 |
⇒ 两者并存,处置相反:
导出时把 key 字段置空,并在导出提示里说明「AI key 不随文件走,换机请用云同步」。
🔴 云同步带 key 的前提(服务端必须做到): - 加密存储,不能明文落库。至少 AES-256 + 每用户独立密钥 - 服务端不解密使用(它只是个保险箱,解密在客户端) - 有「清除云端 key」的入口 —— 用户换 key / 怀疑泄露时能一键清
⚠️ 如果服务端做不到加密存储,宁可不同步 key: 明文存一堆用户的 AI key,是把一个「用户自己的风险」变成「你的风险」。
模型列表怎么「同步」:三个做法
| 方案 | 说明 | 代价 |
|---|---|---|
| A 硬编码 | 扩展里写死当前可用模型 | 模型更新要发版 |
| B 从厂商拉 | DeepSeek/GLM 都有 /models 端点 |
各家格式不同,要适配 |
| C 从来发信服务端拉 | 你统一维护一份清单 | 多一个端点,但可控 |
我押 C:你能统一决定「推荐哪个模型」,也能在某个模型涨价/下线时不发版就切。
代价是 SPEC-017 那批端点里再加一个 /api/ext/ai/models。
调用方式:扩展有 host_permissions: <all_urls>,可以直接 fetch 厂商 API,不需要你的服务器中转。
⇒ 你零成本、零流量、零责任;用户的 key 也不经过你的服务器(这点对隐私是加分)。
四、跨职能连带¶
- 商业化:双轨制之后逻辑清楚了 —— 自带 key 卖功能,平台代付卖点数。 前者是 VIP 权益(免费版不给入口),后者是消耗品。 ⚠️ 两条价格要能互相解释:如果「平台代付 100 次」的点数价明显贵于用户自己去充 DeepSeek, 用户会觉得被宰;它的溢价卖的是「不用注册第三方账号」,这个价值得讲出来。
- 支持成本:用户填错 key / 余额不足 / 模型下线,都会变成你的客服工单。 ⇒ 错误信息必须直接可行动(「你的 DeepSeek 余额不足」而不是「请求失败」)。
- 数据安全:匹配度识别要把商家名字和官网描述发给 AI 厂商。 这些是公开信息,风险低,但要在 UI 上说一句,别让用户事后才发现。
五、建议的顺序¶
- 先做 ①(关键词),半天,验证「AI 入口 + key 管理」这套基建
- key 的导出安全跟着 ① 一起做(否则 ① 上线当天就有隐患)
- ②(匹配度)单独一刀,先在几百条数据上验证准确度,再开放全量