feat: initialize documentation site with VitePress and add comprehensive user guides

Author: dingyi222666

docs/.vitepress/config.ts

@@ -36,8 +36,8 @@
 
 - 选择为 `memory` 时，角色卡会被加载到内存中，可以进行动态加载。
 
-- 选择为 `file` 时，角色卡会被转换为 ChatLuna 的预设文件，并存储在 `<koishi 数据目录>/data/chathub/preset` 目录下。
-  
+- 选择为 `file` 时，角色卡会被转换为 ChatLuna 的预设文件，并存储在 `<koishi 数据目录>/data/chathub/presets` 目录下。
+
   需要重启 ChatLuna 才能加载最新转换的角色卡。
 
 #### jailbreak

docs/ecosystem/extension/character-card.md

@@ -1,54 +1,122 @@
 # 聊天模式
 
-聊天模式是 ChatLuna 中一个非常重要的模块，每个房间都可以选择不同的聊天模式，不同的聊天模式下，可以使用不同的工具，Prompt 等，多样的聊天模式可以满足不同的聊天场景。
+聊天模式决定了 ChatLuna 在一轮对话中的行为方式。不同的模式下，模型的能力范围不同。
 
-## 可用模式
+目前 ChatLuna 支持以下几种聊天模式：
 
-ChatLuna 中内置了以下几种聊天模式：
+- **chat**：基础聊天模式。适用于普通对话，同时支持预设中的常见能力，如世界书、作者注释和长期记忆。
+- **agent**：工具调用模式。模型可以在对话中调用工具、拆分任务和执行操作。
+- **browsing**：联网检索模式。模型会先从外部获取信息，再结合检索结果进行回答。适用于查询最新信息或处理网页相关的轻量任务。
 
-- **chat**: 默认，也是最基本的聊天模式，支持预设的全部功能（世界书，作者注释等），并且也支持长期记忆。
+## 配置
 
-- **agent**: 基于 LangChain 的 Agent 提供的聊天模式。可以让模型调用多样化的工具，大幅扩展模型的能力。
+### chat
 
-不仅如此，ChatLuna 团队还维护以下聊天模式：
+`chat` 是主插件内置模式，无需额外安装。
 
-- **browsing**: 基于聊天模式增强的网页浏览模式，模型可以从外部获取最新信息。
+### agent
 
-下面我们介绍如何配置和使用这些聊天模式。
+`agent` 也是主插件内置模式。
 
-## 配置
+该模式本身只提供"允许模型调用工具"的能力，工具需要另行安装。
 
-### chat
+:::tip 提示
+ChatLuna 主插件不内置可供 `agent` 模式使用的工具。
 
-chat，也就是最主要的聊天模式。ChatLuna 的主插件已经内置此模式，无需额外配置。
+一般需要安装 [`chatluna-plugin-common`](../../ecosystem/introduction.md) 或 [`chatluna-mcp-client`](../../ecosystem/plugin/mcp-client.md) 等插件来提供工具支持。
+:::
 
-### agent
+### browsing
 
-agent 模式也是 ChatLuna 主插件中内置的聊天模式。
+`browsing` 是官方维护的聊天模式，但未打包进主插件。
 
-agent 模式让模型可以调用工具，并根据工具的返回结果，继续调用工具，直到完成任务。能实现复杂的任务。
+需要额外安装 `chatluna-search-service` 才能使用。安装方式参见 [生态介绍](../../ecosystem/introduction.md)。
 
-> [!TIP]
-> ChatLuna 主插件中没有内置可供 agent 聊天模式使用的工具。
->
-> 你需要安装 [`chatluna-plugin-common`](../../ecosystem/introduction.md) 或 [`chatluna-mcp-client`](../../ecosystem/plugin/mcp-client.md) 插件来为 agent 模式提供可用的工具。
+## 修改聊天模式
 
