DeepSeek-Infra

mcp
Guvenlik Denetimi
Basarisiz
Health Uyari
  • No license — Repository has no license file
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Basarisiz
  • rm -rf — Recursive force deletion command in .github/workflows/control-rpc-development.yml
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Local-first Agentic AI Infrastructure Platform with LLM Gateway, Agent DAG Runtime, MCP Tool Hub, A2A Agent Mesh, Local RAG, Tool Sandbox and Observability.

README.md

DeepSeek Infra

中文 / English

版本
Python
Coverage Gate
许可证

4.8.0 — 签名联邦与跨 Fleet 灾难恢复(候选实现完成)。Gate A 已关闭不可变 Wave Schedule identity、可续租 runner lease 与真实进程接管;Signed Federation 已实现 dedicated Fleet signing identity、operator-pinned peer trust、Receiver-controlled ingress、签名异地副本证明和 production federated DR,两个 Fleet 始终保持独立 Authority。详见 发布说明、运维手册 与 Evidence 索引。

当前稳定版本说明:4.7.6。4.8.0 的本地真实 MinIO 候选验证已完成;正式 release-ready 仍等待最终 PR head/merge SHA 的全量 CI、三个 exact federation artifacts 与 Evidence Assembly。

历史连续性基线:4.3.6、4.3.7、4.4.0、4.4.1、4.4.2、4.4.3、4.4.4、4.4.5、4.4.6、4.4.7、4.4.8、4.4.9、4.4.10、4.4.11、4.4.12、4.4.13、4.5.0、4.5.1, 4.5.2、4.5.3、4.5.4、4.5.5、4.5.6、4.5.7、4.5.8、4.5.9、4.6.0、4.6.2、4.6.3、4.6.4、4.6.5、4.6.6、4.6.7、4.6.8、4.6.9、4.7.0、4.7.1、4.7.2、4.7.3、4.7.4、4.7.5、4.7.6。

  • 持久化 Agent DAG 运行时 — Planner → Worker → Critic → Synthesizer,支持断线恢复
  • MCP 原生工具中心 — 17 个本地工具以标准 MCP Server 暴露,外部 MCP server 桥接带 health / retry / 熔断
  • 无状态 MCP 执行平面 — 官方 TypeScript SDK + Redis 持久任务/幂等 + 双实例轮询/租约恢复 + OpenTelemetry
  • A2A 风格 Agent 网格 — Agent Card 发现 + 任务生命周期,跨 Agent 委派
  • 本地 RAG 数据层 — 混合检索 + 引用回链,零外部依赖
  • 工具策略引擎 — 按能力的权限控制,SSRF / 路径 / 注入防护逐次生效
  • Workspace Core 工作台 — 项目、保存项、产物中心和导出包统一为本地对象模型
  • Automation Runtime — 手动、定时、间隔与事件触发的本地自动化,复用 Workspace / Skill / Browser 能力并留下可追溯历史
  • Trace 可观测性 — 瀑布图、Prometheus 指标、健康探针
  • Evidence-closed 自治韧性 — persistent Risk Debt、公平多波次调度、真实 transfer reserve、单 effect crash takeover、单调 blast safety,以及 report/proof/SHA-256 一体化取证
  • Docker 一键部署 — 单卷持久化、非 root 运行、内置 HEALTHCHECK
cp .env.example .env   # 填写 DEEPSEEK_API_KEY
docker compose up -d
curl http://127.0.0.1:8000/healthz

眼见为实 → 截图 · 2 分钟 Demo · 实现状态矩阵


DeepSeek Infra 是一个本地优先的 Agentic AI 基础设施平台:集成 Agent 运行时、MCP 原生工具中心、A2A 风格 Agent 网格、LLM 网关、本地 RAG 和端到端可观测性。

DeepSeek Infra 是一个本地优先的 Agentic AI Infra 平台:一套本机 FastAPI 后端把 LLM 网关、多 Agent DAG 运行时、本地向量 RAG、工具调用运行时、链路可观测性和端云模型路由组装成一个可私有化、多端运行、可观测、可扩展的 Agentic AI 系统,并以标准协议对外互操作——本地工具面经 MCP(Model Context Protocol)暴露给任意 MCP 客户端,本地 Agent 经 A2A 风格的 Agent Card + 任务生命周期与外部 Agent 互通。桌面端双击打开内嵌 WebView 的本地应用窗口,Android 端打包成 APK,任何 OpenAI 兼容客户端也能把 base_url 指向本机 /v1。除了你主动发往 DeepSeek / Tavily 的请求,数据都留在本机。

想看逐版本变更记录,请见 CHANGELOG.md。本文档描述当前版本的架构与用法。

先验证,再相信:实现状态矩阵(13 个模块各自的代码 / 测试 / Demo 落地程度)· 2 分钟 Demo · Benchmarks · 部署 · 威胁模型

**架构图语言 / Diagram language:**点击下方标题选择中文或 English。

中文架构图

DeepSeek Infra 中文架构总览

English architecture

DeepSeek Infra architecture overview

可编辑的架构图与职责边界说明见 docs/ARCHITECTURE.md。

Python 是默认且权威运行时;Rust(14 个 Crates,含 Worker 执行面与流式存储/传输)与 Go(cmd/deepseekd 影子控制面)遵循版本化 Protobuf v1 契约与单表单写原则协同执行。

核心基础设施模块

