deepddw

🌐 English · 简体中文 这是中文说明。英文版见 README.md。

deepDDW 给 DeepSeek Harness（DSH）补齐三块拼图：记忆、知识库、文档搜索——而且全部支持局域网内任意设备访问。不用装 App，不改 DSH 一行源码。

• 🧠 记忆体 — 跨会话长期记忆，读写走 DSH 官方标准 MCP 接口
• 📚 知识库 — 文档入库与检索（行业资料、SOP、研究笔记）随时可查
• 🌐 局域网多设备 — 部署一次，手机/平板/笔记本同网可用，共用同一个 DSH 工作台

60 秒上手：

npm i -g @deepseek-ai/dsh              # 1. 服务器安装官方 DSH
git clone https://github.com/ccch713/deepddw.git && cd deepddw
./install.sh --with-dsh                # 2. 安装 deepDDW
./install.sh --port 8600               # 3. 启动
# 4. 局域网任意设备打开 http://<服务器IP>:8600/（手机扫码自动配对）

📸 截图位：手机/平板访问工作台实拍（稍后补充）。

当前状态：v0.5.0 · MIT · CI（pytest + ruff）✅ · DSH for Teams —— 多用户、局域网多设备、记忆与知识库团队蒸馏 · 入选 awesome-deepseek-harness · 路线图见文末

⚠️ 重要 —— 安装前必读

deepDDW 实现了独立的记忆体与知识库隔离机制。为避免冲突或记忆混乱，安装前请务必：

1. 备份你现有的记忆体与知识库内容（无论它们在 DSH 环境中的哪个位置）；
2. 卸载/停用你已安装的其他任何记忆体或知识库插件；
3. 然后再安装 deepDDW，让它接管记忆体与知识库。

如果 deepDDW 与其他记忆/知识库插件同时运行，可能导致数据冲突或命名空间之间的记忆混淆。特此警告。⚠️

---

为什么用 deepDDW？

大多数 DSH 扩展只提供记忆。deepDDW 是完整的工作台——记忆 + 知识库 + 文档检索 + 局域网多设备访问：

官方 DSH 的限制	deepDDW 的解法
🔒 仅本机可用	✅ 局域网内任意设备访问：服务器部署后，电脑、笔记本、手机、平板，同一个网络内的智能设备全部可用
🧠 无记忆体	✅ 长期记忆写入/检索，对话经验可沉淀
📚 无知识库	✅ 知识库检索/入库，行业文档、SOP、研究笔记随时调用

一句话：把"个人玩具"变成"小组织能用的工具"——整体封装、简便部署、降低运维成本，让小型商业组织部署即可使用，基本可以支撑 20 人以下企业的日常 AI 工作流。

deepDDW 由我们的 DDW AI HUB 平台沉淀而来——经过企业级部署验证，以开源（MIT）形式封装进 DSH 生态。

---

它怎么工作？（技术线路）

📱 手机 / 💻 电脑 / 📱 平板 / 🖥️ 笔记本 —— 局域网内任意设备
   │                    （浏览器访问，无需安装 App）
   ▼
