34 KiB
DeepSeek Harness Remote — Full Vibecoding Development Prompt
历史归档:本文保留原始需求背景,不作为当前实现任务。权威边界见根 README、AGENTS和当前设计。本仓库提供 Plugin、Client、共享协议和
apps/server最小自部署版本;完整 Server、Remote Web 与 Admin 仍由独立仓库实现。
你是一名资深全栈 / Electron / React Native / WebRTC / FastAPI / TypeScript 工程师。
请帮助我从零设计并实现一个开源项目:
deepseek-harness-remote
它为 DeepSeek Harness 提供类似 Codex Remote / Claude Code Remote 的远程访问能力,但第一阶段不要追求完整复刻任何商业产品。
核心目标:
在一台运行 DeepSeek Harness 的电脑上安装 Remote 插件后,我可以通过 Android、Web、macOS、Windows、Linux 客户端安全连接到这台电脑,查看 Harness 状态、会话、Agent 输出、权限请求,并继续发送指令。
项目应该优先:
- 架构清晰;
- 可自部署;
- 尽量 P2P;
- Server 尽量只做协调;
- 不修改 DeepSeek Harness 核心源码;
- MVP 能真正跑起来;
- 安全边界明确;
- 后续容易扩展成完整 Remote Agent 产品。
一、必须先阅读和理解的项目
开发前先阅读:
DeepSeek Harness:
https://github.com/deepseek-ai/deepseek-harness
DeepSeek Harness Quickstart:
https://deepseek-harness.github.io/deepseek-harness/guide/quickstart
重点阅读:
- Cordis plugin architecture
injectapply(ctx)ctx.effect()ctx.on()- Harness sessions
- agents
- tools
- permissions
- workspace
- Web UI
- Cordis patch / plugin loader
dsh web --patch
Cordis Primer:
docs/cordis-primer.md
并参考我已有的桌面端项目:
https://github.com/liguobao/dsh-desktop
尤其理解:
- Electron 如何启动本地
@deepseek-ai/dsh - 如何加载独立 Harness plugin
$DSH_HOME/profiles/node_modules--patch- Electron main / preload / renderer 安全隔离
- Harness Web UI 与 Electron 的关系
- Windows / macOS / Linux 打包方式
禁止为了方便直接修改 DeepSeek Harness 源码。
Remote 必须尽可能以独立 Plugin 实现。
二、产品定义
项目名称:
deepseek-harness-remote
简称:
DSH Remote
整体由四部分构成:
DeepSeek Harness Host
│
│ Cordis Plugin
▼
@dsh-remote/plugin
│
├──────── WebRTC DataChannel ────────┐
│ │
│ ▼
│ Remote Client
│
│
└── Signaling / Relay ──► DSH Remote Server
完整结构:
deepseek-harness-remote/
apps/
server/
server-web/
desktop/
android/
web/
packages/
plugin/
protocol/
crypto/
webrtc/
client-core/
ui/
config/
docs/
deploy/
examples/
推荐使用 monorepo。
JS/TS 包管理优先:
pnpm workspace
Python Server 独立维护:
apps/server
三、MVP 产品范围
第一版不要实现完整 Codex Remote。
第一版必须跑通:
Host 端
电脑运行:
dsh
安装:
npm install @dsh-remote/plugin
或者通过 Harness profile/plugin 机制加载。
Plugin 启动后:
Remote service started
Device Code:
DSH-82KF-7QMP
Server:
https://remote.example.com
Waiting for remote client...
可以生成二维码:
dshremote://pair?server=...&code=...
Host 必须显示:
- Device ID
- Device name
- OS
- Harness version
- Plugin version
- 在线状态
- Server
- P2P 状态
- 已绑定设备
- 最近远程连接
四、Remote Client 第一版功能
客户端打开以后:
My Devices
MacBook Pro
Online
P2P
Windows PC
Offline
Linux Server
Online
Relay
进入设备:
MacBook Pro
Workspace
~/Projects/foo
Harness
Running
Session
Fix OAuth issue
需要支持:
1. 查看状态
显示:
- host online/offline
- OS
- hostname
- Harness version
- plugin version
- current workspace
- active session
- connection mode
连接模式显示为:
LAN
P2P
TURN
Relay
五、会话功能
远程端至少能够:
List Sessions
Get Session
Create Session
Resume Session
Send Message
Stop Generation
Subscribe Session Events
UI 类似聊天客户端。
例如:
User:
帮我看看 src/auth.ts
Assistant:
我先检查相关文件……
Tool:
read src/auth.ts
Assistant:
这里存在……
Permission Request:
Execute:
npm test
[Allow once]
[Allow]
[Deny]
必须支持 Streaming。
不要轮询获取输出。
使用事件协议。
六、权限请求是第一等公民
Remote 不能变成一个“无条件远程 shell”。
必须把 Harness 原有 Permission 系统映射到 Remote Protocol。
例如:
{
"type": "permission.request",
"requestId": "xxx",
"sessionId": "xxx",
"permission": {
"kind": "command",
"command": "npm test",
"cwd": "/home/user/project"
}
}
客户端:
Remote permission request
Command:
npm test
Directory:
~/project
[Allow Once]
[Allow Session]
[Deny]
Remote Client 不应该拥有比本机 Harness 更高的权限。
原则:
Remote 只是 Harness UI / control surface 的另一种入口,而不是绕过 Harness 权限模型。
七、Plugin 架构
实现:
packages/plugin
包名:
@dsh-remote/plugin
插件遵循 DeepSeek Harness / Cordis 生命周期。
示意:
export const inject = [
"sessions",
"agents",
...
]
export function apply(ctx, config) {
// initialize remote service
ctx.effect(() => {
// startup
return () => {
// shutdown
}
})
}
但不要猜测 Harness API。
在写实现前:
必须首先阅读当前 DeepSeek Harness 源码确认真实 API。
不要虚构:
ctx.sessions.xxx
ctx.agent.xxx
ctx.permissions.xxx
如果 API 和预想不同:
以实际 API 为准。
建立 adapter:
packages/plugin/src/adapters/
session-adapter.ts
permission-adapter.ts
workspace-adapter.ts
agent-adapter.ts
避免 Remote Protocol 与 Harness 内部 API 强耦合。
形成:
Harness API
│
▼
Harness Adapter
│
▼
Remote Protocol
未来 Harness API 变更时,只修改 adapter。
八、Plugin 不启动公开 HTTP Server
默认禁止:
0.0.0.0:xxxx
不要简单地:
在 Host 开一个 WebSocket server
然后暴露公网端口
Host Plugin 应主动向协调 Server 发起出站连接。
例如:
Host
└── WSS outbound
│
▼
Remote Server
这样:
- 不要求公网 IP
- 不要求用户配置端口映射
- NAT 后可以使用
- 公司网络更容易工作
九、Connection 架构
连接优先级:
1 LAN direct
2 WebRTC P2P
3 WebRTC TURN
4 WebSocket encrypted relay
抽象统一接口:
interface RemoteTransport {
connect(): Promise<void>
send(data: Uint8Array): Promise<void>
onMessage(cb): void
close(): Promise<void>
getStats(): TransportStats
}
实现:
LanTransport
WebRTCTransport
RelayTransport
业务协议绝对不能直接依赖 WebRTC API。
十、WebRTC
优先使用:
RTCPeerConnection
RTCDataChannel
用途是数据传输,不需要音视频。
创建:
dsh-control
dsh-events
也可以 MVP 只使用一个:
dsh
DataChannel:
ordered: true
WebRTC signaling 通过 Server 完成。
例如:
Host
|
| websocket
|
Server
|
| websocket
|
Client
Server 传递:
offer
answer
ice candidate
Server 不参与正常 P2P 数据。
十一、STUN / TURN
支持配置:
iceServers:
- urls:
- stun:stun.example.com:3478
- urls:
- turn:turn.example.com:3478
username: xxx
credential: xxx
不要在客户端永久硬编码 TURN 密码。
Server 提供短期 TURN credential。
推荐为 coturn 预留支持。
部署结构:
FastAPI
PostgreSQL/SQLite
coturn
nginx/caddy
但 MVP DB 使用 SQLite。
十二、Relay Fallback
如果 WebRTC 失败:
Host <-- WSS --> Server <-- WSS --> Client
Server 只负责转发 envelope。
例如:
{
"deviceId": "...",
"connectionId": "...",
"payload": "..."
}
Relay payload 应使用端到端加密。
Server 不应该能够读取 Harness conversation 内容。
十三、端到端加密
不要仅依赖 HTTPS/WSS。
定义 app-level secure channel。
推荐研究并选一种成熟方案:
Noise Protocol
或者:
X25519
HKDF-SHA256
ChaCha20-Poly1305
优先使用成熟 library。
禁止自己发明密码算法。
每个设备生成:
device public key
device private key
private key:
Android:
Android Keystore
macOS:
Keychain
Windows:
DPAPI / Credential Manager
Linux:
Secret Service
Web:
IndexedDB
Web 安全能力较弱,要在 UI 明确说明。
十四、设备身份
每个 Host 创建:
device_id
device_name
device_keypair
例如:
{
"deviceId": "01K...",
"name": "Li's MacBook",
"platform": "darwin",
"publicKey": "..."
}
Device ID 使用:
UUIDv7
或者:
ULID
不要:
hostname 作为 ID
MAC address 作为 ID
硬盘序列号作为 ID
十五、设备配对
支持两种方式。
A. Device Code
Host:
Device code:
82KF-7QMP
Expires in 10 minutes
Remote Client:
Enter device code
建议 code:
8 位 Base32
要求:
- 至少约 40 bit entropy
- 10 分钟过期
- 单次使用
- Server rate limit
- IP rate limit
- device rate limit
- 错误次数限制
不要使用简单:
123456
作为永久认证方式。
十六、QR Code
Host:
┌──────────────────┐
│ │
│ QR CODE │
│ │
└──────────────────┘
内容:
dshremote://pair?v=1
&server=https://remote.xxx
&code=82KF7QMP
Android 扫码即可配对。
十七、Login 模式
第一版 Login 可以简化。
支持:
Anonymous Device Pairing
后续加入:
Account Login
架构提前预留:
users
devices
device_members
sessions
Server DB:
users
devices
device_pairings
device_memberships
connections
refresh_tokens
匿名 pairing 可以创建:
guest identity
但未来能够迁移到账户。
十八、Server
目录:
apps/server
技术栈固定:
Python 3.12+
FastAPI
SQLAlchemy 2
Alembic
Pydantic v2
SQLite
uvicorn
不要第一版使用:
Redis
Kafka
RabbitMQ
Celery
Kubernetes
Postgres
保持简单。
十九、Server API
基本 API:
GET /health
POST /api/v1/pairings
POST /api/v1/pairings/claim
POST /api/v1/pairings/confirm
GET /api/v1/devices
GET /api/v1/devices/{id}
DELETE /api/v1/devices/{id}
POST /api/v1/auth/refresh
GET /api/v1/turn/credentials
WebSocket:
/ws/v1/host
/ws/v1/client
或者统一:
/ws/v1/connect
连接建立后 authentication frame:
{
"type": "hello",
"role": "host",
"deviceId": "...",
"token": "..."
}
二十、Signaling Protocol
例如:
{
"type": "signal.offer",
"connectionId": "...",
"targetDeviceId": "...",
"sdp": "..."
}
{
"type": "signal.answer",
"connectionId": "...",
"sdp": "..."
}
{
"type": "signal.ice",
"connectionId": "...",
"candidate": {}
}
Server 只转发。
二十一、Remote Protocol
建立:
packages/protocol
这是项目最重要的 shared package。
所有端:
Host Plugin
Desktop
Android
Web
都使用同一 Protocol。
Protocol version:
DSH Remote Protocol v1
所有 message:
{
"v": 1,
"id": "01K...",
"type": "...",
"timestamp": 1786...,
"payload": {}
}
二十二、RPC
采用简单 request / response。
Request:
{
"v": 1,
"id": "abc",
"type": "rpc.request",
"payload": {
"method": "sessions.list",
"params": {}
}
}
Response:
{
"v": 1,
"id": "def",
"type": "rpc.response",
"payload": {
"requestId": "abc",
"result": []
}
}
Error:
{
"type": "rpc.error",
"payload": {
"requestId": "abc",
"code": "PERMISSION_DENIED",
"message": "..."
}
}
二十三、核心 RPC
MVP:
system.info
workspace.get
sessions.list
sessions.get
sessions.create
session.send
session.stop
permissions.respond
connection.ping
尽量不要提供:
shell.exec
filesystem.read
filesystem.write
这种绕过 Harness 的 Remote RPC。
文件操作应该通过 Harness Agent 完成。
二十四、Event
Host 主动发送:
session.created
session.updated
message.created
message.delta
tool.started
tool.updated
tool.finished
permission.requested
permission.resolved
agent.status
connection.stats
例如:
{
"type": "event",
"payload": {
"event": "message.delta",
"data": {
"sessionId": "...",
"messageId": "...",
"delta": "正在检查..."
}
}
}
二十五、断线恢复
Remote 必须考虑:
手机切 WiFi
进入后台
WebRTC 断开
电脑休眠
网络切换
客户端需要:
CONNECTING
CONNECTED_P2P
CONNECTED_RELAY
RECONNECTING
OFFLINE
断线后:
- reconnect signaling
- recreate WebRTC
- fallback relay
- session resync
增加:
events.sequence
例如:
{
"seq": 8271
}
客户端保存:
lastSeq
Reconnect:
sync.from(lastSeq)
如果历史 event 已清理:
FULL_RESYNC_REQUIRED
然后请求:
sessions.get
二十六、Keepalive
Host 与 Server:
ping 20-30 秒
不要过于频繁。
Host DB heartbeat:
last_seen
Client 展示:
Online
Last seen 32 sec ago
二十七、Android
Android 第一版使用:
React Native
优先考虑:
Expo
但如果 WebRTC / Keystore / native integration 对 Expo 限制明显:
切换:
React Native CLI
不要为了 Expo 强行牺牲 WebRTC。
包:
react-native-webrtc
状态:
Zustand
网络:
fetch
WebSocket
Secure Storage:
Keystore backed storage
Android MVP 页面:
Server Setup
Pair Device
Devices
Device Detail
Sessions
Chat
Permission Dialog
Settings
二十八、Desktop
不要重复造轮子。
优先复用 / 合并:
dsh-desktop
技术:
Electron
React
TypeScript
最终可能演进:
DSH Desktop
Local
Remote
侧边栏:
Local
Remote Devices
Mac mini
Linux Server
但第一阶段允许:
apps/desktop
单独实现 Remote UI。
应尽量共享:
packages/client-core
packages/ui
packages/protocol
二十九、Web Client
路径:
apps/web
技术:
React
Vite
TypeScript
Web 是“有限支持”。
支持:
- device list
- connection
- sessions
- chat
- permission approve
- WebRTC
限制:
- 浏览器 storage security
- 页面关闭即断开
- background limitations
- notification limitations
- mobile browser lifecycle
不要尝试做 Web terminal。
三十、Server Web
用户明确要求:
Python + FastAPI + React + SQLite
所以 Server 管理界面:
apps/server-web
使用:
React
Vite
TypeScript
Server 可以生产部署时托管:
server-web/dist
FastAPI:
/static
/
页面:
Login
Devices
Pair Device
Connections
Server Settings
三十一、自部署
必须做到:
docker compose up -d
包含:
remote-server
coturn
SQLite:
/data/remote.db
例如:
services:
server:
image: ghcr.io/.../dsh-remote-server
turn:
image: coturn/coturn
支持:
REMOTE_PUBLIC_URL
REMOTE_SECRET_KEY
DATABASE_URL
TURN_URL
TURN_SECRET
三十二、默认 Server
Client 支持默认 Server:
例如:
https://remote.example.com
不要把具体我的生产域名写死在源代码逻辑中。
定义:
DEFAULT_REMOTE_SERVER
build-time / runtime 可覆盖。
例如:
DSH_REMOTE_SERVER
用户可以改为:
https://remote.my-company.com
三十三、Server 不是 Remote Computer 的代理 API
Server 不应该保存:
workspace files
source code
conversation plaintext
shell history
tool output
正常 P2P 模式:
Server 只知道:
device presence
device public key
pairing
connection metadata
signaling
Relay 模式:
Server 只看到 encrypted payload。
三十四、安全设计
必须写:
docs/SECURITY_ARCHITECTURE.md
Threat Model 至少讨论:
攻击者拿到 Device Code
措施:
TTL
single-use
rate-limit
pair confirmation
Server 被入侵
不能直接控制 Host。
原因:
device private key stays local
E2EE
恶意 Client
只能拥有用户明确授权的设备权限。
Replay attack
message:
nonce
counter
timestamp
AEAD。
Stolen refresh token
支持:
device revoke
token rotation
MITM
设备 key fingerprint 验证。
三十五、Pair Confirmation
推荐增加安全确认。
Client 输入 code:
82KF-7QMP
Host 显示:
Android Pixel 10
wants to connect.
Fingerprint:
F4A2 992C 13AB
[Allow]
[Deny]
确认后双方保存:
trusted peer public key
这样 Server 即使知道 Device Code 也不能偷偷绑定设备。
三十六、Capabilities
连接 handshake:
Host:
{
"protocol": 1,
"capabilities": [
"sessions.list",
"sessions.send",
"session.streaming",
"permission.respond"
]
}
Client 根据 capabilities 隐藏不支持的按钮。
不要假设不同 Harness 版本拥有完全相同能力。
三十七、Version Compatibility
Handshake:
{
"remoteProtocol": 1,
"pluginVersion": "0.1.0",
"harnessVersion": "...",
"platform": "darwin"
}
如果不兼容:
REMOTE_PROTOCOL_UNSUPPORTED
UI:
This device requires DSH Remote 2.x
三十八、日志
Host:
$DSH_HOME/logs/remote.log
日志禁止记录:
auth token
private key
full prompt
source file content
TURN password
只记录:
connection id
transport
duration
error code
state transition
三十九、Metrics
MVP 本地统计即可:
connection attempts
p2p success rate
relay fallback rate
connection establishment time
disconnects
Admin Web:
P2P 78%
TURN 15%
Relay 7%
不做复杂监控平台。
四十、测试
必须有:
protocol unit tests
测试:
encoding
decoding
version validation
RPC correlation
event sequence
crypto tests
key exchange
encrypt/decrypt
tampered message rejection
replay rejection
server tests
pytest:
pairing
auth
device list
WebSocket auth
signaling
relay authorization
plugin tests
Mock Harness context。
client-core
测试:
reconnect
transport fallback
RPC timeout
event ordering
四十一、WebRTC 测试
至少测试:
same LAN
different NAT
TURN forced
WebRTC disabled -> Relay
network interruption
client reconnect
提供:
FORCE_RELAY=true
调试选项。
也提供:
FORCE_TURN=true
四十二、开发模式
应该能做到:
Terminal 1:
pnpm dev:server
Terminal 2:
pnpm dev:web
Terminal 3:
pnpm dev:plugin
或者:
pnpm dev
启动需要的开发服务。
四十三、Demo Mode
为了开发前端,不应该必须启动 DeepSeek Harness。
提供:
MockHost
能够模拟:
sessions
streaming message
tool call
permission request
运行:
pnpm dev:mock-host
这样 Android/Web/Desktop 都能独立开发 UI。
四十四、UI 风格
UI 简洁,接近:
ChatGPT
Codex
Linear
GitHub Mobile
而不是传统后台管理系统。
颜色不要过多。
Mobile 优先。
主要页面:
Devices
Device
Sessions
Chat
Chat 最重要。
连接状态使用小标签:
P2P
Relay
Offline
四十五、Chat 页面
示例:
< MacBook Pro
Fix OAuth redirect issue
────────────────────
You
检查 OAuth 登录为什么失败。
DSH
我先查看认证相关代码。
▶ Read
src/auth/oauth.ts
DSH
这里 redirect_uri 与后台配置不同。
⚠ Permission
Run:
npm test
[Allow Once]
[Deny]
────────────────────
[ Ask DSH... ] ↑
支持:
Markdown
code block
tool call
permission request
streaming cursor
四十六、不要在第一版做的功能
明确不要:
完整远程桌面
VNC
SSH replacement
PTY terminal
remote filesystem browser
Git GUI
IDE
多人协作
voice
video
screen sharing
cloud workspace
remote git hosting
AI model proxy
billing
organization RBAC
enterprise SSO
除非基本架构已经全部完成。
四十七、MVP Milestones
必须按阶段实现。
Milestone 0 — Research
先不要写大量代码。
输出:
docs/research/
包括:
harness-plugin-api.md
harness-session-api.md
harness-permission-api.md
dsh-desktop-integration.md
webrtc-design.md
必须基于实际源码。
不要猜。
Milestone 1 — Protocol
完成:
packages/protocol
packages/crypto
packages/client-core
包含:
RPC
Events
Handshake
Capabilities
Crypto
Transport interface
单元测试通过。
Milestone 2 — Server
完成:
FastAPI
SQLite
Alembic
pairing
devices
WebSocket
signaling
relay
可以运行:
docker compose up
Milestone 3 — Mock Host
实现:
mock-host
Web client 可以:
pair
connect
view sessions
send message
receive streaming
Milestone 4 — Harness Plugin
真正接入:
DeepSeek Harness
实现:
sessions
streaming
permission events
send message
stop
必须通过 Plugin,不修改 Harness core。
Milestone 5 — Web Client
Web MVP 完整。
这是最快验证整体系统的客户端。
Milestone 6 — Android
使用相同:
client-core
protocol
crypto
实现 Android App。
Milestone 7 — Desktop
基于:
dsh-desktop
或者共享其 Electron 架构。
实现 Windows:
.exe
portable.exe
macOS:
.dmg
Linux:
.AppImage
Milestone 8 — WebRTC
如果前面为了验证系统先实现 Relay:
现在正式加入:
WebRTC P2P
STUN
TURN
fallback
最终优先:
P2P
Server Relay 作为最后 fallback。
四十八、实现策略
非常重要:
不要在第一天同时写:
FastAPI
Web
Android
Electron
WebRTC
Crypto
Harness Plugin
最终会出现一堆不能工作的半成品。
按照 vertical slice 开发。
第一个真正可运行的 slice:
Mock Host
↕
Server Relay
↕
Web Client
能:
pair
connect
send message
stream result
第二个:
Real Harness Plugin
替换 Mock Host。
第三个:
E2EE
第四个:
WebRTC
第五个:
Android
第六个:
Desktop
四十九、关于 WebRTC 的现实原则
目标是:
尽量直连
而不是:
必须 100% P2P
企业 NAT、CGNAT、防火墙可能导致 P2P 失败。
因此系统必须设计为:
WebRTC ICE
│
├─ direct
│
├─ TURN
│
└─ encrypted relay
任何情况下用户应该首先获得“能连上”的体验。
然后优化连接质量。
五十、代码质量
要求:
TypeScript:
strict: true
禁止大量:
any
Python:
ruff
mypy
pytest
TS:
eslint
vitest
React:
避免巨型 component。
目录:
features/
components/
services/
stores/
五十一、不要过度抽象
MVP 不要出现:
AbstractConnectionFactoryProviderManager
RemoteSessionCoordinatorOrchestrator
优先:
ConnectionManager
RemoteClient
RemoteHost
SessionAdapter
保持可读。
五十二、错误处理
定义统一 error codes:
AUTH_FAILED
PAIRING_EXPIRED
PAIRING_INVALID
DEVICE_OFFLINE
DEVICE_REVOKED
CONNECTION_FAILED
P2P_FAILED
RPC_TIMEOUT
UNSUPPORTED_VERSION
PERMISSION_DENIED
SESSION_NOT_FOUND
HARNESS_UNAVAILABLE
客户端不要展示:
undefined
Network Error
500
而应该转换成用户可理解提示。
五十三、README
根目录 README 必须说明:
What is DSH Remote?
Architecture
Quick Start
Pairing
Self Hosting
Security
Development
Roadmap
README 第一张图画:
Signaling
┌───────────┐
│ Server │
└─────┬─────┘
│
ICE / auth
│
┌──────────┴──────────┐
DeepSeek Harness Android/Web/Desktop
Plugin
│
└──── WebRTC ─────────┘
五十四、Plugin 使用体验
最终用户应该可以类似:
dsh remote enable
如果 Harness Plugin 不允许注册 CLI command:
提供:
npx dsh-remote setup
它帮助写入 Plugin 配置。
不要要求用户手工编辑复杂 YAML。
配置:
remote:
server: https://remote.example.com
deviceName: My Mac
enabled: true
五十五、Host CLI
建议提供:
dsh-remote status
dsh-remote pair
dsh-remote devices
dsh-remote revoke <device>
dsh-remote logout
dsh-remote doctor
例如:
$ dsh-remote status
DSH Remote
Device:
MacBook Pro
ID:
01K...
Server:
https://remote.example.com
Status:
Online
Transport:
Ready
Trusted Clients:
2
五十六、Doctor
dsh-remote doctor
检查:
✓ DeepSeek Harness found
✓ Remote plugin installed
✓ Server reachable
✓ Device identity OK
✓ Signaling connected
✓ STUN reachable
✓ TURN configured
✓ Crypto key available
这对排查 NAT / 防火墙问题很重要。
五十七、Server Admin
Web admin 可以查看:
Devices
Connections
Pairings
Server health
TURN health
不要显示 conversation 内容。
管理员应该只能看到:
Device
Online
Transport
Last Seen
Version
五十八、最终 Repo Layout
目标:
deepseek-harness-remote/
apps/
server/
app/
migrations/
tests/
server-web/
web/
android/
desktop/
mock-host/
packages/
plugin/
protocol/
crypto/
webrtc/
client-core/
ui/
config/
deploy/
docker-compose.yml
coturn/
caddy/
docs/
architecture.md
protocol.md
security.md
self-hosting.md
plugin.md
android.md
desktop.md
web.md
package.json
pnpm-workspace.yaml
README.md
五十九、Protocol 文档
必须写:
docs/protocol.md
内容:
Handshake
Authentication
Pairing
Encryption
RPC
Events
Reconnect
Versioning
Capabilities
协议不能只存在于 TypeScript 类型里。
六十、Architecture Decision Records
重要选择写 ADR:
docs/adr/
0001-monorepo.md
0002-fastapi-server.md
0003-webrtc-datachannel.md
0004-device-identity.md
0005-e2ee.md
0006-transport-fallback.md
0007-harness-plugin-boundary.md
每篇很短即可。
六十一、最终用户体验
最终最重要的体验:
PC:
$ dsh
DSH Remote:
82KF-7QMP
手机:
打开 DSH Remote:
Pair Device
输入:
82KF-7QMP
电脑确认:
Allow Pixel 10?
[Allow]
手机:
MacBook Pro
Online · P2P
打开:
My Project
看到当前 Harness session。
输入:
继续刚才那个 OAuth 问题。
Host 上 DeepSeek Harness 继续执行。
出现:
npm test
手机收到:
Permission Request
[Allow Once]
[Deny]
点击 Allow。
手机继续看到 Streaming Result。
这就是 MVP 成功标准。
六十二、明确的验收标准
项目不能仅仅做到“代码很多”。
以下流程必须真实通过:
Test A
Mac Host
↓
Remote Server
↓
Chrome Web
完成 pairing。
Test B
Chrome 能看到 Host sessions。
Test C
Chrome 发送:
hello
真正进入 DeepSeek Harness session。
Test D
Harness streaming token 实时出现在 Browser。
Test E
Harness 发起 permission request。
Browser 可以 Allow / Deny。
Test F
Chrome 断网再恢复。
Session 恢复。
Test G
强制:
FORCE_RELAY=1
仍然可用。
Test H
启用 WebRTC。
连接显示:
P2P
正常发送消息。
Test I
TURN-only 网络:
显示:
TURN
正常工作。
Test J
Server 无法解密 Relay payload。
六十三、开发执行方式
现在开始开发时:
不要一次性生成整个项目后宣布完成。
按以下顺序工作:
- Inspect DeepSeek Harness source.
- Inspect dsh-desktop source.
- 写 research 文档。
- 提出最终 architecture。
- scaffold monorepo。
- 实现 protocol。
- 写 tests。
- 实现 Server。
- 实现 Mock Host。
- 实现 Web。
- 跑通第一个 vertical slice。
- 接入真实 Harness Plugin。
- 加 encryption。
- 加 WebRTC。
- 加 Android。
- 加 Desktop。
- 完成 Docker self-host。
- 完成文档。
- 跑所有测试。
- 输出验收结果。
每一个阶段完成后都必须实际:
build
lint
test
不要仅凭阅读代码声称通过。
六十四、遇到不确定 API 时的规则
DeepSeek Harness 仍然快速变化。
所以:
任何 Harness API 都不能靠猜。
如果需要:
session
permission
workspace
agent events
plugin loader
web UI
先:
grep
rg
read source
read docs
read tests
然后才实现。
如果 Harness 当前没有直接暴露某个能力:
优先:
- 使用已有 service;
- 使用 existing event;
- 使用 Cordis plugin extension;
- adapter;
- 最后才考虑提交 upstream capability。
不要 fork Harness。
六十五、编码优先级
发生取舍时,按照以下顺序:
Security
>
Correctness
>
Working MVP
>
Simple Architecture
>
Compatibility
>
P2P performance
>
UI polish
>
Feature count
六十六、最终目标
这个项目的定位不是:
“从手机 SSH 到电脑,然后操作 DSH。”
而是:
“DeepSeek Harness 原生的 Remote Control Plane。”
Harness 仍然运行在用户电脑。
代码仍然留在用户电脑。
Agent 仍然在用户电脑上操作 workspace。
Remote Server 负责:
Identity
Pairing
Presence
Signaling
Fallback relay
Remote Client 负责:
Observe
Interact
Approve
Resume
核心架构:
DSH Remote Server
identity / signaling / relay
▲ ▲
│ │
WSS │ │ WSS
│ │
│ │
┌─────────┘ └─────────┐
│ │
▼ ▼
DeepSeek Harness Remote Client
Cordis Remote Plugin Android
Host Web
Desktop
└──────── WebRTC ───────────┘
encrypted
direct
最终做到:
Server 可以消失,但 Host 和 Client 的信任关系仍然属于用户自己的设备。
Server 可以中继连接,但原则上不能读取用户的 Harness 会话内容。
Remote Client 可以操作 Harness,但不能绕过 Harness 自己的权限系统。
先完成最小、可靠、能真正使用的版本,再扩展功能。
现在从:
Milestone 0 — Research
开始。
先检查 DeepSeek Harness 与 dsh-desktop 的真实代码结构,不要立即生成猜测性的 Plugin API。
完成 Research 后输出:
- Harness 可用的插件 API;
- Sessions 的真实接入点;
- Streaming 的真实接入点;
- Permission 的真实接入点;
- dsh-desktop 可以复用的代码;
- 推荐的最终 monorepo tree;
- 第一条 vertical slice 的实现方案;
- 已确认事实与仍待验证假设。
然后直接继续进入 Milestone 1,不要因为非关键设计细节停下来询问我。