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