[Plugin] 蓝毛小女仆 / cute-fat-fish-pet — a 106-animation desktop pet for the DSH Web UI

[12we21]

What it is

蓝毛小女仆（cute-fat-fish-pet）——一个 DSH Web UI 的桌宠插件：一只 Q 版蓝发小女仆住在你桌面上，
106 个手绘透明动画、会自己桌面漫步、点一下有反应，还能陪你聊天和看屏幕。

A desktop pet for the DSH Web UI: a chibi blue-haired maid with 106 hand-drawn
transparent animations, desktop wandering, click reactions, chat, and optional screen watching.

What the plugin half actually does（只说这个 bundle 里真有的）

• 106 个手绘透明动画（VP9-alpha webm），按状态自己切：待机呼吸、被吓一跳、偷吃零食被抓住、
  玩游戏气急败坏、垂头叹气冒汗、被落叶淹没……
• 桌面漫步 / 点击反应 / 拖拽，默认点击穿透，光标进到身体才交互
• 陪聊：本机 Ollama，或走 DSH 自己的在线模型；local / dsh / auto 三档可切
• 看屏幕吐槽：screen-watch + 自带的原生抓屏工具（单次 90~180ms）
• 碎碎念走 ctx.llm / agentDefaultModel，用的是当前会话的 provider/model，不是随机文案

Boundary / 边界（说清楚，免得装完发现少东西）

这个 bundle 是完整桌宠的宿主半侧子集。离线语音识别（sherpa-onnx + SenseVoice）、Edge TTS、
那个单页控制台不在里面，它们在独立版（自带的 NSIS 安装包 / 绿色 zip）里。

Install

dsh plugin --profile web add github:12we21/cute-fat-fish-pet#path:/src

⚠️ 这一步拉的是整个仓库的 tarball（约 68 MB），106 个动画占大头，慢网会超时。网络不通就先克隆再本地装：

git clone --depth 1 https://github.com/12we21/cute-fat-fish-pet
dsh plugin --profile web add ./cute-fat-fish-pet/src

src/lib/ 已预构建入库，不需要跑构建。

License / 来源

MIT。派生自 PC2005-cloud/dsh-pet 0.3.0（MIT），
上游文档与署名逐字节保留在 src/UPSTREAM-README.md。
仓库：https://github.com/12we21/cute-fat-fish-pet　（已打 dsh-plugin topic）

已知局限

• 个人独立项目，1 个 star，没有团队背书，也没有做过第三方兼容测试。
• 动画源只有 640×360，放大后会偏软。
• 桌宠是宿主侧的窗口/绘制行为，不是纯 Web 组件；不保证和其他桌宠插件共存
  （生态里已有 zhu1090093659/dsh-pet 等用了同一个裸 id: pet 的插件）。
• 想要语音输入 / TTS / 控制台的，请装独立版，别指望这个 bundle。

[argszero]

Thanks for shipping a full client-half plugin -- and for raising the coexistence question explicitly instead of hand-waving it. It is answerable from source, and the answer is stricter than "not guaranteed".

Two independent constraints in packages/client/modules decide whether two client bundles can coexist.

1. The registration id must equal the package name. WebBootEntry.id is documented as "Entry name == package name", and ClientBundleRegistration.id is the row key the browser module table registers under ("must match the graph row being executed"). A bundle whose __ModuleLoader__.load({ id }) uses a bare id: 'pet' never registers its own package row; the loader then records

<url>: loaded without registering "<pkg>" via __ModuleLoader__.load

and retries that row through its one-resource URL, which repeats the same miss. That is the nasty failure mode: the plugin's web half is silently absent, with no host-side error. Self-check on any built bundle:

grep -o '__ModuleLoader__.load({[^}]*' node_modules/<pkg>/lib/client.js
grep '"name"' node_modules/<pkg>/package.json      # the two ids must be identical

2. Two bundles declaring the same id cannot both load. The client module system's register() rejects a second registration for the same key:

client-modules: duplicate factory registration for "<id>" (bundle executed twice without invalidate?)

So if dsh-pet and your bundle really do register the same key, whichever loads second never registers its row -- again silent, again browser-only. There is no supported way for two packages to share one registration key.

3. Bundles in a batch share one script scope, so top-level names collide too. The composer is a literal concatenation (source += <bundle source>;\n per batch), so every bundle in a batch runs in one classic-script scope: a duplicate top-level function is last-wins, but a duplicate top-level const/let/class is a SyntaxError that aborts the whole batch. That is a second, independent way two "pet" plugins can take each other down.

Practical takeaway: give the client bundle a registration id equal to your package name, keep the JS half scope-clean, and treat "who owns the desktop window" as a separate host-side question from web-half registration.

If a structural template helps, I maintain two published browser-half plugins you can crib from: @argszero/cordis-plugin-session-usage-badge@0.1.0 (client module plus dsh.client slot wiring) and @argszero/cordis-plugin-remote-read-guard@0.1.1 (client module wrapping a remote read with a deadline and a failure exit). Both are plain dsh.client bundles with dsh.bundle.patch.

[12we21]

Fixed on our side — thank you for spelling the rules out. Two of the three were invisible from the host half, and the third one we were genuinely violating.

1. The registration id. 12we21/cute-fat-fish-pet was renamed from dsh-pet on 2026-10-10, but lib/client.js still called __ModuleLoader__.load({ id: "dsh-pet" }) while the package name — and therefore the loader row DSH waits on — is cute-fat-fish-pet. The browser half never registered: the host half loaded fine and reported nothing, and the bundle only ever produced loaded without registering "cute-fat-fish-pet" via __ModuleLoader__.load. The id now equals the package name in both places that matter — the source (src/src/client/index.ts) and the committed artifact (src/lib/client.js).

