TianJie52009/dsh-kaomoji

Add Japanese kaomoji to DeepSeek Harness (dsh) replies.

🤖 Pure Codex generation — the code and docs in this repository were generated entirely by OpenAI Codex and have not been human-reviewed. Please read and test before use.

dsh-kaomoji is a zero-dependency dsh plugin. Before a model call it injects a “mood → kaomoji” whitelist rule into the system prompt, so the model copies a real, well-formed kaomoji verbatim at the right moment. The curated library is based on 顔文字屋 kaomojiya.org, one of the largest Japanese kaomoji sites.

简体中文 | English

Features

• Prompt-only design — no stream rewriting, no extra model calls, stable for KV caches.
• Whitelist prevents garbled output — the model copies characters exactly instead of inventing malformed faces.
• 12 mood buckets — happy, love, sad, cry, angry, surprised, confused, shy, playful, encourage, thanks, sorry.
• Three frequency modes — auto (default; greetings, casual chat, recommendations and empathetic replies get one), frequent, off.
• Placement control — inline after the mood-matching sentence (default) or end of the reply.
• Visual settings card under Settings → General, saved live without a restart.
• No third-party runtime dependencies — only the dsh systemPrompt service and Node built-ins.

How it works

1. On startup the plugin registers a prompt section named dsh-kaomoji:guidance (order 176) via ctx.systemPrompt.section().
2. On every prompt assembly the section contributes:
   • the active mode and placement rules;
   • the mood-categorized kaomoji whitelist;
   • an optional user customPrompt.
3. The model emits one of the listed kaomoji where it fits. Because kaomoji are plain text, no custom rendering is needed in the chat UI.

Settings use a same-origin route registered on the web server (POST /dsh-kaomoji-settings):

1. The Settings → General card reads/writes ~/.dsh/dsh-kaomoji.json.
2. The Host updates the prompt section and emits system-prompt/change immediately, so the next reply follows the new settings without a restart.

Prompt injection is preferred over post-processing the stream because it avoids stream parsing, sentence-boundary guessing, and keyword-based sentiment guessing, and it follows the same mechanism as plugins like dsh-emoji.

Install

Prerequisites: a dsh Web Profile with @deepseek-ai/dsh-system-prompt, Node.js ^22.19.0 || >=24.0.0, pnpm 11.

cd "$env:USERPROFILE\.dsh\profiles\web"

# Option A: install from npm (recommended)
dsh plugin --profile web add dsh-kaomoji

# Option B: install straight from GitHub (no npm release needed)
dsh plugin --profile web add github:TianJie52009/dsh-kaomoji

# Local development build
pnpm add file:C:\path\to\dsh-kaomoji

If you install with pnpm manually, make sure "dsh-kaomoji" is listed in dsh.profile.bundles inside package.json.

Restart the Web Host afterwards (or let dsh-hot-reload mount it live). The Host starts injecting the guidance; the Web client adds the “Kaomoji (dsh-kaomoji)” card at the bottom of Settings → General.

Configuration

Defaults are ready to use (mode: auto). There are two settings layers:

1. Deployment defaults: override config for id: dsh-kaomoji in the profile’s cordis.patch.yml;
2. User settings: edited in the Settings → General card and stored in ~/.dsh/dsh-kaomoji.json; user settings win. “Reset to defaults” removes the user layer and falls back to the deployment defaults.

Example cordis.patch.yml:

- id: dsh-kaomoji
  config:
    mode: frequent     # off | auto | frequent
    placement: end     # inline | end
    maxPerTurn: 2
    customPrompt: "Keep it professional; prefer thanks/encourage kaomoji"

Key	Type	Default	Description
mode	'off' | 'auto' | 'frequent'	'auto'	off disables; auto adds one to greetings, casual chat, recommendations and empathetic replies; frequent adds one to every conversational reply (code-only/formal replies excluded)
placement	'inline' | 'end'	'inline'	Put the kaomoji after the best-matching sentence, or at the reply end
maxPerTurn	number (1–5)	1	Max kaomoji per reply; frequent distributes that many across different sentences (fewer in very short replies)
customPrompt	string	''	Extra style/scene guidance; cannot change mode, whitelist or limits
settingsFile	string	~/.dsh/dsh-kaomoji.json	(advanced) user-settings file path
Card edits take effect immediately; deployment-default edits in
cordis.patch.yml require a dsh restart.

Remote access (Tailscale / LAN)