# 模块 代码位置 职责
1 LLM Gateway infra/gateway/ OpenAI 兼容 /v1 门面、模型路由、流式转发、Prompt Cache 友好的上下文管理、请求队列重试与 fallback。
2 Agent DAG Runtime infra/agent_runtime/ Planner 动态生成执行图、依赖调度、同层并行、Critic 修订环、token 预算护栏、事件持久化与断线重放。
3 Local RAG Data Layer infra/rag/ 文档解析 / 分块 / 本地 embedding / SQLite·sqlite-vec 向量索引 / 混合检索 / 引用回链。
4 Tool Calling Runtime infra/tool_runtime/ 受控本地工具执行(数学沙箱、文件检索、URL 精读、PPT / Word / PDF / 思维导图生成等),前置 Capability-based Tool Policy Engine:schema 校验、按角色的能力权限、风险分级、SSRF / 路径越界 / 敏感写入防护、人工确认、结果 prompt injection 清洗与审计日志。
5 Observability & Trace infra/observability/ 每轮请求的 trace run/span、瀑布图、/metrics Prometheus 指标、/healthz·/readyz 探针。
6 Edge-Cloud Model Router infra/gateway/edge_inference.py 简单任务路由到本地端侧模型,复杂任务走云端 DeepSeek,云端失败可回退本地。
7 MCP Tool Hub infra/mcp/ 把本地工具面封装成 MCP server(JSON-RPC 2.0:tools / resources / prompts),Claude Desktop、Cursor 等任意 MCP 客户端可直接复用;外接 MCP server 可桥接进本地 Agent 工具面。
7.5 Stateless MCP Task Service stateless-mcp/ 请求级 TypeScript MCP server factory;Redis 保存任务、日志、租约与幂等索引,双实例故障后可接管恢复,默认 Python Hub 不受影响。
8 A2A Agent Mesh infra/agent_runtime/a2a.py 为每个本地 Agent 暴露 Agent Card 与 A2A 任务生命周期(message/send·message/stream·tasks/resubscribe·tasks/get·tasks/cancel),支持 artifact chunks 与跨 Agent 委派。
9 Context Taint Firewall infra/gateway/context_taint.py 上下文按来源打信任标签(网页 / 文件 / 工具结果 = 不可信),扫描注入 / 密钥外泄 / 工具指令,隔离包装不可信块,污染轮高危工具升级人工确认。
10 Workspace Core infra/workspace/ Project 2.0、Saved Items、Artifact Hub 与 Markdown / HTML / JSON / ZIP 导出,统一本地 AI 工作台对象模型。
11 Multimodal Media Layer infra/media/ Image / PDF / 音频 / 视频 / 网页 snapshot 的导入、分段、citation、project export 与 media-to-RAG 生命周期。
12 Browser Control Runtime infra/browser/ 受控浏览器会话、安全门控动作、私有地址拦截、Browser-to-Media snapshot、网页内容 RAG 索引与审计日志。
13 Automation Runtime infra/automation/ 本地自动化定义、trigger/condition/action/policy、run history、trace linkage 与 release-gated smoke/eval evidence。

每个模块落地到什么程度(Status / Code / Tests / Demo,含明确写出的缺口)见 docs/IMPLEMENTATION_STATUS.md。跨端运行打包(Desktop WebView / Android APK / 单文件 exe / 手机控制台启动器)由 web/、launcher/、android_entry.py 与 desktop_app.py 承载。

Screenshots(截图)

Chat · 搜索来源与引用 Agent Run · Timeline 与 Activity
Chat with search sources and citations Agent run timeline and activity
Trace 瀑布图 文件阅读器
Trace waterfall File reader
诊断面板 Activity 侧栏
Diagnostics panel Activity drawer
Projects 工作台 Skills 面板
Projects workspace Skills panel
Memory 面板
Memory panel

截图反映当前 DeepSeek Infra React UI。请参见 2 分钟 Demo 了解各功能的实际演示。

架构分层

总览见第一屏架构图;分层细节、模块职责与数据流的文字版见 docs/ARCHITECTURE.md。

亮点

  • 一套后端,多种形态:同一份 Python 后端既能作为桌面本地应用窗口(内嵌 WebView,不跳外部浏览器)运行,也能打包成 Android APK,或作为本机 / 局域网服务启动。
  • 本地优先、数据不出端:对话历史、草稿、文件缓存、向量索引、长期记忆、追踪与缓存全部保存在本机;DeepSeek / Tavily API Key 可以只用环境变量、不落库。
  • OpenAI 兼容网关:POST /v1/chat/completions + GET /v1/models,任何 OpenAI SDK / 工具把 base_url 指向本机即可复用整套运行时。
  • 标准协议互操作:本地工具经 POST /mcp 以 MCP 协议暴露(不再只是内部工具,Claude Desktop / Cursor / 其他 Agent 客户端可直接接入);本地 Agent 经 /.well-known/agent-card.json 与 /a2a 以 A2A 风格协议对外提供任务委派。
  • 可观测、可运维:每轮请求生成 trace,/metrics 暴露 Prometheus 指标,/healthz·/readyz 提供探针。

能力详解

