ysk-omni 1.0.0

package/docs/en/operations.md

@@ -0,0 +1,40 @@
+# Operations
+
+## Health
+
+```bash
+ysk-omni doctor
+ysk-omni status
+curl -sS http://127.0.0.1:3850/health
+curl -sS http://127.0.0.1:3850/ready
+```
+
+`/ready` checks SQLite and whether `llama-server` is on PATH.
+
+## Process manager
+
+```bash
+ysk-omni start --pm2
+ysk-omni restart --pm2
+ysk-omni logs -n 80
+ysk-omni logs clear
+```
+
+Admin → PM2 can inspect the same process (`ysk-omni`). Changing port there rewrites config and restarts.
+
+## Reverse proxy
+
+Set `TRUST_PROXY` to the hop count (Cloudflare → nginx → app = `2`). `PROXY_IP_SOURCE` selects how the client IP is read so bans and audit use the real address.
+
+## Updates
+
+```bash
+ysk-omni update --check
+ysk-omni update
+```
+
+Admin → System → Package can check npm/GitHub and one-click update (brief API downtime).
+
+## Port in use
+
+`doctor` reports EADDRINUSE. Stop the extra runner (`ysk-omni stop` or PM2 stop) so only one process holds :3850.

package/docs/en/runtimes.md

@@ -0,0 +1,20 @@
+# Runtimes
+
+Admin **Runtimes** lists inference tools by **host OS** (macOS, Linux, Windows): installed, missing, how to install.
+
+## One-click install
+
+Each card with an allowlisted plan has **Install**. The gateway runs Homebrew, pip, winget, or Docker as appropriate for this OS.
+
+**Uninstall** asks for confirmation, then reverses that plan.
+
+```bash
+ysk-omni runtimes
+ysk-omni runtimes install llamacpp
+ysk-omni runtimes install ffmpeg
+ysk-omni runtimes uninstall llamacpp
+```
+
+Runtime ids include `llamacpp`, `ffmpeg`, `mlx`, and others shown on the page.
+
+Catalog **Load** still needs the binary on `PATH` (or `OMNI_LLAMA_SERVER`). Install here first if `doctor` reports llama-server missing.

package/docs/zh/README.md

