DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
release: v1.6.13
Bingxi Zhao (Frank)f07029cfcf2c
diff --git a/README.md b/README.mdindex 863dd303f..65dd79024 100644--- a/README.md+++ b/README.md@@ -48,6 +48,11 @@### 📦 Releases+> **[2026.10.4]** [v1.6.13](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.13) — Reading and listening improvements, question-bank practice, resilient document parsing, configurable speech, workspace-visible attachments, Polish, and new providers.++<details>+<summary><b>Past releases (more than 1 week ago)</b></summary>+> **[2026.9.27]** [v1.6.12](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.12) — Workspace KB moves, Kiwix archives, source figures, Task Board, German UI, and chat recovery.> **[2026.9.24]** [v1.6.11](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.11) — French and Ukrainian interfaces, reading folders with in-chat selection actions, figures sent to vision models, paged Office previews, and self-syncing knowledge bases.@@ -56,9 +61,6 @@> **[2026.9.21]** [v1.6.9](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.9) — Folder-based learning workspaces, daily practice, redesigned Settings, clearer streaming conversations, persistent usage accounting, and recoverable archives with explicit permanent deletion.-<details>-<summary><b>Past releases (more than 1 week ago)</b></summary>-> **[2026.9.14]** [v1.6.8](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.8) — A recycle bin for deleted chats, search across your whole conversation history, a tool that looks past your knowledge base, and a sweep of fixes for quiet failures.> **[2026.9.11]** [v1.6.7](https://github.com/HKUDS/DeepTutor/releases/tag/v1.6.7) — A fix release: books that arrived as one empty chapter, quizzes that produced nothing, the model's scratchpad in the text, formulas printed raw, and cards you could not submit.@@ -217,7 +219,7 @@</details>-> ✨ **v1.6.12 is live.** `pip install -U deeptutor` picks up the latest stable release.+> ✨ **v1.6.13 is live.** `pip install -U deeptutor` picks up the latest stable release.### 📰 News@@ -236,7 +238,7 @@ DeepTutor is an agent-native learning workspace that connects tutoring, problem- **One runtime for every mode** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading, and Immersive Watching share one capability runtime and session context while keeping purpose-built loops and pipelines.- **Task Board** — Track study tasks in To do, In progress, and Done, with notes, drag-and-drop or keyboard-accessible move buttons, and an archive you can restore from. Cards stay in the current workspace and follow the existing appearance and language settings; no model configuration is required.- **Connected learning context** — Knowledge bases, books, Co-Writer drafts, notebooks, question banks, personas, and Memory can be reused across the workflows that support them, subject to account grants and learning policies.-- **Immersive video learning** — paste a YouTube link for privacy-enhanced native playback, synchronized captions, timestamp-grounded tutoring, and resumable progress; administrators can switch playback to a self-hosted Invidious instance without rebuilding materials.+- **Immersive video learning** — paste a YouTube link for privacy-enhanced native playback, synchronized captions, timestamp-grounded tutoring, saved timestamp marks, and resumable progress; administrators can switch playback to a self-hosted Invidious instance without rebuilding materials.- **Subagents and Partners** — from Chat, consult a live agent harness (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw, or DeepSeek) or a Partner, import past conversations, and run persistent IM companions on the same brain.- **Multi-engine knowledge** — versioned RAG libraries across LlamaIndex, PageIndex, GraphRAG, LightRAG, a remote LightRAG Server, a self-hosted WeKnora knowledge base, a Tencent IMA or MarginNote 4 library, a connected Kiwix ZIM archive, or a linked Obsidian vault, with pluggable document parsing. See [native LightRAG role models](deeptutor/services/rag/pipelines/lightrag/README.md) for independent extraction, query and vision settings, default-only creation and confirmed rebuilds.- **Extensible tools and skills** — built-in tools, MCP servers, CLI apps, image / video / voice generation models, and installable community skills from EduHub.@@ -559,7 +561,7 @@ Everything under `data/user/settings/` is plain JSON/YAML. The **Settings** page| `auth.json` | Optional auth toggle, username, password hash, token/cookie settings || `integrations.json` | Optional PocketBase and sidecar integration settings || `interface.json` | UI and model output language / theme / sidebar preferences |-| `document_parsing.json` | Parsing engine selection, remote endpoints, and engine-specific options |+| `document_parsing.json` | Parsing engine and image-description model selection, remote endpoints, and engine-specific options || `video_learning.json` | Default YouTube/Invidious playback provider, Invidious origins, and optional transcript adapter || `main.yaml` | Runtime behavior defaults and path injection || `agents.yaml` | Capability/tool temperature and token settings |@@ -684,9 +686,9 @@ The loop is deliberately simple: the model thinks in rounds, calls tools when usUser-toggleable tools are `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason`, and `geogebra_analysis` — plus `imagegen` and `videogen` once you configure the matching generation model. Contextual tools such as `rag`, `kb_files`, `knowledge_frontier`, `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`, and `workspace_export` mount automatically when the turn has the right context.-Context comes in two kinds: **sticky session context** (capability, workspace or course, tools, knowledge bases, persona, model, and Reading / Mastery state) persists across turns; **one-time references** (files, chat history, books, reading sections, notebooks, question bank, imported agents) come from the `+` menu for a single turn. The voice button only transcribes the current message.+Context comes in two kinds: **sticky session context** (capability, workspace or course, tools, knowledge bases, persona, model, and Reading / Mastery state) persists across turns; **one-time references** (files, chat history, books, reading sections, notebooks, selected question-bank entries, imported agents) come from the `+` menu for a single turn. The voice button only transcribes the current message.-Home keeps **Chat**, **Ask Questions**, **Quiz**, and **Visualize** one click away; **Research** for cited reports, **Solve** for worked reasoning, and **Immersive Watching** sit under *More Capabilities*. **Personalized Learning** groups Book, **Mastery Path**, **Immersive Reading**, Watching, and **Practice**; Reading adds verified citations, saved notes, source-grounded read-aloud / study guidance / vocabulary / quiz / translation actions, and notebook capture, while Course Study keeps its course-bound context.+Home keeps **Chat**, **Ask Questions**, **Quiz**, and **Visualize** one click away; **Research** for cited reports, **Solve** for worked reasoning, and **Immersive Watching** sit under *More Capabilities*. **Personalized Learning** groups Book, **Mastery Path**, **Immersive Reading**, Watching, and **Practice**; Reading adds verified citations, saved notes, natural read-aloud from source passages / study guidance / vocabulary / quiz / translation actions, and notebook capture, while Course Study keeps its course-bound context.</details>@@ -770,7 +772,7 @@ Co-Writer is a split-view Markdown workspace for reports, tutorials, notes, and<img src="assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Co-Writer editor with live preview" width="900"></div>-Its defining idea is **surgical editing**: select a span and ask DeepTutor to rewrite, expand, or shorten it. The edit agent can ground the change in a knowledge base or web evidence and keeps a trace of its tool calls. If the draft has not changed while it works, the result replaces the selected text directly and remains reversible with **Undo**.+Its defining idea is **surgical editing**: select a span and ask DeepTutor to rewrite, expand, or shorten it. Choose the edit model; it can use a knowledge base or web evidence and keeps a trace of its tool calls. If the draft has not changed while it works, the result replaces the selected text directly and remains reversible with **Undo**.</details>@@ -810,7 +812,7 @@ Knowledge bases are the document collections behind RAG — they ground Chat turMigrating an existing Obsidian, Hermes, or Markdown library? See [Knowledge migration guide](./docs-for-user/KNOWLEDGE_MIGRATION.md) for connected-vault and indexed-copy paths.-Creating a KB, you can **create new** (upload and index documents), **link existing** (reuse an index in place), or **connect Kiwix** (search one served ZIM archive on demand). Choose its storage workspace at creation; an existing KB can move between workspaces after a preview, keeping assignments and saved references. A KB can also track **GitHub repositories** (repo, branch, glob) or **documentation-site URLs** (bounded crawl depth and page count, re-synced every 24 h by default); sync hash-diffs added, changed, and removed content so followed documentation stays current without re-uploading, and **linked folders** pick up new or changed local files on sync. Re-indexing writes a new flat `version-N` directory and keeps prior ones, so a working index is never destroyed mid-rebuild. A single document can be removed even from an **error**-state base — dropping a file that failed to parse without a full delete-and-rebuild. Document parsing — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM, or LiteParse — is chosen in **Settings → Knowledge & documents**, with local model downloads off by default. Docling can also run in **remote** mode against a Docling Serve server (no local install or models needed), configured on that page (`mode=remote`, a server base URL, and an optional API key) or the `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` environment variables. Tika is remote-only and points at the Apache Tika server configured on that page. The CLI mirrors the lifecycle with `list/info/create/connect-kiwix/add/search/set-default/delete`, source add/remove commands, `list-sources`, and `sync`.+Creating a KB, you can **create new** (upload and index documents), **link existing** (reuse an index in place), or **connect Kiwix** (search one served ZIM archive on demand). Choose its storage workspace at creation; an existing KB can move between workspaces after a preview, keeping assignments and saved references. A KB can also track **GitHub repositories** (repo, branch, glob) or **documentation-site URLs** (bounded crawl depth and page count, re-synced every 24 h by default); sync hash-diffs added, changed, and removed content so followed documentation stays current without re-uploading, and **linked folders** pick up new or changed local files on sync. Re-indexing writes a new flat `version-N` directory and keeps prior ones, so a working index is never destroyed mid-rebuild. A single document can be removed even from an **error**-state base — dropping a file that failed to parse without a full delete-and-rebuild. Document parsing — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM, or LiteParse — and an optional image-description model are chosen in **Settings → Knowledge & documents**, with local model downloads off by default. Docling can also run in **remote** mode against a Docling Serve server (no local install or models needed), configured on that page (`mode=remote`, a server base URL, and an optional API key) or the `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` environment variables. Tika is remote-only and points at the Apache Tika server configured on that page. The CLI mirrors the lifecycle with `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, source add/remove commands, `list-sources`, and `sync`.The built-in LightRAG engine is installed with `pip install 'deeptutor[rag-lightrag]'`. That extra contains the supported LightRAG SDK but does not install MinerU. Choose MinerU independently in Document Parsing and either configure its cloud mode or install its current local CLI when structured parsing is wanted. MinerU accepts PDF, common raster images, DOCX, PPTX, and XLSX; the legacy `magic-pdf` command remains PDF-only. Text-only and the other parsing engines do not require MinerU.@@ -831,7 +833,7 @@ Native LightRAG queries and incremental indexing require the embedding configura<img src="assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor Learning Space hub" width="900"></div>-Learning Space is the library, organization, and personalization layer. **Conversations & Materials** holds Chat History, notebooks with movable records and Markdown export, and a question bank with answers and explanations. **Practice** in Personalized Learning turns saved questions into review sessions, mistake tracking, and scheduled repetition. **Personalization** holds personas, skills (`SKILL.md` playbooks), one-click **MCP Services**, and **CLI Apps** from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) catalog, each with an on-demand usage guide. The separate **My Courses** workspace groups subject conversations and tutor threads; each asset is offered only in the workflows that support it.+Learning Space is the library, organization, and personalization layer. **Conversations & Materials** holds Chat History, notebooks with movable records and Markdown export, and a question bank with answers and explanations. Start **Practice** from a question-bank selection or Personalized Learning for review sessions, mistake tracking, and scheduled repetition. **Personalization** holds personas, skills (`SKILL.md` playbooks), one-click **MCP Services**, and **CLI Apps** from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) catalog, each with an on-demand usage guide. The separate **My Courses** workspace groups subject conversations and tutor threads; each asset is offered only in the workflows that support it.<div align="center"><img src="assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Import skills from EduHub" width="900">diff --git a/assets/README/README_AR.md b/assets/README/README_AR.mdindex 6afa654fa..e593467c7 100644--- a/assets/README/README_AR.md+++ b/assets/README/README_AR.md@@ -10,7 +10,7 @@</p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="مستودع GitHub الرائج لهذا اليوم" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="ترتيب تاريخ النجوم" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor هو بيئة تعلم أصيلة للوكلاء تربط التدري- **بيئة تشغيل واحدة لجميع الأوضاع** — تشترك Chat وAsk Questions وQuiz وResearch وVisualize وSolve وCourse Study وMastery Path وImmersive Reading وImmersive Watching في بيئة تشغيل واحدة للقدرات وسياق الجلسة، مع احتفاظ كل منها بحلقات وخطوط أنابيب مصممة لغرضها.- **Task Board** — تتبّع مهام الدراسة ضمن «للإنجاز» و«قيد التنفيذ» و«مكتمل»، مع ملاحظات وسحب وإفلات أو أزرار نقل يمكن استخدامها بلوحة المفاتيح، وأرشيف يمكنك الاستعادة منه. تبقى البطاقات في مساحة العمل الحالية وتتبع إعدادات المظهر واللغة القائمة؛ ولا يلزم تهيئة أي نموذج.- **سياق تعلم متصل** — يمكن إعادة استخدام قواعد المعرفة والكتب ومسودات Co-Writer ودفاتر الملاحظات وبنوك الأسئلة والشخصيات والذاكرة عبر سير العمل التي تدعمها، وفقاً لمنح الحساب وسياسات التعلّم.-- **التعلّم الغامر بالفيديو** — ألصق رابط YouTube لتشغيل أصلي معزَّز الخصوصية، وترجمات متزامنة، وتدريس مرتكز على الطوابع الزمنية، وتقدّم قابل للاستئناف؛ ويمكن للمشرفين تحويل التشغيل إلى نسخة Invidious ذاتية الاستضافة دون إعادة بناء المواد.+- **التعلّم الغامر بالفيديو** — ألصق رابط YouTube لتشغيل أصلي معزَّز الخصوصية، وترجمات متزامنة، وتدريس مرتكز على الطوابع الزمنية، وعلامات محفوظة للطوابع الزمنية، وتقدّم قابل للاستئناف؛ ويمكن للمشرفين تحويل التشغيل إلى نسخة Invidious ذاتية الاستضافة دون إعادة بناء المواد.- **الوكلاء الفرعيون والشركاء** — من داخل Chat، استشر مُشغِّل وكيل حيّاً (Claude Code أو Codex أو Grok CLI أو Antigravity أو Kimi أو opencode أو MiMo أو Hermes أو OpenClaw أو DeepSeek) أو Partner، واستورد المحادثات السابقة، وشغّل رفاق IM دائمين على نفس الدماغ.- **معرفة متعددة المحركات** — مكتبات RAG مُصدَّرة عبر LlamaIndex وPageIndex وGraphRAG وLightRAG، أو LightRAG Server عن بُعد، أو قاعدة معرفة WeKnora ذاتية الاستضافة، أو مكتبة Tencent IMA أو MarginNote 4، أو أرشيف Kiwix ZIM متصل، أو مخزن Obsidian مرتبط، مع تحليل مستندات قابل للتوصيل. راجع [نماذج أدوار LightRAG الأصلية](../../deeptutor/services/rag/pipelines/lightrag/README.md) لإعدادات مستقلة للاستخراج والاستعلام والرؤية، والإنشاء بالنماذج الافتراضية فقط، وإعادة البناء بعد التأكيد.- **أدوات ومهارات قابلة للتوسيع** — أدوات مدمجة وخوادم MCP وتطبيقات CLI ونماذج توليد الصور/الفيديو/الصوت ومهارات مجتمع قابلة للتثبيت من EduHub.@@ -75,6 +75,19 @@ DeepTutor هو بيئة تعلم أصيلة للوكلاء تربط التدرييأتي DeepTutor بأربعة مسارات تثبيت. وكلها تشترك في تخطيط واحد لمساحة عمل وقت التشغيل: تعيش الإعدادات الخاصة في `data/user/settings/` تحت الدليل الذي تُطلق منه التطبيق (أو تحت `DEEPTUTOR_HOME` / `deeptutor start --home` إذا حددت واحداً صراحةً). للتطبيق الكامل، التدفق الموصى به هو **اختر دليل مساحة عمل وقت التشغيل → تثبيت → `deeptutor init` → `deeptutor start`**.+### تجربة Docker بأمر واحد++إذا لم يكن Docker مثبتاً بعد، [ثبّت Docker](https://docs.docker.com/get-docker/) أولاً. ثم جرّب التطبيق الكامل دون إعداد Python أو Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++افتح [http://127.0.0.1:3782](http://127.0.0.1:3782)، وهيّئ مزودي النماذج في **الإعدادات ← المزودون**، واضغط `Ctrl+C` عند الانتهاء. تحتفظ وحدة التخزين المسماة `deeptutor-data` بالإعدادات والبيانات المحلية للتشغيل التالي.+### مساحة عمل المحتوى**مساحة عمل المحتوى** منفصلة عن مساحة عمل DeepTutor الخاصة لوقت التشغيل. إنها المجلد الذي يمكن للوكلاء قراءته، وتوضع الملفات المُولَّدة تحت `outputs/<capability>/<session>/<turn>/`. تعزل مساحات العمل المخصصة المحادثات والمواد التعليمية والتقدم والذاكرات المؤقتة في شجرة خاصة `.deeptutor/data/` لا تستطيع أدوات الملفات تصفحها. وتبقى الإعدادات وبيانات الاعتماد وMemory مشتركة على مستوى الحساب.@@ -329,7 +342,7 @@ deeptutor config show| `auth.json` | تبديل مصادقة اختياري، واسم مستخدم، وتجزئة كلمة مرور، وإعدادات الرمز/الكوكي || `integrations.json` | إعدادات تكامل PocketBase والمرافق الاختيارية || `interface.json` | تفضيلات لغة واجهة المستخدم ولغة مخرجات النموذج / الثيمة / الشريط الجانبي |-| `document_parsing.json` | اختيار محرك التحليل ونقاط النهاية البعيدة والخيارات الخاصة بكل محرك |+| `document_parsing.json` | اختيار محرك التحليل ونموذج وصف الصور ونقاط النهاية البعيدة والخيارات الخاصة بكل محرك || `video_learning.json` | مزود تشغيل YouTube/Invidious الافتراضي، ومصادر Invidious، ومحوّل اختياري للنصوص المفرّغة || `main.yaml` | افتراضيات سلوك وقت التشغيل وحقن المسار || `agents.yaml` | إعدادات درجة حرارة القدرة/الأداة والرمز |@@ -350,6 +363,8 @@ deeptutor config showملف `.env` في جذر المشروع **لا يُقرأ** كملف تهيئة للتطبيق. للإعداد الأدنى للنموذج، احفظ عنوان URL أساسياً ومفتاح API في **الإعدادات ← المزودون**، ثم أضف نموذج LLM وحدّده في **نماذج اللغة**. أضف ملف تعريف التضمين فقط إذا كنت تخطط لاستخدام ميزات قاعدة المعرفة / RAG.+لاستخدام API Route، اختر **API Route** في **الإعدادات ← المزودون** وأدخل مفتاح API Route. يستخدم الإعداد المسبق `https://global.api-route.com/v1`؛ ثم أضف نموذجاً باستخدام معرّف نموذج API Route الخاص به في **نماذج اللغة**. راجع [دليل البدء السريع لـ API Route](https://www.api-route.com/docs/quickstart) لإعداد المفتاح والنموذج.+تعرض ملفات تعريف LLM وملفات تعريف نماذج المهام إعداد **تنسيق API** عندما يدعم مزودها الاختيار. أبقِ `Auto` للتوجيه والرجوع العاديين، أو اختر `OpenAI Chat Completions` أو `OpenAI Responses` أو `Anthropic Messages`؛ ويظل وضع Responses الإجباري مغلقاً عند الفشل. الحقل المحفوظ هو `api_format` (`auto` أو `openai_chat` أو `openai_responses` أو `anthropic`)؛ و`wire_api` حالة توافق مشتقة. وتغطي إعدادات التجاوز `Auto` / `Supported` / `Not supported` الخاصة بكل نموذج استدعاء الأدوات وإدخال الصور وإخراج JSON وعناصر التحكم في الاستدلال.</details>@@ -422,9 +437,9 @@ Chat هي القدرة الافتراضية والمكان الذي يبدأ فالأدوات القابلة للتبديل من قِبَل المستخدم هي `brainstorm` و`web_search` و`paper_search` و`zotero_search` و`reason` و`geogebra_analysis` — بالإضافة إلى `imagegen` و`videogen` بمجرد تهيئة نموذج التوليد المطابق. الأدوات السياقية مثل `rag` و`kb_files` و`knowledge_frontier` و`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) عبر الأدوار؛ وتأتي **المراجع لمرة واحدة** (الملفات وتاريخ المحادثة والكتب وأقسام القراءة ودفاتر الملاحظات وبنك الأسئلة والوكلاء المستوردون) من قائمة `+` لدور واحد. ولا يفعل زر الصوت سوى تفريغ الرسالة الحالية نصياً.+يأتي السياق في نوعين: يستمر **السياق الثابت للجلسة** (القدرة، ومساحة العمل أو الدورة، والأدوات، وقواعد المعرفة، والشخصية، والنموذج، وحالة Reading / Mastery) عبر الأدوار؛ وتأتي **المراجع لمرة واحدة** (الملفات وتاريخ المحادثة والكتب وأقسام القراءة ودفاتر الملاحظات ومدخلات بنك الأسئلة المحددة والوكلاء المستوردون) من قائمة `+` لدور واحد. ولا يفعل زر الصوت سوى تفريغ الرسالة الحالية نصياً.-تُبقي الصفحة الرئيسية **Chat** و**Ask Questions** و**Quiz** و**Visualize** على بُعد نقرة واحدة؛ وتقع **Research** للتقارير المستشهَد بها و**Solve** للاستدلال المشروح و**Immersive Watching** تحت *المزيد من القدرات*. يجمع **التعلم المخصص** كلاً من Book و**Mastery Path** و**Immersive Reading** وWatching و**التدريب**؛ وتضيف Reading استشهادات موثَّقة، وملاحظات محفوظة، وإجراءات قراءة بصوت عالٍ / إرشاد دراسي / مفردات / اختبار / ترجمة مرتكزة على المصدر، والتقاطاً إلى دفتر الملاحظات، بينما يحتفظ Course Study بسياقه المرتبط بالدورة.+تُبقي الصفحة الرئيسية **Chat** و**Ask Questions** و**Quiz** و**Visualize** على بُعد نقرة واحدة؛ وتقع **Research** للتقارير المستشهَد بها و**Solve** للاستدلال المشروح و**Immersive Watching** تحت *المزيد من القدرات*. يجمع **التعلم المخصص** كلاً من Book و**Mastery Path** و**Immersive Reading** وWatching و**التدريب**؛ وتضيف Reading استشهادات موثَّقة، وملاحظات محفوظة، وقراءة طبيعية بصوت عالٍ من مقاطع المصدر / إرشاد دراسي / مفردات / اختبار / ترجمة، والتقاطاً إلى دفتر الملاحظات، بينما يحتفظ Course Study بسياقه المرتبط بالدورة.</details>@@ -489,7 +504,7 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقا<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="محرر Co-Writer مع معاينة مباشرة" width="900"></div>-الفكرة المحورية هي **التحرير الجراحي**: حدد نطاقاً واطلب من DeepTutor إعادة كتابته أو توسيعه أو تقصيره. يمكن لوكيل التحرير ترسيخ التغيير في قاعدة معرفة أو دليل ويب، ويحتفظ بأثر استدعاءات أدواته. وإذا لم تتغير المسودة أثناء عمله، تستبدل النتيجة النص المحدد مباشرةً وتظل قابلة للعكس باستخدام **Undo**.+الفكرة المحورية هي **التحرير الجراحي**: حدد نطاقاً واطلب من DeepTutor إعادة كتابته أو توسيعه أو تقصيره. اختر نموذج التحرير؛ ويمكنه استخدام قاعدة معرفة أو أدلة من الويب، ويحتفظ بأثر استدعاءات أدواته. وإذا لم تتغير المسودة أثناء عمله، تستبدل النتيجة النص المحدد مباشرةً وتظل قابلة للعكس باستخدام **Undo**.</details>@@ -510,7 +525,7 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقا<img src="../../assets/figs/web-1.4.6+/book/03-book-demo%20interactive%20module.png" alt="كتلة ودجت تفاعلية في الكتاب" width="31%"></p>-يُجمِّع كل فصل إلى كتل ذات أنواع محددة وقابلة للتحرير — نصوص وأقسام وتنبيهات واختبارات وبطاقات فلاش وجداول زمنية ورمز وأشكال وHTML تفاعلية ورسوم متحركة وأشكال مفاهيم وغوص عميق وملاحظات مستخدم — وله Page Chat الخاصة به. أدرج كتلة أو حرّكها أو أعد توليدها أو كتابتها أو غيّر نوعها؛ وتدخل المقاطع المحددة إلى صندوق وارد لمقتطفات التعلّم يمكن مراجعته. يبقى التقدّم والإشارات المرجعية ومحاولات الاختبار ومقتطفات التعلّم وPage Chat خاصاً بكل قارئ، حتى عندما يشارك المشرف كتاباً للقراءة فقط أو للتحرير التعاوني؛ ويظل حذف الكتب المشتركة مقصوراً على المشرف. يمكن تصدير أي كتاب إلى Markdown، وتتوقف عمليات التجميع الطويلة مؤقتاً وتُستأنف، ويكشف `deeptutor book health` / `refresh-fingerprints` عن انجراف المصادر.+يُجمِّع كل فصل إلى كتل ذات أنواع محددة وقابلة للتحرير — نصوص وتنبيهات واختبارات وبطاقات فلاش وجداول زمنية ورمز وأشكال وHTML تفاعلية ورسوم متحركة وأشكال مفاهيم وغوص عميق وملاحظات مستخدم — وله Page Chat الخاصة به. أدرج كتلة أو حرّكها أو أعد توليدها أو كتابتها أو غيّر نوعها؛ وتدخل المقاطع المحددة إلى صندوق وارد لمقتطفات التعلّم يمكن مراجعته. يبقى التقدّم والإشارات المرجعية ومحاولات الاختبار ومقتطفات التعلّم وPage Chat خاصاً بكل قارئ، حتى عندما يشارك المشرف كتاباً للقراءة فقط أو للتحرير التعاوني؛ ويظل حذف الكتب المشتركة مقصوراً على المشرف. يمكن تصدير أي كتاب إلى Markdown، وتتوقف عمليات التجميع الطويلة مؤقتاً وتُستأنف، ويكشف `deeptutor book health` / `refresh-fingerprints` عن انجراف المصادر.</details>@@ -529,12 +544,18 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقاهل تنقل مكتبة Obsidian أو Hermes أو Markdown موجودة؟ راجع [دليل نقل المعرفة](../../docs-for-user/KNOWLEDGE_MIGRATION.md) لمساري المخزن المتصل والنسخة المفهرسة.-عند إنشاء قاعدة معرفة، يمكنك **إنشاء جديدة** (تحميل المستندات وفهرستها)، أو **ربط موجودة** (إعادة استخدام فهرس في مكانه)، أو **توصيل Kiwix** (البحث عند الطلب في أرشيف ZIM واحد يقدّمه خادم). اختر مساحة عمل التخزين عند الإنشاء؛ ويمكن نقل قاعدة معرفة موجودة بين مساحات العمل بعد معاينة، مع الاحتفاظ بالتعيينات والمراجع المحفوظة. يمكن لقاعدة المعرفة أيضاً تتبُّع **مستودعات GitHub** (المستودع والفرع ونمط glob) أو **عناوين URL لمواقع التوثيق** (مع حدود لعمق الزحف وعدد الصفحات، وتُعاد مزامنتها كل 24 ساعة افتراضياً)؛ تقارن المزامنة تجزئات المحتوى لتحديد ما أُضيف أو تغيّر أو أُزيل، كي تبقى الوثائق التي تتابعها محدَّثة دون إعادة رفع، وتلتقط **المجلدات المرتبطة** الملفات المحلية الجديدة أو المتغيرة عند المزامنة. تكتب إعادة الفهرسة دليل `version-N` مسطحاً جديداً وتحتفظ بالسابقة، لذا لا يُدمَّر فهرس عامل أبداً أثناء إعادة البناء. يمكن إزالة مستند واحد حتى من قاعدة في حالة **خطأ** — إسقاط ملف فشل تحليله بدون حذف وإعادة بناء كاملين. تحليل المستندات — نص فقط أو MinerU أو Docling أو Tika أو markitdown أو PyMuPDF4LLM أو LiteParse — يُختار في **الإعدادات ← المعرفة والمستندات**، مع إيقاف تنزيلات النماذج المحلية افتراضياً. يمكن لـ Docling أيضاً العمل في وضع **بعيد** مقابل خادم Docling Serve (بلا حاجة إلى تثبيت محلي أو نماذج)، يُهيَّأ في الصفحة نفسها (`mode=remote`، وعنوان URL أساسي للخادم، ومفتاح API اختياري) أو متغيرات البيئة `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. أما Tika فهو بعيد فقط ويشير إلى خادم Apache Tika المهيَّأ في تلك الصفحة. تعكس واجهة CLI دورة الحياة عبر `list/info/create/connect-kiwix/add/search/set-default/delete`، وأوامر إضافة المصادر وإزالتها، و`list-sources`، و`sync`.+عند إنشاء قاعدة معرفة، يمكنك **إنشاء جديدة** (تحميل المستندات وفهرستها)، أو **ربط موجودة** (إعادة استخدام فهرس في مكانه)، أو **توصيل Kiwix** (البحث عند الطلب في أرشيف ZIM واحد يقدّمه خادم). اختر مساحة عمل التخزين عند الإنشاء؛ ويمكن نقل قاعدة معرفة موجودة بين مساحات العمل بعد معاينة، مع الاحتفاظ بالتعيينات والمراجع المحفوظة. يمكن لقاعدة المعرفة أيضاً تتبُّع **مستودعات GitHub** (المستودع والفرع ونمط glob) أو **عناوين URL لمواقع التوثيق** (مع حدود لعمق الزحف وعدد الصفحات، وتُعاد مزامنتها كل 24 ساعة افتراضياً)؛ تقارن المزامنة تجزئات المحتوى لتحديد ما أُضيف أو تغيّر أو أُزيل، كي تبقى الوثائق التي تتابعها محدَّثة دون إعادة رفع، وتلتقط **المجلدات المرتبطة** الملفات المحلية الجديدة أو المتغيرة عند المزامنة. تكتب إعادة الفهرسة دليل `version-N` مسطحاً جديداً وتحتفظ بالسابقة، لذا لا يُدمَّر فهرس عامل أبداً أثناء إعادة البناء. يمكن إزالة مستند واحد حتى من قاعدة في حالة **خطأ** — إسقاط ملف فشل تحليله بدون حذف وإعادة بناء كاملين. يُختار تحليل المستندات — نص فقط أو MinerU أو Docling أو Tika أو markitdown أو PyMuPDF4LLM أو LiteParse — ونموذج اختياري لوصف الصور في **الإعدادات ← المعرفة والمستندات**، مع إيقاف تنزيلات النماذج المحلية افتراضياً. يمكن لـ Docling أيضاً العمل في وضع **بعيد** مقابل خادم Docling Serve (بلا حاجة إلى تثبيت محلي أو نماذج)، يُهيَّأ في الصفحة نفسها (`mode=remote`، وعنوان URL أساسي للخادم، ومفتاح API اختياري) أو متغيرات البيئة `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. أما Tika فهو بعيد فقط ويشير إلى خادم Apache Tika المهيَّأ في تلك الصفحة. تعكس واجهة CLI دورة الحياة عبر `list/info/create/connect-kiwix/add/search/eval/set-default/delete`، وأوامر إضافة المصادر وإزالتها، و`list-sources`، و`sync`.يُثبَّت محرك LightRAG المدمج عبر `pip install 'deeptutor[rag-lightrag]'`. تحتوي هذه الإضافة على SDK الخاص بـ LightRAG المدعوم لكنها لا تُثبِّت MinerU. اختر MinerU بشكل مستقل في تحليل المستندات، وإما هيّئ وضعه السحابي أو ثبّت واجهة سطر أوامره المحلية الحالية عندما تحتاج إلى تحليل منظَّم. يقبل MinerU ملفات PDF والصور النقطية الشائعة وDOCX وPPTX وXLSX؛ ويظل الأمر القديم `magic-pdf` مقصوراً على PDF. لا يتطلب وضع النص فقط ومحركات التحليل الأخرى MinerU.يتطلب استعلام LightRAG الأصلي والفهرسة التزايدية تهيئة التضمين المسجَّلة في الفهرس المنشور، بما يشمل النموذج والبُعد وهوية نقطة النهاية. إذا تغيّرت، فاستعد التهيئة الأصلية أو أعد البناء باستخدام التضمين الحالي؛ والفهارس التي لا تحمل هوية تضمين مسجَّلة تتطلب إعادة البناء. تعرض صفحات تفاصيل قاعدة المعرفة وإصدارات الفهرس إرشادات التعافي، بينما تبقى الملفات متاحة للعرض والتنزيل.+**تقييم قاعدة المعرفة.** مع توفر عدة محركات، يصبح سؤال «أيها يسترجع أفضل النتائج هنا؟» سؤالاً تجريبياً — ولذلك يجيب عنه `deeptutor kb eval`. اكتب مجموعة أسئلة وأجوبة (كائن JSON واحد في كل سطر: `query` مع مقاطع `gold` التي ينبغي أن يُرجعها الاسترجاع المثالي)، ثم قيّم قاعدة المعرفة باستخدام `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. يُجرى الاسترجاع لكل حالة عبر المسار نفسه الذي يستخدمه دور المحادثة، وتُطابَق استشهاداتها المرتّبة مع المقاطع المرجعية باستخدام النص المطابق تماماً أو التداخل اللفظي (يمكن ضبط العتبات عبر `--min-ratio`؛ ولا يُقيَّم التكافؤ الدلالي)، ويُبلّغ التشغيل عن **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. المقاييس دوال خالصة على الترتيب، لذا لا يحكم أي نموذج على المخرجات: يمكن إعادة إنتاج الدرجات ومقارنة فروقها، ويحوّل خط أساس محفوظ المجموعة إلى بوابة لاكتشاف التراجعات عند تبديل نموذج التضمين أو تغيير مُعيد الترتيب أو تجربة حجم المقاطع. الحالات التي يفشل بحثها (فهرس مفقود أو بيانات اعتماد غير صالحة) لا تحصل على درجة وتُعرض منفصلة بدلاً من خفض المتوسطات. يستخدم PageIndex الاستدلال للاسترجاع ولا يُرجع مقاطع مرتّبة، ولذلك يُستثنى.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقا<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="مركز فضاء التعلم في DeepTutor" width="900"></div>-فضاء التعلم هو طبقة المكتبة والتنظيم والتخصيص. تضم **المحادثات والمواد** سجل Chat ودفاتر الملاحظات بسجلات قابلة للنقل وتصدير إلى Markdown، وبنك أسئلة مع الإجابات والشروح. يحوّل **التدريب** ضمن التعلم المخصص الأسئلة المحفوظة إلى جلسات مراجعة وتتبع للأخطاء وتكرار مجدول. أما **التخصيص** فيضم الشخصيات والمهارات (أدلة `SKILL.md`) و**خدمات MCP** التي تُثبَّت بنقرة واحدة و**تطبيقات CLI** من كتالوج [CLI-Anything](https://github.com/HKUDS/CLI-Anything)، ولكل تطبيق دليل استخدام يُحمَّل عند الطلب. وتجمع مساحة **دوراتي** المنفصلة محادثات المواد ومحادثات المدرّسين؛ ولا يُتاح كل أصل إلا في سير العمل التي تدعمه.+فضاء التعلم هو طبقة المكتبة والتنظيم والتخصيص. تضم **المحادثات والمواد** سجل Chat ودفاتر الملاحظات بسجلات قابلة للنقل وتصدير إلى Markdown، وبنك أسئلة مع الإجابات والشروح. ابدأ **التدريب** من مجموعة أسئلة محددة في بنك الأسئلة أو من التعلم المخصص لجلسات المراجعة وتتبع الأخطاء والتكرار المجدول. أما **التخصيص** فيضم الشخصيات والمهارات (أدلة `SKILL.md`) و**خدمات MCP** التي تُثبَّت بنقرة واحدة و**تطبيقات CLI** من كتالوج [CLI-Anything](https://github.com/HKUDS/CLI-Anything)، ولكل تطبيق دليل استخدام يُحمَّل عند الطلب. وتجمع مساحة **دوراتي** المنفصلة محادثات المواد ومحادثات المدرّسين؛ ولا يُتاح كل أصل إلا في سير العمل التي تدعمه.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="استيراد مهارات من EduHub" width="900">@@ -561,7 +582,7 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقا<img src="../../assets/figs/web-1.4.6+/memory/00-overview.png" alt="نظرة عامة على ذاكرة DeepTutor" width="900"></div>-الذاكرة نظام ثلاثي الطبقات مدعوم بالملفات يمكنك قراءته وتنظيمه ومراجعته — وهو عمداً *ليس* مخزناً ناقلاً مخفياً. **L1** هو مرآة مساحة العمل بالإضافة إلى آثار أحداث تراكمية فقط (`trace/<surface>/<date>.jsonl`)؛ **L2** هو حقائق منظَّمة لكل سطح (`L2/<surface>.md`) مع مراجع إلى كيانات L1؛ و**L3** هو تركيب عبر الأسطح (`L3/<profile|recent|scope|preferences>.md`) يسجل أسطح L2 المساهمة فيه.+الذاكرة نظام ثلاثي الطبقات مدعوم بالملفات يمكنك قراءته وتنظيمه ومراجعته — وهو عمداً *ليس* مخزناً مخفياً للمتجهات. **L1** هو مرآة مساحة العمل بالإضافة إلى آثار أحداث تراكمية فقط (`trace/<surface>/<date>.jsonl`)؛ **L2** هو حقائق منظَّمة لكل سطح (`L2/<surface>.md`) مع مراجع إلى كيانات L1؛ و**L3** هو تركيب عبر الأسطح (`L3/<profile|recent|scope|preferences>.md`) يسجل أسطح L2 المساهمة فيه.<div align="center"><img src="../../assets/figs/web-1.4.6+/memory/01-3%20layer%20memory%20graph.png" alt="رسم بياني لذاكرة DeepTutor" width="900">@@ -580,13 +601,18 @@ Co-Writer هو مساحة عمل Markdown ذات عرض مقسَّم للتقاالإعدادات هي لوحة التحكم التشغيلية، وتُفتح على صفحة **عام** لضبط لغة الواجهة ومخرجات النموذج. يربط شريط التنقل القابل للبحث صفحات مستقلة: تضم **شخصي** مساحات العمل ونقل البيانات والمظهر وإحصاءات الاستخدام؛ وتضم **التعلم والمحادثة** نقاط الانطلاق والمرفقات وVideo Learning وعناصر تحكم المتعلم وولي الأمر وتقدّم التعلّم والذاكرة؛ وتضم **النماذج والخدمات** المزودين ونماذج اللغة ونماذج المهام والتضمين والبحث والصوت والتوليد متعدد الوسائط؛ وتضم **الميزات والتكاملات** الأدوات ومعاملات القدرات والشركاء والوكلاء والمعرفة والمستندات. يضم **النظام** الشبكة وحالة التشغيل وحول؛ وتتيح **المحادثات المؤرشفة** البحث في المحادثات المؤرشفة واستعادتها أو حذفها نهائياً. تحتوي حالة التشغيل على سلامة الخلفية والذاكرة المقيمة ومصفوفة **جاهزية** (Readiness) التي تقيّم عوائق القدرات وتحذيراتها واقتراحاتها. تفصل مساحات العمل ملفات المواضيع وحالة التعلم، مع نقل موثَّق وتصدير ضمن نقل البيانات. يحتفظ **المزود** بعنوان مقدم الخدمة وبيانات اعتماده لتعيد نماذج خدماته استخدامها؛ وتختار صفحات النماذج مزودين محفوظين وتضبط أسماء النماذج وقدراتها. تُثبّت **نماذج المهام** نموذجاً صغيراً وسريعاً للأعمال الخلفية — تسمية المحادثات وكتابة نقاط الانطلاق — وتستخدم النموذج الافتراضي النشط عند تركها فارغة. يجمع الصوت توليد الكلام وتفريغه؛ ويجمع التوليد متعدد الوسائط نماذج الصور والفيديو. تضبط صفحة الشركاء والوكلاء المُشغِّلات المحلية وبوابة Hermes بعيدة.+**الكلام عبر Xiaomi MiMo.** أضف مزود Xiaomi MiMo بعنوان `https://api.xiaomimimo.com/v1` ومفتاح API الخاص به، ثم أضف `mimo-v2.5-tts` ضمن الإعدادات ← الصوت. اختر صوتاً مسبقاً مثل `mimo_default` أو `冰糖` أو `苏打`، واستخدم إخراج `wav` أو `pcm16`، وجرّبه قبل تطبيقه. تتحكم تعليمات الصوت في الأسلوب وسرعة الكلام. يدعم هذا الموائم الكلام بالأصوات المسبقة فقط؛ ويتطلب تصميم الأصوات واستنساخها نماذج منفصلة ولا يدعمهما. إذا كان نموذج MiMo صوتي قديم مهيّأً عبر الموائم العام المتوافق مع OpenAI، فأعد إنشاء مدخل الكلام باستخدام مزود Xiaomi MiMo كي يستخدم بروتوكول chat-completions. راجع [دليل MiMo الرسمي لتوليد الكلام](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**الكلام عبر MiniMax** — في الإعدادات ← الصوت، اختر MiniMax لتحويل النص إلى كلام وحدّد `speech-2.8-hd`. هيّئ مفتاح API لـ MiniMax ومعرّف صوت من أصوات النظام أو صوت مخصص؛ والصوت الافتراضي هو `English_expressive_narrator`. عنوان API الأساسي الافتراضي هو `https://api.minimax.io/v1`؛ ولمنطقة الصين استخدم `https://api.minimaxi.com/v1`. تستخدم القراءة بصوت عالٍ ومعاينات الصوت نقطة نهاية الكلام الأصلية، مع إخراج MP3 أو WAV أو FLAC أو PCM، وعناصر تحكم في معدل أخذ العينات والسرعة واللغة. راجع [واجهة API للكلام في MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http) لمعرّفات الأصوات وتوفرها للحساب.++يستخدم **Video Learning** ضمن الإعدادات ← التعلم والمحادثة مشغّل YouTube IFrame الرسمي المعزَّز للخصوصية افتراضياً. لإبقاء التشغيل محلياً، اضبط مصدر Invidious API الذي يديره المشرف (مثلاً `http://127.0.0.1:3000`)، واختبره، وحدد Invidious، ثم احفظ. تلتقط مقاطع الفيديو الجديدة أو التي يُعاد فتحها المزود فوراً مع الاحتفاظ بمعرّف المادة والتقدّم نفسيهما. تُبث وسائط Invidious عبر وكيل النطاق البايتّي في DeepTutor؛ فلا تُكشف عناوين URL المصدرية للمتصفح ولا تُخزَّن على القرص. إذا تعطلت النسخة، يظل DeepTutor غير متصل بـ YouTube حتى يختار المتعلم صراحةً الرجوع إلى تشغيل YouTube الأصلي. التدريس بالترجمات العامة اختياري: ثبّت `.[video-learning]`؛ ويستمر التشغيل من دونه، بينما تُعطَّل ميزة **اشرح هنا** المعتمدة على النص المفرّغ مع توضيح السبب.<div align="center"><img src="../../assets/figs/web-1.4.6+/settings/01-appearance%20settings.png" alt="إعدادات المظهر والثيمات في DeepTutor" width="900"></div>-تستخدم معظم الأقسام تدفق صياغة-وتطبيق، لذا يمكنك اختبار مزود قبل الالتزام به. يمكنك أيضاً أن تطلب ذلك ببساطة في Chat: يقرأ المساعد التهيئة الحالية، ويطبّق التغيير، ويخبرك إن كان يحتاج إلى إعادة تشغيل أو إعادة فهرسة — مع اختبار النموذج الجديد قبل الالتزام به، بحيث لا يمكنه تبديل نفسه إلى شيء يتعذّر الوصول إليه. مفاتيح API لا تمرّ أبداً عبر النموذج، الذي يفتح لك بدلاً من ذلك الاستمارة المطابقة. تشحن أربع ثيمات في الصندوق — Default وCream وDark وGlass. ملفات `.env` في جذر المشروع تُتجاهل عمداً؛ يعيش تهيئة وقت التشغيل تحت `data/user/settings/*.json` إلا إذا وجّه `DEEPTUTOR_HOME` أو `deeptutor start --home` التطبيق في مكان آخر.+تستخدم معظم الأقسام تدفق صياغة-وتطبيق، لذا يمكنك اختبار مزود قبل الالتزام به. يمكنك أيضاً أن تطلب ذلك ببساطة في Chat: يقرأ المساعد التهيئة الحالية، ويطبّق التغيير، ويخبرك إن كان يحتاج إلى إعادة تشغيل أو إعادة فهرسة — مع اختبار النموذج الجديد قبل الالتزام به، بحيث لا يمكنه تبديل نفسه إلى شيء يتعذّر الوصول إليه. مفاتيح API لا تمرّ أبداً عبر النموذج، الذي يفتح لك بدلاً من ذلك الاستمارة المطابقة. تشحن أربع ثيمات في الصندوق — Default وCream وDark وGlass. ملفات `.env` في جذر المشروع تُتجاهل عمداً؛ تعيش تهيئة وقت التشغيل تحت `data/user/settings/*.json` إلا إذا وجّه `DEEPTUTOR_HOME` أو `deeptutor start --home` التطبيق في مكان آخر.**OpenAI Codex OAuth (تجريبي).** إضافة **OpenAI Codex** ضمن **الإعدادات ← المزودون** تفتح تسجيل دخول عبر المتصفح يعمل مقابل خطة ChatGPT الخاصة بك، لذا لا حاجة إلى `OPENAI_API_KEY`. تعيش الرموز (tokens) فقط في `data/system/user-secrets/<owner>/private/openai-codex/` — في نشر Compose متعدد الحاويات، خارج كل شجرة يمكن لصندوق أمان التنفيذ الوصول إليها — ولا يقرأ DeepTutor أو يعدّل أبداً تسجيل دخولك إلى CLI في `~/.codex`. تأتي قائمة النماذج من الكتالوج الحي لذلك الحساب؛ تسجيل الدخول ينشر الملف الشخصي لكنه لا يصبح النموذج النشط إلا عندما لا يكون هناك LLM مهيأ بعد. ولأن الرمز يخوّل خطة شخص واحد فقط، فالملف الشخصي غير قابل للمشاركة عبر منح المستخدمين — كل حساب يسجّل دخوله بنفسه، بما في ذلك المستخدمون العاديون: تظهر بطاقة تسجيل دخولهم ضمن **المزودون**، وتبقى النماذج الناتجة والكتالوج وتسجيل الخروج خاصة بذلك الحساب.@@ -696,7 +722,7 @@ deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format j| `deeptutor run <capability> <message>` | تشغيل دور قدرة واحدة (`chat` و`ask_questions` و`deep_solve` و`deep_question` و`deep_research` و`visualize` و`math_animator` و`mastery_path` و`immersive_reading` و`course_study` و`immersive_watching` و`audio_overview`)؛ أضف `--format json` لإخراج NDJSON || `deeptutor chat` | REPL تفاعلي مع تحكمات القدرة والأداة وقاعدة المعرفة ودفتر الملاحظات والتاريخ || `deeptutor partner list/create/start/stop` | إدارة الشركاء المتصلين بـ IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | إدارة قواعد المعرفة ومزامنة مصادر GitHub/الويب المسجَّلة (مع أوامر إضافة المصادر وإزالتها) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | إدارة قواعد المعرفة، وتوصيل أرشيفات Kiwix، وتقييم جودة الاسترجاع مقابل مجموعة أسئلة وأجوبة، ومزامنة مصادر GitHub/الويب المسجَّلة (مع أوامر إضافة المصادر وإزالتها) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | إدارة المهارات، التثبيت من المراكز، ونشر مهاراتك الخاصة (`eduhub:<slug>` افتراضياً، راجع النظام البيئي) || `deeptutor memory show/clear` | فحص مستندات الذاكرة L2/L3 أو مسح ذاكرة L1/الكل || `deeptutor session list/show/open/rename/delete` | إدارة الجلسات المشتركة |@@ -816,7 +842,7 @@ DeepTutor هو مشروع مفتوح المصدر تقوده [Bingxi Zhao](https### 🙏 التقدير-خالص الشكر لـ [**Chao Huang**](https://sites.google.com/view/chaoh)، مدير مختبر ذكاء البيانات @ HKU، ولزملائنا في HKUDS على دعمهم الحار — وخاصةً [**Jiahao Zhang**](https://github.com/zzhtx258)، و[**Zirui Guo**](https://github.com/LarFii)، و[**Xubin Ren**](https://github.com/Re-bin). ونحن ممتنون عميقاً أيضاً لـ **مجتمع المصادر المفتوحة**: نجومكم وإصداراتكم وطلبات السحب والنقاشات تشكّل DeepTutor كل يوم.+خالص الشكر لـ [**Chao Huang**](https://sites.google.com/view/chaoh)، مدير مختبر ذكاء البيانات @ HKU، ولزملائنا في HKUDS على دعمهم الحار — وخاصةً [**Jiahao Zhang**](https://github.com/zzhtx258)، و[**Zirui Guo**](https://github.com/LarFii)، و[**Xubin Ren**](https://github.com/Re-bin). ونحن ممتنون عميقاً أيضاً لـ **مجتمع المصادر المفتوحة**: نجومكم والمشكلات التي تبلّغون عنها وطلبات السحب والنقاشات تشكّل DeepTutor كل يوم.يقف DeepTutor أيضاً على أكتاف مشاريع مفتوحة المصدر متميزة أعطتنا أدوات وإلهاماً:diff --git a/assets/README/README_CN.md b/assets/README/README_CN.mdindex d986576e0..f8b2ee009 100644--- a/assets/README/README_CN.md+++ b/assets/README/README_CN.md@@ -5,12 +5,12 @@# DeepTutor:终身个性化辅导<p align="center">- <a href="https://deeptutor.info" target="_blank"><img alt="Docs — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> - <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Collaborate — work with us" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a>+ <a href="https://deeptutor.info" target="_blank"><img alt="文档 — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> + <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="合作 — 与我们携手" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a></p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub 今日热门仓库" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History 排名" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor 是一个智能体原生的学习工作区,将辅导、解题、测- **统一的运行时** — Chat、Ask Questions、Quiz、Research、Visualize、Solve、Course Study、Mastery Path、Immersive Reading 和 Immersive Watching 共享同一套能力运行时与会话上下文,同时保留各自为特定用途设计的循环和流水线。- **Task Board** — 在待办、进行中和已完成三个状态中追踪学习任务,支持添加备注、拖放或使用键盘可操作的移动按钮,并可从归档中恢复任务。卡片保留在当前工作区,沿用现有的外观和语言设置,无需配置模型。- **互联的学习上下文** — 知识库、书籍、Co-Writer 草稿、笔记本、题库、人格预设和 Memory 可在支持它们的工作流中复用,并受账号授权与学习策略约束。-- **沉浸式视频学习** — 粘贴 YouTube 链接,即可使用隐私增强的原生播放、同步字幕、基于时间戳的辅导和可续接的学习进度;管理员可以将播放切换到自托管的 Invidious 实例,无需重新构建素材。+- **沉浸式视频学习** — 粘贴 YouTube 链接,即可使用隐私增强的原生播放、同步字幕、基于时间戳的辅导、已保存的时间戳标记和可续接的学习进度;管理员可以将播放切换到自托管的 Invidious 实例,无需重新构建素材。- **子智能体与 Partners** — 在 Chat 中调用实时智能体运行框架(Claude Code、Codex、Grok CLI、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw 或 DeepSeek)或 Partner、导入历史对话,并让持久化 IM 伴侣运行在同一套大脑之上。- **多引擎知识库** — 跨 LlamaIndex、PageIndex、GraphRAG、LightRAG、远程 LightRAG Server、自托管的 WeKnora 知识库、Tencent IMA 或 MarginNote 4 知识库、已连接的 Kiwix ZIM 归档,或链接的 Obsidian vault 的版本化 RAG 知识库,支持可插拔的文档解析。详见[原生 LightRAG 角色模型](../../deeptutor/services/rag/pipelines/lightrag/README.md),了解独立的抽取、查询与视觉设置、仅默认创建以及确认后的重建。- **可扩展工具与技能** — 内置工具、MCP 服务器、CLI 应用、图像 / 视频 / 语音生成模型,以及从 EduHub 安装的社区技能。@@ -342,7 +342,7 @@ deeptutor config show| `auth.json` | 可选认证开关、用户名、密码哈希、token/cookie 设置 || `integrations.json` | 可选的 PocketBase 和 sidecar 集成设置 || `interface.json` | UI 语言与模型输出语言 / 主题 / 侧边栏偏好 |-| `document_parsing.json` | 解析引擎选择、远程端点与引擎专属选项 |+| `document_parsing.json` | 解析引擎与图像描述模型选择、远程端点与引擎专属选项 || `video_learning.json` | 默认的 YouTube/Invidious 播放提供商、Invidious 来源和可选的转录适配器 || `main.yaml` | 运行时行为默认值和路径注入 || `agents.yaml` | 能力/工具的 temperature 和 token 设置 |@@ -363,6 +363,8 @@ Web Search 引用默认经过过滤:只会展示公开的 `http`/`https` URL项目根目录的 `.env` **不会**作为应用配置文件被读取。最简模型配置:在 **Settings → Providers** 中保存 Base URL 和 API Key,然后在 **Language models** 中添加并选择一个 LLM。仅在计划使用知识库 / RAG 功能时才需要添加嵌入配置。+使用 API Route 时,在 **Settings → Providers** 中选择 **API Route** 并输入 API Route 密钥。预设地址为 `https://global.api-route.com/v1`;随后在 **Language models** 中使用 API Route 模型 ID 添加模型。密钥与模型的配置方法详见 [API Route 快速入门](https://www.api-route.com/docs/quickstart)。+如果提供商支持选择,LLM 和任务模型配置会提供 **API format** 设置。常规路由与回退请保留 `Auto`,也可选择 `OpenAI Chat Completions`、`OpenAI Responses` 或 `Anthropic Messages`;强制 Responses 模式仍会故障关闭。持久化字段为 `api_format`(`auto`、`openai_chat`、`openai_responses` 或 `anthropic`);`wire_api` 是派生的兼容性状态。每个模型均可通过 `Auto` / `Supported` / `Not supported` 覆盖工具调用、图像输入、JSON 输出和推理控制。</details>@@ -435,9 +437,9 @@ Chat 是默认能力,也是大多数工作的起点。单个对话线程可以用户可切换的工具有 `brainstorm`、`web_search`、`paper_search`、`zotero_search`、`reason` 和 `geogebra_analysis` — 配置了对应生成模型后还有 `imagegen` 和 `videogen`。上下文工具如 `rag`、`kb_files`、`knowledge_frontier`、`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 状态)会在各轮次间持续保留;**一次性引用**(文件、聊天历史、书籍、阅读章节、笔记本、题库、导入的智能体)通过 `+` 菜单添加,仅用于单次对话轮次。语音按钮只会转录当前消息。+上下文分为两类:**粘性会话上下文**(能力、工作区或课程、工具、知识库、人格预设、模型,以及 Reading / Mastery 状态)会在各轮次间持续保留;**一次性引用**(文件、聊天历史、书籍、阅读章节、笔记本、选中的题库条目、导入的智能体)通过 `+` 菜单添加,仅用于单次对话轮次。语音按钮只会转录当前消息。-主页让 **Chat**、**Ask Questions**、**Quiz** 和 **Visualize** 一键可达;用于生成引用报告的 **Research**、用于展示完整推理过程的 **Solve** 和 **Immersive Watching** 位于 *更多能力* 之下。**个性化学习**汇集 Book、**Mastery Path**、**Immersive Reading**、Watching 和**练习**;Reading 提供经过验证的引用、已保存的笔记、基于来源的朗读 / 学习指导 / 词汇 / 测验 / 翻译操作,以及笔记本摘录,而 Course Study 则保留与课程绑定的上下文。+主页让 **Chat**、**Ask Questions**、**Quiz** 和 **Visualize** 一键可达;用于生成引用报告的 **Research**、用于展示完整推理过程的 **Solve** 和 **Immersive Watching** 位于 *更多能力* 之下。**个性化学习**汇集 Book、**Mastery Path**、**Immersive Reading**、Watching 和**练习**;Reading 提供经过验证的引用、已保存的笔记、对来源段落的自然朗读 / 学习指导 / 词汇 / 测验 / 翻译操作,以及笔记本摘录,而 Course Study 则保留与课程绑定的上下文。</details>@@ -502,7 +504,7 @@ Co-Writer 是一个分屏 Markdown 工作区,适用于报告、教程、笔记<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Co-Writer 编辑器与实时预览" width="900"></div>-其核心理念是**精准编辑**:选中一段文字,让 DeepTutor 对其进行改写、扩展或缩短。编辑智能体可以基于知识库或网络证据进行修改,并保留工具调用追踪。如果智能体工作期间草稿未发生变化,结果会直接替换所选文本,并且仍可通过 **Undo** 撤销。+其核心理念是**精准编辑**:选中一段文字,让 DeepTutor 对其进行改写、扩展或缩短。你可以选择编辑模型;它可以使用知识库或网络证据,并保留工具调用追踪。如果模型工作期间草稿未发生变化,结果会直接替换所选文本,并且仍可通过 **Undo** 撤销。</details>@@ -542,12 +544,18 @@ Book 将选定的来源转化为交互式**活书** — 不是静态 PDF,而要迁移现有的 Obsidian、Hermes 或 Markdown 资料库?请参阅[知识迁移指南](../../docs-for-user/KNOWLEDGE_MIGRATION.md),了解连接 vault 与索引副本两种路径。-创建 KB 时,可以选择**新建**(上传文档并构建索引)、**链接已有**(原位复用索引),或**连接 Kiwix**(按需搜索一个通过服务提供的 ZIM 归档)。创建时可选择其存储工作区;已有知识库可在预览后移至其他工作区,同时保留资源分配和已保存的引用。知识库还可以追踪 **GitHub 仓库**(仓库、分支和 glob 匹配模式)或**文档站点 URL**(限制爬取深度和页面数量,默认每 24 小时重新同步一次);同步时会通过内容哈希差异识别新增、变更和移除的内容,让你关注的文档保持最新,无需重新上传,**链接文件夹**也会在同步时拾取新增或变更的本地文件。重新索引会写入新的平铺 `version-N` 目录并保留旧版本,因此重建过程中现有索引不会被破坏。即使知识库处于 **error** 状态,也可以单独移除其中一份文档 — 无需完整地删除重建,就能丢弃解析失败的文件。文档解析 — 纯文本、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse — 在 **Settings → Knowledge & documents** 中选择,本地模型下载默认关闭。Docling 也可以以 **remote** 模式运行,对接 Docling Serve 服务器(无需本地安装或模型),可在该页面中配置(`mode=remote`、服务器 Base URL 和可选的 API Key),或通过 `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` 环境变量配置。Tika 仅支持远程模式,需指向该页面中配置的 Apache Tika 服务器。CLI 通过 `list/info/create/connect-kiwix/add/search/set-default/delete`、来源添加/移除命令、`list-sources` 和 `sync` 管理完整生命周期。+创建 KB 时,可以选择**新建**(上传文档并构建索引)、**链接已有**(原位复用索引),或**连接 Kiwix**(按需搜索一个通过服务提供的 ZIM 归档)。创建时可选择其存储工作区;已有知识库可在预览后移至其他工作区,同时保留资源分配和已保存的引用。知识库还可以追踪 **GitHub 仓库**(仓库、分支和 glob 匹配模式)或**文档站点 URL**(限制爬取深度和页面数量,默认每 24 小时重新同步一次);同步时会通过内容哈希差异识别新增、变更和移除的内容,让你关注的文档保持最新,无需重新上传,**链接文件夹**也会在同步时拾取新增或变更的本地文件。重新索引会写入新的平铺 `version-N` 目录并保留旧版本,因此重建过程中现有索引不会被破坏。即使知识库处于 **error** 状态,也可以单独移除其中一份文档 — 无需完整地删除重建,就能丢弃解析失败的文件。文档解析 — 纯文本、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse — 以及可选的图像描述模型均在 **Settings → Knowledge & documents** 中选择,本地模型下载默认关闭。Docling 也可以以 **remote** 模式运行,对接 Docling Serve 服务器(无需本地安装或模型),可在该页面中配置(`mode=remote`、服务器 Base URL 和可选的 API Key),或通过 `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` 环境变量配置。Tika 仅支持远程模式,需指向该页面中配置的 Apache Tika 服务器。CLI 通过 `list/info/create/connect-kiwix/add/search/eval/set-default/delete`、来源添加/移除命令、`list-sources` 和 `sync` 管理完整生命周期。内置的 LightRAG 引擎通过 `pip install 'deeptutor[rag-lightrag]'` 安装。该额外依赖包含受支持的 LightRAG SDK,但不会安装 MinerU。如需结构化解析,请在文档解析中单独选择 MinerU,并配置其云端模式或安装当前的本地 CLI。MinerU 支持 PDF、常见的光栅图像、DOCX、PPTX 和 XLSX;旧版 `magic-pdf` 命令仍仅支持 PDF。纯文本及其他解析引擎均不需要 MinerU。原生 LightRAG 的查询与增量索引依赖已发布索引所记录的嵌入配置,包括模型、维度和端点身份。如果该配置发生变化,需要恢复原始配置,或使用当前嵌入重建索引;未记录嵌入身份的索引则必须重建。知识库详情页和索引版本视图会显示恢复指引,同时文件仍可正常查看和下载。+**评估知识库。** 有多个引擎可选时,“哪一个在这里检索得最好?”需要通过实测回答,`deeptutor kb eval` 正是为此而设。编写一个 QA 数据集(每行一个 JSON 对象,包含 `query` 和理想检索应返回的 `gold` 段落),然后使用 `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]` 为知识库评分。每个样例均通过聊天轮次所用的同一路径检索,按排序返回的引用会通过精确文本匹配或词汇重叠与标准段落进行匹配(可用 `--min-ratio` 调整阈值;不评估语义等价),运行结果报告 **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**。各指标都是对排序结果计算的纯函数,无需模型裁判:评分可复现、可比较差异;保存基线后,就能用这个数据集为切换嵌入模型、更改重排序器或实验分块大小设置回归检查。检索失败的样例(如缺少索引或凭证有误)不计分,会单独报告,不会拉低平均值。PageIndex 以推理进行检索,不返回有排序的文本块,因此不在评估范围内。++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -557,7 +565,7 @@ Book 将选定的来源转化为交互式**活书** — 不是静态 PDF,而<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor 学习空间中心" width="900"></div>-学习空间是内容库、组织与个性化层。**对话与素材**包含聊天历史、支持移动记录和 Markdown 导出的笔记本,以及保存答案与解析的题库。个性化学习中的**练习**将已保存的题目转化为复习会话、错题追踪和定期复习。**个性化**包含人格预设、技能(`SKILL.md` 剧本)、一键安装的 **MCP 服务**,以及来自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 目录的 **CLI 应用**,每个应用的使用指南按需加载。独立的**我的课程**工作区按学科归拢对话与导师线程;每项素材只会出现在支持它的工作流中。+学习空间是内容库、组织与个性化层。**对话与素材**包含聊天历史、支持移动记录和 Markdown 导出的笔记本,以及保存答案与解析的题库。可以从题库选区或个性化学习启动**练习**,进行复习会话、错题追踪和定期复习。**个性化**包含人格预设、技能(`SKILL.md` 剧本)、一键安装的 **MCP 服务**,以及来自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 目录的 **CLI 应用**,每个应用的使用指南按需加载。独立的**我的课程**工作区按学科归拢对话与导师线程;每项素材只会出现在支持它的工作流中。<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="从 EduHub 导入技能" width="900">@@ -593,6 +601,10 @@ Memory Graph 展示整个金字塔 — L3 综合位于中心,L2 在中间圆Settings 是操作控制面板,首页**通用**用于设置界面与模型输出语言。可搜索的导航栏链接到各个独立页面:**个人**包括工作区、数据迁移、外观和用量统计;**学习与对话**包括起始建议、附件、Video Learning、学习者与监护人控制、学习进度,以及 Memory;**模型与服务**包括提供商、语言模型、任务模型、嵌入、搜索、语音和多模态生成;**功能与集成**包括工具、能力参数、Partners 与智能体以及知识与文档。**系统**包括网络、运行状态和关于;**已归档对话**支持搜索、恢复或永久删除归档的对话。运行状态展示后端健康状况、常驻内存占用,以及评估能力阻断项、警告和建议的**就绪度**(Readiness)矩阵。工作区将主题文件和学习状态分开,数据迁移提供经过验证的迁移和导出。**提供商**保存厂商地址和凭证,供其服务模型复用;模型页面选择已保存的提供商,并配置模型名称和能力。**任务模型**为后台工作(如给会话命名、撰写起始建议)指定一个小而快的模型,留空时则回退到当前默认模型。语音汇集语音合成与转录;多模态生成汇集图像与视频模型。Partners 与智能体用于配置本地智能体运行框架和远程 Hermes 网关。+**Xiaomi MiMo 语音。** 添加 Xiaomi MiMo 提供商,填写 `https://api.xiaomimimo.com/v1` 和 API Key,然后在 Settings → Voice 中添加 `mimo-v2.5-tts`。选择 `mimo_default`、`冰糖` 或 `苏打` 等预设音色,使用 `wav` 或 `pcm16` 输出,并在应用前试听。语音指令可控制风格和语速。该适配器仅支持预设语音;声音设计与声音克隆需要独立模型,目前不受支持。如果旧的 MiMo 语音模型通过通用的 OpenAI 兼容适配器配置,请使用 Xiaomi MiMo 提供商重新创建语音条目,使其采用 chat-completions 协议。详见 [MiMo 官方语音指南](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5)。++**MiniMax 语音** — 在 Settings → Voice 中,将文本转语音提供商选为 MiniMax,并选择 `speech-2.8-hd`。配置 MiniMax API Key 和系统或自定义音色 ID;默认音色为 `English_expressive_narrator`。API 基础地址默认为 `https://api.minimax.io/v1`;中国地区使用 `https://api.minimaxi.com/v1`。朗读与音色预览使用原生语音端点,支持 MP3、WAV、FLAC 或 PCM 输出,以及采样率、语速和语言控制。音色 ID 和账号可用性详见 [MiniMax 语音 API](https://platform.minimax.io/docs/api-reference/speech-t2a-http)。+Settings → Learning & conversation 下的 **Video Learning** 默认使用 YouTube 官方的隐私增强型 IFrame Player。若要让播放保持在本地,请设置由管理员管理的 Invidious API 来源(例如 `http://127.0.0.1:3000`),测试后选择 Invidious 并保存。新建或重新打开的视频会立即采用该提供商,同时保留相同的素材 ID 和进度。Invidious 媒体通过 DeepTutor 的字节范围代理进行流式传输;上游 URL 既不会暴露给浏览器,也不会存储到磁盘。如果实例发生故障,DeepTutor 将保持与 YouTube 离线,直到学习者明确选择原生 YouTube 回退方案。公共字幕辅导是可选功能:安装 `.[video-learning]`;即使未安装,播放仍会继续,但基于转录的 **在此解释** 功能会被禁用并说明原因。<div align="center">@@ -700,8 +712,8 @@ deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format j| 命令 | 说明 ||:---|:---|-| `deeptutor init` | 为当前工作区创建或更新 `data/user/settings` |-| `deeptutor doctor [--online]` | 检查工作区是否已准备好启动会话;`--online` 还会探测已配置的模型提供商,`--format json` 打印报告 |+| `deeptutor init` | 在当前运行时主目录中创建或更新 `data/user/settings` |+| `deeptutor doctor [--online]` | 检查运行时是否已准备好启动会话;`--online` 还会探测已配置的模型提供商,`--format json` 打印报告 || `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | 同时启动后端 + 前端;可选择后台运行或禁止自动打开浏览器 || `deeptutor stop [--home PATH]` | 停止通过 `--detach` 启动的启动器 || `deeptutor serve [--port PORT]` | 仅启动 FastAPI 后端 |@@ -709,7 +721,7 @@ deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format j| `deeptutor run <capability> <message>` | 运行单次能力对话(`chat`、`ask_questions`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`、`immersive_reading`、`course_study`、`immersive_watching`、`audio_overview`);添加 `--format json` 可获得 NDJSON 输出 || `deeptutor chat` | 交互式 REPL,支持能力、工具、知识库、笔记本和历史控制 || `deeptutor partner list/create/start/stop` | 管理 IM 连接的 Partners |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | 管理知识库并同步已注册的 GitHub/Web 来源(包含来源添加/移除命令) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | 管理知识库、连接 Kiwix 归档、用 QA 数据集评估检索质量,并同步已注册的 GitHub/Web 来源(包含来源添加/移除命令) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | 管理技能、从 Hub 安装并发布自己的技能(默认 `eduhub:<slug>`,详见生态系统) || `deeptutor memory show/clear` | 查看 L2/L3 记忆文档或清除 L1/全部记忆 || `deeptutor session list/show/open/rename/delete` | 管理共享会话 |@@ -864,7 +876,7 @@ DeepTutor 也站在众多优秀开源项目的肩膀上,它们给予了我们<picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark" /><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />- <img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />+ <img alt="Star History 排名" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" /></picture></a></p>diff --git a/assets/README/README_ES.md b/assets/README/README_ES.mdindex cdf65e244..37df93b8c 100644--- a/assets/README/README_ES.md+++ b/assets/README/README_ES.md@@ -63,7 +63,7 @@ DeepTutor es un espacio de trabajo de aprendizaje nativo de agentes que conecta- **Un runtime para todos los modos** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading e Immersive Watching comparten un mismo runtime de capacidades y contexto de sesión, pero conservan bucles y pipelines especializados para cada propósito.- **Task Board** — Sigue las tareas de estudio en To do, In progress y Done, con notas, movimientos mediante arrastrar y soltar o botones accesibles desde el teclado, y un archivo desde el que puedes restaurarlas. Las tarjetas permanecen en el espacio de trabajo actual y respetan la configuración existente de apariencia e idioma; no se requiere configurar ningún modelo.- **Contexto de aprendizaje conectado** — Las bases de conocimiento, los libros, los borradores de Co-Writer, los cuadernos, los bancos de preguntas, las personas y Memory pueden reutilizarse en los flujos de trabajo que los admiten, sujetos a los permisos de la cuenta y a las políticas de aprendizaje.-- **Aprendizaje inmersivo por vídeo** — pega un enlace de YouTube para una reproducción nativa con privacidad mejorada, subtítulos sincronizados, tutoría basada en marcas de tiempo y progreso reanudable; los administradores pueden cambiar la reproducción a una instancia de Invidious autoalojada sin reconstruir los materiales.+- **Aprendizaje inmersivo por vídeo** — pega un enlace de YouTube para una reproducción nativa con privacidad mejorada, subtítulos sincronizados, tutoría basada en marcas de tiempo, marcas de tiempo guardadas y progreso reanudable; los administradores pueden cambiar la reproducción a una instancia de Invidious autoalojada sin reconstruir los materiales.- **Subagentes y Partners** — desde Chat, consulta un entorno de agente en vivo (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw o DeepSeek) o un Partner, importa conversaciones pasadas y ejecuta compañeros IM persistentes con el mismo cerebro.- **Conocimiento multi-motor** — bibliotecas RAG con versiones: LlamaIndex, PageIndex, GraphRAG, LightRAG, un LightRAG Server remoto, una base de conocimiento WeKnora autoalojada, una biblioteca de Tencent IMA o MarginNote 4, un archivo Kiwix ZIM conectado, o un vault Obsidian vinculado, con análisis de documentos conectable. Consulta los [modelos de rol nativos de LightRAG](../../deeptutor/services/rag/pipelines/lightrag/README.md) para conocer la configuración independiente de extracción, consulta y visión, la creación limitada a valores predeterminados y las reconstrucciones confirmadas.- **Herramientas y habilidades extensibles** — herramientas integradas, servidores MCP, aplicaciones CLI, modelos de generación de imagen / video / voz, y skills de la comunidad instalables desde EduHub.@@ -75,6 +75,19 @@ DeepTutor es un espacio de trabajo de aprendizaje nativo de agentes que conectaDeepTutor incluye cuatro rutas de instalación. Todas comparten un mismo diseño de hogar de ejecución: la configuración privada vive en `data/user/settings/` bajo el directorio desde el que se inicia (o bajo `DEEPTUTOR_HOME` / `deeptutor start --home` si se establece explícitamente). Para la aplicación completa, el flujo recomendado es **elegir un directorio de hogar de ejecución → instalar → `deeptutor init` → `deeptutor start`**.+### Prueba de Docker con un Solo Comando++Si todavía no tienes Docker instalado, [instala Docker](https://docs.docker.com/get-docker/) primero. Después prueba la aplicación completa sin configurar Python ni Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++Abre [http://127.0.0.1:3782](http://127.0.0.1:3782), configura los proveedores de modelos en **Settings → Providers** y pulsa `Ctrl+C` cuando termines. El volumen con nombre `deeptutor-data` conserva la configuración y los datos locales para la próxima ejecución.+### Espacio de Trabajo de ContenidoEl **Espacio de Trabajo de Contenido** es independiente del hogar de ejecución privado de DeepTutor. Es la carpeta que los agentes pueden leer, con los archivos generados bajo `outputs/<capability>/<session>/<turn>/`. Los espacios de trabajo personalizados aíslan conversaciones, materiales de aprendizaje, progreso y cachés en un árbol privado `.deeptutor/data/` que las herramientas de archivos no pueden explorar. La configuración, las credenciales y Memory siguen compartiéndose a nivel de cuenta.@@ -101,8 +114,8 @@ Aplicación web local completa + CLI, sin necesidad de clonar. Requiere **Python```bashmkdir -p my-deeptutor && cd my-deeptutorpip install -U deeptutor-deeptutor init # solicita puertos + proveedor LLM + embedding/búsqueda opcionales-deeptutor start # inicia backend + frontend; mantener la terminal abierta+deeptutor init # prompts for ports + LLM provider + optional embedding/search+deeptutor start # starts backend + frontend; keep the terminal open````deeptutor init` solicita el puerto de backend (predeterminado `8001`), el puerto de frontend (predeterminado `3782`), proveedor LLM / URL base / clave API / modelo, un proveedor de embeddings opcional para Base de Conocimiento / RAG y un proveedor de búsqueda opcional para Web Search.@@ -122,12 +135,12 @@ Para desarrollo en un checkout. Usa **Python 3.11–3.14** y **Node.js 22 LTS**git clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Crear un venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1python3 -m venv .venv && source .venv/bin/activatepython -m pip install --upgrade pip-# Instalar dependencias de backend + frontend+# Install backend + frontend depspython -m pip install -e .( cd web && npm ci --legacy-peer-deps )@@ -152,14 +165,14 @@ python -m pip install --upgrade pip<summary><b>Extras de instalación opcionales</b> — motores RAG / dev / partners / matrix / math-animator</summary>```bash-pip install -e ".[rag-lightrag]" # Motor LightRAG integrado (SDK compatible exacto)-pip install -e ".[graphrag]" # Motor GraphRAG de Microsoft (Python 3.11–3.13)-pip install -e ".[dev]" # herramientas de pruebas/lint-pip install -e ".[partners]" # SDKs de canales IM de Partners-pip install -e ".[video-learning]" # extra de compatibilidad; los subtítulos vienen incluidos en las instalaciones completa/CLI-pip install -e ".[matrix]" # canal Matrix sin E2EE/libolm-pip install -e ".[matrix-e2e]" # Matrix E2EE; requiere libolm-pip install -e ".[math-animator]" # complemento Manim; requiere LaTeX/ffmpeg/libs del sistema+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```</details>@@ -273,7 +286,7 @@ Cuando no necesitas la UI web. El paquete de solo CLI se instala desde un checkogit clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Crear un venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1python3 -m venv .venv-cli && source .venv-cli/bin/activatepython -m pip install --upgrade pip@@ -289,7 +302,7 @@ deeptutor chat<summary><b>Comandos comunes</b></summary>```bash-deeptutor chat # REPL interactivo+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --tool rag --kb my-kbdeeptutor run chat "Explain Fourier transform"deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb@@ -338,7 +351,7 @@ Todo bajo `data/user/settings/` es JSON/YAML plano. La página **Settings** es e| `auth.json` | Interruptor de autenticación opcional, nombre de usuario, hash de contraseña, configuración de token/cookie || `integrations.json` | Configuración opcional de PocketBase e integraciones sidecar || `interface.json` | Idioma de UI y de salida del modelo / tema / preferencias de barra lateral |-| `document_parsing.json` | Selección del motor de análisis, endpoints remotos y opciones específicas de cada motor |+| `document_parsing.json` | Selección del motor de análisis y del modelo de descripción de imágenes, endpoints remotos y opciones específicas de cada motor || `video_learning.json` | Proveedor de reproducción predeterminado de YouTube/Invidious, orígenes de Invidious y adaptador de transcripción opcional || `main.yaml` | Valores predeterminados de comportamiento de runtime e inyección de rutas || `agents.yaml` | Configuración de temperatura y tokens de capacidades/herramientas |@@ -359,6 +372,8 @@ Cuando `trusted_domains` no está vacío, las referencias se limitan a esos domiEl `.env` de la raíz del proyecto **no** se lee como archivo de configuración de la aplicación. Para una configuración mínima del modelo, guarda una URL Base y una clave API en **Settings → Providers**, luego agrega y selecciona un LLM en **Language models**. Agrega un perfil de embeddings solo si planeas usar funciones de Base de Conocimiento / RAG.+Para API Route, selecciona **API Route** en **Settings → Providers** e introduce una clave de API Route. El ajuste predefinido usa `https://global.api-route.com/v1`; después añade un modelo con su ID de modelo de API Route en **Language models**. Consulta la [guía de inicio rápido de API Route](https://www.api-route.com/docs/quickstart) para configurar la clave y el modelo.+Los perfiles de LLM y de modelos de tareas ofrecen una opción de **formato de API** cuando su proveedor admite distintas alternativas. Mantén `Auto` para el enrutamiento y el fallback normales, o elige `OpenAI Chat Completions`, `OpenAI Responses` o `Anthropic Messages`; el modo Responses forzado sigue fallando de forma cerrada. El campo persistido es `api_format` (`auto`, `openai_chat`, `openai_responses` o `anthropic`); `wire_api` es un estado de compatibilidad derivado. Los ajustes por modelo `Auto` / `Supported` / `Not supported` abarcan las llamadas a herramientas, la entrada de imágenes, la salida JSON y los controles de razonamiento.</details>@@ -431,9 +446,9 @@ El bucle es deliberadamente simple: el modelo piensa en rondas, llama herramientLas herramientas activables por el usuario son `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason` y `geogebra_analysis` — más `imagegen` y `videogen` una vez que configures el modelo de generación correspondiente. Las herramientas contextuales como `rag`, `kb_files`, `knowledge_frontier`, `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` y `workspace_export` se montan automáticamente cuando el turno tiene el contexto adecuado.-El contexto viene en dos tipos: el **contexto de sesión persistente** (capacidad, espacio de trabajo o curso, herramientas, bases de conocimiento, persona, modelo y estado de Reading / Mastery) persiste entre turnos; las **referencias de un solo uso** (archivos, historial de chat, libros, secciones de lectura, cuadernos, banco de preguntas, agentes importados) vienen del menú `+` para un único turno. El botón de voz solo transcribe el mensaje actual.+El contexto viene en dos tipos: el **contexto de sesión persistente** (capacidad, espacio de trabajo o curso, herramientas, bases de conocimiento, persona, modelo y estado de Reading / Mastery) persiste entre turnos; las **referencias de un solo uso** (archivos, historial de chat, libros, secciones de lectura, cuadernos, entradas seleccionadas del banco de preguntas, agentes importados) vienen del menú `+` para un único turno. El botón de voz solo transcribe el mensaje actual.-Inicio mantiene **Chat**, **Ask Questions**, **Quiz** y **Visualize** a un clic; **Research** para informes con citas, **Solve** para razonamiento trabajado e **Immersive Watching** se encuentran bajo *More Capabilities*. **Aprendizaje personalizado** agrupa Book, **Mastery Path**, **Immersive Reading**, Watching y **Práctica**; Reading añade citas verificadas, notas guardadas, acciones de lectura en voz alta / orientación de estudio / vocabulario / quiz / traducción fundamentadas en la fuente y captura en notebooks, mientras que Course Study mantiene su propio contexto vinculado al curso.+Inicio mantiene **Chat**, **Ask Questions**, **Quiz** y **Visualize** a un clic; **Research** para informes con citas, **Solve** para razonamiento trabajado e **Immersive Watching** se encuentran bajo *More Capabilities*. **Aprendizaje personalizado** agrupa Book, **Mastery Path**, **Immersive Reading**, Watching y **Práctica**; Reading añade citas verificadas, notas guardadas, lectura natural en voz alta de pasajes de la fuente / acciones de orientación de estudio / vocabulario / quiz / traducción y captura en notebooks, mientras que Course Study mantiene su propio contexto vinculado al curso.</details>@@ -498,7 +513,7 @@ Co-Writer es un espacio de trabajo Markdown de vista dividida para informes, tut<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Editor Co-Writer con vista previa en vivo" width="900"></div>-Su idea definitoria es la **edición quirúrgica**: selecciona un fragmento y pide a DeepTutor que lo reescriba, expanda o acorte. El agente de edición puede fundamentar el cambio en una base de conocimiento o evidencia web y conserva un rastro de sus llamadas a herramientas. Si el borrador no ha cambiado mientras trabaja, el resultado sustituye directamente el texto seleccionado y sigue siendo reversible con **Undo**.+Su idea definitoria es la **edición quirúrgica**: selecciona un fragmento y pide a DeepTutor que lo reescriba, expanda o acorte. Elige el modelo de edición; puede usar una base de conocimiento o evidencia web y conserva un rastro de sus llamadas a herramientas. Si el borrador no ha cambiado mientras trabaja, el resultado sustituye directamente el texto seleccionado y sigue siendo reversible con **Undo**.</details>@@ -538,12 +553,18 @@ Las bases de conocimiento son las colecciones de documentos detrás del RAG —¿Estás migrando una biblioteca existente de Obsidian, Hermes o Markdown? Consulta la [guía de migración de conocimiento](../../docs-for-user/KNOWLEDGE_MIGRATION.md) para conocer las rutas de vault conectado y copia indexada.-Al crear una KB, puedes **crear nueva** (subir e indexar documentos), **vincular existente** (reutilizar un índice en su ubicación) o **conectar Kiwix** (buscar bajo demanda en un archivo ZIM servido). Elige su espacio de trabajo de almacenamiento al crearla; una KB existente puede trasladarse entre espacios de trabajo tras una vista previa, conservando las asignaciones y las referencias guardadas. Una KB también puede rastrear **repositorios de GitHub** (repositorio, rama y patrón glob) o **URLs de sitios de documentación** (con límites de profundidad de rastreo y número de páginas, resincronizadas cada 24 h por defecto); la sincronización compara hashes para detectar contenido añadido, modificado y eliminado, de modo que la documentación que sigues se mantiene actualizada sin volver a subirla, y las **carpetas vinculadas** recogen archivos locales nuevos o modificados al sincronizar. La re-indexación escribe un nuevo directorio `version-N` plano y conserva los anteriores, de modo que un índice funcional nunca se destruye a mitad de la reconstrucción. Un solo documento puede eliminarse incluso de una base en estado de **error** — descartando un archivo que no se pudo analizar sin necesidad de borrar y reconstruir todo. El análisis de documentos — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM o LiteParse — se elige en **Settings → Knowledge & documents**, con descargas de modelos locales desactivadas por defecto. Docling también puede ejecutarse en modo **remoto** contra un servidor Docling Serve (sin necesidad de instalación local ni modelos), configurado en esa página (`mode=remote`, una URL base de servidor y una clave API opcional) o las variables de entorno `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika es solo remoto y apunta al servidor Apache Tika configurado en esa página. La CLI refleja el ciclo de vida con `list/info/create/connect-kiwix/add/search/set-default/delete`, comandos para añadir o eliminar fuentes, `list-sources` y `sync`.+Al crear una KB, puedes **crear nueva** (subir e indexar documentos), **vincular existente** (reutilizar un índice en su ubicación) o **conectar Kiwix** (buscar bajo demanda en un archivo ZIM servido). Elige su espacio de trabajo de almacenamiento al crearla; una KB existente puede trasladarse entre espacios de trabajo tras una vista previa, conservando las asignaciones y las referencias guardadas. Una KB también puede rastrear **repositorios de GitHub** (repositorio, rama y patrón glob) o **URLs de sitios de documentación** (con límites de profundidad de rastreo y número de páginas, resincronizadas cada 24 h por defecto); la sincronización compara hashes para detectar contenido añadido, modificado y eliminado, de modo que la documentación que sigues se mantiene actualizada sin volver a subirla, y las **carpetas vinculadas** recogen archivos locales nuevos o modificados al sincronizar. La re-indexación escribe un nuevo directorio `version-N` plano y conserva los anteriores, de modo que un índice funcional nunca se destruye a mitad de la reconstrucción. Un solo documento puede eliminarse incluso de una base en estado de **error** — descartando un archivo que no se pudo analizar sin necesidad de borrar y reconstruir todo. El análisis de documentos — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM o LiteParse — y un modelo opcional de descripción de imágenes se eligen en **Settings → Knowledge & documents**, con descargas de modelos locales desactivadas por defecto. Docling también puede ejecutarse en modo **remoto** contra un servidor Docling Serve (sin necesidad de instalación local ni modelos), configurado en esa página (`mode=remote`, una URL base de servidor y una clave API opcional) o las variables de entorno `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika es solo remoto y apunta al servidor Apache Tika configurado en esa página. La CLI refleja el ciclo de vida con `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, comandos para añadir o eliminar fuentes, `list-sources` y `sync`.El motor LightRAG integrado se instala con `pip install 'deeptutor[rag-lightrag]'`. Ese extra contiene el SDK de LightRAG compatible pero no instala MinerU. Elige MinerU de forma independiente en Document Parsing y configura su modo en la nube o instala su CLI local vigente cuando se desee un análisis estructurado. MinerU acepta PDF, imágenes rasterizadas comunes, DOCX, PPTX y XLSX; el comando heredado `magic-pdf` sigue limitado a PDF. Text-only y los demás motores de análisis no requieren MinerU.Las consultas nativas de LightRAG y la indexación incremental requieren la configuración de embeddings registrada por el índice publicado, incluyendo el modelo, la dimensión y la identidad del endpoint. Si cambia, restaura la configuración original o reconstruye con el embedding actual; los índices sin una identidad de embeddings registrada requieren una reconstrucción. Las vistas de detalle de la base de conocimiento y de versión de índice muestran orientación de recuperación, mientras los archivos permanecen disponibles para visualización y descarga.+**Evaluar una base de conocimiento.** Con varios motores disponibles, «¿cuál recupera mejor aquí?» es una pregunta empírica, y `deeptutor kb eval` permite responderla. Escribe un conjunto de preguntas y respuestas (un objeto JSON por línea: una `query` y los pasajes `gold` que debería devolver una recuperación ideal), y evalúa la KB con `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. Cada caso se recupera por la misma ruta que usa un turno de chat; sus citas ordenadas se comparan con los pasajes de referencia mediante coincidencia exacta de texto o solapamiento léxico (los umbrales se ajustan con `--min-ratio`; no se evalúa la equivalencia semántica), y la ejecución informa de **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. Las métricas son funciones puras sobre la clasificación, así que ningún modelo juzga la salida: las puntuaciones son reproducibles y se pueden comparar mediante diffs, y una referencia guardada convierte el conjunto en una comprobación de regresiones para cambiar embeddings, modificar el reranker o experimentar con el tamaño de los fragmentos. Los casos cuya búsqueda falla (por un índice ausente o credenciales incorrectas) no reciben puntuación y se informan por separado, en lugar de reducir las medias. PageIndex usa el razonamiento para recuperar y no devuelve fragmentos ordenados, por lo que se excluye.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -553,7 +574,7 @@ Las consultas nativas de LightRAG y la indexación incremental requieren la conf<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="Hub del Espacio de Aprendizaje DeepTutor" width="900"></div>-El Espacio de Aprendizaje es la capa de biblioteca, organización y personalización. **Conversaciones y Materiales** guarda el historial de Chat, cuadernos con registros transferibles y exportación a Markdown, y un banco de preguntas con respuestas y explicaciones. **Práctica**, en Aprendizaje personalizado, convierte las preguntas guardadas en sesiones de repaso, seguimiento de errores y repetición programada. **Personalización** guarda personas, skills (guías `SKILL.md`), **Servicios MCP** con instalación en un clic y **Aplicaciones CLI** del catálogo [CLI-Anything](https://github.com/HKUDS/CLI-Anything), cada una con una guía de uso cargada bajo demanda. El espacio de trabajo independiente **Mis cursos** agrupa las conversaciones por materia y los hilos del tutor; cada recurso solo se ofrece en los flujos de trabajo que lo admiten.+El Espacio de Aprendizaje es la capa de biblioteca, organización y personalización. **Conversaciones y Materiales** guarda el historial de Chat, cuadernos con registros transferibles y exportación a Markdown, y un banco de preguntas con respuestas y explicaciones. Inicia **Práctica** desde una selección del banco de preguntas o desde Aprendizaje personalizado para sesiones de repaso, seguimiento de errores y repetición programada. **Personalización** guarda personas, skills (guías `SKILL.md`), **Servicios MCP** con instalación en un clic y **Aplicaciones CLI** del catálogo [CLI-Anything](https://github.com/HKUDS/CLI-Anything), cada una con una guía de uso cargada bajo demanda. El espacio de trabajo independiente **Mis cursos** agrupa las conversaciones por materia y los hilos del tutor; cada recurso solo se ofrece en los flujos de trabajo que lo admiten.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Importar skills desde EduHub" width="900">@@ -589,6 +610,10 @@ El Memory Graph muestra toda la pirámide — síntesis L3 en el centro, L2 en eSettings es el panel de control operativo y se abre en **General**, donde se configuran el idioma de la interfaz y el de salida del modelo. Su navegador con búsqueda enlaza páginas independientes: **Personal** incluye Espacios de trabajo, Migración de datos, Apariencia y Estadísticas de uso; **Aprendizaje y conversación** incluye sugerencias iniciales, adjuntos, Video Learning, controles de alumnos y tutores, Progreso de aprendizaje y Memory; **Modelos y servicios** incluye Proveedores, Modelos de lenguaje, Modelos de tarea, Embedding, Search, Voz y Generación multimodal; **Funciones e integraciones** incluye herramientas, parámetros de capacidades, Partners y agentes, y Conocimiento y documentos. **Sistema** reúne Red, Estado de ejecución y Acerca de; **Chats archivados** permite buscar, restaurar o eliminar permanentemente conversaciones archivadas. Estado de ejecución contiene la salud del backend, la memoria residente y la matriz de **Preparación** (Readiness), que clasifica bloqueos, advertencias y sugerencias de las capacidades. Espacios de trabajo mantiene separados los archivos de cada tema y el estado de aprendizaje, con migración y exportación verificadas en Migración de datos. Un **proveedor** guarda la dirección y credencial de un servicio para reutilizarlas con sus modelos; las páginas de modelos seleccionan proveedores guardados y configuran nombres y capacidades. Los **modelos de tarea** fijan un modelo pequeño y rápido para el trabajo en segundo plano — nombrar conversaciones y escribir sugerencias iniciales — y recurren al predeterminado activo cuando se dejan vacíos. Voz agrupa síntesis y transcripción de voz; Generación multimodal reúne modelos de imagen y vídeo. Partners y agentes configura entornos de agentes locales y una pasarela remota de Hermes.+**Síntesis de voz de Xiaomi MiMo.** Añade un proveedor Xiaomi MiMo con `https://api.xiaomimimo.com/v1` y su clave API; después añade `mimo-v2.5-tts` en Settings → Voz. Elige una voz predefinida como `mimo_default`, `冰糖` o `苏打`, usa salida `wav` o `pcm16` y escúchala antes de aplicar los cambios. Las instrucciones de voz controlan el estilo y la velocidad del habla. Este adaptador solo admite voces predefinidas; el diseño y la clonación de voces requieren modelos separados y no son compatibles. Si un modelo de voz anterior de MiMo estaba configurado mediante el adaptador genérico compatible con OpenAI, vuelve a crear su entrada de voz usando el proveedor Xiaomi MiMo para que utilice el protocolo de chat-completions. Consulta la [guía oficial de voz de MiMo](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**Síntesis de voz de MiniMax** — en Settings → Voz, elige MiniMax para texto a voz y selecciona `speech-2.8-hd`. Configura una clave API de MiniMax y un ID de voz del sistema o personalizado; la voz predeterminada es `English_expressive_narrator`. La base de API predeterminada es `https://api.minimax.io/v1`; para la región de China usa `https://api.minimaxi.com/v1`. La lectura en voz alta y las previsualizaciones de voz usan el endpoint nativo de voz, con salida MP3, WAV, FLAC o PCM, y controles de frecuencia de muestreo, velocidad e idioma. Consulta la [API de voz de MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http) para conocer los IDs de voz y la disponibilidad por cuenta.+**Video Learning** en Settings → Aprendizaje y conversación usa de forma predeterminada el reproductor IFrame oficial de YouTube con privacidad mejorada. Para mantener la reproducción en local, configura el origen de la API de Invidious gestionado por el administrador (por ejemplo `http://127.0.0.1:3000`), pruébalo, selecciona Invidious y guarda. Los vídeos nuevos o reabiertos adoptan inmediatamente el proveedor con el mismo ID de material y progreso. El contenido multimedia de Invidious se transmite a través del proxy de rangos de bytes de DeepTutor; las URL de origen no se exponen al navegador ni se almacenan en disco. Si la instancia falla, DeepTutor permanece desconectado de YouTube hasta que el alumno elija explícitamente la alternativa nativa de YouTube. La tutoría mediante subtítulos públicos es opcional: instala `.[video-learning]`; la reproducción continúa sin este extra, mientras que **Explain here** basado en la transcripción se desactiva con una explicación.<div align="center">@@ -632,11 +657,11 @@ La autenticación está **desactivada por defecto** — DeepTutor corre en modo```textdata/-├── user/ # Espacio de trabajo del administrador + configuración global-├── users/<uid>/ # Alcance por usuario: historial de chat, memoria, cuadernos, KBs-├── partners/<id>/workspace/ # Alcance del partner (usuario sintético)-├── cli-apps/ # Aplicaciones CLI instaladas, montadas de solo lectura en el sandbox-└── system/ # auth · grants · audit · user-secrets/<owner> (tokens OAuth)+├── user/ # Admin workspace + global settings+├── users/<uid>/ # Per-user scope: chat history, memory, notebooks, KBs+├── partners/<id>/workspace/ # Partner (synthetic-user) scope+├── cli-apps/ # Installed CLI apps, mounted read-only into the sandbox+└── system/ # auth · grants · audit · user-secrets/<owner> (OAuth tokens)```El **primer usuario registrado se convierte en administrador** y controla los catálogos de modelos, las credenciales de proveedor, las bases de conocimiento compartidas, las skills, los libros compartidos canónicos y los permisos por usuario. Para los usuarios locales creados por el administrador se elige Standard, Learner o Custom. Learner bloquea las capacidades de aprendizaje y la política de materiales, añade un perfil adaptativo y admite credenciales de dispositivo revocables con caducidad y límites diarios; los guardianes autorizados pueden ver informes, aprobar materiales y restablecer credenciales. Los demás usuarios obtienen espacios de trabajo aislados y acceso con alcance a modelos, KBs, skills, Partners y libros compartidos sin recibir claves API en bruto. Si `auth.json` ya contiene un `username` + `password_hash`, esa cuenta *es* el administrador: `/register` permanece cerrado y las cuentas creadas desde `/admin/users` siempre tienen `role=user` hasta que las asciendas.@@ -659,7 +684,7 @@ Un binario `deeptutor`, dos formas de entrar: un **REPL** interactivo para quien`deeptutor chat` abre un REPL interactivo y selecciona un modo con `--capability`; `deeptutor run <capability> "<message>"` recibe esa capacidad como primer argumento posicional y sale después de un turno. Ambos aceptan `--tool`, `--kb`, `--config` y `--workspace` para seleccionar un espacio de trabajo registrado.```bash-deeptutor chat # REPL interactivo+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --kb my-kb --tool ragdeeptutor run chat "Explain the Fourier transform" --tool rag --kb textbookdeeptutor run chat "Find recent work beyond this material" --kb textbook --tool knowledge_frontier@@ -677,17 +702,17 @@ La gestión esencial del espacio de trabajo también está disponible aquí —DeepTutor está construido para ser *operado por otro agente*. Agrega `--format json` a cualquier `run` y cada turno transmite **NDJSON — un evento por línea** (`content`, `tool_call`, `tool_result`, `done`, …), cada línea etiquetada con su `session_id`. Las ejecuciones son seguras sin TTY: una pausa `ask_user` sin TTY se resuelve automáticamente con una respuesta vacía en lugar de bloquearse.```bash-# Disparo único, legible por máquina+# One shot, machine-readabledeeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json-# Encadenar turnos en una sesión con estado — captura el id, reutilízalo+# Chain turns in one stateful session — capture the id, reuse itSID=$(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```-El repo incluye un [`SKILL.md`](../../SKILL.md) raíz — un documento de traspaso de ~200 líneas que enseña a cualquier LLM que use herramientas toda la superficie en una lectura. Entrégaselo a Claude Code, Codex u OpenCode (los recogen automáticamente), o envuelve `deeptutor run` como herramienta en un bucle LangChain / AutoGen. Recetas completas: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+El repo incluye un [`SKILL.md`](../../SKILL.md) raíz — un documento de traspaso de ~200 líneas que enseña a cualquier LLM que use herramientas toda la superficie en una lectura. Entrégaselo a Claude Code, Codex u OpenCode (recogen `SKILL.md` automáticamente), o envuelve `deeptutor run` como herramienta en un bucle LangChain / AutoGen. Recetas completas: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>@@ -705,7 +730,7 @@ El repo incluye un [`SKILL.md`](../../SKILL.md) raíz — un documento de traspa| `deeptutor run <capability> <message>` | Ejecutar un turno de capacidad único (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); agrega `--format json` para salida NDJSON || `deeptutor chat` | REPL interactivo con controles de capacidad, herramienta, KB, notebook e historial || `deeptutor partner list/create/start/stop` | Gestionar partners conectados por IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Gestionar bases de conocimiento y sincronizar fuentes de GitHub/web registradas (con comandos para añadir o eliminar fuentes) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Gestionar bases de conocimiento, conectar archivos Kiwix, evaluar la calidad de recuperación con un conjunto de preguntas y respuestas, y sincronizar fuentes de GitHub/web registradas (con comandos para añadir o eliminar fuentes) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Gestionar skills, instalar desde hubs y publicar las propias (`eduhub:<slug>` por defecto, consulta Ecosistema) || `deeptutor memory show/clear` | Inspeccionar documentos de memoria L2/L3 o borrar memoria L1/toda || `deeptutor session list/show/open/rename/delete` | Gestionar sesiones compartidas |@@ -742,18 +767,18 @@ Las skills de DeepTutor usan el formato abierto **Agent-Skills** — una carpeta**Encontrar e instalar** — en el navegador, abre **Learning Space → Skills → Import from EduHub** para navegar el catálogo y descargar una skill directamente en tu biblioteca. Desde la terminal:```bash-deeptutor skill search "socratic tutor" # buscar en EduHub (el hub predeterminado)-deeptutor skill install socratic-tutor # fetch → verificar → registrar-deeptutor skill install eduhub:[email protected] # fijar un hub y una versión-deeptutor skill list # skills locales con su proveniencia del hub+deeptutor skill search "socratic tutor" # search EduHub (the default hub)+deeptutor skill install socratic-tutor # fetch → verify → register+deeptutor skill install eduhub:[email protected] # pin a hub and a version+deeptutor skill list # local skills with their hub provenance```**Publicar la tuya propia** — empaqueta un `SKILL.md` y compártelo con la comunidad:```bash-deeptutor skill login # inicio de sesión en EduHub desde el navegador-deeptutor skill publish ./my-skill # interactivo: elige una pista + etiquetas, luego sube-deeptutor skill update # revertir o lanzar una nueva versión+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 también es un registro independiente compatible con ClawHub, así que los agentes que no son DeepTutor (Claude Code, Codex, …) pueden usarlo directamente a través del CLI `eduhub` — `npx eduhub install socratic-tutor`.diff --git a/assets/README/README_FR.md b/assets/README/README_FR.mdindex 4e15e371a..9e5963264 100644--- a/assets/README/README_FR.md+++ b/assets/README/README_FR.md@@ -10,7 +10,7 @@</p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="Dépôt GitHub tendance du jour" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Classement de l’historique des étoiles" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor est un espace de travail d'apprentissage natif à l'agent qui connecte- **Un seul runtime pour chaque mode** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading et Immersive Watching partagent le même runtime de capacités et le même contexte de session, tout en conservant des boucles et des pipelines conçus pour chaque usage.- **Task Board** — Suivez vos tâches d'étude dans les colonnes À faire, En cours et Terminé, avec des notes, un déplacement par glisser-déposer ou au moyen de boutons accessibles au clavier, et une archive depuis laquelle vous pouvez les restaurer. Les cartes restent dans l'espace de travail actuel et suivent les paramètres d'apparence et de langue existants ; aucune configuration de modèle n'est nécessaire.- **Contexte d'apprentissage connecté** — Les bases de connaissances, les livres, les brouillons Co-Writer, les carnets, les banques de questions, les personas et la Memory peuvent être réutilisés dans les flux de travail qui les prennent en charge, sous réserve des attributions du compte et des politiques d'apprentissage.-- **Apprentissage vidéo immersif** — collez un lien YouTube pour une lecture native avec protection renforcée de la confidentialité, des sous-titres synchronisés, un tutorat ancré dans les horodatages et une progression reprenable ; les administrateurs peuvent basculer la lecture vers une instance Invidious auto-hébergée sans reconstruire les supports.+- **Apprentissage vidéo immersif** — collez un lien YouTube pour une lecture native avec protection renforcée de la confidentialité, des sous-titres synchronisés, un tutorat ancré dans les horodatages, des repères temporels enregistrés et une progression reprenable ; les administrateurs peuvent basculer la lecture vers une instance Invidious auto-hébergée sans reconstruire les supports.- **Sous-agents et Partners** — depuis Chat, consultez un harness d'agent en direct (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw ou DeepSeek) ou un Partner, importez des conversations passées et exécutez des compagnons IM persistants sur le même cerveau.- **Connaissances multi-moteur** — bibliothèques RAG versionnées via LlamaIndex, PageIndex, GraphRAG, LightRAG, un LightRAG Server distant, un déploiement WeKnora auto-hébergé, une bibliothèque Tencent IMA ou MarginNote 4, une archive ZIM Kiwix connectée, ou un vault Obsidian lié, avec une analyse de documents enfichable. Consultez les [modèles de rôle LightRAG natifs](../../deeptutor/services/rag/pipelines/lightrag/README.md) pour des paramètres d'extraction, de requête et de vision indépendants, une création limitée aux valeurs par défaut, et des reconstructions confirmées.- **Outils et compétences extensibles** — outils intégrés, serveurs MCP, applications CLI, modèles de génération d'images / vidéos / voix, et compétences communautaires installables depuis EduHub.@@ -73,7 +73,20 @@ DeepTutor est un espace de travail d'apprentissage natif à l'agent qui connecte## 🚀 Démarrage-DeepTutor propose quatre chemins d'installation. Ils partagent tous une même structure de répertoire d'exécution : les paramètres résident dans `data/user/settings/` sous le répertoire depuis lequel vous lancez l'application (ou sous `DEEPTUTOR_HOME` / `deeptutor start --home` si vous en définissez un explicitement). Pour l'application complète, le flux recommandé est **choisir un répertoire d'exécution → installer → `deeptutor init` → `deeptutor start`**.+DeepTutor propose quatre chemins d'installation. Ils partagent tous une même structure de répertoire d'exécution : les paramètres privés résident dans `data/user/settings/` sous le répertoire depuis lequel vous lancez l'application (ou sous `DEEPTUTOR_HOME` / `deeptutor start --home` si vous en définissez un explicitement). Pour l'application complète, le flux recommandé est **choisir un répertoire d'exécution → installer → `deeptutor init` → `deeptutor start`**.++### Essai Docker en une commande++Si Docker n'est pas encore installé, [installez Docker](https://docs.docker.com/get-docker/) d'abord. Essayez ensuite l'application complète sans configurer Python ni Node.js :++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++Ouvrez [http://127.0.0.1:3782](http://127.0.0.1:3782), configurez les fournisseurs de modèles dans **Paramètres → Fournisseurs**, puis appuyez sur `Ctrl+C` quand vous avez terminé. Le volume nommé `deeptutor-data` conserve les paramètres et les données locales pour la prochaine exécution.### Content Workspace@@ -339,7 +352,7 @@ Tout ce qui se trouve sous `data/user/settings/` est du JSON/YAML brut. La page| `auth.json` | Basculement d'authentification optionnel, nom d'utilisateur, hachage de mot de passe, paramètres de jeton/cookie || `integrations.json` | Paramètres d'intégration PocketBase et sidecar optionnels || `interface.json` | Langue de l'interface et de sortie du modèle / thème / préférences de barre latérale |-| `document_parsing.json` | Choix du moteur d'analyse, points de terminaison distants et options propres à chaque moteur |+| `document_parsing.json` | Choix du moteur d'analyse et du modèle de description d'images, points de terminaison distants et options propres à chaque moteur || `video_learning.json` | Fournisseur de lecture YouTube/Invidious par défaut, origines Invidious et adaptateur de transcription optionnel || `main.yaml` | Valeurs par défaut du comportement d'exécution et injection de chemin || `agents.yaml` | Paramètres de température et de jetons pour les capacités/outils |@@ -360,7 +373,9 @@ Lorsque `trusted_domains` n'est pas vide, les références sont limitées à cesLe fichier `.env` à la racine du projet n'est **pas** lu comme fichier de configuration d'application. Pour une configuration minimale de modèle, enregistrez une URL de base et une clé API dans **Paramètres → Fournisseurs**, puis ajoutez et sélectionnez un LLM dans **Modèles de langage**. Ajoutez un profil d'embedding uniquement si vous prévoyez d'utiliser les fonctionnalités Base de Connaissances / RAG.-Les profils LLM et de modèles de tâche proposent un paramètre de format API lorsque leur fournisseur permet un choix. Conservez `Auto` pour le routage normal et le repli, ou choisissez `OpenAI Chat Completions`, `OpenAI Responses` ou `Anthropic Messages` ; le mode Responses forcé continue d'échouer de manière fermée. Le champ persistant est `api_format` (`auto`, `openai_chat`, `openai_responses` ou `anthropic`) ; `wire_api` est un état de compatibilité dérivé. Les options de remplacement `Auto` / `Supported` / `Not supported` par modèle couvrent l'appel d'outils, l'entrée d'images, la sortie JSON et les contrôles de raisonnement.+Pour API Route, sélectionnez **API Route** dans **Paramètres → Fournisseurs** et saisissez une clé API Route. Le préréglage utilise `https://global.api-route.com/v1` ; ajoutez ensuite un modèle avec son identifiant de modèle API Route dans **Modèles de langage**. Consultez le [guide de démarrage API Route](https://www.api-route.com/docs/quickstart) pour la configuration de la clé et du modèle.++Les profils LLM et de modèles de tâche proposent un paramètre de **format API** lorsque leur fournisseur permet un choix. Conservez `Auto` pour le routage normal et le repli, ou choisissez `OpenAI Chat Completions`, `OpenAI Responses` ou `Anthropic Messages` ; le mode Responses forcé continue d'échouer de manière fermée. Le champ persistant est `api_format` (`auto`, `openai_chat`, `openai_responses` ou `anthropic`) ; `wire_api` est un état de compatibilité dérivé. Les options de remplacement `Auto` / `Supported` / `Not supported` par modèle couvrent l'appel d'outils, l'entrée d'images, la sortie JSON et les contrôles de raisonnement.</details>@@ -432,9 +447,9 @@ La boucle est délibérément simple : le modèle réfléchit en rounds, appelleLes outils basculables par l'utilisateur sont `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason` et `geogebra_analysis` — plus `imagegen` et `videogen` une fois que vous avez configuré le modèle de génération correspondant. Les outils contextuels tels que `rag`, `kb_files`, `knowledge_frontier`, `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` et `workspace_export` se montent automatiquement quand le tour dispose du bon contexte.-Le contexte se présente en deux types : le **contexte de session persistant** (capacité, espace de travail ou cours, outils, bases de connaissances, persona, modèle et état Reading / Mastery) persiste entre les tours ; les **références ponctuelles** (fichiers, historique de chat, livres, sections de lecture, carnets, banque de questions, agents importés) proviennent du menu `+` pour un seul tour. Le bouton vocal ne transcrit que le message en cours.+Le contexte se présente en deux types : le **contexte de session persistant** (capacité, espace de travail ou cours, outils, bases de connaissances, persona, modèle et état Reading / Mastery) persiste entre les tours ; les **références ponctuelles** (fichiers, historique de chat, livres, sections de lecture, carnets, entrées sélectionnées de la banque de questions, agents importés) proviennent du menu `+` pour un seul tour. Le bouton vocal ne transcrit que le message en cours.-L'accueil garde **Chat**, **Ask Questions**, **Quiz** et **Visualize** accessibles en un clic ; **Research** pour les rapports cités, **Solve** pour le raisonnement guidé et **Immersive Watching** se trouvent sous *Plus de Capacités*. **Apprentissage personnalisé** regroupe Book, **Mastery Path**, **Immersive Reading**, Watching et **Practice** ; Reading ajoute des citations vérifiées, des notes enregistrées, des actions de lecture à voix haute / accompagnement d'étude / vocabulaire / quiz / traduction ancrées dans les sources, ainsi que la capture dans les carnets, tandis que Course Study conserve son contexte lié au cours.+L'accueil garde **Chat**, **Ask Questions**, **Quiz** et **Visualize** accessibles en un clic ; **Research** pour les rapports cités, **Solve** pour le raisonnement guidé et **Immersive Watching** se trouvent sous *Plus de Capacités*. **Apprentissage personnalisé** regroupe Book, **Mastery Path**, **Immersive Reading**, Watching et **Practice** ; Reading ajoute des citations vérifiées, des notes enregistrées, une lecture à voix haute naturelle à partir des passages sources et des actions d'accompagnement d'étude / vocabulaire / quiz / traduction, ainsi que la capture dans les carnets, tandis que Course Study conserve son contexte lié au cours.</details>@@ -499,7 +514,7 @@ Co-Writer est un espace de travail Markdown à vue divisée pour les rapports, t<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Éditeur Co-Writer avec aperçu en direct" width="900"></div>-Son idée directrice est l'**édition chirurgicale** : sélectionnez une plage et demandez à DeepTutor de la réécrire, l'étendre ou la raccourcir. L'agent d'édition peut ancrer le changement dans une base de connaissances ou des preuves web et conserve une trace de ses appels d'outils. Si le brouillon n'a pas changé pendant son travail, le résultat remplace directement le texte sélectionné et reste réversible avec **Undo**.+Son idée directrice est l'**édition chirurgicale** : sélectionnez une plage et demandez à DeepTutor de la réécrire, l'étendre ou la raccourcir. Choisissez le modèle d'édition ; il peut utiliser une base de connaissances ou des preuves web et conserve une trace de ses appels d'outils. Si le brouillon n'a pas changé pendant son travail, le résultat remplace directement le texte sélectionné et reste réversible avec **Undo**.</details>@@ -539,12 +554,18 @@ Les bases de connaissances sont les collections de documents derrière le RAGVous migrez une bibliothèque Obsidian, Hermes ou Markdown existante ? Consultez le [guide de migration des connaissances](../../docs-for-user/KNOWLEDGE_MIGRATION.md) pour les parcours de vault connecté et de copie indexée.-Lors de la création d'une KB, vous pouvez **en créer une nouvelle** (téléverser et indexer des documents), **en lier une existante** (réutiliser un index sur place) ou **connecter Kiwix** (interroger à la demande une archive ZIM servie). Choisissez son espace de travail de stockage lors de la création ; une KB existante peut être déplacée entre espaces de travail après un aperçu, tout en conservant ses attributions et ses références enregistrées. Une KB peut aussi suivre des **dépôts GitHub** (dépôt, branche, glob) ou des **URL de sites de documentation** (profondeur d'exploration et nombre de pages limités, resynchronisés toutes les 24 h par défaut) ; la synchronisation compare les empreintes pour détecter les contenus ajoutés, modifiés ou supprimés, afin que la documentation suivie reste à jour sans nouveau téléversement, et les **dossiers liés** récupèrent les fichiers locaux nouveaux ou modifiés lors de la synchronisation. La re-indexation écrit un nouveau répertoire plat `version-N` et conserve les précédents, donc un index fonctionnel n'est jamais détruit en milieu de reconstruction. Un seul document peut être supprimé même d'une base en état d'**erreur** — retirer un fichier dont l'analyse a échoué sans devoir tout supprimer et reconstruire. L'analyse de documents — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM ou LiteParse — est choisie dans **Paramètres → Connaissances & documents**, avec les téléchargements de modèles locaux désactivés par défaut. Docling peut aussi fonctionner en mode **distant** contre un serveur Docling Serve (aucune installation ni modèle local nécessaire), configuré sur cette page (`mode=remote`, une URL de base de serveur, et une clé API optionnelle) ou les variables d'environnement `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika est distant uniquement et pointe vers le serveur Apache Tika configuré sur cette page. La CLI reprend le cycle de vie avec `list/info/create/connect-kiwix/add/search/set-default/delete`, les commandes d'ajout et de suppression de sources, `list-sources` et `sync`.+Lors de la création d'une KB, vous pouvez **en créer une nouvelle** (téléverser et indexer des documents), **en lier une existante** (réutiliser un index sur place) ou **connecter Kiwix** (interroger à la demande une archive ZIM servie). Choisissez son espace de travail de stockage lors de la création ; une KB existante peut être déplacée entre espaces de travail après un aperçu, tout en conservant ses attributions et ses références enregistrées. Une KB peut aussi suivre des **dépôts GitHub** (dépôt, branche, glob) ou des **URL de sites de documentation** (profondeur d'exploration et nombre de pages limités, resynchronisés toutes les 24 h par défaut) ; la synchronisation compare les empreintes pour détecter les contenus ajoutés, modifiés ou supprimés, afin que la documentation suivie reste à jour sans nouveau téléversement, et les **dossiers liés** récupèrent les fichiers locaux nouveaux ou modifiés lors de la synchronisation. La re-indexation écrit un nouveau répertoire plat `version-N` et conserve les précédents, donc un index fonctionnel n'est jamais détruit en milieu de reconstruction. Un seul document peut être supprimé même d'une base en état d'**erreur** — retirer un fichier dont l'analyse a échoué sans devoir tout supprimer et reconstruire. L'analyse de documents — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM ou LiteParse — et un modèle optionnel de description d'images sont choisis dans **Paramètres → Connaissances & documents**, avec les téléchargements de modèles locaux désactivés par défaut. Docling peut aussi fonctionner en mode **distant** contre un serveur Docling Serve (aucune installation ni modèle local nécessaire), configuré sur cette page (`mode=remote`, une URL de base de serveur, et une clé API optionnelle) ou les variables d'environnement `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika est distant uniquement et pointe vers le serveur Apache Tika configuré sur cette page. La CLI reprend le cycle de vie avec `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, les commandes d'ajout et de suppression de sources, `list-sources` et `sync`.Le moteur LightRAG intégré s'installe avec `pip install 'deeptutor[rag-lightrag]'`. Cet extra contient le SDK LightRAG pris en charge mais n'installe pas MinerU. Choisissez MinerU indépendamment dans Analyse de Documents et configurez son mode cloud ou installez sa CLI locale actuelle pour l'analyse structurée. MinerU accepte les PDF, les images raster courantes, les fichiers DOCX, PPTX et XLSX ; l'ancienne commande `magic-pdf` reste limitée aux PDF. Le mode texte seul et les autres moteurs d'analyse n'ont pas besoin de MinerU.Les requêtes LightRAG natives et l'indexation incrémentielle nécessitent la configuration d'embedding enregistrée par l'index publié, incluant le modèle, la dimension et l'identité du point de terminaison. Si elle change, restaurez la configuration d'origine ou reconstruisez avec l'embedding actuel ; les index sans identité d'embedding enregistrée nécessitent une reconstruction. Les vues de détail de la base de connaissances et de version d'index affichent des conseils de récupération, tandis que les fichiers restent disponibles pour la consultation et le téléchargement.+**Évaluer une base de connaissances.** Avec plusieurs moteurs disponibles, « lequel récupère le mieux les informations ici ? » est une question empirique — à laquelle `deeptutor kb eval` apporte une réponse. Rédigez un jeu de questions-réponses (un objet JSON par ligne : une `query` et les passages `gold` qu'une récupération idéale devrait renvoyer), puis évaluez la KB avec `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. Chaque cas est interrogé par le même chemin qu'un tour de chat ; ses citations classées sont comparées aux passages de référence par correspondance exacte du texte ou recouvrement lexical (les seuils sont réglables avec `--min-ratio` ; l'équivalence sémantique n'est pas évaluée), et l'exécution affiche **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. Les métriques sont des fonctions pures du classement, donc aucun modèle ne juge la sortie : les scores sont reproductibles et comparables, et une référence enregistrée transforme le jeu en contrôle de non-régression pour un changement d'embedding, de reranker ou une expérience sur la taille des fragments. Les cas dont la recherche a échoué (index manquant, identifiants incorrects) n'ont pas de score et sont signalés séparément au lieu de faire baisser les moyennes. PageIndex utilise le raisonnement pour la récupération et ne renvoie pas de fragments classés ; il est donc exclu.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -554,7 +575,7 @@ Les requêtes LightRAG natives et l'indexation incrémentielle nécessitent la c<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="Hub Learning Space de DeepTutor" width="900"></div>-Learning Space est la couche de bibliothèque, d'organisation et de personnalisation. **Conversations & Matériaux** contient Chat History, les carnets avec des enregistrements déplaçables et un export Markdown, ainsi qu'une banque de questions avec réponses et explications. **Practice**, dans Apprentissage personnalisé, transforme les questions enregistrées en séances de révision, en suivi des erreurs et en répétitions programmées. **Personnalisation** contient les personas, les compétences (livrets de jeu `SKILL.md`), les **Services MCP** connectables en un clic et les **Applications CLI** du catalogue [CLI-Anything](https://github.com/HKUDS/CLI-Anything), chacune avec un guide d'utilisation chargé à la demande. L'espace de travail distinct **My Courses** regroupe les conversations par matière et les fils du tuteur ; chaque ressource n'est proposée que dans les flux de travail qui la prennent en charge.+Learning Space est la couche de bibliothèque, d'organisation et de personnalisation. **Conversations & Matériaux** contient Chat History, les carnets avec des enregistrements déplaçables et un export Markdown, ainsi qu'une banque de questions avec réponses et explications. Lancez **Practice** depuis une sélection dans la banque de questions ou depuis Apprentissage personnalisé pour des séances de révision, le suivi des erreurs et des répétitions programmées. **Personnalisation** contient les personas, les compétences (livrets de jeu `SKILL.md`), les **Services MCP** connectables en un clic et les **Applications CLI** du catalogue [CLI-Anything](https://github.com/HKUDS/CLI-Anything), chacune avec un guide d'utilisation chargé à la demande. L'espace de travail distinct **My Courses** regroupe les conversations par matière et les fils du tuteur ; chaque ressource n'est proposée que dans les flux de travail qui la prennent en charge.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Importer des compétences depuis EduHub" width="900">@@ -590,6 +611,11 @@ Le Memory Graph montre toute la pyramide — la synthèse L3 au centre, L2 dansSettings est le plan de contrôle opérationnel et s'ouvre sur **Général**, pour la langue de l'interface et de sortie du modèle. Sa navigation avec recherche mène à des pages indépendantes : **Personnel** couvre les espaces de travail, la migration des données, l'apparence et les statistiques d'utilisation ; **Apprentissage & conversation** couvre les suggestions de démarrage, les pièces jointes, Video Learning, les contrôles des apprenants et des responsables, Progression d'apprentissage, ainsi que Memory ; **Modèles & services** couvre les fournisseurs, les modèles de langage, les modèles de tâche, Embedding, la recherche, la voix et la génération multimodale ; **Fonctionnalités & intégrations** couvre les outils, les paramètres des capacités, Partners & agents et Connaissances & documents. **Système** contient Réseau, État d'exécution et À propos ; **Conversations archivées** permet de rechercher, restaurer ou supprimer définitivement les conversations archivées. État d'exécution contient la santé du backend, la mémoire résidente et la matrice **Readiness**, qui évalue les blocages, avertissements et suggestions pour les capacités. Les espaces de travail séparent les fichiers thématiques et l'état d'apprentissage ; Migration des données propose une migration vérifiée et un export. Un **fournisseur** conserve l'adresse et les identifiants d'un prestataire pour ses modèles de service ; les pages des modèles sélectionnent des fournisseurs enregistrés et configurent les noms et capacités des modèles. Les **modèles de tâche** réservent un petit modèle rapide au travail en arrière-plan — nommer les conversations et rédiger les suggestions de démarrage — et utilisent le modèle actif par défaut si le champ est vide. Voix regroupe la synthèse vocale et la transcription ; Génération multimodale regroupe les modèles d'image et de vidéo. Partners & agents configure les harnesses locaux et une passerelle Hermes distante.+**Synthèse vocale Xiaomi MiMo.** Ajoutez un fournisseur Xiaomi MiMo avec `https://api.xiaomimimo.com/v1` et sa clé API, puis ajoutez `mimo-v2.5-tts` dans Paramètres → Voix. Choisissez un préréglage tel que `mimo_default`, `冰糖` ou `苏打`, utilisez une sortie `wav` ou `pcm16`, puis écoutez un aperçu avant de l'appliquer. Les instructions vocales contrôlent le style et la vitesse de parole. Cet adaptateur ne prend en charge que les voix prédéfinies ; la conception et le clonage de voix nécessitent des modèles distincts et ne sont pas pris en charge. Si un ancien modèle vocal MiMo était configuré via l'adaptateur générique compatible OpenAI, recréez son entrée vocale avec le fournisseur Xiaomi MiMo afin qu'elle utilise le protocole chat-completions. Consultez le [guide officiel de synthèse vocale MiMo](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**Synthèse vocale MiniMax** — dans Paramètres → Voix, choisissez MiniMax pour la synthèse vocale et sélectionnez `speech-2.8-hd`. Configurez une clé API MiniMax et un identifiant de voix système ou personnalisé ; la voix par défaut est `English_expressive_narrator`. L'URL de base de l'API est `https://api.minimax.io/v1` par défaut ; pour la région Chine, utilisez `https://api.minimaxi.com/v1`. La lecture à voix haute et les aperçus vocaux utilisent le point de terminaison vocal natif, avec une sortie MP3, WAV, FLAC ou PCM et des contrôles de fréquence d'échantillonnage, de vitesse et de langue. Consultez l'[API de synthèse vocale MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http) pour les identifiants de voix et la disponibilité selon le compte.++**Video Learning** sous Paramètres → Apprentissage & conversation utilise par défaut le YouTube IFrame Player officiel avec protection renforcée de la confidentialité. Pour conserver la lecture locale, définissez l'origine de l'API Invidious gérée par l'administrateur (par exemple `http://127.0.0.1:3000`), testez-la, sélectionnez Invidious, puis enregistrez. Les vidéos nouvelles ou rouvertes adoptent immédiatement le fournisseur tout en conservant le même ID de support et la même progression. Les médias Invidious sont diffusés via le proxy byte-range de DeepTutor ; les URL en amont ne sont ni exposées au navigateur ni stockées sur disque. En cas de défaillance de l'instance, DeepTutor reste hors connexion à YouTube jusqu'à ce que l'apprenant choisisse explicitement la solution de repli YouTube native. Le tutorat basé sur les sous-titres publics est optionnel : installez `.[video-learning]` ; la lecture continue sans cet extra, tandis que la fonction **Explain here** basée sur les transcriptions est désactivée avec une explication.<div align="center">@@ -706,7 +732,7 @@ Le dépôt inclut un [`SKILL.md`](../../SKILL.md) racine — un document de pass| `deeptutor run <capability> <message>` | Exécuter un seul tour de capacité (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`) ; ajoutez `--format json` pour la sortie NDJSON || `deeptutor chat` | REPL interactif avec contrôles de capacité, outil, KB, carnet et historique || `deeptutor partner list/create/start/stop` | Gérer les partners connectés à IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Gérer les bases de connaissances et synchroniser les sources GitHub/web enregistrées (avec les commandes d'ajout et de suppression de sources) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Gérer les bases de connaissances, connecter des archives Kiwix, évaluer la qualité de récupération avec un jeu de questions-réponses et synchroniser les sources GitHub/web enregistrées (avec les commandes d'ajout et de suppression de sources) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Gérer les compétences, installer depuis les hubs et publier les siennes (`eduhub:<slug>` par défaut, voir Écosystème) || `deeptutor memory show/clear` | Inspecter les documents de mémoire L2/L3 ou effacer la mémoire L1/toute || `deeptutor session list/show/open/rename/delete` | Gérer les sessions partagées |diff --git a/assets/README/README_HI.md b/assets/README/README_HI.mdindex fc66b8973..18d332aab 100644--- a/assets/README/README_HI.md+++ b/assets/README/README_HI.md@@ -10,7 +10,7 @@</p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub पर दिन की ट्रेंडिंग रिपॉज़िटरी" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="स्टार इतिहास रैंक" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor एक agent-native learning workspace है जो tutoring, problem- **हर मोड के लिए एक रनटाइम** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading और Immersive Watching एक ही capability runtime और session context share करते हैं, जबकि हर उद्देश्य के लिए बने loops और pipelines बनाए रखते हैं।- **Task Board** — पढ़ाई के tasks को To do, In progress और Done में track करें, notes, drag-and-drop या keyboard से सुलभ move buttons, और restore किए जा सकने वाले archive के साथ। Cards current workspace में रहते हैं और मौजूदा appearance और language settings का पालन करते हैं; किसी model configuration की जरूरत नहीं है।- **जुड़ा हुआ लर्निंग कॉन्टेक्स्ट** — Knowledge bases, books, Co-Writer drafts, notebooks, question banks, personas, और Memory को उन workflows में reuse किया जा सकता है जो उन्हें support करते हैं, account grants और learning policies के अधीन।-- **इमर्सिव वीडियो लर्निंग** — privacy-enhanced native playback, synchronized captions, timestamp-grounded tutoring और resumable progress के लिए एक YouTube link paste करें; administrators materials को rebuild किए बिना playback को self-hosted Invidious instance पर switch कर सकते हैं।+- **इमर्सिव वीडियो लर्निंग** — privacy-enhanced native playback, synchronized captions, timestamp-grounded tutoring, सहेजे गए timestamp marks और resumable progress के लिए एक YouTube link paste करें; administrators materials को rebuild किए बिना playback को self-hosted Invidious instance पर switch कर सकते हैं।- **सब-एजेंट और Partners** — Chat से एक live agent harness (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw, या DeepSeek) या एक Partner से सलाह लें, पिछली conversations import करें, और same brain पर persistent IM companions चलाएं।- **मल्टी-इंजन नॉलेज** — LlamaIndex, PageIndex, GraphRAG, LightRAG, एक remote LightRAG Server, एक self-hosted WeKnora knowledge base, एक Tencent IMA या MarginNote 4 library, एक connected Kiwix ZIM archive, या एक linked Obsidian vault के साथ versioned RAG libraries, pluggable document parsing के साथ। independent extraction, query और vision settings, default-only creation और confirmed rebuilds के लिए [native LightRAG role models](../../deeptutor/services/rag/pipelines/lightrag/README.md) देखें।- **एक्सटेंसिबल टूल्स और स्किल्स** — built-in tools, MCP servers, CLI apps, image / video / voice generation models, और EduHub से installable community skills।@@ -75,7 +75,20 @@ DeepTutor एक agent-native learning workspace है जो tutoring, problemDeepTutor चार installation paths के साथ आता है। वे सभी एक runtime-home layout साझा करते हैं: private settings उस directory के नीचे `data/user/settings/` में रहती हैं जहां से आप launch करते हैं (या `DEEPTUTOR_HOME` / `deeptutor start --home` के नीचे अगर आप explicitly set करते हैं)। पूरे app के लिए, recommended flow है **एक runtime-home directory चुनें → install करें → `deeptutor init` → `deeptutor start`**।-### Content Workspace+### एक कमांड से Docker आज़माएं++अगर Docker अभी install नहीं है, तो पहले [Docker install करें](https://docs.docker.com/get-docker/)। फिर Python या Node.js setup किए बिना पूरा app आज़माएं:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++[http://127.0.0.1:3782](http://127.0.0.1:3782) खोलें, **Settings → Providers** में model providers configure करें, और काम पूरा होने पर `Ctrl+C` दबाएं। Named `deeptutor-data` volume settings और local data को अगले run के लिए रखता है।++### सामग्री कार्यक्षेत्र**Content Workspace** DeepTutor के private runtime home से अलग है। यह वह folder है जिसे agents पढ़ सकते हैं; generated files `outputs/<capability>/<session>/<turn>/` के अंदर रहती हैं। Custom workspaces conversations, learning materials, progress और caches को एक private `.deeptutor/data/` tree में अलग रखते हैं जिसे file tools browse नहीं कर सकते। Settings, credentials और Memory account level पर shared रहते हैं।@@ -94,7 +107,7 @@ Learning Space resource library manage करता है। **Settings → Wor`outputs/` के बाहर execution read-only है। Content workspace में कहीं और किसी generated file को copy करने के लिए उस exact source और destination के लिए एक explicit **Allow once** confirmation चाहिए। उपलब्ध होने पर एक system sandbox या Docker runner इस boundary को enforce करता है; local restricted-subprocess fallback को Workspace settings में **best effort** के रूप में दिखाया जाता है।<details>-<summary><b>Option 1 — PyPI से Install करें</b> · पूरा local Web app + CLI, clone की जरूरत नहीं</summary>+<summary><b>विकल्प 1 — PyPI से इंस्टॉल करें</b> · पूरा local Web app + CLI, clone की जरूरत नहीं</summary>पूरा local Web app + CLI, clone की जरूरत नहीं। **Python 3.11–3.14** और PATH पर **Node.js 20+** runtime चाहिए (`deeptutor start` packaged Next.js standalone server को spawn करता है)।@@ -114,7 +127,7 @@ deeptutor start # starts backend + frontend; keep the terminal open</details><details>-<summary><b>Option 2 — Source से Install करें</b> · checkout के विरुद्ध develop करें</summary>+<summary><b>विकल्प 2 — स्रोत से इंस्टॉल करें</b> · checkout के विरुद्ध develop करें</summary>Checkout के विरुद्ध development के लिए। CI और Docker से match करने के लिए **Python 3.11–3.14** और **Node.js 22 LTS** उपयोग करें।@@ -138,7 +151,7 @@ deeptutor start --dev`deeptutor start` local `web/` frontend को production के लिए एक बार build करता है और उसे reuse करता है; `--dev` Next.js को HMR के साथ run करता है। Config layout, ports, और `Ctrl+C` Option 1 से match करते हैं।<details>-<summary><b>Conda environment</b> (<code>venv</code> की बजाय)</summary>+<summary><b>Conda एनवायरनमेंट</b> (<code>venv</code> की बजाय)</summary>```bashconda create -n deeptutor python=3.11@@ -149,7 +162,7 @@ python -m pip install --upgrade pip</details><details>-<summary><b>वैकल्पिक install extras</b> — RAG engines / dev / partners / matrix / math-animator</summary>+<summary><b>वैकल्पिक इंस्टॉल extras</b> — RAG engines / dev / partners / matrix / math-animator</summary>```bashpip install -e ".[rag-lightrag]" # Built-in LightRAG engine (exact supported SDK)@@ -165,7 +178,7 @@ pip install -e ".[math-animator]" # Manim addon; requires LaTeX/ffmpeg/system</details><details>-<summary><b>Frontend dependency tweaks और dev-server troubleshooting</b></summary>+<summary><b>Frontend dependencies में बदलाव और dev-server समस्याओं का समाधान</b></summary>**Frontend dependencies बदलना:** `web/package-lock.json` refresh करने के लिए `npm install --legacy-peer-deps` run करें, फिर `web/package.json` और `web/package-lock.json` दोनों को commit करें।@@ -181,7 +194,7 @@ deeptutor start --dev</details><details>-<summary><b>Option 3 — Docker</b> · एक self-contained container</summary>+<summary><b>विकल्प 3 — Docker</b> · एक self-contained container</summary>पूरे Web app के लिए एक container। GitHub Container Registry पर images:@@ -236,7 +249,7 @@ Compose के लिए, `python scripts/docker_compose.py up -d` चलान```<details>-<summary><b>Host पर Ollama / LM Studio / llama.cpp / vLLM / Lemonade से Connect करना</b></summary>+<summary><b>Host पर Ollama / LM Studio / llama.cpp / vLLM / Lemonade से जुड़ना</b></summary>Docker के अंदर, `localhost` container itself है, आपका host machine नहीं। Host पर चल रहे model service तक पहुंचने के लिए, host gateway उपयोग करें (recommended):@@ -265,7 +278,7 @@ Docker Desktop (macOS/Windows) आमतौर पर `--add-host` के बि</details><details>-<summary><b>Option 4 — केवल CLI</b> · कोई Web UI नहीं, source checkout से</summary>+<summary><b>विकल्प 4 — केवल CLI</b> · कोई Web UI नहीं, source checkout से</summary>जब आपको Web UI की जरूरत न हो। CLI-only package PyPI से नहीं, source checkout से install होता है।@@ -286,7 +299,7 @@ deeptutor chat`deeptutor init --cli` पूरे app के समान `data/user/settings/` layout share करता है लेकिन backend/frontend port prompts skip करता है। यह फिर भी Embedding और Search selectors offer करता है (जरूरत न हो तो **Skip** चुनें), मुख्य runtime files (`system.json`, `auth.json`, `integrations.json`, `interface.json`, `model_catalog.json`, `main.yaml`, `agents.yaml`) लिखता है, और active LLM provider और model के लिए prompt करता है।<details>-<summary><b>सामान्य commands</b></summary>+<summary><b>सामान्य कमांड</b></summary>```bashdeeptutor chat # interactive REPL@@ -305,7 +318,7 @@ Local `deeptutor-cli` install में कोई Web assets या server depen</details><details>-<summary><b>Code Execution Sandbox (office skills)</b> · docx / pdf / pptx / xlsx के लिए model-generated code run करना</summary>+<summary><b>कोड निष्पादन Sandbox (office skills)</b> · docx / pdf / pptx / xlsx के लिए model-generated code run करना</summary>Built-in office skills — **docx / pdf / pptx / xlsx** — model द्वारा एक short Python script (`python-docx`, `reportlab`, `openpyxl`, …) लिखकर, इसे केवल `exec` tool के जरिए run करके, और saved workspace file present करके काम करती हैं। यह tool तब mount होता है जब एक sandbox backend active होता है। DeepTutor इस क्रम में सबसे मजबूत configured backend चुनता है:@@ -318,18 +331,18 @@ Built-in office skills — **docx / pdf / pptx / xlsx** — model द्वा</details><details>-<summary><b>Configuration reference</b> — <code>data/user/settings/</code> के नीचे config files (JSON/YAML)</summary>+<summary><b>कॉन्फ़िगरेशन संदर्भ</b> — <code>data/user/settings/</code> के नीचे config files (JSON/YAML)</summary>`data/user/settings/` के नीचे सब कुछ plain JSON/YAML है। **Settings** page recommended editor है; workspace registrations अलग से `data/user/.runtime/workspaces.sqlite3` में रहते हैं।-| File | उद्देश्य |+| फ़ाइल | उद्देश्य ||:---|:---|| `model_catalog.json` | Provider connections और LLM, task, embedding, search, TTS, STT, image व video profiles, credentials, और active selections || `system.json` | Backend/frontend ports, public API base, CORS, SSL verification, attachment directory और upload/extraction limits |-| `auth.json` | Optional auth toggle, username, password hash, token/cookie settings |+| `auth.json` | वैकल्पिक authentication toggle, username, password hash और token/cookie settings || `integrations.json` | Optional PocketBase और sidecar integration settings || `interface.json` | UI और model output language / theme / sidebar preferences |-| `document_parsing.json` | Parsing engine selection, remote endpoints और engine-specific options |+| `document_parsing.json` | Parsing engine और image-description model का चयन, remote endpoints और engine-specific options || `video_learning.json` | Default YouTube/Invidious playback provider, Invidious origins, और optional transcript adapter || `main.yaml` | Runtime behavior defaults और path injection || `agents.yaml` | Capability/tool temperature और token settings |@@ -350,12 +363,14 @@ Web Search references default रूप से filter होते हैं:Project-root `.env` application config file के रूप में **नहीं** पढ़ा जाता। Minimal model setup के लिए, **Settings → Providers** में Base URL और API key save करें, फिर **Language models** में एक LLM add और select करें। Embedding profile केवल तभी add करें जब आप Knowledge Base / RAG features उपयोग करने की योजना रखते हों।+API Route के लिए, **Settings → Providers** में **API Route** चुनें और API Route key दर्ज करें। Preset `https://global.api-route.com/v1` उपयोग करता है; फिर **Language models** में उसके API Route model ID से model जोड़ें। Key और model setup के लिए [API Route quickstart](https://www.api-route.com/docs/quickstart) देखें।+LLM और task-model profiles तब **API format** setting expose करते हैं जब उनका provider choices support करता है। सामान्य routing और fallback के लिए `Auto` रखें, या `OpenAI Chat Completions`, `OpenAI Responses`, अथवा `Anthropic Messages` चुनें; Forced Responses mode fail-closed रहता है। Persist किया गया field `api_format` है (`auto`, `openai_chat`, `openai_responses`, या `anthropic`); `wire_api` derived compatibility state है। Per-model `Auto` / `Supported` / `Not supported` overrides tool calling, image input, JSON output, और reasoning controls को cover करते हैं।</details><details>-<summary><b>Uninstall और cleanup</b></summary>+<summary><b>अनइंस्टॉल करना और सफ़ाई</b></summary>DeepTutor अपने installed code, private runtime home, और optional Content Workspace को अलग रखता है। Default रूप से runtime home वही directory है जहां आप `deeptutor init` / `deeptutor start` चलाते हैं; `--home PATH` या `DEEPTUTOR_HOME` इसे override करता है। Private application state उस home के भीतर `data` directory में होता है, इसलिए startup banner में `Workspace:` से शुरू होने वाली line उस runtime location की पहचान कराती है। अगर **Settings → Workspace** किसी दूसरे folder की ओर point करता है, तो उस content folder को अलग से backup या remove करें; यह DeepTutor uninstall करने पर जानबूझकर erase नहीं होता।@@ -397,7 +412,7 @@ DeepTutor अपने installed code, private runtime home, और optional Con> **Screenshot स्थिति:** overview v1.6.5 के लिए current है। नीचे दी गई surface screenshots अभी v1.4.6 references हैं और versioned refresh जारी है। इन्हें workflows समझने के लिए उपयोग करें, current exact navigation के रूप में नहीं।<details>-<summary><b>🏗️ System architecture</b></summary>+<summary><b>🏗️ सिस्टम आर्किटेक्चर</b></summary><div align="center"><img src="../../assets/figs/system/system%20architecture.png" alt="DeepTutor सिस्टम आर्किटेक्चर" width="900">@@ -406,7 +421,7 @@ DeepTutor अपने installed code, private runtime home, और optional Con</details><details>-<summary><b>💬 Chat — वह Agent Loop जो आप Actually उपयोग करते हैं</b></summary>+<summary><b>💬 Chat — आपके दैनिक उपयोग का एजेंट लूप</b></summary>Chat default capability है और जहां से अधिकांश काम शुरू होता है। एक single thread normally बात कर सकता है, tools call कर सकता है, selected knowledge bases में खुद को ground कर सकता है, attachments पढ़ सकता है, images generate कर सकता है, subagents से consult कर सकता है, notebook records लिख सकता है, और turns के पार same context के साथ जारी रह सकता है।@@ -422,14 +437,14 @@ Loop जानबूझकर simple है: model rounds में सोचतUser-toggleable tools हैं `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason`, और `geogebra_analysis` — साथ ही `imagegen` और `videogen` जब आप matching generation model configure करें। Contextual tools जैसे `rag`, `kb_files`, `knowledge_frontier`, `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` तब automatically mount होते हैं जब turn के पास सही context हो।-Context दो प्रकार की होती है: **sticky session context** (capability, workspace या course, tools, knowledge bases, persona, model, और Reading / Mastery state) turns के पार persist करती है; **एक-बार references** (files, chat history, books, reading sections, notebooks, question bank, imported agents) एक single turn के लिए `+` menu से आते हैं। Voice button केवल current message को transcribe करता है।+Context दो प्रकार की होती है: **sticky session context** (capability, workspace या course, tools, knowledge bases, persona, model, और Reading / Mastery state) turns के पार persist करती है; **एक-बार references** (files, chat history, books, reading sections, notebooks, चुनी हुई question-bank entries, imported agents) एक single turn के लिए `+` menu से आते हैं। Voice button केवल current message को transcribe करता है।-Home **Chat**, **Ask Questions**, **Quiz**, और **Visualize** को एक क्लिक की दूरी पर रखता है; cited reports के लिए **Research**, worked reasoning के लिए **Solve**, और **Immersive Watching** *More Capabilities* के नीचे रहते हैं। **Personalized Learning** में Book, **Mastery Path**, **Immersive Reading**, Watching और **Practice** एक साथ हैं; Reading verified citations, saved notes, source-grounded read-aloud / study guidance / vocabulary / quiz / translation actions, और notebook capture जोड़ता है, जबकि Course Study अपना course-bound context बनाए रखता है।+Home **Chat**, **Ask Questions**, **Quiz**, और **Visualize** को एक क्लिक की दूरी पर रखता है; cited reports के लिए **Research**, worked reasoning के लिए **Solve**, और **Immersive Watching** *More Capabilities* के नीचे रहते हैं। **Personalized Learning** में Book, **Mastery Path**, **Immersive Reading**, Watching और **Practice** एक साथ हैं; Reading verified citations, saved notes, source passages का स्वाभाविक read-aloud / study guidance / vocabulary / quiz / translation actions, और notebook capture जोड़ता है, जबकि Course Study अपना course-bound context बनाए रखता है।</details><details>-<summary><b>🤝 Partner — Same Brain पर Persistent Companions</b></summary>+<summary><b>🤝 Partner — एक ही बुद्धि पर चलने वाले स्थायी साथी</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/partners/00-partners%20overview.png" alt="DeepTutor Partners workspace" width="900">@@ -454,7 +469,7 @@ Channel layer schema-driven है और installed extras और configured cre</details><details>-<summary><b>🧑🚀 My Agents — दूसरे Agents को Consult और Import करें</b></summary>+<summary><b>🧑🚀 My Agents — दूसरे एजेंट से सलाह लें और उन्हें इम्पोर्ट करें</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/myagents/00-overview.png" alt="DeepTutor My Agents workspace" width="900">@@ -477,7 +492,7 @@ Grok अपनी खुद की authentication और session storage उप</details><details>-<summary><b>✍️ Co-Writer — Selection-Aware Markdown Drafting</b></summary>+<summary><b>✍️ Co-Writer — चुने हुए पाठ के अनुसार Markdown लेखन</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/co-writer/00-overview.png" alt="DeepTutor Co-Writer workspace" width="900">@@ -489,12 +504,12 @@ Co-Writer reports, tutorials, notes, और long-form learning artifacts के<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="live preview वाला Co-Writer editor" width="900"></div>-इसका defining idea **surgical editing** है: एक span select करें और DeepTutor से rewrite, expand, या shorten करने के लिए कहें। Edit agent change को एक knowledge base या web evidence में ground कर सकता है और अपने tool calls का trace रखता है। अगर उसके काम के दौरान draft नहीं बदला है, तो result selected text को directly replace करता है और **Undo** से reversible रहता है।+इसका defining idea **surgical editing** है: एक span select करें और DeepTutor से rewrite, expand, या shorten करने के लिए कहें। Edit model चुनें; वह knowledge base या web evidence उपयोग कर सकता है और अपने tool calls का trace रखता है। अगर उसके काम के दौरान draft नहीं बदला है, तो result selected text को directly replace करता है और **Undo** से reversible रहता है।</details><details>-<summary><b>📖 Book — आपकी सामग्री से Living Books</b></summary>+<summary><b>📖 Book — आपकी सामग्री से जीवंत पुस्तकें</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/book/00-book_overview.png" alt="DeepTutor पुस्तक लाइब्रेरी" width="900">@@ -515,7 +530,7 @@ Book selected sources को एक interactive **living book** में बद</details><details>-<summary><b>📚 Knowledge Center — Multi-Engine RAG Libraries</b></summary>+<summary><b>📚 Knowledge Center — कई इंजन वाली RAG लाइब्रेरी</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/knowledge/00-overview.png" alt="DeepTutor ज्ञान केंद्र" width="900">@@ -529,22 +544,28 @@ Knowledge bases RAG के पीछे document collections हैं — वExisting Obsidian, Hermes, या Markdown library migrate कर रहे हैं? Connected-vault और indexed-copy paths के लिए [Knowledge migration guide](../../docs-for-user/KNOWLEDGE_MIGRATION.md) देखें।-KB बनाते समय, आप **नया create** कर सकते हैं (documents upload और index करें), **existing link** कर सकते हैं (कहीं और बने index को in-place reuse करें), या **Kiwix connect** कर सकते हैं (serve किए गए एक ZIM archive में जरूरत पर search करें)। Creation के समय उसका storage workspace चुनें; existing KB को preview के बाद workspaces के बीच move किया जा सकता है, जबकि assignments और saved references बने रहते हैं। एक KB **GitHub repositories** (repo, branch, glob) या **documentation-site URLs** (सीमित crawl depth और page count, default रूप से हर 24 घंटे में re-sync) को भी track कर सकती है; sync added, changed, और removed content का hash-diff करती है, इसलिए जो documentation आप follow करते हैं वह re-upload किए बिना current बनी रहती है, और **linked folders** sync पर नई या बदली हुई local files pick up करते हैं। Re-indexing एक नई flat `version-N` directory लिखता है और prior ones रखता है, इसलिए एक working index rebuild के दौरान कभी destroy नहीं होता। एक single document को **error**-state base से भी remove किया जा सकता है — पूरी delete-and-rebuild के बिना parse होने में failed हुई file को drop करना। Document parsing — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM, या LiteParse — **Settings → Knowledge & documents** में choose किया जाता है, local model downloads default रूप से off हैं। Docling को **remote** mode में भी एक Docling Serve server के विरुद्ध चलाया जा सकता है (कोई local install या models की जरूरत नहीं), जिसे उसी page पर (`mode=remote`, एक server base URL, और एक optional API key) या `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` environment variables के जरिए configure किया जाता है। Tika remote-only है और उस page पर configured Apache Tika server पर point करता है। CLI lifecycle को `list/info/create/connect-kiwix/add/search/set-default/delete`, source add/remove commands, `list-sources`, और `sync` से mirror करता है।+KB बनाते समय, आप **नया create** कर सकते हैं (documents upload और index करें), **existing link** कर सकते हैं (कहीं और बने index को in-place reuse करें), या **Kiwix connect** कर सकते हैं (serve किए गए एक ZIM archive में जरूरत पर search करें)। Creation के समय उसका storage workspace चुनें; existing KB को preview के बाद workspaces के बीच move किया जा सकता है, जबकि assignments और saved references बने रहते हैं। एक KB **GitHub repositories** (repo, branch, glob) या **documentation-site URLs** (सीमित crawl depth और page count, default रूप से हर 24 घंटे में re-sync) को भी track कर सकती है; sync added, changed, और removed content का hash-diff करती है, इसलिए जो documentation आप follow करते हैं वह re-upload किए बिना current बनी रहती है, और **linked folders** sync पर नई या बदली हुई local files pick up करते हैं। Re-indexing एक नई flat `version-N` directory लिखता है और prior ones रखता है, इसलिए एक working index rebuild के दौरान कभी destroy नहीं होता। एक single document को **error**-state base से भी remove किया जा सकता है — पूरी delete-and-rebuild के बिना parse होने में failed हुई file को drop करना। Document parsing — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM, या LiteParse — और एक optional image-description model **Settings → Knowledge & documents** में चुने जाते हैं, local model downloads default रूप से off हैं। Docling को **remote** mode में भी एक Docling Serve server के विरुद्ध चलाया जा सकता है (कोई local install या models की जरूरत नहीं), जिसे उसी page पर (`mode=remote`, एक server base URL, और एक optional API key) या `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` environment variables के जरिए configure किया जाता है। Tika remote-only है और उस page पर configured Apache Tika server पर point करता है। CLI lifecycle को `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, source add/remove commands, `list-sources`, और `sync` से mirror करता है।Built-in LightRAG engine `pip install 'deeptutor[rag-lightrag]'` से install होता है। उस extra में supported LightRAG SDK शामिल है लेकिन यह MinerU install नहीं करता। Document Parsing में MinerU को स्वतंत्र रूप से चुनें और structured parsing चाहिए हो तो या तो इसका cloud mode configure करें या इसका current local CLI install करें। MinerU PDF, common raster images, DOCX, PPTX, और XLSX स्वीकार करता है; legacy `magic-pdf` command PDF-only रहता है। Text-only और बाकी parsing engines को MinerU की जरूरत नहीं होती।Native LightRAG queries और incremental indexing को उस embedding configuration की जरूरत होती है जो published index द्वारा record की गई है, जिसमें model, dimension, और endpoint identity शामिल हैं। अगर यह बदल जाती है, तो original configuration restore करें या current embedding के साथ rebuild करें; जिन indexes में recorded embedding identity नहीं है उन्हें rebuild करना जरूरी है। Knowledge-base detail और index-version views recovery guidance दिखाते हैं, जबकि files viewing और download के लिए उपलब्ध रहती हैं।+**Knowledge base का मूल्यांकन।** कई engines उपलब्ध हों, तो “यहां कौन सबसे अच्छा retrieval करता है?” का जवाब परीक्षण से मिलता है — `deeptutor kb eval` यही करता है। एक QA set लिखें (हर line पर एक JSON object: एक `query` और `gold` passages जो आदर्श retrieval में मिलने चाहिए), फिर `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]` से KB का मूल्यांकन करें। हर case उसी path से retrieve होता है जो chat turn उपयोग करता है; उसके ranked citations को exact text या lexical overlap से gold passages के साथ match किया जाता है (thresholds `--min-ratio` से बदले जा सकते हैं; semantic equivalence का मूल्यांकन नहीं होता), और run **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k** report करता है। Metrics ranking पर pure functions हैं, इसलिए कोई model output को judge नहीं करता: scores reproducible हैं और उनका diff किया जा सकता है। Saved baseline इस set को embedding बदलने, reranker बदलने या chunk-size experiment के लिए regression gate बनाता है। जिन cases की search fail हुई (missing index या गलत credentials), उनका score नहीं होता और उन्हें अलग report किया जाता है, जिससे वे averages को नीचे नहीं खींचते। PageIndex retrieval के लिए reasoning उपयोग करता है और ranked chunks नहीं लौटाता, इसलिए उसे शामिल नहीं किया जाता।++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>-<summary><b>🌐 Learning Space — Skills, Personas, और Reusable Context</b></summary>+<summary><b>🌐 Learning Space — Skills, Personas और दोबारा उपयोग योग्य संदर्भ</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor Learning Space केंद्र" width="900"></div>-Learning Space library, organization, और personalization layer है। **Conversations & Materials** में Chat History, movable records और Markdown export वाले notebooks, तथा answers और explanations वाला question bank है। Personalized Learning में **Practice** saved questions को review sessions, mistake tracking और scheduled repetition में बदलता है। **Personalization** में personas, skills (`SKILL.md` playbooks), one-click **MCP Services**, और [CLI-Anything](https://github.com/HKUDS/CLI-Anything) catalog के **CLI Apps** हैं, जिनकी usage guide on-demand load होती है। अलग **My Courses** workspace subject conversations और tutor threads को group करता है; हर asset केवल उन workflows में उपलब्ध होता है जो उसे support करते हैं।+Learning Space library, organization, और personalization layer है। **Conversations & Materials** में Chat History, movable records और Markdown export वाले notebooks, तथा answers और explanations वाला question bank है। Review sessions, mistake tracking और scheduled repetition के लिए question bank में चुने गए प्रश्नों या Personalized Learning से **Practice** शुरू करें। **Personalization** में personas, skills (`SKILL.md` playbooks), one-click **MCP Services**, और [CLI-Anything](https://github.com/HKUDS/CLI-Anything) catalog के **CLI Apps** हैं, जिनकी usage guide on-demand load होती है। अलग **My Courses** workspace subject conversations और tutor threads को group करता है; हर asset केवल उन workflows में उपलब्ध होता है जो उसे support करते हैं।<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="EduHub से skills import करें" width="900">@@ -555,7 +576,7 @@ Learning Space library, organization, और personalization layer है। **C</details><details>-<summary><b>🧠 Memory — Inspectable Personalization</b></summary>+<summary><b>🧠 Memory — जांचा जा सकने वाला वैयक्तिकरण</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/memory/00-overview.png" alt="DeepTutor memory अवलोकन" width="900">@@ -572,7 +593,7 @@ Memory Graph पूरा pyramid दिखाता है — L3 synthesis cen</details><details>-<summary><b>⚙️ Settings — एक Control Plane</b></summary>+<summary><b>⚙️ Settings — नियंत्रण का एक केंद्र</b></summary><div align="center"><img src="../../assets/figs/web-1.4.6+/settings/00-setting%20overview.png" alt="DeepTutor Settings केंद्र" width="900">@@ -580,6 +601,10 @@ Memory Graph पूरा pyramid दिखाता है — L3 synthesis cenSettings operational control plane है, जो interface और model output language के लिए **General** पर खुलता है। इसका searchable navigator independent pages से जोड़ता है: **Personal** में Workspaces, Data migration, Appearance और Usage statistics हैं; **Learning & conversation** में starting points, attachments, Video Learning, learner और guardian controls, Learning progress, तथा Memory हैं; **Models & services** में Providers, Language models, Task models, Embedding, Search, Voice और Multimodal generation हैं; **Features & integrations** में tools, capability parameters, Partners & agents और Knowledge & documents हैं। **System** में Network, Runtime status और About हैं; **Archived chats** archived conversations खोजने, restore करने या permanently delete करने देता है। Runtime status में backend health, resident memory और capability blockers, warnings तथा suggestions बताने वाला **Readiness** matrix है। Workspaces topic files और learning state अलग रखता है, जबकि Data migration में verified migration और export उपलब्ध हैं। एक **provider** vendor का address और credential रखता है ताकि उसके service models उन्हें reuse कर सकें; model pages saved providers चुनते हैं और model names तथा capabilities configure करते हैं। **Task models** background work — conversations को नाम देना और starting points लिखना — के लिए छोटा, तेज़ model pin करते हैं, और खाली होने पर active default उपयोग करते हैं। Voice में speech synthesis और transcription एक साथ हैं; Multimodal generation में image और video models हैं। Partners & agents local harnesses और remote Hermes gateway configure करता है।+**Xiaomi MiMo वाक् संश्लेषण।** `https://api.xiaomimimo.com/v1` और उसकी API key के साथ Xiaomi MiMo provider जोड़ें, फिर Settings → Voice में `mimo-v2.5-tts` जोड़ें। `mimo_default`, `冰糖` या `苏打` जैसा preset चुनें, `wav` या `pcm16` output उपयोग करें, और apply करने से पहले उसकी आवाज़ सुनकर जांचें। Voice instructions शैली और बोलने की गति नियंत्रित करते हैं। यह adapter केवल preset speech support करता है; voice design और voice cloning के लिए अलग models चाहिए और वे supported नहीं हैं। अगर पुराना MiMo speech model generic OpenAI-compatible adapter से configure किया गया था, तो Xiaomi MiMo provider से उसकी speech entry फिर बनाएं ताकि वह chat-completions protocol उपयोग करे। [आधिकारिक MiMo वाक् संश्लेषण गाइड](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5) देखें।++**MiniMax वाक् संश्लेषण** — Settings → Voice में text-to-speech के लिए MiniMax चुनें और `speech-2.8-hd` select करें। MiniMax API key और system या custom voice ID configure करें; default voice `English_expressive_narrator` है। Default API base `https://api.minimax.io/v1` है; China region के लिए `https://api.minimaxi.com/v1` उपयोग करें। Read-aloud और voice previews native speech endpoint उपयोग करते हैं, जिसमें MP3, WAV, FLAC या PCM output, sample rate, speed और language controls उपलब्ध हैं। Voice IDs और account availability के लिए [MiniMax speech API](https://platform.minimax.io/docs/api-reference/speech-t2a-http) देखें।+Settings → Learning & conversation के तहत **Video Learning** default रूप से official privacy-enhanced YouTube IFrame Player उपयोग करता है। Playback को local रखने के लिए administrator-managed Invidious API origin (उदाहरण के लिए `http://127.0.0.1:3000`) set करें, इसे test करें, Invidious select करें, और save करें। नई या फिर से खोली गई videos वही material ID और progress रखते हुए तुरंत provider अपना लेती हैं। Invidious media DeepTutor के byte-range proxy से stream होता है; upstream URLs न browser के सामने expose होते हैं, न disk पर store किए जाते हैं। अगर instance fail हो जाए, तो learner के explicitly native YouTube fallback चुनने तक DeepTutor YouTube से offline रहता है। Public-caption tutoring optional है: `.[video-learning]` install करें; इसके बिना playback जारी रहता है, जबकि transcript-based **Explain here** कारण के साथ disabled रहता है।<div align="center">@@ -617,7 +642,7 @@ Remote-topology detection की एक localhost boundary है। अगर W</details><details>-<summary><b>👥 Multi-User — Shared Deployments</b> · optional auth, isolated per-user workspaces</summary>+<summary><b>👥 Multi-User — साझा डिप्लॉयमेंट</b> · optional auth, isolated per-user workspaces</summary>Authentication **default रूप से बंद** है — DeepTutor single-user चलता है। इसे on करें और एक `data/` tree एक admin workspace, isolated per-user workspaces, और partner workspaces को side by side host करती है:@@ -645,7 +670,7 @@ Split private/public origins के लिए, `auth.private_login_hosts` (यएक `deeptutor` binary, दो तरीके से: terminal में रहने वालों के लिए interactive **REPL**, और DeepTutor को tool के रूप में drive करने वाले दूसरे agents के लिए structured **JSON**। दोनों तरफ same capabilities, tools, और knowledge bases।<details>-<summary><b>खुद drive करें</b></summary>+<summary><b>खुद चलाएं</b></summary>`deeptutor chat` एक interactive REPL खोलता है और `--capability` से mode चुनता है; `deeptutor run <capability> "<message>"` उस capability को अपना पहला positional argument लेता है और एक turn के बाद exit करता है। दोनों `--tool`, `--kb`, `--config` और registered workspace चुनने के लिए `--workspace` accept करते हैं।@@ -663,7 +688,7 @@ Core workspace management यहां भी उपलब्ध है — know</details><details>-<summary><b>किसी agent को drive करने दें</b></summary>+<summary><b>किसी एजेंट को चलाने दें</b></summary>DeepTutor *दूसरे agent द्वारा operated* होने के लिए built है। किसी भी `run` में `--format json` add करें और हर turn **NDJSON — एक event per line** stream करता है (`content`, `tool_call`, `tool_result`, `done`, …), हर line `session_id` के साथ tagged। Runs headless-safe हैं: बिना TTY के `ask_user` pause automatically empty reply से resolve होता है बजाय hang करने के।@@ -683,9 +708,9 @@ Repo एक root [`SKILL.md`](../../SKILL.md) ship करता है — ए</details><details>-<summary><b>Command reference</b></summary>+<summary><b>कमांड संदर्भ</b></summary>-| Command | विवरण |+| कमांड | विवरण ||:---|:---|| `deeptutor init` | Current runtime home में `data/user/settings` create या update करें || `deeptutor doctor [--online]` | Check करें कि runtime session शुरू करने के लिए ready है या नहीं; `--online` configured model provider को भी probe करता है, `--format json` report print करता है |@@ -696,7 +721,7 @@ Repo एक root [`SKILL.md`](../../SKILL.md) ship करता है — ए| `deeptutor run <capability> <message>` | एक single capability turn run करें (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); NDJSON output के लिए `--format json` add करें || `deeptutor chat` | capability, tool, KB, notebook, और history controls के साथ interactive REPL || `deeptutor partner list/create/start/stop` | IM-connected partners manage करें |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Knowledge bases manage करें और registered GitHub/web sources sync करें (source add/remove commands के साथ) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Knowledge bases manage करें, Kiwix archives connect करें, QA set के आधार पर retrieval quality मापें, और registered GitHub/web sources sync करें (source add/remove commands के साथ) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Skills manage करें, hubs से install करें, और अपनी खुद publish करें (default `eduhub:<slug>`, Ecosystem देखें) || `deeptutor memory show/clear` | L2/L3 memory docs inspect करें या L1/all memory clear करें || `deeptutor session list/show/open/rename/delete` | Shared sessions manage करें |@@ -709,7 +734,7 @@ Repo एक root [`SKILL.md`](../../SKILL.md) ship करता है — ए</details><details>-<summary><b>CLI-only distribution</b></summary>+<summary><b>केवल CLI का वितरण</b></summary>CLI-only package `packaging/deeptutor-cli` में रहता है। इस checkout में, इसे source से install करें:@@ -726,7 +751,7 @@ python -m pip install -e ./packaging/deeptutor-cliDeepTutor skills open **Agent-Skills** format उपयोग करती हैं — एक `SKILL.md` playbook (YAML frontmatter + Markdown) और optional reference files के साथ एक folder। इसमें DeepTutor-specific कुछ नहीं है, इसलिए format बोलने वाली कोई भी registry आपकी library के लिए एक source बन जाती है। DeepTutor **[EduHub](https://eduhub.deeptutor.info/)** के साथ ship होता है — हमारी अपनी education-focused skill registry — default hub के रूप में built in।<details>-<summary><b>EduHub — DeepTutor का skill ecosystem</b></summary>+<summary><b>EduHub — DeepTutor का स्किल इकोसिस्टम</b></summary>[**EduHub**](https://eduhub.deeptutor.info/) वह community hub है जिसे DeepTutor ने teaching-oriented agent skills share करने के लिए launch किया — Socratic tutors, flashcard builders, essay feedback, exam blueprints, concept explainers, और बहुत कुछ। यह DeepTutor में built in है, इसलिए configure करने की कोई जरूरत नहीं: एक bare slug या `eduhub:` prefix इसे resolve करता है।@@ -752,7 +777,7 @@ EduHub एक standalone, ClawHub-compatible registry भी है, इसल</details><details>-<summary><b>Import safety gate</b></summary>+<summary><b>इम्पोर्ट सुरक्षा जांच</b></summary>Source चाहे जो भी हो, हर import आपके workspace को touch करने से पहले **same safety gate** से गुजरता है:@@ -766,7 +791,7 @@ Multi-user deployments में, browser imports authenticated caller की sk</details><details>-<summary><b>ClawHub के साथ भी compatible</b></summary>+<summary><b>ClawHub के साथ भी संगत</b></summary>क्योंकि DeepTutor open Agent-Skills format बोलता है, **[ClawHub](https://clawhub.ai/)** भी एक first-class source है — यह EduHub के साथ built in है। इसे hub prefix से चुनें:@@ -820,7 +845,7 @@ DeepTutor [HKUDS](https://github.com/HKUDS) Group के अंदर [Bingxi ZhDeepTutor outstanding open-source projects के कंधों पर खड़ा है जिन्होंने हमें tools और inspiration दोनों दिए:-| Project | भूमिका / Inspiration |+| प्रोजेक्ट | भूमिका / प्रेरणा ||:---|:---|| [**LlamaIndex**](https://github.com/run-llama/llama_index) | RAG pipeline और document-indexing backbone || [**nanobot**](https://github.com/HKUDS/nanobot) | Ultra-lightweight agent engine जिसने original TutorBot को powered किया *(HKUDS)* |diff --git a/assets/README/README_JA.md b/assets/README/README_JA.mdindex 7f1de8423..57bf5c745 100644--- a/assets/README/README_JA.md+++ b/assets/README/README_JA.md@@ -63,7 +63,7 @@ DeepTutorは、個別指導、問題解決、クイズ生成、研究、ビジ- **すべてのモードで1つのランタイム** — Chat、Ask Questions、Quiz、Research、Visualize、Solve、Course Study、Mastery Path、Immersive Reading、Immersive Watchingは、同じ機能ランタイムとセッションコンテキストを共有しながら、用途別に設計されたループとパイプラインを維持します。- **Task Board** — 学習タスクをTo do、In progress、Doneで管理できます。メモ、ドラッグ&ドロップやキーボードで操作できる移動ボタン、復元可能なアーカイブを備えます。カードは現在のワークスペースに保存され、既存の外観と言語の設定に従います。モデル設定は不要です。- **接続された学習コンテキスト** — 知識ベース、本、Co-Writerの下書き、ノートブック、問題バンク、ペルソナ、Memoryは、アカウントのグラントと学習ポリシーに従い、それらをサポートするワークフロー間で再利用できます。-- **没入型動画学習** — YouTubeリンクを貼り付けるだけで、プライバシー強化ネイティブ再生、同期字幕、タイムスタンプに基づく個別指導、再開可能な進捗を利用できます。管理者は教材を再構築せずに、再生をセルフホストのInvidiousインスタンスへ切り替えられます。+- **没入型動画学習** — YouTubeリンクを貼り付けるだけで、プライバシー強化ネイティブ再生、同期字幕、タイムスタンプに基づく個別指導、タイムスタンプのマークの保存、再開可能な進捗を利用できます。管理者は教材を再構築せずに、再生をセルフホストのInvidiousインスタンスへ切り替えられます。- **サブエージェントとPartners** — Chatからライブエージェントハーネス(Claude Code、Codex、Grok CLI、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw、DeepSeek)またはPartnerに相談し、過去の会話をインポートし、同じブレインで永続的なIMコンパニオンを実行できます。- **マルチエンジン知識** — LlamaIndex、PageIndex、GraphRAG、LightRAG、リモートのLightRAG Server、セルフホストのWeKnora知識ベース、Tencent IMAまたはMarginNote 4ライブラリ、接続されたKiwix ZIMアーカイブ、あるいはリンクされたObsidianボールトにまたがるバージョン管理されたRAGライブラリ(プラグ可能なドキュメント解析付き)。独立した抽出・クエリ・ビジョン設定、デフォルトのみの作成、確認付き再構築については[ネイティブLightRAGロールモデル](../../deeptutor/services/rag/pipelines/lightrag/README.md)を参照してください。- **拡張可能なツールとスキル** — 組み込みツール、MCPサーバー、CLIアプリ、画像/ビデオ/音声生成モデル、EduHubからインストール可能なコミュニティスキル。@@ -75,6 +75,19 @@ DeepTutorは、個別指導、問題解決、クイズ生成、研究、ビジDeepTutorは4つのインストールパスを提供しています。どれも同じランタイムホームのレイアウトを共有します。プライベート設定は、起動元のディレクトリ(または明示的に設定した場合は`DEEPTUTOR_HOME`/`deeptutor start --home`)配下の`data/user/settings/`に保存されます。フルアプリの場合、推奨されるフローは **ランタイムホームディレクトリの選択 → インストール → `deeptutor init` → `deeptutor start`** です。+### 1コマンドでDockerを試す++Dockerがまだインストールされていない場合は、まず[Dockerをインストール](https://docs.docker.com/get-docker/)してください。その後、PythonやNode.jsを設定せずにフルアプリを試せます。++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++[http://127.0.0.1:3782](http://127.0.0.1:3782)を開き、**Settings → Providers**でモデルプロバイダーを設定してください。終了するには`Ctrl+C`を押します。名前付きの`deeptutor-data`ボリュームに、次回の実行に向けて設定とローカルデータが保持されます。+### コンテンツワークスペース**コンテンツワークスペース**は、DeepTutorのプライベートなランタイムホームとは別のものです。エージェントが読み取れるフォルダで、生成ファイルは`outputs/<capability>/<session>/<turn>/`に置かれます。カスタムワークスペースでは、会話、学習教材、進捗、キャッシュが、ファイルツールから参照できないプライベートな`.deeptutor/data/`ツリーに分離されます。設定、認証情報、Memoryは引き続きアカウント単位で共有されます。@@ -329,7 +342,7 @@ deeptutor config show| `auth.json` | オプション認証トグル、ユーザー名、パスワードハッシュ、トークン/クッキー設定 || `integrations.json` | オプションのPocketBaseとサイドカー統合設定 || `interface.json` | UIの言語とモデル出力言語/テーマ/サイドバー設定 |-| `document_parsing.json` | 解析エンジンの選択、リモートエンドポイント、エンジン固有のオプション |+| `document_parsing.json` | 解析エンジンと画像説明モデルの選択、リモートエンドポイント、エンジン固有のオプション || `video_learning.json` | デフォルトのYouTube/Invidious再生プロバイダー、Invidiousオリジン、オプションの文字起こしアダプター || `main.yaml` | ランタイム動作のデフォルトとパス注入 || `agents.yaml` | 機能/ツールのtemperatureとトークン設定 |@@ -350,6 +363,8 @@ deeptutor config showプロジェクトルートの`.env`はアプリケーション設定ファイルとして**読み込まれません**。最小限のモデル設定では、**Settings → Providers**にBase URLとAPIキーを保存し、**Language models**でLLMを追加して選択してください。Knowledge Base / RAG機能を使用する予定がある場合のみ埋め込みプロフィールを追加してください。+API Routeを使う場合は、**Settings → Providers**で**API Route**を選択し、API Routeのキーを入力します。プリセットのURLは`https://global.api-route.com/v1`です。その後、**Language models**でAPI RouteのモデルIDを指定してモデルを追加してください。キーとモデルの設定については、[API Routeクイックスタート](https://www.api-route.com/docs/quickstart)を参照してください。+プロバイダーが選択肢をサポートする場合、LLMおよびタスクモデルのプロフィールには**APIフォーマット**設定が表示されます。通常のルーティングとフォールバックには`Auto`のままにするか、`OpenAI Chat Completions`、`OpenAI Responses`、または`Anthropic Messages`を選択します。Responses強制モードは引き続きフェイルクローズです。永続化されるフィールドは`api_format`(`auto`、`openai_chat`、`openai_responses`、または`anthropic`)であり、`wire_api`は派生した互換性状態です。モデルごとの`Auto` / `Supported` / `Not supported`オーバーライドは、ツール呼び出し、画像入力、JSON出力、推論制御を対象とします。</details>@@ -422,9 +437,9 @@ Chatはデフォルト機能であり、ほとんどの作業が始まる場所ユーザーが切り替えられるツールは`brainstorm`、`web_search`、`paper_search`、`zotero_search`、`reason`、`geogebra_analysis` — 加えて、対応する生成モデルを設定すれば`imagegen`と`videogen`も利用できます。`rag`、`kb_files`、`knowledge_frontier`、`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`などのコンテキスト依存ツールは、ターンに適切なコンテキストがある場合に自動的にマウントされます。-コンテキストには2種類あります:**スティッキーセッションコンテキスト**(機能、ワークスペースまたはコース、ツール、知識ベース、ペルソナ、モデル、Reading / Masteryの状態)はターンをまたいで持続します。**ワンタイム参照**(ファイル、チャット履歴、本、読書セクション、ノートブック、問題バンク、インポートしたエージェント)は単一のターンのために`+`メニューから追加します。音声ボタンが文字起こしするのは現在のメッセージだけです。+コンテキストには2種類あります:**スティッキーセッションコンテキスト**(機能、ワークスペースまたはコース、ツール、知識ベース、ペルソナ、モデル、Reading / Masteryの状態)はターンをまたいで持続します。**ワンタイム参照**(ファイル、チャット履歴、本、読書セクション、ノートブック、問題バンクから選択した項目、インポートしたエージェント)は単一のターンのために`+`メニューから追加します。音声ボタンが文字起こしするのは現在のメッセージだけです。-Homeでは**Chat**、**Ask Questions**、**Quiz**、**Visualize**にワンクリックでアクセスできます。引用付きレポートの**Research**、手順を追った推論の**Solve**、**Immersive Watching**は*その他の機能*の下にあります。**個別学習**にはBook、**Mastery Path**、**Immersive Reading**、Watching、**練習**がまとまっています。Readingには検証済みの引用、保存したノート、ソースに基づく読み上げ / 学習ガイダンス / 語彙 / クイズ / 翻訳アクション、ノートブックへの取り込みがあり、Course Studyはコースに紐づいたコンテキストを維持します。+Homeでは**Chat**、**Ask Questions**、**Quiz**、**Visualize**にワンクリックでアクセスできます。引用付きレポートの**Research**、手順を追った推論の**Solve**、**Immersive Watching**は*その他の機能*の下にあります。**個別学習**にはBook、**Mastery Path**、**Immersive Reading**、Watching、**練習**がまとまっています。Readingには検証済みの引用、保存したノート、ソースの文章からの自然な読み上げ / 学習ガイダンス / 語彙 / クイズ / 翻訳アクション、ノートブックへの取り込みがあり、Course Studyはコースに紐づいたコンテキストを維持します。</details>@@ -489,7 +504,7 @@ Co-Writerはレポート、チュートリアル、メモ、長文学習コン<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Co-Writerエディターとライブプレビュー" width="900"></div>-その定義的なアイデアは**外科的編集**です。テキストの範囲を選択し、DeepTutorに書き直し、拡張、または短縮を依頼します。編集エージェントは知識ベースまたはウェブの証拠に基づいて変更をグラウンドし、ツール呼び出しのトレースを保持できます。処理中に下書きが変更されていなければ、結果は選択したテキストを直接置き換え、**Undo**で元に戻せます。+その定義的なアイデアは**外科的編集**です。テキストの範囲を選択し、DeepTutorに書き直し、拡張、または短縮を依頼します。編集モデルを選択でき、知識ベースやウェブの証拠を利用しながら、ツール呼び出しのトレースを保持します。処理中に下書きが変更されていなければ、結果は選択したテキストを直接置き換え、**Undo**で元に戻せます。</details>@@ -529,12 +544,18 @@ Bookは選択したソースをインタラクティブな**生きている本**既存のObsidian、Hermes、Markdownライブラリを移行する場合は、接続ボールトとインデックス付きコピーの手順を[Knowledge migration guide](../../docs-for-user/KNOWLEDGE_MIGRATION.md)で確認してください。-KBを作成する際は、**新規作成**(ドキュメントをアップロードしてインデックスを構築)、**既存をリンク**(既存のインデックスをその場で再利用)、または**Kiwixに接続**(提供中の1つのZIMアーカイブをオンデマンドで検索)を選べます。作成時に保存先ワークスペースを選択します。既存のKBも、プレビューで確認した後に、割り当てと保存済みの参照を維持したままワークスペース間で移動できます。KBは**GitHubリポジトリ**(リポジトリ、ブランチ、glob)または**ドキュメントサイトのURL**(クロール深度とページ数に上限あり、デフォルトで24時間ごとに再同期)も追跡できます。同期はコンテンツのハッシュ差分から追加・変更・削除を検出するため、フォローしているドキュメントを再アップロードなしで最新の状態に保てます。**リンクされたフォルダ**は同期時にローカルの新規・変更ファイルを取り込みます。再インデックスは新しいフラットな`version-N`ディレクトリを書き込み、以前のものを保持するため、再構築中に作業中のインデックスが破壊されることはありません。解析に失敗したファイルを完全な削除・再構築なしで取り除けるよう、**error**状態のベースからでも単一のドキュメントを削除できます。ドキュメント解析(Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM、LiteParse)は**Settings → Knowledge & documents**で選択し、ローカルモデルのダウンロードはデフォルトでオフです。Docling は、Docling Serve サーバーに対して**remote**モードで実行することもできます(ローカルインストールやモデルは不要)。この設定は同じページ(`mode=remote`、サーバーのベースURL、オプションのAPIキー)または `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` 環境変数で行います。Tikaはリモート専用で、そのページに設定したApache Tikaサーバーを参照します。CLIは`list/info/create/connect-kiwix/add/search/set-default/delete`、ソースの追加/削除コマンド、`list-sources`、`sync`でライフサイクルをミラーします。+KBを作成する際は、**新規作成**(ドキュメントをアップロードしてインデックスを構築)、**既存をリンク**(既存のインデックスをその場で再利用)、または**Kiwixに接続**(提供中の1つのZIMアーカイブをオンデマンドで検索)を選べます。作成時に保存先ワークスペースを選択します。既存のKBも、プレビューで確認した後に、割り当てと保存済みの参照を維持したままワークスペース間で移動できます。KBは**GitHubリポジトリ**(リポジトリ、ブランチ、glob)または**ドキュメントサイトのURL**(クロール深度とページ数に上限あり、デフォルトで24時間ごとに再同期)も追跡できます。同期はコンテンツのハッシュ差分から追加・変更・削除を検出するため、フォローしているドキュメントを再アップロードなしで最新の状態に保てます。**リンクされたフォルダ**は同期時にローカルの新規・変更ファイルを取り込みます。再インデックスは新しいフラットな`version-N`ディレクトリを書き込み、以前のものを保持するため、再構築中に作業中のインデックスが破壊されることはありません。解析に失敗したファイルを完全な削除・再構築なしで取り除けるよう、**error**状態のベースからでも単一のドキュメントを削除できます。ドキュメント解析(Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM、LiteParse)とオプションの画像説明モデルは**Settings → Knowledge & documents**で選択し、ローカルモデルのダウンロードはデフォルトでオフです。Docling は、Docling Serve サーバーに対して**remote**モードで実行することもできます(ローカルインストールやモデルは不要)。この設定は同じページ(`mode=remote`、サーバーのベースURL、オプションのAPIキー)または `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` 環境変数で行います。Tikaはリモート専用で、そのページに設定したApache Tikaサーバーを参照します。CLIは`list/info/create/connect-kiwix/add/search/eval/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のみです。テキストのみおよびその他の解析エンジンはMinerUを必要としません。ネイティブLightRAGのクエリとインクリメンタルインデックス作成には、モデル、次元、エンドポイントの識別情報を含む、公開されたインデックスに記録された埋め込み設定が必要です。これが変更された場合は、元の設定を復元するか、現在の埋め込みで再構築してください。埋め込みの識別情報が記録されていないインデックスは再構築が必要です。知識ベース詳細ビューとインデックスバージョンビューには復旧ガイダンスが表示され、ファイルは引き続き閲覧・ダウンロードできます。+**知識ベースの採点。** 複数のエンジンが利用できるなか、「この資料ではどれが最もよく検索できるか」は実測で判断する問題です。その答えを得るのが`deeptutor kb eval`です。QAセット(1行に1つのJSONオブジェクト:`query`と、理想的な検索結果に含まれるべき`gold`の文章)を作成し、`deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`でKBを採点します。各ケースはチャットターンと同じ経路で検索され、順位付きの引用が完全一致または語彙の重なりで正解の文章と照合されます(しきい値は`--min-ratio`で調整でき、意味的な同等性は評価しません)。実行結果には**Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**が報告されます。指標は順位だけを入力とする純粋関数なので、モデルによる出力の判定はありません。スコアには再現性があり、差分比較も可能です。ベースラインを保存すると、埋め込みの切り替え、再ランカーの変更、チャンクサイズの実験に対する回帰チェックとして、このセットを利用できます。インデックスの欠落や不正な認証情報などで検索に失敗したケースにはスコアを付けず、平均を引き下げる代わりに個別に報告します。PageIndexは推論によって検索し、順位付きのチャンクを返さないため、対象外です。++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ KBを作成する際は、**新規作成**(ドキュメントをアップロ<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor Learning Spaceハブ" width="900"></div>-Learning Spaceはライブラリ、整理、パーソナライゼーションの層です。**会話と素材**にはChat History、レコードの移動とMarkdownへのエクスポートに対応したノートブック、回答と解説を保存する問題バンクがあります。個別学習の**練習**では、保存した問題を復習セッション、間違いの記録、定期的な反復学習に活用できます。**パーソナライゼーション**にはペルソナ、スキル(`SKILL.md`プレイブック)、ワンクリックで導入できる**MCPサービス**、[CLI-Anything](https://github.com/HKUDS/CLI-Anything)カタログの**CLIアプリ**があり、各アプリの使用ガイドはオンデマンドで読み込まれます。独立した**My Courses**ワークスペースは科目ごとの会話とチュータースレッドをまとめ、各アセットはそれをサポートするワークフローでのみ提供されます。+Learning Spaceはライブラリ、整理、パーソナライゼーションの層です。**会話と素材**にはChat History、レコードの移動とMarkdownへのエクスポートに対応したノートブック、回答と解説を保存する問題バンクがあります。問題バンクで選択した項目、または個別学習から**練習**を開始して、復習セッション、間違いの記録、定期的な反復学習を行えます。**パーソナライゼーション**にはペルソナ、スキル(`SKILL.md`プレイブック)、ワンクリックで導入できる**MCPサービス**、[CLI-Anything](https://github.com/HKUDS/CLI-Anything)カタログの**CLIアプリ**があり、各アプリの使用ガイドはオンデマンドで読み込まれます。独立した**My Courses**ワークスペースは科目ごとの会話とチュータースレッドをまとめ、各アセットはそれをサポートするワークフローでのみ提供されます。<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="EduHubからスキルをインポート" width="900">@@ -580,6 +601,10 @@ Memory Graphはピラミッド全体を表示します — L3合成が中心、LSettingsはオペレーションコントロールプレーンで、最初に表示される**一般**でインターフェースとモデル出力の言語を設定します。検索可能なナビゲーターから独立した各ページにアクセスできます。**個人**にはワークスペース、データ移行、外観、使用量統計、**学習と会話**にはスターティングポイント、添付ファイル、Video Learning、学習者と保護者の管理、Learning progress、Memory、**モデルとサービス**にはプロバイダー、言語モデル、タスクモデル、埋め込み、検索、音声、マルチモーダル生成、**機能と連携**にはツール、機能パラメーター、Partners & agents、Knowledge & documentsがあります。**システム**にはネットワーク、実行状態、Aboutがあり、**アーカイブ済みチャット**ではアーカイブした会話の検索、復元、完全削除ができます。実行状態にはバックエンドの健全性、常駐メモリ、機能の阻害要因・警告・提案を評価する**Readiness**マトリクスが表示されます。ワークスペースはトピックのファイルと学習状態を分離し、データ移行では検証付きの移行とエクスポートができます。**プロバイダー**はベンダーのアドレスと認証情報を保持し、そのサービスモデルで再利用します。モデルページでは保存済みプロバイダーを選び、モデル名と機能を設定します。**タスクモデル**は会話への命名やスターティングポイントの生成などのバックグラウンド作業に小さく高速なモデルを固定し、空欄の場合はアクティブなデフォルトを使用します。音声には音声合成と文字起こし、マルチモーダル生成には画像と動画のモデルがまとまっています。Partners & agentsではローカルハーネスとリモートのHermesゲートウェイを設定します。+**Xiaomi MiMoの音声合成。** `https://api.xiaomimimo.com/v1`とAPIキーを指定してXiaomi MiMoプロバイダーを追加し、Settings → Voiceで`mimo-v2.5-tts`を追加します。`mimo_default`、`冰糖`、`苏打`などのプリセットを選び、出力形式を`wav`または`pcm16`にして、適用前に試聴してください。音声指示でスタイルと読み上げ速度を調整できます。このアダプターはプリセット音声のみをサポートします。音声デザインと音声クローンには別のモデルが必要で、このアダプターでは利用できません。以前のMiMo音声モデルを汎用のOpenAI互換アダプターで設定していた場合は、Xiaomi MiMoプロバイダーを使って音声エントリーを作成し直し、chat-completionsプロトコルを使うようにしてください。[MiMo公式音声ガイド](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5)を参照してください。++**MiniMaxの音声合成** — Settings → Voiceでテキスト読み上げにMiniMaxを選択し、`speech-2.8-hd`を選びます。MiniMaxのAPIキーと、システム音声またはカスタム音声のIDを設定してください。デフォルトの音声は`English_expressive_narrator`です。APIベースのデフォルトは`https://api.minimax.io/v1`で、中国リージョンでは`https://api.minimaxi.com/v1`を使用します。読み上げと音声プレビューはネイティブの音声エンドポイントを使用し、MP3、WAV、FLAC、PCMの出力形式、サンプルレート、速度、言語を調整できます。音声IDとアカウントでの利用可否については、[MiniMax音声API](https://platform.minimax.io/docs/api-reference/speech-t2a-http)を参照してください。+Settings → Learning & conversationの**Video Learning**は、デフォルトで公式のプライバシー強化YouTube IFrame Playerを使用します。再生をローカルに保つには、管理者が管理するInvidious APIオリジン(例:`http://127.0.0.1:3000`)を設定してテストし、Invidiousを選択して保存します。新規または再度開いた動画には、同じ教材IDと進捗のままプロバイダーが直ちに反映されます。InvidiousメディアはDeepTutorのバイトレンジプロキシ経由でストリーミングされ、アップストリームURLがブラウザに公開されたりディスクに保存されたりすることはありません。インスタンスに障害が発生した場合、学習者がネイティブのYouTubeフォールバックを明示的に選択するまで、DeepTutorはYouTubeへ接続しないままです。公開字幕による個別指導はオプションです:`.[video-learning]`をインストールしてください。未インストールでも再生は続行しますが、文字起こしに基づく**Explain here**は理由とともに無効になります。<div align="center">@@ -696,7 +721,7 @@ deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format j| `deeptutor run <capability> <message>` | 単一機能ターンを実行(`chat`、`ask_questions`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`、`immersive_reading`、`course_study`、`immersive_watching`、`audio_overview`);`--format json`でNDJSON出力 || `deeptutor chat` | 機能、ツール、KB、ノートブック、履歴コントロール付きインタラクティブREPL || `deeptutor partner list/create/start/stop` | IM接続Partnersを管理 |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | 知識ベースを管理し、登録済みGitHub/Webソースを同期(ソースの追加/削除コマンドを含む) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | 知識ベースを管理し、Kiwixアーカイブへ接続し、QAセットに対する検索品質を採点し、登録済みGitHub/Webソースを同期(ソースの追加/削除コマンドを含む) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | スキルを管理、ハブからインストール、自分のスキルを公開(デフォルトは`eduhub:<slug>`、エコシステム参照) || `deeptutor memory show/clear` | L2/L3メモリドキュメントを検査またはL1/全メモリをクリア || `deeptutor session list/show/open/rename/delete` | 共有セッションを管理 |diff --git a/assets/README/README_PL.md b/assets/README/README_PL.mdindex c8ae577ec..c4f2e7c6f 100644--- a/assets/README/README_PL.md+++ b/assets/README/README_PL.md@@ -2,15 +2,15 @@<p align="center"><img src="../../assets/figs/logo/logo.png" alt="Logo DeepTutor" height="56" style="vertical-align: middle;"> <img src="../../assets/figs/logo/banner.png" alt="DeepTutor" height="48" style="vertical-align: middle;"></p>-# DeepTutor: Dożywotnie Spersonalizowane Korepetycje+# DeepTutor: Spersonalizowane korepetycje przez całe życie<p align="center">- <a href="https://deeptutor.info" target="_blank"><img alt="Docs — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> - <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Collaborate — work with us" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a>+ <a href="https://deeptutor.info" target="_blank"><img alt="Dokumentacja — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> + <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Współpraca — pracuj z nami" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a></p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="Popularne repozytorium dnia na GitHub" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Ranking historii gwiazdek" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor to natywne dla agentów środowisko nauki, które łączy korepetycje,- **Jedno środowisko dla wszystkich trybów** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading i Immersive Watching współdzielą jedno środowisko uruchomieniowe możliwości oraz kontekst sesji, zachowując wyspecjalizowane pętle i potoki dla poszczególnych zadań.- **Task Board** — śledź zadania związane z nauką w kolumnach Do zrobienia, W toku i Gotowe, dodawaj notatki, przenoś karty przeciąganiem lub przyciskami dostępnymi z klawiatury i korzystaj z archiwum, z którego można je przywrócić. Karty pozostają w bieżącym obszarze roboczym i stosują istniejące ustawienia wyglądu oraz języka; konfiguracja modelu nie jest wymagana.- **Połączony kontekst uczenia się** — bazy wiedzy, książki, szkice Co-Writer, notatniki, banki pytań, persony i Memory można ponownie wykorzystywać w obsługujących je przepływach pracy, z uwzględnieniem uprawnień konta i polityk nauczania.-- **Immersyjne uczenie się z wideo** — wklej link do YouTube, aby korzystać z natywnego odtwarzania o podwyższonej ochronie prywatności, zsynchronizowanych napisów, korepetycji osadzonych w znacznikach czasu i wznawialnych postępów; administratorzy mogą przełączyć odtwarzanie na samodzielnie hostowaną instancję Invidious bez ponownego tworzenia materiałów.+- **Immersyjne uczenie się z wideo** — wklej link do YouTube, aby korzystać z natywnego odtwarzania o podwyższonej ochronie prywatności, zsynchronizowanych napisów, korepetycji osadzonych w znacznikach czasu, zapisanych znaczników czasu i wznawialnych postępów; administratorzy mogą przełączyć odtwarzanie na samodzielnie hostowaną instancję Invidious bez ponownego tworzenia materiałów.- **Subagenty i Partners** — z poziomu Chat konsultuj aktywnie działającego agenta (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw lub DeepSeek) albo Partner, importuj poprzednie konwersacje i uruchamiaj stałych towarzyszy IM na tym samym mózgu.- **Wielosilnikowa wiedza** — wersjonowane biblioteki RAG z LlamaIndex, PageIndex, GraphRAG, LightRAG, zdalnym LightRAG Server, samodzielnie hostowanym WeKnora, biblioteką Tencent IMA lub MarginNote 4, podłączonym archiwum Kiwix ZIM, lub podłączonym vault Obsidian, z podłączalnym parsowaniem dokumentów. Zobacz [natywne modele ról LightRAG](../../deeptutor/services/rag/pipelines/lightrag/README.md), aby poznać niezależne ustawienia ekstrakcji, zapytań i wizji, tworzenie ograniczone do wartości domyślnych oraz potwierdzone przebudowy.- **Rozszerzalne narzędzia i umiejętności** — wbudowane narzędzia, serwery MCP, aplikacje CLI, modele generowania obrazów / wideo / głosu oraz instalowalne umiejętności społecznościowe z EduHub.@@ -73,7 +73,20 @@ DeepTutor to natywne dla agentów środowisko nauki, które łączy korepetycje,## 🚀 Pierwsze kroki-DeepTutor oferuje cztery ścieżki instalacji. Wszystkie współdzielą jeden układ obszaru roboczego: ustawienia żyją w `data/user/settings/` pod katalogiem, z którego uruchamiasz (lub pod `DEEPTUTOR_HOME` / `deeptutor start --home` jeśli ustawisz je jawnie). Dla pełnej aplikacji zalecany przepływ to **wybierz katalog obszaru roboczego → zainstaluj → `deeptutor init` → `deeptutor start`**.+DeepTutor oferuje cztery ścieżki instalacji. Wszystkie współdzielą jeden układ katalogu środowiska uruchomieniowego: prywatne ustawienia znajdują się w `data/user/settings/` pod katalogiem, z którego uruchamiasz aplikację (lub pod `DEEPTUTOR_HOME` / `deeptutor start --home`, jeśli ustawisz je jawnie). Dla pełnej aplikacji zalecany przepływ to **wybierz katalog środowiska uruchomieniowego → zainstaluj → `deeptutor init` → `deeptutor start`**.++### Wypróbuj Docker jednym poleceniem++Jeśli Docker nie jest jeszcze zainstalowany, najpierw [zainstaluj Docker](https://docs.docker.com/get-docker/). Następnie wypróbuj pełną aplikację bez konfigurowania Pythona ani Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++Otwórz [http://127.0.0.1:3782](http://127.0.0.1:3782), skonfiguruj dostawców modeli w **Settings → Providers** i naciśnij `Ctrl+C`, gdy skończysz. Nazwany wolumin `deeptutor-data` zachowuje ustawienia i dane lokalne do następnego uruchomienia.### Content Workspace@@ -101,8 +114,8 @@ Pełna lokalna aplikacja Web + CLI, bez potrzeby klonowania. Wymaga **Python 3.1```bashmkdir -p my-deeptutor && cd my-deeptutorpip install -U deeptutor-deeptutor init # pyta o porty + dostawcę LLM + opcjonalne osadzanie/wyszukiwanie-deeptutor start # uruchamia backend + frontend; utrzymuj terminal otwarty+deeptutor init # prompts for ports + LLM provider + optional embedding/search+deeptutor start # starts backend + frontend; keep the terminal open````deeptutor init` pyta o port backendu (domyślnie `8001`), port frontendu (domyślnie `3782`), dostawcę LLM / bazowy URL / klucz API / model, opcjonalnego dostawcę osadzania dla Bazy wiedzy / RAG oraz opcjonalnego dostawcę wyszukiwania dla Web Search.@@ -122,12 +135,12 @@ Do programowania przy użyciu kodu źródłowego. Użyj **Python 3.11–3.14** igit clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Utwórz venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1python3 -m venv .venv && source .venv/bin/activatepython -m pip install --upgrade pip-# Zainstaluj zależności backendu + frontendu+# Install backend + frontend depspython -m pip install -e .( cd web && npm ci --legacy-peer-deps )@@ -152,14 +165,14 @@ python -m pip install --upgrade pip<summary><b>Opcjonalne dodatki instalacyjne</b> — silniki RAG / dev / partners / matrix / math-animator</summary>```bash-pip install -e ".[rag-lightrag]" # Wbudowany silnik LightRAG (dokładnie obsługiwany SDK)-pip install -e ".[graphrag]" # Silnik Microsoft GraphRAG (Python 3.11–3.13)-pip install -e ".[dev]" # narzędzia testów/lint-pip install -e ".[partners]" # SDK kanałów IM Partners+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 SDKspip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs-pip install -e ".[matrix]" # kanał Matrix bez E2EE/libolm-pip install -e ".[matrix-e2e]" # Matrix E2EE; wymaga libolm-pip install -e ".[math-animator]" # addon Manim; wymaga LaTeX/ffmpeg/bibliotek systemowych+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```</details>@@ -216,7 +229,7 @@ Dla Compose ustaw `DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder` przed uruchomOtwórz [http://127.0.0.1:3782](http://127.0.0.1:3782). Kontener tworzy `/app/data/user/settings/*.json` przy pierwszym uruchomieniu; skonfiguruj dostawców modeli ze strony Web Settings. Konfiguracja, klucze API, dzienniki, domyślny Content Workspace, pamięć i bazy wiedzy są przechowywane w woluminie `deeptutor-data`. Oddzielnie zamontowany Content Workspace zachowuje się zamiast tego w swojej ścieżce hosta. Opcjonalne dodatki należą do wdrożenia, nie do powłoki: ustaw `DEEPTUTOR_EXTRAS` (oraz `DEEPTUTOR_APT_PACKAGES` dla bibliotek systemowych), a każdy kontener uruchomiony z tego wdrożenia ponownie je zastosuje, podczas gdy `docker exec … pip install` zostałby utracony przy kolejnym `compose down`.-- **Różne porty hosta:** zmień lewą stronę każdego mapowania `-p host:kontener` (np. `-p 127.0.0.1:8088:3782`). Jeśli zmienisz porty po stronie kontenera w `/app/data/user/settings/system.json`, uruchom ponownie i zaktualizuj prawą stronę każdego mapowania, aby pasowała.+- **Różne porty hosta:** zmień lewą stronę każdego mapowania `-p host:container` (np. `-p 127.0.0.1:8088:3782`). Jeśli zmienisz porty po stronie kontenera w `/app/data/user/settings/system.json`, uruchom ponownie i zaktualizuj prawą stronę każdego mapowania, aby pasowała.- **Odłączony:** dodaj `-d`, następnie `docker logs -f deeptutor`, aby śledzić, `docker stop deeptutor`, aby zatrzymać, `docker rm deeptutor` przed ponownym użyciem nazwy. Wolumin `deeptutor-data` przechowuje prywatne dane środowiska uruchomieniowego i domyślny Content Workspace między restartami; oddzielnie zamontowany Content Workspace zachowuje się w swojej ścieżce hosta.**Zdalny Docker / odwrotne proxy:** przeglądarka komunikuje się wyłącznie z serwerem frontendu (`:3782`); middleware Next.js wewnątrz kontenera przekazuje `/api/*` i `/ws/*` do serwera backendu po stronie serwera. W typowym przypadku jednego kontenera nie konfigurujesz w ogóle bazowego adresu API — po prostu skieruj swój reverse proxy / terminator TLS na `:3782`. Bazowy adres API jest potrzebny tylko dla **wdrożenia rozdzielonego** (backend w osobnym kontenerze/hoście): ustaw `next_public_api_base` w `data/user/settings/system.json` na adres sieciowy, którego serwer frontendu używa do osiągnięcia backendu (jest czytany po stronie serwera, nigdy nie wysyłany do przeglądarki).@@ -273,7 +286,7 @@ Gdy nie potrzebujesz interfejsu webowego. Pakiet tylko CLI jest instalowany zegit clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Utwórz venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1python3 -m venv .venv-cli && source .venv-cli/bin/activatepython -m pip install --upgrade pip@@ -289,7 +302,7 @@ deeptutor chat<summary><b>Typowe polecenia</b></summary>```bash-deeptutor chat # interaktywny REPL+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --tool rag --kb my-kbdeeptutor run chat "Explain Fourier transform"deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb@@ -329,7 +342,7 @@ Wszystko w `data/user/settings/` to zwykły JSON/YAML. Zalecanym edytorem jest s| `auth.json` | Opcjonalny przełącznik uwierzytelniania, nazwa użytkownika, hash hasła, ustawienia tokena/cookie || `integrations.json` | Opcjonalne ustawienia PocketBase i integracji sidecar || `interface.json` | Preferencje języka interfejsu i języka odpowiedzi modelu / motywu / paska bocznego |-| `document_parsing.json` | Wybór silnika parsowania, zdalne punkty końcowe i opcje specyficzne dla silnika |+| `document_parsing.json` | Wybór silnika parsowania i modelu opisującego obrazy, zdalne punkty końcowe i opcje specyficzne dla silnika || `video_learning.json` | Domyślny dostawca odtwarzania YouTube/Invidious, źródła Invidious i opcjonalny adapter transkrypcji || `main.yaml` | Domyślne zachowanie środowiska uruchomieniowego i wstrzykiwanie ścieżek || `agents.yaml` | Ustawienia temperatury i tokenów możliwości/narzędzi |@@ -350,6 +363,8 @@ Gdy `trusted_domains` nie jest puste, odwołania są ograniczone do tych domen iPlik `.env` w katalogu głównym projektu **nie** jest czytany jako plik konfiguracyjny aplikacji. Dla minimalnej konfiguracji modelu zapisz bazowy URL i klucz API w **Settings → Providers**, a następnie dodaj i wybierz LLM w **Language models**. Dodaj profil osadzania tylko jeśli planujesz korzystać z funkcji Bazy wiedzy / RAG.+Dla API Route wybierz **API Route** w **Settings → Providers** i wpisz klucz API Route. Ustawienie wstępne korzysta z `https://global.api-route.com/v1`; następnie dodaj model, używając jego identyfikatora modelu API Route w **Language models**. Informacje o konfiguracji klucza i modelu znajdziesz w [przewodniku szybkiego startu API Route](https://www.api-route.com/docs/quickstart).+Profile LLM i modeli zadaniowych udostępniają ustawienie **formatu API**, gdy ich dostawca umożliwia wybór. Pozostaw `Auto` dla zwykłego routingu i mechanizmu awaryjnego albo wybierz `OpenAI Chat Completions`, `OpenAI Responses` lub `Anthropic Messages`; wymuszony tryb Responses nadal działa w sposób fail-closed. Zapisywane pole to `api_format` (`auto`, `openai_chat`, `openai_responses` lub `anthropic`); `wire_api` jest pochodnym stanem kompatybilności. Nadpisania `Auto` / `Supported` / `Not supported` dla poszczególnych modeli obejmują wywoływanie narzędzi, dane wejściowe obrazów, dane wyjściowe JSON i sterowanie rozumowaniem.</details>@@ -422,9 +437,9 @@ Pętla jest celowo prosta: model myśli w rundach, wywołuje narzędzia gdy sąNarzędzia przełączalne przez użytkownika to `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason` i `geogebra_analysis` — plus `imagegen` i `videogen` po skonfigurowaniu odpowiedniego modelu generowania. Narzędzia kontekstowe takie jak `rag`, `kb_files`, `knowledge_frontier`, `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` i `workspace_export` montują się automatycznie gdy tura ma odpowiedni kontekst.-Kontekst dzieli się na dwa rodzaje: **trwały kontekst sesji** (możliwość, obszar roboczy lub kurs, narzędzia, bazy wiedzy, persona, model oraz stan Reading / Mastery) jest zachowany przez tury; **jednorazowe odwołania** (pliki, historia czatu, książki, sekcje do czytania, notatniki, bank pytań, zaimportowani agenci) pochodzą z menu `+` dla jednej tury. Przycisk głosowy jedynie transkrybuje bieżącą wiadomość.+Kontekst dzieli się na dwa rodzaje: **trwały kontekst sesji** (możliwość, obszar roboczy lub kurs, narzędzia, bazy wiedzy, persona, model oraz stan Reading / Mastery) jest zachowany przez tury; **jednorazowe odwołania** (pliki, historia czatu, książki, sekcje do czytania, notatniki, wybrane wpisy banku pytań, zaimportowani agenci) pochodzą z menu `+` dla jednej tury. Przycisk głosowy jedynie transkrybuje bieżącą wiadomość.-Home daje dostęp jednym kliknięciem do **Chat**, **Ask Questions**, **Quiz** i **Visualize**; **Research** do raportów z cytowaniami, **Solve** do rozumowania krok po kroku oraz **Immersive Watching** znajdują się w sekcji *More Capabilities*. **Spersonalizowana nauka** grupuje Book, **Mastery Path**, **Immersive Reading**, Watching i **Ćwiczenia**; Reading dodaje zweryfikowane cytowania, zapisane notatki, oparte na źródłach działania czytania na głos / wskazówek do nauki / słownictwa / quizu / tłumaczenia oraz przechwytywanie do notatnika, a Course Study zachowuje kontekst związany z kursem.+Home daje dostęp jednym kliknięciem do **Chat**, **Ask Questions**, **Quiz** i **Visualize**; **Research** do raportów z cytowaniami, **Solve** do rozumowania krok po kroku oraz **Immersive Watching** znajdują się w sekcji *More Capabilities*. **Spersonalizowana nauka** grupuje Book, **Mastery Path**, **Immersive Reading**, Watching i **Ćwiczenia**; Reading dodaje zweryfikowane cytowania, zapisane notatki, naturalne czytanie na głos fragmentów źródłowych / wskazówki do nauki / słownictwo / quizy / tłumaczenia oraz zapisywanie w notatniku, a Course Study zachowuje kontekst związany z kursem.</details>@@ -489,7 +504,7 @@ Co-Writer to obszar roboczy Markdown z podzielonym widokiem dla raportów, samou<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Edytor Co-Writer z podglądem na żywo" width="900"></div>-Jego wyróżniającym pomysłem jest **precyzyjna edycja**: zaznacz fragment i poproś DeepTutor o przepisanie, rozszerzenie lub skrócenie. Agent edycji może ugruntować zmianę w bazie wiedzy lub dowodach webowych i zachowuje ślad swoich wywołań narzędzi. Jeśli szkic nie zmienił się podczas jego pracy, wynik bezpośrednio zastępuje zaznaczony tekst i nadal można go cofnąć za pomocą **Undo**.+Jego wyróżniającym pomysłem jest **precyzyjna edycja**: zaznacz fragment i poproś DeepTutor o przepisanie, rozszerzenie lub skrócenie. Wybierz model edycji; może on korzystać z bazy wiedzy lub dowodów z sieci i zachowuje ślad swoich wywołań narzędzi. Jeśli szkic nie zmienił się podczas jego pracy, wynik bezpośrednio zastępuje zaznaczony tekst i nadal można go cofnąć za pomocą **Undo**.</details>@@ -529,12 +544,18 @@ Bazy wiedzy to kolekcje dokumentów za RAG — ugruntowują tury Chat, edycje CoPrzenosisz istniejącą bibliotekę Obsidian, Hermes lub Markdown? Zobacz [przewodnik po migracji wiedzy](../../docs-for-user/KNOWLEDGE_MIGRATION.md), aby poznać ścieżki podłączonego vault i indeksowanej kopii.-Tworząc KB, możesz **utworzyć nową** (przesłać i zindeksować dokumenty), **połączyć istniejącą** (ponownie użyć indeksu w miejscu) lub **podłączyć Kiwix** (przeszukiwać na żądanie jedno udostępniane archiwum ZIM). Wybierz obszar roboczy do przechowywania przy tworzeniu; istniejącą KB można przenieść między obszarami roboczymi po obejrzeniu podglądu, zachowując przypisania i zapisane odwołania. Baza wiedzy może też śledzić **repozytoria GitHub** (repozytorium, gałąź i wzorzec glob) lub **adresy URL witryn dokumentacji** (z ograniczoną głębokością przeszukiwania i liczbą stron, domyślnie resynchronizowane co 24 h); synchronizacja porównuje skróty treści, aby wykryć elementy dodane, zmienione i usunięte, dzięki czemu śledzona dokumentacja pozostaje aktualna bez ponownego przesyłania, a **połączone foldery** wychwytują nowe lub zmienione pliki lokalne przy synchronizacji. Ponowne indeksowanie zapisuje nowy płaski katalog `version-N` i zachowuje poprzednie, więc działający indeks nigdy nie jest niszczony w trakcie przebudowy. Pojedynczy dokument można usunąć nawet z bazy w stanie **błędu** — usuwając plik, który nie sparsował się poprawnie, bez pełnego usuwania i przebudowy. Parsowanie dokumentów — Tylko tekst, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM lub LiteParse — jest wybierane w **Settings → Knowledge & documents**, z domyślnie wyłączonymi pobieraniami lokalnego modelu. Docling może też działać w trybie **zdalnym** względem serwera Docling Serve (bez lokalnej instalacji czy modeli), konfigurowanym na tej stronie (`mode=remote`, bazowy URL serwera i opcjonalny klucz API) lub zmienne środowiskowe `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika jest wyłącznie zdalna i wskazuje na serwer Apache Tika skonfigurowany na tej stronie. CLI odzwierciedla cykl życia przez `list/info/create/connect-kiwix/add/search/set-default/delete`, polecenia dodawania/usuwania źródeł, `list-sources` i `sync`.+Tworząc KB, możesz **utworzyć nową** (przesłać i zindeksować dokumenty), **połączyć istniejącą** (ponownie użyć indeksu w miejscu) lub **podłączyć Kiwix** (przeszukiwać na żądanie jedno udostępniane archiwum ZIM). Wybierz obszar roboczy do przechowywania przy tworzeniu; istniejącą KB można przenieść między obszarami roboczymi po obejrzeniu podglądu, zachowując przypisania i zapisane odwołania. Baza wiedzy może też śledzić **repozytoria GitHub** (repozytorium, gałąź i wzorzec glob) lub **adresy URL witryn dokumentacji** (z ograniczoną głębokością przeszukiwania i liczbą stron, domyślnie resynchronizowane co 24 h); synchronizacja porównuje skróty treści, aby wykryć elementy dodane, zmienione i usunięte, dzięki czemu śledzona dokumentacja pozostaje aktualna bez ponownego przesyłania, a **połączone foldery** wychwytują nowe lub zmienione pliki lokalne przy synchronizacji. Ponowne indeksowanie zapisuje nowy płaski katalog `version-N` i zachowuje poprzednie, więc działający indeks nigdy nie jest niszczony w trakcie przebudowy. Pojedynczy dokument można usunąć nawet z bazy w stanie **błędu** — usuwając plik, który nie sparsował się poprawnie, bez pełnego usuwania i przebudowy. Silnik parsowania dokumentów — Tylko tekst, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM lub LiteParse — oraz opcjonalny model opisujący obrazy wybiera się w **Settings → Knowledge & documents**, a pobieranie lokalnych modeli jest domyślnie wyłączone. Docling może też działać w trybie **zdalnym** względem serwera Docling Serve (bez lokalnej instalacji czy modeli), konfigurowanym na tej stronie (`mode=remote`, bazowy URL serwera i opcjonalny klucz API) lub za pomocą zmiennych środowiskowych `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika jest wyłącznie zdalna i wskazuje na serwer Apache Tika skonfigurowany na tej stronie. CLI odzwierciedla cykl życia przez `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, polecenia dodawania/usuwania źródeł, `list-sources` i `sync`.Wbudowany silnik LightRAG instaluje się poleceniem `pip install 'deeptutor[rag-lightrag]'`. Ten dodatek zawiera obsługiwany SDK LightRAG, ale nie instaluje MinerU. Wybierz MinerU niezależnie w Document Parsing i skonfiguruj jego tryb chmurowy albo zainstaluj jego aktualny lokalny CLI, gdy potrzebne jest strukturalne parsowanie. MinerU akceptuje pliki PDF, popularne obrazy rastrowe, DOCX, PPTX i XLSX; starsze polecenie `magic-pdf` nadal obsługuje wyłącznie pliki PDF. Tryb tylko tekstowy i pozostałe silniki parsowania nie wymagają MinerU.Natywne zapytania LightRAG i indeksowanie przyrostowe wymagają konfiguracji embeddingu zapisanej przez opublikowany indeks, obejmującej model, wymiar i tożsamość punktu końcowego. Jeśli się zmieni, przywróć oryginalną konfigurację lub przebuduj indeks z użyciem aktualnego embeddingu; indeksy bez zapisanej tożsamości embeddingu wymagają przebudowy. Widoki szczegółów bazy wiedzy i wersji indeksu pokazują wskazówki dotyczące odzyskiwania, a pliki pozostają dostępne do przeglądania i pobierania.+**Ocena bazy wiedzy.** Gdy dostępnych jest kilka silników, odpowiedź na pytanie „który najlepiej wyszukuje w tych materiałach?” wymaga pomiaru — i temu służy `deeptutor kb eval`. Przygotuj zestaw pytań i odpowiedzi (jeden obiekt JSON w wierszu: `query` oraz fragmenty `gold`, które powinno zwrócić idealne wyszukiwanie), a następnie oceń bazę poleceniem `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. Każdy przypadek korzysta z tej samej ścieżki wyszukiwania co tura czatu; cytowania uporządkowane według rankingu są dopasowywane do wzorcowych fragmentów na podstawie identycznego tekstu lub wspólnego słownictwa (progi można ustawiać przez `--min-ratio`; równoważność semantyczna nie jest oceniana), a wynik obejmuje **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. Metryki są czystymi funkcjami rankingu, więc żaden model nie ocenia wyniku: oceny są odtwarzalne i można je porównywać, a zapisany wynik odniesienia pozwala używać zestawu do sprawdzania regresji po zmianie embeddingu, modelu ponownego rankingu lub rozmiaru fragmentów. Przypadki, w których wyszukiwanie się nie powiodło (brak indeksu, błędne dane uwierzytelniające), nie otrzymują oceny i są raportowane oddzielnie, zamiast obniżać średnie. PageIndex używa rozumowania do wyszukiwania i nie zwraca uporządkowanych fragmentów, więc jest wykluczony.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ Natywne zapytania LightRAG i indeksowanie przyrostowe wymagają konfiguracji emb<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="Centrum Learning Space DeepTutor" width="900"></div>-Learning Space to warstwa biblioteki, organizacji i personalizacji. **Conversations & Materials** obejmuje Chat History, notatniki z możliwością przenoszenia rekordów i eksportu do Markdown oraz bank pytań z odpowiedziami i wyjaśnieniami. **Ćwiczenia** w Spersonalizowanej nauce zamieniają zapisane pytania w sesje powtórkowe, śledzenie błędów i powtórki według harmonogramu. **Personalization** obejmuje persony, umiejętności (podręczniki `SKILL.md`), instalowane jednym kliknięciem **Usługi MCP** oraz **Aplikacje CLI** z katalogu [CLI-Anything](https://github.com/HKUDS/CLI-Anything), każdą z przewodnikiem użycia wczytywanym na żądanie. Oddzielny obszar roboczy **My Courses** grupuje rozmowy według przedmiotów i wątki tutorów; każdy zasób jest oferowany tylko w przepływach pracy, które go obsługują.+Learning Space to warstwa biblioteki, organizacji i personalizacji. **Conversations & Materials** obejmuje Chat History, notatniki z możliwością przenoszenia rekordów i eksportu do Markdown oraz bank pytań z odpowiedziami i wyjaśnieniami. Rozpocznij **Ćwiczenia** od zaznaczenia w banku pytań lub ze Spersonalizowanej nauki, aby prowadzić sesje powtórkowe, śledzić błędy i powtarzać materiał według harmonogramu. **Personalization** obejmuje persony, umiejętności (podręczniki `SKILL.md`), instalowane jednym kliknięciem **Usługi MCP** oraz **Aplikacje CLI** z katalogu [CLI-Anything](https://github.com/HKUDS/CLI-Anything), każdą z przewodnikiem użycia wczytywanym na żądanie. Oddzielny obszar roboczy **My Courses** grupuje rozmowy według przedmiotów i wątki tutorów; każdy zasób jest oferowany tylko w przepływach pracy, które go obsługują.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Importowanie umiejętności z EduHub" width="900">@@ -580,6 +601,10 @@ Memory Graph pokazuje całą piramidę — synteza L3 w centrum, L2 w środkowymSettings to panel sterowania aplikacją, który otwiera się na stronie **General**, służącej do wyboru języka interfejsu i odpowiedzi modelu. Nawigator z wyszukiwaniem prowadzi do niezależnych stron: **Personal** obejmuje Workspaces, migrację danych, wygląd i statystyki użycia; **Learning & conversation** — punkty startowe, załączniki, Video Learning, ustawienia uczniów i opiekunów, Learning progress oraz Memory; **Models & services** — dostawców, modele językowe, modele zadań, osadzanie, wyszukiwanie, głos i generowanie multimodalne; **Features & integrations** — narzędzia, parametry możliwości, Partners & agents oraz Knowledge & documents. **System** obejmuje sieć, stan środowiska uruchomieniowego i informacje o aplikacji; **Archived chats** pozwala wyszukiwać, przywracać lub trwale usuwać zarchiwizowane rozmowy. Stan środowiska uruchomieniowego zawiera stan backendu, pamięć rezydentną i macierz **Readiness**, która ocenia blokady, ostrzeżenia i sugestie dotyczące możliwości. Workspaces rozdziela pliki tematów i stan nauki, a migracja danych oferuje zweryfikowany transfer i eksport. **Dostawca** przechowuje adres i poświadczenia firmy do ponownego użycia przez jej modele usług; strony modeli pozwalają wybierać zapisanych dostawców oraz konfigurować nazwy i możliwości modeli. **Modele zadań** przypinają mały, szybki model do pracy w tle — nazywania rozmów i pisania punktów startowych — a gdy są puste, korzystają z aktywnego modelu domyślnego. Głos grupuje syntezę mowy i transkrypcję; generowanie multimodalne grupuje modele obrazów i wideo. Partners & agents służy do konfiguracji lokalnych środowisk agentów i zdalnej bramy Hermes.+**Synteza mowy Xiaomi MiMo.** Dodaj dostawcę Xiaomi MiMo z adresem `https://api.xiaomimimo.com/v1` i jego kluczem API, a następnie dodaj `mimo-v2.5-tts` w Settings → Voice. Wybierz gotowy głos, na przykład `mimo_default`, `冰糖` lub `苏打`, użyj formatu wyjściowego `wav` lub `pcm16` i odsłuchaj próbkę przed zastosowaniem ustawień. Instrukcje głosowe sterują stylem i szybkością mówienia. Ten adapter obsługuje wyłącznie gotowe głosy; projektowanie i klonowanie głosu wymagają osobnych modeli i nie są obsługiwane. Jeśli starszy model mowy MiMo był skonfigurowany przez ogólny adapter zgodny z OpenAI, utwórz jego wpis ponownie, korzystając z dostawcy Xiaomi MiMo, aby używał protokołu chat-completions. Zobacz [oficjalny przewodnik syntezy mowy MiMo](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**Synteza mowy MiniMax** — w Settings → Voice wybierz MiniMax do zamiany tekstu na mowę i model `speech-2.8-hd`. Skonfiguruj klucz API MiniMax oraz identyfikator głosu systemowego lub własnego; domyślny głos to `English_expressive_narrator`. Domyślny bazowy adres API to `https://api.minimax.io/v1`; dla regionu Chin użyj `https://api.minimaxi.com/v1`. Czytanie na głos i próbki głosu korzystają z natywnego punktu końcowego syntezy mowy, z formatami wyjściowymi MP3, WAV, FLAC lub PCM oraz ustawieniami częstotliwości próbkowania, szybkości i języka. Informacje o identyfikatorach głosów i dostępności dla kont znajdziesz w [API syntezy mowy MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http).+**Video Learning** w Settings → Learning & conversation domyślnie korzysta z oficjalnego odtwarzacza YouTube IFrame Player o podwyższonej ochronie prywatności. Aby odtwarzać lokalnie, ustaw zarządzane przez administratora źródło API Invidious (na przykład `http://127.0.0.1:3000`), przetestuj je, wybierz Invidious i zapisz. Nowe lub ponownie otwarte filmy natychmiast przejmują dostawcę, zachowując ten sam identyfikator materiału i postęp. Multimedia Invidious są strumieniowane przez proxy zakresów bajtów DeepTutor; nadrzędne adresy URL nie są ani ujawniane przeglądarce, ani zapisywane na dysku. Jeśli instancja ulegnie awarii, DeepTutor pozostaje odłączony od YouTube, dopóki uczeń nie wybierze jawnie natywnego trybu awaryjnego YouTube. Korepetycje oparte na publicznych napisach są opcjonalne: zainstaluj `.[video-learning]`; bez niego odtwarzanie nadal działa, natomiast funkcja **Explain here** oparta na transkrypcji jest wyłączona wraz z podaniem przyczyny.<div align="center">@@ -623,11 +648,11 @@ Uwierzytelnianie jest **domyślnie wyłączone** — DeepTutor działa jednoosob```textdata/-├── user/ # Obszar roboczy administratora + globalne ustawienia-├── users/<uid>/ # Zakres per-użytkownik: historia czatu, pamięć, notatniki, KB-├── partners/<id>/workspace/ # Zakres partnera (użytkownika syntetycznego)-├── cli-apps/ # Zainstalowane aplikacje CLI, zamontowane tylko do odczytu w piaskownicy-└── system/ # auth · grants · audit · user-secrets/<owner> (tokeny OAuth)+├── user/ # Admin workspace + global settings+├── users/<uid>/ # Per-user scope: chat history, memory, notebooks, KBs+├── partners/<id>/workspace/ # Partner (synthetic-user) scope+├── cli-apps/ # Installed CLI apps, mounted read-only into the sandbox+└── system/ # auth · grants · audit · user-secrets/<owner> (OAuth tokens)```**Pierwszy zarejestrowany użytkownik staje się administratorem** i jest właścicielem katalogów modeli, danych uwierzytelniających dostawców, współdzielonych baz wiedzy, umiejętności, kanonicznych współdzielonych książek i uprawnień per-użytkownik. Lokalni użytkownicy utworzeni przez administratora wybierają Standard, Learner lub Custom. Learner blokuje możliwości edukacyjne i politykę materiałów, dodaje profil adaptacyjny oraz obsługuje odwoływalne poświadczenia urządzenia z datą wygaśnięcia i limitami dziennymi; upoważnieni guardians mogą przeglądać raporty, zatwierdzać materiały i resetować poświadczenia. Pozostali użytkownicy otrzymują izolowane obszary robocze oraz ograniczony dostęp do modeli, KB, umiejętności, Partners i współdzielonych książek bez otrzymywania surowych kluczy API. Jeśli `auth.json` zawiera już `username` + `password_hash`, to konto *jest* administratorem: `/register` pozostaje zamknięte, a konta utworzone z `/admin/users` mają zawsze `role=user`, dopóki ich nie awansujesz.@@ -650,7 +675,7 @@ Jeden plik binarny `deeptutor`, dwa sposoby wejścia: interaktywny **REPL** dla`deeptutor chat` otwiera interaktywny REPL i wybiera tryb za pomocą `--capability`; `deeptutor run <capability> "<message>"` przyjmuje tę możliwość jako pierwszy argument pozycyjny i kończy się po jednej turze. Oba przyjmują `--tool`, `--kb`, `--config` oraz `--workspace` do wyboru zarejestrowanego obszaru roboczego.```bash-deeptutor chat # interaktywny REPL+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --kb my-kb --tool ragdeeptutor run chat "Explain the Fourier transform" --tool rag --kb textbookdeeptutor run chat "Find recent work beyond this material" --kb textbook --tool knowledge_frontier@@ -668,10 +693,10 @@ Podstawowe zarządzanie obszarem roboczym jest dostępne również tutaj — bazDeepTutor jest zbudowany aby być *obsługiwany przez innego agenta*. Dodaj `--format json` do dowolnego `run` a każda tura strumieniuje **NDJSON — jedno zdarzenie na linię** (`content`, `tool_call`, `tool_result`, `done`, …), każda linia oznaczona swoim `session_id`. Uruchomienia są bezpieczne bez TTY: pauza `ask_user` bez TTY automatycznie rozwiązuje się pustą odpowiedzią zamiast zawieszać.```bash-# Jednorazowo, czytelne maszynowo+# One shot, machine-readabledeeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json-# Łącz tury w jednej sesji stanowej — przechwyć id, ponownie użyj+# Chain turns in one stateful session — capture the id, reuse itSID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \--config mode=report --config depth=standard --format json \| jq -r 'select(.type=="done").session_id')@@ -696,7 +721,7 @@ Repozytorium zawiera główny [`SKILL.md`](../../SKILL.md) — około 200-liniow| `deeptutor run <capability> <message>` | Uruchom jedną turę możliwości (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); dodaj `--format json` dla wyjścia NDJSON || `deeptutor chat` | Interaktywny REPL z kontrolkami możliwości, narzędzia, KB, notatnika i historii || `deeptutor partner list/create/start/stop` | Zarządzaj partnerami połączonymi przez IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Zarządzaj bazami wiedzy i synchronizuj zarejestrowane źródła GitHub/Web (z poleceniami dodawania/usuwania źródeł) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Zarządzaj bazami wiedzy, podłączaj archiwa Kiwix, oceniaj jakość wyszukiwania na zestawie pytań i odpowiedzi oraz synchronizuj zarejestrowane źródła GitHub/Web (z poleceniami dodawania/usuwania źródeł) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Zarządzaj umiejętnościami, instaluj z hubów i publikuj własne (`eduhub:<slug>` domyślnie, patrz Ekosystem) || `deeptutor memory show/clear` | Inspekcjonuj dokumenty pamięci L2/L3 lub wyczyść pamięć L1/wszystko || `deeptutor session list/show/open/rename/delete` | Zarządzaj współdzielonymi sesjami |@@ -733,18 +758,18 @@ Umiejętności DeepTutor używają otwartego formatu **Agent-Skills** — folder**Znajdź i zainstaluj** — w przeglądarce otwórz **Learning Space → Skills → Import from EduHub** aby przeglądać katalog i pobrać umiejętność bezpośrednio do swojej biblioteki. Z terminala:```bash-deeptutor skill search "socratic tutor" # wyszukaj EduHub (domyślny hub)-deeptutor skill install socratic-tutor # pobierz → weryfikuj → zarejestruj-deeptutor skill install eduhub:[email protected] # przypnij hub i wersję-deeptutor skill list # lokalne umiejętności z proweniencją hubu+deeptutor skill search "socratic tutor" # search EduHub (the default hub)+deeptutor skill install socratic-tutor # fetch → verify → register+deeptutor skill install eduhub:[email protected] # pin a hub and a version+deeptutor skill list # local skills with their hub provenance```**Opublikuj własną** — spakuj `SKILL.md` i podziel się ze społecznością:```bash-deeptutor skill login # logowanie przeglądarki do EduHub-deeptutor skill publish ./my-skill # interaktywne: wybierz ścieżkę + tagi, następnie prześlij-deeptutor skill update # wycofaj lub wydaj nową wersję+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 jest również samodzielnym, kompatybilnym z ClawHub rejestrem, więc agenty które nie są DeepTutorem (Claude Code, Codex, …) mogą używać go bezpośrednio przez CLI `eduhub` — `npx eduhub install socratic-tutor`.diff --git a/assets/README/README_PT.md b/assets/README/README_PT.mdindex 66abb9f14..b8852fec0 100644--- a/assets/README/README_PT.md+++ b/assets/README/README_PT.md@@ -63,7 +63,7 @@ O DeepTutor é um espaço de trabalho de aprendizagem nativo de agentes que cone- **Um runtime para todos os modos** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading e Immersive Watching partilham o mesmo runtime de capacidades e o mesmo contexto de sessão, mantendo loops e pipelines específicos para cada finalidade.- **Task Board** — acompanhe tarefas de estudo em Por fazer, Em curso e Concluído, com notas, arrastar e largar ou botões de movimentação acessíveis por teclado, e um arquivo do qual pode restaurá-las. Os cartões permanecem no workspace atual e seguem as definições de aparência e idioma existentes; não é necessário configurar um modelo.- **Contexto de aprendizagem conectado** — bases de conhecimento, livros, rascunhos Co-Writer, notebooks, bancos de questões, personas e Memory podem ser reutilizados nos fluxos de trabalho que os suportam, sujeitos às concessões da conta e às políticas de aprendizagem.-- **Aprendizagem imersiva por vídeo** — cole um link do YouTube para reprodução nativa com privacidade melhorada, legendas sincronizadas, tutoria fundamentada em marcas temporais e progresso retomável; os administradores podem mudar a reprodução para uma instância Invidious auto-hospedada sem reconstruir materiais.+- **Aprendizagem imersiva por vídeo** — cole um link do YouTube para reprodução nativa com privacidade melhorada, legendas sincronizadas, tutoria fundamentada em marcas temporais, marcas temporais guardadas e progresso retomável; os administradores podem mudar a reprodução para uma instância Invidious auto-hospedada sem reconstruir materiais.- **Subagentes e Partners** — a partir do Chat, consulte um harness de agente ao vivo (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw ou DeepSeek) ou um Partner, importe conversas anteriores e execute companheiros IM persistentes no mesmo cérebro.- **Conhecimento multi-motor** — bibliotecas RAG com versões: LlamaIndex, PageIndex, GraphRAG, LightRAG, um LightRAG Server remoto, bases de conhecimento WeKnora auto-hospedadas, uma biblioteca Tencent IMA ou MarginNote 4, um arquivo Kiwix ZIM conectado, ou um vault Obsidian vinculado, com análise de documentos conectável. Consulte os [modelos de função nativos do LightRAG](../../deeptutor/services/rag/pipelines/lightrag/README.md) para configurações independentes de extração, consulta e visão, criação apenas com predefinições e reconstruções confirmadas.- **Ferramentas e habilidades extensíveis** — ferramentas integradas, servidores MCP, aplicações CLI, modelos de geração de imagem / vídeo / voz e habilidades da comunidade instaláveis do EduHub.@@ -73,7 +73,20 @@ O DeepTutor é um espaço de trabalho de aprendizagem nativo de agentes que cone## 🚀 Começar-O DeepTutor inclui quatro caminhos de instalação. Todos partilham um layout de espaço de trabalho: as configurações vivem em `data/user/settings/` sob o diretório a partir do qual é iniciado (ou sob `DEEPTUTOR_HOME` / `deeptutor start --home` se definido explicitamente). Para a aplicação completa, o fluxo recomendado é **escolher um diretório de espaço de trabalho → instalar → `deeptutor init` → `deeptutor start`**.+O DeepTutor inclui quatro caminhos de instalação. Todos partilham o mesmo layout de diretório de runtime: as configurações privadas vivem em `data/user/settings/` sob o diretório a partir do qual é iniciado (ou sob `DEEPTUTOR_HOME` / `deeptutor start --home` se definido explicitamente). Para a aplicação completa, o fluxo recomendado é **escolher um diretório de runtime → instalar → `deeptutor init` → `deeptutor start`**.++### Experimentar com Docker num Único Comando++Se ainda não tiver o Docker instalado, [instale o Docker](https://docs.docker.com/get-docker/) primeiro. Depois experimente a aplicação completa sem configurar Python nem Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++Abra [http://127.0.0.1:3782](http://127.0.0.1:3782), configure provedores de modelos em **Settings → Providers** e prima `Ctrl+C` quando terminar. O volume nomeado `deeptutor-data` guarda as configurações e os dados locais para a próxima execução.### Content Workspace@@ -329,7 +342,7 @@ Tudo sob `data/user/settings/` é JSON/YAML simples. A página **Settings** é o| `auth.json` | Interruptor de autenticação opcional, nome de utilizador, hash de palavra-passe, configurações de token/cookie || `integrations.json` | Configurações opcionais de PocketBase e integrações sidecar || `interface.json` | Preferências de idioma da UI e de saída do modelo / tema / barra lateral |-| `document_parsing.json` | Seleção do motor de análise, endpoints remotos e opções específicas de cada motor |+| `document_parsing.json` | Seleção do motor de análise e do modelo de descrição de imagens, endpoints remotos e opções específicas de cada motor || `video_learning.json` | Provedor predefinido de reprodução YouTube/Invidious, origens Invidious e adaptador opcional de transcrições || `main.yaml` | Predefinições de comportamento de runtime e injeção de caminhos || `agents.yaml` | Configurações de temperatura e tokens de capacidades/ferramentas |@@ -350,7 +363,9 @@ Quando `trusted_domains` não está vazio, as referências ficam limitadas a essO `.env` da raiz do projeto **não** é lido como ficheiro de configuração da aplicação. Para uma configuração mínima do modelo, guarde um URL Base e uma chave API em **Settings → Providers**; depois adicione e selecione um LLM em **Language models**. Adicione um perfil de embeddings apenas se planear usar funcionalidades de Base de Conhecimento / RAG.-Os perfis LLM e de modelos de tarefa expõem uma definição de formato da API quando o respetivo provedor permite escolher. Mantenha `Auto` para o encaminhamento normal e fallback, ou escolha `OpenAI Chat Completions`, `OpenAI Responses` ou `Anthropic Messages`; o modo Responses forçado continua fechado em caso de falha. O campo persistido é `api_format` (`auto`, `openai_chat`, `openai_responses` ou `anthropic`); `wire_api` é um estado de compatibilidade derivado. As substituições `Auto` / `Supported` / `Not supported` por modelo abrangem chamadas de ferramentas, entrada de imagens, saída JSON e controlos de raciocínio.+Para API Route, selecione **API Route** em **Settings → Providers** e introduza uma chave API Route. A predefinição usa `https://global.api-route.com/v1`; depois adicione um modelo com o respetivo ID de modelo API Route em **Language models**. Consulte o [guia de início rápido do API Route](https://www.api-route.com/docs/quickstart) para configurar a chave e o modelo.++Os perfis LLM e de modelos de tarefa expõem uma definição de **formato da API** quando o respetivo provedor permite escolher. Mantenha `Auto` para o encaminhamento normal e fallback, ou escolha `OpenAI Chat Completions`, `OpenAI Responses` ou `Anthropic Messages`; o modo Responses forçado continua fechado em caso de falha. O campo persistido é `api_format` (`auto`, `openai_chat`, `openai_responses` ou `anthropic`); `wire_api` é um estado de compatibilidade derivado. As substituições `Auto` / `Supported` / `Not supported` por modelo abrangem chamadas de ferramentas, entrada de imagens, saída JSON e controlos de raciocínio.</details>@@ -422,9 +437,9 @@ O loop é deliberadamente simples: o modelo pensa em rondas, chama ferramentas qAs ferramentas ativáveis pelo utilizador são `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason` e `geogebra_analysis` — mais `imagegen` e `videogen` depois de configurar o modelo de geração correspondente. Ferramentas contextuais como `rag`, `kb_files`, `knowledge_frontier`, `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` e `workspace_export` montam automaticamente quando o turno tem o contexto certo.-O contexto é de dois tipos: o **contexto de sessão fixo** (capacidade, espaço de trabalho ou curso, ferramentas, bases de conhecimento, persona, modelo e estado de Reading / Mastery) persiste entre turnos; as **referências únicas** (ficheiros, histórico de chat, livros, secções de leitura, notebooks, banco de questões, agentes importados) vêm do menu `+` para um único turno. O botão de voz transcreve apenas a mensagem atual.+O contexto é de dois tipos: o **contexto de sessão fixo** (capacidade, espaço de trabalho ou curso, ferramentas, bases de conhecimento, persona, modelo e estado de Reading / Mastery) persiste entre turnos; as **referências únicas** (ficheiros, histórico de chat, livros, secções de leitura, notebooks, entradas selecionadas do banco de questões, agentes importados) vêm do menu `+` para um único turno. O botão de voz transcreve apenas a mensagem atual.-A página inicial mantém **Chat**, **Ask Questions**, **Quiz** e **Visualize** a um clique de distância; **Research** para relatórios com citações, **Solve** para raciocínio desenvolvido e **Immersive Watching** ficam em *More Capabilities*. **Aprendizagem personalizada** agrupa Book, **Mastery Path**, **Immersive Reading**, Watching e **Prática**; Reading acrescenta citações verificadas, notas guardadas, ações de áudio / guia de estudo / vocabulário / quiz / tradução fundamentadas nas fontes e captura para notebooks, enquanto Course Study mantém o seu próprio contexto vinculado ao curso.+A página inicial mantém **Chat**, **Ask Questions**, **Quiz** e **Visualize** a um clique de distância; **Research** para relatórios com citações, **Solve** para raciocínio desenvolvido e **Immersive Watching** ficam em *More Capabilities*. **Aprendizagem personalizada** agrupa Book, **Mastery Path**, **Immersive Reading**, Watching e **Prática**; Reading acrescenta citações verificadas, notas guardadas, leitura em voz alta natural de trechos da fonte / ações de orientação de estudo / vocabulário / quiz / tradução e captura para notebooks, enquanto Course Study mantém o seu próprio contexto vinculado ao curso.</details>@@ -489,7 +504,7 @@ Co-Writer é um espaço de trabalho Markdown de vista dividida para relatórios,<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Editor Co-Writer com pré-visualização em tempo real" width="900"></div>-A sua ideia central é a **edição cirúrgica**: selecione um trecho e peça ao DeepTutor para reescrever, expandir ou encurtar. O agente de edição pode fundamentar a alteração numa base de conhecimento ou evidência web e mantém um rasto das suas chamadas de ferramentas. Se o rascunho não tiver mudado durante o trabalho, o resultado substitui diretamente o texto selecionado e continua reversível com **Undo**.+A sua ideia central é a **edição cirúrgica**: selecione um trecho e peça ao DeepTutor para reescrever, expandir ou encurtar. Escolha o modelo de edição; este pode usar uma base de conhecimento ou evidências da web e mantém um rasto das suas chamadas de ferramentas. Se o rascunho não tiver mudado durante o trabalho, o resultado substitui diretamente o texto selecionado e continua reversível com **Undo**.</details>@@ -529,12 +544,18 @@ As bases de conhecimento são as coleções de documentos por trás do RAG — fVai migrar uma biblioteca Obsidian, Hermes ou Markdown existente? Consulte o [guia de migração de Knowledge](../../docs-for-user/KNOWLEDGE_MIGRATION.md) para os caminhos de vault ligado e cópia indexada.-Ao criar uma KB, pode **criar nova** (carregar e indexar documentos), **vincular existente** (reutilizar um índice no local) ou **conectar Kiwix** (pesquisar um arquivo ZIM servido quando necessário). Escolha o workspace de armazenamento ao criar a KB; uma KB existente pode ser movida entre workspaces após uma pré-visualização, mantendo as atribuições e as referências guardadas. Uma KB também pode rastrear **repositórios GitHub** (repositório, branch, glob) ou **URLs de sites de documentação** (com profundidade de rastreio e número de páginas limitados, resincronizados a cada 24 h por predefinição); a sincronização compara hashes para detetar conteúdo adicionado, alterado ou removido, para que a documentação que segue se mantenha atual sem reenvio, e as **pastas vinculadas** capturam ficheiros locais novos ou alterados na sincronização. A reindexação escreve um novo diretório plano `version-N` e mantém os anteriores, pelo que um índice funcional nunca é destruído a meio de uma reconstrução. Um único documento pode ser removido mesmo de uma base em estado de **erro** — descartando um ficheiro que falhou a análise sem uma eliminação e reconstrução completas. A análise de documentos — Somente Texto, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM ou LiteParse — é escolhida em **Settings → Knowledge & documents**, com downloads de modelos locais desativados por predefinição. O Docling também pode correr em modo **remoto** contra um servidor Docling Serve (sem necessidade de instalação local nem de modelos), configurado nessa página (`mode=remote`, um URL base do servidor e uma chave API opcional) ou das variáveis de ambiente `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. O Tika é apenas remoto e aponta para o servidor Apache Tika configurado nessa página. A CLI espelha o ciclo de vida com `list/info/create/connect-kiwix/add/search/set-default/delete`, comandos para adicionar ou remover fontes, `list-sources` e `sync`.+Ao criar uma KB, pode **criar nova** (carregar e indexar documentos), **vincular existente** (reutilizar um índice no local) ou **conectar Kiwix** (pesquisar um arquivo ZIM servido quando necessário). Escolha o workspace de armazenamento ao criar a KB; uma KB existente pode ser movida entre workspaces após uma pré-visualização, mantendo as atribuições e as referências guardadas. Uma KB também pode rastrear **repositórios GitHub** (repositório, branch, glob) ou **URLs de sites de documentação** (com profundidade de rastreio e número de páginas limitados, resincronizados a cada 24 h por predefinição); a sincronização compara hashes para detetar conteúdo adicionado, alterado ou removido, para que a documentação que segue se mantenha atual sem reenvio, e as **pastas vinculadas** capturam ficheiros locais novos ou alterados na sincronização. A reindexação escreve um novo diretório plano `version-N` e mantém os anteriores, pelo que um índice funcional nunca é destruído a meio de uma reconstrução. Um único documento pode ser removido mesmo de uma base em estado de **erro** — descartando um ficheiro que falhou a análise sem uma eliminação e reconstrução completas. A análise de documentos — Somente Texto, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM ou LiteParse — e um modelo opcional de descrição de imagens são escolhidos em **Settings → Knowledge & documents**, com downloads de modelos locais desativados por predefinição. O Docling também pode correr em modo **remoto** contra um servidor Docling Serve (sem necessidade de instalação local nem de modelos), configurado nessa página (`mode=remote`, um URL base do servidor e uma chave API opcional) ou das variáveis de ambiente `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. O Tika é apenas remoto e aponta para o servidor Apache Tika configurado nessa página. A CLI espelha o ciclo de vida com `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, comandos para adicionar ou remover fontes, `list-sources` e `sync`.O motor LightRAG integrado é instalado com `pip install 'deeptutor[rag-lightrag]'`. Esse extra contém o SDK LightRAG suportado, mas não instala o MinerU. Escolha o MinerU de forma independente em Document Parsing e configure o seu modo cloud ou instale a sua CLI local atual quando quiser análise estruturada. O MinerU aceita PDF, imagens raster comuns, DOCX, PPTX e XLSX; o comando legado `magic-pdf` continua limitado a PDF. O motor Somente Texto e os restantes motores de análise não requerem o MinerU.As consultas nativas do LightRAG e a indexação incremental exigem a configuração de embedding registada pelo índice publicado, incluindo o modelo, a dimensão e a identidade do endpoint. Se esta mudar, restaure a configuração original ou reconstrua com o embedding atual; os índices sem uma identidade de embedding registada exigem uma reconstrução. As vistas de detalhe da base de conhecimento e de versão do índice mostram orientações de recuperação, enquanto os ficheiros permanecem disponíveis para visualização e download.+**Avaliar uma base de conhecimento.** Com vários motores disponíveis, «qual recupera melhor aqui?» é uma pergunta empírica — e `deeptutor kb eval` responde-lhe. Escreva um conjunto de perguntas e respostas (um objeto JSON por linha: uma `query` e os trechos `gold` que uma recuperação ideal deveria devolver) e avalie a KB com `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. Cada caso é recuperado pelo mesmo caminho usado num turno de chat; as suas citações ordenadas são comparadas com os trechos de referência por texto exato ou sobreposição lexical (os limiares são ajustáveis com `--min-ratio`; a equivalência semântica não é avaliada), e a execução apresenta **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. As métricas são funções puras sobre a ordenação, pelo que nenhum modelo julga o resultado: as pontuações são reproduzíveis e comparáveis por diff, e guardar uma referência transforma o conjunto numa verificação de regressão para uma mudança de embedding, uma alteração do reranker ou uma experiência com o tamanho dos chunks. Os casos em que a pesquisa falhou (índice em falta, credenciais incorretas) não recebem pontuação e são reportados separadamente, em vez de baixar as médias. O PageIndex usa raciocínio para a recuperação e não devolve chunks ordenados, pelo que fica excluído.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ As consultas nativas do LightRAG e a indexação incremental exigem a configura<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="Hub do Espaço de Aprendizado DeepTutor" width="900"></div>-O Espaço de Aprendizado é a camada de biblioteca, organização e personalização. **Conversas e Materiais** contém o Chat History, notebooks com registos transferíveis e exportação em Markdown, e um banco de questões com respostas e explicações. **Prática**, em Aprendizagem personalizada, transforma as questões guardadas em sessões de revisão, acompanhamento de erros e repetição programada. **Personalização** contém personas, skills (playbooks `SKILL.md`), **Serviços MCP** de um clique e **Aplicações CLI** do catálogo [CLI-Anything](https://github.com/HKUDS/CLI-Anything), cada uma com um guia de utilização carregado a pedido. O espaço de trabalho separado **My Courses** agrupa conversas por disciplina e threads de tutoria; cada recurso é oferecido apenas nos fluxos de trabalho que o suportam.+O Espaço de Aprendizado é a camada de biblioteca, organização e personalização. **Conversas e Materiais** contém o Chat History, notebooks com registos transferíveis e exportação em Markdown, e um banco de questões com respostas e explicações. Inicie **Prática** a partir de uma seleção do banco de questões ou de Aprendizagem personalizada para sessões de revisão, acompanhamento de erros e repetição programada. **Personalização** contém personas, skills (playbooks `SKILL.md`), **Serviços MCP** de um clique e **Aplicações CLI** do catálogo [CLI-Anything](https://github.com/HKUDS/CLI-Anything), cada uma com um guia de utilização carregado a pedido. O espaço de trabalho separado **My Courses** agrupa conversas por disciplina e threads de tutoria; cada recurso é oferecido apenas nos fluxos de trabalho que o suportam.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Importar skills do EduHub" width="900">@@ -580,6 +601,11 @@ O Memory Graph mostra toda a pirâmide — síntese L3 no centro, L2 no anel doConfigurações é o plano de controlo operacional e abre em **Geral**, com o idioma da interface e o de saída do modelo. O navegador pesquisável liga a páginas independentes: **Pessoal** inclui Workspaces, Migração de dados, Aparência e Estatísticas de utilização; **Aprendizagem e conversa** inclui pontos de partida, anexos, Video Learning, controlos de alunos e responsáveis, Progresso de aprendizagem e Memory; **Modelos e serviços** inclui Provedores, Modelos de linguagem, Modelos de tarefa, Embedding, Search, Voz e Geração multimodal; **Funcionalidades e integrações** inclui ferramentas, parâmetros de capacidades, Partners e agentes e Conhecimento e documentos. **Sistema** reúne Rede, Estado de execução e Sobre; **Conversas arquivadas** permite pesquisar, restaurar ou eliminar permanentemente conversas arquivadas. Estado de execução contém a saúde do backend, memória residente e a matriz de **Prontidão**, que classifica bloqueios, avisos e sugestões das capacidades. Workspaces mantém os ficheiros dos temas e o estado de aprendizagem separados, com migração e exportação verificadas em Migração de dados. Um **provedor** guarda o endereço e a credencial de um fornecedor para reutilização pelos seus modelos de serviço; as páginas de modelos selecionam provedores guardados e configuram nomes e capacidades dos modelos. Os **modelos de tarefa** fixam um modelo pequeno e rápido para trabalho em segundo plano — nomear conversas e escrever pontos de partida — e usam a predefinição ativa quando deixados em branco. Voz agrupa síntese e transcrição de voz; Geração multimodal agrupa modelos de imagem e vídeo. Partners e agentes configura harnesses locais e um gateway Hermes remoto.+**Voz Xiaomi MiMo.** Adicione um provedor Xiaomi MiMo com `https://api.xiaomimimo.com/v1` e a sua chave API; depois adicione `mimo-v2.5-tts` em Settings → Voz. Escolha uma voz predefinida como `mimo_default`, `冰糖` ou `苏打`, use saída `wav` ou `pcm16` e experimente-a antes de aplicar. As instruções de voz controlam o estilo e a velocidade da fala. Este adaptador suporta apenas vozes predefinidas; o design e a clonagem de voz exigem modelos separados e não são suportados. Se um modelo de voz MiMo anterior tiver sido configurado através do adaptador genérico compatível com OpenAI, recrie a respetiva entrada de voz usando o provedor Xiaomi MiMo, para que utilize o protocolo chat-completions. Consulte o [guia oficial de voz MiMo](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**Voz MiniMax** — em Settings → Voz, escolha MiniMax para síntese de voz e selecione `speech-2.8-hd`. Configure uma chave API MiniMax e um ID de voz do sistema ou personalizado; a voz predefinida é `English_expressive_narrator`. A base da API é `https://api.minimax.io/v1` por predefinição; para a região da China, use `https://api.minimaxi.com/v1`. A leitura em voz alta e as pré-visualizações de voz usam o endpoint de voz nativo, com saída MP3, WAV, FLAC ou PCM e controlos de taxa de amostragem, velocidade e idioma. Consulte a [API de voz MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http) para IDs de voz e disponibilidade por conta.++**Video Learning** em Settings → Aprendizagem e conversa usa por predefinição o YouTube IFrame Player oficial com privacidade melhorada. Para manter a reprodução local, defina a origem da API Invidious gerida pelo administrador (por exemplo, `http://127.0.0.1:3000`), teste-a, selecione Invidious e guarde. Vídeos novos ou reabertos adotam imediatamente o provedor com o mesmo ID de material e progresso. O conteúdo multimédia Invidious é transmitido através do proxy de intervalos de bytes do DeepTutor; os URLs upstream não são expostos ao navegador nem guardados no disco. Se a instância falhar, o DeepTutor permanece offline do YouTube até que o aluno escolha explicitamente o fallback nativo do YouTube. A tutoria com legendas públicas é opcional: instale `.[video-learning]`; a reprodução continua sem esse extra, enquanto **Explain here** baseada na transcrição fica desativada com uma explicação.<div align="center">@@ -687,8 +713,8 @@ O repositório inclui um [`SKILL.md`](../../SKILL.md) raiz — um documento de t| Comando | Descrição ||:---|:---|-| `deeptutor init` | Criar ou atualizar `data/user/settings` para o espaço de trabalho atual |-| `deeptutor doctor [--online]` | Verificar se o espaço de trabalho está pronto para iniciar uma sessão; `--online` também sonda o provedor de modelo configurado, `--format json` imprime o relatório |+| `deeptutor init` | Criar ou atualizar `data/user/settings` no diretório de runtime atual |+| `deeptutor doctor [--online]` | Verificar se o runtime está pronto para iniciar uma sessão; `--online` também sonda o provedor de modelo configurado, `--format json` imprime o relatório || `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | Lançar backend + frontend juntos, opcionalmente desconectado ou sem abrir o navegador || `deeptutor stop [--home PATH]` | Parar um launcher iniciado com `--detach` || `deeptutor serve [--port PORT]` | Iniciar apenas o backend FastAPI |@@ -696,7 +722,7 @@ O repositório inclui um [`SKILL.md`](../../SKILL.md) raiz — um documento de t| `deeptutor run <capability> <message>` | Executar um turno de capacidade único (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); adicionar `--format json` para saída NDJSON || `deeptutor chat` | REPL interativo com controlos de capacidade, ferramenta, KB, notebook e histórico || `deeptutor partner list/create/start/stop` | Gerir partners ligados por IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Gerir bases de conhecimento e sincronizar fontes GitHub/web registadas (com comandos para adicionar ou remover fontes) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Gerir bases de conhecimento, conectar arquivos Kiwix, avaliar a qualidade da recuperação com um conjunto de perguntas e respostas e sincronizar fontes GitHub/web registadas (com comandos para adicionar ou remover fontes) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Gerir habilidades, instalar de hubs e publicar as suas (`eduhub:<slug>` por padrão, veja Ecossistema) || `deeptutor memory show/clear` | Inspecionar documentos de memória L2/L3 ou limpar memória L1/toda || `deeptutor session list/show/open/rename/delete` | Gerir sessões partilhadas |diff --git a/assets/README/README_RU.md b/assets/README/README_RU.mdindex 083ce0ba3..8229ab9f4 100644--- a/assets/README/README_RU.md+++ b/assets/README/README_RU.md@@ -5,12 +5,12 @@# DeepTutor: Пожизненное Персонализированное Обучение<p align="center">- <a href="https://deeptutor.info" target="_blank"><img alt="Docs — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> - <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Collaborate — work with us" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a>+ <a href="https://deeptutor.info" target="_blank"><img alt="Документация — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> + <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Сотрудничество — работайте с нами" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a></p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="Популярный репозиторий дня на GitHub" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Рейтинг истории звёзд" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -30,13 +30,13 @@[](https://www.python.org/downloads/)[](https://nextjs.org/)-[](LICENSE)+[](../../LICENSE)[](https://github.com/HKUDS/DeepTutor/releases)[](https://arxiv.org/abs/2604.26962)-[](https://discord.gg/eRsjPgMU4t)-[](./Communication.md)-[](https://github.com/HKUDS/DeepTutor/issues/78)+[](https://discord.gg/eRsjPgMU4t)+[](../../Communication.md)+[](https://github.com/HKUDS/DeepTutor/issues/78)[Возможности](#-ключевые-возможности) · [Начать](#-начало-работы) · [Исследовать](#-обзор-deeptutor) · [CLI](#%EF%B8%8F-deeptutor-cli--интерфейс-для-агентов) · [Экосистема](#-экосистема--eduhub-и-сообщество-навыков) · [Сообщество](#-сообщество)@@ -63,7 +63,7 @@ DeepTutor — это агентная учебная рабочая среда,- **Единая среда выполнения для всех режимов** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading и Immersive Watching работают в единой среде выполнения и используют общий контекст сессии, но сохраняют специализированные циклы и конвейеры для своих задач.- **Task Board** — отслеживайте учебные задачи в колонках «Сделать», «В работе» и «Готово»: добавляйте заметки, перемещайте карточки перетаскиванием или доступными с клавиатуры кнопками и восстанавливайте их из архива. Карточки остаются в текущем рабочем пространстве и используют действующие настройки оформления и языка; настройка модели не требуется.- **Связанный контекст обучения** — базы знаний, книги, черновики Co-Writer, блокноты, банки вопросов, персоны и Memory можно повторно использовать в поддерживающих их рабочих процессах с учётом грантов учётной записи и политик обучения.-- **Иммерсивное обучение по видео** — вставьте ссылку YouTube для нативного воспроизведения с повышенной конфиденциальностью, синхронизированными субтитрами, репетиторством с привязкой ко временным меткам и возобновляемым прогрессом; администраторы могут переключить воспроизведение на самостоятельно размещённый экземпляр Invidious без пересборки материалов.+- **Иммерсивное обучение по видео** — вставьте ссылку YouTube для нативного воспроизведения с повышенной конфиденциальностью, синхронизированными субтитрами, репетиторством с привязкой ко временным меткам, сохранёнными временными отметками и возобновляемым прогрессом; администраторы могут переключить воспроизведение на самостоятельно размещённый экземпляр Invidious без пересборки материалов.- **Субагенты и Partners** — из Chat обращайтесь к живой агентной среде (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw или DeepSeek) или к Partner, импортируйте прошлые разговоры и запускайте постоянных IM-компаньонов на том же мозге.- **Многодвигательные знания** — версионированные RAG-библиотеки на основе LlamaIndex, PageIndex, GraphRAG, LightRAG, удалённого LightRAG Server, самостоятельно размещённого WeKnora, библиотеки Tencent IMA или MarginNote 4, подключённого архива Kiwix ZIM либо связанного хранилища Obsidian, с подключаемым разбором документов. См. [нативные ролевые модели LightRAG](../../deeptutor/services/rag/pipelines/lightrag/README.md) для независимых настроек извлечения, запросов и обработки изображений, создания только со значениями по умолчанию и подтверждённых пересборок.- **Расширяемые инструменты и навыки** — встроенные инструменты, MCP-серверы, CLI-приложения, модели генерации изображений / видео / голоса и устанавливаемые навыки сообщества из EduHub.@@ -75,6 +75,19 @@ DeepTutor — это агентная учебная рабочая среда,DeepTutor поставляется с четырьмя путями установки. Все они используют одну структуру рабочего пространства: настройки хранятся в `data/user/settings/` в директории запуска (или в `DEEPTUTOR_HOME` / `deeptutor start --home`, если задано явно). Для полного приложения рекомендуемый процесс: **выбрать директорию рабочего пространства → установить → `deeptutor init` → `deeptutor start`**.+### Пробный запуск Docker одной командой++Если Docker ещё не установлен, сначала [установите Docker](https://docs.docker.com/get-docker/). Затем попробуйте полное приложение без настройки Python или Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++Откройте [http://127.0.0.1:3782](http://127.0.0.1:3782), настройте провайдеров моделей в разделе **Настройки → Провайдеры** и нажмите `Ctrl+C`, когда закончите. Именованный том `deeptutor-data` сохраняет настройки и локальные данные для следующего запуска.+### Рабочее пространство для контента**Рабочее пространство для контента** отделено от приватного каталога среды выполнения DeepTutor. Это папка, которую могут читать агенты; созданные файлы находятся в `outputs/<capability>/<session>/<turn>/`. Пользовательские рабочие пространства изолируют разговоры, учебные материалы, прогресс и кэши в приватном дереве `.deeptutor/data/`, недоступном файловым инструментам. Настройки, учётные данные и Memory остаются общими на уровне аккаунта.@@ -101,8 +114,8 @@ deeptutor workspace reset```bashmkdir -p my-deeptutor && cd my-deeptutorpip install -U deeptutor-deeptutor init # запрашивает порты + провайдер LLM + необязательные настройки встраивания/поиска-deeptutor start # запускает бэкенд + фронтенд; держите терминал открытым+deeptutor init # prompts for ports + LLM provider + optional embedding/search+deeptutor start # starts backend + frontend; keep the terminal open````deeptutor init` запрашивает порт бэкенда (по умолчанию `8001`), порт фронтенда (по умолчанию `3782`), провайдер LLM / базовый URL / API-ключ / модель, необязательный провайдер встраивания для базы знаний / RAG и необязательный провайдер поиска для Web Search.@@ -122,12 +135,12 @@ deeptutor start # запускает бэкенд + фронтенд; дерgit clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Создание venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1python3 -m venv .venv && source .venv/bin/activatepython -m pip install --upgrade pip-# Установка зависимостей бэкенда + фронтенда+# Install backend + frontend depspython -m pip install -e .( cd web && npm ci --legacy-peer-deps )@@ -152,14 +165,14 @@ python -m pip install --upgrade pip<summary><b>Необязательные дополнения при установке</b> — движки RAG / dev / partners / matrix / math-animator</summary>```bash-pip install -e ".[rag-lightrag]" # Встроенный движок LightRAG (точно поддерживаемая версия SDK)-pip install -e ".[graphrag]" # Движок Microsoft GraphRAG (Python 3.11–3.13)-pip install -e ".[dev]" # инструменты тестирования/линтинга-pip install -e ".[partners]" # SDK каналов IM для Партнёров+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 SDKspip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs-pip install -e ".[matrix]" # канал Matrix без E2EE/libolm-pip install -e ".[matrix-e2e]" # Matrix E2EE; требует libolm-pip install -e ".[math-animator]" # дополнение Manim; требует LaTeX/ffmpeg/системных библиотек+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```</details>@@ -273,7 +286,7 @@ Docker Desktop (macOS/Windows) обычно разрешает `host.docker.integit clone https://github.com/HKUDS/DeepTutor.gitcd DeepTutor-# Создание venv (macOS/Linux). Windows PowerShell:+# Create a venv (macOS/Linux). Windows PowerShell:# py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1python3 -m venv .venv-cli && source .venv-cli/bin/activatepython -m pip install --upgrade pip@@ -289,7 +302,7 @@ deeptutor chat<summary><b>Основные команды</b></summary>```bash-deeptutor chat # интерактивный REPL+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --tool rag --kb my-kbdeeptutor run chat "Explain Fourier transform"deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb@@ -329,7 +342,7 @@ deeptutor config show| `auth.json` | Необязательное переключение аутентификации, имя пользователя, хэш пароля, настройки токенов/куки || `integrations.json` | Необязательные настройки интеграции PocketBase и сайдкара || `interface.json` | Язык интерфейса и вывода модели / тема / настройки боковой панели |-| `document_parsing.json` | Выбор движка разбора, удалённые конечные точки и параметры конкретного движка |+| `document_parsing.json` | Выбор движка разбора и модели описания изображений, удалённые конечные точки и параметры конкретного движка || `video_learning.json` | Провайдер воспроизведения YouTube/Invidious по умолчанию, источники Invidious и необязательный адаптер транскриптов || `main.yaml` | Значения по умолчанию для среды выполнения и внедрение пути || `agents.yaml` | Настройки температуры и токенов для возможностей/инструментов |@@ -350,7 +363,9 @@ deeptutor config showКорневой файл `.env` проекта **не** читается как файл конфигурации приложения. Для минимальной настройки модели сохраните базовый URL и API-ключ в разделе **Настройки → Провайдеры**, затем добавьте и выберите LLM в разделе **Языковые модели**. Добавляйте профиль встраивания только если планируете использовать функции базы знаний / RAG.-Профили LLM и моделей задач предоставляют настройку формата API, если их провайдер поддерживает выбор. Оставьте `Auto` для обычной маршрутизации и резервного варианта или выберите `OpenAI Chat Completions`, `OpenAI Responses` либо `Anthropic Messages`; принудительный режим Responses по-прежнему работает с отказом по умолчанию. Сохраняемое поле — `api_format` (`auto`, `openai_chat`, `openai_responses` или `anthropic`); `wire_api` — производное состояние совместимости. Переопределения `Auto` / `Supported` / `Not supported` для каждой модели охватывают вызов инструментов, ввод изображений, вывод JSON и элементы управления рассуждением.+Для API Route выберите **API Route** в разделе **Настройки → Провайдеры** и введите ключ API Route. Предустановленная конфигурация использует `https://global.api-route.com/v1`; затем добавьте модель с её идентификатором API Route в разделе **Языковые модели**. Инструкции по настройке ключа и модели приведены в [кратком руководстве API Route](https://www.api-route.com/docs/quickstart).++Профили LLM и моделей задач предоставляют настройку **формата API**, если их провайдер поддерживает выбор. Оставьте `Auto` для обычной маршрутизации и резервного варианта или выберите `OpenAI Chat Completions`, `OpenAI Responses` либо `Anthropic Messages`; принудительный режим Responses по-прежнему работает с отказом по умолчанию. Сохраняемое поле — `api_format` (`auto`, `openai_chat`, `openai_responses` или `anthropic`); `wire_api` — производное состояние совместимости. Переопределения `Auto` / `Supported` / `Not supported` для каждой модели охватывают вызов инструментов, ввод изображений, вывод JSON и элементы управления рассуждением.</details>@@ -422,9 +437,9 @@ DeepTutor отделяет установленный код, приватноеПереключаемые пользователем инструменты: `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason` и `geogebra_analysis` — плюс `imagegen` и `videogen` после настройки соответствующей генеративной модели. Контекстные инструменты, такие как `rag`, `kb_files`, `knowledge_frontier`, `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) сохраняется между ходами; **одноразовые ссылки** (файлы, история чата, книги, разделы чтения, блокноты, банк вопросов, импортированные агенты) берутся из меню `+` для одного хода. Кнопка голосового ввода только транскрибирует текущее сообщение.+Контекст бывает двух видов: **постоянный контекст сессии** (возможность, рабочее пространство или курс, инструменты, базы знаний, персонаж, модель и состояние Reading / Mastery) сохраняется между ходами; **одноразовые ссылки** (файлы, история чата, книги, разделы чтения, блокноты, выбранные записи банка вопросов, импортированные агенты) берутся из меню `+` для одного хода. Кнопка голосового ввода только транскрибирует текущее сообщение.-На главной странице **Chat**, **Ask Questions**, **Quiz** и **Visualize** доступны в один клик; **Research** для цитируемых отчётов, **Solve** для пошаговых рассуждений и **Immersive Watching** находятся в разделе *Дополнительные возможности*. **Персонализированное обучение** объединяет Book, **Mastery Path**, **Immersive Reading**, Watching и **Практику**; Reading добавляет проверенные цитаты, сохранённые заметки, основанные на источниках действия чтения вслух / сопровождения обучения / работы со словарём / викторины / перевода и сохранение в блокнот, а Course Study сохраняет контекст, привязанный к курсу.+На главной странице **Chat**, **Ask Questions**, **Quiz** и **Visualize** доступны в один клик; **Research** для цитируемых отчётов, **Solve** для пошаговых рассуждений и **Immersive Watching** находятся в разделе *Дополнительные возможности*. **Персонализированное обучение** объединяет Book, **Mastery Path**, **Immersive Reading**, Watching и **Практику**; Reading добавляет проверенные цитаты, сохранённые заметки, естественное чтение вслух отрывков из источников / сопровождение обучения / работу со словарём / викторины / перевод и сохранение в блокнот, а Course Study сохраняет контекст, привязанный к курсу.</details>@@ -489,7 +504,7 @@ Co-Writer — это разделённое рабочее пространст<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Редактор Co-Writer с живым предварительным просмотром" width="900"></div>-Его определяющая идея — **хирургическое редактирование**: выберите фрагмент и попросите DeepTutor переписать, расширить или сократить его. Агент редактирования может опираться на базу знаний или веб-данные и ведёт журнал вызовов инструментов. Если черновик не изменился за время его работы, результат напрямую заменяет выделенный текст и остаётся обратимым с помощью **Undo**.+Его определяющая идея — **хирургическое редактирование**: выберите фрагмент и попросите DeepTutor переписать, расширить или сократить его. Выберите модель редактирования; она может использовать базу знаний или веб-данные и ведёт журнал вызовов инструментов. Если черновик не изменился за время его работы, результат напрямую заменяет выделенный текст и остаётся обратимым с помощью **Undo**.</details>@@ -529,12 +544,18 @@ Co-Writer — это разделённое рабочее пространстПереносите существующую библиотеку Obsidian, Hermes или Markdown? В [руководстве по миграции знаний](../../docs-for-user/KNOWLEDGE_MIGRATION.md) описаны варианты с подключённым хранилищем и индексированной копией.-При создании KB можно **создать новую** (загрузить и проиндексировать документы), **связать существующую** (повторно использовать индекс на месте) или **подключить Kiwix** (искать в одном предоставляемом сервером ZIM-архиве по мере необходимости). При создании выберите рабочее пространство для хранения KB; существующую KB можно перенести между рабочими пространствами после предварительного просмотра, сохранив назначения и сохранённые ссылки. База знаний также может отслеживать **репозитории GitHub** (репозиторий, ветка и glob-шаблон) или **URL сайтов документации** (с ограничениями глубины обхода и числа страниц, по умолчанию повторно синхронизируются каждые 24 часа); синхронизация сравнивает хеши содержимого, чтобы выявить добавленные, изменённые и удалённые материалы, поэтому документация, за которой вы следите, остаётся актуальной без повторной загрузки, а **связанные папки** подхватывают новые или изменённые локальные файлы при синхронизации. Переиндексирование записывает новую плоскую директорию `version-N` и сохраняет предыдущие, поэтому рабочий индекс никогда не уничтожается в процессе перестройки. Отдельный документ можно удалить даже из базы в состоянии **error** — убрав файл, который не удалось разобрать, без полного удаления и пересборки. Разбор документов — только текст, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM или LiteParse — выбирается в **Настройки → Знания и документы**, с отключёнными по умолчанию загрузками локальных моделей. Docling может также работать в **удалённом режиме**, обращаясь к серверу Docling Serve (без локальной установки и моделей), который настраивается на той же странице (`mode=remote`, базовый URL сервера и необязательный API-ключ) или через переменные окружения `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika работает только в удалённом режиме и указывает на сервер Apache Tika, настроенный на этой странице. CLI отражает жизненный цикл через `list/info/create/connect-kiwix/add/search/set-default/delete`, команды добавления/удаления источников, `list-sources` и `sync`.+При создании KB можно **создать новую** (загрузить и проиндексировать документы), **связать существующую** (повторно использовать индекс на месте) или **подключить Kiwix** (искать в одном предоставляемом сервером ZIM-архиве по мере необходимости). При создании выберите рабочее пространство для хранения KB; существующую KB можно перенести между рабочими пространствами после предварительного просмотра, сохранив назначения и сохранённые ссылки. База знаний также может отслеживать **репозитории GitHub** (репозиторий, ветка и glob-шаблон) или **URL сайтов документации** (с ограничениями глубины обхода и числа страниц, по умолчанию повторно синхронизируются каждые 24 часа); синхронизация сравнивает хеши содержимого, чтобы выявить добавленные, изменённые и удалённые материалы, поэтому документация, за которой вы следите, остаётся актуальной без повторной загрузки, а **связанные папки** подхватывают новые или изменённые локальные файлы при синхронизации. Переиндексирование записывает новую плоскую директорию `version-N` и сохраняет предыдущие, поэтому рабочий индекс никогда не уничтожается в процессе перестройки. Отдельный документ можно удалить даже из базы в состоянии **error** — убрав файл, который не удалось разобрать, без полного удаления и пересборки. Движок разбора документов — только текст, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM или LiteParse — и необязательная модель описания изображений выбираются в **Настройки → Знания и документы**, с отключёнными по умолчанию загрузками локальных моделей. Docling может также работать в **удалённом режиме**, обращаясь к серверу Docling Serve (без локальной установки и моделей), который настраивается на той же странице (`mode=remote`, базовый URL сервера и необязательный API-ключ) или через переменные окружения `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN`. Tika работает только в удалённом режиме и указывает на сервер Apache Tika, настроенный на этой странице. CLI отражает жизненный цикл через `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, команды добавления/удаления источников, `list-sources` и `sync`.Встроенный движок LightRAG устанавливается командой `pip install 'deeptutor[rag-lightrag]'`. Это дополнение содержит поддерживаемый SDK LightRAG, но не устанавливает MinerU. Выбирайте MinerU отдельно в разделе Разбор документов и либо настройте его облачный режим, либо установите актуальный локальный CLI, если нужен структурированный разбор. MinerU принимает PDF, распространённые растровые изображения, DOCX, PPTX и XLSX; устаревшая команда `magic-pdf` по-прежнему работает только с PDF. Текстовый и другие движки разбора не требуют MinerU.Нативные запросы LightRAG и инкрементальное индексирование требуют конфигурации встраивания, зафиксированной опубликованным индексом, включая модель, размерность и идентичность конечной точки. Если она меняется, восстановите исходную конфигурацию или пересоберите индекс с текущим встраиванием; индексы без зафиксированной идентичности встраивания требуют пересборки. Раздел сведений о базе знаний и представления версий индекса показывают рекомендации по восстановлению, а файлы остаются доступными для просмотра и скачивания.+**Оценка базы знаний.** Когда доступны несколько движков, вопрос «какой из них лучше ищет в этих материалах?» требует практической проверки — для этого есть `deeptutor kb eval`. Подготовьте набор вопросов и ответов (по одному объекту JSON на строку: `query` и отрывки `gold`, которые должен возвращать идеальный поиск), затем оцените KB командой `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`. Поиск для каждого примера выполняется тем же способом, что и в ходе чата; ранжированные цитаты сопоставляются с эталонными отрывками по точному тексту или лексическому пересечению (пороги настраиваются через `--min-ratio`; семантическая эквивалентность не оценивается), а результат содержит **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k**. Метрики — чистые функции от ранжирования, поэтому никакая модель не оценивает результат: оценки воспроизводимы и пригодны для сравнения, а сохранённый базовый результат превращает набор в проверку регрессий при смене модели встраивания, изменении переранжирования или экспериментах с размером фрагментов. Примеры, в которых поиск завершился ошибкой (отсутствующий индекс, неверные учётные данные), не получают оценки и указываются отдельно, не снижая средние значения. PageIndex использует рассуждение для поиска и не возвращает ранжированные фрагменты, поэтому исключён.++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ Co-Writer — это разделённое рабочее пространст<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="Хаб Пространства Обучения DeepTutor" width="900"></div>-Пространство Обучения — это уровень библиотеки, организации и персонализации. **Разговоры и материалы** содержат Chat History, блокноты с перемещаемыми записями и экспортом в Markdown, а также банк вопросов с ответами и объяснениями. **Практика** в Персонализированном обучении превращает сохранённые вопросы в сеансы повторения, отслеживание ошибок и повторение по расписанию. **Персонализация** содержит персонажей, навыки (сценарии `SKILL.md`), устанавливаемые одним кликом **MCP-сервисы** и **CLI-приложения** из каталога [CLI-Anything](https://github.com/HKUDS/CLI-Anything), причём руководство по использованию каждого приложения загружается по требованию. Отдельное рабочее пространство **My Courses** группирует разговоры по предметам и ветки репетиторов; каждый ресурс предлагается только в поддерживающих его рабочих процессах.+Пространство Обучения — это уровень библиотеки, организации и персонализации. **Разговоры и материалы** содержат Chat History, блокноты с перемещаемыми записями и экспортом в Markdown, а также банк вопросов с ответами и объяснениями. Запускайте **Практику** из выбранных вопросов банка вопросов или из Персонализированного обучения для сеансов повторения, отслеживания ошибок и повторения по расписанию. **Персонализация** содержит персонажей, навыки (сценарии `SKILL.md`), устанавливаемые одним кликом **MCP-сервисы** и **CLI-приложения** из каталога [CLI-Anything](https://github.com/HKUDS/CLI-Anything), причём руководство по использованию каждого приложения загружается по требованию. Отдельное рабочее пространство **My Courses** группирует разговоры по предметам и ветки репетиторов; каждый ресурс предлагается только в поддерживающих его рабочих процессах.<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Импорт навыков из EduHub" width="900">@@ -580,6 +601,10 @@ Co-Writer — это разделённое рабочее пространстНастройки — это операционная панель управления, которая открывается страницей **Общие** для выбора языка интерфейса и вывода модели. Навигатор с поиском ведёт на независимые страницы: **Личное** включает рабочие пространства, миграцию данных, внешний вид и статистику использования; **Обучение и разговоры** — стартовые подсказки, вложения, Video Learning, управление учащимися и опекунами, Прогресс обучения и Memory; **Модели и сервисы** — провайдеров, языковые модели, Task-модели, встраивание, поиск, речь и мультимодальную генерацию; **Возможности и интеграции** — инструменты, параметры возможностей, партнёров и агентов, знания и документы. **Система** включает сеть, состояние среды выполнения и сведения о проекте; **Архивные чаты** позволяют искать, восстанавливать или навсегда удалять архивные разговоры. Состояние среды выполнения показывает состояние бэкенда, резидентную память и матрицу **Готовности**, оценивающую блокирующие проблемы, предупреждения и рекомендации для возможностей. Рабочие пространства разделяют файлы тем и состояние обучения, а миграция данных обеспечивает проверяемый перенос и экспорт. **Провайдер** хранит адрес и учётные данные поставщика для повторного использования его сервисными моделями; на страницах моделей выбираются сохранённые провайдеры и задаются имена и возможности моделей. **Task-модели** закрепляют небольшую быструю модель за фоновой работой — названием разговоров и написанием стартовых подсказок — и при пустом значении используют активную модель по умолчанию. Речь объединяет синтез и распознавание речи; мультимодальная генерация объединяет модели изображений и видео. В разделе Партнёры и агенты настраиваются локальные агентные среды и удалённый шлюз Hermes.+**Синтез речи Xiaomi MiMo.** Добавьте провайдера Xiaomi MiMo с адресом `https://api.xiaomimimo.com/v1` и его API-ключом, затем добавьте `mimo-v2.5-tts` в разделе Настройки → Речь. Выберите предустановленный голос, например `mimo_default`, `冰糖` или `苏打`, формат вывода `wav` или `pcm16` и прослушайте образец перед применением. Голосовые инструкции управляют стилем и скоростью речи. Этот адаптер поддерживает только предустановленные голоса; создание и клонирование голоса требуют отдельных моделей и не поддерживаются. Если старая речевая модель MiMo была настроена через общий адаптер, совместимый с OpenAI, создайте её речевой профиль заново с провайдером Xiaomi MiMo, чтобы использовать протокол chat-completions. См. [официальное руководство по синтезу речи MiMo](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).++**Синтез речи MiniMax** — в разделе Настройки → Речь выберите MiniMax для преобразования текста в речь и модель `speech-2.8-hd`. Настройте API-ключ MiniMax и идентификатор системного или пользовательского голоса; голос по умолчанию — `English_expressive_narrator`. Базовый URL API по умолчанию — `https://api.minimax.io/v1`; для региона Китай используйте `https://api.minimaxi.com/v1`. Чтение вслух и прослушивание образцов используют нативную конечную точку синтеза речи с выводом в MP3, WAV, FLAC или PCM и настройками частоты дискретизации, скорости и языка. Идентификаторы голосов и доступность для учётных записей описаны в [API синтеза речи MiniMax](https://platform.minimax.io/docs/api-reference/speech-t2a-http).+**Video Learning** в разделе Настройки → Обучение и разговоры по умолчанию использует официальный YouTube IFrame Player с повышенной конфиденциальностью. Чтобы воспроизведение оставалось локальным, задайте управляемый администратором источник Invidious API (например, `http://127.0.0.1:3000`), протестируйте его, выберите Invidious и сохраните настройки. Новые и повторно открытые видео сразу используют выбранного провайдера с тем же идентификатором материала и прогрессом. Медиаданные Invidious передаются потоково через прокси DeepTutor с поддержкой диапазонов байтов; исходные URL не раскрываются браузеру и не сохраняются на диске. При сбое экземпляра DeepTutor не обращается к YouTube, пока учащийся явно не выберет нативный резервный вариант YouTube. Репетиторство по общедоступным субтитрам необязательно: установите `.[video-learning]`; без него воспроизведение продолжает работать, а действие **«Объяснить здесь»** на основе транскрипта отключается с указанием причины.<div align="center">@@ -623,11 +648,11 @@ CLI выводит команду туннеля, а затем сразу пы```textdata/-├── user/ # Рабочее пространство администратора + глобальные настройки-├── users/<uid>/ # Пользовательская область: история чата, память, блокноты, KB-├── partners/<id>/workspace/ # Область партнёра (синтетического пользователя)-├── cli-apps/ # Установленные CLI-приложения, монтируются в песочницу только для чтения-└── system/ # auth · grants · audit · user-secrets/<owner> (OAuth-токены)+├── user/ # Admin workspace + global settings+├── users/<uid>/ # Per-user scope: chat history, memory, notebooks, KBs+├── partners/<id>/workspace/ # Partner (synthetic-user) scope+├── cli-apps/ # Installed CLI apps, mounted read-only into the sandbox+└── system/ # auth · grants · audit · user-secrets/<owner> (OAuth tokens)```**Первый зарегистрированный пользователь становится администратором** и владеет каталогами моделей, учётными данными провайдеров, общими базами знаний, навыками, каноническими общими книгами и грантами для пользователей. Локальные пользователи, созданные администратором, выбирают Standard, Learner или Custom. Learner блокирует учебные возможности и политику материалов, добавляет адаптивный профиль и поддерживает отзываемые учётные данные устройства со сроком действия и дневными лимитами; авторизованные guardians могут просматривать отчёты, одобрять материалы и сбрасывать учётные данные. Остальные пользователи получают изолированные рабочие пространства и ограниченный доступ к моделям, KB, навыкам, Partners и общим книгам без получения необработанных API-ключей. Если `auth.json` уже содержит `username` + `password_hash`, эта учётная запись *является* администратором: `/register` остаётся закрытым, а учётные записи, созданные в `/admin/users`, всегда имеют `role=user` до повышения роли.@@ -650,7 +675,7 @@ data/`deeptutor chat` открывает интерактивный REPL и выбирает режим с помощью `--capability`; `deeptutor run <capability> "<message>"` принимает эту возможность как первый позиционный аргумент и завершается после одного хода. Обе команды принимают `--tool`, `--kb`, `--config` и `--workspace` для выбора зарегистрированного рабочего пространства.```bash-deeptutor chat # интерактивный REPL+deeptutor chat # interactive REPLdeeptutor chat --capability deep_solve --kb my-kb --tool ragdeeptutor run chat "Explain the Fourier transform" --tool rag --kb textbookdeeptutor run chat "Find recent work beyond this material" --kb textbook --tool knowledge_frontier@@ -668,10 +693,10 @@ deeptutor run deep_research "Survey 2026 papers on RAG" \DeepTutor создан для того, чтобы *им управлял другой агент*. Добавьте `--format json` к любой команде `run`, и каждый ход транслирует **NDJSON — одно событие на строку** (`content`, `tool_call`, `tool_result`, `done`, …), каждая строка помечена своим `session_id`. Запуски безопасны без TTY: пауза `ask_user` без TTY автоматически разрешается пустым ответом вместо зависания.```bash-# Один запрос, машиночитаемый+# One shot, machine-readabledeeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json-# Цепочка ходов в одной сессии с состоянием — захватите id, повторно используйте его+# Chain turns in one stateful session — capture the id, reuse itSID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \--config mode=report --config depth=standard --format json \| jq -r 'select(.type=="done").session_id')@@ -696,7 +721,7 @@ deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format j| `deeptutor run <capability> <message>` | Запустить один ход возможности (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); добавьте `--format json` для вывода NDJSON || `deeptutor chat` | Интерактивный REPL с управлением возможностями, инструментами, KB, блокнотами и историей || `deeptutor partner list/create/start/stop` | Управление партнёрами, подключёнными к IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | Управление базами знаний и синхронизация зарегистрированных источников GitHub/Web (с командами добавления/удаления источников) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Управление базами знаний, подключение архивов Kiwix, оценка качества поиска на наборе вопросов и ответов и синхронизация зарегистрированных источников GitHub/Web (с командами добавления/удаления источников) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Управление навыками, установка из хабов и публикация своих (`eduhub:<slug>` по умолчанию, см. Экосистема) || `deeptutor memory show/clear` | Просмотр документов памяти L2/L3 или очистка памяти L1/всей памяти || `deeptutor session list/show/open/rename/delete` | Управление общими сессиями |@@ -733,18 +758,18 @@ python -m pip install -e ./packaging/deeptutor-cli**Найти и установить** — в браузере откройте **Пространство Обучения → Навыки → Импорт из EduHub** для просмотра каталога и загрузки навыка прямо в вашу библиотеку. Из терминала:```bash-deeptutor skill search "socratic tutor" # поиск в EduHub (хаб по умолчанию)-deeptutor skill install socratic-tutor # получить → проверить → зарегистрировать-deeptutor skill install eduhub:[email protected] # указать хаб и версию-deeptutor skill list # локальные навыки с их хабовой принадлежностью+deeptutor skill search "socratic tutor" # search EduHub (the default hub)+deeptutor skill install socratic-tutor # fetch → verify → register+deeptutor skill install eduhub:[email protected] # pin a hub and a version+deeptutor skill list # local skills with their hub provenance```**Опубликуйте свой** — упакуйте `SKILL.md` и поделитесь им обратно с сообществом:```bash-deeptutor skill login # вход через браузер в EduHub-deeptutor skill publish ./my-skill # интерактивно: выберите трек + теги, затем загрузите-deeptutor skill update # откатиться или выпустить новую версию+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 реестром, поэтому агенты, отличные от DeepTutor (Claude Code, Codex, …), могут использовать его напрямую через CLI `eduhub` — `npx eduhub install socratic-tutor`.@@ -858,7 +883,7 @@ DeepTutor также стоит на плечах выдающихся прое<div align="center">-Лицензировано по [Apache License 2.0](LICENSE).+Лицензировано по [Apache License 2.0](../../LICENSE).<p><img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.DeepTutor&style=for-the-badge&color=00d4ff" alt="Просмотры">diff --git a/assets/README/README_TH.md b/assets/README/README_TH.mdindex f0cd2b3bc..39d951a5b 100644--- a/assets/README/README_TH.md+++ b/assets/README/README_TH.md@@ -10,7 +10,7 @@</p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="คลัง GitHub ที่กำลังเป็นที่นิยมประจำวัน" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="อันดับประวัติดาว" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -38,7 +38,7 @@[](../../Communication.md)[](https://github.com/HKUDS/DeepTutor/issues/78)-[คุณสมบัติ](#-คุณสมบัติหลัก) · [เริ่มต้น](#-เริ่มต้น) · [สำรวจ](#-สำรวจ-deeptutor) · [CLI](#️-deeptutor-cli--อินเทอร์เฟซ-agent-native) · [ระบบนิเวศ](#-ระบบนิเวศ--eduhub--ชุมชน-skills) · [ชุมชน](#-ชุมชน)+[คุณสมบัติ](#-คุณสมบัติหลัก) · [เริ่มต้น](#-เริ่มต้น) · [สำรวจ](#-สำรวจ-deeptutor) · [CLI](#️-deeptutor-cli--อินเทอร์เฟซ-agent-native) · [ระบบนิเวศ](#-ระบบนิเวศ--eduhub-และชุมชน-skills) · [ชุมชน](#-ชุมชน)</div>@@ -63,7 +63,7 @@ DeepTutor คือ workspace การเรียนรู้แบบ agent-n- **รันไทม์เดียวสำหรับทุกโหมด** — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading และ Immersive Watching ใช้ capability runtime และบริบท session ชุดเดียวกัน โดยยังคงลูปและ pipeline ที่ออกแบบมาเฉพาะสำหรับแต่ละวัตถุประสงค์- **Task Board** — ติดตามงานการเรียนใน To do, In progress และ Done พร้อมโน้ต การลากและวางหรือปุ่มย้ายที่ใช้ได้ด้วยแป้นพิมพ์ และรายการที่เก็บถาวรซึ่งกู้คืนได้ การ์ดจะอยู่ใน workspace ปัจจุบันและใช้การตั้งค่ารูปลักษณ์และภาษาเดิม โดยไม่ต้องกำหนดค่า model- **บริบทการเรียนรู้ที่เชื่อมต่อกัน** — ฐานความรู้, หนังสือ, ร่าง Co-Writer, สมุดบันทึก, คลังคำถาม, บุคลิกภาพ และ Memory สามารถนำมาใช้ซ้ำในเวิร์กโฟลว์ที่รองรับ โดยอยู่ภายใต้สิทธิ์ของบัญชีและนโยบายการเรียนรู้-- **การเรียนรู้ผ่านวิดีโออย่างดื่มด่ำ** — วางลิงก์ YouTube เพื่อเล่นวิดีโอแบบ native ที่เพิ่มความเป็นส่วนตัว พร้อมคำบรรยายที่ซิงค์กัน, การสอนพิเศษที่อ้างอิง timestamp และความคืบหน้าที่กลับมาเรียนต่อได้; ผู้ดูแลระบบสามารถเปลี่ยนการเล่นเป็น Invidious instance ที่ self-hosted ได้โดยไม่ต้องสร้างสื่อขึ้นใหม่+- **การเรียนรู้ผ่านวิดีโออย่างดื่มด่ำ** — วางลิงก์ YouTube เพื่อเล่นวิดีโอแบบ native ที่เพิ่มความเป็นส่วนตัว พร้อมคำบรรยายที่ซิงค์กัน, การสอนพิเศษที่อ้างอิง timestamp, จุดเวลาที่บันทึกไว้ และความคืบหน้าที่กลับมาเรียนต่อได้; ผู้ดูแลระบบสามารถเปลี่ยนการเล่นเป็น Invidious instance ที่ self-hosted ได้โดยไม่ต้องสร้างสื่อขึ้นใหม่- **ซับเอเจนต์และ Partners** — จาก Chat คุณสามารถปรึกษา agent harness แบบสด (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw หรือ DeepSeek) หรือ Partner, นำเข้าบทสนทนาในอดีต และรันเพื่อนถาวรบน IM ด้วยสมองเดียวกัน- **ความรู้หลายเอ็นจิน** — ไลบรารี RAG แบบเวอร์ชันผ่าน LlamaIndex, PageIndex, GraphRAG, LightRAG, LightRAG Server ระยะไกล, WeKnora deployment แบบ self-hosted, ไลบรารี Tencent IMA หรือ MarginNote 4, คลัง Kiwix ZIM ที่เชื่อมต่อ หรือ Obsidian vault ที่เชื่อมโยง พร้อมการแยกวิเคราะห์เอกสารแบบ pluggable ดู [native LightRAG role models](../../deeptutor/services/rag/pipelines/lightrag/README.md) สำหรับการตั้งค่า extraction, query และ vision ที่เป็นอิสระจากกัน, การสร้างแบบใช้ค่าเริ่มต้นเท่านั้น และการสร้างใหม่ที่ต้องมีการยืนยัน- **เครื่องมือและทักษะที่ขยายได้** — เครื่องมือในตัว, เซิร์ฟเวอร์ MCP, แอป CLI, โมเดลสร้างรูปภาพ/วิดีโอ/เสียง และทักษะชุมชนที่ติดตั้งได้จาก EduHub@@ -75,6 +75,19 @@ DeepTutor คือ workspace การเรียนรู้แบบ agent-nDeepTutor มีเส้นทางการติดตั้งสี่เส้นทาง ทั้งหมดแชร์ layout runtime home เดียวกัน: การตั้งค่าส่วนตัวอยู่ใน `data/user/settings/` ภายใต้ไดเร็กทอรีที่คุณเปิดตัว (หรือภายใต้ `DEEPTUTOR_HOME` / `deeptutor start --home` หากคุณตั้งค่าไว้อย่างชัดเจน) สำหรับแอปเต็มรูปแบบ ขั้นตอนที่แนะนำคือ **เลือกไดเร็กทอรี runtime home → ติดตั้ง → `deeptutor init` → `deeptutor start`**+### ทดลองใช้ Docker ด้วยคำสั่งเดียว++หากยังไม่ได้ติดตั้ง Docker ให้[ติดตั้ง Docker](https://docs.docker.com/get-docker/)ก่อน จากนั้นทดลองแอปเต็มรูปแบบได้โดยไม่ต้องตั้งค่า Python หรือ Node.js:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++เปิด [http://127.0.0.1:3782](http://127.0.0.1:3782), กำหนดค่า model providers ใน **Settings → Providers** และกด `Ctrl+C` เมื่อใช้งานเสร็จ named volume `deeptutor-data` จะเก็บการตั้งค่าและข้อมูลในเครื่องไว้สำหรับการรันครั้งถัดไป+### Content Workspace**Content Workspace** แยกออกจาก runtime home ส่วนตัวของ DeepTutor เป็นโฟลเดอร์ที่ agent อ่านได้ โดยไฟล์ที่สร้างจะอยู่ใต้ `outputs/<capability>/<session>/<turn>/` workspace แบบกำหนดเองแยกบทสนทนา สื่อการเรียน ความคืบหน้า และ cache ไว้ในโครงสร้างส่วนตัว `.deeptutor/data/` ที่เครื่องมือไฟล์ไม่สามารถเรียกดูได้ การตั้งค่า credentials และ Memory ยังคงแชร์กันในระดับบัญชี@@ -337,7 +350,7 @@ office skills ที่ติดตั้งมา — **docx / pdf / pptx / xls| `auth.json` | สวิตช์ auth แบบเสริม, ชื่อผู้ใช้, password hash, การตั้งค่า token/cookie || `integrations.json` | การตั้งค่า PocketBase แบบเสริมและการรวม sidecar || `interface.json` | ความชอบภาษา UI และภาษา output ของ model / ธีม / แถบด้านข้างของ UI |-| `document_parsing.json` | การเลือกเอ็นจินแยกวิเคราะห์, remote endpoints และตัวเลือกเฉพาะเอ็นจิน |+| `document_parsing.json` | การเลือกเอ็นจินแยกวิเคราะห์และโมเดลอธิบายรูปภาพ, remote endpoints และตัวเลือกเฉพาะเอ็นจิน || `video_learning.json` | provider การเล่น YouTube/Invidious เริ่มต้น, ต้นทาง Invidious และ transcript adapter แบบเสริม || `main.yaml` | ค่าเริ่มต้นพฤติกรรม runtime และการ inject path || `agents.yaml` | การตั้งค่า temperature และ token ของ capability/tool |@@ -358,7 +371,9 @@ office skills ที่ติดตั้งมา — **docx / pdf / pptx / xls`.env` ที่ root ของโปรเจกต์จะ **ไม่** ถูกอ่านเป็นไฟล์ config ของแอปพลิเคชัน สำหรับการตั้งค่า model เบื้องต้น ให้บันทึก Base URL และ API key ใน **Settings → Providers** จากนั้นเพิ่มและเลือก LLM ใน **Language models** เพิ่มโปรไฟล์ embedding เฉพาะเมื่อคุณวางแผนใช้ Knowledge Base / RAG features-โปรไฟล์ LLM และ task-model จะแสดงการตั้งค่า API format เมื่อ provider รองรับหลายตัวเลือก คงค่า Auto ไว้สำหรับการกำหนดเส้นทางและ fallback ตามปกติ หรือเลือก OpenAI Chat Completions, OpenAI Responses หรือ Anthropic Messages; การบังคับใช้ Responses ยังคง fail-closed ฟิลด์ที่บันทึกคือ `api_format` (`auto`, `openai_chat`, `openai_responses` หรือ `anthropic`); `wire_api` เป็นสถานะความเข้ากันได้ที่อนุมานจากค่านี้ การ override ระดับแต่ละโมเดลด้วย Auto / Supported / Not supported ครอบคลุมการเรียกใช้เครื่องมือ, การป้อนภาพ, เอาต์พุต JSON และตัวควบคุมการให้เหตุผล+สำหรับ API Route ให้เลือก **API Route** ใน **Settings → Providers** และกรอก API Route key preset ใช้ `https://global.api-route.com/v1`; จากนั้นเพิ่มโมเดลใน **Language models** โดยใช้ model ID ของ API Route ดู[คู่มือเริ่มต้น API Route](https://www.api-route.com/docs/quickstart)สำหรับการตั้งค่า key และ model++โปรไฟล์ LLM และ task-model จะแสดงการตั้งค่า **API format** เมื่อ provider รองรับหลายตัวเลือก คงค่า `Auto` ไว้สำหรับการกำหนดเส้นทางและ fallback ตามปกติ หรือเลือก `OpenAI Chat Completions`, `OpenAI Responses` หรือ `Anthropic Messages`; การบังคับใช้ Responses ยังคง fail-closed ฟิลด์ที่บันทึกคือ `api_format` (`auto`, `openai_chat`, `openai_responses` หรือ `anthropic`); `wire_api` เป็นสถานะความเข้ากันได้ที่อนุมานจากค่านี้ การ override ระดับแต่ละโมเดลด้วย `Auto` / `Supported` / `Not supported` ครอบคลุมการเรียกใช้เครื่องมือ, การป้อนภาพ, เอาต์พุต JSON และตัวควบคุมการให้เหตุผล</details>@@ -430,9 +445,9 @@ Chat คือความสามารถเริ่มต้นและสเครื่องมือที่ผู้ใช้สลับได้ ได้แก่ `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason`, และ `geogebra_analysis` — รวมถึง `imagegen` และ `videogen` เมื่อคุณกำหนดค่าโมเดลสร้างที่ตรงกัน เครื่องมือตามบริบทเช่น `rag`, `kb_files`, `knowledge_frontier`, `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` จะ mount อัตโนมัติเมื่อ turn มีบริบทที่ถูกต้อง-บริบทมีสองประเภท: **sticky session context** (capability, workspace หรือ course, tools, knowledge bases, persona, model และสถานะ Reading / Mastery) คงอยู่ตลอด turns; **one-time references** (ไฟล์, ประวัติ chat, หนังสือ, ส่วนการอ่าน, notebooks, question bank, imported agents) มาจากเมนู `+` สำหรับ turn เดียว ปุ่ม voice ทำหน้าที่ถอดเสียงเฉพาะข้อความปัจจุบัน+บริบทมีสองประเภท: **บริบท session ที่คงอยู่** (capability, workspace หรือ course, tools, knowledge bases, persona, model และสถานะ Reading / Mastery) คงอยู่ตลอด turns; **การอ้างอิงครั้งเดียว** (ไฟล์, ประวัติ chat, หนังสือ, ส่วนการอ่าน, notebooks, รายการคำถามที่เลือกจาก question bank, imported agents) มาจากเมนู `+` สำหรับ turn เดียว ปุ่ม voice ทำหน้าที่ถอดเสียงเฉพาะข้อความปัจจุบัน-Home ทำให้ **Chat**, **Ask Questions**, **Quiz** และ **Visualize** อยู่ห่างเพียงคลิกเดียว; **Research** สำหรับรายงานที่มีการอ้างอิง, **Solve** สำหรับการให้เหตุผลแบบละเอียด และ **Immersive Watching** อยู่ภายใต้ *More Capabilities* **Personalized Learning** รวม Book, **Mastery Path**, **Immersive Reading**, Watching และ **Practice**; Reading เพิ่ม citations ที่ตรวจสอบแล้ว, notes ที่บันทึกไว้, การอ่านออกเสียง / คำแนะนำการเรียน / คำศัพท์ / quiz / การแปลที่อ้างอิง source และการบันทึกลง notebook ขณะที่ Course Study มีบริบทที่ผูกกับ course ของตัวเอง+Home ทำให้ **Chat**, **Ask Questions**, **Quiz** และ **Visualize** อยู่ห่างเพียงคลิกเดียว; **Research** สำหรับรายงานที่มีการอ้างอิง, **Solve** สำหรับการให้เหตุผลแบบละเอียด และ **Immersive Watching** อยู่ภายใต้ *More Capabilities* **Personalized Learning** รวม Book, **Mastery Path**, **Immersive Reading**, Watching และ **Practice**; Reading เพิ่ม citations ที่ตรวจสอบแล้ว, notes ที่บันทึกไว้, การอ่านออกเสียงอย่างเป็นธรรมชาติจากข้อความต้นฉบับ / คำแนะนำการเรียน / คำศัพท์ / quiz / การแปล และการบันทึกลง notebook ขณะที่ Course Study มีบริบทที่ผูกกับ course ของตัวเอง</details>@@ -517,7 +532,7 @@ Co-Writer คือ workspace Markdown แบบ split-view สำหรับ<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="ตัวแก้ไข Co-Writer พร้อมตัวอย่างแบบสด" width="900"></div>-แนวคิดหลักคือ **การแก้ไขแบบผ่าตัด**: เลือกช่วงและขอให้ DeepTutor เขียนใหม่, ขยาย หรือย่อ agent การแก้ไขสามารถอ้างอิงการเปลี่ยนแปลงจาก knowledge base หรือหลักฐานเว็บ และเก็บ trace ของ tool calls หาก draft ไม่เปลี่ยนระหว่างทำงาน ผลลัพธ์จะแทนที่ข้อความที่เลือกโดยตรงและยังย้อนกลับได้ด้วย **Undo**+แนวคิดหลักคือ **การแก้ไขเฉพาะจุด**: เลือกช่วงและขอให้ DeepTutor เขียนใหม่, ขยาย หรือย่อ เลือกโมเดลสำหรับการแก้ไขได้; โมเดลสามารถใช้ knowledge base หรือหลักฐานเว็บ และเก็บ trace ของ tool calls หาก draft ไม่เปลี่ยนระหว่างทำงาน ผลลัพธ์จะแทนที่ข้อความที่เลือกโดยตรงและยังย้อนกลับได้ด้วย **Undo**</details>@@ -557,12 +572,18 @@ Knowledge bases คือคอลเลกชันเอกสารที่กำลังย้ายไลบรารี Obsidian, Hermes หรือ Markdown ที่มีอยู่ใช่ไหม ดู [คู่มือการย้ายข้อมูล Knowledge](../../docs-for-user/KNOWLEDGE_MIGRATION.md) สำหรับเส้นทางแบบ connected-vault และ indexed-copy-เมื่อสร้าง KB คุณสามารถ **สร้างใหม่** (อัพโหลดและทำ index เอกสาร), **เชื่อมโยงที่มีอยู่** (ใช้ index เดิมในที่เดิม) หรือ **เชื่อมต่อ Kiwix** (ค้นหา ZIM archive หนึ่งชุดที่ให้บริการอยู่ตามต้องการ) เลือก storage workspace ขณะสร้าง; หลังจากดูตัวอย่างแล้ว คุณสามารถย้าย KB ที่มีอยู่ระหว่าง workspaces โดยคงการกำหนดและการอ้างอิงที่บันทึกไว้ KB ยังสามารถติดตาม **GitHub repositories** (repo, branch, glob) หรือ **URL ของเว็บไซต์เอกสาร** (จำกัดความลึกในการ crawl และจำนวนหน้า โดย re-sync ทุก 24 ชั่วโมงเป็นค่าเริ่มต้น) ได้; การ sync จะเปรียบเทียบ hash ของเนื้อหาที่เพิ่ม เปลี่ยนแปลง และลบ เพื่อให้เอกสารที่ติดตามทันสมัยอยู่เสมอโดยไม่ต้องอัพโหลดใหม่ และ **linked folders** จะดึงไฟล์ local ที่เพิ่มหรือเปลี่ยนแปลงเข้ามาเมื่อ sync การ re-indexing จะเขียน directory `version-N` ใหม่และเก็บอันก่อนหน้าไว้ ดังนั้น index ที่ทำงานอยู่จะไม่ถูกทำลายระหว่างการสร้างใหม่ สามารถลบเอกสารหนึ่งรายการได้แม้ KB จะอยู่ในสถานะ **error** — ตัดไฟล์ที่แยกวิเคราะห์ไม่สำเร็จออกโดยไม่ต้องลบและสร้างใหม่ทั้งหมด การแยกวิเคราะห์เอกสาร — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM หรือ LiteParse — ถูกเลือกใน **Settings → Knowledge & documents** โดยการดาวน์โหลด local model ปิดโดยค่าเริ่มต้น Docling ยังสามารถรันในโหมด **remote** กับเซิร์ฟเวอร์ Docling Serve ได้ (ไม่ต้องติดตั้ง local หรือใช้ model ใด ๆ) โดยกำหนดค่าในหน้านั้น (`mode=remote`, server base URL และ API key ที่เป็นทางเลือก) หรือผ่าน environment variables `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` Tika ทำงานในโหมด remote เท่านั้นและชี้ไปยังเซิร์ฟเวอร์ Apache Tika ที่กำหนดค่าไว้ในหน้านั้น CLI ครอบคลุม lifecycle ด้วย `list/info/create/connect-kiwix/add/search/set-default/delete`, คำสั่งเพิ่ม/ลบ source, `list-sources` และ `sync`+เมื่อสร้าง KB คุณสามารถ **สร้างใหม่** (อัพโหลดและทำ index เอกสาร), **เชื่อมโยงที่มีอยู่** (ใช้ index เดิมในที่เดิม) หรือ **เชื่อมต่อ Kiwix** (ค้นหา ZIM archive หนึ่งชุดที่ให้บริการอยู่ตามต้องการ) เลือก storage workspace ขณะสร้าง; หลังจากดูตัวอย่างแล้ว คุณสามารถย้าย KB ที่มีอยู่ระหว่าง workspaces โดยคงการกำหนดและการอ้างอิงที่บันทึกไว้ KB ยังสามารถติดตาม **GitHub repositories** (repo, branch, glob) หรือ **URL ของเว็บไซต์เอกสาร** (จำกัดความลึกในการ crawl และจำนวนหน้า โดย re-sync ทุก 24 ชั่วโมงเป็นค่าเริ่มต้น) ได้; การ sync จะเปรียบเทียบ hash ของเนื้อหาที่เพิ่ม เปลี่ยนแปลง และลบ เพื่อให้เอกสารที่ติดตามทันสมัยอยู่เสมอโดยไม่ต้องอัพโหลดใหม่ และ **linked folders** จะดึงไฟล์ local ที่เพิ่มหรือเปลี่ยนแปลงเข้ามาเมื่อ sync การ re-indexing จะเขียน directory `version-N` ใหม่แบบแบนและเก็บอันก่อนหน้าไว้ ดังนั้น index ที่ทำงานอยู่จะไม่ถูกทำลายระหว่างการสร้างใหม่ สามารถลบเอกสารหนึ่งรายการได้แม้ KB จะอยู่ในสถานะ **error** — ตัดไฟล์ที่แยกวิเคราะห์ไม่สำเร็จออกโดยไม่ต้องลบและสร้างใหม่ทั้งหมด การแยกวิเคราะห์เอกสาร — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM หรือ LiteParse — และโมเดลอธิบายรูปภาพที่เป็นทางเลือก ถูกเลือกใน **Settings → Knowledge & documents** โดยการดาวน์โหลด local model ปิดโดยค่าเริ่มต้น Docling ยังสามารถรันในโหมด **remote** กับเซิร์ฟเวอร์ Docling Serve ได้ (ไม่ต้องติดตั้ง local หรือใช้ model ใด ๆ) โดยกำหนดค่าในหน้านั้น (`mode=remote`, server base URL และ API key ที่เป็นทางเลือก) หรือผ่าน environment variables `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` Tika ทำงานในโหมด remote เท่านั้นและชี้ไปยังเซิร์ฟเวอร์ Apache Tika ที่กำหนดค่าไว้ในหน้านั้น CLI ครอบคลุม lifecycle ด้วย `list/info/create/connect-kiwix/add/search/eval/set-default/delete`, คำสั่งเพิ่ม/ลบ source, `list-sources` และ `sync`เอ็นจิน LightRAG ในตัวติดตั้งด้วย `pip install 'deeptutor[rag-lightrag]'` ส่วนเสริมนั้นมี SDK LightRAG ที่รองรับอยู่ แต่ไม่ได้ติดตั้ง MinerU เลือก MinerU แยกต่างหากใน Document Parsing แล้วกำหนดค่าโหมด cloud ของมันหรือติดตั้ง local CLI เวอร์ชันปัจจุบันเมื่อต้องการการแยกวิเคราะห์แบบมีโครงสร้าง MinerU รองรับ PDF, รูปภาพ raster ทั่วไป, DOCX, PPTX และ XLSX; คำสั่ง `magic-pdf` แบบ legacy ยังคงรองรับเฉพาะ PDF เท่านั้น Text-only และเอ็นจินแยกวิเคราะห์อื่น ๆ ไม่จำเป็นต้องใช้ MinerUการ query และการทำ indexing แบบ incremental ของ LightRAG แบบ native ต้องใช้การตั้งค่า embedding ที่บันทึกไว้โดย index ที่เผยแพร่แล้ว ซึ่งรวมถึง model, dimension และ endpoint identity หากมีการเปลี่ยนแปลง ให้คืนค่าการตั้งค่าเดิมหรือสร้างใหม่ด้วย embedding ปัจจุบัน; index ที่ไม่มีการบันทึก embedding identity ไว้จำเป็นต้องสร้างใหม่ หน้ารายละเอียด knowledge base และหน้า index version จะแสดงคำแนะนำในการกู้คืน ในขณะที่ไฟล์ยังคงเปิดดูและดาวน์โหลดได้อยู่+**การประเมินคะแนนฐานความรู้** เมื่อมีหลายเอ็นจินให้เลือก คำถามว่า "เอ็นจินไหนค้นคืนข้อมูลได้ดีที่สุดสำหรับเนื้อหานี้?" ต้องตอบด้วยการทดลอง — `deeptutor kb eval` จึงช่วยตอบคำถามนี้ สร้างชุด QA (หนึ่ง JSON object ต่อบรรทัด: `query` พร้อมข้อความ `gold` ที่การค้นคืนในอุดมคติควรส่งกลับ) จากนั้นประเมิน KB ด้วย `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]` แต่ละกรณีจะค้นคืนผ่านเส้นทางเดียวกับที่ chat turn ใช้ โดยจับคู่ citations ที่จัดอันดับแล้วกับข้อความ gold ด้วยข้อความที่ตรงกันหรือการทับซ้อนของคำ (ปรับ threshold ได้ด้วย `--min-ratio`; ไม่ได้ประเมินความเทียบเท่าทางความหมาย) และรายงาน **Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k** metrics เป็นฟังก์ชันบริสุทธิ์ที่คำนวณจากอันดับ จึงไม่มีโมเดลตัดสิน output: คะแนนสามารถทำซ้ำและเปรียบเทียบความต่างได้ และ baseline ที่บันทึกไว้ช่วยให้ชุด QA เป็นเกณฑ์ตรวจสอบ regression เมื่อเปลี่ยน embedding, เปลี่ยน reranker หรือทดลอง chunk size กรณีที่ค้นหาไม่สำเร็จ (เช่น ไม่มี index หรือ credentials ไม่ถูกต้อง) จะไม่มีคะแนนและรายงานแยกต่างหาก แทนที่จะทำให้ค่าเฉลี่ยลดลง PageIndex ใช้การให้เหตุผลเป็น retrieval และไม่ส่งคืน chunks ที่จัดอันดับ จึงไม่รวมอยู่ในการประเมินนี้++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -572,13 +593,13 @@ Knowledge bases คือคอลเลกชันเอกสารที่<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="ศูนย์กลาง Learning Space ของ DeepTutor" width="900"></div>-Learning Space คือชั้น library, organization และ personalization **Conversations & Materials** เก็บ Chat History, notebooks ที่ย้าย records และ export เป็น Markdown ได้ และ question bank พร้อมคำตอบและคำอธิบาย **Practice** ใน Personalized Learning เปลี่ยนคำถามที่บันทึกไว้เป็น session ทบทวน การติดตามข้อผิดพลาด และการทบทวนซ้ำตามกำหนด **Personalization** เก็บ personas, skills (`SKILL.md` playbooks), **MCP Services** แบบคลิกเดียว และ **CLI Apps** จาก catalog [CLI-Anything](https://github.com/HKUDS/CLI-Anything) โดยแต่ละรายการมีคู่มือการใช้งานที่โหลดตามต้องการ workspace **My Courses** ที่แยกออกมาจะจัดกลุ่มบทสนทนาตามวิชาและ tutor threads; asset แต่ละรายการจะแสดงเฉพาะในเวิร์กโฟลว์ที่รองรับเท่านั้น+Learning Space คือชั้น library, organization และ personalization **Conversations & Materials** เก็บ Chat History, notebooks ที่ย้าย records และ export เป็น Markdown ได้ และ question bank พร้อมคำตอบและคำอธิบาย เริ่ม **Practice** จากคำถามที่เลือกใน question bank หรือจาก Personalized Learning เพื่อทบทวน ติดตามข้อผิดพลาด และทบทวนซ้ำตามกำหนด **Personalization** เก็บ personas, skills (`SKILL.md` playbooks), **MCP Services** แบบคลิกเดียว และ **CLI Apps** จาก catalog [CLI-Anything](https://github.com/HKUDS/CLI-Anything) โดยแต่ละรายการมีคู่มือการใช้งานที่โหลดตามต้องการ workspace **My Courses** ที่แยกออกมาจะจัดกลุ่มบทสนทนาตามวิชาและ tutor threads; asset แต่ละรายการจะแสดงเฉพาะในเวิร์กโฟลว์ที่รองรับเท่านั้น<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="นำเข้า skills จาก EduHub" width="900"></div>-คุณไม่จำเป็นต้องเขียน skill ทุกอันเอง — **นำเข้าจาก EduHub** จะเรียกดู catalog ชุมชนและดาวน์โหลด skill ตรงเข้า library ผ่านประตูความปลอดภัย (ดู [ระบบนิเวศ](#-ระบบนิเวศ--eduhub--ชุมชน-skills))+คุณไม่จำเป็นต้องเขียน skill ทุกอันเอง — **นำเข้าจาก EduHub** จะเรียกดู catalog ชุมชนและดาวน์โหลด skill ตรงเข้า library ผ่านประตูความปลอดภัย (ดู [ระบบนิเวศ](#-ระบบนิเวศ--eduhub-และชุมชน-skills))</details>@@ -608,6 +629,11 @@ Memory Graph แสดงพีระมิดทั้งหมด — กาSettings คือศูนย์ควบคุมการทำงาน โดยเปิดที่หน้า **General** สำหรับภาษา UI และภาษา output ของ model ตัวนำทางที่ค้นหาได้เชื่อมไปยังหน้าแยกกัน: **Personal** ครอบคลุม Workspaces, Data migration, Appearance และ Usage statistics; **Learning & conversation** ครอบคลุมจุดเริ่มต้น ไฟล์แนบ Video Learning การควบคุมผู้เรียนและผู้ปกครอง Learning progress และ Memory; **Models & services** ครอบคลุม Providers, Language models, Task models, Embedding, Search, Voice และ Multimodal generation; **Features & integrations** ครอบคลุมเครื่องมือ พารามิเตอร์ความสามารถ Partners & agents และ Knowledge & documents **System** มี Network, Runtime status และ About; **Archived chats** ใช้ค้นหา กู้คืน หรือลบบทสนทนาที่เก็บถาวรอย่างถาวร Runtime status แสดงสถานะ backend, resident memory และเมทริกซ์ **Readiness** ที่ประเมินปัญหาที่ขัดขวาง คำเตือน และข้อเสนอแนะของความสามารถ Workspaces แยกไฟล์แต่ละหัวข้อและสถานะการเรียน โดยมีการย้ายข้อมูลที่ตรวจสอบแล้วและการส่งออกใน Data migration **provider** เก็บที่อยู่และ credential ของผู้ให้บริการเพื่อให้ model ของบริการนั้นใช้ซ้ำได้ หน้า model เลือก provider ที่บันทึกไว้และกำหนดชื่อและความสามารถของ model **Task models** กำหนด model ขนาดเล็กที่รวดเร็วสำหรับงานเบื้องหลัง เช่น การตั้งชื่อบทสนทนาและเขียนจุดเริ่มต้น และใช้ model เริ่มต้นที่ใช้งานอยู่เมื่อปล่อยว่าง Voice รวมการสังเคราะห์เสียงพูดและการถอดเสียง ส่วน Multimodal generation รวม model ภาพและวิดีโอ Partners & agents กำหนดค่า harness ในเครื่องและ Hermes gateway ระยะไกล+**เสียงพูด Xiaomi MiMo** เพิ่ม Xiaomi MiMo provider ด้วย `https://api.xiaomimimo.com/v1` และ API key จากนั้นเพิ่ม `mimo-v2.5-tts` ใน Settings → Voice เลือก preset เช่น `mimo_default`, `冰糖` หรือ `苏打`, ใช้ output แบบ `wav` หรือ `pcm16` และทดลองฟังก่อนนำไปใช้ คำสั่งเสียงควบคุมรูปแบบและความเร็วในการพูด adapter นี้รองรับเฉพาะเสียง preset; การออกแบบเสียงและการโคลนเสียงต้องใช้โมเดลแยกต่างหากและไม่รองรับใน adapter นี้ หากเคยกำหนดค่าโมเดลเสียง MiMo รุ่นเก่าผ่าน adapter ทั่วไปที่เข้ากันได้กับ OpenAI ให้สร้างรายการเสียงใหม่โดยใช้ Xiaomi MiMo provider เพื่อให้ใช้ protocol chat-completions ดู[คู่มือเสียง MiMo อย่างเป็นทางการ](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5)++**เสียงพูด MiniMax** — ใน Settings → Voice เลือก MiniMax สำหรับ text-to-speech และเลือก `speech-2.8-hd` กำหนดค่า MiniMax API key และ voice ID ของระบบหรือที่กำหนดเอง; เสียงเริ่มต้นคือ `English_expressive_narrator` API base เริ่มต้นคือ `https://api.minimax.io/v1`; สำหรับภูมิภาคจีนใช้ `https://api.minimaxi.com/v1` การอ่านออกเสียงและการทดลองเสียงใช้ native speech endpoint พร้อม output แบบ MP3, WAV, FLAC หรือ PCM รวมถึงตัวควบคุม sample rate, ความเร็ว และภาษา ดู[MiniMax speech API](https://platform.minimax.io/docs/api-reference/speech-t2a-http)สำหรับ voice IDs และความพร้อมใช้งานของบัญชี++**Video Learning** ภายใต้ Settings → Learning & conversation ใช้ YouTube IFrame Player อย่างเป็นทางการที่เพิ่มความเป็นส่วนตัวเป็นค่าเริ่มต้น หากต้องการให้การเล่นอยู่ในระบบ local ให้ตั้งค่า Invidious API origin ที่ผู้ดูแลระบบจัดการ (ตัวอย่างเช่น `http://127.0.0.1:3000`), ทดสอบ, เลือก Invidious แล้วบันทึก วิดีโอใหม่หรือวิดีโอที่เปิดอีกครั้งจะใช้ provider ทันทีโดยมี material ID และความคืบหน้าเดิม สื่อ Invidious จะ stream ผ่าน byte-range proxy ของ DeepTutor; upstream URLs จะไม่ถูกเปิดเผยต่อเบราว์เซอร์หรือเก็บไว้บนดิสก์ หาก instance ล้มเหลว DeepTutor จะยังคงออฟไลน์จาก YouTube จนกว่าผู้เรียนจะเลือก fallback ไปยัง native YouTube อย่างชัดเจน การสอนพิเศษจากคำบรรยายสาธารณะเป็นทางเลือก: ติดตั้ง `.[video-learning]`; การเล่นยังคงทำงานได้หากไม่มี ส่วน **Explain here** ที่อิง transcript จะถูกปิดใช้งานพร้อมระบุเหตุผล<div align="center">@@ -616,7 +642,7 @@ Settings คือศูนย์ควบคุมการทำงาน โส่วนส่วนใหญ่ใช้ draft-and-apply flow เพื่อให้คุณทดสอบ provider ก่อนยืนยัน คุณยังสามารถแค่ถามใน Chat ได้เช่นกัน: ผู้ช่วยจะอ่านการกำหนดค่าปัจจุบัน, ใช้การเปลี่ยนแปลง และบอกว่าจำเป็นต้องรีสตาร์ทหรือ re-index หรือไม่ — โดยทดสอบ model ใหม่ก่อนที่จะยืนยัน จึงไม่สามารถเปลี่ยนตัวเองไปยังสิ่งที่เข้าถึงไม่ได้ API keys จะไม่ผ่านเข้าไปใน model เลย ซึ่งจะเปิดฟอร์มที่ตรงกันให้คุณแทน ธีมสี่แบบมาในกล่อง — Default, Cream, Dark และ Glass ไฟล์ `.env` ที่ root ของโปรเจกต์ถูกเพิกเฉยโดยเจตนา; การกำหนดค่า runtime อยู่ใน `data/user/settings/*.json` เว้นแต่ `DEEPTUTOR_HOME` หรือ `deeptutor start --home` จะชี้แอปไปที่อื่น-**OpenAI Codex OAuth (ทดลอง)** การเพิ่ม **OpenAI Codex** ภายใต้ **Settings → Providers** จะเปิดการลงชื่อเข้าใช้ผ่านเบราว์เซอร์ที่รันกับแผน ChatGPT ของคุณเอง จึงไม่จำเป็นต้องใช้ `OPENAI_API_KEY` Tokens อยู่เฉพาะใน `data/system/user-secrets/<owner>/private/openai-codex/` — ในการปรับใช้แบบ multi-container ด้วย Compose จะอยู่นอกเหนือทุก tree ที่ exec sandbox สามารถเข้าถึงได้ — และ DeepTutor จะไม่อ่านหรือแก้ไข `~/.codex` CLI login ของคุณเลย รายการ model มาจาก catalog แบบสดของบัญชีนั้น; การลงชื่อเข้าใช้จะเผยแพร่โปรไฟล์ แต่จะกลายเป็น model ที่ใช้งานอยู่ก็ต่อเมื่อยังไม่มีการกำหนดค่า LLM ใด ๆ เท่านั้น จึงไม่มีทางเปลี่ยนทิศทางของการปรับใช้โดยที่คุณไม่รู้ตัว เนื่องจาก token อนุญาตให้ใช้แผนของคนคนเดียว โปรไฟล์นี้จึงไม่สามารถแชร์ผ่าน per-user grants ได้ — แต่ละบัญชีต้องลงชื่อเข้าใช้ด้วยตัวเอง รวมถึงผู้ใช้ทั่วไปด้วย: การ์ดลงชื่อเข้าใช้ของพวกเขาจะอยู่ภายใต้ **Providers** และ models, catalog และการลงชื่อออกที่ได้จะเป็นส่วนตัวเฉพาะบัญชีนั้นเท่านั้น+**OpenAI Codex OAuth (ทดลอง)** การเพิ่ม **OpenAI Codex** ภายใต้ **Settings → Providers** จะเปิดการลงชื่อเข้าใช้ผ่านเบราว์เซอร์ที่รันกับแผน ChatGPT ของคุณเอง จึงไม่จำเป็นต้องใช้ `OPENAI_API_KEY` Tokens อยู่เฉพาะใน `data/system/user-secrets/<owner>/private/openai-codex/` — ในการปรับใช้แบบ multi-container ด้วย Compose จะอยู่นอกเหนือทุก tree ที่ exec sandbox สามารถเข้าถึงได้ — และ DeepTutor จะไม่อ่านหรือแก้ไข `~/.codex` CLI login ของคุณเลย รายการ model มาจาก catalog แบบสดของบัญชีนั้น; การลงชื่อเข้าใช้จะเผยแพร่โปรไฟล์ แต่จะกลายเป็น model ที่ใช้งานอยู่ก็ต่อเมื่อยังไม่มีการกำหนดค่า LLM ใด ๆ เท่านั้น เนื่องจาก token อนุญาตให้ใช้แผนของคนคนเดียว โปรไฟล์นี้จึงไม่สามารถแชร์ผ่าน per-user grants ได้ — แต่ละบัญชีต้องลงชื่อเข้าใช้ด้วยตัวเอง รวมถึงผู้ใช้ทั่วไปด้วย: การ์ดลงชื่อเข้าใช้ของพวกเขาจะอยู่ภายใต้ **Providers** และ models, catalog และการลงชื่อออกที่ได้จะเป็นส่วนตัวเฉพาะบัญชีนั้นเท่านั้นเมื่อลงชื่อเข้าใช้และตอน **Refresh models** DeepTutor จะอ่านเวอร์ชันเสถียรล่าสุดของ `@openai/codex` จาก official npm registry และใช้เป็น `client_version` ของ catalog request นี่เป็นเพียง metadata: จะไม่ติดตั้ง ดาวน์โหลด หรืออัพเกรด Codex CLI และ npm request จะไม่พก OAuth credentials ไปด้วย การค้นหานี้มี deadline สามวินาทีและขีดจำกัดขนาด response 64 KiB หากล้มเหลว DeepTutor จะใช้เวอร์ชันที่สำเร็จล่าสุดของบัญชีนั้น หรือ fallback ที่มีอยู่ในตัวเมื่อไม่มีอะไรถูก cache ไว้ จะบันทึกเวอร์ชันใหม่ก็ต่อเมื่อ catalog แบบสดถูก parse สำเร็จเท่านั้น; validators จะไม่ถูกนำมาใช้ซ้ำข้ามเวอร์ชันหรือข้าม credential generation การถูกปฏิเสธเวอร์ชันหรือโครงสร้าง catalog ที่เข้ากันไม่ได้จะอนุญาตให้ retry หนึ่งครั้งด้วยเวอร์ชันก่อนหน้า; ความล้มเหลวด้าน authentication, rate-limit และ TLS จะไม่ถูก retry ในฐานะปัญหาเรื่องเวอร์ชัน การรีเฟรชแบบ manual ที่ล้มเหลวจะรายงาน error แทนที่จะนำ catalog ที่ cache ไว้เดิมมาแสดงว่าถูกรีเฟรชแล้ว@@ -716,7 +742,7 @@ repo มี root [`SKILL.md`](../../SKILL.md) — เอกสาร handover ~2| คำสั่ง | คำอธิบาย ||:---|:---|| `deeptutor init` | สร้างหรืออัพเดต `data/user/settings` ใน runtime home ปัจจุบัน |-| `deeptutor doctor [--online]` | ตรวจสอบว่า workspace พร้อมเริ่ม session หรือไม่; `--online` ยังตรวจสอบ model provider ที่กำหนดค่าไว้ด้วย, `--format json` พิมพ์รายงานออกมา |+| `deeptutor doctor [--online]` | ตรวจสอบว่า runtime พร้อมเริ่ม session หรือไม่; `--online` ยังตรวจสอบ model provider ที่กำหนดค่าไว้ด้วย, `--format json` พิมพ์รายงานออกมา || `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | เปิดตัว backend + frontend ด้วยกัน; เลือก detach หรือปิดการเปิดเบราว์เซอร์ได้ || `deeptutor stop [--home PATH]` | หยุด launcher ที่เริ่มด้วย `--detach` || `deeptutor serve [--port PORT]` | เริ่มเฉพาะ FastAPI backend |@@ -724,7 +750,7 @@ repo มี root [`SKILL.md`](../../SKILL.md) — เอกสาร handover ~2| `deeptutor run <capability> <message>` | รัน capability turn เดียว (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `immersive_watching`, `audio_overview`); เพิ่ม `--format json` สำหรับ NDJSON output || `deeptutor chat` | Interactive REPL พร้อม capability, tool, KB, notebook และ history controls || `deeptutor partner list/create/start/stop` | จัดการ partners ที่เชื่อมต่อผ่าน IM |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | จัดการ knowledge bases และ sync GitHub/web sources ที่ลงทะเบียนไว้ (พร้อมคำสั่งเพิ่ม/ลบ source) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | จัดการ knowledge bases, เชื่อมต่อคลัง Kiwix, ประเมินคุณภาพ retrieval เทียบกับชุด QA และ sync GitHub/web sources ที่ลงทะเบียนไว้ (พร้อมคำสั่งเพิ่ม/ลบ source) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | จัดการทักษะ ติดตั้งจากฮับ และเผยแพร่ของคุณเอง (`eduhub:<slug>` โดยค่าเริ่มต้น ดู Ecosystem) || `deeptutor memory show/clear` | ตรวจสอบ L2/L3 memory docs หรือล้าง L1/all memory || `deeptutor session list/show/open/rename/delete` | จัดการ shared sessions |diff --git a/assets/README/README_TW.md b/assets/README/README_TW.mdindex 9a888051c..f0ab9b7bf 100644--- a/assets/README/README_TW.md+++ b/assets/README/README_TW.md@@ -5,12 +5,12 @@# DeepTutor:終身個人化學習導師<p align="center">- <a href="https://deeptutor.info" target="_blank"><img alt="Docs — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> - <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="Collaborate — work with us" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a>+ <a href="https://deeptutor.info" target="_blank"><img alt="文件 — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a> + <a href="https://deeptutor.info/collaborate/" target="_blank"><img alt="合作 — 與我們攜手" src="https://img.shields.io/badge/Collaborate-work%20with%20us%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a></p><p align="center">-<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a>+<a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending"><img alt="GitHub 今日熱門儲存庫" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&type=trending" height="55"></picture></a> <a href="https://trendshift.io/repositories/17099"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS/DeepTutor | Trendshift" width="250" height="55"></a> <a href="https://www.star-history.com/hkuds/deeptutor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark"><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor"><img alt="Star History 排名" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" width="185" height="55"></picture></a></p><p align="center">@@ -63,7 +63,7 @@ DeepTutor 是代理程式原生的學習工作區,在同一個可擴充系統- **所有模式共用一套執行階段** — Chat、Ask Questions、Quiz、Research、Visualize、Solve、Course Study、Mastery Path、Immersive Reading 與 Immersive Watching 共用同一套能力執行階段與工作階段情境,同時保有針對各自用途設計的迴圈與管線。- **Task Board** — 以待辦、進行中與已完成追蹤學習任務,並可加入備註、透過拖放或支援鍵盤操作的移動按鈕調整狀態,也能從封存中還原任務。卡片會保留在目前的工作區,沿用既有的外觀與語言設定;無須設定模型。- **相互連結的學習情境** — 知識庫、書籍、Co-Writer 草稿、筆記本、題庫、角色設定與 Memory 可在支援這些內容的工作流程中重複使用,但仍受帳號授權與學習政策限制。-- **沉浸式影片學習** — 貼上 YouTube 連結,即可使用隱私強化的原生播放、同步字幕、以時間戳為依據的教學,以及可續接的學習進度;管理員也能將播放切換至自架的 Invidious 執行個體,無須重新建立素材。+- **沉浸式影片學習** — 貼上 YouTube 連結,即可使用隱私強化的原生播放、同步字幕、以時間戳為依據的教學、已儲存的時間戳標記,以及可續接的學習進度;管理員也能將播放切換至自架的 Invidious 執行個體,無須重新建立素材。- **子代理程式與 Partners** — 可從 Chat 諮詢即時代理程式執行框架(Claude Code、Codex、Grok CLI、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw 或 DeepSeek)或 Partner、匯入過往對話,並讓持續運作的 IM 夥伴共用同一套核心。- **多引擎知識系統** — 透過 LlamaIndex、PageIndex、GraphRAG、LightRAG、遠端 LightRAG Server、自架 WeKnora 知識庫、Tencent IMA 或 MarginNote 4 知識庫、連接的 Kiwix ZIM 封存檔,或連結的 Obsidian vault 建立版本化 RAG 知識庫,並支援可插拔的文件解析。請參閱[原生 LightRAG 角色模型](../../deeptutor/services/rag/pipelines/lightrag/README.md),了解獨立的擷取、查詢與視覺設定、僅預設建立,以及確認後的重建。- **可擴充的工具與技能** — 內建工具、MCP 伺服器、CLI 應用程式、影像/影片/語音生成模型,以及可從 EduHub 安裝的社群技能。@@ -75,6 +75,19 @@ DeepTutor 是代理程式原生的學習工作區,在同一個可擴充系統DeepTutor 提供四種安裝方式,皆共用同一套執行環境目錄配置:私有設定會儲存在啟動目錄下的 `data/user/settings/`(若明確設定 `DEEPTUTOR_HOME` 或 `deeptutor start --home`,則改儲存在該位置)。完整應用程式的建議流程是:**選擇一個執行環境目錄 → 安裝 → `deeptutor init` → `deeptutor start`**。+### 一行指令試用 Docker++若尚未安裝 Docker,請先[安裝 Docker](https://docs.docker.com/get-docker/)。接著無須設定 Python 或 Node.js,即可試用完整應用程式:++```bash+docker run --rm --name deeptutor \+ -p 127.0.0.1:3782:3782 \+ -v deeptutor-data:/app/data \+ ghcr.io/hkuds/deeptutor:latest+```++開啟 [http://127.0.0.1:3782](http://127.0.0.1:3782),在 **Settings → Providers** 設定模型供應商,使用完畢後按下 `Ctrl+C`。具名的 `deeptutor-data` volume 會保留設定與本機資料,供下次執行使用。+### 內容工作區**內容工作區(Content Workspace)**與 DeepTutor 的私有執行環境目錄是分開的。這是代理程式可以讀取的資料夾,生成的檔案會放在 `outputs/<capability>/<session>/<turn>/` 下。自訂工作區會將對話、學習素材、進度與快取隔離在私有的 `.deeptutor/data/` 目錄樹中,檔案工具無法瀏覽此目錄。設定、憑證與 Memory 則維持帳號層級共用。@@ -307,7 +320,7 @@ deeptutor config show<details><summary><b>程式碼執行沙箱(office skills)</b> · 執行模型為 docx/pdf/pptx/xlsx 產生的程式碼</summary>-內建的 office skills(**docx/pdf/pptx/xlsx**)會讓模型撰寫一段簡短的 Python 指令碼(`python-docx`、`reportlab`、`openpyxl` 等),透過唯一的 `exec` 工具執行,再提供下載 URL。只要有啟用中的沙箱後端,該工具就會掛載。DeepTutor 會依下列順序選用已設定的最強後端:+內建的 office skills(**docx/pdf/pptx/xlsx**)會讓模型撰寫一段簡短的 Python 指令碼(`python-docx`、`reportlab`、`openpyxl` 等),透過唯一的 `exec` 工具執行,再呈現已儲存的工作區檔案。只要有啟用中的沙箱後端,這些工具就會掛載。DeepTutor 會依下列順序選用已設定的最強後端:- **Runner sidecar:** `DEEPTUTOR_SANDBOX_RUNNER_URL` 會將執行工作導向 `Dockerfile.runner` 所提供、經過強化且採最低權限的服務。- **Linux bubblewrap:** 若可使用 `bwrap`,它會隔離處理程序與檔案。@@ -329,7 +342,7 @@ deeptutor config show| `auth.json` | 選用的驗證開關、使用者名稱、密碼雜湊、token/cookie 設定 || `integrations.json` | 選用的 PocketBase 與 sidecar 整合設定 || `interface.json` | UI 與模型輸出語言/主題/側邊欄偏好設定 |-| `document_parsing.json` | 解析引擎選擇、遠端端點與各引擎專屬選項 |+| `document_parsing.json` | 解析引擎與影像描述模型選擇、遠端端點及各引擎專屬選項 || `video_learning.json` | 預設 YouTube/Invidious 播放供應商、Invidious 來源與選用的逐字稿介面卡 || `main.yaml` | 執行階段行為預設值與路徑注入 || `agents.yaml` | 能力/工具的 temperature 與 token 設定 |@@ -350,6 +363,8 @@ Web Search 參考來源預設會經過篩選:只會顯示未內嵌憑證、未專案根目錄的 `.env` **不會**被讀取為應用程式設定檔。若只需最基本的模型設定,請在 **Settings → Providers** 儲存 Base URL 與 API key,再到 **Language models** 新增並選用 LLM。只有在打算使用 Knowledge Base/RAG 功能時才需要加入 embedding 設定檔。+使用 API Route 時,請在 **Settings → Providers** 選擇 **API Route** 並輸入 API Route 金鑰。預設端點為 `https://global.api-route.com/v1`;接著在 **Language models** 使用 API Route 模型 ID 新增模型。金鑰與模型設定方式請參閱 [API Route 快速入門](https://www.api-route.com/docs/quickstart)。+當供應商支援選擇時,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 輸出與推理控制等能力。</details>@@ -422,9 +437,9 @@ Chat 是預設能力,也是大多數工作的起點。單一對話可以進行使用者可切換的工具包括 `brainstorm`、`web_search`、`paper_search`、`zotero_search`、`reason` 與 `geogebra_analysis`;設定對應的生成模型後,還會有 `imagegen` 與 `videogen`。`rag`、`kb_files`、`knowledge_frontier`、`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 狀態)會延續到後續回合;**單次參照**(檔案、聊天記錄、書籍、閱讀章節、筆記本、題庫、匯入的代理程式)則從 `+` 選單加入,只用於單一回合。語音按鈕只會轉錄目前的訊息。+情境分成兩類:**固定的工作階段情境**(能力、工作區或課程、工具、知識庫、角色設定、模型,以及 Reading/Mastery 狀態)會延續到後續回合;**單次參照**(檔案、聊天記錄、書籍、閱讀章節、筆記本、選定的題庫題目、匯入的代理程式)則從 `+` 選單加入,只用於單一回合。語音按鈕只會轉錄目前的訊息。-Home 讓 **Chat**、**Ask Questions**、**Quiz** 與 **Visualize** 一鍵可達;用於建立附引用報告的 **Research**、提供完整推理解題的 **Solve**,以及 **Immersive Watching**,則位於 *More Capabilities* 之下。**Personalized Learning** 集合 Book、**Mastery Path**、**Immersive Reading**、Watching 與 **Practice**。Reading 提供經驗證的引用、已儲存的筆記、以來源為依據的朗讀/學習指南/詞彙/測驗/翻譯動作,以及擷取至筆記本的功能;Course Study 則保有自己的課程情境。+Home 讓 **Chat**、**Ask Questions**、**Quiz** 與 **Visualize** 一鍵可達;用於建立附引用報告的 **Research**、提供完整推理解題的 **Solve**,以及 **Immersive Watching**,則位於 *More Capabilities* 之下。**Personalized Learning** 集合 Book、**Mastery Path**、**Immersive Reading**、Watching 與 **Practice**。Reading 提供經驗證的引用、已儲存的筆記、根據來源段落進行的自然朗讀/學習指南/詞彙/測驗/翻譯動作,以及擷取至筆記本的功能;Course Study 則保有自己的課程情境。</details>@@ -489,7 +504,7 @@ Co-Writer 是用於報告、教學文章、筆記與長篇學習作品的分割<img src="../../assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Co-Writer 編輯器與即時預覽" width="900"></div>-它的核心概念是**精準編輯**:選取一段內容,請 DeepTutor 改寫、擴寫或縮短。編輯代理程式可以知識庫或 Web 證據作為修改依據,並保留工具呼叫軌跡。若代理程式工作期間草稿未發生變更,結果會直接取代所選文字,且仍可使用 **Undo** 復原。+它的核心概念是**精準編輯**:選取一段內容,請 DeepTutor 改寫、擴寫或縮短。你可以選擇編輯模型;它可以知識庫或 Web 證據作為修改依據,並保留工具呼叫軌跡。若模型工作期間草稿未發生變更,結果會直接取代所選文字,且仍可使用 **Undo** 復原。</details>@@ -529,12 +544,18 @@ Book 會將選定來源轉換成互動式**活書**;它不是靜態 PDF,而要遷移現有的 Obsidian、Hermes 或 Markdown 知識庫嗎?請參閱 [Knowledge 遷移指南](../../docs-for-user/KNOWLEDGE_MIGRATION.md),了解連結 vault 與索引副本兩種方式。-建立知識庫時,可以選擇**建立新的知識庫**(上傳文件並建立索引)、**連結現有知識庫**(就地重複使用索引),或**連接 Kiwix**(按需搜尋一個由服務提供的 ZIM 封存檔)。建立時可選擇其儲存工作區;既有知識庫可在預覽後移至其他工作區,並保留指派與已儲存的參照。知識庫也可以追蹤 **GitHub repositories**(repo、branch、glob)或**文件網站 URL**(限制爬取深度與頁面數量,預設每 24 小時重新同步一次);同步時會以內容雜湊差異識別新增、變更與移除的內容,因此你所追蹤的文件能保持最新,無須重新上傳,**已連結的資料夾**也會在同步時取得新增或變更的本機檔案。重新建立索引時,系統會寫入新的扁平 `version-N` 目錄並保留先前版本,因此可用索引不會在重建途中遭到破壞。即使知識庫處於 **error** 狀態,也能移除單一文件;可直接刪除解析失敗的檔案,無須刪除並重建全部內容。文件解析方式(Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse)可在 **Settings → Knowledge & documents** 選擇,預設不下載本機模型。Docling 也可以在**遠端(remote)**模式下運作,改連線至 Docling Serve 伺服器(無須本機安裝或下載模型),可在同一頁面(設定 `mode=remote`、伺服器基礎 URL 與選用的 API 金鑰)或 `DOCLING_MODE`/`DOCLING_API_BASE_URL`/`DOCLING_API_TOKEN` 環境變數進行設定。Tika 僅支援遠端模式,會連線至該頁面設定的 Apache Tika 伺服器。CLI 也提供對應的完整生命週期指令:`list/info/create/connect-kiwix/add/search/set-default/delete`、來源新增/移除指令、`list-sources` 與 `sync`。+建立知識庫時,可以選擇**建立新的知識庫**(上傳文件並建立索引)、**連結現有知識庫**(就地重複使用索引),或**連接 Kiwix**(按需搜尋一個由服務提供的 ZIM 封存檔)。建立時可選擇其儲存工作區;既有知識庫可在預覽後移至其他工作區,並保留指派與已儲存的參照。知識庫也可以追蹤 **GitHub repositories**(repo、branch、glob)或**文件網站 URL**(限制爬取深度與頁面數量,預設每 24 小時重新同步一次);同步時會以內容雜湊差異識別新增、變更與移除的內容,因此你所追蹤的文件能保持最新,無須重新上傳,**已連結的資料夾**也會在同步時取得新增或變更的本機檔案。重新建立索引時,系統會寫入新的扁平 `version-N` 目錄並保留先前版本,因此可用索引不會在重建途中遭到破壞。即使知識庫處於 **error** 狀態,也能移除單一文件;可直接刪除解析失敗的檔案,無須刪除並重建全部內容。文件解析方式(Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse)與選用的影像描述模型可在 **Settings → Knowledge & documents** 選擇,預設不下載本機模型。Docling 也可以在**遠端(remote)**模式下運作,改連線至 Docling Serve 伺服器(無須本機安裝或下載模型),可在同一頁面(設定 `mode=remote`、伺服器基礎 URL 與選用的 API 金鑰)或 `DOCLING_MODE`/`DOCLING_API_BASE_URL`/`DOCLING_API_TOKEN` 環境變數進行設定。Tika 僅支援遠端模式,會連線至該頁面設定的 Apache Tika 伺服器。CLI 也提供對應的完整生命週期指令:`list/info/create/connect-kiwix/add/search/eval/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。原生 LightRAG 的查詢與增量索引,需要已發布索引所記錄的 embedding 設定,包括模型、維度與端點身分。若該設定有變更,請還原原始設定,或以目前的 embedding 重建索引;未記錄 embedding 身分的索引則必須重建。知識庫詳細資料與索引版本檢視會顯示恢復指引,檔案仍可正常檢視與下載。+**評估知識庫。** 有多種引擎可選擇時,「哪個引擎在這裡檢索得最好?」需要實際測量,而 `deeptutor kb eval` 就能回答這個問題。建立 QA 資料集(每行一個 JSON 物件,包含 `query` 與理想檢索應回傳的 `gold` 段落),再使用 `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]` 評估知識庫。每個案例都透過與聊天回合相同的路徑檢索,依完全相同的文字或詞彙重疊程度,將排序後的引用與標準段落配對(可用 `--min-ratio` 調整門檻;不評估語意等價性),並回報 **Recall@k/Precision@k/nDCG@k/MRR/MAP/Hit@k**。指標是依排序計算的純函式,無須模型評判輸出,因此分數可重現並可比較差異;儲存基準後,就能在切換 embedding、調整 reranker 或實驗不同區塊大小時,將資料集用作回歸檢查閘道。搜尋失敗的案例(例如缺少索引或憑證錯誤)不會計分,而是另外回報,避免拉低平均值。PageIndex 透過推理進行檢索,不回傳已排序的區塊,因此不納入評估。++```jsonl+{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}+```+</details><details>@@ -544,7 +565,7 @@ Book 會將選定來源轉換成互動式**活書**;它不是靜態 PDF,而<img src="../../assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor Learning Space 中心" width="900"></div>-Learning Space 是資源庫、組織與個人化層。**Conversations & Materials** 包含 Chat History、支援搬移紀錄與匯出 Markdown 的筆記本,以及含答案與解說的題庫。Personalized Learning 中的 **Practice** 可將已儲存的題目轉為複習工作階段、錯題追蹤與定期複習。**Personalization** 包含角色設定、技能(`SKILL.md` 操作手冊)、一鍵安裝的 **MCP Services**,以及來自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 型錄的 **CLI Apps**,每個應用程式的使用指南會按需載入。獨立的 **My Courses** 工作區會依科目歸納對話與導師討論串;每項資產只會出現在支援它的工作流程中。+Learning Space 是資源庫、組織與個人化層。**Conversations & Materials** 包含 Chat History、支援搬移紀錄與匯出 Markdown 的筆記本,以及含答案與解說的題庫。從選定的題庫題目或 Personalized Learning 啟動 **Practice**,即可進行複習工作階段、錯題追蹤與定期複習。**Personalization** 包含角色設定、技能(`SKILL.md` 操作手冊)、一鍵安裝的 **MCP Services**,以及來自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 型錄的 **CLI Apps**,每個應用程式的使用指南會按需載入。獨立的 **My Courses** 工作區會依科目歸納對話與導師討論串;每項資產只會出現在支援它的工作流程中。<div align="center"><img src="../../assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="從 EduHub 匯入技能" width="900">@@ -580,6 +601,11 @@ Memory Graph 會呈現完整金字塔:L3 綜整位於中央、L2 位於中圈Settings 是操作控制中心,開啟時會顯示用於設定介面與模型輸出語言的 **General** 頁面。可搜尋的導覽選單連結至各個獨立頁面:**Personal** 包含 Workspaces、Data migration、Appearance 與 Usage statistics;**Learning & conversation** 包含起始提示、附件、Video Learning、學習者與監護人控制、Learning progress,以及 Memory;**Models & services** 包含 Providers、Language models、Task models、Embedding、Search、Voice 與 Multimodal generation;**Features & integrations** 包含工具、能力參數、Partners & agents,以及 Knowledge & documents。**System** 包含 Network、Runtime status 與 About;**Archived chats** 可搜尋、還原或永久刪除已封存的對話。Runtime status 包含後端健康狀況、常駐記憶體,以及評估各項能力阻礙、警告與建議的 **Readiness** 矩陣。Workspaces 讓不同主題的檔案與學習狀態保持獨立,Data migration 則提供經驗證的遷移與匯出功能。**供應商(provider)**保存廠商位址與憑證,供其服務模型重複使用;模型頁面可選擇已儲存的供應商,並設定模型名稱與能力。**任務模型**可為命名對話、撰寫起始提示等背景工作指定小型快速模型;留空時則使用目前的預設模型。Voice 集合語音合成與轉錄;Multimodal generation 集合影像與影片模型。Partners & agents 可設定本機代理程式執行框架與遠端 Hermes gateway。+**Xiaomi MiMo 語音。** 新增 Xiaomi MiMo 供應商,輸入 `https://api.xiaomimimo.com/v1` 與其 API 金鑰,再到 Settings → Voice 新增 `mimo-v2.5-tts`。選擇 `mimo_default`、`冰糖` 或 `苏打` 等預設音色,使用 `wav` 或 `pcm16` 輸出,並在套用前試聽。語音指示可控制風格與語速。此介接器只支援預設音色的語音合成;音色設計與聲音複製需要獨立模型,目前不受支援。若舊的 MiMo 語音模型是透過通用的 OpenAI 相容介接器設定,請使用 Xiaomi MiMo 供應商重新建立語音項目,以採用 chat-completions 協定。請參閱 [MiMo 官方語音指南](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5)。++**MiniMax 語音** — 在 Settings → Voice 中,為文字轉語音選擇 MiniMax,並選用 `speech-2.8-hd`。設定 MiniMax API 金鑰與系統或自訂音色 ID;預設音色為 `English_expressive_narrator`。API base 預設為 `https://api.minimax.io/v1`;中國地區請使用 `https://api.minimaxi.com/v1`。朗讀與音色預覽使用原生語音端點,支援 MP3、WAV、FLAC 或 PCM 輸出,以及取樣率、語速與語言控制。音色 ID 與帳號可用性請參閱 [MiniMax 語音 API](https://platform.minimax.io/docs/api-reference/speech-t2a-http)。++**Video Learning** 位於 Settings → Learning & conversation,預設使用官方隱私強化版 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** 會停用並顯示原因。<div align="center">@@ -696,7 +722,7 @@ repo 根目錄附有 [`SKILL.md`](../../SKILL.md),這份約 200 行的交接| `deeptutor run <capability> <message>` | 執行單一能力回合(`chat`、`ask_questions`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`、`immersive_reading`、`course_study`、`immersive_watching`、`audio_overview`);加上 `--format json` 可輸出 NDJSON || `deeptutor chat` | 具備能力、工具、知識庫、筆記本與記錄控制的互動式 REPL || `deeptutor partner list/create/start/stop` | 管理連接 IM 的 partners |-| `deeptutor kb list/info/create/connect-kiwix/add/search/set-default/delete/list-sources/sync` | 管理知識庫,並同步已註冊的 GitHub/Web 來源(含來源新增/移除指令) |+| `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | 管理知識庫、連接 Kiwix 封存檔、依 QA 資料集評估檢索品質,並同步已註冊的 GitHub/Web 來源(含來源新增/移除指令) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | 管理技能、從 hub 安裝並發布自己的技能(預設為 `eduhub:<slug>`,請參閱生態系) || `deeptutor memory show/clear` | 檢視 L2/L3 記憶文件,或清除 L1/所有記憶 || `deeptutor session list/show/open/rename/delete` | 管理共享工作階段 |@@ -795,7 +821,7 @@ deeptutor skill install clawhub:udiedrichsen/stock-analysis</p><p align="center">- 代碼 <b><code>DEEPTUTOR20</code></b> — <b>20 美元折扣</b>,適用於首次 <a href="https://developer.pageindex.ai/">PageIndex 訂閱</a>(新客戶 · Standard/Pro/Max)+ 使用代碼:<b><code>DEEPTUTOR20</code></b> — 首次 <a href="https://developer.pageindex.ai/">PageIndex 訂閱</a>可享 20 美元折扣!</p>## 🌐 社群@@ -851,7 +877,7 @@ DeepTutor 也站在許多傑出開放原始碼專案的肩膀上;它們同時<picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark" /><source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />- <img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />+ <img alt="Star History 排名" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" /></picture></a></p>diff --git a/assets/releases/past_releases/ver1-5-16.md b/assets/releases/past_releases/ver1-5-16.mdindex df708d58f..d6268cf1d 100644--- a/assets/releases/past_releases/ver1-5-16.md+++ b/assets/releases/past_releases/ver1-5-16.md@@ -2,7 +2,7 @@**Release Date:** 2026.08.22-[v1.5.15](past_releases/ver1-5-15.md) added a capture inbox under the Book reader and, in doing so, stopped its pages from turning. That is fixed here, alongside a new connected knowledge source — a **MarginNote 4** library that its own add-on fills — and a run of failures that were only reachable through a particular gateway: tool-call ids that grew until the provider refused them, embeddings rejected for a parameter we deliberately omit, and a temperature limit that only applied if you had named the right binding. Drop-in — no migrations, nothing to re-index.+[v1.5.15](ver1-5-15.md) added a capture inbox under the Book reader and, in doing so, stopped its pages from turning. That is fixed here, alongside a new connected knowledge source — a **MarginNote 4** library that its own add-on fills — and a run of failures that were only reachable through a particular gateway: tool-call ids that grew until the provider refused them, embeddings rejected for a parameter we deliberately omit, and a temperature limit that only applied if you had named the right binding. Drop-in — no migrations, nothing to re-index.## What's Newdiff --git a/assets/releases/past_releases/ver1-6-1.md b/assets/releases/past_releases/ver1-6-1.mdindex 051861a67..fd372e67f 100644--- a/assets/releases/past_releases/ver1-6-1.md+++ b/assets/releases/past_releases/ver1-6-1.md@@ -2,7 +2,7 @@**Release Date:** 2026.08.30-[v1.6.0](past_releases/ver1-6-0.md) connected the learning workspace. v1.6.1 is about the parts you touch every day: model configuration splits into a credential you enter once and a per-purpose assignment, Settings becomes a navigator instead of a wall of cards, the sidebar files study conversations under their topic and lets you arrange it yourself, and LightRAG runs as a first-party engine rather than through a wrapper. Drop-in — no migrations, no re-index.+[v1.6.0](ver1-6-0.md) connected the learning workspace. v1.6.1 is about the parts you touch every day: model configuration splits into a credential you enter once and a per-purpose assignment, Settings becomes a navigator instead of a wall of cards, the sidebar files study conversations under their topic and lets you arrange it yourself, and LightRAG runs as a first-party engine rather than through a wrapper. Drop-in — no migrations, no re-index.## What's Newdiff --git a/assets/releases/ver1-6-10.md b/assets/releases/past_releases/ver1-6-10.mdsimilarity index 100%rename from assets/releases/ver1-6-10.mdrename to assets/releases/past_releases/ver1-6-10.mddiff --git a/assets/releases/ver1-6-11.md b/assets/releases/past_releases/ver1-6-11.mdsimilarity index 100%rename from assets/releases/ver1-6-11.mdrename to assets/releases/past_releases/ver1-6-11.mddiff --git a/assets/releases/ver1-6-12.md b/assets/releases/past_releases/ver1-6-12.mdsimilarity index 100%rename from assets/releases/ver1-6-12.mdrename to assets/releases/past_releases/ver1-6-12.mddiff --git a/assets/releases/ver1-6-9.md b/assets/releases/past_releases/ver1-6-9.mdsimilarity index 93%rename from assets/releases/ver1-6-9.mdrename to assets/releases/past_releases/ver1-6-9.mdindex 0b504f823..09f5a5045 100644--- a/assets/releases/ver1-6-9.md+++ b/assets/releases/past_releases/ver1-6-9.md@@ -2,13 +2,13 @@**Release Date:** 2026.09.21-Building on [v1.6.8](past_releases/ver1-6-8.md), v1.6.9 brings folder-based learning workspaces, a daily practice loop, redesigned Settings, and clearer streaming conversations. Learning surfaces move under `/learning/` with redirects for old links; conversation deletion now means permanent deletion, with archiving available for conversations you want to keep.+Building on [v1.6.8](ver1-6-8.md), v1.6.9 brings folder-based learning workspaces, a daily practice loop, redesigned Settings, and clearer streaming conversations. Learning surfaces move under `/learning/` with redirects for old links; conversation deletion now means permanent deletion, with archiving available for conversations you want to keep.## What's New### Workspaces for your learning data-Choose a workspace when starting a conversation, book, mastery path, reading or watching session. Custom workspaces keep learning data in `.deeptutor/data/` and generated files in `outputs/`; settings, credentials and Memory remain shared across your account. Manage workspaces and their Skills, MCP services and knowledge bases in **Settings → Workspaces**. Partners can keep private resources or stay linked to a workspace. See [workspaces](../../docs-for-user/workspaces.md).+Choose a workspace when starting a conversation, book, mastery path, reading or watching session. Custom workspaces keep learning data in `.deeptutor/data/` and generated files in `outputs/`; settings, credentials and Memory remain shared across your account. Manage workspaces and their Skills, MCP services and knowledge bases in **Settings → Workspaces**. Partners can keep private resources or stay linked to a workspace. See [workspaces](../../../docs-for-user/workspaces.md).### Data migration with previews and recoverydiff --git a/assets/releases/ver1-6-13.md b/assets/releases/ver1-6-13.mdnew file mode 100644index 000000000..660f7f43c--- /dev/null+++ b/assets/releases/ver1-6-13.md@@ -0,0 +1,50 @@+# DeepTutor v1.6.13 Release Notes++**Release Date:** 2026.10.04++Building on [v1.6.12](past_releases/ver1-6-12.md), v1.6.13 expands reading, listening, and question-bank practice, improves document parsing and speech configuration, and brings Polish plus more model providers. Chat attachments now follow the selected workspace, with existing uploads and URLs preserved during the transition.++## What's New++### Read, listen, and revisit++Immersive Reading gains natural read-aloud audio and quiz star rewards. Immersive Watching gains timestamped marks, notes, and suggested review points. PDF resizing and EPUB chapter navigation preserve reading position more reliably; learners can open explicitly assigned books and reading materials within their granted access.++### Practice from your question bank++Start practice directly from the Question Bank and select multiple saved questions for a chat. Guided Learning shuffles multiple-choice options and avoids exposing correct answers through option letters or retrieval prompts. Co-Writer lets you choose the model for an edit.++### More reliable document retrieval++Choose an independent vision model for document image descriptions; successful descriptions are cached per workspace, with optional bounded batching. MinerU cloud parsing slices oversized PDFs and resumes completed parts, while local failures report actionable causes. Optional tiny-scan normalization, numbered-exercise lookup, and better figure retention improve textbook retrieval. `deeptutor kb eval` measures retrieval quality against a local evaluation dataset.++### Speech settings that explain failures++Speech models have a configurable synthesis timeout used by previews and playback. DashScope Qwen-Audio and Qwen3 TTS use their respective endpoints, voices, formats, and regional requirements. Preview errors distinguish authentication, permissions, parameters, quota, network failures, and timeouts. Reply playback preserves math, cancels stale requests, and prevents overlapping audio.++### Workspaces and connections++New chat uploads live in the selected workspace's `chat/attachments` directory so workspace tools can find them. Earlier uploads move there when their conversation is used or its data is migrated; existing attachment URLs remain readable. SearXNG connection tests explain Docker addressing, disabled JSON output, and empty search results. Web sources can pair bilingual content, and knowledge-base checks reuse probes without blocking the API.++### Partners, languages, and providers++Export Partner group conversations as Markdown and configure Telegram response policies per chat. Feishu delivery and Telegram code blocks are more reliable. Polish joins the interface languages; Requesty, API Route, and FutureInfra join LLM providers, with native MiniMax speech and Xiaomi MiMo v2.5 preset speech support.++### Chat recovery and everyday fixes++History search checks full conversation transcripts and excludes recycled sessions. Long conversation branches, reconnecting submissions, LaTeX selections, and learner routes recover more reliably. Image payloads no longer inflate token estimates, GLM reasoning options match supported settings, and `deeptutor doctor` honors the configured provider and token budget.++Updated setup and feature documentation accompanies the release at [deeptutor.info](https://deeptutor.info/).++## Upgrade Notes++Run `pip install -U deeptutor`; Docker users pull `ghcr.io/hkuds/deeptutor:latest`.++- **Attachments:** no manual move is required. Earlier uploads are relocated into the selected workspace when needed; keep existing application data mounted during the upgrade.+- **Speech:** set **Request timeout (seconds)** in the speech model when synthesis needs more time; the default is 60 seconds, with a supported range of 5–600 seconds. Use **Preview voice** to test synthesis; fetching a model list alone does not validate a voice.+- **DashScope Qwen-Audio TTS:** use a Beijing API key and a voice supported by the selected model. A provider API base URL selects the matching speech endpoint automatically; Qwen3 TTS uses its own voices and WAV output.+- **Document images:** select an image-description model in Document Parsing settings if the main model cannot inspect images. Batching and tiny-scan normalization are optional; older indexed content needs re-parsing and reindexing to gain newly generated descriptions or figure records.+- **Learner books:** administrators must grant the Books surface and explicitly assign a book; learner access stays scoped to those assignments.+- **systemd installs:** stop the service, upgrade DeepTutor in its Python environment, and restart the service.++**Full Changelog**: https://github.com/HKUDS/DeepTutor/compare/v1.6.12...v1.6.13diff --git a/deeptutor/__version__.py b/deeptutor/__version__.pyindex 03dd4dcc7..20df8511a 100644--- a/deeptutor/__version__.py+++ b/deeptutor/__version__.py@@ -6,6 +6,6 @@ before publishing to PyPI; the web sidebar badge and CLI banner read from thisfile directly."""-__version__ = "1.6.12"+__version__ = "1.6.13"__all__ = ("__version__",)diff --git a/deeptutor/api/routers/settings.py b/deeptutor/api/routers/settings.pyindex c15f3850a..13e8f4edf 100644--- a/deeptutor/api/routers/settings.py+++ b/deeptutor/api/routers/settings.py@@ -334,6 +334,7 @@ class ProviderProbePayload(BaseModel):api_format: str = "auto"api_version: str = ""extra_headers: dict[str, str] | str | None = None+ proxy: str = ""service: Literal["llm", "task", "embedding", "search", "tts", "stt", "imagegen", "videogen"] = ("llm")@@ -1961,7 +1962,9 @@ async def test_provider_connection(payload: ProviderProbePayload):status_code=400, detail="Saved credentials were not found. Enter the key again.")if payload.service == "search":- return await probe_search_provider(payload.binding, payload.base_url, key)+ return await probe_search_provider(+ payload.binding, payload.base_url, key, proxy=payload.proxy+ )return await probe_provider(payload.binding, payload.base_url, key, payload.api_format, headers, payload.api_version)@@ -2173,8 +2176,8 @@ async def update_enabled_tools(update: EnabledToolsUpdate):async def preview_voice(payload: VoicePreviewPayload) -> Response:"""Audition the model being edited without saving or activating its catalog."""_require_settings_admin()- from deeptutor.services.voice.base import VoiceProviderError- from deeptutor.services.voice.preview import synthesize_preview+ from deeptutor.services.voice.base import VoiceProviderError, VoiceProviderTimeout+ from deeptutor.services.voice.preview import preview_failure_message, synthesize_previewservice = get_model_catalog_service()current = service.load()@@ -2190,14 +2193,12 @@ async def preview_voice(payload: VoicePreviewPayload) -> Response:)except ValueError as exc:raise HTTPException(status_code=400, detail=str(exc)) from exc+ except VoiceProviderTimeout as exc:+ raise HTTPException(status_code=504, detail=str(exc)) from excexcept VoiceProviderError as exc:- # Other provider adapters may include raw upstream bodies in their errors.- # Never send those bodies (or echoed credentials) back to the browser.raise HTTPException(status_code=502,- detail=(- "Voice preview failed. Check the provider credentials, model, voice, language and format."- ),+ detail=preview_failure_message(exc),) from excreturn Response(audio, media_type=content_type, headers={"Cache-Control": "no-store"})diff --git a/deeptutor/api/routers/voice.py b/deeptutor/api/routers/voice.pyindex b3a16c495..7af27668e 100644--- a/deeptutor/api/routers/voice.py+++ b/deeptutor/api/routers/voice.py@@ -19,6 +19,7 @@ from deeptutor.services.voice import (transcribe_audio,)from deeptutor.services.voice.audio import _parse_pcm_content_type, _pcm16_to_wav+from deeptutor.services.voice.base import VoiceProviderTimeoutlogger = logging.getLogger(__name__)@@ -47,6 +48,8 @@ async def text_to_speech(payload: TTSRequest) -> Response:)except ValueError as exc: # missing/invalid configurationraise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc+ except VoiceProviderTimeout as exc:+ raise HTTPException(status_code=status.HTTP_504_GATEWAY_TIMEOUT, detail=str(exc)) from excexcept VoiceProviderError as exc:logger.warning("TTS provider error: %s", exc)raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc)) from excdiff --git a/deeptutor/services/config/provider_runtime.py b/deeptutor/services/config/provider_runtime.pyindex 6535f163c..4cf6e8b08 100644--- a/deeptutor/services/config/provider_runtime.py+++ b/deeptutor/services/config/provider_runtime.py@@ -31,6 +31,7 @@ from deeptutor.services.voice.config import (STT_MULTIPART,STTConfig,TTSConfig,+ resolve_tts_request_timeout,)from .embedding_endpoint import (@@ -1204,12 +1205,15 @@ def resolve_tts_runtime_config(api_key = _as_str((profile or {}).get("api_key"))if not api_key and spec.is_local:api_key = "sk-no-key-required"- from deeptutor.services.voice.options import voice_model_options+ from deeptutor.services.voice.options import is_qwen_audio_tts, voice_model_optionsoptions = voice_model_options(provider, "tts", resolved_model)- voice = _as_str((model or {}).get("voice")) or (- options["voices"][0]["id"] if options["voices"] else spec.default_voice- )+ default_voice = spec.default_voice+ if options["voices"]:+ default_voice = options["voices"][0]["id"]+ elif provider == "dashscope" and is_qwen_audio_tts(resolved_model):+ default_voice = ""+ voice = _as_str((model or {}).get("voice")) or default_voiceresponse_format = _as_str((model or {}).get("response_format")) or options["formats"][0]raw_speed = (model or {}).get("speed")speed = _coerce_optional_float(raw_speed)@@ -1237,6 +1241,7 @@ def resolve_tts_runtime_config(sample_rate=int((model or {}).get("sample_rate") or 24000),instructions=_as_str((model or {}).get("instructions")),max_input_chars=options.get("max_input_chars", 4096),+ request_timeout=resolve_tts_request_timeout((model or {}).get("request_timeout")),)diff --git a/deeptutor/services/config/settings_profile.py b/deeptutor/services/config/settings_profile.pyindex 4e079ddad..05c5cdb7a 100644--- a/deeptutor/services/config/settings_profile.py+++ b/deeptutor/services/config/settings_profile.py@@ -94,6 +94,7 @@ _CATALOG_MODEL_FIELDS = ("language","sample_rate","speed",+ "request_timeout",)diff --git a/deeptutor/services/partners/manager.py b/deeptutor/services/partners/manager.pyindex efa0ee5f8..e4879003f 100644--- a/deeptutor/services/partners/manager.py+++ b/deeptutor/services/partners/manager.py@@ -777,6 +777,7 @@ class PartnerManager:)pending: deque[_OMsg] = deque()+ msg: _OMsgtry:event_bus = get_event_bus()@@ -784,7 +785,7 @@ class PartnerManager:if pending:msg = pending.popleft()else:- msg: _OMsg = await bus.consume_outbound()+ msg = await bus.consume_outbound()metadata = msg.metadata or {}if metadata.get("_stream_delta") and not metadata.get("_stream_end"):diff --git a/deeptutor/services/search/providers/searxng.py b/deeptutor/services/search/providers/searxng.pyindex c076aa66f..313a21e7c 100644--- a/deeptutor/services/search/providers/searxng.py+++ b/deeptutor/services/search/providers/searxng.py@@ -13,13 +13,20 @@ from ..types import Citation, SearchResult, WebSearchResponsefrom . import register_provider+class SearxngResponseError(ValueError):+ """The endpoint replied, but not with the SearXNG JSON search schema."""++def _validate_base_url(base_url: str) -> str:normalized = base_url.strip().rstrip("/")- parsed = urlparse(normalized if "://" in normalized else f"http://{normalized}")- if parsed.scheme not in {"http", "https"}:- raise ValueError("SearXNG base_url must use http/https")- if not parsed.netloc:- raise ValueError("SearXNG base_url is missing host")+ try:+ parsed = urlparse(normalized if "://" in normalized else f"http://{normalized}")+ valid = parsed.scheme in {"http", "https"} and parsed.hostname+ parsed.port+ except ValueError:+ valid = False+ if not valid:+ raise requests.exceptions.InvalidURL("SearXNG base_url must be a valid HTTP/HTTPS address.")return parsed.geturl().rstrip("/")@@ -50,9 +57,17 @@ class SearxngProvider(BaseSearchProvider):request_kwargs["proxies"] = {"http": self.proxy, "https": self.proxy}resp = requests.get(endpoint, timeout=timeout, **request_kwargs)if resp.status_code != 200:- raise Exception(f"SearXNG API error: {resp.status_code} - {resp.text}")- payload = resp.json()- rows = payload.get("results", [])+ # Keep the status for diagnostics, without echoing upstream bodies or keys.+ raise requests.HTTPError(+ f"SearXNG API returned HTTP {resp.status_code}.", response=resp+ )+ try:+ payload = resp.json()+ except ValueError as exc:+ raise SearxngResponseError("SearXNG search did not return valid JSON.") from exc+ rows = payload.get("results") if isinstance(payload, dict) else None+ if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):+ raise SearxngResponseError("SearXNG JSON response is missing a valid results list.")citations: list[Citation] = []search_results: list[SearchResult] = []for idx, row in enumerate(rows[: max(1, min(int(max_results), 10))], 1):diff --git a/deeptutor/services/session/turns/executor.py b/deeptutor/services/session/turns/executor.pyindex a12d73029..d34799d17 100644--- a/deeptutor/services/session/turns/executor.py+++ b/deeptutor/services/session/turns/executor.py@@ -321,6 +321,12 @@ class TurnExecutor:# but the URL we record here outlives that pruning. Upload errors# are non-fatal — extraction still runs from the in-memory base64.attachment_store = get_attachment_store()+ materialize_session = getattr(attachment_store, "materialize_session", None)+ if callable(materialize_session):+ try:+ await materialize_session(session_id)+ except OSError as exc:+ logger.warning("could not move previous attachments into workspace: %s", exc)for record in attachment_records:if record.get("url"):continue # already hosted (e.g. legacy URL)diff --git a/deeptutor/services/settings/provider_probe.py b/deeptutor/services/settings/provider_probe.pyindex 056bf3560..8e190c2df 100644--- a/deeptutor/services/settings/provider_probe.py+++ b/deeptutor/services/settings/provider_probe.py@@ -6,6 +6,7 @@ import asynciofrom urllib.parse import urlsplitimport aiohttp+import requestsfrom deeptutor.services.llm.cloud_provider import _auth_binding, _get_aiohttp_connectorfrom deeptutor.services.llm.utils import build_auth_headers, collect_model_names@@ -62,7 +63,13 @@ def detect_capabilities(items: list) -> list[dict]:def test_search_access(- binding: str, base_url: str, api_key: str | None, *, proxy: str = "", max_results: int = 1+ binding: str,+ base_url: str,+ api_key: str | None,+ *,+ proxy: str = "",+ max_results: int = 1,+ require_results: bool = True,):"""Test exactly one search adapter, never a fallback or live credentials."""from deeptutor.services.config.provider_runtime import (@@ -83,27 +90,55 @@ def test_search_access(response = get_provider(binding, **kwargs).search("DeepTutor configuration health check", **kwargs)- if not (response.answer or response.search_results):+ if require_results and not (response.answer or response.search_results):raise ValueError("Search provider returned no answer or results.")return response-async def probe_search_provider(binding: str, base_url: str, api_key: str | None) -> dict:+async def probe_search_provider(+ binding: str, base_url: str, api_key: str | None, *, proxy: str = ""+) -> dict:from deeptutor.services.config.provider_runtime import search_missing_credential+ from deeptutor.services.search.providers.searxng import SearxngResponseError- if search_missing_credential(binding, api_key or "", base_url):- return {"status": "auth_error", "models": []}+ missing = search_missing_credential(binding, api_key or "", base_url)+ if missing:+ return {"status": "invalid_url" if missing == "base_url" else "auth_error", "models": []}try:- await asyncio.wait_for(- asyncio.to_thread(test_search_access, binding, base_url, api_key), timeout=25+ response = await asyncio.wait_for(+ asyncio.to_thread(+ test_search_access, binding, base_url, api_key, proxy=proxy, require_results=False+ ),+ timeout=25,)- return {+ result = {"status": "connected","models": [],"capabilities": [{"category": "search", "evidence": "metadata"}],}- except TimeoutError:+ if not (response.answer or response.search_results):+ result["warning"] = "empty_results"+ return result+ except (TimeoutError, requests.Timeout):return {"status": "timeout", "models": []}+ except requests.ConnectionError:+ return {"status": "unreachable", "models": []}+ except (requests.exceptions.InvalidURL, requests.exceptions.InvalidSchema):+ return {"status": "invalid_url", "models": []}+ except SearxngResponseError:+ return {"status": "invalid_response", "models": []}+ except requests.HTTPError as exc:+ status = exc.response.status_code if exc.response is not None else None+ category = (+ "json_forbidden"+ if binding == "searxng" and status == 403+ else "auth_error"+ if status in {401, 403}+ else "rate_limited"+ if status == 429+ else "http_error"+ )+ return {"status": category, "models": [], "http_status": status}except Exception:# No upstream exception text: it may contain the submitted key.return {"status": "http_error", "models": []}diff --git a/deeptutor/services/storage/attachment_store.py b/deeptutor/services/storage/attachment_store.pyindex cdba8d5c3..1add9469b 100644--- a/deeptutor/services/storage/attachment_store.py+++ b/deeptutor/services/storage/attachment_store.py@@ -32,6 +32,7 @@ import asyncioimport loggingimport osfrom pathlib import Path+import shutilfrom typing import Protocol, runtime_checkablefrom urllib.parse import quote@@ -42,7 +43,8 @@ from deeptutor.services.path_service import get_path_servicelogger = logging.getLogger(__name__)-_DEFAULT_SUBPATH = ("workspace", "chat", "attachments")+_LEGACY_SUBPATH = ("workspace", "chat", "attachments")+_VISIBLE_SUBPATH = ("chat", "attachments")# Public route prefix served by deeptutor.api.routers.attachments_PUBLIC_URL_PREFIX = "/files/attachments"@@ -103,15 +105,16 @@ class AttachmentStore(Protocol):class LocalDiskAttachmentStore:"""Default :class:`AttachmentStore` backend writing to local disk.- The root directory defaults to ``data/user/workspace/chat/attachments``- under the project root (matching :class:`PathService`'s public outputs).- Override via ``data/user/settings/system.json`` ``chat_attachment_dir``.+ New uploads live in the selected content workspace's ``chat/attachments``+ directory so workspace tools can discover them. Older uploads remain+ readable from the previous application-data location until materialized."""- def __init__(self, root: Path | None = None) -> None:+ def __init__(self, root: Path | None = None, *, legacy_root: Path | None = None) -> None:if root is None:root = _attachment_root()self._root = root+ self._legacy_root = legacy_root if legacy_root != root else None@propertydef root(self) -> Path:@@ -122,16 +125,19 @@ class LocalDiskAttachmentStore:def _session_dir(self, session_id: str) -> Path:sid = _coerce_filename(session_id)- return (self._root / sid).resolve()+ return self._root / siddef _safe_join(self, session_id: str, name: str) -> Path | None:"""Join *name* under the session dir and confirm the result staysinside ``self._root``. Returns ``None`` if traversal is detected."""session_dir = self._session_dir(session_id)+ raw_candidate = session_dir / name+ if session_dir.is_symlink() or raw_candidate.is_symlink():+ return None# Resolve the candidate even if it doesn't exist yet — prevents a# symlink-based attack that would point outside the root once created.- candidate = (session_dir / name).resolve()+ candidate = raw_candidate.resolve()try:candidate.relative_to(self._root.resolve())except ValueError:@@ -185,23 +191,25 @@ class LocalDiskAttachmentStore:passasync def delete_session(self, session_id: str) -> None:- session_dir = self._session_dir(session_id)- if not session_dir.exists():- returnloop = asyncio.get_running_loop()- await loop.run_in_executor(None, self._rmtree_sync, session_dir)+ roots = (self._root, self._legacy_root) if self._legacy_root else (self._root,)+ for root in roots:+ session_dir = LocalDiskAttachmentStore(root)._session_dir(session_id)+ if session_dir.exists() and not session_dir.is_symlink():+ await loop.run_in_executor(None, self._rmtree_sync, session_dir)async def delete_attachment(self, session_id: str, attachment_id: str) -> None:- session_dir = self._session_dir(session_id)- if not session_dir.exists():- returnloop = asyncio.get_running_loop()- await loop.run_in_executor(None, self._delete_attachment_sync, session_dir, attachment_id)+ roots = (self._root, self._legacy_root) if self._legacy_root else (self._root,)+ for root in roots:+ session_dir = LocalDiskAttachmentStore(root)._session_dir(session_id)+ if session_dir.exists() and not session_dir.is_symlink():+ await loop.run_in_executor(+ None, self._delete_attachment_sync, session_dir, attachment_id+ )@staticmethoddef _rmtree_sync(path: Path) -> None:- import shutil-try:shutil.rmtree(path)except OSError as exc:@@ -225,12 +233,50 @@ class LocalDiskAttachmentStore:def resolve_path(self, *, session_id: str, attachment_id: str, filename: str) -> Path | None:stored = self._stored_filename(attachment_id, filename)target = self._safe_join(session_id, stored)- if target is None or not target.is_file():+ if target is not None and target.is_file():+ return target+ if self._legacy_root is None:return None- return target+ legacy = LocalDiskAttachmentStore(self._legacy_root)+ target = legacy._safe_join(session_id, stored)+ return target if target is not None and target.is_file() else None++ async def materialize_session(self, session_id: str) -> None:+ """Move earlier uploads into the selected workspace before tool discovery."""+ if self._legacy_root is None:+ return+ loop = asyncio.get_running_loop()+ await loop.run_in_executor(None, self._materialize_session_sync, session_id)++ def _materialize_session_sync(self, session_id: str) -> None:+ legacy = LocalDiskAttachmentStore(self._legacy_root)+ source_dir = legacy._session_dir(session_id)+ if not source_dir.is_dir() or source_dir.is_symlink():+ return+ destination_dir = self._session_dir(session_id)+ for source in source_dir.iterdir():+ if source.is_symlink() or not source.is_file():+ continue+ destination = self._safe_join(session_id, source.name)+ if destination is None or destination.exists():+ continue+ destination_dir.mkdir(parents=True, exist_ok=True)+ shutil.move(str(source), str(destination))+ try:+ source_dir.rmdir()+ except OSError:+ pass++ def materialize_all_sessions(self) -> None:+ """Bring legacy uploads into this workspace before data migration."""+ if self._legacy_root is None or not self._legacy_root.is_dir():+ return+ for entry in self._legacy_root.iterdir():+ if entry.is_dir() and not entry.is_symlink():+ self._materialize_session_sync(entry.name)-_stores: dict[str, AttachmentStore] = {}+_stores: dict[tuple[str, str], AttachmentStore] = {}def get_attachment_store() -> AttachmentStore:@@ -240,19 +286,38 @@ def get_attachment_store() -> AttachmentStore:backends can be selected here based on an env var."""root = _attachment_root()- key = str(root)+ legacy_root = _legacy_attachment_root()+ key = (str(root), str(legacy_root))if key not in _stores:- _stores[key] = LocalDiskAttachmentStore(root=root)+ _stores[key] = LocalDiskAttachmentStore(root=root, legacy_root=legacy_root)return _stores[key]def _attachment_root() -> Path:- from deeptutor.services.workspace.context import current_workspace_id+ from deeptutor.services.workspace.context import current_workspace_id, get_workspace_scopeoverride = str(load_system_settings().get("chat_attachment_dir") or "").strip()if override and not current_workspace_id():return Path(override).expanduser().resolve()- return get_path_service().get_user_root().joinpath(*_DEFAULT_SUBPATH).resolve()+ scope = get_workspace_scope()+ if scope is not None and scope.workspace_id:+ content_root = scope.content_root+ else:+ from deeptutor.services.workspace import get_content_workspace_service++ content_root = get_content_workspace_service().general_binding().root+ from deeptutor.services.workspace.models import WorkspaceError++ directory = content_root+ for component in _VISIBLE_SUBPATH:+ directory = directory / component+ if directory.is_symlink():+ raise WorkspaceError("Chat attachment directories cannot be symbolic links.")+ return directory.resolve()+++def _legacy_attachment_root() -> Path:+ return get_path_service().get_user_root().joinpath(*_LEGACY_SUBPATH).resolve()def reset_attachment_store() -> None:diff --git a/deeptutor/services/voice/__init__.py b/deeptutor/services/voice/__init__.pyindex d071e5dc1..100979a11 100644--- a/deeptutor/services/voice/__init__.py+++ b/deeptutor/services/voice/__init__.py@@ -15,6 +15,7 @@ from deeptutor.services.voice.base import (TranscriptCue,VoiceProviderError,strip_markdown_for_speech,+ synthesize_with_timeout,)from deeptutor.services.voice.config import STTConfig, TTSConfig@@ -60,7 +61,7 @@ async def synthesize_speech(if not prepared:raise VoiceProviderError("Nothing to speak after cleaning the text.")adapter = get_tts_adapter(config.adapter)- return await adapter.synthesize(prepared, config)+ return await synthesize_with_timeout(adapter, prepared, config)async def transcribe_audio(diff --git a/deeptutor/services/voice/adapters/dashscope.py b/deeptutor/services/voice/adapters/dashscope.pyindex 1b849bbee..648796ae2 100644--- a/deeptutor/services/voice/adapters/dashscope.py+++ b/deeptutor/services/voice/adapters/dashscope.py@@ -19,12 +19,15 @@ from deeptutor.services.voice.base import (BaseTTSAdapter,VoiceProviderError,VoiceProviderHTTPError,+ VoiceProviderTimeout,build_auth_headers,join_audio_path,)from deeptutor.services.voice.config import STTConfig, TTSConfig+from deeptutor.services.voice.options import is_qwen_audio_tts_TTS_PATH = "services/aigc/multimodal-generation/generation"+_QWEN_AUDIO_TTS_PATH = "services/audio/tts/SpeechSynthesizer"_AUDIO_CONTENT_TYPES = {"mp3": "audio/mpeg","wav": "audio/wav",@@ -33,7 +36,9 @@ _AUDIO_CONTENT_TYPES = {}-def _provider_error(resp: httpx.Response, action: str) -> None:+def _provider_error(+ resp: httpx.Response, action: str, *, public_message: str | None = None+) -> None:if resp.status_code < 400:returndetail = (resp.text or "").strip()[:400]@@ -41,6 +46,7 @@ def _provider_error(resp: httpx.Response, action: str) -> None:f"{action} failed with HTTP {resp.status_code}" + (f": {detail}" if detail else "."),status_code=resp.status_code,body=resp.text,+ public_message=public_message,)@@ -48,7 +54,92 @@ def _dashscope_error(data: dict[str, Any], action: str) -> None:if data.get("code") not in (None, "", 0, "0") or data.get("success") is False:code = data.get("code") or "unknown"message = data.get("message") or "no detail provided"- raise VoiceProviderError(f"{action} failed ({code}): {message}")+ raise VoiceProviderError(+ f"{action} failed ({code}): {message}",+ public_message=(+ "Speech parameters were rejected. Check the model, voice, language and audio format."+ if code == "InvalidParameter"+ else None+ ),+ )+++def _tts_url(config: TTSConfig) -> str:+ """Select the model's native route while preserving explicit endpoints."""+ parsed = urlsplit(config.base_url.strip())+ if parsed.scheme not in {"http", "https"} or not parsed.hostname:+ raise ValueError("Speech synthesis requires an HTTP or HTTPS provider URL.")+ if config.model.startswith("qwen") and "realtime" in config.model:+ raise ValueError(+ "Realtime speech models are not supported here. Select a non-realtime TTS model."+ )+ native_audio = is_qwen_audio_tts(config.model)+ host = parsed.hostname.lower()+ official_host = host in {+ "dashscope.aliyuncs.com",+ "dashscope-intl.aliyuncs.com",+ "dashscope-us.aliyuncs.com",+ } or host.endswith(".maas.aliyuncs.com")+ if native_audio and (+ host in {"dashscope-intl.aliyuncs.com", "dashscope-us.aliyuncs.com"}+ or (+ host.endswith(".maas.aliyuncs.com")+ and not host.endswith(".cn-beijing.maas.aliyuncs.com")+ )+ ):+ raise ValueError(+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL."+ )+ # Shared chat connections may carry DashScope's OpenAI-compatible base.+ # Translate only official hosts; gateway overrides retain their own paths.+ if official_host and parsed.path.rstrip("/") == "/compatible-mode/v1":+ parsed = parsed._replace(path="/api/v1")+ suffix = _QWEN_AUDIO_TTS_PATH if native_audio else _TTS_PATH+ other = _TTS_PATH if native_audio else _QWEN_AUDIO_TTS_PATH+ if parsed.path.rstrip("/").endswith("/" + other):+ if official_host:+ raise ValueError(+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically."+ )+ return parsed.geturl()+ return join_audio_path(parsed.geturl(), suffix)+++def _tts_input(text: str, config: TTSConfig) -> dict[str, Any]:+ native_audio = is_qwen_audio_tts(config.model)+ inputs: dict[str, Any] = {"text": text}+ if config.voice:+ inputs["voice"] = config.voice+ elif native_audio:+ raise ValueError("Enter a voice ID supported by the selected Qwen-Audio TTS model.")+ if config.language:+ if native_audio:+ language = {"Chinese": "zh", "English": "en", "Auto": ""}.get(+ config.language, config.language+ )+ if language:+ inputs["language_hints"] = [language]+ else:+ inputs["language_type"] = config.language+ if config.instructions:+ inputs["instruction" if native_audio else "instructions"] = config.instructions+ if native_audio:+ audio_format = (config.response_format or "mp3").lower()+ if audio_format not in _AUDIO_CONTENT_TYPES:+ raise ValueError("Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.")+ rates = {8000, 12000, 16000, 24000, 48000}+ if audio_format != "opus":+ rates |= {22050, 44100}+ if config.sample_rate not in rates:+ raise ValueError(+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format."+ )+ if config.speed is not None and not 0.5 <= config.speed <= 2:+ raise ValueError("Qwen-Audio TTS speed must be between 0.5 and 2.")+ inputs.update(format=audio_format, sample_rate=config.sample_rate)+ if config.speed is not None:+ inputs["rate"] = config.speed+ return inputsclass DashScopeTTSAdapter(BaseTTSAdapter):@@ -57,7 +148,7 @@ class DashScopeTTSAdapter(BaseTTSAdapter):async def synthesize(self, text: str, config: TTSConfig) -> tuple[bytes, str]:if not config.base_url:raise VoiceProviderError("No endpoint URL configured for TTS.")- url = join_audio_path(config.base_url, _TTS_PATH)+ url = _tts_url(config)headers = {"Content-Type": "application/json",**build_auth_headers(config.auth_style, config.api_key),@@ -65,14 +156,8 @@ class DashScopeTTSAdapter(BaseTTSAdapter):}payload: dict[str, Any] = {"model": config.model,- "input": {"text": text},+ "input": _tts_input(text, config),}- if config.voice:- payload["input"]["voice"] = config.voice- if config.language:- payload["input"]["language_type"] = config.language- if config.instructions:- payload["input"]["instructions"] = config.instructionstry:async with httpx.AsyncClient(timeout=config.request_timeout) as client:@@ -81,13 +166,34 @@ class DashScopeTTSAdapter(BaseTTSAdapter):data = self._json_object(resp)_dashscope_error(data, "DashScope TTS")audio_url = self._audio_url(data)- audio_resp = await client.get(audio_url)- _provider_error(audio_resp, "DashScope audio download")- except (httpx.HTTPError, ValueError) as exc:- raise VoiceProviderError(f"DashScope TTS request error: {exc}") from exc+ download_hint = "Speech was generated, but the audio download failed. Try again or check the network connection."+ try:+ audio_resp = await client.get(audio_url)+ except httpx.HTTPError as exc:+ raise VoiceProviderError(+ f"DashScope audio download error: {exc}", public_message=download_hint+ ) from exc+ _provider_error(+ audio_resp, "DashScope audio download", public_message=download_hint+ )+ except httpx.TimeoutException as exc:+ raise VoiceProviderTimeout() from exc+ except httpx.HTTPError as exc:+ raise VoiceProviderError(+ f"DashScope TTS request error: {exc}",+ public_message="Could not connect to the speech provider. Check the provider URL and network connection.",+ ) from exc+ except ValueError as exc:+ raise VoiceProviderError(+ f"DashScope TTS response error: {exc}",+ public_message="The speech provider returned an invalid response. Check the provider URL.",+ ) from excif not audio_resp.content:- raise VoiceProviderError("DashScope TTS returned empty audio.")+ raise VoiceProviderError(+ "DashScope TTS returned empty audio.",+ public_message="The speech provider returned empty audio. Try another text or voice.",+ )content_type = audio_resp.headers.get("content-type") or self._url_content_type(audio_url, config.response_format)@@ -95,13 +201,18 @@ class DashScopeTTSAdapter(BaseTTSAdapter):content_type = _AUDIO_CONTENT_TYPES.get((config.response_format or "wav").lower(), "audio/wav")+ if is_qwen_audio_tts(config.model) and config.response_format.lower() == "pcm":+ content_type = f"audio/pcm;rate={config.sample_rate};channels=1"return audio_resp.content, content_type@staticmethoddef _json_object(resp: httpx.Response) -> dict[str, Any]:data = resp.json()if not isinstance(data, dict):- raise VoiceProviderError("DashScope TTS returned a malformed response.")+ raise VoiceProviderError(+ "DashScope TTS returned a malformed response.",+ public_message="The speech provider returned an invalid response. Check the provider URL.",+ )return data@staticmethod@@ -113,7 +224,10 @@ class DashScopeTTSAdapter(BaseTTSAdapter):url = audio.get("url")if isinstance(url, str) and url:return url- raise VoiceProviderError("DashScope TTS response had no audio URL.")+ raise VoiceProviderError(+ "DashScope TTS response had no audio URL.",+ public_message="The speech provider returned an invalid response. Check the provider URL.",+ )@staticmethoddef _url_content_type(url: str, response_format: str) -> str:diff --git a/deeptutor/services/voice/base.py b/deeptutor/services/voice/base.pyindex bd5bdf461..a21e7fd96 100644--- a/deeptutor/services/voice/base.py+++ b/deeptutor/services/voice/base.py@@ -3,10 +3,13 @@from __future__ import annotationsfrom abc import ABC, abstractmethod+import asynciofrom dataclasses import dataclassimport loggingimport re+import httpx+from deeptutor.services.voice.config import (AUTH_API_KEY_HEADER,AUTH_TOKEN,@@ -21,12 +24,34 @@ logger = logging.getLogger(__name__)class VoiceProviderError(RuntimeError):"""Raised when a TTS/STT provider request fails or is misconfigured."""+ def __init__(self, message: str, *, public_message: str | None = None) -> None:+ super().__init__(message)+ # Only application-authored text belongs here, never an upstream body.+ self.public_message = public_message+++class VoiceProviderTimeout(VoiceProviderError):+ """A synthesis deadline or transport timeout, with safe actionable copy."""++ def __init__(self) -> None:+ super().__init__(+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech "+ "model settings or try shorter text."+ )+class VoiceProviderHTTPError(VoiceProviderError):"""Provider returned a non-2xx HTTP response."""- def __init__(self, message: str, *, status_code: int, body: str = "") -> None:- super().__init__(message)+ def __init__(+ self,+ message: str,+ *,+ status_code: int,+ body: str = "",+ public_message: str | None = None,+ ) -> None:+ super().__init__(message, public_message=public_message)self.status_code = status_codeself.body = body@@ -44,6 +69,23 @@ class BaseTTSAdapter(ABC):"""+async def synthesize_with_timeout(+ adapter: BaseTTSAdapter, text: str, config: TTSConfig+) -> tuple[bytes, str]:+ """One deadline covers synthesis, streams and audio downloads in every entry point."""+ try:+ async with asyncio.timeout(config.request_timeout):+ return await adapter.synthesize(text, config)+ except (TimeoutError, httpx.TimeoutException) as exc:+ raise VoiceProviderTimeout() from exc+ except VoiceProviderError as exc:+ # Existing adapters wrap transport errors. Preserve a timeout's identity+ # so the API can explain how to change the limit without echoing upstream data.+ if isinstance(exc.__cause__, (TimeoutError, httpx.TimeoutException)):+ raise VoiceProviderTimeout() from exc+ raise++@dataclass(frozen=True, slots=True)class TranscriptCue:"""One timed span of recognised speech, relative to the clip's own start.@@ -220,6 +262,8 @@ __all__ = ["TranscriptCue","VoiceProviderError","VoiceProviderHTTPError",+ "VoiceProviderTimeout",+ "synthesize_with_timeout","BaseTTSAdapter","BaseSTTAdapter","build_auth_headers",diff --git a/deeptutor/services/voice/config.py b/deeptutor/services/voice/config.pyindex 1b33fdd10..c80322fab 100644--- a/deeptutor/services/voice/config.py+++ b/deeptutor/services/voice/config.py@@ -22,6 +22,25 @@ STT_BASE64_JSON = "base64_json" # OpenRouter: {model, input_audio:{data,format}# OpenAI caps speech input at 4096 chars; keep a safe generic ceiling.DEFAULT_MAX_INPUT_CHARS = 4096+DEFAULT_TTS_REQUEST_TIMEOUT = 60+TTS_REQUEST_TIMEOUT_MIN = 5+TTS_REQUEST_TIMEOUT_MAX = 600+++def resolve_tts_request_timeout(value: object) -> int:+ """An unset catalog field keeps the historical default; invalid edits fail loudly."""+ if value is None or value == "":+ return DEFAULT_TTS_REQUEST_TIMEOUT+ try:+ timeout = int(str(value).strip())+ except (TypeError, ValueError):+ timeout = 0+ if not TTS_REQUEST_TIMEOUT_MIN <= timeout <= TTS_REQUEST_TIMEOUT_MAX:+ raise ValueError(+ f"Speech request timeout must be a whole number between "+ f"{TTS_REQUEST_TIMEOUT_MIN} and {TTS_REQUEST_TIMEOUT_MAX} seconds."+ )+ return timeout@dataclass(slots=True)@@ -45,7 +64,7 @@ class TTSConfig:sample_rate: int = 24000instructions: str = ""max_input_chars: int = DEFAULT_MAX_INPUT_CHARS- request_timeout: int = 60+ request_timeout: int = DEFAULT_TTS_REQUEST_TIMEOUT@dataclass(slots=True)diff --git a/deeptutor/services/voice/options.py b/deeptutor/services/voice/options.pyindex 8ff5a9ed6..0b6e0a612 100644--- a/deeptutor/services/voice/options.py+++ b/deeptutor/services/voice/options.py@@ -15,6 +15,11 @@ def choices(values: list[str]) -> list[dict]:return [{"id": value, "label": value} for value in values]+def is_qwen_audio_tts(model: str) -> bool:+ """Qwen-Audio TTS uses SpeechSynthesizer, unlike Qwen3's multimodal API."""+ return model.startswith("qwen-audio-") and "-tts-" in model++OPENAI_VOICES = choices("alloy ash ballad coral echo fable nova onyx sage shimmer verse marin cedar".split())@@ -165,7 +170,7 @@ def _tts_models(provider: str) -> tuple[list[dict], str]:{"id": "Momo", "label": "茉兔 · Momo"},{"id": "Kai", "label": "凯 · Kai"},]- return [+ qwen_models = [preset(m,voices=[v for v in qwen_voices if v["id"] in {"Cherry", "Ethan"}]@@ -176,8 +181,49 @@ def _tts_models(provider: str) -> tuple[list[dict], str]:),formats=["wav"],instructions="instruct" in m,+ configuration_note="Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.",)for m in ["qwen3-tts-flash", "qwen3-tts-instruct-flash", "qwen3-tts-flash-2025-09-18"]+ ]+ audio_voices = {+ "qwen-audio-3.0-tts-plus": [+ {+ "id": "longanlingxin",+ "label": "龙安灵心 · longanlingxin",+ "languages": ["zh", "en"],+ },+ {+ "id": "longanlufeng",+ "label": "龙安鲁风 · longanlufeng",+ "languages": ["zh", "en"],+ },+ ],+ "qwen-audio-3.0-tts-flash": [+ {+ "id": "longanfengyue",+ "label": "龙安风悦 · longanfengyue",+ "languages": ["zh", "en"],+ },+ {+ "id": "longanhuan_v3.6",+ "label": "龙安欢 · longanhuan_v3.6",+ "languages": ["zh", "en"],+ },+ ],+ }+ return qwen_models + [+ preset(+ m,+ voices=voices,+ languages=choices(["zh", "en"]),+ formats=["mp3", "wav", "opus", "pcm"],+ sample_rates=[8000, 12000, 16000, 24000, 48000],+ speed={"min": 0.5, "max": 2, "step": 0.05},+ instructions=True,+ configuration_note="Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.",+ docs_url="https://help.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list",+ )+ for m, voices in audio_voices.items()], "https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list"if provider == "groq":return [@@ -226,6 +272,7 @@ def voice_options(provider: str, service: str) -> dict:fallback = {**deepcopy(models[0]), "id": "", "voices": [], "instructions": False}elif provider == "dashscope":fallback = {**deepcopy(models[0]), "id": "", "voices": [], "instructions": False}+ fallback.pop("configuration_note", None)elif provider == "groq":fallback = preset("", formats=["wav"])elif provider == "xiaomi_mimo":diff --git a/deeptutor/services/voice/preview.py b/deeptutor/services/voice/preview.pyindex 61c14f6ad..9a89ec5cb 100644--- a/deeptutor/services/voice/preview.py+++ b/deeptutor/services/voice/preview.py@@ -4,7 +4,29 @@ from copy import deepcopyfrom .adapters import get_tts_adapterfrom .audio import _parse_pcm_content_type, _pcm16_to_wav-from .base import VoiceProviderError+from .base import VoiceProviderError, VoiceProviderHTTPError, synthesize_with_timeout+++def preview_failure_message(error: VoiceProviderError) -> str:+ """Give an actionable diagnosis without echoing upstream text or secrets."""+ if error.public_message:+ return error.public_message+ if isinstance(error, VoiceProviderHTTPError):+ if error.status_code == 401:+ return "Speech authentication failed. Check the API key and its region."+ if error.status_code == 403:+ return "Speech access was denied. Check model and voice permissions and the API key region."+ if error.status_code == 404:+ return "Speech endpoint or model was not found. Check the provider URL and model ID."+ if error.status_code in {400, 422}:+ return "Speech parameters were rejected. Check the model, voice, language and audio format."+ if error.status_code == 429:+ return "Speech quota or rate limit was reached. Check your balance and quota, or retry later."+ if error.status_code >= 500:+ return "The speech provider is temporarily unavailable. Try again later."+ return (+ "Voice preview failed. Check the provider credentials, model, voice, language and format."+ )async def synthesize_preview(catalog: dict, profile_id: str, model_id: str, text: str):@@ -24,8 +46,9 @@ async def synthesize_preview(catalog: dict, profile_id: str, model_id: str, textraise ValueError("Saved speech credentials were not found. Enter them again.")if len(text) > config.max_input_chars:raise ValueError(f"This speech model accepts at most {config.max_input_chars} characters.")- config.request_timeout = min(config.request_timeout, 60)- audio, content_type = await get_tts_adapter(config.adapter).synthesize(text, config)+ audio, content_type = await synthesize_with_timeout(+ get_tts_adapter(config.adapter), text, config+ )if not audio:raise VoiceProviderError("The provider returned empty audio.")pcm = _parse_pcm_content_type(content_type)diff --git a/deeptutor/services/workspace/data_migration.py b/deeptutor/services/workspace/data_migration.pyindex baa11adc6..197d403f0 100644--- a/deeptutor/services/workspace/data_migration.py+++ b/deeptutor/services/workspace/data_migration.py@@ -51,7 +51,7 @@ FEATURES = {def _feature_path(paths, feature: str) -> Path:if feature == "attachments":if hasattr(paths, "scope"):- return paths.get_chat_workspace_root() / "attachments"+ return paths.scope.content_root / "chat" / "attachments"from deeptutor.services.storage.attachment_store import _attachment_rootwith workspace_context():@@ -556,6 +556,16 @@ def migrate_data(with data_activity(exclusive=True):assert_no_pending_recovery()+ if "chat" in features or "attachments" in features:+ from deeptutor.services.storage.attachment_store import (+ LocalDiskAttachmentStore,+ get_attachment_store,+ )++ with workspace_context(source_id):+ attachment_store = get_attachment_store()+ if isinstance(attachment_store, LocalDiskAttachmentStore):+ attachment_store.materialize_all_sessions()plan = preview(source_id, target_id, features, session_ids=session_ids)if plan["blockers"]:raise WorkspaceError(" ".join(plan["blockers"]))diff --git a/docs-for-user/VOICE_CONFIGURATION.md b/docs-for-user/VOICE_CONFIGURATION.mdindex 24fef9784..409895fa0 100644--- a/docs-for-user/VOICE_CONFIGURATION.md+++ b/docs-for-user/VOICE_CONFIGURATION.md@@ -16,19 +16,42 @@## 按模型配置-选项按服务商和具体模型提供。OpenAI 的不同 TTS 系列、OpenRouter 的 OpenAI/Gemini 模型、火山 TTS 1.0/2.0、Groq 英语/阿拉伯语模型分别使用对应音色建议。阿里云目前对接 Qwen TTS 的原生 HTTP 接口;CosyVoice 等使用其他协议的模型需要另行适配。+选项按服务商和具体模型提供。OpenAI 的不同 TTS 系列、OpenRouter 的 OpenAI/Gemini 模型、火山 TTS 1.0/2.0、Groq 英语/阿拉伯语模型分别使用对应音色建议。阿里云支持 Qwen3 TTS 和 Qwen-Audio TTS 的原生 HTTP 接口,并按模型自动选择调用端点;CosyVoice 等模型仍需另行适配。建议列表不是完整的模型目录。对于账号专属模型、部署名、私有音色,可以手动填写 ID;需确认它们使用当前服务商适配器支持的接口协议。+## 阿里云百炼++在「设置 → 语音」添加 **Aliyun DashScope** 模型。提供方 URL 可使用北京地域 API 基地址 `https://dashscope.aliyuncs.com/api/v1`,也可使用业务空间地址 `https://你的WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1`。填入同地域的百炼 API Key。++| 模型 ID | 推荐音色 ID | 音频格式 | 语言 |+| --- | --- | --- | --- |+| `qwen3-tts-flash` | `Cherry`(芊悦,注意大小写) | WAV | `Chinese` 或 `Auto` |+| `qwen3-tts-instruct-flash` | `Cherry` | WAV | `Chinese` 或 `Auto` |+| `qwen-audio-3.0-tts-plus` | `longanlingxin`(龙安灵心) | MP3、WAV、Opus、PCM | `zh` 或 `en`;留空由文本和音色决定 |+| `qwen-audio-3.0-tts-flash` | `longanfengyue`(龙安风悦) | MP3、WAV、Opus、PCM | `zh` 或 `en`;留空由文本和音色决定 |++Qwen-Audio TTS 的非实时合成仅在北京地域可用。Qwen3 TTS 也可使用新加坡地域,但须使用对应地域的 URL 和 API Key。两类模型的音色 ID 和语言参数不同,切换模型时请从对应的推荐音色中选择。++提供方连接若使用阿里云官方的 `/compatible-mode/v1` 地址,语音调用会自动转换为原生 API 基地址。若填写完整的合成端点,该端点须与模型系列匹配;通常填写 API 基地址即可。++「获取模型列表」只验证列表接口可访问,不代表所选模型、音色已能合成语音。请点击「试听音色」验证,成功后保存并选择默认 TTS 模型。+## 试听在 TTS 模型配置中选择音色、语言和参数,填写相应语言的示例文本,点击「试听音色」。试听使用当前表单,不要求先保存,也不修改默认模型。修改配置或试听文本后,旧试听会清除;生成中的请求可取消。+如果合成较慢,在同一模型配置中调整「请求超时(秒)」:范围为 5–600 秒,留空默认 60 秒。试听使用当前表单的值;应用设置后,正文朗读也使用该值。超时会提示调整此参数或缩短文本。+一般试听文本最多 500 字符,Groq Orpheus 最多 200 字符。试听会调用所配置的服务商,可能产生语音合成费用。+试听失败时,页面会区分 API Key/地域不匹配、模型或音色权限不足、地址或模型不存在、参数被拒绝、额度/限流、网络超时和音频下载失败。错误提示不显示服务商返回的原始报文或凭据。+## 官方接口资料- [火山 TTS HTTP SSE](https://www.volcengine.com/docs/6561/1598757)- [火山音色列表](https://www.volcengine.com/docs/6561/1257544)- [火山录音识别极速版](https://www.volcengine.com/docs/6561/1631584)- [Qwen TTS 音色列表](https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list)+- [Qwen-Audio TTS 音色列表](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list)+- [Qwen-Audio TTS HTTP 接口](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api)diff --git a/docs-for-user/workspaces.md b/docs-for-user/workspaces.mdindex bd273f40f..c58fa82f1 100644--- a/docs-for-user/workspaces.md+++ b/docs-for-user/workspaces.md@@ -10,6 +10,7 @@| --- | --- || 默认工作区的数据 | 保留历史 `data/user/workspace/`、`data/user/chat_history.db` 等路径;多用户使用各自的数据根目录。 || 自建工作区的数据 | 工作区文件夹内的 `.deeptutor/data/`,包括独立会话数据库、学习资料、进度和缓存。 |+| 聊天上传附件 | 所选工作区的 `chat/attachments/<会话 ID>/`,可通过工作区文件搜索发现;旧附件在继续该会话时迁入。显式配置 `CHAT_ATTACHMENT_DIR` 的默认工作区仍使用指定目录。 || 便于查看的生成文件 | 工作区文件夹内的 `outputs/`,按功能、会话和轮次组织。 || 设置、凭据、工作区登记信息 | 属于用户账号,切换工作区不改变。 || 记忆 | 仍由账号共享,本次不按工作区隔离。 |diff --git a/tests/__init__.py b/tests/__init__.pynew file mode 100644index 000000000..ae234e477--- /dev/null+++ b/tests/__init__.py@@ -0,0 +1 @@+"""Keep spawned test workers importing this suite instead of third-party test packages."""diff --git a/tests/api/test_voice_preview.py b/tests/api/test_voice_preview.pyindex 60c39adb6..bd6b4e345 100644--- a/tests/api/test_voice_preview.py+++ b/tests/api/test_voice_preview.py@@ -3,11 +3,12 @@ from types import SimpleNamespacefrom fastapi import FastAPIfrom fastapi.testclient import TestClient+import httpximport pytestfrom deeptutor.api.routers import settingsfrom deeptutor.services.voice import preview-from deeptutor.services.voice.base import VoiceProviderError+from deeptutor.services.voice.base import VoiceProviderError, VoiceProviderHTTPErrordef fixture_catalog(secret="secret"):@@ -105,6 +106,37 @@ def test_preview_never_echoes_upstream_credentials(client, monkeypatch):assert "secret" not in response.text and "Authorization" not in response.text+def test_preview_uses_the_draft_timeout_without_a_hidden_sixty_second_cap(client, monkeypatch):+ async def synth(text, config):+ assert config.request_timeout == 180+ return b"audio", "audio/mpeg"++ monkeypatch.setattr(preview, "get_tts_adapter", lambda name: SimpleNamespace(synthesize=synth))+ catalog = fixture_catalog()+ catalog["services"]["tts"]["profiles"][0]["models"][1]["request_timeout"] = "180"+ response = client.post(+ "/settings/voice/preview",+ json={"catalog": catalog, "profile_id": "p", "model_id": "new", "text": "Hello"},+ )+ assert response.status_code == 200+++def test_preview_timeout_explains_the_setting_without_echoing_the_provider(client, monkeypatch):+ import httpx++ async def synth(*args):+ raise VoiceProviderError("secret") from httpx.ReadTimeout("upstream-secret")++ monkeypatch.setattr(preview, "get_tts_adapter", lambda name: SimpleNamespace(synthesize=synth))+ response = client.post(+ "/settings/voice/preview",+ json={"catalog": fixture_catalog(), "profile_id": "p", "model_id": "new", "text": "Hello"},+ )+ assert response.status_code == 504+ assert "Request timeout (seconds)" in response.text+ assert "secret" not in response.text++def test_preview_requires_admin(client, monkeypatch):from fastapi import HTTPException@@ -117,3 +149,131 @@ def test_preview_requires_admin(client, monkeypatch):json={"catalog": fixture_catalog(), "profile_id": "p", "model_id": "new", "text": "Hello"},)assert response.status_code == 403+++ "status,diagnosis",+ [+ (401, "authentication failed"),+ (403, "access was denied"),+ (404, "not found"),+ (400, "parameters were rejected"),+ (422, "parameters were rejected"),+ (429, "quota or rate limit"),+ (503, "temporarily unavailable"),+ ],+)+def test_preview_explains_provider_failure_without_echoing_its_body(+ client, monkeypatch, status, diagnosis+):+ async def synth(*args):+ raise VoiceProviderHTTPError(+ "echo draft-secret Authorization: Bearer secret",+ status_code=status,+ body='{"message":"draft-secret"}',+ )++ monkeypatch.setattr(preview, "get_tts_adapter", lambda name: SimpleNamespace(synthesize=synth))+ response = client.post(+ "/settings/voice/preview",+ json={"catalog": fixture_catalog(), "profile_id": "p", "model_id": "new", "text": "Hello"},+ )+ assert response.status_code == 502+ assert diagnosis in response.json()["detail"]+ assert "secret" not in response.text and "Authorization" not in response.text+++def test_preview_synthesizes_the_unsaved_qwen_audio_plus_configuration(client, monkeypatch):+ """Run the screenshot's configuration through the real resolver and adapter."""+ catalog = fixture_catalog()+ catalog["connections"][0].update(+ provider="dashscope", base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"+ )+ catalog["services"]["tts"]["profiles"][0]["provider_ref"]["binding"] = "dashscope"+ catalog["services"]["tts"]["profiles"][0]["models"][1] = {+ "id": "new",+ "model": "qwen-audio-3.0-tts-plus",+ "voice": "longanlingxin",+ "response_format": "mp3",+ }+ before = deepcopy(catalog)++ async def post(_self, url, **kwargs):+ assert url == "https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer"+ assert kwargs["json"] == {+ "model": "qwen-audio-3.0-tts-plus",+ "input": {+ "text": "你好,我是你的学习伙伴。",+ "voice": "longanlingxin",+ "format": "mp3",+ "sample_rate": 24000,+ },+ }+ return httpx.Response(+ 200, json={"output": {"audio": {"url": "https://cdn.example/audio.mp3"}}}+ )++ async def get(_self, url, **kwargs):+ assert url == "https://cdn.example/audio.mp3"+ return httpx.Response(200, content=b"ID3audio", headers={"content-type": "audio/mpeg"})++ monkeypatch.setattr(httpx.AsyncClient, "post", post)+ monkeypatch.setattr(httpx.AsyncClient, "get", get)+ response = client.post(+ "/settings/voice/preview",+ json={+ "catalog": catalog,+ "profile_id": "p",+ "model_id": "new",+ "text": "你好,我是你的学习伙伴。",+ },+ )+ assert response.status_code == 200 and response.content == b"ID3audio"+ assert response.headers["content-type"] == "audio/mpeg"+ assert catalog == before++[email protected]("failure", ["timeout", "connection", "invalid_response", "download"])+def test_dashscope_preview_reports_the_failed_stage_without_exposing_credentials(+ client, monkeypatch, failure+):+ catalog = fixture_catalog()+ catalog["connections"][0].update(+ provider="dashscope", base_url="https://dashscope.aliyuncs.com/api/v1"+ )+ catalog["services"]["tts"]["profiles"][0]["provider_ref"]["binding"] = "dashscope"+ catalog["services"]["tts"]["profiles"][0]["models"][1] = {+ "id": "new",+ "model": "qwen3-tts-flash",+ "voice": "Cherry",+ }++ async def post(*args, **kwargs):+ if failure == "timeout":+ raise httpx.ReadTimeout("echo draft-secret")+ if failure == "connection":+ raise httpx.ConnectError("echo draft-secret")+ if failure == "invalid_response":+ return httpx.Response(200, text="draft-secret")+ return httpx.Response(+ 200, json={"output": {"audio": {"url": "https://cdn.example/audio.wav"}}}+ )++ async def get(*args, **kwargs):+ return httpx.Response(403, text="draft-secret")++ monkeypatch.setattr(httpx.AsyncClient, "post", post)+ monkeypatch.setattr(httpx.AsyncClient, "get", get)+ response = client.post(+ "/settings/voice/preview",+ json={"catalog": catalog, "profile_id": "p", "model_id": "new", "text": "Hello"},+ )+ expected = {+ "timeout": "timed out",+ "connection": "Could not connect",+ "invalid_response": "invalid response",+ "download": "audio download failed",+ }+ assert response.status_code == (504 if failure == "timeout" else 502)+ assert expected[failure] in response.json()["detail"]+ assert "secret" not in response.textdiff --git a/tests/api/test_voice_routes.py b/tests/api/test_voice_routes.pyindex 1dcfef4cc..f2ae1b547 100644--- a/tests/api/test_voice_routes.py+++ b/tests/api/test_voice_routes.py@@ -12,6 +12,7 @@ import pytestfrom deeptutor.api.routers import voice as voice_routerfrom deeptutor.services.voice import VoiceProviderError+from deeptutor.services.voice.base import VoiceProviderTimeout@pytest.fixture()@@ -84,6 +85,16 @@ def test_tts_missing_config_is_400(client: TestClient, monkeypatch: pytest.Monkeassert resp.status_code == 400+def test_tts_timeout_is_504_with_an_actionable_setting(client, monkeypatch) -> None:+ async def timeout(*args, **kwargs):+ raise VoiceProviderTimeout()++ monkeypatch.setattr(voice_router, "synthesize_speech", timeout)+ resp = client.post("/api/voice/tts", json={"text": "hello"})+ assert resp.status_code == 504+ assert "Request timeout (seconds)" in resp.json()["detail"]++def test_stt_returns_text(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:captured: dict[str, Any] = {}diff --git a/tests/services/test_provider_probe.py b/tests/services/test_provider_probe.pyindex 8c97060e6..290050e0c 100644--- a/tests/services/test_provider_probe.py+++ b/tests/services/test_provider_probe.py@@ -5,10 +5,126 @@ from types import SimpleNamespaceimport aiohttpimport pytest+import requestsfrom deeptutor.services.settings import provider_probe+ "status,expected",+ [(403, "json_forbidden"), (429, "rate_limited"), (500, "http_error")],+)+async def test_searxng_json_search_errors_are_actionable(monkeypatch, status, expected):+ """A working HTML homepage does not establish JSON API access."""+ response = requests.Response()+ response.status_code = status+ response._content = b"upstream-secret-do-not-return"+ calls = []++ def get(url, **kwargs):+ calls.append((url, kwargs))+ return response++ monkeypatch.setattr(requests, "get", get)+ result = await provider_probe.probe_search_provider("searxng", "http://localhost:8888", None)+ assert result == {"status": expected, "models": [], "http_status": status}+ assert "secret" not in str(result)+ assert calls[0][0] == "http://localhost:8888/search"+ assert calls[0][1]["params"]["format"] == "json"+++ "error,expected",+ [+ (requests.ReadTimeout("secret"), "timeout"),+ (requests.ConnectionError("secret"), "unreachable"),+ ],+)+async def test_search_transport_failures_keep_their_reason(monkeypatch, error, expected):+ def get(*args, **kwargs):+ raise error++ monkeypatch.setattr(requests, "get", get)+ assert await provider_probe.probe_search_provider("searxng", "http://localhost:8888", None) == {+ "status": expected,+ "models": [],+ }++[email protected]("url", ["", "http://[", "ftp://example.test", "http://example.test:bad"])+async def test_invalid_searxng_addresses_do_not_send_a_request(monkeypatch, url):+ calls = []+ monkeypatch.setattr(requests, "get", lambda *args, **kwargs: calls.append(args))+ assert await provider_probe.probe_search_provider("searxng", url, None) == {+ "status": "invalid_url",+ "models": [],+ }+ assert calls == []++[email protected]("body", [b"<html>secret</html>", b'{"error":"secret"}', b"[]"])+async def test_searxng_invalid_search_payload_is_not_connected(monkeypatch, body):+ response = requests.Response()+ response.status_code = 200+ response._content = body+ monkeypatch.setattr(requests, "get", lambda *args, **kwargs: response)+ assert await provider_probe.probe_search_provider("searxng", "http://localhost:8888", None) == {+ "status": "invalid_response",+ "models": [],+ }+++async def test_empty_search_results_verify_connection_but_warn(monkeypatch):+ response = requests.Response()+ response.status_code = 200+ response._content = b'{"results":[]}'+ monkeypatch.setattr(requests, "get", lambda *args, **kwargs: response)+ result = await provider_probe.probe_search_provider("searxng", "http://localhost:8888", None)+ assert result["status"] == "connected"+ assert result["warning"] == "empty_results"+ # A full model/search test still requires actual results.+ with pytest.raises(ValueError, match="no answer or results"):+ provider_probe.test_search_access("searxng", "http://localhost:8888", None)+++async def test_provider_probe_uses_the_form_search_proxy(monkeypatch):+ from deeptutor.api.routers import settings as router++ monkeypatch.setattr(router, "_require_settings_admin", lambda: None)+ monkeypatch.setattr(+ router, "get_model_catalog_service", lambda: SimpleNamespace(load=lambda: {})+ )+ monkeypatch.setattr(+ router, "get_settings_draft_service", lambda: SimpleNamespace(load=lambda: {})+ )+ response = requests.Response()+ response.status_code = 200+ response._content = b'{"results":[{"title":"OK","url":"https://example.test"}]}'+ calls = []++ def get(url, **kwargs):+ calls.append(kwargs)+ return response++ monkeypatch.setattr(requests, "get", get)+ result = await router.test_provider_connection(+ router.ProviderProbePayload(+ service="search",+ binding="searxng",+ base_url="http://searxng:8080",+ proxy="http://proxy:3128",+ )+ )+ assert result["status"] == "connected"+ assert calls[0]["proxies"] == {"http": "http://proxy:3128", "https": "http://proxy:3128"}++class Response:def __init__(self, status=200, payload=None):self.status, self.payload = status, payloaddiff --git a/tests/services/test_voice.py b/tests/services/test_voice.pyindex 8211509ca..8172955cd 100644--- a/tests/services/test_voice.py+++ b/tests/services/test_voice.py@@ -7,6 +7,7 @@ config resolution.from __future__ import annotations+import asyncioimport base64from dataclasses import dataclassimport json@@ -33,10 +34,12 @@ from deeptutor.services.voice.adapters.openai_compat import (from deeptutor.services.voice.audio import normalize_wav, pcm_to_wavfrom deeptutor.services.voice.base import (VoiceProviderError,+ VoiceProviderTimeout,build_auth_headers,join_audio_path,normalize_stt_content_type,strip_markdown_for_speech,+ synthesize_with_timeout,)from deeptutor.services.voice.config import STTConfig, TTSConfigfrom deeptutor.services.voice.options import voice_options@@ -364,6 +367,133 @@ async def test_dashscope_tts_posts_native_shape_and_downloads_audio(assert captured["gets"][0]["url"] == "https://cdn.example.com/audio.wav"+ "base_url,expected",+ [+ (+ "https://dashscope.aliyuncs.com/api/v1",+ "https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer",+ ),+ (+ "https://dashscope.aliyuncs.com/compatible-mode/v1",+ "https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer",+ ),+ (+ "https://workspace.cn-beijing.maas.aliyuncs.com/api/v1",+ "https://workspace.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer",+ ),+ (+ "https://gateway.example/audio/tts/SpeechSynthesizer?region=beijing",+ "https://gateway.example/audio/tts/SpeechSynthesizer?region=beijing",+ ),+ (+ "https://gateway.example/services/aigc/multimodal-generation/generation",+ "https://gateway.example/services/aigc/multimodal-generation/generation",+ ),+ ],+)+async def test_qwen_audio_plus_uses_its_own_endpoint_and_speech_parameters(+ monkeypatch, base_url, expected+):+ """The reported Plus/longanlingxin setup must use SpeechSynthesizer, including custom endpoints."""+ captured = _capture_http(+ monkeypatch,+ post=httpx.Response(+ 200, json={"output": {"audio": {"url": "https://cdn.example/audio.mp3"}}}+ ),+ get=httpx.Response(200, content=b"ID3audio", headers={"content-type": "audio/mpeg"}),+ )+ config = TTSConfig(+ model="qwen-audio-3.0-tts-plus",+ base_url=base_url,+ api_key="key",+ voice="longanlingxin",+ response_format="mp3",+ language="zh",+ speed=1.2,+ sample_rate=24000,+ instructions="温柔地朗读",+ )+ audio, content_type = await DashScopeTTSAdapter().synthesize("你好", config)+ assert audio == b"ID3audio" and content_type == "audio/mpeg"+ assert captured["posts"][0]["url"] == expected+ assert captured["posts"][0]["json"] == {+ "model": "qwen-audio-3.0-tts-plus",+ "input": {+ "text": "你好",+ "voice": "longanlingxin",+ "format": "mp3",+ "sample_rate": 24000,+ "language_hints": ["zh"],+ "rate": 1.2,+ "instruction": "温柔地朗读",+ },+ }+++async def test_qwen_audio_pcm_preserves_the_requested_sample_rate_for_playback(monkeypatch):+ _capture_http(+ monkeypatch,+ post=httpx.Response(+ 200, json={"output": {"audio": {"url": "https://cdn.example/audio.pcm"}}}+ ),+ get=httpx.Response(+ 200, content=b"\0\0", headers={"content-type": "application/octet-stream"}+ ),+ )+ config = TTSConfig(+ model="qwen-audio-3.0-tts-flash",+ base_url="https://dashscope.aliyuncs.com/api/v1",+ voice="longanfengyue",+ response_format="pcm",+ sample_rate=16000,+ )+ assert await DashScopeTTSAdapter().synthesize("你好", config) == (+ b"\0\0",+ "audio/pcm;rate=16000;channels=1",+ )+++ "overrides,diagnosis",+ [+ ({"base_url": "https://dashscope-intl.aliyuncs.com/api/v1"}, "only in Beijing"),+ (+ {"base_url": "https://workspace.ap-southeast-1.maas.aliyuncs.com/api/v1"},+ "only in Beijing",+ ),+ (+ {+ "base_url": "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"+ },+ "does not match this model",+ ),+ ({"model": "qwen3-tts-flash-realtime"}, "Realtime speech models"),+ ({"response_format": "aac"}, "supports MP3"),+ ({"response_format": "opus", "sample_rate": 44100}, "sample rate"),+ ({"voice": ""}, "Enter a voice ID"),+ ],+)+async def test_invalid_qwen_audio_configuration_fails_before_a_provider_call(+ monkeypatch, overrides, diagnosis+):+ captured = _capture_http(monkeypatch, post=None, get=None)+ config = TTSConfig(+ **{+ "model": "qwen-audio-3.0-tts-plus",+ "base_url": "https://dashscope.aliyuncs.com/api/v1",+ "voice": "longanlingxin",+ **overrides,+ }+ )+ with pytest.raises(ValueError, match=diagnosis):+ await DashScopeTTSAdapter().synthesize("你好", config)+ assert captured["posts"] == []++@pytest.mark.asyncioasync def test_openrouter_tts_falls_back_to_chat_audio_stream(monkeypatch: pytest.MonkeyPatch,@@ -617,6 +747,48 @@ def test_resolve_tts_config_uses_provider_default_base() -> None:assert cfg.voice == "FunAudioLLM/CosyVoice2-0.5B:anna"assert cfg.response_format == "wav"assert cfg.api_key == "sf-key"+ assert cfg.request_timeout == 60++[email protected]("value", [180, "180"])+def test_speech_model_timeout_reaches_the_adapter(value, tmp_path) -> None:+ from deeptutor.services.config.model_catalog import ModelCatalogService++ catalog = _voice_catalog()+ catalog["services"]["tts"]["profiles"][0]["models"][0]["request_timeout"] = value+ service = ModelCatalogService(path=tmp_path / "model_catalog.json")+ service.save(catalog)+ assert resolve_tts_runtime_config(catalog=service.load()).request_timeout == 180++[email protected]("value", [0, -1, "abc", "12.5", 601, True])+def test_invalid_speech_timeouts_are_rejected(value) -> None:+ catalog = _voice_catalog()+ catalog["services"]["tts"]["profiles"][0]["models"][0]["request_timeout"] = value+ with pytest.raises(ValueError, match="Speech request timeout"):+ resolve_tts_runtime_config(catalog=catalog)+++async def test_synthesis_deadline_cancels_an_active_stream() -> None:+ """The whole synthesis is bounded even if audio chunks keep arriving."""++ class SlowAdapter:+ cancelled = False++ async def synthesize(self, text, config):+ try:+ while True:+ await asyncio.sleep(0.005)+ finally:+ self.cancelled = True++ adapter = SlowAdapter()+ with pytest.raises(VoiceProviderTimeout, match="Request timeout"):+ await synthesize_with_timeout(+ adapter, "Hello", TTSConfig(model="test", request_timeout=0.02)+ )+ assert adapter.cancelleddef test_resolve_stt_config_picks_openrouter_base64_style() -> None:diff --git a/tests/services/test_volcengine_voice.py b/tests/services/test_volcengine_voice.pyindex 31e6b7075..59d031283 100644--- a/tests/services/test_volcengine_voice.py+++ b/tests/services/test_volcengine_voice.py@@ -227,6 +227,24 @@ def test_voice_choices_are_per_model_and_unknown_models_have_no_false_voice_defa].endswith(":alex")+def test_qwen_audio_defaults_and_hints_match_the_selected_model():+ plus = catalog("dashscope", "qwen-audio-3.0-tts-plus")+ before = deepcopy(plus)+ config = resolve_tts_runtime_config(plus)+ assert config.voice == "longanlingxin" and config.response_format == "mp3"+ assert plus == before+ options = voice_model_options("dashscope", "tts", "qwen-audio-3.0-tts-plus")+ assert [v["id"] for v in options["voices"]] == ["longanlingxin", "longanlufeng"]+ assert options["docs_url"].endswith("qwen-audio-tts-voice-list")+ assert "Beijing" in options["configuration_note"]+ assert (+ resolve_tts_runtime_config(catalog("dashscope", "qwen-audio-3.0-tts-flash")).voice+ == "longanfengyue"+ )+ # Future Qwen-Audio models must not silently acquire Qwen3's Cherry voice.+ assert resolve_tts_runtime_config(catalog("dashscope", "qwen-audio-9.0-tts-plus")).voice == ""++@pytest.mark.parametrize("suffix,service",[diff --git a/tests/services/workspace/test_data_migration.py b/tests/services/workspace/test_data_migration.pyindex 7dd519ae1..b31a5443f 100644--- a/tests/services/workspace/test_data_migration.py+++ b/tests/services/workspace/test_data_migration.py@@ -334,6 +334,45 @@ async def test_custom_attachment_root_moves_original_files(account, monkeypatch,assert path.read_bytes() == b"original"+async def test_moving_chat_moves_legacy_attachment_into_selected_workspace(account):+ from deeptutor.services.storage.attachment_store import (+ _legacy_attachment_root,+ get_attachment_store,+ )+ from deeptutor.services.workspace.session_move import move_chat++ target = account.create_workspace("Destination")["workspace_id"]+ with workspace_context():+ session = await get_sqlite_session_store().create_session()+ legacy = _legacy_attachment_root() / session["id"] / "doc_notes.txt"+ legacy.parent.mkdir(parents=True, exist_ok=True)+ legacy.write_bytes(b"old upload")+ await get_sqlite_session_store().add_message(+ session["id"], "user", "/files/attachments/{}/doc/notes.txt".format(session["id"])+ )+ move_chat(session["id"], target)+ assert not legacy.exists()+ assert not account.search(account.general_binding(), "notes.txt")+ with workspace_context(target):+ store = get_attachment_store()+ resolved = store.resolve_path(+ session_id=session["id"], attachment_id="doc", filename="notes.txt"+ )+ assert (+ resolved+ == account.binding_by_id(target).root+ / "chat"+ / "attachments"+ / session["id"]+ / "doc_notes.txt"+ )+ assert resolved.read_bytes() == b"old upload"+ assert account.search(account.binding_by_id(target), "notes.txt")[0]["path"].startswith(+ "chat/attachments/"+ )++def test_initialized_empty_feature_can_receive_migration(account):target = account.create_workspace("Empty initialized")["workspace_id"]source = get_path_service().get_workspace_dir() / "reading"diff --git a/tests/services/workspace/test_data_scope.py b/tests/services/workspace/test_data_scope.pyindex 977af0bf5..ad1f89002 100644--- a/tests/services/workspace/test_data_scope.py+++ b/tests/services/workspace/test_data_scope.py@@ -76,6 +76,57 @@ async def test_sessions_and_turns_are_not_accessible_from_other_workspaces(accouassert await other.get_messages(session["id"]) == []+async def test_chat_attachments_are_searchable_in_selected_workspace(account):+ from deeptutor.services.storage.attachment_store import (+ _legacy_attachment_root,+ get_attachment_store,+ )++ selected = account.create_workspace("Selected")["workspace_id"]+ for workspace_id in ("", selected):+ binding = (+ account.general_binding() if not workspace_id else account.binding_by_id(workspace_id)+ )+ with workspace_context(workspace_id):+ store = get_attachment_store()+ assert store.root == binding.root / "chat" / "attachments"+ await store.put(+ session_id="chat-one",+ attachment_id="new",+ filename="current-notes.txt",+ data=b"current attachment",+ )+ assert account.search(binding, "current-notes.txt") == [+ {+ "path": "chat/attachments/chat-one/new_current-notes.txt",+ "line": None,+ "preview": "new_current-notes.txt",+ }+ ]++ legacy = _legacy_attachment_root() / "chat-one" / "old_previous-notes.txt"+ legacy.parent.mkdir(parents=True, exist_ok=True)+ legacy.write_bytes(b"previous attachment")+ assert (+ store.resolve_path(+ session_id="chat-one", attachment_id="old", filename="previous-notes.txt"+ )+ == legacy+ )+ await store.materialize_session("chat-one")+ assert not legacy.exists()+ assert (+ store.resolve_path(+ session_id="chat-one", attachment_id="old", filename="previous-notes.txt"+ )+ == binding.root / "chat" / "attachments" / "chat-one" / "old_previous-notes.txt"+ )+ assert account.search(binding, "previous-notes.txt")[0]["path"].startswith(+ "chat/attachments/chat-one/"+ )++@pytest.mark.asyncioasync def test_background_task_and_thread_keep_original_workspace(account):a, b = account.create_workspace("A"), account.create_workspace("B")diff --git a/web/components/settings/ProviderModelDiscovery.tsx b/web/components/settings/ProviderModelDiscovery.tsxindex 14c650f10..947081f37 100644--- a/web/components/settings/ProviderModelDiscovery.tsx+++ b/web/components/settings/ProviderModelDiscovery.tsx@@ -13,6 +13,7 @@ export type ProviderProbeInput = {api_format?: string;api_version?: string;extra_headers?: Record<string, string> | string;+ proxy?: string;service?: string;profile_id?: string;connection_id?: string;diff --git a/web/components/settings/RegistryControls.tsx b/web/components/settings/RegistryControls.tsxindex b5697b65f..4c9f71e00 100644--- a/web/components/settings/RegistryControls.tsx+++ b/web/components/settings/RegistryControls.tsx@@ -87,7 +87,20 @@ const PROBE_MESSAGES: Record<string, string> = {invalid_url: "Enter a valid HTTP or HTTPS provider address.",http_error:"The provider returned an error. Check the address or try again later.",+ json_forbidden:+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.",+ invalid_response:+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.",};++function usesLoopbackAddress(address: string): boolean {+ try {+ const host = new URL(address.includes("://") ? address : `http://${address}`).hostname;+ return host === "localhost" || host.startsWith("127.") || host === "[::1]";+ } catch {+ return false;+ }+}const CATEGORIES = ["Language models","Embedding models",@@ -203,6 +216,17 @@ function ProbeForm({className={`text-xs leading-relaxed ${result.status === "connected" ? "text-emerald-700 dark:text-emerald-400" : "text-[var(--muted-foreground)]"}`}>{t(PROBE_MESSAGES[result.status] || PROBE_MESSAGES.http_error)}+ {result.http_status != null && ` · HTTP ${result.http_status}`}+ {result.warning === "empty_results" && (+ <p className="mt-2">+ {t("The search API is reachable but returned no results. Check the enabled engines and their network access.")}+ </p>+ )}+ {input.binding === "searxng" && result.status !== "connected" && usesLoopbackAddress(input.base_url) && (+ <p className="mt-2">+ {t("This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.")}+ </p>+ )}{result.status === "connected" &&input.service !== "search" &&` · ${t("{{count}} models available", { count: result.models.length })}`}diff --git a/web/components/settings/VoiceModelFields.tsx b/web/components/settings/VoiceModelFields.tsxindex 5cfcc51a6..1fa6c3e5a 100644--- a/web/components/settings/VoiceModelFields.tsx+++ b/web/components/settings/VoiceModelFields.tsx@@ -3,6 +3,7 @@import { useId } from 'react'import { useTranslation } from 'react-i18next'import type { CatalogModel, VoiceModelOption, VoiceOptions } from '@/lib/model-catalog-types'+import { DEFAULT_SPEECH_REQUEST_TIMEOUT, MIN_SPEECH_REQUEST_TIMEOUT, MAX_SPEECH_REQUEST_TIMEOUT } from '@/lib/voice-settings'import { RegistryField, RegistryModelIdField } from './RegistryControls'import { inputClass, selectClass } from './shared'@@ -26,12 +27,36 @@ export function VoiceModelFields({const { t } = useTranslation()const speedId = useId()const instructionId = useId()+ const timeoutId = useId()const voice = preset?.voices.find(v => v.id === model.voice)const languages =preset?.languages.filter(l => !voice?.languages || voice.languages.includes(l.id)) ?? []+ const docsUrl = preset?.docs_url ?? options?.docs_urlreturn (<section aria-label={t('Speech options')} className="space-y-4"><div className="grid gap-4 lg:grid-cols-2">+ {service === 'tts' && (+ <div className="space-y-1.5">+ <label htmlFor={timeoutId} className="text-xs font-medium">+ {t('Request timeout (seconds)')}+ </label>+ <input+ id={timeoutId}+ type="number"+ className={inputClass}+ disabled={disabled}+ value={model.request_timeout ?? ''}+ min={MIN_SPEECH_REQUEST_TIMEOUT}+ max={MAX_SPEECH_REQUEST_TIMEOUT}+ step={1}+ placeholder={String(DEFAULT_SPEECH_REQUEST_TIMEOUT)}+ onChange={e => update('request_timeout', e.target.value)}+ />+ <p className="text-xs text-[var(--muted-foreground)]">+ {t('5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.')}+ </p>+ </div>+ )}{service === 'tts' && (<><label className="space-y-1.5 text-xs font-medium">@@ -156,6 +181,16 @@ export function VoiceModelFields({{t(preset?.language_note ?? 'Language follows the text and selected voice.')}</p>)}+ {preset?.configuration_note && (+ <p className="text-xs leading-relaxed text-[var(--muted-foreground)]">+ {t(preset.configuration_note)}+ </p>+ )}+ {service === 'tts' && (+ <p className="text-xs leading-relaxed text-[var(--muted-foreground)]">+ {t('Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.')}+ </p>+ )}{service === 'tts' && provider === 'volcengine_speech' && (<p className="text-xs text-[var(--muted-foreground)]">{t(@@ -167,11 +202,11 @@ export function VoiceModelFields({{t('Suggestions depend on the provider and model. You can enter other model, voice and language IDs supported by your account.')}- {options?.docs_url && (+ {docsUrl && (<>{' '}<a- href={options.docs_url}+ href={docsUrl}target="_blank"rel="noreferrer"className="underline underline-offset-4"diff --git a/web/components/settings/VoicePreviewPanel.tsx b/web/components/settings/VoicePreviewPanel.tsxindex a36f8fa26..e3b93b8e0 100644--- a/web/components/settings/VoicePreviewPanel.tsx+++ b/web/components/settings/VoicePreviewPanel.tsx@@ -6,6 +6,7 @@ import { useTranslation } from 'react-i18next'import { useSettings } from '@/features/settings/store/SettingsStore'import { apiFetch, apiUrl } from '@/lib/api'import { modelTestFingerprint } from '@/lib/model-settings'+import { speechRequestTimeout, SPEECH_TIMEOUT_MESSAGE } from '@/lib/voice-settings'import { inputClass, subPanelClass } from './shared'import { registryButton } from './RegistryControls'@@ -69,7 +70,9 @@ function PreviewRequest({const request = new AbortController()controller.current = requestsetPending(true)- const timeout = setTimeout(() => request.abort(), 65000)+ const model = draft.services.tts.profiles.find(p => p.id === profileId)?.models.find(m => m.id === modelId)+ // Allow the configured backend deadline plus time to return its error.+ const timeout = setTimeout(() => request.abort(), (speechRequestTimeout(model) + 5) * 1000)try {const response = await apiFetch(apiUrl('/api/settings/voice/preview'), {method: 'POST',@@ -91,7 +94,7 @@ function PreviewRequest({} catch (err) {if (!request.signal.aborted)setError(err instanceof Error ? err.message : 'Voice preview failed.')- else if (controller.current === request) setError('Voice preview was cancelled or timed out.')+ else if (controller.current === request) setError(SPEECH_TIMEOUT_MESSAGE)} finally {clearTimeout(timeout)if (controller.current === request) setPending(false)diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.tsindex 8dcf701a0..7db477feb 100644--- a/web/contracts/generated/api.ts+++ b/web/contracts/generated/api.ts@@ -14239,6 +14239,11 @@ export interface components {| null;/** Profile Id */readonly profile_id?: string | null;+ /**+ * Proxy+ * @default+ */+ readonly proxy: string;/*** Service* @default llmdiff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.jsonindex 4665e4c46..3c62404b4 100644--- a/web/contracts/schema/openapi.json+++ b/web/contracts/schema/openapi.json@@ -7696,6 +7696,11 @@],"title": "Profile Id"},+ "proxy": {+ "default": "",+ "title": "Proxy",+ "type": "string"+ },"service": {"default": "llm","enum": [diff --git a/web/features/chat/messages/ChatMessageList.tsx b/web/features/chat/messages/ChatMessageList.tsxindex 3d2b20cfb..aa3568ea7 100644--- a/web/features/chat/messages/ChatMessageList.tsx+++ b/web/features/chat/messages/ChatMessageList.tsx@@ -54,6 +54,10 @@ import { apiFetch, apiUrl } from "@/lib/api";import { notify } from "@/lib/notifications";import { docIconFor } from "@/lib/doc-attachments";import { useVoiceAutoplay } from "@/hooks/useVoiceAutoplay";+import {+ SPEECH_PLAYBACK_FAILURE_MESSAGE,+ SPEECH_TIMEOUT_MESSAGE,+} from "@/lib/voice-settings";import { extractMathAnimatorResult } from "@/lib/math-animator-types";import {extractQuizQuestions,@@ -1367,8 +1371,9 @@ export function PlayAudioButton({if (gen !== genRef.current) return;if (!resp.ok) {const detail = await ttsErrorMessage(resp);+ if (gen !== genRef.current) return;notify(- detail || t("Could not play this reply. Check Text-to-Speech in Settings."),+ t(detail || (resp.status === 504 ? SPEECH_TIMEOUT_MESSAGE : SPEECH_PLAYBACK_FAILURE_MESSAGE)),{ tone: "error" },);stop();@@ -1392,7 +1397,7 @@ export function PlayAudioButton({};audio.onerror = () => {if (gen !== genRef.current) return;- notify(t("Could not play this reply. Check Text-to-Speech in Settings."), {+ notify(t(SPEECH_PLAYBACK_FAILURE_MESSAGE), {tone: "error",});stop();@@ -1406,7 +1411,7 @@ export function PlayAudioButton({} catch (err) {if (gen !== genRef.current) return;if (err instanceof Error && err.name === "AbortError") return;- notify(t("Could not play this reply. Check Text-to-Speech in Settings."), {+ notify(t(SPEECH_PLAYBACK_FAILURE_MESSAGE), {tone: "error",});stop();diff --git a/web/lib/model-catalog-types.ts b/web/lib/model-catalog-types.tsindex c21ecdd23..efcc5bbd9 100644--- a/web/lib/model-catalog-types.ts+++ b/web/lib/model-catalog-types.ts@@ -11,6 +11,8 @@ export type Discovery = {models: { id: string }[];capabilities?: { category: string; evidence: string }[];checked_at?: string;+ http_status?: number | null;+ warning?: string;};export type ServiceName =| "llm"@@ -64,6 +66,7 @@ export type CatalogModel = {sample_rate?: string;instructions?: string;resource_id?: string;+ request_timeout?: string | number;response_format?: string;language?: string;// Image generation: pixel size (e.g. "1024x1024"), quality, and style.@@ -222,6 +225,8 @@ export type VoiceModelOption = {languages: VoiceChoice[];formats: string[];language_note?: string;+ configuration_note?: string;+ docs_url?: string;max_input_chars?: number;speed?: { min: number; max: number; step: number };sample_rates?: number[];diff --git a/web/lib/provider-registry.ts b/web/lib/provider-registry.tsindex 86e0cf3a1..48cce1cf9 100644--- a/web/lib/provider-registry.ts+++ b/web/lib/provider-registry.ts@@ -201,6 +201,7 @@ export function providerProbeInput(source: ProviderSource, fallbackUrl = "") {api_version: s.api_version,api_format: s.api_format || "auto",extra_headers: s.extra_headers,+ proxy: s.proxy || "",service: source.service || (s as CatalogConnection).source_service || "llm",};}diff --git a/web/lib/voice-settings.ts b/web/lib/voice-settings.tsindex 1a5c62edb..44022e755 100644--- a/web/lib/voice-settings.ts+++ b/web/lib/voice-settings.ts@@ -1,4 +1,19 @@-import type { VoiceOptions, VoiceModelOption } from './model-catalog-types'+import type { CatalogModel, VoiceOptions, VoiceModelOption } from './model-catalog-types'++export const DEFAULT_SPEECH_REQUEST_TIMEOUT = 60+export const MIN_SPEECH_REQUEST_TIMEOUT = 5+export const MAX_SPEECH_REQUEST_TIMEOUT = 600+export const SPEECH_TIMEOUT_MESSAGE =+ 'Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.'+export const SPEECH_PLAYBACK_FAILURE_MESSAGE =+ 'Speech playback failed. Check the speech model settings and provider connection.'++export function speechRequestTimeout(model: CatalogModel | undefined): number {+ const seconds = Number(model?.request_timeout)+ return Number.isInteger(seconds) && seconds >= MIN_SPEECH_REQUEST_TIMEOUT && seconds <= MAX_SPEECH_REQUEST_TIMEOUT+ ? seconds+ : DEFAULT_SPEECH_REQUEST_TIMEOUT+}export function voiceModelOptions(options: VoiceOptions | undefined,diff --git a/web/locales/de/app.json b/web/locales/de/app.jsonindex 1553f1507..2ed08f5b3 100644--- a/web/locales/de/app.json+++ b/web/locales/de/app.json@@ -5301,5 +5301,34 @@"Select a vision model for image descriptions in documents.": "Wähle ein Vision-Modell für Bildbeschreibungen in Dokumenten.","Failed to load image description models.": "Die Modelle für Bildbeschreibungen konnten nicht geladen werden.","Could not play this reply. Check Text-to-Speech in Settings.": "Diese Antwort konnte nicht vorgelesen werden. Prüfe Text-to-Speech in den Einstellungen.",- "Couldn't confirm your answer. Check your connection and retry.": "Deine Antwort konnte nicht bestätigt werden. Prüfe die Verbindung und versuche es erneut."+ "Couldn't confirm your answer. Check your connection and retry.": "Deine Antwort konnte nicht bestätigt werden. Prüfe die Verbindung und versuche es erneut.",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "Die Sprachparameter wurden abgelehnt. Prüfe Modell, Stimme, Sprache und Audioformat.",+ "Speech authentication failed. Check the API key and its region.": "Die Sprachauthentifizierung ist fehlgeschlagen. Prüfe den API-Schlüssel und seine Region.",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "Das Sprachkontingent oder die Anfragengrenze wurde erreicht. Prüfe Guthaben und Kontingent oder versuche es später erneut.",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "Die Sprachsynthese erfordert eine HTTP- oder HTTPS-Anbieter-URL.",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "Das Abrufen der Modellliste testet keine Sprachsynthese. Teste dieses Modell und diese Stimme mit der Stimmenvorschau.",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "Echtzeit-Sprachmodelle werden hier nicht unterstützt. Wähle ein TTS-Modell ohne Echtzeitübertragung.",+ "Speech access was denied. Check model and voice permissions and the API key region.": "Der Sprachzugriff wurde verweigert. Prüfe die Modell- und Stimmenberechtigungen sowie die Region des API-Schlüssels.",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "Die Qwen-Audio-TTS-Sprechgeschwindigkeit muss zwischen 0,5 und 2 liegen.",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "Die Sprachsynthese hat das Zeitlimit überschritten. Erhöhe das Zeitlimit für Anfragen (Sekunden) in den Sprachmodelleinstellungen oder kürze den Text.",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "Der Suchendpunkt hat eine ungültige Antwort zurückgegeben. Prüfe, ob die Adresse die JSON-Such-API von SearXNG bereitstellt.",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG hat die JSON-Suchanfrage abgelehnt. Aktiviere json unter search.formats in der settings.yml und prüfe die Zugriffsregeln.",+ "Speech playback failed. Check the speech model settings and provider connection.": "Die Sprachausgabe ist fehlgeschlagen. Prüfe die Sprachmodelleinstellungen und die Verbindung zum Anbieter.",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 Sekunden. Lass das Feld für 60 Sekunden leer. Gilt für Sprachvorschauen und die Sprachausgabe.",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "Der Sprachendpunkt oder das Modell wurde nicht gefunden. Prüfe die Anbieter-URL und Modell-ID.",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS verwendet Stimmen wie Cherry und gibt WAV-Audio aus. Die Region des API-Schlüssels muss zur Anbieter-URL passen.",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS unterstützt die Audioformate MP3, WAV, Opus und PCM.",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "Gib eine Stimmen-ID ein, die das ausgewählte Qwen-Audio-TTS-Modell unterstützt.",+ "The speech provider is temporarily unavailable. Try again later.": "Der Sprachanbieter ist vorübergehend nicht verfügbar. Versuche es später erneut.",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "Der konfigurierte Sprachendpunkt passt nicht zu diesem Modell. Verwende die API-Basis-URL des Anbieters, damit der Endpunkt automatisch gewählt wird.",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS ist nur in Peking verfügbar. Verwende einen API-Schlüssel und eine Anbieter-URL für Peking.",+ "The speech provider returned empty audio. Try another text or voice.": "Der Sprachanbieter hat leeres Audio zurückgegeben. Versuche einen anderen Text oder eine andere Stimme.",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "Die gewählte Abtastrate wird für dieses Qwen-Audio-TTS-Audioformat nicht unterstützt.",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "Dieser Test wird vom DeepTutor-Backend ausgeführt. In Docker verweist localhost auf den DeepTutor-Container. Verwende einen Dienstnamen im gemeinsamen Netzwerk mit Container-Port oder host.docker.internal mit dem veröffentlichten Host-Port.",+ "The speech provider returned an invalid response. Check the provider URL.": "Der Sprachanbieter hat eine ungültige Antwort zurückgegeben. Prüfe die Anbieter-URL.",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "Die Such-API ist erreichbar, hat aber keine Ergebnisse zurückgegeben. Prüfe die aktivierten Suchmaschinen und deren Netzwerkzugriff.",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "Der Sprachanbieter konnte nicht erreicht werden. Prüfe die Anbieter-URL und Netzwerkverbindung.",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS erfordert einen API-Schlüssel für Peking. In der Anbieterverbindung kannst du eine Arbeitsbereichs-URL für Peking angeben; der Sprachendpunkt wird automatisch gewählt.",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "Die Sprache wurde erzeugt, aber der Audiodownload ist fehlgeschlagen. Versuche es erneut oder prüfe die Netzwerkverbindung.",+ "Request timeout (seconds)": "Zeitlimit für Anfragen (Sekunden)"}diff --git a/web/locales/en/app.json b/web/locales/en/app.jsonindex 514a648b1..c746a517f 100644--- a/web/locales/en/app.json+++ b/web/locales/en/app.json@@ -5301,5 +5301,34 @@"Use main LLM (fallback)": "Use main LLM (fallback)","Failed to load image description models.": "Failed to load image description models.","Select a vision model for image descriptions in documents.": "Select a vision model for image descriptions in documents.",- "Couldn't confirm your answer. Check your connection and retry.": "Couldn't confirm your answer. Check your connection and retry."+ "Couldn't confirm your answer. Check your connection and retry.": "Couldn't confirm your answer. Check your connection and retry.",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "Speech parameters were rejected. Check the model, voice, language and audio format.",+ "Speech authentication failed. Check the API key and its region.": "Speech authentication failed. Check the API key and its region.",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "Speech quota or rate limit was reached. Check your balance and quota, or retry later.",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "Speech synthesis requires an HTTP or HTTPS provider URL.",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "Realtime speech models are not supported here. Select a non-realtime TTS model.",+ "Speech access was denied. Check model and voice permissions and the API key region.": "Speech access was denied. Check model and voice permissions and the API key region.",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "Qwen-Audio TTS speed must be between 0.5 and 2.",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.",+ "Speech playback failed. Check the speech model settings and provider connection.": "Speech playback failed. Check the speech model settings and provider connection.",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "Speech endpoint or model was not found. Check the provider URL and model ID.",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "Enter a voice ID supported by the selected Qwen-Audio TTS model.",+ "The speech provider is temporarily unavailable. Try again later.": "The speech provider is temporarily unavailable. Try again later.",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.",+ "The speech provider returned empty audio. Try another text or voice.": "The speech provider returned empty audio. Try another text or voice.",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "The selected sample rate is not supported for this Qwen-Audio TTS audio format.",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.",+ "The speech provider returned an invalid response. Check the provider URL.": "The speech provider returned an invalid response. Check the provider URL.",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "The search API is reachable but returned no results. Check the enabled engines and their network access.",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "Could not connect to the speech provider. Check the provider URL and network connection.",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "Speech was generated, but the audio download failed. Try again or check the network connection.",+ "Request timeout (seconds)": "Request timeout (seconds)"}diff --git a/web/locales/fr/app.json b/web/locales/fr/app.jsonindex 3579dfc0d..59cb12394 100644--- a/web/locales/fr/app.json+++ b/web/locales/fr/app.json@@ -5744,5 +5744,34 @@"Select a vision model for image descriptions in documents.": "Sélectionnez un modèle de vision pour décrire les images des documents.","Failed to load image description models.": "Impossible de charger les modèles de description des images.","Could not play this reply. Check Text-to-Speech in Settings.": "Impossible de lire cette réponse. Vérifiez la synthèse vocale dans les paramètres.",- "Couldn't confirm your answer. Check your connection and retry.": "Impossible de confirmer votre réponse. Vérifiez votre connexion et réessayez."+ "Couldn't confirm your answer. Check your connection and retry.": "Impossible de confirmer votre réponse. Vérifiez votre connexion et réessayez.",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "La synthèse vocale a dépassé le délai. Augmentez le délai d’expiration des requêtes (secondes) dans les paramètres du modèle vocal ou raccourcissez le texte.",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "Le point de terminaison de recherche a renvoyé une réponse invalide. Vérifiez que cette adresse fournit l’API de recherche JSON de SearXNG.",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG a refusé la requête de recherche JSON. Activez json dans search.formats de son fichier settings.yml et vérifiez les règles d’accès.",+ "Speech playback failed. Check the speech model settings and provider connection.": "La lecture audio a échoué. Vérifiez les paramètres du modèle vocal et la connexion au fournisseur.",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 secondes. Laissez vide pour 60 secondes. S’applique aux aperçus vocaux et à la lecture audio.",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "Ce test est exécuté depuis le backend de DeepTutor. Dans Docker, localhost désigne le conteneur DeepTutor. Utilisez un nom de service sur le réseau partagé avec le port du conteneur, ou host.docker.internal avec le port publié sur l’hôte.",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "L’API de recherche est accessible, mais n’a renvoyé aucun résultat. Vérifiez les moteurs activés et leur accès réseau.",+ "Request timeout (seconds)": "Délai d’expiration des requêtes (secondes)",+ "Speech authentication failed. Check the API key and its region.": "L’authentification du service vocal a échoué. Vérifiez la clé API et sa région.",+ "Speech access was denied. Check model and voice permissions and the API key region.": "L’accès au service vocal a été refusé. Vérifiez les autorisations du modèle et de la voix ainsi que la région de la clé API.",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "Le point de terminaison ou le modèle vocal est introuvable. Vérifiez l’URL du fournisseur et l’identifiant du modèle.",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "Les paramètres vocaux ont été refusés. Vérifiez le modèle, la voix, la langue et le format audio.",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "Le quota ou la limite de requêtes vocales a été atteint. Vérifiez votre solde et votre quota, ou réessayez plus tard.",+ "The speech provider is temporarily unavailable. Try again later.": "Le fournisseur vocal est temporairement indisponible. Réessayez plus tard.",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "La voix a été générée, mais le téléchargement audio a échoué. Réessayez ou vérifiez la connexion réseau.",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "Impossible de se connecter au fournisseur vocal. Vérifiez son URL et la connexion réseau.",+ "The speech provider returned an invalid response. Check the provider URL.": "Le fournisseur vocal a renvoyé une réponse invalide. Vérifiez son URL.",+ "The speech provider returned empty audio. Try another text or voice.": "Le fournisseur vocal a renvoyé un audio vide. Essayez un autre texte ou une autre voix.",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "La synthèse vocale nécessite une URL de fournisseur en HTTP ou HTTPS.",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "Les modèles vocaux en temps réel ne sont pas pris en charge ici. Sélectionnez un modèle TTS hors temps réel.",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS est disponible uniquement dans la région de Pékin. Utilisez une clé API et une URL de fournisseur pour cette région.",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "Le point de terminaison vocal configuré ne correspond pas à ce modèle. Utilisez l’URL de base de l’API du fournisseur pour sélectionner automatiquement le point de terminaison.",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "Saisissez un identifiant de voix pris en charge par le modèle Qwen-Audio TTS sélectionné.",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS prend en charge les formats audio MP3, WAV, Opus et PCM.",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "La fréquence d’échantillonnage sélectionnée n’est pas prise en charge pour ce format audio Qwen-Audio TTS.",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "La vitesse de Qwen-Audio TTS doit être comprise entre 0,5 et 2.",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS utilise des voix comme Cherry et produit un audio WAV. Faites correspondre la région de la clé API à l’URL du fournisseur.",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS nécessite une clé API pour la région de Pékin. Vous pouvez définir une URL d’espace de travail de Pékin dans la connexion au fournisseur ; le point de terminaison vocal est sélectionné automatiquement.",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "Récupérer la liste des modèles ne teste pas la synthèse vocale. Utilisez l’aperçu vocal pour tester ce modèle et cette voix."}diff --git a/web/locales/pl/app.json b/web/locales/pl/app.jsonindex 68a31b611..c527ebf8c 100644--- a/web/locales/pl/app.json+++ b/web/locales/pl/app.json@@ -5317,5 +5317,34 @@"Select a vision model for image descriptions in documents.": "Wybierz model wizyjny do opisywania obrazów w dokumentach.","Failed to load image description models.": "Nie udało się wczytać modeli do opisywania obrazów.","Could not play this reply. Check Text-to-Speech in Settings.": "Nie udało się odczytać tej odpowiedzi. Sprawdź ustawienia syntezy mowy.",- "Couldn't confirm your answer. Check your connection and retry.": "Nie udało się potwierdzić odpowiedzi. Sprawdź połączenie i spróbuj ponownie."+ "Couldn't confirm your answer. Check your connection and retry.": "Nie udało się potwierdzić odpowiedzi. Sprawdź połączenie i spróbuj ponownie.",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG odrzucił żądanie wyszukiwania JSON. Włącz json w search.formats w pliku settings.yml i sprawdź reguły dostępu.",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "Punkt końcowy wyszukiwania zwrócił nieprawidłową odpowiedź. Sprawdź, czy adres udostępnia API wyszukiwania JSON SearXNG.",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "API wyszukiwania jest dostępne, ale nie zwróciło wyników. Sprawdź włączone wyszukiwarki i ich dostęp do sieci.",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "Ten test jest wykonywany przez backend DeepTutor. W Dockerze localhost wskazuje kontener DeepTutor. Użyj nazwy usługi we wspólnej sieci i portu kontenera albo host.docker.internal i opublikowanego portu hosta.",+ "Request timeout (seconds)": "Limit czasu żądania (sekundy)",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 sekund. Pozostaw puste, aby użyć 60 sekund. Dotyczy podglądu głosu i odtwarzania mowy.",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "Przekroczono limit czasu syntezy mowy. Zwiększ limit czasu żądania w ustawieniach modelu mowy lub użyj krótszego tekstu.",+ "Speech playback failed. Check the speech model settings and provider connection.": "Odtwarzanie mowy nie powiodło się. Sprawdź ustawienia modelu mowy i połączenie z dostawcą.",+ "Speech authentication failed. Check the API key and its region.": "Uwierzytelnienie usługi mowy nie powiodło się. Sprawdź klucz API i jego region.",+ "Speech access was denied. Check model and voice permissions and the API key region.": "Odmówiono dostępu do usługi mowy. Sprawdź uprawnienia do modelu i głosu oraz region klucza API.",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "Nie znaleziono punktu końcowego ani modelu mowy. Sprawdź adres URL dostawcy i identyfikator modelu.",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "Parametry mowy zostały odrzucone. Sprawdź model, głos, język i format audio.",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "Osiągnięto limit użycia lub częstotliwości żądań usługi mowy. Sprawdź saldo i limity albo spróbuj ponownie później.",+ "The speech provider is temporarily unavailable. Try again later.": "Dostawca usługi mowy jest tymczasowo niedostępny. Spróbuj ponownie później.",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "Mowa została wygenerowana, ale pobranie audio nie powiodło się. Spróbuj ponownie lub sprawdź połączenie sieciowe.",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "Nie udało się połączyć z dostawcą usługi mowy. Sprawdź adres URL dostawcy i połączenie sieciowe.",+ "The speech provider returned an invalid response. Check the provider URL.": "Dostawca usługi mowy zwrócił nieprawidłową odpowiedź. Sprawdź adres URL dostawcy.",+ "The speech provider returned empty audio. Try another text or voice.": "Dostawca usługi mowy zwrócił puste audio. Spróbuj użyć innego tekstu lub głosu.",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "Synteza mowy wymaga adresu URL dostawcy korzystającego z HTTP lub HTTPS.",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "Modele mowy czasu rzeczywistego nie są tu obsługiwane. Wybierz model TTS, który nie działa w czasie rzeczywistym.",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS jest dostępny tylko w regionie Pekin. Użyj klucza API i adresu URL dostawcy dla regionu Pekin.",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "Skonfigurowany punkt końcowy mowy nie pasuje do tego modelu. Użyj bazowego adresu URL API dostawcy, aby automatycznie wybrać punkt końcowy.",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "Podaj identyfikator głosu obsługiwany przez wybrany model Qwen-Audio TTS.",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS obsługuje formaty audio MP3, WAV, Opus i PCM.",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "Wybrana częstotliwość próbkowania nie jest obsługiwana dla tego formatu audio Qwen-Audio TTS.",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "Prędkość Qwen-Audio TTS musi wynosić od 0,5 do 2.",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS używa głosów takich jak Cherry i generuje audio WAV. Dopasuj region klucza API do adresu URL dostawcy.",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS wymaga klucza API z regionu Pekin. W połączeniu z dostawcą możesz ustawić adres URL przestrzeni roboczej z regionu Pekin; punkt końcowy mowy zostanie wybrany automatycznie.",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "Pobranie listy modeli nie sprawdza syntezy mowy. Użyj podglądu głosu, aby przetestować model i głos."}diff --git a/web/locales/uk/app.json b/web/locales/uk/app.jsonindex c39898b9d..6fe42bb82 100644--- a/web/locales/uk/app.json+++ b/web/locales/uk/app.json@@ -5317,5 +5317,34 @@"Select a vision model for image descriptions in documents.": "Виберіть модель зору для опису зображень у документах.","Failed to load image description models.": "Не вдалося завантажити моделі опису зображень.","Could not play this reply. Check Text-to-Speech in Settings.": "Не вдалося озвучити цю відповідь. Перевірте синтез мовлення в налаштуваннях.",- "Couldn't confirm your answer. Check your connection and retry.": "Не вдалося підтвердити вашу відповідь. Перевірте з’єднання та спробуйте ще раз."+ "Couldn't confirm your answer. Check your connection and retry.": "Не вдалося підтвердити вашу відповідь. Перевірте з’єднання та спробуйте ще раз.",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "Час очікування синтезу мовлення минув. Збільште тайм-аут запиту (секунди) у налаштуваннях мовленнєвої моделі або скоротіть текст.",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "Пошукова кінцева точка повернула некоректну відповідь. Переконайтеся, що ця адреса надає пошуковий JSON API SearXNG.",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG відхилив пошуковий запит JSON. Увімкніть json у search.formats файлу settings.yml і перевірте правила доступу.",+ "Speech playback failed. Check the speech model settings and provider connection.": "Не вдалося відтворити мовлення. Перевірте налаштування мовленнєвої моделі та з’єднання з постачальником.",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 секунд. Залиште порожнім для 60 секунд. Застосовується до попереднього прослуховування та відтворення мовлення.",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "Цей тест виконується з бекенду DeepTutor. У Docker localhost вказує на контейнер DeepTutor. Використовуйте назву служби у спільній мережі та порт контейнера або host.docker.internal і опублікований порт хоста.",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "Пошуковий API доступний, але не повернув результатів. Перевірте увімкнені пошукові системи та їхній доступ до мережі.",+ "Request timeout (seconds)": "Тайм-аут запиту (секунди)",+ "Speech authentication failed. Check the API key and its region.": "Не вдалося автентифікуватися в сервісі мовлення. Перевірте ключ API та його регіон.",+ "Speech access was denied. Check model and voice permissions and the API key region.": "Доступ до сервісу мовлення заборонено. Перевірте дозволи для моделі й голосу та регіон ключа API.",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "Кінцеву точку або модель мовлення не знайдено. Перевірте URL провайдера та ідентифікатор моделі.",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "Параметри мовлення відхилено. Перевірте модель, голос, мову та формат аудіо.",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "Досягнуто квоти або ліміту частоти запитів мовлення. Перевірте баланс і квоту або повторіть спробу пізніше.",+ "The speech provider is temporarily unavailable. Try again later.": "Провайдер мовлення тимчасово недоступний. Повторіть спробу пізніше.",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "Мовлення згенеровано, але завантажити аудіо не вдалося. Повторіть спробу або перевірте мережеве з’єднання.",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "Не вдалося під’єднатися до провайдера мовлення. Перевірте URL провайдера та мережеве з’єднання.",+ "The speech provider returned an invalid response. Check the provider URL.": "Провайдер мовлення повернув некоректну відповідь. Перевірте URL провайдера.",+ "The speech provider returned empty audio. Try another text or voice.": "Провайдер мовлення повернув порожнє аудіо. Спробуйте інший текст або голос.",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "Для синтезу мовлення потрібен URL провайдера з протоколом HTTP або HTTPS.",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "Моделі мовлення реального часу тут не підтримуються. Виберіть модель TTS, що не працює в реальному часі.",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS доступний лише в регіоні Пекін. Використовуйте ключ API та URL провайдера для регіону Пекін.",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "Налаштована кінцева точка мовлення не відповідає цій моделі. Використовуйте базовий URL API провайдера для автоматичного вибору кінцевої точки.",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "Введіть ідентифікатор голосу, який підтримує вибрана модель Qwen-Audio TTS.",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS підтримує аудіоформати MP3, WAV, Opus і PCM.",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "Вибрана частота дискретизації не підтримується для цього аудіоформату Qwen-Audio TTS.",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "Швидкість Qwen-Audio TTS має бути від 0,5 до 2.",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS використовує голоси на кшталт Cherry та створює аудіо WAV. Регіон ключа API має відповідати URL провайдера.",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS потребує ключа API для регіону Пекін. У підключенні провайдера можна задати URL робочого простору для регіону Пекін; кінцева точка мовлення вибирається автоматично.",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "Отримання списку моделей не перевіряє синтез мовлення. Скористайтеся попереднім прослуховуванням голосу, щоб перевірити модель і голос."}diff --git a/web/locales/zh/app.json b/web/locales/zh/app.jsonindex 001f02f07..fd70fc556 100644--- a/web/locales/zh/app.json+++ b/web/locales/zh/app.json@@ -5301,5 +5301,34 @@"Use main LLM (fallback)": "使用主模型(默认)","Failed to load image description models.": "无法加载图片描述模型。","Select a vision model for image descriptions in documents.": "选择用于文档图片描述的视觉模型。",- "Couldn't confirm your answer. Check your connection and retry.": "无法确认你的答案是否已提交。请检查连接后重试。"+ "Couldn't confirm your answer. Check your connection and retry.": "无法确认你的答案是否已提交。请检查连接后重试。",+ "Speech parameters were rejected. Check the model, voice, language and audio format.": "语音参数被拒绝,请检查模型、音色、语言和音频格式是否匹配。",+ "Speech authentication failed. Check the API key and its region.": "语音服务鉴权失败,请检查 API Key 及其所属地域。",+ "Speech quota or rate limit was reached. Check your balance and quota, or retry later.": "语音服务额度不足或触发限流,请检查余额和配额,或稍后重试。",+ "Speech synthesis requires an HTTP or HTTPS provider URL.": "语音合成需要 HTTP 或 HTTPS 提供方 URL。",+ "Fetching the model list does not test speech synthesis. Use Preview voice to test this model and voice.": "获取模型列表不会验证语音合成是否可用。请点击「试听音色」测试当前模型和音色。",+ "Realtime speech models are not supported here. Select a non-realtime TTS model.": "此处暂不支持实时语音模型,请选择非实时 TTS 模型。",+ "Speech access was denied. Check model and voice permissions and the API key region.": "语音服务拒绝访问,请检查模型、音色权限及 API Key 所属地域。",+ "Qwen-Audio TTS speed must be between 0.5 and 2.": "Qwen-Audio TTS 语速须在 0.5 到 2 倍之间。",+ "Speech synthesis timed out. Increase Request timeout (seconds) in the speech model settings or try shorter text.": "语音合成超时。请在语音模型设置中增大「请求超时(秒)」,或缩短文本。",+ "The search endpoint returned an invalid response. Check that the address serves the SearXNG JSON search API.": "搜索接口返回了无效响应。请确认该地址提供 SearXNG 的 JSON 搜索 API。",+ "SearXNG rejected the JSON search request. Enable json in search.formats in its settings.yml and check access rules.": "SearXNG 拒绝了 JSON 搜索请求。请在其 settings.yml 的 search.formats 中启用 json,并检查访问规则。",+ "Speech playback failed. Check the speech model settings and provider connection.": "语音播放失败。请检查语音模型设置和提供方连接。",+ "5–600 seconds. Leave blank for 60 seconds. Applies to voice previews and speech playback.": "5–600 秒,留空默认 60 秒。适用于音色试听和正文朗读。",+ "Speech endpoint or model was not found. Check the provider URL and model ID.": "未找到语音接口或模型,请检查提供方 URL 和模型 ID。",+ "Qwen3 TTS uses voices such as Cherry and outputs WAV audio. Match the API key region to the provider URL.": "Qwen3 TTS 使用 Cherry 等音色,输出 WAV 音频。API Key 所属地域须与提供方 URL 一致。",+ "Qwen-Audio TTS supports MP3, WAV, Opus and PCM audio formats.": "Qwen-Audio TTS 支持 MP3、WAV、Opus 和 PCM 音频格式。",+ "Enter a voice ID supported by the selected Qwen-Audio TTS model.": "请填写所选 Qwen-Audio TTS 模型支持的音色 ID。",+ "The speech provider is temporarily unavailable. Try again later.": "语音服务暂时不可用,请稍后重试。",+ "The configured speech endpoint does not match this model. Use the provider API base URL to select the endpoint automatically.": "当前语音端点与模型不匹配,请填写提供方 API 基地址,由系统自动选择合成端点。",+ "Qwen-Audio TTS is available only in Beijing. Use a Beijing API key and provider URL.": "Qwen-Audio TTS 非实时合成仅支持北京地域,请使用北京地域的 API Key 和提供方 URL。",+ "The speech provider returned empty audio. Try another text or voice.": "语音服务返回了空音频,请尝试其他文本或音色。",+ "The selected sample rate is not supported for this Qwen-Audio TTS audio format.": "所选采样率不适用于当前 Qwen-Audio TTS 音频格式,请改选推荐采样率。",+ "This test runs from the DeepTutor backend. In Docker, localhost points to the DeepTutor container. Use a shared-network service name and container port, or host.docker.internal and the published host port.": "测试请求由 DeepTutor 后端发出。在 Docker 中,localhost 指向 DeepTutor 容器自身。请使用同一网络内的服务名和容器端口,或 host.docker.internal 和宿主机映射端口。",+ "The speech provider returned an invalid response. Check the provider URL.": "语音服务返回了无效响应,请检查提供方 URL 是否正确。",+ "The search API is reachable but returned no results. Check the enabled engines and their network access.": "搜索 API 可以访问,但未返回结果。请检查已启用的搜索引擎及其网络连接。",+ "Could not connect to the speech provider. Check the provider URL and network connection.": "无法连接语音服务,请检查提供方 URL 和网络连接。",+ "Qwen-Audio TTS requires a Beijing API key. You can set a Beijing workspace URL in the provider connection; the speech endpoint is selected automatically.": "Qwen-Audio TTS 需要北京地域的 API Key。可在提供方连接中填写北京业务空间 URL,系统会自动选择合成端点。",+ "Speech was generated, but the audio download failed. Try again or check the network connection.": "语音已生成,但音频下载失败,请重试或检查网络连接。",+ "Request timeout (seconds)": "请求超时(秒)"}diff --git a/web/tests/chat-read-aloud-playback.spec.tsx b/web/tests/chat-read-aloud-playback.spec.tsxindex 576ed20cc..33d22e650 100644--- a/web/tests/chat-read-aloud-playback.spec.tsx+++ b/web/tests/chat-read-aloud-playback.spec.tsx@@ -3,6 +3,7 @@ import userEvent from "@testing-library/user-event";import { afterEach, expect, it, vi } from "vitest";import { PlayAudioButton } from "@/features/chat/messages/ChatMessageList";import { apiFetch } from "@/lib/api";+import { notify } from "@/lib/notifications";import { initI18n } from "@/i18n/init";vi.mock("@/lib/api", async (original) => ({@@ -12,6 +13,7 @@ vi.mock("@/lib/api", async (original) => ({vi.mock("@/hooks/useVoiceAutoplay", () => ({useVoiceAutoplay: () => ({ autoplayEnabled: false }),}));+vi.mock("@/lib/notifications", () => ({ notify: vi.fn() }));initI18n("en");const instances: FakeAudio[] = [];class FakeAudio {@@ -55,3 +57,20 @@ it("does not play a late response body after leaving the chat", async () => {expect(instances).toHaveLength(0);expect(URL.createObjectURL).not.toHaveBeenCalled();});++it("does not show a late speech error after playback is cancelled", async () => {+ let resolve!: (body: { detail: string }) => void;+ const body = new Promise<{ detail: string }>((yes) => { resolve = yes; });+ vi.mocked(apiFetch).mockResolvedValueOnce({+ ok: false,+ status: 504,+ json: () => body,+ } as Response);+ render(<PlayAudioButton content="First" autoPlayFresh={false} />);+ const user = userEvent.setup();+ const button = screen.getByRole("button", { name: "Play aloud" });+ await user.click(button);+ await user.click(button);+ await act(async () => { resolve({ detail: "Speech synthesis timed out." }); });+ expect(notify).not.toHaveBeenCalled();+});diff --git a/web/tests/provider-registry-workflow.spec.tsx b/web/tests/provider-registry-workflow.spec.tsxindex 8daa76ff6..390ddfd0d 100644--- a/web/tests/provider-registry-workflow.spec.tsx+++ b/web/tests/provider-registry-workflow.spec.tsx@@ -17,6 +17,7 @@ import { RegistryProbe } from "@/components/settings/RegistryControls";import {flattenModels,providerRegistry,+ providerProbeInput,reconcileRegistrySave,} from "@/lib/provider-registry";import { modelTestFingerprint } from "@/lib/model-settings";@@ -373,6 +374,37 @@ it("discards an in-flight discovery after switching provider credentials", async});+it("sends the search proxy and explains JSON rejection from a Docker loopback address", async () => {+ const catalog = fixture();+ catalog.services.search.profiles = [{+ id: "search", name: "Local search", provider: "searxng",+ base_url: "http://localhost:8888", api_key: "", api_version: "",+ proxy: "http://proxy:3128", models: [],+ }];+ const source = providerRegistry(catalog).find(item => item.provider === "searxng")!;+ mocks.fetch.mockResolvedValue({+ ok: true,+ json: async () => ({ status: "json_forbidden", models: [], http_status: 403 }),+ });+ render(<RegistryProbe input={providerProbeInput(source)} onResult={() => {}} />);+ fireEvent.click(screen.getByRole("button", { name: "Test provider" }));+ await waitFor(() => expect(screen.getByRole("status").textContent).toContain("search.formats"));+ expect(screen.getByRole("status").textContent).toContain("HTTP 403");+ expect(screen.getByRole("status").textContent).toContain("DeepTutor container");+ expect(JSON.parse(mocks.fetch.mock.calls[0][1].body).proxy).toBe("http://proxy:3128");+});++it("shows an empty search result as a reachable API with an engine warning", () => {+ render(<RegistryProbe+ input={{ service: "search", binding: "searxng", base_url: "http://localhost:8888" }}+ discovery={{ status: "connected", models: [], warning: "empty_results" }}+ onResult={() => {}}+ />);+ expect(screen.getByRole("status").textContent).toContain("Provider connected");+ expect(screen.getByRole("status").textContent).toContain("enabled engines");+ expect(screen.getByRole("status").textContent).not.toContain("DeepTutor container");+});+it.each([["voice", ["tts", "stt"], ["imagegen", "videogen"], "Text-to-Speech", "Speech-to-Text"],["multimodal", ["imagegen", "videogen"], ["tts", "stt"], "Image Generation", "Video Generation"],diff --git a/web/tests/reading-outline-tracking.spec.tsx b/web/tests/reading-outline-tracking.spec.tsxindex 0b053bac1..7acad8755 100644--- a/web/tests/reading-outline-tracking.spec.tsx+++ b/web/tests/reading-outline-tracking.spec.tsx@@ -58,10 +58,15 @@ vi.mock("@/components/reading/TextUnitView", () => ({vi.mock("@/components/reading/EpubDocumentView", () => ({EpubDocumentView: ({onVisibleLocatorChange,+ onProgressChange,}: {onVisibleLocatorChange?: (locator: number) => void;+ onProgressChange?: (percentage: number | null) => void;}) => (- <button type="button" onClick={() => onVisibleLocatorChange?.(5)}>+ <button type="button" onClick={() => {+ onVisibleLocatorChange?.(5);+ onProgressChange?.(0.37);+ }}>turn epub to chapter 5</button>),@@ -87,7 +92,7 @@ describe("the reading outline", () => {fireEvent.click(await screen.findByText("turn epub to chapter 5"));expect(screen.getByText("Second chapter")).toBeInTheDocument();- expect(screen.getByText(/21%/)).toBeInTheDocument();+ expect(screen.getByText(/37%/)).toBeInTheDocument();expect(screen.queryByText("chapter 5 / 20")).not.toBeInTheDocument();});});diff --git a/web/tests/voice-settings.spec.tsx b/web/tests/voice-settings.spec.tsxindex 75008248f..f95b175d4 100644--- a/web/tests/voice-settings.spec.tsx+++ b/web/tests/voice-settings.spec.tsx@@ -1,14 +1,16 @@import React, { useState } from 'react'-import { fireEvent, render, screen, waitFor } from '@testing-library/react'+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'import { beforeEach, expect, it, vi } from 'vitest'import { VoicePreviewPanel } from '@/components/settings/VoicePreviewPanel'import { VoiceModelFields } from '@/components/settings/VoiceModelFields'import { ModelsWorkspace } from '@/components/settings/ModelsWorkspace'+import { PlayAudioButton } from '@/features/chat/messages/ChatMessageList'import { voiceModelOptions } from '@/lib/voice-settings'import type { SettingsContextValue } from '@/features/settings/store/SettingsStore'import type { Catalog, VoiceOptions } from '@/lib/model-catalog-types'-const mock = vi.hoisted(() => ({ settings: {} as SettingsContextValue, fetch: vi.fn() }))+const mock = vi.hoisted(() => ({ settings: {} as SettingsContextValue, fetch: vi.fn(), notify: vi.fn() }))+vi.mock('@/lib/notifications', () => ({ notify: mock.notify }))vi.mock('@/features/settings/store/SettingsStore', () => ({ useSettings: () => mock.settings }))vi.mock('@/lib/api', () => ({apiUrl: (url: string) => url,@@ -17,6 +19,14 @@ vi.mock('@/lib/api', () => ({vi.mock('react-i18next', () => ({useTranslation: () => ({ t: (s: string) => s, i18n: { language: 'en' } }),}))+vi.mock('@/hooks/useVoiceAutoplay', () => ({+ useVoiceAutoplay: () => ({+ autoplayEnabled: false,+ enableForSession: vi.fn(),+ markPrompted: vi.fn(),+ shouldPromptOnFirstPlay: () => true,+ }),+}))const options: VoiceOptions = {models: [{@@ -75,8 +85,12 @@ function fixture(): Catalog {}return { version: 1, services, connections: [] }}-function Harness({ workspace = false }: { workspace?: boolean }) {- const [draft, setDraft] = useState(fixture)+function Harness({ workspace = false, timeout }: { workspace?: boolean; timeout?: string }) {+ const [draft, setDraft] = useState(() => {+ const catalog = fixture()+ if (timeout) catalog.services.tts.profiles[0].models[1].request_timeout = timeout+ return catalog+ })// eslint-disable-next-line react-hooks/immutabilitymock.settings = {draft,@@ -114,6 +128,7 @@ function Harness({ workspace = false }: { workspace?: boolean }) {}beforeEach(() => {mock.fetch.mockReset()+ mock.notify.mockReset()vi.stubGlobal('matchMedia', () => ({ matches: false }))URL.createObjectURL = vi.fn(() => 'blob:preview')URL.revokeObjectURL = vi.fn()@@ -145,6 +160,37 @@ it('shows provider-specific voices, speed and language choices and accepts privatarget: { value: 'private-speaker' },})expect(update).toHaveBeenCalledWith('voice', 'private-speaker')+ fireEvent.change(screen.getByRole('spinbutton', { name: 'Request timeout (seconds)' }), {+ target: { value: '180' },+ })+ expect(update).toHaveBeenCalledWith('request_timeout', '180')+})++it('shows the Qwen-Audio voice, regional guidance and documentation for the selected model', () => {+ const preset = {+ id: 'qwen-audio-3.0-tts-plus',+ label: 'Qwen Audio Plus',+ voices: [{ id: 'longanlingxin', label: '龙安灵心 · longanlingxin', languages: ['zh', 'en'] }],+ languages: [{ id: 'zh', label: 'Chinese' }, { id: 'en', label: 'English' }],+ formats: ['mp3', 'wav', 'opus', 'pcm'],+ configuration_note: 'Qwen-Audio TTS requires a Beijing API key.',+ docs_url: 'https://help.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list',+ }+ render(+ <VoiceModelFields+ service="tts"+ provider="dashscope"+ model={{ id: 'plus', name: 'Plus', model: preset.id, voice: 'longanlingxin' }}+ options={{ ...options, models: [preset] }}+ preset={preset}+ update={vi.fn()}+ disabled={false}+ />+ )+ expect(screen.getByRole('combobox', { name: 'Suggested voice' })).toHaveValue('longanlingxin')+ expect(screen.getByText(preset.configuration_note)).toBeTruthy()+ expect(screen.getByRole('link', { name: 'Provider voice documentation' })).toHaveAttribute('href', preset.docs_url)+ expect(screen.getByText(/Fetching the model list does not test speech synthesis/)).toBeTruthy()})it('switching model updates an incompatible preset voice and clears unsupported instructions', async () => {@@ -207,3 +253,34 @@ it('reports failures and allows retry without applying settings', async () => {await waitFor(() => expect(screen.getByRole('alert').textContent).toBe('Check the Speech key'))expect(screen.getByRole('button', { name: 'Preview voice' }).hasAttribute('disabled')).toBe(false)})++it('lets a slow preview use the configured timeout and cancels at that deadline', async () => {+ vi.useFakeTimers()+ try {+ mock.fetch.mockImplementation((_url, options) => new Promise((_resolve, reject) => {+ options.signal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')))+ }))+ render(<Harness timeout="180" />)+ fireEvent.click(screen.getByRole('button', { name: 'Preview voice' }))+ const signal = mock.fetch.mock.calls[0][1].signal+ await act(async () => { await vi.advanceTimersByTimeAsync(65000) })+ expect(signal.aborted).toBe(false)+ await act(async () => { await vi.advanceTimersByTimeAsync(120000) })+ expect(signal.aborted).toBe(true)+ expect(screen.getByRole('alert').textContent).toContain('Request timeout (seconds)')+ } finally {+ vi.useRealTimers()+ }+})++it('shows a playback timeout instead of silently returning to idle', async () => {+ mock.fetch.mockResolvedValue({ ok: false, status: 504 })+ render(<PlayAudioButton content="Hello" autoPlayFresh={false} />)+ fireEvent.click(screen.getByRole('button', { name: 'Play aloud' }))+ await waitFor(() => expect(mock.notify).toHaveBeenCalledWith(+ expect.stringContaining('Request timeout (seconds)'),+ { tone: 'error' }+ ))+ expect(screen.queryByText('Auto-play replies in this conversation?')).toBeNull()+ expect(screen.getByRole('button', { name: 'Play aloud' }).hasAttribute('disabled')).toBe(false)+})