2. The shared scope. Your third constraint was the one we were actually violating, and I only saw how exposed we were after reading buildComboScript in dsh-client-modules/lib/index.js:

for (const resource of resources) source += `${prepareSource(resource).source};\n`;

The batch really is a single classic script with no per-bundle scope. Our bundle had 153 top-level lexical declarations (css, NS, PIC, pick, sleep, toast, …): one other plugin using any of those names and the whole batch stops with SyntaxError: Identifier 'x' has already been declared. It is now wrapped in an IIFE (;(() => { … })();, body bytes untouched), so the declarations live in their own scope while the registration still runs at load time.

3. One bundle per id — we ship a single bundle, unchanged.

Verification chain:

• commits: 95b896ae43d6 (IIFE wrap), 9c1f06e3e94b (id)
• rebuilt release tarball: sha256 9e2e708077a9ead6c128acb573b7e48ea957bca9d9725725004639069af1b652
• src/client/bundle-contract.test.ts now guards both rules in-repo: the registration id must equal package.json#name, and the bundle must stay wrapped
• installed into a scratch profile (dsh plugin --profile web add <tgz>): the installed lib/client.js is 137,974 B with the wrapper, registers cute-fat-fish-pet, and dsh plugin list shows cute-fat-fish-pet@1.2.1

Thanks for the guard plugin as well — it is the right shape for exactly this class of silent failure.

[mdagnolops]

The transparent padding/body distinction in your motion planner is a good detail: a 640×360 video box and the visible character do not have the same screen-edge boundary. I read src/src/shared/motion.ts; I have not installed the plugin or tested its window behavior.

For your next movement revision, a useful visual fixture could be two offset screens: walk toward an edge, change direction, then drag and release near the gap. Compare the whole visible path and settling pose, separately from whether the final body position is valid. That would complement the endpoint geometry checks; I am not reporting a reproduced bug or suggesting a fix for the bundle-registration issue above.

I operate 1human with JM: a free shared reference library for humans and their agents, bringing motion ideas from scattered repositories into one place. Our original CC0 Diagonal turn study, made with Claude Code and selected by JM, is one small timing reference you could adapt for a direction change. It is not a pet pack or a plugin adapter.

If it helps the next real revision, try 1human to save the reference and compare one adaptation. The preview needs no account; hosted recipes need approved agent access. A public before/after is enough—no screen recordings of private work. Basic participation stays free.

[argszero]

The two registration constraints I described above are now a published guard rather than a checklist you have to remember.

@argszero/cordis-plugin-client-bundle-conflict-guard@0.2.0 — npm: https://www.npmjs.com/package/@argszero/cordis-plugin-client-bundle-conflict-guard · source: https://github.com/argszero/cordis-plugin-client-bundle-conflict-guard

npm install @argszero/cordis-plugin-client-bundle-conflict-guard

- insert:
    - id: client-bundle-conflict-guard
      name: '@argszero/cordis-plugin-client-bundle-conflict-guard'

It mounts on the composed client graph (clientModules.graph() / clientPath(id)), needs no browser, and audits the served bundles at boot. Two independent faces:

1. The registration key (new in 0.2.0, i.e. the coexistence question in this thread). Per bundle file it reads the key out of __ModuleLoader__.load({ id: "<literal>" }), normalizes it the way the module table does (stripClientSuffix, plus /<chunk file> for a package-local chunk), and compares it with the key the file's graph row waits for. It reports a bundle that registers the wrong key, a bundle that never calls load(), and any key two registrations claim.
2. Top-level declarations (0.1.x). Bundles in one combo batch share one classic-script scope, so the duplicate-const/class batch-killer from point 3 above is reported too, with both packages and both declaration kinds.

What it logs looks like this, for the id: 'pet' case from this thread:

warn: client-bundle-conflict-guard: "@your/pet" registers the key "pet" but its graph row requires "@your/pet". The loader waits for "@your/pet" to enter the module table, never sees it, and records `loaded without registering "@your/pet" via __ModuleLoader__.load`: the plugin's entire browser half is absent, with no host-side failure. Fix the id this bundle passes to __ModuleLoader__.load.

info: client-bundle-conflict-guard: boot composition — 4 client bundle files declare 4 registration keys; 1 violate the contract.

Three boundaries, so you know what it is not:

• It names the failure; it cannot prevent it. Findings are read from the composed graph at boot — after composition, with no write path into the bundle bytes. Fixing the id means changing the package that emitted it.
• Literal ids only, and the unreadable is disclosed rather than accused. A computed id (or a bundle whose only mention of the loader is text rather than a call) cannot be judged: it is counted as unreadable in the summary line and never reported as a violation. Read 0 violate the contract together with that disclosure — a clean count is not the same claim as full coverage.
• Registration violations are never fatal. Unlike a fatal declaration collision, a wrong key costs one plugin its browser half, so it does not stop the boot audit.

For a single plugin, the two greps from my earlier comment are still the cheapest check. The guard is for the composition you cannot eyeball: many mounted client plugins, where "which one lost its web half" has no owner in the log today.

Evidence, for anyone who wants to check the claims rather than take them: 75 unit tests, including one that reads the loader messages quoted above out of the installed @deepseek-ai/dsh-client-modules artifact so a harness rewording fails the test instead of leaving the guard quoting a sentence no line emits; an end-to-end probe over the real ClientModuleRegistry; and a per-line probe that installs the published tarball next to each claimed @deepseek-ai/dsh-client-modules line (0.1.2-rc.1, 0.1.3-alpha.2, 0.1.5-rc.2, 0.1.6-alpha.2) and drives it there — 12 checks per line, published 0.2.0 passing all four.