# 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,不要因为非关键设计细节停下来询问我。