跳过主要内容
P

dsh-pighub

positer/dsh-pighub

PigHub 的 DSH 插件,在侧栏每天领猪、重复升星,支持拖出置顶桌宠。数据存于 ~/.PigHub,未内嵌任何上游图片。

安装

dsh plugin --profile web add github:positer/dsh-pighub

README

dsh-pighub

**PigHub(猪猪库)的 DeepSeek Harness 插件:**在侧边栏养一个猪圈。每天领一只猪猪,重复的升星,攒够了把猪拖到桌面上遛。

猪猪素材来自 PigHub 社区图库及其开源镜像,在构建期就处理好并随包分发:去白底、裁到猪身、判定默认会不会动、要不要描摹成 SVG,全部在 npm run assets:build 时完成,产物是包内普通文件。

运行时不访问素材库:不请求上游、不做图像计算、不占用户算力。署名与出处见 assets/ATTRIBUTION.md,内容按版本手动更新。

它长什么样

  • 侧边栏入口:PigHub 站内那只标准小猪,保留原色彩(逐色块描摹自 pighub-1114:粉身、玫红耳/腮、浅粉高光),镜像成朝右,与已有入口同尺寸。
  • 猪圈面板:左边带围栏的大正方形猪圈(min(60vmin,560px));右上像素风标题(手写 5×7 位图字模),其下「今日猪猪」;再往下是可排序、可按位置筛选的猪猪清单。
  • 跟随 DSH 亮/暗色主题:草地、小屋、文字全部走 --dsw-alias-* 令牌(color-mix 与背景令牌混色),围栏用的是用户给的位图、 不参与混色——所以换主题不用改一行代码,也不需要维护第二套围栏;围栏之外的区域是透明的,亮暗两种页面底色都能直接透出来。
  • 设置按钮在面板整体右上角:星级显示三档(关闭 / 默认 / 常驻)、素材库版本与来源、下一版候选池、数据目录。
  • 每日一只:一天抽一次,池子是本版本冻结库;重复获得同一只升一星,分别记录「首次获得」与「最近升星」。
  • 抽卡演出:从你按下的按钮弹出(缩放回弹 + 火花)→ 飞到窗口中心放大到 1.8 倍 → 停留 2.5 秒, 头顶一张深色半透明圆角卡片写着名字 + 描述(描述 = 这只猪在 manifest 里那一条的逐图判定理由,超 60 字截断)→ 再飞回猪圈,落点就是这只猪真实的落点(不是估算,见「验证」里的 landGap)。演出期间不拦任何交互: 点任意地方即刻收场(监听挂在 document 上、不阻止事件传播,按钮照按、猪照拖);prefers-reduced-motion 下不飞, 直接把卡片摆出来停 2.5 秒。
  • 会动的猪:自己游走、点一下有弹性回弹;游走模型逐参数对齐桌面桌宠(lib/native/pet-window.cs)—— 每只猪各自计时,每 1.7 秒决策一次、72% 原地发呆,动起来就匀速走过去(每秒 1 个身位),不是猛跳一下。 走动时面朝运动方向(素材默认朝左,向右走才镜像),而且是蹦跳不是平移(外层位移弧 + 内层 squash & stretch)。
  • 步长:每次决策采样的步长是 [1.65, 3.0) 个身位(身位 = 这只猪自己的宽度),方向在 0–360° 里均匀取一个; 但一次决策最多走 1.7 个身位——桌宠会在 1700 ms 后再决策、把「走到一半」截断,猪圈在同一个点上截断目标, 时长与距离仍成正比(恒速)。
  • 边界是挡住的,不是弹回来的:撞到围栏就夹在围栏上(与桌宠撞到屏幕工作区同一条规则:夹取而非反弹), 不再重掷方向,也不会把一步拆成碎步。
  • 自由拖动:按住拖动时实时跟随指针(影子与圈里那只同尺寸),拖动期间这只猪暂停游走; 松手即固定落点并原地站稳约 6 秒(只用一个站稳计时器:不再多叠一次决策延迟),不会一放就自己走开; 在猪圈里松手即把落脚点改成松手处。落在哪儿会写进 state.json 的 pig.pos, 下次打开面板一进来就在那个点(第一帧先发呆,不会立刻弹走)。 落地即新的游走起点,不许回头:松手那一拍就把这只猪的位置基准换成落点、并取消在飞的位移过渡, 下一次决策从落点开始——不会出现「先滑回拖动前的位置、再滑到落点」的两段位移。 实测落点与猪圆心误差 ≤0.03 px、反向位移 0(3 次 × 2 种 effect 时序 + 像素连拍, 见 archive/drag-drop-origin.md)。
  • 逐只行为开关:右键猪本体或列表行 → 「允许运动 / 保持静止」。静止的猪不再游走、不响应点击,但仍可拖动;开关存进 state.json 的 pig.motion,缺省回落素材判定。
  • 猪圈容量 12:超过就自动落进仓库,并提示「猪圈满了,先住进仓库了」——不静默丢猪。
  • 按位置筛选:清单上方 全部 / 猪圈 / 桌宠 / 库存 四档;点库存行即放回猪圈。
  • 木栅栏(有景深,用一张真图):围栏是一张 1254×1254 的木栅栏方框图(assets/img/pen-fence.png,逐字节原样入库,不重画/不改色/不拉伸), 按同一条水平线切成远/近两层:远侧画在猪后面、近侧画在猪前面,所以猪从中间走过时头压住远栏、身子被近栏挡住。 两层是同一份像素(每行只归一层),叠回去与单层整图逐像素相同(452 px 下实测 0 差异)。
  • 草地只铺在框里:草坪按给定红框内缩(8.37% / 91.47% × 18.26% / 96.65%),框外的猪圈区域一个像素都不画(alpha=0), 直接露出宿主页面底色——深色页面上不会出现「一块绿色/深色方块」。
  • 猪之间按脚底排前后:脚底越靠下(屏幕 y 越大)越靠前,两只猪叠在一起时下遮挡上;同一脚底按 id 稳定排序,不会两帧之间抢层。 脚底 = 猪的中心 + 渲染高度 / 2(贴图紧裁到猪身,所以贴图底边就是脚底;高度 = sizeRatio × 清单里的高宽比),不是拿 top 当脚底。 z 只在一档区间里变(远栏 1 < 仓库小屋 2 < 猪 3..28 < 近栏 30),所以猪永远压不过近侧围栏、也不会掉到远栏下面; 拖动中的那只临时取这一档的顶。逐轮读数与截图见 archive/pig-occlusion.md。
  • 仓库小屋:猪圈左下角的小房子,把小猪拖进去即收进库存——隐藏且不再加载贴图。位置三态:猪圈 / 桌宠 / 库存,互斥。
  • GIF 素材:动图原样随包分发(去白/裁切/描摹都会把动画冻成静态图),构建期用 magic 判定,客户端直接交给浏览器播放。
  • 桌面桌宠(Windows 原生窗口):把猪放到桌宠位后,插件会拉起一个自建的原生顶层窗口 (WinForms + WS_EX_LAYERED/TOPMOST/TOOLWINDOW/NOACTIVATE + UpdateLayeredWindow 逐像素 alpha), 猪在整个 Windows 桌面上走动,可以盖在任何应用窗口之上;透明像素不挡鼠标(WM_NCHITTEST 自己判 alpha); 一个窗口画全部桌宠;双击回猪圈、右键切运动。位置写进 state.json 的 pig.desktopPos。 走动时是蹦跳不是平移:与猪圈同一节拍(283 ms)同一幅度(0.12 个身位)的位移弧,外加一层 以脚底为锚点的 squash & stretch(纵向 0.94 ↔ 1.06、横向取倒数所以面积守恒)—— 落地压扁、最高点拉长、脚始终踩在同一条地线上;站着不动时不缩放。 非 Windows 或取不到编译器时回退到页面级浮层(不报错)。首次运行会用系统自带 csc.exe 编译一次 (约 1–3 秒,按源码哈希缓存)。
  • 回圈的连贯性:把猪叫回猪圈时(原生窗口双击 / 拖回猪圈 / 工具或路由的 {action:'pet',pigId,pet:false}), 猪圈里立刻就有它:桌宠在场时浏览器半每 250 ms 对一次账——只问一个几十字节的「渲染相关状态变了没有」令牌, 变了才拉整张快照;没有桌宠时 1 s 问一次、10 s 拉一张整张快照兜底(位置靠它对账)。 实测空窗 175–267 ms(4 次);改前只靠 10 s 一轮整张快照,实测 0.16–8.36 s, 而且两次相隔 1.1 s 的放回动作在界面上相差 10.03 s(= 轮询相位,不是渲染慢)。见 archive/pet-return-continuity.md。
  • 页面内桌宠(回退路径):把猪拖出猪圈即成为置顶浮层,可拖动;允许运动的猪会自己溜达(约三成落脚点落回猪圈), 拖回猪圈矩形内松手即回圈(也可以双击回圈)。哪些猪在猪圈外,记录在 state.json 的 pets 里,清单上会标「桌宠」。 平台限制:原生桌宠只在 Windows 上可用(v0.9.0 起);其它平台自动回退到页面级浮层。
  • 清单不标活死:会不会动是行为开关,不是身份;清单只在「静止」时给一个提示标签,位置(库存 / 桌宠)照常标。

