dsh-memes-reply
让 DSH 在回复里贴一张会动的蓝色大肥鱼表情包。素材经插件自有 HTTP 路由直出，保留动画（动画 WebP，默认保留全部帧）。
- 模型按语境用一个工具挑图，一轮最多一张（硬性拦在工具层，不指望模型自觉）
- 素材不进系统提示词：157 张全在
index.json 里，靠关键词/中文标签检索
- 不动任何既有 UI：图片用 markdown 内联进回复正文，流式打字期间就能看到
- 原生风格的配置面板（设置 → 插件 → 可配置）：实时状态行 + 12 个配置字段 + 素材预览墙，"点一张＝下一轮贴它"
- 常驻挂件：页面上一直有一只大肥鱼（点一下换一张、可拖、可收成小圆点）——随时能看到
- 自动贴纸（B-auto）：模型没贴时，按规则不问模型也补一张（关键词命中 / 每 N 轮），出现在输入框上方
- 一键关掉：面板总开关 +
/fish off 本会话静音
安装
# 1) 装进 web profile（会把包加进依赖与 bundle 层）
dsh plugin --profile web add "link:D:\developing\DSH-plugin\dsh-memes-reply"
# 2) 生成压缩素材与缩略图（首次必做；同时写 ~/.dsh 与包内 assets/）
node scripts/import-assets.mjs --format webp --also-package --thumbs
# 3) 重启 dsh web（bundle 层与客户端脚本清单都在启动时读取）
dsh --profile web --dump-config 里能看到 id: memes-reply 就说明装对了。
装好后 node test/live-probe.mjs 会一次性把客户端 bundle、贴纸字节、缩略图、清单、
「下一轮用这张」与状态行全部打一遍。
配置面板
位置：设置 → 插件 → 可配置（和 dsh-hmm-wait 并排）。形态对齐原版折叠卡片
（标题 + 描述 + 未保存徽章 + chevron → 展开体 → 底部 丢弃/保存），全部用 --dsw-alias-* 主题变量。
| 区域 | 内容 |
|---|
| 状态行 | 素材张数 / 格式 / 总体积 / 已服务次数 / 生效的 index.json 路径（12 秒轮询 + 手动刷新） |
| 字段 | 总开关、呈现形态、画质来源、压缩副本目录、原图目录、冷却轮数；每个字段右侧「默认」＝清掉该字段的覆盖（官方 scope.unset） |
| 预览墙 | 12 格缩略图（静态首帧，均值 7 KB）＋「换一批」；点一张即 POST /latch 设为下一轮指定，并加载全尺寸动画确认 |
| 底部 | 换一批 · 取消指定 · 丢弃 · 保存 |
配置字段走官方 ctx.settingsScope（草稿→保存，revision 冲突自带恢复），落盘到
~/.dsh/settings.yaml 的 dsh-memes-reply: 段；状态行/预览墙/指定走插件自己的同源路由。
用法
| 入口 | 说明 |
|---|
工具 use_sticker(mood, id?) | 模型自己调：mood 是2–4 字情绪词（得意、翻车、摸鱼、bug、收工…）。form=inline 返回可粘进正文的 markdown；form=sticker 只回"已交给贴纸层"，正文零 URL |
/fish | 状态 + 前 40 张清单 |
/fish list <关键词> | 过滤清单 |
/fish on | /fish off | 本会话静音开关（状态持久在 <DSH_HOME>/memes-reply/state.json） |
/fish <id|关键词> | 给下一轮指定一张（一次性；优先于面板的全局指定） |
/fish mode inline|sticker | 本会话形态覆盖（sticker = 正文零 URL，模型挑的那张改走贴纸层） |
| 设置面板 | 状态行 + 12 个字段 + 预览墙 + 「下一轮用这张」（全局一次性指定） |
常驻挂件：随时能看到大肥鱼
页面上一直有一只大肥鱼（默认右下角，128px 圆形）。它坐在 shell.overlay ——
官方对那个座位的定义就是 frame-wide floating layer，加法型（replaceRisk: none），
而且整层 click-through、条目自己 opt in 到 pointer events，所以它不挡下面的界面。
（这也是你原来那只 鲸鱼娘 的模型：~/.dsh/pet.json 里就是 display: {visible, size, right, bottom}。）
| 行为 | 说明 |
|---|
| 点一下鱼身 | 换一张（随机取一张） |
| 拖动 | 移动位置；落点写进 state.json，刷新/换会话都还在 |
| 悬停 | 浮出 ✨ 换一张 / ✕ 收起 |
| 收起后 | 变成 32px 小圆点（用缩略图当图标），点它随时再展开 |
| 设置 | 常驻挂件开关 / 大小（64–320）/ 默认停靠角 |
自动贴纸（B-auto）：不问模型也能贴
模型"用不用"是概率，你要的是确定性 —— 所以有第二条路：host 自己判断，客户端自己画。
| 环节 | 做法 |
|---|
| 输入 | host 观察 llm/stream 的 text-delta，攒下这一轮的助手正文（有上限，只用于扫词） |
| 决策 | 最后一步的流结束时（这一步没调工具 ⇒ 正文已完整）就决策；agent/turn-stopping 只作兜底，且对同一轮幂等 |
| 传递 | 结果进"待取位"，客户端每 0.8 秒轮询 /auto/pending；拿到就放进落地仓（src/store.ts，按轮次索引） |
| 渲染 | conversation.chat.turnTail 上的气泡角圆贴纸（见下），点图看大图、✕ 收起 |
为什么是"隐形轮询器 + 落地仓 + 链式座位"三件套
链式座位的 select 是同步纯函数（只拿得到 {turn, seq, openFile}，没有 sessionId，也不能异步），
所以自己发不了请求。于是拆成三件：
- 隐形轮询器（
conversation.input.dock，渲染 null）：这个座位常驻且拿得到 sessionId，负责把待取位搬进仓；
- 落地仓（
src/store.ts）：按 turn 索引 + 新鲜度 + 收起标记，peek(turn) 是纯查询（反复调用不会"消费"掉，否则贴纸会闪一下就没）；
- 链式座位（
conversation.chat.turnTail，priority: 10）：select 同步查仓，有就接下渲染，没有就让位。
autoMode 三档：
keyword（默认）：整词命中某个标签/别名才贴（"修好了"→ Bug、"收工"→ 庆祝）。不看整段文本打分，而是反向扫 157 条的关键词表，命中最长的那个词。every：每 N 轮必贴一张（autoEveryTurns，确定性挑图：hash(会话:轮次)，可复现）。off：只由模型决定。
三道闸门（任一命中就不补），避免"两条路同时贴"：
- 模型这一轮已经贴过（同一轮最多一张这条纪律对两条路径都成立）；
- 本会话被
/fish off 静音；
- 命中的贴纸在最近用过列表里（与手动贴纸共享冷却）。
代价与取舍：
- 轮询 0.8 秒一次本地 JSON（
autoMode=off 时响应只有几十字节）；
turnTail 是竞争性链，我用 priority: 10 排在 present 交付卡片（priority: 0）之后：
有交付卡片的回合不显示贴纸，但交付卡片本身完全正常 —— 这是刻意的让位，不是 bug；- 链的 ownerProps 里没有
sessionId，组件里用 matched.sessionId === props.sessionId 再核对一次；
万一误判，失败模式只是"这一回合不显示"。
绑定：为什么按 seq 而不是按轮次号
真事故（trace 实证，2026-09-16）：
21:52:01 host:publish turn=22 id=tanhao ← host 认为这是第 22 轮
21:52:02 client:poll-event turn=22 id=tanhao ← 事件已正确送达
21:52:05 client:select turn=20 miss ← 客户端来问的是第 20 轮
host 的轮次号来自 agent/pre-step（agent 计数器），客户端的来自 TurnLocation.turn
（会话事件计数器）—— 同一时刻差 2，而且差值会漂移。所以"按轮次号对齐"这条路本身不成立
（我最初写的 ±1 兜底只是碰运气）。
改用 ownerProps.seq（该轮 finalNode 的会话序号，单调递增、跨编号体系稳定）：
| 步骤 | 规则 |
|---|
| 事件到达 | 记下"已见过的最大 seq"作为水线 |
| selector 判定 | 本轮已认领过 → 稳定返回；编号恰巧一致 → 直接命中；否则第一条 seq 越过水线的尾巴接手 |
| 页面刚加载就收到事件 | 水线还是 0 → 用第一条渲染的尾巴立基线，不接手（否则历史上最旧的那一轮会抢走它） |
| 组件挂载 | claim(turn) 把待绑定那张搬到本轮，之后本轮稳定返回、别的轮次再也拿不走 |
| 保留时长 | 客户端仓 30 分钟（比 host 投递 TTL 长得多）：every 在轮次开始就发布，而长回合可能跑十几分钟 |
备选 conversation.chat.assistant-actions 看着更合适（list 加法型、还给 messageId），
但被否掉了：data-actions-reveal=hover 的 CSS 只命中 .actions 容器，而 extraActions
渲染在它内部 —— 贴纸会跟着图标行在旧回合一起被 hover 隐藏。尾巴链的内容是它的
兄弟节点，不受影响。
时序：为什么 every 模式在"轮次开始"就发布
链式座位的 select 是渲染期同步判定，而轮询是 800ms 一次 —— 如果等到"流结束"才发布，
渲染那一刻仓里大概率还是空的（发布到渲染的窗口只有几十毫秒），约 94% 的回合必然 miss，
而且那个节点之后不会再重渲染。所以：
| 模式 | 发布时机 | 理由 |
|---|
every | agent/pre-step（轮次开始） | 不需要正文，越早越稳：事件必然先于尾巴节点渲染进仓 |
keyword | 最后一步的流结束 | 需要正文；仍有极小概率赶不上，此时下一轮的 ±1 兜底会把它补上（晚一轮显示） |
模型 form=sticker | 工具调用时 | 更早，天然安全 |
另外修掉两个"会静默不出图"的坑：
- 游标跨进程失效：重启后 host 的
seq 归零，而浏览器里的旧游标还停在上一进程的值 →
event.seq <= since 会把事件永久过滤掉。现在 pending 会把"超前"的游标夹回 0。
- 坏轮次号：
every 模式下 turn 缺失时 NaN % 1 !== 0 → 永远不发布且零报错。
现在轮次号/间隔非法一律按 1 处理（宁可按规则贴一张，也不要静默不贴）。
出问题时怎么查（/stats.trace）
这条链有四个环节：host 决策 → 待取位 → 客户端轮询 → 链式座位渲染。任何一环静默失败都表现为
"什么都没出现"。所以两端都把关键动作写进同一个内存环形缓冲（最新 48 条，不落盘），
GET /api/dsh-memes-reply/stats 的 trace 字段一次读全：
| 谁记的 | kind | 说明 |
|---|
| host | host:tap-installed / host:tap-no-session | 模型流观察者挂上了吗 / 请求里没带 sessionId |
| host | host:final-step | 最后一步（没调工具）→ 该决策了 |
| host | host:turn-stopping | 兜底路径触发 |
| host | host:bail | 为什么没贴（总开关 / autoMode=off / 本轮已贴 / 静音 / 模型已贴 / 索引缺失 / 没选中） |
| host | host:publish | 已发布（带 id 与 reason） |
| 浏览器 | client:poller-mount | 隐形轮询器挂上了（带它拿到的 sessionId） |
| 浏览器 | client:poll-alive | 心跳（ticks/since）→ 证明真的在轮询 |
| 浏览器 | client:poll-failed / client:poll-event | 请求失败 / 收到事件（带 response.turn） |
| 浏览器 | client:select | 链式选择器判定（hit:<id> / miss，带 owner 的轮次号） |
| 浏览器 | client:bubble-mount | 气泡组件真的挂载了（带 event.turn） |
对照 client:select 的 turn 与 host:publish 的 turn，就能立刻看出"两侧轮次号是否一致"。
顺带修掉一个真会静默失效的 bug：every 模式下若轮次号缺失，NaN % 1 !== 0 会永远不发布、
且没有任何报错。现在轮次号/间隔非法时按 1 处理（宁可按规则贴一张，也不要静默不贴），
并有回归测试钉住。
为什么自己写路由
官方 /api/file 是给"正文里显示本地文件"准备的，但它 Cache-Control: private, no-store、无 Range、且带连接服务鉴权；贴纸动辄几百 KB 到 3 MB，靠它会每次渲染重下。自带路由可以：
ETag（素材 sha256）+ Cache-Control: private, max-age=31536000, immutable → 同一张只下载一次- 只接受回环 Host，不发任何 CORS 头（与
dsh-showme-html 同款围栏）
- id 走白名单正则（
^[a-z0-9][a-z0-9-]{0,39}$），不存在路径穿越面
也没有走 DSH 附件流水线：那条路会把 GIF 归一化成静态图（只留第一帧），鱼就不动了。
为什么别的会话不贴纸（以及怎么解决）
工具对所有会话都可用——扫全部会话日志可见：装好之后跑过的别的会话，请求里都带着
use_sticker（ds-tts 连续 6 轮都带着），但一次都没调用过。原因是它排在 71 个工具的目录末尾，
在正常写代码/查问题的流程里，模型没有理由去动一个"装饰性"工具；可用 ≠ 会用。
所以插件除了注册工具，还往系统提示里加一行（ctx.systemPrompt.section()，顺序锚在所有内置工具
说明之后）：
情绪合适时（问题修好、踩了坑、夸一句、任务收工）可以用 use_sticker 贴一张大肥鱼；一轮最多一张，用户说不要图时别贴。
- 只在 工具真的注册了 + 总开关开着 + 本会话没被
/fish off 静音 时输出，否则输出空串（0 token）；
- 约 60 token/请求；把总开关关掉就全省掉；
- 想要确定性（每条回复都有图、完全不问模型）得靠 M2 的客户端贴纸层，那是另一条路。
素材与画质
原图 460 MB / 500×500 / 50fps。50fps 对卡通贴纸是浪费，但既然选了"保留全部帧"，压缩就只动尺寸与质量：
| 档 | 参数（动画 WebP） |
|---|
| 1–3 | 320px · q60 / q50 / q40 |
| 4 | 280px · q40 |
| 5 | 240px · q35 |
| 6 | 200px · q30 |
320px 是前端 markdown 图片的满尺寸显示上限（CSS width:auto; max-width:100%），再大纯属浪费。
# 默认：保留全部帧，单张上限 700 KB（体积换顺滑）
node scripts/import-assets.mjs --format webp --also-package
# 降到 25fps：动作仍比 GIF 顺，体积省掉约 1/3（推荐在意外体积时用）
node scripts/import-assets.mjs --format webp --fps 25 --also-package
# 想换回 GIF（体积最小，帧率会被阶梯砍到 10–20fps）
node scripts/import-assets.mjs --format gif --also-package
node scripts/import-assets.mjs --thumbs --also-package # 只补缩略图（设置面板预览墙）
node scripts/import-assets.mjs --dry-run # 只看会做什么
node scripts/import-assets.mjs --reindex --also-package # 只重算元数据+标签，不重新编码
当前产物：157 张 / 85.9 MB / 均值 560 KB（全帧的代价）。assets/ 跟着仓库走的话建议用
--fps 25 减半到 ~45 MB，或把 assets/ 加进 .gitignore（运行时主力其实是 ~/.dsh 那份）。
改素材语义/标签：编辑 scripts/sticker-map.json（128 条：id + 中文 tags + 英文 aliases），重跑导入。
id 是 ASCII 短名（dianzan、aixin-2），进 URL；原名只留在索引里。
词的纪律（踩过两次）
凡是展示给模型看的词，都必须能被自己的检索器命中：工具描述里的例子、系统提示里的场景短语、
失败文案里建议的重试词——全都有回归测试盯着。
踩过的两次：描述里写「得意」却检索不到；提示里写「任务收工」导致模型传「扒源码收工」也检索不到。
检索器对中文是容忍的：修好了→修好、踩了坑→踩坑、扒源码收工→（含）收工 都能落到图上，
而 ≤2 字的短查询（点赞、哭）行为不变。匹配不上时工具会明说可以重试并给出保证命中的词；
设置里的「兜底贴纸」（默认关）能让它无论如何都贴一张，并如实标注是兜底。
查"最近到底有没有人用上"：
node scripts/scan-sticker-usage.mjs # 每个会话：提示是否进请求 / 工具是否可用 / 是否真调用 / 出了几张图
开发
npm run typecheck # tsc --noEmit（host + client 全量）
npm run build # tsc 出 host（lib/*.js + d.ts）→ tsdown 出客户端 bundle（lib/client.js）
npm run check:client # 客户端 bundle 纯净化检查（宿主依赖不得进浏览器）
npm test # 先 build + 纯洁检查，再跑 53 个测试
node test/live-probe.mjs # 对正在运行的 GUI 打活体探针（bundle/字节/304/缩略图/清单/latch/状态行）
测试分四类：route.test.mjs（路由分支：字节/缩略图/清单/latch/围栏）、search.test.mjs（检索，含
"工具描述里的示例词必须命中"的回归）、apply.test.mjs（桩服务跑 apply()，串通"工具→URL→字节→
限额→/fish→面板指定"）、index.test.mjs + thumbs.test.mjs（真实产物体检）、client-bundle.test.mjs（产物契约）。
浏览器半边的纪律：src/client/** 只能 import react、@deepseek-ai/dsh-client-* 和本包的
types.ts/protocol.ts/config.ts。绝不能 import schema.ts（会把 schemastery 打进浏览器），
这条由 npm run check:client 强制。
已知局限
- 形态 B 已实现：
form=sticker 时模型挑的那张走贴纸层（正文零 URL），另有 B-auto 的自动贴纸
- 配置面板只在 Web GUI 存在（Electron/CLI 没有这个 surface），不影响 host 侧功能
- 预览墙依赖缩略图：没跑过
--thumbs 时该格降级成名字 chip（不会破图）
- 动画 WebP 需要现代浏览器（Chrome/Edge/Firefox，Safari 14+）；老浏览器只会显示第一帧
- 图片只在 Web GUI 有意义：CLI/headless 场景里 markdown 只是文本，URL 会变成噪音
- 路由无 Range：图片是整文件读（单张 ≤16 MiB 上限）；WebP 本身已压缩，不做 gzip
- 素材字节走
ctx.fs：会话处于受限沙箱模式时读取可能被拒，此时工具不产出 URL（宁可让模型换一张，也不出破图）
- 原图目录是可选项：
quality=original 需要自己填 originalRoot，否则静默回落压缩副本
POST /latch 没有鉴权（本机任意页面可调）：只影响"下一轮贴哪张"，且有回环围栏 + 不发 CORS 头 + id 白名单
文件地图
| 路径 | 作用 |
|---|
src/index.ts | host 装配：路由 + 工具 + 命令 + 设置 + 轮次观察者 |
src/route.ts | 七条端点：/sticker、/thumb、/catalog、/latch、/auto/pending、/pet、/stats（回环围栏、ETag/304） |
src/tool.ts | use_sticker：选图（会话指定 > 面板指定 > id > 检索）、每轮限额、形态分支 |
src/assets.ts | 索引加载与三根解析（原图 → assetRoot → 包内 assets；缩略图同理） |
src/search.ts | 关键词检索（纯函数，中文反向包含 + 同分按名字短优先） |
src/command.ts | /fish |
src/auto.ts | 自动贴纸引擎：文本缓冲、规则（keyword/every）、待取位、流观察者 + "最后一步"信号（纯函数可测） |
src/store.ts | 贴纸落地仓（按轮次索引 + 新鲜度 + 收起标记），host 与浏览器共用、纯逻辑可单测 |
src/prompt.ts | 系统提示里的一行"贴纸可用"提示（按开关/静音/工具是否注册动态输出） |
src/state.ts / src/schema.ts / src/config.ts / src/turn.ts / src/protocol.ts / src/types.ts | 状态、设置 schema（含 schemastery）、纯常量、每轮账本、共享常量与类型 |
src/client/index.tsx | 浏览器半边：注入样式 + 注册 settings.plugin.item、shell.overlay、conversation.input.dock、conversation.chat.turnTail |
src/client/pet.tsx | 常驻挂件（点击换图 / 拖拽 / 悬停工具 / 收起成小圆点） |
src/client/bubble.tsx | 气泡角圆贴纸（链式座位，让位交付卡片） |
src/client/poller.tsx | 隐形轮询器（拿 sessionId 喂落地仓，渲染 null） |
src/client/panel.tsx / api.ts / auto.ts / styles.ts | 折叠卡片、同源数据通道、轮询封装、主题变量 CSS |
scripts/import-assets.mjs | 压素材 + 缩略图 + index.json（零依赖，只要 ffmpeg） |
scripts/sticker-map.json | 128 条语义 → id/tags/aliases（人工可改） |
scripts/check-client-purity.mjs | 客户端 bundle 纯净化门禁 |
