DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
docs: consolidate developer and agent handbook
Bingxi Zhao (Frank)1ea7df155447
diff --git a/.dockerignore b/.dockerignoreindex dcc732fbc..7825564fc 100644--- a/.dockerignore+++ b/.dockerignore@@ -18,6 +18,7 @@*.md!README.mddocs/+docs-for-dev/assets/gifs/assets/figs/assets/README/diff --git a/.gitignore b/.gitignoreindex 7a3b087c0..9ad4d87e6 100644--- a/.gitignore+++ b/.gitignore@@ -8,8 +8,11 @@# Runtime data (knowledge bases, partner workspaces, memory, etc.)data//multi-user/-# Local development documents; public guides live in docs-for-user/.+# Developer and agent documentation is tracked in docs-for-dev/.+# Keep obsolete local notes and downloaded references out of the repository./docs/+/docs-for-use/+/docs-for-user//design-qa.md# Local development screenshots, acceptance snapshots, and task reports./artifacts/diff --git a/AGENTS.md b/AGENTS.mdindex c542d4b78..829994a78 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -81,7 +81,7 @@ Multi-stage pipelines that own the turn:| `video_lesson` | code_generation → render_check → render_output (Remotion lesson played live in the browser, with TTS narration) |All capabilities converge on `emit_capability_result()` in-`deeptutor/capabilities/_shared.py` so every turn emits the same envelope+`deeptutor/agents/_shared/capability_result.py` so every turn emits the same envelope(response payload + `cost_summary` from `UsageTracker`). Status copy andprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.@@ -122,7 +122,7 @@ to inspect installed/enabled/ready states and `deeptutor plugin list` to discoveregistered capabilities and tools. Source Web startup also needs Node.js 22 LTSand `npm ci --legacy-peer-deps` in `web/`. CLI-only source users can skip frontendsetup, but still need the full Python dependencies. Follow-[Agent Setup](docs-for-user/AGENT_SETUP.md) for credentials and verification.+[Agent Setup](docs-for-dev/AGENT_SETUP.md) for credentials and verification.## Key Files@@ -140,7 +140,7 @@ setup, but still need the full Python dependencies. Follow| `deeptutor/core/context.py` | `UnifiedContext` dataclass || `deeptutor/tools/builtin/__init__.py` | All built-in tool wrappers || `deeptutor/capabilities/` | Built-in capability implementations |-| `deeptutor/app.py` | `DeepTutorApp` — Python SDK facade |+| `deeptutor/app/` | `DeepTutorApp` SDK facade + durable application service || `deeptutor_cli/main.py` | Typer CLI entry point || `deeptutor/api/routers/unified_ws.py` | Unified WebSocket endpoint |diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a93d032bb..e6ac16992 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -12,7 +12,7 @@ Thank you for your interest in contributing to DeepTutor! We welcome developers## Table of Contents-- [Maintainers](#maintainers)+- [Maintainer](#maintainer)- [Branching Strategy](#branching-strategy)- [Quick Start for Contributors](#quick-start-for-contributors)- [Development Setup](#development-setup)@@ -92,6 +92,11 @@ pre-commit run --all-files## Development Setup+Start with the [developer and agent handbook](docs-for-dev/README.md).+[Agent setup](docs-for-dev/AGENT_SETUP.md) owns installation and configuration;+[Development](docs-for-dev/DEVELOPMENT.md) and [Testing](docs-for-dev/TESTING.md)+describe the source workflow and verification gates.+<details><summary><b>Setting Up Your Environment</b></summary>@@ -105,7 +110,12 @@ source venv/bin/activate # On Windows: venv\Scripts\activate**Step 2: Install dependencies**```bash-pip install -e ".[all]"+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps+python scripts/install_extras.py dev+cd web+npm ci --legacy-peer-deps+cd ..```</details>diff --git a/README.md b/README.mdindex 00c61f4f1..aa5ccfc3c 100644--- a/README.md+++ b/README.md@@ -259,17 +259,18 @@ Copy this prompt into your terminal-capable AI agent (such as Codex or Claude Co```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.-Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+Clone the dev branch, or inspect and reuse my existing checkout. Start at+docs-for-dev/README.md, then read docs-for-dev/AGENT_SETUP.md and SKILL.md.+Follow the setup guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-The [Agent Setup guide](docs-for-user/AGENT_SETUP.md) covers the full flow, including non-interactive CLI configuration. To install it yourself, choose one of the paths below.+The [developer and agent handbook](docs-for-dev/README.md) is the documentation entry point for setup, architecture, extension development, testing, and troubleshooting. Its [Agent Setup guide](docs-for-dev/AGENT_SETUP.md) covers the full installation flow, including non-interactive CLI configuration. To install it yourself, choose one of the paths below.-DeepTutor ships four installation paths. They all share one runtime-home layout: private settings live in `data/user/settings/` under the directory you launch from (or under `DEEPTUTOR_HOME` / `deeptutor start --home` if you set one explicitly). See [Local Data Persistence](./docs-for-user/DATA_STORAGE.md) for the complete storage layout, database support, and backup notes. For the full app, the recommended flow is **pick a runtime-home directory → install → `deeptutor init` → `deeptutor start`**.+DeepTutor ships four installation paths. They all share one runtime-home layout: private settings live in `data/user/settings/` under the directory you launch from (or under `DEEPTUTOR_HOME` / `deeptutor start --home` if you set one explicitly). See [Local Data Persistence](./docs-for-dev/DATA_STORAGE.md) for the complete storage layout, database support, and backup notes. For the full app, the recommended flow is **pick a runtime-home directory → install → `deeptutor init` → `deeptutor start`**.### One-Command Docker Trial@@ -314,7 +315,7 @@ Skills, MCP services and knowledge bases to each workspace, or retain itsexisting access rules. Existing workspaces keep their current access until aselection is saved. Assignments reference the original resources without copyingcredentials or knowledge indexes; workspace-specific skills can override shared-versions. See [workspace resource assignments](docs-for-user/workspaces.md).+versions. See [workspace resource assignments](docs-for-dev/workspaces.md).Execution is read-only outside `outputs/`. Copying a generated file elsewherein the content workspace requires an explicit **Allow once** confirmation for@@ -423,7 +424,7 @@ One container for the full Web app. Images on GitHub Container Registry:- `ghcr.io/hkuds/deeptutor:latest` — latest stable release- `ghcr.io/hkuds/deeptutor:<version>` — exact release without the leading `v` (for example `:1.6.3`); pre-releases receive only their version tag-> See [CONTAINERIZATION.md](./docs-for-user/CONTAINERIZATION.md) for podman/rootless/read-only-rootfs deployments and the full per-installation guide.+> See [CONTAINERIZATION.md](./docs-for-dev/CONTAINERIZATION.md) for podman/rootless/read-only-rootfs deployments and the full per-installation guide.```bashdocker run --rm --name deeptutor \@@ -507,7 +508,7 @@ Then in **Settings → Providers**, point the provider Base URL at `host.docker.Docker Desktop (macOS/Windows) usually resolves `host.docker.internal` without `--add-host`. On Linux, the flag is the portable way to create that hostname on modern Docker Engine.-**Linux alternative — host networking:** add `--network=host` and drop the `-p` flags. The container shares the host network directly, so open [http://127.0.0.1:3782](http://127.0.0.1:3782) (or the `frontend_port` in `system.json`), and host services can be reached with normal localhost URLs like `http://127.0.0.1:11434/v1`. Note that host networking exposes container ports directly on the host and may conflict with existing services — to keep them on loopback, set `BACKEND_HOST=127.0.0.1` and `FRONTEND_HOST=127.0.0.1` (see [CONTAINERIZATION.md](./docs-for-user/CONTAINERIZATION.md)).+**Linux alternative — host networking:** add `--network=host` and drop the `-p` flags. The container shares the host network directly, so open [http://127.0.0.1:3782](http://127.0.0.1:3782) (or the `frontend_port` in `system.json`), and host services can be reached with normal localhost URLs like `http://127.0.0.1:11434/v1`. Note that host networking exposes container ports directly on the host and may conflict with existing services — to keep them on loopback, set `BACKEND_HOST=127.0.0.1` and `FRONTEND_HOST=127.0.0.1` (see [CONTAINERIZATION.md](./docs-for-dev/CONTAINERIZATION.md)).</details>@@ -680,7 +681,7 @@ uninstalling DeepTutor.Start with a **workspace** for a subject or project. Its **Home**, **Learning**, and **Resources** hold your conversations, learning activities, and materials. **Partners** and **Personalization** stay with your account across workspaces. The tour below shows how these surfaces connect, followed by settings and multi-user deployment.-If an answer loses an earlier constraint, cites weak evidence, or disagrees with selected material, collect the diagnostics in [`REASONING_SAFETY_CHECKLIST.md`](./docs-for-user/REASONING_SAFETY_CHECKLIST.md) before opening an issue.+If an answer loses an earlier constraint, cites weak evidence, or disagrees with selected material, collect the diagnostics in [`REASONING_SAFETY_CHECKLIST.md`](./docs-for-dev/REASONING_SAFETY_CHECKLIST.md) before opening an issue.<div align="center"><img src="assets/figs/web-dev/overview.png" alt="DeepTutor Home and workspace navigation" width="900">@@ -837,7 +838,7 @@ Knowledge bases are the document collections behind RAG — they ground Chat tur<img src="assets/figs/web-dev/knowledge-create.png" alt="Create a knowledge base" width="900"></div>-Migrating an existing Obsidian, Hermes, or Markdown library? See [Knowledge migration guide](./docs-for-user/KNOWLEDGE_MIGRATION.md) for connected-vault and indexed-copy paths.+Migrating an existing Obsidian, Hermes, or Markdown library? See [Knowledge migration guide](./docs-for-dev/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 — 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/eval-diff/set-default/delete`, source add/remove commands, `list-sources`, and `sync`.@@ -915,7 +916,7 @@ On sign-in and **Refresh models**, DeepTutor reads the latest stable `@openai/coSuccessful version history survives same-account token renewal and catalog authentication errors, without making invalidated model data or ETags usable again. Signing out clears that account's local cache, including the version history. Ordinary status reads and inference do not query npm. New catalog entries do not replace a model you already selected or restart learning sessions; appearing in the catalog does not establish full inference-protocol compatibility. There is no background version updater or user version setting.-Default local Docker and Podman deployments use separate loopback networks and need a temporary bridge during sign-in. Follow the [temporary local Codex OAuth bridge guide](./docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) for the exact Docker, Compose, Podman, and teardown commands.+Default local Docker and Podman deployments use separate loopback networks and need a temporary bridge during sign-in. Follow the [temporary local Codex OAuth bridge guide](./docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) for the exact Docker, Compose, Podman, and teardown commands.For a remote deployment, the browser's `localhost` and the server's `localhost` are different machines, so an ordinary reverse proxy alone cannot carry the browser's localhost callback to the server. Use an SSH tunnel as the callback bridge. The tunnel reaches the already-published Web port; Next.js rewrites only the exact callback path to the public callback broker, and the broker validates `state` before routing to the original OAuth operation. The callback listener remains on the backend loopback, ports `1455` and `1457` are not published, and this path supports the default Docker bridge network.@@ -999,7 +1000,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-The repo ships a root [`SKILL.md`](SKILL.md) — a compact handover doc for the CLI. Ask your agent to read it explicitly; its [Agent Setup guide](docs-for-user/AGENT_SETUP.md) covers installation and configuration. You can also wrap `deeptutor run` as a tool in a LangChain / AutoGen loop. Full recipes: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+The repo ships a root [`SKILL.md`](SKILL.md) — a compact handover doc for the CLI. Ask your agent to read it explicitly; its [Agent Setup guide](docs-for-dev/AGENT_SETUP.md) covers installation and configuration. You can also wrap `deeptutor run` as a tool in a LangChain / AutoGen loop. Full recipes: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/SKILL.md b/SKILL.mdindex 3f89be211..51ee9fe1f 100644--- a/SKILL.md+++ b/SKILL.md@@ -28,10 +28,12 @@ Use this skill when the user wants to:## Agent Setup+Start with the [developer and agent handbook](docs-for-dev/README.md) to find+the relevant setup, architecture, development, testing, or feature guide.When the user asks you to install, configure, or troubleshoot DeepTutor, follow-[docs-for-user/AGENT_SETUP.md](docs-for-user/AGENT_SETUP.md). It covers cloning,+[docs-for-dev/AGENT_SETUP.md](docs-for-dev/AGENT_SETUP.md). It covers cloning,environment preparation, credential sources, optional RAG/search, startup,-and verification, plus a [troubleshooting approach](docs-for-user/AGENT_SETUP.md#6-troubleshooting)+and verification, plus a [troubleshooting approach](docs-for-dev/AGENT_SETUP.md#6-troubleshooting)for existing installations. Read it before changing settings; reuse existing checkoutsand preserve the user's files. Keep `DEEPTUTOR_HOME` consistent for all commands.diff --git a/assets/README/README_AR.md b/assets/README/README_AR.mdindex cbddb42d0..bd4aa554e 100644--- a/assets/README/README_AR.md+++ b/assets/README/README_AR.md@@ -79,16 +79,16 @@ DeepTutor هو بيئة تعلم أصيلة للوكلاء تربط التدري```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-يغطي [دليل إعداد الوكيل](../../docs-for-user/AGENT_SETUP.md) التدفق كاملاً، بما فيه التهيئة غير التفاعلية عبر CLI. لتثبيته بنفسك، اختر أحد المسارات أدناه.+يغطي [دليل إعداد الوكيل](../../docs-for-dev/AGENT_SETUP.md) التدفق كاملاً، بما فيه التهيئة غير التفاعلية عبر CLI. لتثبيته بنفسك، اختر أحد المسارات أدناه.-يأتي DeepTutor بأربعة مسارات تثبيت. وكلها تشترك في تخطيط واحد لمساحة عمل وقت التشغيل: تعيش الإعدادات الخاصة في `data/user/settings/` تحت الدليل الذي تُطلق منه التطبيق (أو تحت `DEEPTUTOR_HOME` / `deeptutor start --home` إذا حددت واحداً صراحةً). راجع [حفظ البيانات المحلية](../../docs-for-user/DATA_STORAGE.md) للاطلاع على تخطيط التخزين الكامل ودعم قواعد البيانات وملاحظات النسخ الاحتياطي. للتطبيق الكامل، التدفق الموصى به هو **اختر دليل مساحة عمل وقت التشغيل → تثبيت → `deeptutor init` → `deeptutor start`**.+يأتي DeepTutor بأربعة مسارات تثبيت. وكلها تشترك في تخطيط واحد لمساحة عمل وقت التشغيل: تعيش الإعدادات الخاصة في `data/user/settings/` تحت الدليل الذي تُطلق منه التطبيق (أو تحت `DEEPTUTOR_HOME` / `deeptutor start --home` إذا حددت واحداً صراحةً). راجع [حفظ البيانات المحلية](../../docs-for-dev/DATA_STORAGE.md) للاطلاع على تخطيط التخزين الكامل ودعم قواعد البيانات وملاحظات النسخ الاحتياطي. للتطبيق الكامل، التدفق الموصى به هو **اختر دليل مساحة عمل وقت التشغيل → تثبيت → `deeptutor init` → `deeptutor start`**.### تجربة Docker بأمر واحد@@ -117,7 +117,7 @@ deeptutor workspace resetتفحص القدرات مساحة العمل المحددة لها من خلال أدوات مساحة العمل المدمجة. لا يتلقى النموذج سوى مسارات نسبية مثل `outputs/...`؛ وعندما يستخدم `workspace_present`، تُصيِّر الواجهة لقطة مصادَق عليها وقابلة للفتح. يعمل المسار النسبي الدقيق نفسه أيضاً في رابط أو صورة Markdown عادية. تغيير الملف المصدر لاحقاً لا يغيّر لقطة قُدِّمت مسبقاً.-يدير فضاء التعلم مكتبة الموارد. في **الإعدادات ← مساحات العمل**، عيّن المهارات وخدمات MCP وقواعد المعرفة لكل مساحة عمل، أو احتفظ بقواعد الوصول الحالية. تحتفظ مساحات العمل الموجودة بصلاحيات وصولها الحالية حتى يُحفظ الاختيار. تشير التعيينات إلى الموارد الأصلية دون نسخ بيانات الاعتماد أو فهارس المعرفة؛ ويمكن للمهارات الخاصة بمساحة عمل أن تتجاوز النسخ المشتركة. راجع [تعيين موارد مساحات العمل](../../docs-for-user/workspaces.md).+يدير فضاء التعلم مكتبة الموارد. في **الإعدادات ← مساحات العمل**، عيّن المهارات وخدمات MCP وقواعد المعرفة لكل مساحة عمل، أو احتفظ بقواعد الوصول الحالية. تحتفظ مساحات العمل الموجودة بصلاحيات وصولها الحالية حتى يُحفظ الاختيار. تشير التعيينات إلى الموارد الأصلية دون نسخ بيانات الاعتماد أو فهارس المعرفة؛ ويمكن للمهارات الخاصة بمساحة عمل أن تتجاوز النسخ المشتركة. راجع [تعيين موارد مساحات العمل](../../docs-for-dev/workspaces.md).التنفيذ للقراءة فقط خارج `outputs/`. نسخ ملف مُولَّد إلى مكان آخر في مساحة عمل المحتوى يتطلب تأكيد **السماح مرة واحدة** الصريح لذلك المصدر والوجهة المحددين تماماً. يفرض صندوق أمان النظام أو مُشغِّل Docker هذا الحد عند توفره؛ ويظهر الرجوع إلى العملية الفرعية المقيَّدة محلياً كـ **أفضل جهد ممكن** في إعدادات مساحة العمل.@@ -222,7 +222,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — أحدث إصدار مستقر- `ghcr.io/hkuds/deeptutor:<version>` — الإصدار المحدد بدقة من دون `v` في البداية (مثلاً `:1.6.3`)؛ لا تحصل الإصدارات الأولية إلا على وسم إصدارها-> راجع [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) لعمليات نشر podman/rootless/read-only-rootfs والدليل الكامل لكل تثبيت.+> راجع [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) لعمليات نشر podman/rootless/read-only-rootfs والدليل الكامل لكل تثبيت.```bashdocker run --rm --name deeptutor \@@ -292,7 +292,7 @@ docker run --rm --name deeptutor \عادةً ما يحل Docker Desktop (macOS/Windows) `host.docker.internal` بدون `--add-host`. على Linux، يُعدّ هذا العلم الطريقة المحمولة لإنشاء هذا الاسم المضيف على Docker Engine الحديث.-**بديل Linux — شبكة المضيف:** أضف `--network=host` وأزل علامات `-p`. تشارك الحاوية شبكة المضيف مباشرةً، لذا افتح [http://127.0.0.1:3782](http://127.0.0.1:3782) (أو `frontend_port` في `system.json`)، ويمكن الوصول إلى خدمات المضيف بعناوين URL العادية لـ localhost مثل `http://127.0.0.1:11434/v1`. لاحظ أن شبكة المضيف تكشف منافذ الحاوية مباشرةً على المضيف وقد تتعارض مع الخدمات الموجودة — للإبقاء عليها على loopback، اضبط `BACKEND_HOST=127.0.0.1` و`FRONTEND_HOST=127.0.0.1` (راجع [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**بديل Linux — شبكة المضيف:** أضف `--network=host` وأزل علامات `-p`. تشارك الحاوية شبكة المضيف مباشرةً، لذا افتح [http://127.0.0.1:3782](http://127.0.0.1:3782) (أو `frontend_port` في `system.json`)، ويمكن الوصول إلى خدمات المضيف بعناوين URL العادية لـ localhost مثل `http://127.0.0.1:11434/v1`. لاحظ أن شبكة المضيف تكشف منافذ الحاوية مباشرةً على المضيف وقد تتعارض مع الخدمات الموجودة — للإبقاء عليها على loopback، اضبط `BACKEND_HOST=127.0.0.1` و`FRONTEND_HOST=127.0.0.1` (راجع [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -425,7 +425,7 @@ deeptutor config showابدأ **بمساحة عمل** لمادة دراسية أو مشروع. تضم **الصفحة الرئيسية** و**التعلّم** و**الموارد** محادثاتك وأنشطتك التعليمية وموادك. ويبقى **الشركاء** و**التخصيص** مرتبطين بحسابك عبر مساحات العمل. تبيّن الجولة أدناه كيفية اتصال هذه الواجهات، ثم تتناول الإعدادات والنشر متعدد المستخدمين.-إذا فقدت إجابة قيداً سابقاً، أو استشهدت بدليل ضعيف، أو خالفت المادة المحددة، فاجمع بيانات التشخيص في [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) قبل فتح مشكلة.+إذا فقدت إجابة قيداً سابقاً، أو استشهدت بدليل ضعيف، أو خالفت المادة المحددة، فاجمع بيانات التشخيص في [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) قبل فتح مشكلة.<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="الصفحة الرئيسية والتنقل بين مساحات العمل في DeepTutor" width="900">@@ -563,7 +563,7 @@ Chat هي القدرة الافتراضية والمكان الذي يبدأ ف<img src="../../assets/figs/web-dev/knowledge-create.png" alt="إنشاء قاعدة معرفة" width="900"></div>-هل تنقل مكتبة Obsidian أو Hermes أو Markdown موجودة؟ راجع [دليل نقل المعرفة](../../docs-for-user/KNOWLEDGE_MIGRATION.md) لمساري المخزن المتصل والنسخة المفهرسة.+هل تنقل مكتبة Obsidian أو Hermes أو Markdown موجودة؟ راجع [دليل نقل المعرفة](../../docs-for-dev/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/eval/eval-diff/set-default/delete`، وأوامر إضافة المصادر وإزالتها، و`list-sources`، و`sync`.@@ -641,7 +641,7 @@ Chat هي القدرة الافتراضية والمكان الذي يبدأ فيبقى سجل الإصدارات الناجحة قائماً عبر تجديد الرمز لنفس الحساب وأخطاء مصادقة الكتالوج، دون أن يعيد ذلك صلاحية بيانات نماذج أو ETags أُلغيت صلاحيتها. يمسح تسجيل الخروج الذاكرة المؤقتة المحلية لذلك الحساب، بما يشمل سجل الإصدارات. لا تستعلم قراءات الحالة العادية والاستدلال npm. لا تستبدل إدخالات الكتالوج الجديدة نموذجاً اخترته مسبقاً ولا تُعيد تشغيل جلسات التعلّم؛ وظهور نموذج في الكتالوج لا يثبت توافقاً كاملاً مع بروتوكول الاستدلال. لا يوجد مُحدِّث إصدار في الخلفية ولا إعداد إصدار يتحكم فيه المستخدم.-تستخدم عمليات نشر Docker وPodman المحلية الافتراضية شبكات loopback منفصلة وتحتاج إلى جسر مؤقت أثناء تسجيل الدخول. اتبع [دليل جسر OAuth المؤقت المحلي لـ Codex](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) للاطلاع على أوامر Docker وCompose وPodman والإزالة الدقيقة.+تستخدم عمليات نشر Docker وPodman المحلية الافتراضية شبكات loopback منفصلة وتحتاج إلى جسر مؤقت أثناء تسجيل الدخول. اتبع [دليل جسر OAuth المؤقت المحلي لـ Codex](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) للاطلاع على أوامر Docker وCompose وPodman والإزالة الدقيقة.في حالة النشر عن بُعد، يكون `localhost` الخاص بالمتصفح و`localhost` الخاص بالخادم جهازين مختلفين، لذا لا يستطيع وكيل عكسي عادي وحده نقل استدعاء (callback) localhost من المتصفح إلى الخادم. استخدم نفق SSH كجسر للاستدعاء. يصل النفق إلى منفذ الويب المنشور بالفعل؛ يعيد Next.js توجيه مسار الاستدعاء الدقيق فقط إلى وسيط الاستدعاء العام، ويتحقق الوسيط من `state` قبل التوجيه إلى عملية OAuth الأصلية. يبقى مستمع الاستدعاء على loopback الخلفية، والمنفذان `1455` و`1457` غير منشورين، ويدعم هذا المسار شبكة جسر Docker الافتراضية.@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-يأتي المستودع بملف [`SKILL.md`](../../SKILL.md) في الجذر — وثيقة تسليم موجزة لواجهة CLI. اطلب من وكيلك قراءته صراحةً؛ ويغطي [دليل إعداد الوكيل](../../docs-for-user/AGENT_SETUP.md) التثبيت والتهيئة. يمكنك أيضاً تغليف `deeptutor run` كأداة في حلقة LangChain / AutoGen. الوصفات الكاملة: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+يأتي المستودع بملف [`SKILL.md`](../../SKILL.md) في الجذر — وثيقة تسليم موجزة لواجهة CLI. اطلب من وكيلك قراءته صراحةً؛ ويغطي [دليل إعداد الوكيل](../../docs-for-dev/AGENT_SETUP.md) التثبيت والتهيئة. يمكنك أيضاً تغليف `deeptutor run` كأداة في حلقة LangChain / AutoGen. الوصفات الكاملة: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_CN.md b/assets/README/README_CN.mdindex 889322a65..e333fc1c0 100644--- a/assets/README/README_CN.md+++ b/assets/README/README_CN.md@@ -80,16 +80,16 @@ DeepTutor 是一个智能体原生的学习工作区,将辅导、解题、测```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[智能体配置指南](../../docs-for-user/AGENT_SETUP.md) 涵盖完整流程,包括非交互式 CLI 配置。若要自行安装,请选择下方的一种方式。+[智能体配置指南](../../docs-for-dev/AGENT_SETUP.md) 涵盖完整流程,包括非交互式 CLI 配置。若要自行安装,请选择下方的一种方式。-DeepTutor 提供四种安装方式,四者共享同一套运行时主目录布局:私有设置存储在启动目录下的 `data/user/settings/` 中(如果显式指定了 `DEEPTUTOR_HOME` / `deeptutor start --home`,则存储在该位置)。完整的存储布局、数据库支持和备份说明见[本地数据持久化](../../docs-for-user/DATA_STORAGE.md)。完整应用的推荐流程为:**选定运行时主目录 → 安装 → `deeptutor init` → `deeptutor start`**。+DeepTutor 提供四种安装方式,四者共享同一套运行时主目录布局:私有设置存储在启动目录下的 `data/user/settings/` 中(如果显式指定了 `DEEPTUTOR_HOME` / `deeptutor start --home`,则存储在该位置)。完整的存储布局、数据库支持和备份说明见[本地数据持久化](../../docs-for-dev/DATA_STORAGE.md)。完整应用的推荐流程为:**选定运行时主目录 → 安装 → `deeptutor init` → `deeptutor start`**。### 一条命令 Docker 试用@@ -118,7 +118,7 @@ deeptutor workspace reset各项能力通过内置的 workspace 工具查看所选的工作区。模型只会收到形如 `outputs/...` 的相对路径;当它使用 `workspace_present` 时,界面会渲染出一份可打开的、经过鉴权的快照。同样的相对路径在普通的 Markdown 链接或图片中也同样有效。之后修改源文件不会改变已经呈现过的快照。-学习空间负责管理资源库。在 **Settings → Workspaces** 中,可以为每个工作区分配 Skills、MCP 服务和知识库,或保留其现有访问规则。已有工作区会保持当前的访问权限,直到保存新的选择。分配直接引用原始资源,不会复制凭证或知识索引;工作区专属技能可以覆盖共享版本。详见[工作区资源分配](../../docs-for-user/workspaces.md)。+学习空间负责管理资源库。在 **Settings → Workspaces** 中,可以为每个工作区分配 Skills、MCP 服务和知识库,或保留其现有访问规则。已有工作区会保持当前的访问权限,直到保存新的选择。分配直接引用原始资源,不会复制凭证或知识索引;工作区专属技能可以覆盖共享版本。详见[工作区资源分配](../../docs-for-dev/workspaces.md)。`outputs/` 之外的执行是只读的。要把生成的文件复制到内容工作区内的其他位置,需要针对那个确切的源与目标显式确认一次**允许一次**。系统沙箱或 Docker runner 在可用时会强制执行这一边界;本地受限子进程回退方案在 Workspace 设置中会被标注为**尽力而为**。@@ -223,7 +223,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — 最新稳定版本- `ghcr.io/hkuds/deeptutor:<version>` — 不含前导 `v` 的精确版本(例如 `:1.6.3`);预发布版本只会获得对应的版本标签-> 有关 podman / 无根容器 / 只读根文件系统部署及完整的每种安装指南,请参阅 [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)。+> 有关 podman / 无根容器 / 只读根文件系统部署及完整的每种安装指南,请参阅 [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)。```bashdocker run --rm --name deeptutor \@@ -293,7 +293,7 @@ docker run --rm --name deeptutor \Docker Desktop(macOS/Windows)通常无需 `--add-host` 即可解析 `host.docker.internal`。在 Linux 上,该标志是在现代 Docker Engine 上创建该主机名的便携方式。-**Linux 替代方案 — 宿主机网络:** 添加 `--network=host` 并去掉 `-p` 标志。容器直接共享宿主机网络,打开 [http://127.0.0.1:3782](http://127.0.0.1:3782)(或 `system.json` 中的 `frontend_port`),宿主机服务可通过普通 localhost URL(如 `http://127.0.0.1:11434/v1`)访问。注意宿主机网络会将容器端口直接暴露在宿主机上,可能与现有服务冲突 — 若需保持在回环地址上,可设置 `BACKEND_HOST=127.0.0.1` 和 `FRONTEND_HOST=127.0.0.1`(详见 [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md))。+**Linux 替代方案 — 宿主机网络:** 添加 `--network=host` 并去掉 `-p` 标志。容器直接共享宿主机网络,打开 [http://127.0.0.1:3782](http://127.0.0.1:3782)(或 `system.json` 中的 `frontend_port`),宿主机服务可通过普通 localhost URL(如 `http://127.0.0.1:11434/v1`)访问。注意宿主机网络会将容器端口直接暴露在宿主机上,可能与现有服务冲突 — 若需保持在回环地址上,可设置 `BACKEND_HOST=127.0.0.1` 和 `FRONTEND_HOST=127.0.0.1`(详见 [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md))。</details>@@ -426,7 +426,7 @@ DeepTutor 将已安装的代码、私有运行时主目录与可选的内容工先为一个学科或项目建立**工作区**。其中的**主页**、**学习**和**资源**分别承载对话、学习活动和素材。**Partners** 和**个性化**随账号在不同工作区之间共享。下方导览展示这些界面如何衔接,随后介绍设置与多用户部署。-如果回答遗漏了先前的约束、引用了薄弱证据,或与选定素材不一致,请先按照 [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) 收集诊断信息,再提交 Issue。+如果回答遗漏了先前的约束、引用了薄弱证据,或与选定素材不一致,请先按照 [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) 收集诊断信息,再提交 Issue。<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="DeepTutor 主页与工作区导航" width="900">@@ -564,7 +564,7 @@ Book 将选定的来源转化为交互式**活书** — 不是静态 PDF,而<img src="../../assets/figs/web-dev/knowledge-create.png" alt="创建知识库" width="900"></div>-要迁移现有的 Obsidian、Hermes 或 Markdown 资料库?请参阅[知识迁移指南](../../docs-for-user/KNOWLEDGE_MIGRATION.md),了解连接 vault 与索引副本两种路径。+要迁移现有的 Obsidian、Hermes 或 Markdown 资料库?请参阅[知识迁移指南](../../docs-for-dev/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/eval/eval-diff/set-default/delete`、来源添加/移除命令、`list-sources` 和 `sync` 管理完整生命周期。@@ -641,7 +641,7 @@ Settings → Learning & conversation 下的 **Video Learning** 为 Reading 配成功的版本历史记录能在同账号令牌续期和目录认证错误之后继续保留,但不会让已失效的模型数据或 ETag 重新变得可用。退出登录会清除该账号的本地缓存,包括版本历史记录。普通的状态读取和推理调用不会查询 npm。目录中出现的新条目不会替换你已经选定的模型,也不会重启学习会话;出现在目录中并不代表已建立完整的推理协议兼容性。目前没有后台版本自动更新器,也没有用户可设置的版本选项。-默认的本地 Docker 和 Podman 部署各自使用独立的回环网络,登录时需要一个临时桥接。具体的 Docker、Compose、Podman 及拆除命令请参阅[临时本地 Codex OAuth 桥接指南](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)。+默认的本地 Docker 和 Podman 部署各自使用独立的回环网络,登录时需要一个临时桥接。具体的 Docker、Compose、Podman 及拆除命令请参阅[临时本地 Codex OAuth 桥接指南](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)。远程部署时,浏览器的 `localhost` 和服务器的 `localhost` 不是同一台机器,仅有普通反向代理无法把浏览器的 localhost callback 送到服务器,必须用 SSH 隧道建立 callback 桥。隧道通向已发布的 Web 端口;Next.js 只把精确的 callback 路径改写到 public callback broker,broker 校验 `state` 后才路由到原 OAuth operation。callback listener 仍位于后端 loopback,不发布 `1455`/`1457`,并支持默认 Docker bridge 网络。@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-仓库根目录附带 [`SKILL.md`](../../SKILL.md) — 一份简洁的 CLI 交接文档。请明确要求你的智能体阅读它;其[智能体配置指南](../../docs-for-user/AGENT_SETUP.md) 涵盖安装与配置。你也可以将 `deeptutor run` 包装为 LangChain / AutoGen 循环中的工具。完整示例:[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。+仓库根目录附带 [`SKILL.md`](../../SKILL.md) — 一份简洁的 CLI 交接文档。请明确要求你的智能体阅读它;其[智能体配置指南](../../docs-for-dev/AGENT_SETUP.md) 涵盖安装与配置。你也可以将 `deeptutor run` 包装为 LangChain / AutoGen 循环中的工具。完整示例:[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。</details>diff --git a/assets/README/README_ES.md b/assets/README/README_ES.mdindex 46df0b16d..383706d6d 100644--- a/assets/README/README_ES.md+++ b/assets/README/README_ES.md@@ -80,16 +80,16 @@ Copia este prompt en tu agente de IA con acceso a la terminal (como Codex o Clau```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-La [guía de configuración para agentes](../../docs-for-user/AGENT_SETUP.md) abarca todo el proceso, incluida la configuración no interactiva desde la CLI. Para instalarlo tú mismo, elige una de las rutas siguientes.+La [guía de configuración para agentes](../../docs-for-dev/AGENT_SETUP.md) abarca todo el proceso, incluida la configuración no interactiva desde la CLI. Para instalarlo tú mismo, elige una de las rutas siguientes.-DeepTutor 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). Consulta [Persistencia de datos locales](../../docs-for-user/DATA_STORAGE.md) para conocer el diseño completo del almacenamiento, la compatibilidad con bases de datos y las indicaciones para copias de seguridad. Para la aplicación completa, el flujo recomendado es **elegir un directorio de hogar de ejecución → instalar → `deeptutor init` → `deeptutor start`**.+DeepTutor 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). Consulta [Persistencia de datos locales](../../docs-for-dev/DATA_STORAGE.md) para conocer el diseño completo del almacenamiento, la compatibilidad con bases de datos y las indicaciones para copias de seguridad. 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@@ -118,7 +118,7 @@ deeptutor workspace resetLas capacidades inspeccionan el espacio de trabajo seleccionado a través de las herramientas de espacio de trabajo integradas. El modelo solo recibe rutas relativas como `outputs/...`; cuando usa `workspace_present`, la interfaz renderiza una instantánea autenticada y abrible. Esa misma ruta relativa exacta también funciona en un enlace o imagen Markdown normal. Cambiar el archivo de origen más tarde no cambia una instantánea ya presentada.-El Espacio de Aprendizaje gestiona la biblioteca de recursos. En **Settings → Workspaces**, asigna Skills, servicios MCP y bases de conocimiento a cada espacio de trabajo, o conserva sus reglas de acceso actuales. Los espacios existentes mantienen su acceso hasta que se guarda una selección. Las asignaciones hacen referencia a los recursos originales sin copiar credenciales ni índices de conocimiento; las skills específicas del espacio de trabajo pueden sustituir las versiones compartidas. Consulta las [asignaciones de recursos del espacio de trabajo](../../docs-for-user/workspaces.md).+El Espacio de Aprendizaje gestiona la biblioteca de recursos. En **Settings → Workspaces**, asigna Skills, servicios MCP y bases de conocimiento a cada espacio de trabajo, o conserva sus reglas de acceso actuales. Los espacios existentes mantienen su acceso hasta que se guarda una selección. Las asignaciones hacen referencia a los recursos originales sin copiar credenciales ni índices de conocimiento; las skills específicas del espacio de trabajo pueden sustituir las versiones compartidas. Consulta las [asignaciones de recursos del espacio de trabajo](../../docs-for-dev/workspaces.md).La ejecución es de solo lectura fuera de `outputs/`. Copiar un archivo generado a otro lugar dentro del espacio de trabajo de contenido requiere una confirmación explícita de **Allow once** para ese origen y destino exactos. Un sandbox del sistema o el runner de Docker impone este límite cuando está disponible; el fallback local de subproceso restringido se muestra como **mejor esfuerzo** en la configuración de Workspace.@@ -223,7 +223,7 @@ Un contenedor para la aplicación web completa. Imágenes en GitHub Container Re- `ghcr.io/hkuds/deeptutor:latest` — versión estable más reciente- `ghcr.io/hkuds/deeptutor:<version>` — versión exacta sin la `v` inicial (por ejemplo, `:1.6.3`); las versiones preliminares reciben únicamente su etiqueta de versión-> Consulta [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) para despliegues con podman/rootless/sistema de archivos raíz de solo lectura y la guía completa por instalación.+> Consulta [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) para despliegues con podman/rootless/sistema de archivos raíz de solo lectura y la guía completa por instalación.```bashdocker run --rm --name deeptutor \@@ -293,7 +293,7 @@ Luego en **Settings → Providers**, apunta la URL Base del proveedor a `host.doDocker Desktop (macOS/Windows) generalmente resuelve `host.docker.internal` sin `--add-host`. En Linux, el flag es la forma portátil de crear ese nombre de host en Docker Engine moderno.-**Alternativa para Linux — red del host:** agrega `--network=host` y elimina los flags `-p`. El contenedor comparte la red del host directamente, así que abre [http://127.0.0.1:3782](http://127.0.0.1:3782) (o el `frontend_port` en `system.json`), y los servicios del host se pueden alcanzar con URLs de localhost normales como `http://127.0.0.1:11434/v1`. Ten en cuenta que la red del host expone los puertos del contenedor directamente en el host y puede entrar en conflicto con servicios existentes — para mantenerlos en loopback, establece `BACKEND_HOST=127.0.0.1` y `FRONTEND_HOST=127.0.0.1` (consulta [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**Alternativa para Linux — red del host:** agrega `--network=host` y elimina los flags `-p`. El contenedor comparte la red del host directamente, así que abre [http://127.0.0.1:3782](http://127.0.0.1:3782) (o el `frontend_port` en `system.json`), y los servicios del host se pueden alcanzar con URLs de localhost normales como `http://127.0.0.1:11434/v1`. Ten en cuenta que la red del host expone los puertos del contenedor directamente en el host y puede entrar en conflicto con servicios existentes — para mantenerlos en loopback, establece `BACKEND_HOST=127.0.0.1` y `FRONTEND_HOST=127.0.0.1` (consulta [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -435,7 +435,7 @@ DeepTutor separa su código instalado, su hogar de ejecución privado y el EspacEmpieza con un **espacio de trabajo** para una materia o un proyecto. Sus secciones **Inicio**, **Aprendizaje** y **Recursos** reúnen tus conversaciones, actividades de aprendizaje y materiales. **Partners** y **Personalización** acompañan a tu cuenta entre espacios de trabajo. El recorrido siguiente muestra cómo se conectan estas superficies, seguido de la configuración y el despliegue multiusuario.-Si una respuesta pierde una restricción anterior, cita evidencia débil o contradice el material seleccionado, recopila los diagnósticos de [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) antes de abrir un issue.+Si una respuesta pierde una restricción anterior, cita evidencia débil o contradice el material seleccionado, recopila los diagnósticos de [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) antes de abrir un issue.<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="Inicio de DeepTutor y navegación del espacio de trabajo" width="900">@@ -573,7 +573,7 @@ Las bases de conocimiento son las colecciones de documentos detrás del RAG —<img src="../../assets/figs/web-dev/knowledge-create.png" alt="Crear una base de conocimiento" width="900"></div>-¿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.+¿Estás migrando una biblioteca existente de Obsidian, Hermes o Markdown? Consulta la [guía de migración de conocimiento](../../docs-for-dev/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 — 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/eval-diff/set-default/delete`, comandos para añadir o eliminar fuentes, `list-sources` y `sync`.@@ -650,7 +650,7 @@ En el inicio de sesión y **Actualizar modelos**, DeepTutor lee la última versiEl historial de versiones exitoso sobrevive a la renovación de tokens de la misma cuenta y a los errores de autenticación del catálogo, sin volver a hacer utilizables los datos de modelo invalidados ni las ETags. Cerrar sesión borra la caché local de esa cuenta, incluido el historial de versiones. Las lecturas de estado ordinarias y la inferencia no consultan npm. Las nuevas entradas del catálogo no reemplazan un modelo que ya has seleccionado ni reinician las sesiones de aprendizaje en curso; aparecer en el catálogo no establece compatibilidad total del protocolo de inferencia. No hay un actualizador de versión en segundo plano ni una configuración de versión para el usuario.-Los despliegues locales predeterminados de Docker y Podman usan redes de loopback separadas y necesitan un puente temporal durante el inicio de sesión. Sigue la [guía del puente temporal local de OAuth de Codex](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) para conocer los comandos exactos de Docker, Compose, Podman y desmontaje.+Los despliegues locales predeterminados de Docker y Podman usan redes de loopback separadas y necesitan un puente temporal durante el inicio de sesión. Sigue la [guía del puente temporal local de OAuth de Codex](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) para conocer los comandos exactos de Docker, Compose, Podman y desmontaje.Para un despliegue remoto, el `localhost` del navegador y el `localhost` del servidor son máquinas diferentes, de modo que un proxy inverso ordinario por sí solo no puede llevar la devolución de llamada localhost del navegador hasta el servidor. Usa un túnel SSH como puente de devolución de llamada. El túnel llega hasta el puerto Web ya publicado; Next.js reescribe únicamente la ruta exacta de devolución de llamada hacia el broker público de devolución de llamada, y el broker valida `state` antes de enrutar hacia la operación OAuth original. El listener de devolución de llamada permanece en el loopback del backend, los puertos `1455` y `1457` no se publican, y esta ruta admite la red bridge predeterminada de Docker.@@ -734,7 +734,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \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 compacto de traspaso para la CLI. Pide a tu agente que lo lea explícitamente; su [guía de configuración para agentes](../../docs-for-user/AGENT_SETUP.md) abarca la instalación y la configuración. También puedes envolver `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 compacto de traspaso para la CLI. Pide a tu agente que lo lea explícitamente; su [guía de configuración para agentes](../../docs-for-dev/AGENT_SETUP.md) abarca la instalación y la configuración. También puedes envolver `deeptutor run` como herramienta en un bucle LangChain / AutoGen. Recetas completas: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_FR.md b/assets/README/README_FR.mdindex 7485e8383..9d5c5d720 100644--- a/assets/README/README_FR.md+++ b/assets/README/README_FR.md@@ -80,16 +80,16 @@ Copiez cette consigne dans votre agent IA capable d’utiliser un terminal (comm```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-Le [guide de configuration par un agent](../../docs-for-user/AGENT_SETUP.md) décrit tout le parcours, y compris la configuration CLI non interactive. Pour l’installer vous-même, choisissez l’une des méthodes ci-dessous.+Le [guide de configuration par un agent](../../docs-for-dev/AGENT_SETUP.md) décrit tout le parcours, y compris la configuration CLI non interactive. Pour l’installer vous-même, choisissez l’une des méthodes ci-dessous.-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). Consultez la [persistance des données locales](../../docs-for-user/DATA_STORAGE.md) pour la structure complète du stockage, la prise en charge des bases de données et les recommandations de sauvegarde. 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). Consultez la [persistance des données locales](../../docs-for-dev/DATA_STORAGE.md) pour la structure complète du stockage, la prise en charge des bases de données et les recommandations de sauvegarde. 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@@ -118,7 +118,7 @@ deeptutor workspace resetLes capacités inspectent leur espace de travail sélectionné via les outils workspace intégrés. Le modèle ne reçoit que des chemins relatifs tels que `outputs/...` ; quand il utilise `workspace_present`, l'interface affiche un instantané authentifié et ouvrable. Le même chemin relatif exact fonctionne aussi dans un lien ou une image Markdown normal. Modifier le fichier source ultérieurement ne change pas un instantané déjà présenté.-Learning Space gère la bibliothèque de ressources. Dans **Paramètres → Espaces de travail**, attribuez des compétences, des services MCP et des bases de connaissances à chaque espace, ou conservez ses règles d'accès existantes. Les espaces existants gardent leurs accès actuels jusqu'à l'enregistrement d'une sélection. Les attributions référencent les ressources d'origine sans copier les identifiants ni les index de connaissances ; les compétences propres à un espace peuvent remplacer les versions partagées. Consultez les [attributions de ressources aux espaces de travail](../../docs-for-user/workspaces.md).+Learning Space gère la bibliothèque de ressources. Dans **Paramètres → Espaces de travail**, attribuez des compétences, des services MCP et des bases de connaissances à chaque espace, ou conservez ses règles d'accès existantes. Les espaces existants gardent leurs accès actuels jusqu'à l'enregistrement d'une sélection. Les attributions référencent les ressources d'origine sans copier les identifiants ni les index de connaissances ; les compétences propres à un espace peuvent remplacer les versions partagées. Consultez les [attributions de ressources aux espaces de travail](../../docs-for-dev/workspaces.md).L'exécution est en lecture seule en dehors de `outputs/`. Copier un fichier généré ailleurs dans le content workspace nécessite une confirmation explicite **Allow once** pour cette source et cette destination exactes. Un sandbox système ou le runner Docker impose cette frontière quand il est disponible ; le repli local par sous-processus restreint est indiqué comme **best effort** dans les paramètres Workspace.@@ -223,7 +223,7 @@ Un conteneur pour l'application Web complète. Images sur GitHub Container Regis- `ghcr.io/hkuds/deeptutor:latest` — dernière version stable- `ghcr.io/hkuds/deeptutor:<version>` — version exacte sans le `v` initial (par exemple `:1.6.3`) ; les préversions ne reçoivent que leur tag de version-> Voir [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) pour les déploiements podman/rootless/système de fichiers racine en lecture seule et le guide complet par installation.+> Voir [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) pour les déploiements podman/rootless/système de fichiers racine en lecture seule et le guide complet par installation.```bashdocker run --rm --name deeptutor \@@ -303,7 +303,7 @@ Puis dans **Paramètres → Fournisseurs**, pointez l'URL de base du fournisseurDocker Desktop (macOS/Windows) résout généralement `host.docker.internal` sans `--add-host`. Sur Linux, le drapeau est la façon portable de créer ce nom d'hôte avec les versions modernes de Docker Engine.-**Alternative Linux — réseau hôte :** ajoutez `--network=host` et supprimez les drapeaux `-p`. Le conteneur partage directement le réseau hôte, ouvrez donc [http://127.0.0.1:3782](http://127.0.0.1:3782) (ou le `frontend_port` dans `system.json`), et les services hôtes sont accessibles avec des URLs localhost normales comme `http://127.0.0.1:11434/v1`. Notez que le réseau hôte expose les ports du conteneur directement sur l'hôte et peut entrer en conflit avec des services existants — pour les maintenir sur loopback, définissez `BACKEND_HOST=127.0.0.1` et `FRONTEND_HOST=127.0.0.1` (voir [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**Alternative Linux — réseau hôte :** ajoutez `--network=host` et supprimez les drapeaux `-p`. Le conteneur partage directement le réseau hôte, ouvrez donc [http://127.0.0.1:3782](http://127.0.0.1:3782) (ou le `frontend_port` dans `system.json`), et les services hôtes sont accessibles avec des URLs localhost normales comme `http://127.0.0.1:11434/v1`. Notez que le réseau hôte expose les ports du conteneur directement sur l'hôte et peut entrer en conflit avec des services existants — pour les maintenir sur loopback, définissez `BACKEND_HOST=127.0.0.1` et `FRONTEND_HOST=127.0.0.1` (voir [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -436,7 +436,7 @@ DeepTutor sépare son code installé, son répertoire d'exécution privé et sonCommencez par un **espace de travail** pour une matière ou un projet. Ses rubriques **Accueil**, **Apprentissage** et **Ressources** rassemblent vos conversations, activités d'apprentissage et supports. **Partners** et **Personnalisation** restent liés à votre compte entre les espaces de travail. La visite ci-dessous montre comment ces surfaces sont reliées, puis présente les paramètres et le déploiement multi-utilisateur.-Si une réponse perd une contrainte antérieure, cite des preuves faibles ou contredit les supports sélectionnés, rassemblez les diagnostics dans [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) avant d'ouvrir une issue.+Si une réponse perd une contrainte antérieure, cite des preuves faibles ou contredit les supports sélectionnés, rassemblez les diagnostics dans [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) avant d'ouvrir une issue.<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="Accueil de DeepTutor et navigation des espaces de travail" width="900">@@ -574,7 +574,7 @@ Les bases de connaissances sont les collections de documents derrière le RAG<img src="../../assets/figs/web-dev/knowledge-create.png" alt="Créer une base de connaissances" width="900"></div>-Vous 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.+Vous migrez une bibliothèque Obsidian, Hermes ou Markdown existante ? Consultez le [guide de migration des connaissances](../../docs-for-dev/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 — 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/eval-diff/set-default/delete`, les commandes d'ajout et de suppression de sources, `list-sources` et `sync`.@@ -652,7 +652,7 @@ La plupart des sections utilisent un flux brouillon-et-application, vous pouvezL'historique des versions réussies survit au renouvellement de jeton du même compte et aux erreurs d'authentification du catalogue, sans rendre à nouveau utilisables les données de modèle ou les ETags invalidés. La déconnexion efface le cache local de ce compte, y compris l'historique des versions. Les lectures d'état ordinaires et l'inférence n'interrogent pas npm. Les nouvelles entrées du catalogue ne remplacent pas un modèle déjà sélectionné ni ne redémarrent les sessions d'apprentissage ; figurer dans le catalogue n'établit pas une compatibilité complète du protocole d'inférence. Il n'existe pas de mise à jour de version en arrière-plan ni de paramètre de version utilisateur.-Les déploiements locaux par défaut Docker et Podman utilisent des réseaux loopback séparés et nécessitent un pont temporaire pendant la connexion. Suivez le [guide du pont OAuth Codex local temporaire](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) pour les commandes exactes de Docker, Compose, Podman et d'arrêt.+Les déploiements locaux par défaut Docker et Podman utilisent des réseaux loopback séparés et nécessitent un pont temporaire pendant la connexion. Suivez le [guide du pont OAuth Codex local temporaire](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) pour les commandes exactes de Docker, Compose, Podman et d'arrêt.Pour un déploiement distant, le `localhost` du navigateur et le `localhost` du serveur sont deux machines différentes, donc un simple proxy inverse ne peut pas à lui seul acheminer le callback localhost du navigateur jusqu'au serveur. Utilisez un tunnel SSH comme pont de callback. Le tunnel atteint le port Web déjà publié ; Next.js ne réécrit que le chemin de callback exact vers le courtier de callback public, et ce courtier valide `state` avant de router vers l'opération OAuth d'origine. L'écouteur de callback reste sur le loopback du backend, les ports `1455` et `1457` ne sont pas publiés, et ce chemin prend en charge le réseau bridge Docker par défaut.@@ -736,7 +736,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-Le dépôt inclut un [`SKILL.md`](../../SKILL.md) racine — un document de passation concis pour la CLI. Demandez explicitement à votre agent de le lire ; son [guide de configuration par un agent](../../docs-for-user/AGENT_SETUP.md) couvre l’installation et la configuration. Vous pouvez aussi envelopper `deeptutor run` comme un outil dans une boucle LangChain / AutoGen. Recettes complètes : [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+Le dépôt inclut un [`SKILL.md`](../../SKILL.md) racine — un document de passation concis pour la CLI. Demandez explicitement à votre agent de le lire ; son [guide de configuration par un agent](../../docs-for-dev/AGENT_SETUP.md) couvre l’installation et la configuration. Vous pouvez aussi envelopper `deeptutor run` comme un outil dans une boucle LangChain / AutoGen. Recettes complètes : [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_HI.md b/assets/README/README_HI.mdindex 8d970f680..2589dbe29 100644--- a/assets/README/README_HI.md+++ b/assets/README/README_HI.md@@ -80,16 +80,16 @@ DeepTutor एक agent-native learning workspace है जो tutoring, problem```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[Agent Setup guide](../../docs-for-user/AGENT_SETUP.md) में पूरी प्रक्रिया दी गई है, जिसमें non-interactive CLI configuration भी शामिल है। खुद install करने के लिए नीचे दिए गए paths में से एक चुनें।+[Agent Setup guide](../../docs-for-dev/AGENT_SETUP.md) में पूरी प्रक्रिया दी गई है, जिसमें non-interactive CLI configuration भी शामिल है। खुद install करने के लिए नीचे दिए गए paths में से एक चुनें।-DeepTutor चार installation paths के साथ आता है। वे सभी एक runtime-home layout साझा करते हैं: private settings उस directory के नीचे `data/user/settings/` में रहती हैं जहां से आप launch करते हैं (या `DEEPTUTOR_HOME` / `deeptutor start --home` के नीचे अगर आप explicitly set करते हैं)। पूरे storage layout, database support और backup संबंधी जानकारी के लिए [स्थानीय डेटा का स्थायी संग्रह](../../docs-for-user/DATA_STORAGE.md) देखें। पूरे app के लिए, recommended flow है **एक runtime-home directory चुनें → install करें → `deeptutor init` → `deeptutor start`**।+DeepTutor चार installation paths के साथ आता है। वे सभी एक runtime-home layout साझा करते हैं: private settings उस directory के नीचे `data/user/settings/` में रहती हैं जहां से आप launch करते हैं (या `DEEPTUTOR_HOME` / `deeptutor start --home` के नीचे अगर आप explicitly set करते हैं)। पूरे storage layout, database support और backup संबंधी जानकारी के लिए [स्थानीय डेटा का स्थायी संग्रह](../../docs-for-dev/DATA_STORAGE.md) देखें। पूरे app के लिए, recommended flow है **एक runtime-home directory चुनें → install करें → `deeptutor init` → `deeptutor start`**।### एक कमांड से Docker आज़माएं@@ -118,7 +118,7 @@ deeptutor workspace resetCapabilities built-in workspace tools के जरिए अपना selected workspace inspect करती हैं। Model को केवल `outputs/...` जैसे relative paths मिलते हैं; जब वह `workspace_present` उपयोग करता है, तो UI एक authenticated, openable snapshot render करता है। वही exact relative path एक normal Markdown link या image में भी काम करता है। बाद में source file बदलने से पहले से presented snapshot नहीं बदलता।-Learning Space resource library manage करता है। **Settings → Workspaces** में हर workspace को Skills, MCP services और knowledge bases assign करें, या उसके existing access rules बनाए रखें। Selection save होने तक existing workspaces का current access बना रहता है। Assignments credentials या knowledge indexes copy किए बिना original resources को reference करते हैं; workspace-specific skills shared versions को override कर सकती हैं। [Workspace resource assignments](../../docs-for-user/workspaces.md) देखें।+Learning Space resource library manage करता है। **Settings → Workspaces** में हर workspace को Skills, MCP services और knowledge bases assign करें, या उसके existing access rules बनाए रखें। Selection save होने तक existing workspaces का current access बना रहता है। Assignments credentials या knowledge indexes copy किए बिना original resources को reference करते हैं; workspace-specific skills shared versions को override कर सकती हैं। [Workspace resource assignments](../../docs-for-dev/workspaces.md) देखें।`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** के रूप में दिखाया जाता है।@@ -223,7 +223,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — latest stable release- `ghcr.io/hkuds/deeptutor:<version>` — शुरू के `v` के बिना exact release (उदाहरण `:1.6.3`); pre-releases को केवल उनका version tag मिलता है-> podman/rootless/read-only-rootfs deployments और पूरे per-installation guide के लिए [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) देखें।+> podman/rootless/read-only-rootfs deployments और पूरे per-installation guide के लिए [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) देखें।```bashdocker run --rm --name deeptutor \@@ -293,7 +293,7 @@ docker run --rm --name deeptutor \Docker Desktop (macOS/Windows) आमतौर पर `--add-host` के बिना `host.docker.internal` resolve करता है। Linux पर, यह flag modern Docker Engine पर वह hostname बनाने का portable तरीका है।-**Linux alternative — host networking:** `--network=host` add करें और `-p` flags हटाएं। Container host network directly share करता है, इसलिए [http://127.0.0.1:3782](http://127.0.0.1:3782) (या `system.json` में `frontend_port`) खोलें, और host services को normal localhost URLs जैसे `http://127.0.0.1:11434/v1` से reach किया जा सकता है। ध्यान दें कि host networking container ports को host पर directly expose करता है और existing services से conflict हो सकता है — उन्हें loopback पर रखने के लिए `BACKEND_HOST=127.0.0.1` और `FRONTEND_HOST=127.0.0.1` set करें ([CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) देखें)।+**Linux alternative — host networking:** `--network=host` add करें और `-p` flags हटाएं। Container host network directly share करता है, इसलिए [http://127.0.0.1:3782](http://127.0.0.1:3782) (या `system.json` में `frontend_port`) खोलें, और host services को normal localhost URLs जैसे `http://127.0.0.1:11434/v1` से reach किया जा सकता है। ध्यान दें कि host networking container ports को host पर directly expose करता है और existing services से conflict हो सकता है — उन्हें loopback पर रखने के लिए `BACKEND_HOST=127.0.0.1` और `FRONTEND_HOST=127.0.0.1` set करें ([CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) देखें)।</details>@@ -426,7 +426,7 @@ DeepTutor अपने installed code, private runtime home, और optional Conकिसी विषय या project के लिए एक **workspace** से शुरू करें। उसके **Home**, **Learning** और **Resources** में आपकी conversations, learning activities और materials रहते हैं। **Partners** और **Personalization** अलग-अलग workspaces में भी आपके account से जुड़े रहते हैं। नीचे का tour बताता है कि ये surfaces कैसे जुड़ती हैं, फिर settings और multi-user deployment समझाता है।-अगर कोई answer पहले का constraint खो दे, weak evidence cite करे, या selected material से disagree करे, तो issue खोलने से पहले [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) में diagnostics collect करें।+अगर कोई answer पहले का constraint खो दे, weak evidence cite करे, या selected material से disagree करे, तो issue खोलने से पहले [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) में diagnostics collect करें।<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="DeepTutor Home और workspace नेविगेशन" width="900">@@ -564,7 +564,7 @@ Knowledge bases RAG के पीछे document collections हैं — व<img src="../../assets/figs/web-dev/knowledge-create.png" alt="एक knowledge base बनाएं" width="900"></div>-Existing Obsidian, Hermes, या Markdown library migrate कर रहे हैं? Connected-vault और indexed-copy paths के लिए [Knowledge migration guide](../../docs-for-user/KNOWLEDGE_MIGRATION.md) देखें।+Existing Obsidian, Hermes, या Markdown library migrate कर रहे हैं? Connected-vault और indexed-copy paths के लिए [Knowledge migration guide](../../docs-for-dev/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 — और एक 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/eval-diff/set-default/delete`, source add/remove commands, `list-sources`, और `sync` से mirror करता है।@@ -641,7 +641,7 @@ Sign-in और **Refresh models** पर, DeepTutor official npm registry सेSuccessful version history same-account token renewal और catalog authentication errors के पार बची रहती है, बिना invalidated model data या ETags को फिर से usable बनाए। Sign out करने से उस account का local cache clear हो जाता है, जिसमें version history भी शामिल है। सामान्य status reads और inference npm को query नहीं करते। नई catalog entries आपके पहले से selected model को replace नहीं करती हैं या learning sessions restart नहीं करती हैं; catalog में दिखना पूरी inference-protocol compatibility स्थापित नहीं करता। कोई background version updater या user version setting नहीं है।-Default local Docker और Podman deployments separate loopback networks उपयोग करते हैं और sign-in के दौरान एक temporary bridge की जरूरत होती है। Docker, Compose, Podman, और teardown के exact commands के लिए [temporary local Codex OAuth bridge guide](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) follow करें।+Default local Docker और Podman deployments separate loopback networks उपयोग करते हैं और sign-in के दौरान एक temporary bridge की जरूरत होती है। Docker, Compose, Podman, और teardown के exact commands के लिए [temporary local Codex OAuth bridge guide](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) follow करें।Remote deployment में, browser का `localhost` और server का `localhost` एक ही machine नहीं हैं, इसलिए सिर्फ एक ordinary reverse proxy browser के localhost callback को server तक नहीं पहुंचा सकता — callback bridge बनाने के लिए SSH tunnel जरूरी है। Tunnel पहले से published Web port तक पहुंचता है; Next.js केवल exact callback path को public callback broker पर rewrite करता है, और broker original OAuth operation पर route करने से पहले `state` validate करता है। Callback listener backend loopback पर ही रहता है, ports `1455` और `1457` publish नहीं होते, और यह path default Docker bridge network को support करता है।@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-Repo एक root [`SKILL.md`](../../SKILL.md) ship करता है — CLI के लिए एक संक्षिप्त handover doc। अपने agent से इसे स्पष्ट रूप से पढ़ने को कहें; इसकी [Agent Setup guide](../../docs-for-user/AGENT_SETUP.md) में installation और configuration दिए गए हैं। आप `deeptutor run` को LangChain / AutoGen loop में एक tool के रूप में भी wrap कर सकते हैं। पूरे recipes: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)।+Repo एक root [`SKILL.md`](../../SKILL.md) ship करता है — CLI के लिए एक संक्षिप्त handover doc। अपने agent से इसे स्पष्ट रूप से पढ़ने को कहें; इसकी [Agent Setup guide](../../docs-for-dev/AGENT_SETUP.md) में installation और configuration दिए गए हैं। आप `deeptutor run` को LangChain / AutoGen loop में एक tool के रूप में भी wrap कर सकते हैं। पूरे recipes: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)।</details>diff --git a/assets/README/README_JA.md b/assets/README/README_JA.mdindex c369d0e59..5f9645d7c 100644--- a/assets/README/README_JA.md+++ b/assets/README/README_JA.md@@ -80,16 +80,16 @@ DeepTutorは、個別指導、問題解決、クイズ生成、研究、ビジ```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[エージェントセットアップガイド](../../docs-for-user/AGENT_SETUP.md)は、対話なしでのCLI設定を含む一連の手順を説明しています。自分でインストールする場合は、以下の方法から選んでください。+[エージェントセットアップガイド](../../docs-for-dev/AGENT_SETUP.md)は、対話なしでのCLI設定を含む一連の手順を説明しています。自分でインストールする場合は、以下の方法から選んでください。-DeepTutorは4つのインストールパスを提供しています。どれも同じランタイムホームのレイアウトを共有します。プライベート設定は、起動元のディレクトリ(または明示的に設定した場合は`DEEPTUTOR_HOME` / `deeptutor start --home`)配下の`data/user/settings/`に保存されます。ストレージの全体構成、データベースのサポート、バックアップの注意点については[ローカルデータの永続化](../../docs-for-user/DATA_STORAGE.md)をご覧ください。フルアプリの場合、推奨されるフローは **ランタイムホームディレクトリの選択 → インストール → `deeptutor init` → `deeptutor start`** です。+DeepTutorは4つのインストールパスを提供しています。どれも同じランタイムホームのレイアウトを共有します。プライベート設定は、起動元のディレクトリ(または明示的に設定した場合は`DEEPTUTOR_HOME` / `deeptutor start --home`)配下の`data/user/settings/`に保存されます。ストレージの全体構成、データベースのサポート、バックアップの注意点については[ローカルデータの永続化](../../docs-for-dev/DATA_STORAGE.md)をご覧ください。フルアプリの場合、推奨されるフローは **ランタイムホームディレクトリの選択 → インストール → `deeptutor init` → `deeptutor start`** です。### 1コマンドでDockerを試す@@ -118,7 +118,7 @@ deeptutor workspace reset各機能は、組み込みのワークスペースツールを通じて選択されたワークスペースを検査します。モデルが受け取るのは`outputs/...`のような相対パスのみです。`workspace_present`を使用すると、UIは認証済みの開けるスナップショットをレンダリングします。同じ正確な相対パスは、通常のMarkdownリンクや画像でもそのまま機能します。後で元のファイルを変更しても、すでに提示されたスナップショットは変わりません。-Learning Spaceはリソースライブラリを管理します。**Settings → Workspaces**で各ワークスペースにSkills、MCPサービス、知識ベースを割り当てるか、既存のアクセスルールを維持できます。既存のワークスペースは、選択を保存するまで現在のアクセス権を保持します。割り当ては元のリソースを参照し、認証情報や知識インデックスをコピーしません。ワークスペース固有のスキルは共有版を上書きできます。[ワークスペースのリソース割り当て](../../docs-for-user/workspaces.md)を参照してください。+Learning Spaceはリソースライブラリを管理します。**Settings → Workspaces**で各ワークスペースにSkills、MCPサービス、知識ベースを割り当てるか、既存のアクセスルールを維持できます。既存のワークスペースは、選択を保存するまで現在のアクセス権を保持します。割り当ては元のリソースを参照し、認証情報や知識インデックスをコピーしません。ワークスペース固有のスキルは共有版を上書きできます。[ワークスペースのリソース割り当て](../../docs-for-dev/workspaces.md)を参照してください。実行は`outputs/`の外では読み取り専用です。生成されたファイルをコンテンツワークスペース内の別の場所にコピーするには、その正確なコピー元とコピー先について明示的な**Allow once**の確認が必要です。利用可能な場合はシステムサンドボックスまたはDocker runnerがこの境界を強制します。ローカルの制限付きサブプロセスフォールバックは、Workspace設定で**best effort**として表示されます。@@ -223,7 +223,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — 最新の安定版リリース- `ghcr.io/hkuds/deeptutor:<version>` — 先頭の`v`を除いた正確なリリース(例:`:1.6.3`)。プレリリースにはそのバージョンタグのみが付与されます-> ポッドマン/rootless/読み取り専用rootfsデプロイメントと完全なインストール別ガイドについては [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) を参照してください。+> ポッドマン/rootless/読み取り専用rootfsデプロイメントと完全なインストール別ガイドについては [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) を参照してください。```bashdocker run --rm --name deeptutor \@@ -293,7 +293,7 @@ docker run --rm --name deeptutor \Docker Desktop(macOS/Windows)は通常`--add-host`なしで`host.docker.internal`を解決します。Linuxでは、このフラグが最新のDocker Engineでそのホスト名を作成するポータブルな方法です。-**Linuxの代替 — ホストネットワーキング:** `--network=host`を追加して`-p`フラグを削除します。コンテナはホストネットワークを直接共有するため、[http://127.0.0.1:3782](http://127.0.0.1:3782)(または`system.json`の`frontend_port`)を開き、ホストサービスには`http://127.0.0.1:11434/v1`のような通常のlocalhostのURLでアクセスできます。ホストネットワーキングはコンテナのポートをホスト上に直接公開し、既存のサービスと競合する可能性があります — それらをループバックに保つには`BACKEND_HOST=127.0.0.1`と`FRONTEND_HOST=127.0.0.1`を設定してください([CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)参照)。+**Linuxの代替 — ホストネットワーキング:** `--network=host`を追加して`-p`フラグを削除します。コンテナはホストネットワークを直接共有するため、[http://127.0.0.1:3782](http://127.0.0.1:3782)(または`system.json`の`frontend_port`)を開き、ホストサービスには`http://127.0.0.1:11434/v1`のような通常のlocalhostのURLでアクセスできます。ホストネットワーキングはコンテナのポートをホスト上に直接公開し、既存のサービスと競合する可能性があります — それらをループバックに保つには`BACKEND_HOST=127.0.0.1`と`FRONTEND_HOST=127.0.0.1`を設定してください([CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)参照)。</details>@@ -426,7 +426,7 @@ DeepTutorは、インストールされたコード、プライベートなラ科目やプロジェクト用の**ワークスペース**から始めましょう。その**Home**、**Learning**、**Resources**に、会話、学習活動、教材がまとまります。**Partners**と**Personalization**はワークスペースをまたいでアカウントに紐づきます。以下のツアーでは各画面のつながりを紹介し、続いて設定とマルチユーザーデプロイメントを説明します。-回答が以前の制約を失ったり、弱い根拠を引用したり、選択した資料と矛盾したりする場合は、Issueを開く前に[`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md)に診断情報をまとめてください。+回答が以前の制約を失ったり、弱い根拠を引用したり、選択した資料と矛盾したりする場合は、Issueを開く前に[`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md)に診断情報をまとめてください。<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="DeepTutorのHomeとワークスペースナビゲーション" width="900">@@ -564,7 +564,7 @@ Bookは選択したソースをインタラクティブな**生きている本**<img src="../../assets/figs/web-dev/knowledge-create.png" alt="知識ベースの作成" width="900"></div>-既存のObsidian、Hermes、Markdownライブラリを移行する場合は、接続ボールトとインデックス付きコピーの手順を[Knowledge migration guide](../../docs-for-user/KNOWLEDGE_MIGRATION.md)で確認してください。+既存のObsidian、Hermes、Markdownライブラリを移行する場合は、接続ボールトとインデックス付きコピーの手順を[Knowledge migration guide](../../docs-for-dev/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/eval/eval-diff/set-default/delete`、ソースの追加/削除コマンド、`list-sources`、`sync`でライフサイクルをミラーします。@@ -641,7 +641,7 @@ Settings → Learning & conversationの**Video Learning**では、Reading用のY成功したバージョン履歴は、同一アカウントのトークン更新やカタログ認証エラーをまたいで保持されますが、無効化されたモデルデータやETagが再び使用可能になることはありません。サインアウトすると、バージョン履歴を含むそのアカウントのローカルキャッシュがクリアされます。通常のステータス読み取りと推論はnpmに問い合わせません。新しいカタログエントリは、すでに選択済みのモデルを置き換えたり学習セッションを再起動させたりしません。カタログに登場することは、完全な推論プロトコル互換性を保証するものではありません。バックグラウンドのバージョン更新機能やユーザー向けのバージョン設定はありません。-デフォルトのローカルDockerおよびPodmanデプロイメントは別々のループバックネットワークを使用するため、サインイン中に一時的なブリッジが必要です。正確なDocker、Compose、Podman、および後片付け用のコマンドについては、[一時的なローカルCodex OAuthブリッジガイド](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)を参照してください。+デフォルトのローカルDockerおよびPodmanデプロイメントは別々のループバックネットワークを使用するため、サインイン中に一時的なブリッジが必要です。正確なDocker、Compose、Podman、および後片付け用のコマンドについては、[一時的なローカルCodex OAuthブリッジガイド](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)を参照してください。リモートデプロイメントでは、ブラウザ側の`localhost`とサーバー側の`localhost`は別のマシンであるため、通常のリバースプロキシだけではブラウザのlocalhostコールバックをサーバーまで運べません。コールバックの橋渡しとしてSSHトンネルを使用してください。トンネルは既に公開されているWebポートに到達します。Next.jsは正確なコールバックパスのみを公開コールバックブローカーに書き換え、ブローカーは元のOAuth操作にルーティングする前に`state`を検証します。コールバックリスナーはバックエンドのループバックに留まり、ポート`1455`と`1457`は公開されず、このパスはデフォルトのDockerブリッジネットワークをサポートします。@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-リポジトリには、CLIの簡潔な引き継ぎドキュメントであるルートの[`SKILL.md`](../../SKILL.md)が含まれています。エージェントに明示的に読み取るよう依頼してください。[エージェントセットアップガイド](../../docs-for-user/AGENT_SETUP.md)では、インストールと設定を説明しています。`deeptutor run`をLangChain / AutoGenループのツールとしてラップすることもできます。完全なレシピ:[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。+リポジトリには、CLIの簡潔な引き継ぎドキュメントであるルートの[`SKILL.md`](../../SKILL.md)が含まれています。エージェントに明示的に読み取るよう依頼してください。[エージェントセットアップガイド](../../docs-for-dev/AGENT_SETUP.md)では、インストールと設定を説明しています。`deeptutor run`をLangChain / AutoGenループのツールとしてラップすることもできます。完全なレシピ:[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。</details>diff --git a/assets/README/README_PL.md b/assets/README/README_PL.mdindex 7bd82ea47..db7691c67 100644--- a/assets/README/README_PL.md+++ b/assets/README/README_PL.md@@ -79,16 +79,16 @@ Skopiuj ten prompt do swojego agenta AI z dostępem do terminala (na przykład C```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[Przewodnik konfiguracji przez agenta](../../docs-for-user/AGENT_SETUP.md) opisuje cały proces, w tym nieinteraktywną konfigurację przez CLI. Aby zainstalować aplikację samodzielnie, wybierz jedną z poniższych ścieżek.+[Przewodnik konfiguracji przez agenta](../../docs-for-dev/AGENT_SETUP.md) opisuje cały proces, w tym nieinteraktywną konfigurację przez CLI. Aby zainstalować aplikację samodzielnie, wybierz jedną z poniższych ścieżek.-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). Pełny układ przechowywania danych, obsługiwane bazy danych i informacje o kopiach zapasowych opisuje [Trwałe przechowywanie danych lokalnych](../../docs-for-user/DATA_STORAGE.md). Dla pełnej aplikacji zalecany przepływ to **wybierz katalog środowiska uruchomieniowego → 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). Pełny układ przechowywania danych, obsługiwane bazy danych i informacje o kopiach zapasowych opisuje [Trwałe przechowywanie danych lokalnych](../../docs-for-dev/DATA_STORAGE.md). Dla pełnej aplikacji zalecany przepływ to **wybierz katalog środowiska uruchomieniowego → zainstaluj → `deeptutor init` → `deeptutor start`**.### Wypróbuj Docker jednym poleceniem@@ -117,7 +117,7 @@ deeptutor workspace resetMożliwości przeglądają wybrany obszar roboczy przez wbudowane narzędzia workspace. Model otrzymuje wyłącznie względne ścieżki, takie jak `outputs/...`; gdy użyje `workspace_present`, UI renderuje uwierzytelniony, otwieralny zrzut. Ta sama dokładna względna ścieżka działa też w normalnym linku Markdown lub obrazie. Zmiana pliku źródłowego później nie zmienia już zaprezentowanego zrzutu.-Learning Space zarządza biblioteką zasobów. W **Settings → Workspaces** można przypisać umiejętności, usługi MCP i bazy wiedzy do każdego obszaru roboczego lub zachować jego dotychczasowe reguły dostępu. Istniejące obszary zachowują bieżący dostęp do czasu zapisania wyboru. Przypisania odwołują się do oryginalnych zasobów bez kopiowania poświadczeń ani indeksów wiedzy; umiejętności specyficzne dla obszaru roboczego mogą nadpisywać wersje współdzielone. Zobacz [przypisywanie zasobów do obszarów roboczych](../../docs-for-user/workspaces.md).+Learning Space zarządza biblioteką zasobów. W **Settings → Workspaces** można przypisać umiejętności, usługi MCP i bazy wiedzy do każdego obszaru roboczego lub zachować jego dotychczasowe reguły dostępu. Istniejące obszary zachowują bieżący dostęp do czasu zapisania wyboru. Przypisania odwołują się do oryginalnych zasobów bez kopiowania poświadczeń ani indeksów wiedzy; umiejętności specyficzne dla obszaru roboczego mogą nadpisywać wersje współdzielone. Zobacz [przypisywanie zasobów do obszarów roboczych](../../docs-for-dev/workspaces.md).Wykonanie jest tylko do odczytu poza `outputs/`. Skopiowanie wygenerowanego pliku gdzie indziej w content workspace wymaga jawnego potwierdzenia **Allow once** dla dokładnie tego źródła i celu. Piaskownica systemowa lub Docker runner egzekwuje tę granicę, gdy jest dostępna; lokalny awaryjny ograniczony podproces jest oznaczony jako **best effort** w ustawieniach Workspace.@@ -222,7 +222,7 @@ Jeden kontener dla pełnej aplikacji Web. Obrazy w GitHub Container Registry:- `ghcr.io/hkuds/deeptutor:latest` — najnowsze stabilne wydanie- `ghcr.io/hkuds/deeptutor:<version>` — dokładne wydanie bez początkowego `v` (na przykład `:1.6.3`); wydania wstępne otrzymują wyłącznie własny tag wersji-> Zobacz [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) w celu uzyskania informacji o wdrożeniach podman/rootless/read-only-rootfs i pełnym przewodniku per-instalacja.+> Zobacz [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) w celu uzyskania informacji o wdrożeniach podman/rootless/read-only-rootfs i pełnym przewodniku per-instalacja.```bashdocker run --rm --name deeptutor \@@ -292,7 +292,7 @@ Następnie w **Settings → Providers** wskaż bazowy URL dostawcy na `host.dockDocker Desktop (macOS/Windows) zazwyczaj rozwiązuje `host.docker.internal` bez `--add-host`. Na Linuksie flaga jest przenośnym sposobem tworzenia tej nazwy hosta w nowoczesnym Docker Engine.-**Alternatywa dla Linuksa — sieć hosta:** dodaj `--network=host` i usuń flagi `-p`. Kontener bezpośrednio współdzieli sieć hosta, więc otwórz [http://127.0.0.1:3782](http://127.0.0.1:3782) (lub `frontend_port` w `system.json`), a usługi hosta są dostępne pod normalnymi adresami URL localhost jak `http://127.0.0.1:11434/v1`. Pamiętaj, że sieciowanie hosta bezpośrednio ujawnia porty kontenera na hoście i może powodować konflikty z istniejącymi usługami — aby utrzymać je na loopback, ustaw `BACKEND_HOST=127.0.0.1` i `FRONTEND_HOST=127.0.0.1` (patrz [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**Alternatywa dla Linuksa — sieć hosta:** dodaj `--network=host` i usuń flagi `-p`. Kontener bezpośrednio współdzieli sieć hosta, więc otwórz [http://127.0.0.1:3782](http://127.0.0.1:3782) (lub `frontend_port` w `system.json`), a usługi hosta są dostępne pod normalnymi adresami URL localhost jak `http://127.0.0.1:11434/v1`. Pamiętaj, że sieciowanie hosta bezpośrednio ujawnia porty kontenera na hoście i może powodować konflikty z istniejącymi usługami — aby utrzymać je na loopback, ustaw `BACKEND_HOST=127.0.0.1` i `FRONTEND_HOST=127.0.0.1` (patrz [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -425,7 +425,7 @@ DeepTutor oddziela zainstalowany kod, prywatny obszar roboczy środowiska uruchoZacznij od **obszaru roboczego** dla przedmiotu lub projektu. Jego **Strona główna**, **Nauka** i **Zasoby** zawierają rozmowy, aktywności edukacyjne i materiały. **Partners** i **Personalizacja** są przypisane do konta i dostępne w różnych obszarach roboczych. Poniższy przegląd pokazuje powiązania między tymi częściami aplikacji, a następnie opisuje ustawienia i wdrożenia wieloużytkownikowe.-Jeśli odpowiedź pomija wcześniejsze ograniczenie, przywołuje słabe dowody lub jest sprzeczna z wybranym materiałem, przed otwarciem issue zbierz dane diagnostyczne zgodnie z [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md).+Jeśli odpowiedź pomija wcześniejsze ograniczenie, przywołuje słabe dowody lub jest sprzeczna z wybranym materiałem, przed otwarciem issue zbierz dane diagnostyczne zgodnie z [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md).<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="Strona główna DeepTutor i nawigacja po obszarach roboczych" width="900">@@ -563,7 +563,7 @@ Bazy wiedzy to kolekcje dokumentów za RAG — ugruntowują tury Chat, edycje no<img src="../../assets/figs/web-dev/knowledge-create.png" alt="Tworzenie bazy wiedzy" width="900"></div>-Przenosisz 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.+Przenosisz istniejącą bibliotekę Obsidian, Hermes lub Markdown? Zobacz [przewodnik po migracji wiedzy](../../docs-for-dev/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. 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/eval-diff/set-default/delete`, polecenia dodawania/usuwania źródeł, `list-sources` i `sync`.@@ -640,7 +640,7 @@ Podczas logowania i przy **Refresh models** DeepTutor odczytuje najnowszą stabiHistoria udanych wersji przetrwa odnowienie tokena tego samego konta i błędy uwierzytelniania katalogu, bez przywracania użyteczności unieważnionych danych modelu czy ETagów. Wylogowanie czyści lokalną pamięć podręczną tego konta, w tym historię wersji. Zwykłe odczyty stanu i inferencja nie zapytują npm. Nowe wpisy katalogu nie zastępują już wybranego modelu ani nie restartują sesji nauki; obecność w katalogu nie ustanawia pełnej kompatybilności protokołu inferencji. Nie istnieje żaden działający w tle aktualizator wersji ani ustawienie wersji dla użytkownika.-Domyślne lokalne wdrożenia Docker i Podman używają oddzielnych sieci loopback i podczas logowania wymagają tymczasowego mostu. Postępuj zgodnie z [przewodnikiem po tymczasowym lokalnym moście OAuth Codex](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge), aby poznać dokładne komendy dla Docker, Compose, Podman i demontażu.+Domyślne lokalne wdrożenia Docker i Podman używają oddzielnych sieci loopback i podczas logowania wymagają tymczasowego mostu. Postępuj zgodnie z [przewodnikiem po tymczasowym lokalnym moście OAuth Codex](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge), aby poznać dokładne komendy dla Docker, Compose, Podman i demontażu.Dla zdalnego wdrożenia `localhost` przeglądarki i `localhost` serwera to dwie różne maszyny, więc sam zwykły reverse proxy nie może przenieść callbacku localhost przeglądarki do serwera. Użyj tunelu SSH jako mostu callback. Tunel dociera do już opublikowanego portu Web; Next.js przepisuje wyłącznie dokładną ścieżkę callback do publicznego brokera callback, a broker waliduje `state` przed przekierowaniem do pierwotnej operacji OAuth. Nasłuch callback pozostaje na loopbacku backendu, porty `1455` i `1457` nie są publikowane, a ta ścieżka obsługuje domyślną sieć bridge Dockera.@@ -724,7 +724,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-Repozytorium zawiera główny [`SKILL.md`](../../SKILL.md) — zwięzły dokument przekazujący agentowi wiedzę o CLI. Jawnie poproś agenta o jego przeczytanie; [przewodnik konfiguracji przez agenta](../../docs-for-user/AGENT_SETUP.md) opisuje instalację i konfigurację. Możesz również opakować `deeptutor run` jako narzędzie w pętli LangChain / AutoGen. Pełne przepisy: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+Repozytorium zawiera główny [`SKILL.md`](../../SKILL.md) — zwięzły dokument przekazujący agentowi wiedzę o CLI. Jawnie poproś agenta o jego przeczytanie; [przewodnik konfiguracji przez agenta](../../docs-for-dev/AGENT_SETUP.md) opisuje instalację i konfigurację. Możesz również opakować `deeptutor run` jako narzędzie w pętli LangChain / AutoGen. Pełne przepisy: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_PT.md b/assets/README/README_PT.mdindex 93c959f1e..9286bbf3b 100644--- a/assets/README/README_PT.md+++ b/assets/README/README_PT.md@@ -79,16 +79,16 @@ Copie este prompt para o seu agente de IA com acesso ao terminal (como Codex ou```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-O [guia de configuração por agentes](../../docs-for-user/AGENT_SETUP.md) cobre todo o processo, incluindo a configuração não interativa pela CLI. Para instalar por conta própria, escolha um dos caminhos abaixo.+O [guia de configuração por agentes](../../docs-for-dev/AGENT_SETUP.md) cobre todo o processo, incluindo a configuração não interativa pela CLI. Para instalar por conta própria, escolha um dos caminhos abaixo.-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). Consulte [Persistência de Dados Locais](../../docs-for-user/DATA_STORAGE.md) para o layout completo de armazenamento, o suporte de bases de dados e as notas de cópia de segurança. Para a aplicação completa, o fluxo recomendado é **escolher um diretório de runtime → 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). Consulte [Persistência de Dados Locais](../../docs-for-dev/DATA_STORAGE.md) para o layout completo de armazenamento, o suporte de bases de dados e as notas de cópia de segurança. 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@@ -117,7 +117,7 @@ deeptutor workspace resetAs capacidades inspecionam o workspace selecionado através das ferramentas de workspace integradas. O modelo recebe apenas caminhos relativos como `outputs/...`; quando usa `workspace_present`, a UI apresenta um instantâneo autenticado e que pode ser aberto. O mesmo caminho relativo exato também funciona num link ou imagem Markdown normal. Alterar o ficheiro de origem mais tarde não altera um instantâneo já apresentado.-O Espaço de Aprendizado gere a biblioteca de recursos. Em **Settings → Workspaces**, atribua Skills, serviços MCP e bases de conhecimento a cada workspace, ou mantenha as suas regras de acesso existentes. Os workspaces existentes conservam o acesso atual até que seja guardada uma seleção. As atribuições referenciam os recursos originais sem copiar credenciais nem índices de conhecimento; as skills específicas de um workspace podem substituir as versões partilhadas. Consulte as [atribuições de recursos do workspace](../../docs-for-user/workspaces.md).+O Espaço de Aprendizado gere a biblioteca de recursos. Em **Settings → Workspaces**, atribua Skills, serviços MCP e bases de conhecimento a cada workspace, ou mantenha as suas regras de acesso existentes. Os workspaces existentes conservam o acesso atual até que seja guardada uma seleção. As atribuições referenciam os recursos originais sem copiar credenciais nem índices de conhecimento; as skills específicas de um workspace podem substituir as versões partilhadas. Consulte as [atribuições de recursos do workspace](../../docs-for-dev/workspaces.md).A execução é apenas de leitura fora de `outputs/`. Copiar um ficheiro gerado para outro local dentro do content workspace requer uma confirmação explícita **Allow once** para essa origem e destino exatos. Uma sandbox de sistema ou o executor Docker aplica esse limite quando disponível; o fallback local de subprocesso restrito é apresentado como **best effort** nas definições de Workspace.@@ -222,7 +222,7 @@ Um contentor para a aplicação web completa. Imagens no GitHub Container Regist- `ghcr.io/hkuds/deeptutor:latest` — lançamento estável mais recente- `ghcr.io/hkuds/deeptutor:<version>` — lançamento exato sem o `v` inicial (por exemplo, `:1.6.3`); os pré-lançamentos recebem apenas a respetiva tag de versão-> Consulte [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) para implementações podman/rootless/read-only-rootfs e o guia completo por instalação.+> Consulte [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) para implementações podman/rootless/read-only-rootfs e o guia completo por instalação.```bashdocker run --rm --name deeptutor \@@ -292,7 +292,7 @@ Depois em **Settings → Providers**, aponte o URL Base do provedor para `host.dO Docker Desktop (macOS/Windows) geralmente resolve `host.docker.internal` sem `--add-host`. No Linux, o flag é a forma portátil de criar esse nome de host no Docker Engine moderno.-**Alternativa para Linux — rede do host:** adicione `--network=host` e remova os flags `-p`. O contentor partilha a rede do host diretamente, por isso abra [http://127.0.0.1:3782](http://127.0.0.1:3782) (ou o `frontend_port` em `system.json`), e os serviços do host podem ser alcançados com URLs de localhost normais como `http://127.0.0.1:11434/v1`. Note que a rede do host expõe as portas do contentor diretamente no host e pode entrar em conflito com serviços existentes — para os manter no loopback, defina `BACKEND_HOST=127.0.0.1` e `FRONTEND_HOST=127.0.0.1` (consulte [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**Alternativa para Linux — rede do host:** adicione `--network=host` e remova os flags `-p`. O contentor partilha a rede do host diretamente, por isso abra [http://127.0.0.1:3782](http://127.0.0.1:3782) (ou o `frontend_port` em `system.json`), e os serviços do host podem ser alcançados com URLs de localhost normais como `http://127.0.0.1:11434/v1`. Note que a rede do host expõe as portas do contentor diretamente no host e pode entrar em conflito com serviços existentes — para os manter no loopback, defina `BACKEND_HOST=127.0.0.1` e `FRONTEND_HOST=127.0.0.1` (consulte [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -425,7 +425,7 @@ O DeepTutor separa o código instalado, o seu espaço de trabalho de runtime priComece por um **workspace** para uma disciplina ou projeto. A **Página inicial**, a **Aprendizagem** e os **Recursos** guardam as suas conversas, atividades de aprendizagem e materiais. Os **Partners** e a **Personalização** acompanham a conta entre workspaces. O tour abaixo mostra como estas áreas se ligam, seguido das configurações e da implementação multi-utilizador.-Se uma resposta perder uma restrição anterior, citar evidências fracas ou discordar do material selecionado, recolha os diagnósticos em [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) antes de abrir uma issue.+Se uma resposta perder uma restrição anterior, citar evidências fracas ou discordar do material selecionado, recolha os diagnósticos em [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) antes de abrir uma issue.<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="Página inicial e navegação entre workspaces do DeepTutor" width="900">@@ -563,7 +563,7 @@ As bases de conhecimento são as coleções de documentos por trás do RAG — f<img src="../../assets/figs/web-dev/knowledge-create.png" alt="Criar uma base de conhecimento" width="900"></div>-Vai 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.+Vai migrar uma biblioteca Obsidian, Hermes ou Markdown existente? Consulte o [guia de migração de Knowledge](../../docs-for-dev/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 — 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/eval-diff/set-default/delete`, comandos para adicionar ou remover fontes, `list-sources` e `sync`.@@ -641,7 +641,7 @@ No início de sessão e em **Refresh models**, o DeepTutor lê a última versãoO histórico de versões bem-sucedido sobrevive à renovação de token da mesma conta e a erros de autenticação do catálogo, sem tornar novamente utilizáveis dados de modelo ou ETags invalidados. Terminar sessão limpa a cache local dessa conta, incluindo o histórico de versões. As leituras de estado normais e a inferência não consultam o npm. Novas entradas do catálogo não substituem um modelo já selecionado nem reiniciam sessões de aprendizagem em curso; aparecer no catálogo não estabelece compatibilidade total do protocolo de inferência. Não existe um atualizador de versão em segundo plano nem uma definição de versão pelo utilizador.-As implementações locais predefinidas com Docker e Podman usam redes loopback separadas e precisam de uma ponte temporária durante o início de sessão. Siga o [guia da ponte OAuth temporária local do Codex](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) para os comandos exatos de Docker, Compose, Podman e desmontagem.+As implementações locais predefinidas com Docker e Podman usam redes loopback separadas e precisam de uma ponte temporária durante o início de sessão. Siga o [guia da ponte OAuth temporária local do Codex](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) para os comandos exatos de Docker, Compose, Podman e desmontagem.Para uma implementação remota, o `localhost` do navegador e o `localhost` do servidor são máquinas diferentes, pelo que um proxy inverso comum sozinho não consegue transportar o callback localhost do navegador até ao servidor. Use um túnel SSH como ponte de callback. O túnel alcança a porta Web já publicada; o Next.js reencaminha apenas o caminho exato de callback para o broker de callback público, e o broker valida `state` antes de encaminhar para a operação OAuth original. O listener de callback permanece no loopback do backend, as portas `1455` e `1457` não são publicadas, e este caminho suporta a rede bridge predefinida do Docker.@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-O repositório inclui um [`SKILL.md`](../../SKILL.md) na raiz — um documento compacto de orientação para a CLI. Peça ao seu agente para o ler explicitamente; o respetivo [guia de configuração por agentes](../../docs-for-user/AGENT_SETUP.md) cobre a instalação e a configuração. Também pode envolver `deeptutor run` como uma ferramenta num loop LangChain / AutoGen. Receitas completas: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+O repositório inclui um [`SKILL.md`](../../SKILL.md) na raiz — um documento compacto de orientação para a CLI. Peça ao seu agente para o ler explicitamente; o respetivo [guia de configuração por agentes](../../docs-for-dev/AGENT_SETUP.md) cobre a instalação e a configuração. Também pode envolver `deeptutor run` como uma ferramenta num loop LangChain / AutoGen. Receitas completas: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_RU.md b/assets/README/README_RU.mdindex 92938de70..ee8e82b0a 100644--- a/assets/README/README_RU.md+++ b/assets/README/README_RU.md@@ -80,16 +80,16 @@ DeepTutor — это агентная учебная рабочая среда,```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[Руководство по настройке с помощью агента](../../docs-for-user/AGENT_SETUP.md) описывает весь процесс, включая неинтерактивную настройку через CLI. Для самостоятельной установки выберите один из способов ниже.+[Руководство по настройке с помощью агента](../../docs-for-dev/AGENT_SETUP.md) описывает весь процесс, включая неинтерактивную настройку через CLI. Для самостоятельной установки выберите один из способов ниже.-DeepTutor поставляется с четырьмя путями установки. Все они используют одну структуру каталога среды выполнения: приватные настройки хранятся в `data/user/settings/` в директории запуска (или в `DEEPTUTOR_HOME` / `deeptutor start --home`, если задано явно). Полная структура хранения, поддержка баз данных и рекомендации по резервному копированию описаны в разделе [Локальное хранение данных](../../docs-for-user/DATA_STORAGE.md). Для полного приложения рекомендуемый процесс: **выбрать каталог среды выполнения → установить → `deeptutor init` → `deeptutor start`**.+DeepTutor поставляется с четырьмя путями установки. Все они используют одну структуру каталога среды выполнения: приватные настройки хранятся в `data/user/settings/` в директории запуска (или в `DEEPTUTOR_HOME` / `deeptutor start --home`, если задано явно). Полная структура хранения, поддержка баз данных и рекомендации по резервному копированию описаны в разделе [Локальное хранение данных](../../docs-for-dev/DATA_STORAGE.md). Для полного приложения рекомендуемый процесс: **выбрать каталог среды выполнения → установить → `deeptutor init` → `deeptutor start`**.### Пробный запуск Docker одной командой@@ -118,7 +118,7 @@ deeptutor workspace resetВозможности просматривают выбранное рабочее пространство через встроенные инструменты рабочего пространства. Модель получает только относительные пути вроде `outputs/...`; когда она использует `workspace_present`, интерфейс отображает аутентифицированный, открываемый снимок. Тот же самый относительный путь работает и в обычной Markdown-ссылке или изображении. Последующее изменение исходного файла не меняет уже представленный снимок.-Пространство Обучения управляет библиотекой ресурсов. В **Настройки → Рабочие пространства** можно назначить каждому пространству навыки, MCP-сервисы и базы знаний или сохранить существующие правила доступа. Существующие пространства сохраняют текущий доступ, пока новый выбор не будет сохранён. Назначения ссылаются на исходные ресурсы без копирования учётных данных или индексов знаний; навыки конкретного пространства могут переопределять общие версии. См. [назначение ресурсов рабочим пространствам](../../docs-for-user/workspaces.md).+Пространство Обучения управляет библиотекой ресурсов. В **Настройки → Рабочие пространства** можно назначить каждому пространству навыки, MCP-сервисы и базы знаний или сохранить существующие правила доступа. Существующие пространства сохраняют текущий доступ, пока новый выбор не будет сохранён. Назначения ссылаются на исходные ресурсы без копирования учётных данных или индексов знаний; навыки конкретного пространства могут переопределять общие версии. См. [назначение ресурсов рабочим пространствам](../../docs-for-dev/workspaces.md).Выполнение доступно только для чтения за пределами `outputs/`. Копирование созданного файла в другое место Рабочего пространства для контента требует явного подтверждения **Разрешить один раз** для конкретной пары источник/назначение. Системная песочница или Docker runner обеспечивают эту границу, когда доступны; локальный резервный вариант с ограниченным подпроцессом отображается в настройках рабочего пространства как **выполняется по возможности (best effort)**.@@ -223,7 +223,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — последний стабильный выпуск- `ghcr.io/hkuds/deeptutor:<version>` — точный выпуск без начальной `v` (например, `:1.6.3`); предварительные выпуски получают только собственный тег версии-> Смотрите [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) для развёртываний на podman/rootless/read-only-rootfs и полного руководства по установке.+> Смотрите [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) для развёртываний на podman/rootless/read-only-rootfs и полного руководства по установке.```bashdocker run --rm --name deeptutor \@@ -293,7 +293,7 @@ docker run --rm --name deeptutor \Docker Desktop (macOS/Windows) обычно разрешает `host.docker.internal` без `--add-host`. На Linux этот флаг — переносимый способ создания этого имени хоста в современном Docker Engine.-**Альтернатива для Linux — сетевой режим хоста:** добавьте `--network=host` и уберите флаги `-p`. Контейнер напрямую использует сеть хоста, поэтому откройте [http://127.0.0.1:3782](http://127.0.0.1:3782) (или `frontend_port` в `system.json`), а сервисы хоста доступны через обычные localhost-URL, например `http://127.0.0.1:11434/v1`. Обратите внимание, что хостовый сетевой режим открывает порты контейнера напрямую на хосте и может конфликтовать с существующими сервисами — чтобы оставить их на loopback, установите `BACKEND_HOST=127.0.0.1` и `FRONTEND_HOST=127.0.0.1` (см. [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)).+**Альтернатива для Linux — сетевой режим хоста:** добавьте `--network=host` и уберите флаги `-p`. Контейнер напрямую использует сеть хоста, поэтому откройте [http://127.0.0.1:3782](http://127.0.0.1:3782) (или `frontend_port` в `system.json`), а сервисы хоста доступны через обычные localhost-URL, например `http://127.0.0.1:11434/v1`. Обратите внимание, что хостовый сетевой режим открывает порты контейнера напрямую на хосте и может конфликтовать с существующими сервисами — чтобы оставить их на loopback, установите `BACKEND_HOST=127.0.0.1` и `FRONTEND_HOST=127.0.0.1` (см. [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)).</details>@@ -426,7 +426,7 @@ DeepTutor отделяет установленный код, приватноеНачните с **рабочего пространства** для предмета или проекта. Его разделы **Главная**, **Обучение** и **Ресурсы** содержат ваши разговоры, учебные занятия и материалы. **Partners** и **Персонализация** остаются связанными с учётной записью при переходе между рабочими пространствами. Далее показано, как связаны эти разделы, а затем описаны настройки и многопользовательское развёртывание.-Если ответ теряет ранее заданное ограничение, ссылается на слабые доказательства или противоречит выбранному материалу, соберите диагностические данные по [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md), прежде чем открывать issue.+Если ответ теряет ранее заданное ограничение, ссылается на слабые доказательства или противоречит выбранному материалу, соберите диагностические данные по [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md), прежде чем открывать issue.<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="Главная страница DeepTutor и навигация по рабочему пространству" width="900">@@ -564,7 +564,7 @@ Grok использует собственную аутентификацию и<img src="../../assets/figs/web-dev/knowledge-create.png" alt="Создание базы знаний" width="900"></div>-Переносите существующую библиотеку Obsidian, Hermes или Markdown? В [руководстве по миграции знаний](../../docs-for-user/KNOWLEDGE_MIGRATION.md) описаны варианты с подключённым хранилищем и индексированной копией.+Переносите существующую библиотеку Obsidian, Hermes или Markdown? В [руководстве по миграции знаний](../../docs-for-dev/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/eval/eval-diff/set-default/delete`, команды добавления/удаления источников, `list-sources` и `sync`.@@ -642,7 +642,7 @@ Grok использует собственную аутентификацию иИстория успешных версий сохраняется при обновлении токена той же учётной записи и при ошибках аутентификации каталога, но не делает недействительные данные модели или ETags снова пригодными для использования. Выход из системы очищает локальный кэш этой учётной записи, включая историю версий. Обычные проверки состояния и инференс не обращаются к npm. Новые записи каталога не заменяют уже выбранную вами модель и не перезапускают учебные сессии; появление в каталоге не означает полную совместимость протокола инференса. Фонового обновления версий или настройки версии пользователем не существует.-Локальные развёртывания Docker и Podman по умолчанию используют раздельные loopback-сети и во время входа требуют временного моста. Следуйте [руководству по временному локальному мосту Codex OAuth](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) для точных команд Docker, Compose, Podman и отключения моста.+Локальные развёртывания Docker и Podman по умолчанию используют раздельные loopback-сети и во время входа требуют временного моста. Следуйте [руководству по временному локальному мосту Codex OAuth](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) для точных команд Docker, Compose, Podman и отключения моста.При удалённом развёртывании `localhost` браузера и `localhost` сервера — это разные машины, поэтому обычный обратный прокси сам по себе не может доставить обратный вызов (callback) с localhost браузера на сервер. Используйте SSH-туннель в качестве моста для обратного вызова. Туннель ведёт к уже опубликованному порту Web; Next.js переписывает только точный путь обратного вызова на публичный брокер обратных вызовов, а брокер проверяет `state`, прежде чем перенаправить к исходной операции OAuth. Слушатель обратного вызова остаётся на loopback-интерфейсе бэкенда, порты `1455` и `1457` не публикуются, и этот путь поддерживает сеть Docker bridge по умолчанию.@@ -726,7 +726,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-В репозитории есть корневой [`SKILL.md`](../../SKILL.md) — краткое руководство для агента по работе с CLI. Явно попросите агента прочитать его; [руководство по настройке с помощью агента](../../docs-for-user/AGENT_SETUP.md) описывает установку и конфигурацию. Также можно обернуть `deeptutor run` как инструмент в цикл LangChain / AutoGen. Полные рецепты: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).+В репозитории есть корневой [`SKILL.md`](../../SKILL.md) — краткое руководство для агента по работе с CLI. Явно попросите агента прочитать его; [руководство по настройке с помощью агента](../../docs-for-dev/AGENT_SETUP.md) описывает установку и конфигурацию. Также можно обернуть `deeptutor run` как инструмент в цикл LangChain / AutoGen. Полные рецепты: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).</details>diff --git a/assets/README/README_TH.md b/assets/README/README_TH.mdindex 60562cd20..15cc555e5 100644--- a/assets/README/README_TH.md+++ b/assets/README/README_TH.md@@ -80,16 +80,16 @@ DeepTutor คือ workspace การเรียนรู้แบบ agent-n```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[คู่มือ Agent Setup](../../docs-for-user/AGENT_SETUP.md) ครอบคลุมขั้นตอนทั้งหมด รวมถึงการกำหนดค่าผ่าน CLI แบบไม่โต้ตอบ หากต้องการติดตั้งด้วยตัวเอง ให้เลือกหนึ่งในเส้นทางด้านล่าง+[คู่มือ Agent Setup](../../docs-for-dev/AGENT_SETUP.md) ครอบคลุมขั้นตอนทั้งหมด รวมถึงการกำหนดค่าผ่าน CLI แบบไม่โต้ตอบ หากต้องการติดตั้งด้วยตัวเอง ให้เลือกหนึ่งในเส้นทางด้านล่าง-DeepTutor มีเส้นทางการติดตั้งสี่เส้นทาง ทั้งหมดแชร์ layout runtime home เดียวกัน: การตั้งค่าส่วนตัวอยู่ใน `data/user/settings/` ภายใต้ไดเร็กทอรีที่คุณเปิดตัว (หรือภายใต้ `DEEPTUTOR_HOME` / `deeptutor start --home` หากคุณตั้งค่าไว้อย่างชัดเจน) ดู [การจัดเก็บข้อมูลในเครื่องอย่างถาวร](../../docs-for-user/DATA_STORAGE.md) สำหรับ layout การจัดเก็บทั้งหมด การรองรับฐานข้อมูล และคำแนะนำในการสำรองข้อมูล สำหรับแอปเต็มรูปแบบ ขั้นตอนที่แนะนำคือ **เลือกไดเร็กทอรี runtime home → ติดตั้ง → `deeptutor init` → `deeptutor start`**+DeepTutor มีเส้นทางการติดตั้งสี่เส้นทาง ทั้งหมดแชร์ layout runtime home เดียวกัน: การตั้งค่าส่วนตัวอยู่ใน `data/user/settings/` ภายใต้ไดเร็กทอรีที่คุณเปิดตัว (หรือภายใต้ `DEEPTUTOR_HOME` / `deeptutor start --home` หากคุณตั้งค่าไว้อย่างชัดเจน) ดู [การจัดเก็บข้อมูลในเครื่องอย่างถาวร](../../docs-for-dev/DATA_STORAGE.md) สำหรับ layout การจัดเก็บทั้งหมด การรองรับฐานข้อมูล และคำแนะนำในการสำรองข้อมูล สำหรับแอปเต็มรูปแบบ ขั้นตอนที่แนะนำคือ **เลือกไดเร็กทอรี runtime home → ติดตั้ง → `deeptutor init` → `deeptutor start`**### ทดลองใช้ Docker ด้วยคำสั่งเดียว@@ -118,7 +118,7 @@ deeptutor workspace resetแต่ละความสามารถตรวจสอบ workspace ที่เลือกผ่านเครื่องมือ workspace ในตัว model จะได้รับเฉพาะ relative path เช่น `outputs/...`; เมื่อ model ใช้ `workspace_present` UI จะ render snapshot ที่ authenticated และเปิดได้ relative path เดียวกันเป๊ะนี้ยังใช้ได้ในลิงก์หรือรูปภาพ Markdown ปกติ การเปลี่ยนไฟล์ต้นทางในภายหลังจะไม่เปลี่ยน snapshot ที่นำเสนอไปแล้ว-Learning Space จัดการไลบรารีทรัพยากร ใน **Settings → Workspaces** ให้กำหนด Skills, บริการ MCP และ knowledge bases ให้แต่ละ workspace หรือคงกฎการเข้าถึงเดิมไว้ workspace ที่มีอยู่จะคงสิทธิ์การเข้าถึงปัจจุบันจนกว่าจะบันทึกการเลือก การกำหนดทรัพยากรจะอ้างอิงต้นฉบับโดยไม่คัดลอก credentials หรือดัชนีความรู้ และ skills เฉพาะ workspace สามารถแทนที่เวอร์ชันที่แชร์ได้ ดู[การกำหนดทรัพยากรให้ workspace](../../docs-for-user/workspaces.md)+Learning Space จัดการไลบรารีทรัพยากร ใน **Settings → Workspaces** ให้กำหนด Skills, บริการ MCP และ knowledge bases ให้แต่ละ workspace หรือคงกฎการเข้าถึงเดิมไว้ workspace ที่มีอยู่จะคงสิทธิ์การเข้าถึงปัจจุบันจนกว่าจะบันทึกการเลือก การกำหนดทรัพยากรจะอ้างอิงต้นฉบับโดยไม่คัดลอก credentials หรือดัชนีความรู้ และ skills เฉพาะ workspace สามารถแทนที่เวอร์ชันที่แชร์ได้ ดู[การกำหนดทรัพยากรให้ workspace](../../docs-for-dev/workspaces.md)การรันโค้ดเป็นแบบ read-only นอก `outputs/` การคัดลอกไฟล์ที่สร้างขึ้นไปยังที่อื่นใน content workspace ต้องมีการยืนยัน **Allow once** อย่างชัดเจนสำหรับ@@ -227,7 +227,7 @@ Container เดียวสำหรับแอป Web แบบเต็ม- `ghcr.io/hkuds/deeptutor:latest` — รุ่นเสถียรล่าสุด- `ghcr.io/hkuds/deeptutor:<version>` — รุ่นที่ระบุแบบตรงตัวโดยไม่มี `v` นำหน้า (เช่น `:1.6.3`); รุ่นก่อนเผยแพร่จะได้รับเฉพาะแท็กเวอร์ชันของตน-> ดู [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md) สำหรับการปรับใช้ podman/rootless/read-only-rootfs และคู่มือต่อการติดตั้งแบบครบถ้วน+> ดู [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md) สำหรับการปรับใช้ podman/rootless/read-only-rootfs และคู่มือต่อการติดตั้งแบบครบถ้วน```bashdocker run --rm --name deeptutor \@@ -301,7 +301,7 @@ docker run --rm --name deeptutor \Docker Desktop (macOS/Windows) มักจะ resolve `host.docker.internal` ได้โดยไม่ต้องใช้ `--add-host` บน Linux ตัวเลือกนี้คือวิธีที่ portable ในการสร้าง hostname บน Docker Engine สมัยใหม่-**ทางเลือกบน Linux — host networking:** เพิ่ม `--network=host` และลบ flags `-p` ออก Container จะแชร์ network ของ host โดยตรง เปิด [http://127.0.0.1:3782](http://127.0.0.1:3782) (หรือ `frontend_port` ใน `system.json`) และ services ของ host สามารถเข้าถึงได้ด้วย localhost URLs ปกติ เช่น `http://127.0.0.1:11434/v1` โปรดทราบว่า host networking จะเปิดเผยพอร์ต container โดยตรงบน host และอาจขัดแย้งกับ services ที่มีอยู่ — หากต้องการเก็บไว้บน loopback ให้ตั้ง `BACKEND_HOST=127.0.0.1` และ `FRONTEND_HOST=127.0.0.1` (ดู [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md))+**ทางเลือกบน Linux — host networking:** เพิ่ม `--network=host` และลบ flags `-p` ออก Container จะแชร์ network ของ host โดยตรง เปิด [http://127.0.0.1:3782](http://127.0.0.1:3782) (หรือ `frontend_port` ใน `system.json`) และ services ของ host สามารถเข้าถึงได้ด้วย localhost URLs ปกติ เช่น `http://127.0.0.1:11434/v1` โปรดทราบว่า host networking จะเปิดเผยพอร์ต container โดยตรงบน host และอาจขัดแย้งกับ services ที่มีอยู่ — หากต้องการเก็บไว้บน loopback ให้ตั้ง `BACKEND_HOST=127.0.0.1` และ `FRONTEND_HOST=127.0.0.1` (ดู [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md))</details>@@ -434,7 +434,7 @@ DeepTutor แยกโค้ดที่ติดตั้ง, runtime home สเริ่มต้นด้วย **workspace** สำหรับวิชาหรือโปรเจกต์ โดย **Home**, **Learning** และ **Resources** เก็บบทสนทนา กิจกรรมการเรียน และสื่อการเรียนของคุณ ส่วน **Partners** และ **Personalization** จะผูกกับบัญชีของคุณข้าม workspaces การสำรวจด้านล่างแสดงให้เห็นว่าส่วนเหล่านี้เชื่อมต่อกันอย่างไร ตามด้วยการตั้งค่าและการปรับใช้แบบ multi-user-หากคำตอบทำข้อกำหนดก่อนหน้าหลุดหาย, อ้างหลักฐานที่อ่อน หรือไม่สอดคล้องกับสื่อที่เลือก ให้รวบรวมข้อมูลวินิจฉัยตาม [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md) ก่อนเปิด issue+หากคำตอบทำข้อกำหนดก่อนหน้าหลุดหาย, อ้างหลักฐานที่อ่อน หรือไม่สอดคล้องกับสื่อที่เลือก ให้รวบรวมข้อมูลวินิจฉัยตาม [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md) ก่อนเปิด issue<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="หน้า Home และการนำทาง workspace ของ DeepTutor" width="900">@@ -592,7 +592,7 @@ Knowledge bases คือคอลเลกชันเอกสารที่<img src="../../assets/figs/web-dev/knowledge-create.png" alt="สร้าง knowledge base" width="900"></div>-กำลังย้ายไลบรารี Obsidian, Hermes หรือ Markdown ที่มีอยู่ใช่ไหม ดู [คู่มือการย้ายข้อมูล Knowledge](../../docs-for-user/KNOWLEDGE_MIGRATION.md) สำหรับเส้นทางแบบ connected-vault และ indexed-copy+กำลังย้ายไลบรารี Obsidian, Hermes หรือ Markdown ที่มีอยู่ใช่ไหม ดู [คู่มือการย้ายข้อมูล Knowledge](../../docs-for-dev/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/eval/eval-diff/set-default/delete`, คำสั่งเพิ่ม/ลบ source, `list-sources` และ `sync`@@ -670,7 +670,7 @@ Settings คือศูนย์ควบคุมการทำงาน โประวัติเวอร์ชันที่สำเร็จจะยังอยู่รอดผ่านการ renew token ของบัญชีเดิมและข้อผิดพลาด authentication ของ catalog โดยไม่ทำให้ model data หรือ ETags ที่ invalidate แล้วกลับมาใช้ได้อีก การลงชื่อออกจะล้าง local cache ของบัญชีนั้น รวมถึงประวัติเวอร์ชันด้วย การอ่านสถานะปกติและ inference จะไม่ query npm รายการ catalog ใหม่จะไม่แทนที่ model ที่คุณเลือกไว้แล้วหรือรีสตาร์ท learning session; การปรากฏใน catalog ไม่ได้เป็นการยืนยันความเข้ากันได้ของ inference protocol แบบสมบูรณ์ ไม่มี background version updater หรือ user version setting-การปรับใช้ Docker และ Podman บนเครื่อง local แบบเริ่มต้นใช้ loopback network แยกจากกัน และต้องการสะพานเชื่อมชั่วคราวระหว่างการลงชื่อเข้าใช้ ทำตาม [คู่มือสะพานเชื่อม Codex OAuth ชั่วคราวสำหรับเครื่อง local](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) สำหรับคำสั่ง Docker, Compose, Podman และ teardown ที่แน่นอน+การปรับใช้ Docker และ Podman บนเครื่อง local แบบเริ่มต้นใช้ loopback network แยกจากกัน และต้องการสะพานเชื่อมชั่วคราวระหว่างการลงชื่อเข้าใช้ ทำตาม [คู่มือสะพานเชื่อม Codex OAuth ชั่วคราวสำหรับเครื่อง local](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge) สำหรับคำสั่ง Docker, Compose, Podman และ teardown ที่แน่นอนสำหรับการปรับใช้แบบ remote `localhost` ของเบราว์เซอร์และ `localhost` ของเซิร์ฟเวอร์คือคนละเครื่องกัน ดังนั้น reverse proxy ธรรมดาเพียงอย่างเดียวไม่สามารถส่ง callback แบบ localhost ของเบราว์เซอร์ไปถึงเซิร์ฟเวอร์ได้ ให้ใช้ SSH tunnel เป็นสะพานเชื่อม callback ตัว tunnel จะไปถึงพอร์ต Web ที่เผยแพร่อยู่แล้ว; Next.js จะ rewrite เฉพาะ callback path ที่ตรงเป๊ะไปยัง public callback broker เท่านั้น และ broker จะตรวจสอบ `state` ก่อนที่จะ route ไปยัง OAuth operation ต้นทาง callback listener ยังคงอยู่ที่ backend loopback พอร์ต `1455` และ `1457` จะไม่ถูกเผยแพร่ และเส้นทางนี้รองรับ Docker bridge network เริ่มต้น@@ -754,7 +754,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-repo มี root [`SKILL.md`](../../SKILL.md) — เอกสาร handover แบบกระชับสำหรับ CLI ขอให้ agent ของคุณอ่านไฟล์นี้อย่างชัดเจน; [คู่มือ Agent Setup](../../docs-for-user/AGENT_SETUP.md) ครอบคลุมการติดตั้งและการกำหนดค่า คุณยังสามารถ wrap `deeptutor run` เป็นเครื่องมือใน LangChain / AutoGen loop ได้ด้วย สูตรเต็ม: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)+repo มี root [`SKILL.md`](../../SKILL.md) — เอกสาร handover แบบกระชับสำหรับ CLI ขอให้ agent ของคุณอ่านไฟล์นี้อย่างชัดเจน; [คู่มือ Agent Setup](../../docs-for-dev/AGENT_SETUP.md) ครอบคลุมการติดตั้งและการกำหนดค่า คุณยังสามารถ wrap `deeptutor run` เป็นเครื่องมือใน LangChain / AutoGen loop ได้ด้วย สูตรเต็ม: [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)</details>diff --git a/assets/README/README_TW.md b/assets/README/README_TW.mdindex d648952ff..812fa7672 100644--- a/assets/README/README_TW.md+++ b/assets/README/README_TW.md@@ -79,16 +79,16 @@ DeepTutor 是代理程式原生的學習工作區,在同一個可擴充系統```textHelp me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.Clone the dev branch, or inspect and reuse my existing checkout, and read SKILL.md and-docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,+docs-for-dev/AGENT_SETUP.md first. Follow that guide to prepare the environment,configure my model provider, verify the setup, and start the Web app.Ask me for any missing provider, model, or credential-source information;do not print API keys. Preserve my existing files and settings, and finishwith the access URL and the results of your checks.```-[代理程式設定指南](../../docs-for-user/AGENT_SETUP.md)涵蓋完整流程,包括非互動式 CLI 設定。若要自行安裝,請選擇下列其中一種方式。+[代理程式設定指南](../../docs-for-dev/AGENT_SETUP.md)涵蓋完整流程,包括非互動式 CLI 設定。若要自行安裝,請選擇下列其中一種方式。-DeepTutor 提供四種安裝方式,皆共用同一套執行環境目錄配置:私有設定會儲存在啟動目錄下的 `data/user/settings/`(若明確設定 `DEEPTUTOR_HOME` 或 `deeptutor start --home`,則改儲存在該位置)。請參閱[本機資料持久化](../../docs-for-user/DATA_STORAGE.md),了解完整的儲存配置、資料庫支援與備份說明。完整應用程式的建議流程是:**選擇一個執行環境目錄 → 安裝 → `deeptutor init` → `deeptutor start`**。+DeepTutor 提供四種安裝方式,皆共用同一套執行環境目錄配置:私有設定會儲存在啟動目錄下的 `data/user/settings/`(若明確設定 `DEEPTUTOR_HOME` 或 `deeptutor start --home`,則改儲存在該位置)。請參閱[本機資料持久化](../../docs-for-dev/DATA_STORAGE.md),了解完整的儲存配置、資料庫支援與備份說明。完整應用程式的建議流程是:**選擇一個執行環境目錄 → 安裝 → `deeptutor init` → `deeptutor start`**。### 一行指令試用 Docker@@ -117,7 +117,7 @@ deeptutor workspace reset各項能力都能透過內建的 workspace 工具檢視所選工作區。模型只會收到 `outputs/...` 之類的相對路徑;當它使用 `workspace_present` 時,UI 會顯示一個已驗證身分、可開啟的快照。同一組相對路徑,在一般的 Markdown 連結或圖片中也同樣可用。日後變更來源檔案,並不會改變已呈現的快照。-Learning Space 管理資源庫。在 **Settings → Workspaces** 中,可為各工作區指派 Skills、MCP 服務與知識庫,或保留原有的存取規則。既有工作區會維持目前的存取權,直到儲存選擇為止。指派會參照原始資源,不會複製憑證或知識索引;工作區專屬技能可以覆寫共用版本。請參閱[工作區資源指派](../../docs-for-user/workspaces.md)。+Learning Space 管理資源庫。在 **Settings → Workspaces** 中,可為各工作區指派 Skills、MCP 服務與知識庫,或保留原有的存取規則。既有工作區會維持目前的存取權,直到儲存選擇為止。指派會參照原始資源,不會複製憑證或知識索引;工作區專屬技能可以覆寫共用版本。請參閱[工作區資源指派](../../docs-for-dev/workspaces.md)。在 `outputs/` 之外,執行動作一律唯讀。若要將生成的檔案複製到內容工作區中的其他位置,必須針對該確切的來源與目的地,明確以 **Allow once** 確認。系統沙箱或 Docker runner(若可用)會強制執行此邊界;本機受限制的子處理程序備援方式,則會在 Workspace 設定中顯示為**盡力而為(best effort)**。@@ -222,7 +222,7 @@ deeptutor start --dev- `ghcr.io/hkuds/deeptutor:latest` — 最新穩定版本- `ghcr.io/hkuds/deeptutor:<version>` — 不含開頭 `v` 的確切版本(例如 `:1.6.3`);預先發行版本只會提供其版本標籤-> 如需 podman/rootless/唯讀 rootfs 部署及各安裝方式的完整指南,請參閱 [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md)。+> 如需 podman/rootless/唯讀 rootfs 部署及各安裝方式的完整指南,請參閱 [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md)。```bashdocker run --rm --name deeptutor \@@ -292,7 +292,7 @@ docker run --rm --name deeptutor \Docker Desktop(macOS/Windows)通常不加 `--add-host` 也能解析 `host.docker.internal`。在 Linux 上,此旗標是在現代 Docker Engine 建立該主機名稱的可攜方式。-**Linux 替代方案 — host networking:** 加上 `--network=host` 並移除 `-p` 旗標。容器會直接共用主機網路,因此請開啟 [http://127.0.0.1:3782](http://127.0.0.1:3782)(或 `system.json` 中的 `frontend_port`),並以一般 localhost URL(例如 `http://127.0.0.1:11434/v1`)連接主機服務。請注意,host networking 會直接在主機上公開容器連接埠,且可能與既有服務衝突;若要讓它們維持在 loopback,請設定 `BACKEND_HOST=127.0.0.1` 與 `FRONTEND_HOST=127.0.0.1`(參閱 [CONTAINERIZATION.md](../../docs-for-user/CONTAINERIZATION.md))。+**Linux 替代方案 — host networking:** 加上 `--network=host` 並移除 `-p` 旗標。容器會直接共用主機網路,因此請開啟 [http://127.0.0.1:3782](http://127.0.0.1:3782)(或 `system.json` 中的 `frontend_port`),並以一般 localhost URL(例如 `http://127.0.0.1:11434/v1`)連接主機服務。請注意,host networking 會直接在主機上公開容器連接埠,且可能與既有服務衝突;若要讓它們維持在 loopback,請設定 `BACKEND_HOST=127.0.0.1` 與 `FRONTEND_HOST=127.0.0.1`(參閱 [CONTAINERIZATION.md](../../docs-for-dev/CONTAINERIZATION.md))。</details>@@ -425,7 +425,7 @@ DeepTutor 會將已安裝的程式碼、私有執行環境目錄與選用的內先為科目或專案建立一個**工作區**。其中的 **Home**、**Learning** 與 **Resources** 分別容納對話、學習活動與素材。**Partners** 與 **Personalization** 隨帳號跨工作區共用。下方導覽會介紹這些介面如何相互連結,接著說明設定與多使用者部署。-如果回答遺漏先前限制、引用薄弱證據,或與所選素材不一致,請先將診斷資料收集到 [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-user/REASONING_SAFETY_CHECKLIST.md),再建立 issue。+如果回答遺漏先前限制、引用薄弱證據,或與所選素材不一致,請先將診斷資料收集到 [`REASONING_SAFETY_CHECKLIST.md`](../../docs-for-dev/REASONING_SAFETY_CHECKLIST.md),再建立 issue。<div align="center"><img src="../../assets/figs/web-dev/overview.png" alt="DeepTutor 首頁與工作區導覽" width="900">@@ -563,7 +563,7 @@ Book 會將選定來源轉換成互動式**活書**;它不是靜態 PDF,而<img src="../../assets/figs/web-dev/knowledge-create.png" alt="建立知識庫" width="900"></div>-要遷移現有的 Obsidian、Hermes 或 Markdown 知識庫嗎?請參閱 [Knowledge 遷移指南](../../docs-for-user/KNOWLEDGE_MIGRATION.md),了解連結 vault 與索引副本兩種方式。+要遷移現有的 Obsidian、Hermes 或 Markdown 知識庫嗎?請參閱 [Knowledge 遷移指南](../../docs-for-dev/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/eval/eval-diff/set-default/delete`、來源新增/移除指令、`list-sources` 與 `sync`。@@ -641,7 +641,7 @@ Settings 是操作控制中心,開啟時會顯示用於設定介面與模型同一帳號的 token 更新,以及型錄驗證錯誤,都不會影響先前已成功記錄的版本歷史;但這不會讓已失效的模型資料或 ETag 重新變得可用。登出會清除該帳號的本機快取,包括版本歷史。一般的狀態讀取與推理呼叫不會查詢 npm。新的型錄項目不會取代你已選用的模型,也不會重新啟動學習工作階段;出現在型錄中並不代表已完整相容於推理協定。目前沒有背景版本更新程式,也沒有使用者可設定的版本選項。-預設本機 Docker 與 Podman 部署各自使用獨立的 loopback 網路,登入期間需要暫時橋接。請依照[暫時性本機 Codex OAuth 橋接指南](../../docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge),使用確切的 Docker、Compose、Podman 與拆除指令。+預設本機 Docker 與 Podman 部署各自使用獨立的 loopback 網路,登入期間需要暫時橋接。請依照[暫時性本機 Codex OAuth 橋接指南](../../docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge),使用確切的 Docker、Compose、Podman 與拆除指令。在遠端部署中,瀏覽器的 `localhost` 與伺服器的 `localhost` 是不同電腦,因此單靠一般反向代理,無法將瀏覽器的 localhost callback 傳送到伺服器。請使用 SSH 通道作為 callback 橋接。此通道會連到已發布的 Web 連接埠;Next.js 只將確切的 callback 路徑改寫至公開 callback broker,broker 驗證 `state` 後再導向原始 OAuth 操作。Callback listener 仍位於後端 loopback,`1455` 與 `1457` 不會發布;此方式支援預設 Docker bridge 網路。@@ -725,7 +725,7 @@ SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json```-repo 根目錄附有 [`SKILL.md`](../../SKILL.md),這是一份精簡的 CLI 交接文件。請明確要求代理程式讀取它;其中的[代理程式設定指南](../../docs-for-user/AGENT_SETUP.md)涵蓋安裝與設定。你也可以在 LangChain/AutoGen 迴圈中將 `deeptutor run` 包裝成工具。完整作法請參閱 [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。+repo 根目錄附有 [`SKILL.md`](../../SKILL.md),這是一份精簡的 CLI 交接文件。請明確要求代理程式讀取它;其中的[代理程式設定指南](../../docs-for-dev/AGENT_SETUP.md)涵蓋安裝與設定。你也可以在 LangChain/AutoGen 迴圈中將 `deeptutor run` 包裝成工具。完整作法請參閱 [Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。</details>diff --git a/assets/releases/past_releases/ver1-4-10.md b/assets/releases/past_releases/ver1-4-10.mdindex 8fada36b3..1d1a813ae 100644--- a/assets/releases/past_releases/ver1-4-10.md+++ b/assets/releases/past_releases/ver1-4-10.md@@ -27,7 +27,7 @@ admin accounts at a glance.### Run DeepTutor in a container, rootless-ready-A new [CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-user/CONTAINERIZATION.md)+A new [CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/CONTAINERIZATION.md)guide covers three shapes — plain `docker run`, `docker compose` with thePocketBase sidecar, and a hardened rootless **Podman** path (`compose.yaml`,read-only root filesystem, tmpfs system dirs) — plus a `.env.example` to startdiff --git a/assets/releases/past_releases/ver1-4-11.md b/assets/releases/past_releases/ver1-4-11.mdindex 716fce5ee..1c3711ad8 100644--- a/assets/releases/past_releases/ver1-4-11.md+++ b/assets/releases/past_releases/ver1-4-11.md@@ -38,7 +38,7 @@ host networking you can keep both services on loopback (`127.0.0.1`) instead ofexposing them on every interface. supervisord now runs as root so services startcorrectly under rootful Docker, and the dead `gosu` / `libcap2-bin` infrastructureis gone — the container follows a single root-supervisord model. See-[CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-user/CONTAINERIZATION.md).+[CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/CONTAINERIZATION.md).### Honest session-loading overlaydiff --git a/assets/releases/past_releases/ver1-5-9.md b/assets/releases/past_releases/ver1-5-9.mdindex d46113a2f..191ec7b9c 100644--- a/assets/releases/past_releases/ver1-5-9.md+++ b/assets/releases/past_releases/ver1-5-9.md@@ -28,7 +28,7 @@ Novita AI joins the LLM gateways (`novita`, `https://api.novita.ai/openai`). Min### Codex sign-in inside a local container-Default local Docker and Podman deployments put the browser and the server on separate loopback networks, so the OAuth callback never arrived. There is now a temporary `compose.codex-oauth.yaml` overlay (and the equivalent `docker`/`podman` commands) that publishes ports `1455`/`1457` only while you sign in — with teardown, so those ports go back to your other Codex clients. See [CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge).+Default local Docker and Podman deployments put the browser and the server on separate loopback networks, so the OAuth callback never arrived. There is now a temporary `compose.codex-oauth.yaml` overlay (and the equivalent `docker`/`podman` commands) that publishes ports `1455`/`1457` only while you sign in — with teardown, so those ports go back to your other Codex clients. See [CONTAINERIZATION.md](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge).### Failures that used to arrive as nothing@@ -44,7 +44,7 @@ A capability that raised — or a request for one that does not exist — ended`pip install -U deeptutor`; Docker users pull `ghcr.io/hkuds/deeptutor:latest`. No schema changes, and nothing to re-index.-- **`docker-compose.ghcr.yml` users: copy your state out before the next `up -d`.** The new whole-tree mount means empty host directories would shadow what is in the container's writable layer, regenerating the auth secret (logging everyone out) and starting with no non-admin accounts. The one `docker cp` loop is in [CONTAINERIZATION.md → One-time migration](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-user/CONTAINERIZATION.md#one-time-migration-docker-composeghcryml-now-mounts-all-of-data).+- **`docker-compose.ghcr.yml` users: copy your state out before the next `up -d`.** The new whole-tree mount means empty host directories would shadow what is in the container's writable layer, regenerating the auth secret (logging everyone out) and starting with no non-admin accounts. The one `docker cp` loop is in [CONTAINERIZATION.md → One-time migration](https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/CONTAINERIZATION.md#one-time-migration-docker-composeghcryml-now-mounts-all-of-data).- **MiniMax on the mainland-China platform:** the default base URL is now the global endpoint. Set `base_url` to `https://api.minimaxi.com/v1` (or `https://api.minimaxi.com/anthropic`) *and* use a China-platform key — keys are issued per platform. Saved profiles keep whatever URL they already have.- **Gemini embeddings:** existing `gemini-embedding-001` profiles are left where they are on purpose. New profiles and `gemini-embedding-2` use the native endpoint.diff --git a/assets/releases/past_releases/ver1-6-15.md b/assets/releases/past_releases/ver1-6-15.mdindex 0abfee4ca..af65ea4dc 100644--- a/assets/releases/past_releases/ver1-6-15.md+++ b/assets/releases/past_releases/ver1-6-15.md@@ -39,7 +39,7 @@ Run `pip install -U deeptutor`; Docker users pull `ghcr.io/hkuds/deeptutor:lates- **Gemini speech:** select a Google voice and WAV or PCM output. This adapter does not accept a speed parameter; use voice instructions for delivery style.- **Query rewrite:** disabled by default. Enable it in `data/user/settings/query_rewrite.json`, through the documented process overrides, or explicitly for an evaluation. Rewriting makes an additional model call.- **Workspace instructions:** configure them in Settings → Workspace. Changes apply from the next turn; Deep Research, Quiz, and Manim do not use them.-- **Request screening:** install `deeptutor[guard]` and enable `security_guard.enabled` in `system.json` only when wanted. Review proxy and rate-limit settings in the [guard guide](../../docs-for-user/SECURITY_GUARD.md); counters are local to each server process.+- **Request screening:** install `deeptutor[guard]` and enable `security_guard.enabled` in `system.json` only when wanted. Review proxy and rate-limit settings in the [guard guide](../../../docs-for-dev/SECURITY_GUARD.md); counters are local to each server process.- **Index recovery:** retries reuse compatible completed parses and validated cloud slices. They do not resume interrupted local inference or embedding midway through its work.**Full Changelog**: https://github.com/HKUDS/DeepTutor/compare/v1.6.14...v1.6.15diff --git a/assets/releases/past_releases/ver1-6-9.md b/assets/releases/past_releases/ver1-6-9.mdindex 09f5a5045..bd569ae76 100644--- a/assets/releases/past_releases/ver1-6-9.md+++ b/assets/releases/past_releases/ver1-6-9.md@@ -8,7 +8,7 @@ Building on [v1.6.8](ver1-6-8.md), v1.6.9 brings folder-based learning workspace### 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-dev/workspaces.md).### Data migration with previews and recoverydiff --git a/deeptutor/api/security_guard.py b/deeptutor/api/security_guard.pyindex 0870486fc..6338914b5 100644--- a/deeptutor/api/security_guard.py+++ b/deeptutor/api/security_guard.py@@ -2,7 +2,7 @@Disabled by default. When ``system.json`` -> ``security_guard.enabled`` is false(or ``DEEPTUTOR_GUARD_ENABLED`` is unset), nothing here imports ``guard`` and the-middleware stack is unchanged. See ``docs-for-user/SECURITY_GUARD.md``.+middleware stack is unchanged. See ``docs-for-dev/SECURITY_GUARD.md``.The guard runs inside the application, in front of the routers. It screens HTTPrequests by client address (rate limit, IP allow/deny lists, ban list) and scansdiff --git a/deeptutor_cli/README.md b/deeptutor_cli/README.mdindex 8e6d3c593..dcc4eff8b 100644--- a/deeptutor_cli/README.md+++ b/deeptutor_cli/README.md@@ -248,7 +248,7 @@ deeptutor config apply setup.json [--home PATH] # 无交互应用配置```让外部 Agent 配置 DeepTutor 时,先阅读根目录的 [SKILL.md](../SKILL.md),再按-[Agent Setup 指南](../docs-for-user/AGENT_SETUP.md) 完成安装、配置、启动和验证。+[Agent Setup 指南](../docs-for-dev/AGENT_SETUP.md) 完成安装、配置、启动和验证。`deeptutor init --non-interactive [--home PATH]` 只创建缺失的默认设置,不询问参数、不选择模型,也不会覆盖已有设置。CLI-only 可以同时加 `--cli`。diff --git a/deeptutor_cli/config_cmd.py b/deeptutor_cli/config_cmd.pyindex b5d4bfd5d..fb88f92c8 100644--- a/deeptutor_cli/config_cmd.py+++ b/deeptutor_cli/config_cmd.py@@ -27,9 +27,7 @@ def register(app: typer.Typer) -> None:@app.command("apply")def config_apply(- file: Path = typer.Argument(- ..., help="Setup JSON file (see docs-for-user/AGENT_SETUP.md)."- ),+ file: Path = typer.Argument(..., help="Setup JSON file (see docs-for-dev/AGENT_SETUP.md)."),home: Path | None = typer.Option(None, "--home", help="Runtime workspace root."),check: bool = typer.Option(False, "--check", help="Validate without writing settings or contacting providers."diff --git a/docker-compose.ghcr.yml b/docker-compose.ghcr.ymlindex df2b8d797..08e4526d4 100644--- a/docker-compose.ghcr.yml+++ b/docker-compose.ghcr.yml@@ -72,7 +72,7 @@ services:# tokens), data/users, data/partners and data/cli-apps in the container's# writable layer — discarded on every recreate. Upgrading from that# layout needs a one-time copy out of the running container first; see- # docs-for-user/CONTAINERIZATION.md → "One-time migration".+ # docs-for-dev/CONTAINERIZATION.md → "One-time migration".- ./data:/app/data- "${DEEPTUTOR_WORKSPACE_HOST:-./data/user/workspace}:/workspace"diff --git a/docs-for-use/AGENT_SETUP.md b/docs-for-dev/AGENT_SETUP.mdsimilarity index 97%rename from docs-for-use/AGENT_SETUP.mdrename to docs-for-dev/AGENT_SETUP.mdindex 96aa5a4b1..00344ae2d 100644--- a/docs-for-use/AGENT_SETUP.md+++ b/docs-for-dev/AGENT_SETUP.md@@ -1,5 +1,7 @@# Set Up and Troubleshoot DeepTutor with Your Agent+[Handbook](README.md) · [Development](DEVELOPMENT.md) · [Modules](MODULES.md) · [Storage](DATA_STORAGE.md)+This guide is for an external agent installing, configuring, and verifyingDeepTutor for a user, or investigating problems in an existing installation.For an existing problem, start with [Troubleshooting](#6-troubleshooting) rather@@ -60,7 +62,7 @@ The 1.7.0 package layout uses `python -m pip install "deeptutor[full]"`for the complete Web app. Bare `deeptutor` contains core chat, CLI and SDK;it does not contain the server or Web assets. For development builds,use the source flow above or the local wheels described in-[Modules](../docs-for-dev/MODULES.md).+[Modules](MODULES.md).When upgrading from 1.6.15, stop DeepTutor, back up the existing runtime home,and keep using the same `DEEPTUTOR_HOME`. To install 1.7.0, run@@ -207,7 +209,7 @@ app needs server and web; RAG needs knowledge and parsing; optional capabilitiesneed their owning modules. Core-only intentionally omits these modules. Sourcecheckouts use `module enable/disable`; wheel installs also support`module install/uninstall`. Stop DeepTutor before changes, and use-`--wheelhouse /path/to/wheels` for unpublished modules. See [Modules](../docs-for-dev/MODULES.md).+`--wheelhouse /path/to/wheels` for unpublished modules. See [Modules](MODULES.md).`doctor` checks local readiness; `doctor --online` makes a small real model requestand may incur provider usage. Inspect exit status and required failures. Fix@@ -289,3 +291,9 @@ based on evidence; there is no need to run every command for every problem.hypotheses. If unresolved, provide a concise handoff: environment/version,reproduction, expected versus actual behavior, relevant redacted errors,checks already tried, and the next useful investigation.++## Implementation and verification++- [deeptutor_cli/setup_config.py](../deeptutor_cli/setup_config.py)+- [deeptutor_cli/doctor.py](../deeptutor_cli/doctor.py)+- [tests/cli/test_agent_setup.py](../tests/cli/test_agent_setup.py)diff --git a/docs-for-dev/ARCHITECTURE.md b/docs-for-dev/ARCHITECTURE.mdnew file mode 100644index 000000000..00f5ffbc0--- /dev/null+++ b/docs-for-dev/ARCHITECTURE.md@@ -0,0 +1,105 @@+# Architecture and source owners++[Handbook](README.md) · [Development](DEVELOPMENT.md) · [Events](EVENTS_AND_PROGRESS.md)++DeepTutor 1.7.0 is one source repository with independently packaged Python+modules. CLI, WebSocket and Python SDK entry points converge on a durable+application service before executing a capability.++```mermaid+flowchart TD+ CLI[Typer CLI] --> APP[TurnApplicationService]+ WS[WebSocket adapter] --> APP+ SDK[DeepTutorApp SDK] --> APP+ APP <--> STORE[Session store and runtime coordinator]+ APP --> ENGINE[TurnEngine]+ ENGINE --> ORCH[ChatOrchestrator]+ ORCH --> CAP[Selected capability]+ CAP --> LOOP[Agent loop or stage pipeline]+ LOOP --> TOOLS[Authorized tool registry]+ CAP --> BUS[Per-turn StreamBus]+ BUS --> STORE+ STORE --> REPLAY[Adapter replay to consumers]+```++## Trace a request++| Responsibility | Source owner |+| --- | --- |+| CLI parsing and commands | [`deeptutor_cli/main.py`](../deeptutor_cli/main.py) |+| SDK facade and application requests | [`deeptutor/app/`](../deeptutor/app/) |+| Durable admission, execution and replay | [`app/service.py`](../deeptutor/app/service.py) |+| WebSocket adaptation | [`unified_ws.py`](../deeptutor/api/routers/unified_ws.py) |+| Lower-level execution | [`runtime/turn_engine.py`](../deeptutor/runtime/turn_engine.py) |+| Context-to-capability routing | [`runtime/orchestrator.py`](../deeptutor/runtime/orchestrator.py) |+| Capability/tool registration | [`runtime/registry/`](../deeptutor/runtime/registry/) |+| Module-owned contributions | [`modules/manifests/`](../deeptutor/modules/manifests/) |+| Shared chat loop | [`agents/loop/`](../deeptutor/agents/loop/) |+| Persistent sessions and turn lifecycle | [`services/session/`](../deeptutor/services/session/) |+| Worker leases and notifications | [`runtime/coordination/`](../deeptutor/runtime/coordination/) |++`UnifiedContext` in [`core/context.py`](../deeptutor/core/context.py) is the+execution context. Entry points should use the application service rather+than instantiate an orchestrator to bypass durable state. Persistence,+submission identity, replay, cancellation and recovery belong to the shared+application/runtime path. See [events](EVENTS_AND_PROGRESS.md) before changing+stream behavior.++## Tools, capabilities and modules++A tool is one model-selected operation. A capability owns a complete turn and+may run a shared loop or a multi-stage pipeline. `chat` is the default;+capability activation and context determine additional tool availability.+Every capability emits the common result envelope, including usage costs.+See [extension contracts](TOOLS_AND_CAPABILITIES.md).++Official [module manifests](MODULES.md#ownership-and-assembly) own package+paths, dependencies, capabilities, routers, CLI groups, navigation and+lifecycle callbacks. Installed, enabled and ready are separate states.+Metadata must be readable without importing unavailable feature packages.+Third-party [plugins](PLUGINS.md) add review and lifecycle rules of their own;+they are not the same as official module wheels.++## Configuration and isolation++[`runtime/home.py`](../deeptutor/runtime/home.py) resolves the runtime home;+[`services/config/runtime_settings.py`](../deeptutor/services/config/runtime_settings.py)+owns settings and supported process overrides. Runtime settings live under+`data/user/settings/`; `.env` is not an application configuration source.+Container startup has its own JSON-to-environment handling, described in+[Containerization](CONTAINERIZATION.md#runtime-configuration).++Account authorization and workspace selection are separate checks. Paths and+services resolve through [`services/workspace/`](../deeptutor/services/workspace/)+and [`services/path_service.py`](../deeptutor/services/path_service.py).+Selected workspace data, account credentials and shared resource grants have+different lifetimes; consult [storage](DATA_STORAGE.md) and+[workspace contracts](workspaces.md) before touching migrations or caches.++## Frontend boundaries++The Next.js App Router in [`web/app/`](../web/app/) composes pages. Domain,+store and transport slices live under [`web/features/`](../web/features/).+Reusable UI and transport primitives live under [`web/shared/`](../web/shared/).+[`web/contracts/`](../web/contracts/) holds generated API and turn contracts.++The [dependency rules](../web/.dependency-cruiser.cjs) prohibit cycles,+imports of route `page.tsx` modules, upward dependencies from shared code,+and rendering-layer imports from feature domain/store/transport code except+for the named settings-store exception. Prefer existing transport and store+owners to component-local WebSocket, retry or persistence implementations.++[`web/proxy.ts`](../web/proxy.ts) forwards API/WebSocket traffic to the+backend. Browser settings and runtime server configuration are different+boundaries; do not bake deployment addresses or secrets into client code.++## Experimental engine path++The Python scheduler remains the default. `DEEPTUTOR_CHAT_ENGINE` can select+experimental TypeScript paths implemented in+[`packages/chat-engine/`](../packages/chat-engine/) and+[`runtime/ts_engine/`](../deeptutor/runtime/ts_engine/). The native path has+compatibility checks and Python integration points. An old migration plan is+not evidence that the whole backend has moved to TypeScript. Changes here+must preserve the application service, storage and public event contracts;+see the dedicated engine jobs in [Testing](TESTING.md).diff --git a/docs-for-use/CONTAINERIZATION.md b/docs-for-dev/CONTAINERIZATION.mdsimilarity index 95%rename from docs-for-use/CONTAINERIZATION.mdrename to docs-for-dev/CONTAINERIZATION.mdindex b7ab1d504..dd2522be8 100644--- a/docs-for-use/CONTAINERIZATION.md+++ b/docs-for-dev/CONTAINERIZATION.md@@ -1,5 +1,7 @@# DeepTutor Containerization+[Handbook](README.md) · [Agent setup](AGENT_SETUP.md) · [Storage](DATA_STORAGE.md)+This document covers deploying DeepTutor from a container image: therecommended `docker run` path, the hardened rootless-Podman path with aread-only root filesystem, runtime configuration, the optional PocketBase@@ -42,7 +44,7 @@ no longer lives in the frontend bundle. Concretely:`DEEPTUTOR_API_BASE_URL` at request time. That env var is set by thecontainer entrypoint on every start, read from`data/user/settings/system.json`.-- `start-frontend.sh` is now 12 lines: it sets `PORT`/`HOSTNAME` and+- `start-frontend.sh` sets `PORT`/`HOSTNAME` and`exec`s `node /app/web/server.js`. No mutations of the bundle.- `supervisord` runs as root (PID 1) and drops each program (backend,frontend) to a non-root `deeptutor` user (UID 1000) via its per-program@@ -332,11 +334,11 @@ What `compose.yaml` does, and why:- **`read_only: true` on every service.** The container's rootfs isread-only. The only writable surface is the `tmpfs:` mounts listedper service plus the bind-mounted `./data` and Content Workspace directories.-- **`userns_mode: keep-id`.** The container's UID 0 maps to your host- UID; the container's UID 1000 (the `deeptutor` user inside the image)- maps to your host UID 1000 (which most distros reserve for the first- human user). The `:U` suffix on every volume mount tells podman to- chown the bind-mount target to that mapped UID.+- **`userns_mode: keep-id`.** Uses the runtime's keep-id user namespace.+ Inspect the actual mapping on the target host; do not assume that container+ UID 0 or UID 1000 maps identically for every host account. The `:U` mount+ option adjusts ownership for the container mapping and can change host+ directory ownership. Use dedicated data directories and verify write access.- **`tmpfs:` mounts for the system dirs the runtime expects to write.**`/tmp` (Python/Node scratch), `/run` and `/var/run` (pidfiles),`/var/log`, `/root`, `/home`. Sizes are intentionally generous; trim@@ -361,7 +363,10 @@ invariants apply if you want to drive `podman run` directly:```bashmkdir -p data/user/settings-echo '{}' > data/user/settings/system.json+# Create defaults only when no settings exist; preserve existing configuration.+if [ ! -f data/user/settings/system.json ]; then+ printf '{}\n' > data/user/settings/system.json+fipodman run --rm -d --name deeptutor \-p 127.0.0.1:8001:8001 \@@ -539,3 +544,12 @@ renormalized on save.scan) is available through `security_guard` in `system.json` and the`guard` extra (`DEEPTUTOR_EXTRAS: "guard"`). It is off by default; see[SECURITY_GUARD.md](SECURITY_GUARD.md).++## Implementation and verification++- [Dockerfile](../Dockerfile)+- [docker-compose.yml](../docker-compose.yml)+- [docker-compose.ghcr.yml](../docker-compose.ghcr.yml)+- [compose.yaml](../compose.yaml)+- [scripts/docker_compose.py](../scripts/docker_compose.py)+- [tests/scripts/test_docker_compose.py](../tests/scripts/test_docker_compose.py)diff --git a/docs-for-use/DATA_STORAGE.md b/docs-for-dev/DATA_STORAGE.mdsimilarity index 92%rename from docs-for-use/DATA_STORAGE.mdrename to docs-for-dev/DATA_STORAGE.mdindex e8c19cac6..6b2b37995 100644--- a/docs-for-use/DATA_STORAGE.md+++ b/docs-for-dev/DATA_STORAGE.md@@ -1,5 +1,7 @@# Local Data Persistence+[Handbook](README.md) · [Workspaces](workspaces.md) · [Containers](CONTAINERIZATION.md)+DeepTutor's default installation does not require PostgreSQL, MySQL, or anotherdatabase server. Durable state is written below one runtime-home directory, soa deployment has one tree to mount, inspect, and back up. Some state is stored@@ -83,3 +85,9 @@ the app runs can lose recent transactions. Back up the complete runtime-home`data` directory plus each separately configured Content Workspace. Treat everycopy as sensitive because it can contain credentials, private conversationtext, and uploaded learning material.++## Implementation and verification++- [deeptutor/runtime/home.py](../deeptutor/runtime/home.py)+- [deeptutor/services/path_service.py](../deeptutor/services/path_service.py)+- [deeptutor/services/workspace/context.py](../deeptutor/services/workspace/context.py)diff --git a/docs-for-dev/DEVELOPMENT.md b/docs-for-dev/DEVELOPMENT.mdnew file mode 100644index 000000000..0ebf9d260--- /dev/null+++ b/docs-for-dev/DEVELOPMENT.md@@ -0,0 +1,100 @@+# Developing DeepTutor++[Handbook](README.md) · [Architecture](ARCHITECTURE.md) · [Testing](TESTING.md)++## Prepare a source environment++Follow [Agent setup](AGENT_SETUP.md) for Python 3.11–3.14, Node.js 22 LTS,+provider configuration and readiness. A source checkout exposes all modules;+install its external dependencies before the editable core:++```bash+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps+python scripts/install_extras.py dev+cd web+npm ci --legacy-peer-deps+cd ..+```++Use `scripts/install_extras.py` for optional source dependencies. Installing+feature wheels over an editable checkout can obscure source ownership; use a+separate environment for [wheel lifecycle testing](MODULES.md#validation).+System executables such as FFmpeg and LaTeX remain separate prerequisites for+the features that need them.++Inspect `git status`, the active branch and remotes before updating. Develop+against `dev`; follow [contribution policy](../CONTRIBUTING.md) for PR targets.+Reuse an appropriate task checkout or use a separate worktree when concurrent+work needs isolation. Preserve unrelated edits. Keep runtime data and test+outputs out of Git.++## Use a dedicated runtime home++`DEEPTUTOR_HOME` is the directory that owns `data/`, not `data/` itself. Pick+an explicit, private development home and use it for every command. For+example, in a fresh shell:++```bash+export DEEPTUTOR_HOME="$HOME/.local/share/deeptutor-dev"+deeptutor init --non-interactive+deeptutor config show+deeptutor module list+```++Do not point fixtures at an existing learner's runtime. A Content Workspace+is a separate storage and authorization scope; see [workspaces](workspaces.md).+The application does not automatically load the project's `.env` file.++## Run and inspect++For the combined launcher, use `deeptutor start` and read the actual URLs in+its output. For separate development processes, run the API and frontend in+two terminals with the same chosen runtime home:++```bash+# Terminal 1: API, with reload+deeptutor serve --host 127.0.0.1 --port 8001 --reload+```++```bash+# Terminal 2: frontend, from web/+DEEPTUTOR_API_BASE_URL=http://127.0.0.1:8001 npm run dev+```++Choose free ports; do not stop unrelated services. Confirm browser requests+reach the intended API through the frontend proxy. A listening frontend alone+does not establish provider, module or turn readiness. Use+`deeptutor doctor --format json` and the original user operation to verify.++## Make a change at its owner++1. Reproduce the behavior with a minimal synthetic fixture. Identify whether+ the owner is the adapter, shared runtime, capability, tool, feature store,+ provider, or frontend projection.+2. Read the nearest implementation and its tests. For API changes, follow+ request validation through authentication, account/workspace resolution,+ persistence, events and UI consumption.+3. Change that owner rather than adding a second runtime, path resolver,+ provider client or storage abstraction. Shared protocols stay import-light.+4. Update module declarations, request contracts, prompts and locale strings+ when affected. Regenerate derived files with their owning scripts.+5. Run [checks appropriate to the change](TESTING.md), reproduce the original+ action, and explain any validation limits in the PR.++Use explicit argument lists and `shell=False` for subprocesses; retain process+tree cleanup on cancellation. Resolve storage through the existing account+and workspace context rather than constructing a global data path. Never+return credentials or private provider-replay metadata to browser responses.++## Generated files and documentation++The repository intentionally tracks generated API contracts, requirement+files and dependency locks. Update their generators or authoritative inputs,+then regenerate. `web/.next*`, installed dependencies, bytecode, logs and+manual acceptance artifacts stay untracked.++Update the relevant handbook topic and README links when a public behavior+changes. Put reusable executable examples under this handbook's+[`examples/`](examples/learning_echo/README.md). Keep command examples usable+from the repository root and avoid personal machine paths.diff --git a/docs-for-dev/EVENTS_AND_PROGRESS.md b/docs-for-dev/EVENTS_AND_PROGRESS.mdnew file mode 100644index 000000000..6a4bf570c--- /dev/null+++ b/docs-for-dev/EVENTS_AND_PROGRESS.md@@ -0,0 +1,73 @@+# Events, durable replay and indexing progress++[Handbook](README.md) · [Architecture](ARCHITECTURE.md) · [Indexing recovery](INDEXING_RECOVERY.md)++Different event systems have different persistence guarantees. Start with+the operation being diagnosed; a process-local notification is not a durable+turn journal.++| Flow | Main owners | What to inspect |+| --- | --- | --- |+| Model turn | [Application service](../deeptutor/app/service.py), [turn runtime](../deeptutor/services/session/turn_runtime.py), [StreamBus](../deeptutor/runtime/stream_bus.py) | Submission identity, persisted sequence, replay cursor, terminal event |+| Multi-worker coordination | [Coordinator](../deeptutor/runtime/coordination/) | Lease owner, fencing, cancellation notification, recovery |+| Knowledge ingestion | [Progress tracker](../deeptutor/knowledge/progress_tracker.py), [indexing journal](../deeptutor/knowledge/indexing_run.py) | Task identity, source outcomes, publication state, last activity |+| Knowledge UI transport | [Progress ports](../deeptutor/knowledge/progress_events.py), [broadcaster](../deeptutor/api/utils/progress_broadcaster.py), [task stream](../deeptutor/api/utils/task_log_stream.py) | Snapshot, WebSocket progress, SSE logs/terminal state |+| Process notifications | [EventBus](../deeptutor/events/event_bus.py) | Current publishers/subscribers; process lifetime |++## Turn lifecycle++The application service coordinates admission and execution through the shared+session store and runtime. Each execution has a per-turn stream bus; events+must enter the persistence/replay path before adapters deliver them to+consumers. A browser disconnect does not by itself prove the turn failed or+authorize a second execution. Recovery must distinguish an active lease from+a lost worker and preserve terminal state.++When changing streaming, test duplicate submission, reconnect after partial+output, replay after a terminal event, cancellation and worker loss. Preserve+event IDs/sequences and existing projection rules instead of treating arrival+order or rendered text as the durable source of truth. Protocol types live in+[`core/stream.py`](../deeptutor/core/stream.py); the frontend consumes the+contracts under [`web/contracts/`](../web/contracts/).++One worker can use the memory coordinator. More than one backend worker+requires Redis coordination, configured through `system.backend_workers` and+`integrations.turn_coordination`. The+[settings validator](../deeptutor/runtime/coordination/settings.py) rejects+multiple workers with a memory coordinator and rejects Redis without a URL.+Redis is the coordination/notification layer; it does not replace the session+store. `deeptutor doctor runtime --format json` reports runtime diagnostics.++## Knowledge-base progress++`ProgressTracker` persists snapshots and emits through injected progress+ports. The API installs the WebSocket/SSE ports; domain code must not import+FastAPI to report progress. CLI/SDK execution can still persist progress+without a browser broadcaster.++The knowledge router exposes a progress WebSocket and task-log SSE stream.+[`useKnowledgeProgress`](../web/hooks/useKnowledgeProgress.ts) combines them,+tracks the expected task, and reconciles terminal state. Preserve workspace+scope and task identity when reconnecting or applying a snapshot. Logs and+percentage estimates are observations, not proof that an index was published.++The [indexing journal](INDEXING_RECOVERY.md) records source-level success,+failure and interrupted work. Completion must agree with persisted publication;+a parser reaching its last batch is insufficient. Rebuilds must not replace a+queryable version with a partial candidate. For parsing checkpoints and exact+source locators, also read [source visuals](SOURCE_VISUALS.md).++## Debugging sequence++1. Identify the account, workspace, session/turn or KB/task ID and time window.+2. Check durable status first, then the coordinator/worker and transport.+3. Compare the browser's cursor/task identity to the server's persisted state.+4. Reproduce dropped connections, old snapshots and duplicate frames with+ fixtures. Do not repair progress by overwriting success fields manually.+5. Verify terminal state after reopening, not only while the original browser+ connection remains alive.++Relevant suites include [application tests](../tests/app/),+[coordination tests](../tests/runtime/coordination/),+[knowledge tests](../tests/knowledge/), and+[knowledge progress WebSocket tests](../tests/api/test_knowledge_progress_ws.py).diff --git a/docs/INDEXING_RECOVERY.md b/docs-for-dev/INDEXING_RECOVERY.mdsimilarity index 87%rename from docs/INDEXING_RECOVERY.mdrename to docs-for-dev/INDEXING_RECOVERY.mdindex 7e3e71117..915b4ad23 100644--- a/docs/INDEXING_RECOVERY.md+++ b/docs-for-dev/INDEXING_RECOVERY.md@@ -1,5 +1,7 @@# Long-document indexing and recovery+[Handbook](README.md) · [Related guide](EVENTS_AND_PROGRESS.md)+Each knowledge base records its latest indexing run in `.indexing-run.json`.The Files/detail view exposes **Indexing recovery details**, including individualsource outcomes, current phase and phase-local counts, elapsed runtime, time@@ -35,3 +37,9 @@ A failed or partial candidate does not overwrite a previous queryable version.Completed and failed sources are reported separately, including partial success.The durable journal is scoped to the active user/workspace knowledge base;linked/read-only knowledge bases cannot be cancelled through mutation routes.++## Implementation and verification++- [deeptutor/knowledge/indexing_run.py](../deeptutor/knowledge/indexing_run.py)+- [deeptutor/services/parsing/cache.py](../deeptutor/services/parsing/cache.py)+- [tests/knowledge/test_indexing_run.py](../tests/knowledge/test_indexing_run.py)diff --git a/docs-for-use/KNOWLEDGE_MIGRATION.md b/docs-for-dev/KNOWLEDGE_MIGRATION.mdsimilarity index 91%rename from docs-for-use/KNOWLEDGE_MIGRATION.mdrename to docs-for-dev/KNOWLEDGE_MIGRATION.mdindex 92aa2ea81..4b40a2a4c 100644--- a/docs-for-use/KNOWLEDGE_MIGRATION.md+++ b/docs-for-dev/KNOWLEDGE_MIGRATION.md@@ -1,7 +1,10 @@# Knowledge migration guide+[Handbook](README.md) · [Related guide](INDEXING_RECOVERY.md)+This guide covers moving existing notes from Obsidian, Hermes, or another-Markdown-based tool into DeepTutor. It matches the v1.6.0 Knowledge Center.+Markdown-based tool into the current Knowledge Center. For moving existing+DeepTutor data between workspaces, use [workspace data migration](workspaces.md).## Choose a migration path@@ -112,3 +115,9 @@ when filenames repeat or hierarchy is meaningful. Use `deeptutor kb list` andnote, and then delete that scratch note from Obsidian.- Keep the original backup until retrieval quality and asset references areconfirmed.++## Implementation and verification++- [deeptutor/capabilities/obsidian/vault.py](../deeptutor/capabilities/obsidian/vault.py)+- [deeptutor/api/routers/knowledge.py](../deeptutor/api/routers/knowledge.py)+- [deeptutor_cli/kb.py](../deeptutor_cli/kb.py)diff --git a/docs-for-dev/MODULES.md b/docs-for-dev/MODULES.mdindex 23bf13de3..ee6b39777 100644--- a/docs-for-dev/MODULES.md+++ b/docs-for-dev/MODULES.md@@ -1,5 +1,7 @@# Modules and installation+[Handbook](README.md) · [Related guide](TESTING.md)+DeepTutor has one source repository and disjoint Python distributions. `deeptutor`owns the shared turn runtime, CLI and Python SDK. Feature distributions add codeinto the same package namespace without overwriting core files. `deeptutor-cli`@@ -160,17 +162,11 @@ offline module command. It no longer upgrades packages beneath active turns.Model-weight downloads remain background jobs, because they do not alter Pythoncode. Third-party managed plugins retain their existing isolated environments.-## Worker streaming and cancellation+## Third-party worker extensions-A worker may advertise `"transport": "ndjson-v1"` in `describe_capability`.-For a run, it emits JSON lines of `{"kind":"event","event":{...}}`, then-`{"kind":"complete"}`. Events are forwarded immediately through the ordinary-turn stream, which owns persistence/replay. EOF without completion, malformed-frames and permission escalation fail the run. Requests, frames, total output,-stderr and execution time have bounds; the consumer queue applies backpressure.-Cancellation closes the process group and waits for cleanup. Legacy one-response-workers remain supported and also stop on cancellation. The learning-echo example-shows both protocols. These workers do not share the host's Python environment.+Managed plugin workers use their own environments and lifecycle, separately+from official module wheels. See [plugin streaming and cancellation](PLUGINS.md#worker-protocol-and-cancellation)+and the [runnable example](examples/learning_echo/README.md).## Validation@@ -193,3 +189,9 @@ Manim additionally needs system rendering libraries, FFmpeg andLaTeX. A render and cancellation test should accompany changes to its renderer.The Web application remains one frontend distribution; independently replaceablethird-party frontend bundles are outside this Python module contract.++## Implementation and verification++- [deeptutor/modules/manifests/](../deeptutor/modules/manifests/)+- [scripts/build_modules.py](../scripts/build_modules.py)+- [scripts/check_module_install.py](../scripts/check_module_install.py)diff --git a/docs-for-dev/MODULE_REVIEW.md b/docs-for-dev/MODULE_REVIEW.mddeleted file mode 100644index 11c88addb..000000000--- a/docs-for-dev/MODULE_REVIEW.md+++ /dev/null@@ -1,47 +0,0 @@-# Module boundary review — 2026-10-28--Reviewed against local `dev` at `e347c0c2e017248d08297c0cf00f5c55f79747fe`.--## Resolved issues--- Parsing imported the knowledge indexing journal even for plain-text parsing.- Parsing now owns the progress protocol/context; knowledge keeps compatibility- exports and supplies the journal implementation.-- Research and Questions prepared PageIndex tools without a knowledge base.- They now prepare these tools only for an explicitly selected, enabled KB.- Research credentials no longer import the knowledge-source adapter.-- Calendar unconditionally read Mastery storage. Mastery projections are now- optional; calendar events, practice projections and automations remain usable.-- Knowledge Frontier needs both Research and Knowledge. Its tool contribution- declares both availability requirements instead of exposing a broken tool.-- Books' standard quiz/visual blocks and source grounding now have explicit- dependencies. Optional notebook, audio-note and Manim integrations reject- unavailable modules with actionable hints. Core suggestions/diagnostics work- without Memory/Knowledge.-- Word/Excel creation and practice imports/exports also need python-docx and- openpyxl. These remain core dependencies, independent of Parsing.-- Malformed selection is rejected before pip runs. A failed selection write after- installation rolls back added packages. Enable rejects mismatched versions.- Locks cover both the interpreter and shared deployment state.-- Installation, plugin and Manim cancellation share process-tree cleanup;- Windows uses taskkill /T /F instead of killing only the parent.--## Validation--- Expanded Python regression: 3,979 passed, 61 skipped.-- Final cancellation/module/plugin/renderer/launcher checks: 236 passed.-- Fresh-process assembly for all 25 modules prohibits imports of unrelated- modules. Independent Core, Parsing, Research, Question, Calendar and API paths- are exercised; Parsing includes a repeated cache read.-- 26 wheels built with no overlapping installed files.-- Disposable wheel environment: core chat and durable replay, Word/Excel file- generation, Solve install/run/uninstall/reinstall, independent Parsing,- Research and Calendar, then individual removal while Solve remains usable.- Retained data hashes and pip check passed. Model responses use a local fixture.-- Web typecheck and module tests passed; production Web build was validated during- implementation. Architecture/import contracts, Ruff, generated requirements,- repository hygiene and README structure checks passed.--Executed locally on macOS / Python 3.13. Windows cleanup command construction is-covered by tests; an actual Windows host was not used. CI has an extended wheel-lifecycle job for Python 3.11 and 3.13. No packages were published.diff --git a/docs-for-dev/PLUGINS.md b/docs-for-dev/PLUGINS.mdnew file mode 100644index 000000000..282547d26--- /dev/null+++ b/docs-for-dev/PLUGINS.md@@ -0,0 +1,116 @@+# Third-party plugin development++[Handbook](README.md) · [Tools and capabilities](TOOLS_AND_CAPABILITIES.md) · [Reading extensions](READING_EXTENSIONS.md)++Official [module wheels](MODULES.md) share DeepTutor's interpreter and version.+Third-party plugins have a separate manifest, approval and lifecycle contract.+Start with the runnable [Learning Echo example](examples/learning_echo/README.md),+which declares a tool, capability, HTTP route and static page without external+Python dependencies.++## Manifest and registration++A package ships static `deeptutor.plugin.json` using schema+`deeptutor.plugin/v1`. Read+[`manifest.py`](../deeptutor/plugins/manifest.py) and the+[example manifest](examples/learning_echo/learning_echo/deeptutor.plugin.json)+for the exact fields. It declares identity/version, DeepTutor/API compatibility,+permission disclosure, dependency closure and typed extensions. Unknown fields+and invalid paths are rejected.++| Extension | Runtime contract |+| --- | --- |+| `tool`, `capability` | Host entry-point protocol or approved managed JSON worker |+| `loop_capability` | Existing shared-loop extension protocol |+| `reading_extension` | Server-verified Reading context and bounded result types |+| `visualizer` | Typed packaged visualizer declaration |+| `http_route` | Managed worker endpoint under the host plugin namespace |+| `frontend_page` | Declared static assets served with restrictive sandbox CSP |+| `persistence_schema`, `app_connector` | Approved declaration/introspection; no general migration or connector execution API |++Built-in IDs take precedence. Each extension retains its own typed protocol.+Existing Python entry-point groups honor root-manifest approval when one is+present; new packages should not rely on the legacy manifest-free path.+Discovery reads metadata without importing third-party code. The+[registry](../deeptutor/plugins/registry.py) distinguishes available,+approval-required, enabled, disabled, incompatible, broken and deprecated state.++## Installation and approval++Use `deeptutor plugin --help` for lifecycle commands. Managed installation+accepts a local wheel or resolves a reviewed entry from the vendored+[`catalog.json`](../deeptutor/plugins/catalog.json). Catalog browsing/version+resolution is offline; explicit installation downloads the pinned artifact.+There is no arbitrary URL installer or automatic background upgrade.++Catalog artifacts bind an HTTPS wheel URL, SHA-256, size and platform metadata.+Downloads reject redirects and size/digest mismatches before pip. The local+lifecycle validates the manifest from the wheel before importing code, creates+a version-private environment, and installs an explicit wheel-only dependency+closure. It does not mutate the host interpreter.++Approval binds the normalized manifest and artifact identity. Inspect the+current snapshot before approving. Installation, upgrade, same-version+reinstall and rollback clear prior approval. Approval does not automatically+enable a locally disabled plugin. Failed installations preserve the previous+usable state; retained versions support rollback. External host-installed+plugin upgrades need restart to replace already imported Python modules.++The owner is [`lifecycle.py`](../deeptutor/plugins/lifecycle.py), with state+under runtime `data/user/settings/plugins.json`. API lifecycle mutations need+administrator authorization. [Plugin tests](../tests/plugins/) cover manifest,+artifact, transaction, recovery and approval boundaries.++## Worker protocol and cancellation++[`runtime.py`](../deeptutor/plugins/runtime.py) launches a worker module using+the plugin environment's Python. Worker declarations cannot exceed the approved+manifest. Legacy workers exchange one JSON request and response on stdin/stdout.++A capability can advertise `"transport": "ndjson-v1"` in its description.+It then emits JSON lines with `{"kind":"event","event":{...}}`, followed+by `{"kind":"complete"}`. Events enter the normal durable turn stream;+workers do not own a parallel public stream. EOF before completion and+malformed frames fail the run. Requests, frames, output, stderr and execution+have bounds; queues apply backpressure. Cancellation closes the process group+and waits for cleanup. The example supports both streaming and legacy modes.++## HTTP and static pages++Managed HTTP routes use `/api/plugins/{plugin-id}{path}` and cannot replace+built-in routes. The host resolves approved, enabled, compatible managed state+and authenticates before starting a worker. With host authentication enabled,+even a plugin route declared `public` requires a host session: it does not+bypass the host account boundary. The `admin` policy adds an administrator+check. Unavailable plugin routes return 404.++Workers receive declared method/path, normalized query values and a bounded+JSON body, not host cookies, bearer tokens or authentication headers.+Responses have validated JSON status/body and restricted `Cache-Control`;+redirects and authentication responses belong to the host. See+[API tests](../tests/api/test_plugins_router.py).++A static page declares schema `deeptutor.plugin-frontend-page/v1`, one entry+and an explicit asset closure. Only approved regular package files may be+served; symlinks and undeclared assets are rejected. The canonical URL is+`/api/plugins/{plugin-id}/pages/{extension-id}/`. Keep the trailing slash for+relative assets.++Pages run in a sandboxed browser context with restrictive CSP, including+`connect-src 'none'`; they do not inject React/Next code into the host bundle+or arbitrarily fetch host APIs. See [`frontend.py`](../deeptutor/plugins/frontend.py),+[frontend tests](../tests/plugins/test_frontend.py), and the+[example page manifest](examples/learning_echo/learning_echo/frontend/page.json).++## Trust limits and validation++Permission declarations and approval are not an OS sandbox. Host entry-point+extensions execute in the host interpreter; managed workers isolate Python+dependencies but retain host operating-system access. Review actual packages+and dependencies. Packaged browser pages have their own browser sandbox.+Direct Chrome extension reuse is unsupported.++Validate the manifest, build a wheel, exercise approval/enablement, the worker+and page, then disable/revoke and cancel a run. Use a disposable runtime home.+See [Testing](TESTING.md) and the separate+[Reading extension context/result rules](READING_EXTENSIONS.md).diff --git a/docs-for-use/PRACTICE.md b/docs-for-dev/PRACTICE.mdsimilarity index 95%rename from docs-for-use/PRACTICE.mdrename to docs-for-dev/PRACTICE.mdindex 8aec6772d..70e6a3eb3 100644--- a/docs-for-use/PRACTICE.md+++ b/docs-for-dev/PRACTICE.md@@ -1,5 +1,7 @@# 练习:题库、错题与每日复习+[Handbook](README.md) · [Related guide](workspaces.md)+「学习空间 → 题库」(`/space/questions`)用于管理完整题库与错题,支持导入、搜索、筛选、标签和收藏。「个性化学习 → 练习」(`/learning/practice`)提供练习统计、每日错题复习,以及相同的题库、错题和导入功能。两个入口共用题目与复习记录;学习空间的题库页面不展示统计图表或每日复习面板。@@ -106,3 +108,9 @@ SQLite 在原有题目写入时自动收集错题,不要求每个来源单独回退应用版本前仍应备份数据库;旧版本不能展示新的复习计划,但原始题库数据不依赖新表。开发安装更新后需要重启后端才能注册新接口,前端需使用对应版本。++## Implementation and verification++- [deeptutor/services/practice/](../deeptutor/services/practice/)+- [deeptutor/api/routers/practice.py](../deeptutor/api/routers/practice.py)+- [tests/api/test_practice.py](../tests/api/test_practice.py)diff --git a/docs-for-use/READING_EXTENSIONS.md b/docs-for-dev/READING_EXTENSIONS.mdsimilarity index 94%rename from docs-for-use/READING_EXTENSIONS.mdrename to docs-for-dev/READING_EXTENSIONS.mdindex 7c0f49836..43b9e8cc3 100644--- a/docs-for-use/READING_EXTENSIONS.md+++ b/docs-for-dev/READING_EXTENSIONS.md@@ -1,5 +1,7 @@# Immersive Reading extensions+[Handbook](README.md) · [Related guide](PLUGINS.md)+Immersive Reading discovers server-side packages through the`deeptutor.reading_extensions` Python entry-point group. DeepTutor ships readaloud, study guidance, vocabulary, quiz, and explicit-target translation@@ -65,3 +67,7 @@ class ExampleExtension:Protocol changes must remain backward-compatible within version `1`. A futureincompatible contract must use a new protocol version rather than changing themeaning of an existing field.++## Implementation and verification++- [deeptutor/reading/extensions.py](../deeptutor/reading/extensions.py)diff --git a/docs-for-dev/README.md b/docs-for-dev/README.mdnew file mode 100644index 000000000..bfcadb41e--- /dev/null+++ b/docs-for-dev/README.md@@ -0,0 +1,75 @@+# DeepTutor developer and agent handbook++Start here to install, diagnose, or change DeepTutor. This handbook describes+the **1.7.0 source tree**; use the documentation from the same tag when working+on another release. The version authority is+[`deeptutor/__version__.py`](../deeptutor/__version__.py). Commands below run+from the repository root unless a page says otherwise.++## Choose a reading path++| Your task | Read in order | Completion evidence |+| --- | --- | --- |+| Install and configure the app | [Agent setup](AGENT_SETUP.md) → [Storage](DATA_STORAGE.md) | Dependencies, module readiness, actual model response, reachable app |+| Fix an existing installation | [Setup troubleshooting](AGENT_SETUP.md#6-troubleshooting) → the relevant topic below | Original failing action works in the same instance and workspace |+| Develop a change | [Development](DEVELOPMENT.md) → [Architecture](ARCHITECTURE.md) → [Testing](TESTING.md) | Focused regression and applicable project checks |+| Add a tool or capability | [Tool and capability contracts](TOOLS_AND_CAPABILITIES.md) → [Modules](MODULES.md) | Registration, availability, execution and terminal-result tests |+| Build a third-party extension | [Plugins](PLUGINS.md) → [Runnable Learning Echo example](examples/learning_echo/README.md) | Wheel, manifest, approval, worker and frontend checks |+| Investigate streaming or memory | [Events and progress](EVENTS_AND_PROGRESS.md) → [Runtime design](RUNTIME_DESIGN.md) | Persistence/replay and cancellation evidence |+| Deploy or upgrade | [Modules](MODULES.md) → [Containers](CONTAINERIZATION.md) → [Storage](DATA_STORAGE.md) | Matching versions, retained data, readiness and a representative turn |++For a terminal-capable agent, read this index, [AGENTS.md](../AGENTS.md), and+the task's guide before editing. [SKILL.md](../SKILL.md) is the compact CLI+reference. Inspect the checkout, working-tree changes, Python environment and+runtime home before following an example. Keep existing user data and+credentials separate from disposable test fixtures. Diagnose a failing+installation before deciding to reinstall it.++## Topic map++### Runtime and extension development++- [Architecture and source owners](ARCHITECTURE.md): entry points, durable+ turns, frontend boundaries and configuration.+- [Tools and capabilities](TOOLS_AND_CAPABILITIES.md): single-shot tools,+ turn-owning pipelines, context gates and result envelopes.+- [Modules](MODULES.md): distribution ownership, installation and lifecycle.+- [Plugins](PLUGINS.md): manifests, review, workers, HTTP and static pages.+- [Reading extensions](READING_EXTENSIONS.md): verified selection context and+ bounded results.+- [Events and progress](EVENTS_AND_PROGRESS.md): turn replay versus indexing+ progress and process-local notifications.+- [Runtime design](RUNTIME_DESIGN.md): lazy loading, isolated parsing, private+ model history and prompt-cache observability.+- [Remote Hermes backend](remote-hermes-backend.md): gateway protocol and+ Connected Agents integration.++### Storage, deployment and feature contracts++- [Data storage](DATA_STORAGE.md) and [workspaces](workspaces.md): runtime+ home, account/workspace scope, backups, resource assignment and migration.+- [Containerization](CONTAINERIZATION.md) and [request screening](SECURITY_GUARD.md):+ deployment configuration, OAuth callback ports and proxy boundaries.+- [Knowledge migration](KNOWLEDGE_MIGRATION.md), [indexing recovery](INDEXING_RECOVERY.md),+ and [source visuals](SOURCE_VISUALS.md): ingestion, publication, original+ evidence and visual assessment.+- [Scientific research](SCIENTIFIC_RESEARCH.md): paper tools, evidence and MCP+ authorization.+- [Practice](PRACTICE.md): question imports, review records and scheduling.+- [Video learning](watching-workspace.md) and [voice](VOICE_CONFIGURATION.md):+ Reading media migration, captions, speech adapters and verification.+- [Answer-quality diagnosis](REASONING_SAFETY_CHECKLIST.md): reproducible+ retrieval, citation, context and assessment failures.++## Keeping this handbook useful++Keep one canonical page for each contract and link to it. Each topic should+point to its implementation owners or regression tests. Update affected+examples when commands, routes, ownership or storage change; generated schemas+and module manifests take precedence over prose. Record what a check proves,+including provider/network or platform limits.++Keep task plans, one-off test counts, screenshots, private paths, downloaded+reference repositories and unrelated product research out of this handbook.+Use PRs or local ignored output for execution evidence. A design proposal is+not current behavior until its implementation can be located and verified.diff --git a/docs-for-use/REASONING_SAFETY_CHECKLIST.md b/docs-for-dev/REASONING_SAFETY_CHECKLIST.mdsimilarity index 96%rename from docs-for-use/REASONING_SAFETY_CHECKLIST.mdrename to docs-for-dev/REASONING_SAFETY_CHECKLIST.mdindex 2d540896f..5ab9f1a35 100644--- a/docs-for-use/REASONING_SAFETY_CHECKLIST.md+++ b/docs-for-dev/REASONING_SAFETY_CHECKLIST.md@@ -1,5 +1,7 @@# Long-Horizon Reasoning and Safety Checklist+[Handbook](README.md) · [Related guide](AGENT_SETUP.md#6-troubleshooting)+Use this checklist when a tutoring answer looks unreliable, changes assumptions midway, cites weak evidence, or fails to reflect the material a learner selected. It is intentionally diagnostic: it helps users collect useful evidence and helps maintainers distinguish a prompt problem, retrieval problem, context problem, or product bug.## Quick Diagnostic Questions@@ -76,3 +78,8 @@ Expected behavior:Actual behavior:What I already tried:```++## Implementation and verification++- [deeptutor/agents/loop/](../deeptutor/agents/loop/)+- [deeptutor/services/rag/](../deeptutor/services/rag/)diff --git a/docs-for-dev/RUNTIME_DESIGN.md b/docs-for-dev/RUNTIME_DESIGN.mdnew file mode 100644index 000000000..db8b886a9--- /dev/null+++ b/docs-for-dev/RUNTIME_DESIGN.md@@ -0,0 +1,83 @@+# Runtime design: activation, workers and model history++[Handbook](README.md) · [Architecture](ARCHITECTURE.md) · [Events](EVENTS_AND_PROGRESS.md)++This page retains implemented decisions from earlier design notes. It describes+current boundaries; historical memory measurements and one-machine test counts+are not performance guarantees.++## Lazy activation++Tool/capability catalogs use import-light descriptors. Registry inspection must+not eagerly import unused providers, parsers or optional modules. Registries+load implementations on demand; module selection and plugin approval remain+effective at activation. Compatibility exports may use lazy wrappers to retain+existing import paths.++The frontend similarly defers settings editors. Preserve anchor/navigation+activation and authentication single-flight behavior when changing loading.+Verify with import-boundary tests and frontend route budgets, not only a warm+process timing. Source owners: [registries](../deeptutor/runtime/registry/),+[module assembly](../deeptutor/modules/), and [settings](../web/features/settings/).++## Short-lived parsing workers++Heavy synchronous extraction can retain native-library memory in a long-lived+API process even when run in a thread. The+[isolated-worker boundary](../deeptutor/runtime/isolated_worker.py) launches a+short-lived interpreter through+[`worker_process.py`](../deeptutor/runtime/worker_process.py), using an internal+importable callable and private temporary input/result files.++This is trusted internal IPC. Its serialized Python objects are not an API for+untrusted upload or network input. Clients cannot select an arbitrary callable.+The child process boundary releases its memory on exit, but is not by itself an+OS security sandbox for untrusted code.++Timeout and cancellation must terminate and join the process tree before+returning. Concurrency is bounded by `DEEPTUTOR_ISOLATED_WORKERS` (default two);+call sites can override the default timeout. Keep platform-specific cleanup+and result/error restoration covered by+[worker tests](../tests/runtime/test_isolated_worker.py). Parser failures must+remain distinguishable from empty successful extraction.++## Private model history++Display messages and provider-ready model history serve different purposes.+[`model_history.py`](../deeptutor/services/session/model_history.py) retains a+versioned private `model_turn` with prepared input, snapshots, model/tool+messages, replay metadata and request fingerprints. Public session responses+and exports redact it. Legacy rows without valid model metadata retain their+display-history fallback.++The shared loop appends changing runtime facts as named snapshots while+keeping standing instructions stable. Replacing one snapshot changes that+section; it must not reinterpret source material as system policy. Tool+availability, workspace paths and resource permissions still come from their+normal authorities.++Retention/compaction must keep a model turn's tool calls and results together.+Interrupted tools get an explicit unavailable-outcome result rather than a+fabricated successful response. Route changes remove incompatible private+provider replay fields while retaining public evidence. Changes must preserve+stored conversation content and account/workspace isolation.++## Cache evidence++Request-cache diagnostics compare canonical request fingerprints and unchanged+prefix messages. They do not prove that a provider served cached tokens.+Actual provider usage counters are the evidence for billed/cache-hit behavior;+route changes, eviction, tool changes and compaction can invalidate reuse.++Start with [model-history regressions](../tests/services/session/test_model_history.py)+and [request-cache tests](../tests/services/llm/test_request_cache.py). The+opt-in [prompt-cache integration test](../tests/integration/test_prompt_cache.py)+uses synthetic inputs with the configured real provider:++```bash+DEEPTUTOR_CACHE_E2E=1 python -m pytest tests/integration/test_prompt_cache.py -q+```++This can incur provider usage. A passing synthetic cache probe is not a+production latency or cost benchmark, and stage-specific pipelines may have+different history contracts from the shared chat loop.diff --git a/docs/SCIENTIFIC_RESEARCH.md b/docs-for-dev/SCIENTIFIC_RESEARCH.mdsimilarity index 89%rename from docs/SCIENTIFIC_RESEARCH.mdrename to docs-for-dev/SCIENTIFIC_RESEARCH.mdindex ef68af6c1..ab06b11ba 100644--- a/docs/SCIENTIFIC_RESEARCH.md+++ b/docs-for-dev/SCIENTIFIC_RESEARCH.md@@ -1,8 +1,11 @@# Scientific research workflows+[Handbook](README.md) · [Related guide](TOOLS_AND_CAPABILITIES.md)+DeepTutor mounts `preprint`, `research_audit` and `research_lit` for scientificpaper requests, paper-search-enabled chat, and Deep Research. They are-context-gated tools; the seven user-toggleable tools remain unchanged.+context-gated tools, separate from the eight user-toggleable tools described+in [Tools and capabilities](TOOLS_AND_CAPABILITIES.md#mounting-rules).- `preprint(paper, action="read", pages=[...])` reads the primary arXiv PDF,preserves requested versions and legacy archive IDs, records its SHA-256 and@@ -89,3 +92,10 @@ setting changes neither `web_fetch` nor native paper/repository downloads.Legacy administrator-owned local/stdio configurations keep their originalbehavior. Native arXiv metadata is paced in-process; provider rate-limit errorsremain visible. See the [arXiv API documentation](https://info.arxiv.org/help/api/user-manual.html).++## Implementation and verification++- [deeptutor/tools/research_tools.py](../deeptutor/tools/research_tools.py)+- [deeptutor/services/research/primitives.py](../deeptutor/services/research/primitives.py)+- [tests/services/research/test_primitives.py](../tests/services/research/test_primitives.py)+- [tests/services/research/test_mcp_boundaries.py](../tests/services/research/test_mcp_boundaries.py)diff --git a/docs-for-use/SECURITY_GUARD.md b/docs-for-dev/SECURITY_GUARD.mdsimilarity index 93%rename from docs-for-use/SECURITY_GUARD.mdrename to docs-for-dev/SECURITY_GUARD.mdindex f0bb0d2bf..b350d3486 100644--- a/docs-for-use/SECURITY_GUARD.md+++ b/docs-for-dev/SECURITY_GUARD.md@@ -1,5 +1,7 @@# Optional request screening (fastapi-guard)+[Handbook](README.md) · [Related guide](CONTAINERIZATION.md)+DeepTutor can screen HTTP requests inside the backend with [fastapi-guard](https://github.com/Guard-Core/fastapi-guard). It is **off by default**. When it is off, the package is never imported and the middleware stack is unchanged. Like any new setting, `system.json` gains the disabled `security_guard` block with its defaults on the next load, and a malformed block is replaced by the defaults.The guard is an application-layer control. It complements a reverse proxy, WAF or firewall at the edge, and it keeps working when the backend port is reached without one (for example a published `:8001`, `deeptutor serve` on a LAN, or a tunnel).@@ -26,10 +28,13 @@ Two engine behaviours worth knowing, as of fastapi-guard 8.1.1 / guard-core 4.4.## Enable it-1. Install the extra (it adds `fastapi-guard`; `redis` is already a DeepTutor dependency, `maxminddb` and `cachetools` are new):+1. Install the optional guard dependencies in the environment that owns the server:```bash- pip install "deeptutor[guard]" # or: pip install -r requirements/guard.txt+ # Source checkout:+ python scripts/install_extras.py guard+ # Wheel environment with the server already installed:+ python -m pip install "deeptutor[guard]"```In Docker set `DEEPTUTOR_EXTRAS: "guard"` on the service, the same way as other extras (see [CONTAINERIZATION.md](CONTAINERIZATION.md)).@@ -79,3 +84,8 @@ Dual-stack binds: with guard-core 4.4.0, a peer reported in IPv4-mapped form (`:**Bundled frontend.** The Next.js proxy (`web/proxy.ts`) deletes `X-Forwarded-For` and the other forwarded headers from browser requests (`web/lib/backend-forward.ts`) and does not add the browser's address. Requests that reach the backend through it all arrive from the frontend's own address (loopback in the default layout), with no forwarded header. One shared limit would throttle every user together, so `exempt_ips` (default `127.0.0.1` and `::1`) exempts that address from the rate limit. Through the frontend, requests are therefore screened for attack patterns and the denylist, but not rate-limited. Per-client limits apply to requests that reach the backend directly, or through a reverse proxy that sets `X-Forwarded-For` and is listed in `trusted_proxies` (with `exempt_ips` containing loopback, a loopback request that carries `X-Forwarded-For` is limited as the forwarded client). `exempt_ips` skips the rate limit only: the denylist, bans and the attack-pattern scan still apply to listed addresses. The guard does not ban loopback addresses.**Allowlist with the bundled frontend.** If `whitelist` is set, frontend traffic (loopback) is refused unless loopback is listed. With the bundled frontend, add `127.0.0.1` and `::1` to `whitelist`. The allowlist and denylist then govern direct backend access only, because the frontend hides browser addresses.++## Implementation and verification++- [deeptutor/api/security_guard.py](../deeptutor/api/security_guard.py)+- [tests/api/test_security_guard.py](../tests/api/test_security_guard.py)diff --git a/docs-for-use/SOURCE_VISUALS.md b/docs-for-dev/SOURCE_VISUALS.mdsimilarity index 95%rename from docs-for-use/SOURCE_VISUALS.mdrename to docs-for-dev/SOURCE_VISUALS.mdindex 63e2d9bff..9b9b4884a 100644--- a/docs-for-use/SOURCE_VISUALS.md+++ b/docs-for-dev/SOURCE_VISUALS.md@@ -1,5 +1,7 @@# Source visuals in knowledge bases+[Handbook](README.md) · [Related guide](INDEXING_RECOVERY.md)+DeepTutor can retain extracted source images when a PDF or EPUB parser emitsimage files. The KB stores verified parser-extracted PNG, JPEG, GIF, or WebPbytes with a deterministic asset ID, document hash, parser identity, source@@ -213,7 +215,9 @@ Use `false` to disable it. The option also lives at`engines.mineru.normalize_tiny_scans` in `document_parsing.json`. Enabling itchanges the cloud parse-cache signature; old parses remain intact. Existingindexes are not rebuilt automatically. The optional-`deeptutor[parse-pymupdf4llm]` extra provides the required PyMuPDF dependency.+`deeptutor[parse-pymupdf4llm]` wheel extra provides the required PyMuPDF dependency.+For a source checkout, use `python scripts/install_extras.py parse-pymupdf4llm`+(see [module installation](MODULES.md#source-checkout)).Only text-free pages below 144 points on their longest side, with ahigh-resolution image covering at least 80% of the page at an apparent density@@ -252,3 +256,11 @@ not cached; successful split groups can be reused. Setting the sizeback to `1` restores the normal single-image path. The model must supportmultiple image blocks; unsupported API responses are reported without a burstof fallback requests.++## Implementation and verification++- [deeptutor/services/rag/visual_assets.py](../deeptutor/services/rag/visual_assets.py)+- [deeptutor/services/rag/source_pages.py](../deeptutor/services/rag/source_pages.py)+- [deeptutor/services/parsing/engines/mineru/](../deeptutor/services/parsing/engines/mineru/)+- [deeptutor/learning/visual_practice.py](../deeptutor/learning/visual_practice.py)+- [tests/services/rag/test_source_visual_grounding.py](../tests/services/rag/test_source_visual_grounding.py)diff --git a/docs-for-dev/TESTING.md b/docs-for-dev/TESTING.mdnew file mode 100644index 000000000..5e4d79ff8--- /dev/null+++ b/docs-for-dev/TESTING.md@@ -0,0 +1,96 @@+# Testing and validation++[Handbook](README.md) · [Development](DEVELOPMENT.md) · [Modules](MODULES.md#validation)++Use the repository's configured tools and the environment from+[Agent setup](AGENT_SETUP.md). Run targeted checks during development and the+affected project gates before publishing. A documentation-only change does+not require paid model calls or a full rendering workload.++## Select checks by change++| Change | Minimum useful evidence |+| --- | --- |+| Documentation and CLI examples | Links/anchors, CLI documentation contracts, command help, no stale paths |+| Python domain logic | Focused pytest reproduction; Ruff; relevant import boundaries |+| API or turn events | Request/authorization tests, generated contract check, persistence/replay tests, consumer tests |+| Frontend behavior | Typecheck, focused Node/Vitest test, dependency check; browser verification for interaction/layout |+| Module ownership/dependencies | Generated requirements, module isolation, wheel lifecycle smoke |+| Plugin worker or packaged page | Manifest, runtime/lifecycle and API tests, reference example wheel |+| Parsing/subprocess code | Real child success/error/timeout/cancellation; relevant platform checks |+| Provider/model integration | Mocked contract tests plus an explicitly configured real-provider probe when needed |++## Python++```bash+python -m pytest tests/cli/test_docs_contract.py tests/scripts/test_docker_compose.py+python -m pytest tests/app tests/runtime/coordination+python -m pytest tests/plugins tests/api/test_plugins_router.py+python -m ruff check .+python -m ruff format --check .+lint-imports+python scripts/check_architecture.py+python scripts/sync_module_requirements.py --check+python scripts/check_repo_hygiene.py+```++These are separate entry points; select the relevant suites rather than+assuming the first command covers all changes. The full Python suite is+`python -m pytest tests deeptutor/learning/tests`. Some integration cases+need fixtures such as Redis, optional engines or platform executables.+Read skip conditions and report skipped checks accurately.++`check_repo_hygiene.py` checks tracked paths. The stricter+`check_workspace_hygiene.py` also requires an entirely clean checkout, so run+it after committing rather than interpreting intended edits as a test failure.++## Web and generated contracts++From `web/`:++```bash+npm run typecheck+npm run architecture:check+npm run test:node+npm run test:unit+npm run lint+npm run i18n:check+npm run contracts:check+```++`npm run check:fast` runs the deterministic checks above; `npm run check`+adds the production build and route budgets. Use `npm run contracts:generate`+after changing backend schemas, then inspect and commit the generated diff.+The generator owns [`web/contracts/`](../web/contracts/) and calls the+[Python export script](../scripts/export_frontend_contracts.py).++Rendered component tests use Vitest and Testing Library. Node tests cover+pure contracts and state logic. Playwright `npm run audit` expects a running+frontend at `WEB_BASE_URL`; critical and multi-worker projects have separate+fixture requirements in [`playwright.config.ts`](../web/playwright.config.ts).+Do not run browser mutations against a learner's only copy of data.++## Modules, engines and optional integration++Follow [Modules → Validation](MODULES.md#validation) for disposable wheel+installation, uninstall/reinstall and retained-data checks. Do not use the+development interpreter to test package removal.++The experimental TypeScript engine has its own `npm test` under+[`packages/chat-engine/`](../packages/chat-engine/), plus Python bridge and+application compatibility tests. The canonical matrix is in+[`tests.yml`](../.github/workflows/tests.yml) and+[`modules.yml`](../.github/workflows/modules.yml).++`deeptutor doctor --online` performs a real model request. Prompt-cache,+video rendering and multi-worker acceptance tests may require explicit opt-in+variables. State the actual environment and verification performed; historical+test counts and a mock provider do not establish current production behavior.++## Reviewing a documentation change++Check relative links from each file, not from the repository root. Search+README translations, CLI help, UI setup prompts and test fixtures when moving+a guide. Keep source links free of fragile line numbers. Use the installed+CLI's `--help` and authoritative manifests/settings to validate commands and+defaults. Keep local artifacts and secrets out of the commit.diff --git a/docs-for-dev/TOOLS_AND_CAPABILITIES.md b/docs-for-dev/TOOLS_AND_CAPABILITIES.mdnew file mode 100644index 000000000..05844dc93--- /dev/null+++ b/docs-for-dev/TOOLS_AND_CAPABILITIES.md@@ -0,0 +1,74 @@+# Tools and capabilities++[Handbook](README.md) · [Architecture](ARCHITECTURE.md) · [Modules](MODULES.md) · [Plugins](PLUGINS.md)++## The two contracts++[`BaseTool`, `ToolDefinition`, and `ToolResult`](../deeptutor/core/tool_protocol.py)+describe one operation selected by a model. A tool validates arguments,+performs the operation and returns content plus structured metadata/error+state. Availability is not equivalent to permission to access every resource.++[`TurnCapability` and `CapabilityManifest`](../deeptutor/core/capability_protocol.py)+describe a pipeline that owns a turn. A capability consumes `UnifiedContext`+and emits stream events. Capabilities converge on+[`emit_capability_result()`](../deeptutor/agents/_shared/capability_result.py) for the+response payload and `cost_summary`; do not invent another completion envelope.++The built-in catalog is derived from+[`modules/manifests/`](../deeptutor/modules/manifests/) by+[`builtin_capabilities.py`](../deeptutor/runtime/bootstrap/builtin_capabilities.py).+Use `deeptutor module list`, `deeptutor plugin list` and `deeptutor plugin info`+to inspect the current installation rather than assuming every source feature+is available in a core-only wheel environment.++## Mounting rules++The eight user-toggleable tools are `brainstorm`, `web_search`, `paper_search`,+`zotero_search`, `reason`, `geogebra_analysis`, `imagegen` and `videogen`.+`USER_TOGGLEABLE_TOOL_NAMES` in+[`tools/builtin/__init__.py`](../deeptutor/tools/builtin/__init__.py) is the+authoritative list; CLI `--tool` selects from it.++`CONFIGURABLE_BUILTIN_TOOL_NAMES` declares context-gated tools, including+research, retrieval, memory, notebook, execution and deferred tool discovery.+[`tool_composition.py`](../deeptutor/agents/_shared/tool_composition.py) owns+mount flags and always-available workspace tools. Capability-owned solve,+mastery and other specialized tools follow their activation contracts.+The Partner allow/deny surface can further narrow access.++Account grants, workspace resource policies, module selection and capability+activation must all remain effective at discovery and dispatch. A tool name+in a UI or a manifest must not bypass those checks. MCP/CLI deferred discovery+must use the existing loader rather than installing a parallel registry.++## Add or change a built-in++1. Implement the typed operation or capability in its owning module. Keep+ optional libraries out of metadata-only imports.+2. Update the tool spec or capability declaration, aliases and the owning+ module manifest. The lazy tool descriptors live in+ [`builtin_specs.py`](../deeptutor/tools/builtin_specs.py).+3. Put mounting logic in the existing composition/activation owner. Decide+ explicitly whether a tool is user-toggleable, context-gated or+ capability-owned.+4. Update request validation and translated prompts where needed. Capability+ prompts live under [`capabilities/prompts/`](../deeptutor/capabilities/prompts/);+ some agent implementations own additional prompts in their own directory.+5. Test metadata/implementation parity, missing-module behavior, authorized+ resource scope, failure and cancellation, and the public result envelope.+ Follow [Testing](TESTING.md) for schema regeneration and broader checks.++For an independently distributed package, use the [plugin contract](PLUGINS.md)+and [Learning Echo example](examples/learning_echo/README.md) instead of+modifying built-in registration. Reading toolbar actions have a separate+[Reading extension protocol](READING_EXTENSIONS.md).++## Diagnose an unexpected tool call++Compare the active module state, capability, selected resources, user tool+selection and workspace policies with the actual schemas admitted to the+model request. Then inspect dispatch and the returned evidence. A selected KB+does not prove retrieval ran; a retrieved URL does not prove pixels reached+the model. See [source visuals](SOURCE_VISUALS.md) and+[answer-quality diagnosis](REASONING_SAFETY_CHECKLIST.md).diff --git a/docs-for-dev/VOICE_CONFIGURATION.md b/docs-for-dev/VOICE_CONFIGURATION.mdnew file mode 100644index 000000000..5d0edd3bb--- /dev/null+++ b/docs-for-dev/VOICE_CONFIGURATION.md@@ -0,0 +1,58 @@+# Speech configuration and adapter development++[Handbook](README.md) · [Agent setup](AGENT_SETUP.md) · [Video learning](watching-workspace.md)++TTS (speech synthesis) and STT (speech recognition) have their own provider+profiles and defaults in Speech settings, independently of the chat model.++## Configure and verify++1. Select an implemented provider and supply its endpoint, exact model/resource+ ID and credential type.+2. Discover voices through the provider when supported. Voice IDs are not a+ permanent bundled catalog; account-specific voices and model IDs remain+ editable. A listed voice does not prove account entitlement.+3. Choose language, format and other options supported by that model family.+4. Preview a short sample, then save/select the default. Preview uses the current+ form without changing the saved default.+5. Verify actual read-aloud or transcription after saving. Model-list success+ alone does not prove speech synthesis or recognition works.++Preview invokes the provider and may incur usage. Form changes invalidate the+old preview; an in-flight preview can be cancelled. Request timeout accepts+5–600 seconds, defaulting to 60. Short samples help isolate configuration errors.++## Provider boundaries++- **Volcengine Speech:** Speech credentials differ from Ark LLM keys. The+ adapter accepts Speech API Key authentication and the older App ID/access-token+ form. Match TTS resource and voice family. STT uses a recording-file API;+ audio normalization may require system FFmpeg.+- **Aliyun DashScope:** Qwen3 TTS and Qwen-Audio TTS have distinct native+ endpoints and parameters. The adapter normalizes supported official+ compatible-mode bases; a private endpoint must implement the selected+ protocol. Match key and endpoint region. Confirm voices through discovery+ and actual preview instead of assuming an old example remains available.+- **Other adapters:** a compatible chat endpoint does not establish a+ compatible speech API. Model options and live discovery determine supported+ voices and formats.++Preserve distinct authentication, region/model, permission, rate-limit, timeout+and audio-download errors without exposing credential-bearing responses.+Retain cancellation and configured timeouts rather than adding unbounded retries.++## Source map++| Responsibility | Implementation |+| --- | --- |+| Profiles and resolution | [voice/config.py](../deeptutor/services/voice/config.py) |+| Model/parameter hints | [voice/options.py](../deeptutor/services/voice/options.py) |+| Voice discovery | [voice/discovery.py](../deeptutor/services/voice/discovery.py) |+| Preview | [voice/preview.py](../deeptutor/services/voice/preview.py) |+| Provider protocols | [voice/adapters/](../deeptutor/services/voice/adapters/) |+| Audio conversion | [voice/audio.py](../deeptutor/services/voice/audio.py) |++When adding an adapter, test credential handling, endpoint normalization,+decoding, timeout/cancellation and error redaction. Report live checks separately+from mocked protocol tests. Provider catalogs, availability and billing remain+external to this repository.diff --git a/docs-for-dev/examples/learning_echo/README.md b/docs-for-dev/examples/learning_echo/README.mdnew file mode 100644index 000000000..f4d558e47--- /dev/null+++ b/docs-for-dev/examples/learning_echo/README.md@@ -0,0 +1,64 @@+# Learning Echo plugin++[Handbook](../../README.md) · [Plugin contract](../../PLUGINS.md) · [Testing](../../TESTING.md)++This package is the reference implementation for the managed plugin runtime.+It declares one Tool, one Capability, one HTTP route, and one static frontend+page. The page requests only the `sandboxed-iframe` UI permission; the package+has no Python dependencies.++## Package layout++- [Manifest](learning_echo/deeptutor.plugin.json): plugin identity, permissions+ and the four extension declarations.+- [Worker](learning_echo/worker.py): descriptions, tool execution, capability+ streaming and JSON HTTP responses.+- [Page manifest](learning_echo/frontend/page.json): the explicit static asset+ closure; [index.html](learning_echo/frontend/index.html) and+ [app.js](learning_echo/frontend/app.js) implement the sandboxed page.+- [Build metadata](pyproject.toml): packages the worker, manifest and assets.++## Build and inspect++From the repository root, build a local wheel:++```bash+python -m pip wheel --no-deps -w /tmp/deeptutor-plugins docs-for-dev/examples/learning_echo+```++Use a disposable `DEEPTUTOR_HOME`, then run `deeptutor plugin install` with+the generated wheel path and inspect it with:++```bash+deeptutor plugin show org.deeptutor.learning_echo+deeptutor plugin state+```++Review the manifest and artifact before calling+`deeptutor plugin approve org.deeptutor.learning_echo`; explicitly enable it+if it is disabled. Installed and approved are distinct states. The install+step reads `deeptutor.plugin.json` before importing plugin code and creates a+plugin-private virtual environment.++After approval and enablement, the page is available at+`/api/plugins/org.deeptutor.learning_echo/pages/learning_echo_page/`. Its entry+and asset closure are declared in `learning_echo/frontend/page.json`.++With host authentication enabled, opening the page or its `public` HTTP route+still requires the host session. The page's CSP blocks arbitrary network+access; it is not an example of injecting host frontend code.++## Verify and adapt++From the repository root:++```bash+python -m pytest tests/plugins/test_runtime.py tests/api/test_plugins_router.py+```++These tests use this package as the worker/page fixture. Preserve the tests+when moving or changing the example. For a new plugin, choose a distinct+package/manifest identity, declare the actual permission and dependency+closure, and test failure, cancellation, disabled state and reapproval after+an upgrade. See [the plugin guide](../../PLUGINS.md) for trust limits and+rollback behavior.diff --git a/examples/plugins/learning_echo/learning_echo/__init__.py b/docs-for-dev/examples/learning_echo/learning_echo/__init__.pysimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/__init__.pyrename to docs-for-dev/examples/learning_echo/learning_echo/__init__.pydiff --git a/examples/plugins/learning_echo/learning_echo/deeptutor.plugin.json b/docs-for-dev/examples/learning_echo/learning_echo/deeptutor.plugin.jsonsimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/deeptutor.plugin.jsonrename to docs-for-dev/examples/learning_echo/learning_echo/deeptutor.plugin.jsondiff --git a/examples/plugins/learning_echo/learning_echo/frontend/app.js b/docs-for-dev/examples/learning_echo/learning_echo/frontend/app.jssimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/frontend/app.jsrename to docs-for-dev/examples/learning_echo/learning_echo/frontend/app.jsdiff --git a/examples/plugins/learning_echo/learning_echo/frontend/index.html b/docs-for-dev/examples/learning_echo/learning_echo/frontend/index.htmlsimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/frontend/index.htmlrename to docs-for-dev/examples/learning_echo/learning_echo/frontend/index.htmldiff --git a/examples/plugins/learning_echo/learning_echo/frontend/page.json b/docs-for-dev/examples/learning_echo/learning_echo/frontend/page.jsonsimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/frontend/page.jsonrename to docs-for-dev/examples/learning_echo/learning_echo/frontend/page.jsondiff --git a/examples/plugins/learning_echo/learning_echo/worker.py b/docs-for-dev/examples/learning_echo/learning_echo/worker.pysimilarity index 100%rename from examples/plugins/learning_echo/learning_echo/worker.pyrename to docs-for-dev/examples/learning_echo/learning_echo/worker.pydiff --git a/examples/plugins/learning_echo/pyproject.toml b/docs-for-dev/examples/learning_echo/pyproject.tomlsimilarity index 100%rename from examples/plugins/learning_echo/pyproject.tomlrename to docs-for-dev/examples/learning_echo/pyproject.tomldiff --git a/docs-for-use/remote-hermes-backend.md b/docs-for-dev/remote-hermes-backend.mdsimilarity index 90%rename from docs-for-use/remote-hermes-backend.mdrename to docs-for-dev/remote-hermes-backend.mdindex 27e4ed3ea..73764e318 100644--- a/docs-for-use/remote-hermes-backend.md+++ b/docs-for-dev/remote-hermes-backend.md@@ -1,5 +1,7 @@# Remote Hermes Agent backend+[Handbook](README.md) · [Related guide](ARCHITECTURE.md)+DeepTutor Connected Agents can call a Hermes Agent gateway without installing aHermes CLI in the DeepTutor container. The backend kind is `hermes_remote` andits display name is **Hermes Agent (remote)**.@@ -92,3 +94,10 @@ settings files, logs, event text, and frontend payloads.Streaming is quiet except for the structured SSE lifecycle exposed by theadapter. It does not poll or retry `POST /v1/runs`; a caller cancellation oridle watchdog always attempts a bounded stop.++## Implementation and verification++- [deeptutor/services/subagent/hermes_remote.py](../deeptutor/services/subagent/hermes_remote.py)+- [deeptutor/services/subagent/hermes_remote_client.py](../deeptutor/services/subagent/hermes_remote_client.py)+- [deeptutor/services/subagent/hermes_remote_events.py](../deeptutor/services/subagent/hermes_remote_events.py)+- [tests/services/test_hermes_remote_backend.py](../tests/services/test_hermes_remote_backend.py)diff --git a/docs-for-use/watching-workspace.md b/docs-for-dev/watching-workspace.mdsimilarity index 94%rename from docs-for-use/watching-workspace.mdrename to docs-for-dev/watching-workspace.mdindex f90b610c5..fc0b132a6 100644--- a/docs-for-use/watching-workspace.md+++ b/docs-for-dev/watching-workspace.md@@ -1,5 +1,7 @@# Video learning in Immersive Reading+[Handbook](README.md) · [Related guide](READING_EXTENSIONS.md)+Open **Reading** under Learning, add a YouTube or Bilibili URL to a collection, and study it beside the tutor. Videos use the same reading material, transcript, annotations and conversation stores as documents. The media stage supports transcript search and follow, timestamp citations, fullscreen viewing and the current/next caption lines. Missing captions or unsupported playback are shown explicitly; a tutor must not claim to have watched footage from transcript text alone.New timestamped notes are Reading annotations. Their location is captured when the editor opens, so playback moving while you write does not move the note. Failed saves keep the draft for retry; an older save finishing does not erase newer text.@@ -21,3 +23,8 @@ Use **Browse Invidious** in the add-material dialog to search or select from an## Verification and recoveryCheck playback, seeking, transcript search/follow, timestamp citations, and note save/edit/retry. Reopen a migrated conversation and confirm that its message history and source identity remain unchanged. Also check missing captions, an unavailable provider, narrow screens and owner access boundaries. Preserve the existing data directory and owner identity during deployment or rollback; do not overwrite newer user data with a backup merely to undo a frontend change.++## Implementation and verification++- [deeptutor/reading/](../deeptutor/reading/)+- [web/components/reading/](../web/components/reading/)diff --git a/docs-for-use/workspaces.md b/docs-for-dev/workspaces.mdsimilarity index 93%rename from docs-for-use/workspaces.mdrename to docs-for-dev/workspaces.mdindex b3625bc8b..a143237bf 100644--- a/docs-for-use/workspaces.md+++ b/docs-for-dev/workspaces.md@@ -1,6 +1,8 @@# 工作区与学习数据-普通对话在输入框选择或新建工作区;书籍、掌握路径、沉浸式阅读、沉浸式观看在开始弹窗选择工作区。任务的资料、会话、进度、练习记录和生成文件都保存在所选工作区,未选择时使用「默认工作区」。侧栏历史与个性化学习首页汇总当前账号的各工作区记录,打开记录时进入它所属的工作区。+[Handbook](README.md) · [Related guide](DATA_STORAGE.md)++普通对话在输入框选择或新建工作区;书籍、掌握路径、沉浸式阅读(含视频学习)在开始弹窗选择工作区。任务的资料、会话、进度、练习记录和生成文件都保存在所选工作区,未选择时使用「默认工作区」。侧栏历史与个性化学习首页汇总当前账号的各工作区记录,打开记录时进入它所属的工作区。升级后,原有学习数据保留在原来的目录,统一属于默认工作区。旧版给对话设置的文件夹绑定不会自动拆分历史资料;需要重新整理时,使用「设置 → 个人 → 数据迁移」。@@ -86,3 +88,8 @@ sessions = await app.list_sessions()知识中心集中显示账户及各未归档工作区的知识库,并标注来源;新建资源默认进入账户资源库。删除资源前会列出引用它的工作区。资源删除或失去访问权限后不会自动启用其他资源,分配设置中会提示失效条目。移动工作区文件夹保留其资源引用;若迁移整个知识库数据到另一工作区,须先解除相关分配,或选择导出副本。工作区分配控制 DeepTutor 暴露和调用哪些 MCP 服务。外部服务自身的文件、数据库和远程账号权限仍由该服务配置决定;分配不会自动改变其进程、根目录或远程授权。++## Implementation and verification++- [deeptutor/services/workspace/](../deeptutor/services/workspace/)+- [deeptutor/services/partners/workspace_binding.py](../deeptutor/services/partners/workspace_binding.py)diff --git a/docs-for-use/VOICE_CONFIGURATION.md b/docs-for-use/VOICE_CONFIGURATION.mddeleted file mode 100644index 409895fa0..000000000--- a/docs-for-use/VOICE_CONFIGURATION.md+++ /dev/null@@ -1,57 +0,0 @@-# 语音配置与音色试听--语音合成(TTS)和语音识别(STT)位于「设置 → 语音」;图像、视频生成位于「设置 → 多模态生成」。两者分别选择模型和默认配置。--## 火山引擎原生语音--在语音页面新增 **Volcengine Speech (Doubao)** 服务商。这里使用火山语音控制台的凭据,与方舟 Ark 的模型 API Key 分开。--- 新版控制台:填入 Speech API Key,App ID 留空。-- 旧版控制台:填入 App ID,并在密钥栏填 Access Token。-- 默认地址:`https://openspeech.bytedance.com/api/v3`。-- TTS:选择模型资源 ID,例如 `seed-tts-2.0`,再选择相同版本的音色,例如 Vivi 2.0。可配置语言、语速、格式、采样率;TTS 2.0 可填写表达指令。-- STT:模型使用 `bigmodel`,默认资源 ID 为 `volc.bigasr.auc_turbo`,使用录音文件识别极速版接口。浏览器录音会转换为 16 kHz 单声道 WAV;转换需要系统安装 ffmpeg。--账号须已开通所选资源及音色权限。模型或音色出现在建议列表中,不代表当前账号已获授权。--## 按模型配置--选项按服务商和具体模型提供。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-use/workspace-resources-verification.md b/docs-for-use/workspace-resources-verification.mddeleted file mode 100644index 7c9a17509..000000000--- a/docs-for-use/workspace-resources-verification.md+++ /dev/null@@ -1,60 +0,0 @@-# Workspace resource assignment verification--Verified locally on 2026-09-19 against the current working tree.--## Compatibility--- Missing resource policies keep the previous workspace access rules; no existing indexes, credentials or learning records are moved.-- Null means inherited access; an empty list explicitly disables that resource type.-- MCP selections narrow account grants at discovery, schema loading, cached schema recovery and dispatch.-- Skill manifests and reads share one resolver, including local overrides and always-loaded bodies.-- Knowledge references identify both catalog origin and name; selections cannot grant another account's private resources.-- Referenced knowledge catalogs cannot be moved through aggregate data migration until their assignments are removed. Moving a workspace folder preserves its identity.--## Passed checks--- Related knowledge, skills and provider regression run: 153 tests.-- Workspace, permissions and provider boundary regression run: 143 tests.-- Final focused policy, MCP and read-skill run: 25 tests. Counts overlap.-- Frontend workspace settings, resource picker, knowledge creation, Co-Writer and scope regression: 24 tests across six files.-- TypeScript typecheck; lint on the affected surfaces; backend Ruff; API contract export/generation check; locale key parity; production build.-- Browser verification in an isolated runtime: existing inherited workspace, creation of a selected workspace, persisted skills/MCP/KB assignments, account resource library and workspace-specific skill creation, verified absent from the account-shared catalog. Existing user data and the running user instance were not used for QA.--## Broader working-tree test result--The full Node frontend test suite reported 1,150 passed and 34 failed. This is **not** a claim of a clean repository-wide baseline. The working tree contains other ongoing changes; several failures assert older URLs without the current `dt_workspace` query parameter, while others concern unrelated update/trace/settings contracts. The failures are preserved here rather than counted as passing resource-assignment validation.--- app update client uses the canonical system routes-- sidebar presents the update state as a clickable status dot-- reasoning produced after a card becomes its own segment below it-- a turn with no tool work is a single run of prose-- an app id with URL-significant characters is escaped in the path-- ordinary users send a scoped Codex reasoning effort update-- global surfaces are handed the course so they can scope themselves-- course organization patch sends only the requested metadata-- GraphRAG candidate probe sends catalog IDs without activating the model-- listImaKnowledgeBases sends credentials and preserves pagination-- IMA credential rejection stays inline instead of redirecting login-- connectImaKnowledgeBase sends the DeepTutor name and invalidates on success-- create and re-index send the exact pinned selection and preserve none-- pending-policy update is JSON-only and creates no indexing request-- model controls are scoped to built-in LightRAG create/rebuild surfaces-- a timed-out model catalog request can be retried-- every device-bridge call names its library through X-MN4-KB-- a device id is escaped into the revoke path-- a hand-written disabled_tools blocklist survives GET → edit → PUT-- the request path comes from the caller's surface, not a hardcoded base-- the per-user surface reads its own route and keeps the additive fields-- toggling one server writes only that server-- a rename adds the new server before removing the old one-- a refused rename never reaches the delete-- a name with URL-significant characters is escaped in the path-- removing the last server still refreshes from the response-- a no-op write re-reads instead of PUTting anything-- the admin registry keeps its whole-map PUT-- onboarding client sends the partner-scoped lifecycle requests-- channel runtime client reads the partner-scoped status endpoint-- settings-context: persistUiSettingsPatch sends only the changed code-block field-- settings-context: persistUiSettingsPatch can save theme without sending code-block fields-- Next's checked-in environment declaration uses the canonical dev cache-- Watching links retain their owning workspace, including legacy sessionsdiff --git a/docs/guides/events-and-progress-chain.md b/docs/guides/events-and-progress-chain.mddeleted file mode 100644index 3d3e6a899..000000000--- a/docs/guides/events-and-progress-chain.md+++ /dev/null@@ -1,146 +0,0 @@-# 事件与进度链路代码导读(guide-events-2026-10-04)--- 基线:`origin/dev @ fe003ddce`(v1.6.12)。-- 范围:`deeptutor/events/event_bus`(全局事件总线)、KB 进度上报与 WS 广播、任务事件与前端 Activity 的衔接、事件丢失/乱序的既有防护;文末与 fix-progress-\* 系列卡结论互引。-- 行号锚均为该基线下的 `path:line`,相对仓库根目录。--## 0. 全景:三条链路--DeepTutor 里"事件"不是一条总线,而是三条各自独立的链路,读代码时先分清:--| 链路 | 生产者 | 载体 | 消费者 | 现状 |-| --- | --- | --- | --- | --- |-| A. KB 进度/任务事件 | 索引任务(ProgressTracker) | 双通道:WS 广播 + SSE 任务流 | `useKnowledgeProgress` → 日志框/进度条 | 主线,即 fix-progress-\* 系列对象 |-| B. 全局 EventBus | orchestrator / partners 完成事件 | 进程内单例队列 | **当前无任何生产订阅者** | 火后不理的事实审计钩子 |-| C. 会话/书/伙伴/学习活动流 | StreamBus、book hub、partner feed、mastery hub | 各自的 WS/SSE | 聊天 ActivityStack、书页、伙伴面板 | 各自带重放/续传机制 |--链路 A 的端到端流转(bus→WS→前端,验收点 1):--```mermaid-flowchart LR- subgraph 后端- IDX["索引任务<br/>run_initialization_task / run_reindex_task<br/>knowledge.py:974 / :3718"]- PT["ProgressTracker.update<br/>progress_tracker.py:176"]- PERS["持久化<br/>.progress.json + kb_config.json<br/>progress_tracker.py:114"]- PORT["端口层 progress_events<br/>broadcast_progress / emit_task_progress<br/>progress_events.py:31 / :36"]- BC["ProgressBroadcaster.broadcast<br/>progress_broadcaster.py:47"]- TSM["KnowledgeTaskStreamManager.emit<br/>task_log_stream.py:66"]- WS["WS /ws/knowledge-bases/{kb}/progress<br/>knowledge.py:4256"]- SSE["SSE /knowledge-bases/tasks/{task_id}/stream<br/>knowledge.py:3299"]- end- subgraph 前端- HOOK["useKnowledgeProgress<br/>useKnowledgeProgress.ts:69"]- UI["KbTaskLogs 日志框+进度条<br/>KbTaskLogs.tsx:14"]- end- IDX -->|"task_id 注入 tracker<br/>knowledge.py:1016 / :3795"| PT- PT --> PERS- PT -->|"有 task_id 时"| PORT- PORT -->|"emit_task_event"| TSM --> SSE- PORT -->|"create_task 广播"| BC- BC --> WS- WS -->|"快照+增量帧"| HOOK- SSE -->|"process_log/progress/complete/failed"| HOOK- HOOK --> UI-```--## 1. 全局事件总线 `deeptutor/events/event_bus.py`--- 数据结构:`Event`(type/task_id/agent_output/event_id/timestamp,:31-55);`EventType` 只有三种完成事件(:22-28)。-- `EventBus` 是进程级单例(:69-88):每个事件类型一个 handler 列表 + 一个 `asyncio.Queue`。-- 发布:`publish()` 只做入队,首发布时自动 `start()` 后台消费协程(:101-106)。-- 消费:`_process_events()` 逐事件串行调用 handler;单个 handler 抛错记 `logger.error` 并继续,不中断、不重投(:122-136)。这会隔离处理器故障,但失败的调用不会重试,不能保证事件处理成功。内存队列也不提供崩溃后的恢复;持久化 turn 事件的回放由 turn runtime 和 session store 负责。-- 生命周期:`flush(timeout)` 等待队列排空,超时只 warning(:153-165);`stop()` 先 join(10s 超时,超时即"部分事件可能丢失",:167-185)。app 启动时拉起(api/main.py:174-181),关停时停止(api/main.py:393-396)。-- **关键事实**:生产代码里只有两处 `publish`——orchestrator 每个 turn 结束发 `CAPABILITY_COMPLETE`(deeptutor/runtime/orchestrator.py:204-219),伙伴主动消息同样发(deeptutor/services/partners/manager.py:784-796);但仓库内没有任何 `EventType` 的生产订阅者。SOLVE_COMPLETE / QUESTION_COMPLETE 无人发布也无人订阅。它目前是"随时可挂分析器"的预留口,不是前端数据的来源——找进度问题不要看这里。--## 2. KB 进度上报:从任务到端口--### 2.1 ProgressTracker(deeptutor/knowledge/progress_tracker.py)--- `update()`(:176-281)是唯一写入口:组装进度 dict(`timestamp` 每次刷新,:212),依次做四件事——- 1. 终端日志(:238-269,失败有 stdlib 兜底);- 2. `_save_progress`(:114-174):写 `kb_config.json`(经 `KnowledgeBaseManager.update_kb_status`,:140)+ 原子写 `.progress.json` 快照(:170)。重启后恢复全靠这两份持久层;- 3. 有 `task_id` 时发任务事件 `emit_task_progress(task_id, progress)`(:273-279);- 4. `_notify`(:92-112):server 模式下 `create_task(broadcast_progress(...))` 走 WS 广播;本进程回调列表逐个调用,回调异常仅 debug(:108-112)。-- i18n 设计:线上传英文模板 `message_key` + `message_params`,由前端用 `t()` 渲染(:24-37 的 docstring 讲清了"索引跑在无语言上下文的分离任务里"的动机)。-- `visible_progress()`(:50-68):原生终端态在 publication 落盘前对外仍显示 `processing_documents`/99%,防止"假完成"。-- `verify_terminal()`(:283-322):任务收尾校验两份持久写都真正落盘,丢了直接抛错——这是防"进度说完成、索引其实没发布"的闸门。-- task_id 注入点:建库/上传 `knowledge.py:1016`,重建/重试 `knowledge.py:3795`。--### 2.2 端口层 progress_events(deeptutor/knowledge/progress_events.py)--- 领域层不 import FastAPI:`install_progress_ports(broadcast=..., emit_task_event=...)`(:21-28)由 API 层在 lifespan 里装配——`broadcast=ProgressBroadcaster.get_instance().broadcast`、`emit_task_event=task_stream_manager.emit`(api/main.py:131-134);关停时卸载(api/main.py:348)。CLI/SDK 用 no-op 默认值,进度只落盘不广播。--## 3. WS 广播与 SSE 任务流--### 3.1 WS:ProgressBroadcaster + websocket_progress--- `ProgressBroadcaster`(deeptutor/api/utils/progress_broadcaster.py:14-73):类级 `dict[key, set[WebSocket]]` 连接表;`broadcast()` 逐连接 `send_json({"type":"progress",...})`,发送失败的连接直接剔除(:56-69)。注意 key 是订阅键:限定目录的 KB 用 `"{base_dir}/{kb_name}"`,否则用裸 `kb_name`(knowledge.py:4268-4281)。-- `websocket_progress`(knowledge.py:4256-4528)是这段的核心,连接建立后的初始快照决策树:- 1. 快照终态且 task_id 匹配 → 直接回放并关闭(:4298-4302);- 2. 带 `task_id` 但本进程不认识 → 服务重启过的孤儿任务,合成 `knowledge_task_interrupted` 可重试错误帧,并同步写 `emit_failed` 进 SSE(:4304-4347);- 3. TaskIDManager 元数据已是终态 → 合成终帧(:4349-4376);- 4. 快照新鲜度 >120s 视为无活动任务(:4378-4390),配合"KB 已 ready"直接发终态关闭,避免前端无限轮询(:4392-4417);- 5. 其余按条件回放初始快照(:4419-4442),进入 1s 轮询循环:`timestamp` 变化才发(:4460-4465),终态后 sleep 3s 关闭(:4467-4469),期间兜底检查 TaskIDManager 终态(:4470-4504)。-- 既有吞错点(当前 dev 线现状):时间戳解析 :4387/:4433、循环内 :4509-4510、收尾 send/close/reset_current_user :4514-4517/:4520-4528。--### 3.2 SSE:KnowledgeTaskStreamManager--- deeptutor/api/utils/task_log_stream.py:每任务有界缓冲(500 条 / 2MB,:27-28),超限丢最旧但**保留单条超大终态事件**的裁剪版(:174-186);终态墓碑最多 256 条 / 24h(:30-32),新订阅者可从墓碑恢复终态(:57-63、:128-135)。-- `stream()`(:251-273):先回放 backlog,再走订阅队列,15s 心跳注释防代理断连(:262-267),收到 complete/failed 即止。-- 事件来源三类:ProgressTracker 的端口事件(`emit(task_id,"progress",...)`)、`_task_log`(knowledge.py:667)与 `capture_task_logs` 转发的任务日志(task_log_stream.py:342-358,含 lightrag/graphrag 非传播 logger 的挂钩 :317-331)、任务边界 `emit_complete`/`emit_failed`(knowledge.py:1059/:1110/:3961/:3990 等)。-- 路由:`GET /knowledge-bases/tasks/{task_id}/stream`(knowledge.py:3299-3308)。--## 4. 前端衔接:useKnowledgeProgress → Activity 展示--web/hooks/useKnowledgeProgress.ts 是 KB 进度的唯一前端汇聚点,**WS 与 SSE 双通道并行**:--- `subscribeWs`(:148-262):连 `/ws/knowledge-bases/{kb}/progress?task_id=...`(:169-177);onmessage 过滤 `task_id` 不匹配的帧(:196-201);断开后指数退避重连 500ms×2ⁿ 封顶 5s(:246-259);无 expected task 时从快照恢复任务(:205-207 → `resumeTask` :464-483,按 task_id 前缀推断 create/reindex/upload)。-- `openTaskStream`(:273-445):EventSource 订阅 SSE(:296-301),处理 `process_log`(追加日志,:306-329)、`progress`(更新进度条并去重追加日志行,:331-362)、`complete`/`failed`(结算任务状态并回调 onTaskSettled 持久化历史,:364-436);SSE 出错靠 EventSource 自动重连,WS 充当权威终态回退(:438-442 注释)。-- 渲染:KbTaskLogs.tsx(:14-72)用 ProcessLogs 日志框 + progressbar;`progressMessage`/`resolveProgressPercent`(web/lib/knowledge-helpers.ts:77/:509)负责模板翻译与百分比;`appendTaskLog`(useKnowledgeProgress.ts:25-29)按最后一行去重。-- 语义:WS 帧只信 `task_id` 匹配 + 终态短路(收到 completed/error 即关双通道并回调 onComplete,:235-239);`trackedTaskIdsRef` 防止列表轮询的旧响应重开流或抹掉日志(:91-93)。--## 5. 会话/书/伙伴/学习:其余 Activity 事件面--- **聊天 turn(SessionActivityPanel/ActivityStack 的数据源)**:能力执行通过每 turn 一个 `StreamBus`(deeptutor/runtime/stream_bus.py:31-103;订阅者自带所属 loop,:44-46);orchestrator 把 bus 事件转发给消费者并在结束时发 `CAPABILITY_COMPLETE`(orchestrator.py:185-219)。turn 事件带 `seq` 持久化;统一 WS `deeptutor/api/routers/unified_ws.py` 提供 `subscribe_turn`/`subscribe_session`/`resume_from`(:140-175、:244-262);`TurnLifecycle.subscribe_turn`(deeptutor/services/session/turns/lifecycle.py:354 起)按"持久 backlog → 活跃订阅者 → 追赶补齐 → 未见 DONE 则合成"四段衔接。前端 TurnRuntimeClient.ts 维护 `lastSeq`(:119)、乱序/空洞缓冲(:327-333)、断线按 afterSeq 续传(:272),心跳超时走重连(:282)。事件最终进 TracePresentation.tsx 的 `ActivityStack`(:1231、:1257)。-- **书**:每本书一条进程级长生命周期总线(deeptutor/book/event_hub.py:45-71,历史 400 条 + seq,书删除才关闭),解决"请求级 bus 在 finally 关闭导致后台编译事件全丢"的问题(模块 docstring :8-28);WS `/books`(deeptutor/api/routers/book.py:1519)attach 后按 `after_seq` 转发(:1495-1505)。-- **伙伴**:`PartnerActivityFeed` 有界窗口重放 + 持久 activity id(deeptutor/api/routers/partners.py:1882-1886),跨渠道主动消息以 `proactive` 帧补进 feed(deeptutor/services/partners/manager.py:781-784)。-- **学习 Mastery**:`MasteryTopicEventHub` 只是"唤醒提示"——信号队列 `maxsize=1` 合并、允许丢(deeptutor/learning/event_hub.py:37-40),SQLite 事件尾才是重放权威(模块 docstring :1-8);WS 在 deeptutor/api/routers/mastery_path.py:771。--## 6. 事件丢失 / 乱序的既有防护清单--| 场景 | 防护 | 锚 |-| --- | --- | --- |-| 广播时无人连接 | 连接表为空直接返回;进度已持久化,重连后从快照恢复 | progress_broadcaster.py:50-51;knowledge.py:4282-4283 |-| 页面刷新/WS 重连 | 初始快照决策树(终态回放 / 孤儿转可重试错误 / 元数据终帧) | knowledge.py:4293-4376 |-| 服务重启 | `.progress.json` 原子快照 + kb_config 状态 + 未知 task_id 合成 `knowledge_task_interrupted` | progress_tracker.py:170;knowledge.py:4304-4347 |-| "假完成" | `visible_progress` 门控 + `verify_terminal` 落盘校验 | progress_tracker.py:50-68、:283-322 |-| SSE 订阅晚于事件 | backlog 回放 + 终态墓碑 24h | task_log_stream.py:121-138、:190-202 |-| SSE 中间代理超时 | 15s keep-alive 注释帧 | task_log_stream.py:262-267 |-| 前端乱序/旧帧 | WS 端 `task_id` 过滤 + `timestamp` 变化才发;聊天端 `seq`/`lastSeq` 空洞缓冲 | knowledge.py:4453-4465;TurnRuntimeClient.ts:327-333 |-| 终态丢失 | 双通道互为回退(WS 权威终态 + SSE complete/failed);聊天端合成 DONE | useKnowledgeProgress.ts:438-442;lifecycle.py:358-363 |-| 事件处理抛错 | EventBus handler 异常隔离记日志;SSE/WS 发送失败仅剔连接 | event_bus.py:122-136;progress_broadcaster.py:56-66 |-| 进程内存上限 | 任务缓冲/墓碑/TaskIDManager 各自有界并按 TTL 清理 | task_log_stream.py:27-32;task_id_manager.py:85-120 |--## 7. 已知薄弱点与 fix-progress-\* 系列卡互引--以下吞错点在当前 dev 基线(fe003ddce)**仍然存在**,是后续加固候选:--1. `progress_tracker._notify` 双层吞错(progress_tracker.py:103-106):广播 ImportError、`create_task` 失败、协程内异常全部静默。广播失败应限频留痕,`create_task` 完成回调也应捕获协程异常;无事件循环的 `RuntimeError` 可保持静默。-2. `websocket_progress` 收尾/解析吞错(knowledge.py:4387/:4433/:4509-4510/:4514-4517/:4520-4528):时间戳解析、错误帧发送、close、reset_current_user 多为宽泛吞错。收窄捕获类型并分级留痕,可让断连保持正常而真实故障可追踪。-3. `update_kb_status` 静默失败也会让配置状态与进度快照分叉,宜与上述两处一起做失败可见性回归。-4. `ProgressBroadcaster.broadcast` 对发送失败仅 debug 留痕(progress_broadcaster.py:59-62),主读法是"剔连接即可",但与 `_notify` 静默叠加时故障完全不可见。-5. 结构性事实:全局 EventBus 当前无生产订阅者(第 1 节);`TaskIDManager`/任务流缓冲/连接表均为进程本地,跨进程/重启的一致性完全依赖持久层快照 + 孤儿转换逻辑,这也是"进度卡死"类问题先查 `.progress.json` 与 `kb_config.json` 的原因。--## 8. 建议阅读顺序与验证命令--顺序:progress_tracker.py → progress_events.py → api/main.py:104-181(装配)→ progress_broadcaster.py → knowledge.py:4256-4528 → task_log_stream.py → knowledge.py:3299 → useKnowledgeProgress.ts → KbTaskLogs.tsx;再按需读 stream_bus.py / unified_ws.py / book/event_hub.py。--复核锚点(在仓库根执行):--```bash-git rev-parse origin/dev # 期望 fe003ddce...-grep -n "def update\|def _notify\|def _save_progress" deeptutor/knowledge/progress_tracker.py-grep -n "install_progress_ports" deeptutor/api/main.py-grep -n "websocket_progress\|tasks/{task_id}/stream" deeptutor/api/routers/knowledge.py-grep -rn "EventType.CAPABILITY_COMPLETE" deeptutor --include="*.py"-```diff --git a/docs/guides/tools-surface.md b/docs/guides/tools-surface.mddeleted file mode 100644index b1d25db38..000000000--- a/docs/guides/tools-surface.md+++ /dev/null@@ -1,187 +0,0 @@-# DeepTutor `tools` 工具面全景导读--- 基线:origin/dev @ `fe003ddce`(v1.6.12)。-- 范围:`deeptutor/tools/` 全部顶层模块 + `vision/` 子包 + `builtin/` 注册集 + 与 `deeptutor/capabilities/` 的调用关系 + `tests/tools/` 覆盖对照。-- 所有锚点形如 `path:line`,相对仓库根。--## 1. 这一层是什么:四段注册链--工具从"一个 Python 类"走到"模型这一轮真正能调用",经过四段链路:--```-BaseTool 协议 BuiltinToolSpec 目录 ToolRegistry 进程表 每轮 compose-(核心协议,谁都能实现) → (启动期零导入的"花名册") → (按名懒加载实例 + 别名解析) → (per-turn 决定挂哪些)-deeptutor/core/tool_protocol.py:220 deeptutor/tools/builtin_specs.py:20 deeptutor/runtime/registry/tool_registry.py:26 deeptutor/agents/_shared/tool_composition.py:170-```--1. **协议层** `deeptutor/core/tool_protocol.py`- - `ToolParameter:17`(单个参数,含 `sensitive:43` 脱敏、`items:36` 数组内层 schema)、`ToolDefinition:56`(OpenAI function-calling schema,`raw_parameters:69` 支持整段 JSON-Schema 直通)、`ToolResult:130`(`content` 给模型、`sources` 给引用、`pause_for_user:164` 让 `ask_user` 暂停回合等用户、`model_message:167` 只进模型上下文的私有多模态附件)、`BaseTool:220`(`deferred:246` 标记渐进披露工具)、`ToolLookup:184`(注册表只读面)。-2. **目录层** `deeptutor/tools/builtin_specs.py:20` `BuiltinToolSpec`- - 只存 `name + "module:Class"` 字符串,`load_class():24` / `create():32` 时才 import,并在 `create()` 里校验类名与目录名不漂移。`BUILTIN_TOOL_SPECS:46` 是唯一的内置工具花名册(共 **94 个**名字,见 §5),`BUILTIN_TOOL_NAMES:207`、`TOOL_ALIASES:217`(`pdf→read_source`、`rag_hybrid→rag{mode:hybrid}` 等 4 条)、`LazyBuiltinToolTypes:228`(给 Settings API 的惰性类序列)。-3. **进程注册表** `deeptutor/runtime/registry/tool_registry.py:26` `ToolRegistry`- - `load_builtins():55` 只把目录 dict 拷进来(零导入);`get():96` / `execute():151` 命中时才 `_load_builtin():59` 实例化;`_resolve_request():75` 做别名合并;`get_tool_registry():170` 进程级单例。- - 多用户外部工具(MCP 等)不进进程表,走 `deeptutor/runtime/registry/scoped_registry.py:40` `ScopedToolRegistry`:per-turn overlay + 派发时授权(`execute` 拒绝未授权 provider 工具,注释见文件头 1-21 行)。-4. **每轮组合** `deeptutor/agents/_shared/tool_composition.py:170` `compose_enabled_tools`- - 纯函数,chat 与 quiz 共用。顺序:用户开关工具 → 条件自动挂载 → 能力自有工具 → 常开工具(`write_memory/web_fetch/github/ask_user/cron`,`deeptutor/agents/_shared/tool_composition.py:262`)→ `forced`/`suppressed` 修正(`_finalize:268`)。`AUTO_MOUNTED_TOOLS:40` 直接由 `CONFIGURABLE_BUILTIN_TOOL_NAMES` 派生,两个面永不漂移。--## 2. 能力选择点(这一轮挂什么、参数从哪来)--- **条件挂载表** `_CONDITIONAL_MOUNT_FLAGS`(`deeptutor/agents/_shared/tool_composition.py:47`):`rag/kb_files/knowledge_frontier ← has_kb`、`read_source ← has_sources`、`read_memory ← has_memory`、`list_notebook/write_note ← has_notebooks`、`question_bank ← has_question_bank`、`read_skill ← has_skills`、`load_tools ← has_deferred_tools`、`exec ← has_exec`、四个 `mastery_*` 导航工具 ← `has_mastery_nav/has_mastery_topics`。探测函数(`user_has_memory:287`、`user_has_notebooks:307`、`user_has_mastery_topics:324`、`user_has_question_bank:340`)一律 fail-closed。-- **管线装配点** `deeptutor/agents/loop/pipeline.py:726` `AgenticLoopPipeline._compose_enabled_tools`:逐项填 `ToolMountFlags:142`(`has_kb` 只统计"能力不持有的共选 KB"——纯 Obsidian 回合不挂 rag,issue #650;`has_sources` 在答案环恒为 False,`read_source` 由 explore_context 前置阶段持有,`deeptutor/agents/loop/pipeline.py:739-742`);随后 `drop_unconfigured_generation_tools`(`deeptutor/agents/_shared/tool_runtime.py:20`)摘掉没配模型的 `imagegen/videogen`,`workspace_export` 在注册表存在时追加(`deeptutor/agents/loop/pipeline.py:778-781`)。-- **服务端注入参数缝** `deeptutor/agents/loop/pipeline.py:1323` `_augment_tool_kwargs`:模型永远不填的参数都在这里注入——`rag` 的 `mode:"hybrid"` 与 `_vision_supported`、`cron` 的 `_cron_owner`(路由归属,`deeptutor/agents/loop/pipeline.py:1366-1395`)、`write_note` 的真实 `conversation_history`、`geogebra_analysis` 的首图 base64、`web_search` 的 output_dir 等。读任何工具的"输入契约"时要意识到:schema 是模型可见的一半,这一层是另一半。-- **Prompt 提示层** `deeptutor/tools/prompting/__init__.py:52` `load_prompt_hints` 从 `prompting/hints/<zh|en>/<tool>.yaml` 读每工具的 when_to_use/guideline;`compose_prompt_text:203` 提供 5 种渲染格式。这是"能力选择"的软一半:模型看到什么决定它挑什么。-- **渐进披露** `BaseTool.deferred`(`deeptutor/core/tool_protocol.py:246`)+ `load_tools` 工具(`deeptutor/tools/builtin/__init__.py:1731`):MCP 等外部工具只以一行清单进系统提示,模型用 `load_tools` 拉全 schema;`DeferredToolLoader` 在 `deeptutor/runtime/registry/deferred_tools.py:116`。--## 3. 顶层模块一览表--`deeptutor/tools/` 下 29 个顶层模块,按角色分组(锚点为模块入口/核心函数):--| 模块 | 角色 | 挂载类别 | tests/tools 覆盖 |-|---|---|---|---|-| `builtin/`(`__init__.py`) | 21 个内置工具的 BaseTool 包装层 | 见 §5 | 部分(见 §7) |-| `builtin_specs.py` | 注册目录(§1) | — | 间接(tests/core) |-| `ask_user.py` | 澄清卡 payload 构建 | 内置 ask_user 的实现体 | ✅ test_ask_user.py |-| `brainstorm.py` | 发散式一次 LLM 调用 | 用户可开关 | ❌(包装层在 tests/core) |-| `reason.py` | 深推理一次 LLM 调用 | 用户可开关 | ❌(包装层在 tests/core) |-| `rag_tool.py` | RAGService 薄包装 | 条件自动挂 | ✅ test_rag_tool.py |-| `web_search.py` | 纯 re-export services.search | 用户可开关 | ✅(测的是 services 层) |-| `web_fetch.py` | 抓 URL→markdown(含 SSRF 防护) | 常开 | ✅ test_web_fetch.py |-| `exec_tool.py` | 唯一沙箱执行面 | 条件(has_exec) | ✅ 三个测试文件 |-| `cron_tool.py` | 定时任务 schedule/list/cancel | 常开 | ❌(tests/services/cron 覆盖) |-| `github_query.py` | gh CLI 只读查询 | 常开 | ✅ test_github_query.py |-| `knowledge_frontier.py` | KB 前沿论文发现 | 条件(has_kb) | ✅ test_knowledge_frontier_tool.py |-| `paper_search_tool.py` | arXiv 搜索 | 用户可开关 | ❌(包装层在 tests/core) |-| `zotero_search.py` | Zotero Web API 检索 | 用户可开关 | ✅ test_zotero_search.py |-| `read/list/write` 笔记三件套:`list_notebook.py`、`write_note.py` | 笔记索引/读写 | 条件(has_notebooks) | ✅ 两文件均有 |-| `question_bank.py` | 错题库六动作 | 条件(has_question_bank) | ✅ test_question_bank_tool.py |-| `mastery_nav.py` | mastery 图谱四个只读导航工具 | 条件(has_mastery_nav) | ⚠️ tests/tools 无(`deeptutor/learning/tests/test_mastery_navigation.py` 有 19 例) |-| `mastery_tool.py` / `solve_tool.py` | 兼容 re-export(实现已迁 capabilities) | — | 随 capabilities 测试 |-| `media_gen_tool.py` | imagegen/videogen | 用户可开关 + 模型配置门 | ❌(tests/services/test_media_gen 覆盖服务层) |-| `partner_memory.py` | 伙伴三分区记忆/历史 | 伙伴回合强制挂载 | ❌(tests/services/partners 覆盖) |-| `workspace.py` | 工作区 list/read/search/present/export | 基线常挂 | ⚠️ 仅 flow 级(test_pptx_workspace_flow 间接) |-| `file_tools.py` | read_file/write_file/edit_file/list_dir | **未注册(休眠模块)** | ✅ test_file_tools.py |-| `vision/` | 图像/GGB 子包 | 供 geogebra/可视化链路 | ❌ tests/tools 无(tests/visualizers 有 ggb_validator) |-| `question/` | MinerU 解析 + 出题 | research/question 管线专用 | ✅ test_question_extractor.py、test_mineru*.py |-| `tex_chunker.py` / `tex_downloader.py` | arXiv LaTeX 下载与分块 | research 管线专用 | ❌ 薄弱 |-| `prompting/` | 提示 hints 加载/渲染 | 全工具共用 | ⚠️ 仅经 exec 提示测试间接覆盖 |-| `__init__.py` | 顶层 lazy export(`_LAZY_EXPORTS:7`) | — | — |--## 4. 每个顶层工具一卡(输入 / 输出契约 / 失败语义)--### 4.1 内置包装层 `builtin/`(21 个工具的 BaseTool 面孔)--每个卡 = 一个 BaseTool 子类,`get_definition` 给 schema、`execute` 委托给同目录实现模块。共同基类 `_PromptHintsMixin:26`(`builtin/__init__.py`,下同)接上 §2 的提示层。--- **brainstorm**(`BrainstormTool:33`):入参 `topic`(必填)+ `context`;输出 `ToolResult(content=answer, metadata={topic, answer, model})`。失败:无模型配置时实现体抛 `ValueError`(`deeptutor/tools/brainstorm.py:69`),由循环兜成工具错误。-- **rag**(`RAGTool:105`):入参 `query`+`kb_name`(二者非空否则 `raise ValueError:127-132`);输出正文+`sources`(`_rag_sources:68` 用检索自身 provenance,仅成功非空答案才回退 query echo,issue #694/#1500)+ `success=not failed`。失败语义:`error_type`/`needs_reindex` 转成给模型的一句话正文;命中视觉素材时按 `_vision_supported` 决定注入像素(`_rag_visual_model_message:182`,多用户作用域先解析再读文件)或提示模型"没看图别装看过"。-- **kb_files**(`KbFilesTool:227`):`kb_name` 必填,`pattern` glob/子串、`limit` 由 `_kb_files_limit:312` 钳制;KB 不可访问抛 `ValueError:289`。语言由服务端注入(§2)。-- **knowledge_frontier**(`KnowledgeFrontierTool:323`):`kb_name` 必填 + `focus/max_papers≤10/years_limit≤10`;输出报告 + `sources`(kb_sources + arxiv 论文行)。KB 不可访问抛 `ValueError:377`;只推荐不导入。-- **web_search**(`WebSearchTool:406`):`query`(缺省由 §2 注入用户消息);`asyncio.to_thread` 包同步搜索(`asyncio.to_thread` at `deeptutor/tools/builtin/__init__.py:422`);dict 结果取 `answer/citations`,非 dict 兜成字符串。无显式失败分支——搜索服务异常会上抛由循环兜底。-- **reason**(`ReasonTool:446`):`query`+`context`;一次 LLM 调用(`deeptutor/tools/reason.py:42`)。无模型配置抛 `ValueError`(`deeptutor/tools/reason.py:81`)。-- **paper_search**(`PaperSearchToolWrapper:484`):`query/max_results≤20/years_limit/sort_by`;**失败软着陆**:任何 arXiv 异常→`ToolResult("arXiv search is temporarily unavailable…", error:True)`(`:526-531`),空结果给"No arXiv preprints found"。-- **zotero_search**(`ZoteroSearchToolWrapper:564`):`query/user_id` 必填 + `api_key(sensitive=True)/max_results≤25`;`ZoteroSearchError` 码表(`:567-573`)把 invalid_api_key/library_not_found/rate_limited/network_unavailable/invalid_response 翻成模型可读文案,`success=False`。`api_key` 走 `sensitive` 不进 trace。-- **read_source**(`ReadSourceTool:821`):`source_id`(`nb-/bk-/rd-/hs-/qb-/at-` 前缀)从注入的 `source_index` 取全文;id 缺失时唯一来源自动补齐,多来源报错;未知 id 回显合法 id 列表(`:872-881`)。工具本身无状态、无 IO。-- **read_memory / write_memory**(`ReadMemoryTool:888` / `WriteMemoryTool:918`):read 无参、读 L3 四文档拼接;write 校验 `op∈{add,edit}` 与非空 `text`(`:973-980`),先落 L1 trace 再 `write_preference`;拒绝时 `content="write_memory rejected: …"`,去重时显式回 "already saved"(issue #647)。-- **read_skill**(`ReadSkillTool:1637`):`name` 必填 + `file` 默认 SKILL.md;技能名不存在→列可用技能;文件不存在→列出该技能前 40 个文件(`_SKILL_FILE_LIST_LIMIT:309`)终止重试环;非法名/路径转 `success=False` 文案。-- **load_tools**(`LoadToolsTool:1731`):`names` 数组;`_tool_loader` 服务端注入,缺失时返回"(unavailable)";未知名单独列出,`success` 规则见 `:1784`。-- **web_fetch**(`WebFetchTool:1023`):`url` 必填 + `max_chars`(默认 50000,解析失败兜默认);`FetchOutcome.ok=False` 原样转 `success=False`。实现卡见 §4.2 web_fetch。-- **list_notebook / write_note**(`ListNotebookTool:1087` / `WriteNoteTool:1304`):实现契约见 §4.2。write_note 的 append 默认正文=真实转录(注入 `conversation_history`),只有显式给 `content` 才写 agent 正文。-- **question_bank**(`QuestionBankTool:1137`):`action` 六枚举 + 场景参数(`question/answers/category/entry_ids/limit`);`outcome.ok=False` 时 `content=error`。实现卡见 §4.2。-- **github**(`GithubTool:1430`):`query_type∈{pr,issue,run,repo,api}` + `target`;只读构造(见 §4.2 github_query);gh 缺失/超时/非零退出都转 `success=False` 文案。-- **ask_user**(`AskUserTool:1493`):`questions` 1-4 条 + `intro`;payload 校验失败转 `success=False`(`:1620-1621`);成功时返回占位正文 + `pause_for_user` 暂停回合等回复。实现卡见 §4.2。-- **cron**(`CronTool:1789`):`action∈{schedule,list,cancel}` + 排程三选一(`at/every_seconds/cron_expr`,`deeptutor/tools/cron_tool.py:59-68` 强制恰一个);`_cron_owner` 缺失→"not available in this context"(`deeptutor/tools/cron_tool.py:77-82`);在定时任务上下文里禁止再排程(`:107-111`);时间解析失败/未知 job 均为 `ok=False` 文案。-- **geogebra_analysis**(`GeoGebraAnalysisTool:687`):`question` + `image_base64`(无图→`success=False:729-733`;非 data URI 防御性补前缀 `:739-740`);240s 视觉调用上限(`_VISION_ANALYSIS_TIMEOUT_S:693`,超时/管线异常都转 `success=False`);`language` 服务端注入、拒绝模型覆盖(`:726-727`)。--### 4.2 实现模块卡--- **ask_user.py**:`build_ask_user_payload:102` 把 v2 `{questions[]}` 与 legacy `{question, options}` 归一成 `AskUserPayload`;上限常量 `MAX_QUESTIONS=4/MAX_OPTIONS=8:30-31`;丢弃截断流修复出的"半个 option"(`_drop_half_written_options:217`)、去重 label/body(#1409)、去模型自加的 "Other";错误一律 `(None, error_message)` 返回而非抛出。`build_ask_user_preview:160` 用 json_repair 把流式半截参数画成卡片预览(best-effort,不影响真实派发)。-- **brainstorm.py / reason.py**:同构的一次 LLM 调用(`brainstorm:45` / `reason:42`),agent 参数取自配置(`get_agent_params("brainstorm")/("solve")`),返回 `{topic|query, answer, model}`。失败:`ValueError("No model configured…")`;LLM 异常上抛。-- **rag_tool.py**:`rag_search:15` 校验非空 query/kb_name,多用户走 `resolve_for_rag`(无显式 base_dir 时),KB 不可访问抛 `ValueError:41`;同文件还有 `initialize_rag:54` / `delete_rag:66`(索引生命周期,非 chat 工具)。-- **web_search.py**:纯 re-export(`:26-42`);真身在 `deeptutor/services/search/__init__.py:131`。-- **web_fetch.py**:`fetch_url_as_markdown:73` → `FetchOutcome:57`。安全姿态(文件头 10-22 行自述):仅 http/https;私网/环回/链路本地地址拒绝且 pre-flight + 每一跳重定向后复查(`_is_disallowed_host:177`,DNS 失败 fail-closed);响应硬顶 4MB(`MAX_RESPONSE_BYTES:39`)、正文截断 `max_chars`;15s 超时、最多 5 跳。正文抽取优先复用 html_extractor,失败退正则路径(`_extract_readable:242`)。-- **exec_tool.py**:`ExecTool:36` 是**唯一**沙箱执行面。`_execute_shell:192` 过 `_DENY_PATTERNS:19`(rm -rf、mkfs、fork 炸弹等→`sandbox.command_blocked`);`_execute_source:223` 把 python/c/cpp 源码落盘再跑(平台命令拼装 `_command_for_platform:106`);超时 30s 默认、300s 上限(`_DEFAULT_TIMEOUT/_MAX_TIMEOUT:32-33`);产物经 `_render_result:301` 快照-收集-渲染,`success=ok and exit_code==0:366`。`_sandbox_*` kwargs 全部服务端注入。-- **cron_tool.py**:`run_cron_action:76` 纯函数;三动作 + `add/remove` 旧别名(`:86-89`);schedule 参数构造 `_build_schedule:59`(恰一个时间源,否则 ValueError);无 `_cron_owner` 即拒绝。输出给模型的是渲染文本。-- **github_query.py**:`run_github_query:66` → `GithubOutcome:49`。argv 白名单 `_build_argv:152` 只有 view/list,`api` 分支固定 GET、不经过 shell(`:192-196`);gh 不安装→友好 `ok=False`;20s 超时、16k 输出截断。-- **knowledge_frontier.py**:`discover_frontier:26` 三步:KB 摘要(内部调 rag)→ LLM 派生 ≤3 个 arXiv 查询(失败时退化用文档名)→ 搜索去重渲染。参数钳制 `_clamped_int`,文档名 fallback 保证"删掉 LLM 也还有结果"。-- **list_notebook.py**:`list_notebooks_or_records:49` 双模式(索引/下钻);上限 50 笔记本/80 记录(`:31-32`);未知 notebook_id 回显合法 id(`:121-126`);错误返回 `ListOutcome(ok=False, error=…)` 不抛。-- **write_note.py**:`write_note:61` 双模式 append/edit;长度帽 title 200/note 4k/content 200k(`:37-39`);`turns_to_include` 默认 3 或 "all"(`:43-44`);依赖注入 `notebook_manager/conversation_history` 便于测试;一切失败走 `WriteOutcome(ok=False)`。-- **question_bank.py**:`run_question_bank:470` 六动作(`ACTIONS:45`);`_coerce_ids:77` 把模型给脏的 entry_ids 拆成"可用+拒绝"两份,绝不静默丢弃;list 上限 20/100(`:52-53`);伙伴回合把写路径解析到 learner 真实库(`_partner_bank_paths:137`);全部依赖注入 `store`。-- **mastery_nav.py**:四工具(`MASTERY_NAV_TOOL_NAMES:56`)`mastery_topics/sessions/open_session/new_session`。两条安全线(模块头 18-32 行):**只读**(不租约、不登记、不动 mastery 等级)与**不导航**(后两者只产 `mastery_handoff` 卡,`HANDOFF_META_KEY:54`,学习者点击才跳)。所有 id 先对 store 校验(`_topic_or_error:80`);在当前话题自己的会话里拒绝发"开新会话"卡(`_handoff_lands_where_we_already_are:94`,#1412/#1411)。-- **media_gen_tool.py**:`ImagegenTool:135`(`prompt` 必填、`n≤4`)与 `VideogenTool:217`(`aspect_ratio/duration`)。未配置模型→`ValueError` 转 `success=False`;`GenerationProviderError`→失败文案;产物写进工作区 outputs/ 并以 artifacts 返回,**呈现必须再走 workspace_present**(模块头 10-15 行)。-- **partner_memory.py**:三工具 `partner_read/memorize/search`(`PARTNER_BUILTIN_TOOL_NAMES:26`)。分裂记忆模型(模块头 3-15 行):owner 的 L3 只读 + 伙伴自有分区可写;产品 chat 中被抑制、伙伴回合强制挂载。search 是伙伴会话历史的关键词扫描(snippet 140 字、上限 300 命中,`:32-33`)。-- **workspace.py**:五工具 `WorkspaceListTool:25 / ReadTool:73 / SearchTool:116 / PresentTool:156 / ExportTool:219`。前三只读(`WorkspaceError` 统一转 `_failure:21`);present 是"把文件以卡片呈现给用户"的唯一正当路径;export 是**唯一**越出 outputs/ 的写,且必须经 ask_user 授权卡一次一签(`:269-327`)。前四个是 `WORKSPACE_BASELINE_TOOLS`(`deeptutor/agents/_shared/tool_composition.py:73`)——独占能力回合与伙伴过滤都摘不掉的基线。-- **paper_search_tool.py**:`ArxivSearchTool:24`;抓取量 = 2×需求(上限 30)再按年过滤截断(`:72`、`:116`);30s 超时、429 退避重试一次(`:94-107`);一切异常→空列表(由包装层转文案)。-- **zotero_search.py**:`ZoteroSearchClient:33` + 码化异常 `ZoteroSearchError:24`;401/403→invalid_api_key、404→library_not_found、429→rate_limited、网络→network_unavailable、非 JSON→invalid_response(`:81-97`);user_id 白名单正则(`:19`)。-- **file_tools.py**:`ReadFileTool:41/WriteFileTool:109/EditFileTool:134/ListDirTool:189`。路径必须在 `_allowed_dir` 内(`_resolve_workspace_path:13`,越界 `PermissionError`);edit 的 not-found 会给最相似片段的 unified diff(`_not_found_message:266`)。**注意:该模块当前未进入 BUILTIN_TOOL_SPECS,也没有任何管线挂载它——注册表视角是休眠代码**(仅 tests/tools/test_file_tools.py 引用)。-- **mastery_tool.py:9 / solve_tool.py:8**:纯兼容 re-export,实现已迁 `deeptutor/capabilities/mastery/tools` 与 `deeptutor/capabilities/solve/tools`。-- **tex_downloader.py**:`TexDownloader:44`——arXiv e-print 下载→解包→定位主 tex;`TexDownloadResult(success, tex_path, tex_content, error)`(`:28`)。requests 同步 30s 超时(`:83`)。-- **tex_chunker.py**:`TexChunker:21`——按 section/token 分块(tiktoken,模型不支持时退 cl100k_base,`:37-45`);token 估算失败退 len/4(`:62-65`)。-- **question/**:`deeptutor/tools/question/question_extractor.py:321` `extract_questions_from_paper`(MinerU 产物→LLM 抽题);`deeptutor/tools/question/exam_mimic.py:18` `mimic_exam_questions` 是出题协调器的薄入口(pdf_path / paper_dir 二选一,`:29-32`);`deeptutor/tools/question/__init__.py:10-16` 把 MinerU 解析 re-export 成历史 API。-- **prompting/**:见 §2 末条。`ToolPromptComposer:89` 五种格式(list/table/aliases/phased/list_with_usage)。-- **vision/**:见 §6。--## 5. builtin 集:101 个注册名与四种挂载类别--`BUILTIN_TOOL_SPECS`(`deeptutor/tools/builtin_specs.py`)共 101 个名字,按宿主分:`tools/builtin` 22 + `exec` 1 + `workspace` 5 + `submit_visualization` 1 + `imagegen/videogen` 2 + `mastery_nav` 4 + `research_tools` 3 + `learning_journal_tools` 2 + capabilities 持有的 58(mastery 15、solve 3、notes 4、obsidian 9、marginnote4 7、subagent 1、ima 5、reading 8、setup 4、partner_authoring 1、partner_group 1)+ `partner_memory` 3。--挂载类别(决定谁有权开关它):--| 类别 | 名单锚点 | 机制 |-|---|---|---|-| 用户开关(/settings/tools "体验增强") | `USER_TOGGLEABLE_TOOL_NAMES`(`deeptutor/tools/builtin/__init__.py:1907`):brainstorm、web_search、paper_search、zotero_search、reason、geogebra_analysis、imagegen、videogen | composer 开关 + 管理员全局白名单(`admin_enabled_optional_tools:98`) |-| 条件自动挂载(对用户"锁定") | `CONFIGURABLE_BUILTIN_TOOL_NAMES:1932` 共 20 个 | `_CONDITIONAL_MOUNT_FLAGS`(§2) |-| 常开自动挂载 | write_memory、web_fetch、github、ask_user、cron(`deeptutor/agents/_shared/tool_composition.py:262`) | 无条件(伙伴白名单仍可减) |-| 能力自有 | capabilities 的 `owned_tools`(§7) | 能力激活即加挂 |-| 伙伴强制/抑制 | `PARTNER_BUILTIN_TOOL_NAMES:208`;chat 记忆工具被 `_PARTNER_SUPPRESSED_TOOLS` 抑制 | `forced/suppressed`(`deeptutor/agents/_shared/tool_composition.py:219-228`) |-| 基线(不可摘) | `WORKSPACE_BASELINE_TOOLS`(`deeptutor/agents/_shared/tool_composition.py:73`)workspace_list/read/search/present | 独占回合也保留(`compose_enabled_tools:247`) |-| 占位(暂停上架) | `COMING_SOON_TOOL_TYPES:1896`(当前为空) | Settings 显示 "Coming soon",不进注册表 |--## 6. vision 子包--`deeptutor/tools/vision/`(`deeptutor/tools/vision/__init__.py:1-41` 一次导出四组),服务 GeoGebra 可视化链路(`geogebra_analysis` 工具 + `agents/vision_solver` + `visualizers`):--- **image_utils.py**:URL→base64 下载与校验(`is_valid_image_url:33`、`is_base64_image:49`),10MB 上限、30s 超时(`:21-24`);`ImageError:27`。-- **coord_transform.py**:BBox 像素坐标 ↔ GeoGebra 数学坐标(文件头 1-14 行写明两坐标系差异);`GGBCoordSystem:29`、`bbox_to_ggb`/`ggb_to_bbox`/`suggest_coord_system` 等。-- **ggb_validator.py**:`validate_command/validate_ggbscript` + `ValidationResult:12`(original/fixed/warnings/errors);内置"该用方括号"的命令白名单修复 LLM 常见笔误。-- **block_parser.py**:从 LLM 流式输出里抽 ```ggbscript[page-id;title] 围栏块(`parse_ggb_blocks:47`、`StreamingBlockParser`),块内容过 ggb_validator 校验并保留原文。-- 测试现状:`tests/tools/` 无 vision 测试;`tests/visualizers/test_ggb_validator.py` 覆盖 validator;`tests/agents/vision_solver/` 覆盖 agent 侧。coord_transform/block_parser/image_utils 全测试树无直接单测(见 §8 缺口 3)。--## 7. 与 capabilities 的调用关系--- **两种能力协议**(`deeptutor/capabilities/protocol.py`):- - `LoopExtension:38`(普通能力):复用 chat 全量工具面,只在激活时把 `owned_tools:104` **加**在面上(`deeptutor/agents/loop/pipeline.py:811-816` 汇集)。可选钩子:`pre_loop:53`(回合前预 pass)、`augment_kwargs:118`(给自有工具注入服务端 kwargs)、`rebinding_tools:81`(如 `mastery_switch`,先执行并重绑本轮其余调用)。- - `KnowledgeCapability:130`:**独占**面。激活时 `exclusive_tools:145` 生效,回合只剩 `owned_tools + ask_user 地板`,外加共选 KB 的 `rag/kb_files/knowledge_frontier` 三件(`_KB_COEXISTING_TOOLS`,`deeptutor/agents/_shared/tool_composition.py:68`、`compose_enabled_tools:230-248`,#650)。obsidian、marginnote4、ima 是此类。-- **能力注册** `deeptutor/capabilities/registry.py:28` `LoopCapabilitySpec`(class_path + 惰性工厂 + 漂移校验);插件 entry-point 亦可在运行期并入(registry.py 内 `_LegacyLoopCapabilitiesView:107` 一带)。-- **tools/ 与 capabilities/ 的边界**:通用工具住 `tools/`;一种能力专属、跟随能力激活的工具住 `capabilities/<name>/tools.py`,但仍登记进同一张 `BUILTIN_TOOL_SPECS` 目录(`deeptutor/tools/builtin_specs.py:96-204`),注册与挂载机制完全一致——差别只在"谁决定挂"(§2 的 flags vs §7 的 owned_tools)。-- **搜索/研究等固定管线**(research、question 管线)不经过 chat 组合器,直接 import `tools/` 的函数(如 `tex_downloader`、`paper_search_tool.ArxivSearchTool`、`question/`)——这也是 tex/question 两族缺 chat 测试的原因:它们的调用方在 `agents/research`、`agents/question`。--## 8. tests/tools 覆盖对照(薄弱工具标注)--`tests/tools/` 现有 21 个测试文件(含 `builtin/test_read_skill_tool.py`)。按"模块 → 测试"映射:--**有直接覆盖**:ask_user(563 行,最厚)、write_note(368 行)、web_fetch(323 行)、question_bank(298 行)、exec_tool(test_code_execution_guidance + test_exec_prompt_hints + test_pptx_workspace_flow + test_office_artifact_execution,含 workspace_present 联动)、github_query(187 行)、zotero_search(195 行)、kb_files(196 行)、read_source(85 行)、list_notebook(147 行)、knowledge_frontier(175 行)、rag_tool(127 行,测 services.factory + rag_tool 契约)、question_extractor(75 行)+ mineru 两文件、file_tools(60 行)。--**tests/tools 缺口**(括号内为树内其他位置的既有覆盖,若无标注则全仓测试树内也无直接单测):--1. **cron_tool** — `tests/services/cron/test_cron_tool.py` 有;`tests/tools/` 无(可接受,位置合理)。-2. **mastery_nav.py(500 行)** — `tests/tools/` 无,但 `deeptutor/learning/tests/test_mastery_navigation.py`(372 行、19 例)直接覆盖全部四工具:id 解析、跨话题拒绝、自我会话拒绝(#1412/#1411)、空图谱。覆盖充分,只是位置在 learning 包内。-3. **vision/coord_transform.py(436 行)、block_parser.py(251 行)、image_utils.py(210 行)** — ❗ 薄弱:全测试树(tests/、deeptutor/**/tests/)零直接引用。坐标换算与围栏解析是纯函数、易测;目前 vision 子包只有 ggb_validator 有专测(`tests/visualizers/test_ggb_validator.py`)。-4. **tex_downloader.py / tex_chunker.py** — ❗ 薄弱:下载/解包/主文件定位、按 token 分块全树无单测(research 管线消费方亦无)。-5. **paper_search_tool.py** — 包装层被 `tests/core/test_builtin_tools.py:616` 用 fake 覆盖;**ArxivSearchTool 本体**(年过滤、429 重试、抓取量放大)无直接单测(knowledge_frontier 测试同样只 fake 它)。-6. **media_gen_tool.py** — `tests/services/test_media_gen.py` 覆盖服务层 + 包装层的提示语与 `ImagegenTool().execute` 主路径(`:584-599`);参数钳制边界(n≤4、size 透传)与 videogen 失败分支覆盖较薄。-7. **partner_memory.py** — `tests/services/partners/test_partner_memory_tools.py` 有;`tests/tools/` 无(位置合理)。-8. **brainstorm.py / reason.py 本体** — 包装层在 tests/core 有 fake 级覆盖;实现体(agent 参数回退、无模型 ValueError)无专测。-9. **workspace.py** — 仅 `test_pptx_workspace_flow.py` 以流式集成路径触达 exec+present;`WorkspaceListTool/ReadTool/SearchTool/ExportTool` 的参数钳制与 `_failure` 转换无直接单测。export 的授权卡流程值得补。-10. **file_tools.py** — 有测试但**工具本身未注册**(§4.2):要么补进目录并挂载,要么明确标注弃用——二选一,当前状态最容易误导读者。-11. **prompting/** — `load_prompt_hints` 的 zh/en 回退仅经 `test_exec_prompt_hints.py` 间接触达;`ToolPromptComposer` 五种格式无格式级单测。-12. **web_search.py** — 测试都在 services 层(provider 白名单等);顶层 re-export 无需独立测试,正常。--**覆盖强度排序(最需补)**:vision(coord_transform/block_parser/image_utils) > tex_downloader/tex_chunker > ArxivSearchTool 本体 > workspace 四工具 > prompting 格式渲染 > media_gen 边界分支。--## 9. 读代码的推荐路径--1. 先读协议:`deeptutor/core/tool_protocol.py:220`(BaseTool)与 `:130`(ToolResult 的 pause_for_user/model_message 两个特殊通道)。-2. 再读目录与注册表:`deeptutor/tools/builtin_specs.py:46` + `deeptutor/runtime/registry/tool_registry.py:96`(get 的懒加载与别名)。-3. 然后读组合器:`deeptutor/agents/_shared/tool_composition.py:170` 的 docstring 就是本层最完整的语义说明。-4. 挑三个代表工具精读:`rag`(builtin/__init__.py:105,多用户+视觉+失败语义最复杂)、`ask_user`(ask_user.py:102 + AskUserTool:1493,暂停-恢复回合)、`exec`(exec_tool.py:36,沙箱+产物)。-5. 最后按需进 capabilities:`deeptutor/capabilities/protocol.py:38/130` 理解"加挂"与"独占"两族。diff --git a/docs/plugin-platform-rfc.md b/docs/plugin-platform-rfc.mddeleted file mode 100644index 0749a84bd..000000000--- a/docs/plugin-platform-rfc.md+++ /dev/null@@ -1,399 +0,0 @@-# DeepTutor Plugin Platform RFC (Phase C and Catalog E)--Status: accepted implementation slice-Schema: `deeptutor.plugin/v1`-Last reviewed: 2026-09-08--## Problem--DeepTutor already has several isolated extension mechanisms: capability-plugins, loop capabilities, Reading extensions, tools, and the newer-visualizer catalog. Third-party developers cannot describe one package with-one identity, compatibility matrix, permission disclosure, artifact pin, and-marketplace state. The absence of that root contract makes every extension-point invent its own distribution and trust model.--The plugin platform therefore standardizes package metadata and catalog state-first. It does not attempt to make every extension use one universal runtime-API.--## Non-goals for this slice--- No arbitrary Chrome CRX/extension loading. Chrome extensions assume browser- APIs, extension process boundaries, and a browser permission model that do- not map safely to a Python server process.-- No arbitrary URL installation, background update check, or automatic upgrade.- Catalog installation is an explicit command that resolves a vendored,- reviewed artifact pin before downloading.-- No claim that Python permission fields create an OS sandbox. They define the- approval and runtime contract boundary. Managed Tool and Capability workers- run in a separate Python process with a plugin-private environment, but that- process boundary is dependency isolation, not a hard security sandbox.-- No replacement of the existing `deeptutor.plugins` capability loader,- `deeptutor.loop_capabilities`, or `deeptutor.reading_extensions` entry-point- behavior. Those loaders now honor an approved root manifest whenever a- package declares one; packages without a root manifest retain the migration- window.-- Learning Experience widgets/events are intentionally deferred.--## Root manifest--A Python plugin ships `deeptutor.plugin.json` inside its package or wheel. The-file is static JSON and must be readable without importing the plugin.--```json-{- "schema_version": "deeptutor.plugin/v1",- "id": "org.author.example",- "name": "Example Plugin",- "version": "1.0.0",- "description_i18n": {- "en": "Example extension package",- "zh": "示例扩展包"- },- "author": "Author Name",- "license": "Apache-2.0",- "homepage": "https://example.com",- "source_url": "https://github.com/author/example",- "compatibility": {- "deeptutor": ">=1.6.0,<2",- "api": {- "capability": "1",- "loop_capability": "1",- "http_route": "1",- "frontend_page": "1",- "persistence_schema": "1",- "app_connector": "1",- "tool": "1",- "reading_extension": "1",- "visualizer": "1"- }- },- "permissions": {- "reading": ["selection", "visible_text"],- "learning_events": [],- "network": ["https://api.example.com"],- "models": [],- "storage": ["plugin-private"],- "ui": ["sandboxed-iframe"]- },- "dependencies": ["requests>=2.32,<3"],- "extensions": [- {- "type": "reading_extension",- "id": "translation",- "entry_point": "translation"- },- {- "type": "visualizer",- "id": "fraction_tiles",- "manifest": "visualizers/fraction_tiles/visualizer.json"- },- {- "type": "http_route",- "id": "study_summary",- "entry_point": "example_plugin.worker",- "path": "/study/summary",- "methods": ["GET", "POST"],- "auth": "authenticated"- }- ]-}-```--The manifest parser rejects unknown fields. This is deliberate: the root file-is a public compatibility contract, and silently accepting misspelled fields-would make plugin behavior depend on the DeepTutor release.--### Extension types--| Type | Meaning | Current behavior |-| --- | --- | --- |-| `capability` | Turn-owning capability | Existing entry points load only after manifest approval; managed workers load through the JSON subprocess adapter |-| `loop_capability` | Chat-loop capability | Existing entry points load only after manifest approval |-| `tool` | Single-shot LLM tool | Existing entry points load only after manifest approval; managed workers load through the JSON subprocess adapter |-| `reading_extension` | Reading toolbar/action extension | Existing entry point remains authoritative and loads only after manifest approval |-| `visualizer` | Packaged visualizer asset bundle | Manifest declaration; bundle manifest is not eagerly read |-| `http_route` | Managed JSON HTTP endpoint | Approved managed routes execute in the plugin venv worker |-| `frontend_page` | Declared plugin page | Packaged static pages are served through a host-gated asset route with an explicit asset closure and restrictive CSP |-| `persistence_schema` | Declared plugin data schema | Authenticated introspection only; migrations and data access are future work |-| `app_connector` | Declared downstream application adapter | Authenticated introspection only; adapter execution is future work |--Each extension has one stable `id`. Python-backed extensions declare-`entry_point`; visualizers declare their packaged bundle `manifest`. A root-manifest may contain multiple extensions, but it does not grant a universal-runtime API. Runtime code still binds each extension to its typed protocol.--`http_route` and `frontend_page` declare static paths beginning with `/`.-HTTP route methods are limited to `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`;-authentication is exactly one of `public`, `authenticated`, or `admin`.-Persistence schemas declare a packaged JSON file and named operations. App-connectors declare named operations. Unknown fields remain invalid for every-extension type.--Built-in DeepTutor IDs always win. A plugin cannot replace a built-in-capability, tool, Reading action, or visualizer by reusing its ID.--`dependencies` is an explicit, ordered closure. Requirements must be PEP 508-name-and-version constraints; direct URLs, environment markers, extras, and-duplicate canonical names are rejected. Managed installation passes every-requirement plus the plugin wheel to the plugin-private interpreter with-`pip install --no-deps --only-binary=:all:`, so pip cannot mutate the host environment or discover-a different transitive graph at install time.--## Registry states--`PluginRegistry` reads installed distribution files and the vendored catalog.-It never calls `entry_point.load()` and never imports third-party code.--| State | Meaning |-| --- | --- |-| `available` | Catalog entry is not installed |-| `approval-required` | Installed and compatible, but its exact permission snapshot has not been approved |-| `enabled` | Installed, compatible, and not locally disabled |-| `disabled` | Installed and locally disabled |-| `incompatible` | Installed, but its DeepTutor or API contract is not supported |-| `broken` | Manifest unreadable/invalid, duplicate ID, or cannot be represented |-| `deprecated` | Catalog or review metadata marks the plugin obsolete |--A malformed installed manifest affects only that plugin. A malformed catalog-row affects only that row. Existing entry-point loaders keep their containment-behavior.--Local enablement is persisted as:--```json-{- "version": 2,- "disabled": [],- "plugins": {- "org.author.example": {- "manifest": {},- "installation": null,- "history": [],- "approval": {- "digest": "sha256-of-manifest-and-artifact-identity",- "approved_at": "2026-09-08T00:00:00Z"- }- }- }-}-```--The file is written atomically under `data/user/settings/plugins.json`. The-legacy version 1 `{version, disabled}` shape is read as version 2 with no-plugin rows; the legacy file itself is not rewritten until another plugin state-operation commits.--`approval.digest` binds the complete normalized manifest and the installed-artifact identity. Managed installs use the reviewed wheel SHA-256; external-distributions use their version and RECORD identity. A manifest, version or-artifact change invalidates approval even when permissions are unchanged.-External distribution upgrades require a process restart to replace already-imported host modules; managed workers start from their version-private environment. Approval does not automatically enable a locally-disabled plugin.--Managed installation records also retain the installed package root. Records-written before this field existed remain valid; executable frontend pages do-not guess or scan for that root and return 404 until the plugin is reinstalled-or upgraded.--## Official catalog--The official catalog is a vendored, manually reviewed JSON snapshot. Browsing-and version resolution do not make a live third-party registry request:--- schema `deeptutor.plugin-catalog/v2` has one row per immutable- `(plugin ID, version)` pair; legacy v1 snapshots remain readable but cannot- be remote-install sources;-- the package requirement is pinned;-- the distribution artifact has a direct immutable HTTPS wheel URL, SHA-256- digest, exact byte size, and non-empty platform tags;-- compatibility and permissions are repeated from review-time metadata;-- status is `available`, `deprecated`, or `hidden`;-- malformed or duplicate rows are dropped without invalidating the catalog;-- `latest` resolves only the newest available non-prerelease version; exact- versions must match the catalog string, deprecated versions require an- explicit flag, and hidden rows are never returned.--The initial snapshot is intentionally empty. DeepTutor maintainers must not-invent third-party plugins to seed it. Real entries are added only with source-review, artifact pinning, and recorded reviewers.--## Catalog distribution--`deeptutor plugin install <plugin-id>` resolves a row in the vendored catalog,-downloads only that row's reviewed HTTPS URL, and then invokes the local-lifecycle with the catalog digest. Redirects are rejected, the download has a-timeout and bounded size, `Content-Length` must match the reviewed size, and-the streamed bytes must match both size and SHA-256 before installation. A-failed download removes its temporary wheel and never reaches pip or plugin-state. The URL is review metadata, not a CLI input: there is no arbitrary URL-install path and no automatic update check.--## Managed lifecycle--`PluginLifecycleManager` installs only an existing local wheel. That wheel can-come from the explicit local command or the verified catalog downloader. It-reads and validates the root manifest directly from the zip archive before-creating an environment or importing plugin code. An optional local `--sha256`-pin and the mandatory catalog pin are checked before install. The reviewed-artifact is copied under the plugin's managed root, and each plugin version-receives its own virtual environment.--Installation, upgrade, same-version reinstall, and rollback all clear the-previous approval. This is deliberate: the user approved an exact permission,-artifact, and manifest snapshot, not an implicit trust transfer to another-version. Failed dependency installation leaves the current version, approval,-and environment unchanged. A successful upgrade keeps the prior version-directory and environment for rollback; rollback moves the current version to-history and restores the prior environment. Uninstall removes the managed state,-artifacts, environments, and local enable/disable entry for that plugin.--Managed Tool and Capability extensions use a worker module entry point such as-`learning_echo.worker`. DeepTutor launches that module with the plugin venv-interpreter, exchanges one JSON request and response over stdin/stdout, and-rejects worker declarations whose permission snapshot exceeds the approved-manifest. Existing Python entry-point extensions continue to load classes or-factories in the host process, but only after the root-manifest gate accepts-them.--## Managed HTTP and introspection API--Managed HTTP routes are always dispatched under-`/api/plugins/{plugin-id}{path}`. They cannot override a built-in route and are-resolved from plugin state once at the start of each request. Only an approved,-compatible, enabled, managed installation with an installation record can-expose a route.-Unapproved, incompatible, broken, deprecated, disabled, external, and missing-routes all return the same HTTP 404 response.--The host performs route authentication before launching the worker. A public-route has no host credential dependency; `authenticated` uses the normal-session/bearer dependency; `admin` uses the host admin dependency. The worker-request contains only the declared method and path, normalized query values,-a JSON body no larger than 1 MiB, and the manifest's auth policy. Cookies,-bearer tokens, and raw host request headers are never forwarded.--Workers implement `handle_http` and return one JSON object containing a-response `status`, JSON `body`, and optional headers. Allowed statuses are the-normal application statuses the plugin can own (`200`, `201`, `202`, `204`,-`400`, `404`, `409`, `422`, and `500`); authentication and redirect statuses-belong to the host. `Cache-Control` is the only worker-provided response-header, with values limited to `no-store`, `no-cache`, or `max-age=<seconds>`.-The host always sets the JSON media type. Invalid worker output becomes a-generic HTTP 500 response and affects only that plugin request.--`GET /api/plugins/extensions` is authenticated and enumerates the extension-declarations of approved, enabled, managed installations. It is the discovery-surface for persistence schemas and app connectors. An executable-`frontend_page` also includes `entry_url`.--## Managed frontend pages--A `frontend_page` that declares a packaged page manifest executes as static-browser assets, not as host React or Next code. The page manifest is a separate-JSON contract (`deeptutor.plugin-frontend-page/v1`) with one `entry` and an-explicit `assets` closure. Paths are relative to the installed package root,-must be regular files, cannot be symlinks, and are limited to small web asset-types and aggregate sizes.--The host serves the canonical page URL-`/api/plugins/{plugin-id}/pages/{extension-id}/`; the non-slash form redirects-to it so relative asset URLs resolve predictably. It serves declared asset-paths only after registry gating and the manifest's host authentication-policy. Responses use `no-store` and `nosniff`, and carry a restrictive CSP with-`sandbox allow-scripts`,-`connect-src 'none'`, no framing by third parties, and no plugin-controlled-response headers. The entry document uses same-origin resource policy while-declared assets use `Cross-Origin-Resource-Policy: cross-origin`; the sandboxed-document has an opaque origin, so same-origin asset policy would block its own-packaged scripts. This gives static plugin UI a browser execution context-without injecting untrusted code into DeepTutor's frontend bundle. It is not a-signature system and does not remove the need for plugin review.--## Trust and compatibility--The current trust model is human curation plus pinned metadata. Catalog-browsing and version resolution remain offline. Local installation accepts a-wheel and verifies an optional artifact digest before invoking pip; catalog-installation additionally binds the download URL, size, and digest to the-reviewed snapshot. Signing and a process/container security sandbox are-separate future phases and must not be implied by this catalog format.--Python permissions are disclosure and approval metadata in v1. Existing-entry-point extensions still execute in the host Python process after approval.-Managed worker extensions execute outside the host process but retain host-operating-system access. Reviewers and users need that fact to be visible; OS-scope enforcement belongs to a later isolation design.--Reading extensions continue to use the server-verified Reading context and-restricted result types. A plugin cannot widen its context by changing its-manifest declaration.--Visualizers that need untrusted HTML/UI execution use the existing sandboxed-iframe model. Their packaged asset manifests and renderer contracts remain-separate typed specs. Managed frontend pages use their own explicit asset-closure and CSP sandbox rather than the visualizer runtime.--## Chrome compatibility--Direct Chrome extension reuse is out of scope. A future compatibility layer can-target a narrow subset, but it must translate a Chrome extension into a typed-DeepTutor extension declaration and a review record. It must not import Chrome-background/service-worker code into DeepTutor or hand browser-level authority-to a Python plugin. Marketplace distribution remains based on Python packages;-Chrome-specific assets may ship as resources inside such a package.--## Delivery phases--1. **Phase A - contract**: root manifest validation, RFC, catalog schema.-2. **Phase B - visibility**: metadata-only installed/catalog registry and CLI- state/search/show/enable/disable commands.-3. **Phase C - runtime gating**: existing capability, loop, Reading, and tool- loaders respect local enablement and manifest compatibility.-4. **Phase D - visualizer loading**: package visualizer manifests into the- v1.6.2-style visualizer catalog while preserving built-in precedence.-5. **Phase E - installation**: pinned artifact download, digest verification,- and an explicit user-approved installation flow.-6. **Phase F - sandbox/signing**: stronger isolation, signatures, and developer- publishing workflow.--This repository currently implements Phases A through C, plus the local-wheel-and catalog-driven remote installation, approval, Tool/Capability/HTTP worker,-upgrade, rollback, uninstall, and managed introspection slice of Phase E.-Developer publishing automation, persistence migrations, app connector-execution, visualizer packaging, signing, and a stronger sandbox remain future-phases.--## Local dev completion of Phase 1 (#1307)--Root-manifest gates run before every `entry_point.load()` through the shared-loader, including legacy and reading groups. Cached objects recheck scope,-approval, generation and enablement before execution. Legacy packages without a-root manifest retain compatibility during migration. Private worker execution-uses a 60-second deadline, 1 MiB request budget, 2 MiB stdout budget and 64 KiB-stderr budget; async tool/capability/HTTP calls run off the event loop.--State mutations and lifecycle work have nonblocking process ownership. Corrupt-state is preserved and rejected. Version artifacts are immutable; failed-same-version installs preserve the prior environment and bytes. Rollback-verifies the retained artifact hash and clears approval. Installation accepts-wheel-only dependencies so installing an unapproved package does not build a-source distribution. Dependency constraints are disclosed; dependency hash-signatures and stronger isolation remain on the ecosystem roadmap above.--Authenticated API inspection includes `GET /api/plugins/catalog`, `/state`,-`/{id}/info` and `/extensions`. Admin mutations include `POST /{id}/install`-(reviewed catalog version), `/approve` (requires the inspected `snapshot_digest`),-`/enable`, `/disable`, `/rollback`, and `DELETE /{id}/installation`. CLI also-supports local wheel installation with an optional expected SHA-256. Install,-upgrade and rollback all require fresh approval. The vendored catalog starts-empty; the packaged learning_echo example exercises the real wheel/worker/static-page path without inventing third-party catalog entries.--Host authentication establishes the user scope before resolving any HTTP route-or frontend asset. With host authentication enabled, even a manifest's `public`-route needs a host session; `public` means no additional plugin-specific admin-check. No bearer token, cookie or authentication header is forwarded to workers.-The host's normal authentication-disabled local mode remains usable.diff --git a/examples/plugins/learning_echo/README.md b/examples/plugins/learning_echo/README.mddeleted file mode 100644index 73251b2e7..000000000--- a/examples/plugins/learning_echo/README.md+++ /dev/null@@ -1,20 +0,0 @@-# Learning Echo plugin--This package is the reference implementation for the managed plugin runtime.-It declares one Tool, one Capability, one HTTP route, and one static frontend-page. The page requests only the `sandboxed-iframe` UI permission; the package-has no Python dependencies.--Build a local wheel:--```bash-python -m pip wheel --no-deps -w /tmp/deeptutor-plugins examples/plugins/learning_echo-```--Install, review, approve, and roll back through `deeptutor plugin`. The install-step reads `deeptutor.plugin.json` before importing plugin code and creates a-plugin-private virtual environment.--After approval and enablement, the page is available at-`/api/plugins/org.deeptutor.learning_echo/pages/learning_echo_page/`. Its entry-and asset closure are declared in `learning_echo/frontend/page.json`.diff --git a/tests/api/test_plugins_router.py b/tests/api/test_plugins_router.pyindex f86e34cee..ff0ce63a7 100644--- a/tests/api/test_plugins_router.py+++ b/tests/api/test_plugins_router.py@@ -443,7 +443,7 @@ def test_real_wheel_http_flow_uses_managed_worker_subprocess(raw["permissions"]["ui"] = ["sandboxed-iframe"]raw["extensions"][1]["manifest"] = "frontend/page.json"wheel_path = tmp_path / "learning_echo-1.0.0-py3-none-any.whl"- source_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ source_root = Path(__file__).parents[2] / "docs-for-dev" / "examples" / "learning_echo"files = {"learning_echo/deeptutor.plugin.json": json.dumps(raw).encode("utf-8"),"learning_echo/__init__.py": (diff --git a/tests/cli/test_docs_contract.py b/tests/cli/test_docs_contract.pyindex 95b391818..3b2a43466 100644--- a/tests/cli/test_docs_contract.py+++ b/tests/cli/test_docs_contract.py@@ -5,23 +5,54 @@ from __future__ import annotationsfrom pathlib import Pathimport reimport shlex+from urllib.parse import unquote, urlsplitROOT = Path(__file__).resolve().parents[2]DOCS_ROOT = ROOT / "site" / "src" / "content" / "docs"+HANDBOOK_ROOT = ROOT / "docs-for-dev"PUBLIC_DOCS = (ROOT / "README.md",ROOT / "deeptutor_cli" / "README.md",ROOT / "SKILL.md",- ROOT / "docs-for-user" / "AGENT_SETUP.md",+ ROOT / "docs-for-dev" / "AGENT_SETUP.md",)+def test_handbook_links_resolve_and_index_reaches_every_guide() -> None:+ """Moving guides/examples must retain a navigable, self-contained handbook."""+ index = HANDBOOK_ROOT / "README.md"+ assert index.is_file()+ assert (HANDBOOK_ROOT / "AGENT_SETUP.md").is_file()+ pages = {path.resolve() for path in HANDBOOK_ROOT.rglob("*.md")}+ graph: dict[Path, set[Path]] = {}+ for path in pages:+ text = re.sub(r"```.*?```", "", path.read_text(encoding="utf-8"), flags=re.S)+ graph[path] = set()+ for href in re.findall(r"\[[^\]]+\]\(([^)]+)\)", text):+ url = urlsplit(href.strip().strip("<>"))+ if url.scheme or url.netloc:+ continue+ target = (path.parent / unquote(url.path)).resolve() if url.path else path+ assert target.exists(), f"{path.relative_to(ROOT)}: broken link {href}"+ if target in pages:+ graph[path].add(target)+ visited: set[Path] = set()+ pending = [index.resolve()]+ while pending:+ page = pending.pop()+ if page not in visited:+ visited.add(page)+ pending.extend(graph[page] - visited)+ assert visited == pages, f"Guides unreachable from handbook index: {pages - visited}"++def _command_doc_paths() -> list[Path]:paths: list[Path] = []if DOCS_ROOT.exists():paths.extend(DOCS_ROOT.rglob("*.md"))paths.extend(path for path in PUBLIC_DOCS if path.exists())- return paths+ paths.extend(HANDBOOK_ROOT.rglob("*.md"))+ return list(dict.fromkeys(paths))def _docs_text() -> str:diff --git a/tests/plugins/test_runtime.py b/tests/plugins/test_runtime.pyindex 4b3339971..dcba89595 100644--- a/tests/plugins/test_runtime.py+++ b/tests/plugins/test_runtime.py@@ -111,7 +111,7 @@ async def test_example_worker_tool_and_capability(tmp_path, monkeypatch) -> Nonemonkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)manifest = parse_manifest(_raw_manifest())installation = _installation(tmp_path)- example_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ example_root = Path(__file__).parents[2] / "docs-for-dev" / "examples" / "learning_echo"monkeypatch.setattr("deeptutor.plugins.runtime._clean_env",lambda: {@@ -146,7 +146,7 @@ def test_example_worker_http_route(tmp_path, monkeypatch) -> None:monkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)manifest = parse_manifest(_raw_manifest())installation = _installation(tmp_path)- example_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ example_root = Path(__file__).parents[2] / "docs-for-dev" / "examples" / "learning_echo"monkeypatch.setattr("deeptutor.plugins.runtime._clean_env",lambda: {**dict(os.environ), "PYTHONPATH": str(example_root)},diff --git a/tests/scripts/test_docker_compose.py b/tests/scripts/test_docker_compose.pyindex e0a25d7b1..68282b296 100644--- a/tests/scripts/test_docker_compose.py+++ b/tests/scripts/test_docker_compose.py@@ -147,13 +147,13 @@ def test_container_docs_use_temporary_codex_oauth_bridge() -> None:"""README links to the canonical guide, which owns the exact commands."""root = Path(__file__).resolve().parents[2]readme = (root / "README.md").read_text(encoding="utf-8")- guide = (root / "docs-for-user" / "CONTAINERIZATION.md").read_text(encoding="utf-8")+ guide = (root / "docs-for-dev" / "CONTAINERIZATION.md").read_text(encoding="utf-8")heading = "### Temporary local Codex OAuth bridge"assert heading in guide, f"{heading} was renamed; update this test with it"section = guide.split(heading, 1)[1].split("\n### ", 1)[0]normalized_section = " ".join(section.replace("\\\n", " ").split())- assert "docs-for-user/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge" in readme+ assert "docs-for-dev/CONTAINERIZATION.md#temporary-local-codex-oauth-bridge" in readmeassert "127.0.0.1:1455:3782" in sectionassert "127.0.0.1:1457:3782" in sectionfor base_file in ("docker-compose.yml", "docker-compose.ghcr.yml"):diff --git a/web/locales/de/app.json b/web/locales/de/app.jsonindex 9f7a105ca..708e68d4f 100644--- a/web/locales/de/app.json+++ b/web/locales/de/app.json@@ -5253,7 +5253,7 @@"settings.agentSetup.instructions": "Kopiere diesen Prompt in einen Agenten mit Terminalzugriff auf deine DeepTutor-Installation, etwa Codex oder Claude Code.","settings.agentSetup.copy": "Prompt kopieren","settings.agentSetup.copyFailed": "Kopieren fehlgeschlagen. Markiere den Text oben und kopiere ihn manuell.",- "settings.agentSetup.prompt": "Hilf mir, meine vorhandene DeepTutor-Installation einzurichten: https://github.com/HKUDS/DeepTutor.\nLies zuerst SKILL.md und docs-for-user/AGENT_SETUP.md im Quellcode der passenden Version oder im Repository, falls kein lokaler Quellcode vorliegt.\nErmittle Installation, Version, laufende Instanz, Konto und Laufzeitverzeichnis. Verwende meine Umgebung weiter und bewahre vorhandene Dateien, Einstellungen und noch nicht angewendete Entwürfe.\nVerbinde einen Anbieter und wähle ein Chatmodell; richte Embedding, Suche und weitere Dienste nur bei Bedarf ein. Frage nach fehlenden Modellentscheidungen oder Zugangsdatenquellen. Fordere keine API-Schlüssel im Chat an und gib sie nicht aus.\nNutze die Anleitung und --help der installierten CLI zur Einrichtung und Prüfung derselben Instanz. Berichte über Änderungen, tatsächliche Prüfergebnisse und offene Schritte.",+ "settings.agentSetup.prompt": "Hilf mir, meine vorhandene DeepTutor-Installation einzurichten: https://github.com/HKUDS/DeepTutor.\nLies zuerst SKILL.md und docs-for-dev/AGENT_SETUP.md im Quellcode der passenden Version oder im Repository, falls kein lokaler Quellcode vorliegt.\nErmittle Installation, Version, laufende Instanz, Konto und Laufzeitverzeichnis. Verwende meine Umgebung weiter und bewahre vorhandene Dateien, Einstellungen und noch nicht angewendete Entwürfe.\nVerbinde einen Anbieter und wähle ein Chatmodell; richte Embedding, Suche und weitere Dienste nur bei Bedarf ein. Frage nach fehlenden Modellentscheidungen oder Zugangsdatenquellen. Fordere keine API-Schlüssel im Chat an und gib sie nicht aus.\nNutze die Anleitung und --help der installierten CLI zur Einrichtung und Prüfung derselben Instanz. Berichte über Änderungen, tatsächliche Prüfergebnisse und offene Schritte.","settings.voiceDiscovery.loading": "Stimmen werden geladen…","settings.voiceDiscovery.modelFirst": "Wähle zuerst ein Modell.","settings.voiceDiscovery.failed": "Stimmen konnten nicht geladen werden. Prüfe Verbindung und Berechtigungen und versuche es erneut.",diff --git a/web/locales/en/app.json b/web/locales/en/app.jsonindex dd05c905a..ca59328cb 100644--- a/web/locales/en/app.json+++ b/web/locales/en/app.json@@ -5253,7 +5253,7 @@"settings.agentSetup.instructions": "Copy this prompt into an Agent with terminal access to your DeepTutor installation, such as Codex or Claude Code.","settings.agentSetup.copy": "Copy prompt","settings.agentSetup.copyFailed": "Could not copy. Select the text above and copy it manually.",- "settings.agentSetup.prompt": "Help me configure my existing DeepTutor installation: https://github.com/HKUDS/DeepTutor.\nFirst read SKILL.md and docs-for-user/AGENT_SETUP.md in the matching checkout (or in that repository if no local source is available).\nIdentify the installation, version, running instance, account, and runtime home. Reuse my environment and preserve existing files, settings, and pending drafts.\nHelp me connect a provider and select a chat model; configure embedding, search, and other services only as needed. Ask for missing model choices or credential sources; do not ask me to paste API keys into chat or print them.\nFollow the guide and the installed CLI's --help to configure and verify this same instance. Finish with what changed, actual check results, and any remaining steps.",+ "settings.agentSetup.prompt": "Help me configure my existing DeepTutor installation: https://github.com/HKUDS/DeepTutor.\nFirst read SKILL.md and docs-for-dev/AGENT_SETUP.md in the matching checkout (or in that repository if no local source is available).\nIdentify the installation, version, running instance, account, and runtime home. Reuse my environment and preserve existing files, settings, and pending drafts.\nHelp me connect a provider and select a chat model; configure embedding, search, and other services only as needed. Ask for missing model choices or credential sources; do not ask me to paste API keys into chat or print them.\nFollow the guide and the installed CLI's --help to configure and verify this same instance. Finish with what changed, actual check results, and any remaining steps.","settings.voiceDiscovery.loading": "Fetching voices…","settings.voiceDiscovery.modelFirst": "Choose a model to fetch its voices.","settings.voiceDiscovery.failed": "Could not fetch voices. Check the provider connection and permissions, then retry.",diff --git a/web/locales/fr/app.json b/web/locales/fr/app.jsonindex b84a8a78b..7f273ca34 100644--- a/web/locales/fr/app.json+++ b/web/locales/fr/app.json@@ -5693,7 +5693,7 @@"settings.agentSetup.instructions": "Copiez cette consigne dans un Agent ayant accès au terminal de votre installation DeepTutor, comme Codex ou Claude Code.","settings.agentSetup.copy": "Copier la consigne","settings.agentSetup.copyFailed": "Échec de la copie. Sélectionnez le texte ci-dessus et copiez-le manuellement.",- "settings.agentSetup.prompt": "Aide-moi à configurer mon installation existante de DeepTutor : https://github.com/HKUDS/DeepTutor.\nLis d’abord SKILL.md et docs-for-user/AGENT_SETUP.md dans les sources de la version correspondante, ou dans ce dépôt si les sources locales sont absentes.\nIdentifie l’installation, la version, l’instance active, le compte et le répertoire d’exécution. Réutilise mon environnement et préserve les fichiers, paramètres et brouillons en attente.\nConnecte un fournisseur et sélectionne un modèle de conversation ; configure les embeddings, la recherche et les autres services selon mes besoins. Demande les choix de modèles ou les sources d’identifiants manquants ; ne me demande pas de coller des clés API dans le chat et ne les affiche pas.\nSuis le guide et l’aide --help de la CLI installée pour configurer et vérifier cette même instance. Termine par les changements, les résultats réels des vérifications et les étapes restantes.",+ "settings.agentSetup.prompt": "Aide-moi à configurer mon installation existante de DeepTutor : https://github.com/HKUDS/DeepTutor.\nLis d’abord SKILL.md et docs-for-dev/AGENT_SETUP.md dans les sources de la version correspondante, ou dans ce dépôt si les sources locales sont absentes.\nIdentifie l’installation, la version, l’instance active, le compte et le répertoire d’exécution. Réutilise mon environnement et préserve les fichiers, paramètres et brouillons en attente.\nConnecte un fournisseur et sélectionne un modèle de conversation ; configure les embeddings, la recherche et les autres services selon mes besoins. Demande les choix de modèles ou les sources d’identifiants manquants ; ne me demande pas de coller des clés API dans le chat et ne les affiche pas.\nSuis le guide et l’aide --help de la CLI installée pour configurer et vérifier cette même instance. Termine par les changements, les résultats réels des vérifications et les étapes restantes.","settings.voiceDiscovery.loading": "Chargement des voix…","settings.voiceDiscovery.modelFirst": "Choisissez d’abord un modèle.","settings.voiceDiscovery.failed": "Impossible de charger les voix. Vérifiez la connexion et les autorisations, puis réessayez.",diff --git a/web/locales/pl/app.json b/web/locales/pl/app.jsonindex edb59bd88..1ac2d198b 100644--- a/web/locales/pl/app.json+++ b/web/locales/pl/app.json@@ -5269,7 +5269,7 @@"settings.agentSetup.instructions": "Skopiuj ten prompt do Agenta z dostępem do terminala instalacji DeepTutor, na przykład Codex lub Claude Code.","settings.agentSetup.copy": "Kopiuj prompt","settings.agentSetup.copyFailed": "Kopiowanie nie powiodło się. Zaznacz powyższy tekst i skopiuj go ręcznie.",- "settings.agentSetup.prompt": "Pomóż mi skonfigurować istniejącą instalację DeepTutor: https://github.com/HKUDS/DeepTutor.\nNajpierw przeczytaj SKILL.md i docs-for-user/AGENT_SETUP.md w źródłach odpowiedniej wersji lub w tym repozytorium, jeśli brak lokalnych źródeł.\nUstal instalację, wersję, uruchomioną instancję, konto i katalog środowiska uruchomieniowego. Wykorzystaj istniejące środowisko i zachowaj pliki, ustawienia oraz niezastosowane wersje robocze.\nPodłącz dostawcę i wybierz model rozmowy; skonfiguruj embeddingi, wyszukiwanie i pozostałe usługi tylko w razie potrzeby. Zapytaj o brakujące wybory modeli lub źródła danych uwierzytelniających; nie proś o wklejanie kluczy API na czacie i nie wyświetlaj ich.\nKorzystaj z przewodnika i --help zainstalowanego CLI, aby skonfigurować i zweryfikować tę samą instancję. Na końcu podaj zmiany, rzeczywiste wyniki kontroli i pozostałe kroki.",+ "settings.agentSetup.prompt": "Pomóż mi skonfigurować istniejącą instalację DeepTutor: https://github.com/HKUDS/DeepTutor.\nNajpierw przeczytaj SKILL.md i docs-for-dev/AGENT_SETUP.md w źródłach odpowiedniej wersji lub w tym repozytorium, jeśli brak lokalnych źródeł.\nUstal instalację, wersję, uruchomioną instancję, konto i katalog środowiska uruchomieniowego. Wykorzystaj istniejące środowisko i zachowaj pliki, ustawienia oraz niezastosowane wersje robocze.\nPodłącz dostawcę i wybierz model rozmowy; skonfiguruj embeddingi, wyszukiwanie i pozostałe usługi tylko w razie potrzeby. Zapytaj o brakujące wybory modeli lub źródła danych uwierzytelniających; nie proś o wklejanie kluczy API na czacie i nie wyświetlaj ich.\nKorzystaj z przewodnika i --help zainstalowanego CLI, aby skonfigurować i zweryfikować tę samą instancję. Na końcu podaj zmiany, rzeczywiste wyniki kontroli i pozostałe kroki.","settings.voiceDiscovery.loading": "Pobieranie głosów…","settings.voiceDiscovery.modelFirst": "Najpierw wybierz model.","settings.voiceDiscovery.failed": "Nie udało się pobrać głosów. Sprawdź połączenie i uprawnienia, a następnie ponów próbę.",diff --git a/web/locales/uk/app.json b/web/locales/uk/app.jsonindex ee57868b6..cf8087fb2 100644--- a/web/locales/uk/app.json+++ b/web/locales/uk/app.json@@ -5269,7 +5269,7 @@"settings.agentSetup.instructions": "Скопіюйте цей запит в Агента з доступом до термінала вашої інсталяції DeepTutor, наприклад Codex або Claude Code.","settings.agentSetup.copy": "Копіювати запит","settings.agentSetup.copyFailed": "Не вдалося скопіювати. Виділіть текст вище та скопіюйте вручну.",- "settings.agentSetup.prompt": "Допоможи налаштувати мою наявну інсталяцію DeepTutor: https://github.com/HKUDS/DeepTutor.\nСпочатку прочитай SKILL.md і docs-for-user/AGENT_SETUP.md у вихідному коді відповідної версії або в цьому репозиторії, якщо локального коду немає.\nВизнач спосіб встановлення, версію, запущений екземпляр, обліковий запис і робочий каталог середовища виконання. Використовуй наявне середовище, збережи файли, налаштування та незастосовані чернетки.\nПідключи постачальника й вибери модель для розмов; налаштовуй ембеддинги, пошук та інші сервіси за потреби. Запитай про відсутні рішення щодо моделей чи джерела облікових даних; не проси вставляти ключі API в чат і не виводь їх.\nДотримуйся посібника та --help встановленого CLI, щоб налаштувати й перевірити саме цей екземпляр. Наприкінці повідом про зміни, фактичні результати перевірок і решту кроків.",+ "settings.agentSetup.prompt": "Допоможи налаштувати мою наявну інсталяцію DeepTutor: https://github.com/HKUDS/DeepTutor.\nСпочатку прочитай SKILL.md і docs-for-dev/AGENT_SETUP.md у вихідному коді відповідної версії або в цьому репозиторії, якщо локального коду немає.\nВизнач спосіб встановлення, версію, запущений екземпляр, обліковий запис і робочий каталог середовища виконання. Використовуй наявне середовище, збережи файли, налаштування та незастосовані чернетки.\nПідключи постачальника й вибери модель для розмов; налаштовуй ембеддинги, пошук та інші сервіси за потреби. Запитай про відсутні рішення щодо моделей чи джерела облікових даних; не проси вставляти ключі API в чат і не виводь їх.\nДотримуйся посібника та --help встановленого CLI, щоб налаштувати й перевірити саме цей екземпляр. Наприкінці повідом про зміни, фактичні результати перевірок і решту кроків.","settings.voiceDiscovery.loading": "Завантаження голосів…","settings.voiceDiscovery.modelFirst": "Спочатку виберіть модель.","settings.voiceDiscovery.failed": "Не вдалося отримати голоси. Перевірте підключення та дозволи й повторіть спробу.",diff --git a/web/locales/zh/app.json b/web/locales/zh/app.jsonindex 6a3c1deaa..ca6bd1997 100644--- a/web/locales/zh/app.json+++ b/web/locales/zh/app.json@@ -5253,7 +5253,7 @@"settings.agentSetup.instructions": "复制这段提示词,粘贴给能够通过终端访问 DeepTutor 安装环境的 Agent,例如 Codex 或 Claude Code。","settings.agentSetup.copy": "复制提示词","settings.agentSetup.copyFailed": "复制失败,请选中上方文本手动复制。",- "settings.agentSetup.prompt": "请帮我配置已经安装的 DeepTutor:https://github.com/HKUDS/DeepTutor。\n先阅读对应版本源码中的 SKILL.md 和 docs-for-user/AGENT_SETUP.md;没有本地源码时,从上述仓库读取指南。\n确认安装方式、版本、正在运行的实例、账号和运行目录,复用现有环境,保留已有文件、设置和待应用的草稿。\n帮我连接提供方并选择对话模型,嵌入模型、搜索等其他服务按需配置。缺少模型选择或凭据来源时再问我,不要让我在聊天中粘贴 API Key,也不要输出密钥。\n根据指南和已安装 CLI 的 --help 完成配置,并验证当前这个实例是否可用。最后告诉我改了什么、实际检查结果和仍需完成的步骤。",+ "settings.agentSetup.prompt": "请帮我配置已经安装的 DeepTutor:https://github.com/HKUDS/DeepTutor。\n先阅读对应版本源码中的 SKILL.md 和 docs-for-dev/AGENT_SETUP.md;没有本地源码时,从上述仓库读取指南。\n确认安装方式、版本、正在运行的实例、账号和运行目录,复用现有环境,保留已有文件、设置和待应用的草稿。\n帮我连接提供方并选择对话模型,嵌入模型、搜索等其他服务按需配置。缺少模型选择或凭据来源时再问我,不要让我在聊天中粘贴 API Key,也不要输出密钥。\n根据指南和已安装 CLI 的 --help 完成配置,并验证当前这个实例是否可用。最后告诉我改了什么、实际检查结果和仍需完成的步骤。","settings.voiceDiscovery.loading": "正在获取音色…","settings.voiceDiscovery.modelFirst": "请先选择模型,再获取音色。","settings.voiceDiscovery.failed": "音色获取失败,请检查提供方连接和权限后重试。",diff --git a/web/tests/settings-agent-setup.spec.tsx b/web/tests/settings-agent-setup.spec.tsxindex 4ecd9c4f0..6d6bf091e 100644--- a/web/tests/settings-agent-setup.spec.tsx+++ b/web/tests/settings-agent-setup.spec.tsx@@ -25,7 +25,7 @@ describe("Agent setup handoff", () => {fireEvent.click(trigger);const prompt = screen.getByRole("textbox") as HTMLTextAreaElement;expect(prompt).toHaveAttribute("readonly");- expect(prompt.value).toContain("docs-for-user/AGENT_SETUP.md");+ expect(prompt.value).toContain("docs-for-dev/AGENT_SETUP.md");expect(prompt.value).toContain("existing DeepTutor installation");expect(prompt.value).toContain("pending drafts");fireEvent.click(screen.getByRole("button", { name: en["settings.agentSetup.copy"] }));