dsh-fireworks：DeepSeek Harness 烟花庆祝引擎

前言¶

在 Agent 编程过程中，及时的反馈机制有助于提升开发体验。DeepSeek Harness (DSH) 提供了插件扩展能力。dsh-fireworks 是一个插件，能在对话窗口上空渲染烟花，根据不同的事件触发庆祝效果。它不直接干扰交互，而是作为一种视觉反馈存在。

核心功能¶

六类事件驱动¶

插件针对 DSH 的特定生命周期事件配置了不同的烟花效果：

• session/created：开场迎宾（如双子星、青门初开）。
• turn/end：回合礼花，规模随 token 变化。
• tool：工具调用成功星花，1.4s 内合批连放。
• milestone：累计 token 里程碑大礼（2k/8k/20k/50k/120k/300k 六档）。
• todo：任务全部完成时的收工终场（多弹齐射）。
• fail：工具失败时的哑炮（克制幽默）。

基于 Token 的规模映射¶

烟花的盛大程度由 token 用量决定。计算公式为 outputTokens + 0.2 * inputTokens，通过 log₂ 曲线映射为 magnitude（0..1）。该数值插值控制星数、爆速、爆炸高度、亮度和饱和度。

视觉与渲染¶

• 卡组与变体：内置 30 张属性卡和 20 种花型（牡丹、菊、柳、冠毛、频闪等）。支持稀有度系统（1-5）和洗牌袋不放回抽取，确保同事件连发时变种不重复。
• 渲染引擎：优先使用 WebGL2 GPU 渲染，利用三桶累积缓冲实现长曝光质感，使用点精灵径向衰减和 8bit 量化防残影。若 WebGL2 不可用，自动回退至 Canvas2D。
• 一发多色：支持按概率配比混色，color.bands 可定义不同颜色的星群占比。

集成与控制¶

• 零侵入：使用 position:fixed; pointer-events:none 的透明浮层，不遮挡对话交互。
• 自适应：自动识别页面底色亮度，浅色主题下自动切换墨色渲染；深浅主题切换实时跟随。
• 显示范围：支持全屏、侧边栏、角落等多种显示模式。
• 设置与性能：提供设置页总开关、全局强度滑杆、各类独立开关及试放按钮。具备性能自律机制：粒子上限、帧时降质、页面隐藏暂停、prefers-reduced-motion 支持，以及宿主侧令牌桶限流（10 枚/5s）以防止子 Agent 风暴刷屏。

安装¶

执行以下命令安装插件：

dsh plugin --profile web add @weibaohui/dsh-fireworks -w

安装后重启 dsh web 即可生效。入口位于 设置 → 烟花庆祝。

典型用法¶

1. 自动触发：正常进行 Agent 编程，插件会自动根据事件触发对应烟花（新会话迎宾 → 每轮礼花 → 工具星花 → 里程碑 → 终场齐射）。
2. 手动试放：在设置页使用各类别的「试放」按钮，或点击「全部试放」查看效果。
3. 控制台调用：在浏览器控制台输入 __dshFireworks.fire('finale', 0.9) 触发终场齐射。
4. 预览引擎：直接在浏览器打开 demo/demo.html 进行测试（?shot=1 连放，?demo=1 录播）。

依赖与要求¶

• DeepSeek Harness 版本需 >= 0.1.7-rc.2。
• Node.js 版本需 >= 22.5。
• 依赖 @deepseek-ai/cordis 作为 peer dependency。
• 依赖 @weibaohui/dsh-plugin-kit。

结尾¶

dsh-fireworks 将代码执行的反馈具象化为视觉体验，适合希望在 Agent 开发中获得仪式感或即时反馈的开发者。源码与文档位于 GitHub。