Underwater008/deepshell

DeepShell

官方 DeepSeek Harness 的原生 shell —— macOS 应用 + Windows 安装程序（预览版）。
在 Mac 上约 150 行 Swift 加一个 bash 脚本；在 Windows 上则是零点击安装程序。

⬇️ Download for Windows
windows-release

DeepSHell —— dsh —— 深海之贝。这份致敬正是重点所在：它
名副其实。

它能做什么

- 将官方 DeepSeek Harness（来自 npm 的 @deepseek-ai/dsh，与上游
发布完全一致）作为 launchd 服务运行，登录时启动，
崩溃时重启
- 在原生 WKWebView 窗口中承载官方 Web UI（菜单栏、Cmd+Q、
复制/粘贴）—— 一个真正的 Mac 应用
- 从设置或菜单栏进行手机连接：通过 Tailscale
Funnel 实现持久浏览器访问，并配有二维码 —— harness 本身仍保持在 127.0.0.1，
正如上游所期望的那样
- 手机优先的 Web UI：为 harness 页面打造的移动端界面 —— 画布外
侧边栏抽屉、紧凑顶栏，以及防止 iOS 在你打字时
跳动屏幕的键盘修复（packages/dsh-mobile-ui）
- 让你使用引擎支持的任何 OpenAI 兼容提供商（自定义
baseURL、apiKeyEnv 凭据引用、自定义请求头）—— 自托管 vLLM、
RunPod、Modal、Ollama，随你所用
- 通过自托管的 SearXNG sidecar 为 agent 提供
无需密钥的网页搜索 —— 无需 DeepSeek 或
搜索 API 密钥（search/ + packages/dsh-web-search-searxng）
- 针对本地片段的视频问答：一个 video_qa 工具插件将视频交给
支持视频的 Kimi 模型，并以文本形式返回答案 —— 总结、
转录、定位某个瞬间（packages/dsh-video-qa-moonshot）
- 每次重启时跟踪上游 @latest（或固定某个版本）

安装

Windows（预览版）

⬇️ 下载 DeepShell-Setup.exe
—— 单个 exe，无需终端，无需管理员权限：官方 harness 加上一个便携式 Node
运行时，按用户安装。双击 → 一个进度条 → DeepShell
在它自己的应用窗口中打开。安装细节，包括 Modal 双请求头
密钥，见 WINDOWS.md。macOS 的附加功能（原生应用、手机
连接）尚未纳入 Windows 预览版。

macOS

需要 macOS 12+（Apple Silicon）、Node（通过 nvm 或 Homebrew），以及
可选的 qrencode 和 Tailscale macOS 应用以支持手机连接。无需
iPhone 应用或购买域名。

git clone https://github.com/Underwater008/deepshell.git
cd deepshell
./deepshell.sh install      # launchd 服务：登录时启动，崩溃时重启
./native/build.sh           # 构建 native/DeepShell.app

将 native/DeepShell.app 拖入你的 Dock。在
~/.dsh/settings.yaml（上游 schema）中配置提供商/模型——它会在更新后保留。

该应用包目前需要在每台 Mac 上执行上述设置；仅复制
.app 并不会安装 harness 服务或 phone-connect 插件。

用法

./deepshell.sh open         # 在浏览器中打开 UI（或点击 Dock 应用）
./deepshell.sh status       # 服务状态 + 当前 URL
./deepshell.sh restart      # 同时拉取最新的上游版本
./deepshell.sh tunnel       # 永久手机地址 + 配对二维码
./deepshell.sh local        # 切换回仅 localhost
./deepshell.sh phone install    # 刷新 Settings 卡片并重启 harness
./deepshell.sh mobile install   # 手机优先 UI：抽屉 + 顶栏 + 键盘修复（无需重启）
./deepshell.sh search install   # SearXNG sidecar + harness 接线，一条幂等命令
./deepshell.sh search status    # 健康检查 + 实时查询测试 + 接线检查（也有 start|stop|restart|logs）
./deepshell.sh uninstall

应用中的 Phone 菜单通过二维码窗口执行相同的操作。

移动端 UI（手机优先布局 + 键盘修复）

