# Rainbow Fart-DSH 产品需求与版本迭代

文档版本：1.1　更新日期：2026-09-24　维护对象：DSH Web 插件 `rainbow-fart-dsh`

## 1. 产品目标

让 AI Coding 中可观察到的进展得到即时、有节奏的正向反馈：成功事件形成连击，积分明确可查，每轮结束有简短评价；达成较苛刻条件时，在会话两侧出现可自定义的惊喜效果。插件是趣味反馈层，不把积分或赞美当作代码质量、测试通过、部署成功的证明。

**使用场景**：用户在 DSH Web 中进行编码；希望能随时看到分数与规则，并按个人偏好选择主题、动画、音效和角色。插件不改变 Agent 的工具执行及会话日志。

**当前交付边界**：本机 DSH Web、当前浏览器中的设置与会话积分。未发布到公共插件市场；没有跨设备同步。

## 2. 版本总览

状态说明：**已打包**代表存在对应本地安装包；**本机安装**代表当前 DSH Web 使用该版本；**待验收**代表代码已具备但相应真实场景还没有观察到。

| 版本 | 迭代目标与主要变化 | 状态 |
| --- | --- | --- |
| 0.1.0 | 初版鼓励层：成功工具调用、完成轮次形成连击；3/5/8 连击增强提示；失败打断；音效开关与可选 Jev 语义判断。 | 已打包 |
| 0.2.0 | 加入会话积分和可展开的计分规则；刷新后保留积分，预览不计分。 | 已打包 |
| 0.2.1 | 澄清 Jev 只影响鼓励提示，不改变积分，并修正文案。 | 已打包 |
| 0.3.0 | 加入每轮短评与最近评价展示，评价依据本轮积分，可受已启用的 Jev 判断调整。 | 已打包 |
| 0.3.1 | 轮次结束时先显示本地积分评价；Jev 返回后仅在需要时改档，避免等待模型才出现评价。 | 已打包 |
| 0.4.0 | **自定义与双侧彩蛋迭代**：主题、动效、音效、可选 Jev、烟花、鲸鱼娘、替换素材和严格触发条件。 | 已打包 |
| 0.4.1 | 修复鲸鱼娘图片路由的 DSH 请求配置，并为左侧效果避开侧边栏。 | 已打包 |
| 0.4.2 | 增强烟花可见度，完善关闭动效与系统减少动态效果时的表现。 | 已打包 |
| 0.4.3 | 根据用户提供的两张参考图重绘默认鲸鱼娘透明立绘，保留原有彩蛋规则与自定义替换入口。 | 已打包并本机试装；旧图片缓存阻碍页面展示新图 |
| 0.4.4 | 更新默认图片资源地址，取消图片缓存，以便新立绘在页面刷新后加载。 | 已打包、曾本机安装；页面预览已确认新立绘 |
| 0.4.5 | 彩蛋改按本轮达到过的最高连击判定，避免长回复使轮末瞬时连击过期；计分与 10 分钟冷却不变。 | 已打包、曾本机安装；回归测试通过，真实合格新轮次待验收 |
| 0.5.0 | 将积分与操作面板改为跟随视口的左侧竖向侧栏；窄窗口回退横条，设置中可主动切换；减少重复几何状态更新。 | 已打包、曾本机安装；宽屏/窄屏与滚动验收通过 |
| 0.5.1 | 设置与规则浮层改为不透底，缩短竖栏旁设置面板的最大高度，改善文字可读性。 | 已打包、曾本机安装；设置面板已在真实会话中视觉复核 |
| 0.5.2 | 竖栏贴近左侧导航边缘；规则弹窗加入按工具名和完成轮次汇总的真实积分明细，旧分数单列；总分和明细数字快速滚动到最终值。 | 已打包、曾本机安装；贴边布局、旧分数展示、数字动效和窄屏回退已在浏览器验收；真实新工具事件明细待观察 |
| 0.5.3 | 左侧面板收为窄竖条，只保留品牌图标、连击状态与操作入口；总积分和最近评价移入 `?` 弹窗。 | 已打包、本机安装；宽屏、窄屏、滚动和弹窗已在浏览器复核 |
| 0.5.4 | 整理公开仓库、MIT 许可、可复现安装说明和 CI；修正 JPEG 上传提示，音频上传后自动选中自定义音色；适配并验证 DSH 0.1.7-rc.1。 | 源码检查与本机 Web 冒烟验证通过；真实模型轮次仍待验证 |
| 0.5.5 | 得分弹窗显示本次分数、本轮前三类活动明细；`?` 面板增加分类汇总，保留原始工具名；支持 DSH PTC 子工具事件并避免外层 `run_code` 重复计分。 | 已发布并本机安装；真实 Web 检索计分、刷新持久化已验证，PTC 与 Skill 真实轮次待观察 |
| 0.5.6 | 在插件设置里加入 Jev API 密钥保存、状态与删除入口；复用 DSH 凭据服务，J 按钮可直达配置；未配置时本地计分照常工作。 | 自动化测试与隔离 Web 的保存／刷新／删除流程通过；有效 TypeSafe 密钥的真实调用待验收 |

