dsh-kaomoji 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to **dsh-kaomoji** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/lang/zh-CN/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- 首个可用版本：向 dsh 系统提示词注入「情绪 → 颜文字」白名单规则。
+- 三种模式：`off` / `auto` / `frequent`，默认 `auto`。
+- 放置位置可调：`inline`（贴合情绪的句子后，默认）/ `end`（回复末尾）。
+- 单条回复颜文字数量上限 `maxPerTurn`（默认 1，范围 1–5）。
+- 用户附加提示词 `customPrompt`（只细化风格，不能覆盖模式/白名单/上限）。
+- Web 端「设置 → 通用设置」配置卡片：模式 / 放置位置 / 数量上限 / 附加提示词，
+  通过 loopback RPC 写入 `~/.dsh/dsh-kaomoji.json`，保存即热生效。
+- 与 dsh-emoji 的共存设计：独立提示词段（order 176）、独立 RPC 通道、
+  独立设置槽位（通用设置 vs 插件页），互不覆盖。
+- 精选词库 `data/catalog.json`（12 个情绪分类，标注来源页），词库来自
+  [顔文字屋 kaomojiya.org](https://www.kaomojiya.org/)。
+- 零第三方运行时依赖；内置 `node:test` 单测（Host RPC + Client 加载）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-kaomoji contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,218 @@
+# dsh-kaomoji
+
+> Add Japanese kaomoji to [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) replies.
+
+[![npm](https://img.shields.io/npm/v/dsh-kaomoji.svg)](https://www.npmjs.com/package/dsh-kaomoji)
+[![license](https://img.shields.io/github/license/TianJie52009/dsh-kaomoji.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/dsh-kaomoji.svg)](https://nodejs.org)
+
+> 🤖 **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](https://www.kaomojiya.org/), one of the
+largest Japanese kaomoji sites.
+
+[简体中文](./README.md) | 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), `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 dedicated loopback RPC channel (`/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.
+
+```powershell
+cd "$env:USERPROFILE\.dsh\profiles\web"
+
+# Option A: install straight from GitHub (works today)
+dsh plugin --profile web add github:TianJie52009/dsh-kaomoji
+
+# Option B: install from npm (after the package is published)
+dsh plugin --profile web add 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`:
+
+```yaml
+- 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` uses kaomoji only when helpful; `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 |
+| `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.
+
+## Kaomoji library & attribution
+
+The built-in library lives in [`data/catalog.json`](./data/catalog.json), with a
+source URL per category:
+
+| Mood | Source page |
+| --- | --- |
+| happy | [happy-kaomoji](https://www.kaomojiya.org/happy-kaomoji) |
+| love | [love-kaomoji](https://www.kaomojiya.org/love-kaomoji) |
+| sad | [sad-kaomoji](https://www.kaomojiya.org/sad-kaomoji) |
+| cry | [cry-kaomoji](https://www.kaomojiya.org/cry-kaomoji) |
+| angry | [angry-kaomoji](https://www.kaomojiya.org/angry-kaomoji) |
+| surprised | [odoroiteru-kaomoji](https://www.kaomojiya.org/odoroiteru-kaomoji) |
+| confused | [komaru-kaomoji](https://www.kaomojiya.org/komaru-kaomoji) |
+| shy / playful | [shy-kaomoji](https://www.kaomojiya.org/shy-kaomoji) |
+| encourage | [hagemasu-kaomoji](https://www.kaomojiya.org/hagemasu-kaomoji) |
+| thanks | [thanks-kaomoji](https://www.kaomojiya.org/thanks-kaomoji) |
+| sorry | [sorry-kaomoji](https://www.kaomojiya.org/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
+
+```text
+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
+```
+
+```powershell
+npm test   # run unit tests
+npm pack   # verify the publish payload (runs npm test via prepack)
+```
+
+Inspect the injected guidance quickly:
+
+```powershell
+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:
+
+```powershell
+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](https://github.com/hellodigua/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
+
+- **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](./LICENSE)
+
+Kaomoji characters are sourced from [顔文字屋 kaomojiya.org](https://www.kaomojiya.org/)
+(free for personal and commercial use per the site).

package/README.md

@@ -0,0 +1,226 @@
+# dsh-kaomoji
+
+> 给 [DeepSeek Harness](https://github.com/deepseek-ai)（dsh）的回复自动添加日式颜文字（kaomoji）。
+
+[![npm](https://img.shields.io/npm/v/dsh-kaomoji.svg)](https://www.npmjs.com/package/dsh-kaomoji)
+[![license](https://img.shields.io/github/license/TianJie52009/dsh-kaomoji.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/dsh-kaomoji.svg)](https://nodejs.org)
+
+> 🤖 **纯 Codex 生成**：本仓库的代码与文档均由 OpenAI Codex 自动生成，未经人工逐行审查。使用前请自行阅读并测试。
+
+`dsh-kaomoji` 是一个零第三方依赖的 dsh 插件：它在模型生成前向系统提示词注入一段「情绪 → 颜文字」白名单规则，让模型按回复情绪**原样复制**一个真实、可读的颜文字。精选词库来自日本最大的颜文字站之一 [顔文字屋 kaomojiya.org](https://www.kaomojiya.org/)。
+
+[English](./README.en.md) | 简体中文
+
+## 特性
+
+- **纯提示词方案**：不截断、不改写模型流，也不额外调用模型，稳定且对 KV 缓存友好。
+- **白名单防乱码**：模型只会从词库中逐字符复制颜文字，不会凭印象拼出坏字符。
+- **情绪分桶**：内置 12 个情绪分类（开心 / 心动 / 难过 / 大哭 / 生气 / 惊讶 / 困惑 / 害羞 / 俏皮 / 鼓励 / 感谢 / 道歉），并随规则给出可用样例。
+- **三种频率模式**：`auto`（智能点缀，默认）/ `frequent`（每条对话回复都带）/ `off`（关闭）。
+- **放置位置可选**：贴在情绪最贴切的句子后（`inline`，默认）或固定在回复末尾（`end`）。
+- **可视化配置卡片**：卡片位于「设置 → 通用设置」，保存即生效、无需重启。
+- **零第三方运行时依赖**：只用 dsh 自带的 `systemPrompt` 服务与 Node 标准库。
+
+## 工作原理
+
+1. 插件启动时通过 `ctx.systemPrompt.section()` 注册一段名为 `dsh-kaomoji:guidance`、顺序号为 `176` 的提示词段。
+2. 每次组装模型提示词时，该段会把下面的内容交给模型：
+   - 当前模式与放置规则（如「每条回复一个」「不要放进代码块」）；
+   - 按情绪分类的颜文字白名单；
+   - 用户附加的 `customPrompt`（可选）。
+3. 模型生成时在合适位置直接输出列表内的颜文字——因为它只是普通文本，聊天界面无需任何自定义渲染即可显示。
+
+设置部分走独立的 loopback RPC（`/dsh-kaomoji-settings`）：
+
+1. 「设置 → 通用设置」的卡片读取/写入 `~/.dsh/dsh-kaomoji.json`；
+2. Host 收到写入后立刻更新提示词段并发出 `system-prompt/change`，**下一次回复就生效**，不需要重启。
+
+选择提示词注入而不是「流后处理追加」的原因：
+
+- 不需要解析流式输出、判断句子边界或猜测情绪，规避追加错位的风险；
+- 由模型在上下文里选择最贴切的情绪桶，而不是按关键词硬猜；
+- 与 dsh-emoji 等既有插件保持同一套机制，行为可预期。
+
+### 效果示例
+
+`frequent + end` 模式下的回复结尾：
+
+```text
+当然可以，我帮你把正则改成忽略大小写再跑一次测试。
+测试已经全绿了 (๑•̀ㅂ•́)و✧
+```
+
+## 安装
+
+### 环境要求
+
+- dsh（DeepSeek Harness）Web Profile，内置 `@deepseek-ai/dsh-system-prompt`
+- Node.js `^22.19.0 || >=24.0.0`
+- pnpm 11（dsh 默认使用 pnpm）
+
+### 方式一：从 GitHub 直装（现在就能用）
+
+无需等 npm 发布，dsh CLI 支持直接装 GitHub 仓库：
+
+```powershell
+dsh plugin --profile web add github:TianJie52009/dsh-kaomoji
+```
+
+等价的 pnpm 写法：
+
+```powershell
+cd "$env:USERPROFILE\.dsh\profiles\web"
+pnpm add github:TianJie52009/dsh-kaomoji
+```
+
+### 方式二：从 npm 安装（包发布后）
+
+```powershell
+cd "$env:USERPROFILE\.dsh\profiles\web"
+
+# dsh CLI 会自动把插件加入 dsh.profile.bundles
+dsh plugin --profile web add dsh-kaomoji
+
+# 本地开发版：先把仓库 clone/解压到本地，再把路径换成该目录
+pnpm add file:C:\path\to\dsh-kaomoji
+```
+
+> 用 pnpm 手动安装时，请确认 `package.json` 的 `dsh.profile.bundles` 已包含 `"dsh-kaomoji"`，否则插件不会加载。
+
+装好后重启 Web Host（或由已安装的 `dsh-hot-reload` 完成热挂载）。Host 端开始注入提示词；Web 端在「设置 → 通用设置」底部会出现「颜文字（dsh-kaomoji）」配置卡片。
+
+## 配置
+
+默认配置即开即用（`mode: auto`）。有两层设置：
+
+1. **部署默认值**：在 profile 的 `cordis.patch.yml` 中以 `id: dsh-kaomoji` 覆盖 `config`（适合管理员/装机默认）；
+2. **用户设置**：通用设置卡片里修改，写入 `~/.dsh/dsh-kaomoji.json`，优先级高于部署默认值；点「恢复默认」会删掉用户层，回到部署默认值。
+
+`cordis.patch.yml` 示例：
+
+```yaml
+- id: dsh-kaomoji
+  config:
+    mode: frequent     # off | auto | frequent
+    placement: end     # inline | end
+    maxPerTurn: 2
+    customPrompt: "正式场景克制一点，优先使用「感谢 / 鼓励」类颜文字"
+```
+
+### 配置项
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mode` | `'off' \| 'auto' \| 'frequent'` | `'auto'` | `off` 关闭；`auto` 只在确有助益时使用；`frequent` 每条对话回复都带一个（纯代码 / 正式技术交付除外） |
+| `placement` | `'inline' \| 'end'` | `'inline'` | 放在情绪最贴切的句子/短段后，或固定在回复末尾 |
+| `maxPerTurn` | `number`（1–5） | `1` | 每条回复最多允许的颜文字数量 |
+| `customPrompt` | `string` | `''` | 附加风格/场景说明；不能改变模式、白名单或数量上限 |
+| `settingsFile` | `string` | `~/.dsh/dsh-kaomoji.json` | （进阶）用户设置持久化文件路径 |
+
+卡片里的修改即时写入用户层并热生效；修改 `cordis.patch.yml` 的部署默认值后需重启 dsh。
+
+## 词库来源与许可
+
+内置词库见 [`data/catalog.json`](./data/catalog.json)，每个分类都标注了 kaomojiya.org 对应的来源页：
+
+| 情绪 | 来源页 |
+| --- | --- |
+| happy（开心/高兴） | [happy-kaomoji](https://www.kaomojiya.org/happy-kaomoji) |
+| love（喜欢/心动） | [love-kaomoji](https://www.kaomojiya.org/love-kaomoji) |
+| sad（难过/低落） | [sad-kaomoji](https://www.kaomojiya.org/sad-kaomoji) |
+| cry（大哭/泪目） | [cry-kaomoji](https://www.kaomojiya.org/cry-kaomoji) |
+| angry（生气/不满） | [angry-kaomoji](https://www.kaomojiya.org/angry-kaomoji) |
+| surprised（惊讶/震惊） | [odoroiteru-kaomoji](https://www.kaomojiya.org/odoroiteru-kaomoji) |
+| confused（困惑/困扰） | [komaru-kaomoji](https://www.kaomojiya.org/komaru-kaomoji) |
+| shy（害羞） | [shy-kaomoji](https://www.kaomojiya.org/shy-kaomoji) |
+| playful（俏皮/卖萌） | [shy-kaomoji](https://www.kaomojiya.org/shy-kaomoji)（てへぺろ 系） |
+| encourage（鼓励/加油） | [hagemasu-kaomoji](https://www.kaomojiya.org/hagemasu-kaomoji) |
+| thanks（感谢） | [thanks-kaomoji](https://www.kaomojiya.org/thanks-kaomoji) |
+| sorry（道歉） | [sorry-kaomoji](https://www.kaomojiya.org/sorry-kaomoji) |
+
+顔文字屋的页面声明可免费使用（无需注册，商用・非商用均可）。本插件仅收录其人工精选子集，并在 `catalog.json` 中保留来源标注。本插件本体以 MIT 协议发布。
+
+想扩充词库时，请同步修改：
+
+1. [`data/catalog.json`](./data/catalog.json)——完整词库（含来源标注）；
+2. [`lib/index.js`](./lib/index.js) 的 `CATALOG`——真正注入提示词的白名单。
+
+## 本地开发
+
+### 目录结构
+
+```text
+dsh-kaomoji/
+├── lib/
+│   ├── index.js       # 插件入口：config 归一化、规则生成、systemPrompt 段注册
+│   ├── client.js      # Web 端：设置 → 通用设置 的配置卡片（ModuleLoader 格式）
+│   └── index.d.ts     # TypeScript 声明
+├── data/
+│   └── catalog.json   # 情绪 -> 颜文字 精选词库（含来源标注）
+├── test/
+│   └── plugin.test.mjs# node:test 单元测试
+├── cordis.patch.yml   # dsh bundle 挂载补丁
+├── package.json
+├── README.md / README.en.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+### 常用命令
+
+```powershell
+npm test                          # 运行 node:test 单元测试
+npm pack                          # 打包验证发布内容（会先跑 prepack: npm test）
+```
+
+快速查看注入后的提示词规则：
+
+```powershell
+node -e "import('./lib/index.js').then((m) => console.log(m.buildGuidance({ mode: 'frequent', placement: 'end' })))"
+```
+
+### 发布到 npm（维护者）
+
+`dsh plugin --profile web add dsh-kaomoji` 这种裸包名安装依赖 npm 上的正式发布。维护者首次发布前需要登录一次官方 registry（`registry.npmmirror.com` 是只读镜像，不能发布）：
+
+```powershell
+npm login --registry https://registry.npmjs.org
+npm publish --access public --registry https://registry.npmjs.org
+```
+
+`package.json` 已声明 `publishConfig.registry = https://registry.npmjs.org/`，发布后其他人即可直接使用上面的「方式二」。
+
+## 兼容性
+
+- 面向 npm `@deepseek-ai/dsh` rc.7 系运行时；
+- peer 依赖：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-system-prompt`（均为可选声明，由 Web Profile 提供共享运行时）；
+- 与 [dsh-emoji](https://github.com/hellodigua/dsh-emoji) 可共存：提示词段名/排序不同（`dsh-emoji:guidance` @175 vs `dsh-kaomoji:guidance` @176），设置命名空间、RPC 通道、卡片槽位（插件页 vs 通用设置）均无冲突；颜文字是纯文本，dsh-emoji 的流转写只处理规范 Unicode emoji，不会互相改写。
+
+## FAQ
+
+### 为什么模型偶尔没有加颜文字？
+
+`auto` 模式本来就不要求每回合使用；只有 `frequent` 才要求「对话回复都带一个」。如果 `frequent` 下仍经常漏掉，多半是回复被模型判为纯代码/正式交付，或上下文里其它 persona 指令更强势——可用 `customPrompt` 再强调一次。
+
+### 我想用白名单之外的颜文字怎么办？
+
+在 `customPrompt` 中给出精确字符串，例如「这次回复结尾用 (=^･ω･^=) 猫猫颜文字」。规则允许用户显式指定的内容例外；若你希望长期使用，建议把它加入 `CATALOG` 与 `catalog.json`。
+
+### 会污染代码回复吗？
+
+不会。规则明确禁止把颜文字放进代码块、行内代码、链接、表格和工具输出，且代码型回复不适用 `frequent` 的「每条都带」要求。
+
+### 设置卡片在哪里？
+
+在「设置 → 通用设置」底部（主题、语言、回车行为等行之后）。卡片里可切换模式、放置位置、数量上限和附加提示词；保存即生效，也可以在卡片里一键恢复默认。
+
+### 和 dsh-emoji 一起用会冲突吗？
+
+不会产生技术冲突（见「兼容性」）。唯一要注意的是使用节奏：如果两个插件都开 `frequent`，同一条回复可能既带 😊 又带 (´∀｀)。建议只让其中一个保持 `frequent`，另一个用 `auto`（或在对应设置页关掉），观感会更好。
+
+## License
+
+[MIT](./LICENSE)
+
+词库字符来源：[顔文字屋 kaomojiya.org](https://www.kaomojiya.org/)（页面声明免费使用，商用・非商用均可）。

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-kaomoji bundle layer：把颜文字插件挂载进 profile。
+#
+# 纯 insert(id/name) 可热挂载；想改默认行为时，在自己的 profile
+# cordis.patch.yml 里用同一个 id 覆盖 config 即可，例如：
+#   - id: dsh-kaomoji
+#     config:
+#       mode: frequent        # off | auto | frequent
+#       placement: end        # inline | end
+#       maxPerTurn: 2
+- insert:
+    - id: dsh-kaomoji
+      name: dsh-kaomoji

package/data/catalog.json

@@ -0,0 +1,83 @@
+{
+  "schemaVersion": 1,
+  "name": "dsh-kaomoji-core@1",
+  "source": {
+    "name": "顔文字屋 (Kaomojiya)",
+    "url": "https://www.kaomojiya.org/",
+    "note": "本站页面声明：注册、收费均不需要，商用・非商用皆可自由使用。本目录是该站 3000+ 颜文字中的人工精选子集（以适合对话回复的纯颜文字为主），仅供 dsh-kaomoji 本地白名单使用。"
+  },
+  "categories": [
+    {
+      "id": "happy",
+      "labels": { "zh": "开心/高兴", "en": "happy" },
+      "sourceUrl": "https://www.kaomojiya.org/happy-kaomoji",
+      "examples": ["(´∀｀)", "(´∀｀*)", "( ◜ω◝ )", "＼(^o^)／", "(*´▽`*)"]
+    },
+    {
+      "id": "love",
+      "labels": { "zh": "喜欢/心动", "en": "love" },
+      "sourceUrl": "https://www.kaomojiya.org/love-kaomoji",
+      "examples": ["(♡´౪`♡)", "(●´ω｀●)♡", "( ˘ ³˘)♡", "(´∀｀)♡", "(｡♥‿♥｡)"]
+    },
+    {
+      "id": "sad",
+      "labels": { "zh": "难过/低落", "en": "sad" },
+      "sourceUrl": "https://www.kaomojiya.org/sad-kaomoji",
+      "examples": ["(´；ω；`)", "(´；ω；｀)", "(｡•́︿•̀｡)", "(〒﹏〒)", "(இωஇ)"]
+    },
+    {
+      "id": "cry",
+      "labels": { "zh": "大哭/泪目", "en": "cry" },
+      "sourceUrl": "https://www.kaomojiya.org/cry-kaomoji",
+      "examples": ["｡ﾟ(ﾟ´Д｀ﾟ)ﾟ｡", "(T_T)", "(ಥ_ಥ)", "(つд⊂)", "( ；∀；)"]
+    },
+    {
+      "id": "angry",
+      "labels": { "zh": "生气/不满", "en": "angry" },
+      "sourceUrl": "https://www.kaomojiya.org/angry-kaomoji",
+      "examples": ["(｀ε´)", "ヽ(`Д´)ﾉ", "(# ﾟДﾟ)", "( ｀_ゝ´)", "(¬˛¬ )", "( ･᷄ὢ･᷅ )"]
+    },
+    {
+      "id": "surprised",
+      "labels": { "zh": "惊讶/震惊", "en": "surprised" },
+      "sourceUrl": "https://www.kaomojiya.org/odoroiteru-kaomoji",
+      "examples": ["( °Д° )", "Σ(*ﾟдﾟ*)", "Σ(ﾟﾛﾟ;)", "（〇o〇）", "(๑°ㅁ°๑)"]
+    },
+    {
+      "id": "confused",
+      "labels": { "zh": "困惑/困扰", "en": "confused" },
+      "sourceUrl": "https://www.kaomojiya.org/komaru-kaomoji",
+      "examples": ["(´･-･`)", "(^_^;)", "(´･ω･`)", "( -᷄ω-᷅ )", "(｡ŏ﹏ŏ)", "╮( •́ω•̀ )╭"]
+    },
+    {
+      "id": "shy",
+      "labels": { "zh": "害羞/不好意思", "en": "shy" },
+      "sourceUrl": "https://www.kaomojiya.org/shy-kaomoji",
+      "examples": ["(〃ﾉдﾉ)", "(*ﾉωﾉ)", "(///ω///)", "(//∇//)", "(〃▽〃)"]
+    },
+    {
+      "id": "playful",
+      "labels": { "zh": "俏皮/卖萌", "en": "playful" },
+      "sourceUrl": "https://www.kaomojiya.org/shy-kaomoji",
+      "examples": ["(・ω<)", "(｡•ω<｡)", "(∩_∩)", "(〃´∀｀〃)"]
+    },
+    {
+      "id": "encourage",
+      "labels": { "zh": "鼓励/加油", "en": "encourage" },
+      "sourceUrl": "https://www.kaomojiya.org/hagemasu-kaomoji",
+      "examples": ["(•̀ω•́)✧", "(｡•̀ᴗ-)✧", "(๑•̀ㅂ•́)و✧", "(ง •̀_•́)ง", "(つω`｡)"]
+    },
+    {
+      "id": "thanks",
+      "labels": { "zh": "感谢", "en": "thanks" },
+      "sourceUrl": "https://www.kaomojiya.org/thanks-kaomoji",
+      "examples": ["(人´∀`)", "(*´▽`人)", "(*˘︶˘人)", "m(_ _)m", "⸜(*ˊᵕˋ*)⸝"]
+    },
+    {
+      "id": "sorry",
+      "labels": { "zh": "道歉", "en": "sorry" },
+      "sourceUrl": "https://www.kaomojiya.org/sorry-kaomoji",
+      "examples": ["(人'д`o)", "(´｡･д人)", "(｡-人-｡)", "m(_ _)m"]
+    }
+  ]
+}