dsh-frx-bg — 凡人修仙传背景插件

dsh(web) GUI 的背景叠加插件：每 10 分钟轮换一张凡人修仙传主题水墨壁纸，半透明铺在内容之上、不遮挡交互；右下角境界角标显示序号与下次换图时间，♡ 收藏按钮一键收藏喜欢的图。

一个 dsh.client 双面 cordis 插件 + dsh.bundle：宿主半（lib/index.js）发图与收藏路由，客户端半（lib/client.js）注入背景层 + 角标 + 轮换 + 收藏 UI。声明了 dsh.bundle，dsh plugin add 装完自动注册，无需手写 cordis.patch.yml。

---

一键安装

方式一：dsh 插件商店（推荐，npm 一键装）

dsh plugin --profile web add dsh-frx-bg

装完重启 dsh web（让宿主路由加载），再刷新浏览器即可。本包声明了 dsh.bundle.patch，会被自动加入 dsh.profile.bundles 并读包内的 cordis.patch.yml 注册宿主插件——不用再手写 profile 的 patch。

首次使用前背景为空，需先跑一次「取图」（见下）填充 assets/。取图后刷新浏览器即见。

方式二：从 gitcode 手动装（不走 npm）

适合不想用 npm、或想直接改源码的场景：

# 1) 拉仓库
git clone https://gitcode.com/liuhui93/deepseek_harness_plugin.git
cd deepseek_harness_plugin/dsh-frx-bg

# 2) 部署到 web profile
DEST=~/.dsh/profiles/web/node_modules/dsh-frx-bg
mkdir -p "$DEST/lib" "$DEST/assets" "$DEST/favorites"
cp package.json cordis.patch.yml fetch_frx.py "$DEST/"
cp lib/index.js lib/client.js "$DEST/lib/"

# 3) 注册宿主插件（手动装才需要；npm 装会自动注册）
#    编辑 ~/.dsh/profiles/web/cordis.patch.yml，加入：
#    - insert:
#        - id: frx-bg
#          name: dsh-frx-bg

# 4) 取图（见下）→ 重启 dsh web → 刷新浏览器

两种方式二选一，别同时用（重复注册）。从 npm 装过又改用手动，先 dsh plugin --profile web remove dsh-frx-bg 再走方式二。

---

取图 / 换一批

图片不随包分发（省空间）。首次使用前与想换新图时跑 fetch_frx.py：

python3 fetch_frx.py              # 默认抓 24 张最新，同步部署，重写 IMAGES
python3 fetch_frx.py --count 12   # 换 12 张（IMAGES 自动对齐）
python3 fetch_frx.py --pages 2    # 少扫候选页、更快
python3 fetch_frx.py --no-sync    # 只写源 assets/、不动部署（测试）

做了什么：解算术滑动验证码 → 扫画廊多页 → 取每张详情页 og:image（~1202×676 高清预览，约 400–500KB/张）→ 按上传日期降序（p01=最新）→ 下 N 张到 assets/p01..pNN.jpg → 重写 lib/client.js 的 IMAGES → 同步部署副本。刷新浏览器即见。

凡人修仙传每周六更新一集，更新后新图上传日期新，自动冒到前面被抓。

手动取图（抓取失败时的兜底）

fetch_frx.py 抓不到时（站点改验证码 / IP 被风控 / 断网），自己下图：

1. 从任意来源下凡人修仙传主题图片（壁纸站、截图都行）。
2. 重命名成 p01.jpg、p02.jpg、… pNN.jpg（序号从 01 起连续，张数随意）。
3. 放进插件 assets/（fetch_frx.py 同级）。
4. python3 fetch_frx.py --sync-only —— 扫 assets/p*.jpg 按序号排序，把 lib/client.js 的 IMAGES 对齐成实际张数并同步部署。
5. 刷新浏览器即见。

--sync-only 不联网、不解验证码，只做"扫本地图 → 对齐 IMAGES → 同步部署"。加 --no-sync 只改源、不动部署（先预览）。放多少张就轮换多少张。

---

收藏（♡）

看图时遇到喜欢的，点右下角 ♡ 收藏 即可：

• 点 → 当前图存入 favorites/（按内容 hash 去重，重复收藏提示「已收藏过」），按钮变 ♥ 已收藏（红）。
• 收藏图加入轮换（批量 ++ 收藏一起转）；当前是收藏图时 ♥ 实心红，再点即取消。
• 收藏清单存 favorites/_favorites.json（记录 src/hash/added）。换图（fetch_frx.py）只动 assets/，收藏不被覆盖——这是收藏的核心价值。
• 客户端启动时拉 GET /frx-bg/state 取收藏列表；拉取失败则降级为纯批量轮换。