-### browsing
+ChatLuna 提供了多种方式来修改聊天模式，适用于不同场景。
+
+### 新建会话时指定
+
+在创建会话时通过 `-c` 参数直接指定聊天模式：
+
+```powershell
+chatluna.new [title:text] -c <chatMode:string>
+```
+
+<chat-panel>
+  <chat-message nickname="User">chatluna.new 调试会话 -c plugin</chat-message>
+  <chat-message nickname="Bot">已创建并切换到新会话 调试会话。</chat-message>
+</chat-panel>
+
+此操作只影响新建的会话，不会修改已有会话。
+
+### 修改当前会话
+
+在已有会话中切换聊天模式，使用 `chatluna.use.mode`：
+
+```powershell
+chatluna.use.mode <mode:string> -p <preset:string>
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `mode` | 目标聊天模式 |
+| `-p` | 目标预设通道。仅在需要操作其他通道时指定 |
+
+<chat-panel>
+  <chat-message nickname="User">chatluna.use.mode browsing</chat-message>
+  <chat-message nickname="Bot">已将当前会话切换为 browsing 模式。</chat-message>
+</chat-panel>
+
+如果存在多条预设通道，也可以单独修改其中一条：
+
+```powershell
+chatluna.use.mode plugin -p translator
+```
+
+### 修改当前作用域的默认模式
+
+修改当前群聊或私聊作用域中，后续新建会话所使用的默认聊天模式，使用 `chatluna.rule.mode`：
+
+```powershell
+chatluna.rule.mode [mode:string] -f -c
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `mode` | 要设置的默认聊天模式 |
+| `-f` | 与 `mode` 一起使用时，将该模式固定到当前作用域 |
+| `-c` | 清除当前作用域上的模式规则 |
 
-浏览模式是官方维护的聊天模式，但由于体积原因，默认没有集成到 ChatLuna 主插件中。
+<chat-panel>
+  <chat-message nickname="User">chatluna.rule.mode browsing</chat-message>
+  <chat-message nickname="Bot">已将当前作用域的新会话默认模式设置为 browsing。</chat-message>
+</chat-panel>
 
-你需要额外安装 `chatluna-search-service`，才能使用此聊天模式。
+如需将模式锁定，防止被修改：
 
-阅读 [此文档](../../ecosystem/introduction.md) 了解如何安装和配置 `chatluna-search-service`。
+```powershell
+chatluna.rule.mode plugin -f
+```
 
-## 使用
+:::warning 注意
+单独使用 `-f` 没有实际效果。`-f` 只有与具体模式一起传入时才会生效。
+:::
 
-使用聊天模式与预设类似，分为两种场景。
+## 全局默认值
 
