update: new docs

NapNeko · Nov 24, 2024 · 5c7106e · 5c7106e
1 parent 16f0742
commit 5c7106e
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 121 deletions.
diff --git a/package.json b/package.json
@@ -12,6 +12,8 @@
     "vitepress": "^1.3.4"
   },
   "devDependencies": {
-    "markdown-it-mathjax3": "^4.3.2"
+    "markdown-it-mathjax3": "^4.3.2",
+    "mermaid": "^11.4.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
   }
 }
diff --git a/src/.vitepress/config/index.ts b/src/.vitepress/config/index.ts
@@ -1,10 +1,18 @@
 import { defineConfig } from 'vitepress'
 import { shared } from './shared'
 import { zh } from './zh'
+import { withMermaid } from "vitepress-plugin-mermaid";
 
-export default defineConfig({
+export default withMermaid(defineConfig({
   ...shared,
   locales: {
     root: { label: '简体中文', ...zh }
+  },
+  mermaid: {
+    // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options
+  },
+  // optionally set additional config for plugin itself with MermaidPluginConfig
+  mermaidPlugin: {
+    class: "mermaid my-class", // set additional css classes for parent container 
   }
-})
+}));
diff --git a/src/config/basic.md b/src/config/basic.md
@@ -32,103 +32,22 @@ NapCat 的目录保存了配置文件、日志和缓存等信息。
 }
 ```
 
-访问 `/webui/`，然后进行以下操作：
+访问 `http://ip:port/webui/`，然后进行以下操作：
 
 1. 进入 QQ 登录，点击 `QRCode` 进行二维码登录。
 
-2. 登录成功后，即可修改配置。
+2. 登录成功后，即可进入网络配置。
 
 3. 配置完成后，点击保存，重启即可生效。
 
-## 用文件配置 OneBot11 设置
+### 进入 网络配置 添加配置
+此时需要理解
 
