ds-harness-remote-fast/README.zh.md

342 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<p align="center">
<img src="docs/logo.svg" alt="DeepSeek Harness Remote" width="600">
</p>
<p align="center">
<a href="README.md">English</a>
&nbsp;·&nbsp;
<strong>中文</strong>
&nbsp;·&nbsp;
<a href="README.ja.md">日本語</a>
</p>
<p align="center">
<a href="docs/README.md"><img src="https://img.shields.io/badge/%E6%96%87%E6%A1%A3-blue?logo=googledocs&amp;logoColor=white" alt="文档"></a>
<a href="https://dsh.r2049.cn/app"><img src="https://img.shields.io/badge/Web-4D6BFE?logo=googlechrome&amp;logoColor=white" alt="Web"></a>
<a href="https://github.com/liguobao/ds-harness-remote/releases/latest"><img src="https://img.shields.io/badge/Android-3DDC84?logo=android&amp;logoColor=white" alt="Android"></a>
<a href="https://github.com/liguobao/ds-harness-remote/issues/20"><img src="https://img.shields.io/badge/iOS-000000?logo=apple&amp;logoColor=white" alt="iOS"></a>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/ds-harness-remote"><img src="https://img.shields.io/npm/v/ds-harness-remote?color=CB3837&amp;logo=npm" alt="npm"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"></a>
<a href="apps/server/README.zh.md"><img src="https://img.shields.io/badge/%E8%87%AA%E9%83%A8%E7%BD%B2-Docker-2496ED?logo=docker&amp;logoColor=white" alt="自部署"></a>
<a href="https://dshfind.com/zh/plugins/liguobao/ds-harness-remote?ref=badge"><img src="https://dshfind.com/api/badge/liguobao/ds-harness-remote?metric=downloads&amp;lang=zh" alt="dshfind 下载量"></a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/177732" target="_blank"><img src="https://trendshift.io/api/badge/repositories/177732" alt="liguobao%2Fds-harness-remote | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>
## 一次连接,随时可用。
从手机、电脑、浏览器继续使用你的 DeepSeek Harness 实例。无论使用哪台设备,都可以回到同一个 Harness 会话。
Harness 始终运行在工作电脑上,原有的工作区、工具和项目配置保持不变。DS Harness Remote 只是通往这个工作环境的另一个窗口。
已支持 DeepSeek Harness 桌面版,使用最新版本安装即可:
`ds-harness-remote@0.6.5`
## 主要特性
- 从另一台设备(Web、PC、移动端)远程到本地Harness实例:DSH 优先,CodeX、Cursor、Antigravity 一样可用。
- 已支持 DeepSeek Harness 桌面版,安装即可使用。原生界面,不另外维护一套桌面会话 UI。
- 支持新建工作区、模型配置、对话模型切换,远端如本地一样丝滑。
- Harness 主机无需开放公网监听端口,无需公网IP,可以从任意可上网的地方,通过双向端到端加密链路安全连接。
- 优先使用P2P网络,全球多TURN节点中转,极端情况下使用多Server Relay兜底,一切畅通无阻。
- 通过 Harness 原生侧栏提供工作区文件、只读预览、远程终端和已授权本机开发服务预览。
- Remote Tool 上下文注入,支持 发现主机与工作区、创建和管理 Harness 会话、读取历史、等待执行、请求中断及传输获准文件。[详情](packages/plugin/README.md#remote-agent-tools)
- 除了支持DeepSeek Harness,同时通过ACP协议支持 Codex、Cursor、Google Antigravity、Pi、OpenCode、Claude Code、Harness Agent等工具的原生工作区,远程文件浏览、终端均可使用。
- Android、iOS、Web、原生DSH 都有对应客户端,全平台可用。
- 多个客户端可以同时连接同一个 Harness Host,RPC 与数据流按连接隔离。
## 支持的客户端
| 客户端 | 形态 | 状态 | 说明 |
| --- | --- | --- | --- |
| DSH 插件 | Remote 侧栏 | 已支持 | 主控、被控任君差遣~ |
| Web | 浏览器页面 | 已支持 | 打开 [https://dsh.r2049.cn](https://dsh.r2049.cn),复用 Harness 原生界面 |
| Android | 原生 App | 已支持 | 从 [Releases](https://github.com/liguobao/ds-harness-remote/releases/latest) 下载 APK,见 [Android 说明](apps/android/README.md) |
| DSH Go | C佬精品 | 已支持 | 详情见:[ccch1mneyyy/dsh-go: 手机上直接跑,也能遥控你电脑上的 DSH。](https://github.com/ccch1mneyyy/dsh-go)
| iOS | TestFlight 内测 | 内测 | 未公开上架,入口见 [issue #20](https://github.com/liguobao/ds-harness-remote/issues/20) |
| dsh-TUI | 独立 Host 组合包 + CLI | 核心真机验收通过 | 安装同版本 `ds-harness-remote-tui`,见[验证版本与边界](docs/compatibility.md);安装脚本不会为它自动创建 Web 服务 |
| Linux | 云服务器 | 已支持 | [官网](https://dsh.r2049.cn/)登录后一键安装。
多个客户端可以同时连接同一个 Host,RPC 与数据流按连接隔离。
## 安装
### 支持 DeepSeek Harness 桌面版
在 DeepSeek Harness Desktop 的 **扩展 / 插件管理** 中,选择从 **npm** 安装,输入包名和版本:
`ds-harness-remote@0.6.5`
安装后重启 Desktop。也可使用它的官方 `dsh` 启动器安装固定版本:
`dsh plugin --profile desktop add -w ds-harness-remote@0.6.5`。
DSH 0.2.2 起,npm 安装支持在插件页检查版本和一键更新;热更新失败时由 DSH 尝试恢复旧版。GitHub / 本地 link 安装需先切换到 npm,见[在线更新说明](docs/installation.zh.md#dsh-插件页在线更新)。
### Linux 一键安装
见官网首页[https://dsh.r2049.cn](https://dsh.r2049.cn/),登陆后获取一键安装授权码安装即可。
### 原生Android 客户端
支持同时使用多工作区连接对话,同时创造性加入了 「Bot 模式」( Power by [Fei2411/DS-Bot](https://github.com/Fei2411/DS-Bot))
从 [GitHub Releases](https://github.com/liguobao/ds-harness-remote/releases/latest) 下载最新 APK,登录同一账号即可看到主机。
## DSH Go - DeepSeek Harness 装进口袋:手机本机运行,也能遥控你的电脑。
[ccch1mneyyy/dsh-go](https://github.com/ccch1mneyyy/dsh-go):已内置 ds-harness-remote 协议,既可以在手机本机运行 DeepSeek Harness,也可以远程连接电脑。
在手机端DSH Go安装 ds-harness-remote 插件后,电脑端、Web端一样可以远程到手机上的DSH,丝滑使用Mobile Use.
### iOS 客户端
- [内测招募](https://github.com/liguobao/ds-harness-remote/issues/20)
## 快速开始
1. 从 DeepSeek Harness 侧边栏打开 **Remote** 入口。
2. 按需选择登录方式:「知乎」、「Github」、[Google ] 授权登录均已支持,账号密码登录(使用邀请码注册,可邮件本仓库作者申请)
3. 在另一台设备上使用 DeepSeek Harness安装同样插件,根据1、2完成同样方式的登录。也可以按需使用Remote Web、iOS、Android、DSH Go等客户端,即开即用,无需安装任何插件。
4. 选择在线 Host,再选择已有 Workspace 或浏览远端目录后打开。
默认使用本项目提供的 [https://dsh.r2049.cn](https://dsh.r2049.cn) 托管 Remote Server。
自建托管Server可使用仓库内的[最小 Server](apps/server/README.zh.md),当前版本已包含 WebRTC LAN/P2P/TURN 连接协调(TURN 需自行部署 coturn)与加密 Relay Server 等功能,暂不支持托管Remote Web的完整功能。
## 界面截图
### 桌面端
在另一台电脑上选择在线 Host,然后打开它的 Workspace。Workspace 会在 Harness 原生界面中打开,顶部显示当前 Host 和加密连接状态。
<p align="center">
<img src="docs/images/host-list.png" alt="列出在线 Host 的远端工作区选择界面" width="40%">
<img src="docs/images/remote.png" alt="通过端到端加密远程连接运行的 Harness 会话" width="40%">
</p>
注意:如果想关闭当前电脑远控其他主机功能,可在[https://dsh.r2049.cn/](https://dsh.r2049.cn/) 「主机列表」中,打开「仅被控」开关,开启「仅被控」后当前设备无法看到账号下其他设备,Web端、其他客户端依旧可以远程当前设备。
### Android
支持文字/图片 Prompt、模型切换,以及可用工作区的文件和终端。
<p align="center">
<img src="docs/images/mobile-list.jpg" alt="Android 客户端中的在线和离线设备列表" width="30%">
<img src="docs/images/image-msg.jpg" alt="从 Android 客户端发送图片 Prompt" width="30%">
<img src="docs/images/image-result.jpg" alt="在 Android 客户端中查看图片理解结果" width="30%">
</p>
移动端设置提供默认关闭的全局「会话精简模式」,下次打开会话生效。
支持该能力的 Host 缩减历史工具详情,保留正文和工具状态,关闭此设置后重新打开会话可加载完整历史。
## 工作方式
```text
DSH Desktop / Remote Web / Android
↔ 已认证的端到端加密通道
Host 上的 Remote 插件
↔ 支持的 Harness 能力或可选 Codex 工作区支持
Harness 会话/Workspace 或 Codex 项目
```
Harness 主机无需开放公网监听端口。只要能够访问互联网,就可以从任意地方连接,ds-harness-remote 通过双向端到端加密链路通信。
它将客户端切换到所选 Host 的 Harness 原生 API,因此原有 Workspace、工具和权限流程都保留在该电脑上。
你也可以远程修改主机上的 Harness 和插件设置;可编辑的选项取决于 Harness 和各插件通过官方设置接口开放的配置项。
## 实验性 ACP 工作区
Host 启动本机支持ACP 的Agent,通过ds-harness-remote 通道传递 Prompt、流式回复和审批。所有Agent都使用自身工作区和会话,只做DSH 会话翻译转换,不写入 Harness 存储。
当前已支持:
- **Codex**:通过 App Server 接入,使用统一工作区入口。
- **Cursor**:通过 CLI 的 ACP 接口接入。
- **Antigravity(AGY)**:通过 CLI 的 stream-json 接口适配接入。
- **Pi Agent(实验性)**:安装并配置 Pi 与 `pi-acp` 后自动检测,可在设置中关闭;工具按主机用户权限执行,默认无逐工具确认。
- **OpenCode**:通过 `opencode acp` 接入,支持工作区与历史;会话归档需版本提供认证 API,暂不支持恢复归档。
- **Claude**:通过本机已授权的 `claude-agent-acp` 接入,需在设置中开启;支持文字与审批,暂不支持图片。
- **Hermes**:通过 `hermes acp` 接入,需在设置中开启;支持文字、图片、流式输出、审批与模型选择。
Claude 和 Hermes 均支持直接 Files/Terminal 访问,复用 Host 的工作区路径隔离与终端权限设置。
配置与后端适配开发见 [Agent 工作区接入指南](docs/acp-remote.md)。
Desktop/Android 的 Cursor、Claude、Hermes、Pi、OpenCode、AGY 模型选择使用 Host 实际模型目录,由Agent ACP决定
思考强度选项以上游实际提供为准。Cursor 每个会话使用独立进程,切换模型不会影响其他会话。
## 端到端加密
Harness 业务流量在 Client 加密,只能由选定的 Host 解密,固定使用 `Noise_IK_25519_ChaChaPoly_SHA256`。
连接必须同时通过同账号 membership 与本地固定的设备 identity key 校验。
服务端可以协调连接并看到必要的网络元数据,但不能读取会话消息、Prompt、工具输出、Workspace 路径或 远端文件内容。
握手、密钥生命周期、可见元数据、重放保护和安全边界详见[端到端加密](docs/end-to-end-encryption.md)。
## 网络与传输
Host 只建立出站连接,不监听公网端口,也不要求路由器端口转发。
Remote 按 `LAN -> P2P -> TURN -> Relay` 协商路径;
WebRTC 不可用或连接失败时,会降级到加密的 WebSocket Relay。
所有路径都承载同一份 Noise 密文,并保持相同的 Host/Client 身份边界。
网络拓扑、控制面与数据面、NAT、降级、重连语义和当前验证状态详见[网络与传输](docs/network.md)。
## 安全边界
- LAN 、P2P网络下,除了网络协调相关指令,所有的数据不经过服务器;TURN服务使用开源coturn服务器部署,Relay 模式使用WebSocket转发。
- 所有的会话流量经过端到端加密;服务端只中继密文,不保存会话明文或设备私钥。
- 同账号设备连接无需额外确认,详见[设备信任与权限边界](docs/end-to-end-encryption.md#2-设备身份与信任)。
- [Remote Tools 注入说明](docs/remote-tools.md):可选的 `remote_*` 会话工具,默认开启,可在详细 Remote 设置中开启。
- 交互终端使用 Host 本地的 `terminal.enabled`(默认开启),以 Host 用户身份运行,独立于 Agent 审批;
- 不开放通用工具 RPC 或远程桌面。
- Workspace 选择器只列出文件夹,并且只返回受限的只读目录元数据。
- 远端文件预览不能写入、删除、上传、执行文件,也不能调用远端系统的“外部打开”。
- Codex Remote / Agent ACP是可选功能,可以关闭,并遵循与 Remote 其他能力相同的加密 Host 权限边界。
- 移除设备后,其凭证、membership 和已建立的 Remote 连接均会失效。
## 常见问题
**需要公网 IP 或端口转发吗?**
不需要。Host 只建立出站连接,不监听公网端口。
**服务端能看到我的会话内容吗?**
不能。服务端只中继密文;它能读到的是完成授权、在线状态、选路与限流所需的控制元数据,例如设备归属、在线状态、连接时间与 `connectionId`,读不到 Prompt、对话内容、工具输入输出、Workspace 路径与文件预览内容。
**哪台机器可以当 Host?**
装了 Remote 插件并已登录的 Harness 实例,无论是Windows还是MacOS、Linux,甚至于DSH-Go 都可以作为Harness Remote Host实例。
**可以几台设备同时连同一个 Host?**
暂无限制,当前可以同时使用多设备并发连接,RPC 与数据流按连接隔离。
**支持哪些 Harness 版本?**
当前基线为 `dsh-v0.2.2-rc.1`;`dsh-v0.2.1-rc.5` 与 `0.2.0` rc.2 / rc.1 在同一官方 carrier 上继续兼容,详见[兼容性说明](docs/compatibility.zh.md)。
Host 插件、随包 Remote 客户端和 Android 已移除 Harness `0.1.1-rc.2` ApiProxy 兼容。请使用提供官方 Typert Remote carrier 的 Host;
仅提供 ApiProxy 或不支持能力发现的旧 Host 会被拒绝,不再降级。
CodeX/ACP 保留独立数据面,Desktop 内存投影统一使用 Typert。
**Linux 安装为什么要求 root?**
安装脚本要配置 systemd 系统服务;Host、Agent 工具与远程终端因此具备 root 权限,只应对可信账号开放。
**iOS 可以直接装吗?**
目前是 TestFlight 内测,未公开上架,入口见 [issue #20](https://github.com/liguobao/ds-harness-remote/issues/20)。
**和 frp、内网穿透或远程桌面有什么不同?**
通用端口映射使用Server TCP转发流量,流量需要从Server经过一道,受限于Server端的带宽瓶颈。
本项目使用4层网络模式依次探测,在复杂网络环境下依旧能保持良好的P2P直连。
远程桌面为了满足用户使用需求,需要把整个电脑屏幕获取下来,然后再用户侧重放,整体对上下行带宽和电脑性能都有要求。
本项目只把 Harness 原生会话界面需要的消息加密后传输到远端,不开放通用工具 RPC 与桌面控制,权限与审批仍留在 Host 侧。
Tailscale 、 CF Turn 、UU远程都是非常优秀的解决方案,大家按需使用即可。
## 推荐搭配插件
### Intelligent UI
[Intelligent UI](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui) 让模型用卡片、表格、图表和表单作答。
Android 客户端可原生渲染这些内容,并在 **插件 → Remote 适配** 中列出该插件,可直接开关和修改实时设置。
### [Fei2411/DS-Bot](https://github.com/Fei2411/DS-Bot)
DS Bot 是一个基于 DeepSeek Harness(简称 dsh)的 bot 插件,插件将 dsh 改造为 bot 形式。你可以与自己创建的 bot 交流、工作。
## 文档
- [插件说明](packages/plugin/README.md)
- [安装指南](docs/installation.zh.md)
- [Codex Remote 技术说明](docs/codex-remote.md)
- [ACP Remote / Agent adapter 技术说明](docs/acp-remote.md)
- [文档索引](docs/README.md)
- [端到端加密](docs/end-to-end-encryption.md)
- [网络与传输](docs/network.md)
- [远程协议](docs/protocol.md)
- [开发进度与路线图](docs/TODO.md)
- [更新记录](docs/CHANGELOG.md)
- [隐私说明](docs/PRIVACY.md)
- [Android 说明](apps/android/README.md)
- 当前开发适配基线为 `dsh-v0.2.2-rc.1`,验证范围见[兼容性说明](docs/compatibility.zh.md)。
## 友情链接
- 友情链接:[DSH Go](https://github.com/ccch1mneyyy/dsh-go) — 把 DeepSeek Harness 装进口袋:手机本机运行,也能遥控你的电脑。「已适配 Remote。」
- 友情链接:[dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI)(终端优先的 Harness 客户端,Remote Host 使用独立 `ds-harness-remote-tui` 组合包)
- 友情链接:[LINUX DO 社区](https://linux.do/)
- 友情链接:[赛博刘看山](https://kanshan.r2049.cn/)
## Star History
<a href="https://www.star-history.com/?repos=liguobao%2Fds-harness-remote&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=liguobao/ds-harness-remote&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=liguobao/ds-harness-remote&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=liguobao/ds-harness-remote&type=date&legend=top-left" />
</picture>
</a>
## 贡献者
`ds-harness-remote` 由开源社区共同驱动与维护。我们坚信,优秀的基础工具不仅由代码铸就,更由每一位使用它、测试它、修正文档或分享想法的人共同塑造。
无论你的技术背景如何,任何形式的参与都同样珍贵:
- **提交 Issue**:发现异常、有新功能设想,或对使用体验有更好的建议?欢迎随时发起讨论。
- **文档与多语言**:完善使用指南、修正表述细节,或协助保持中文、英文与日文文档同步。
- **测试与多端体验**:在你的实际环境中(Desktop / Web / Android)体验运行,反馈真实场景下的表现。
- **代码与代码审查**:认领待办事项、修复缺陷、实现新特性,或是协助 Review 社区的 Pull Request。
<p align="center">
<a href="https://github.com/liguobao/ds-harness-remote/graphs/contributors">
<img src="https://contrib.rocks/image?repo=liguobao/ds-harness-remote&max=30" alt="贡献者头像墙" />
</a>
</p>
<p align="center">
<em>衷心感谢每一位让这个项目变得更好的贡献者!</em>
</p>
## 连接问题排查
Android:复现问题后打开 **设置 → 诊断 → 导出连接日志**,选择文件夹保存 `.txt`。日志保留本次 App 进程启动以来最近 500 条连接诊断;重启 App 后清空,不包含凭据和会话内容。
Host:在 **插件 → Remote 设置** 开启 **Debug 日志**,立即生效并持久保存;排查完成后关闭(恢复 `info` 级别)。日志带 `[ds-harness-remote]` 前缀,Desktop 可在 `desktop.log` 查找。手动配置可设置 `logLevel: debug`。
## 项目声明与商标
本项目是独立的社区项目,不是 DeepSeek 官方产品。DeepSeek 及相关名称和商标归其各自权利人所有。
## License
[MIT](packages/plugin/LICENSE)