dsh-dock-launcher

DeepSeek Harness 开关（常驻状态型程序坞应用）

简体中文 | English

中文：常驻程序坞的 DeepSeek Harness 开关 —— 左键点击回到/启动 dsh 网页界面，右键打开菜单（停止服务、动画开关）；图标实时显示服务与任务状态，并在任务完成或需要确认时发光提醒。

English: An always-on Dock toggle for DeepSeek Harness — left-click to open or start the dsh web UI, right-click for the menu (stop service, animation toggle). The icon mirrors live service/task state and glows when a task finishes or needs confirmation.

仓库：https://github.com/wjingshan/dsh-dock-launcher

⬇️ 下载最新版（Release） — 解压后把 App 拖进「应用程序」即可。

一个运行在 macOS（Apple Silicon / M4）上的常驻小程序：程序坞图标 = 拨动开关。 左键点击 = 启动 / 回到 DeepSeek Harness（dsh）网页界面；右键点击 = 操作菜单（停止服务、动画开关等）。 图标实时呈现服务与任务状态，并在任务完成 / 需要确认 / 等你选择时做动态提醒。

界面语言跟随系统，内置 简体中文 / English / 日本語 / 한국어（可在「系统设置 → 通用 → 语言与地区 → 应用程序」单独指定本 App 的语言）。

八张图放在同一列、而不是排成一行：GitHub 的 max-width: 100% 会把图片压缩到所在单元格的宽度。 横排时每列宽度都不同（实测 121～235px），每张图就被压成不同尺寸，看起来"大小不一"；放在同一列则 共用同一个列宽，无论视口多宽，八张图的显示尺寸必然完全一致。

点下图标立刻进入「启动中」：关闭态红胶囊上绿色从左端扫满（0.3 秒通电，前缘带一道柔光），此后 胶囊保持绿色，白色滑块在整只胶囊里左↔右往复（余弦，两端速度为零；一个来回 1.1 秒）——「开关已经 通了电，还在等服务就绪」。服务就绪时滑块从当前位置平滑滑到右端停住（0.25 秒归位），落定那一帧与 「运行 · 空闲」图标逐像素一致，无缝接管。启动失败（未找到 dsh / 起不来 / 120 秒无响应）则是 绿色从右端退去、滑块滑回左端，并在中间那颗圆钮上弹出红色 ✕（0.55 秒入场，之后静止），同时 弹出原因说明。

上表里「任务进行中 / 任务完成 / 需要确认 · 单选 / 多选」都是动图。dsh 停下来等你选分支（ask_user_question）或审批计划（exit_plan_mode）时进入「需要你介入」态——DeepSeek 与 HARNESS 分别向上下让开、开关上的白圆点放大成一个大圆角方形、里面浮现蓝色符号，随后不停循环，直到你在 dsh 页面做好选择、dsh 继续运算，才播放反向动画收回成开关：

• 需要确认（审批）· 等你选择 · 单选 / 普通提问：圆内是蓝色问号，循环「亮度呼吸」（圆内蓝光一明一暗）。这几种情形共用同一套问号动画（所以表中并作一列），在 App 里的区别只在提示音与通知文案。
• 多选：圆内是蓝色对勾，循环「淡化叠加」——对勾从起点写出 → 画完从起点逐渐褪掉 → 还剩约一半时新一笔从起点重画，两笔同框。

图标使用连续圆角(squircle) 并随系统浅/深色外观自动切换底板配色（下图左：深色外观；右：浅色外观）：

⚠️ 前置要求（别人装了却用不了，多半是这几条）

本 App 是 DeepSeek Harness（dsh）的配套开关，不是独立软件，请先满足：

1. 已安装 DeepSeek Harness，dsh 命令可用，并至少运行过一次 dsh web 完成初始化（否则点图标会提示「未找到 dsh」）；
2. API keys（含 DEEPSEEK_API_KEY）：右键菜单 「编辑 API keys…」 写入 $DSH_HOME/.env（缺省 ~/.dsh/.env，dsh 启动时自动读取并注入所有插件）；也可在 ~/.zshrc 里 export，或在 dsh 网页的 Models 页保存。否则 dsh 发消息会报 no API key，依赖第三方 API 的插件（例如鲸鱼娘 Galgame 的升级 CG 需要 DASHSCOPE_API_KEY）会报缺少 key；
3. （可选）brew install zstd：任务状态监测与提醒需要它；缺失时 App 仍能启停服务，但图标不反映任务状态；
4. 系统要求：macOS 14+，Apple Silicon 或 Intel（通用二进制）；
5. 首次打开：本 App 未使用付费开发者证书签名/公证，若提示「无法验证开发者」或「已损坏」—— 右键 App → 打开，或执行：

   xattr -dr com.apple.quarantine "/Applications/DeepSeek Harness 开关.app"
   

   推荐直接用下面的一键安装（脚本会自动去掉隔离标记）。

