dsh-maid-emoji

Readme

# dsh-maid-emoji · 智能体表情包系统

让任意 dsh 智能体在回复中发送表情图片的插件。**安装即内置默认表情包**
（女仆表情包，47 张），零配置即可用；也可以随时添加任意自定义表情包文件夹。
智能体在回复中用 `::文件名::` 标记引用表情，让对话更生动可爱。

![效果预览](docs/preview.png)

## 功能

- **内置默认表情包**：随插件分发（`assets/emoji`，47 张），安装后无需任何配置即可使用；
  可在设置中关闭，或让自定义文件夹的同名表情覆盖内置版本。
- **自定义表情包文件夹**：添加 / 移除任意数量的文件夹（PNG / JPG / WebP / GIF）；
  支持点击「浏览…」打开系统文件夹选择器，也可以手动输入路径。
- **表情自动发送**：插件把表情清单注入系统提示词；智能体在回复正文中以
  `::文件名::` 标记（如 `::开心::`）引用表情，Host 端经 `llm/stream`
  瀑布把标记转写为表情图片，模型无需记忆完整 URL，输出更稳定；
  也兼容直接写 `![表情名](http://127.0.0.1:3080/emoji/<文件名>)` 图片。
- **显示尺寸控制**：设置表情显示宽度（px，32–512），高度按比例缩放，对话中即时生效。
- **配置界面**：插件配置页的「表情包设置」折叠卡片，含启用开关、内置包开关、
  清单注入开关、每轮表情数量上限、显示宽度、表情预览网格、保存 / 放弃 / 重新扫描。
- **HTTP 表情服务**：`/emoji/*` 前缀路由，按文件名从内置或自定义文件夹流式返回图片字节。
- **动态生效**：修改配置自动重新扫描；修改系统提示词随下轮组装生效（新会话效果最佳）。

## 安装

以下任选一种方式把插件装进 web profile（`~/.dsh/profiles/web`），
然后重启 dsh web、刷新浏览器即可。插件依赖 `@deepseek-ai/schemastery`，
会在安装时自动从 npm registry 拉取，无需额外手工处理（开发用的 `link:` 方式除外，见下）。

### 方式一：本地安装包（推荐分发）

```sh
# 在插件目录内生成安装包
cd dsh-maid-emoji
npm pack          # 生成 dsh-maid-emoji-0.1.0.tgz

# 安装方在 profile 目录内执行
cd ~/.dsh/profiles/web
pnpm add ./dsh-maid-emoji-0.1.0.tgz
```

### 方式二：Git 仓库

把本仓库推到 GitHub 后，安装方执行：

```sh
cd ~/.dsh/profiles/web
pnpm add "github:<owner>/dsh-maid-emoji"
```

### 方式三：npm 发布

把 `package.json` 中的 `"private": true` 移除后 `npm publish`，安装方执行 `pnpm add dsh-maid-emoji`。

### 方式四：本地目录直连（开发用）

```json
{
  "dependencies": {
    "dsh-maid-emoji": "link:G:/深鲸湾/biaoqingbao/dsh-maid-emoji"
  }
}
```

> **注意**：`link:` 是直接链接源目录。Node 解析符号链接后会从源目录向上查找依赖，
> 因此源目录需要能解析到 `@deepseek-ai/schemastery`——若插件报
> `Cannot find package '@deepseek-ai/schemastery'`，在插件目录内执行
> `pnpm add @deepseek-ai/schemastery@^3.18.1` 补齐即可。
> tarball / git / npm 方式没有此问题（依赖由包管理器装进虚拟 store）。

### 无论哪种方式，都需在 profile 中登记

确认 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 含 `"dsh-maid-emoji"`（tarball / git / npm 方式由 pnpm 自动写入 dependencies，bundles 需手工补一行）：

```json
{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "…其余插件…",
        "dsh-maid-emoji"
      ]
    }
  }
}
```

然后：

```sh
cd ~/.dsh/profiles/web
pnpm install
```

最后 **重启 dsh web** 并刷新浏览器页面。

## 使用

0. **开箱即用**：安装重启后，内置的女仆表情包（47 张）已自动可用，直接对话即可。
1. 打开 **设置 → 插件 → 插件配置 → 表情包设置**（折叠卡片，点三角展开）。
2. 添加自定义表情包文件夹：点「浏览…」在系统弹窗中选中文件夹，或手动输入路径后点「添加」。
3. 点击「保存」——卡片会显示表情数量（内置 + 自定义）与预览缩略图。
4. 回到对话：智能体在合适的时候就会用 `::文件名::` 标记发出表情啦～

> 提示：表情文件名即表情语义（如「开心.png」「委屈.png」），
> 智能体会按语境选用最贴切的一张。文件夹里直接放图片即可，无需额外配置。

## 工作原理

| 部分 | 说明 |
|---|---|
| Host 半侧 `lib/index.js` | 注册 `maid-emoji` settings 命名空间；扫描文件夹建立清单；注册 `/emoji/*` HTTP 路由；贡献 `emoji:usage` 系统提示词段（order 200，动态求值）；注册 `/dsh-maid-emoji` loopback RPC；监听 `llm/stream` 瀑布把 `::文件名::` 标记转写为表情图片（代码块保护、每轮上限、未命中保留）。 |
| 浏览器半侧 `lib/client.js` | 手工维护的 `__ModuleLoader__.load` bundle，向 `settings.plugin.item` slot 注册「表情包设置」折叠卡片；经 loopback RPC 读写配置；注入 CSS 控制对话中表情显示宽度（无需 api-proxy 白名单）。 |
| 系统提示词段 | 说明 `::文件名::` 标记语法、示例与规则，并列出当前可用表情（文件名即含义，去扩展名）。配置不变时文本稳定，利于 KV 前缀缓存。 |
| HTTP 表情服务 | `http://<host>:<port>/emoji/<文件名>`，文件名经 URL 解码后精确匹配清单，返回对应 MIME 的图片字节。 |

## 常见问题

- **卡片没出现**：确认插件已加入 `dsh.profile.bundles` 并重启 dsh；确认浏览器刷新。
- **表情图片不显示**：检查 `/emoji/<文件名>` 在浏览器中能否直接打开；文件名含特殊字符时以卡片预览中的 URL 为准。
- **修改系统提示词未生效**：提示词随每轮组装动态求值，无需重启；若想立即验证，新建一个会话。
- **文件夹改了但表情没更新**：在卡片点「重新扫描」，或重新保存一次配置。

## 许可

MIT