dsh-coyote

English · 简体中文

面向 DeepSeek Harness（DSH）的 DG-LAB 郊狼电击控制插件，同时提供 Agent 工具与网页 GUI 两条控制面。

一个安全边界（CoyoteRuntime）同时约束两张面孔：八个模型侧 coyote_* 工具与浏览器面板。任何一方都无法绕过软上限、非对称升速限制、会话冷却、播放硬上限与断连即停。v0.2 起另有一个可选的自动电击层，把 agent 事件（工具调用、报错、回合结束……）映射为有界脉冲 —— 见自动电击。

仅限成年人。本插件控制真实电刺激设备，使用前请阅读安全须知。

工作原理

DSH Agent ─coyote_* 工具──┐
                           ├─▶ CoyoteRuntime（安全边界）─▶ V3 WebSocket 服务 ─▶ DG-LAB App（扫码）─▶ 郊狼设备
DSH 网页 GUI ─/gui 桥接───┘      软上限 · 升速限制 · 冷却 · 硬上限 · 断连即停
agent 事件 ─自动电击（可选）──┘   布防闸门 · 冷却 · maxIntensity 封顶 · 基线恢复

插件扮演官方 DG-LAB V3 socket 协议的 WebSocket 服务端：配对时生成二维码，官方 App 扫码后，插件即成为控制终端，App 负责把指令转发到设备。

快速开始

dsh plugin --profile web add dsh-coyote

插件的 bundle patch 会自动插入自己的行 —— 无需任何配置即可使用，下方默认值自动生效。需要调参时，在 profile overlay 中按行 id 定位：

- id: coyote
  config:
    port: 9999          # WebSocket 端口；手机必须能访问本机
    softLimitA: 60      # 通道软上限，0..200 —— 按使用者舒适度调整
    softLimitB: 60

1. DSH 网页侧边栏底部出现 ⚡ Coyote 按钮，点击打开控制面板。
2. 点 开始配对，出现二维码。
3. 用官方 DG-LAB App（同局域网）扫码；反向代理场景可配置 publicWsUrl（wss://）。
4. 面板与 Agent 即可共同控制设备 —— 始终在同一个限制之内。

八个工具

| 工具 | 功能 | |---|---| | coyote_status | 完整快照：链路状态、二维码、设备强度、生效上限、剩余冷却，以及（启用时的）自动电击块。只读。 | | coyote_pair | 开始配对；返回二维码内容与可渲染二维码图。 | | coyote_disconnect | 结束会话：停止一切、断开 App 关系、进入冷却。 | | coyote_set_strength | 在 0..200 原始域设置 A/B/双通道。绝对 value 或相对 delta，返回实际施加值与钳制原因。 | | coyote_play_wave | 按预设名、声明式 spec 或原始 hex 播放；once/loop、强度缩放、B 通道镜像。 | | coyote_stop_wave | 停止波形播放，保留通道强度。 | | coyote_panic_stop | 紧急停止：清空双通道波形队列、强度归零。幂等，任何状态下调用都安全。 | | coyote_waveforms | 波形库列表；导入 Game-Hub .pulses JSON 或裸 hex 列表。 |

工具描述本身就在讲解安全模型，模型无需读源码即可正确使用。

安全模型

所有约束在 CoyoteRuntime 中、于任何指令发出之前生效：

| 机制 | 默认值 | 效果 | |---|---|---| | 软上限 softLimitA/B | 100 | 每通道 Agent 侧上限，0..200。 | | 设备硬上限 | App 侧 | 生效上限 = min(软上限, 设备上限)；每次上报都重读，手机端调低立即生效。 | | 非对称升速限制 | 40/秒，突发 40 | 强度上调走令牌桶；下调永远立即放行。 | | 会话冷却 sessionCooldownSec | 3 秒（可调，0 关闭） | 上个会话结束后需等待才能重新配对，防止滥用。 | | 会话硬上限 maxSessionSec | 3600 秒（0 关闭） | 单次绑定会话到时自动结束（停止并归零）。 | | 播放硬上限 maxPlaySec | 600 秒 | 每次播放自动终止，到期同时清空设备队列。 | | 断连即停 | 始终开启 | App 断开即停播、清队列、重置状态。 |

GUI 面板走完全相同的 runtime —— 浏览器绕不过 Agent 的限制，反之亦然。

波形

• 12 个内置预设（呼吸、心跳、惩罚、电锯……）自带建议起始强度，由声明式规格确定性合成（频率扫 10..1000 ms、强度扫 0..100，曲线 linear|sine|pulse|random，可选占空比节奏）。
• 社区波形导入：粘贴 Game-Hub .pulses JSON（[{name, pulseData:[hex…]}]）或裸 hex 列表；校验后持久化到 waveformDir，启动时自动加载。同名重导入为覆盖更新。

自动电击

可选的事件驱动电击（v0.2）：插件监听 DSH 会话事件流与 agent/error / agent/status 运行时事件，把它们归约为十一个封闭的领域事件，对每条启用的规则发出一个有界脉冲。默认关闭 —— autoStim.enabled: true 之前不监听任何事件、面板也不出现该区块。

每个脉冲都是绝对瞬态：通道强度先抬升到 min(规则 intensity, maxIntensity)（runtime 仍会钳到软/设备上限与升速限制），波形播放一次，然后恢复脉冲前强度。刚配对、强度为 0 的设备也能直接工作。

闸门链 —— 每个闸门都通过才触发，被拦下的事件直接丢弃并计数，绝不排队：

