Obsidian Stats logoObsidian Stats

Wallvia

by Maplelia
5
4
3
2
1
Score: 50/100
Install Code

Description

Bring your Wallpaper Engine everywhere - one repository for the Obsidian plugin, the VS Code extension and the npm CLI. The plugin lives at the repo root; vscode/ and codex/ sit beside it.

Reviews

No reviews yet.

Stats

0
stars
1
downloads
0
forks
1
days
0
days
0
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
18
commits

Latest Version

0.2.4
9 hours ago

Changelog

See all version on GitHub

README file from

Github

Wallvia

Bring your Wallpaper Engine everywhere.

同一套「壁纸 + 毛玻璃」体验,分别落地到你的编辑器、笔记库与 AI 编码应用。

Obsidian 版是一个社区插件：把当前的 Wallpaper Engine 壁纸铺成笔记库背景，并让侧边栏、弹窗与标签页变成毛玻璃。详见 插件文档。

License: MIT Platforms Node

VS Code · Obsidian · Codex · 安装方式 · 致谢

Wallvia 在 VS Code 中的效果

VS Code 1.140.0 实测:壁纸铺满窗口,活动栏 / 标题栏 / 状态栏透明,编辑器 55% 通透,侧栏与 Chat 面板带压暗洗色,文字依然清晰。

目录

这是什么

一个把背景图铺在你的工作界面之后、并让界面表面变成半透明毛玻璃的小工具, 外加一层压暗,保证文字在任何图片上都读得清。

三个平台共用同一套设计语言与参数语义(fit / dim / glass), 但各自用该平台真正可行的方式实现 —— 因为三个宿主的插件能力完全不同:

平台 壁纸来源 实现方式 需要管理员 改宿主文件
VS Code 自选图片 / 本机已下载的 WE 壁纸 补丁 workbench.html + 生成 CSS 视安装位置而定 是(带备份,可还原)
Obsidian vault 内图片 / 本机已下载的 WE 壁纸 官方插件 API + CSS 变量 否 否
Codex 桌面版 跟随 Wallpaper Engine CDP 运行时注入 + 后台 keeper 否 否

三个平台

Wallvia for VS Code

选一张图当整个 workbench 的背景,也可以直接从本机已下载的 Wallpaper Engine 壁纸里挑。命令面板一句话搞定,VS Code 升级后自动重打补丁。

  • 扩展 ID wallvia.wallvia
  • 图形设置面板 + 6 条命令(命令面板搜 wallvia)
  • 对齐:覆盖 / 填充 / 居中;两种模式:glass / fade

→ 详细文档

Wallvia for Obsidian

选一张 vault 里的图当工作区背景,支持亮/暗主题分别压暗,图片改名自动跟随。

  • 插件 ID wallvia
  • 应用内浮层面板(与 DSH 上的 dsh-web-all 一致):右下角可拖动的图片按钮 → 面板里带图片预览和效果编辑(对齐 / 压暗 / 通透 / 模糊 / 不透明度),改完即时生效
  • ribbon 图标打开同一个面板;插件设置页提供同一组旋钮
  • 命令面板 Choose from Wallpaper Engine:列出本机已下载的 WE 壁纸(当前使用的排最前),预览图自动复制进 vault
  • 对齐:覆盖 / 填充 / 居中
  • 支持 BRAT 一键安装

→ 详细文档

Wallvia for Codex

跟随你 Wallpaper Engine 当前的壁纸,通过 CDP 注入,不碰应用文件、不需要管理员。

  • CLI:wallvia watch
  • 列出本机已下载的 WE 壁纸并选择:wallvia list / wallvia use <编号|id>
  • 对齐方式:覆盖(cover) / 填充(fill) / 居中(center)(旧值 contain / tile 仍可读)
  • 双击启动器即用
  • 换壁纸约 1.5 秒自动跟随

→ 详细文档

快速开始

一个仓库(Maplelia/Wallvia)、三个平台,都已发布;最省事的方式如下(细节与替代方案见 INSTALL.md):

VS Code — 一行下载并安装（自动取最新版）:

$r = irm https://api.github.com/repos/Maplelia/Wallvia/releases/latest
$u = ($r.assets | Where-Object name -like '*.vsix').browser_download_url
irm $u -OutFile "$env:TEMP\wallvia.vsix"; code --install-extension "$env:TEMP\wallvia.vsix"

Obsidian — 在 BRAT 里粘仓库地址即可自动安装与更新:

https://github.com/Maplelia/Wallvia

Codex 桌面版 — 一行安装（装好后新开终端直接 wallvia watch）:

npm i -g wallvia        # 已上架 npm:https://www.npmjs.com/package/wallvia