素材:冻结、逐图判定、定制切分

assets/sources.json           候选池(从公开目录里挑出来的候选)
assets/judgements.json        逐图判定:kind(live/dead) + mood(cute/reject) + 裁切框 + 去白阈值 + 判定理由
assets/cards/selection.json   角色卡里通过可爱闸门的收编名单(cute 进包 / reject 只留档)
assets/manifest.json          冻结产物:上面三份 + 每张贴图的 sha256/bytes + assetVersion

构建:npm run assets:build。它有两条硬约束:候选池里每一张都必须有判定(少一条或多一条都直接失败),每一张都必须有理由。所以「逐图判定」是构建的前置条件,不是口号。

角色卡的批量入口是 npm run cards:make(--append 增量出样,不动已有判定)→ 逐张目检写进 assets/cards/index.json → npm run cards:report 生成判定表 → npm run cards:select 生成收编名单 → npm run assets:adopt 收进冻结库。

可爱闸门(硬约束):判定里还有一条 mood —— 只收 cute;血腥(獠牙撕咬 / 伤口 / 血)、身体恐怖(一具身体多张脸)、 惊悚造型一律 reject,不进包,连理由一起记进 manifest.moodRejected。没有 mood 或没写理由,构建直接失败。 扩包走 npm run assets:adopt:只增不改,把 assets/cards/ 里通过闸门的卡收编进 assets/img 与清单 (校验指纹与字节数、幂等、拒收留档),老素材不会被重新冻结。

