# DeepTutor：終身個人化學習導師

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](../../LICENSE) [![GitHub release](https://img.shields.io/github/v/release/HKUDS/DeepTutor?style=flat-square&color=brightgreen)](https://github.com/HKUDS/DeepTutor/releases) [![arXiv](https://img.shields.io/badge/arXiv-2604.26962-b31b1b?style=flat-square&logo=arxiv&logoColor=white)](https://arxiv.org/abs/2604.26962) [![Discord](https://img.shields.io/badge/Discord-Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/eRsjPgMU4t) [![Feishu](https://img.shields.io/badge/Feishu-Group-00D4AA?style=flat-square&logo=feishu&logoColor=white)](../../Communication.md) [![WeChat](https://img.shields.io/badge/WeChat-Group-07C160?style=flat-square&logo=wechat&logoColor=white)](https://github.com/HKUDS/DeepTutor/issues/78) [主要功能](#-主要功能) · [開始使用](#-開始使用) · [探索](#-探索-deeptutor) · [CLI](#️-deeptutor-cli--代理程式原生介面) · [生態系](#-生態系--eduhub-與技能社群) · [社群](#-社群)

--- > 🤝 **我們歡迎任何形式的貢獻！** 歡迎在 [`Roadmap`](https://github.com/HKUDS/DeepTutor/issues/498) 為規劃項目投票或提出新構想，並參閱[貢獻指南](../../CONTRIBUTING.md)，了解分支策略、程式碼規範與參與方式。 ### 📰 最新消息 - **2026-05-22** 🌐 官方文件網站 [**deeptutor.info**](https://deeptutor.info/) 正式上線 — 指南、參考資料與能力導覽集中在同一處。 - **2026-04-19** 🎉 111 天內突破 2 萬顆 Star！感謝大家對真正個人化智慧教學的支持。 - **2026-04-10** 📄 論文已登上 arXiv — 閱讀[預印本](https://arxiv.org/abs/2604.26962)，了解 DeepTutor 背後的設計與理念。 - **2026-02-06** 🚀 僅 39 天便突破 1 萬顆 Star！衷心感謝傑出的社群。 - **2026-01-01** 🎊 新年快樂！加入我們的 [Discord](https://discord.gg/eRsjPgMU4t)、[WeChat](https://github.com/HKUDS/DeepTutor/issues/78) 或 [Discussions](https://github.com/HKUDS/DeepTutor/discussions) — 一起塑造 DeepTutor。 - **2025-12-29** 🎓 DeepTutor 正式發布！ ## ✨ 主要功能 DeepTutor 是代理程式原生的學習工作區，在同一個可擴充系統中串聯教學、解題、測驗生成、研究、視覺化與精熟練習。 - **所有模式共用一套執行階段** — Chat、Ask Questions、Quiz、Research、Visualize、Solve、Course Study、Mastery Path、Immersive Reading 與 Immersive Watching 共用同一套能力執行階段與工作階段情境，同時保有針對各自用途設計的迴圈與管線。 - **相互連結的學習情境** — 知識庫、書籍、Co-Writer 草稿、筆記本、題庫、角色設定與 Memory 可在支援這些內容的工作流程中重複使用，但仍受帳號授權與學習政策限制。 - **沉浸式影片學習** — 貼上 YouTube 連結，即可使用隱私強化的原生播放、同步字幕、以時間戳為依據的教學，以及可續接的學習進度；管理員也能將播放切換至自架的 Invidious 執行個體，無須重新建立素材。 - **子代理程式與 Partners** — 可從 Chat 諮詢即時代理程式執行框架（Claude Code、Codex、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw 或 DeepSeek）或 Partner、匯入過往對話，並讓持續運作的 IM 夥伴共用同一套核心。 - **多引擎知識系統** — 透過 LlamaIndex、PageIndex、GraphRAG、LightRAG、遠端 LightRAG Server、自架 WeKnora 知識庫、Tencent IMA 或 MarginNote 4 知識庫，或連結的 Obsidian vault 建立版本化 RAG 知識庫，並支援可插拔的文件解析。 - **可擴充的工具與技能** — 內建工具、MCP 伺服器、CLI 應用程式、影像／影片／語音生成模型，以及可從 EduHub 安裝的社群技能。 - **可檢視的記憶** — L1 軌跡、L2 介面摘要與 L3 綜整讓個人化內容透明且可編輯；Memory Graph 會將 L2 事實連結至 L1 證據，並將 L3 綜整連結至其貢獻來源介面。 --- ## 🚀 開始使用 DeepTutor 提供四種安裝方式，皆共用同一套執行環境目錄配置：私有設定會儲存在啟動目錄下的 `data/user/settings/`（若明確設定 `DEEPTUTOR_HOME` 或 `deeptutor start --home`，則改儲存在該位置）。完整應用程式的建議流程是：**選擇一個執行環境目錄 → 安裝 → `deeptutor init` → `deeptutor start`**。 ### 內容工作區 **內容工作區（Content Workspace）**與 DeepTutor 的私有執行環境目錄是分開的。這是代理程式可以讀取的資料夾，凡是代理程式建立的檔案、下載內容、程式碼執行結果、快取與生成的素材，都會放在依回合區分的 `outputs////` 目錄下。Settings、API key、資料庫、Memory 與內部應用程式狀態則都不在此範圍內。在未經設定的情況下，內容工作區位於 `<執行環境目錄>/data/user/workspace`。本機的 PyPI、CLI 與原始碼安裝，皆可在 **Settings → Workspace** 或以下列指令，選擇任何現有且可讀寫的資料夾： ```bash deeptutor workspace show deeptutor workspace set /absolute/path/to/my-folder deeptutor workspace reset ``` 每項能力都能透過內建的 workspace 工具檢視同一個資料夾。模型只會收到 `outputs/...` 之類的相對路徑；當它使用 `workspace_present` 時，UI 會顯示一個已驗證身分、可開啟的快照。同一組相對路徑，在一般的 Markdown 連結或圖片中也同樣可用。日後變更來源檔案，並不會改變已呈現的快照。在 `outputs/` 之外，執行動作一律唯讀。若要將生成的檔案複製到內容工作區中的其他位置，必須針對該確切的來源與目的地，明確以 **Allow once** 確認。系統沙箱或 Docker runner（若可用）會強制執行此邊界；本機受限制的子處理程序備援方式，則會在 Workspace 設定中顯示為**盡力而為（best effort）**。

方式一 — 從 PyPI 安裝 · 完整本機 Web 應用程式＋CLI，無須 clone

完整本機 Web 應用程式＋CLI，無須 clone。需要 **Python 3.11–3.14**，且 PATH 中須有 **Node.js 20+** 執行階段（`deeptutor start` 會啟動套件內的 Next.js standalone 伺服器）。 ```bash mkdir -p my-deeptutor && cd my-deeptutor pip install -U deeptutor deeptutor init # prompts for ports + LLM provider + optional embedding/search deeptutor start # starts backend + frontend; keep the terminal open ``` `deeptutor init` 會引導你設定後端連接埠（預設 `8001`）、前端連接埠（預設 `3782`）、LLM 供應商／Base URL／API key／模型、Knowledge Base／RAG 選用的 embedding 供應商，以及 Web Search 選用的搜尋供應商。執行 `deeptutor start` 後，開啟終端機顯示的前端 URL；預設為 [http://127.0.0.1:3782](http://127.0.0.1:3782)。在該終端機按下 `Ctrl+C`，即可同時停止後端與前端。若只是快速試用，也可以略過 `deeptutor init`；應用程式會以預設連接埠與空白模型設定啟動，之後再到 **Settings → Models** 設定即可。

方式二 — 從原始碼安裝 · 針對 checkout 進行開發

適合針對原始碼 checkout 進行開發。請使用 **Python 3.11–3.14** 與 **Node.js 22 LTS**，以符合 CI 和 Docker 環境。 ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # Create a venv (macOS/Linux). Windows PowerShell: # py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1 python3 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip # Install backend + frontend deps python -m pip install -e . ( cd web && npm ci --legacy-peer-deps ) deeptutor init deeptutor start --dev ``` `deeptutor start` 會先為本機 `web/` 前端建立一次正式環境版本，之後重複使用；`--dev` 則會以 HMR 執行 Next.js。設定配置、連接埠與 `Ctrl+C` 停止方式皆與方式一相同。

Conda 環境（取代 venv）

```bash conda create -n deeptutor python=3.11 conda activate deeptutor python -m pip install --upgrade pip ```

選用的額外安裝項目 — RAG 引擎／dev／partners／matrix／math-animator

```bash pip install -e ".[rag-lightrag]" # Built-in LightRAG engine (exact supported SDK) pip install -e ".[graphrag]" # Microsoft GraphRAG engine (Python 3.11–3.13) pip install -e ".[dev]" # tests/lint tools pip install -e ".[partners]" # Partner IM channel SDKs pip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs pip install -e ".[matrix]" # Matrix channel without E2EE/libolm pip install -e ".[matrix-e2e]" # Matrix E2EE; requires libolm pip install -e ".[math-animator]" # Manim addon; requires LaTeX/ffmpeg/system libs ```

調整前端相依套件與開發伺服器疑難排解

**變更前端相依套件：** 執行 `npm install --legacy-peer-deps` 以更新 `web/package-lock.json`，接著同時提交 `web/package.json` 與 `web/package-lock.json`。 **開發伺服器卡住：** 若 `deeptutor start --dev` 回報已有前端處理程序但該處理程序沒有回應，請停止訊息中顯示的 PID。若實際上並無 Next.js 處理程序執行，代表 lock 檔已過期；移除後再試一次： ```bash rm -f web/.next/dev/lock web/.next/lock deeptutor start --dev ```

方式三 — Docker · 單一自足式容器

以單一容器執行完整 Web 應用程式。映像檔位於 GitHub Container Registry： - `ghcr.io/hkuds/deeptutor:latest` — 最新穩定版本 - `ghcr.io/hkuds/deeptutor:` — 不含開頭 `v` 的確切版本（例如 `:1.6.3`）；預先發行版本只會提供其版本標籤 > 如需 podman／rootless／唯讀 rootfs 部署及各安裝方式的完整指南，請參閱 [CONTAINERIZATION.md](../../CONTAINERIZATION.md)。 ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` 若要在容器啟動時選擇主機端的內容資料夾，請將它掛載到固定的容器路徑，並把 DeepTutor 鎖定到該路徑： ```bash mkdir -p "$PWD/deeptutor-workspace/outputs" docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ -v "$PWD/deeptutor-workspace:/workspace" \ -e DEEPTUTOR_WORKSPACE_ROOT=/workspace \ -e DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS=/workspace \ ghcr.io/hkuds/deeptutor:latest ``` 若使用 Compose，請在執行 `python scripts/docker_compose.py up -d` 前設定 `DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder`；未設定時預設為 `./data/user/workspace`。Docker 的路徑於啟動時即已選定，因此會在 Web 設定頁面中顯示為鎖定狀態。 > **只需要發布 `3782`。** 瀏覽器只會與前端 origin 通訊；Next.js middleware（`web/proxy.ts`）會將 `/api/*` 與 `/ws/*` 轉送到容器**內部**的 FastAPI 後端。發布 `8001`（`-p 127.0.0.1:8001:8001`）並非必要；只有在你想直接以 curl 或指令碼呼叫 API 時才方便。開啟 [http://127.0.0.1:3782](http://127.0.0.1:3782)。容器會在首次啟動時建立 `/app/data/user/settings/*.json`；請從 Web 設定頁面設定模型供應商。設定、API key、記錄、預設的內容工作區、記憶與知識庫都會保留在 `deeptutor-data` volume 中；另行掛載的內容工作區則會保留在其主機路徑上。選用的額外套件應設定在部署層級，而不是在 shell 裡：設定 `DEEPTUTOR_EXTRAS`（系統函式庫則另設 `DEEPTUTOR_APT_PACKAGES`），由它啟動的每個容器都會重新套用；相較之下，`docker exec … pip install` 這類做法會在下一次 `compose down` 時消失。 - **不同的主機連接埠：** 變更各 `-p host:container` 對應左側的值（例如 `-p 127.0.0.1:8088:3782`）。若你在 `/app/data/user/settings/system.json` 變更容器側連接埠，請重新啟動，並同步更新各對應右側的值。 - **背景執行：** 加上 `-d`；接著以 `docker logs -f deeptutor` 查看記錄、`docker stop deeptutor` 停止，並在重複使用名稱前執行 `docker rm deeptutor`。`deeptutor-data` volume 會在重新啟動後保留私有的執行階段資料與預設的內容工作區；另行掛載的內容工作區則會保留在其主機路徑上。 **遠端 Docker／反向代理：** 瀏覽器只會與前端 origin（`:3782`）通訊；容器內的 Next.js middleware 會在伺服器端將 `/api/*` 與 `/ws/*` 轉送到後端。在常見的單容器情境中，完全不必設定 API base，只要將反向代理／TLS terminator 指向 `:3782`。只有在**拆分部署**（後端位於其他容器／主機）時才需要 API base：將 `data/user/settings/system.json` 中的 `next_public_api_base` 設為前端伺服器用來連接後端的網路內位址（此值只在伺服器端讀取，不會傳送至瀏覽器）。 ```json { "next_public_api_base": "http://backend:8001" } ``` `next_public_api_base_external`（及其別名 `public_api_base`）可作為優先順序較低的備援值。CORS 使用前端 **origin**，而不是 API URL。停用驗證時，DeepTutor 預設允許一般 HTTP／HTTPS 瀏覽器 origin；啟用驗證時，請加入精確的前端 origin： ```json { "cors_origins": ["https://deeptutor.example.com"] } ```

連接主機上的 Ollama／LM Studio／llama.cpp／vLLM／Lemonade

在 Docker 內，`localhost` 指的是容器本身，而不是主機。若要連接主機上執行的模型服務，請使用 host gateway（建議方式）： ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \ --add-host=host.docker.internal:host-gateway \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` 接著在 **Settings → Models** 中，將供應商 Base URL 指向 `host.docker.internal`： - Ollama LLM：`http://host.docker.internal:11434/v1` - Ollama embedding：`http://host.docker.internal:11434/api/embed` - LM Studio：`http://host.docker.internal:1234/v1` - llama.cpp：`http://host.docker.internal:8080/v1` - Lemonade：`http://host.docker.internal:13305/api/v1` Docker Desktop（macOS／Windows）通常不加 `--add-host` 也能解析 `host.docker.internal`。在 Linux 上，此旗標是在現代 Docker Engine 建立該主機名稱的可攜方式。 **Linux 替代方案 — host networking：** 加上 `--network=host` 並移除 `-p` 旗標。容器會直接共用主機網路，因此請開啟 [http://127.0.0.1:3782](http://127.0.0.1:3782)（或 `system.json` 中的 `frontend_port`），並以一般 localhost URL（例如 `http://127.0.0.1:11434/v1`）連接主機服務。請注意，host networking 會直接在主機上公開容器連接埠，且可能與既有服務衝突；若要讓它們維持在 loopback，請設定 `BACKEND_HOST=127.0.0.1` 與 `FRONTEND_HOST=127.0.0.1`（參閱 [CONTAINERIZATION.md](../../CONTAINERIZATION.md)）。

方式四 — 僅使用 CLI · 無 Web UI，從原始碼 checkout 安裝

適合不需要 Web UI 的情境。僅含 CLI 的套件須從原始碼 checkout 安裝，而不是從 PyPI 安裝。 ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # Create a venv (macOS/Linux). Windows PowerShell: # py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1 python3 -m venv .venv-cli && source .venv-cli/bin/activate python -m pip install --upgrade pip python -m pip install -e ./packaging/deeptutor-cli deeptutor init --cli deeptutor chat ``` `deeptutor init --cli` 與完整應用程式共用相同的 `data/user/settings/` 配置，但會略過後端／前端連接埠提示。它仍會提供 Embedding 與 Search 選擇器（不需要時請選擇 **Skip**）、寫入主要的執行階段檔案（`system.json`、`auth.json`、`integrations.json`、`interface.json`、`model_catalog.json`、`main.yaml`、`agents.yaml`），並會詢問目前使用的 LLM 供應商與模型。

常用指令

```bash deeptutor chat # interactive REPL deeptutor chat --capability deep_solve --tool rag --kb my-kb deeptutor run chat "Explain Fourier transform" deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb deeptutor kb create my-kb --doc textbook.pdf deeptutor memory show deeptutor config show ```

本機 `deeptutor-cli` 安裝不含 Web 資源或伺服器相依套件。請保留原始碼 checkout，因為 editable install 會指向該處。若之後要加入 Web 應用程式，請安裝 PyPI 套件（方式一），並從相同工作區執行 `deeptutor init` 與 `deeptutor start`。

程式碼執行沙箱（office skills） · 執行模型為 docx／pdf／pptx／xlsx 產生的程式碼

內建的 office skills（**docx／pdf／pptx／xlsx**）會讓模型撰寫一段簡短的 Python 指令碼（`python-docx`、`reportlab`、`openpyxl` 等），透過唯一的 `exec` 工具執行，再提供下載 URL。只要有啟用中的沙箱後端，該工具就會掛載。DeepTutor 會依下列順序選用已設定的最強後端： - **Runner sidecar：** `DEEPTUTOR_SANDBOX_RUNNER_URL` 會將執行工作導向 `Dockerfile.runner` 所提供、經過強化且採最低權限的服務。 - **Linux bubblewrap：** 若可使用 `bwrap`，它會隔離處理程序與檔案。 - **受限制的子處理程序備援：** 本機與單一容器安裝只會在允許時採用此方式；在 Docker 下，容器本身仍是另一層隔離邊界。 `data/user/settings/system.json` 中的 `sandbox_allow_subprocess` 設定（預設 `true`）只控制最後一種備援方式。將其設為 `false`（或匯出 `DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0`），即可在沒有 runner 或 `bwrap` 後端時拒絕子處理程序執行；這不會停用前述較強的後端。

設定參考 — data/user/settings/ 下的設定檔（JSON／YAML）

`data/user/settings/` 下的內容都是純 JSON／YAML。建議使用瀏覽器中的 **Settings** 頁面進行編輯。 | 檔案 | 用途 | |:---|:---| | `model_catalog.json` | 供應商連線，以及 LLM、任務、embedding、搜尋、TTS、STT、影像與影片設定檔、憑證和目前選用項目 | | `system.json` | 後端／前端連接埠、公開 API base、CORS、SSL 驗證、附件目錄與上傳／擷取限制 | | `auth.json` | 選用的驗證開關、使用者名稱、密碼雜湊、token／cookie 設定 | | `integrations.json` | 選用的 PocketBase 與 sidecar 整合設定 | | `interface.json` | UI 與模型輸出語言／主題／側邊欄偏好設定 | | `content_workspace.json` | 內容工作區的資料夾綁定，以及目前使用中的工作區選擇 | | `video_learning.json` | 預設 YouTube／Invidious 播放供應商、Invidious 來源與選用的逐字稿介面卡 | | `main.yaml` | 執行階段行為預設值與路徑注入 | | `agents.yaml` | 能力／工具的 temperature 與 token 設定 | Web Search 參考來源預設會經過篩選：只會顯示未內嵌憑證、未使用異常連接埠的公開 `http`／`https` URL。部署環境可以在 `data/user/settings/system.json` 中加入以教育為導向的網域政策： ```json { "web_search_source_filtering": { "enabled": true, "blocked_domains": ["spam.example"], "trusted_domains": ["edu.cn", "arxiv.org"] } } ``` 當 `trusted_domains` 非空時，參考來源只限於這些網域及其子網域；`blocked_domains` 一律優先。專案根目錄的 `.env` **不會**被讀取為應用程式設定檔。若只需最基本的模型設定，請開啟 **Settings → Models**、加入 LLM 設定檔（Base URL／API key／模型名稱）並儲存。只有在打算使用 Knowledge Base／RAG 功能時才需要加入 embedding 設定檔。當供應商支援選擇時，LLM 與任務模型設定檔會提供 **API format** 設定。一般路由與備援請保留 `Auto`，也可以選擇 `OpenAI Chat Completions`、`OpenAI Responses` 或 `Anthropic Messages`；強制使用 Responses 時仍採用失敗即停止（fail-closed）策略。持久化欄位為 `api_format`（`auto`、`openai_chat`、`openai_responses` 或 `anthropic`）；`wire_api` 則是由此衍生出的相容性狀態。每個模型可個別以 `Auto`／`Supported`／`Not supported` 覆寫工具呼叫、影像輸入、JSON 輸出與推理控制等能力。

解除安裝與清理

DeepTutor 會將已安裝的程式碼、私有執行環境目錄與選用的內容工作區分開管理。預設情況下，執行環境目錄就是你執行 `deeptutor init`／`deeptutor start` 的目錄；`--home PATH` 或 `DEEPTUTOR_HOME` 可覆寫此位置。私有應用程式狀態位於該目錄內的 `data` 子目錄，因此啟動橫幅中以 `Workspace:` 開頭的那一行，指出的就是這個執行環境位置。若 **Settings → Workspace** 指向其他資料夾，請另行備份或移除該內容資料夾；解除安裝 DeepTutor 並不會清除它，這是刻意的設計。 1. 停止應用程式。在執行 `deeptutor start` 的終端機按下 `Ctrl+C`；若 launcher 是以 `--detach` 啟動，請執行 `deeptutor stop [--home PATH]`。刪除資料前，也請停止所有執行中的 Partner 與 detached Docker 容器。 2. 只有在你也想清除所有本機狀態時，才移除執行階段資料。這包括設定與 API key、聊天記錄、工作階段、Memory、Notebooks、Books、Reading 狀態、Skills、Partners 狀態、記錄、Knowledge Bases、解析快取、生成的產物，以及套件化前端的執行階段快取。請先從啟動橫幅複製完整的 `Workspace:` 路徑，確認其 `data` 子目錄確實是預期的 DeepTutor 資料目錄。如日後可能需要其中任何內容，請先備份，再將該確切目錄移至作業系統的垃圾桶。切勿對相對路徑或尚未解析的環境變數執行遞迴刪除命令。 3. 移除已安裝的套件。請使用與發行版相符的命令： ```bash python -m pip uninstall deeptutor python -m pip uninstall deeptutor-cli ``` 如果虛擬環境只為 DeepTutor 建立，請透過環境管理工具移除。若是從原始碼安裝，請停用環境、離開原始碼目錄，並在該確切 checkout 中執行 `git status --short`。確認其中沒有不相關或尚未提交的工作後，才可將 checkout 移至垃圾桶。 4. 若使用 Docker，移除前請檢查確切容器與具名 volume。移除 volume 會永久清除 Docker 管理的資料： ```bash docker ps -a --filter name=^/deeptutor$ docker volume inspect deeptutor-data docker rm -f deeptutor docker volume rm deeptutor-data ```

## 📖 探索 DeepTutor 先從日常最常使用的主要介面開始：Chat、Partners、My Agents、Co-Writer、Book、Knowledge Center、Learning Space、Memory 與 Settings。導覽最後會介紹用於共享且相互隔離工作區的 Multi-User 部署。如果回答遺漏先前限制、引用薄弱證據，或與所選素材不一致，請先將診斷資料收集到 [`REASONING_SAFETY_CHECKLIST.md`](../../REASONING_SAFETY_CHECKLIST.md)，再建立 issue。

🏗️ 系統架構

💬 Chat — 真正實用的代理程式迴圈

Chat 是預設能力，也是大多數工作的起點。單一對話可以進行一般交談、呼叫工具、根據選定的知識庫建立回答依據、讀取附件、生成影像、諮詢子代理程式、寫入筆記本紀錄，並在各回合之間沿用相同情境。

這個迴圈刻意保持簡單：模型分輪思考、在有幫助時呼叫工具、觀察結果，最後以不含工具呼叫的訊息完成回合。`ask_user` 比較特殊；代理程式不必猜測，而是可以暫停回合、提出結構化的釐清問題，並在你回答後繼續。

使用者可切換的工具包括 `brainstorm`、`web_search`、`paper_search`、`reason` 與 `geogebra_analysis`；設定對應的生成模型後，還會有 `imagegen` 與 `videogen`。`rag`、`kb_files`、`read_source`、`read_memory`、`write_memory`、`read_skill`、`load_tools`、`exec`、`web_fetch`、`ask_user`、`list_notebook`、`write_note`、`question_bank`、`github`、`consult_subagent`、`workspace_list`、`workspace_read`、`workspace_search`、`workspace_present` 與 `workspace_export` 等情境式工具，會在回合具有相符情境時自動掛載。情境分成兩類：**固定的工作階段情境**（能力、工作區或課程、工具、知識庫、角色設定、模型，以及 Reading／Mastery 狀態）會延續到後續回合；**單次參照**（檔案、聊天記錄、書籍、閱讀章節、筆記本、題庫、匯入的代理程式）則從 `+` 選單加入，只用於單一回合。語音按鈕只會轉錄目前的訊息。 Home 讓 **Chat**、**Ask Questions**、**Quiz** 與 **Visualize** 一鍵可達；用於建立附引用報告的 **Research**、提供完整推理解題的 **Solve**，以及 **Immersive Watching**，則位於 *More Capabilities* 之下。**Mastery Path** 與 **Immersive Reading** 是側邊欄中的專屬工作區。Reading 新增經驗證且可點擊的引用、已儲存的引文與筆記、以來源為依據的音訊／學習指南／詞彙／測驗／翻譯動作，以及擷取至筆記本的功能；Course Study 則保有自己的課程情境。

🤝 Partner — 共用同一套核心的持續型夥伴

Partners 是持續運作的夥伴，各自擁有 soul、模型政策、知識庫、記憶與頻道。它們不是另一套 bot 引擎；每一則從 Web 或 IM 收到的訊息，都會在限定於該 partner 的工作區內成為一般的 `ChatOrchestrator` 回合。Partner 就像是「擁有個性與電話號碼的聊天」。

每個 partner 都有 `SOUL.md`、模型選擇、頻道、工具政策與指派的知識庫。知識庫、技能與筆記本會複製到 `data/partners//workspace/`，因此同一套 RAG、skill、notebook 與 memory 工具都能直接運作，無須特殊處理。已驗證的非管理員使用者擁有私有的 Partner 工作階段與關係記憶，而 Partner 只能以唯讀方式讀取其個人記憶；管理員、群組與未繫結流量則使用共享的 Partner 範圍。

頻道層由結構描述驅動；依已安裝的額外套件與設定的憑證，可連接飛書、Telegram、Slack、Discord、釘釘、QQ／NapCat、企業微信、WhatsApp、Zulip、Mattermost、Matrix、Mochat 與 Microsoft Teams 等 IM 平台。Partner 也可以連接成子代理程式，並從一般聊天回合中接受諮詢；請參閱下方的 **My Agents**。為了更快完成設定，Partner 頻道頁面可直接在瀏覽器中繪製 QR code（而非輸出到伺服器記錄），用來建立飛書／Lark 應用程式或企業微信 AI 機器人，或登入個人微信帳號。飛書／Lark 會偵測帳號網域，並將掃碼使用者存為初始允許發送者。企業微信會保留既有的允許清單，否則預設允許所有能觸及該機器人的使用者，並顯示明顯的開放存取警告；若供應商的掃碼協定有所變更，手動頻道表單仍可使用。

🧑‍🚀 My Agents — 諮詢與匯入其他代理程式

My Agents 會將其他代理程式變成 DeepTutor 的情境，並提供兩項不同功能。**連接即時代理程式** — 連接你電腦上的 Claude Code、Codex、Antigravity、Kimi、opencode、MiMo Code、Hermes Agent、OpenClaw 或 DeepSeek Harness，或你的一位 Partner，並從聊天回合內諮詢它。DeepTutor 會實際*執行*其他代理程式，再透過 `consult_subagent` 工具將其工作即時串流至 Activity 面板。使用 Agent chip 選取代理程式及其回合上限，或透過 `@` 篩選同一份已連接代理程式清單；這項選擇會保留在工作階段中。

**匯入過往對話** — 將現有的 Claude Code 與 Codex 記錄匯入為可命名、搜尋及繼續的代理程式。Claude 記錄依專案／工作目錄選取，Codex 記錄則依日曆日期選取；重新整理時會再次同步該範圍並拉取新對話。你可以在 Chat 回合中透過 `+` → My Agents 參照其中一段對話；DeepTutor 會將其讀作第三方逐字稿，保留為*對方*的對話，而不是 DeepTutor 自己的口吻。

✍️ Co-Writer — 能感知選取範圍的 Markdown 寫作

Co-Writer 是用於報告、教學文章、筆記與長篇學習作品的分割檢視 Markdown 工作區。文件會自動儲存並呈現即時預覽（KaTeX 數學式、圖解 fences）；草稿成為可重複使用的情境後，也能存回筆記本。可匯入 `.docx` 開新草稿，也可將目前編輯器匯出為 Markdown 或 Word。

它的核心概念是**精準編輯**：選取一段內容，請 DeepTutor 改寫、擴寫或縮短。編輯代理程式可以知識庫或 Web 證據作為修改依據，並保留工具呼叫軌跡。若代理程式工作期間草稿未發生變更，結果會直接取代所選文字，且仍可使用 **Undo** 復原。

📖 Book — 從你的素材建立活書

Book 會將選定來源轉換成互動式**活書**；它不是靜態 PDF，而是由具型別區塊組成的閱讀環境。書籍可從知識庫、筆記本、題庫或聊天記錄建立；生成內容前，建立流程會先提出章節大綱，讓你審視整體架構，而非直接接受無從確認的單次輸出。

Book 測驗區塊 Book Manim 動畫區塊 Book 互動式元件區塊

每章都會編譯成可編輯的具型別區塊：文字、提示框、測驗、單字卡、時間軸、程式碼、圖表、互動式 HTML、動畫、概念圖、深入探討與使用者筆記，並有自己的 Page Chat。你可以插入、移動、重新生成、重寫區塊或切換其型別；選取的段落會進入可供檢視的學習摘錄收件匣。即使管理員將書籍以唯讀或共同編輯方式共享，每位讀者的進度、書籤、測驗嘗試、學習摘錄與 Page Chat 仍為私有；共享書籍仍只能由管理員刪除。任何書籍皆可匯出為 Markdown，長時間的編譯可暫停並續行，`deeptutor book health`／`refresh-fingerprints` 會標記來源漂移。

📚 Knowledge Center — 多引擎 RAG 知識庫

知識庫是 RAG 背後的文件集合，可為 Chat 回合、Co-Writer 編輯、Book 生成與 Partner 對話提供依據。其特色在於可**選擇檢索引擎**：**LlamaIndex**（預設，混合 vector＋BM25，並可選用 cross-encoder reranking 與 exact-flat 或 HNSW FAISS 索引）、**PageIndex**（可推理的檢索並附頁面層級引用，支援託管式或自架 OSS）、**GraphRAG** 與 **LightRAG**（知識圖譜檢索）、**LightRAG Server**（透過 HTTP 連接的外部 LightRAG 執行個體負責檢索）、**WeKnora**（從自架部署中的知識庫檢索，無須建立本機索引或複製文件）、**Tencent IMA**（在 IMA 中整理的知識庫 — 透過其 OpenAPI 進行搜尋、瀏覽與寫回）、**MarginNote 4**（你的 MN4 學習資料 — 文件、摘錄、思維導圖卡片及彼此之間的連結 — 由該應用程式的 Add-on 推送匯入，並透過專用工具進行導覽），或讓導師就地讀寫的已連結 **Obsidian** vault。每個知識庫都會繫結至單一引擎。

要遷移現有的 Obsidian、Hermes 或 Markdown 知識庫嗎？請參閱 [Knowledge 遷移指南](../../KNOWLEDGE_MIGRATION.md)，了解連結 vault 與索引副本兩種方式。建立知識庫時，可以選擇**建立新的知識庫**（上傳文件並建立全新索引），或**連結現有知識庫**（重複使用在其他位置建立的索引、就地讀取且不重新建立索引）。知識庫也可以追蹤 **GitHub repositories**（repo、branch、glob）或**文件網站 URL**（限制爬取深度與頁面數量）；依需求同步時會以內容雜湊差異識別新增、變更與移除的內容，因此你所追蹤的文件能保持最新，無須重新上傳。重新建立索引時，系統會寫入新的扁平 `version-N` 目錄並保留先前版本，因此可用索引不會在重建途中遭到破壞。即使知識庫處於 **error** 狀態，也能移除單一文件；可直接刪除解析失敗的檔案，無須刪除並重建全部內容。文件解析方式（Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse）可在 **Settings → Knowledge Base** 選擇，預設不下載本機模型。Docling 也可以在**遠端（remote）**模式下運作，改連線至 Docling Serve 伺服器（無須本機安裝或下載模型），可透過 **Settings → Document Parsing**（設定 `mode=remote`、伺服器基礎 URL 與選用的 API 金鑰）或 `DOCLING_MODE`／`DOCLING_API_BASE_URL`／`DOCLING_API_TOKEN` 環境變數進行設定。Tika 僅支援遠端模式，會連線至該頁面設定的 Apache Tika 伺服器。CLI 也提供對應的完整生命週期指令：`list/info/create/add/search/set-default/delete`、來源新增／移除指令、`list-sources` 與 `sync`。內建的 LightRAG 引擎可透過 `pip install 'deeptutor[rag-lightrag]'` 安裝；此額外套件包含明確支援的 LightRAG SDK，但不會安裝 MinerU。若需要結構化解析，請在 Document Parsing 中另行選擇 MinerU，並設定其雲端模式，或安裝目前的本機 CLI。MinerU 支援 PDF、常見點陣圖格式、DOCX、PPTX 與 XLSX；舊版 `magic-pdf` 仍僅支援 PDF。Text-only 與其他解析引擎不需要 MinerU。

🌐 Learning Space — 技能、角色設定與可重複使用的情境

Learning Space 是資源庫、組織與個人化層。**Conversations & Materials** 包含 Chat History、筆記本 — 紀錄可在筆記本之間搬移或複製，並支援匯出為 Markdown — 以及保留你的答案、參考答案與解說的題庫。**Personalization** 包含角色設定、技能（`SKILL.md` 操作手冊）、一鍵安裝的 **MCP Services**，以及來自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 型錄的 **CLI Apps**，每個應用程式的使用指南會按需載入。獨立的 **My Courses** 工作區會依科目歸納對話與導師討論串；每項資產只會出現在支援它的工作流程中。

你不必自行撰寫每一項技能；**Import from EduHub** 可瀏覽社群型錄，並透過安全閘道將技能直接下載至技能庫（參閱[生態系](#-生態系--eduhub-與技能社群)）。

🧠 Memory — 可檢視的個人化

Memory 是以檔案為基礎、可讀取、整理及稽核的三層系統；它刻意*不使用*隱藏的向量儲存區。**L1** 是工作區鏡像與僅附加的事件軌跡（`trace//.jsonl`）；**L2** 是各介面整理後的事實（`L2/.md`），並附有對 L1 實體的參照；**L3** 是跨介面的綜整（`L3/.md`），會記錄其貢獻來源 L2 介面。

Memory Graph 會呈現完整金字塔：L3 綜整位於中央、L2 位於中圈、L1 軌跡則在外圈，並提供精確的 L2 → L1 證據邊與 L3 → 貢獻來源介面連結。Memory 會追蹤 `chat`、`notebook`、`quiz`、`kb`、`book`、partner 與 `cowriter` 等介面；綜整器的 Update／Audit／Dedup 預算可在 **Settings → Memory** 調整。

⚙️ Settings — 統一控制中心

Settings 是操作控制中心：開頭是即時狀態列（後端健康狀況與常駐記憶體）、介面與模型輸出語言，以及將每項能力評為 blocker、warning 或 suggestion 的 **Readiness** 矩陣；再往下是常駐顯示、可搜尋的導覽選單，一鍵即可抵達任何頁面：**Appearance**（主題、程式碼區塊樣式）、**Network**（API base、連接埠、CORS）、**Workspace**（代理程式可讀取的資料夾及其共用的 `outputs/`）、**Models**（連線、LLM、任務模型、Embedding、Search、Text-to-Speech、Speech-to-Text、Image Generation、Video Generation）、**Knowledge Base**（文件解析引擎）、**Chat**（Video Learning、可搜尋工具、各能力參數、起始提示、附件上限）、**Partners & Agents**（九個本機代理程式執行框架）、**Learner profile**（年齡、年級、課綱、語言、閱讀程度、解說風格）、**Guardian**（已授權學習者、教材、報告、憑證重設）、**Memory**（綜整器預算），以及 **About**（版本檢查與安全更新）。**連線**會保存單一供應商憑證，並鏡射至該供應商可提供的每項服務，因此 API key 只需輸入一次，無須分別貼到五個不同頁面；**任務模型**會為那些沒人特別要求的工作 — 例如替對話命名、撰寫輸入框的起始提示 — 指定一個小巧、快速的模型，若留空則會回退至目前使用中的預設模型。 **Video Learning** 位於 Settings → Chat，預設使用官方隱私強化版 YouTube IFrame Player。若要讓播放保持在本機，請設定由管理員管理的 Invidious API 來源（例如 `http://127.0.0.1:3000`）、進行測試、選擇 Invidious 並儲存。新開啟或重新開啟的影片會立即採用該供應商，同時保留相同的素材 ID 與進度。Invidious 媒體會透過 DeepTutor 的 byte-range proxy 串流；上游 URL 不會暴露給瀏覽器，也不會儲存在磁碟上。若該執行個體發生故障，在學習者明確選擇原生 YouTube 備援前，DeepTutor 將維持離線而不連線至 YouTube。公開字幕教學為選用功能：安裝 `.[video-learning]`；未安裝時仍可繼續播放，但以逐字稿為基礎的 **Explain here** 會停用並顯示原因。

大多數區段採用草稿後套用的流程，因此可先測試供應商再確認變更。你也可以直接在 Chat 中提出要求：助理會讀取目前設定、套用變更，並告知是否需要重新啟動或重新建立索引 — 在正式套用新模型前先行探測，因此不會把自己切換到無法連線的設定上。API key 絕不會經過模型，助理會改為替你開啟對應的表單。內建四種主題：Default、Cream、Dark 與 Glass。系統會刻意忽略專案根目錄的 `.env` 檔案；除非 `DEEPTUTOR_HOME` 或 `deeptutor start --home` 將應用程式指向其他位置，否則執行階段設定位於 `data/user/settings/*.json`。 **OpenAI Codex OAuth（實驗性功能）。** 在 Models → LLM 下選擇 **OpenAI Codex** 後，API key 欄位會改為透過瀏覽器登入自己的 ChatGPT 方案，因此不需要 `OPENAI_API_KEY`。Token 只會存放在 `data/system/user-secrets//private/openai-codex/`；在多容器 Compose 部署中，此位置不屬於 exec 沙箱可觸及的任何目錄，而 DeepTutor 絕不會讀取或修改 `~/.codex` CLI 登入。模型清單來自該帳號的即時型錄；登入會發布設定檔，但只有在尚未設定 LLM 時，才會將其設為目前使用的模型。由於 token 授權的是個人方案，該設定檔不能透過使用者授權分享；每個帳號（包括一般使用者）都要自行登入。其卡片位於 Models → LLM，產生的模型、型錄與登出狀態也只屬於該帳號。預設本機 Docker 與 Podman 部署各自使用獨立的 loopback 網路，登入期間需要暫時橋接。請依照[暫時性本機 Codex OAuth 橋接指南](../../CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)，使用確切的 Docker、Compose、Podman 與拆除指令。在遠端部署中，瀏覽器的 `localhost` 與伺服器的 `localhost` 是不同電腦，因此單靠一般反向代理，無法將瀏覽器的 localhost callback 傳送到伺服器。請使用 SSH 通道作為 callback 橋接。此通道會連到已發布的 Web 連接埠；Next.js 只將確切的 callback 路徑改寫至公開 callback broker，broker 驗證 `state` 後再導向原始 OAuth 操作。Callback listener 仍位於後端 loopback，`1455` 與 `1457` 不會發布；此方式支援預設 Docker bridge 網路。 ```bash ssh -N -L 1455:127.0.0.1:3782 @ ``` 若 DeepTutor 回報備援 callback 連接埠 `1457`，請使用： ```bash ssh -N -L 1457:127.0.0.1:3782 @ ``` 只執行符合實際 callback 連接埠的那一個指令，絕不可同時執行兩者。`3782` 只是 Web 連接埠範例；實際值是回報為 `callback_forward_port` 的已設定前端／容器連接埠。這個值不保證 SSH 主機的 `127.0.0.1` 上也有相同連接埠正在監聽。若 Docker 或 Podman 發布不同的主機連接埠，或反向代理在其他連接埠監聽，請只將右側目標連接埠（上例中的 `3782`）換成 SSH 主機 `127.0.0.1` 上實際監聽的 Web 連接埠；左側 callback 連接埠仍須維持 `1455` 或 `1457`。`` 是其 loopback 擁有該監聽連接埠的 SSH 主機。若瀏覽器 URL 指向反向代理或負載平衡器，請換成正確的 SSH 前端主機。 CLI 會顯示通道指令，接著立即嘗試開啟瀏覽器。在遠端部署上，請保持授權頁面開啟而不要完成操作，在另一個終端機建立顯示的通道後，再繼續授權。遠端拓撲偵測以 localhost 為界。若 Web 本身是透過 SSH 或 IDE localhost 轉送連線，瀏覽器無法得知伺服器位於遠端。對於目前的 Web 操作，請讓授權頁面保持未完成、讀取該操作授權 URL 中的 `redirect_uri` 以判斷 callback 連接埠是 `1455` 或 `1457`，再建立第二條從該本機連接埠連至實際 Web 連接埠的通道。你也可以取消該 Web 操作，改用 CLI 開始新的操作；CLI 輸出屬於新操作，不得用於現有 Web 操作。Quota 錯誤與型錄失敗會原樣回報，絕不會改用付費供應商。這是實驗性相容方式，上游介面日後可能變更。

👥 Multi-User — 共享部署 · 選用驗證、相互隔離的每位使用者工作區

驗證功能**預設關閉**，DeepTutor 會以單一使用者模式執行。開啟後，一個 `data/` 目錄樹便能並列容納管理員工作區、相互隔離的每位使用者工作區，以及 partner 工作區： ```text data/ ├── user/ # Admin workspace + global settings ├── users// # Per-user scope: chat history, memory, notebooks, KBs ├── partners//workspace/ # Partner (synthetic-user) scope ├── cli-apps/ # Installed CLI apps, mounted read-only into the sandbox └── system/ # auth · grants · audit · user-secrets/ (OAuth tokens) ``` **第一位註冊的使用者會成為管理員**，並擁有模型型錄、供應商憑證、共享知識庫、技能、作為主版本的共享書籍與每位使用者的授權。管理員建立的本機使用者可選擇 Standard、Learner 或 Custom。Learner 會鎖定學習能力與教材政策、加入可調適的個人檔案，並支援可撤銷、具到期時間與每日上限的裝置憑證；已授權的 Guardians 可檢視報告、核准教材及重設憑證。其他使用者會取得隔離的工作區，以及範圍受限的模型、知識庫、技能、Partners 與共享書籍存取權，而不會收到原始 API key。如果 `auth.json` 已包含 `username` + `password_hash`，該帳號就是管理員：`/register` 會維持關閉，從 `/admin/users` 建立的帳號在升級前一律為 `role=user`。 **啟用方式：** 在 `data/user/settings/auth.json` 開啟驗證、重新啟動 `deeptutor start`、到 `/register` 註冊第一位管理員，接著從 `/admin/users` 新增使用者，並透過授權指派模型、知識庫、技能、partners、工具／MCP／CLI app 政策與程式碼執行權限；再從每位使用者的 **Book access** 面板設定共享書籍。 > PocketBase 仍是單一使用者整合；除非已連接外部使用者儲存區，否則在多使用者部署中請將 `integrations.pocketbase_url` 留白。

## ⌨️ DeepTutor CLI — 代理程式原生介面一個 `deeptutor` 執行檔，提供兩種入口：給終端機使用者的互動式 **REPL**，以及讓其他代理程式驅動 DeepTutor 的結構化 **JSON**。兩者使用相同的能力、工具與知識庫。

自行操作

`deeptutor chat` 會開啟互動式 REPL，並以 `--capability` 選擇模式；`deeptutor run ""` 則將能力作為第一個位置引數，執行單一回合後結束。兩者都接受 `--tool`、`--kb` 與 `--config`。 ```bash deeptutor chat # interactive REPL deeptutor chat --capability deep_solve --kb my-kb --tool rag deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard ``` 這裡也提供核心工作區管理功能，包括知識庫（`kb`）、工作階段（`session`）、partners（`partner`）、技能（`skill`）、筆記本、記憶與設定；課程與工作階段的組織仍在 Web 應用程式中進行。完整清單如下。

讓代理程式操作

DeepTutor 從設計上就能*由其他代理程式操作*。對任何 `run` 加上 `--format json`，每個回合便會以 **NDJSON — 每行一個事件**（`content`、`tool_call`、`tool_result`、`done` 等）串流，且每行都會標上 `session_id`。執行流程可安全用於 headless 環境：若 `ask_user` 在沒有 TTY 的情況下暫停，系統會自動以空白回覆處理，而不會無限等待。 ```bash # One shot, machine-readable deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json # Chain turns in one stateful session — capture the id, reuse it SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard --format json \ | jq -r 'select(.type=="done").session_id') deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json ``` repo 根目錄附有 [`SKILL.md`](../../SKILL.md)，這份約 200 行的交接文件能讓任何支援工具呼叫的 LLM 一次掌握完整介面。將它交給 Claude Code、Codex 或 OpenCode（它們會自動讀取 `SKILL.md`），或在 LangChain／AutoGen 迴圈中將 `deeptutor run` 包裝成工具。完整作法請參閱 [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。

指令參考

| 指令 | 說明 | |:---|:---| | `deeptutor init` | 在目前的執行環境目錄中建立或更新 `data/user/settings` | | `deeptutor doctor [--online]` | 檢查此執行環境是否已就緒可開始工作階段；`--online` 也會探測目前設定的模型供應商，`--format json` 會輸出 JSON 格式報告 | | `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | 同時啟動後端與前端；可選擇 detached 模式或不開啟瀏覽器 | | `deeptutor stop [--home PATH]` | 停止以 `--detach` 啟動的 launcher | | `deeptutor serve [--port PORT]` | 只啟動 FastAPI 後端 | | `deeptutor workspace show/set/reset` | 檢視、選擇或還原每位使用者的內容工作區 | | `deeptutor run ` | 執行單一能力回合（`chat`、`ask_questions`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`、`immersive_reading`、`course_study`、`immersive_watching`）；加上 `--format json` 可輸出 NDJSON | | `deeptutor chat` | 具備能力、工具、知識庫、筆記本與記錄控制的互動式 REPL | | `deeptutor partner list/create/start/stop` | 管理連接 IM 的 partners | | `deeptutor kb list/info/create/add/search/set-default/delete/list-sources/sync` | 管理知識庫，並同步已註冊的 GitHub／Web 來源（含來源新增／移除指令） | | `deeptutor skill search/install/list/remove/login/logout/publish/update` | 管理技能、從 hub 安裝並發布自己的技能（預設為 `eduhub:`，請參閱生態系） | | `deeptutor memory show/clear` | 檢視 L2／L3 記憶文件，或清除 L1／所有記憶 | | `deeptutor session list/show/open/rename/delete` | 管理共享工作階段 | | `deeptutor notebook list/create/show/add-md/replace-md/remove-record` | 從 Markdown 檔案管理筆記本 | | `deeptutor book list/health/refresh-fingerprints` | 檢視書籍並更新來源 fingerprint | | `deeptutor plugin list/info` | 檢視已註冊的工具與能力 | | `deeptutor config show` | 顯示設定摘要 | | `deeptutor provider login ` | 供應商驗證（`openai-codex` OAuth 登入；`github-copilot` 會驗證既有 Copilot 登入工作階段；`codebuddy` 會驗證 CodeBuddy SDK 驗證狀態，並在需要時開始登入） |

僅含 CLI 的發行套件

僅含 CLI 的套件位於 `packaging/deeptutor-cli`。在這份 checkout 中，請從原始碼安裝： ```bash python -m pip install -e ./packaging/deeptutor-cli ``` 它尚未發布至 PyPI，因此主要的[開始使用](#-開始使用)章節仍採用從原始碼安裝的方式。

## 🧩 生態系 — EduHub 與技能社群 DeepTutor 技能採用開放的 **Agent-Skills** 格式，也就是包含 `SKILL.md` 操作手冊（YAML frontmatter＋Markdown）與選用參考檔案的資料夾。這個格式並非 DeepTutor 專屬，因此任何支援此格式的 registry 都能成為你的知識庫來源。DeepTutor 內建我們以教育為核心的技能 registry **[EduHub](https://eduhub.deeptutor.info/)**，並將其設為預設 hub。

EduHub — DeepTutor 的技能生態系

[**EduHub**](https://eduhub.deeptutor.info/) 是 DeepTutor 推出的社群中心，用於分享教學導向的代理程式技能，包括蘇格拉底式導師、單字卡建立工具、文章回饋、考試藍圖、概念解說等。它已整合至 DeepTutor，無須任何設定；只輸入 slug 或加上 `eduhub:` 前置字串都會解析至此。 **尋找並安裝** — 在瀏覽器中開啟 **Learning Space → Skills → Import from EduHub**，即可瀏覽型錄並將技能直接下載到知識庫。若從終端機操作： ```bash deeptutor skill search "socratic tutor" # search EduHub (the default hub) deeptutor skill install socratic-tutor # fetch → verify → register deeptutor skill install eduhub:socratic-tutor@1.2.0 # pin a hub and a version deeptutor skill list # local skills with their hub provenance ``` **發布自己的技能** — 將 `SKILL.md` 打包並分享給社群： ```bash deeptutor skill login # browser sign-in to EduHub deeptutor skill publish ./my-skill # interactive: pick a track + tags, then upload deeptutor skill update # roll back or release a new version ``` EduHub 也是獨立且相容於 ClawHub 的 registry，因此不是 DeepTutor 的代理程式（Claude Code、Codex 等）也能直接透過 `eduhub` CLI 使用：`npx eduhub install socratic-tutor`。

匯入安全閘道

不論來源為何，每次匯入都必須通過**相同的安全閘道**，才會有任何內容進入工作區： - 系統會先檢查 registry 的**安全性判定**；除非傳入 `--allow-unverified`，否則會拒絕標記有問題的套件； - 壓縮檔會進行防禦性解壓縮，並檢查路徑穿越、項目數量、大小、壓縮率、副檔名與符號連結；可執行位元會被移除，而無副檔名檔案仍允許保留； - frontmatter 會正規化成 DeepTutor 的結構描述，並**移除** `always:`，因此下載的技能無法強迫自己進入每一個系統提示； - 來源資訊（hub、版本、判定與安裝時間）會寫入 `.hub-lock.json`，供稽核與更新使用。在多使用者部署中，瀏覽器匯入會進入已驗證呼叫者的技能層，CLI 與管理員控制台安裝則以擁有者／管理員工作區為目標；管理員技能在授權前會對一般使用者保持隱藏及唯讀。

同時相容於 ClawHub

由於 DeepTutor 支援開放的 Agent-Skills 格式，**[ClawHub](https://clawhub.ai/)** 也是第一級來源，並與 EduHub 一同內建。可透過 hub 前置字串選擇： ```bash deeptutor skill search "git release notes" --hub clawhub deeptutor skill install clawhub:git-release-notes@1.0.1 deeptutor skill install clawhub:udiedrichsen/stock-analysis ``` 當多位發布者共用相同的 slug 時，搜尋結果會列出各發布者，並附上完整範圍的安裝參照（`clawhub:/`）。可在 `data/user/settings/skill_hubs.json` 加入更多 registry：`type: "clawhub"` 項目指向任何相容的 HTTP API（EduHub 與 ClawHub 皆支援）；`type: "command"` 可包裝 registry 提供的任何擷取 CLI；`"default"` 則指定只輸入 slug 時使用的 hub。它們都會通過相同的匯入閘道。

## 🤝 開放原始碼合作夥伴

代碼 DEEPTUTOR20 — 20 美元折扣，適用於首次 PageIndex 訂閱（新客戶 · Standard／Pro／Max）

## 🌐 社群 ### 🔗 維護者

Bingxi Zhao

Xingyu Hou

Jiahao Zhang

### 📮 聯絡方式 DeepTutor 是由 [HKUDS](https://github.com/HKUDS) 團隊的 [Bingxi Zhao](https://github.com/pancacake) 主導的開放原始碼專案，並以**完全開放原始碼的形式**持續迭代，與社群共同打造。目前我們**不提供**任何形式的付費線上產品。如欲討論、分享構想或洽談合作，歡迎來信 **bingxizhao39@gmail.com**。 ### 🙏 致謝衷心感謝香港大學 Data Intelligence Lab 主任 [**Chao Huang**](https://sites.google.com/view/chaoh)，以及 HKUDS 實驗室夥伴的熱情支持；特別感謝 [**Jiahao Zhang**](https://github.com/zzhtx258)、[**Zirui Guo**](https://github.com/LarFii) 與 [**Xubin Ren**](https://github.com/Re-bin)。我們也深深感謝**開放原始碼社群**；你們的 stars、issues、pull requests 與 discussions 每一天都在形塑 DeepTutor。 DeepTutor 也站在許多傑出開放原始碼專案的肩膀上；它們同時提供了工具與靈感： | 專案 | 角色／啟發 | |:---|:---| | [**LlamaIndex**](https://github.com/run-llama/llama_index) | RAG 管線與文件索引的骨幹 | | [**nanobot**](https://github.com/HKUDS/nanobot) | 驅動最初 TutorBot 的超輕量代理程式引擎（*HKUDS*） | | [**LightRAG**](https://github.com/HKUDS/LightRAG) | 簡潔且快速的 RAG（*HKUDS*） | | [**AutoAgent**](https://github.com/HKUDS/AutoAgent) | 零程式碼代理程式框架（*HKUDS*） | | [**AI-Researcher**](https://github.com/HKUDS/AI-Researcher) | 自動化研究管線（*HKUDS*） | | [**OpenClaw**](https://github.com/openclaw/openclaw) | ClawHub 背後的開放代理程式閘道與技能生態系 | | [**Codex**](https://github.com/openai/codex) | 啟發 CLI 工作流程的代理程式原生程式設計 CLI | | [**Claude Code**](https://github.com/anthropics/claude-code) | 啟發 DeepTutor 代理程式迴圈的代理式程式設計 CLI | | [**ManimCat**](https://github.com/Wing900/ManimCat) | AI 驅動的 Math Animator 數學動畫生成 | ### 🗺️ Roadmap 與貢獻我們希望 DeepTutor 持續迭代與進步，最終成為回饋開放原始碼社群的一份禮物。我們會持續更新[**roadmap**](https://github.com/HKUDS/DeepTutor/issues/498)；歡迎到該處為項目投票或提出新構想。如果你想參與貢獻，請參閱[**貢獻指南**](../../CONTRIBUTING.md)，了解分支策略、程式碼規範與開始方式。

我們希望 DeepTutor 成為送給社群的一份禮物。🎁

採用 [Apache License 2.0](../../LICENSE) 授權。