Mac 工具箱 ddxl123/dsh-mac-tools

Mac 工具箱（DeepSeek Harness 插件）

一个 DeepSeek Harness 插件，装好即是一整套 本机 Mac 工具箱：

- 截图（类 QQ）——用 macOS 原生区域/窗口选择框选任意应用，然后进入真正的编辑器：裁剪、箭头、矩形、椭圆、画笔、文字、马赛克、高亮，支持撤销/重做、复制到剪贴板、保存到磁盘。
- 计算器——完整的计算器面板，以及智能体可以精确调用的表达式引擎。
- 手机互传——手机和 Mac 连同一个 Wi-Fi，用手机相机扫二维码，就能用浏览器收发文本、文件、照片；不用装 App，文件不出局域网。
- 剪贴板——在面板或智能体里读写 macOS 文本剪贴板。
- 运行状态——类 App Store 应用 State 的实时监控：CPU/内存/磁盘/网络/电池曲线、系统信息、SMC 温度与风扇、进程排行、阈值告警；以及类 Macs Fan Control 的风扇转速控制（自动 / 手动转速 / 温度曲线 / 预设），首次启用需一次性管理员授权。原「系统信息」页已并入这里。

全部在本机完成。这是一个纯面板插件：只在左侧栏增加 Mac 工具箱 入口，不向智能体注册任何工具。

安装

这是一个普通的 DSH bundle。在任意会话里对插件目录安装即可：

plugin_manager install_bundle target: /绝对路径/dsh-mac-tools

或使用 CLI：

dsh plugin --profile desktop add /绝对路径/dsh-mac-tools

本地目录安装是链接方式。安装后刷新 Web 页面，左侧栏会出现 Mac 工具箱。如果安装时 Host 已经在运行，最稳妥的方式是重启一次 DeepSeek Harness，让两个半端版本一致。在创造模式（启用 HMR）下无需重启：在插件页把 mac-tools 行关掉再打开，会触发配置重组并原地重新加载链接的 Host 代码。

权限

截图需要 系统设置 → 隐私与安全性 → 屏幕录制 → 允许 DeepSeek Harness。没有授权时 macOS 会静默返回一张只有壁纸的图片（或拒绝窗口截图），面板会显示 permission 失败码并提示去哪个开关授权。

不需要辅助功能（Accessibility）权限：区域/窗口选择用的是 macOS 自带的原生选择界面，插件只额外读写剪贴板。

面板

从左侧栏打开，或按 ⌥⌘M。⇧⌘A 直接开始一次交互截图，并打开面板进入编辑器。

⌃⌥A（可配置）是系统级截图快捷键：在任何其它应用拥有焦点时也能按。
它会拉起 macOS 原生区域/窗口选择，然后把截图贴回原来的位置（置顶悬浮窗，覆盖刚才框选的屏幕区域），同时复制到剪贴板、保存到截图目录，并播放 Glass 提示音（不需要自动贴图可设 pinAfterGlobalCapture: false）。
不需要额外权限；原生小助手首次会用 Xcode Command Line Tools 编译一次（开发者 Mac 通常已装）。

快捷键可以在面板里直接自定义：截图按钮下方的「全局截图快捷键」一行点 修改，然后按下新组合（Control/Option/Command + 一个按键；Esc 取消）。自定义结果保存在 profile 的插件状态目录（<profile home>/dsh-mac-tools/hotkey.json），重启不丢失；点 恢复默认 回到 globalHotkey 配置值。
面板内的快速截图快捷键（默认 ⇧⌘A）是 DSH 普通快捷键，可在 设置 → 快捷键 中改键。

截图页

- 区域 / 窗口截图——屏幕变暗后拖拽框选；按 空格 切换到窗口点选模式，按 Esc 取消。
- 全屏截图、窗口截图（点选一个窗口）、3 秒后全屏（延时截图）、选择应用窗口（列出所有可见应用窗口，可搜索，前台窗口有标记，点击即截取）。
- 历史截图：每一次截图（面板截图或 ⌥A 全局截图）都会自动持久保存，并在编辑器下方以缩略图列表展示；点击可重新载入编辑器，也可直接贴图 / 复制 / 删除。
- 贴图可当场标注：双击贴图（或按 A、右键「标注图片」），贴图上会浮出小工具栏——画笔 / 箭头 / 矩形 / 椭圆 / 高亮、颜色、粗细、撤销、清空、完成；在贴图上直接画，复制/保存会包含标注。想用完整面板编辑器时，右键选择「在面板中编辑」即可。
- 「截图时隐藏 DSH」（默认开启）：屏幕截图时自动隐藏 DeepSeek Harness 窗口，截完立即恢复，避免自己的窗口挡住要截的内容；按钮就在截图工具栏上，可随时关闭。
该开关同样作用于全局快捷键截图——快捷键截图没有页面可询问，所以由 Host 记住这个选择（当前 DSH 进程内有效）。
- 编辑器支持 裁剪、箭头、矩形、椭圆、画笔、文字、马赛克、高亮，六种颜色、三档线宽，撤销/重做/还原，复制（PNG 进剪贴板）、保存（保存到配置目录，并可在 Finder 中显示）与 贴图：把编辑后的图片作为置顶悬浮窗钉在桌面上，位置就是截图时框选的屏幕区域。之后可拖动、滚轮缩放、右键菜单（复制 / 保存 / 不透明度 / 关闭），Esc 关闭，⌘C 复制。
- 编辑器快捷键：⌘Z 撤销、⇧⌘Z 重做、Enter 应用裁剪、Esc 先取消裁剪再关闭截图。

