Plugin-shot (dsh-plugin-shot-dev)
explorer-exe-bilibili/plugin-shot/dsh-plugin-shot-dev
Registers the plugin-shot-dev skill for building Plugin-shot plugins without the host source tree: it downloads the official offline SDK, scaffolds from a template, writes the C++, builds with CMake, and runs `Plugin-shot.exe --test-plugin` before the plugin is installed.
Install
dsh plugin --profile web add github:explorer-exe-bilibili/plugin-shotThis plugin lives in the dsh-plugin-shot-dev subdirectory of the repository.
README
Plugin-shot
中文 | English

一句话,给截图工具加个功能。 万物皆插件:宿主只做加载、校验、调度;截图、保存、剪贴板、通知、托盘、热键、设置页都由插件提供。 缺什么功能,跟 DSH 说一句——它用离线 SDK 写插件、编译、用真实宿主自检,再经你同意装进插件目录。
Plugin-shot 是一个 Windows-first 的 C++23 截图工具,也是一次「把桌面工具做成插件宿主」的实验: 宿主很小,插件可以独立编译、独立分发、运行期热插拔;ABI 只追加,数据形状不进契约。
30 秒了解
- 一句话加功能:装 DSH 技能
plugin-shot-dev,对 DSH 说“每次截图后在右下角加时间水印”,它下 SDK、生成工程、编译、用--test-plugin自检,再经你同意装进plugins/。 - 不用宿主源码:离线 SDK 核心包 0.9 MB,自带契约头、构建规则、4 个模板、2 个 demo;不装 vcpkg、不装 OpenCV(需要时加 13 MB 叠加包)。
- 真宿主自检:
--test-plugin走真实加载链路 + 隔离数据目录,PASS/FAIL/SKIP + JSON;两个 demo 自检 PASS(水印 22/0/3,归档 15/0/5)。 - Windows 即用:Windows 10/11 x64 便携版,解压运行
Plugin-shot.exe,无需安装。 - Linux 已验证:Ubuntu 24.04(X11)/ Ubuntu 26(Wayland,单显示器)核心链路已真机跑通,按 构建 编译。
- 三种入口 / 截图之后:
Ctrl+Alt+S整屏、Ctrl+Alt+A区域框选(悬停吸附、单击截窗)、Ctrl+Alt+O设置;保存 PNG/JPEG、写剪贴板、弹通知。Windows / X11 为全局热键,Wayland 用session_control的 D-Bus 入口。 - 能力即插件:托盘、热键、设置页、保存、通知、剪贴板本身都是插件,可在设置页一键禁用/启用。
一句话是怎么发生的
- 在 DSH 里安装
dsh-plugin-shot-dev/(设置 → 插件 → 添加插件 → 选择目录;需要 DSH 0.2.x)。 - 对 DSH 说清楚想要什么,例如“截图保存后自动按日期归档到「年-月-日」文件夹”。
- DSH 判断能力 → 下载 SDK → 脚手架生成工程 → 写代码 / 配置项 / 中英文案。
cmake编译 +Plugin-shot.exe --test-plugin <dll> --json-out report.json自检;PASS 后再交付。- 你确认后 DLL 进
plugins/,重启或截一张验收;卸载就是删 DLL。
细节见 document/AUTHORING.md、document/PLUGIN_TEST.md、dsh-plugin-shot-dev/README.md。
下载
Plugin-shot 0.1.0 · GitHub Releases · 更新日志
| 资产 | 用途 |
|---|---|
Plugin-shot-0.1.0-win64.zip(约 6.5 MB) | Windows x64 便携版,解压双击 Plugin-shot.exe |
plugin-shot-sdk-0.1.0-win64.zip(约 0.9 MB) | 离线插件 SDK 核心包:契约头、shot_plugin_helpers、构建模块、文档、模板、两个 demo、技能 |
plugin-shot-sdk-0.1.0-win64-opencv.zip(约 13 MB) | 可选 OpenCV 叠加包;解压后把 opencv/ 放进核心 SDK 根 |
0.1.0 发布后修复了一批发现在发布包中的问题,当前资产为修复版(
--help/--capture/--test-plugin已复测);SHA-256 见 Release 页。
每个 zip 都有同名 .sha256。0.1.0 的预编译包只提供 Windows;Linux 已在 Ubuntu 24.04
(X11)与 Ubuntu 26(Wayland,单显示器)真机验证,按 构建 从源码编译
(分步见 Linux 编译手册);macOS 尚未验证。详见 平台。
CI artifact:三平台 CI 构建完成后会把产物上传到 GitHub Actions 的 artifact (
plugin-shot-<platform>-release;Windows 另有plugin-shot-windows-dist-<版本>,含宿主便携包 与 SDK 包,名称与内容见.github/workflows/cmake.yml)。Windows 的宿主便携包与 SDK 包可直接 下载使用;Linux / macOS 的 artifact 是编译产物打包,依赖构建机上的 vcpkg 运行库(RPATH 指向 构建目录),需自行补齐依赖或按 构建 从源码编译。
界面

