dsh-plugin-ascension

Readme

> 🇬🇧 English | 🇨🇳 [简体中文](./README.zh-CN.md)

# dsh-plugin-ascension

A Wang Lin cultivation companion floating in the dsh web UI. It **watches the LLM session state in real time and drives animations** (thinking = hand seals, tool = casting, replying = calligraphy, done = breakthrough leap, failed = injured), and **levels up as you work** (Qi Refining → Foundation → Core → Nascent Soul → Spirit Severing → Infant Change → Ascension), with fancier skins at higher realms.

> Capabilities ported and re-themed from [`@linxin666/dsh-pet`](https://www.npmjs.com/package/@linxin666/dsh-pet) (MIT): session event projection, state machine, and affinity/cultivation economy as pure logic modules.

## Install

```bash
# Option 1 (recommended): from npm
dsh plugin --profile web add dsh-plugin-ascension

# Option 2: from GitHub
dsh plugin --profile web add github:d-ouyang/dsh-plugin-ascension

# local dev: dsh plugin --profile web add ./dsh-plugin-ascension
```

Restart the web service (`:3080`) after installing.

## Features

### State monitoring (the pet acts out what the LLM is doing)
The host subscribes to the official session event stream (`ctx.on('session/event')`) and maps it to 7 phases driving 9 animation tracks:

| Phase | Trigger | Bubble text | Track | Sheet row | Frames |
|---|---|---|---|---|---|
| idle | stopped / no session | 停止修炼 | stand | 6 | spritesheet (standing placeholder) |
| waiting | turn start / step start / awaiting input / blocked | 凝神入定 · 静待机缘 | meditation | — | meditation.webp (✅ real) |
| thinking | LLM reasoning | 掐诀推演 · 参悟神通结果 | running | 7 | spritesheet (✅ real) |
| tool | tool call | 正在施展神通 · 还有 N 道神通未了 | running | 7 | spritesheet (placeholder) |
| review | streaming reply | 凝神书字 · 整理心得 | running | 8 | spritesheet (placeholder) |
| done | turn completed | 圆满出关！ | running-right | — | dragon.webp (✅ real, 雷龙庆祝) |
| failed | tool error / interrupt / max-tokens | 神通反噬 · 心魔反噬 · 灵力枯竭 | stand | 6 | spritesheet (standing placeholder) |

- Animations loop **ping-pong** (0→1→…→n→…→1→0) while the phase lasts
- done celebration window: **3 s** for a normal turn, **6 s** on a realm breakthrough (`celebrateMs`, passed via `onStatus` opts)

### Cultivation & realms
- +1 per completed turn (cultivate); click pet +1 (discuss, 3 min cooldown); feed pill +1 (30 s cooldown)
- 7 realms (Qi Refining → Foundation → Core → Nascent Soul → Spirit Severing → Infant Change → Ascension), thresholds configurable in `ascension-core.js` (`REALMS`)
- **Realm-up triggers the breakthrough animation and auto-switches to the next realm's skin**; missing skins fall back to the previous realm

### Interaction & effects
| Interaction | Effect |
|---|---|
| Click pet | Discuss (+cultivation, reaction bubble above or left) |
| Drag pet | Move it (persisted to config) |
| Hover pet | Ancient-style panel: realm badge + cultivation progress bar + pill/hide buttons |
| Click hide | Wang Lin **shrinks into the Tianni Pearl** (bottom-right); the pearl loops a gold-wood-water-fire-earth rotating gradient |
| Click pearl | Wang Lin **grows back out of the pearl** (animation first, config synced async) |

- Bubble moves to the **left** of the pet while hovering, never overlapping the panel
- All transitions render optimistically without waiting for the API

### Settings section (Settings → Ascension)
Full-width form with **Save / Cancel** at the bottom (applied on save):
- **Enable**: master switch, stops monitoring/animation when off
- **Hide pet**: show/hide the pet body
- Name, skin, size (60–400 px), right / bottom insets

### Tool
Ask in chat: *"王林现在什么境界？"* → `ascension_status` returns realm / cultivation / distance to next realm / pet & feed counts / current animation.

## Making skins (important)

One skin = one directory (`pet.json` + one spritesheet), with a **fixed 9-row action order**:

| Row | Action | Frames | Wang Lin pose |
|---|---|---|---|
| 0 | idle | 6 | standing with hands down (placeholder) |
| 1 | sword | 4 | sword flight (御剑) |
| 2 | running-left | 8 | sword flight left |
| 3 | waving | 4 | fist-and-palm salute |
| 4 | jumping | 5 | breakthrough leap |
| 5 | failed | 8 | wounded pose (placeholder) |
| 6 | stand | 6 | still, focused (idle/failed 站姿) |
| 7 | running | 6 | hand seals (掐诀) |
| 8 | review | 6 | writing with qi |

- **Cell size**: current skin is `768×832` (4× HD), declared by the `cell` field in `pet.json` — any size works
- **Recommended pipeline**: generate a looping action video with Jimeng, **split into frames** (frames from one video keep the character position stable), export per-frame PNGs
- **Background removal**: color-key for solid backgrounds + hole filling + edge feathering (keeps aura effects, removes gray edges); silver-white hair is auto-brightened to remove gray flicker
- **Pack** (requires sharp):
  ```bash
  cd /Users/ouyangding/dsh-plugin-ascension
  pnpm install
  node skin-pack.js <skin-id> --name "Wang Lin · Qi Refining"
  ```
  → outputs `assets/<id>/` (spritesheet.webp + pet.json + previews/)
- **Drop-in without code changes**: copy a packed skin directory to `~/.dsh/ascension/skins/<id>/` (user skins win)
- Realm ↔ skin id: `wang-lin-1`..`wang-lin-7` map to the 7 realms

## Data & API

- Persistence: `~/.dsh/ascension/` (state.json / settings.json)
- RPC: `/api/ascension/{state, interact, set-enabled, set-visible, set-config, set-skin}`, `/api/ascension/skins/<id>/*` (skin assets), `/api/ascension/tiannizhu/*` (pearl animation)

## Development

```
dsh-plugin-ascension/
├── index.js           # host: session/event subscription + cultivation service + RPC + skin registry
├── ascension-core.js  # pure logic: realms / cultivation / event projection / state machine
├── client/client.js   # client: settings section + floating pet + Tianni Pearl (hand-written bundle)
├── skin-pack.js       # skin packer: frames → spritesheet + pet.json + previews
├── assets/            # built-in skin (wang-lin-1) + pearl animation
└── cordis.patch.yml / package.json
```

## Credits

State monitoring / state machine / cultivation economy ported from [`@linxin666/dsh-pet`](https://www.npmjs.com/package/@linxin666/dsh-pet) (MIT License).