对话与推理

  • 支持 deepseek-v4-pro 与 deepseek-v4-flash,默认 deepseek-v4-pro;快速模式 / 专家模式一键切换,专家模式默认开启深度思考。
  • 推理过程与最终回复均流式输出,流式阶段会区分显示「思考中 / 调用工具中 / 搜索中 / Agent 工作中 / 生成中」。
  • 支持暂停、中断、继续、重新生成;可编辑历史用户消息后重发,也可以从任意助手回复创建分支。
  • Markdown 全面渲染:代码块(行号 / 折叠 / 复制 / 下载 / vscode://file/... 打开本地路径)、行内与块级公式(本地 KaTeX,不依赖外部 CDN)、mermaid 流程图,以及把表格数值列一键转成柱状 / 折线 / 饼图。

多 Agent DAG 协作

  • 开启多 Agent 后,Leader 拆解任务,Researcher / Coder / Reasoner / Critic 等角色按声明的 depends_on 做拓扑分层、同层并行,再由 Synthesizer 综合成最终回答。
  • 可恢复 Agent Run:每次运行持久化到 .agent-runs/,事件带 runId / index / createdAt,刷新页面或断线后可从最后一个事件继续恢复;Activity 面板支持单 Agent 重跑或只重新综合。
  • Critic 可点名一个前序 worker 带反馈重跑一轮再综合;token 预算护栏 MULTI_AGENT_TOKEN_BUDGET 超额后不再启动后续层,但综合阶段始终执行。

联网搜索

  • 关闭 / 自动 / 强制三档联网搜索;自动模式由模型决定本轮是否联网。
  • 多轮互补搜索 + 结果去重重排 + 本地 .search-cache 缓存;模型也可以通过 web_search 工具按需检索,并对搜索结果来源做二次精读。
  • Tavily API Key 可来自服务端环境变量,也可来自页面设置中的本轮请求。

文件理解与文档工作台

  • 多文件上传,支持文本 / Markdown / CSV / JSON / 代码 / RTF / HTML / DOCX / XLSX / PPTX / EPUB / PDF,以及 PNG / JPG / WebP / BMP / TIFF / GIF 等图片;流式 multipart 解析,默认单文件最大 200 MB。
  • 文件在本地后端解析、分块、缓存,聊天请求只发送 fileId 等元数据;提问时按问题从缓存检索相关片段。
  • 文档阅读工作台:上传 PDF / 图片 / 文本后点「预览」,宽屏切换成左侧文档对话、右侧原文逐页阅读,支持翻页 / 缩放 / 目录 / 跨页搜索 / 框选区域转图片提问 / 翻译全文 / 一键总结。
  • 回答引用回链:模型使用 [^F1-2] 这类引用标记时,前端渲染为可点击 pin 并打开对应文件片段预览。

图片视觉与 OCR

  • 图片视觉理解:上传图片默认交给 deepseek-v4-pro 多模态模型理解,可读图、看图答题、识别公式与图表,而不是只提取纯文字。
  • OCR 作为「提取文字」的降级路径:优先调用 DeepSeek API 转写,API 不可用时桌面端回退本地 Tesseract / Windows OCR,Android APK 走内置 ML Kit;公式截图可接入 pix2tex 等本地公式 OCR 择优。

生成式产物

  • DeepSeek function calling 可调用本地工具直接产出可下载文件:create_pptx 用 python-pptx 渲染真实 .pptx、create_document 生成排版精美的 .docx / .pdf、create_mindmap 生成可下载 .svg 思维导图并在正文内嵌预览。
  • 还内建 python_eval、search_files、fetch_url、web_search、数据转换、图表、提醒、记忆等工具;终态文件工具成功后直接回传本地下载链接,不再把完整工具结果二次发回模型,保护 prompt cache 命中率。

Workspace Core(项目 / 保存项 / 产物 / 导出)

  • Project 2.0:项目成为一级工作台对象,统一聚合文件、对话、项目记忆、保存项、产物、trace 与导出记录;GET /api/workspace/projects/{projectId} 返回 stats 与子对象列表。
  • Saved Items:聊天片段、助手回答、文件引用、RAG 片段、网页摘录、媒体说明、生成产物、Trace / Eval 结果都可以保存到项目,并用 purpose=reference|memory_candidate|export_fragment 标记后续用途。
  • Artifact Hub:.generated/ 中的 pptx / docx / pdf / svg / markdown / csv / json 等产物可注册为项目产物,支持预览、下载、重命名、版本记录与来源追踪。
  • Export:对话、项目、保存项集合、产物包和证据包可导出为 Markdown / HTML / JSON / ZIP;项目 ZIP 固定包含 metadata.json、conversations/、saved-items/、artifacts/、files/source-files/ 与 traces/,并做 API Key / token 脱敏。

协议互操作:MCP Tool Hub 与 A2A Agent Mesh

  • MCP-native Tool Hub:POST /mcp 是一个 MCP JSON-RPC 2.0 server(initialize / tools/list / tools/call / resources/list|read / prompts/list|get / ping)。本地 17 个工具(搜索、抓取、文件检索、Python 计算、图表、思维导图、PPT / Word / PDF 生成、记忆、提醒)原样暴露为标准 MCP tools,输入 schema 与风险注解(read-only / destructive / open-world)一并下发;生成的产物(pptx / docx / pdf / svg)以 generated://<fileId> resources 暴露,另附 slides-outline、research-brief 两个 prompts。每个 tools/call 都过同一套 Tool Policy 闸门(capability 切片经 MCP_CAPABILITY 配置,schema / SSRF / 路径 / 敏感写入防护与结果清洗全部生效)。外接方向由内置 MCP client(MCP_CLIENT_ENABLED=1 + MCP_CLIENT_SERVERS)消费外部 MCP server 的工具目录;v2.2.3 起支持 per-server timeout、retry、短期 circuit breaker,GET /api/mcp/external/tools 返回 server health / last error / last refresh / retry count,外部调用写入 mcp_external trace span 与 Prometheus 摘要指标。
  • 无状态 MCP 执行平面:stateless-mcp/ 使用官方 TypeScript SDK;每个 Streamable HTTP 请求创建独立的 McpServer,不在实例内保存客户端会话。code_search、start_test_run、get_task、query_logs 与 server_info 通过 Redis 保存真正需要恢复的任务、租约和幂等索引;双实例可在 NGINX 后轮询,实例退出后由租约接管恢复,OpenTelemetry 记录工具耗时、结果与失败率。它是面向代码检索和测试任务的专用执行平面,不替换上面的 17 工具兼容端点。
  • A2A Agent Mesh:每个本地 Agent 角色(orchestrator / researcher / coder / reasoner / critic)都有自己的 Agent Card(/.well-known/agent-card.json 做发现,GET /a2a/agents 列全部)与 JSON-RPC 任务生命周期:message/send 提交任务后台执行、message/stream 以 SSE 推送状态与 artifact chunks、tasks/resubscribe 按 afterChunkIndex 恢复订阅、tasks/get / tasks/cancel / tasks/list 管理任务。任务在角色的 capability 切片内执行(researcher 只有搜索面、reasoner 无工具),快照持久化到 .a2a/;A2AClient 可向 A2A_PEERS 里的外部 Agent 委派任务,examples/a2a_peer_demo.py 提供本地 external peer loopback。

上下文安全:Taint Tracking 与注入防火墙

  • Context Taint Tracking:每次请求组装完成后,prompt 按来源分段打信任标签——系统提示 / 用户输入 / 记忆为可信,网页搜索上下文、上传文件内容、外部工具结果为不可信——并对不可信段扫描三类指令:prompt 注入("ignore previous instructions" / "忽略上述指令"…)、密钥外泄(要求把 API Key 发送出去)、工具调用指令(资料里命令模型调用 forget_memory 等)。报告进 diagnostics.contextTaint,状态见 GET /api/taint。
  • 主动防御:搜索上下文与文件上下文前置确定性的「防注入隔离」声明并红action明确注入行(对 prompt cache 前缀稳定无损);工具调用参数中出现运行时自身凭证(DeepSeek / Tavily Key、本地 token)一律硬拒绝(secret_exfiltration_blocked);污染轮升级——本轮上下文检出注入指令后,高风险 / 敏感写入工具(fetch_url、forget_memory、suggest_memory、create_reminder)自动转为待人工确认,直到用户显式批准。

端云协同推理

  • 可选接入本地端侧模型(EDGE_INFERENCE_ENABLED=1 + llama-cpp-python 或 MLC-LLM 后端 + GGUF 路径):edgeMode=auto 把闲聊 / 概括 / 改写 / 翻译等短任务优先路由到本地模型,代码 / 数学 / 搜索 / 文档生成 / 多 Agent / 图片任务继续走云端。
  • 云端连接失败时简单任务可自动回退本地端侧模型;没有云端 API Key 但本地模型可用时,也能进行普通对话。
  • POST /api/edge/route-preview 可在不加载模型的情况下解释本轮会走端侧还是云端,并返回 reason 与当前 Edge 状态。

本地数据层与可观测性

  • 本地 RAG:.file-cache、.projects 和 .memory 同步进 .local-rag/rag.sqlite3,默认纯 SQLite + 哈希 embedding 零依赖;安装可选依赖后可启用 sqlite-vec 向量表与 ONNX Runtime 本地 embedding。
  • 链路追踪:每轮普通聊天、端侧推理和多 Agent DAG 都会生成 traceId 写入 .traces/,助手消息可打开 trace waterfall 查看各节点耗时、token 与 prompt cache 命中率;GET /trace/{trace_id} 提供独立只读瀑布页面,GET /api/traces/{trace_id}/export.json 导出脱敏 JSON;GET /metrics 聚合成 Prometheus 指标。
  • 语义缓存:无工具、无搜索、无附件的请求会在调用 DeepSeek 前查 .semantic-cache/,相似度达阈值时直接返回本地缓存结果。
  • API 网关韧性:Context Manager 稳定 system prompt 与工具定义前缀,最大化 DeepSeek Prefix Cache 命中;SQLite 请求队列在断网、超时、429 / 5xx 等可重试失败时退避重试,手机息屏或短暂断网后后台 Agent 工作流可等网络恢复再续跑。
  • 请求调度 / Backpressure / 限流:所有上游模型调用先过本地请求调度层——优先级队列(交互 > Agent worker > 后台)、并发上限、令牌桶限流与 backpressure(过载即快速 503 卸载而非无界堆积),耗尽重试 / 被卸载的请求落入持久化 Dead Letter Queue,启动时后台恢复上次崩溃残留的在途请求。默认对正常负载透明,可经 SCHEDULER_* 收紧。
  • Evaluation Harness(可评测):evals/ 提供 AI Runtime 回归评测 —— golden 数据集 + CLI runner 对 RAG Recall@K、引用准确率、工具策略、Prompt Injection 防御、Agent 录制回放、延迟与 token/USD 成本自动打分,评分核心是纯函数库 deepseek_infra/infra/evaluation/harness.py。CI 通过 run_offline_eval_suite.py --include-agent --strict 统一运行稳定离线的 RAG / Tool Policy / Prompt Injection adversarial / Agent Eval,写出 evals/reports/latest.json 与 latest.md;再用 compare_eval_baseline.py --strict 对照 v2.2.6 / agent-v2.2.8 baseline 阻断退化,并用 run_security_corpus.py --strict 输出版本化安全语料报告。

长期记忆 · Seek 助手

  • 用「记住:…」保存偏好 / 项目背景 / 长期任务,用「忘记 …」删除;模型也可在回答中提出记忆建议,需用户确认才写入。支持 global / project:<id> / seek:<id> 作用域与冲突检测;敏感内容会被拦截,不进入长期记忆(.memory/memories.json)。
  • Seek 助手:创建本地自定义助手(名称 / 指令 / 开场提示 / 参考文件),对话中自动注入;参考文件随消息快照保存。最多 40 个,支持导入 / 导出 JSON。

前端体验

  • PWA:manifest、图标和 Service Worker 齐全,可安装到手机桌面;支持 Share Target 从系统分享导入文章 / URL / 图片 / 文档。
  • 四种视觉风格(ChatGPT / Linear / Notion / Arc)× 浅色 / 深色 / 跟随系统,外加可选 Gemini 皮肤;Web Speech 语音输入与朗读、拖拽 / 粘贴上传、选区引用提问、草稿自动保存、本地提醒、命令面板(Ctrl/Cmd+K)与全局快捷键。后端不可用时进入离线模式,仍可查看 / 搜索本地历史。

OpenAI 兼容网关

把任意 OpenAI SDK 或工具的 base_url 指向本机 /v1 即可复用整套运行时。api_key 传本地访问 token(用于本地鉴权);上游 DeepSeek Key 由服务端配置(DEEPSEEK_API_KEY)提供。

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="<本地访问 token>")
resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer <本地访问 token>"
  • POST /v1/chat/completions:支持 stream 流式(标准 chat.completion.chunk SSE + [DONE])与非流式(chat.completion)。
  • GET /v1/models:列出可用模型(deepseek-v4-pro / deepseek-v4-flash)。
  • 多 Provider:启用 Ollama(OLLAMA_ENABLED=1)后,/v1/models 会额外列出 ollama/<本地模型>,请求该模型即走本地 Ollama;DeepSeek 专属的工具 / 搜索 / 多 Agent 仍只在 DeepSeek 模型上可用。
  • 完整字段见 docs/API.md。