App 菜单里也有 「环境自检…」 可以随时查看以上各项的实际状态与修复建议。

一键安装

复制到「终端」执行，自动下载最新版并安装到 /Applications（含去除隔离标记、并自动启动）：

sh -c "$(curl -fsSL https://raw.githubusercontent.com/wjingshan/dsh-dock-launcher/main/install.sh)"

也可以手动安装：从 Releases 下载 .dmg（打开后拖入「应用程序」）或 .zip（解压后拖入）。

首次打开若提示「无法验证开发者」：右键 App → 打开（或 系统设置 → 隐私与安全性 → 仍要打开）。

成品

DeepSeek Harness 开关.app   （当前版本 v0.15.0）

功能

• 点下就有反馈：点击图标后立即切到「启动中」动画（绿色通电 + 白色滑块左右往复），页面出现的这几秒不再是一片空白；成功时滑块归位、无缝变成「运行 · 空闲」，失败则绿电退去并在圆钮上留下红色 ✕，一眼就能区分「还在启动」和「启动失败」。
• 程序坞左键 = 回到页面：优先切回已打开的 127.0.0.1:3080 标签；页面被关了就恢复一个新标签；服务没运行则启动它。打开的是带 token 的完整地址，因此不会落到 401 未授权页：优先读 dock-bridge 插件写的运行时文件，未装该插件时回退解析 dsh 启动日志。
• 程序坞右键 = 操作菜单：打开页面 / 知道了(停止提醒) / 停止服务…（二次确认） / 动画开关 / 打开日志 / 退出。
• 状态图标（6 态）：
  • 关闭（红，滑块左）= 服务已停止
  • 启动中：点下图标立刻播放的通电 + 滑块左右往复动画（见上）
  • 启动失败：关闭态 + 圆钮上的红色 ✕（入场：绿电退去 + 滑块归左 + ✕ 弹入，之后静止），菜单变为「重新启动 DSH 服务」
  • 运行 · 空闲（绿，滑块右）
  • 任务进行中：多色极光流动（蓝→青→绿→紫长色带缓慢流动 + 一道柔光掠过，60fps）
  • 待关注提醒：需要你介入（需确认 / 等你选择）= 变形动画（问号 / 对勾，见下）；任务完成 = 绿色边缘内发光 + 边缘内侧 2px 白色流光