./deepshell.sh mobile install 将 packages/dsh-mobile-ui 接入 web
profile——这是一个仅浏览器端的插件，会在 768px 及以下的屏幕上重塑 harness 页面，风格类似 ChatGPT-iOS：

- 左侧栏消失。一个紧凑的顶栏（模糊、适配刘海）接管：
汉堡菜单 将侧边栏作为离屏抽屉滑入，覆盖在变暗的背景之上；中间显示会话标题；✎ 开始新聊天。
选择会话、搜索结果或 New chat 会关闭抽屉。
- 输入时屏幕不再跳动。 iOS Safari 仍然忽略
interactive-widget=resizes-content（WebKit bug 259770），因此该插件
将 window.visualViewport 跟踪到 CSS 变量中，将应用尺寸调整为
可见区域，并反向平移 Safari 的键盘平移——输入框
会直接停靠在键盘上方。文本输入还设置了 16px 最小值，以便 iOS
在聚焦时停止自动缩放。（Chromium/Android 则使用标准的
interactive-widget=resizes-content meta。）
- 输入框边距收窄，拖拽手柄消失，并且会尊重 home indicator /
刘海的安全区域。

它在下次页面加载时生效——无需重启 harness，无需批准提示
（它是一条受信任的 composition 行，就像 phone-connect 卡片一样）。桌面
窗口不受影响；将任意浏览器窗口缩窄到 768px 以下即可预览。
如果上游版本发布了自带的移动端布局，或者你想恢复默认行为，
./deepshell.sh mobile uninstall 会移除该补丁行（同样即时生效）。

从 Web UI 连接手机（Settings 卡片）

手机访问也可通过 Settings → Plugins → Remote
卡片（packages/dsh-phone-connect）使用，由 deepshell.sh install 自动安装：

./deepshell.sh phone install   # 刷新现有安装并重启
./deepshell.sh phone status    # 检查连接状态

手机访问使用 Mac 上的 Tailscale Funnel；iPhone 使用 Chrome、
Safari 或其他兼容浏览器。不要求使用 Safari。
Funnel 提供 HTTPS 主机名，因此你无需购买域名。
安装独立的 Tailscale Mac 应用，
使用你自己的账户登录，并允许 macOS 网络扩展。在提示时为这台
Mac 启用 HTTPS/Funnel，然后在
DeepShell 中选择 启用永久访问。如果提供商需要设置，卡片会说明缺少的步骤。

在你偏好的浏览器中打开配对链接或扫描二维码一次。登录后，
在同一浏览器中收藏该简洁地址。浏览器会话是独立的，因此从 Safari 切换到 Chrome 也需要配对 Chrome。
只要 Tailscale 设备名称和网络保持不变，该地址在 DeepShell 和 Mac 重启后
都保持不变。配对令牌
在 harness 启动时会轮换，但现有浏览器会话在重启后仍然有效
（默认 30 天）。过期或已清除的浏览器会话需要重新扫描。

卡片区分 保存此地址 和 配对手机。其 API
仍位于 harness 会话以及 Host/Origin 检查之后。保存的连接
状态位于 ~/Library/Application Support/deepshell/phone/，在
Git 之外。CLI、原生菜单和设置使用相同的连接实现。

每次安装都使用该 Mac 上当前登录的 Tailscale 账户，
并获得该设备的地址。DeepShell 不捆绑任何开发者账户、共享身份验证
密钥或个人连接状态。其他用户必须
使用自己的账户完成设置；他们的连接不会经过开发者的 Mac 或 Tailscale 账户。

- 退出 DeepShell 会停止其服务；重新打开会在同一地址恢复已启用的远程
访问。关闭窗口会保持服务运行。
- 在 Mac 登录时，launchd 会启动 harness。如果 Tailscale 稍后连接，
DeepShell 会自动重试保存的连接。
- 关闭 会在重启后保持。DeepShell 绝不会在没有明确操作的情况下启用新的
永久连接。
- Mac 必须处于唤醒状态并联网。启用 FileVault 时，重启后可能需要本地
登录才能运行应用；远程访问无法在启动时解锁 Mac。
- HTTPS 监听器是公开的，但 DeepShell 访问仍然需要登录。
请妥善保管配对二维码。该应用会保留无关的 Tailscale 服务。
- Funnel 在所有 Tailscale 套餐中都可用，但有带宽限制。
Personal 套餐用于非商业用途；商业用途需要合适的
套餐。请参阅 Funnel 和
定价。DeepShell 不会选择任何付费套餐。