不想经过 npm 就用脚本（二选一，两者都提供 wallvia 命令）:

irm https://cdn.jsdelivr.net/gh/Maplelia/Wallvia@main/codex/install.ps1 | iex

用 jsDelivr 而不是 raw.githubusercontent.com,因为后者在部分网络下不通; 安装脚本内部走 codeload.github.com 下载仓库 ZIP,同样不受该限制。

都在同一个仓库里:Obsidian 插件位于根目录,VS Code 扩展在 vscode/,CLI 在 codex/。

本地开发用

code --install-extension (Get-ChildItem vscode\*.vsix | Select-Object -Last 1).FullName   # VS Code(本地包)
Copy-Item manifest.json,main.js,styles.css "$env:USERPROFILE\Documents\MyVault\.obsidian\plugins\wallvia"
cd codex; npm run watch                              # Codex(关旧实例 → 带端口重启 → 注入 → 保持)
cd codex; npm run list                               # 列出本机已下载的 WE 壁纸
cd codex; npm run use -- 3                           # 把 3 号壁纸的预览图应用到 Codex

核心概念:三个旋钮

三个平台的参数语义完全一致:

旋钮 范围 默认 作用
fit cover fill center cover 对齐方式:覆盖(cover)/ 填充(fill)/ 居中(center);旧值 contain / tile 仍可读
dim 0-80(Obsidian 为 0-1) 22-45 压暗层强度,越高文字越清晰
glass 0-100 55-75 表面通透度。0 = 完全不透明;100 = 最通透(保留可读性下限)

调参经验:

  • 亮色 / 花哨的图 → dim 调高(40-60);
  • 想让界面「更玻璃」 → glass 拉高,必要时加一点 blur;
  • 主题冲突或某个面板不透 → VS Code 切 fade 模式兜底。

工作原理

三个平台都在真实应用里实测过,细节值得一读,因为每个平台都有一个"不知道就做不出来"的坑:

VS Code:补丁 + 生成 CSS

VS Code 没有任何官方 API 能设置整个 workbench 的背景图。所以:

  1. 图片拷进扩展的 globalStorage;
  2. 在 workbench.html 同目录生成 wallvia-bg.css;
  3. 往 <head> 注入一段带标记的 <link>(幂等、可还原);
  4. 同步 product.json 的 checksums,避免"安装已损坏"警告。

三个必须踩对的细节:

细节 做错的后果
checksums 必须是 sha256 的无填充 base64(43 字符) 写成 hex → 每次启动弹 "installation appears to be corrupt"
图片 URI 必须百分号编码 路径含空格或中文时(Windows 常见)渲染器拒绝加载
.monaco-workbench、.part.editor 等不透明祖先要一起透明化 CSS 全部生效,但图片被底色盖住 → 看不见壁纸

Obsidian:官方 API + CSS 变量

插件运行在渲染进程,有完整 DOM 权限:

  • styles.css 定义结构(body::before 图片层、::after 压暗层、表面透明化);
  • main.js 把动态值写进 document.body 的 --wallvia-* 变量;
  • 图片 URL 每次重载都会变,所以只存 vault 相对路径,运行时用 getResourcePath(path) + "?v=" + mtime 解析;
  • 亮色主题用白色压暗、暗色主题用黑色,两种主题都保持对比度。

Codex 桌面版:CDP 运行时注入

Codex 以 MSIX 包分发,app.asar 受系统 ACL 保护无法修改,而且单实例锁会吞掉带调试端口的新启动。所以:

启动器:关掉已运行实例 → 以 --remote-debugging-port 重启
          │
          ▼
keeper(每 1.5 秒):读 WE config.json → preview.jpg → data:URL
          → 对每个主窗口 Runtime.evaluate 注入 <style>
          → 换壁纸 / 窗口重载时自动重注入

