v10.1.5

10.1.5 · 可完全替代 Zotero Debug Bridge

新增 /debug-bridge/execute 兼容端点，接口契约与原版逐条对齐，装 ZBridge 就能卸掉原版 Debug Bridge：

项	行为
路径	POST http://127.0.0.1:23119/debug-bridge/execute
鉴权	Authorization: Bearer <token>（也接受 ?token=）
令牌来源	extensions.zotero.zbridge.token，与原有两个端点共用同一个 pref
成功	201 + application/json + 「字符串套 JSON」双层编码
无令牌	401 bearer token required
令牌错误	401 invalid bearer token
脚本异常	500 debug-bridge failed: …

三个端点

方法	路径	令牌
GET	/zbridge/ping	不需要，只回版本与端点列表
POST	/zbridge/execute	?token=
POST	/debug-bridge/execute	Authorization: Bearer（兼容）

升级方式

Zotero → 工具 → 插件 → 右上角齿轮 → Install Add-on From File…，选本页附件 zbridge-10.1.5.xpi，重启 Zotero。

验证

• node test/unit.js 63/63（原 49 条 + 兼容端点 14 条）
• python build.py --probe 9/9 真机
• python test/verify_profiles.py 逐 profile 起 Zotero 验三端点，7 个 profile 中 6 个通过（akyia4yv.2021 数据目录在 OneDrive，60 秒内端点未起，配置已就位）
• 本机 7 个 profile 已全部卸载原版 Debug Bridge，仅保留 ZBridge

ZBridge 10.1.4

让本机网页（WPS / Office 加载项、file:// 页面、本地 Web 应用）直连 Zotero，不需要任何中继进程。

Zotero 自带的 HTTP server 对浏览器来源有三道拦截（断连、不给 CORS 头、预检短路），
ZBridge 注册自己的端点把这三件事处理掉，于是浏览器里的加载项终于能直接调 Zotero。

---

本次更新（10.1.4）

• 清单改为 strict_max_version: "*"：Zotero 7.0 以上全系列可安装，不再被版本号拦住。
  • 10.0 / 10.0.x / 10.1 / 10.2 / 10.5 / 10.99 均可，已实测 10.0.7。
  • 代码里没有任何版本分支判断，只依赖 Zotero.Server.Endpoints、init(request) → [status, headers, body] 契约、allowRequestsFromUnsafeWebContent——这三样从 Zotero 7 到 10 一直没变。
• 三处兼容兜底，不再只按 10.0.7 写死：
  • query 参数载体：request.searchParams → 回退 request.query
  • 请求体：UTF-8 字符串 → 回退字节数组 TextDecoder 转码
  • Zotero.Server.Endpoints 缺失：只写日志、跳过注册，绝不抛异常拖垮 Zotero 启动
• 新增单元测试：test/unit.js 用 vm 造假 Zotero 环境，49 条断言，不装 Zotero 也能跑。
• 构建脚本增强：build.py --bump 双写版本号（manifest + bootstrap），版本不一致直接报错。

⚠️ 插件版本号与 Zotero 版本号无关，是插件自己的递增序号。10.1.4 只表示迭代次数，
Zotero 从 10.0 升到 10.5 不需要动插件版本。

---

安装

1. 下载本页下方的 zbridge-10.1.4.xpi（不要解压，它就是个 zip）
2. Zotero → 工具 → 插件 → 右上角齿轮 ⚙ → 从文件安装插件…
3. 选 zbridge-10.1.4.xpi → 弹窗提示未签名 → 点 安装
4. 提示重启 → 立即重启（也可以直接拖 xpi 到插件窗口，效果相同）

不需要管理员权限，不联网，不占额外端口，没有独立进程。

---

装完验证（三步，全过才算装好）

TOKEN=e3b6034fbdd85456f5ac6df1a4e54ef4   # 没改过就用默认值

① 端点活着（不需要令牌）

curl -s "http://127.0.0.1:23119/zbridge/ping"

期望：

{"name":"ZBridge","version":"10.1.4","zotero":"10.0.7","minZotero":"7.0","compat":"Zotero 7.0+ (verified on 10.0.7)","endpoints":["/zbridge/execute","/zbridge/ping"]}

zotero 是你本机实际版本，version 是插件版本，两者无关。

② 能执行 JS

curl -s -X POST "http://127.0.0.1:23119/zbridge/execute?token=$TOKEN" \
  -H "Content-Type: text/plain" --data-binary 'return 1+1'

期望返回 2。

③ 模拟浏览器来源（这一步才是 ZBridge 存在的意义）

curl -s -X POST "http://127.0.0.1:23119/zbridge/execute?token=$TOKEN" \
  -H "Content-Type: text/plain" -H "Origin: null" --data-binary 'return Zotero.version'

期望返回你本机的 Zotero 版本串。

---

安全说明

• 端点只监听 127.0.0.1，外网访问不到。
• /zbridge/execute 必须带 ?token=，令牌存在 Zotero 配置项 extensions.zotero.zbridge.token，改完即时生效、不用重启。
• /zbridge/ping 有意不校验令牌，只回版本信息，方便排障——不要拿它当作鉴权测试。
• 令牌走 query 而非自定义头，是为了让请求成为「简单请求」、不触发 CORS 预检。

---

文件校验

zbridge-10.1.4.xpi
sha256: d92f0a7b3f826dba1d5d04bca26b042d9f302449e337711406bba83b0fe41921

update.json 里的 update_hash 与此一致，Zotero 自动更新会校验它。

---

完整文档

安装详细步骤（含升级、卸载、故障排查表）、英文说明、构建方法：见 README。

ZBridge 10.0

ZBridge 10.0

让本机网页（file:// 加载项、WPS/Office 加载项、本地网页应用）直连 Zotero，无需任何中继进程。

为什么需要它

Zotero 10 的 HTTP 服务器对任何带 Origin 头的请求在进入端点前就断开连接，除非端点声明
allowRequestsFromUnsafeWebContent；而 CORS 响应头只在来源是 zotero.org 时才自动加。
浏览器里的页面无法自行去掉 Origin，因此原版 debug-bridge 只能靠一个本机中继转发。

ZBridge 把这三件事做在自己的端点里：

• 声明 allowRequestsFromUnsafeWebContent = true
• 自行返回 Access-Control-Allow-Origin: *（含 401/500 分支）
• 令牌走 query 而非 Authorization 头 —— 避免触发 CORS 预检（Zotero 的 OPTIONS 会在进入端点前短路且不带 CORS 头）

端点

端点	说明
POST /zbridge/execute?token=<32位>	请求体为裸 JS，返回 JSON
GET /zbridge/ping	自检，返回版本信息，不需要令牌

安装

1. 下载 zbridge-10.0.xpi
2. Zotero → 工具 → 插件 → 右上角齿轮 → Install Plugin From File…
3. 首次请求时用 /zbridge/ping 确认端点已注册

令牌在第 N 次… 见 README；插件首次加载会生成 32 位随机令牌并打印到 帮助 → 调试输出日志。

与 debug-bridge 的关系

路径不同（/zbridge/* vs /debug-bridge/*），可以并存，互不干扰。

许可证

MIT