为 DeepSeek Harness Web 对话回复加入可切换、可上传的自定义行内表情，内置 40 个语义 key。
- Language
- TypeScript
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add github:hellodigua/dsh-emojiRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
一句话定位
为 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.itemslot 渲染设置卡片，并按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 运行时与浏览器 |
安装方式
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）