调整部分页面内容与结构；增强章节目录生成组件报错提示

Author: srsng

docs/.vitepress/config.mts

@@ -26,9 +26,9 @@ export default defineConfig({
     outline: [2, 4],
     nav: [
       { text: "主页", link: "/" },
-      // { text: "使用文档", link: Chapters.xrobot_guide_device },
+      { text: "开发文档", link: Chapters.xrobot_platform },
       { text: "API参考", link: Chapters.xrobot_api },
-      { text: "最佳实践： ESP32 接入", link: Chapters.xrobot_platform_esp32 },
+      { text: "最佳实践", link: Chapters.xrobot_platform_esp32 },
       { text: "FAQ", link: Chapters.xrobot_faq },
     ],
     sidebar: sidebarItems,

docs/.vitepress/theme/components/ChapterContents.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { useData } from "vitepress";
 import {
   ChapterItems,
   Chapters,
@@ -18,25 +19,37 @@ let tocs: { link: string; text: string }[][] = [];
 
 // console.log("chapter_root", chapter_root);
 // console.log("ChapterItems[chapter_root]", ChapterItems[chapter_root]);
-
-ChapterItems[chapter_root]?.forEach((subchapter) => {
-  const t = subchapter.items?.filter((item) => {
-    return item.link !== chapter_root && !item.goback;
+const items = ChapterItems[chapter_root];
+if (!items) {
+  const { page } = useData();
+  console.warn(
+    "Error at gen ChapterContents, chapter_root:",
+    chapter_root,
+    "filePath:",
+    page.value.filePath,
+    "title:",
+    page.value.title
+  );
+} else {
+  items.forEach((subchapter) => {
+    const t = subchapter.items?.filter((item) => {
+      return item.link !== chapter_root && !item.goback;
+    });
+    if (t) {
+      tocs.push(t);
+      chapter_name.push(subchapter.text);
+    }
   });
-  if (t) {
-    tocs.push(t);
-    chapter_name.push(subchapter.text);
-  }
-});
+}
 
 // console.log("chapter_name:", chapter_name);
 // console.log("tocs:", tocs);
 </script>
 
 <template>
-  <h1 v-if="root">目录</h1>
+  <h2 v-if="root">目录</h2>
   <div v-for="(subchapter, index) in tocs">
-    <h2>{{ chapter_name[index] }}</h2>
+    <h3>{{ chapter_name[index] }}</h3>
     <div v-if="subchapter.length === 0"><span>暂无内容</span></div>
     <ol v-else>
       <li v-for="(item, index2) in subchapter" :key="item.link">

docs/.vitepress/theme/constrants/route.ts

@@ -23,16 +23,16 @@ export enum Chapters {
   // api
   xrobot_api = "/xrobot/api/",
   xrobot_api_server = "/xrobot/api/server/",
-  xrobot_api_client = "/xrobot/api/client/",
+  // xrobot_api_client = "/xrobot/api/client/",
   xrobot_api_protocol = "/xrobot/api/protocol/",
   // platform
   xrobot_platform = "/xrobot/platform/",
   xrobot_platform_esp32 = "/xrobot/platform/esp32/",
   xrobot_platform_others = "/xrobot/platform/others/",
   xrobot_platform_others_mp = "/xrobot/platform/others/mini-program/",
-  xrobot_platform_others_device = "/xrobot/platform/others/device/",
   xrobot_platform_others_console = "/xrobot/platform/others/console/",
-  xrobot_platform_others_net_config = "/xrobot/platform/others/net-config/",
+  xrobot_platform_others_device = "/xrobot/platform/others/device/",
+  xrobot_platform_others_device_net_config = "/xrobot/platform/others/net-config/",
   // faq
   xrobot_faq = "/xrobot/faq/",
 }
@@ -79,7 +79,7 @@ export function apply_prefix(item: ChapterItem, prefix: Chapters) {
 
 export const items_xrobot_api_server = [
   {
-    text: "服务端API参考",
+    text: "平台接入API",
     collapsed: true,
     link: Chapters.xrobot_api_server,
     items: [
@@ -91,18 +91,18 @@ export const items_xrobot_api_server = [
   },
 ];
 
-export const items_xrobot_api_client = [
-  {
-    text: "客户端API参考",
-    collapsed: true,
-    link: Chapters.xrobot_api_client,
-    items: [].map((item) => apply_prefix(item, Chapters.xrobot_api_client)),
-  },
-];
+// export const items_xrobot_api_client = [
+//   {
+//     text: "设备接入协议",
+//     collapsed: true,
+//     link: Chapters.xrobot_api_client,
+//     items: [].map((item) => apply_prefix(item, Chapters.xrobot_api_client)),
+//   },
+// ];
 
 export const items_xrobot_api_protocol = [
   {
-    text: "WebSocket API参考",
+    text: "设备接入协议",
     collapsed: true,
     link: Chapters.xrobot_api_protocol,
     items: [
@@ -120,7 +120,7 @@ export const items_xrobot_api = [
     link: Chapters.xrobot_api,
     items: [
       ...items_xrobot_api_server,
-      ...items_xrobot_api_client,
+      // ...items_xrobot_api_client,
       ...items_xrobot_api_protocol,
     ],
   },
@@ -140,14 +140,31 @@ export const items_xrobot_platform_mp = [
   },
 ];
 
+const items_xrobot_platform_net_config = [
+  {
+    text: "配网",
+    link: Chapters.xrobot_platform_others_device_net_config,
+    collapsed: true,
+    items: [
+      { text: "通过微信小程序", link: "mp" },
+      { text: "通过浏览器", link: "browser" },
+    ].map((item) =>
+      apply_prefix(item, Chapters.xrobot_platform_others_device_net_config)
+    ),
+  },
+];
+
 export const items_xrobot_platform_device = [
   {
     text: "设备配置与使用",
     link: Chapters.xrobot_platform_others_device,
     collapsed: true,
-    items: [{ text: "使用指南", link: "device-intro" }].map((item) =>
-      apply_prefix(item, Chapters.xrobot_platform_others_device)
-    ),
+    items: [
+      ...[{ text: "设备基本配置流程说明", link: "device-intro" }].map((item) =>
+        apply_prefix(item, Chapters.xrobot_platform_others_device)
+      ),
+      ...items_xrobot_platform_net_config,
+    ],
   },
 ];
 
@@ -157,7 +174,7 @@ const items_xrobot_platform_console = [
     link: Chapters.xrobot_platform_others_console,
     collapsed: true,
     items: [
-      { text: "基本介绍", link: "intro" },
+      // { text: "基本介绍", link: "intro" },
       { text: "智能体连接指南", link: "device-connection" },
       { text: "设备绑定", link: "device-bind" },
     ].map((item) =>
@@ -166,17 +183,6 @@ const items_xrobot_platform_console = [
   },
 ];
 
-const items_xrobot_platform_net_config = [
-  {
-    text: "配网",
-    link: Chapters.xrobot_platform_others_net_config,
-    collapsed: true,
-    items: [{ text: "通过微信小程序", link: "mp" }].map((item) =>
-      apply_prefix(item, Chapters.xrobot_platform_others_net_config)
-    ),
-  },
-];
-
 export const items_xrobot_guide = [];
 
 const items_xrobot_platform_esp32 = [
@@ -198,10 +204,9 @@ const items_xrobot_platform_others = [
     link: Chapters.xrobot_platform,
     collapsed: true,
     items: [
-      ...items_xrobot_platform_mp,
       ...items_xrobot_platform_device,
+      ...items_xrobot_platform_mp,
       ...items_xrobot_platform_console,
-      ...items_xrobot_platform_net_config,
     ],
   },
 ];
@@ -258,10 +263,10 @@ export const ChapterItems: Record<Chapters, ChapterItem[]> = {
     gobackItem(Chapters.xrobot_api),
     ...items_xrobot_api_server,
   ],
-  [Chapters.xrobot_api_client]: [
-    gobackItem(Chapters.xrobot_api),
-    ...items_xrobot_api_client,
-  ],
+  // [Chapters.xrobot_api_client]: [
+  //   gobackItem(Chapters.xrobot_api),
+  //   ...items_xrobot_api_client,
+  // ],
   [Chapters.xrobot_api_protocol]: [
     gobackItem(Chapters.xrobot_api),
     ...items_xrobot_api_protocol,
@@ -295,7 +300,7 @@ export const ChapterItems: Record<Chapters, ChapterItem[]> = {
     gobackItem(Chapters.xrobot_platform_others),
     ...items_xrobot_platform_console,
   ],
-  [Chapters.xrobot_platform_others_net_config]: [
+  [Chapters.xrobot_platform_others_device_net_config]: [
     gobackItem(Chapters.xrobot_platform_others),
     ...items_xrobot_platform_net_config,
   ],

docs/xrobot/api/server/agent.md

@@ -10,7 +10,7 @@ title: 智能体API
 请求：
 POST https://xrobo.qiniuapi.com/xiaozhi/agent
 Content-Type: application/json
-authorization Bearer 4fxxxxxxxxxxxxxxxxxxxxxxx
+authorization Bearer <token>
 {
 "agentName": "吞吞吐吐" 【用户随意命名，有参数检查】
 }
@@ -23,8 +23,6 @@ authorization Bearer 4fxxxxxxxxxxxxxxxxxxxxxxx
 
 ```
 
-
-
 ## 2. 获取智能体列表
 
 ```
@@ -66,7 +64,7 @@ authorization Bearer 4fxxxxxxxxxxxxxxxxxxxxxxx
 请求：
 PUT https://xrobo.qiniu.com/xiaozhi/agent/3e0535877a0b46ca8555d73ec43a4211
 Content-Type: application/json
-authorization Bearer 4fxxxxxxxxxxxxxxxxxxxxxxx
+authorization Bearer <token>
 {
 agentCode: "AGT*1752818539532"
 agentName: "ggg"
@@ -102,15 +100,15 @@ vllmModelId: "VLLM_ChatGLMVLLM"
 请求：
 DELETE https://xrobo.qiniu.com/xiaozhi/agent/3e0535877a0b46ca8555d73ec43a4211
 Content-Type: application/json
-authorization Bearer 4fxxxxxxxxxxxxxxxxxxxxxxx
+authorization Bearer <token>
 {
 
 }
 响应：
 {
-"code":0,
-"msg":"success",
-"data":null
+    "code":0,
+    "msg":"success",
+    "data":null
 }
 
-```
+```

docs/xrobot/api/server/imgs/user/captcha-eg.png

@@ -4,62 +4,73 @@ title: 用户API
 
 ## 1. 用户注册
 
-```plain
 请求：
+
+```
 POST https://xrobo.qiniu.com/xiaozhi/user/register
 Content-Type: application/json
+```
+
+```json
 {
 "username": "",
 "password": "",
-"captcha": "etnjx", 【下面的方法获取】
-"mobileCaptcha": "", 【否】
-"captchaId": "" 【uuid：cfa94872-48b6-425b-8e6a-17b912b6b6f4"】
+"captcha": "",
+"mobileCaptcha": "",
+"captchaId": ""
 }
+```
+
 响应：
+
+```json
 {
-"code": 0,
-"msg": "",
-"data": {}
+    "code": 0,
+    "msg": "",
+    "data": {}
 }
 
 ```
 
-```
-// 如何获取 captcha
-GET https://xrobo.qiniu.com/xiaozhi/user/captcha?uuid=cfa94872-48b6-425b-8e6a-17b912b6b6f4 [uuid 随机生成]
-```
+### 获取 captcha
+
+GET <https://xrobo.qiniu.com/xiaozhi/user/captcha?uuid=cfa94872-48b6-425b-8e6a-17b912b6b6f4>
+
+uuid 随机生成
 
 响应：
-<img src="../device/imgs/device-bind/4.captcha-eg.png" class="img-center">
 
-## 2. 用户登录
+<img src="./imgs/user/captcha-eg.png" class="img-center" alt="captcha-eg">
 
-```
+## 2. 用户登录
 
 请求：
-POST https://xrobo.qiniuapi.com/xiaozhi/user/login
+
+```
+POST <https://xrobo.qiniuapi.com/xiaozhi/user/login>
 Content-Type: application/json
+```
+
+```json
+
 {
-areaCode: "+86"
-captcha: "xxxxx"
-captchaId: "d4224c42-a0a2-4e38-87a5-edc3ad03c014"
-mobile: ""
-password: "xxxx"
-username: "xxx"
+    "areaCode": "+86",
+    "captcha": "xxxxx",
+    "captchaId": "d4224c42-a0a2-4e38-87a5-edc3ad03c014",
+    "mobile": "",
+    "password": "xxxx",
+    "username": "xxx",
 }
 响应：
 {
-"code": 0,
-"msg": "success",
-"data": {
-"token": "4fxxxxxxxxxxxxxxxxxxxxxxx", 【后续创建 agent 等操作，需要带上 token】
-"expire": 43200,
-"clientHash": "xxxxxx"
-}
+    "code": 0,
+    "msg": "success",
+    "data": {
+        "token": "4fxxxxxxxxxxxxxxxxxxxxxxx",
+        "expire": 43200,
+        "clientHash": "xxxxxx"
+    }
 }
-
 ```
 
-## 3. 声音复刻
-
-见 [声音复刻](./voice-clone.md)
+返回的`token`为后续大多数api的凭证

docs/xrobot/api/server/user.md

@@ -4,4 +4,10 @@ import { Chapters } from "../../../../.vitepress/theme/constrants/route";
 const chapter_root = Chapters.xrobot_platform_others_console;
 </script>
 
+## 基本介绍
+
+七牛云灵芯平台，是灵矽平台 web 端的智能管理后台，集智能体管理、音色复刻等功能于一体。
+
+链接：<https://xrobo.qiniu.com/>
+
 <ChapterContents :chapter=chapter_root />