---

📖 这是什么

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

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

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

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

---

⚡ 30 秒上手

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

---

🧩 工作原理

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 自带的全部安全策略，不会绕过其他防线。

---

⚙️ 配置

- 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