• 动态提醒：需要确认 / 等你选择时播放变形动画（0.9 秒变形 → 落定后循环 → 你做好选择后 0.42 秒反向收回成开关），并伴随弹跳 + 通知 + 提示音——单选 / 普通提问圆内是蓝色问号，循环「亮度呼吸」；多选圆内是蓝色对勾，循环「淡化叠加」（写出 → 从起点逐渐褪掉 → 还剩约一半时重写，两笔同框）；任务完成仍用绿色边缘发光。点图标、选「知道了」或把鼠标移到程序坞也会立即收回。
• 提示音可配置（右键菜单 →「提示音设置…」打开独立设置窗口）：窗口里五种提示各占一行——需确认 / 等你选择 / 任务完成 / 服务启动 / 服务停止，每行可选音效（系统音效 + ~/Library/Sounds）、可点试听按钮；三种提醒还能各自设置重复次数：1 / 2 / 3 / 5 次，或**「直到鼠标移到程序坞」**（鼠标进入程序坞或菜单栏区域即停，无需辅助功能权限）。底部还有「选择音效时自动试听」开关与「恢复默认」；设置持久化保存。
• 关于：右键菜单「关于 …」显示软件名称、版本号（含 build 号）、GitHub 地址与赞助链接，可直接点按钮打开。
• 动画总开关：右键菜单可一键关闭/开启所有图标动画（关闭后为静态图标，弹跳与通知仍保留）；开销极低（仅动画态每帧重绘 128px 图标）。
• API keys 通用入口（右键菜单「编辑 API keys…」）：直接打开 dsh 自己的用户级环境文件 $DSH_HOME/.env（缺省 ~/.dsh/.env，不存在时按 0600 写入带注释的模板）。dsh 启动时读取该文件并注入所有插件与工具进程，所以以后接入任何新 API 只要加一行 KEY=VALUE —— 本 App 不需要跟着改版，也不认识任何具体的 key 名。保存后需要重启 DSH 服务生效（弹窗里可直接点「重启 DSH 服务」）。
• 兜底的 shell 解析：GUI 启动的进程不读 .zshrc，本 App 仍会解析 ~/.zshenv / .zprofile / .zshrc / .bash_profile / .bashrc / .profile 中形如 *_API_KEY / *_TOKEN / *_SECRET / *_PASSWORD / *_CREDENTIAL 的变量（含 *_ACCESS_KEY_ID），并排除 *_PATH / *_FILE / *_DIR / *_URL 这类「名字像 key 其实是路径」的项。已存在的进程环境变量优先；$DSH_HOME/.env 由 dsh 自己读取，本 App 不重复注入，以免两套解析器对同一个值产生分歧。整条链路只读、只写变量名进日志，不记录任何值、不外传。
• 任务状态监测：读取 ~/.dsh/sessions/*/session.jsonl.zstd 活跃会话日志：
  • approval/request、approval/asked → 需要确认
  • turn/end（普通对话回合结束）→ 任务完成；存在活跃 goal 时回合结束不打扰，改为 goal/change（operation == "complete" / goal.phase == "complete"）→ 任务完成
  • turn/start → 进行中
  • tool/call 且工具为 ask_user_question / exit_plan_mode → 等你选择（这两类交互在日志里没有专用事件，只能按工具名识别）

完成提示规则：会话没有活跃 goal 时，一轮对话结束（turn/end）即算完成；会话存在活跃 goal 时，只在整个 goal 真正结束（goal/change · complete）时提示。监测覆盖所有近期活跃会话，多会话并行不漏检。

与同类插件的关系

dsh 生态里已有多个桌面启动器与提醒类项目，本 App 与它们的关键区别在形态：它不是 dsh 插件，而是一个独立的 macOS 原生程序坞应用——dsh 完全没有运行时，它照样在程序坞里待命，左键点一下就把服务拉起来并进入页面。

生态中的相关项目（名称与描述均可对照 awesome-dsh-plugin 精选列表 核实）：

本 App 的组合目前没有第二个项目同时具备：程序坞图标本身就是状态显示与唯一入口（左键回页面 / 右键出菜单），服务未运行时左键直接拉起服务；图标实时区分 关闭 / 启动中 / 启动失败 / 空闲 / 进行中 / 待关注 六态（点下图标就有拨动动画，失败直接留一个红 ✕）；任务完成由真实的 goal 结束事件驱动，多会话并行不漏检。

使用

1. 把 DeepSeek Harness 开关.app 拖进「应用程序」，双击打开（或拖到程序坞固定）。
2. App 启动时如实显示服务状态（未运行则显示红色「关闭」），不会自动拉起 dsh。
3. 左键点程序坞图标 = 启动服务并打开 dsh 页面（已运行则回到页面）。点下后会立刻看到白色滑块左右往复的「启动中」动画；若启动失败，绿电退去、圆钮上出现红色 ✕，右键菜单随之变为「重新启动 DSH 服务」。
4. 右键点程序坞图标 = 打开操作菜单（停止服务需二次确认）。
5. 菜单栏小图标点击可打开同一套菜单。

提示：提醒共有四条通道——Dock 图标动画、程序坞弹跳、提示音、系统通知。系统通知是可选的：不需要横幅的话，右键菜单里选「关闭系统通知」即可，此时连授权框都不会弹（授权只在首次真正要投递通知时才申请）。

权限说明

本 App 只涉及两个系统权限，而且两个都是可选的——不授权也能正常用。

没有申请、也没有使用的权限：辅助功能、输入监控、屏幕录制、完全磁盘访问、文件与文件夹（桌面 / 文稿 / 下载）、麦克风、摄像头、定位、通讯录、日历、照片、登录项。

其中值得一提的是：「鼠标移到程序坞就停提示音」用的是定时轮询鼠标位置（NSEvent.mouseLocation），不是全局事件监听，所以确实不需要辅助功能或输入监控权限。

另外，App 未启用沙盒（entitlements 为空、ad-hoc 签名）：这既是它能自由调用 homebrew 里的 dsh / zstd、读写 ~/.dsh 的前提，也意味着它没有公证——首次打开需要靠 install.sh 去掉 quarantine 标记。

可选增强：dock-bridge 宿主插件

本仓库还附带一个小巧的 dsh 宿主插件 plugins/dsh-dock-bridge。装上它之后，App 不必再去解析 dsh 的启动日志，而是由 dsh 进程直接把端口、PID 和带 token 的地址写出来：

# 从本地路径安装（把路径换成你的克隆位置）
dsh plugin --profile web add /path/to/dsh-dock-launcher/plugins/dsh-dock-bridge

装完重启一次 web profile 即可。要点：

• 插件写 ~/.config/dsh-dock-launcher/runtime.json（权限 0600，因为里面是活的 token），进程退出时删除；SIGTERM 退出路径也覆盖。
• App 只在「上报 PID 仍存活」且「端口仍可连」时才采信该文件，崩溃残留会被自动忽略并回退读日志。
• 不装插件也完全可用：回退路径就是从 ~/Library/Logs/dsh-web.log 里解析带 token 的地址。
• 右键菜单「环境自检…」会显示当前走的是哪条路径。

该插件同时是本仓库向 awesome-dsh-plugin 的投稿条目（它需要一个可 dsh plugin add 安装的宿主插件，而不是纯 .app）。

版本号规范

• 语义化版本，从 0.1.0 开始：
  • patch(+0.0.1) = 修 bug / 小改
  • minor(+0.1.0) = 新增功能 / 行为增强（0.x 阶段的主要改动也走 minor）
  • major(+1.0.0) = 重大改动 / 不兼容（进入稳定期后）
• VERSION = 语义版本号；BUILD_NO = 每次构建递增号（build.sh 自动生成，已 gitignore）。
• 每次改动在 CHANGELOG.md 追加记录。详见 CHANGELOG.md。

构建

cd dsh-dock-launcher
./build.sh          # 一键：绘图标→打包 icns→编译→组装→打包多语言→签名，并注入版本号

• 改图标颜色/造型：src/Icons.swift；改应用图标：src/draw_icon.swift。
• 改启动/监测/提示逻辑：src/ServiceManager.swift、src/TaskMonitor.swift、src/main.swift。
• 多语言文案：resources/*.lproj/Localizable.strings（en / zh-Hans / ja / ko）。

目录结构

dsh-dock-launcher/
├── src/
│   ├── main.swift          # 常驻应用：Dock/菜单栏、监测、动画、通知、左键回页面、右键菜单
│   ├── ServiceManager.swift# 启动/停止/端口探测、通用 API 凭据管线（$DSH_HOME/.env + shell 兜底）
│   ├── TaskMonitor.swift   # 多会话游标、zstd 解压、事件识别
│   ├── Frontmost.swift     # 前台浏览器/标签检测、聚焦或恢复 dsh 页面
│   ├── Icons.swift         # 各状态开关图标 + 菜单栏模板图标 + 动画绘制（极光/发光/流光）
│   └── draw_icon.swift     # 用 CoreGraphics 绘制 App 图标(生成 1024px PNG)
├── resources/              # 界面多语言（en / zh-Hans / ja / ko 的 Localizable.strings）
├── docs/                   # 状态图标预览图 + 支付宝收款码（README 引用）
├── plugins/dsh-dock-bridge/    # 可选宿主插件：提供端口/PID/带 token 地址（可 dsh plugin add）
├── install.sh              # 一键安装到 /Applications
├── Info.plist              # 应用元数据（含 CFBundleLocalizations）
├── build.sh                # 一键构建脚本（读取 VERSION/BUILD_NO 注入版本号）
├── VERSION                 # 语义版本号（第一行）
├── BUILD_NO                # 构建号（每次构建自增，已 gitignore）
├── CHANGELOG.md            # 版本记录
├── LICENSE                 # MIT
├── README.md / README.en.md    # 中文 / 英文说明
└── DeepSeek Harness 开关.app   # 成品（已 gitignore）

许可

MIT © 2026 wjingshan

---

☕ 赞助

DeepSeek Harness 开关 是我自用的小工具，顺手开源出来。如果它帮到了你，欢迎请我喝杯咖啡 ☕