0.1.0–0.5.3 是**本地原型的历史记录**，不等同于公开发布历史。旧安装包不包含在本仓库；当前实现以本目录的源码及 `package.json` 为准。0.5.4 起的公开版本以对应 GitHub 标签为准。

## 3. 当前需求与验收口径

### 3.1 连击、积分与规则展示（0.1–0.2）

1. 成功工具调用基础分 +10；无失败的完成轮次基础分 +20。每次按**计分后的连击数**计算倍率：1–2 次 ×1、3–4 次 ×2、5–7 次 ×3、8 次及以上 ×4。明细按工具名汇总实际得分，而不是给不同工具设定不同基础分。
2. 90 秒内的连续成功延续连击；超时重开。失败清空连击，不扣历史积分；本轮有失败则完成轮次不加分。
3. 宽屏左侧窄竖条展示连击与操作入口，靠近导航边缘；空间不足时回退到右下角横条。总积分、最近评价、规则和按工具汇总的得分明细在 `?` 弹窗展示。积分与明细在当前浏览器按会话保存；刷新后连击重新开始。历史事件不追溯补分，预览不计分。升级前未保存工具名和单次得分的积分作为“此前累计”展示，不伪造归因。
4. 新版开始记录逐项汇总，当前总分等于“此前累计”与所有明细行之和。明细按会话持久化，最多保留 19 种独立工具名，更多工具合并为“其他工具”；无法关联工具名的结果标为“未识别工具”。计分数字在约 420ms 内滚动到最终值；关闭动效或系统要求减少动态效果时立即显示。Jev 不参与计分；普通鼓励提示的冷却时间不影响计分。
5. 0.5.5 起，得分弹窗显示本次得分与原始工具名，并显示本轮得分最高的三个分类：Web 检索、Skill、文件操作、终端命令、浏览器、完成轮次、其他工具、未识别工具。`?` 弹窗显示全部分类汇总和原始工具明细；分类分数必须与新增逐项明细之和一致，旧积分仍单列。PTC 子工具事件按其实际工具名计分，已计分的子工具不能再因外层 `run_code` 成功而重复计分；同一失败不得重复提示。预览只展示标记为示例的明细，不改变积分。

### 3.2 轮末评价（0.3）

每次 `turn/end` 给出短评并保存最近一次结果。按**本轮积分**定档：0「蓄势待发」、1–29「小试牛刀」、30–79「渐入佳境」、80–159「鬼斧神工」、160–279「巅峰之作」、280 及以上「惊世骇俗」；失败轮次为「重整旗鼓」。评价先按本地积分即时显示。

用户开启且 Jev 可用时，`none` 至多「小试牛刀」，`steady` 至多「渐入佳境」；`breakthrough` 概率至少 0.6 时可升一档。Jev 超时或不可用时保留本地评价。

### 3.3 高度自定义（0.4）