设置页本身也是插件:宿主把插件声明的配置项聚成
config_list,表单、主题色、插件启停都在这里。
接手开发 / 让 AI 接手:先读
AGENTS.md(构建、验证、本机环境、已踩过的坑), 再读STYLE.md(代码风格与工程约定)。
设计理念
核心保持极小且稳定,能力通过插件无限扩展(类似 DeepSeek Harness 的思路)。
宿主(当前产物名为 Plugin-shot.exe)负责:
- 扫描插件目录,动态加载
.dll/.so/.dylib - 只解析一个导出符号
shot_module_entry,拿到自描述的模块表 - 先看
struct_size再读字段、比对abi_major,不兼容立刻拒绝加载 - 用
query_interface("shot.image_processor", 1)问能力,不认识的能力安静跳过 - 把实例包装成 C++ 对象,按
PluginType分类索引:五种具名能力之外、但 metadata 声明过的 纯订阅/纯配置插件按Generic兜底加载;插件对象由插件自己销毁,宿主绝不delete - 采集流水线在独立工作线程执行(有界队列,满即丢弃并 warn),抓屏/编码不再阻塞 事件分发;区域截图由宿主整屏抓取后按物理像素裁剪
- 支持运行期启用/禁用插件:禁用即热卸载(销毁实例 → 退订事件总线 →
FreeLibrary), 重新启用则重新加载 DLL 并回灌已存配置 - 把插件贡献的 UI 数据按 list id 聚成只读 JSON 快照(
shot.host.plugin_lists), 列表变化用lists.changed通知;新增数据形状只加 list id + JSON schema,不再改 ABI
插件(动态库)负责一切具体能力。当前主线是截图。
当前状态
| 能力 | 状态 |
|---|---|
插件加载 / 长度与版本校验 / 按类型索引(含 PluginType::Generic 兜底) | ✅ 可用 |
单入口 shot_module_entry + 自描述模块表(struct_size 约定) | ✅ 可用 |
一 DLL 多插件(plugin_count + create(index) + get_info) | ✅ 可用 |
能力查询 query_interface("shot.image_processor", 1) | ✅ 可用 |
屏幕采集 shot.screen_capture(plugins/screen_capture,GDI 抓虚拟桌面物理像素;可选把鼠标光标合成进截图(include_cursor 配置,默认开);混合 DPI 双屏实测 3584x1600;Wayland 走 portal ScreenCast + PipeWire;Linux X11 用 XShmGetImage 优先 / XGetImage 回退 + XFixes 光标合成;两条 Linux 分支均已真机验证:Ubuntu 26 Wayland 的 portal ScreenCast 全屏与 Ubuntu 24.04 X11 单显示器采集) | ✅ 可用(Windows / Linux 单显示器;document/CAPTURE.md) |
图像保存 shot.image_saver(plugins/image_saver,PNG / JPEG + 四个配置项) | ✅ 可用(document/CAPTURE.md) |
采集 → 处理 → 保存流水线(工作线程 + 有界队列 4 + 整段持生命周期锁;capture.request / capture.done / capture.failed) | ✅ 可用(document/CAPTURE.md) |
宿主主循环(事件驱动阻塞等待,无 16ms 轮询;publish / post_to_host / 插件启停都会唤醒) | ✅ 可用(document/EVENT_BUS.md §3) |
区域截图(capture.request 带合法 region,宿主抓整屏后按物理虚拟桌面像素裁剪、越界夹取;plugins/region_selector 框选覆盖层;无 region 的框选触发请求由流水线忽略、不采集;Windows / X11 走宿主流水线裁剪,Wayland 由 region_selector 自行裁剪并发布 capture.done;Windows / Linux(X11、Wayland)均已真机验证) | ✅ 可用(Windows / Linux 单显示器;document/CAPTURE.md §3.1) |
通用插件类型 PluginType::Generic(只声明 shot.configurable + create 里订阅事件;有 metadata 才兜底加载) | ✅ 可用(document/SETTINGS.md §3.3) |
宿主事件总线 shot.host.event_bus(主题发布 / 订阅) | ✅ 可用(document/EVENT_BUS.md) |
通用列表服务 shot.host.plugin_lists(按 list id 返回 JSON 快照:config_list / tray_command_list / i18n_source_list / i18n_list) | ✅ 可用(document/LISTS.md) |
列表事件协议 lists.*(add / remove / update / commit / updated / changed,事件驱动写值) | ✅ 可用(document/LISTS.md) |
宿主插件注册表 shot.host.plugin_registry(启停 / 热卸载) | ✅ 可用(document/SETTINGS.md) |
运行库提供者 shot.lib_provider(PluginType::Lib) | ✅ 可用(plugins/opencv_provider 把 OpenCV 带进进程) |
UI 提供者 shot.ui_provider(窗口/托盘/热键/覆盖层由插件自己创建) | ✅ 可用(plugins/settings_ui、plugins/tray、plugins/hotkey、plugins/region_selector) |
插件配置 shot.configurable(插件声明,宿主聚成 config_list、事件驱动写值 / 存盘 / 回灌) | ✅ 可用(document/SETTINGS.md) |
设置页插件 plugins/settings_ui(读 config_list,ImGui + GLFW + OpenGL3,描述符驱动表单;双屏 150%+100% DPI 已验证) | ✅ 可用(跨平台;Windows / Linux 已验证) |
托盘入口 plugins/tray(tray_command_list 数据驱动菜单:core 四项 + 插件贡献;Windows 用 Win32 托盘,图标默认宿主命名资源 IDI_ICON1、可用 icon 换 .ico;Linux 用 StatusNotifierItem + com.canonical.dbusmenu(GDBus / 系统 gio-2.0),图标取自桌面主题,已在 Ubuntu 顶栏真机验证(图标/菜单正常)) | ✅ 可用(Windows / Linux) |
通知插件 plugins/notify(截屏成功/失败气泡,隐藏占位图标;配置 enabled / show_on_success / show_on_error / sound;Linux 用 libnotify,已在 Ubuntu 24/26 真机验证) | ✅ 可用(Windows / Linux) |
剪贴板插件 plugins/clipboard(订阅 capture.done → CF_DIB / 可选 CF_HDROP;配置 enabled / also_file_drop;Linux 走 X11 selection(X11 直连 / Wayland 经 XWayland 桥接),已在 Ubuntu 24/26 真机验证) | ✅ 可用(Windows / Linux) |
全局热键插件 plugins/hotkey(列表驱动:功能插件向贡献型列表 hotkey_list 添加条目,hotkey.main 只读快照并注册;内置 capture / region / settings → capture.request / settings.open,默认 Ctrl+Alt+S / Ctrl+Alt+A / Ctrl+Alt+O;设置页用 options="hotkey" 录入,值存 hotkey.main/<id>;冲突按列表顺序先到者生效、后者 WARN;Windows 用 RegisterHotKey;Linux 用 X11 XGrabKey(锁修饰符变体、BadAccess 冲突 WARN、self-pipe 事件循环、suspend/resume),已在 Ubuntu 24.04 真机验证(Ctrl+Alt+A / Ctrl+Alt+S / Ctrl+Alt+O 均可触发);纯 Wayland(取不到 X11 Display)运行期降级为只提供列表与配置项、不注册,WARN 指向 session_control) | ✅ 可用(Windows;Linux X11) |
Linux 会话控制插件 plugins/session_control(会话总线暴露 org.pluginshot.Control;Capture / CaptureRegion / OpenSettings / CaptureLong → 既有事件;Wayland 没有全局热键 API,用桌面「自定义快捷键」执行 gdbus call 触发;配置 enabled;仅 Linux) | ✅ 可用(Linux):D-Bus 触发已在 Ubuntu 24.04(X11)/ Ubuntu 26(Wayland)真机验证;见 document/PLATFORMS.md §3.3 |
区域框选覆盖层 plugins/region_selector(悬停窗口吸附 + 单击截窗口 + 拖动选区;四角主题色折角与约 100ms 平滑动画;Esc / 右键取消;Wayland 为门户定格图 + 拖选(确认后先 glfwPollEvents 再编码,裁剪/PNG 编码/写盘移入工作线程;portal 等待 30s、每 5s 一条进度日志);Linux X11 为 GLFW 无边框覆盖层 + 背景快照(合成器下自动回退 XComposite,不再灰遮罩)+ XQueryTree/_NET_WM_WINDOW_TYPE 窗口命中(隐藏后同样补 glfwPollEvents),与 screen_capture 的 X11 分支已联调;两条 Linux 分支均已真机验证:Wayland 门户定格图拖选(确认后覆盖层立即消失、无“应用无响应”、保存+剪贴板)与 X11 单显示器完整交互(悬停吸附、截窗、拖框、Esc、保存+剪贴板)) | ✅ 可用(Windows / Linux 单显示器;document/CAPTURE.md §3.1) |
长截图插件 plugins/long_capture(手动滚动长截图:先经 region_selector 选目标窗口,自带 GDI 采集层连续抓帧 + 行指纹在线拼接 + Enter 保存;配置 max_height;Windows P1) | ✅ 可用(Windows):0.1.0 作为实验特性随包分发、默认在插件列表里禁用(plugins.disabled),在设置页勾选启用后重启生效;真机已验证完整交互(选窗口 → 滚动 → HUD → 保存),只在保存时发一条 capture.done;见 document/PLATFORMS.md §3.3 |
主题色(core/theme_color,6 个预设 + 任意取色;区域框选边框/折角读它) | ✅ 可用(document/SETTINGS.md §5/§6) |
| 混合 DPI 多显示器采集(物理虚拟桌面 3584x1600;采集线程 DPI 上下文兜底;负 origin 未实机验证) | ✅ 可用(document/CAPTURE.md §2.1) |
| 设置页 DPI(双屏 150%+100%:跨屏拖动重缩放、几何按目标屏 clamp、不累积;其它 DPI 组合/三屏未验证) | ✅ 可用(document/SETTINGS.md §6.1) |
命令行 --capture(工作线程 + 退出前派发一轮事件)/ --settings / --test-plugin <dll>(插件自检)/ --help | ✅ 可用 |
GitHub Actions 跨平台 CI(Linux/macOS/Windows 矩阵 + vcpkg 缓存 + preset 构建 + --help 冒烟) | ✅ 2026-11-14 的 run 三平台 job 全部通过(Linux 用 ubuntu-24.04);CI 只跑 --help,真实平台状态见「平台」与 document/PLATFORMS.md |
宿主自身设置(core 伪插件:界面语言 / 日志级别 / 控制台 / 文件日志 / 主题色) | ✅ 可用 |
插件元数据贴尾(metadata.json → DLL 尾部,纯 CMake) | ✅ 可用(宿主加载前读取:预筛 + 依赖拓扑排序) |
| 元数据构建期校验(id 唯一 / interfaces 已注册 / abi 与头一致 / 依赖语法) | ✅ 可用(cmake/ValidatePluginMeta.cmake) |
插件级依赖声明(requires / provides,带版本区间,core 为宿主) | ✅ 可用(document/METADATA.md) |
| 依赖驱动加载顺序(拓扑排序,不满足只跳过该插件) | ✅ 可用 |
插件工程公共构建规则(shot_add_plugin()) | ✅ 可用(宿主与离线 SDK 共用) |
多语言 i18n(core/language = auto 或语言目录 tag;i18n_source_list 插件贡献 + 宿主合并生成只读 i18n_list;外部语言包 files/lang/ 与 %LOCALAPPDATA%\plugin-shot\langs\;设置页/托盘按 display(owner,key) ?? key 解析,旧插件字面量零破坏) | ✅ 可用(document/I18N.md;内置 27 个标签,仓库内置译文仅 zh-CN / en-US;外部语言包协议已就绪、翻译插件 plugins/translator 已加入(默认关);Windows / Linux 真机已验证语言包加载与切换,官方 zh-TW 包界面/托盘跟随;字体动态图集 + Segoe UI/Arial 补字,RTL 与韩/泰/阿拉伯字形未做) |
离线插件 SDK(export_sdk / package_sdk 目标:核心包 + 可选 OpenCV 叠加包,含 manifest、contract_sha256、模板、demo、技能) | ✅ 可用(document/README_SDK.md;发布资产 dist/) |
插件离线自检 --test-plugin <dll>(真实宿主加载路径 + 隔离数据目录 + PASS/FAIL/SKIP JSON) | ✅ 可用(document/PLUGIN_TEST.md;Windows 真机验证,Linux WSL 验证) |
插件开发文档与"一句话写插件"技能(document/AUTHORING.md、skills/plugin-shot-dev/、DSH bundle dsh-plugin-shot-dev/) | ✅ 可用(两个 demo:截图时间水印 / 按日期归档) |
产物名取自
CMakeLists.txt的PROJECT_NAME(当前Plugin-shot):宿主叫Plugin-shot.exe, 插件落bin/plugins/。应用图标缺失时.rc会自动降级成不含 ICON 行,所以改名不会把构建搞挂。
目录结构
.
├── CMakeLists.txt # 跨平台构建脚本(vcpkg 清单模式 + GLOB 自动发现插件)
├── CMakePresets.json # debug / release 两个 preset(CI 与跨平台构建用同一套)
├── vcpkg.json # 依赖清单
├── vcpkg-configuration.json# vcpkg builtin-baseline
├── .github/
│ └── workflows/cmake.yml # 跨平台 CI(Linux/macOS/Windows)
├── files/
│ └── lang/ # 随安装包分发的官方语言包(<tag>.json;构建同步到 bin/files/)
├── include/
│ ├── plugin_api.h # ★ 宿主 ⇄ 插件的 ABI 契约汇总头(只 include;跨边界入口仍是它)
│ ├── plugin_api/ # ★ 契约正文:按主题一个子头(basics / interfaces / 各能力 /
│ │ # host_services / module / abi_layout)
│ ├── plugin_api_export.h # 导出宏:插件默认 dllexport,宿主定义 SCREENSHOT_HOST_EXPORTS
│ ├── shot_plugin_helpers.h # 插件侧工具汇总头(只 include,不声明类)
│ ├── shot_plugin_helpers/ # 每类一个头文件:iface_entry / logger / config /
│ │ # event_bus / plugin_lists / plugin_registry
│ ├── dllHandler.h # LoadLibrary / dlopen 封装(含不抛异常的 tryGetFunction)
│ ├── pluginManager.h # 插件扫描、依赖排序、加载与热卸载(含 Generic 兜底)
│ ├── hostServices.h # 宿主服务表:日志、配置、事件总线、列表服务、插件注册表
│ ├── hostListCatalog.h # 通用列表目录:config_list 生成 + lists.* 事件协议
│ ├── hostRuntime.h # 宿主编排:PluginManager + 列表目录 + 注册表 + 采集流水线 + 生命周期锁
│ ├── capturePipeline.h # 采集流水线:工作线程 + 有界队列 + 区域裁剪
│ ├── config.h # core::Config:JSON 配置文件读写
│ └── PluginInstances/ # 宿主侧插件包装(base / ImageProcessor / LibProvider / ScreenCapture / ImageSaver;Generic 用 base)
├── src/ # 宿主实现与入口
├── plugins/ # 每个子目录都是一个独立插件工程
│ ├── example_processor/ # 完整示例:一个 DLL 两个插件,都带配置项(依赖 OpenCV)
│ ├── opencv_provider/ # 合法但零能力的插件包(把 OpenCV 带进进程)
│ ├── screen_capture/ # 屏幕采集:Windows GDI 物理像素;Linux Wayland portal + PipeWire / X11 XShmGetImage(均已真机验证,Linux 单显示器)
│ ├── image_saver/ # 图像保存:PNG/JPEG,目录/格式/质量/文件名可配置
│ ├── clipboard/ # 剪贴板:capture.done → CF_DIB / CF_HDROP(Windows);Linux 走 X11 selection(X11 直连 / Wayland 经 XWayland,已验证)
│ ├── notify/ # 截屏结果通知:Windows Shell 气泡;Linux 用 libnotify(Linux 已验证)
│ ├── hotkey/ # 列表驱动全局热键 provider(Windows RegisterHotKey;Linux X11 XGrabKey 已验证,纯 Wayland 降级不注册)
│ ├── session_control/ # Linux D-Bus 控制入口:Wayland 下代替全局热键(仅 Linux,D-Bus 触发已验证)
│ ├── region_selector/ # 区域框选覆盖层:悬停窗口吸附、单击截窗、四角主题色折角(Windows;Wayland 门户定格图 + 拖选;X11 GLFW 覆盖层,均已验证,Linux 单显示器)
│ ├── long_capture/ # 长截图:选窗口后连续抓帧 + 行指纹拼接(Windows P1,真机完整交互已验证)
│ ├── settings_ui/ # 设置页:ImGui + GLFW + OpenGL3(跨平台,Windows / Linux 已验证)
│ ├── translator/ # 外部语言包:扫描官方/用户目录,贡献 i18n_source_list(跨平台代码,Windows / Linux 已验证)
│ └── tray/ # 托盘入口:数据驱动菜单 + 图标(Windows 托盘 + Linux SNI;Linux 已验证)
├── document/
│ ├── AUTHORING.md # ★ 插件开发单一事实源:从零到安装(离线 SDK,不需要宿主源码)
│ ├── PLUGIN_TEST.md # `--test-plugin` 自检:检查项、JSON、退出码、局限
│ ├── README_SDK.md # 离线 SDK:两个包、目录、构建、ABI、自检、故障排查
│ ├── SDK_DOCS.md # 仓库文档 → SDK 内文档的映射与防漂移
│ ├── PLATFORMS.md # 跨平台能力矩阵:每插件状态、平台限制、缺口与 CI 现状
│ ├── ABI_POLICY.md # 只追加规则、interface id 登记表
│ ├── SETTINGS.md # 设置页:config_list、事件驱动写值/提交、Generic、DPI、插件启停与热卸载
│ ├── LISTS.md # 通用列表与事件驱动:list id 登记、lists.* 协议与刷新时机
│ ├── CAPTURE.md # 采集流水线:工作线程、区域截图、capture.* 事件与 --capture
│ ├── EVENT_BUS.md # 宿主事件总线:主题约定、线程模型、生命周期
│ ├── I18N.md # 多语言协议:语言目录、外部语言包、两个 i18n 列表、回退链、字体与限制
│ └── METADATA.md # metadata.json 的字段定义、权威规则与不写什么
├── cmake/
│ ├── ShotPlugin.cmake # shot_add_plugin():插件工程公共构建规则(宿主与 SDK 共用,含 SDK 模式)
│ ├── AppendPluginMeta.cmake # 把 metadata.json 贴到 DLL 尾部
│ ├── prune_output_dir.cmake # 产物目录剪枝(不留 pdb/ilk/exp/lib/基础依赖 DLL)
│ ├── export_sdk.cmake # 导出核心 SDK + 可选 OpenCV 叠加包(含 manifest)
│ ├── package_sdk.cmake # 把 SDK 打成 zip + sha256(两个发布资产)
│ └── ... # 运行时依赖布局、链接前杀进程
├── tools/
│ ├── verify/ # 真机验证:带构建锁的 build 包装 + capture/settings/热键/剪贴板/自检 e2e
│ ├── plugin_sdk/ # SDK 模板(generic/image_processor/image_saver/lib_provider)、
│ │ # 两个一句话 demo(watermark/archive)、new_plugin.cmake 脚手架、第三方许可证
│ └── package/ # 宿主便携包打包脚本(dist/)
├── skills/plugin-shot-dev/ # DSH 技能:下载 SDK → 写插件 → 编译 → 自检 → 安装(SKILL.md + references)
├── dsh-plugin-shot-dev/ # 可安装到 DeepSeek Harness 的插件 bundle(携带上面那份技能)
└── sdk/ # export_sdk 生成的离线 SDK(不入库,见 .gitignore;含 opencv/ 叠加包)
## 构建
前置:CMake ≥ 3.20(直接用 `CMakePresets.json` 时需 ≥ 3.21)、支持 C++23 的编译器(Windows 上为 MSVC)、[vcpkg](https://github.com/microsoft/vcpkg)。
```bash
# 工具链优先读 $VCPKG_ROOT / $VCPKG_INSTALLATION_ROOT,都没有则回落到 /opt/vcpkg
export VCPKG_ROOT=/path/to/vcpkg # Windows: set VCPKG_ROOT=D:\vcpkg
cmake -S . -B build/Windows -DCMAKE_BUILD_TYPE=Debug
cmake --build build/Windows
# 导出离线 SDK(供第三方插件在不装 OpenCV 的机器上编译)
cmake --build build/Windows --target export_sdk
# 也可以用 CMake preset(CI 与跨平台构建走同一套;产物在 build/<platform>/)
cmake --preset release -DVCPKG_TARGET_TRIPLET=x64-linux # triplet 按平台填
cmake --build --preset release
Windows 本机还把 vcvars + cmake 包成了便利脚本:bash tools/verify/build.sh(带构建锁,
多终端 / 多 agent 共用构建目录时串行;--target <t> 只构建一个 target)。真机 e2e 冒烟
脚本与运行纪律见 tools/verify/README.md。
可选开关 -DSHOT_ENABLE_OPENCV=OFF 跳过依赖 OpenCV 的插件(opencv_provider /
example_processor),用于 CI 提速或没有 OpenCV 的环境;默认 ON。
首次 configure 会以清单模式自动安装依赖(opencv4 + jpeg/png/tiff/webp 特性、nlohmann-json、
spdlog、glfw3、nativefiledialog-extended、stb,以及设置页插件用的 imgui——
静态库,glfw-binding + opengl3-binding),耗时较长。设置页的运行期依赖 glfw3.dll、
nfd.dll 与 OpenCV 一样由 cmake/copy_runtime_deps.cmake 从 vcpkg 运行时目录布置到 bin/,
插件目录不含这些 DLL。通用列表协议不引入新依赖:列表快照就是 nlohmann-json 序列化的 JSON。
新增插件也没有引入新的 vcpkg 依赖:clipboard 复用 stb / nlohmann-json,notify 只用
user32 / shell32,hotkey 只用 user32,region_selector 复用 imgui / glfw3 /
nlohmann-json。session_control 与 tray 的 Linux 后端都只要系统 gio-2.0 开发包
(Ubuntu:libglib2.0-dev,走 pkg-config),long_capture 复用 stb / nlohmann-json。
Linux X11 分支用的是系统 X11 开发包(libx11-dev / libxext-dev / libxfixes-dev /
libxrandr-dev / 可选 libxcomposite-dev,见「平台」),同样不是 vcpkg 依赖。Linux 侧已用 WSL Ubuntu
24.04 编译通过,Windows 侧全量构建 exit 0。
CI:.github/workflows/cmake.yml 已就绪(Linux / macOS / Windows 矩阵 + vcpkg 清单缓存 +
CMake preset 构建 + --help 无头冒烟)。2026-11-14 的 run 三个 job 全部通过(Linux 用
ubuntu-24.04);CI 只证明构建与 --help 冒烟,不代表真实桌面可用。逐条结论见
document/PLATFORMS.md §4。
跨平台可编译性现状:Linux 已在 WSL2 实测(Ubuntu 24.04.5 LTS / GCC 13.3.0 / x86_64 /
vcpkg x64-linux / CMake 3.28.3 / Ninja 1.11.1 / Release):configure + build 通过
(0 warning),产出 build/Linux/bin/Plugin-shot 与 12 个 .so(13 个插件工程除去仅 Windows
的 long_capture;含 Linux 实现的
screen_capture / region_selector / session_control / clipboard / notify / tray,
以及带 X11 分支的 hotkey);--help 退出码 0。真机验证:Ubuntu 24.04(X11)与
Ubuntu 26(Wayland)上都已跑通核心链路——整屏截图、区域框选(Wayland 门户定格图 / X11 覆盖层)、
热键(X11 XGrabKey)、D-Bus 触发(Wayland)、剪贴板、通知、设置页、语言包与托盘;均为单显示器
环境,X11 多显示器 / 多 X screen / 负坐标尚未验证。SHOT_ENABLE_OPENCV=OFF 也实测通过。
macOS 未在真机验证(只做过代码审计)。Windows 是主要开发与验证平台,全量构建 exit 0,
8 个 e2e/冒烟脚本全绿(见「平台」)。
Linux 产物需按目标发行版构建(glibc 版本约束):.so 链接的是构建机上的 glibc 与系统库,
不能跨发行版共用。本仓库 build/Linux 当前由 WSL Ubuntu 24.04(glibc 2.39)构建,产物最高只
要求 GLIBC_2.38,可在 Ubuntu 24 / 26 上运行;在 Ubuntu 26 构建的产物会要求 GLIBC_2.43,
拷回 Ubuntu 24 会在 dlopen 阶段失败。不要跨发行版共用同一个 build/Linux 目录,也不要把新
发行版构建的 .so 拷回旧发行版。
Linux 的分步编译手册(依赖包、vcpkg、Wayland/X11 差异、运行、安装与排错)见
document/BUILD_LINUX.md。
运行
cd build/Windows/bin && ./Plugin-shot.exe # 不带参数:托盘常驻
cd build/Windows/bin && ./Plugin-shot.exe --capture # 截一张、打印路径后退出
cd build/Windows/bin && ./Plugin-shot.exe --settings # 打开设置页后继续常驻(调试入口)
cd build/Windows/bin && ./Plugin-shot.exe --test-plugin plugins/clipboard.dll --json-out report.json # 插件自检
cd build/Windows/bin && ./Plugin-shot.exe --help # 打印用法
插件目录按相对路径 ./plugins 解析,因此必须在 bin/ 下启动。
控制台行为:Release 构建为窗口子系统,双击 Plugin-shot.exe 启动时不弹控制台窗口;
Debug 构建保留控制台子系统(方便在终端看日志与断点调试)。Release 从终端带参数运行
(--capture / --test-plugin / --help / --settings)时,宿主会
AttachConsole(ATTACH_PARENT_PROCESS) 附着父控制台,命令行输出照常可见;双击无参数常驻则
完全无窗口。
不带参数启动后宿主不会主动打开设置页(托盘正常时):托盘菜单「截屏 / 区域截屏 / 打开设置 /
退出」分别发布 capture.request(空负载)/ capture.request(负载
{"mode":"region"})/ settings.open / app.quit;「区域截屏」由
plugins/region_selector 弹出框选覆盖层,用户确认后它再发一条带 region 的请求,宿主按
物理虚拟桌面像素裁剪(见 document/CAPTURE.md §3.1)。框选触发请求本身不会采集
(流水线直接忽略,不落盘,不会再额外存一张全屏图)。若 tray.main 未加载(被禁用或
加载失败),启动会自动发布 settings.open 兜底。
截图默认保存到 %USERPROFILE%\Pictures,文件名模板 shot_%Y%m%d_%H%M%S、默认 PNG;
目录/格式/质量/文件名都是 plugins/image_saver 的配置项,可在设置页修改。截屏结果由
plugins/notify 弹系统通知、plugins/clipboard 把图片写进系统剪贴板(两者都可在设置页
开关);plugins/hotkey 是列表驱动的热键 provider:默认用 Ctrl+Alt+S / Ctrl+Alt+A /
Ctrl+Alt+O 触发同样的截屏 / 区域截屏 / 打开设置,插件(包括它自己)通过贡献型列表
hotkey_list 声明"组合键 → 事件",加一个热键只需贡献一条条目、不用自己注册;全部热键可在
设置页改(热键项用「录入…」按一次组合键录入,不用手输字符串)。X11 会话下 hotkey 用 XGrabKey
注册(Ubuntu 24.04 真机已验证);纯 Wayland 没有全局热键 API,hotkey 保留列表与配置项但不注册
(运行期降级),改用 plugins/session_control 的 D-Bus 入口 / 桌面自定义快捷键(D-Bus 触发已在
Ubuntu 26 真机验证)。
--capture 成功时日志打印 Capture saved: <path>、退出码 0;失败(采集/保存/插件缺失/
请求队列满)退出码 1,未知参数 2。一次性模式在退出前会派发一轮事件,所以剪贴板/
通知这类订阅者同样能收到本次 capture.done(详见 document/CAPTURE.md §6)。
--test-plugin <dll> 是插件自检模式:它用真实的插件加载/校验路径(HostRuntime)把被测
DLL 装进一个隔离数据目录(不读写用户配置与日志),跑加载、能力、配置、列表/i18n 与事件检查,
输出 PASS/FAIL/SKIP 与可选 JSON,退出码 0/1/2。插件作者不需要构建整个宿主、也不需要
先装进 plugins/ 就能验收(详见 document/PLUGIN_TEST.md)。
日志用 spdlog:控制台 +
%LOCALAPPDATA%\plugin-shot\logs\host.log(追加写);配置写在
%LOCALAPPDATA%\plugin-shot\config.json(宿主设置与插件配置项都在这里,键是 <owner>/<id>,
与 config_list 条目的 owner / id 一一对应)。
多显示器与 DPI
| 项 | 现状 |
|---|---|
| 宿主 DPI 感知 | 启动最早阶段显式声明 per-monitor v2(SetProcessDpiAwarenessContext,逐级回退 SetProcessDpiAwareness / SetProcessDPIAware,全失败只 warn);日志行 DPI awareness: <模式> |
| 多显示器采集 | 虚拟桌面物理像素,本机混合 DPI 双屏(150% 2560x1600 + 100% 1024x768)实测 3584x1600;负 origin(副屏在左/上)未实机验证 |
| 采集线程 DPI | plugins/screen_capture 每次 describe/capture 临时提升调用线程到 PMv2、返回前恢复,不依赖宿主进程声明 |
| 设置页 DPI | 双屏 150%+100% 已验证:跨屏拖动自动重缩放(不累积)、几何恢复按目标显示器 DPI clamp(含标题栏/边框);其它 DPI 组合(125% / 200%)、三屏及以上、负 origin 未验证 |
| 区域坐标 | 物理虚拟桌面像素,原点 = 虚拟桌面左上角;越界夹取(详见 document/CAPTURE.md §3.1) |
产物布局(硬约束)
| 路径 | 内容 |
|---|---|
bin/ | 宿主 exe 与本配置的运行时依赖 DLL(禁止出现 *.pdb / *.ilk) |
bin/plugins/ | 只放插件自身产物(禁止出现 OpenCV 等基础依赖) |
build/<platform>/pdb/ | 全部调试符号 |
sdk/ | 离线 SDK:include/、lib/(release)、lib/debug/、bin/、bin/debug/ |
这些约束由 cmake/copy_runtime_deps.cmake 与 cmake/prune_output_dir.cmake 在构建期强制。
插件产物的扩展名随平台:Windows .dll、macOS .dylib、Linux .so;非 Windows 不复制运行库,
由 RPATH 指向 vcpkg 的 lib/。
理由见下文契约第 3 条:插件一旦自带 OpenCV,同一进程就会出现两份实例。
插件契约
跨边界的入口头只有一个:include/plugin_api.h(纯 C,不依赖 STL)。它只是汇总头,
正文按主题拆在 include/plugin_api/*.h(版本与读取规则、interface id、每个能力一张表、
宿主服务、ShotModule、布局锚点)——插件源码照旧只写 #include "plugin_api.h"。
整个插件包只导出一个 C 函数:
SCREENSHOT_API const ShotModule* shot_module_entry(void);
它返回一张自描述的模块表 ShotModule,其余一切都在表里:
| 字段 | 作用 |
|---|---|
struct_size / abi_major / abi_minor | 自描述长度 + 版本:宿主先看长度再读字段,然后比对 major |
plugin_count | 本 DLL 里有几个插件 |
get_info(index, info) | 不创建实例就能拿到 id / 名称 / 版本 |
create(index, host) | 在插件自己的堆上分配实例,返回不透明指针 |
destroy(instance) | 销毁实例——只能由插件自己调用,宿主绝不 delete |
query_interface(instance, id, version) | 问"你会不会这个能力" |
init(host, flags) / shutdown() | 可选:模块级初始化与收尾,nullptr 表示不需要 |
一个 DLL 就是一个插件包:plugin_count + create(index) 让宿主不必提前知道包里有什么,
metadata.json 的 plugins[] 顺序与索引一一对应。
四条让 ABI 不必再改的规则
- 只加字段,不加符号:整个包只有
shot_module_entry一个导出。加能力靠往结构体末尾追加字段,不是加导出函数。 - 读字段前先问长度:每个跨边界结构体第一个字段都是
struct_size,读取方一律先过SHOT_HAS_FIELD(ptr, type, field)。于是老插件(短结构)与新宿主(想读新字段)能安全共存——加字段永远不需要改版本号。 - 能力用字符串 id 问:
query_interface(instance, "shot.image_processor", 1)返回函数表,没有就返回NULL,宿主安静跳过。新增一类能力 = 新增一个 id + 一个结构体,不动任何已有结构体。 - 数据形状不进 ABI:新增一类 UI/宿主数据(菜单项、配置项、目标列表……)= 新 list id + JSON schema +
lists.*事件;ABI 只描述能力与行为,不描述数据结构,见document/LISTS.md。
include/plugin_api/abi_layout.h 用 static_assert 钉住了每个结构体的字段偏移与总大小
(汇总头里最后 include 它):重排或改类型会直接编译失败,而"追加字段"必须手动更新那一行——
把破坏 ABI 变成一次有意识的行为。
已注册的能力
| interface id | 结构体 | 作用 |
|---|---|---|
shot.image_processor | ShotImageProcessorV1 | 处理一张图:process(self, ShotImage*),返回 0 表示成功 |
shot.screen_capture | ShotScreenCaptureV1 | 屏幕采集:describe 报告虚拟桌面几何(物理像素,多显示器合成),capture 把 BGRA8 像素写进宿主分配的 ShotImage;区域截图由宿主抓整屏后按 region 裁剪,见 document/CAPTURE.md |
shot.image_saver | ShotImageSaverV1 | 图像保存:把 ShotImage 落盘并写回最终路径;格式/质量/目录来自插件配置项,见 document/CAPTURE.md |
shot.configurable | ShotConfigurableV1 | 声明并读写配置项,见下 |
shot.lib_provider | ShotLibProviderV1 | 声明"我是运行库提供者",报告库名与版本;宿主按 PluginType::Lib 登记 |
shot.ui_provider | ShotUIProviderV1 | 窗口/托盘由插件自己创建,宿主只调 init / deinit / post_to_plugin |
shot.host.event_bus | ShotHostEventBusV1 | 宿主服务:进程内主题发布/订阅 |
shot.host.config | ShotHostConfigV1 | 宿主服务:宿主配置读写(旧接口;新代码用 plugin_lists 的 config_list) |
shot.host.board_msg | ShotHostBoardEventV1 | 宿主服务:旧版广播队列(新代码用 event_bus) |
shot.host.plugin_lists | ShotHostPluginListsV1 | 宿主服务:通用列表,按 list id 返回只读 JSON 快照(config_list / tray_command_list / hotkey_list),见 document/LISTS.md |
shot.host.plugin_registry | ShotHostPluginRegistryV1 | 宿主服务:已安装插件状态与异步启停 |
当前契约版本 SHOT_ABI_MAJOR = 2 / SHOT_ABI_MINOR = 0:2.0 删除了旧的配置目录服务,
改为通用列表服务 shot.host.plugin_lists(列表数据是 JSON 快照,注册/写值/提交全部走
lists.* 事件)。删除已发布的服务属于破坏性变更,所以 major 涨到 2;
从 2.0 起,新增一种 UI/宿主数据不再改 ABI:新 list id + JSON schema 即可。
shot.screen_capture / shot.image_processor / shot.image_saver 的能力回调在采集流水线的
工作线程上执行(一次一张、串行),shot.configurable 的 set_config 仍在 main 线程。
插件如果让能力回调与配置共享状态,必须自己做同步(线程模型见 document/CAPTURE.md §7)。
纯订阅者 / 纯配置项插件(Generic)
插件也可以不实现任何宿主可调用的具名能力:只声明 shot.configurable,在
create(index, host) 里订阅事件、在 destroy 里退订。只要 metadata 声明过它,宿主就按
PluginType::Generic 用基类包装加载:注册表照常列 LOADED、可启停、config_list 照常
枚举它的配置项;没有 metadata 又认不出任何具名能力的包会被跳过。完整写法和约束见
document/README_SDK.md,现成例子是
plugins/clipboard/README.md 与
plugins/notify/README.md。
ShotImage 描述一块 8 位像素缓冲:
pixel_format显式声明布局(当前只有SHOT_PIXEL_FORMAT_BGRA8),不再靠channels猜stride以字节计,可以为负(自底向上存储),也可大于width * channels(行尾填充)- 所以必须按行寻址,不能假设
data是连续块
配置:插件声明,宿主渲染与存盘
shot.configurable 让插件自己说清"我有哪些配置项",宿主据此生成界面、保存文件、灌值——
宿主不硬编码任何配置项名字:
typedef struct ShotConfigurableV1 {
uint32_t struct_size;
uint32_t version;
uint32_t (*get_config_count)(void* self);
int32_t (*get_config_desc)(void* self, uint32_t index, ShotConfigDesc* out);
int32_t (*get_config)(void* self, const char* key, char* buf, uint32_t buf_size);
int32_t (*set_config)(void* self, const char* key, const char* value);
} ShotConfigurableV1;
- 配置项由
ShotConfigDesc描述:kind(BOOL / INT / FLOAT / STRING / ENUM / COLOR / PATH)、key、显示名、默认值、取值范围、枚举候选。 - 值一律是字符串:跨边界没有宽度与对齐问题,天然可以存成 JSON,插件也不必为读配置引入 STL。
- 插件遇到不认识的
key必须安全忽略(返回负值)——宿主升级后多传一项,老插件也不会出问题。 - 约定:
set_config可能在运行中被调用(用户拖滑块),实现要么线程安全,要么声明"下次process生效"。
宿主的设置也走同一套描述符:宿主内部以 core 伪插件实现 shot.configurable(日志级别、
控制台/文件日志开关),宿主把所有可配置实例聚成 config_list JSON 快照,设置页只写一套
渲染逻辑。
- 存盘键是
<owner>/<id>,值由宿主落盘到%LOCALAPPDATA%\plugin-shot\config.json; 插件只负责 get/set,不需要自己写配置文件。 - 启动时宿主把已存值灌回插件(没有已存值就用
default_value),插件不需要"读配置"这一步。 - 写值走
lists.update(事件驱动、逐项回结果),落盘走lists.commit;成功后宿主发布既有config.applied(空负载):缓存了派生状态的插件重读当前值即可,没有单独的 reload 调用。 - 输出/保存相关的设置不归宿主:谁实现保存能力,谁在自己的
kConfig[]里声明这些项。
列表:新数据形状不进 ABI:config_list 与托盘菜单的 tray_command_list 来自同一个
通用列表服务。插件要给 UI 提供一批新数据(菜单项、目标列表……)时,定义新 list id + JSON
schema,运行期用 lists.add 注册、宿主用 lists.changed 通知;不要为数据形状新增 ABI
结构体或宿主服务。完整协议、list id 登记表与性能约定见 document/LISTS.md。
完整链路(config_list、设置页插件、插件启停与热卸载)见 document/SETTINGS.md。
设置页与插件启停
设置窗口本身也是插件(plugins/settings_ui,实现 shot.ui_provider),宿主没有主窗口:
- 设置页通过
shot.host.plugin_lists读config_listJSON 快照,按条目 schema 渲染 7 种控件 (BOOL / INT / FLOAT / STRING / ENUM / COLOR / PATH);写值走lists.update、落盘走lists.commit(带tag的事件往返,逐项结果回lists.updated/config.applied); 窗口的 DPI / 多屏行为见「多显示器与 DPI」与document/SETTINGS.md§6.1; - 通过
shot.host.plugin_registry管理插件启停。禁用是热卸载:销毁实例、UI 插件先host.shutdown+deinit、退订事件总线,同包最后一个实例卸载后FreeLibrary; 重新启用则重新加载 DLL 并回灌已存配置。被其他已加载插件requires的插件不允许单独禁用; - 启用会级联启用依赖:启用一个插件时,宿主先递归启用它
requires的提供者;提供者 启用失败则整条启用失败,原因里写明是哪个依赖; - 托盘
plugins/tray可以禁用/重新启用:右键菜单内容来自tray_command_list(宿主预置 core 四项:截屏 / 区域截屏 / 打开设置 / 退出;插件用lists.add贡献),点击菜单项 只发布条目声明的事件;图标默认取宿主 exe 的命名资源IDI_ICON1,可用icon配置换成 任意.ico。托盘不再弹任何气泡:成功/失败提示全部由plugins/notify负责;tray.main未加载(被禁用或加载失败)时,常驻启动会自动发布settings.open,以设置页作为 入口兜底; - 其它插件也走同一套生命周期与配置链路:
plugins/notify(截屏结果通知)、plugins/clipboard(写系统剪贴板)、plugins/hotkey(列表驱动的全局热键 provider: 功能插件贡献hotkey_list条目,它只负责注册并发布条目事件)、plugins/region_selector(框选后发布带region的capture.request)——它们都只通过 事件/配置与宿主协作,不直接调用其它插件,设置页会按config_list自动出现它们的配置节; - 启停请求是异步的:设置页只登记,宿主 main 线程执行完才发布
plugins.changed;一次启用 可能级联多个依赖,所以设置页可能连续收到多条plugins.changed。
必须遵守的 ABI 约定
-
运行库必须是 /MD(
MultiThreadedDLL),宿主与插件一致;/MT会得到两份 CRT。 -
Debug/Release 必须与宿主一致——Debug 插件只能加载进 Debug 宿主。
-
插件不得自带基础依赖(
opencv_*.dll等):宿主 exe 旁边的bin/里已经有一套,插件目录里再放一份会让同一进程出现两个 OpenCV,类型信息、全局状态与内存分配器全部割裂。宿主本身不链接 OpenCV(
CMakeLists.txt只链接nlohmann_json与spdlog)。bin/里的opencv_*.dll来自cmake/copy_runtime_deps.cmake对 vcpkg 运行时目录的整目录布置, 不是链接拉进来的。需要 OpenCV 的插件在自己的CMakeLists.txt里find_package(OpenCV QUIET)并链接(见plugins/opencv_provider), 运行时从bin/里那一份解析到同一个 DLL。 -
跨边界不要传 STL 容器 /
std::string/cv::Mat,也不要传带虚函数的 C++ 对象:跨边界只有 POD 结构体 + 函数指针。 -
只用定宽类型(
uint32_t/int32_t/double),不用int/long/size_t;枚举不进结构体,改用定宽常量。 -
异常绝不跨越 DLL 边界:每个
extern "C"函数内部自行兜底,错误用返回值表达。 -
abi_major必须与宿主一致;只追加能力时提高abi_minor即可,宿主接受 minor ≤ 自己的插件。 -
结构体只能末尾追加:永不重排、永不改类型、永不删,作废字段改名
retired_xxx占位。
元数据贴尾
metadata.json 由 cmake/AppendPluginMeta.cmake 在链接之后追加到 DLL 尾部:
<原始二进制>
---PLUGIN_META_START---
{ "schema": 1, "abi": { ... }, "plugins": [ ... ] }
---PLUGIN_META_END---
- 纯文本标记,不需要 Python、不需要贴尾小工具,宿主
rfind就能取出来。 - 文件尾的额外数据不在 PE/ELF 的节表里,加载器直接忽略,不影响装载。
- 元数据跟着文件走:用户复制或重命名插件也不会出现「清单与 DLL 分家」。
- 标记字面量只在
plugin_api/plugin_info.h里定义一次;构建脚本构建期把汇总头 + 全部子头 拼成整份文本再取宏值(cmake/ReadContractHeader.cmake)。 - 贴尾之前会先校验:
plugins[]非空、id唯一、interfaces里的 id 在契约头里有定义、abi与SHOT_ABI_*一致、package与目标名一致。写错就构建失败,不用等宿主发现。 - 字段定义、权威规则(谁是权威、为什么不写配置项、依赖怎么解析)见
document/METADATA.md。 - 依赖是插件级的:
"requires": ["core>=0.1.0", "opencv>=4.12"],core指宿主自己的版本 (来自 CMake 生成的version.h)。宿主先读所有 DLL 的元数据建依赖图,拓扑排序后加载, 不满足的插件只跳过它自己,同包其它插件和整个宿主继续工作。
写一个插件
一个插件一个 .cpp:状态、process、可选的配置读写,最后组装能力函数表:
// plugins/acme_tools/src/blur.cpp
static int32_t blur_process(void* self, ShotImage* image) {
auto* state = static_cast<BlurState*>(state_of(self)); // 注意:self 是不透明指针
// … 按行处理 image …
return 0; // 0 = 成功
}
const ShotImageProcessorV1 kImageOps =
SHOT_OPS(ShotImageProcessorV1, .process = &blur_process);
const ShotIfaceEntry kIfaces[] = { // 能力目录
{ SHOT_IFACE_IMAGE_PROCESSOR, 1, &kImageOps },
{ nullptr, 0, nullptr }, // 结束标记
};
plugin_entry.cpp 只做三件事:把各插件登记成 kEntries[]、转发 query_interface、返回模块表:
extern "C" {
SCREENSHOT_API const ShotModule* shot_module_entry(void) {
static const ShotModule module = {
.struct_size = sizeof(ShotModule),
.abi_major = SHOT_ABI_MAJOR,
.abi_minor = SHOT_ABI_MINOR,
.plugin_count = kEntryCount,
.get_info = &get_info,
.create = &create_instance,
.destroy = &destroy_instance,
.query_interface = &query_instance, // 转发 shot_query_interface(ifaces, id, ver)
};
return &module;
}
}
完整可编译样板见 plugins/example_processor/:一个 DLL 装两个插件、
都带配置项,目录结构 CMakeLists.txt + metadata.json + include/ + src/。
没有宿主源码也能开发:下载离线 SDK(dist/plugin-shot-sdk-<版本>-win64.zip,或 GitHub
Releases 资产),用 SDK 自带的模板与 tools/new_plugin.cmake 生成工程,cmake 构建后用
宿主 --test-plugin 自检,最后把 DLL 放进 plugins/。分步教程:
document/AUTHORING.md;SDK 布局与构建约束:
document/README_SDK.md;自检:
document/PLUGIN_TEST.md。仓库里还有两个"一句话需求"的完整示例:
tools/plugin_sdk/demos/watermark(截图右下角时间水印)与
tools/plugin_sdk/demos/archive(按日期归档),它们与模板
一起随 SDK 分发。用 AI 写插件可安装 DSH 技能/插件包 dsh-plugin-shot-dev/
(技能 plugin-shot-dev,正文在 skills/plugin-shot-dev/)。
插件工程的 CMakeLists 只有三件事——找模块、列源文件、指元数据:
# SDK 工程:cmake -DSHOT_SDK_ROOT=<SDK 根> -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
list(APPEND CMAKE_MODULE_PATH "${SHOT_SDK_ROOT}/cmake")
include(ShotPlugin)
shot_add_plugin(acme_tools
METADATA metadata.json
SOURCES src/plugin_entry.cpp src/blur.cpp src/sharpen.cpp
INCLUDE_DIRS include)
shot_add_plugin() 统一处理 /MD、PREFIX ""、隐藏符号、产物目录、pdb 重定向、
贴元数据与产物剪枝;SDK 模式下还会自动补 third_party/include(nlohmann / stb)与
可选的 opencv/ 叠加包头库路径——同样这些规则以前散落在根 CMakeLists.txt 里,容易和文档漂移。
打包发布物料
# SDK 两个 zip(核心包 + 可选 OpenCV 叠加包)→ dist/
bash tools/verify/build.sh --target package_sdk
# 宿主便携包 → dist/Plugin-shot-<版本>-win64.zip(需要先做 Release 构建)
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package/make_host_package.ps1 -Version 0.1.0
平台
0.1.0 发布口径:预编译包提供 Windows 10/11 x64 宿主 + 离线插件 SDK(核心包与 可选 OpenCV 叠加包);Linux(Ubuntu 24.04 X11 / Ubuntu 26 Wayland,单显示器)核心链路 已真机验证,本版本仍只提供源码构建,不提供 Linux 预编译包/SDK;macOS 未验证。 下面记录的是仓库代码与真机验证状态。
Windows 是主要开发与验证平台(MSVC + vcpkg x64-windows)。Linux 的默认目标是 Wayland
(本轮实测环境:Ubuntu 26 / Wayland 会话),X11 保留为第二优先并已在 Ubuntu 24.04 / X11
会话验证。Linux(单显示器)的核心链路已真机跑通:Ubuntu 24.04(X11)的整屏采集
(Ctrl+Alt+S / D-Bus)、XGrabKey 热键、XComposite 背景快照框选(悬停窗口吸附、顶栏/dock 与
四角吸附、单击截窗、拖框、Esc 取消、保存+剪贴板)、libnotify 通知、剪贴板、设置页、语言包、
D-Bus 触发与托盘;Ubuntu 26(Wayland)的 portal ScreenCast 整屏采集、门户定格图拖选(确认后
覆盖层立即消失、无“应用无响应”、保存+剪贴板)、通知、剪贴板、D-Bus 触发、设置页、语言包与
托盘。平台实现按目标平台在各自 CMakeLists.txt 里选择:screen_capture(Windows GDI /
Linux Wayland portal + PipeWire / Linux X11 XShmGetImage 优先 + XGetImage 回退,XFixes
光标合成)、region_selector(Windows 覆盖层 / Wayland 门户定格图 + 拖选 / X11 GLFW 无边框
覆盖层 + XComposite 背景快照)、clipboard(Windows CF_DIB / Linux X11 selection)、
notify(Windows Shell 通知 / Linux libnotify)、tray(Windows Win32 托盘 / Linux
StatusNotifierItem + com.canonical.dbusmenu)。
long_capture(Win32 前台窗口 + HUD,真机完整交互已验证:选窗口 → 滚动 → HUD → 保存)只在
Windows 构建;session_control 反过来只在 Linux 构建,D-Bus 触发已在 Ubuntu 24 / 26 真机验证。
hotkey 是例外:Windows 编译 RegisterHotKey 实现,Linux 编译 X11 XGrabKey 实现
(已在 Ubuntu 24.04 真机验证);纯 Wayland(取不到 Display)时运行期降级为仍贡献/读取
hotkey_list、暴露动态配置项但不注册全局热键,启动 WARN 指向 session_control;macOS 等其它
平台编 hotkey_window_stub.cpp。跨平台可编译的还有 settings_ui(GLFW)、image_saver、
example_processor、opencv_provider、translator。
仍未验证:X11 多显示器 / 多 X screen / 负坐标;Wayland 窗口悬停(协议不允许,属平台限制); macOS 全部(CI 的 macOS job 已能通过 configure/build,但没有真机运行)。
完整的跨平台能力矩阵(Windows / Wayland / X11 / macOS 每格状态、原因与补齐路径)见
document/PLATFORMS.md;本节只保留构建与验证结论,不要读成
“全平台支持”。
| 平台 | 状态 |
|---|---|
| Windows(MSVC x64) | ✅ 主要开发与验证平台(含双屏混合 DPI、插件启停、采集/保存/通知/剪贴板/热键/区域框选;本轮 8 个 e2e/冒烟脚本全绿);本轮新增确认区域截图悬停窗口/任务栏/屏幕四角吸附与截窗口尺寸、长截图完整交互(选窗口 → 滚动 → HUD → 保存)、通知点击行为与应用名短名、官方 zh-TW 语言包加载;长截图随包分发但默认在插件列表里禁用(实验特性) |
Linux(WSL2 Ubuntu 24.04.5 LTS / GCC 13.3.0 / x86_64 / vcpkg x64-linux) | ✅ 编译通过(构建环境):configure + build 通过(0 warning),产出 Plugin-shot 与 12 个 .so(screen_capture / region_selector / session_control / clipboard / notify / tray(SNI)/ hotkey(含 X11 分支)/ settings_ui / image_saver / example_processor / opencv_provider / translator);--help 退出 0;真机功能验证见下面两行。SHOT_ENABLE_OPENCV=OFF 也通过;产物 glibc 上限见上文 |
| Linux(Wayland,默认目标) | ✅ 已验证(Ubuntu 26 真机,单显示器):portal ScreenCast 整屏截图(含系统授权弹窗);门户定格图 + 自有窗口拖选的 B 方案框选(确认后覆盖层立即消失、无“应用无响应”、保存+剪贴板;隐藏后先 glfwPollEvents、编码在工作线程);session_control 的 D-Bus 触发;剪贴板(经 XWayland 桥接);libnotify 通知;设置页(页签/插件页/枚举多语言);语言包切换;托盘(SNI + dbusmenu,顶栏图标/菜单正常)。剩余:窗口悬停吸附属协议限制(不提供)、多屏 / HiDPI 拼接未实现。见 document/PLATFORMS.md §3.1 |
| Linux(X11,第二优先) | ✅ 已验证(Ubuntu 24.04 真机,单显示器/单 X screen):整屏采集(Ctrl+Alt+S / D-Bus);XGrabKey 热键(Ctrl+Alt+A / Ctrl+Alt+S / Ctrl+Alt+O);框选覆盖层(XComposite 背景快照,不再灰遮罩、覆盖层高于顶栏/dock、悬停窗口吸附、顶栏/dock 与四角吸附=全屏、单击截窗、拖框、Esc 取消、确认后保存+剪贴板);libnotify 通知(标题/正文、应用名正确、点击打开);剪贴板;设置页;语言包;D-Bus 触发;托盘(顶栏图标/菜单)。剩余:多显示器 / 多 X screen / 负坐标未验证。见 document/PLATFORMS.md §3.2 |
| macOS | 未构建、未在真机验证:CI 的 macOS job 已能通过 configure/build(2026-11-14 run),但只有代码审计(base.cpp 的 _NSGetExecutablePath / 空串 UB / HOME 兜底);没有真实构建/运行结论 |
| GitHub Actions | 2026-11-14 的 run 三平台 job 全部通过(见 document/PLATFORMS.md §4);CI 只做 --help 冒烟,不代表平台可用 |
表里的 Linux 结论都来自同一份二进制;X11 与 Wayland 的运行能力差别很大(Wayland 不允许全局 抓屏、全局热键、全局覆盖层),见矩阵的两列。
Linux 构建的宿主侧系统依赖(Ubuntu 24.04 实测):build-essential ninja-build pkg-config、
autoconf autoconf-archive automake libtool libltdl-dev、bison flex gperf、
gettext autopoint python3-venv、nasm yasm、curl zip unzip、
libgl1-mesa-dev libglu1-mesa-dev libegl1-mesa-dev、X11/wayland 开发库
(libx11-dev libxext-dev libxfixes-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxkbcommon-dev libwayland-dev)、libselinux1-dev libpam0g-dev。nativefiledialog-extended
在 Linux 走 vcpkg 的 NFD_PORTAL=ON,不需要系统 GTK3/dbus 开发包。
按能力分开的系统依赖(session_control 与 Linux 托盘要 libglib2.0-dev;Wayland 采集/框选要 libportal-dev +
libpipewire-0.3-dev + libspa-0.2-dev;Linux 通知要 libnotify-dev;X11 采集要 libx11-dev +
libxext-dev + libxfixes-dev + libxrandr-dev,X11 热键/框选/剪贴板要 libx11-dev)
与“现在是否已装”的完整清单见 document/PLATFORMS.md §4.1。本机 WSL
已装齐这些包、Linux 构建通过;CI 的 apt 步骤也已包含这些包(X11 组见当前 workflow 的 apt 段,
更早一轮见 fc2d69e),最近可见 run 的失败点在 vcpkg baseline,修复后未复跑。
许可
Plugin-shot 以 Apache License 2.0 发布,Copyright 2026 Plugin-shot contributors。
发行包内还包含第三方组件的许可证:见 NOTICE 与包内的 THIRD_PARTY_LICENSES/。
参与
- 构建、验证、本机环境与已经踩过的坑:AGENTS.md
- 代码风格与工程约定:STYLE.md
- 插件契约与设计文档:document/
- 问题与建议:Issues
- 更新日志:CHANGELOG.md