跳转至

插件内置 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 上标了号:

新增 → ①选厂家 → ②填 Key → ③同步模型 → ④选模型 → ⑤测试 → 添加
厂家 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(都已修,逐条是真的)

  1. https 校验放错了层 —— 只在表单(validateAccount),而「同步模型」不经过它 ⇒ 填 http 地址点同步,Key 以明文 Authorization: Bearer 发出去。 ⇒ 挪到网络发送边界,所有出站自动覆盖。 「什么时候校验」比「校验什么」更容易错:安全校验属于边界,不属于某个界面流程。
  2. Key 进 URL —— Gemini 原本走 ?key=。dshf 实测 x-goog-api-key 头可用 ⇒ 没有任何理由把 Key 放 query(DevTools Network 可见、失败请求留痕、 别的带 webRequest 权限的扩展也读得到)。
  3. 错误回显可能含 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」的问题,是个批处理工程:

3,582 个商家
  ├─ 全判一遍?   一次调用判 1 个 = 3,582 次请求
  └─ 批量打包     一次判 20 个 = 180 次请求   ← 必须这么做

要解决的四件事:

  1. 批量打包:一次请求塞 N 个商家(名字 + 分类 + 官网标题/描述),让 AI 一次返回 N 个判断
  2. 只判有必要的:没官网、没邮箱的商家判了也用不上 ⇒ 先过滤
  3. 可中断、可续跑:跑到一半关浏览器,下次接着跑(不重判已判过的)
  4. 结果落库:新增字段 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 ✅   —— 换台电脑登录就全有了,这正是它存在的意义
导出文件  不带 key ❌  —— 文件会离开设备,而 key 是能直接花钱的东西

导出时把 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 上说一句,别让用户事后才发现。

五、建议的顺序

  1. 先做 ①(关键词),半天,验证「AI 入口 + key 管理」这套基建
  2. key 的导出安全跟着 ① 一起做(否则 ① 上线当天就有隐患)
  3. ②(匹配度)单独一刀,先在几百条数据上验证准确度,再开放全量