Rust Gateway Sidecar

Rust Gateway sidecar(3.0.3 起)已迁移为独立文档:RAG 向量排序(JSON 与 f64le 二进制传输)、Gateway / MCP / RAG 请求准备委托、语义缓存二进制嵌入、Rust Policy、sidecar 性能基准与 Docker Compose 启动方式,详见 docs/RUST_GATEWAY_SIDECAR.md。

协议端点(MCP / A2A)

  • POST /mcp — MCP JSON-RPC 2.0 端点(本地 token 鉴权)。把 MCP 客户端的 Streamable HTTP server 地址指向它即可使用本地工具面;GET /api/mcp 查看 Hub 状态。

需要横向扩展、任务恢复和故障演练时,可使用独立的 无状态 MCP Server:官方 TypeScript SDK + Redis 持久任务/幂等索引 + 双实例 NGINX 轮询 + OpenTelemetry。现有 Python /mcp 保留为兼容端点。

  • GET /.well-known/agent-card.json — A2A 发现:orchestrator 的 Agent Card(仅元数据,不鉴权)。
  • GET /a2a/agents — 全部本地 Agent Card;POST /a2a 与 POST /a2a/agents/{agentId} — A2A JSON-RPC(message/send / message/stream / tasks/resubscribe / tasks/get / tasks/cancel / tasks/list,本地 token 鉴权)。
  • GET /api/taint — Context Taint 防火墙状态。

