目标:让开发者,尤其是 AI,在不用人在窗口里点点点、不用人复制日志的前提下,复现各种界面状态、使用应用的真实功能, 并自己看到“刚才发生了什么”。
唯一的 Vite 环境变量是 VITE_DEV_FEATURES(.env.development 默认 true)。关闭时:设置里没有“开发者”页、没有 window.__dev、
没有浏览器模式,src/dev 不会进入产物。任何构建(含 release)里它恒为关闭(vite.config.ts 注入编译期常量 __DEV_FEATURES__)。
| 入口 | 适用者 | 说明 |
|---|---|---|
| AI 推荐:真实 Rust + 浏览器 | AI | npm run dev:ai(放后台跑),就绪后输出 [dev-ai] READY。以 dev-bridge feature 启动 Tauri dev,用浏览器工具打开 http://localhost:1420/(选哪个见下文“选浏览器工具与内核”),页面自动连到真实 Rust。node scripts/dev-ai.mjs status 查询是否就绪 |
| 仅夹具(不编译 Rust) | AI | npm run dev:browser,端口 1421(DEV_PORT 可改),全部命令由夹具应答,适合快速看界面状态与 AI 场景 |
| 真机窗口 | 人类 | npm run tauri dev。人类可以直接操作原生 GUI;AI 场景也在这条路径生效(LLM 默认跟随环境真实请求,免 Key 预览需打开“免 Key 预览 AI”),见下文“AI 场景” |
| 自动化操作真机 | AI(必要时) | npm run tauri dev -- --features webdriver,受窗口遮挡影响,见 automation-debugging.md |
优先用 playwright-cli:它能指定内核,渲染与事件行为和真机对得上;agent-browser(vercel-labs)只有 Chromium,适合临时看页面、抓文本,内核相关的问题不要用它下结论。
内核按平台选,与 Tauri 在真机上用的保持一致:
| 平台 | 真机内核 | 用法 |
|---|---|---|
| macOS | WKWebView | playwright-cli open --browser=webkit <url> |
| Linux | WebKitGTK | playwright-cli open --browser=webkit <url> |
| Windows | WebView2(Chromium) | playwright-cli open --browser=msedge <url>(或 chrome) |
- 界面与手势问题先在对应内核复现:macOS/Linux 的问题在 Chromium 里复现不出来是正常的,反之亦然(如拖到窗口外松开时 mouseup 丢不丢,各内核就不一致)。
- 需要逐事件构造手势(按下、多次移动、抬起分开下发)或中途
eval读组件内部状态时,只有 playwright-cli 够用;它的会话是常驻的,两条命令之间不会丢页面。 - 浏览器版本与 CLI 绑定,首次
open --browser=webkit报缺内核时按提示安装(npx playwright install webkit)。 - 系统取词、托盘、全局快捷键、原生窗口在浏览器里测不了,仍要真机复核(见
automation-debugging.md)。
Rust 侧 src-tauri/src/application/dev_bridge.rs(Cargo feature dev-bridge,release 构建会 compile_error!)起一个本机 HTTP 服务:
- invoke 通过 Tauri 公开的
WebviewWindow::on_message转给主窗口,走generate_handler!里全部已注册命令, 含 State 注入、权限检查和插件命令——新增命令、新增事件无需改任何桥接代码。 - 前端
listen某个事件时,服务端用listen_any订阅并经 SSE 推给浏览器(真实的config-changed、sentence-captured等都能收到)。 - 浏览器经 Vite 的
/__dev/bridge/*代理访问(令牌只在代理里注入,浏览器拿不到;要求本机 Host 与自定义头X-Dev-Bridge)。 端口与令牌写在dev-bridge.local.json(gitignore)。
桥接下仍由夹具处理的命令(有真实副作用):打开程序/目录、全局快捷键挂起恢复、开机自启动、剪贴板、原生窗口、 AnkiConnect 请求与 Anki 的启动探测(默认模拟,不会写进你真实的牌组;“Anki 状态”选“真实 Anki”才连真的)。 配置读取是真实的,但写入默认只落在浏览器会话(“桥接下配置的写入位置”),不会改你本机的开发配置和 API Key。
AI 请求按环境取默认值:Tauri 应用默认真实请求,浏览器桥接/夹具默认模拟。 “跟随环境”是 LLM 场景的默认值;显式切到“真实请求”才会在所有环境联网,显式选任一模拟场景才会在所有环境用夹具。
拦截点在业务侧的 HTTP 入口(src/logics/net.ts),不在 Tauri IPC 层,所以三种入口共用同一套规则。
注意:原生窗口同时在跑同一份前端,划词事件等会被两边各收到一次;但 AI 场景在原生窗口与浏览器页都生效,不会出现“浏览器里是 mock、原生窗口在烧 token”的割裂。
AI 相关请求由 src/dev/mock/llm.ts 处理。llmScenario 默认 auto:Tauri 应用默认真实请求,浏览器(桥接/夹具)默认模拟;显式选择可以覆盖环境默认。覆盖:
- AI 优选:命中候选、fallback、整句翻译、拼写错误、乱码;
- 思考模型的思维链(reasoning)与流式输出;
- 参数降级重试(400 → json_object)与编号错误后的纠正重试;
- HTTP 错误、空响应、非法 JSON;
- 设置页“测试连接”与“获取模型列表”。
默认值 llmScenario='auto':Tauri 联网、浏览器不联网。要强制真实请求请切到“真实请求”;要强制模拟请选任一模拟场景。
打开“免 Key 预览 AI”(mockLlmConfig)后:
read_config会返回http://dev-mock.local/v1、假 Key、假模型,并启用 AI;- 不修改真实配置文件;
- 模拟配置生效期间,
commit_config会剔除 LLM 相关键,避免假配置写进真实配置; - 关闭开关后恢复真实配置;
- 只在非“真实请求”场景生效;
- 在
auto下开启它会强制使用模拟场景(否则 Tauri 的默认真实请求不会使用假配置);如果 LLM 场景已显式选“真实请求”,此开关会被禁用并提示无效。
设置页“AI 优选”顶部会出现“开发模拟”警示卡。这个开关在 tauri dev、dev:ai、dev:browser 都有效,所以没有 API Key 也能预览 AI。
llmScenario |
预期界面/行为 |
|---|---|
auto |
Tauri 真实请求;浏览器桥接/夹具按 pick 模拟(默认) |
pick |
AI 卡命中词典条目,显示“笔记:(dev mock)已选中第一条候选” |
thinking |
先出现“AI 正在思考”,随后进入正文 |
fallback |
显示“AI 生成 / 非词典条目”和模拟语境释义 |
sentence |
显示“AI 译文 / 整句”和模拟整句译文 |
misspelling |
显示“未收录”和“(dev mock)正确拼写:design” |
gibberish |
显示“未收录”和“(dev mock)无法识别的乱码或误触” |
bad-json |
AI 卡进入失败态,错误为 no JSON object found in AI output |
http-error |
AI 卡进入失败态,错误包含 HTTP 401 |
empty |
AI 卡进入失败态,错误为 stream ended with empty content |
compat-retry |
第一次请求 400,warnings 出现“参数不被接受,降级后重试”,随后成功 |
bad-pick-retry |
第一次给非法编号,warnings 出现“追加提醒后重试一次”,第二次成功 |
real |
真实请求;夹具模式(dev:browser)没有 Rust 网络,会失败 |
思考态是瞬态:默认每块 120ms,想截图或看清可以调大到 150–300ms;idle() 等的是“安静”,抓瞬态文案用 waitFor 或短间隔轮询 __dev.text()。思维链内容不进 UI,这是产品设计,夹具只呈现“AI 正在思考”的状态。
切换场景会自动清空 AI 结果缓存与参数兼容缓存;已经显示在界面上的卡片需要点“重新生成”或重新查询才会按新场景重走。也可以随时点开发者页的“重置模拟状态”或调用 __dev.resetMock()。
# 命中候选(零配置)
agent-browser open 'http://localhost:1421/?dev.llmScenario=pick&dev.mockLlmConfig=true'
# 思考模型 + 慢速流式(观察“AI 正在思考”和打字机)
agent-browser open 'http://localhost:1421/?dev.llmScenario=thinking&dev.llmStreamDelayMs=150&dev.mockLlmConfig=true'
# 失败态
agent-browser open 'http://localhost:1421/?dev.llmScenario=http-error&dev.mockLlmConfig=true'agent-browser eval '(async () => {
await __dev.idle();
const m = __dev.mark();
__dev.fill("回车查询单词", "design");
__dev.press("Enter", "回车查询单词");
await __dev.waitFor("重新生成", { timeoutMs: 5000 });
await __dev.idle({ quietMs: 400 });
return { text: __dev.text(), report: await __dev.report(m) };
})()'report().invokes 里会看到 http POST dev-mock.local/v1/chat/completions [dev pick] 200 0ms 这样的记录;
idle() 会把夹具的流式输出算进“尚未安静”,不会在正文还没写完时提前返回。
真实请求:
# 只在 dev:ai / tauri dev 下有真实网络;会使用配置中的真实 API Key,产生费用
agent-browser open 'http://localhost:1421/?dev.llmScenario=real&dev.mockLlmConfig=false'页面里的 window.__dev.help() 会打印用法。核心套路:把一整段操作写进同一条 eval——用 agent-browser 时标签页在两条命令之间可能回到空白页,
元素编号每次快照都会变;playwright-cli 的会话常驻,但也建议一条 eval 走完一段操作,少来回、输出更完整。
__dev 的助手按可见文字定位元素、用 idle() 等应用安静,不需要编号和 sleep。
eval 里直接返回对象(不要 JSON.stringify),输出才不会被二次转义。
agent-browser open 'http://localhost:1420/?dev.ankiState=plugin-missing' # URL 参数:只对本页生效,不写任何文件
agent-browser eval '(async () => {
await __dev.idle();
const m = __dev.mark(); // 1. 取游标
__dev.fill("回车查询单词", "serendipity"); // 2. 操作(按可见文字)
__dev.press("Enter", "回车查询单词");
await __dev.idle({ quietMs: 600 });
__dev.click("添加到 Anki");
await __dev.idle({ quietMs: 600 });
return await __dev.report(m); // 3. 一次拿回发生的一切
})()'report 返回:errors(未捕获异常、console.error)、failedInvokes(失败的命令及错误)、warnings、
invokes(命令与 HTTP 调用轨迹,如 http POST localhost:8765/ [addNote] 200 81ms、search_collins 21ms)、
dialogs / alerts(页面上弹出的对话框与提示的文字,不用截图)、mocks(当前环境实际生效的模拟清单)、rustRecentWarnings(Rust 日志里近期 WARN/ERROR)。
| 接口 | 作用 |
|---|---|
__dev.mark() / await __dev.report(since) |
游标与“自游标以来”的汇总 |
__dev.click(文字或选择器, nth?) |
点击;按可见文字 / aria-label / title 匹配。找不到或有多个同名元素时报错并列出候选(含所在区块的开头文字),用 nth(从 0 起,文档顺序)指定第几个 |
__dev.fill(placeholder或标签, 值, nth?) / __dev.press(键, 目标?) |
填输入框(触发 v-model)/ 按键 |
await __dev.idle({quietMs, timeoutMs}) |
等到无进行中的命令/请求且 DOM 静止;超时不抛错,返回 settled: false。看不到定时器:应用在做重试/宽限期这类 setTimeout 式等待时(如 Anki 连不上时约 8 秒后才弹错误),它会误判“已安静” |
await __dev.waitFor(文字或正则, {timeoutMs}) |
等页面可见文字里出现某段文字,如错误对话框的标题;超时返回 found: false。有重试/宽限期的流程用它代替 idle |
__dev.text(max?) |
页面可见文字 |
__dev.logs({since, level, kind}) |
原始条目(kind: console / error / invoke) |
await __dev.rustLogs({lines, grep, trace}) |
Rust 日志文件尾部(含前端 console 转发进来的内容;默认滤掉 TRACE) |
__dev.list() |
发现全部场景、可选值与当前来源 |
__dev.get() |
无参;返回当前全部生效值 |
__dev.set(k, v) / reset(k?) |
修改/清除会话覆盖;仅当前页面有效,刷新后失效 |
__dev.resetMock() |
清空 AI 结果缓存与参数兼容缓存,让下一次请求按当前场景重走 |
__dev.mockStatus() |
当前环境、所有实际生效的模拟、无效值警告与禁用项;report().mocks 是同一份数据 |
__dev.emit(event, payload) |
浏览器里模拟后端事件,__dev.sampleCapture 是一份划词载荷示例 |
__dev.backend |
'bridge'(真实 Rust)或 'fixtures' |
开发者页顶部有一条醒目的“当前有 N 项模拟生效”横幅;同样的数据可以通过 __dev.mockStatus() 拿到,report() 也会带上它:
{
environment: 'browser-bridge',
environmentLabel: '浏览器 + 桥接',
mocks: [
{ key: 'llmScenario', title: 'AI / LLM', value: '命中候选', detail: '...' },
{ key: 'bridgeConfigWrites', title: '配置写入', value: '仅浏览器会话', detail: '...' },
],
warnings: [{ key: 'llmScenario', message: '...' }],
disabled: [{ key: 'platform', reason: '...' }],
effective: { llmScenario: 'pick' },
settings: { /* 每个 key 的 enabled / disabledReason / warning / effectiveValue */ },
}在开始调试前先调一次 __dev.mockStatus():它可以回答“当前是不是夹具、AI 会不会联网、哪些设置其实没生效、当前环境禁用哪些项”。
页面上的禁用与警示色描述也来自同一份计算(src/dev/status.ts),不会出现 UI 说一套、接口说一套。
设置页的规则:
- 当前模式下完全无效的项会禁用并写明原因(如 Tauri 下的平台模拟、Anki 状态、浏览器后端、配置写入位置);
- 当前值无效的项用 WinUI warning 色(浅色
#9a6700、深色#d4a72c)提示描述文字,卡片边框保持中性(如夹具模式选“真实 Anki/真实请求”、显式真实请求时开“免 Key 预览 AI”、没有模拟请求时调模拟延迟)。
截图用浏览器工具的 screenshot;能用 report / text 回答的问题优先用文字,省 token 也更准。
不开浏览器也能看 Rust 日志:curl -H 'X-Dev-Bridge: 1' 'http://localhost:1420/__dev/bridge/logs?lines=100&grep=error'。
启动/停止:npm run dev:ai(后台跑)、node scripts/dev-ai.mjs status、node scripts/dev-ai.mjs stop。
端口与实例标识由环境变量决定(scripts/dev-env.mjs,vite、tauri 包装器、dev-ai 共用),严格模式:端口被占用就失败,绝不自动顺延。
| 用法 | 行为 |
|---|---|
| 什么都不设 | 与以往完全一致:端口 1420、共用 identifier(沿用已授权的辅助功能与已有配置) |
DEV_PORT=1430 npm run dev:browser |
只换 Vite 端口,夹具浏览器模式(不起 Rust),可与其他实例并行;缺省 1421 |
DEV_INSTANCE=foo DEV_PORT=1430 npm run dev:ai |
并行跑完整的 Tauri:identifier / 产品名带 .foo 后缀,单实例互斥、配置目录、日志文件全部独立 |
- 设了
DEV_INSTANCE就必须显式给DEV_PORT,否则直接失败(避免默认撞上日常实例的 1420)。 - 只换端口、不设实例名,并且已有同 identifier 的 Tauri 在运行时,单实例插件会让新进程悄悄退出;
dev-ai的启动前检查与“就绪前退出”提示会指出这一点。 dev-ai启动前先探测端口:被占用时直接报错并说明占用者是哪个 worktree(是不是自己),退出码 3。status的 JSON 里own表示端口上的是不是本 worktree,AI 以它判断“就绪的是不是自己的实例”。- 隔离实例的配置从模板新建,没有日常实例里的 API Key 和全局快捷键:不会多个 AI 同时烧 token,也不会争抢快捷键;辅助功能授权按 identifier 记,隔离实例需重新授权(并行实例走桥接,划词取词本就不在浏览器里测)。
- 桥接端口随机分配,连接信息写在各 worktree 自己的
dev-bridge.local.json;dev-settings.local.json、dev-ai.local.pid同样按 worktree 隔离。每个 worktree 各自编译 Rust(各自的target/)。 - WebDriver(固定 4445)不支持并行:并行开发请用桥接,不要用 WebDriver。
注册表在 src/dev/schema.ts(标题、说明、默认值、取值范围),设置页“开发者”入口、文件校验、URL 参数和 window.__dev 都由它生成。
设置页按语义分组:AI 与 LLM、Anki 与模板、更新与版本、浏览器模式、其他行为;完全无效的项会禁用并写明原因,值无效的项会用 WinUI warning 色提示。
新增一项:改注册表;业务代码经 logics/debug.ts 读取,纯 dev 夹具可直接读 src/dev/state.ts 的 devSettings。
取值优先级:URL 参数 / window.__dev.set(仅当前页面) > dev-settings.local.json(项目根,gitignore,
设置页修改立即生效并写入,外部编辑也会实时同步;读写经 Vite 插件 /__dev/settings)> 默认值。
默认值原则:不产生外部副作用的读取/展示尽量与真实行为一致;有副作用的外部调用由显式场景控制——Anki 写入默认模拟,AI 按环境默认(Tauri 真实、浏览器模拟)。
需要按环境取不同默认值的设置用 auto 在运行时解析,不拆成两个键:目前只有 LLM 场景。
拆键会让同一个行为在两个入口各有一份值,容易漂移,也让 URL 参数/文件配置的优先级更难解释。
- 应用模块顶层不要访问 Tauri 运行时 API(如
os.type()),用函数惰性读取——浏览器模式的 IPC 打桩在应用模块之前才装好。 - 真实 Tauri 命令的调用轨迹只在浏览器模式可用:真实 Tauri 窗口里
__TAURI_INTERNALS__.invoke是不可写、不可配置的属性,包装会抛 TypeError。原生窗口里report().invokes仍会包含 dev 夹具直接处理的 HTTP 请求(由拦截器补记),但不包含真实 Tauri 命令(console / 报错 / 对话框文字照常)。dev 初始化的任何失败都不会阻塞应用挂载。 - 浏览器内核要与平台对齐(macOS/Linux 用
webkit、Windows 用 Chromium,见“选浏览器工具与内核”);即便如此,系统取词、托盘、全局快捷键在浏览器里仍测不了。真机复核见automation-debugging.md(含截图前的可见性保护)。 on_message在 Tauri 文档里标注为非稳定 API(供自定义 invoke 系统使用);升级 Tauri 后若桥接编译失败,只需修dev_bridge.rs一个文件。- playwright-cli / agent-browser 的浏览器若在沙箱里启动失败(
sandbox initialization failed),需在沙箱外运行。
笔记模板不是本应用的一部分:它是一段经 AnkiConnect 发给 Anki 的自包含字符串。源码在 src/card-template/,
由 scripts/card-template.mjs 在 Vite 的 load 钩子里按需构建、改源码时失效缓存并整页重载。
tauri dev、dev:ai、dev:browser、vitest 与 vite build 走的是同一段代码,没有单独的构建步骤。
| 文件 | 作用 |
|---|---|
front.html / back.html |
mustache 模板;<!-- card-script --> 处插入打包后的脚本 |
script.ts |
卡片脚本,打包成单个 IIFE(换卡时脚本会重复执行,靠这层保证安全) |
style.css |
样式;图标以 url('./icons/x.png') 引用,构建时内联为 data URL |
icons/ |
图标源文件(PNG / SVG) |
release-note.md |
模板更新说明,设置页展示 |
预览页:设置 → 开发者 → “卡片模板预览”,或直接访问 /dev/card。渲染的就是构建产物(与发给 Anki 的完全一致),
可切样本、预览宽度与夜间模式;链接点击会被拦下并显示目标地址,折叠与朗读按原样执行。
依赖约束:src/shared/ 与 src/card-template/ 只能用标准 Web API。构建期有白名单(引入应用运行时直接构建失败)、
lint 有限制导入、产物测试会连续执行两次脚本。要共用逻辑请放进 src/shared/。