deepseek-local-api 0.8.0

package/.env.example

@@ -0,0 +1,8 @@
+# Your DeepSeek token from chat.deepseek.com
+# To get this:
+# 1. Go to chat.deepseek.com
+# 2. Sign in
+# 3. Open DevTools (F12)
+# 4. Go to Application > Local Storage
+# 5. Find "userToken" and copy its value
+DEEPSEEK_TOKEN="YOUR_TOKEN_HERE"

package/README.md

@@ -0,0 +1,138 @@
+# DeepSeek Local API & CLI Client (`deepseek-local-api`)
+
+Convert DeepSeek Web Chat into a zero-overhead, OpenAI-compatible local API server and interactive terminal CLI.
+
+---
+
+> [!IMPORTANT]
+> ### ⚠️ Capabilities & Limitations Notice
+> - **Text & Reasoning Generation Only**: This tool is designed strictly for high-quality **text generation and reasoning** (DeepSeek Chat & DeepSeek Reasoner R1).
+> - **No Native Tool/Function Calling**: The DeepSeek Web API does not support native OpenAI-style JSON schema tool calling. If you are using this with an agent harness (such as **OpenCode**, **π / Pi**, **Hermes**, **Cursor**, etc.) that requires tool execution, configure your harness to use **prompt-based text tool calling** (where the model outputs tool calls in text blocks such as JSON/XML for the harness to parse).
+
+---
+
+## ⚡ Quick Start
+
+### 1. Set Your Token
+Obtain your token from [chat.deepseek.com](https://chat.deepseek.com):
+1. Sign in to [chat.deepseek.com](https://chat.deepseek.com).
+2. Open DevTools (**F12**), go to **Application** > **Local Storage**.
+3. Copy the value of `userToken`.
+4. Create a `.env` file in your directory:
+   ```env
+   DEEPSEEK_TOKEN="your_token_here"
+   ```
+
+### 2. Run Directly with npx
+```bash
+# Run interactive chat
+npx deepseek-local-api
+
+# Or start the OpenAI-compatible local server
+npx deepseek-local-api --server 3000
+```
+
+### 3. Or Install Globally
+```bash
+npm install -g deepseek-local-api
+
+# Now available anywhere:
+deepseek-local-api
+# Or via short alias:
+deepseek
+```
+
+---
+
+## 🛠️ Usage Modes
+
+### Mode 1: Interactive Terminal Chat
+Run without arguments to start an interactive multi-turn conversation:
+```bash
+deepseek-local-api
+```
+**Interactive Features:**
+- **Tab Autocomplete**: Type `/` and press `Tab` to see and autocomplete commands.
+- **Arrow-Key Session Picker**: Use `↑` / `↓` to select from past saved sessions.
+- **Live In-Chat Commands:**
+  - `/help`: Display all available commands.
+  - `/thinking`: Toggle reasoning/thinking mode on or off.
+  - `/search`: Toggle web search mode on or off.
+  - `/server [port]`: Launch the local OpenAI-compatible server on the fly.
+  - `/new`: Start a fresh session.
+  - `/id`: Print current session ID and direct web URL.
+  - `/exit`: Quit session.
+
+---
+
+### Mode 2: Single-Turn CLI Prompt
+Send a quick prompt and stream the result directly to your terminal:
+```bash
+deepseek-local-api "Explain Dijkstra algorithm in simple terms"
+```
+
+---
+
+### Mode 3: OpenAI-Compatible Local Server
+Run a local API server compatible with any OpenAI API client:
+```bash
+# Start on localhost (127.0.0.1:3000)
+deepseek-local-api --server 3000
+
+# Expose to your local network / LAN (0.0.0.0:8080)
+deepseek-local-api --server 8080 --network
+```
+
+#### Supported Endpoints:
+- `POST http://localhost:3000/v1/chat/completions`
+  - Supports standard OpenAI payload (`model`, `messages`, `stream`).
+  - Supports both **Streaming** (`stream: true` via SSE) and **Non-Streaming** (`stream: false`).
+  - Includes `reasoning_content` delta for thinking process.
+  - Full **CORS** enabled.
+- `GET http://localhost:3000/v1/models`
+  - Returns `deepseek-chat` and `deepseek-reasoner`.
+- `GET http://localhost:3000/health`
+  - Health check endpoint.
+
+---
+
+## 🤖 Harness Integration Guide (OpenCode, π / Pi, Hermes, Cursor, Continue)
+
+You can plug this server into any AI harness or coding tool by pointing it to your local endpoint:
+
+### Configuration Settings
+| Setting | Value |
+| :--- | :--- |
+| **Base URL** | `http://localhost:3000/v1` |
+| **API Key** | `dummy-token` *(any non-empty string)* |
+| **Models** | `deepseek-chat` or `deepseek-reasoner` |
+| **Streaming** | Enabled (`true`) |
+
+---
+
+### Recommended System Prompt for Harnesses & Agents
+
+Copy and paste this system prompt into your harness configuration (OpenCode, Pi, Hermes, etc.) to ensure optimal performance and prompt-based tool parsing:
+
+```text
+You are an AI programming assistant powered by DeepSeek via a local OpenAI-compatible API provider.
+
+CRITICAL OPERATIONAL RULES:
+1. Native API-level function/tool calling is NOT supported by this provider.
+2. All tool usage must follow a strict text-based format. When you need to execute an action (reading a file, running a shell command, searching, etc.), output your request in a structured code block:
+   ```json
+   {
+     "action": "<tool_name>",
+     "parameters": {
+       "<param_key>": "<param_value>"
+     }
+   }
+   ```
+3. When reasoning is required, clearly structure your thinking before providing the final answer.
+4. Keep answers concise, actionable, and focused on code execution.
+```
+
+---
+
+## 📄 License
+MIT

package/bin/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+
+// Attempt to load .env from current working directory, then fallback to package root
+const cwdEnv = path.resolve(process.cwd(), '.env');
+const pkgEnv = path.join(__dirname, '..', '.env');
+
+if (fs.existsSync(cwdEnv)) {
+    require('dotenv').config({ path: cwdEnv });
+} else if (fs.existsSync(pkgEnv)) {
+    require('dotenv').config({ path: pkgEnv });
+} else {
+    require('dotenv').config();
+}
+
+const args = process.argv.slice(2);
+
+// Handle --help / -h
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+\x1b[1;36mDeepSeek Local API & CLI Client\x1b[0m
+
+\x1b[1mUSAGE:\x1b[0m
+  deepseek-local-api [options] [message]
+  deepseek [options] [message]
+
+\x1b[1mMODES:\x1b[0m
+  \x1b[32mInteractive Chat:\x1b[0m
+    deepseek-local-api
+    (Launches multi-turn interactive session with Tab autocomplete)
+
+  \x1b[32mSingle Prompt:\x1b[0m
+    deepseek-local-api "Your prompt message"
+    deepseek-local-api "Your prompt" [session-id]
+
+  \x1b[32mOpenAI-Compatible Local API Server:\x1b[0m
+    deepseek-local-api --server 3000
+    deepseek-local-api --server 8080 --network
+
+\x1b[1mSERVER OPTIONS:\x1b[0m
+  --server, -s [port]    Start OpenAI-compatible HTTP server (default port: 3000)
+  --port, -p [port]      Alternative port flag
+  --network, -n, --public Enable local network / LAN access (binds to 0.0.0.0)
+
+\x1b[1mGENERAL OPTIONS:\x1b[0m
+  --help, -h             Show this help screen
+  --version, -v          Show package version
+
+\x1b[1mENVIRONMENT VARIABLES:\x1b[0m
+  DEEPSEEK_TOKEN         Your DeepSeek auth token (from chat.deepseek.com)
+  DEEPSEEK_COOKIE        Optional WAF / session cookie
+`);
+    process.exit(0);
+}
+
+// Handle --version / -v
+if (args.includes('--version') || args.includes('-v')) {
+    const pkg = require('../package.json');
+    console.log(`deepseek-local-api v${pkg.version}`);
+    process.exit(0);
+}
+
+// Forward execution to main index runner
+require('../src/index.js');

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "deepseek-local-api",
+  "version": "0.8.0",
+  "description": "Convert DeepSeek Web Chat to an OpenAI-compatible local API and interactive CLI for any harness or agent",
+  "main": "src/index.js",
+  "bin": {
+    "deepseek-local-api": "bin/cli.js",
+    "deepseek": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node -r dotenv/config src/index.js",
+    "server": "node -r dotenv/config src/index.js --server 3000",
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "wasm",
+    ".env.example",
+    "README.md"
+  ],
+  "keywords": [
+    "deepseek",
+    "chat",
+    "api",
+    "openai-compatible",
+    "llm",
+    "harness",
+    "reasoner",
+    "client",
+    "cli"
+  ],
+  "author": "m-elramsesy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m-elramsesy/deepseek-local-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/m-elramsesy/deepseek-local-api/issues"
+  },
+  "homepage": "https://github.com/m-elramsesy/deepseek-local-api#readme",
+  "license": "MIT",
+  "dependencies": {
+    "dotenv": "^16.0.3"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/client/ChatSession.js

@@ -0,0 +1,187 @@
+const fs = require('fs');
+const path = require('path');
+const { API_ENDPOINTS } = require('../config/constants');
+const { HeadersBuilder } = require('../config/headers');
+
+const DATA_DIR = path.join(__dirname, '..', '..', 'data');
+const SESSIONS_FILE = path.join(DATA_DIR, 'sessions.json');
+
+class ChatSession {
+    constructor(sessionId = null, parentMessageId = null, title = null) {
+        this.sessionId = ChatSession.parseSessionId(sessionId);
+        this.currentMessageId = 0;
+        this.parentMessageId = parentMessageId;
+        this.title = title || 'New Chat';
+    }
+
+    /**
+     * Parse session ID from either a raw UUID or a full DeepSeek web URL
+     * e.g. https://chat.deepseek.com/a/chat/s/48893d3d-cb96-4e8c-a7ef-344038a36e15
+     */
+    static parseSessionId(input) {
+        if (!input || typeof input !== 'string') return null;
+        const trimmed = input.trim();
+        const uuidMatch = trimmed.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+        return uuidMatch ? uuidMatch[0] : trimmed;
+    }
+
+    /**
+     * Get direct web URL for this session
+     */
+    getWebUrl() {
+        return this.sessionId ? API_ENDPOINTS.WEB_SESSION_URL(this.sessionId) : null;
+    }
+
+    /**
+     * Create a brand new session on DeepSeek
+     */
+    static async create(token, parentMessageId = null) {
+        const headers = HeadersBuilder.getAuthHeaders(token);
+        const payload = { character_id: null };
+
+        try {
+            const response = await fetch(API_ENDPOINTS.CREATE_SESSION, {
+                method: 'POST',
+                headers: headers,
+                body: JSON.stringify(payload)
+            });
+
+            if (!response.ok) {
+                const errorData = await response.text();
+                console.error("Session creation error:", errorData);
+                throw new Error(`Session creation failed: ${response.status}`);
+            }
+
+            const data = await response.json();
+            const sessionId = data?.data?.biz_data?.id || data?.biz_data?.id;
+            if (!sessionId) {
+                throw new Error("Could not find session ID in response");
+            }
+
+            const session = new ChatSession(sessionId, parentMessageId);
+            session.save();
+            return session;
+        } catch (error) {
+            console.error("Error in createSession:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Resume an existing session by ID or Web URL.
+     * Attempts to fetch message history from DeepSeek to determine the latest parent_message_id.
+     */
+    static async resume(token, sessionIdOrUrl) {
+        const sessionId = this.parseSessionId(sessionIdOrUrl);
+        if (!sessionId) {
+            throw new Error("Invalid session ID or URL provided");
+        }
+
+        // Check local saved session first
+        const saved = this.getSavedSession(sessionId);
+        let parentMessageId = saved ? saved.parentMessageId : null;
+        let title = saved ? saved.title : 'Resumed Chat';
+
+        // Try to query DeepSeek for latest messages in this session
+        try {
+            const headers = HeadersBuilder.getAuthHeaders(token);
+            const historyUrl = `${API_ENDPOINTS.HISTORY_MESSAGES}?chat_session_id=${sessionId}`;
+            const res = await fetch(historyUrl, {
+                method: 'GET',
+                headers: headers
+            });
+
+            if (res.ok) {
+                const data = await res.json();
+                const messages = data?.data?.biz_data?.chat_messages || data?.biz_data?.chat_messages || [];
+                if (messages.length > 0) {
+                    const lastMsg = messages[messages.length - 1];
+                    parentMessageId = lastMsg.message_id || lastMsg.id || parentMessageId;
+                    if (!saved?.title && messages[0]?.content) {
+                        title = messages[0].content.slice(0, 35);
+                    }
+                }
+            }
+        } catch (e) {
+            // Fallback to local state if offline or API call fails
+        }
+
+        const session = new ChatSession(sessionId, parentMessageId, title);
+        session.save();
+        return session;
+    }
+
+    getCurrentMessageId() {
+        return this.currentMessageId;
+    }
+
+    incrementMessageId() {
+        this.currentMessageId += 1;
+        return this.currentMessageId;
+    }
+
+    getParentMessageId() {
+        return this.parentMessageId === null ? null : this.parentMessageId;
+    }
+
+    setParentMessageId(id) {
+        this.parentMessageId = id;
+        this.save();
+    }
+
+    setTitle(title) {
+        this.title = title;
+        this.save();
+    }
+
+    getId() {
+        return this.sessionId;
+    }
+
+    // --- Lightweight Local Persistence ---
+
+    static ensureDataDir() {
+        if (!fs.existsSync(DATA_DIR)) {
+            fs.mkdirSync(DATA_DIR, { recursive: true });
+        }
+    }
+
+    static loadAllSavedSessions() {
+        this.ensureDataDir();
+        if (!fs.existsSync(SESSIONS_FILE)) return [];
+        try {
+            return JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8'));
+        } catch (e) {
+            return [];
+        }
+    }
+
+    static getSavedSession(id) {
+        const sessions = this.loadAllSavedSessions();
+        return sessions.find(s => s.id === id) || null;
+    }
+
+    save() {
+        if (!this.sessionId) return;
+        ChatSession.ensureDataDir();
+        const sessions = ChatSession.loadAllSavedSessions();
+        const idx = sessions.findIndex(s => s.id === this.sessionId);
+        const entry = {
+            id: this.sessionId,
+            webUrl: this.getWebUrl(),
+            title: this.title,
+            parentMessageId: this.parentMessageId,
+            updatedAt: new Date().toISOString()
+        };
+
+        if (idx >= 0) {
+            sessions[idx] = { ...sessions[idx], ...entry };
+        } else {
+            sessions.unshift(entry);
+        }
+
+        fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2), 'utf8');
+    }
+}
+
+module.exports = ChatSession; 

package/src/client/DeepseekClient.js

@@ -0,0 +1,134 @@
+const { API_ENDPOINTS, CHAT_CONFIG } = require('../config/constants');
+const { HeadersBuilder } = require('../config/headers');
+const PowService = require('../services/PowService');
+const ChatSession = require('./ChatSession');
+
+class DeepseekClient {
+    constructor(token, parentMessageId = null) {
+        this.token = token;
+        this.powService = new PowService();
+        this.currentSession = null;
+        this.parentMessageId = parentMessageId;
+    }
+
+    async initialize() {
+        await this.powService.initialize();
+    }
+
+    async createSession() {
+        this.currentSession = await ChatSession.create(this.token, this.parentMessageId);
+        return this.currentSession;
+    }
+
+    async resumeSession(sessionIdOrUrl) {
+        this.currentSession = await ChatSession.resume(this.token, sessionIdOrUrl);
+        return this.currentSession;
+    }
+
+    async sendMessage(message, session = null, { thinking_enabled = false, search_enabled = false } = {}) {
+        if (!session && !this.currentSession) {
+            session = await this.createSession();
+        }
+        const chatSession = session || this.currentSession;
+
+        if (chatSession.title === 'New Chat') {
+            chatSession.setTitle(message.slice(0, 35));
+        }
+
+        // Increment message ID for human message
+        chatSession.incrementMessageId();
+
+        const powDataB64 = await this.powService.getPowResponse(
+            this.token,
+            API_ENDPOINTS.TARGET_PATH
+        );
+
+        const headers = HeadersBuilder.getChatHeaders(this.token, powDataB64);
+
+        const payload = {
+            prompt: message,
+            model: CHAT_CONFIG.DEFAULT_MODEL,
+            stream: true,
+            temperature: CHAT_CONFIG.DEFAULT_TEMPERATURE,
+            max_tokens: CHAT_CONFIG.DEFAULT_MAX_TOKENS,
+            ref_file_ids: [],
+            thinking_enabled,
+            search_enabled,
+            chat_session_id: chatSession.getId(),
+            parent_message_id: chatSession.getParentMessageId()
+        };
+
+        try {
+            const response = await fetch(API_ENDPOINTS.COMPLETION, {
+                method: 'POST',
+                headers: headers,
+                body: JSON.stringify(payload)
+            });
+
+            if (!response.ok) {
+                const errorData = await response.text();
+                console.error("Chat completion error:", errorData);
+                throw new Error(`Chat completion failed: ${response.status}`);
+            }
+
+            // Increment message ID for AI response
+            chatSession.incrementMessageId();
+            
+            return response;
+        } catch (error) {
+            console.error("Error in sendMessage:", error);
+            throw error;
+        }
+    }
+
+    async *streamResponse(response, session = null) {
+        const chatSession = session || this.currentSession;
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let currentPath = null;
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop();
+
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith('event:')) continue;
+
+                    if (trimmed.startsWith('data:')) {
+                        const dataStr = trimmed.slice(5).trim();
+                        if (!dataStr || dataStr === '{}') continue;
+
+                        try {
+                            const parsed = JSON.parse(dataStr);
+
+                            // Capture and save the response_message_id for threading next message
+                            if (parsed.response_message_id && chatSession) {
+                                chatSession.setParentMessageId(parsed.response_message_id);
+                            }
+
+                            if (parsed.p) currentPath = parsed.p;
+                            if (parsed.v !== undefined && typeof parsed.v === 'string') {
+                                const isThinking = currentPath === 'response/thinking_content';
+                                yield {
+                                    type: isThinking ? 'thinking' : 'content',
+                                    text: parsed.v
+                                };
+                            }
+                        } catch (e) {}
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+}
+
+module.exports = DeepseekClient; 

package/src/config/constants.js

@@ -0,0 +1,29 @@
+const DEEPSEEK_HOST = "chat.deepseek.com";
+
+const API_ENDPOINTS = {
+    CREATE_POW: `https://${DEEPSEEK_HOST}/api/v0/chat/create_pow_challenge`,
+    COMPLETION: `https://${DEEPSEEK_HOST}/api/v0/chat/completion`,
+    CREATE_SESSION: `https://${DEEPSEEK_HOST}/api/v0/chat_session/create`,
+    FETCH_SESSIONS: `https://${DEEPSEEK_HOST}/api/v0/chat_session/fetch_page`,
+    HISTORY_MESSAGES: `https://${DEEPSEEK_HOST}/api/v0/chat/history_messages`,
+    TARGET_PATH: '/api/v0/chat/completion',
+    WEB_SESSION_URL: (id) => `https://${DEEPSEEK_HOST}/a/chat/s/${id}`
+};
+
+const WASM_CONFIG = {
+    DEFAULT_PATH: "./wasm/sha3_wasm_bg.7b9ca65ddd.wasm",
+    SUPPORTED_ALGORITHMS: ["DeepSeekHashV1"]
+};
+
+const CHAT_CONFIG = {
+    DEFAULT_MODEL: "deepseek-chat",
+    DEFAULT_TEMPERATURE: 0.7,
+    DEFAULT_MAX_TOKENS: 4096
+};
+
+module.exports = {
+    DEEPSEEK_HOST,
+    API_ENDPOINTS,
+    WASM_CONFIG,
+    CHAT_CONFIG
+}; 

package/src/config/headers.js

@@ -0,0 +1,45 @@
+const BASE_HEADERS = {
+    "Host": "chat.deepseek.com",
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36",
+    "Accept": "*/*",
+    "Accept-Encoding": "gzip, deflate, br, zstd",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Content-Type": "application/json",
+    "Origin": "https://chat.deepseek.com",
+    "Referer": "https://chat.deepseek.com/",
+    "Sec-Ch-Ua": "\"Not A(Brand\";v=\"8\", \"Chromium\";v=\"152\", \"Google Chrome\";v=\"152\"",
+    "Sec-Ch-Ua-Mobile": "?0",
+    "Sec-Ch-Ua-Platform": "\"Windows\"",
+    "Sec-Fetch-Dest": "empty",
+    "Sec-Fetch-Mode": "cors",
+    "Sec-Fetch-Site": "same-origin",
+    "x-app-version": "20241129.1",
+    "x-client-locale": "en_US",
+    "x-client-platform": "web",
+    "x-client-version": "1.0.0-always"
+};
+
+class HeadersBuilder {
+    static getAuthHeaders(token, cookie = process.env.DEEPSEEK_COOKIE) {
+        const headers = {
+            ...BASE_HEADERS,
+            "Authorization": `Bearer ${token}`
+        };
+        if (cookie) {
+            headers["Cookie"] = cookie;
+        }
+        return headers;
+    }
+
+    static getChatHeaders(token, powDataB64, cookie = process.env.DEEPSEEK_COOKIE) {
+        return {
+            ...this.getAuthHeaders(token, cookie),
+            "x-ds-pow-response": powDataB64
+        };
+    }
+}
+
+module.exports = {
+    BASE_HEADERS,
+    HeadersBuilder
+};