同一套流程里还有矢量图化:判定为平涂卡通的图会被描摹成自包含 SVG(量化 → 等值线 → 简化 → 路径),以 data:image/svg+xml 渲染,放大不模糊;场景/照片类整图保留位图,因为描出来只会更脏。是否描摹同样逐图记录在判定表里。

去白底在构建期完成(色键 / 框阵 / 补洞见 lib/imaging.js),产物就是包内的普通文件;运行时只剩两件事:读清单、发本地贴图。 早期版本曾在浏览器里用「同源代理 + canvas 漫水填充」做这件事,那条路已经拆掉——它要联网、要占用户算力,还依赖上游可用性, 与本插件的构建期约定相反。裁切框与阈值逐图不同,所以同一张源图在任何机器上切出同一个结果。

安装

dsh plugin --profile <你的 profile> add dsh-pighub

装完重启 DSH:Host 半负责数据与抽取,浏览器半在启动时进图。

装完之后请再点一次侧边栏的 PigHub 入口。 实测(6/6 次「卸载 → 安装 → 打开面板」): 安装返回成功、素材路由已经 200,但主区域不会自己重新挂载面板,看起来就是一片空白; 点一次入口即恢复(点击后 1.06–1.18 s 画出来)。这是宿主槽位的行为,不是插件抛错—— 逐轮读数见 archive/verify-completion-and-stability.md §3。

