# dsh-emoji

> 为 DeepSeek Harness Web 对话回复加入可切换、可上传的自定义行内表情，内置 40 个语义 key。

## Metadata

- Author: [@hellodigua](https://github.com/hellodigua)
- Repo: <https://github.com/hellodigua/dsh-emoji.git>
- GitHub: [hellodigua/dsh-emoji](https://github.com/hellodigua/dsh-emoji)
- Stars: 31
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-19T08:35:02.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:hellodigua/dsh-emoji
```

## Wiki

## 一句话定位
为 DeepSeek Harness 的 Web 对话回复加一套可切换、可上传自定义的行内表情。AI 直接使用 42 个受控 Unicode 表情挑选语义，Host 在流式响应时按映射换成本地 PNG，浏览器渲染为行内图片，不增加额外模型调用。

## 核心能力
- 提供内置「蓝鲸表情包」覆盖 40 个稳定语义 key（如 happy、thinking、doge），开箱即用
- AI 通过 42 个受控 Unicode 表情选择语义，Host 在 LLM 流上自动改写为当前表情包的行内 PNG
- 支持在「设置 → 插件 → 表情（Whale Emoji）」中切换关闭、智能、高频三档使用频率，智能模式每回合最多 3 张，高频模式最多 4 张
- 提供小、正常、偏大、大四档显示尺寸（1.25em / 1.5em / 2em / 2.5em），并支持在自定义附加提示词里控制选择、语气和场景
- 允许用户上传自定义 ZIP 表情包，AI 仍使用同一组受控 Unicode 字符，仅替换图片素材，无需重启 Host
- 用户表情包按 id@version 不可变安装，并通过 SHA-256 去重；上传/移除会自动 bump 内部 revision，让浏览器立即感知变化

## 技术实现
- **语言**: TypeScript（含 React 18 客户端卡片）
- **关键依赖**: @deepseek-ai/cordis（插件容器）、@deepseek-ai/dsh-system-prompt（注入 emoji 策略）、fflate（ZIP 解压）、pngjs（PNG 校验），以及 dsh-llm 流式桥接 + dsh-host-webserver 静态素材路由
- **架构模式**: Host + Web Client 双半。Host 端通过 `dsh.bundle.patch` 注入 Cordis，监听 `llm/stream`、`system-prompt/change`，注册 `webServer` 路由 `/api/dsh-emoji/assets/`；Web Client 半注入到 `settings.plugin.item` slot 渲染设置卡片，并按 `displaySize` 注入样式
- **入口文件**: `src/index.ts` (Host apply) + `src/client/index.ts` (Web apply)

## 适用场景
想给 DSH Web 对话加点情绪点缀、又不想反复训练 AI 表情行为的普通用户。如果想让 AI 默认在每条回复里塞一个合适的表情，可以用高频模式；如果偶尔点缀、用得克制，则用默认的智能模式。手上有原创或社区表情包想替换默认蓝鲸，也可以上传符合 40 个语义 key 的自定义 ZIP 直接切换。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | ^0.1.0-rc.7 | 由 package.json peerDependencies 声明；cordis.patch.yml 注入到 Host |
| Node.js | ^22.19.0 \|\| >=24.0.0 | 由 package.json#engines 声明 |
| React | ^18.2.0 | Web Client 端设置卡片依赖 |
| 操作系统 | 跨平台 | 无原生模块，仅依赖 Node.js 运行时与浏览器 |

## 安装方式
```bash
dsh plugin --profile web add github:hellodigua/dsh-emoji
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| mode | 枚举 off/auto/frequent | AI 使用行内表情的频率策略；关闭=不用，智能=最多 3 张/回合默认，高频=最多 4 张/回合 | auto |
| displaySize | 枚举 small/normal/large/xlarge | 浏览器中行内表情的显示尺寸，影响样式表 | normal |
| customPrompt | 字符串（≤ 4000 字符） | 附加到 emoji 策略提示词中的用户提示，可控制选择、语气和使用场景，但不能改变模式/允许的 Unicode/上限 | "" |
| activePack | 字符串 id@version | 当前回复使用的表情包；用户上传/切换后立即对下一次模型调用生效 | deepseek@8 |
| packRevision | 自然数 | 内部版本号，仅当表情包目录变更时自增；用于让客户端和 Host 的素材 URL 自动失效 | 0 |

## 常见问题

**Q: AI 会在什么时候使用表情？会自动补图吗？**

A: AI 主动从 42 个受控 Unicode 表情里挑选，插件不会根据正文猜测情绪；模型在智能模式下被允许不使用表情，高频模式下被要求在对话回复中安插一个匹配情绪的表情。同一条回复里多张表情必须由有效正文分隔，且插件表情不会出现在代码、链接里。

**Q: 三档频率之间有什么区别？**

A: 关闭（off）= 不使用任何插件表情；智能（auto，默认）= 只有在能改善友好、鼓励或俏皮语气时才使用，每回合最多 3 张；高频（frequent）= 在所有对话回复中加入一个合适的表情，每回合最多 4 张。频率切换在下一次模型调用生效。

**Q: 可以上传自己的表情包吗？有什么限制？**

A: 支持。上传 ZIP 时插件会自动校验：必须包含 `pack.json`（声明 schemaVersion=1、keySet='dsh-emoji-core@1'、id、name、version）和 `images/` 目录下每个语义 key 的同名 PNG；ZIP 上限 20 MiB、解压后上限 80 MiB、单文件 ≤ 2 MiB、图片宽高 ≤ 512 像素；不合规的格式、缺失 key、未知 keySet、伪造校验或与已有版本冲突都会被拒绝。

**Q: 用户表情包保存在哪里？会被一起清理掉吗？**

A: 用户包保存在 `$DSH_HOME/emoji-packs/`（默认 `~/.dsh/emoji-packs/`），按 `id/version/` 不可变安装。设置卡片里的「移除」只是从选择列表隐藏，并保留不可变的素材字节，使得历史消息里那版的 URL 仍能继续回放；想彻底清理需要手动删除该目录。

**Q: 切换表情包或调整频率后需要重启吗？**

A: 不需要。下一次模型调用就会使用新设置；如果只调整显示尺寸，浏览器端会立即通过样式热更新体现。

**Q: 卸载插件后历史消息里的表情还能看吗？**

A: 插件的主注册信息会被移除，但已经持久化到消息里的素材 URL 仍指向原始文件；只要用户表情包字节还在 `~/.dsh/emoji-packs/` 下，URL 就能继续回放；内置蓝鲸包随插件发布，安装回来即可恢复。

**Q: 自定义附加提示词能扩大 AI 的表情选择范围吗？**

A: 不能。提示词只影响语气、风格与使用场景；运行时不可编辑约束会把模式、允许的 42 个 Unicode 字符和数量上限始终固定，自定义提示词无法绕过。

**Q: 卸载插件会影响其他插件的图片吗？**

A: 不会。本插件的样式表和路由只命中 `img[src*="/api/dsh-emoji/assets/"]`，不会改变普通 Markdown 图片或其他插件的图片渲染。

## 上手难度
入门 — 默认安装即用，默认智能模式即可获得情绪点缀；自定义表情包上传需要准备符合规范的 40 张 PNG，对普通用户有较高要求但不是必选。

## 已知问题与限制
- 旧版 v0.1 持久化在历史消息中的 `/api/dsh-emoji/assets/deepseek/ds_XX.png` 资源路径仍可正常回放，由 `packs.ts:411` 的 `resolveLegacyAsset` 兜底解析
- 用户表情包的自定义 `id` 不得使用 `deepseek`，内置包 id 被独占（`packs.ts:114`）
- 内置蓝鲸包不可移除，当前正在使用的表情包也不可移除，必须先切换再移除（`packs.ts:494-495`）
- 当 DSH Host 的 `webServer` 服务尚未注册时，Host 端会主动抛出 `dsh-emoji: webServer service missing while resolving emoji URL`，需要确认 Web Profile 已正确启用（`src/index.ts:64`）
- 自定义提示词虽允许为空，最多 4000 字符，但仅能影响选择/语气/场景，不能改变模式、Unicode 白名单或上限（`src/index.ts:42-48`）
- 当前 40 个规范 Unicode 映射定义在 `reaction-emoji.ts:11-52`，新增 key 不会进入历史映射；不兼容扩展会通过新 keySet 主版本发布（`EMOJI_KEYS.md:28`）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-emoji](https://deepseek-plugin.org/plugins/hellodigua/dsh-emoji)
Wiki generated by AI (model: `MiniMax-M3`)