@@ -0,0 +1,25 @@
+# YSK Omni 文件
+
+本機 Hugging Face 權重，前面一層 OpenAI 相容 HTTP 閘道。文字走 llama-server 或 vLLM。圖像、語音、轉錄、影片走獨立 worker。
+
+| | |
+|--|--|
+| 預設連接埠 | **3850** |
+| CLI | `ysk-omni` · 短名 `ysko` |
+| 產品頁 | [ysk.hk/products/ysk-omni](https://ysk.hk/products/ysk-omni) |
+| English | [docs/en](../en/README.md) |
+
+## 目錄
+
+1. [快速開始](getting-started.md)
+2. [架構](architecture.md)
+3. [CLI 手冊](cli.md)
+4. [HTTP API](api.md)
+5. [Admin 面板](admin.md)
+6. [目錄](catalog.md)
+7. [執行環境](runtimes.md)
+8. [API 金鑰](keys.md)
+9. [媒體](media.md)
+10. [設定](configuration.md)
+11. [維運](operations.md)
+12. [開發](development.md)

package/docs/zh/admin.md

@@ -0,0 +1,44 @@
+# Admin 面板
+
+網址：`http://127.0.0.1:3850/admin/`
+
+生產 SPA：`admin/src/full/app.js` → `public/admin/boot.js`（`npm run build:admin`）。語言：英文與香港書面語。
+
+## 登入
+
+```bash
+ysk-omni admin otp
+```
+
+在登入頁輸入該碼。五分鐘過期、只能用一次。面板不會在瀏覽器保存 live API 金鑰。
+
+停用面板（只能用 CLI 重開）：
+
+```bash
+ysk-omni admin off
+ysk-omni admin on
+```
+
+## 頁面
+
+| 導航 | 用途 |
+|------|------|
+| 儀表板 | KPI、健康 |
+| 對話 | 操場。預設已載入 GGUF。媒體模型會在對話中出圖／出片／出聲 |
+| 對話記錄 | 加密請求歷史 |
+| API 金鑰 | 新增／編輯：角色、模式、速率、IP 白名單、**可用模型** |
+| 文件 | 已上傳檔案 |
+| 媒體庫 | 工作室：圖像、影片、語音、轉錄；媒體庫 |
+| 目錄 | Hub 搜尋、下載佇列、本機模型、Load／Unload／刪除 |
+| 執行環境 | 按作業系統安裝／解除安裝 llama-server、ffmpeg 等 |
+| 審計日誌 | 審計紀錄 |
+| 安全設定 | 全域 safe、預設模型 |
+| API 能力 | 協議與媒體旗標 |
+| 用量與防護 | 限額與用量 |
+| DDoS 中心 | 政策、封鎖 |
+| 佇列 | 暫停、排空、工作 |
+| PM2 | 行程管理 |
+| 系統狀態 | 軟件（Node、npm、llama-server、ffmpeg、PM2、Prisma）、套件更新、環境 |
+| 支援 | 作者與贊助 |
+
+部署新的 `boot.js` 後請硬重新整理瀏覽器。

package/docs/zh/api.md

@@ -0,0 +1,78 @@
+# HTTP API
+
+基底網址：`http://127.0.0.1:3850`。認證：`Authorization: Bearer omni_live_…`。
+
+## 模型
+
+`GET /v1/models` 列出**此金鑰可用**的 id，並帶 `modality`、`runtime`（`text`、`image`、`video`、`tts`、`stt`）。內建包括 `echo`、`piper/lessac-high`、`tts-1`、`whisper-1`，加上本機登錄與已載入引擎。
+
+金鑰有可用模型清單時，回傳清單與目錄的交集。空白清單＝全部目錄。
+
+`GET /v1/models/:id` 回傳單一 id，否則 404 或 403 `model_not_allowed`。
+
+## 對話
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| POST | `/v1/chat/completions` | OpenAI 對話。串流：`"stream": true` |
+| POST | `/v1/responses` | OpenAI Responses（文字子集） |
+| POST | `/v1/messages` | Anthropic Messages（亦接受 `x-api-key`） |
+
+文字引擎：已載入 GGUF（llama-server）、vLLM 或 `echo`。在此路由傳入媒體模型 id 不會自動生成媒體；請用媒體端點或 Admin 操場（依目錄 runtime 轉送）。
+
+完成結果的閘道擴充：`omni.sessionId`、`omni.asset_ids`（媒體）。OpenAI SDK 會忽略未知欄位。
+
+```json
+{
+  "model": "echo",
+  "messages": [{ "role": "user", "content": "你好" }]
+}
+```
+
+## 媒體
+
+| 方法 | 路徑 |
+|------|------|
+| POST | `/v1/images/generations` |
+| POST | `/v1/images/edits` |
+| POST | `/v1/videos` |
+| GET | `/v1/videos/:id` |
+| GET | `/v1/videos/:id/content` |
+| POST | `/v1/audio/speech` |
+| POST | `/v1/audio/transcriptions` |
+| GET | `/v1/media/assets/:id/content` |
+
+將 `OMNI_IMAGE_URL`／`OMNI_TTS_URL`／`OMNI_STT_URL`／`OMNI_VIDEO_URL` 指向 OpenAI 形狀的 worker。未設圖像／TTS／STT worker → **501** `engine_unconfigured`。未設影片 worker 時可能回一段短 H.264 樣本。
+
+圖像／影片／語音需要 **agent** 或 **admin** 金鑰，除非演員是 Admin OTP。
+
+輸出副檔名：`png`／`jpeg`／`mp3`／`wav`／`mp4` 等；閘道會用 ffmpeg 轉換。
+
+## 文件與 assistants
+
+| 方法 | 路徑 |
+|------|------|
+| POST/GET/DELETE | `/v1/documents` · `/v1/documents/:id` |
+| POST | `/v1/assistants` 及相關 OpenAI 形狀路由（受能力旗標限制） |
+
+## 健康
+
+| 方法 | 路徑 |
+|------|------|
+| GET | `/health` |
+| GET | `/ready` | 資料庫 + 文字引擎（PATH 上的 llama-server） |
+
+## 錯誤
+
+JSON：`{ "error": { "message", "type", "code" } }`。
+
+| 代碼 | 常見狀態 |
+|------|----------|
+| `unauthorized` | 401 |
+| `forbidden` | 403 |
+| `model_not_allowed` | 403 |
+| `feature_disabled` | 403／501 |
+| `engine_unconfigured` | 501 |
+| `engine_timeout` | 504 |
+| `rate_limit_exceeded` | 429 |
+| `queue_full`／`queue_draining` | 429／503 |

package/docs/zh/architecture.md

@@ -0,0 +1,44 @@
+# 架構
+
+```text
+用戶端（OpenAI SDK / curl / Open WebUI）
+        │  Authorization: Bearer omni_live_…
+        ▼
+   Express 閘道 :3850
+   · 認證 · 限流 · safe/agent · 佇列 · Admin
+        │
+        ├─ GGUF 文字     → llama-server（OMNI_LLAMA_SERVER / PATH）
+        ├─ safetensors   → vLLM
+        ├─ echo          → 內建協議測試模型
+        ├─ 圖像          → OMNI_IMAGE_URL
+        ├─ TTS / STT     → OMNI_TTS_URL / OMNI_STT_URL
+        └─ 影片          → OMNI_VIDEO_URL（或短 H.264 樣本）
+```
+
+## 行程
+
+| 行程 | 職責 |
+|------|------|
+| `ysk-omni start` | 閘道、Admin SPA、SQLite、目錄、金鑰政策 |
+| `llama-server` | **Load** 後持久 GGUF 對話 |
+| vLLM | safetensors 對話 |
+| 媒體 worker | OpenAI 形狀的 `/v1/images/generations`、`/v1/videos`、`/v1/audio/*` |
+
+閘道不會啟動外部編程 CLI。文字推論是 llama-server、vLLM 或 `echo`。
+
+## 資料
+
+預設主目錄：`~/.ysk-omni`。
+
+| 路徑 | 內容 |
+|------|------|
+| `data/gateway.db` | 金鑰、對話、佇列、審計（Prisma / SQLite） |
+| `models/` | 已拉取權重（GGUF 與 Hub 快照） |
+| `.env` | `ENCRYPTION_KEY`、`PORT`、worker 網址 |
+| `logs/` | 閘道與 PM2 日誌 |
+
+對話內容以 AES-256-GCM 加密儲存。
+
+## Admin
+
+Vite SPA 位於 `/admin/`，生產包 `public/admin/boot.js` 來自 `admin/src/full/app.js`。登入用一次性碼，不是貼上 live 金鑰。

package/docs/zh/catalog.md

@@ -0,0 +1,30 @@
+# 目錄
+
+Admin **目錄**與 CLI 管理本機權重。Pull **不會**在你按該列的 Pull（或執行 `ysk-omni pull`）之前開始下載。
+
+## Hub
+
+Hugging Face 分頁使用官方 Hub REST API（`GET https://huggingface.co/api/models`，Link 標頭游標）。同步會快取下載量最高的 50 個 GGUF id（只寫中繼資料）。
+
+沒有本機 runtime 的列會隱藏。容量以單一單位顯示（MB 或 GB），並在可知時附估計 VRAM。
+
+## 下載佇列
+
+進行中的拉取在專用區塊：百分比、容量、速度、預計完成時間。轉到其他 Admin 分頁不會丟失該區塊。沒有下載任何檔案的失敗拉取不會留下紅字橫幅。
+
+## 本機模型
+
+已拉取的 GGUF 與快照（whisper、diffusion、T2V）列於本機模型。動作：**Load**、**Unload**、**刪除**。亦可輸入 Hub 路徑拉取。
+
+```bash
+ysk-omni catalog --modality image
+ysk-omni catalog search sdxl --modality image
+ysk-omni catalog sync
+ysk-omni pull org/repo:Q4_K_M
+ysk-omni models
+ysk-omni load <id>
+ysk-omni unload <id>
+ysk-omni rm <id>
+```
+
+Load 會為 GGUF 啟動 llama-server。safetensors 文字 id 需要 vLLM。diffusion／whisper／T2V 由媒體 worker 從磁碟使用，不是 llama-server。

package/docs/zh/cli.md

@@ -0,0 +1,180 @@
+# CLI 手冊
+
+指令：`ysk-omni`。短名：`ysko`（不要用 `yo`）。
+
+```bash
+ysk-omni --help
+ysk-omni <command> --help
+```
+
+## 全局旗標
+
+| 旗標 | 說明 |
+|------|------|
+| `--home <path>` | 資料主目錄（預設 `~/.ysk-omni` 或專案根） |
+| `--port <n>` | HTTP 連接埠（預設 **3850**） |
+| `--json` | 支援時輸出機器可讀 JSON |
+| `-V, --version` | 套件版本 |
+
+以下每個命令都接受全局旗標。
+
+## 生命週期
+
+| 命令 | 作用 |
+|------|------|
+| `setup` | 建立資料目錄、`.env`、遷移、種子 admin 金鑰；嘗試 `npm i -g pm2` |
+| `start` | 啟動閘道。`-f, --foreground` · `--pm2` |
+| `stop` | 停止背景閘道 |
+| `restart` | 重啟。`-f, --foreground` · `--pm2` |
+| `status` | 行程與健康 |
+| `migrate` | `prisma migrate deploy` |
+| `seed` | 若缺少則種子 admin 金鑰 |
+| `doctor` | Node、環境、已載入模型、VRAM、建置、執行器、連接埠衝突 |
+| `open` | 列印 API／Admin 網址。`--admin` 只列 Admin |
+| `version` | 套件版本 |
+| `update` | 自我更新。`--check` · `--no-restart` · `--channel auto\|git\|npm-global\|npm-local` |
+
+```bash
+ysk-omni --home ~/.ysk-omni setup
+ysk-omni start --foreground
+ysk-omni start --pm2
+ysk-omni doctor
+ysk-omni update --check
+```
+
+## API 金鑰
+
+`key create` 只列印密鑰 **一次**。
+
+| 命令 | 旗標 |
+|------|------|
+| `key` | 裸指令會建立 **admin** 金鑰（相容）。請用 `key create` |
+| `key create` | `-n <name>` `-r admin\|client` `-m safe\|agent` `--rate-limit <n>` `--models <id,id>` |
+| `key admin` | 等同 `key create -r admin`。`-n <name>` |
+| `key list` | 列出金鑰（不含密鑰） |
+| `key show <id>` | 單一金鑰 |
+| `key update <id>` | `-n` `-r` `-m` `--rate-limit` `--active on\|off` `--models <ids>` |
+| `key revoke <id>` | 撤銷 |
+| `key activate <id>` | 重新啟用 |
+
+`--models` 為逗號分隔可用模型清單。建立時留空＝不限制。見 [API 金鑰](keys.md)。
+
+```bash
+ysk-omni key create -n studio -r client -m agent --models echo,piper/lessac-high
+ysk-omni key update <id> --models echo
+```
+
+## Admin 面板
+
+| 命令 | 作用 |
+|------|------|
+| `admin` / `admin status` | 面板開關狀態 |
+| `admin on` | 啟用（設定庫） |
+| `admin off` | 停用。只能用 `admin on` 重開 |
+| `admin otp` | 一次性登入碼（別名 `admin login-code`）。5 分鐘、單次使用 |
+| `admin sessions` / `admin sessions list` | 有效 OTP 工作階段 |
+| `admin sessions revoke <id>` | id 前綴，或 `all`／`all-expired` |
+
+## 安全設定
+
+| 命令 | 旗標 |
+|------|------|
+| `settings` / `settings get` | 顯示 |
+| `settings set` | `--global-safe on\|off` `--tools none\|readonly` `--max-turns <n>` `--timeout-ms <n>` `--default-model <id>` |
+| `settings preset <name>` | `local` · `prod` · `code` · `read` · `chat` · `long` |
+
+## 目錄與模型
+
+| 命令 | 作用 |
+|------|------|
+| `catalog` | 本機登錄。`--modality text\|image\|video\|tts\|stt` |
+| `catalog search [q]` | Hub 搜尋（有本機 runtime 者）。`--modality` |
+| `catalog sync` | 快取下載量最高的 50 個 GGUF id（只寫中繼資料，不下載） |
+| `show <spec>` | 列出 `org/repo` 或 `org/repo:Q4_K_M` 的 GGUF 量化 |
+| `pull <spec>` | 拉取 GGUF 或記錄 safetensors id |
+| `models` | 列出本機登錄（含 `echo`） |
+| `rm <id>` | 刪除本機登錄列與檔案 |
+| `load <id>` | 將 GGUF 載入 llama-server（或 vLLM） |
+| `unload <id>` | 卸載 |
+
+```bash
+ysk-omni catalog --modality text
+ysk-omni catalog search whisper --modality stt
+ysk-omni catalog sync
+ysk-omni pull Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+ysk-omni load Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+ysk-omni unload Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+ysk-omni rm Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+```
+
+## 執行環境
+
+| 命令 | 作用 |
+|------|------|
+| `runtimes` | 主機作業系統、已安裝／缺失、安裝方案 |
+| `runtimes install <id>` | Homebrew／pip／winget／Docker（`llamacpp`、`ffmpeg`、`mlx` 等） |
+| `runtimes uninstall <id>` | 依方案解除安裝（Admin 會先確認） |
+
+## 對話佇列
+
+裸 `queue`＝統計。
+
+| 命令 | 作用 |
+|------|------|
+| `queue stats` | 深度與數量 |
+| `queue policy`／`policy get` | 顯示政策 |
+| `queue policy set` | 更新政策欄位 |
+| `queue policy preset <name>` | 具名預設 |
+| `queue pause`／`resume` | 工人認領 |
+| `queue drain`／`undrain` | 拒絕／允許新入隊 |
+| `queue jobs` | 列出工作 |
+| `queue job <id>` | 單一工作 |
+| `queue cancel <id>` | 取消 |
+| `queue requeue <id>` | 重新入隊 |
+| `queue priority <id> <n>` | 設定優先級 |
+| `queue purge-dead` | 刪除失敗／已取消。`-y, --yes` |
+
+## DDoS 與黑名單
+
+裸 `ddos`＝摘要。
+
+| 命令 | 旗標 |
+|------|------|
+| `ddos policy`／`policy get` | 顯示 |
+| `ddos policy set` | `--auto-ban` `--rate-limit-max` `--rate-limit-ip-max` `--chat-burst-max` `--failed-auth-threshold` `--rate-hit-threshold` `--max-concurrent-per-ip` `--velocity-max-requests` `--proxy-trust-hops` `--proxy-ip-source auto\|cloudflare\|nginx\|x-forwarded-for\|socket` |
+| `ddos policy preset <name>` | `relaxed` · `balanced` · `strict` |
+| `ddos policy reset` | 還原環境變數預設 |
+| `ddos ban <ip>` | `--ttl <seconds>` `--reason <text>` |
+| `ddos unban <ip>` | 自黑名單移除 |
+| `ddos blacklist` | 列出有效項目 |
+
+## 文件、對話、審計
+
+| 命令 | 作用 |
+|------|------|
+| `docs`／`docs list` | `--limit` `--offset` |
+| `docs show <id>` | 單一文件 |
+| `docs delete <id>` | 刪除 |
+| `chats`／`chats list` | 已儲存對話請求 |
+| `chats show <id>` | 單一請求 |
+| `conversations list` | 操場執行緒 |
+| `conversations delete <id>` | 刪除執行緒 |
+| `audit`／`audit list` | 審計日誌 |
+| `stats` | 儀表板式資料庫摘要 |
+
+## API 能力旗標
+
+與 Admin → API 能力對齊。
+
+| 命令 | 作用 |
+|------|------|
+| `api features`／`api features get` | 顯示旗標 |
+| `api features set` | `--openai-chat` `--openai-responses` `--anthropic-messages` `--tools` `--vision` `--images-api` `--audio-api` `--video-api` `--files-openai-alias` `--strict-sampling` …（各為 `on\|off`） |
+| `api features preset <name>` | `open` · `locked` · `dev` |
+
+## 日誌
+
+| 命令 | 旗標 |
+|------|------|
+| `logs`／`logs show` | `-n, --lines <n>`（預設 40） |
+| `logs clear` | 清空 PM2 與 ysk-omni 日誌檔 |

package/docs/zh/configuration.md

@@ -0,0 +1,52 @@
+# 設定
+
+`ysk-omni setup` 會寫入 `~/.ysk-omni/.env`。不要提交 `.env`。見 [`.env.example`](../../.env.example)。
+
+預設 `NODE_ENV` 為 **production**。只有本機開發才用 `development`。
+
+## 核心
+
+| 變數 | 說明 |
+|------|------|
+| `PORT` | 預設 **3850** |
+| `HOST` | 監聽位址（`0.0.0.0`） |
+| `DATABASE_URL` | SQLite，例如 `file:../data/gateway.db`（相對 `prisma/`） |
+| `ENCRYPTION_KEY` | 32-byte 金鑰：`openssl rand -base64 32` |
+| `ADMIN_BOOTSTRAP_KEY` | 可選的第一把 admin 密鑰 |
+| `OMNI_HOME` | 資料主目錄 |
+| `STORAGE_DIR` | 加密檔案（預設 `./storage`） |
+| `CORS_ORIGINS` | 逗號分隔 origins（改 `PORT` 時請一併更新） |
+| `LOG_LEVEL` | `fatal` … `trace` |
+| `BODY_LIMIT`／`UPLOAD_MAX_BYTES`／`DOCUMENT_DB_MAX_BYTES` | 大小上限 |
+| `ADMIN_PANEL_ENABLED` | 硬關 `/admin`（需重啟）。運行時：`ysk-omni admin on\|off` |
+| `PM2_ADMIN_ENABLED` | 允許 Admin 控制 PM2 |
+
+## 引擎與 worker
+
+| 變數 | 說明 |
+|------|------|
+| `OMNI_DEFAULT_MODEL` | 用戶端省略 `model` 時使用 |
+| `OMNI_LLAMA_SERVER` | `llama-server` 路徑 |
+| `OMNI_LLAMA_N_GPU_LAYERS` | 預設 `-1`（全部層）。`0`＝CPU |
+| `OMNI_VLLM` | vLLM 二進位或 Python 直譯器 |
+| `OMNI_VLLM_MODULE` | `1`＝`python -m vllm.entrypoints.openai.api_server` |
+| `OMNI_IMAGE_URL`／`OMNI_TTS_URL`／`OMNI_STT_URL`／`OMNI_VIDEO_URL` | OpenAI 形狀 worker |
+| `OMNI_MAX_CONCURRENT` | 進行中的對話工作（亦種子佇列併發） |
+| `OMNI_TIMEOUT_MS` | 預設逾時 |
+| `OMNI_SAFE_MODE` | 強制所有金鑰進入 safe |
+| `OMNI_SAFE_MAX_TURNS`／`OMNI_SAFE_TIMEOUT_MS` | safe 預設 |
+| `OMNI_ALWAYS_APPROVE` | 只對 agent；safe 一律關閉 |
+| `OMNI_DEFAULT_CWD`／`OMNI_CWD_ALLOWLIST` | 工作區路徑（空白 cwd＝`<STORAGE_DIR>/workspaces/default`） |
+
+## 限額與代理
+
+| 變數 | 說明 |
+|------|------|
+| `RATE_LIMIT_WINDOW_MS`／`RATE_LIMIT_MAX`／`RATE_LIMIT_IP_MAX` | 速率限制 |
+| `CHAT_BURST_MAX` | 每把金鑰短窗突發 |
+| `BLOCK_FAILED_AUTH_*`／`BLOCK_DURATION_MS` | 認證失敗 IP 封鎖 |
+| `TRUST_PROXY` | 層數：`0`／`1`／`2`…（`true`→1，`false`→0） |
+| `PROXY_IP_SOURCE` | `auto` · `cloudflare` · `nginx` · `x-forwarded-for` · `socket` |
+| `QUEUE_BACKEND` | `sqlite`（預設）。`redis`／`kafka` 預留 |
+
+資料庫內的 DDoS 政策在首次儲存後會覆寫環境變數。

package/docs/zh/development.md

@@ -0,0 +1,49 @@
+# 開發
+
+## 由原始碼
+
+```bash
+git clone https://github.com/yanshekki/ysk-omni.git
+cd ysk-omni
+npm install
+npx prisma generate
+npx tsc -p tsconfig.json
+npm run build:admin
+ysk-omni --home ~/.ysk-omni start --foreground
+```
+
+## Admin
+
+| 腳本 | 作用 |
+|------|------|
+| `npm run build:admin` | Vite → `public/admin/boot.js` |
+| `npm run dev:admin` | Vite :5174，API 代理至 :3850 |
+| `npm run typecheck:admin` | Admin TypeScript |
+
+生產入口是 `admin/src/full/app.js`。模組化 `admin/src/pages/*` 供測試；在功能對齊完成前不要把頁面切離 `full/app.js`。
+
+介面文案：英文 + 香港書面語，見 `admin/src/full/i18n.js`。
+
+## 測試
+
+見 [tests/README.md](../../tests/README.md)。
+
+```bash
+npm test
+npm run test:admin
+npm run test:api
+npm run test:cli
+npm run test:registry
+```
+
+可選即時媒體：`OMNI_LIVE_TINY=1` 或 `OMNI_LIVE_BEST=1`，並設 `OMNI_LIVE_KEY`。
+
+## 目錄
+
+| 路徑 | 職責 |
+|------|------|
+| `src/` | 閘道、CLI |
+| `admin/src/full/` | 生產 Admin SPA |
+| `prisma/` | SQLite schema 與遷移 |
+| `scripts/tiny-media-worker.py` | 本機圖像／TTS／STT／影片 worker |
+| `docs/en` · `docs/zh` | 產品文件 |

package/docs/zh/getting-started.md

@@ -0,0 +1,62 @@
+# 快速開始
+
+## 前置要求
+
+- Node.js 20 或以上
+- 文字 GGUF：`PATH` 上的 `llama-server`，或 `OMNI_LLAMA_SERVER`
+- 文字 safetensors：`vLLM`（`OMNI_VLLM`）
+- 圖像／語音／影片：OpenAI 形狀的 HTTP worker（見[媒體](media.md)）
+
+## 安裝並啟動
+
+```bash
+npm install -g ysk-omni
+
+ysk-omni doctor
+ysk-omni setup          # 資料目錄、.env、遷移、種子 admin 金鑰
+ysk-omni start          # http://127.0.0.1:3850
+ysk-omni start --pm2    # 同一行程交 PM2 管理
+```
+
+資料主目錄預設 `~/.ysk-omni`。可用 `--home` 或 `OMNI_HOME` 覆寫。
+
+## Admin 登入
+
+Admin 不會在瀏覽器長期保存 API 金鑰。請產生一次性登入碼：
+
+```bash
+ysk-omni admin otp
+```
+
+開啟 `http://127.0.0.1:3850/admin/` 並輸入該碼（五分鐘、單次使用）。
+
+## 第一個模型
+
+```bash
+ysk-omni catalog search Qwen --modality text
+ysk-omni pull Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+ysk-omni load Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q2_K
+```
+
+尚未載入引擎時，可用 `model=echo` 做協議測試。
+
+## 第一次 API 呼叫
+
+```bash
+curl -sS http://127.0.0.1:3850/v1/models \
+  -H "Authorization: Bearer omni_live_…"
+
+curl -sS http://127.0.0.1:3850/v1/chat/completions \
+  -H "Authorization: Bearer omni_live_…" \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"echo","messages":[{"role":"user","content":"你好"}]}'
+```
+
+`GET /v1/models` 列出此金鑰可用的 id。用 `--models` 限制金鑰（見 [API 金鑰](keys.md)）。
+
+列印網址：
+
+```bash
+ysk-omni open
+ysk-omni open --admin
+```

package/docs/zh/keys.md

@@ -0,0 +1,30 @@
+# API 金鑰
+
+金鑰格式為 `omni_live_…`。在 Admin 或 CLI 建立。密鑰只顯示一次。
+
+## 角色與模式
+
+| 欄位 | 值 |
+|------|------|
+| 角色 | `admin` · `client` |
+| 模式 | `safe`（對外）· `agent`（完整媒體與工具） |
+| 速率 | 每分鐘請求數 |
+| IP 白名單 | 每行一個 IP 或 CIDR。留空＝不限制 IP |
+| 可用模型 | 多選 + 額外 id。留空＝全部模型 |
+
+Admin OTP 工作階段對模型沒有限制（空白清單）。
+
+## 可用模型清單
+
+以 JSON 存在金鑰上。完整 id 比對（`echo`、`piper/lessac-high`、`org/repo:Q4_K_M`）。
+
+- 空白清單：不限制
+- 非空：對話、圖像、影片、語音、轉錄、`GET /v1/models` 只准清單內 id
+- 不在清單 → **403** `model_not_allowed`
+
+```bash
+ysk-omni key create -n app -r client -m safe --models echo,piper/lessac-high
+ysk-omni key update <id> --models echo
+```
+
+用戶以 `GET /v1/models` 查詢可用清單。