本插件已在真机(DSH 桌面版 / profile desktop)上装过并逐屏核验:侧边栏图标、猪圈面板与排版、 桌宠浮层与游走。那次核验暴露的三个「只有真机才会犯」的缺陷(宿主 ToolDefinition.output 必填、 围栏 SVG 只占猪圈宽 58.6%、统计行误用候选池计数)都已在 0.5.10 修掉,逐条数字见 CHANGELOG。

数据放在哪

所有本地数据都在用户主目录的 `/.PigHub/:

文件内容
state.json拥有哪些猪(含活/死判定与切分参数)、星级、首次获得与最近升星、每日抽取记录、桌宠列表
catalog.json下一版候选池的目录缓存(只有 id/标题/文件名/URL)
prefs.json排序偏好与星级显示档位

状态文件损坏时不会静默覆盖:原文改名为 state.json.corrupt-<时间戳> 留着,插件退回空状态继续可用。

结构

dsh-pighub/
├── lib/index.js             Host 半:读盘、POST /pighub、每张素材一条 /pighub/asset/<file>、pighub_about / pig-say
├── lib/store.js             抽取 / 升星 / 排序 / 原子写盘
├── lib/assets.js            冻结库读取(抽猪池只认它)
├── lib/client.js            浏览器半:closure-factory bundle,注册三个槽位
├── assets/                  冻结素材库:候选 / 判定 / 产物贴图(img/)/ 署名
├── scripts/build-assets.mjs 冻结库构建(逐图判定校验)
├── test/                    离线测试(发布闸门)
└── .github/workflows/       pack → OIDC 发布

浏览器半只用官方增量槽位:sidebar.panellist(入口)、main(面板,key 与入口 id 相同)、shell.overlay(页面级桌宠层)。

DSH 工具

插件的 Host 半注册两个工具(ctx.tools.register,都在 ctx.effect 里,可回收):

工具参数返回说明
pighub_about无版本 / 数据目录 / 今日状态 / 收藏数 / 素材库摘要 / 运行时探测只读,无副作用
pig-say{ text: string }(必填,≤200 字){ ok:true, pigId, text, truncated }让桌面上随机一只桌宠猪用气泡说这句纯文本,约 6 秒后自动消失,气泡跟着猪走

pig-say 的拒绝是返回值,不是异常:

{ "ok": false, "error": "no_desktop_pet", "message": "当前没有桌宠猪猪,先把猪猪放到桌宠" }

同一族里还有 empty_text(空/纯空白)、desktop_pet_no_asset(桌宠列表里的猪找不到贴图)、 desktop_pet_unavailable(有猪但原生窗口起不来,例如非 Windows 或 desktopPet:false)。 超过 200 字按码点截断(不切坏 emoji)并回 truncated:true + note。

气泡走既有 IPC:宿主往原生窗口会话目录的 commands.jsonl 追加一行 {"type":"say","id":"<猪>","text":"…","until":<Unix 毫秒>},原生侧下一帧读到就画、到点自动不画。 样式对齐 NewMate 的桌宠气泡(同字体/圆角/浅底/细边/尾巴),三处刻意的差异与理由见 docs/DESKTOP-PET-NATIVE.md §7。验收读数见 archive/pig-say.md。

三层一致:尺寸、运动、进出

猪有三个显示层——猪圈本体、页面级浮层(非 Windows 的回退路径)、原生桌面窗口(Windows)。 三层的尺寸与运动用同一份口径,不是各自拍脑袋:

量口径落在哪里
本体宽度sizeRatio(assets/manifest.json,按不透明面积归一化,中位数 96 CSS px)猪圈:CSS width: sizeRatio px;浮层:同一个值;原生:sizeRatio × devicePixelRatio 物理像素
决策间隔1700 ms,每只猪各自计时三层一致
发呆概率0.72三层一致
单步距离1.65–3.0 个身位采样,一次决策最多走 1.7 个身位(速度 × 1.7 s)猪圈按「身位 ÷ 圈宽 × 100」换算成百分比、不缩放;原生按物理像素
移动速度1 身位/秒猪圈按「距离 ÷ 速度」算 CSS 过渡时长;原生每帧按速度逼近
朝向dx > 0 才朝右;素材默认朝左,向右走水平镜像三层一致
边界夹取:撞到边缘就贴着走,不反弹猪圈夹进活动区,原生夹进屏幕工作区
走动弹跳位移弧 283 ms / 0.12 身位,叠一层纵向 0.94 ↔ 1.06、横向取倒数的缩放,锚点在脚底;只有走动才动猪圈:CSS pighub-travel + pighub-hop;原生:pet-window.cs 的同一条 hopUnit 相位 + GDI+ 三行矩阵
随机数每次决策恰好 3 个:发呆 → 角度 → 步长猪圈同一顺序、同一数量(贴边不再重掷角度)

一处已知未对齐:页面级浮层(非 Windows 的回退路径)用的是同一套常量,但没有 1.7 身位的一窗上限, 且朝向在 dx = 0 时偏向右。它不在本轮范围(本轮只对齐猪圈本体),逐项差异见 archive/pen-pet-alignment.md §2.2。

进出连续:从猪圈拖出去时,桌面上的落点就是松手点(实测误差 ≤ 2px);拖回猪圈时,落点换算成圈内百分比 (也是松手处,不是回到原位);往返前后尺寸不变。静止的猪同样会采纳新落点,只是不走动。

停止与卸载(Cordis 契约)

插件的每一样东西都挂在 ctx.effect 上:两个工具、状态路由、每张素材的静态路由、以及原生桌宠的生命周期。 Cordis 卸载 fiber 时会 await 每一个 disposer(fiber.ts 的 _unload()),所以桌宠的 disposer 返回的是一个 Promise:

契约现在的做法实测
disposer 可等待return () => stopDesktopPet('plugin_unloaded'),硬上限 2 s 一定 settledisable 返回时进程已不在(3 次,见 报告)
停止幂等并发/重复调用共用同一次停止;没有会话直接回 already_stopped连点两次 disable 第二次 changed:false、无异常
强杀兜底写 <session>/stop → 等 1.2 s → taskkill /PID <pid> /T /F → 再等 0.6 s → child.kill()正常路径 graceful:true,只用了 105–128 ms
启动竞态首次编译 csc 要 1–3 s;这期间被 disable 的拉起请求回 stopped_during_start探针实测:2.5 s 后没有多出进程
宿主被强杀拉起时写 <session>/pid(含宿主 pid),下次 apply 先 reclaimStaleSessions()造一个宿主已死的会话 → 下次 enable 时进程被杀、目录被删

停止的完整读数(3 次开停、逐毫秒时间戳、tasklist / 采样进程 / HTTP 404 三种独立读数)见 archive/cordis-stop-compat.md。做不到的两条也写在那里: taskkill /T 的孙进程语义在本机没拿到干净对照(真实桌宠不派生子进程,实测 children=0), 轮询定时器的清理只有代码证据、没有进程外读数。

素材补全(逐角色卡)

池子里的猪来自上游社区图,有一部分天生就是半身像(构建期没有切坏它们,是源图如此)。 对检测出的「直切成残缺」的猪逐个补全,每只单独定参数、留 before/after。现行清单以编码字段为准:

模式(completion.mode)只数卡补了什么
contour-closure9255 / 27 / 341 / 379 / 659 / 865 / 868 / 1087 / 1099切口之外不复制像素:用椭圆端帽把切口跨度闭合(端点切线平行于原轮廓)、端帽内取「原图最近的纯填色」平涂、沿新轮廓按猪自己的勾线色/线宽重描;底/顶切口另补 2 条圆底腿
body-graft3104 / 452 / 481只有头的胸像:按头像自己的填色/轮廓色补躯干椭圆 + 2 条圆底腿,头像原样压在上面(头自己的轮廓盖住接缝),头像像素一个未改
head-swap2751 / 974切掉原图黑边后把脸贴到标准猪身体上,切口 8px alpha ramp,脸往身体里挪 10px 后逐图搜 dy

机器可读的同一份记录:写在 manifest 的 completion 字段(每只带 mode / by / note / at)。

校验读数(2026-11-13 实测,报告 archive/verify-completion-and-stability.md):14 只的 bytes/sha256/size 与磁盘逐字节相符、sizeRatio 落在 68.52–102.95、/pighub/asset/<file> 全部 200 且字节数等于清单、 scripts/audit-completeness.py 无切边;接缝(±8 逐列/行中位亮度剖面的最大相邻台阶)13 只 ≤ 3.18, pighub-1099 是 3.18(接缝处 0.00,底边是直线)。

pighub-868 已于 2026-11-13 23:58 单独返修(腹底原本是一条横贯 200px 的平切直边,记录值 144.18): 按「重定义剪影 → 沿新剪影重画 2px 描边」重做了腹底收口,报告 archive/fix-868-belly.md。 两点值得写在这里,因为它们改变了判据本身:

  • 接缝台阶这条判据对它是"已经满足"的:抹暗行那版就已经是 0.00,改后仍是 0.00—— 所以 868 是否修好不能看这个数。真正的证据是腹底缘的平直度:最长严格水平段 42 列 → 12 列, 最长「极差 ≤1px」段 42 列 → 21 列(标准猪同类位置 31 列,折算到同画布宽 15 列),外加 3 倍放大目检。
  • 它现在比房子里的标准猪更有弧度,代价是腿短了约 7 行(腿只有 25 行可让,腹底下沉就得吃腿)。

audit-completeness.py 通过不等于切口不外露:它的判据落在 bbox 最外一行/列,而补出来的腿会把 bbox 撑开, 切口于是变成内部边。判封口要同时看接缝台阶与 3 倍放大图(taste.md §Q.5)。

文档冲突(2026-11-13 核对):本节此前有两张互相矛盾的表,把 868/379/255 记成 bottom-legs、 341/865/659 记成 side-body、974 记成「未完成」。这三种写法在 manifest 里都不存在(974 已完成换头)。 按「以代码为准」的口径改成上面这一张。

标准猪(普通猪)是 standard-pig,也是补全时的形状参考。

标准猪的尾巴(2026-11-14 重画)

标准猪的尾巴原来是错的:它是一根「直条 + 端头」,是当年从侧栏图标(220px 源图)矢量化时丢掉的细节。 按用户给的权威原图 archive/reference-standard-pig-tail.jpg(863×764)重画成螺旋卷尾:

  • 原图量到了什么:那条尾巴是一条带宽 30px(中位;8 个极角 26–41)的带子,绕 1.1 圈后末端压回起始带, 环心映射到 482 画布是 (440,59)、外缘半径 ≈33.5px;原图自己的顶边与右边是贴画布被切掉的。
  • 画成什么:螺旋中心 (438,49)、r0=46px → r_loop=23px、1.10 圈、带宽 20.4→11.6px、描边 2.6px、色 (252,124,132); 臀部背线在 x∈[380,428] 按原图重接。缩放后四边留白 ≥6px(不会重蹈原图被切的覆辙)。 偏离任务书的两点(量出来才改的):带宽按原图 ~16px 而不是 2px(2px 在 96px 显示尺寸上是 0.4px, 屏幕上会消失),环比原图小 ~7%(原图那只被画布切过)。逐条读数见 archive/standard-pig-tail.md。
  • 两只换头猪跟着重跑:751 / 974 用各自的原脸在新身体上重合成,脸一个像素没动 (face_box 与色偏都与 2026-11-13 那次逐字相同;头区只有挖空椭圆边界的 117/166 px、最大差 ≤10/255), 然后自动带上新尾巴。接缝读数与修前逐位相同:974 列 1.0 / 行 1.0,751 列 0.0 / 行 0.33。

图鉴(未获取的猪)

面板右上角「图鉴」按钮打开一个网格,列出池子里全部猪猪(不只是已获取的):

状态显示
已获取彩色贴图 + 原名
未获取暗色剪影(filter:brightness(0) saturate(0); opacity:.28)+ 名字显示 「???」

标题栏显示「图鉴 N 只 · 已收集 M 只」。数据来自快照里的 pool 字段(id / 名字 / 贴图地址,含未获取)。

猪圈视觉(2026-11-14 换成用户给的木栅栏)

围栏不再是自己画的 SVG,而是用户给的一张 1254×1254 木栅栏图,原样入库(assets/img/pen-fence.png, sha256 30b82f48… 与用户给的文件逐字节相同),整幅由 GET /pighub/pen/pen-fence.png 提供。

  • 去白底:这张图的背景本来就是 alpha=0,棱边那条"近白"规则(与 scripts/gif-alpha.py 同一套:只删与画布边缘连通的近白) 跑完命中 0 个像素——所以"去白底前后栅栏像素逐字节一致"是实测出来的 0,不是"没做"。
  • 切两层:同一条水平线(1254 原图第 636 行 = 50.68%,取内圈竖直中点)把图切成上半(远)/下半(近), 每行只属于一层;两层叠回去与单层整图显示空间逐像素 0 差异(scripts/pen-fence-split.py 自带这条断言)。
  • 怎么摆:两层各是一个 overflow:hidden 裁剪盒 + 盒里一张贴顶/贴底的同一张图(background-size:100% 100%)。 不用 clip-path:它的边会抗锯齿,分割线上两层 alpha 都 <1,顺序合成后那条线会亮出来(实测 53 px 宽、绿通道 +14/255)。 溢出裁剪是硬边、按整像素归属,所以叠出来与整图一致(实测 452 px 下 0 差异)。
  • 谁压谁:远栏 1 < 仓库小屋 2 < 猪 3..28(档内按脚底名次排,见上文「猪之间按脚底排前后」)< 近栏 30 < 设置 31 < 图鉴 32。 整档留在 40 以下:猪圈自己没有层叠上下文,越过 40 就会盖到右键菜单/桌宠层(40/41)、抽卡演出(59/60/61)与 toast(62)。 猪的活动区(圆心)= 栅栏内圈各收半个猪身。
  • 草地:只铺在给定红框里(8.37% / 91.47% × 18.26% / 96.65%),红框外不铺草;猪圈自己 background:transparent、 没有描边、没有铺满全圈的叠层,所以草地与围栏之外的区域 alpha=0,直接露宿主页面底色(亮/暗两种底色都实测过)。
  • 猪圈里其余的东西(仓库小屋、踩踏土、草簇)保持原样,只是被红框裁住。逐项读数与三次真机截图见 archive/pen-fence-art.md。

猪圈主题包

猪圈的草地与围栏(远侧/近侧两层)可以整体换掉,默认外观是内置主题 classic。

主题放 ~/.PigHub/themes/<name>/,一个目录一个主题:theme.json(geometry{grass,inner,box} 百分比 + fence{image,split,back,front},缺项逐字段回落 classic)+ 可选的 fence-back.png / fence-front.png / grass.png / house.png。

三种换法:设置里选(立即生效)、把目录丢进 ~/.PigHub/themes/ 后重载、或用设置里的 「更换主题包(.zip)…」 选一个 zip 导入(校验失败会给出可读原因且不动现有主题)。

格式细节见 archive/pen-themes.md。

与其他桌宠插件共存

插件市场上的桌宠(例如 dsh-pet)都是页面级浮层,所以按同一套既有约定来:容器 pointer-events: none、自有 z-index 层、样式标签与类名全带 dsh-pighub / .pighub- 前缀、尊重 prefers-reduced-motion。

验证

npm test                  # 107 项离线断言:契约 / 规则 / HTTP 面 / 成像与描摹 / 浏览器半结构 / 停止契约
npm run assets:build      # 重新生成包内贴图(需要源图;会把处理结果写进 assets/img)

2026-11-14 02:14 实测:smoke 19 / store 16 / host 20 / imaging 13 / client 35 / lifecycle 4 = 107 项(npm test 退出码 0)。 client 多出的 5 条是抽卡演出的(时间轴常量、描述截断、三段演出、点击跳过、reduced-motion), host 的 20 里含「快照带 note」断言与另一条线新增的用例。 同一时刻 node test/smoke.mjs 曾报「素材字节数与清单不符」——那是并行的素材重写(15 张图已写、清单未更), 与本轮无关,读数与时刻见 archive/draw-reveal.md §4。

补全产物与运行时稳定性另有三支探针(_ 前缀,不进管线):

  • scripts/_verify-completion.py:14 只补全猪逐张量「来源轮廓 IoU / 接缝台阶 / audit 完整性 / 元数据 / 3 倍放大图」;
  • scripts/_probe-actor-tick.mjs:把发货 bundle 的 250 ms actor 回调真的跑起来(结构测试把 setInterval 换成了空实现, 回调里的路径零覆盖——ReferenceError 那类缺陷只有它能抓),并做「卸载重挂 20 次,活着的定时器数量不变」的累积检查;
  • scripts/_probe-assets.mjs / _probe-consistency.mjs / _probe-asseturl.mjs:贴图 HTTP 200 与字节对账、 id ↔ 文件名串号、URL 上 ?v= 的幂等性。
  • scripts/_probe-pet-stop.mjs:直接量 stopDesktopPet(不经 Cordis)——优雅停的毫秒数、幂等、以及 「不 await 的 start + 立刻 stop」的启动竞态(必须回 stopped_during_start 且不留进程);
  • scripts/_probe-taskkill-tree.mjs:taskkill /T 与「只杀父进程」的对照实验(本机环境干扰,未能区分,见停止报告 §7);
  • scripts/_868-belly.py:pighub-868 腹底收口的构造与复量(剪影曲线 → 描边距渲染), 默认干跑、--write 才写素材,幂等(在已修好的图上再跑 changed px = 0), 同时报「接缝台阶」与「底缘平直度」两套读数——后者才是这类形状缺陷的判据。

界面另有一套本地验证台(不随仓库分发、不进 npm 包):它按宿主契约把 lib/client.js 挂到普通页面上,并埋四个探针——

  • alpha:把渲染出来的图重画到 canvas 逐像素读四角 alpha,证明白底真被抠掉;
  • motion:4.2 秒前后各采一次落脚点,分别统计会动的猪 / 静止的猪 / 桌宠移动了多少只;
  • reveal:自动点一次「今日猪猪」,采样动画阶段并比较落点与真身中心的像素差;
  • svg:统计以 data:image/svg+xml 渲染的图数量,确认矢量化的就是那些图。

当前基线:live=1/1 dead=0/4 pets=1/1(验证台内部计数口径)、会动的猪四角 alpha 全 0、landGapPx=0、svg=2。

发布

走 GitHub Actions + npm Trusted Publishing,仓库里不放长期 token:pack job 无凭据校验 tag 与版本并跑全部测试,publish job 消费同一份 tarball,用 OIDC 换短期凭据发布并生成 provenance。npm 后台三项匹配(仓库 / publish.yml / npm-publish)任一不符都会被拒。

素材来源与许可(重要)

唯一可信源:PigHub(pighub.top 猪猪表情包库)。全部素材只从该库采集、逐图精修,其余仓库一律不采集(登记在 assets/libraries.json,只作为「为什么不用」的记录)。

逐仓库核过 GitHub 的 license.spdx_id 后,结论是没有一个可信的猪图开源库:三个真图库(pighub.top / PigHub-DB / PigPicPot)都没有数据许可,rollpig-resources 明文禁止再托管,MIT 的仓库只有文字资料没有图。

本包内的图因此按 inherited-risk 记录(用户已知悉),出处与指纹见 assets/ATTRIBUTION.md,机器可读的判定见 assets/libraries.json。

许可

  • 本插件代码:MIT,见 LICENSE。
  • 上游 PigHub 素材:未声明数据许可。本包含处理后的贴图字节(assets/img/,构建期去底/裁切后的产物),按 inherited-risk 记录(用户已知悉);出处与指纹见 assets/ATTRIBUTION.md。若上游给出许可条款,以它为准。

版本变化见 CHANGELOG.md。

相关插件