| 闸门 | 效果 | |---|---| | 规则启用 | 未启用规则的事件不做任何事。 | | 布防 | GUI 的布防/解除开关；解除后事件静默丢弃。 | | 非忙碌 | 同一时刻最多一个脉冲（含恢复期）。 | | 冷却 | 自动触发之间默认最少 5 秒。 | | App 已绑定 | 无设备连接则跳过并计数。 | | maxIntensity | 独立封顶（默认 30），叠加在每条规则之上。 |

默认规则表（所有强度 ≤ 默认 maxIntensity 30）：

| 事件 | 触发时机 | 默认 | |---|---|---| | turn_start | 新 agent 回合开始 | tap @12、2 秒、开 | | assistant_start | 回合内第一个流式块 | tap @15、2 秒、开 | | stream_tick | 流式输出每 tickIntervalSec（5 秒） | tremor @15、2 秒、关 | | tool_call | 模型调用工具 | tap @20、2 秒、开 | | tool_error | 工具调用失败 | punish @25、6 秒、开 | | agent_error | 回合失败（两个事件源按回合去重） | punish @30、8 秒、开 | | turn_end_completed | 回合正常完成 | heartbeat @20、4 秒、开 | | turn_end_aborted | 回合中止 / 打断 / 阻塞 | calm @12、3 秒、关 | | turn_end_max_tokens | 回合触到 token 上限 | saw @20、3 秒、关 | | todo_clear | 待办全部完成（每个清单只触发一次） | heartbeat @18、4 秒、开 | | agent_idle | agent 运行→空闲边沿 | calm @12、4 秒、关 |

- id: coyote
  config:
    autoStim:
      enabled: true          # 总开关，显式开启才生效
      maxIntensity: 30       # 所有规则之上的封顶，1..200
      cooldownSec: 5         # 自动触发之间的最小间隔秒数
      tickIntervalSec: 5     # stream_tick 节流间隔
      restoreBaseline: true  # 每个脉冲后恢复脉冲前强度
      events:
        tool_error: { intensity: 25, durationSec: 6, waveform: punish, channel: A }
        agent_error: { enabled: false }   # 单字段覆盖，其余继承默认

未知事件名会在启动时带着完整合法列表报错。波形名大小写不敏感解析：先内置 id、再导入波形名（写错则该脉冲失败软并记日志 —— 不会拖垮宿主）。GUI 面板会出现自动电击区块：实时布防状态、触发/跳过计数与布防/解除按钮；coyote_status 携带同一块给模型。插件卸载时解除布防、截断进行中的脉冲并立即恢复基线。

配置项

全部可选，默认值如下：

| 键 | 默认 | 说明 | |---|---|---| | host | 0.0.0.0 | 监听地址。0.0.0.0 让局域网手机可达。 | | port | 9999 | WebSocket 端口。0 表示系统分配。 | | publicWsUrl | — | wss:// 反向代理场景的二维码地址前缀。 | | waveformDir | coyote-waveforms | 社区波形持久化目录。 | | softLimitA / softLimitB | 100 | 每通道软上限，0..200。 | | sessionCooldownSec | 3 | 重新配对冷却秒数；0 关闭。 | | maxSessionSec | 3600 | 单次绑定会话硬上限秒数；0 关闭。 | | maxPlaySec | 600 | 单次播放硬上限秒数。 | | defaultPlaySec | 30 | 工具调用未给时长时的默认值。 | | increaseRatePerSec | 40 | 持续升速（单位/秒）。 | | increaseBurst | 40 | 突发上调预算（单位）。 | | autoStim | enabled: false | 整个自动电击块：enabled、maxIntensity（30）、cooldownSec（5）、tickIntervalSec（5）、restoreBaseline（true）与逐 events 规则覆盖。 |

架构

src/
  protocol/   纯 V3 编解码：帧、波形条目、二维码
  waveform/   合成器（规格→窗口）、库（12 预设）、导入器、调度器
  transport/  WebSocket 服务 + 控制终端角色（绑定、心跳、失败安全）
  runtime/    一切都经过的安全边界
  auto-stim/  rules（事件表+默认值+校验）、mapper（宿主→领域事件）、engine（闸门+脉冲）、attach（cordis 监听）
  gui/        /gui 桥：JSON 操作 ↔ runtime，广播状态
  tools/      8 个 coyote_* 工具定义
client/index.js   浏览器面板（无构建步骤、加载器注入 React、DSH CSS 变量）
tests/            148 个测试：单元 + 协议级 MockApp + 离线客户端 harness

设计准则：协议层纯函数、安全单一咽喉点、工具薄而诚实、不过度设计。所有协议决策的依据均为官方 DG-LAB-OPENSOURCE socket/V3 文档。

开发

pnpm install
pnpm test         # 148 个测试
pnpm typecheck
pnpm build        # 产出 lib/（tsdown）

说明：pnpm build 会打印一条 tsdown↔rolldown 上游校验告警（Invalid input options … "define"），属上游噪音，产物正确。

安全须知

本插件驱动作用于人体的真实电刺激设备。请遵循设备随附的 DG-LAB 安全指引。要点：

• 从个位数强度起步、缓慢上调；开始前与使用者约定上限与停止信号。
• 保留 App 侧硬上限作为最终防线 —— runtime 会动态遵守它。
• 胸部、颈部、头部为不安全电极位置；任何不适或异常反应立即 coyote_panic_stop（它绝不会让情况更糟）。
• 仅在知情成年人自愿的前提下使用。

许可

MIT · 第三方声明见 NOTICE.md