dsh-pet-guardian-dragon
DSH Web UI 桌宠 —— 形态 A「少女主体 + 守护龙影」。
右下角悬浮（可拖拽）与标题栏常驻双模式，右键即切。零构建、零依赖、不碰 DSH 核心。
本项目是个人学习、作品展示与开源交流项目，不以盈利为目的；代码与美术素材分开授权，
且美术素材不是可自由复用的资源（详见文末「许可」）。
它做什么
| # | 动作 | 实现 |
|---|
| 1 | 待机循环 | 呼吸缩放（dg-breathe，3.4s）。整体摇晃 dg-sway 与整体浮动 dg-float 均已移除，待机不再左右摆动、也不再整体上下平移 |
| 2 | 拖拽反应 | 按住拖动改变位置；按累计横向位移驱动四帧步态循环（walk-1 → walk-2 → walk-3 → walk-4），步幅 32px、帧间交叉淡化 0.1s；松手后按速度惯性收步（1–2 帧）再回待机。拖拽中不做 rotate 倾斜 |
| 3 | 点击互动 | 位移 < 6px 判定为点击 → 切到「回眸」专属立绘，同时保留翻面+提亮（dg-lookback）变换 |
| 4 | 投喂反馈 | 双击宠物 / 右键「投喂爱心」/ 点击标题栏头像 → 切到「投喂」专属立绘 + 爱心粒子上升 + 紫光爆闪，好感度 +2 |
| 5 | 成长进阶 | 好感度分 3 档（Lv1 / Lv2 ≥10 / Lv3 ≥30）：Lv2 起紫炎光环脉动，Lv3 起光环加强并出现上浮火星（属特效层，按约定保留 CSS） |
回眸 / 投喂 / 走路四帧的专属立绘由 art/gen-actions.py 生成，详见下文「动作立绘变体」。
状态还会跟着会话实时变化：会话运行中浮动与摆动明显加速；一轮结束自动播放庆祝并 +1 好感度。
好感度、投喂次数、位置、尺寸、模式全部持久化在 localStorage。
交互速查
| 操作 | 效果 |
|---|
| 拖动 | 移动位置并播放四帧步态循环；松手后按速度惯性收步再回待机（位置在松手时才保存） |
| 单击 | 回眸 |
| 双击 | 投喂爱心 |
| 右键 | 在点击处弹出菜单：投喂 / 切换悬浮↔标题栏 / 显隐 / 放大尺寸 / 缩小尺寸 / 归位 / 重置好感度 |
| 关菜单 | 点菜单外的任意位置、按 Esc、或选中任一菜单项 |
| 悬停 | 显示好感度 HUD |
文件结构
dsh-pet-guardian-dragon/
├── LICENSE # 代码许可（MIT，仅覆盖代码）
├── ART-LICENSE.md # 美术素材许可（非商业；再分发授权待核实）
├── THIRD-PARTY.md # 第三方组件 / 生成模型 / 服务的许可与来源说明
├── package.json # dsh.client 声明：platform:'web' + inject（bundle.patch 已刻意移除，见下）
├── cordis.patch.yml # profile 层：一条 insert 行
├── lib/
│ ├── index.js # 宿主半边（纯客户端插件，apply 有意留空）
│ └── client.js # 浏览器半边（生成物，勿手改）
├── src/
│ └── client.template.js # 浏览器半边源码（手写）
└── art/
├── gen.py # NVIDIA FLUX.1-dev 生图客户端（纯标准库 + 全黑守卫）
├── gen-actions.py # 动作立绘变体（每动作一次独立调用；复用 gen.py 的密钥与全黑守卫）
├── cutout.py # 绿幕抠图（阈值自动标定 + 去绿溢 + 补孔洞）
├── build-art.py # 贴 512 方画布 → webp；优先用 art/src/ 外部生图
├── build-client.py # 注入美术 + 套官方 lazy-CJS 外壳 → lib/client.js（node 自动探测，可用 --node 指定）
├── check-patch.cjs # 校验 cordis.patch.yml（自动定位 profile，可用 --patch/--yaml/--profile 覆盖）
├── smoke-test.cjs # 无头冒烟测试（迷你 React，159 项断言，含交互与立绘切换）
├── inspect_image.py # 图片体检（**刻意不叫 inspect.py**，见下）
├── grep-asar.cjs # 在 app.asar 里搜字符串并打印上下文（查 slot 声明用，可用 --asar 覆盖）
├── src/ # 外部生图产物（透明底 PNG 放这里）
└── out/ # 素材产物（webp + png 预览）
命名教训：这个目录里原来有个 inspect.py，与 Python 标准库的 inspect 重名。
运行 python art/<任意脚本>.py 时脚本目录会进入 sys.path[0]，于是 numpy 内部的
import inspect 加载到了它；而它没有 __main__ 守卫，导入即执行，随后 numpy 因拿不到
inspect.cleandoc 崩溃，报错位置完全指不到真正原因。现已改名 inspect_image.py。
工具脚本不要用标准库模块名，并一律加 __main__ 守卫。
重新构建
# 1) 素材：优先用 art/src/ 下的外部生图；三张齐了就不需要参考图
python art/build-art.py # 有参考图时也可传路径作为兜底
# 动作变体（可选，需要出网提权）
# python art/gen-actions.py --method auto --seed 7
# 2) 客户端 bundle
python art/build-client.py # 会跑 node --check 自校验（node 自动探测，找不到可用 --node 指定）
# 3) 语法自检
node --check lib/index.js && node --check lib/client.js
# 4) 无头冒烟测试（接线 / 渲染 / 分档 / 交互 / 立绘切换 / CSS 一致性）
node art/smoke-test.cjs
# 5) 配置层可解析性
node art/check-patch.cjs
工具脚本的路径解析（不再硬编码个人目录）
三个工具脚本的路径一律按 命令行参数 > 环境变量 > 自动探测 解析，原有「不带参数直接跑」的用法保持不变：
| 脚本 | 命令行参数 | 环境变量 | 自动探测 |
|---|
art/build-client.py | --node <node 可执行文件> | DSH_NODE / DSH_DESKTOP_NODE / NODE_BIN | PATH 里的 node、DSH Desktop 自带 node（%APPDATA%\dsh-desktop\harness\.desktop-bin 等） |
art/check-patch.cjs | --patch / --yaml / --profile | DSH_PATCH_FILE / DSH_JS_YAML / DSH_PROFILE_DIR（或 DSH_WEB_PROFILE） | %APPDATA%\dsh-desktop\harness\profiles\web，并逐级 require.resolve('js-yaml') |
art/grep-asar.cjs | --asar <app.asar> | DSH_ASAR | %LOCALAPPDATA%\Programs\DSH Desktop\resources\app.asar、%ProgramFiles%\DSH Desktop\... |
找不到路径时脚本会打印尝试过的全部位置并以退出码 2 失败，不会静默跳过。
唯一的例外是 build-client.py 的 node：它只用于产物语法自检，找不到时会退化为括号配对粗检并明确提示。
生图与抠图（NVIDIA FLUX.1-dev）
美术已从「参考图裁切」升级为真生图 + 真抠图。三个素材各自独立生成，因此天然可分层。
为什么是「绿幕 + 抠图」而不是直接出透明图
实测该模型只返回 JPEG（无 alpha 通道），width/height 也只接受 768…1344 的固定档位。
所以透明底必须走「纯色幕布 + 后期抠图」。选择绿色是因为形态 A 的配色（银发 / 白紫裙 /
粉花 / 黑镰刀 / 紫眼）完全不含绿，色度上可干净分离。
实测确认的接口契约
| 项 | 值 |
|---|
| 端点 | POST https://ai.api.nvidia.com/v1/genai/black-forest-labs/flux.1-dev |
| 鉴权 | Authorization: Bearer <NVIDIA_API_KEY>（nvapi- 开头） |
| 必填 | prompt |
| 尺寸 | width/height ∈ {768, 832, 896, 960, 1024, 1088, 1152, 1216, 1280, 1344} |
| 步数 | steps ≥ 5 |
| 禁用 | aspect_ratio 等额外字段会 422 extra_forbidden |
| 响应 | {"artifacts":[{"base64":"<JPEG>"}]} |
| 速度 | 896×1216 / 28 步约 12 秒 |
同账号下 stabilityai/* 系列返回 Function … Not found for account（未开通），
FLUX.1-dev 与 flux.1-kontext-dev 可用。
两个必须知道的坑
- 静默全黑输出。某些提示词下接口会返回 HTTP 200、JSON 合法、但内容是纯黑图
（1024×1024、约 6.3 KB、最亮像素 0），且耗时明显更短（2.5–6 s vs 正常的 9–12 s）。
实测 8 次里，含
violet 措辞的 4 次全部触发，不含的 4 次全部正常
（purple 不受影响）。art/gen.py 已加全黑守卫：检测到就报错并拒绝写出文件，
避免把黑图当成素材（可用 --allow-blank 强制）。
- 抠图阈值必须自动标定。不同提示词/种子出来的幕布绿色深浅差别很大——实测少女图边缘
绿优势度 67、头像 88，而龙首只有 37。写死阈值会让浅绿幕布的背景被判成半透明
（bbox 收不紧、边缘留一层绿雾）。
art/cutout.py 现在从画面边缘环带的中位数自动推导
lo/hi，并会提示「几乎检测不到绿幕」。
工作流
# 1) 生成（需要出网；见下方「沙箱注意事项」）
python art/gen.py --preset girl --seed 7 --out art/out/gen/girl-raw.jpg
python art/gen.py --preset dragon --out art/out/gen/dragon-raw.jpg
python art/gen.py --preset avatar --seed 21 --out art/out/gen/avatar-raw.jpg
# 2) 绿幕抠图（自动标定阈值；--check 会输出品红底叠加预览便于目视验收）
python art/cutout.py art/out/gen/girl-raw.jpg art/src/girl.png --check art/out/gen/girl-check.png
# 3) 统一贴到 512 方画布（不需要参考图）
python art/build-art.py
python art/build-client.py
art/gen.py 内置三套提示词（girl / dragon / avatar）。头像提示词必须强锚定
「2D / 赛璐璐 / 非 3D」，否则模型会飘到 3D 写实风，和全身立绘不是同一个角色（实测踩过）。
动作立绘变体（art/gen-actions.py）
「回眸」「投喂反应」以及走路四帧（walk-1 … walk-4）各自使用专属立绘，不再只是同一张图加 CSS 变换。
拖拽已由「按鼠标横向速度 rotate 倾斜」改为「四帧步态循环」，细节见下。
产物：art/src/girl-lookback.png、girl-feed.png、girl-walk-1.png … girl-walk-4.png。
（girl-lean.png 仍会生成，但客户端已不引用，保留以便回退。）
# 生成动作变体（先试图生图 → 按实切换文生图 → 自动走 cutout.py 抠图）
# 默认生成客户端实际使用的六张：lookback / feed / walk-1 .. walk-4
python art/gen-actions.py --method auto --seed 7
python art/build-art.py # 贴 512 方画布（会打印每个产物的来源）
python art/build-client.py
走路四帧（walk-1 … walk-4）
四帧由同一模板拼接，只替换左右腿描述与重心高度：contact（触地）与 passing（过腿）
各出 A / B 两帧，B 帧 = A 帧的 left/right 对调。
WALK_PROMPT = ("Anime character in a walk cycle {pose} pose, {legs}, {arms}, "
"torso at its {torso} point, body upright and facing forward. "
"Her black-purple scythe ... stays resting on her right shoulder ... "
"Wearing a white and purple off-shoulder gown ... Plain green background.")
WALK_POSES = {
"A": {"pose": "contact", "legs": "left leg stepping clearly forward, right leg "
"stretched clearly behind, a wide readable stride", "torso": "lowest", "seed": 401},
"B": {"pose": "passing", "legs": "right knee lifted clearly in front with the foot "
"well off the ground, left leg straight and vertical", "torso": "highest", "seed": 402},
}
assert_walk_frames_consistent() 在每次运行时自检：把各自的腿描述替换成占位符后，
两段提示词必须完全相同，否则直接报错退出。这样「只改左右腿」这条约束由代码保证，
而不是靠人工核对。
两个必须钉住的地方（都踩过）
纯文生图没有参考图，模型会逐帧重新决定提示词没写到的细节，于是出现两类逐帧闪烁：
| 现象 | 根因 | 修法 |
|---|
| 镰刀在「扛肩」与「竖抱身前」之间跳变 | 提示词完全没提镰刀，而 arms 槽位让手臂自由摆动 | 加 scythe ... stays resting on her right shoulder ... do not move or shift the scythe，并把 arms 槽位改成「右手扶着肩上的镰刀」 |
| 整身服装漂成紫色长外套 | 我加的 bare feet 与设定表的 white stockings 直接矛盾，服装线索自相冲突 | 删掉矛盾项，把服装描述逐字复述并置于句末（扩散模型对末尾 token 权重更高） |
另外步幅描述不能太保守：早先写「left heel striking the ground in front」时，左右对调后
两帧看起来几乎一样，走路节奏根本读不出来。现在写成「clearly forward / stretched clearly
behind / knee lifted clearly with the foot well off the ground」，配合 STRIDE_PX = 32
才有可辨的踏步感。
关键发现 1：kontext 图生图在本账号上不可用
任务原本指定用 flux.1-kontext-dev 做图生图。实测该端点只接受服务端预注册的
example_id，不接受任意图片字节，因此无法拿我们自己的立绘作输入：
| 请求 | 结果 |
|---|
image = 裸 base64 | 422 Image has been provided in the invalid form |
image = data:image/jpeg;base64,<真实图> | 422 Expected: example_id, got: base64 |
image = data:image/jpeg;example_id,0 / ,1 | 200，但输出是纯黑图（mean=0、max=0、6.5 KB） |
image = data:image/jpeg;example_id,自定义值 | 500（查不到该示例） |
flux.1-dev + image | 422 Image input is not supported in the base mode |
flux.1-dev mode=canny/depth + 图片 | 同样报 Expected: example_id, got: base64 |
| 另外 12 个图片编辑模型名 | 404 模型不存在 |
flux.1-dev 的 mode 枚举经报错确认为 'base' / 'canny' / 'depth'，图片输入只在
canny/depth（控制图）下被接受，且同样只认 example_id。该账号没有可用的图生图能力。
因此 gen-actions.py 的 --method auto 会先如实尝试指定路径、打印确切拒绝原因，
再切换到 flux.1-dev 文生图；--method img2img 可强制只走原路径（会如实失败）。
关键发现 2：violet 会触发静默全黑
同 seed、同尺寸步数，仅一处措辞差异：
| 提示词 | 结果 |
|---|
...violet eyes... | 静默全黑：HTTP 200、最亮像素 0、6.5 KB、4.0s |
...purple eyes... | 正常：118.9 KB、最亮像素 255、8.0s |
任务给的动作提示词里含 violet eyes，正是触发词。gen-actions.py 因此保留动作原文、
只在构建提示词时做等价替换（violet → purple）并在日志里说明改了什么。
关键发现 3：锁 seeds 是文生图下抑制身份漂移的最强杠杆
文生图没有参考图，角色设计由基础噪声极大决定。用每个动作各自的 seed（101/202/303）时，
发型与服装设计明显漂移；改用原始立绘的 seed=7 后，四张图明显是同一个角色
（发色/瞳色/精灵耳/皇冠+蓝花/白紫裙配粉色花边/同一把镰刀/同样的袜纹一致），
差异只在姿态与表情。所以默认建议 --seed 7。
客户端如何切换
POSE_SRC 把非走路状态映射到立绘：idle / lookback / feed / lean，任一图缺失都回退到
待机立绘，不会出现空白。走路四帧单独走 WALK_FRAMES（顺序 [walk-1, walk-2, walk-3, walk-4]，
同样逐张回退到待机）。
渲染优先级：走路激活时 → 走路帧；否则 → 当前姿态帧。走路帧用独立状态 walkState
（而非复用 pose），这样 lookback/feed 的定时回落不会在拖拽中途把帧改回待机。
步态驱动（常量集中在模板顶部）：
| 常量 | 值 | 作用 |
|---|
STRIDE_PX | 32 | 步幅。相位 = 累计横向位移 ÷ 32，帧号 = floor(相位) % 4 |
FRAME_LIFT_PX | [0, -2, 0, -2] | 四帧各自的纵向偏移，模拟重心起伏 |
SETTLE_STEP_MS | 95 | 收步时每帧停留时长 |
SETTLE_FAST_PX | 12 | 松手速度 ≥ 12 收 2 帧；> 0 收 1 帧；静止则立即回待机 |
pointerdown → 进入走路、从当前帧起步；纯点击（位移 < 6px）不计步pointermove → 按累计位移推进/回退帧号；左右朝向由外层 scaleX(±1) 承担
（四帧本身都面朝前，镜像即可表示向左/向右走），该变换刻意放在不带 transition 的外层，
以免跨零翻转时被插值成一条缝pointerup → 按松手速度进入异步收步链（setTimeout 逐帧推进，走完才回待机）；
位置只在此时落盘
帧切换的视觉处理：.dg-walk-lift 承担 translateY(FRAME_LIFT_PX[i])（0.1s ease-out），
新帧以 .dg-walk-fade 叠在旧帧上做 0.1s 交叉淡化，避免硬切闪帧。
其余切换与既有 CSS 特效同一时机：
- 点击（位移 < 6px）→ 换「回眸」立绘，同时保留原有的翻面+提亮 CSS 变换
- 投喂 / 一轮结束 → 换「投喂」立绘，同时保留原有的发光与爱心粒子
按任务约定，待机微动与成长进阶仍走 CSS（微动幅度无法用文字传达；光环/火星属特效层），
而拖拽不再做 rotate 倾斜；整块 dg-sway 整体摇晃与 dg-float 整体浮动均已移除。
密钥存放
按优先级读取：--key-file > 环境变量 NVIDIA_API_KEY > <工作区根>/.nvidia-key。
密钥刻意放在工作区根目录而不是插件目录内，这样交付物里不含任何凭据。
（注意：密钥曾在对话里以明文出现过，介意的话建议在控制台轮换一次。）
沙箱注意事项（重要）
任何子进程的出网 HTTPS 都需要提权（danger-full-access），否则 TLS 握手一律失败：
| 调用方 | 报错 |
|---|
curl.exe | schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS (0x8009030e) |
PowerShell Invoke-WebRequest | 基础连接已经关闭: 接收时发生错误（内层同为 SEC_E_NO_CREDENTIALS） |
Python urllib | SSL: UNEXPECTED_EOF_WHILE_READING |
但 DNS 解析与 TCP 443 连接都正常（Test-NetConnection 成功、裸 TcpClient 能连上），
所以这不是网络问题，而是沙箱阻止了进程获取 TLS 客户端凭证。注意 Python 用的是内置
OpenSSL 而非 Windows Schannel，同样被拦 —— 说明限制在更底层。提权后 curl 与 Python 均
正常（HTTP 200、模型列表 80 个）。
排查中排除掉的两条歧路，避免重复踩：TLS 版本（显式设置 SecurityProtocol 到
Tls12/Tls13 无效）与本机 HTTP 代理（IE 系统代理开着，但绕过代理直连同样失败）。
接入任意生图模型（不需要改代码）
美术管线与具体生图模型完全解耦。把模型产出的图按固定文件名放进 art/src/，build-art.py 会自动优先使用：
| 文件 | 内容 | 建议 |
|---|
art/src/girl.png | 少女主体 | 透明底全身立绘 |
art/src/dragon.png | 守护龙影 | 透明底 |
art/src/avatar.png | 标题栏头像 | 方形、透明底 |
判定规则：
- 存在且确实含透明像素 → 视为真抠图，直接使用，不加任何遮罩（理想路径，发丝/裙摆/龙影都能保住）
- 存在但不含透明通道 → 退回软边圆角遮罩并打印提示，避免出现硬边矩形
- 不存在 → 用参考图裁切结果兜底
三张齐了之后参考图可以完全不传：
python art/build-art.py # 不需要任何参数
python art/build-client.py
支持 .png / .webp / .jpg（alpha 只可能存在于前两者）。每个产物都会打印来源，便于确认到底用了哪一张：
girl : girl.webp 512x512 34.0 KB <- art/src/girl.png（外部生图·含透明通道）
所以换模型时只需替换 art/src/ 下的图并重跑两条命令，零代码改动。
安装
# 1) 拷进 profile 的 node_modules
$H = "$env:APPDATA\dsh-desktop\harness"
$P = "$H\profiles\web"
Copy-Item -Recurse -Force . "$P\node_modules\dsh-pet-guardian-dragon"
# 2) 在 $P\cordis.patch.yml 末尾追加
# - insert:
# - id: dsh-pet-guardian-dragon
# name: 'dsh-pet-guardian-dragon'
配置层支持热重载；改完硬刷新浏览器（Ctrl/Cmd+Shift+R）。客户端产物缺失或语法错误会让 dsh web 拒绝启动，所以务必先跑 node --check。
回滚：删掉 node_modules\dsh-pet-guardian-dragon 并移除 patch 里的 insert 行。
为什么是手写 bundle 而不是打包
开发环境里 git / npm 不可用，pnpm 又因受限环境禁止子进程命名管道而 spawn EPERM，因此无法克隆仓库或安装依赖。而官方的 clientBundle 预设位于 DeepSeek Harness 仓库的 packages/client/tsdown.client.ts，不在任何已发布包里，仓库外本来就无法复刻。
于是直接照抄官方预设的产物形状手写：
window.__ModuleLoader__.load({ id: "<包名>", factory: (require) => {
var module = { exports: {} }; var exports = module.exports;
/* bundle body */
return module.exports; } });
对应 packages/client/tsdown.client.ts 的 outputOptions.banner / intro / footer。可 require 的平台模块表见 packages/client/web/src/platform.ts（react、react-dom、@deepseek-ai/cordis、@deepseek-ai/dsh-client-ui-slots 等）。
挂载点（已在运行中的 DSH 上实测确认，非推测）
| 模式 | slot | 声明方 | cardinality / scope |
|---|
| 右下角悬浮 | shell.overlay | @deepseek-ai/dsh-client-ui-layout | kind: "list" / scope: "root" |
| 标题栏常驻 | conversation.session.header.actions | @deepseek-ai/dsh-client-ui-conversation | list / session |
shell.overlay 的声明是从运行中的 ui-layout client bundle 里直接读出来的：
ctx.slots.register({ name: "root", children: {
"sidebar": { kind: "single", scope: "root" },
"main": { kind: "keyed", scope: "root" },
"rightbar": { kind: "single", scope: "root" },
"shell.overlay": { kind: "list", scope: "root" }, // ← 本插件挂这里
"shell.leading": { kind: "single", scope: "root" },
} }, AppFrame)
因为它是 list（以必填 id 定址、按 order 排序），追加成员不会与既有 occupant（shell.quota-notice）冲突。
状态来源
@deepseek-ai/dsh-client-ui-session 通过 ctx.slots.provideRoot 注入标准 props：
hooks: { sessions: ctx.sessions.list, sessionStatus: service.sessionStatus }
对应组件 props 为 useSessions / useSessionStatus，其中 sessionStatus 是 Map<sessionId, {running}>。文档说明这两个 hook 在所有 scope 可用，因此 root 作用域的 shell.overlay 也能直接拿到运行状态——不需要标题栏、不需要 IPC、不需要 MCP，而且没有打开会话时也能反映其它会话的运行情况。
已验证的运行时事实
| 验证项 | 结果 |
|---|
| 插件是否进入启动图 | ✅ window.__DSH_BOOT__.entries 含 dsh-pet-guardian-dragon |
| 是否需要重启 DSH | ✅ 不需要，patch 层热重载即生效 |
| bundle 是否被真正提供 | ✅ GET /plugins/??dsh-pet-guardian-dragon/client.js&rev=… → 200 |
| 宿主是否感知产物更新 | ✅ rev 随产物变化：9a54… → 579c… → de75… → 15488a3dbad9 |
| 代码能否真的正确执行 | ✅ 无头冒烟测试 159 项断言全通过（PASS=159 FAIL=0），含 5 个动作、右键菜单、四帧步态相位、收步链、尺寸步进 |
shell.overlay 是否可安全使用 | ✅ 从运行中的 ui-layout 读到 {kind:"list", scope:"root"} |
| 悬浮层是否会被裁剪/错位 | ✅ 抽 CSS 逐项排除（见上节） |
| 配置层是否仍可解析 | ✅ 用 harness 自带的 js-yaml 解析通过，原有条目完好 |
| 产物语法 | ✅ node --check 通过，纯 ASCII |
| 是否弄坏宿主 UI | ✅ 日志里没有本插件的任何错误/告警/畸形声明 |
悬浮层几何：为什么 position:fixed 是安全的
shell.overlay 渲染进 ui-layout 的这个容器（CSS 已从运行中的 bundle 里抽出）：
.pI_x6G_overlayLayer { position:absolute; inset:0; z-index:20; pointer-events:none }
.pI_x6G_overlayLayer > * { pointer-events:auto }
.pI_x6G_frame { position:relative; overflow:hidden; display:grid; height:100% }
排查结论（逐项实测，非推测）：
| 风险 | 结论 |
|---|
祖先有 transform / filter / perspective / will-change / contain / backdrop-filter / isolation → fixed 会改以该祖先为包含块 | ✅ 全部不存在，因此 fixed 相对视口解析 |
frame 的 overflow:hidden 会裁剪宠物 | ✅ 不会。裁剪只作用于包含块链上的祖先；fixed 的包含块是视口，故不受影响 |
| 宠物挡住它后面的 UI | ✅ 已处理：外层 pointer-events:none，本插件 .dg-root{pointer-events:none} + .dg-stage{pointer-events:auto}，只有宠物本体可点 |
| 与既有 occupant 抢位 | ✅ 该槽是 kind:"list"，以必填 id 定址，不冲突 |
无头冒烟测试
冒烟测试不依赖浏览器，也不需要解包 app.asar 去 require 里面的 React，因此 art/smoke-test.cjs 自带一个确定性迷你 React，把 lib/client.js 里真实的 factory 物化、真实的 apply 执行、真实的组件渲染一遍。
node art/smoke-test.cjs # 当前 159 项断言全部通过（PASS=159 FAIL=0）
覆盖内容：
- 产物只请求平台模块（
require 白名单里只有 react，请求别的立即失败）
apply 往 shell.overlay 与 conversation.session.header.actions 注册，id/order/name 正确- 渲染结构：
.dg-root / .dg-stage / .dg-dragon / 内联美术 ×2 / 3 颗火星 / HUD / 拖拽与点击右键钩子
- 成长分档：好感度 0 →
data-tier=1、12 → 2、35 → 3，文案同步
- 模式切换：float 时 overlay 可见、chip 隐藏；header 时相反
- 状态选择器：对
Map（全跑/全停/混合）、Array、普通对象、undefined、42 都给出正确布尔值
- CSS 一致性：渲染出的类名全部有对应规则；8 个关键帧齐全；
.dg-root 为 fixed；三档成长都有视觉差异；
并断言 @keyframes dg-sway 已移除、无 .dg-sway 规则、无 .dg-drag 动画覆盖规则（待机不摇晃 / 拖拽不改周期）
- 降级路径：缺
useSessionStatus（老版本 DSH）仍能渲染；缺 ctx.slots 时安全返回
- 交互行为（用例 G，真正调用事件处理器）：
- 拖拽：位置改变、按下即切入走路帧、累计位移每满 32px 推进一帧、走满四帧回到第一帧、
不足一个步幅不换帧、来回拖按绝对位移累计、方向翻转体现为
scaleX(±1)、
松手不瞬回待机（进入按速度决定的收步链）、只在松手时落盘（pointermove 不写 localStorage）、
.dg-drag 增删、拖拽中不再写 rotate
- 点击：位移 < 6px 判定为点击 → 回眸 class，且不改位置
- 投喂：双击 → 投喂 +1、好感度 +2、发光 class、生成 6 颗爱心粒子
- 成长：好感度 9 → tier1；投喂后 11 → 重新渲染确认真进阶到 tier2 且显示 Lv2
- 会话状态：空闲不加运行态 class；运行中加
dg-thinking/dg-working；一轮结束播放庆祝、好感度 +1、回合数 +1
- 右键菜单（用例 H，回归测试）：
- 菜单是
.dg-root 的直接子元素、不是 .dg-stage 的后代（这条直接钉住曾经的 bug）
- 出现在右键点击处，并夹在视口内
- 按钮点击真的生效（切模式 →
state().mode === 'header'）
- 点菜单外关闭、按
Esc 关闭、选中项后关闭
- 菜单内部按下不关闭（否则按钮的
click 会失去目标）
曾经的真实 bug（已修）：菜单原先是 .dg-stage 的子元素，而 .dg-stage 的
onPointerDown 会 setPointerCapture()（把后续指针事件重定向到 stage）并
preventDefault()（抑制兼容性鼠标事件），于是菜单按钮的 click 永不触发；
而菜单唯一的关闭途径就是那些按钮，结果点不动也关不掉。修法是把菜单移出
.dg-stage 并补上外部点击 / Esc 关闭。注意「按钮有没有 onClick」在旧代码上
也是通过的——这类 bug 只有结构断言与关闭行为断言才抓得到。
-
尺寸放大 / 缩小（用例 J，回归测试）：
- 原先只有一个循环按钮（120→160→200→240→280→跳回 120），尺寸只能一路变大，
绕回小尺寸之前无法往回缩。现拆成「放大尺寸」「缩小尺寸」两个显式项，
并钳制在
SIZE_MIN=120 / SIZE_MAX=280（步长 40）
- 断言：默认 160 时「缩小」可用且点一次变 120；到下限后该项禁用且强制点击不越界；
连点四次「放大」到上限 280；到上限后「放大」禁用且不跳回小尺寸（旧行为正是跳回 120）；
再连点四次「缩小」回到 120
-
立绘切换（用例 I）：
- 待机立绘非空，且七张立绘全部是内联
data: URI（不依赖任何外部请求）
- 拖拽开始即切到走路帧；位移未达一个步幅时保持同一帧（不会抖动式乱切）
- 累计 32px → 推进到第二帧；四帧依次推进且互不相同；走满四帧回到第一帧（步态循环）
- 拖拽中不再写
rotate；松手不瞬回待机（进入收步）
- 轻点 → 切到「回眸」帧，且收步链不会把动作立绘顶掉；投喂 → 切到「投喂」帧
- 待机 + 走路四帧 + 回眸 + 投喂共七张两两不同 —— 专门防止某张缺失时静默回退成同一张却看不出来
-
收步链（用例 K）：
- 松手时仍在运动 → 不瞬回待机，收步期间帧序号单调前进，走完才回待机且淡出层被移除
- 松手瞬间完全静止 → 立即回待机（不进入收步）
- 收步未走完就重新按下 → 旧收步链被掐断，帧停在新按下的位置（防止两条链互相打架）
为了让行为可测，测试里的迷你 React 实现了几处保真细节：hook 状态按组件类型跨渲染复用
（否则 useRef 每次新建，「上一轮是否在运行」这类跨渲染逻辑根本测不到）、DOM 节点按树中路径跨渲染复用
（真实 React 会复用节点，命令式 classList.add('dg-drag') 才能在重渲染后保留；早先每轮新建节点会让这类改动凭空消失，
既造成假失败也会掩盖真实 bug）、提交后冲刷 effect 并先执行上一轮清理、以及带 classList /
style.setProperty / ref 的假 DOM。
已知限制（诚实清单）
- 美术是真生图 + 真抠图，但仍非「分部件骨骼动画」。现在是 NVIDIA FLUX.1-dev 生成、绿幕抠出的独立透明素材（少女主体 / 守护龙影 / 头像 256 / 回眸 / 投喂 / 走路四帧），龙影作为独立元素浮游并参与点击回眸与投喂特效。但每张素材是整图而非分层（发丝/裙摆没有单独图层），因此走路是用四帧整图按相位循环模拟踏步，而不是骨骼驱动的连续步态；发丝与裙摆也没有独立运动。
- 动作变体是文生图产物，不是真正的图生图。任务原本指定 kontext 图生图，但该端点在本账号上只接受预注册的
example_id（完整实测见上文），所以所有变体都是用锁定的角色设定表 + 原始种子 seed=7 独立生成的。各帧在发色/瞳色/精灵耳/皇冠+蓝花/裙装配色/镰刀上一致，但并非像素级同一角色：皇冠尖角形状、裙摆纹样细节、鞋子等仍有小幅差异；走路四帧之间也存在这类差异。更麻烦的是模型会逐帧重新决定提示词没写到的细节——镰刀怎么拿、穿不穿鞋——所以姿态提示词必须显式钉住道具与服装（见上文「两个必须钉住的地方」）。若日后该账号开通了真正的图生图能力，把 gen-actions.py --method img2img 接上即可，脚本与后续管线都不用改。
- 走路是四帧相位驱动，不是逐帧动画。contact-A / passing-A / contact-B / passing-B 四个关键帧按累计横向位移循环，帧间靠 0.1s 交叉淡化与 2px 纵向起伏过渡。再提高流畅度就要为更多相位生成独立立绘，成本线性增长，且每多一帧都会推高内联体积（当前四帧合计约 116 KB）。
- 思考与干活未区分。两者都由「有会话 running」驱动，只是动画速度不同。要区分需要读推理 partial / 运行中工具（
useConversation 的 views.get('chat').legacy），但该 hook 只在 session 作用域可用，悬浮层的 root 作用域拿不到，需要额外设计。
- 未做 Live2D。当前是静态图 + CSS 变换。要真 Live2D 需引入
pixi-live2d-display 与 Cubism Core，并注意模型与 Cubism 的商用授权条件。
- 未在真实浏览器里目视确认。启动图与资源提供都已验证，但「桌宠画出来、拖得动、特效正确」需要你在浏览器里目视确认。代码已包在 React 错误边界里：万一某个 DSH 版本的 slot 契约变化导致渲染抛错，只让桌宠消失，不会连累 AppFrame。
dsh.client.inject 的改动要重启才生效。启动图里当前仍是最初声明的三个 inject 边（宿主对包元数据有缓存）。实测这三个包都存在且组合成功，所以留着也无害；下次重启后会变成空列表。- 走的是 patch 层挂载，未进 profile 清单。DSH Desktop 有一项 profile 一致性审计，它看的是
profiles/web/package.json（dependencies / dsh.profile.bundles），不认 patch 层。所以它可能记一条 profile inconsistency: … is installed but declared nowhere in the profile manifest。实测这不影响加载（本插件确实进了启动图并被正常提供），当前日志里也没有本插件的此类记录。若想彻底消除，等 pnpm 可用时执行 dsh plugin --profile web add link:<本目录绝对路径> 即可（受限环境下禁止子进程命名管道，pnpm 会报 spawn EPERM，因此这一步无法在受限环境中完成）。
许可
本项目是个人学习、作品展示与开源交流项目，不以盈利为目的，采用代码与美术分离的授权结构，
两者不共用同一许可：
| 内容 | 许可 | 文件 |
|---|
代码（lib/index.js、src/client.template.js、art/*.py、art/*.cjs、配置与文档） | MIT | LICENSE |
美术素材（art/src/*.png、art/art-data.json，以及 lib/client.js 中内联的立绘数据） | 单独的素材许可：非商业，且再分发尚未授予、授权链待核实 | ART-LICENSE.md |
- 代码版权：
Copyright (c) 2026 lucas07814。
- 美术素材不是 MIT 许可：代码的 MIT 许可不会自动扩展到素材。
- 本仓库不是可自由复用的素材库：素材的生成模型与生成服务授权链尚未核实，在核实完成前
不应将素材视为已获准自由再分发；商业使用与再分发均需另行取得作者的书面授权。
- 第三方组件、生成模型与生成服务的来源与许可（含仍标注「待核实」的条目）见 THIRD-PARTY.md，
其条款以各上游官方原文为准；其中模型输出许可与生成服务分发许可彼此独立，不互相替代。
