Splite docs to developer and user and bring profile link back

2026-08-07 11:13:45 +08:00
parent 95e04d8c94
commit 7575afaeee
12 changed files with 103 additions and 42 deletions
--- a/docs-developer/docs.json
+++ b/docs-developer/docs.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "AI 视频助手 · 开发者文档",
+  "theme": "mint",
+  "colors": {
+    "primary": "#1b2741",
+    "light": "#3a4a6b",
+    "dark": "#0c1426"
+  },
+  "logo": {
+    "light": "/logo-light.svg",
+    "dark": "/logo-dark.svg",
+    "href": "/"
+  },
+  "appearance": {
+    "default": "dark"
+  },
+  "fonts": {
+    "family": "Inter",
+    "weight": 400,
+    "heading": {
+      "family": "Cormorant Garamond",
+      "weight": 300
+    }
+  },
+  "icons": {
+    "library": "lucide"
+  },
+  "background": {
+    "decoration": "gradient",
+    "color": {
+      "light": "#f3f5fb",
+      "dark": "#070b16"
+    }
+  },
+  "styling": {
+    "eyebrows": "breadcrumbs",
+    "codeblocks": {
+      "theme": {
+        "light": "github-light",
+        "dark": "github-dark"
+      }
+    }
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "开始与对接",
+        "pages": ["index", "integrations"]
+      }
+    ]
+  }
+}
--- a/docs-developer/index.mdx
+++ b/docs-developer/index.mdx
@@ -0,0 +1,45 @@
+---
+title: 快速开始
+description: 用 Docker 启动本地开发环境，并创建第一个可语音预览的助手。
+icon: rocket
+---
+
+# 快速开始
+
+## 1. 启动服务
+
+在项目根目录执行：
+
+```bash
+docker compose up -d
+make db-seed
+```
+
+首次启动会构建后端镜像。启动后访问：
+
+- 前端：`http://localhost:3030`
+- 后端健康检查：`http://localhost:8000/health`
+- 后端接口文档：`http://localhost:8000/docs`
+
+## 2. 配置模型资源
+
+进入「组件库 / 模型资源」，选择协议类型并填写连接信息。OpenAI 兼容服务通常需要：
+
+- `values.modelId`：模型标识
+- `values.apiUrl`：服务地址
+- `secrets.apiKey`：访问密钥
+
+保存前可使用“测试连接”确认可用性。
+
+## 3. 创建助手
+
+进入「创建助手」，绑定需要的模型资源：
+
+- **pipeline**：绑定 LLM、ASR、TTS，适合常规语音对话。
+- **realtime**：绑定 Realtime 模型，适合端到端语音交互。
+
+保存后，从助手详情页打开语音预览即可测试。
+
+<Note>
+浏览器麦克风仅在 localhost 或 HTTPS 下可用。局域网、远程环境请按仓库中的 `deploy/README.md` 配置 HTTPS 与 TURN。
+</Note>
--- a/docs-developer/integrations.mdx
+++ b/docs-developer/integrations.mdx
@@ -0,0 +1,59 @@
+---
+title: 对接说明
+description: 模型服务、外部 Agent 与实时语音通道的接入方式。
+icon: plug
+---
+
+# 对接说明
+
+## 模型服务
+
+优先通过「组件库 / 模型资源」接入。接口定义会动态给出表单字段，凭证写入 `secrets`，普通参数写入 `values`。
+
+| 场景 | 推荐接口类型 |
+| --- | --- |
+| 通用大模型、转写、合成、向量 | `openai-llm`、`openai-asr`、`openai-tts`、`openai-embedding` |
+| 端到端实时语音 | `stepfun-realtime` 或 `qwen-audio-realtime` |
+| 讯飞语音 | `xfyun-asr`、`xfyun-tts`、`xfyun-super-tts` |
+
+讯飞接入需要将 `appId`、`apiKey`、`apiSecret` 写入 `secrets`，WebSocket 地址及音色等参数写入 `values`。
+
+### Qwen-Audio Realtime
+
+在「组件库 / 模型资源」中新建 `Alibaba Cloud Qwen-Audio Realtime` 资源：
+
+- WebSocket URL 必须包含百炼业务空间 ID，例如 `wss://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`。
+- API Key 填写该业务空间可用的百炼密钥。
+- MVP 支持 `server_vad` 与 `smart_turn`；前者可以调整 VAD 阈值和静音时长。
+- 当前模型固定使用 16 kHz 单声道 PCM 输入、24 kHz 单声道 PCM 输出，管线会自动匹配采样率。
+
+保存前可使用「测试连接」验证鉴权、地域、业务空间 ID 和模型是否匹配。
+
+## 外部 Agent
+
+创建助手时选择 Dify、FastGPT 或 OpenCode：
+
+- Dify：填写服务地址和 API Key。
+- FastGPT：额外填写应用 ID。
+- OpenCode：填写服务地址、API Key 和可选提示词。
+
+外部 Agent 的上下文、知识库和工具由对方服务处理。
+
+## 实时语音通道
+
+| 通道 | 地址 | 适用场景 |
+| --- | --- | --- |
+| WebRTC 信令 | `ws(s)://<host>/ws/voice` | 浏览器低延迟语音与视频输入。 |
+| 裸音频 WebSocket | `ws(s)://<host>/ws/stream` | 服务端、话务网关或自定义客户端。 |
+
+两个通道均使用管理员登录 Cookie 鉴权。推荐仅传 `assistant_id`，让服务端解析模型密钥；`inline_config` 仅用于调试。
+
+### WebSocket 音频流启动
+
+连接 `/ws/stream` 后，先发送一条文本 JSON，再发送二进制音频帧：
+
+```json
+{"assistant_id":"asst_xxx"}
+```
+
+WebRTC 在公网环境通常需要 TURN。设置 `STUN_URL`、`TURN_URLS` 和 `TURN_SECRET` 后，可通过 `GET /api/webrtc/ice-servers` 获取浏览器 ICE 配置。远程部署建议让 `STUN_URL` 指向同机 coturn，避免等待不可达的公共 STUN。
--- a/docs-developer/logo-dark.svg
+++ b/docs-developer/logo-dark.svg
@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 196 48" fill="none">
+  <defs>
+    <radialGradient id="sky" cx="0" cy="0" r="1" gradientTransform="matrix(31 0 0 31 14 10)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#5F86B8" stop-opacity=".75"/>
+      <stop offset="1" stop-color="#5F86B8" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="lavender" cx="0" cy="0" r="1" gradientTransform="matrix(28 0 0 28 38 39)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#8A78AD" stop-opacity=".68"/>
+      <stop offset="1" stop-color="#8A78AD" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <circle cx="24" cy="24" r="24" fill="#E8EDF9"/>
+  <circle cx="24" cy="24" r="24" fill="url(#sky)"/>
+  <circle cx="24" cy="24" r="24" fill="url(#lavender)"/>
+  <rect x="14" y="17.5" width="14" height="13" rx="2.25" stroke="#0C1426" stroke-width="2.5"/>
+  <path d="m28 21.25 7-4v13.5l-7-4z" stroke="#0C1426" stroke-width="2.5" stroke-linejoin="round"/>
+  <text x="61" y="31" fill="#E8EDF9" font-family="Cormorant Garamond, serif" font-size="24" font-weight="400">AI视频助手</text>
+</svg>
--- a/docs-developer/logo-light.svg
+++ b/docs-developer/logo-light.svg
@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 196 48" fill="none">
+  <defs>
+    <radialGradient id="sky" cx="0" cy="0" r="1" gradientTransform="matrix(31 0 0 31 14 10)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#A8C8E8" stop-opacity=".8"/>
+      <stop offset="1" stop-color="#A8C8E8" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="lavender" cx="0" cy="0" r="1" gradientTransform="matrix(28 0 0 28 38 39)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#C8B8E0" stop-opacity=".72"/>
+      <stop offset="1" stop-color="#C8B8E0" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <circle cx="24" cy="24" r="24" fill="#E8EDF9"/>
+  <circle cx="24" cy="24" r="24" fill="url(#sky)"/>
+  <circle cx="24" cy="24" r="24" fill="url(#lavender)"/>
+  <rect x="14" y="17.5" width="14" height="13" rx="2.25" stroke="#0C1426" stroke-width="2.5"/>
+  <path d="m28 21.25 7-4v13.5l-7-4z" stroke="#0C1426" stroke-width="2.5" stroke-linejoin="round"/>
+  <text x="61" y="31" fill="#0F1B33" font-family="Cormorant Garamond, serif" font-size="24" font-weight="400">AI视频助手</text>
+</svg>