dsh-deep-whale Skin Installation and Switching

Objective: Make DSH Web skins take effect quickly and recoverably. Switching and code updates for installed links use hot loading; restart only when adding a new package for the first time; updates and specified commit tests only occur when requested by the user.

This skill only provides process guidance; refer to real-time on-site information for specific facts: The repository will be updated (new skins added, attribution chain modified), do not rely on this document or memorized lists, read in real time.

First Determine the Scenario (Decide Which Path to Take)

First check the current dsh environment:

dsh plugin --profile <name> list

(actual profile names such as web; local path installations are displayed as

link:

). Check whether the target skin is already installed by its

package

name, and confirm whether there is a clone of the repository locally:

Already installed (link: dependency) → Scenario A Switch: Direct hot switch, no cloning, no questions, no introduction.
Not installed but local repository clone exists → Scenario B Initial Installation (Local Repository): Use the existing clone directly, never re-download.
Not installed and no local clone → Scenario B Initial Installation (Requires Cloning): Only perform
```
git clone
```
at this time.
User explicitly requests "update/check for updates" → Scenario C Update: Only compare remote commits at this time.
User requests to load local modifications or test specified commits → Scenario D Verify Development Version: Protect the current workspace and running DSH.

Restart Safety Gate (Cannot Be Skipped in Any Scenario)

DSH Web running does not mean the profile on disk can start again; the old process may still hold the plugin graph before modification. Do not treat "current page available" as evidence of cold start, and do not suggest the user restart before checking.

Read the target skin's
```
package.json.name
```
and
```
skin.json.package
```
; the two must be identical.
Check
```
~/.dsh/profiles/<profile>/package.json
```
: The dependency key,
```
dsh.profile.bundles
```
entry, and the actual package name of the local link target must be consistent. If an alias or old scope is found, first remove it with
```
dsh plugin --profile <name> remove <incorrect key>
```
, then
```
add
```
using the absolute path of the target directory; do not manually modify
```
node_modules
```
.
Run
```
dsh plugin --profile <name> list
```
and
```
dsh --profile <name> --dump-config
```
. The target entry must be combinable, have the correct package name, and its start-stop status must meet expectations.
Only when a restart is truly needed, run the cold start probe while keeping the existing process:
```
dsh --profile <name> --no-open --port 0
```
. Wait for it to print the temporary URL, then terminate only this probe process. If the probe fails, keep the original process, fix the issue and retry; prohibit asking the user to restart with the production port to "try it out".
Only after the cold start probe succeeds replace the original process, and verify that the fixed port returns HTTP 200 and the startup page
```
window.__DSH_BOOT__
```
contains the target package name. When terminating the process, only operate the exact PID/session just recorded, do not end processes in batches by process name.

Diagnosis must be bounded: When hot loading does not occur, first check the link target,

lib/client.js

hash, boot entry and

--dump-config

; do not recursively scan the entire

~/.dsh

, global

node_modules

, or use long-term SSE requests to try luck.

Scenario A: Switch (Already Installed) – Fast Switching, No Extra Talk

Execute directly after the user specifies the target skin (e.g., "switch to maid skin"/"switch to orca-link"), no questions, no introduction of author and license:

Modify two patch layers (both must be modified; home layer overrides profile layer):
- ```
~/.dsh/profiles/<profile>/cordis.patch.yml
```
- ```
~/.dsh/cordis.patch.yml
```
Set
```
disabled: false
```
for the target skin, and add a line
```
disabled: true
```
for each other installed skin. Note: Skins not listed in the patch are enabled by default, so "only keep one set" requires explicitly disabling all others.
Hot reload takes effect upon saving (configured with HMR), no restart required; inform the user to refresh the page, and the session will not be affected.
Quick verification: Use
```
dsh --profile <name> --dump-config
```
to confirm the target skin line has
```
disabled: false
```
(use the three-layer verification of the
```
dsh-plugin-verify
```
skill if available).

If the user only says "switch skin" without specifying which one, list the installed skins in one sentence and ask for the target.

Scenario B: Initial Installation (Not Installed)

1. Locate the Repository (Local Priority, Never Re-download)

Look for directories containing
```
skin.json
```
in the current working directory or common locations (repository root or subdirectory); use it once found, do not re-clone.
If no local clone is found, only then
```
git clone https://github.com/Small-tailqwq/dsh-deep-whale
```
to a temporary directory.
Skin directory structure: Each skin = a subdirectory containing
```
skin.json
```
(e.g.,
```
maid-atelier/
```
,
```
orca-link/
```
), with the pre-built client bundle in
```
lib/
```
(distributed with the repository, no need to build yourself).

2. Scan Skin List (Real-time, Do Not Hardcode)

For each directory in the repository containing

skin.json

, read and summarize:

```
id
```
/
```
name
```
(Chinese name) /
```
nameEn
```
/
```
tagline
```
```
package
```
(npm package name),
```
wiring.id
```
(plugin id controlled by patch layer)
```
preview
```
(light/dark preview images)

3. Interact with the User: List All Skins, Ask Which One to Activate

Use an interaction tool (such as

ask_user_question

) to list all skins (name + tagline), ask which one to activate, and always provide the "keep current status/do not switch" option. Do not skip interaction and install without permission during initial installation.