计算器页

显示屏 + 键盘 + 历史记录。计算走 Host 的引擎，因此面板和工具对同一个表达式给出相同结果。支持 + - * / % ^、括号、正负号、隐式乘法（2(3+4)）、百分号（50%）、常量 pi/e/tau，以及函数 sqrt, cbrt, abs, round, floor, ceil, trunc, sign, exp, ln, log, log2, sin, cos, tan, asin, acos, atan, atan2, pow, hypot, min, max, mod。三角函数默认按角度制计算。

手机互传页

一个只在局域网内工作的 Mac ↔ 手机中转站。点「开启手机互传」后，Host 会临时起一个 HTTP 监听，显示二维码（和 URL），并开始倒计时。用手机系统相机扫码（或手动输入 URL）即可打开一个免登录网页——不用装 App、不用账号、不走云。

- 手机 → Mac：发文本（进面板收件箱，可一键复制到 macOS 剪贴板，也可配置自动复制）、选文件/照片，或直接拍照上传。上传带进度，文件保存到传输目录（默认 ~/Downloads/DSH 手机互传），智能体可以像普通文件一样读取处理。
- Mac → 手机：输入文本发送、用系统选择框选任意文件，或在最近截图上一键「发送到手机」；手机页面会列出这些内容，可预览、复制或下载。截图直接取自历史记录。
- 安全：每次会话一个随机 token，30 分钟过期；监听只在会话期间存在；服务端校验 Host 头、净化文件名，不向公网暴露。下载响应固定为 attachment + application/octet-stream（绝不当网页渲染），交给手机浏览器/下载管理器原生保存。
- 注意：手机和 Mac 必须连同一个 Wi-Fi（开了 AP 隔离的访客网络不行）；第一次开启时 macOS 可能询问是否允许 DeepSeek Harness 接受传入连接；手机 VPN 可能拦截局域网访问；较新的 macOS 还可能询问本地网络权限。传输期间别让 Mac 休眠。
- 排障：如果手机上传一直停在 0%，或点下载没反应，先把页面重新打开一次再重试；手机页会把浏览器异常、上传超时/停滞、下载失败上报到 <插件状态目录>/transfer/diagnostics.log（即 ~/.dsh/dsh-mac-tools/transfer/diagnostics.log），同时记录每次上传开始/完成与下载请求，不用远程调试就能看出是哪一步失败。

配置

bundle 行支持以下配置（写在 cordis.patch.yml 或之后的 patch 层），都有默认值：

