DeepSeek-Infra

# DeepSeek Infra <!-- docs-language-switcher:start --> [English](README.en.md) <!-- docs-language-switcher:end -->     > **4.3.7 Replica Convergence & Durable Conflict Resolution:** Conflict tabs enter permanent isolation mode, and subsequent edits only advance their own branch revision, never overwriting the shared Head; a single conflict pointer is upgraded to a durable ledger that can retain any concurrent branch. The notification bar displays the number of pending items and executes "View Latest / Keep Replica" durable transactions one by one—independent replicas commit first, validate the Head and digest, confirm reloadability, and only then release the original branch; crash retries won't generate duplicate replicas. Without Web Locks, use immutable Proposals and a fixed winner order to converge; two truly simultaneous Snapshots are retained; lock callbacks aren't retried after exceptions. Tab selection continuity is decoupled from each real Document's UUID Writer identity, and BroadcastChannel claims automatically rotate duplicate Writers. A damaged Head rolls back and repairs to a valid parent in exclusive arbitration; damaged data enters quarantine; even if a tombstone has been GC'd, a sleeping tab can only create a recovery replica. Recovery Capsule V2 adds per-entry/per-whole digest, write-after-read, deterministic storage pressure compression, and a resolved marker. See [4.3.7 release notes](docs/releases/4.3.7.md) (previous version [4.3.6](docs/releases/4.3.6.md)), [Evidence Index](docs/EVIDENCE_INDEX.md), and [Frontend Modules](docs/FRONTEND_MODULES.md). **4.3.7 validation:** Frontend unit tests and contract tests (69 files / 580 tests) cover conflict branch isolation, multi-branch Ledger, transactional replicas, duplicate Writer rotation, truly interleaved lock-free Proposals, lock callback execution once, degraded Head self-healing, missing-Head prevention, and Capsule V2 validation/compression/quarantine/one-time recovery. Dependencies, backend business protocols, JS/CSS/optional chunk budgets, and the frozen 4.0 runtime contract remain unchanged. ## 30-second Overview DeepSeek Infra is a local-first Personal AI Runtime: Projects, Memory, Skills, MCP tools, multimodal Media, Browser snapshots, Automations, Saved Items, Artifacts and Exports in one private workspace. - **OpenAI Compatible Gateway** — Point any OpenAI SDK's `base_url` to `localhost:8000/v1` for integration - **Persistent Agent DAG Runtime** — Planner → Worker → Critic → Synthesizer, supporting disconnection recovery - **MCP Native Tool Center** — 17 local tools exposed as a standard MCP Server, with external MCP server bridging featuring health/retry/fuse - **A2A-style Agent Mesh** — Agent Card discovery + task lifecycle, cross-Agent delegation - **Local RAG Data Layer** — Hybrid retrieval + citation backlinking, zero external dependencies - **Tool Policy Engine** — Capability-based access control, SSRF/path/injection protection applied sequentially - **Workspace Core** — Projects, saved items, artifact center, and export packages unified into a local object model - **Automation Runtime** — Manual, timed, interval, and event-triggered local automation, reusing Workspace/Skill/Browser capabilities with traceable history - **Trace Observability** — Waterfall diagram, Prometheus metrics, health probes - **Docker One-click Deployment** — Single-volume persistence, non-root execution, built-in HEALTHCHECK ```bash cp .env.example .env # Fill in DEEPSEEK_API_KEY docker compose up -d curl http://127.0.0.1:8000/healthz ``` **Seeing is Believing →** [Screenshots](#screenshots) · [2-minute Demo](docs/DEMO.md) · [Implementation Status Matrix](docs/IMPLEMENTATION_STATUS.md) --- **DeepSeek Infra is a local-first Agentic AI Infrastructure Platform:** An integrated native FastAPI backend combines LLM gateway, multi-Agent DAG runtime, local vector RAG, tool calling runtime, observability, and edge-cloud model routing into a privatizable, multi-platform, observable, and scalable Agentic AI system, interoperating with external systems via standard protocols. Local tools are exposed via **MCP** (Model Context Protocol) to any MCP client, and local Agents communicate with external Agents via **A2A**-style Agent Card + task lifecycle. The desktop version is a local application with an embedded WebView, the Android version is packaged as an APK, and any OpenAI-compatible client can point its `base_url` to the local `/v1`. Except for requests sent to DeepSeek/Tavily, data stays local. > For version-by-version change records, see [CHANGELOG.md](CHANGELOG.md). This document describes the architecture and usage of the **current version**. **Verify before trusting:** [Implementation Status Matrix](docs/IMPLEMENTATION_STATUS.md) (code/test/demo completion status for 13 modules) · [2-minute Demo](docs/DEMO.md) · [Benchmarks](#benchmarks) · [Deployment](docs/DEPLOYMENT.md) · [Threat Model](docs/THREAT_MODEL.md) **Diagram language:** Click the title to switch between Chinese and English. <details open> <summary><strong>English architecture</strong></summary>  </details> > The editable architecture diagram and responsibility boundaries are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). > > Python is the default and authoritative runtime; Rust delegation is optional, deterministic, and has fallback protection. ## Core Infrastructure Modules | # | Module | Code Location | Responsibility | | --- | --- | --- | --- | | 1 | **LLM Gateway** | [`infra/gateway/`](deepseek_infra/infra/gateway/) | OpenAI-compatible `/v1` facade, model routing, streaming forwarding, prompt cache-friendly context management, request queue retry, and fallback. | | 2 | **Agent DAG Runtime** | [`infra/agent_runtime/`](deepseek_infra/infra/agent_runtime/) | Planner dynamically generates execution graphs, dependency scheduling, layer parallelism, Critic revision loops, token budget fencing, event persistence, and disconnection replay. | | 3 | **Local RAG Data Layer** | [`infra/rag/`](deepseek_infra/infra/rag/) | Document parsing/blocking/local embedding/SQLite·sqlite-vec vector index/hybrid retrieval/citation backlinking. | | 4 | **Tool Calling Runtime** | [`infra/tool_runtime/`](deepseek_infra/infra/tool_runtime/) | Controlled local tool execution (math sandbox, file retrieval, URL precision reading, PPT/Word/PDF/mind map generation, etc.), with a preceding capability-based **Tool Policy Engine**: schema validation, role-based capability permissions, risk grading, SSRF/path injection/sensitive write protection, manual confirmation, result prompt injection cleaning, and audit logging. | | 5 | **Observability & Trace** | [`infra/observability/`](deepseek_infra/infra/observability/) | Per-round request trace run/span, waterfall diagram, `/metrics` Prometheus metrics, `/healthz`·`/readyz` probes. | | 6 | **Edge-Cloud Model Router** | [`infra/gateway/edge_inference.py`](deepseek_infra/infra/gateway/edge_inference.py) | Routes simple tasks to local side models, complex tasks to cloud DeepSeek, with fallback to local on cloud failure. | | 7 | **MCP Tool Hub** | [`infra/mcp/`](deepseek_infra/infra/mcp/) | Encapsulates local tools into an MCP server (JSON-RPC 2.0: `tools` / `resources` / `prompts`), allowing any MCP client (Claude Desktop, Cursor, etc.) to directly reuse; external MCP servers can be bridged into the local Agent tool interface. | | 8 | **A2A Agent Mesh** | [`infra/agent_runtime/a2a.py`](deepseek_infra/infra/agent_runtime/a2a.py) | Exposes Agent Card and A2A task lifecycle (`message/send`·`message/stream`·`tasks/resubscribe`·`tasks/get`·`tasks/cancel`) for each local Agent, supporting artifact chunks and cross-Agent delegation. | | 9 | **Context Taint Firewall** | [`infra/gateway/context_taint.py`](deepseek_infra/infra/gateway/context_taint.py) | Tags context with trust labels (web/file/tool result = untrusted), scans for injection/key leakage/tool directives, isolates and packages untrusted blocks, and upgrades high-risk tools with manual confirmation. | | 10 | **Workspace Core** | [`infra/workspace/`](deepseek_infra/infra/workspace/) | Project 2.0, Saved Items, Artifact Hub, and Markdown/HTML/JSON/ZIP export, unified into a local AI workspace object model. | | 11 | **Multimodal Media Layer** | [`infra/media/`](deepseek_infra/infra/media/) | Importing, segmenting, citing, exporting, and media-to-RAG lifecycle for images, PDFs, audio, video, and webpage snapshots. | | 12 | **Browser Control Runtime** | [`infra/browser/`](deepseek_infra/infra/browser/) | Controlled browser sessions, secure gating actions, private address interception, browser-to-media snapshots, webpage content RAG indexing, and audit logging. | | 13 | **Automation Runtime** | [`infra/automation/`](deepseek_infra/infra/automation/) | Local automation definitions, triggers/conditions/actions/policies, run history, trace linkage, and release-gated smoke/eval evidence. | > The completion status of each module (code/test/demo) is in [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md). Cross-platform packaging (Desktop WebView/Android APK/single-file exe/mobile console launcher) is handled by `web/`, `launcher/`, `android_entry.py`, and `desktop_app.py`. ## Screenshots | Chat · Search Sources and Citations | Agent Run · Timeline and Activity | | --- | --- | |  |  | | Trace Waterfall | File Reader | | --- | --- | |  |  | | Diagnostics Panel | Activity Drawer | | --- | --- | |  |  | | Projects Workspace | Skills Panel | | --- | --- | |  |  | | Memory Panel | | | --- | --- | |  | | > Screenshots reflect the current DeepSeek Infra React UI. See [2-minute Demo](docs/DEMO.md) for live demonstrations of each feature. ## Architecture Layers Overview in the first-screen architecture diagram; detailed layers, module responsibilities, and data flows are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Highlights - **One Backend, Multiple Forms**: The same Python backend runs as a desktop local application (embedded WebView, no external browser), Android APK, or native/local service. - **Local-first, Data Stays Local**: Conversation history, drafts, file cache, vector index, long-term memory, tracing, and caching all stay local; DeepSeek/Tavily API keys can be stored as environment variables without being saved to a database. - **OpenAI-compatible Gateway**: `POST /v1/chat/completions` + `GET /v1/models`; any OpenAI SDK/tool can point its `base_url` to the local machine for reuse. - **Standard Protocol Interoperability**: Local tools are exposed via `POST /mcp` using the MCP protocol (not just internal tools; Claude Desktop/Cursor/other Agent clients can directly connect); local Agents provide task delegation via `/.well-known/agent-card.json` and `/a2a` using the A2A protocol. - **Observable and Operable**: Each round of requests generates a trace; `/metrics` exposes Prometheus metrics; `/healthz`·`/readyz` provide probes. ## Capability Details ### Chat and Reasoning - Supports `deepseek-v4-pro` and `deepseek-v4-flash`, defaulting to `deepseek-v4-pro`; quick and expert modes switchable, with expert mode enabling deep thinking by default. - Reasoning processes and final responses are both streamed, with the streaming phase displaying "thinking / calling tools / searching / Agent working / generating". - Supports pause, interrupt, continue, regenerate; editable history user messages can be resent, and branching can start from any assistant response. - Comprehensive Markdown rendering: code blocks (line numbers, folding, copying, downloading, `vscode://file/...` for local path opening), inline and block-level formulas (local KaTeX, no external CDN), `mermaid` flowcharts, and converting table numerical columns to bar/line/pie charts. ### Multi-Agent DAG Collaboration - When multi-Agent is enabled, the Leader decomposes tasks, and Researcher/Coder/Reasoner/Critic roles are topologically layered based on declared `depends_on`, executed in parallel within the same layer, and then synthesized into a final answer by the Synthesizer. - **Recoverable Agent Run**: Each run is persisted to `.agent-runs/`, events are tagged with `runId` / `index` / `createdAt`, and can be resumed from the last event after refreshing the page or disconnecting; the Activity panel supports re-running a single Agent or re-synthesizing. - Critic can nominate a previous worker with feedback to re-run a round before synthesizing; token budget fencing `MULTI_AGENT_TOKEN_BUDGET` prevents further layer launches once exceeded, but synthesis always executes. ### Web Search - Three-tiered web search: off/auto/forced; auto mode determined by the model for each round. - Multi-round complementary search + result deduplication and reordering + local `.search-cache` caching; models can also use the `web_search` tool to retrieve information on demand and perform secondary reading of search results. - Tavily API Key can come from server environment variables or page settings for the current request. ### File Understanding and Workspace - Multi-file upload, supporting text / Markdown / CSV / JSON / code / RTF / HTML / DOCX / XLSX / PPTX / EPUB / PDF, as well as images like PNG / JPG / WebP / BMP / TIFF / GIF; streaming multipart parsing, with a default maximum file size of 200 MB. - Files are parsed, chunked, and cached locally; chat requests only send metadata like `fileId`; questions are answered by retrieving relevant segments from the cache. - Document reading workspace: after uploading PDF / images / text, click 'Preview' to switch to a wide-screen interface with the document on the left and the original text on the right, supporting page turning / zooming / directory / cross-page search / selecting areas to ask questions / translating the full text / summarizing. - Answer citation links: when the model uses references like `[^F1-2]`, the frontend renders them as clickable pins that open the corresponding file segment preview. ### Image Vision and OCR - **Image Visual Understanding**: uploaded images are processed by the `deepseek-v4-pro` multimodal model, which can understand images, answer questions about images, recognize formulas and charts, rather than just extracting pure text. - OCR as a fallback for extracting text: prioritizes calling the DeepSeek API for transcription; if the API is unavailable, the desktop client falls back to local Tesseract / Windows OCR, while the Android APK uses the built-in ML Kit; formula screenshots can use local formula OCR like `pix2tex`. ### Generative Artifacts - DeepSeek function calling can invoke local tools to directly produce downloadable files: `create_pptx` uses `python-pptx` to render real `.pptx` files, `create_document` generates `.docx` / `.pdf` files with precise layout, and `create_mindmap` generates downloadable `.svg` mind maps that can be previewed inline. - Also includes built-in tools like `python_eval`, `search_files`, `fetch_url`, `web_search`, data conversion, charts, reminders, and memory; successful file tools directly return local download links, rather than sending the entire tool result back to the model. ### Workspace Core (Projects / Saved Items / Artifacts / Export) - **Project 2.0**: projects become top-level workspace objects, aggregating files, conversations, project memories, saved items, artifacts, traces, and export records; `GET /api/workspace/projects/{projectId}` returns `stats` and a list of sub-objects. - **Saved Items**: chat fragments, assistant answers, file references, RAG segments, web extracts, media descriptions, generated artifacts, and trace / eval results can all be saved to a project, marked with `purpose=reference|memory_candidate|export_fragment` for later use. - **Artifact Hub**: generated files like `.pptx` / `.docx` / `.pdf` / `.svg` / `.markdown` / `.csv` / `.json` can be registered as project artifacts, supporting preview, download, renaming, versioning, and source tracking. - **Export**: conversations, projects, saved item collections, artifact packages, and evidence packages can be exported as Markdown / HTML / JSON / ZIP; project ZIP files include `metadata.json`, `conversations/`, `saved-items/`, `artifacts/`, `files/source-files/`, and `traces/`, with API keys and tokens sanitized. ### Interoperability: MCP Tool Hub and A2A Agent Mesh - **MCP-native Tool Hub**: `POST /mcp` is an MCP JSON-RPC 2.0 server (`initialize` / `tools/list` / `tools/call` / `resources/list|read` / `prompts/list|get` / `ping`). 17 local tools (search, web scraping, file retrieval, Python computation, charts, mind maps, PPT / Word / PDF generation, memory, reminders) are exposed as standard MCP tools, with input schema and risk annotations (read-only / destructive / open-world) provided. - **A2A Agent Mesh**: each local agent role (orchestrator / researcher / coder / reasoner / critic) has its own **Agent Card** (`/.well-known/agent-card.json` for discovery, `GET /a2a/agents` lists all agents) and JSON-RPC task lifecycle: `message/send` submits tasks for background execution, `message/stream` pushes status and artifact chunks via SSE, `tasks/resubscribe` resumes subscription from a specific chunk index, and `tasks/get` / `tasks/cancel` / `tasks/list` manage tasks. ### Context Security: Taint Tracking and Injection Firewall - **Context Taint Tracking**: each request is assembled and then prompt segments are labeled with trust levels based on their source - system prompts / user input / memory are considered trusted, while web search context, uploaded file content, and external tool results are considered untrusted; untrusted segments are scanned for three types of directives: prompt injection, key exfiltration, and tool invocation directives. - **Active Defense**: search context and file context have deterministic 'injection-proof' declarations; tool call with runtime credentials (DeepSeek / Tavily Key, local token) are strictly rejected; **contamination mitigation** - if a prompt injection directive is detected, high-risk / sensitive write tools automatically require human confirmation. ### Edge and Cloud Collaborative Inference - Optional local edge model support (`EDGE_INFERENCE_ENABLED=1` + `llama-cpp-python` or MLC-LLM backend + GGUF path): `edgeMode=auto` routes short tasks like casual chat / summarization / rewriting / translation to local models, while tasks like coding / math / search / document generation / multi-agent / image processing go to the cloud. - If the cloud connection fails, simple tasks can automatically fall back to local edge models; if no cloud API key is available but a local model is usable, regular conversations can still occur. - `POST /api/edge/route-preview` explains which tasks will be routed to edge or cloud without loading the model, returning the reason and current edge state. ### Local Data Layer and Observability - **Local RAG**: `.file-cache`, `.projects`, and `.memory` are synchronized into `.local-rag/rag.sqlite3`, with pure SQLite and hash-based embedding by default; optional dependencies can enable `sqlite-vec` vector tables and ONNX Runtime for local embedding. - **Tracing**: each chat turn, edge inference, and multi-agent DAG generates a `traceId` written to `.traces/`; assistant messages can display a trace waterfall to view node latency, token usage, and prompt cache hit rates; `GET /trace/{trace_id}` provides a read-only waterfall page, and `GET /api/traces/{trace_id}/export.json` exports a sanitized JSON. - **Semantic Cache**: requests without tools, search, or attachments are checked against `.semantic-cache/` before calling DeepSeek; if a similar request is found, the local cached result is returned directly. ### Long-term Memory · Seek Assistant - Use 'Remember: …' to save preferences / project context / long-term tasks, and 'Forget …' to delete; the model can also suggest memories, which require user confirmation before being written. Supports `global` / `project:<id>` / `seek:<id>` scopes and conflict detection; sensitive content is blocked from entering long-term memory (`.memory/memories.json`). - Seek Assistant: create custom local assistants (name / instructions / opening prompts / reference files), which are automatically injected into conversations; reference files are saved with message snapshots. Up to 40 assistants are supported, with import / export in JSON. ### Frontend Experience - PWA: complete with manifest, icons, and Service Worker, installable to mobile home screens; supports Share Target for importing articles / URLs / images / documents from the system. - Four visual styles (ChatGPT / Linear / Notion / Arc) × light / dark / system theme, plus an optional Gemini skin; supports Web Speech for voice input and reading, drag-and-drop / paste upload, selected text querying, auto-saving drafts, local reminders, command palette (`Ctrl/Cmd+K`), and global hotkeys. ## OpenAI Compatible Gateway Point any OpenAI SDK or tool's `base_url` to `/v1` to reuse the entire runtime. Pass a **local access token** as the `api_key` for local authentication; upstream DeepSeek Key is provided by the server configuration (`DEEPSEEK_API_KEY`). ```python from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="<local_access_token>") resp = client.chat.completions.create( model="deepseek-v4-pro", messages=[{"role": "user", "content": "Hello"}], ) print(resp.choices[0].message.content) ``` ```bash curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer <local_access_token>" ``` - `POST /v1/chat/completions`: supports `stream` (standard `chat.completion.chunk` SSE + `[DONE]`) and non-streaming (`chat.completion`). - `GET /v1/models`: lists available models (`deepseek-v4-pro` / `deepseek-v4-flash`). ## Rust Gateway Sidecar The Rust Gateway sidecar (from 3.0.3) has been moved to a separate document: RAG vector ranking (JSON and `f64le` binary transfer), Gateway / MCP / RAG request delegation, semantic cache binary embedding, Rust Policy, sidecar performance benchmarks, and Docker Compose startup, see [docs/RUST_GATEWAY_SIDECAR.md](docs/RUST_GATEWAY_SIDECAR.md). ## Protocol Endpoints (MCP / A2A) - `POST /mcp` — MCP JSON-RPC 2.0 endpoint (local token authentication). Point the MCP client's Streamable HTTP server address to this endpoint to use local tools; `GET /api/mcp` shows the hub status. - `GET /.well-known/agent-card.json` — A2A discovery: orchestrator's Agent Card (metadata only, no authentication). - `GET /a2a/agents` — lists all local Agent Cards; `POST /a2a` and `POST /a2a/agents/{agentId}` — A2A JSON-RPC (`message/send` / `message/stream` / `tasks/resubscribe` / `tasks/get` / `tasks/cancel` / `tasks/list`, local token authentication). ## Operational Endpoints - `GET /healthz` — liveness: `{status, version, runtime, provider, auth_enabled}` (unauthenticated). - `GET /readyz` — readiness: local storage accessibility and upstream Key configuration status (unauthenticated). - `GET /metrics` — Prometheus text: `ai_requests_total`, `ai_agent_runs_total`, `ai_model_calls_total`, `ai_semantic_cache_hits_total`, `ai_tokens_total`, `ai_run_latency_ms_avg`, etc. Bound to `127.0.0.1` by default. ## Benchmarks [benchmarks/](benchmarks/) provides 4 reproducible benchmarks (all supporting `--json`). The table below **lists offline items with actual measurements** (reproducible runs), while online items depend on your network and upstream load, and no fabricated numbers are provided: > **Benchmark Environment**: Windows 11 · Python 3.13 · CPU Intel i7-13700H · RAM 16 GB · SSD · Dataset 95 chunks · runs 10 · warmup 2 · Report avg · Default zero-dependency hash embedding path | Benchmark | Key Results (Actual) | Reproduction Command | | --- | --- | --- | | RAG Retrieval (Offline) | 95 chunks indexing 130 ms; retrieval avg 20.2 ms · P95 21.7 ms; **Recall@5 1.000 · MRR 0.917** | `python benchmarks/bench_rag_retrieval.py` | | Semantic Cache (Offline) | hash provider: store avg 17.9 ms · lookup avg 8.4 ms; **precise hit 1.00 · unrelated false hit 0.00**; rewrite hit 0.00 (hash similarity about 0.80 < threshold 0.95, conservative non-misanswer is expected behavior). ONNX provider available with `--provider onnx` for separate benchmarking before deciding whether to enable by default. | `python benchmarks/bench_semantic_cache.py --provider hash` | | Chat Latency (Online) | Streaming TTFT / total latency avg·P50·P95, token usage, semantic cache hit distribution | `python benchmarks/bench_chat_latency.py --n 3` | | Agent DAG (Online) | End-to-end latency, per Agent time consumption table, token and estimated cost | `python benchmarks/bench_agent_dag.py` | The accompanying **quality evaluation** is in [evals/](evals/) (all offline and runnable): `python evals/runners/run_offline_eval_suite.py --include-agent --strict` will uniformly leave a [latest eval report](evals/reports/latest.md), with the current baseline being RAG Recall@5 1.000 / Citation Accuracy 0.8333, **Tool Policy Pass Rate 1.000 / Prompt Injection Defense Pass 1.000** for 26 fixed attack and defense use cases, and `block_rate` / `false_positive_rate` / `bypass_rate` hard limits for adversarial injection small corpus; `run_agent_eval.py --strict` additionally generates an [Agent Eval report](evals/reports/agent-latest.md), with a threshold of Tool Call Accuracy 0.90 / Agent Success Rate 0.85 / Prompt Regression Pass Rate 0.90 to block CI. `run_security_corpus.py --strict` generates a [Security Corpus report](evals/reports/security-latest.md), covering prompt injection, tool policy attack, benign false-positive, SSRF, path traversal, and key exposure corpus. See [evals/README.md](evals/README.md), [docs/EVAL_REPORTS.md](docs/EVAL_REPORTS.md), and [docs/AGENT_EVAL.md](docs/AGENT_EVAL.md) for details. The minimum command set for local security capability reproduction is in [docs/SECURITY_SMOKE.md](docs/SECURITY_SMOKE.md). **Historical 3.10.0 preflight:** The original 3.10.0 command roster and evidence remain preserved in git history. The active rc.2 commands and versioned evidence paths are maintained in [docs/EVIDENCE_INDEX.md](docs/EVIDENCE_INDEX.md). ## Quick Start ### Method 1 (Recommended): Local Desktop Application Window 1. Install Python dependencies once: ```powershell python -m pip install -r requirements.txt ``` 2. **Windows**: Double-click `launch.bat` directly; **macOS / Linux**: Double-click or execute `./launch.sh` to open the DeepSeek Infra local application window. 3. Fill in the DeepSeek API Key (required) and Tavily API Key (optional) in the settings at the top right corner of the application; alternatively, provide the keys through environment variables. The desktop application will automatically use the local token entry with `desktop=1` to complete authentication, and you don't need to manually copy the token link; if you choose to access the command-line service through a browser, use the address with `?token=...` printed in the terminal. You need to manually select the port, LAN mode, or view service logs, run `python launch.py --gui` or `DeepSeekInfra.exe --gui` (old name `DeepSeekMobile.exe` continues to be compatible) to open the old GUI launcher. ### Method 2: Run Directly on Mobile Device On Android devices, you can use Termux or Pydroid and other Python environments to run the backend directly, and then open the local address on the browser of the same device: ```bash python -m pip install -r requirements-mobile.txt python launch_mobile.py ``` You can also run `python launch.py --mobile`. The mobile launcher will not import desktop GUI dependencies, listen to `127.0.0.1:8000` by default, and print the `Open on this phone` address after startup; if there is `termux-open-url` in the environment, it will try to open the browser automatically. To allow other devices on the same LAN to access this device, add `--lan` to listen to `0.0.0.0`. Common parameters: ```bash python launch_mobile.py --api-key "Your DeepSeek API Key" --tavily-api-key "Your Tavily API Key (optional)" python launch_mobile.py --port 8010 --no-open python launch_mobile.py --lan ``` ### Method 3: Command-Line Startup (Compatible with Old Usage) ```powershell cd D:\deepseek python -m pip install -r requirements.txt $env:DEEPSEEK_API_KEY="Your DeepSeek API Key" $env:TAVILY_API_KEY="Your Tavily API Key (optional, for online search)" python app.py ``` macOS / Linux: ```bash cd /path/to/deepseek python -m pip install -r requirements.txt export DEEPSEEK_API_KEY="Your DeepSeek API Key" export TAVILY_API_KEY="Your Tavily API Key (optional, for online search)" python app.py ``` You can also temporarily fill in the API Key in the top-right corner settings on the page without setting environment variables. After startup, the terminal will print two addresses: `Computer` (for computer access) and `Phone` (for mobile access, requiring the same Wi-Fi or LAN as the computer). By default, all `/api/*` requests require a local access token. Please use the address with `?token=...` printed in the terminal to open the application, and the browser will automatically save the authentication cookie; the desktop local application window will automatically complete the first-screen authentication with `?token=...&desktop=1`. The default token will be written to the local `.auth-token` and reused after restart. ### Method 4: Packaging into a Single Executable for Distribution When you need to distribute the project to computers without Python installed: ```powershell python -m pip install -r requirements.txt python -m pip install -r requirements-build.txt python scripts/build_exe.py ``` A single `DeepSeekInfra.exe` (old name `DeepSeekMobile.exe` reserved for compatibility; same for macOS / Linux) will be output in `dist/`. Double-click to open the local application window by default; the `.auth-token` / `.file-cache` / `.memory` and other data generated during operation will be written to the directory where the executable is located. The old launcher can be opened through `DeepSeekInfra.exe --gui`. ### Method 5: Packaging into Android APK The `android/` Android Studio project in the repository can package the existing Python backend and web frontend into an APK. After the APK is started, it will run the Python service in the application's private directory and open the local address using the built-in WebView, without needing to install Termux or Pydroid on the device. ```bash cd android gradle :app:assembleDebug ``` Output location: `android/app/build/outputs/apk/debug/app-debug.apk`. For detailed environment, signature, and installation instructions, see [docs/APK.md](docs/APK.md). ### Method 6: Docker / Compose Deployment ```bash cp .env.example .env # Fill in DEEPSEEK_API_KEY, etc. docker compose up -d curl http://127.0.0.1:8000/healthz ``` The image is python:3.12-slim, runs without root, and has a built-in `/healthz` HEALTHCHECK; all runtime data is persisted in a `/data` volume. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for details (including bare metal / systemd / reverse proxy and security boundaries). The default command still only starts Python. Optional Rust sidecar usage `docker-compose.rust.yml`, see [Rust Hybrid Runtime Runbook](docs/RUST_HYBRID_RUNTIME_RUNBOOK.md). ## Environment Variables - `DEEPSEEK_API_KEY`: DeepSeek API Key. Can be left blank and filled in temporarily in page settings. - `TAVILY_API_KEY`: Tavily search API Key. Can be left blank and filled in temporarily in page settings or saved to the local browser. - `PORT`: Local service starting port, default `8000`. - `HOST=0.0.0.0`: Enable LAN / mobile access; listen to `127.0.0.1` by default. - `DEEPSEEK_INFRA_ROOT=/path/to/data`: **Recommended**, specify the data root directory (alternative to `DEEPSEEK_MOBILE_ROOT`). - `DEEPSEEK_MOBILE_ROOT=/path/to/data`: Backward compatible, if both are set, the latter takes precedence. - `DEEPSEEK_INFRA_STATIC_DIR=/path/to/static`: **Recommended**, specify the static resource directory (alternative to `DEEPSEEK_MOBILE_STATIC_DIR`). - `DEEPSEEK_MOBILE_STATIC_DIR=/path/to/static`: Backward compatible, if both are set, the latter takes precedence. - `AUTH_DISABLED=1`: Disable local token authentication, only recommended for trusted development environments. - `AUTH_TOKEN=...`: Use a fixed token for easy local testing. - `AUTH_ALLOWED_HOSTS=host1,host2`: Append allowed Host header names. - `OCR_ENABLED=1`: Allow OCR by default; if not enabled, you can still try OCR again after upload failure. - `OCR_MODE=fast|balanced|quality`: Local OCR enhancement gear, default `balanced`. - `OCR_PDF_DPI=300`: Scan PDF rendering DPI, limited to `150..450`, default `300`. - `OCR_MAX_IMAGE_PIXELS=16000000`: Maximum image pixels allowed for OCR processing, exceeding will be scaled down proportionally. - `OCR_FORMULA_CMD='pix2tex "{image}"'`: Optional local formula OCR command; if not set, it will automatically try `pix2tex` / `latexocr` in PATH. - `OCR_FORMULA_TIMEOUT_SECONDS=120`: Formula OCR command timeout, limited to `5..600` seconds. - `DEEPSEEK_TIMEOUT_SECONDS`: DeepSeek synchronous, streaming, and context compression request socket idle timeout, default `180`. - `MULTI_AGENT_TIMEOUT_SECONDS`: Multi-Agent parallel level timeout, default `3900`; for long tasks, it is recommended to increase with `DEEPSEEK_TIMEOUT_SECONDS`. - `MULTI_AGENT_TOKEN_BUDGET`: Token budget for a single run of multi-Agent, default `2000000`, set `0` for no limit. - `TAVILY_TIMEOUT_SECONDS`: Tavily search request timeout, default `45`. - `UPLOAD_FILE_MAX_BYTES` / `UPLOAD_MAX_BYTES`: Single file / single request body limit, default `200000000` / `220000000`. - `EDGE_INFERENCE_ENABLED=1` / `EDGE_PROVIDER=llama_cpp` (compatible with `EDGE_INFERENCE_PROVIDER`) / `EDGE_MODEL_PATH=/models/qwen2.5-1.5b-instruct-q4_k_m.gguf` / `EDGE_MODE=auto`: Optional local edge inference minimum configuration, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details. - `OLLAMA_ENABLED=1` / `OLLAMA_BASE_URL` / `OLLAMA_TIMEOUT_SECONDS`: Optional local Ollama provider switch, address (default `http://127.0.0.1:11434`), and timeout; after enabling, local models are exposed through the `/v1` gateway with `ollama/<tag>`. - `TOOL_POLICY_ENABLED=1` (enabled by default) / `TOOL_POLICY_ENFORCE_SCHEMA` / `TOOL_POLICY_REQUIRE_CONFIRM` / `TOOL_POLICY_SANITIZE_RESULTS` (enabled by default) / `TOOL_POLICY_AUDIT_ENABLED` (enabled by default): Tool Policy Engine switch - whether to enable tool call security policy, whether to upgrade schema violations from warnings to hard rejects, whether to require human confirmation for high-risk tools, whether to sanitize tool results for prompt injection, and whether to write each policy decision to `.tool-audit/audit.jsonl`. - `SCHEDULER_ENABLED=1` (enabled by default) / `SCHEDULER_MAX_CONCURRENCY` (default 16) / `SCHEDULER_MAX_QUEUE_DEPTH` (default 256, backpressure threshold) / `SCHEDULER_RATE_PER_SECOND` (default 0 = no limit) / `SCHEDULER_RATE_BURST` / `SCHEDULER_ACQUIRE_TIMEOUT_SECONDS` (default 30) / `SCHEDULER_DLQ_ENABLED` (enabled by default) / `SCHEDULER_ORPHAN_SECONDS` (default 900): Local request scheduling layer - maximum concurrency, queue depth (backpressure), token bucket rate limit and burst, admission timeout, Dead Letter Queue switch, and recovery time for in-flight requests at startup. - `MCP_ENABLED=1` (enabled by default) / `MCP_CAPABILITY=full` (capability profile obtained by MCP client) / `MCP_EXPOSE_RESOURCES`, `MCP_EXPOSE_PROMPTS` (enabled by default) / `MCP_CLIENT_ENABLED` (disabled by default) / `MCP_CLIENT_SERVERS='[{"name":"docs","url":"http://127.0.0.1:9001/mcp","timeoutSeconds":10}]'` / `MCP_CLIENT_TIMEOUT_SECONDS` (default 30) / `MCP_CLIENT_MAX_RETRIES` (default 1) / `MCP_CLIENT_RETRY_BACKOFF_SECONDS` (default 0.25) / `MCP_CLIENT_CIRCUIT_BREAKER_FAILURES` (default 3) / `MCP_CLIENT_CIRCUIT_BREAKER_RESET_SECONDS` (default 60): MCP Tool Hub and external MCP client. - `A2A_ENABLED=1` (enabled by default) / `A2A_DEFAULT_AGENT=reasoner` / `A2A_MAX_TASKS` (default 200) / `A2A_HISTORY_LIMIT` (default 20) / `A2A_PEERS=url1,url2` (external A2A Agent endpoints): A2A Agent Mesh. Task execution requires the server-side `DEEPSEEK_API_KEY`. - `TAINT_ENABLED=1` (enabled by default) / `TAINT_HARDEN_SEARCH_CONTEXT`, `TAINT_HARDEN_FILE_CONTEXT` (enabled by default, add isolation declarations to untrusted contexts) / `TAINT_ESCALATE_CONFIRM` (enabled by default, high-risk tool upgrades to human confirmation): Context Taint Tracking and injection firewall. Installation and Dependencies `requirements.txt` contains the dependencies required for backend operation and file parsing, mainly: - `openpyxl`: for reading `.xlsx`; `pypdf` / `PyMuPDF`: for reading PDF text and rendering page by page. - `python-pptx generating `.pptx`; `reportlab`: for generating PDFs with built-in Chinese fonts. - `multipart`: for streaming parsing of `multipart/form-data` uploads; `defusedxml`: for secure parsing of `.docx` / `.xlsx` internal XML. - `customtkinter`: dependency for desktop GUI launcher; for mobile devices, use `requirements-mobile.txt` instead, no need to install this. - `pywebview`: dependency for desktop native application window, using system WebView to display native interface. > Note: The formal dependency is `multipart>=1.3,<2`. If `python-multipart` with the same namespace is installed in the environment, the upload interface will return a clear dependency error; please reinstall according to `requirements.txt`. Optional dependencies can be installed as needed: `requirements-ocr.txt` (local OCR), `requirements-rag.txt` (`sqlite-vec` / ONNX local embedding), `requirements-edge.txt` (`llama-cpp-python` edge-side inference), `requirements-build.txt` (PyInstaller packaging). For image OCR, prioritize using `DEEPSEEK_API_KEY` to call DeepSeek API for transcription; if API Key is missing or recognition is not available, desktop clients will fall back to local Tesseract / Windows OCR. Scanning Poppler / `pdft` in `PATH`; Android APK uses ML Kit as native fallback. Data and Privacy Main data is stored locally: - Conversation unsent drafts / custom Seek: browser `localStorage`. - Project space / document library / saved items / product index / export records: `.projects/{projectId}/`. - File chunk cache: `.file-cache`; search cache: `.search-cache`. - Local RAG vector index: `.local-rag/rag.sqlite3`. - Link tracking: `.traces/traces.sqlite3`; semantic cache: `.semantic-cache/cache.sqlite3`. - Gateway request queue: `.request-queue/queue.sqlite3`; tool policy audit log: `.tool-audit/audit.jsonl`; request scheduling dead letter queue: `.scheduler/scheduler.sqlite3`. - Local reminder queue: `.reminders/reminders.json`; long-term memory: `.memory/memories.json`. - Recoverable Agent Run: `.agent-runs/`; A2A task snapshots: `.a2a/`. - Generated document products (PPT / Word / PDF / mind map) and global Workspace export: `.generated/`. - API Key: DeepSeek / Tavily Key can be saved in the browser or only in server-side environment variables. File chunk cache will be automatically by default, cache is 14 days and `.file-cache` total is controlled at about MB; `.projects/` is persistent Workspace data, only removed when project is deleted, and will not mistakenly delete global `.generated/`, `.memory/`, or other projects. The service cleans up once at startup and approximately every 6 hours during operation. `.gitignore` excludes runtime cache, long-term memory, project document library, local RAG / Trace / semantic cache / request queue, generated document products, A2A task snapshots, reminder queue, coverage, IDE configuration, and local `server*.log` by default. Before release or submission, do not package local data such as `.file-cache`, `.projects`, `.local-rag`, `.traces`, `.semantic-cache`, `.request-queue`, `.generated`, `.tool-audit`, `.scheduler`, `.a2a`, `.budget`, `.memory`, `.reminders`, `.agent-runs`, `.search-cache`, etc. into the release package. It is recommended to use: ```powershell python scripts/release.py --clean-workspace ``` The script will generate `dist/deepseek-infra-<version>.zip` (the old name `deepseek-mobile-<version>.zip` is kept for compatibility), excluding local cache, logs, virtual environment, and IDE files. ## Roadmap The roadmap has been moved to a standalone document: [ROADMAP.en.md](ROADMAP.en.md). ## Documentation All manually maintained Markdown documents provide "Chinese / English" entries at the top; automatically generated evidence, evaluation reports, and `AGENTS.md` remain unchanged to avoid damaging reproducible evidence or agent instructions. - [CHANGELOG.md](CHANGELOG.md) — version-by-version change records. - [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md) — **Implementation Status Matrix**: code / test / demo completion and gaps for 13 modules. - [docs/WORKSPACE.md](docs/WORKSPACE.md) — Workspace Core object model, API, export package structure, and smoke evidence. - [docs/DEMO.md](docs/DEMO.md) — 2-minute demo path (including offline runnable items). - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — layered architecture, infra module, end-cloud routing, and local data layer. - [docs/API.md](docs/API.md) — HTTP API, OpenAI compatible `/v1`, and authentication. - [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) — Docker / Compose / bare machine deployment and reverse proxy boundary. - [docs/SECURITY.md](docs/SECURITY.md) — authentication, sensitive data, and local security boundary. - [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) — seven types of threats → mitigation implementation →. - [docs/FRONTEND_MODULES.md](docs/FRONTEND_MODULES.md) — frontend module splitting. - [docs/APK.md](docs/APK.md) — Android packaging, signing, and installation. - [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — MCP / A2A / OpenAI client compatibility matrix. - [docs/EVIDENCE_INDEX.md](docs/EVIDENCE_INDEX.md) — MCP / A2A / GUI / eval / release evidence total index. - [docs/EDGE_ROUTER_RUNBOOK.md](docs/EDGE_ROUTER_RUNBOOK.md) — Edge Router / Ollama / GGUF local acceptance steps. - [docs/integrations/claude-desktop.md](docs/integrations/claude-desktop.md) / [docs/integrations/cursor.md](docs/integrations/cursor.md) — MCP client configuration snippets and troubleshooting steps. - [evals/README.md](evals/README.md) — evaluation harness; [docs/EVAL_REPORTS.md](docs/EVAL_REPORTS.md) — offline evaluation reports and regression baseline; [docs/AGENT_EVAL.md](docs/AGENT_EVAL.md) — Agent recording and playback specification; [benchmarks/README.md](benchmarks/README.md) — benchmark description. - [docs/RUNTIME_DOCTOR.md](docs/RUNTIME_DOCTOR.md) — runtime physical examination (`scripts/doctor.py`); [docs/RELEASE_READINESS.md](docs/RELEASE_READINESS.md) — pre-release physical examination and release product certification (`scripts/preflight_release.py` / `scripts/smoke_release.py` / release manifest); [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) — release checklist. - [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) - 3.0 quick start. - [docs/MEMORY.md](docs/MEMORY.md) - scoped Memory schema, policy, and APIs. - [docs/SKILLS.md](docs/SKILLS.md) - Skill System and workbench. - [docs/MEDIA.md](docs/MEDIA.md) - multimodal Media import and evidence. - [docs/BROWSER_CONTROL.md](docs/BROWSER_CONTROL.md) - Browser Control runtime. - [docs/AUTOMATION.md](docs/AUTOMATION.md) - Automation Runtime triggers, actions, and run evidence. - [docs/EXPORTS.md](docs/EXPORTS.md) - project/export package formats. - [docs/DEMO_3_0.md](docs/DEMO_3_0.md) - Personal AI Runtime GA demo script and screenshots. ## Precautions Mobile browsers can directly use `http://LAN IP:port`. To stably install to the mobile desktop like a formal app, usually requires HTTPS deployment; local HTTP is more suitable for development and LAN testing. `/metrics`, `/healthz`, `/readyz` do not authenticate by default, please keep the service bound to `127.0.0.1`, or use reverse proxy / firewall to limit access in LAN mode. The root scope PWA cache is managed by `static/ui/sw-root.js` generated by React.