内容
English | [中文](./README.zh-CN.md)
# 工具列表
[](https://nereafantasia.github.io/foo_ui_webview2/)
[](LICENSE)
[](https://www.npmjs.com/package/foo-webview-sdk)
[](https://www.npmjs.com/package/foo-ui-webview2-mcp)
<!-- CI / CodeQL badges return 404 while the repository is private; enable when it becomes public:
[](https://github.com/NereaFantasia/foo_ui_webview2/actions/workflows/ci.yml)
[](https://github.com/NereaFantasia/foo_ui_webview2/actions/workflows/codeql.yml)
-->
<!-- DeepWiki (enable after the repo is indexed): [](https://deepwiki.com/NereaFantasia/foo_ui_webview2) -->
**文档**: https://nereafantasia.github.io/foo_ui_webview2/ <!-- TODO: englishify the documentation site (currently Chinese-only) -->
基于 WebView2 的现代化 UI 组件，用于 foobar2000（C++ DLL）。它将整个 foobar2000 窗口转换为 WebView2 画布，让您可以使用现代 Web 技术构建界面，同时保持原生 Windows 11 视觉效果（Mica/Acrylic）。
- 版本：1.9.0
- 许可证：GPL-3.0-or-later（主要组件）/ MIT（`sdk/`）
---
## 功能
- 完整的 WebView2 UI — 整个客户端区域由 WebView2 渲染
- 原生 Windows 11 效果 — Mica / Acrylic / 标签页背景
- 扩展标题栏到客户端区域 — 自定义标题栏内容，Snap Layout 支持
- 双向 C++ / JS 桥接（BridgeCore）
- 20 多个命名空间的 200 多个 API
- 插件扩展系统（PluginRegistry）
- Web 组件库（fb-* 元素）
- SMP 兼容层
- MCP 服务器 — 通过 CDP 进行 AI 代理集成
- DUI / CUI 面板支持
---
## 技术栈
| 层 | 技术 |
|----|------|
| C++ 组件 | C++20, VS 2022 (v145), Windows SDK 10.0 |
| WebView2 | Microsoft.Web.WebView2 1.0.3719.77 (NuGet) |
| WIL | Microsoft.Windows.ImplementationLibrary 1.0.240803.1 |
| JSON | nlohmann/json |
| foobar2000 | SDK v2.0+ (lib/) |
| Columns UI | SDK （git 子模块：lib/columns_ui-sdk） |
| TypeScript SDK | foo-webview-sdk （sdk/，MIT，tsup） |
| MCP 服务器 | foo-ui-webview2-mcp （mcp/，Node.js 18+） |
---
## npm 包
以下两个 JavaScript 包发布到 npm，可以直接安装（无需源代码构建）：
| 包 | 安装 / 使用 | 描述 |
|----|------------|------|
| [`foo-webview-sdk`](https://www.npmjs.com/package/foo-webview-sdk) | `npm install foo-webview-sdk` | 主题 / 前端 SDK（Bridge API + Web 组件 + SMP 兼容层），参见 [`sdk/`](sdk/) |
| [`foo-ui-webview2-mcp`](https://www.npmjs.com/package/foo-ui-webview2-mcp) | `npx foo-ui-webview2-mcp` | 用于 AI 代理通过 CDP 驱动 foobar2000 的 MCP 服务器，参见 [`mcp/`](mcp/) |
---
## 项目结构
```
foo_ui_webview2/
├── src/ # C++ 源代码
│ ├── core/ # WebView 核心，UserInterface 等
│ ├── window/ # MainWindow，PopupWindow，WindowManager
│ ├── webview/ # WebView 主机和环境
│ ├── api/ # BridgeCore + API 处理程序
│ ├── callbacks/ # foobar2000 SDK 事件回调
│ ├── panels/ # DUI/CUI 面板集成
│ ├── selection/ # 选择跟踪
│ ├── interfaces/ # 服务抽象
│ └── utils/ # 实用函数
├── sdk/ # TypeScript SDK（foo-webview-sdk）
│ ├── src/ # 源代码（bridge/，components/，smp/，types/）
│ └── package.json
├── mcp/ # MCP 服务器（AI 代理 CDP 桥接）
│ ├── src/ # TypeScript 源代码
│ └── tests/ # 单元测试 + 端到端测试
├── tests/ # C++ 单元测试（GoogleTest）
├── docs/vitepress/ # 用户文档站点
├── lib/ # 第三方库
│ ├── foobar2000_sdk/ # foobar2000 SDK（BSD）
│ ├── columns_ui-sdk/ # Columns UI SDK（子模块）
│ └── json/ # nlohmann/json（MIT）
├── build.ps1 # 标准构建脚本
├── build-package.ps1 # .fb2k-component 打包
├── foo_ui_webview2.sln # VS 解决方案
├── foo_ui_webview2.vcxproj # VS 项目文件
└── packages.config # NuGet 包配置
```
---
## 构建
### 要求
- Visual Studio 2022（17.8+），v145 工具集
- Windows SDK 10.0.22621+
- WebView2 运行时
- Node.js 18+（用于构建 SDK / MCP / 文档站点）
### C++ 组件
```powershell
# 标准构建
.\build.ps1 -Config Release -Platform x64
# 打包 .fb2k-component（x86 + x64）
.\build-package.ps1
```
### TypeScript SDK（从源代码构建，用于开发）
> 用户无需构建它 — 只需 `npm install foo-webview-sdk`（参见上面的“npm 包”）。
```powershell
cd sdk
npm run build
```
### MCP 服务器（从源代码构建，用于开发）
> 用户无需构建它 — 只需 `npx foo-ui-webview2-mcp`（参见上面的“npm 包”）。
```powershell
cd mcp
npm install
npm run build
```
### WebUI / 主题
该组件不附带内置前端。请将您的 WebUI（至少包含 `index.html`）放入
`foo_ui_webview2_resources/dist/` 下的 foobar2000 组件目录中，然后重启 foobar2000 加载它。您可以在 `sdk/`（`foo-webview-sdk`）的基础上构建自定义主题。
---
## API 概述
200 多个 API 涵盖以下命名空间：
播放，播放列表，库，窗口，配置，文件，对话框，剪贴板，shell，http，键盘，ui，歌词，元数据，音频，控制台，dnd，队列，发现，重播增益，播放计数，标题格式，选择，端口
### 事件（冒号格式）
```
playback:trackChanged, playback:paused, playback:stopped, playback:seeked,
playback:volumeChanged, playback:time, playlist:itemsAdded, playlist:itemsRemoved,
playlist:activated, playlist:created, playlist:removed, playlist:renamed,
playlist:selectionChanged, metadb:changed, plugin:registered, api:registered
```
### 使用示例
```javascript
// 调用使用点格式
const track = await fb2k.invoke('playback.getCurrentTrack');
const results = await fb2k.invoke('library.search', { query: 'artist:Radiohead' });
// 事件监听器使用冒号格式
fb2k.on('playback:trackChanged', (track) => { /* ... */ });
```
---
## 插件扩展
其他 foobar2000 插件可以通过 PluginRegistry 向前端注册 API：
```cpp
#include "api/PluginRegistry.h"
void RegisterMyApis() {
auto& registry = PluginRegistry::GetInstance();
registry.RegisterPlugin("my_plugin", "My Plugin", "1.0.0", "Author", "Description");
registry.RegisterExternalApi("my_plugin", "doSomething",
[](const json& params) -> json {
return {{"result", "done"}};
},
"Perform an operation"
);
}
```
```javascript
const result = await fb2k.invoke('my_plugin.doSomething', { param1: 'value' });
```
---
## 安全限制
**威胁模型。** 这是一个专用的、特定领域的 UI 主机，用于 foobar2000 — 主题来自您或受信任的来源，因此安装主题的信任度与安装任何 foobar2000 组件相同。因此，目标是 *失败安全*（防止一个有缺陷的主题意外地损害系统），**不是** *隔离不受信任的代码*；过度锁定这样一个专门的组件只会束缚其自身的双手。真正的防护措施是路径验证和协议检查：
| API | 限制 |
|-----|------|
| shell.exec / shell.spawn | 无命令 / 可执行文件白名单 — 命令按给定方式运行；`cwd` 和绝对路径由 PathSecurity 验证（信任主题作者；这不是一个沙箱） |
| shell.openWith | 黑名单 — 阻止 29 个可执行文件 / 脚本扩展名（`.exe`，`.bat`，`.ps1`，`.dll`，`.lnk`，…） |
| file.read/write | 路径限制 — 系统目录（`C:\Windows`，`C:\Program Files`，`C:\ProgramData`）不可访问；写入仅限于 foobar2000 配置目录和 `%TEMP%` |
| http.get/post | SSRF 防护 — 阻止 localhost / 私有 / 链路本地地址（包括 DNS 解析后检查重绑定） |
| CDP 远程调试 | 默认关闭 — 必须手动启用，仅绑定到 localhost |
---
## 许可证
该项目的主要组件根据 **GNU 通用公共许可证 v3.0 或后续版本**（GPL-3.0-or-later）许可；有关完整条款，请参见 [LICENSE](LICENSE)。
- 主要组件：GPL-3.0-or-later
- TypeScript SDK（`sdk/`）：MIT 许可证（参见 `sdk/LICENSE`）
第三方库保留其自身的许可证：foobar2000 SDK（BSD），pfc / libPPUI（zlib），nlohmann/json（MIT），Columns UI SDK。
---
## 致谢
- [foobar2000 SDK](https://www.foobar2000.org/SDK)
- [WebView2](https://developer.microsoft.com/microsoft-edge/webview2/)
- [nlohmann/json](https://github.com/nlohmann/json)
- [Columns UI SDK](https://github.com/reupen/columns_ui-sdk)
- [WIL](https://github.com/microsoft/wil)