| 键 | 默认值 | 含义 |
| saveDirectory | ~/Pictures/DSH Mac Tools | 截图保存目录，支持 ~ 展开。面板的“保存”和工具都写到这里。 |
| maxShots | 20 | 面板临时保留的截图数量，超过后淘汰最旧的；已保存文件不会被淘汰。 |
| interactiveTimeoutMs | 180000 | 原生选择界面等待操作者的最长时间。 |
| hideAppDuringCapture | true | 屏幕截图时短暂隐藏 DeepSeek Harness 窗口（仅当它是前台应用）并在截完后恢复；面板上有单次开关。 |
| globalHotkey | ctrl+alt+a | 系统级截图快捷键的默认值，任何应用在前台时都可用；面板里修改的值会覆盖它（保存到插件状态文件）；留空则初始不启用全局快捷键。 |
| globalHotkeySound | true | 全局快捷键截图成功后播放 Glass 提示音。 |
| pinAfterGlobalCapture | true | 全局快捷键截图后自动贴图到屏幕（面板编辑器里也始终有手动「贴图」按钮）。 |
| historyLimit | 60 | 历史截图最多保留多少张，超出后删除最旧的。 |
| transferPort | 8791 | 手机互传临时监听的优先端口；被占用时顺延尝试后面 9 个。 |
| transferDirectory | ~/Downloads/DSH 手机互传 | 手机发来的文件保存目录，支持 ~ 展开。 |
| transferSessionMinutes | 30 | 一次手机互传会话的有效期，到期后二维码失效、监听停止。 |
| transferMaxFileMB | 512 | 手机单次上传文件大小上限（MB）。 |
| transferAutoCopyText | false | 收到手机文本时自动复制到 macOS 剪贴板。 |
| monitorSampleMs | 1000 | 「运行状态」页 Host 侧采样间隔（毫秒，500–10000）。软件指标最多每 2 秒采集一次，面板轮询频率可以更快或更慢。 |
| alertCpuPercent | 90 | 首次运行的 CPU 占用告警阈值（%）。面板运行时可改，持久化的选择优先于该默认值。 |
| alertTemperatureCelsius | 95 | 首次运行的温度告警阈值（°C，取 SMC 温度组）。 |
| alertMemoryPercent | 90 | 首次运行的内存占用告警阈值（%）。 |
| alertCooldownSeconds | 300 | 同一指标两次告警之间的最短间隔（秒）。 |
| alertNotify | true | 告警触发时是否发 macOS 通知。 |

- id: mac-tools
config:
saveDirectory: ~/Desktop/Screenshots
maxShots: 30

实现说明

- 原生小助手（assets/）：hotkey.swift 监听系统级快捷键，pin.swift 把贴图显示为浮动的 AppKit 窗口，qrcode.swift 用 CoreImage 生成手机互传二维码；三者首次用 swiftc 编译并缓存到临时目录。smc-core.swift 是共享的只读 IOKit AppleSMC 传输层；state.swift 是常驻采样器，每个采样输出一行 JSON（风扇 + 全部可读温度键）；fan-daemon.swift 是风扇卡片安装的特权助手——只提供 Unix socket JSON 的 F0Md/F0Tg 写入，目标转速夹在 SMC 上下限内，并带 12 秒看门狗自动恢复系统自动控制。
- Host 半端（src/）：在 Connection 的 /api 通道上注册受认证的 /api/dsh-mac-tools 路由，维护临时截图注册表，用 /usr/sbin/screencapture 截图、用 /usr/bin/osascript 获取窗口列表、写图片剪贴板和打开文件选择框。「运行状态」页是一条采样循环（src/monitor.js），底层是 src/metrics.js（CPU/内存/磁盘/网络/电池）、src/smc.js（采样器子进程）、src/alerts.js（阈值）与 src/fans.js（风扇控制与 socket 协议）。手机互传监听（src/transfer.js）是一个独立的、按需启动的 node:http 服务，只在会话期间绑定局域网；它提供手机网页和上传/下载 API，收发索引存在插件状态目录。不注册任何智能体工具。
- Client 半端（client/index.js）：一个由 window.__ModuleLoader__ 加载的纯 React bundle，注册左侧栏入口和 main 面板，渲染四个分页，只通过上面的路由与 Host 通信。
- 截图引擎是对系统工具的一层薄封装——区域/窗口选择、取消、窗口点选都是 macOS 原生行为，不是重新实现。

POST /api/dsh-mac-tools { "endpoint": "...", "payload": { ... } }
GET /api/dsh-mac-tools?shot=<id> → image/png
GET /api/dsh-mac-tools?history=<id> → image/png
GET /api/dsh-mac-tools?inbox=<id> → 手机发来文件的字节

?inbox= 预览只对安全的栅格图片（png、jpeg、gif、webp、avif、bmp）内联返回；其它文件一律以 application/octet-stream 附件返回，手机上传的 HTML/SVG 因此不可能在 Web UI 源上执行。

端点：status、windows、capture、cancelCapture、copy、save、calc、clipboard、system、reveal，手机互传的 transferStatus、transferStart、transferStop、transferInbox、transferOutbox，运行状态的 monitor、monitorProcesses、monitorKill、monitorAlertSave、monitorAlertTest，以及风扇控制的 fanInstall、fanUninstall、fanApply、fanPreset。返回 { ok: true, value } 或 { ok: false, error: { code, message, details } }。

手机访问的是它自己的临时服务 http://<Mac局域网IP>:<端口>/t/<token>/（页面、api/state、api/text、api/upload、api/items/<id>），那不是 Harness 的 API，也不携带 Harness 会话。

开发

npm run check # 所有模块 node --check + node --test test/

Host 半端除 dsh 自带的 @deepseek-ai/schemastery 配置 schema 外无第三方依赖；Client 半端只需要 react。

许可证

MIT