运维端点

  • GET /healthz — liveness:{status, version, runtime, provider, auth_enabled}(不鉴权)。
  • GET /readyz — readiness:本地存储可达性与上游 Key 配置状态(不鉴权)。
  • GET /metrics — Prometheus 文本:ai_requests_total、ai_agent_runs_total、ai_model_calls_total、ai_semantic_cache_hits_total、ai_tokens_total、ai_run_latency_ms_avg 等。默认随服务绑定在 127.0.0.1。

Benchmarks(基准与评测)

benchmarks/ 提供 4 个可复跑基准(均支持 --json)。下表离线两项是实测数字(逐次可复现),在线两项依赖你的网络与上游负载,给运行方式不给编造数字:

Benchmark 环境:Windows 11 · Python 3.13 · CPU Intel i7-13700H · RAM 16 GB · SSD · 数据集 95 chunks · runs 10 · warmup 2 · 报告 avg · 默认零依赖 hash embedding 路径

基准 关键结果(实测) 复跑命令
RAG 检索(离线) 95 chunks 索引 130 ms;检索 avg 20.2 ms · P95 21.7 ms;Recall@5 1.000 · MRR 0.917 python benchmarks/bench_rag_retrieval.py
语义缓存(离线) hash provider:store avg 17.9 ms · lookup avg 8.4 ms;精确命中 1.00 · 无关误命中 0.00;改写命中 0.00(hash 相似度约 0.80 < 阈值 0.95,保守不误答是预期行为)。ONNX provider 可用 --provider onnx 单独 benchmark 后再决定是否默认启用。 python benchmarks/bench_semantic_cache.py --provider hash
聊天延迟(在线) 流式 TTFT / 总延迟 avg·P50·P95、token 用量、语义缓存命中分布 python benchmarks/bench_chat_latency.py --n 3
Agent DAG(在线) 端到端延迟、每 Agent 耗时表、token 与估算成本 python benchmarks/bench_agent_dag.py

与之配套的质量评测在 evals/(全部离线可跑):python evals/runners/run_offline_eval_suite.py --include-agent --strict 会统一留下 latest eval report,当前 baseline 为 RAG Recall@5 1.000 / Citation Accuracy 0.8333、26 个固定攻防用例的 Tool Policy Pass Rate 1.000 / Prompt Injection Defense Pass 1.000,以及对抗注入小语料的 block_rate / false_positive_rate / bypass_rate 硬门禁;run_agent_eval.py --strict 额外生成 Agent Eval report,低于 Tool Call Accuracy 0.90 / Agent Success Rate 0.85 / Prompt Regression Pass Rate 0.90 会阻断 CI。run_security_corpus.py --strict 生成 Security Corpus report,覆盖 prompt injection、tool policy attack、benign false-positive、SSRF、路径越界与密钥外泄语料。详见 evals/README.md、docs/EVAL_REPORTS.md 与 docs/AGENT_EVAL.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.

快速开始