1. **UI**：深海、极光、糖果、极简主题；点缀色、面板透明度、弹窗位置与弹出／滑入／淡入形式可调。0.5.0 起，宽屏默认在正文左侧留白区展示随视口固定的侧栏；0.5.3 起收为窄竖条，总分与最近评价在 `?` 弹窗中查看。空间不足时自动回到右下角横条，也可手动选择横条。
2. **动效**：关闭、轻柔、完整三档；系统请求减少动态效果时停用粒子和弹入动画。窄窗口隐藏双侧彩蛋，避免遮挡正文。
3. **音效**：默认关闭；可选清脆音阶、街机、海浪和弦，调整音量，或上传不超过 500 KB 的 MP3/WAV/OGG/WebM 音频。
4. **语义判断**：Jev 独立开关，默认关闭。用户开启且 Host 有凭据时才调用；密钥不会由 Host 返回给浏览器，也不会存入插件的浏览器设置。Jev 不可用时本地连击、积分和评价继续工作。0.5.6 起，可在 ⚙ 设置内保存或删除 TypeSafe API 密钥；J 按钮在未配置时直达入口。设置页区分密钥是否存在与密钥是否有效，保存后不会自动启用 Jev。Host 通过 DSH 凭据服务持久化，环境提供的只读密钥在 UI 中不可覆盖。
5. **彩蛋内容**：双侧烟花、鲸鱼娘鼓励或组合可选；鼓励语、角色尺寸、烟花数量及持续时间可调；可上传不超过 1 MB 的 PNG/JPEG/WebP/GIF 替换角色。预览不计分、不消耗冷却时间。
6. **保存**：自定义设置保存在当前浏览器；恢复默认设置不清除积分。

### 3.4 彩蛋触发规则（0.4）

仅在新的、成功完成的 `turn/end` 检查；同一轮不能有失败。默认须同时满足：**本轮曾达到至少 8 连击**、本轮积分至少 200、距上次彩蛋至少 10 分钟。轮末瞬时连击可能因最后一条回复超过 90 秒而重置；彩蛋使用本轮最高连击，积分仍沿用原规则。上述阈值、开关和效果均可在设置面板调整。可选开启 Jev 门槛；开启后还须得到 `breakthrough` 且概率至少 0.75。默认不依赖 Jev。

彩蛋放在会话正文两侧留白区域，不拦截鼠标操作。默认角色参考用户提供的两张图中蓝发、水手帽、蓝白裙装与鲸鱼玩偶的形象重新绘制，并允许用户替换。

## 4. 验收与剩余验证

### 0.5.6：Jev API 配置入口

隔离的 DSH 0.1.7-rc.1 Web 实例中，未配置密钥时 J 按钮打开设置并聚焦密钥输入框，Jev 开关禁用而预览与本地计分仍可用。保存无效测试密钥后，界面只显示“检测到 API 密钥（未验证）”，输入框清空，Jev 开关可手动启用；刷新后状态仍在。测试密钥不在浏览器 localStorage 或状态接口响应中。删除测试密钥后状态变为未配置，Jev 开关重新禁用。375px 视口中配置卡片无横向溢出，浏览器控制台无错误。Host 测试覆盖空值、含空格、超长值、只读来源、保存、删除和不回显。当前**未使用有效 TypeSafe 密钥验证真实 Jev 请求**。

### 0.5.5：得分明细弹窗

2026-09-24 在隔离的 DSH 0.1.7-rc.1 Web 实例中，预览弹窗显示 Web 检索、Skill、文件操作三类示例明细；预览前后浏览器存储保持不变。375px 窄屏中弹窗保持在视口内。19 项规则及 Host 测试通过，覆盖普通工具、PTC 子调用、外层 `run_code` 去重、失败及分类分数求和；GitHub 推送与 PR 的 CI 均通过。

安装 v0.5.5 并重启本机 3080 服务后，在新会话执行一次真实模型轮次：发生两次 `web_search`，轮末弹窗显示“Web 检索 ×2 +20、完成轮次 +40”，总分 60；`?` 面板同时显示分类汇总与原始工具 `web_search ×2 +20`。刷新后积分、明细和最近评价保留，连击归零。浏览器控制台无错误。真实 PTC 子调用与 Skill 调用尚未观察，相关计分目前以模拟 DSH 事件的规则测试为证据。

### 0.5.4：DSH 0.1.7-rc.1

