MyBooks Toolbox Core API

后端：Core API #core-api

挂在 self.api 上，按命名空间划分：calibre / db / tasks / messages / storage / settings / utils。所有方法都是同步调用， 工具作者不需要关心背后是 Calibre 的 legacy DB、new_api， 还是应用自己的 SQLAlchemy session——这层解耦正是 Core API 存在的意义，接口本身按 语义化版本演进（manifest.json 的 core_api_version 声明兼容的最低版本）。

self.api.calibre Calibre 书库读写

查询、导入、修改书籍元数据与格式文件。

self.api.db 应用数据库

读写应用自己的 SQLAlchemy 模型（Reader / Item），不暴露裸的 Session 或 ORM 对象——全部返回/接收 plain dict，避免工具持有脱离 session 生命周期的实例。

self.api.tasks 后台任务

耗时操作（下载、格式转换、批量扫描等）应该跑成后台任务，让用户能在任务面板看到进度，而不是让 HTTP 请求一直挂起。

self.api.messages 站内消息

给用户发一条持久化的站内通知，独立于任务面板（例如任务已经 complete，但还想额外提示一句"已生成新书，可在书库中查看"）。

self.api.storage 工具专属存储

每个工具都有自己独立的数据目录，路径由 tool_id 派生，不同工具之间互不干扰。

self.api.settings 系统配置只读白名单

MyBooks 的系统配置（数据库连接串、各种第三方 API key/token 等）不能整份透给工具， 所以这里只开放一个白名单：只有显式登记过的 key 才能读到，其余一律返回调用方传入的 default，不会抛异常。

self.api.utils 通用文本/日期处理

纯函数，不依赖工具自身的状态，转发 mybooks/mybooks 仓库 webserver/utils.py 里的同名函数，行为完全一致——书籍导入/整理类工具解析文件名、标准化标题排序、解析各种 格式日期时常用得到，不需要自己再写一份。

前端：toolbox-bridge.js #bridge

工具前端是一份自包含的静态站点，由宿主 MyBooks 用 <iframe> 加载，不要求用 Vue、 不要求和宿主的前端框架版本一致。在 index.html 里引入：

<script src="/static/toolbox-bridge.js"></script>

之后即可使用全局对象 window.MyBooksToolBridge：

const rsp = await MyBooksToolBridge.fetch('run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ book_id: 42 }),
});

前端如何应对宿主主题 / 语言变化 #theme-locale

工具页面运行在一个和宿主完全隔离的 <iframe> 里（CSS/JS 互不影响），机制是这样的：

1. 宿主渲染 <iframe> 时，把当前主题和语言拼进 src 的 query string（作为初始值）：

   <iframe src="/get/tool/{tool_id}/index.html?theme=dark&locale=zh"></iframe>

   这样工具页面首次渲染（甚至在任何 JS 跑起来之前，如果你用 <html data-theme="..."> 这类 SSR 友好的写法）就能同步拿到当前主题/语言，不用等一次异步的 postMessage 握手。
2. 宿主切换深浅色主题或语言时，通过 postMessage 做运行时热更新，不再重新设置 iframe.src——不会触发工具页面整页刷新：
   • 宿主页面监听 $i18n.locale/$vuetify.theme.dark 变化，向 iframe 发 { source: "mybooks-toolbox-host", type: "locale-change" | "theme-change", locale | theme }；
   • toolbox-bridge.js 内部监听这个消息，更新 bridge.theme/ bridge.locale（用 getter 暴露，读到的始终是最新值），并触发工具通过 bridge.onThemeChange/bridge.onLocaleChange 注册的回调；
   • 工具页面内部的临时状态（表单输入等）在切换时会保留，不会像整页刷新那样丢失—— 这也是从"重设 iframe.src"方案改过来的主要动机；
   • 旧版工具（没有调用 onThemeChange/onLocaleChange）不受影响： 读取 bridge.theme/bridge.locale 的方式没变，只是不会主动收到 "变了"的推送，行为退化为"首次加载后主题/语言就不再更新"，不会报错、不会崩溃。