宿主路由（lib/index.js）：

方法	路径	作用
GET	/frx-bg/state	列收藏
POST	/frx-bg/favorite	{"file":"p0X.jpg"} 切换（批量图→存入；收藏图→删除）
GET	/frx-bg/<file>	取批量图
GET	/frx-bg/fav/<file>	取收藏图

客户端改动（lib/client.js）刷新即生效；宿主路由改动（lib/index.js）需重启 dsh web 才加载。重启前点 ♥ 会提示「收藏失败（需重启 dsh web）」。

---

运行参数（lib/client.js）

• IMAGES：p01..pNN（由 fetch_frx.py / --sync-only 维护，勿手改）
• INTERVAL：换图周期，默认 10*60*1000（10 分钟）
• .dsh-frx-layer：z-index:2147483646; pointer-events:none; opacity:.25（改 .opacity 调浓度）
• .dsh-frx-badge：右下境界角标　·　.dsh-frx-fav：右下收藏按钮　·　.dsh-frx-toast：操作提示

---

卸载

# npm 装的：
dsh plugin --profile web remove dsh-frx-bg
# 手动装的：删 ~/.dsh/profiles/web/cordis.patch.yml 里的 insert（恢复 []）

重启 dsh web 即恢复原样。

---

目录结构

dsh-frx-bg/
├── package.json          # dsh.bundle.patch + dsh.client + exports + files
├── cordis.patch.yml      # bundle patch：insert 注册宿主插件（npm 装自动读）
├── lib/
│   ├── index.js          # 宿主半：/frx-bg/* 图片与收藏路由（webServer.register）
│   └── client.js         # 客户端半：背景层 + 角标 + 轮换 + 收藏 UI
├── fetch_frx.py          # 批量换图：moyubuluo 抓最新 N 张 → 填 assets/ + 同步部署
├── assets/               # 图片不随包分发；由 fetch_frx.py 下载填充（运行时需要）
│   └── .gitkeep
├── favorites/            # 收藏图 + _favorites.json（运行时生成）
│   └── .gitkeep
└── README.md

---

双面契约（改代码务必遵守，否则崩溃）

• 宿主半 lib/index.js：Node 侧 cordis 插件，export default { name, inject:['webServer'], apply }；apply 里 ctx.effect(() => ctx.webServer.register({kind:"prefix", path:"/frx-bg", handler}), label)。
• 客户端半 lib/client.js：浏览器 boot 当客户端插件 apply。工厂 必须 return module.exports，导出 { name, inject:[], apply }；DOM 副作用包进 apply(ctx) 的 ctx.effect(() => { …; return disposer; }, label)。
  • ❌ 工厂只做副作用返回 undefined → cordis 抛 invalid plugin ... received undefined → boot catch → "Failed to load plugins" → 所有分区不挂载。
  • 对照官方 @deepseek-ai/dsh-client-ui-brand-official。

---

发布到 npm（维护者）

本包已具备 dsh.bundle 一键注册结构。发布后用户即可 dsh plugin --profile web add dsh-frx-bg：

cd dsh-frx-bg            # 子目录有独立 package.json，作为发布单元
npm login                # 用 npm 账号登录（首次）
npm publish              # 发布；npm 会按 package.json 的 files 只发 lib/cordis.patch.yml/fetch_frx.py
# 发新版前先改 package.json 的 version，再 npm publish

包名 dsh-frx-bg 需在 npm 上未被占用。源码仓库留 gitcode 即可，package.json 的 repository 已填 gitcode（仅信息标注，安装走 npm 不读 git）。

---

诚实说明

• 用的是详情页 og:image 高清预览（~1202×676），不是 4K 原图：4K 在「下载原图」按钮背后的 DownSys 下载流里（更脆），且 4K 单批约 80MB+，与省空间相悖。预览在 .25 透明度下做氛围层足够；要 4K 再单独做下载流。手动取图则由你决定用什么分辨率。
• 验证码是算术滑动题，脚本自动解（处理 +/×/-）；站点改验证方式则需更新脚本（或改用手动取图兜底）。
• 别频繁跑（反复请求会被风控封 IP）。建议每周六更新后跑一次。