-### 普通房间
+主插件配置中的 [`defaultChatMode`](../useful-configurations.md#defaultchatmode) 是全局层面的默认值：
 
-使用 [`chatluna.room.set -c <chatmode>`](../useful-commands.md#设置房间) 命令，对当前你所在的房间切换为你想要使用的聊天模式即可。
+- 当当前作用域没有额外规则时，新会话会使用该值
+- 不会覆盖已有会话的设置
+- 不会替代 `chatluna.rule.mode` 设置的规则
 
-### 模版克隆房间
+各层级的优先级如下：
 
-前往 Koishi 控制台，找到 ChatLuna 主插件的配置项，在 [`defaultChatMode`](../useful-configurations.md#defaultchatmode) 选项里选择你需要使用的聊天模式即可。
+| 层级 | 说明 |
+| --- | --- |
+| `defaultChatMode` | 整个插件的全局默认值 |
+| `chatluna.rule.mode` | 当前作用域的默认值 |
+| `chatluna.new -c` | 新建会话时的显式指定 |
+| `chatluna.use.mode` | 当前会话的即时修改 |

docs/guide/chat-chain/chat-mode.md

@@ -32,16 +32,16 @@
 
 在混元适配器的配置页面，点击运行按钮，如无误，你应该看不到任何错误 log，那即可转到 ChatLuna 的主插件页面。
 
-在主插件页面，下划到 [模版房间选项](../useful-configurations.md#模版房间选项)，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的选项里是否含有混元模型，如果有，则说明混元适配器已经成功的运行。
+在主插件页面，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的候选项里是否出现混元模型。如果有，说明混元适配器已经成功运行。
 
 ![alt text](../../public/images/image-10.png)
 
 但我们仍未完全确认混元适配器是否可用。
 
-因此我们需要新建一个房间，使用 `chatluna.room.create -m hunyuan/hunyuan-turbo -p chatgpt -n test-hunyuan-adapter` 指令来创建一个使用了混元适配器的房间。
+因此我们可以执行 `chatluna.new test-hunyuan-adapter -m hunyuan/hunyuan-turbo -p chatgpt`，创建一个使用混元适配器的新会话进行测试。
 
-新建房间后请尝试和模型对话。
+创建完成后，请尝试和模型对话。
 
 只要能正常对话，就说明你成功的连接到了混元 API。
 
-别忘了在测试完成后调用 `chatluna.room.delete test-hunyuan-adapter` 指令删除测试房间。
+测试完成后，如需清理该测试上下文，可以执行 `chatluna.delete test-hunyuan-adapter`。

docs/guide/configure-model-platform/hunyuan.md

@@ -32,16 +32,16 @@
 
 在文心一言适配器的配置页面，点击运行按钮，如无误，你应该看不到任何错误 log，那即可转到 ChatLuna 的主插件页面。
 
-在主插件页面，下划到 [模版房间选项](../useful-configurations.md#模版房间选项)，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的选项里是否含有 ChatGLM 模型，如果有，则说明 ChatGLM 适配器已经成功的运行。
+在主插件页面，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的候选项里是否出现文心模型。如果有，说明文心适配器已经成功运行。
 
 ![alt text](../../public/images/image-7.png)
 
 但我们仍未完全确认文心一言适配器是否可用。
 
-因此我们需要新建一个房间，使用 `chatluna.room.create -m wenxin/ERNIE-lite -p chatgpt -n test-wenxin-adapter` 指令来创建一个使用了文心一言适配器的房间。
+因此我们可以执行 `chatluna.new test-wenxin-adapter -m wenxin/ERNIE-lite -p chatgpt`，创建一个使用文心适配器的新会话进行测试。
 
-新建房间后请尝试和模型对话。
+创建完成后，请尝试和模型对话。
 
 只要能正常对话，就说明你成功的连接到了文心一言 API。
 
-别忘了在测试完成后调用 `chatluna.room.delete test-wenxin-adapter` 指令删除测试房间。
+测试完成后，如需清理该测试上下文，可以执行 `chatluna.delete test-wenxin-adapter`。

docs/guide/configure-model-platform/wenxin.md

@@ -34,16 +34,16 @@ ChatGLM 是一种由清华大学联合智谱AI开发的大型语言模型家族
 
 在智谱适配器的配置页面，点击运行按钮，如无误，你应该看不到任何错误 log，那即可转到 ChatLuna 的主插件页面。
 
-在主插件页面，下划到 [模版房间选项](../useful-configurations.md#模版房间选项)，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的选项里是否含有 ChatGLM 模型，如果有，则说明 ChatGLM 适配器已经成功的运行。
+在主插件页面，查看 [defaultModel](../useful-configurations.md#defaultmodel) 的候选项里是否出现 ChatGLM 模型。如果有，说明智谱适配器已经成功运行。
 
 ![alt text](../../public/images/image-2.png)
 
 但我们仍未完全确认智谱适配器是否可用。
 
-因此我们需要新建一个房间，使用 `chatluna.room.create -m zhipu/GLM-4-Flash -p chatgpt -n test-zhipu-adapter` 指令来创建一个使用了智谱适配器的房间。
+因此我们可以执行 `chatluna.new test-zhipu-adapter -m zhipu/GLM-4-Flash -p chatgpt`，创建一个使用智谱适配器的新会话进行测试。
 
-新建房间后请尝试和模型对话。
+创建完成后，请尝试和模型对话。
 
 只要能正常对话，就说明你成功的连接到了智谱 API。
 
-别忘了在测试完成后调用 `chatluna.room.delete test-zhipu-adapter` 指令删除测试房间。
+测试完成后，如需清理该测试上下文，可以执行 `chatluna.delete test-zhipu-adapter`。