qishui-host

汽水工具箱的插件宿主：一个薄壳，自己不干任何业务。

它只做四件事：列账号 / 建页签 / 转发事件 / 管插件。宿主里不该出现"冷启动" 这种词——它只认识 plugin.json。想加功能就写插件。

┌──────────────────────────────────────────────────┐
│ 汽水工具箱   core 1.0.0 · API v1   账号:[主号 ▾]  │
├──────────────────────────────────────────────────┤
│ [插件管理] [数据 · 冷启动流量] [数据 · 数据看板]  │
└──────────────────────────────────────────────────┘

安装与运行

# 先装内核（或 pip install git+…/qishui-core.git）
pip install -e ../core

cd host
python -m qishui_host.main            # 起界面
python -m qishui_host.main --list     # 看发现了哪些插件
python -m qishui_host.main --install ../plugins/coldstart
python -m qishui_host.main --task coldstart   # 无界面跑一次（给计划任务用）

环境变量 QISHUI_HOME 决定数据根，不设就用当前目录。插件从两处扫：

<数据根>/plugins/<pid>/plugin.json          ← 用户装的（优先）
<程序目录>/plugins/<repo>/<pid>/plugin.json ← 随包分发的

插件契约

一个插件 = 一个目录 + 一个 plugin.json：

{
  "id": "coldstart",
  "name": "冷启动流量",
  "version": "1.0.0",
  "api_version": 1,
  "summary": "一句话说明它干什么",
  "entry": "coldstart.plugin:ColdStartPlugin",
  "tab": { "group": "数据", "title": "冷启动流量", "order": 10 },
  "needs": ["api", "auth", "store"],
  "standalone": "coldstart/__main__.py",
  "update": { "feed": "https://raw.githubusercontent.com/…/update.json" }
}

api_version 不匹配就拒绝加载并说明原因，绝不半加载——半加载比不加载更难查。

插件类不继承任何基类（不继承就不会被宿主的改动绑死），按需实现：

方法	什么时候调	必须
setup(ctx)	加载后立刻。无界面任务只有这一步	有后台任务就必须
build(ctx)	要嵌成页签时（懒加载，点到才建）	有界面就必须
on_account_switch(uid)	切账号	否
on_day_tick()	每天第一次心跳	否
on_unload()	卸载/退出前	否
run_task()	--task <pid>	否

插件只能通过 ctx 访问能力：

ctx.log("开始抓取");  ctx.warn("...");  ctx.error("...")
ctx.uid;  ctx.port;  ctx.account()          # 当前账号
ctx.api;  ctx.auth                          # 内核能力（端口已自动绑好）
ctx.account_dir();  ctx.account_path("x.json")
ctx.account_load_json("x.json", {})
ctx.store.load_json/save_json/append_jsonl  # 插件私有数据
ctx.settings.get/set                        # 落盘设置
ctx.schedule.daily(fn, "07:30")             # 每日定时
ctx.on_account_switch(cb)                   # 切号回调
ctx.notify(title, text, "info")             # 弹提示
ctx.open_path(p)                            # 打开文件/目录

三条硬规则：

1. 插件崩了不许带崩宿主 —— discover/load/build/broadcast 全程 try/except
2. 插件不许 import 宿主 —— 只能有 ctx
3. 插件不许自己拼账号路径 —— 一律 ctx.account_dir()

违反第 2、3 条的插件，评审直接拒。因为这两件事一旦放开，"换号串数据"和 "宿主一改插件全崩"就一定会发生——我们已经在旧版本里踩过。

插件管理页

宿主第一个页签永远是「插件管理」，每个插件一张卡：

• 停用 / 启用 —— 不建页签、不占内存，文件保留
• 检查更新 —— 读 update.feed，有新版就下载校验解压到暂存区
• 历史版本 —— 列出最近 4 份归档，一键回滚（回滚前会把当前版本也归档）
• 卸载 —— 搬到 plugins/_removed/，账号数据保留，同一个按钮再点一次是「恢复」

卸载之所以不直接删：误点不可逆是最容易让人后悔的操作。留档 + 可恢复， 才敢把按钮放在那儿。

打包成 EXE

pyinstaller --noconfirm --windowed --name 汽水工具箱 ^
  --add-data "plugins;plugins" ^
  --hidden-import qishui_core.api --hidden-import qishui_core.updater ^
  qishui_host/main.py

插件不进主程序，装的时候放 <数据根>/plugins/ 就行——这是拆分的意义： 主程序几十 MB，插件各自几十 MB，谁需要谁装。

许可

MIT。