THEWOLFWALKER/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