4. Inform the User of Copyright Attribution Chain and License (Mandatory for Initial Installation)

Attribution Chain: Read the
```
NOTICE
```
(authoritative source of attribution chain) and README of the selected skin, briefly describe the creation chain ("Original creation by XX → Secondary creation by XX → This skin by XX"), and attach the author's homepage link. Follow the actual content of NOTICE, do not introduce from memory.
License: Follow the skin's
```
LICENSE
```
. The current skin uses CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike 4.0 International), briefly explain:
- ✅ Allowed: Personal/non-commercial use, copying, sharing, secondary modification
- ❌ Prohibited: Commercial use; removing attribution (must retain complete creation chain); releasing derivative works under other licenses (must share alike)
- Prohibition of commercial use is a red line, be sure to point it out.

5. Register and Enable

```
dsh plugin --profile <name> add <absolute repository path>/<skin directory>
```
(local paths are automatically registered as
```
link:
```
). Adding a new plugin package requires a restart, but must first pass the consistency check and cold start probe of the "Restart Safety Gate". Path Specification (High Failure Rate Area for Installation): Absolute paths are the most stable (Windows forward slashes/backslashes are both acceptable, pnpm will automatically normalize); relative paths are resolved according to the directory where the dsh command is called – prefixes like
```
./
```
and
```
../
```
are acceptable, but do not use bare directory names (e.g.,
```
add maid-atelier
```
, which will be treated as an npm package name and pulled from the registry resulting in a 404 failure). After installation, first use
```
dsh plugin --profile <name> list
```
to confirm the package is registered, then proceed. After updates (Scenario C), bundle changes take effect via hot switching in Scenario A (no restart required, unless adding/removing plugin packages); initial installation involves adding a new plugin package, which requires a restart.
After installation and safe restart, also write the
```
disabled
```
lines in the two patch layers (see Scenario A) to keep only one skin enabled at a time.

6. Verify Effectiveness

Use
```
dsh --profile <name> --dump-config
```
to check the
```
disabled
```
status of the skin line and patch source: Each line is marked
```
patched by <file path>
```
, confirm both patch layers take effect (home layer overrides profile layer).
If the
```
dsh-plugin-verify
```
skill is available, use its three-layer verification (combination layer/product layer/execution layer); if not, at least ensure: After refreshing the page, the entries in
```
window.__DSH_BOOT__
```
contain the package name of the target skin (the boot graph uses the package name as the key, not
```
wiring.id
```
), and the process has not restarted (PID remains unchanged, proving hot reload was used).
Inform the user to refresh the page to view the effect; collect phenomena for troubleshooting if the skin is abnormal (console errors, layout issues).

Scenario C: Update (Only When Explicitly Requested by User)

By default, do not perform any network synchronization – use installed/cloned skins as-is. Only when the user explicitly expresses "update skin/check for updates":

```
git fetch origin
```
Compare local and remote:
```
git rev-list --count HEAD..origin/main
```
(number of落后 commits)
If behind > 0 →
```
git pull --ff-only
```
, and inform the user of the update content (
```
git log --oneline HEAD@{1}..HEAD
```
); if already up-to-date → directly inform the user, do not perform unnecessary operations.
If the bundle of an installed skin is updated, still use the patch hot switching in Scenario A to take effect (no restart required, unless adding/removing plugin packages).

Scenario D: Load Local Modifications or Test Specified Commits

Source code modifications in the current link directory: First build according to the repository script and confirm the commit-type
```
lib/
```
is synchronized, then trigger hot loading by disabling/enabling the target entry via patch; record and review the PID, no restart is required under normal circumstances.
Test specified commits: Prohibit executing
```
git restore --source=<commit> --worktree -- <skin>
```
in the workspace the user is currently using. Create a temporary detached worktree, build and verify in it, then re-link the package with the same name to this worktree using the absolute path; record the original link path, and only restore according to the user's instructions after testing is completed.
After re-linking, first check that the dependency key still equals the target
```
package.json.name
```
. If the package identity changes, follow the sequence "remove old key → add via absolute path → dump-config → cold start probe", do not rely on the plugin graph in the old process memory.
If hot loading fails, do not touch unchanged patch files to fake a refresh, and do not immediately suggest restarting; perform bounded diagnosis first. Only use the safe restart process when adding/removing plugin packages or when the boot graph truly cannot be hot-updated.

Known Key Points (For Judgment, Not Hardcoded Facts)

Skins in this repository are pure client plugins for the presentation layer: No service injection, no Cordis events sent, no model requests accessed; materials are embedded in the bundle as data URIs, activation does not rely on remote resources.
Skins can be hot-switched,
```
wiring.id
```
is the plugin id controlled by the patch layer; compatible with skin center/mutual exclusion switching mechanism.
The installation example in the repository README recommends absolute paths (
```
dsh plugin --profile web add <absolute clone path>/<skin directory>
```
), and includes relative path rules and a failure troubleshooting table; the lazy version is to directly let dsh say "install this skin package".
Submit issues to the repository for feedback, do not contact the artist directly; following secondary creations is a different matter.

dsh-skin-install

NPX Install

Tags

SKILL.md Content (Chinese)