较旧的 Cloudflare 快速隧道会保持可见，直到你关闭它们或
成功启用了永久连接，从而实现了受控升级。

退出的含义（生命周期）

DeepShell 遵循“关闭查看器，而非工作；退出即退出”：

- 关闭窗口只是隐藏 UI——harness 和你的 agent
会话会继续运行。点击 Dock 图标即可重新打开；你的 Web 会话
仍然存在。
- 退出应用（Cmd+Q / 右键点击退出）会停止一切：
launchd harness 服务、任何手机转发器，以及 SearXNG 搜索
边车（deepshell.sh stop-all）。重新打开会恢复已保存的永久
连接以及 harness 和搜索边车。
- 更喜欢常开服务器？服务 → 退出后保持服务运行
可选择退出，同一菜单会显示实时的
Harness: running · Search: running 状态，以及手动
立即停止服务。

Web 搜索（无需 API 密钥）

harness 内置的 web_search 工具出厂即接入 DeepSeek 的带密钥
端点。DeepShell 则改为向 harness 的 ctx.web 接缝注册一个微小的
提供方插件（packages/dsh-web-search-searxng），该插件查询本地
SearXNG 实例——一个
免费的元搜索引擎，聚合 70 多个公共引擎，无需密钥，无跟踪。

- ./deepshell.sh search install 会在 Docker 中于
127.0.0.1:8890 启动 SearXNG，并在同一条命令中接入 harness：它会将
提供方插件安装到 web 配置文件中，并添加下面的补丁行。
幂等——全新克隆只需这一条命令（外加重启 harness 以刷新
设置卡片）。DeepShell 在非标准端口上运行它自己的实例，
而不是采用 8888 上已有的任何东西：
拥有该实例意味着拥有引擎集和排名。预置的
settings.yml 在上游默认值之上启用了 google、github 和 mdn——
上游默认禁用 google，而其他主流
引擎（Brave/DDG）会对繁忙 IP 限流，这正是默认安装
最终返回空结果或文档引擎噪音（对于新闻查询）的原因。
- 配置文件补丁层（~/.dsh/profiles/web/cordis.patch.yml）——在缺失时由
search install 写入——将 web 接缝指向
searxng-local 提供方，并挂载插件行；它会热重载，无需
重启 harness。
- ./deepshell.sh search status 是“它是否正常工作？”的检查：容器
健康状态、带结果计数的实时查询测试，以及 harness 接线是否存在——
不涉及 API 密钥，因此这里“已配置”和“正常工作”
是一回事。
- 插件行配置：baseURL（任何可访问的 SearXNG）、可选的 engines
（逗号列表，按查询覆盖）、language、safeSearch。优先使用
实例侧引擎配置（search/settings/settings.yml），而不是
engines 临时方案——受限的集合也会扭曲结果排名。
- 设置可见性：该包附带浏览器端部分，因此
设置 → 插件会显示一个“Web 搜索（SearXNG）”卡片，其中包含实时的
端点/引擎/语言/safeSearch 值（只读，反映
web-search-searxng 设置部分）。在 ~/.dsh/settings.yaml 或补丁层中编辑；更改会实时生效。

第三方模型，完整工具集

将原版配置指向其目录中未提供的模型——比如 Kimi K3——该模型会被假定为仅支持文本：在请求离开你的 Mac 之前，附加图片就会被拒绝。DeepShell 使用完整的上游 schema 在 ~/.dsh/settings.yaml 中配置提供商，其中每个模型都可以声明其真实能力：

providers:
moonshot:
baseURL: https://api.moonshot.ai/v1
apiKeyEnv: MOONSHOT_API_KEY
models:
- id: kimi-k3
input: [text, image]   # 原版配置缺失的那一行