deepDDW 网关（局域网内一台服务器）
   ├─ /dsh/*   反代 → DSH 引擎（官方原版界面，模型配置/对话全原版）
   ├─ /api/*   反代 → DSH 的 RPC/API
   └─ /api/v1/*  deepDDW 能力：知识库 / 记忆体 / 文档 / LLM 配置
        │
        │  DSH 官方 MCP 客户端（streamable-http）
        ▼
deepDDW MCP 工具（模型自动调用）
   ├─ mcp__deepddw__ddw_kb_search        知识库检索
   ├─ mcp__deepddw__ddw_memory_put       写入记忆
   ├─ mcp__deepddw__ddw_memory_search    检索记忆
   └─ mcp__deepddw__ddw_docs_portal_search  文档检索

接入方式 = DSH 标准 MCP：DSH 原生支持 MCP 客户端，deepDDW 暴露标准 streamable-http 端点——零侵入、不改 DSH 一行源码，界面、设置、模型配置全部保持官方原版。

---

为什么你在局域网内能用？

DSH 官方出于安全考虑只监听本机（localhost），手机/平板根本连不上。deepDDW 通过网关反代解决了这个矛盾：

• DSH 保持安全的本机绑定（官方安全设计不被破坏）
• deepDDW 网关统一对外，局域网内任意设备访问 http://<服务器IP>:8600/ 即进入 DSH 原版工作台
• 数据全部存储在你自己的服务器上，不出内网

部署一台，全家/全团队可用——这是官方 DSH 给不了的能力。

---

快速开始

# 1. 在服务器上安装 DSH（官方）
npm i -g @deepseek-ai/dsh

# 2. 安装 deepDDW（整体封装，一条命令）
git clone https://github.com/ccch713/deepddw.git
cd deepddw && ./install.sh --with-dsh

# 3. 启动
./install.sh --port 8600

# 4. 局域网内任意设备打开：
#    http://<服务器IP>:8600/   → DSH 原版工作台
#    手机/平板可"添加到主屏幕"获得 App 体验

# 5. 在 DSH「设置 → 模型」填 API Key
# 6. 对话里让模型"搜索知识库"或"记住 xxx" → 自动调用 mcp__deepddw__* 工具

部署门槛：一台普通电脑/服务器（最低 8GB 内存，推荐 16GB 及以上），Python 3.11+，无 GPU 要求（LLM 走云端 API 或本机 Ollama）。

---

局域网多设备联机（0.2.0）

deepDDW 面向局域网内最多 20 台设备共享一个网关的场景：

• 设备身份：每台浏览器在 localStorage 持久化 device_id，启动页可设置设备名称；重连后身份不变（刷新/重启仍是同一台设备）。
• 在线状态：设备向网关注册/心跳；/api/v1/status（Token 保护）返回谁在线、活跃 WebSocket 数、请求计数、数据库大小与版本；启动页为管理员渲染实时状态卡片。
• 网关限流：滑动窗口，按 Token + 按 IP 双维度（默认 60 req/min/token，全网关总容量耗尽 → 503 过载保护）；可通过 config/deployment.yaml 的 security.rate_limit.* 或 DDW_RATE_LIMIT_* 环境变量覆盖。
• SQLite 并发加固：所有连接统一 WAL + busy_timeout=5000 + synchronous=NORMAL，跨表写事务走进程级写锁（已用 20 并发写验证，无 database is locked）。

POST /api/v1/device/register    # 注册/改名本设备（幂等）
POST /api/v1/device/heartbeat   # 心跳保活
GET  /api/v1/status             # 状态面板（需 Token）

0.2.0 还包含：

• 工作区隔离 — 设备可选工作区（默认 shared）；记忆/日志与 MCP 记忆工具按工作区隔离，文档按 slug 前缀过滤；旧客户端零影响。
• 会话跨设备续接 — 最近会话摘要（最多 5 条）+ "继续此会话"按钮：手机接着电脑端会话继续聊。
• 一键备份 / 恢复 — API 一键备份可下载；恢复前校验 SQLite 文件（文件头 + 完整性检查），替换主库前自动备份现状为 .pre-restore。
• 可选 TLS — 一键自签证书（scripts/gen_self_signed_cert.sh，1 年有效），security.tls.* 启用即可 HTTPS 访问；默认关闭不影响 HTTP。外网访问推荐 Caddy/Nginx 反代（见 docs/tls.md）。
• 版本 / 升级检查 — /api/v1/version 返回最新版与升级标记（GitHub 探测，1h 缓存，离线降级）；启动页显示升级横幅。

---

安全与隐私

能力	说明
🔐 数据全本地	知识库/记忆存自己的服务器，不出内网
🏠 局域网免密	可选项，默认关闭：内网请求免 Token（开启需 DDW_LAN_BYPASS=1，仅建议可信内网）
🌐 外网访问	可配 Token 门禁（支持短码），未授权一律 401
🛡️ DSH 安全绑定	DSH 只监听本机，网关统一对外，不破坏官方安全设计

---

技术栈与许可

组件	说明	许可
DSH 引擎	DeepSeek Harness 官方原版（不改源码）	MIT
deepDDW 网关	FastAPI + SQLite + MCP 双协议	MIT
记忆/知识库	SQLite 存储（可接 agentmemory / 向量）	MIT
搜索	可选 SearXNG	AGPL-3.0（服务端调用豁免）

deepDDW 本体：MIT License — 自由使用、修改、商用，保留版权声明即可。

---

生态与反馈

• 官方插件扩展：deepDDW 保留 DSH 原生插件机制。您可通过 DSH 官方命令从 npm 官方仓库安装官方插件——这也是我们推荐的唯一渠道，以最大程度避免供应链投毒：

  dsh plugin --profile web add <npm包名>   # 仅官方 npm 仓库
  

  第三方插件的安全责任由用户自行查验；deepDDW 仅保障记忆体与知识库的代码完整与安全，不窃取/不利用/不贩卖用户数据。详见 SECURITY.md。
• 知识蒸馏：我们建议您使用适合自己的知识蒸馏 skill / 工作流来沉淀知识——蒸馏方法论由您选择，deepDDW 提供"蒸馏产物 → 可检索知识库 → 模型可用"的完整管道；更多插件与工具正在扩展中
• 记忆/知识移植：知识库为标准 SQLite 结构，记忆按 namespace/key/value 组织——可从其他 Agent 或工具导出移植
• 反馈：非常欢迎您留下宝贵的使用反馈，我们将在后续版本中提供更强大的开源工具

---

Roadmap

只列出已交付或真实在计划内的事项。

已交付：

• 局域网多设备联机（0.2.0） — 设备身份/在线注册表、状态面板、网关限流、SQLite WAL 并发（最多 20 台设备）
• 工作区隔离（P1-1） — 网关层按工作区隔离记忆/知识库（默认 shared，向后兼容）
• 会话跨设备续接（P1-3） — "最近会话"摘要（最多 5 条）+ 继续按钮
• 可选 TLS（P1-2） — 一键自签证书；外网访问 Caddy/Nginx 反代（见 docs/tls.md）
• 备份 / 恢复 API（P2-1） — 一键备份可下载；恢复先校验，替换前自动备份现状 .pre-restore
• 压测报告（P2-2） — 5/10/20 设备：0 错误，P95 ≤ 126ms，无 database is locked（见 docs/load-report.md）
• 版本 / 升级检查（P2-3） — /api/v1/version 探测最新 Release（1h 缓存）；启动页升级横幅
• Docker 一键部署 — docker compose -f deepddw-compose.yml up -d --build（已在真实 macOS arm64 主机验证：core + SearXNG 容器启动、health/MCP/chat 端到端全绿）
• 会话 → 文档沉淀 — 对话经 ddw.docs.save / ddw.session.docs MCP 工具 + REST API 保存到知识库，按会话可检索可追溯
• 知识库向量检索增强 — 混合检索（SQLite FTS5/LIKE + LanceDB，RRF 融合；可选，无 LanceDB 时自动降级纯关键词）
• Windows 打包 — windows-build CI 工作流 PyInstaller one-dir 自动出包，以 Actions 产物分发，v0.1.0 发布已验证（见 docs/windows-packaging.md）
• 反思与沉淀（LLM 化收尾） — 每日反思按风格指南（自动/专业/随意）生成、强制"进展/问题/明日注意"结构并避免与昨日重复；LLM 判定对话无价值时不再落日志
• 记忆检索质量 — 结果按相关性评分排序（命中数×层权重：用户规则优先于旧日志，近期日志加权），取代原插入序；扩写缓存过期行为已测试

---

deepDDW — 企业级底座能力，开源给每个人。