2026-09-24 本机执行 `npm run check`，17 项测试全部通过，`client.js` 语法检查通过。插件通过 `dsh plugin --profile web add` 安装，`--dump-config` 中出现 bundle。DSH Web 在 `127.0.0.1:3080` 启动；未经授权访问页面和插件接口返回 401。浏览器中插件栏、计分弹窗、连击预览、设置面板均可操作；预览后总分仍为 0。默认角色图片接口返回 PNG 200；主题设置刷新后保留；900px 视口使用横条，1717px 视口使用左侧竖条；浏览器控制台无错误。用 1×1 PNG 和静音 WAV 检查了上传与刷新后的保存；自定义图片可在彩蛋预览中正常加载，音频上传后会选择自定义音色并保持静音开关原状态；测试结束已恢复默认设置。当前测试用 DSH 会话没有配置模型 API Key，因此**尚未实测真实模型轮次的工具事件计分、自动彩蛋和 Jev 请求**。不同音频格式的实际播放仍待验收。

### 0.5.3 历史记录

| 项目 | 0.5.3 于 2026-09-24 的证据与状态 |
| --- | --- |
| 核心规则 | 0.5.3 的 `npm run build`、`npm test`（17 项）及 `node --check client.js` 均通过。既有测试覆盖按工具名汇总倍率后的实际得分、完成轮次得分、旧积分保留，以及长回复后本轮最高连击保留。 |
| 本机安装 | 0.5.3 已在本机安装并重启 DSH Web，服务监听 `127.0.0.1:3080`；原会话积分 6480 与用户设置均保留。 |
| 可见效果 | 1717 × 993 视口中，导航边界为 280px，窄竖条左边距 288px、宽 48px，外层不展示总分。点击 `?` 可见“当前总分 6480”、最近评价和明细；设置面板从竖条右侧打开。正文滚动 380px 时竖条纵向位置不变；900 × 800 视口自动回退右下角横条，横条也不展示总分。此前已验收数字滚动动效、双侧烟花、新版鲸鱼娘和鼓励气泡预览。 |
| 新积分明细 | 纯规则测试通过；升级后尚未直接观察真实新工具调用写入对应工具名一行，待下一次真实调用验证。旧积分没有可准确还原的工具逐项记录。 |
| 自动彩蛋 | 浏览器的 `egg.lastAt` 说明旧版曾进入真实触发路径，但当时的视觉与声音未被直接观察；**0.4.5 修复后**尚未等到冷却结束并用真实合格新轮次验收。 |
| 自定义素材与音效 | **待验收**：上传后跨刷新保留、不同音频格式实际播放及浏览器存储额度边界尚未逐项实测。 |

2026-09-24 排查记录：浏览器当时记录的最近一次真实彩蛋触发距读取时约 2 分钟，因而处于 10 分钟冷却；1717px 视口中左右留白区均满足渲染宽度。另通过固定时间的 20 次成功工具调用与超时轮末用例，复现了旧版只看轮末瞬时连击的缺口。两者是独立事实，不能仅凭记录断言用户所见的每一轮具体被哪一项拦截。

下一次验证优先让真实新轮次达到设定门槛，确认自动触发、冷却和积分不受影响；再用小型自定义图片与音频做一次上传和刷新检查。验证通过后更新本表，无须为了验证单独虚增版本号。

## 5. 后续版本记录规则

新增需求先在本节写**目标、范围、验收标准与状态**，版本号确定后补入版本总览。每次变更记录：版本号、用户可见变化、规则或兼容性变化、安装状态、实际验证、已知缺口及对应安装包。只有实现、安装和真实运行都得到证据时，才分别标注这些状态；不把「已计划」写成「已交付」。

### 后续方向候选（未定版号）

以下是用户提出的方向，**尚未定范围或承诺版本**：

| 方向 | 进入实施前要确认的目标与验收 |
| --- | --- |
| 性能优化 | 先测量长会话中的事件处理、布局测量、动画流畅度及内存；只针对实测瓶颈做小范围优化，保留计分和事件去重语义。0.5.0 仅去除了重复的几何状态更新，不代表完成整体性能优化。 |
| 更多音效 | 确定希望增加的音色和触发层级；保留静音、音量和自定义音频入口，逐个预览并检查浏览器自动播放限制。 |
| 更精致的 UI | 确定主题、排版、动效与设置面板的视觉优先级；覆盖宽屏、窄屏、系统减少动态效果及键盘操作。 |