• The settings route is same-origin with the page (POST /dsh-kaomoji-settings), so pages opened over Tailscale, LAN or an SSH tunnel can all save settings — no trustedHosts configuration needed.
• The only requirement is that the page can reach that Host's HTTP port; any failure now shows the server's original error in the card (0.1.4+).

Kaomoji library & attribution

The built-in library lives in data/catalog.json, with a source URL per category:

Mood	Source page
happy	happy-kaomoji
love	love-kaomoji
sad	sad-kaomoji
cry	cry-kaomoji
angry	angry-kaomoji
surprised	odoroiteru-kaomoji
confused	komaru-kaomoji
shy / playful	shy-kaomoji
encourage	hagemasu-kaomoji
thanks	thanks-kaomoji
sorry	sorry-kaomoji

Kaomojiya states the pages are free to use (no registration required, personal and commercial use allowed). This plugin ships a small hand-picked subset and keeps the source attribution. The plugin code itself is MIT-licensed.

To extend the library, update both data/catalog.json (full catalog) and the CATALOG constant in lib/index.js (the prompt whitelist).

Development

dsh-kaomoji/
├── lib/
│   ├── index.js       # Host: config, guidance builder, section registration, settings RPC
│   ├── client.js      # Web: Settings → General card (ModuleLoader format)
│   └── index.d.ts     # TypeScript declarations
├── data/
│   └── catalog.json   # curated kaomoji library with source URLs
├── test/
│   ├── plugin.test.mjs# Host unit tests (guidance + settings RPC)
│   └── client.test.mjs# Client ModuleLoader/store tests
├── cordis.patch.yml   # dsh bundle patch
├── package.json
├── README.md / README.en.md
├── CHANGELOG.md
└── LICENSE

npm test   # run unit tests
npm pack   # verify the publish payload (runs npm test via prepack)

Inspect the injected guidance quickly:

node -e "import('./lib/index.js').then((m) => console.log(m.buildGuidance({ mode: 'frequent', placement: 'end' })))"

Publishing to npm (maintainers)

The bare-name install (dsh plugin --profile web add dsh-kaomoji) requires a real npm release. registry.npmmirror.com is a read-only mirror and cannot publish, so log in to the official registry once:

npm login --registry https://registry.npmjs.org
npm publish --access public --registry https://registry.npmjs.org

package.json already pins publishConfig.registry to https://registry.npmjs.org/.

Compatibility

• Targets the npm @deepseek-ai/dsh rc.7 runtime line.
• Peer deps: @deepseek-ai/cordis, @deepseek-ai/dsh-system-prompt, plus the Web client peers (dsh-client-*, react) — all optional, provided by the Web Profile shared runtime.
• Coexists with dsh-emoji: different prompt section names/orders (dsh-emoji:guidance @175 vs dsh-kaomoji:guidance @176), settings namespace, RPC channel, and card slot (Plugins page vs General). Kaomoji are plain text, so dsh-emoji’s stream rewrite (which handles canonical Unicode emoji only) never touches them.

FAQ

• No kaomoji in replies? Check, in order: (1) the Host half is mounted — dsh plugin --profile web add dsh-kaomoji writes both dependencies and dsh.profile.bundles; a bare pnpm add only loads the client card, so re-install with the dsh CLI or add the insert row to cordis.patch.yml and restart (the log should show [dsh-kaomoji] 已挂载（mode=...）); (2) the mode — auto only fires on friendly/casual/empathetic replies, use frequent for one per conversational reply; (3) the settings card status — “Host not loaded” / “origin not trusted” also means the guidance is absent.
• Why does the model sometimes skip kaomoji in auto mode? That is by design. Only frequent requires one per conversational reply.
• Can I use kaomoji outside the whitelist? Yes — put the exact string in customPrompt; explicit user requests are an exception to the whitelist.
• Will code replies be polluted? No. The rules forbid kaomoji inside code blocks, inline code, links, tables, and tool output.
• Where is the settings card? At the bottom of Settings → General (after language, appearance, composer rows). Changes save live; “Reset to defaults” is available in the card.
• Does it conflict with dsh-emoji? No technical conflict (see Compatibility). If both run in frequent mode a reply may contain an emoji and a kaomoji — keep one of them in auto (or turn one off) for the cleanest look.

License

MIT

Kaomoji characters are sourced from 顔文字屋 kaomojiya.org (free for personal and commercial use per the site).