方式 1(推荐):本地桌面应用窗口

  1. 安装一次 Python 依赖:
    python -m pip install -r requirements.txt
    
  2. Windows 直接双击 launch.bat,macOS / Linux 双击或执行 ./launch.sh,会打开 DeepSeek Infra 本地应用窗口。
  3. 在应用右上角设置里填写 DeepSeek API Key(必填)和 Tavily API Key(可选);也可以先通过环境变量提供 Key。

桌面应用会自动使用带 desktop=1 的本地 token 入口完成认证,双击后不需要手动复制 token 链接;如果改用浏览器访问命令行服务,仍使用终端打印的 ?token=... 地址。需要手动选择端口、局域网模式或查看服务日志时,运行 python launch.py --gui 或 DeepSeekInfra.exe --gui(旧名 DeepSeekMobile.exe 继续兼容)打开旧 GUI 启动器。

方式 2:手机本机直接运行

Android 手机上可以用 Termux 或 Pydroid 这类 Python 环境直接跑后端,然后在同一台手机的浏览器里打开本机地址:

python -m pip install -r requirements-mobile.txt
python launch_mobile.py

也可以运行 python launch.py --mobile。手机启动器不会导入桌面 GUI 依赖,默认监听 127.0.0.1:8000,启动后会打印 Open on this phone 地址;如果环境里有 termux-open-url,会尝试自动打开浏览器。需要让同一局域网其它设备访问这台手机时,加 --lan 监听 0.0.0.0。

常用参数:

python launch_mobile.py --api-key "你的 DeepSeek API Key" --tavily-api-key "你的 Tavily API Key(可选)"
python launch_mobile.py --port 8010 --no-open
python launch_mobile.py --lan

方式 3:命令行启动(兼容旧用法)

cd D:\deepseek
python -m pip install -r requirements.txt
$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
$env:TAVILY_API_KEY="你的 Tavily API Key(可选,用于联网搜索)"
python app.py

macOS / Linux:

cd /path/to/deepseek
python -m pip install -r requirements.txt
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
export TAVILY_API_KEY="你的 Tavily API Key(可选,用于联网搜索)"
python app.py

也可以不设置环境变量,在页面右上角设置里临时填写 API Key。启动后终端会打印两个地址:Computer(电脑本机访问)和 Phone(手机访问,需与电脑在同一 Wi-Fi 或局域网)。