要点:图片必须是 data: URL(渲染器拒绝 file://); 版本 token 同时包含壁纸标识与 CSS 内容哈希,所以改参数或升级本工具也会触发重写; 配置路径与解析结果都做了缓存,避免每 1.5 秒 spawn 进程(实测修复后 keeper 在 12 秒内的子进程数为 0)。

验证情况

node tests/run-all.cjs → ALL TESTS PASSED(零依赖,9 段:清单 / shared-core / codex 模块 / 两个 codex node:test 套件 / Obsidian / Obsidian-WE / VS Code / 真实 Chromium 的 CDP)。

其中 tests/cdp-live.mjs 会启动一个真实无头 Chromium 做端到端注入验证 (/json 发现、WebSocket CDP、Runtime.evaluate、样式真的生效、幂等、变更检测、请求超时)。

真机验证(不只是夹具):

平台 实测内容
Codex 在 MSIX 26.930.3930.0 上注入成功:body::before 上是真实 WE 壁纸(561 KB data:URL)、压暗层 rgba(8,10,18,0.22)、面板不透明度 0.93 → 0.71
VS Code 在 1.139.1 / 1.140.0 上真实打补丁并重启验证:活动栏/标题栏 rgba(0,0,0,0)、编辑器 color(srgb … / 0.55)、无 corrupt 警告,并截图确认
Obsidian 载入 esbuild 产物并通过 mock API 端到端测试(onload 事件、apply() 类与变量、onunload 清理);另有 tests/obsidian-we-picker.cjs 验证 WE 预览图复制进 vault 的 mkdir / writeBinary / 清理路径与失败分支;真实 vault 未截图以免泄露私人笔记

真实测试过程中修掉的问题(节选,完整 14 条见提交历史): 玻璃强度语义反向、verifySkin 永远返回 false、版本 token 不含 CSS 导致永不重注入、 每 1.5 秒重复编码整张壁纸、checksum 写成 hex、URI 未编码、重复 watch 堆积孤儿 keeper、 每 1.5 秒弹 PowerShell 窗口。

仓库结构

.
├── manifest.json / main.js / styles.css   Wallvia for Obsidian(插件,必须在仓库根目录)
├── src/                                   插件源码(TypeScript)
├── vscode/                                Wallvia for VS Code(扩展)
├── codex/                                 Wallvia for Codex(CLI:src/*.mjs + 双击启动器)
├── scripts/bump-version.mjs               一次升三个版本号
├── tests/                                 零依赖测试套件(含真实 Chromium 的 CDP 端到端测试)
├── docs/                                  截图 + 插件详细文档
├── INSTALL.md                             三平台最简安装方式对照
└── CREDITS.md                             来源与第三方致谢

三个平台共用一个仓库,但各自自包含。Obsidian 的官方市场与 BRAT 都只认仓库根目录的 manifest.json / main.js / styles.css,而且 release 的 tag 必须等于 manifest.json 的版本号,所以根目录留给插件、另外两个平台各占一个子目录,一个 tag 同时发布三者。codex/ 的共享核心已内联为 codex/src/state.mjs,vscode/ 无需构建步骤即可加载。

常见问题

需要完全重启 VS Code(不是 Reload Window)。命令面板里搜 wallvia —— 全部 6 条命令都以 Wallvia: 开头,所以搜品牌名必然命中(搜 wallpaper 也能看到大部分)。然后用 Wallvia: Show Status 确认 patched: true。若弹出 "installation appears to be corrupt", 重新执行一次 Wallvia: Choose Wallpaper Engine Wallpaper…(或 Choose Image File…)会重算校验和。

正常现象 —— 更新会替换整个版本目录。扩展启动时会检测版本并自动重打 (可在设置里关闭 wallvia.autoReapply)。本机就实测过一次:安装期间 VS Code 从 1.139.1 自我更新到 1.140.0,补丁被清空。

说明 Codex 不是以调试端口启动的。用 wallvia watch(或双击 start-wallpaper.cmd), 它会先关掉现有实例再带端口重启 —— 单实例锁导致必须这样做。 不想让它关你的窗口就加 --no-kill,自己先关。

Codex 自身的面板本来就有 93% 不透明度,所以默认 --glass 75 只是明显可见。 想更透用 --glass 100(面板降到 62%),或调低 --dim。

该主题对表面用了 !important。用 CSS snippet 追加 background-color: transparent 即可兜底。

因为 code --install-extension 只接受扩展 ID 或 VSIX 路径,不接受 URL。 Obsidian 有 BRAT 可以做这件事,VS Code 没有等价物(本扩展也未上架 Marketplace), 所以请用上面的「下载 release 里的 VSIX 再安装」命令 —— 同样是一行。 详见 INSTALL.md。

致谢与许可

玻璃壁纸机制移植自 DeepSeek Harness(DSH) 生态的壁纸插件 —— 代码来源是 @deepseek-ai/dsh-plugin-wallpaper(MIT), 而 DSH Web UI 里实际挂载该功能的是 @linxin666/dsh-web-all(Apache-2.0) 打包的 skin-center。三个平台的选择器与平台特性,分别参考了 vscode-background、style-context、codex-wallpaper-theme 等独立社区项目 —— 完整说明见 CREDITS.md。

Wallpaper Engine 是 Kristjan Skutta 的产品;Wallvia 只读取其本地 config.json 来判断当前壁纸,与 Wallpaper Engine 无隶属关系。

MIT © 2026 Wallvia contributors

Sponsors