dsh-gamepad-approval

Readme

<div align="center">

# 🎮 dsh-gamepad-approval

### 让 AI 的每一个高危操作，都过你手柄这一关

**Xbox 手柄硬件审批插件** · for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness)

[![npm version](https://img.shields.io/npm/v/dsh-gamepad-approval?style=flat-square&color=107C10&label=npm)](https://www.npmjs.com/package/dsh-gamepad-approval)
[![npm downloads](https://img.shields.io/npm/dt/dsh-gamepad-approval?style=flat-square&color=107C10)](https://www.npmjs.com/package/dsh-gamepad-approval)
[![dsh plugin](https://img.shields.io/badge/dsh-plugin-4D6BFE?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
[![platform](https://img.shields.io/badge/platform-Windows-0078D6?style=flat-square)](https://github.com/goldgish/dsh-gamepad-approval)
[![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

</div>

---

## 📖 这是什么

当 Agent 想执行 `rm -rf`、`git push --force`、格式化磁盘这类高危操作时——

**你的手柄会震动两下，然后等你表态：**

<div align="center">

| 🟢 **A 键** | 🔴 **B 键** |
|:---:|:---:|
| 批准，放行 | 驳回，拒绝执行 |

</div>

审批信号走的是**物理按键**——不在键盘上，不在浏览器里，不在网络上。

> 键盘输入可以被键盘记录器窃取，屏幕点击可以被远程控制伪造，
> 但**没有人能隔空按下你手里的手柄**。

---

## ⚡ 30 秒上手

```bash
dsh plugin --profile default add dsh-gamepad-approval
```

装完即生效。Agent 碰到高危命令 → 手柄震两下 → 你按 A 或 B，就这么简单。

---

## 🔐 为什么「物理审批」有效

| 攻击面 | 传统软件审批 | 手柄审批 |
|:---|:---:|:---:|
| 键盘记录器 | ❌ 可被记录 | ✅ XInput 协议，不走键盘 |
| 远程桌面操控 | ❌ 可被模拟点击 | ✅ 需要物理按压 |
| 恶意脚本自动确认 | ❌ 可伪造弹窗事件 | ✅ 硬件层信号，无法注入 |
| 钓鱼 / UI 劫持 | ❌ 可伪造界面 | ✅ 震动来自你自己的手柄 |

**设计哲学：fail-closed**

无手柄、超时、断连、读不到输入——**一律驳回**。
宁可打断 Agent，绝不放过风险。

---

## 🛡️ 内置 18 条权限规则

覆盖常见高危操作，命中即触发手柄审批：

| 类别 | 示例 | 风险 |
|------|------|:---:|
| 文件删除 | `rm -rf`、`Remove-Item`、`del /f` | 🔴 critical |
| 系统关机 | `shutdown`、`Stop-Computer` | 🔴 critical |
| 磁盘操作 | `format`、`diskpart`、`dd if=` | 🔴 critical |
| 系统配置 | `reg add`、`schtasks`、`systemctl` | 🔴 critical |
| 数据库破坏 | `DROP TABLE`、`TRUNCATE` | 🔴 critical |
| 远程脚本执行 | `curl … \| sh` | 🔴 critical |
| Git 破坏性操作 | `push --force`、`reset --hard` | 🟠 high |
| 密钥访问 | `cat *.pem`、`echo $*_KEY` | 🟠 high |
| 防火墙 | `iptables`、`netsh firewall` | 🟠 high |
| 进程终止 | `taskkill /f`、`kill -9` | 🟠 high |
| 全局安装 | `npm i -g`、`choco install` | 🟡 medium |
| 脚本执行 | `npx`、`npm run`、`bash -c` | 🟡 medium |

---

## 🧩 工作原理

```mermaid
flowchart LR
    A[🤖 Agent 发起 tool-call] --> B{命中高危规则?}
    B -- 否 --> E[✅ 直接放行]
    B -- 是 --> C[🎮 手柄震动两下]
    C --> D{等待物理按键}
    D -- A 键 --> F[✅ 批准<br/>委托 dsh 后续安全门]
    D -- B 键 / 超时 / 断连 --> G[🛑 驳回<br/>fail-closed]
```

插件挂载在 dsh 的 `tools/pre-execute` 管道上，通过 PowerShell 直连手柄（XInput），**不经过浏览器或任何网络层**。

硬件批准只是「加一道门」——放行后仍会走 dsh 自带的全部安全策略，不会绕过其他防线。

---

## ⚙️ 配置

```yaml
- insert:
  - id: gamepad-approval
    name: dsh-gamepad-approval
    config:
      timeoutSeconds: 120   # 等待手柄按键的超时秒数（超时即驳回）
      minRiskLevel: medium  # 触发审批的最低风险等级: low | medium | high | critical
```

嫌打扰太多？把 `minRiskLevel` 调成 `high`，只对真正危险的操作震动手柄。

---

## ❓ FAQ

**Q: 必须是 Xbox 手柄吗？**
任何 XInput 协议的 PC 手柄都可以——包括北通、飞智、八位堂等国产手柄的 Xbox 模式。

**Q: 不插手柄会怎样？**
高危操作会被直接驳回（fail-closed）。Agent 会收到明确的拒绝原因，普通操作不受影响。

**Q: 和浏览器里的审批弹窗有什么区别？**
弹窗跑在软件层，理论上可被同权限的恶意代码模拟；手柄按键是硬件信号，攻击者需要**物理出现在你面前**。

**Q: 和 trea-gamepad（MCP 版）什么关系？**
同一个创意的两个实现：trea-gamepad 面向 Trae（MCP 协议），本插件面向 dsh（cordis 插件体系），核心逻辑与手柄脚本完全一致。

---

## 📄 License

MIT © [goldgish](https://github.com/goldgish)

<div align="center">

**如果这个项目有意思，欢迎点一个 ⭐ Star**

</div>