Skip to content

Bot_Commands_User_Guide.md

Latest commit

 

History

History
272 lines (243 loc) · 20.8 KB

Bot_Commands_User_Guide.md

File metadata and controls

272 lines (243 loc) · 20.8 KB

TelegramSearchBot - 用户指令与使用说明

本文档旨在提供 TelegramSearchBot 的用户指令列表及其使用方法，帮助用户更好地与机器人进行交互。

一、通用用户指令

这些指令可由任何用户在与机器人私聊或在机器人所在的群组中使用。

  1. 搜索内容

    • 指令格式: 搜索 <关键词>
    • 功能: 在机器人索引的消息中搜索包含指定关键词的内容。
    • 示例: 搜索 Orleans入门教程
    • 说明与分页:
      • 机器人会以消息形式返回搜索结果列表，每条结果通常包含消息内容的预览和指向原始消息的链接。
      • 如果结果数量较多，消息底部会附带内联键盘按钮，如“下一页”和“删除历史”。
      • “下一页”按钮: 点击后，机器人会显示下一页的搜索结果。这个功能由 SearchNextPageController 处理，它会从一个临时的缓存（LiteDB中的CacheData表）中读取之前的搜索条件和当前分页状态（通过按钮回调数据中的唯一ID关联），然后获取并展示新的结果页，同时更新分页按钮。Service/BotAPI/SendService.cs 负责生成包含这些按钮的回复消息，并将下一次分页所需的状态（如更新后的跳过条目数）存入缓存。
      • “删除历史”按钮: 点击后，通常会删除之前的搜索结果消息，以保持聊天界面的整洁。

  2. 解析链接 (手动)

    • 指令: /resolveurls
    • 功能: 当用户明确使用此命令时，解析提供的文本（或回复的消息中的文本）中包含的短链接或重定向链接，并显示其最终的目标长链接。
    • 用法1 (直接提供文本): /resolveurls <包含一个或多个链接的文本>
      • 示例: /resolveurls 这是b23.tv/xxxx的一个短链接，还有t.cn/AAAA的另一个。
    • 用法2 (回复消息): 回复一条包含链接的消息，并发送指令 /resolveurls。
    • 说明: 机器人会回复解析后的链接列表。此命令主要用于即时查看链接的解析结果。链接的自动后台处理和存储是另一项功能（见下文“自动URL解析与存储”）。

二、管理员指令

这些指令通常需要特定的管理员权限才能执行。

1. LLM 模型设置 (普通管理员)

普通管理员通常指在被设置为“管理群”的群组内具有管理员权限的用户，或全局管理员。

  • 设置当前聊天使用的LLM模型
    • 指令格式: 设置模型 <模型名称>
    • 功能: 为当前聊天（群组或私聊）设置后续与LLM交互时使用的模型。
    • 示例: 设置模型 gpt-4-turbo
    • 权限: 普通管理员或全局管理员。

2. 全局管理员指令

