isLinXu · Oct 27, 2026 · Oct 27, 2026
diff --git a/README.md b/README.md
@@ -114,7 +114,7 @@ For a deep dive into the design philosophy of MoE modules, detailed routing mech
   - [Training](#training)
   - [Inference](#inference)
   - [Export](#export)
-  - [Gradio Demo](#gradio-demo)
+  - [Studio Task Platform](#studio-task-platform)
 - [Community & Contributing](#-community--contributing)
 - [License](#-license)
 - [Acknowledgements](#-acknowledgements)
@@ -705,18 +705,19 @@ model.export(format="engine", half=True)  # Export to TensorRT
 # formats: onnx, openvino, engine, coreml, saved_model, pb, tflite, edgetpu, tfjs
 ```
 
-### Gradio Demo
+### Studio Task Platform
 
-Launch a local web interface to test the model interactively. This application provides a user-friendly Gradio dashboard for model inference, supporting automatic model scanning, task switching (Detection, Segmentation, Classification), and real-time visualization.
+Launch Studio to submit and manage model tasks in your browser. The platform supports training, validation, prediction, export and environment diagnostics. View job status and logs, cancel tasks, and preview or download results.
+
+Run from the repository root:
 
 ```bash
-python start_studio.py
-# Open http://127.0.0.1:7860 in your browser
+python -m pip install -e ".[studio]"
+python main_engine.py
+# Open http://127.0.0.1:8000 in your browser
 ```
 
-This recommended launcher starts both the FastAPI Studio Job API and the Gradio WebUI. For manual two-process startup,
-run `python main_engine.py` first and then `python app.py` in a second terminal. `python app.py` remains a Gradio-only
-entrypoint and requires the API configured by `F1_STUDIO_API_URL` (default: `http://127.0.0.1:8000`).
+See the [Studio documentation](docs/studio/README.md) and [user guide](docs/studio/user_guide.md) for more startup options and usage instructions.
 
 ## 🤝 Community & Contributing
 

diff --git a/README_CN.md b/README_CN.md
@@ -111,7 +111,7 @@
   - [训练](#训练)
   - [推理](#推理)
   - [导出](#导出)
-  - [Gradio 演示](#gradio-演示)
+  - [Studio 任务平台](#studio-任务平台)
 - [社区与贡献](#-社区与贡献)
 - [许可证](#-许可证)
 - [致谢](#-致谢)
@@ -692,15 +692,20 @@ model.export(format="engine", half=True)  # 导出为 TensorRT
 # 格式: onnx, openvino, engine, coreml, saved_model, pb, tflite, edgetpu, tfjs
 ```
 
-### Gradio 演示
+### Studio 任务平台
 
-启动本地 Web 界面以交互式测试模型。此应用程序提供了一个用户友好的 Gradio 仪表板，用于模型推理，支持自动模型扫描、任务切换（检测、分割、分类）和实时可视化。
+启动 Studio 任务平台，在浏览器中提交和管理模型任务。支持训练、验证、预测、导出和环境诊断，可查看任务状态和运行日志、取消任务，并预览和下载结果文件。
+
+在仓库根目录运行：
 
 ```bash
-python app.py
-# 在浏览器中打开 http://127.0.0.1:7860
+python -m pip install -e ".[studio]"
+python main_engine.py
+# 在浏览器中打开 http://127.0.0.1:8000
 ```
 
+更多启动方式和操作说明见 [Studio 文档](docs/studio/README.md)和[用户指南](docs/studio/user_guide.md)。
+
 ## 🤝 社区与贡献
 
 我们欢迎贡献！有关如何参与的详细信息，请查看我们的 [贡献指南](CONTRIBUTING.md)。

diff --git a/docs/f1_user_manual.md b/docs/f1_user_manual.md
diff --git a/docs/studio/README.md b/docs/studio/README.md
@@ -0,0 +1,55 @@
+# YOLO-Master Studio
+
+Studio is an asynchronous task platform for model training and inference
+workflows. It manages training, validation, prediction, export and diagnostic
+tasks through a shared HTTP API. React, the built-in console and Gradio Jobs
+are clients of this platform.
+
+Each submitted task is a **job** that runs in the background. You can follow its
+status, read logs and download its output files.
+
+## Start from a source checkout
+
+Use Python 3.10 or later. From the repository root, install and start Studio:
+
+```bash
+python -m pip install -e ".[studio]"
+python main_engine.py
+```
+
+Keep the terminal open and visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/). This built-in console
+runs directly from the checkout; it needs neither Node.js nor Gradio. The same
+service provides interactive API documentation at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+
+The service binds to the local machine. See [security](security.md) for deployment
+settings and access rules.
+
+## Submit and inspect a job
+
+Try an environment diagnostic first; it needs no model or dataset:
+
+1. Check **Engine** is `http://127.0.0.1:8000` and select **Apply**.
+2. Choose **Task Type → diagnose**. Leave model and data fields empty.
+3. Open **Advanced options**, set **Output Directory** to `runs/diagnose`,
+   and leave **Extra Params** empty.
+4. Submit the job and select it in the job list. Wait for `completed`, then
+   read its logs and download the JSON and text reports from the artifact list.
+
+An **artifact** is a downloadable output file. Diagnostic reports contain local
+environment information. If the job fails, read its error and logs before resubmitting.
+
+Stop the service with Ctrl+C in its terminal. Closing the browser keeps it running.
+
+## Next steps
+
+- [User guide](user_guide.md): choose a client, prepare model/data paths,
+  track jobs, cancel work and download results.
+- [Clients and launcher](frontend.md): React development, Gradio startup and
+  process ownership.
+- [API](api.md): request examples, errors, log cursors, downloads and the
+  [generated input schema](job_schema.json).
+- [Service configuration](service.md): trusted roots, local origins and settings.
+- [Architecture](architecture.md), [Core](core.md) and [Runtime](runtime.md):
+  execution layers, handlers, persistence and checkpoint recovery.
+- [Security](security.md): supported deployment and file-access rules.
+- [Testing and reproduction](testing.md): automated checks and manual procedures.
diff --git a/docs/studio/api.md b/docs/studio/api.md
@@ -0,0 +1,119 @@
+# Studio HTTP API
+
+[Studio documentation](README.md) · [Service configuration](service.md)
+
+Run `python main_engine.py` from the repository root. The default origin is
+`http://127.0.0.1:8000`. `/docs` and `/openapi.json` describe the running HTTP
+contract. Collection routes accept both `/api/v1/jobs` and `/api/v1/jobs/`.
+
+## Submit a local diagnostic
+
+With the API running in another terminal, this standard-library Python example
+submits a diagnostic without model weights. Run it from the source checkout;
+the example uses the default server output root `runs`:
+
+```python
+import json
+from urllib.request import Request, urlopen
+
+payload = {
+    "job_id": "docs-diagnose-001",
+    "task_type": "diagnose",
+    "output": {"output_dir": "runs"},
+}
+request = Request(
+    "http://127.0.0.1:8000/api/v1/jobs",
+    data=json.dumps(payload).encode("utf-8"),
+    headers={"Content-Type": "application/json"},
+    method="POST",
+)
+with urlopen(request, timeout=10) as response:
+    print(response.status, json.load(response)["job_id"])
+```
+
+Expect HTTP 201 and the submitted ID. Use a new ID for each run; duplicates
+receive 409. Query `GET /api/v1/jobs/docs-diagnose-001` until terminal, then read
+its `/logs` and `/artifacts`. Diagnostic reports describe the local environment.
+For other tasks, `params` carries handler-specific values such as `model_path`,
+`data_source`, `device`, `epochs`
+and `imgsz`; paths must satisfy the server's independent trusted-root policy.
+The handler validates task parameters during execution; query the job's final
+status for the outcome.
+
+## Status, errors and cancellation
+
+Jobs have five states: `pending`, `running`, `completed`, `failed` and
+`cancelled`. The last three are final states. Admission and cancellation
+acknowledgements precede execution/cleanup; poll the job for its final outcome.
+
+- `POST /api/v1/jobs`: 201 accepted; 409 duplicate ID; 429 `QUEUE_FULL`;
+  422 invalid schema or input path; 503 `SERVICE_UNAVAILABLE`,
+  `SERVICE_SHUTDOWN` or `PERSISTENCE_FAILED`.
+- `GET /api/v1/jobs?limit=10&offset=0`: atomic recent-job page and total.
+  `limit` is 1–100, `offset` is nonnegative.
+- `GET /api/v1/jobs/{job_id}`: status, error code/message, metadata,
+  artifact count and numeric duration. Duration excludes queue time; an absent
+  start is null and an actual zero duration is `0.0`.
+- `POST /api/v1/jobs/{job_id}/cancel`: 202 `cancel_requested` acknowledges
+  cancellation; 200 replays an already terminal job; 409 means not cancellable;
+  404 means unknown job. Continue polling after 202 until cleanup is confirmed.
+- Unknown jobs and missing artifacts return 404. Unsupported local-boundary
+  requests receive 403 `LOCAL_ONLY`; disallowed CORS preflights receive 400.
+
+Structured transport errors use `detail.code` and `detail.message`. Existing
+duplicate, path, unknown-job and missing-artifact details remain strings;
+schema/query validation returns a sanitized error list. Handle these shapes
+separately and use status/code for program decisions.
+An admission persistence failure rolls back the unaccepted job and launches no
+worker. A later write failure has a different [durability boundary](runtime.md#persistence-and-recovery):
+execution truth can survive in memory without reaching disk. `/health` keeps
+the compatibility liveness response and exposes no persistence-warning field.
+
+## Log cursors and artifacts
+
+`GET /api/v1/jobs/{job_id}/logs?offset=0&limit=200` pages sanitized flattened
+lines. An explicit `limit` is 1–10000. Omitting it returns all currently
+remaining lines from `offset`; there is no implicit 10000-line truncation.
+Follow `next_offset` until null. Null means the current tail only; continue at
+the prior `offset + len(logs)` for later polls, including terminal tail drains.
+Changing job/API selection must invalidate older in-flight responses.
+
+`GET /api/v1/jobs/{job_id}/artifacts` returns exact relative `artifact_id`
+values, names, image flags and `download_url` values. Download from
+`GET /static/artifacts/{job_id}/{artifact_id:path}`, preserving nested IDs and
+URL-encoding their components. Downloads recheck manifest membership,
+containment and the identity of the opened file. Use the returned download URL.
+A confirmed `weights/shutdown.pt` may also be
+authorized after cleanup on a `failed / SERVICE_SHUTDOWN` job. Only listed
+artifacts are downloadable.
+
+## Regenerate the domain schema
+
+[job_schema.json](job_schema.json) is generated from `core.schema.JobRequest`
+in Pydantic validation mode. It describes domain fields; handler-specific
+`params` and HTTP response models are documented separately. The service applies
+its own lifecycle/security policy to validated inputs. The older
+`docs/api/job_schema.json` describes the legacy F1 registry.
+
+From the repository root, run this Python block (or save it as a temporary script):
+
+```python
+import json
+from pathlib import Path
+
+from core.schema import JobRequest
+
+schema = JobRequest.model_json_schema(mode="validation")
+# Drop only the volatile import-time timestamp annotation; validation is unchanged.
+schema["properties"]["metadata"]["default"].pop("created_at", None)
+Path("docs/studio/job_schema.json").write_text(
+    json.dumps(schema, indent=2, ensure_ascii=False, sort_keys=True) + "\n",
+    encoding="utf-8",
+    newline="\n",
+)
+```
+
+Record the source revision, Python and Pydantic versions when regenerating.
+Generate again in a fresh process and compare the parsed JSON and bytes; only
+the timestamp annotation is intentionally omitted. Use the running OpenAPI for
+complete endpoint/response contracts.
diff --git a/docs/studio/architecture.md b/docs/studio/architecture.md
@@ -0,0 +1,52 @@
+# Studio architecture
+
+[Studio documentation](README.md)
+
+Studio separates browser interaction, HTTP handling and job execution. A job is
+described by the shared `core.schema.JobRequest` model and runs in a worker
+process managed by the API service.
+
+```text
+React / built-in console / Gradio Jobs
+                 | HTTP
+main_engine.py + api/v1/jobs.py
+                 |
+studio.jobs_manager.JobsManager
+                 |
+CPU/GPU queues -> studio.worker_runtime.ManagedWorker
+                 |
+studio.dispatcher -> studio.handlers -> Ultralytics engines
+```
+
+## Layer responsibilities
+
+- [Core](core.md) validates job inputs, removes credentials from public text and
+  dispatches each task to its handler. Handlers adapt synchronous calls to the
+  Ultralytics engines. Direct callers supply trusted policy and validate inputs.
+- [Runtime](runtime.md) admits and schedules jobs, owns public status and
+  timestamps, persists history and authorizes output files in an artifact
+  manifest. `AdmissionPolicy`, `JobStore`, `JobLogs` and `ArtifactResolver`
+  support these operations. `ManagedWorker` contains the OS process tree and
+  reports its outcome; the manager confirms cleanup before publishing a final
+  status or releasing a slot.
+- [Service](service.md) creates one manager during application startup and waits
+  for its cleanup during shutdown (FastAPI's lifespan). HTTP requests read
+  snapshots and cancellation decisions from that manager.
+- [Clients](frontend.md) submit and monitor jobs through HTTP. Gradio's
+  **Inference Studio** retains a separate synchronous inference path beside Jobs.
+
+## Compatibility
+
+Production workers use `studio.dispatcher` and the `studio.handlers` registry.
+The retained `f1` backend and direct-call adapters are separate compatibility
+implementations. `f1/ui` provides lazy compatibility imports for `studio/ui`.
+
+The service accepts legacy `F1_*` configuration aliases and retains the health
+identity `YOLO-Master F1 Task Engine`. Version-1 snapshots and safe historical
+artifact entries remain readable; see [service compatibility](service.md#history-and-lifecycle).
+Each state file has one service owner. Restart reconciles interrupted jobs
+without running them again.
+
+`agent/` has its own runtime, dispatcher and Skills. It does not participate in
+Studio job execution. Deployment and access limits are documented in
+[security](security.md).