默认情况下所有 /api/* 请求都需要本地访问令牌,请使用终端打印的带 ?token=... 的地址打开应用,浏览器会自动保存认证 Cookie;桌面本地应用窗口会自动用 ?token=...&desktop=1 完成首屏认证。默认 token 会写入本地 .auth-token 并在重启后复用。

方式 4:打包成单个 exe 分发

需要把项目分发给完全没装 Python 的电脑时:

python -m pip install -r requirements.txt
python -m pip install -r requirements-build.txt
python scripts/build_exe.py

会在 dist/ 输出单个 DeepSeekInfra.exe(旧名 DeepSeekMobile.exe 以副本保留兼容;macOS / Linux 同)。双击默认打开本地应用窗口;运行期间产生的 .auth-token / .file-cache / .memory 等数据会写到 exe 同目录。旧启动器可通过 DeepSeekInfra.exe --gui 打开。

方式 5:打包成 Android APK

仓库内的 android/ Android Studio 工程可把现有 Python 后端和 Web 前端打进 APK。APK 启动后会在应用私有目录运行 Python 服务,并用内置 WebView 打开 127.0.0.1 本机地址,手机上无需再安装 Termux 或 Pydroid。

cd android
gradle :app:assembleDebug

输出位置:android/app/build/outputs/apk/debug/app-debug.apk。详细环境、签名和安装说明见 docs/APK.md。

方式 6:Docker / Compose 部署

cp .env.example .env   # 填写 DEEPSEEK_API_KEY 等
docker compose up -d
curl http://127.0.0.1:8000/healthz

镜像为 python:3.12-slim、非 root 运行、内置 /healthz HEALTHCHECK;全部运行时数据持久化在一个 /data 卷。详见 docs/DEPLOYMENT.md(含裸机 / systemd / 反向代理与安全边界)。

默认命令仍然只启动 Python。可选 Rust sidecar 使用 docker-compose.rust.yml,详见 Rust Hybrid Runtime Runbook。

独立无状态 MCP 双实例栈使用单独的 Compose 文件;PowerShell 下先设置随机 token,再启动:

$env:MCP_AUTH_TOKEN = '<replace-with-a-long-random-token>'
docker compose -f docker-compose.stateless-mcp.yml up -d --build

负载均衡入口为 http://127.0.0.1:8010/mcp,Collector Prometheus exporter 为 http://127.0.0.1:9464/metrics。Redis AOF 位于独立命名卷,不属于默认 /data 卷;部署、故障演练和备份边界见 docs/STATELESS_MCP.md。

环境变量

  • DEEPSEEK_API_KEY:DeepSeek API Key。可不填,改为在页面设置里临时输入。
  • TAVILY_API_KEY:Tavily 搜索 API Key。可不填,改为在页面设置里临时输入或选择保存到本机浏览器。
  • DEEPSEEK_API_URL / TAVILY_API_URL:可选的上游兼容接口地址;默认分别使用 DeepSeek 与 Tavily 官方接口。
  • PORT:本地服务起始端口,默认 8000。
  • HOST=0.0.0.0:开启局域网 / 手机访问;默认只监听 127.0.0.1。
  • DEEPSEEK_INFRA_ROOT=/path/to/data:推荐,指定数据根目录(替代 DEEPSEEK_MOBILE_ROOT)。
  • DEEPSEEK_MOBILE_ROOT=/path/to/data:向后兼容,与 DEEPSEEK_INFRA_ROOT 同时设置时后者优先。
  • DEEPSEEK_INFRA_STATIC_DIR=/path/to/static:推荐,指定静态资源目录(替代 DEEPSEEK_MOBILE_STATIC_DIR)。
  • DEEPSEEK_MOBILE_STATIC_DIR=/path/to/static:向后兼容,与 DEEPSEEK_INFRA_STATIC_DIR 同时设置时后者优先。
  • AUTH_DISABLED=1:关闭本地 token 鉴权,仅建议在可信开发环境使用。
  • AUTH_TOKEN=...:使用固定 token,便于本地测试。
  • AUTH_ALLOWED_HOSTS=host1,host2:追加允许的 Host 头名称。
  • OCR_ENABLED=1:默认允许 OCR;未开启时也可在上传失败后点击 OCR 重试。
  • OCR_MODE=fast|balanced|quality:本地 OCR 增强档位,默认 balanced。
  • OCR_PDF_DPI=300:扫描 PDF 渲染 DPI,限制在 150..450,默认 300。
  • OCR_MAX_IMAGE_PIXELS=16000000:OCR 前允许处理的最大图片像素数,超出会等比缩小。
  • OCR_FORMULA_CMD='pix2tex "{image}"':可选的本地公式 OCR 命令;未设置时会自动尝试 PATH 中的 pix2tex / latexocr。
  • OCR_FORMULA_TIMEOUT_SECONDS=120:公式 OCR 命令超时,限制在 5..600 秒。
  • DEEPSEEK_TIMEOUT_SECONDS:DeepSeek 同步、流式和上下文压缩请求的 socket idle 超时,默认 180。
  • MULTI_AGENT_TIMEOUT_SECONDS:多 Agent 并行层级超时,默认 3900;长任务建议与 DEEPSEEK_TIMEOUT_SECONDS 一起调高。
  • MULTI_AGENT_TOKEN_BUDGET:多 Agent 单次运行的 token 预算,默认 2000000,设 0 不限制。
  • TAVILY_TIMEOUT_SECONDS:Tavily 搜索请求超时,默认 45。
  • VITE_BACKEND_TARGET / VITE_DEV_SERVER_PORT:仅用于 npm run dev --prefix frontend,覆盖 Vite 开发代理目标与开发服务器端口;默认 http://127.0.0.1:8000 / 5173。
  • UPLOAD_FILE_MAX_BYTES / UPLOAD_MAX_BYTES:单文件 / 单次请求体上限,默认 200000000 / 220000000。
  • EDGE_INFERENCE_ENABLED=1 / EDGE_PROVIDER=llama_cpp(兼容 EDGE_INFERENCE_PROVIDER)/ EDGE_MODEL_PATH=/models/qwen2.5-1.5b-instruct-q4_k_m.gguf / EDGE_MODE=auto:可选的本地端侧推理最小配置,详见 docs/ARCHITECTURE.md。
  • OLLAMA_ENABLED=1 / OLLAMA_BASE_URL / OLLAMA_TIMEOUT_SECONDS:可选的本地 Ollama provider 开关、地址(默认 http://127.0.0.1:11434)与超时;启用后本地模型经 /v1 网关以 ollama/<tag> 暴露。
  • TOOL_POLICY_ENABLED=1(默认开)/ TOOL_POLICY_ENFORCE_SCHEMA / TOOL_POLICY_REQUIRE_CONFIRM / TOOL_POLICY_SANITIZE_RESULTS(默认开)/ TOOL_POLICY_AUDIT_ENABLED(默认开):Tool Policy Engine 开关——是否启用工具调用安全策略、是否把 schema 违例从告警升级为硬拒绝、是否对高风险工具强制人工确认、是否清洗工具结果中的 prompt injection、是否把每条策略决策写入 .tool-audit/audit.jsonl。
  • SCHEDULER_ENABLED=1(默认开)/ SCHEDULER_MAX_CONCURRENCY(默认 16)/ SCHEDULER_MAX_QUEUE_DEPTH(默认 256,backpressure 卸载阈值)/ SCHEDULER_RATE_PER_SECOND(默认 0=不限流)/ SCHEDULER_RATE_BURST / SCHEDULER_ACQUIRE_TIMEOUT_SECONDS(默认 30)/ SCHEDULER_DLQ_ENABLED(默认开)/ SCHEDULER_ORPHAN_SECONDS(默认 900):本地请求调度层——并发上限、队列深度(backpressure)、令牌桶限流速率与突发、准入超时、Dead Letter Queue 开关、启动时回收多久前的在途请求。
  • MCP_ENABLED=1(默认开)/ MCP_CAPABILITY=full(MCP 客户端获得的能力画像)/ MCP_EXPOSE_RESOURCES、MCP_EXPOSE_PROMPTS(默认开)/ MCP_CLIENT_ENABLED(默认关)/ MCP_CLIENT_SERVERS='[{"name":"docs","url":"http://127.0.0.1:9001/mcp","timeoutSeconds":10}]' / MCP_CLIENT_TIMEOUT_SECONDS(默认 30)/ MCP_CLIENT_MAX_RETRIES(默认 1)/ MCP_CLIENT_RETRY_BACKOFF_SECONDS(默认 0.25)/ MCP_CLIENT_CIRCUIT_BREAKER_FAILURES(默认 3)/ MCP_CLIENT_CIRCUIT_BREAKER_RESET_SECONDS(默认 60):MCP Tool Hub 与外接 MCP client。
  • 无状态 MCP 独立服务:MCP_AUTH_TOKEN(必改)、REDIS_URL、REDIS_PREFIX、MCP_ALLOWED_HOSTS、MCP_WORKSPACE_ROOT、MCP_INSTANCE_ID、MCP_TASK_LEASE_MS、MCP_TASK_POLL_MS、MCP_TASK_TIMEOUT_SECONDS、MCP_MAX_OUTPUT_BYTES 与 OTEL_EXPORTER_OTLP_ENDPOINT。这些变量不改变默认 Python /mcp。
  • A2A_ENABLED=1(默认开)/ A2A_DEFAULT_AGENT=reasoner / A2A_MAX_TASKS(默认 200)/ A2A_HISTORY_LIMIT(默认 20)/ A2A_PEERS=url1,url2(外部 A2A Agent 端点):A2A Agent Mesh。任务执行需要服务端 DEEPSEEK_API_KEY。
  • TAINT_ENABLED=1(默认开)/ TAINT_HARDEN_SEARCH_CONTEXT、TAINT_HARDEN_FILE_CONTEXT(默认开,给不可信上下文加隔离声明)/ TAINT_ESCALATE_CONFIRM(默认开,污染轮高危工具升级人工确认):Context Taint Tracking 与注入防火墙。

安装与依赖

requirements.txt 包含后端运行与文件解析所需的依赖,主要有:

  • openpyxl:读取 .xlsx;pypdf / PyMuPDF:读取 PDF 文字与逐页渲染。
  • python-pptx:生成 .pptx;reportlab:生成带内置中文字体的 PDF。
  • multipart:流式解析 multipart/form-data 上传;defusedxml:安全解析 .docx / .xlsx 内部 XML。
  • customtkinter:桌面 GUI 启动器依赖;手机本机运行改用 requirements-mobile.txt,无需安装这一项。
  • pywebview:桌面端本地应用窗口依赖,用系统 WebView 显示本机界面。

注意:正式依赖是 multipart>=1.3,<2。如果环境里同时装了占用同名命名空间的 python-multipart,上传接口会返回明确的依赖错误;请按 requirements.txt 重新安装。

可选依赖按需安装:requirements-ocr.txt(本地 OCR)、requirements-rag.txt(sqlite-vec / ONNX 本地 embedding)、requirements-edge.txt(llama-cpp-python 端侧推理)、requirements-build.txt(PyInstaller 打包)。

图片 OCR 优先用 DEEPSEEK_API_KEY 调 DeepSeek API 转写;API Key 缺失或识别不可用时,桌面端才回退本地 Tesseract / Windows OCR。扫描 PDF 需要 Poppler / pdftoppm 在 PATH 中;Android APK 用 ML Kit 作为本机兜底。

本地数据与隐私

主要数据都保存在本机:

  • 对话历史 / 未发送草稿 / 自定义 Seek:浏览器 localStorage。
  • 项目空间 / 文档库 / 保存项 / 产物索引 / 导出记录:.projects/{projectId}/。
  • 文件分块缓存:.file-cache;搜索缓存:.search-cache。
  • 本地 RAG 向量索引:.local-rag/rag.sqlite3。
  • 链路追踪:.traces/traces.sqlite3;语义缓存:.semantic-cache/cache.sqlite3。
  • 网关请求队列:.request-queue/queue.sqlite3;工具策略审计日志:.tool-audit/audit.jsonl;请求调度死信队列:.scheduler/scheduler.sqlite3。
  • 本地提醒队列:.reminders/reminders.json;长期记忆:.memory/memories.json。
  • 可恢复 Agent Run:.agent-runs/;A2A 任务快照:.a2a/。
  • 生成的文档产物(PPT / Word / PDF / 思维导图)与全局 Workspace 导出:.generated/。
  • API Key:DeepSeek / Tavily Key 可选择保存在浏览器,也可以只用服务端环境变量。

文件分块缓存会自动清理:默认保留 14 天内缓存并把 .file-cache 总量控制在约 500 MB;.projects/ 是持久 Workspace 数据,只在删除对应项目时移除,不会误删全局 .generated/、.memory/ 或其它项目。服务启动时清理一次,运行期间约每 6 小时后台清理一次。

.gitignore 默认排除运行期缓存、长期记忆、项目文档库、本地 RAG / Trace / 语义缓存 / 请求队列、生成文档产物、A2A 任务快照、提醒队列、覆盖率、IDE 配置和本地 server*.log。发布或提交前,请不要把 .file-cache、.projects、.local-rag、.traces、.semantic-cache、.request-queue、.generated、.tool-audit、.scheduler、.a2a、.budget、.memory、.reminders、.agent-runs、.search-cache 等本地数据打包进去。发布压缩包建议使用:

python scripts/release.py --clean-workspace

脚本会生成 dist/deepseek-infra-<version>.zip(旧名 deepseek-mobile-<version>.zip 以副本保留兼容),并排除本地缓存、日志、虚拟环境和 IDE 文件。

Roadmap

路线图已迁移为独立文档:ROADMAP.md。

The roadmap now lives in a standalone document: ROADMAP.en.md.

文档

所有人工维护的 Markdown 文档顶部都提供“中文 / English”入口;自动生成的证据、评测报告和 AGENTS.md 保持原样,避免破坏可复现证据或代理指令。

注意事项

手机浏览器可以直接使用 http://局域网IP:端口。如果要像正式 App 一样稳定安装到手机桌面,通常需要 HTTPS 部署;本地 HTTP 更适合开发和局域网试用。/metrics、/healthz、/readyz 默认不鉴权,请保持服务绑定在 127.0.0.1,或在局域网模式下用反向代理 / 防火墙限制访问。根作用域 PWA 缓存由 React 构建生成的 static/ui/sw-root.js 负责。

Yorumlar (0)

Sonuc bulunamadi