以下指令仅限机器人全局管理员（在 Env.cs 中配置的 AdminId）使用。

  • 群组管理 (在目标群组中发送)

    • 指令: 设置管理群
      • 功能: 将当前群组设置为“管理群”。“管理群”内的管理员可能拥有执行某些特定指令的权限（如 设置模型）。
      • 用法: 在目标群组中发送 设置管理群。
    • 指令: 取消管理群
      • 功能: 取消当前群组的“管理群”状态。
      • 用法: 在目标群组中发送 取消管理群。

  • Bilibili 相关配置 (可在任意聊天中发送，但仅全局管理员可执行)

    • 设置B站Cookie:
      • 指令格式: /setbilicookie <Cookie字符串> 或 设置B站Cookie <Cookie字符串>
      • 功能: 设置用于访问Bilibili受限内容（如会员视频信息）的Cookie。
      • 示例: /setbilicookie SESSDATA=xxxxxx; bili_jct=yyyyy;
    • 获取B站Cookie状态:
      • 指令: /getbilicookie 或 获取B站Cookie
      • 功能: 检查当前是否已配置B站Cookie，并显示其长度（出于安全考虑，不显示完整值）。
    • 设置B站视频最大下载大小:
      • 指令格式: /setbilimaxsize <MB数> 或 设置B站最大下载大小 <MB数>
      • 功能: 设置机器人尝试下载Bilibili视频时的文件大小上限（单位：MB）。
      • 示例: /setbilimaxsize 500 (表示最大下载500MB的视频)
    • 获取B站视频最大下载大小:
      • 指令: /getbilimaxsize 或 获取B站最大下载大小
      • 功能: 查看当前配置的Bilibili视频最大下载大小。

  • LLM渠道配置 (在群组中由全局管理员发送，会触发交互式配置流程)

    • 说明: 以下指令用于管理LLM API渠道。它们会启动一个多步骤的对话流程（状态机），机器人会依次询问配置所需的各项信息。请按照机器人的提示逐步回复。
      • 例如，使用 新建渠道 指令的交互流程可能如下：
        1. 管理员发送: 新建渠道
        2. 机器人回复: 请输入渠道的名称
        3. 管理员发送: 我的OpenAI渠道
        4. 机器人回复: 请输入渠道地址 (例如 https://api.openai.com/v1)
        5. 管理员发送: (对应的API网关地址)
        6. 机器人回复: 请选择渠道类型：\n1. OpenAI\n2. Ollama
        7. 管理员发送: 1
        8. 机器人回复: 请输入渠道的最大并行数量(默认1):
        9. 管理员发送: 5 (或直接回车使用默认值)
        10. 机器人回复: 请输入渠道的优先级(默认0):
        11. 管理员发送: 10 (或直接回车使用默认值)
        12. 机器人回复: 请输入渠道的API Key
        13. 管理员发送: (对应的API Key)
        14. 机器人回复: 渠道创建成功 (或失败信息)
      • 又例如，使用 添加模型 指令的交互流程可能如下：
        1. 管理员发送: 添加模型
        2. 机器人回复: (列出现有渠道) 请选择要添加模型的渠道ID：
        3. 管理员发送: (选择一个渠道ID，例如 1)
        4. 机器人回复: 请输入要添加的模型名称，多个模型用逗号或分号分隔
        5. 管理员发送: gpt-3.5-turbo,text-davinci-003
        6. 机器人回复: 模型添加成功 (或失败信息)
      • 编辑渠道 指令的交互流程示例：
        1. 管理员发送: 编辑渠道
        2. 机器人回复: (列出现有渠道) 请选择要编辑的渠道ID：
        3. 管理员发送: (选择一个渠道ID，例如 1)
        4. 机器人回复: (列出可编辑字段) 请选择要编辑的字段：\n1. 名称 (当前值)\n2. 地址 (当前值)\n3. 类型 (当前值)\n4. API Key\n5. 最大并行数量 (当前值)\n6. 优先级 (当前值)
        5. 管理员发送: (选择字段编号)
        6. 如果选择 1, 2, 4, 5, 6:
          • 机器人回复: 请输入新的值：
          • 管理员发送: (输入新值)
          • 跳到第8步
        7. 如果选择 3 (类型):
          • 机器人回复: 请选择渠道类型：\n1. OpenAI\n2. Ollama
          • 管理员发送: (输入选项编号，例如 1)
        8. 管理员发送: (输入新值或选择编号)
        9. 机器人回复: 更新成功 (或失败信息)
      • 移除模型 指令的交互流程示例：
        1. 管理员发送: 移除模型
        2. 机器人回复: (列出现有渠道) 请选择要移除模型的渠道ID：
        3. 管理员发送: (选择一个渠道ID，例如 1)
        4. 机器人回复: (列出该渠道下的模型) 请选择要移除的模型：\n1. model_A\n2. model_B
        5. 管理员发送: (选择模型编号，例如 1)
        6. 机器人回复: 模型移除成功 (或失败信息)
      • 查看模型 指令的交互流程示例：
        1. 管理员发送: 查看模型
        2. 机器人回复: (列出现有渠道) 请选择要查看模型的渠道ID：
        3. 管理员发送: (选择一个渠道ID，例如 1)
        4. 机器人回复: (列出该渠道下的所有模型) 渠道 [渠道名称] 下的模型列表：\n- model_A\n- model_B
      • 刷新所有渠道 指令的交互流程示例：
        1. 管理员发送: 刷新所有渠道
        2. 机器人回复: 已添加{n}个模型 (刷新并返回添加的模型数量)
      • 设置重试次数 指令的交互流程示例：
        1. 管理员发送: 设置重试次数
        2. 机器人回复: 请输入最大重试次数(默认100):
        3. 管理员发送: 200 (或直接回车使用默认值100)
        4. 机器人回复: 最大重试次数已设置为: 200
      • 设置图片重试次数 指令的交互流程示例：
        1. 管理员发送: 设置图片重试次数
        2. 机器人回复: 请输入图片处理最大重试次数(默认1000):
        3. 管理员发送: 500 (或直接回车使用默认值1000)
        4. 机器人回复: 图片处理最大重试次数已设置为: 500
      • 设置图片模型 指令的交互流程示例：
        1. 管理员发送: 设置图片模型
        2. 机器人回复: 请输入图片分析使用的模型名称:
        3. 管理员发送: gpt-4o
        4. 机器人回复: 图片分析模型已设置为: gpt-4o
    • 指令: 新建渠道
      • 功能: 开始创建新的LLM（大语言模型）API渠道的流程，包括名称、网关地址、API类型 (OpenAI/Ollama)、API Key、最大并行数和优先级。
    • 指令: 编辑渠道
      • 功能: 列出现有LLM渠道，并允许选择一个进行编辑（名称、网关、类型、API Key、并行数、优先级）。这是一个交互式过程。
    • 指令: 添加模型
      • 功能: 为指定的LLM渠道关联一个或多个模型名称。此过程会先要求选择渠道，然后输入模型名称。这是一个交互式过程。
    • 指令: 移除模型
      • 功能: 从指定的LLM渠道移除已关联的模型。此过程会先要求选择渠道，然后选择要移除的模型。这是一个交互式过程。
      • 指令: 查看模型
      • 功能: 查看指定LLM渠道下已关联的所有模型。此过程会先要求选择渠道。
      • 指令: 刷新所有渠道
      • 功能: 刷新所有LLM渠道配置，重新从配置源加载渠道信息。
      • 指令: 设置重试次数
      • 功能: 设置LLM请求的最大重试次数。此过程会询问最大重试次数（默认100）。
      • 指令: 设置图片重试次数
      • 功能: 设置图片处理的最大重试次数。此过程会询问最大重试次数（默认1000）。
      • 指令: 设置图片模型
      • 功能: 设置用于图片分析的LLM模型名称。此过程会询问模型名称。

  • MCP服务器管理 (在群组中由全局管理员发送，会触发交互式配置流程)

    • 说明: 以下指令用于管理MCP (Model Context Protocol) 服务器。它们会启动一个多步骤的对话流程（状态机），机器人会依次询问配置所需的各项信息。请按照机器人的提示逐步回复。
      • 查看MCP服务器 指令:
        1. 管理员发送: 查看MCP服务器
        2. 机器人回复: (列出所有已配置的MCP服务器，包括命令、超时、环境变量、可用工具)
      • 新建MCP服务器 指令的交互流程示例：
        1. 管理员发送: 新建MCP服务器
        2. 机器人回复: 请输入MCP服务器的唯一名称（例如：minimax, github, filesystem）：
        3. 管理员发送: filesystem
        4. 机器人回复: 请输入启动命令（例如：npx, uvx, node, python）：
        5. 管理员发送: npx
        6. 机器人回复: 请输入命令参数（空格分隔，例如：-y @modelcontextprotocol/server-filesystem /tmp），输入 - 跳过：
        7. 管理员发送: -y @modelcontextprotocol/server-filesystem
        8. 机器人回复: 请输入环境变量名（例如：API_KEY），输入 完成 结束环境变量设置：
        9. 管理员发送: 完成
        10. 机器人回复: 请输入超时时间（秒，默认30）：
        11. 管理员发送: 60
        12. 机器人回复: ✅ MCP服务器 'filesystem' 创建成功！发现 {n} 个工具:...
      • 编辑MCP服务器 指令的交互流程示例：
        1. 管理员发送: 编辑MCP服务器
        2. 机器人回复: (列出现有服务器) 请选择要编辑的MCP服务器（输入名称）：
        3. 管理员发送: filesystem
        4. 机器人回复: (显示可编辑字段) 正在编辑MCP服务器: filesystem\n请选择要编辑的字段（输入编号）：\n1. 命令\n2. 参数\n3. 环境变量\n4. 超时时间\n5. 启用/禁用
        5. 管理员发送: 4
        6. 机器人回复: 请输入新的超时时间（秒）：
        7. 管理员发送: 120
        8. 机器人回复: ✅ MCP服务器 'filesystem' 超时时间已更新为: 120s 编辑环境变量示例（选择字段3，需要2步输入）：
        9. 管理员发送: 3
        10. 机器人回复: 请输入要设置的环境变量名（注意：这是写入操作）：
        11. 管理员发送: API_KEY
        12. 机器人回复: 请输入环境变量 API_KEY 的值：
        13. 管理员发送: my-secret-key
        14. 机器人回复: ✅ MCP服务器 'filesystem' 环境变量 'API_KEY' 已设置。
      • 删除MCP服务器 指令的交互流程示例：
        1. 管理员发送: 删除MCP服务器
        2. 机器人回复: (列出现有服务器) 请选择要删除的MCP服务器（输入名称）：
        3. 管理员发送: filesystem
        4. 机器人回复: 确认删除MCP服务器 'filesystem'？输入 是 确认，输入其他取消：
        5. 管理员发送: 是
        6. 机器人回复: ✅ MCP服务器 'filesystem' 已删除。
      • 重启MCP服务器 指令:
        1. 管理员发送: 重启MCP服务器
        2. 机器人回复: ✅ MCP服务器已重启。共 {n} 个工具可用。
    • 指令: 查看MCP服务器
      • 功能: 列出所有已配置的MCP服务器及其状态、命令、参数、环境变量、可用工具。
    • 指令: 新建MCP服务器
      • 功能: 开始创建新的MCP服务器的流程，包括名称、启动命令、参数、环境变量（可选）、超时时间。
    • 指令: 编辑MCP服务器
      • 功能: 编辑现有MCP服务器的配置（命令、参数、环境变量、超时、启用/禁用）。
    • 指令: 删除MCP服务器
      • 功能: 删除已配置的MCP服务器（需确认）。
    • 指令: 重启MCP服务器
      • 功能: 重启所有MCP服务器并重新注册工具。

  • 数据与索引管理 (在与机器人的私聊中由全局管理员发送)

    • 指令: 重建索引
      • 功能: 清空并重建消息的搜索索引（Lucene.Net）。此操作可能耗时较长。
    • 指令: 导入数据
      • 功能: 从预设路径 (/tmp/export.json) 的 JSON 文件中导入用户和消息数据到数据库。 (注意：此功能依赖特定文件路径和格式)
    • 指令: 迁移数据
      • 功能: 将数据从 LiteDB 迁移到 SQLite 数据库。 (注意：此为特定场景下的数据迁移指令)

三、自动功能与内容触发器

机器人还具有一些基于消息内容或类型的自动处理功能：

  1. 与LLM对话 (需要配置并启用OpenAI/Ollama等服务)

    • 触发方式1 (提及机器人): 在消息中 @机器人用户名 <你的消息>。
      • 示例: @MyAwesomeBot 帮我总结一下这篇文章的主要内容。
    • 触发方式2 (回复机器人消息): 直接回复机器人的某条消息。
    • 功能: 将您的消息发送给配置的LLM进行处理，并回复LLM的响应。
    • 工具调用迭代限制: 为防止LLM无限调用工具，机器人默认限制为25次工具调用（可通过 MaxToolCycles 配置）。当达到限制时：
      • 机器人会保存当前对话快照到Redis
      • 用户可选择"继续迭代"按钮恢复对话，或"停止"按钮结束当前对话

  2. Bilibili链接处理

    • 触发方式: 发送包含Bilibili视频链接、动态链接、番剧链接或短链接（如 b23.tv, acg.tv）的消息。
    • 功能: 机器人会自动识别链接，获取视频/动态的详细信息（标题、UP主、封面、简介等），并尝试发送视频文件（如果大小在限制内且可下载）或图片（对于动态）。如果发送媒体文件失败，则会发送文本摘要信息。

  3. 图片OCR识别 (需启用 EnableAutoOCR)

    • 触发方式1 (自动处理): 发送图片。
      • 功能: 机器人会自动对图片进行OCR识别，并将识别出的文本内容合并到消息中进行存储（主要用于后续搜索）。默认情况下不直接回复识别结果。
    • 触发方式2 (显式打印): 发送图片，并在图片的“说明/Caption”中填写文字 打印。
      • 功能: 对图片进行OCR识别，并将识别出的文本直接回复给用户。

  4. 语音/视频ASR识别 (需启用 EnableAutoASR)

    • 触发方式: 发送语音消息、音频文件或视频文件（需启用 EnableVideoASR）。
    • 功能: 机器人会自动对音频/视频进行ASR（语音转文字）处理，并将识别出的文本回复给用户。如果文本过长，可能会以 .srt 文件形式发送。识别的文本也会合并到消息中进行存储。

  5. 二维码识别与处理

    • 触发方式: 发送包含二维码的图片。
    • 功能:
      1. 机器人会自动识别图片中的二维码。
      2. 如果识别成功，会将二维码的原始文本内容直接回复给用户。
      3. 同时，机器人会将二维码的文本内容作为一条新的文本消息进行内部处理。这意味着如果二维码内容是一个URL，它可能会被后续的“自动URL解析与存储”功能进一步解析和存储。
      4. 识别出的QR文本也会被存储。

  6. 自动URL解析与存储

    • 触发方式: 用户发送任何包含URL（如 http://..., https://..., b23.tv/... 等）的消息。
    • 功能: 机器人会在后台静默地尝试解析消息中所有可识别的URL，追踪301/302重定向以获取最终的目标长链接。如果解析成功且原始链接与目标链接不同，该映射关系（原始短链接 -> 目标长链接）会被存储到数据库中，供后续快速查询或 /resolveurls 命令使用。此功能不需要用户执行任何特定命令。

  7. 消息自动存储与索引

    • 触发方式: 用户在机器人所在群组发送消息，或与机器人私聊时发送消息。机器人自身发送的消息（如LLM回复、ASR/OCR结果等）通常也会被存储。
    • 功能: 为了支持后续的“搜索”功能，机器人会自动存储接收和发送的大部分消息内容到数据库，并为这些内容建立搜索索引。
    • 说明: 这是机器人的核心功能之一，确保了搜索指令能够检索到历史消息。具体哪些消息被存储和索引取决于机器人的内部逻辑（例如，MessageService 的实现）。

四、使用提示

  • 部分自动功能（如OCR、ASR）的开启/关闭由机器人管理员在后台配置 (Env.cs 文件中对应的 Enable... 选项)。
  • 管理员指令通常需要在与机器人私聊或在机器人具有管理权限的群组中，由授权的管理员ID发送。
  • 具体可用模型名称 (设置模型 指令) 取决于机器人管理员的配置。
  • LLM工具调用迭代限制: 通过 MaxToolCycles 配置（默认25），防止LLM无限调用工具导致死循环。当达到限制时，会保存对话快照供用户选择继续或停止。
  • 文件工具: 管理员可使用内置文件工具（ReadFile, WriteFile, EditFile, SearchText, ListFiles）进行文件操作，这些工具仅管理员可用。

希望这份指南能帮助您更好地使用 TelegramSearchBot！