-和上面一样，**重启登录后配置才能生效**。
-
-启动登录 NapCat 后，打开 NapCat 的 `config` 目录，找到名为 `onebot11_<你的QQ号>.json` 的文件，如 `onebot11_1234567.json`。
-
-### 配置 HTTP 服务
-
-HTTP 服务的配置主要有两方面：一方面是 HTTP 监听端口（应当由你的应用端来调用），另一方面是 HTTP 上报地址（由 NapCat 来调用你的应用端）。
-
-#### HTTP 监听端口
-
-例如，配置的端口号为 `3000`，那么 API 地址为 `http://localhost:3000`。
-
-#### HTTP 上报地址
-
-::: warning
-上报地址必须是 `http://` 开头
-:::
-
-当 NapCat 收到消息等事件时，会以 `POST` 请求的方式将事件上报到此地址。
-
-### 配置 WebSocket 服务
-
-OneBot 11 标准中，对“正向 WS”“反向 WS”的定义较为模糊，这里明确如下：正向指**接受**应用端的 WS 连接；反向指 NapCat 主动连接应用端监听的反向 WS 地址。
-
-#### 正向 WS 配置
-
-例如，配置的端口号为 `3001`，那么需要在应用端配置的 WS 地址为 `ws://localhost:3001`。
-
-#### 反向 WS 配置
-
-例如，在 NoneBot2 配置 OneBot 的端口为 `8080`，路径为 `/onebot/v11/ws`，那么配置的反向 WS 地址为  `ws://localhost:8080/onebot/v11/ws`。
-
-### 配置内容参数解释
-请注意下面的配置可能并不适用新版本 可以前往新版本webui网络配置修改
-
-```json5
-{
-  "http": {
-    // 是否启用http服务, true为启动，false为禁用
-    "enable": false,
-    // HTTP服务监听的 ip 地址，为空则监听所有地址
-    "host": "",
-    // http服务端口
-    "port": 3000,
-    // http上报密钥，可为空
-    "secret": "",
-    // 是否启用http心跳
-    "enableHeart": false,
-    // 是否启用http上报服务
-    "enablePost": false,
-    // http上报地址, 如["http://127.0.0.1:8080/onebot/v11/http"]
-    "postUrls": []
-  },
-  "ws": {
-    // 是否启用正向websocket服务
-    "enable": false,
-    // 正向websocket服务监听的 ip 地址，为空则监听所有地址
-    "host": "",
-    // 正向websocket服务端口
-    // 当port与http服务port一致时，host也需与http服务host保持一致，否则可能会导致启动失败
-    "port": 3001
-  },
-  "reverseWs": {
-    // 是否启用反向websocket服务
-    "enable": false,
-    // 反向websocket对接的地址, 如["ws://127.0.0.1:8080/onebot/v11/ws"]
-    "urls": []
-  },
-  "GroupLocalTime": {
-    "Record": false,//是否开启本地群聊时间记录
-    "RecordList": []//开启全部群 ["-1"]  单个群配置 ["11111"] 多个群 ["1","2","3"]
-  },
-  // 是否开启调试模式，开启后上报消息会携带一个raw字段，为原始消息内容
-  "debug": false,
-  // ws心跳间隔，单位毫秒
-  "heartInterval": 30000,
-  // 消息上报格式，array为消息组，string为cq码字符串
-  "messagePostFormat": "array",
-  // 是否将本地文件转换为URL，如果获取不到url则使用base64字段返回文件内容
-  "enableLocalFile2Url": true,
-  // 音乐签名URL，用于处理音乐相关请求
-  "musicSignUrl": "",
-  // 是否上报自己发送的消息
-  "reportSelfMessage": false,
-  // access_token，可以为空
-  "token": ""
-}
+```
+HTTP服务端      --->> NapCat作为Http请求接受方 接收对应接口调用并回应 的单工模型
+HTTP客户端      --->> NapCat作为Http请求发起方 将事件推送至插件/应用框架 的单工模型
+WebSocket服务端 --->> 通常指正向WS 既能主动推送事件也能接收请求 的双工模型
+WebSocket客户端 --->> 通常指反向WS 既能主动推送事件也能接收请求 的双工模型
 ```
 
 ## 配置 NapCat 其它设置（如果不懂干嘛，不用看啦）

diff --git a/src/guide/start-install copy.md b/src/guide/start-install copy.md
@@ -0,0 +1,50 @@
+# 开始安装
+## 快速了解
+<!-- ![Napcat](/assets/boot/BootWay01/napcat.png) -->
+
+<!-- 从左至右依次是 正常运行版本 / 启动 NapCat.FrameWork / 启动 NapCat.Shell -->
+
+![NCD](/assets/boot/BootWay01/ncd.png)
+
+<!-- 此图为NapCat Shell Window可视化版本
+
+可以了解到框架与别的框架不同点有
+1. NapCat 能够 保证你的正常QQ的使用 也可以提供注入QQ本体 也可以独立运行命令行 除此外还能同时运行任意模式.
+2. NapCat 不会污染你的QQ环境 更新不会让QQ异常 也不会需要重新配置NapCat.
+3. NapCat 是非常容易使用的 并且带有可选的图形化界面与远程配置 -->
+
+前往 [NapCatQQ 的 release 页面](https://github.com/NapNeko/NapCatQQ/releases)，各位可以看到有两种压缩包，
+文件名后缀分别为 `Shell` 和 `Framework`，应当如何选择呢？
+
+## 了解 Release文件
+
+使用前请务必了解
+
+[点我了解](./boot/release.md)
+
+## Shell 版本
+
+此方法为 `无头启动`
+
+### 优点
+
+- 无需图形化界面
+- 节省内存
+
+### 教程
+
+- 适用教程 [方法2 - 使用命令行启动](./boot/Shell.md) <- 推荐
+- 适用教程 [方法2 - Arch手动配置](./boot/Shell-Linux-SemiAuto.md) <-Arch
+
+## Framework 版本
+
+此方法为 `有头启动`
+
+### 优点
+
+- "人机合一"
+
+### 教程
+
+- 适用教程 [方法1 - 作为 LiteLoader 插件启动](./boot/Framework.md) <- 推荐
+- 适用教程 `方法3 - 原生使用 NapCatQQ 启动` <- 由于启动方式变更,暂不提供教程
diff --git a/src/guide/start-install.md b/src/guide/start-install.md
@@ -1,50 +1,87 @@
-# 开始安装
-## 快速了解
-<!-- ![Napcat](/assets/boot/BootWay01/napcat.png) -->
+# NapCat
 
-<!-- 从左至右依次是 正常运行版本 / 启动 NapCat.FrameWork / 启动 NapCat.Shell -->
+欢迎来到 NapCat Robot 的世界！接下来我将为你讲解一些入门知识。
 
-![NCD](/assets/boot/BootWay01/ncd.png)
+此文档又名：如何驾驭 NapCat 快速踏入一阶魔法师。
 
-<!-- 此图为NapCat Shell Window可视化版本
+## NapCat 施展了什么魔法
 
-可以了解到框架与别的框架不同点有
-1. NapCat 能够 保证你的正常QQ的使用 也可以提供注入QQ本体 也可以独立运行命令行 除此外还能同时运行任意模式.
-2. NapCat 不会污染你的QQ环境 更新不会让QQ异常 也不会需要重新配置NapCat.
-3. NapCat 是非常容易使用的 并且带有可选的图形化界面与远程配置 -->
+```mermaid
+graph TD
+    NTQQ客户端 -- JavaScript交互 <--> NapCat
+    NapCat -- WS/HTTP <--> 插件框架
+    NapCat -- WS/HTTP <--> 独立插件
+    插件框架 <--> 插件1
+    插件框架 <--> 插件2
+```
 
-前往 [NapCatQQ 的 release 页面](https://github.com/NapNeko/NapCatQQ/releases)，各位可以看到有两种压缩包，
-文件名后缀分别为 `Shell` 和 `Framework`，应当如何选择呢？
+::: details 小小的故事...
+在一个遥远的、充满奇幻与科技交织的世界——**NapCat Robot**，有一种神秘且强大的力量，叫做 **NTQQ**。这股力量，简直就像是一颗随时可能爆炸的定时炸弹，能改变一切，却又异常难以控制。很多英雄、巫师、冒险者们曾试图驾驭它，结果都失败得一塌糊涂，甚至连他们的名字都被历史遗忘了，仿佛从未存在过。 
 
-## 了解 Release文件
+然而，在这个充满混乱的世界里，有一只小猫娘，名字叫做 **NapCat**，她不仅是这个故事的主角，而且简直是这个世界最萌最可爱的“灾难制造机”。NapCat外表乖巧，萌萌哒，软乎乎的，简直像个大大的毛球，走路一摇一摆的，超乎想象的笨拙。她曾经被遗弃在一个荒凉的角落里，孤零零地生活着。但某天，她突然发现了一个超级神奇的东西——**JavaScript**！ 
 
-使用前请务必了解
+“诶？这是什么？看起来像是能吃的样子...可是为什么一点也不好吃呢？”
 
-[点我了解](./boot/release.md)
+于是，NapCat就开始了对这门语言的探索——虽然她并不完全理解它，但她凭着直觉和那种天生的好奇心，成功破解了 JavaScript 的奥秘，并意外地与传说中的 **NTQQ** 产生了连接。
 
-## Shell 版本
+虽然看起来她像是无害的傻萌猫娘，但NapCat的这项技能竟然能在没有任何计划的情况下，操控 NTQQ 的某些功能，甚至能轻松改变现实的规则！但问题是……她的每次操作，基本上都是胡乱点击、乱敲键盘、然后出奇不意地发生了不想要的结果。
 
-此方法为 `无头启动`
+“嗯？我是不是把天空变得五颜六色了？咦？月亮不见了？咕噜咕噜……好像做错了什么事呢。”
 
-### 优点
+于是，一切开始变得混乱不堪。天空瞬间变成了彩虹色，时间突然在某些地方停滞，甚至连月亮都神秘消失了！整个世界都被这只小猫娘的“无心之举”搞得一团糟，灾难的阴影笼罩了整个世界。 
 
-- 无需图形化界面
-- 节省内存
+就在大家都以为一切都完了，世界即将崩塌的时候，出现了一个强大的英雄。他不是什么骑着白马，手持宝剑的传统英雄，而是一个比任何人都冷静的智者。他决定采取一种不同的方式来解决这个问题：**OneBot规范**。
 
-### 教程
+“一切都得按照规范来！否则她会再把世界变成一锅粥！”英雄心想。
 
-- 适用教程 [方法2 - 使用命令行启动](./boot/Shell.md) <- 推荐
-- 适用教程 [方法2 - Arch手动配置](./boot/Shell-Linux-SemiAuto.md) <-Arch
+这个英雄明白，NapCat的能力太强大，控制不住的话，真的会把世界毁掉。因此，这位应用采用前辈们广泛使用的OneBot规范，规定 NapCat 任何操作都要写道 **WS/HTTP** 这种纸张上，每次使用 NTQQ 的力量时，都要在“纸上”写下相应的指令，才能让 NTQQ按照预设的方式执行任务。而且每次任务完成后，数据也会通过同样的“纸面”反馈回来，确保一切都在可控范围内。
+
+“啊？这个纸好像好难理解……但是，哦，原来是这么回事呀！”
+
+于是，NapCat开始在这套严格的规范下与 NTQQ 建立了微妙的关系。她不再是那个随便敲敲代码就让天空变色的笨蛋，而是通过认真的输入和执行指令，逐渐恢复了世界的秩序。
+
+可虽然一切变得井然有序，NapCat依旧是那个呆萌、迷糊的猫娘。她依然在“纸”上写着自己不太明白的指令，每次完成任务后，她都会露出一副“我是不是做对了？”的迷茫表情，仿佛在问：“哎？我这次没搞砸吧？”
+
+尽管如此，大家也逐渐接受了她的笨拙，因为她那种天真可爱的样子实在让人忍不住心软。最重要的是，世界终于恢复了平静，大家都知道，这只猫娘虽然有时候会闹出点小乱子，但她那份纯真与努力，才是让这个世界重新恢复平衡的力量。
+
+从那时起，NapCat与NTQQ之间的微妙平衡保持着，而你也可以来这个世界，看看这只可爱笨蛋猫娘是怎么在搞笑与危机四伏中，带着一颗认真又迷糊的心，守护这个充满魔力与冒险的世界的！✨
+:::
+
+由此可以看出 使用NapCat必须保证NTQQ的客户端这一基础的存在, 于是使用流程大概为
+0. 安装**对应版本**NTQQ (特殊情况不需要安装或安装器代为安装)
+1. 下载你需要的NapCat版本
+2. 遵照其详细教程启动NapCat本体
+3. 进入WebUi 启动你需要HTTP/WS 客户端与服务端
+4. 配置框架或者独立插件连接NapCat
 
-## Framework 版本
+## Release里面问题有些什么呢
 
-此方法为 `有头启动`
+| 文件名称        |      注意事项      | 适用平台 |
+| ------------- | :-----------: | -----------: | 
+| NapCat.Framework.Windows.Once.zip | 一键包Framework包(不包含QQ) | Windows.AMD64 |
+| NapCat.Framework.zip     |     Framework本体  | AnyPlat.AnyArch | 
+| NapCat.Shell.zip |   Shell本体+启动器(不包含QQ)    | AnyPlat.AnyArch | 
+| Win无头链接 |   Shell本体+启动器(包含QQ)    | Windows.AMD64 |
+| Win有头链接 |   Framework本体+启动器(包含QQ)    | Windows.AMD64 |
 
-### 优点
+## 思考思考
+NapCat有着众多启动方式 这些启动方式 伴随各种特性
 
-- "人机合一"
+Shell 版本具有低内存 服务器部署简单的方案
 
-### 教程
+Framework 版本是具有可以 人机一体 方便窥屏的方案
+
+### Shell 启动/安装方式
 
 - 适用教程 [方法1 - 作为 LiteLoader 插件启动](./boot/Framework.md) <- 推荐
 - 适用教程 `方法3 - 原生使用 NapCatQQ 启动` <- 由于启动方式变更,暂不提供教程
+
+### Framework 启动/安装方式
+- 适用教程 [方法2 - 使用命令行启动](./boot/Shell.md) <- 推荐
+- 适用教程 [方法2 - Arch手动配置](./boot/Shell-Linux-SemiAuto.md) <-Arch
+
+
+## 安装完成！铛铛
+安装后就可以执行 ```3. 进入WebUi 启动你需要HTTP/WS 客户端与服务端```
+
+[前往WebUi配置教程](../config/basic.md)
diff --git a/src/public/assets/use/webui-image-01.png b/src/public/assets/use/webui-image-01.png