根据 Moonshot 的文档，Kimi K3 本身已经能理解视频——引擎当前的模态接缝是文本/图像，因此一旦上游适配器添加支持，原生视频就会落地。在那之前，下面的 video_qa 工具已经可以回答关于本地视频片段的问题。

视频问答（工具中介，现已可用）

引擎的模态接缝是文本/图像，因此视频目前还无法作为附件传递——但模型已经能“看到”它。packages/dsh-video-qa-moonshot 注册了一个 video_qa 工具，将本地视频直接交给 OpenAI 兼容端点，并以工具文本形式返回答案：总结片段、转写语音、描述场景、定位某个时刻。

- 两种传输方式，根据该行的 baseURL 自动检测：moonshot-files（通过 POST /v1/files 上传，然后引用 ms://——这是 api.moonshot.ai 的文档化流程）和 video-url（为 vLLM 系列服务器内联 base64）。行配置：baseURL、apiKeyEnv、model、transport、maxVideoMB、timeoutMs。
- 已通过 video-url 针对 RunPod 托管的 Kimi K3 进行实时验证。视频支持取决于服务端：同一权重的 Modal vLLM 部署返回了 Kimi-K3 supports image input only——该工具会原样呈现这个错误，因此你始终知道该修复哪一侧。
- 密钥通过 harness 凭据存储（apiKeyEnv）按调用解析，与官方提供商使用同一链路；配置中不含密钥材料。
- 无需 harness 即可对任意端点进行冒烟测试：
node packages/dsh-video-qa-moonshot/scripts/smoke-test.mjs --path clip.mp4

超越 Bearer 的提供商认证——为什么 Modal 在其他 shell 中“永远不工作”

RunPod 在任何地方都能工作，因为它遵循普通的 OpenAI 约定：一个密钥，以 Authorization: Bearer  发送。

Modal 不会给你一个密钥。Modal 代理令牌 是一个 Token ID / Token Secret 对，而 Modal 的原生方案将它们作为两个标头发送——Modal-Key 和 Modal-Secret。只有一个“粘贴你的 API 密钥”字段的 shell 只能发出 Authorization: Bearer ——粘贴 Token ID、Token Secret，或 Modal-Key: … curl 片段，每个请求都会返回 401。Modal 记录了一个逃生通道（将这对值用
period: Bearer wk-….ws-…），但粘贴一个密钥的 GUI 里没有任何东西会告诉你
这一点。

DeepShell 按上游 schema 写入 provider 配置，该 schema 支持每条路由任意
headers: —— 完全按照 Modal 签发的方式发送 Modal-Key + Modal-Secret，或者把
拼接后的密钥对放在环境变量里，用 apiKeyEnv 引用。无论哪种方式，你的 Modal
端点都能在第一次尝试时通过认证。

安全说明

- 该 harness 仅绑定 127.0.0.1（上游硬性拒绝 0.0.0.0）。
手机访问通过 Tailscale Funnel 转发。每次启动的配对令牌
授予一个浏览器会话；请把配对 URL 当作密码对待。
- 无分析、无崩溃报告、无更新 ping。该应用只发起两种
普通类型的网络调用：localhost 以及 harness 所需的内容
（更新时的 npm registry、你的模型 provider）。启用手机访问还会
通过 Tailscale Funnel 连接以中继手机会话。

路线图

- [ ] 应用图标 + 公证的发布构建（Apple Developer 计划）
- [ ] 首次运行引导设置（无需终端即可安装 Node/引擎）
- [ ] Sparkle 自动更新
- [ ] Provider 预设库（RunPod、Modal、vLLM、Ollama……）
- [x] Windows 预览版：零点击安装程序 + 应用模式窗口（见 WINDOWS.md）
- [ ] Windows：代码签名（消除 SmartScreen）、MSIX/Store 安装、自动更新
- [ ] Linux 仅在社区确实需要时才支持

法律

DeepSeek Harness 是 © DeepSeek AI，MIT 许可。DeepShell 是一个独立的
社区项目 —— 与 DeepSeek 无关联、未获其认可或赞助。"DeepShell" 将 dsh
缩写重新推导为一种开放的致敬（DeepSHell），就像第三方客户端一直以来
为自己命名的方式一样。MIT 许可；你想做什么都可以。