3. 读取初始值/订阅变化都用 MyBooksToolBridge，不要自己解析 location.search 或监听 window.onmessage：

   document.documentElement.dataset.theme = MyBooksToolBridge.theme; // "light" | "dark"
   document.documentElement.lang = MyBooksToolBridge.locale;         // "zh" | "zh-TW" | "en" | ...
   
   MyBooksToolBridge.onThemeChange(function (theme) {
     document.documentElement.dataset.theme = theme; // 实时跟随宿主切换
   });
   MyBooksToolBridge.onLocaleChange(function (locale) {
     document.documentElement.lang = locale;
   });

4. 样式层建议用 CSS 变量 + [data-theme]/data-theme 属性选择器，而不是 JS 逐个元素改 style——脚手架模板、以及下方 共享视觉基础 theme.css 都是这个写法：

   :root { --bg: #fff; --text: #1a1a1a; }
   body[data-theme="dark"] { --bg: #1a1a1a; --text: #eee; }
   body { background: var(--bg); color: var(--text); }

工具前端的多语言（i18n）方案 #i18n

边界原则：翻译字串归工具自己所有，toolbox-bridge.js 只负责 "告诉工具当前该用哪个语言、语言变了要通知它"（bridge.locale + bridge.onLocaleChange，见 上一节），不提供、 不托管任何字串目录——工具前端可以自由选择技术栈，一个共享的翻译渲染库会隐含对 DOM 结构/框架的假设，Vue3/React/纯 HTML 工具"如何应用一段翻译文本"的做法并不相同。

后端侧 self.api.* 抛出的、经过 _() 包过的字符串会跟着当前用户的 站点语言走（前提是这些字符串已经在 MyBooks 自己的翻译目录里）；工具自己代码/前端里的字符串 不会被自动翻译，需要工具自己维护。

脚手架默认实现：frontend/lib/i18n.js + frontend/locales/*.json

mytool init 默认生成一套开箱即用、不依赖任何框架的最小 i18n 胶水代码（可以整个删掉换成自己的方案，不是强制约定）：

{ "default": "en", "locales": ["en", "zh"] }

{ "action.run": "Run", "result.error": "Run failed: {error}" }

const i18n = window.MyBooksToolI18n.create();
i18n.ready.then(() => {
  document.getElementById('status').textContent = i18n.t('status.ready', { theme: bridge.theme });
});
i18n.onChange(() => { /* 重新渲染用 i18n.t() 手写的那部分文本 */ });

manifest.json 新增可选字段

{ "locales": ["en", "zh"], "default_locale": "en" }

纯展示性质的元数据（供 mybooks.top 商店列表展示"支持语言"、/admin/toolbox 工具详情展示用），不参与后端加载/兼容性检查，不绑定 core_api_version； mytool validate/build 只做格式性检查（是数组、 default_locale 在 locales 里），省略时不影响工具正常安装运行。

共享视觉基础：theme.css #theme-css

iframe 自包含带来 CSS/JS 完全隔离的同时，也让不同工具、以及工具与内置工具之间的视觉观感 天然缺乏一致性——新工具默认拿不到宿主的 Vuetify 组件库和主题变量。在不引入 Vuetify（会 带回版本锁定、体积膨胀等问题）的前提下，mytool init 额外提供一份轻量的 纯 CSS 视觉基础，让不同技术栈的工具"看起来是同一家产品"，同时不强制任何组件库。

frontend/lib/theme.css 是一组颜色变量（--mb-color-bg/ --mb-color-primary/--mb-color-error 等，共 11 个语义色 token）+ 一批可选的基础组件 class，可以整份使用、只挑变量部分接到自己已有的方案上，或整个删掉不用：

manifest.json 字段 #manifest

工具包根目录的元数据文件，mytool init 会生成一份带占位符的模板，mytool validate/build 会校验这些字段。

mytool CLI #cli

完整命令说明见仓库 README，这里只列速查表。

npm install -g mybooks-tools-builder
mytool init my_tool --name "我的工具" --author "你的名字" --repo-url "https://github.com/you/my_tool"
cd my_tool
mytool validate .
mytool build