565 lines
17 KiB
Markdown
565 lines
17 KiB
Markdown
# 💻 Command组件详解
|
||
|
||
## 📖 什么是Command
|
||
|
||
Command是直接响应用户明确指令的组件，与Action不同，Command是**被动触发**的，当用户输入特定格式的命令时立即执行。Command通过正则表达式匹配用户输入，提供确定性的功能服务。
|
||
|
||
### 🎯 Command的特点
|
||
|
||
- 🎯 **确定性执行**：匹配到命令立即执行，无随机性
|
||
- ⚡ **即时响应**：用户主动触发，快速响应
|
||
- 🔍 **正则匹配**：通过正则表达式精确匹配用户输入
|
||
- 🛑 **拦截控制**：可以控制是否阻止消息继续处理
|
||
- 📝 **参数解析**：支持从用户输入中提取参数
|
||
|
||
## 🆚 Action vs Command 核心区别
|
||
|
||
| 特征 | Action | Command |
|
||
|-----|-------|---------|
|
||
| **触发方式** | 麦麦主动决策使用 | 用户主动触发 |
|
||
| **决策机制** | 两层决策（激活+使用） | 直接匹配执行 |
|
||
| **随机性** | 有随机性和智能性 | 确定性执行 |
|
||
| **用途** | 增强麦麦行为拟人化 | 提供具体功能服务 |
|
||
| **性能影响** | 需要LLM决策 | 正则匹配，性能好 |
|
||
|
||
## 🏗️ Command基本结构
|
||
|
||
### 必须属性
|
||
|
||
```python
|
||
from src.plugin_system import BaseCommand
|
||
|
||
class MyCommand(BaseCommand):
|
||
# 正则表达式匹配模式
|
||
command_pattern = r"^/help\s+(?P<topic>\w+)$"
|
||
|
||
# 命令帮助说明
|
||
command_help = "显示指定主题的帮助信息"
|
||
|
||
# 使用示例
|
||
command_examples = ["/help action", "/help command"]
|
||
|
||
# 是否拦截后续处理
|
||
intercept_message = True
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
"""执行命令逻辑"""
|
||
# 命令执行逻辑
|
||
return True, "执行成功"
|
||
```
|
||
|
||
### 属性说明
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| `command_pattern` | str | 正则表达式匹配模式 |
|
||
| `command_help` | str | 命令帮助说明 |
|
||
| `command_examples` | List[str] | 使用示例列表 |
|
||
| `intercept_message` | bool | 是否拦截消息继续处理 |
|
||
|
||
## 🔍 正则表达式匹配
|
||
|
||
### 基础匹配
|
||
|
||
```python
|
||
class SimpleCommand(BaseCommand):
|
||
# 匹配 /ping
|
||
command_pattern = r"^/ping$"
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
await self.send_text("Pong!")
|
||
return True, "发送了Pong回复"
|
||
```
|
||
|
||
### 参数捕获
|
||
|
||
使用命名组 `(?P<n>pattern)` 捕获参数：
|
||
|
||
```python
|
||
class UserCommand(BaseCommand):
|
||
# 匹配 /user add 张三 或 /user del 李四
|
||
command_pattern = r"^/user\s+(?P<action>add|del|info)\s+(?P<username>\w+)$"
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
# 通过 self.matched_groups 获取捕获的参数
|
||
action = self.matched_groups.get("action")
|
||
username = self.matched_groups.get("username")
|
||
|
||
if action == "add":
|
||
await self.send_text(f"添加用户：{username}")
|
||
elif action == "del":
|
||
await self.send_text(f"删除用户：{username}")
|
||
elif action == "info":
|
||
await self.send_text(f"用户信息：{username}")
|
||
|
||
return True, f"执行了{action}操作"
|
||
```
|
||
|
||
### 可选参数
|
||
|
||
```python
|
||
class HelpCommand(BaseCommand):
|
||
# 匹配 /help 或 /help topic
|
||
command_pattern = r"^/help(?:\s+(?P<topic>\w+))?$"
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
topic = self.matched_groups.get("topic")
|
||
|
||
if topic:
|
||
await self.send_text(f"显示{topic}的帮助")
|
||
else:
|
||
await self.send_text("显示总体帮助")
|
||
|
||
return True, "显示了帮助信息"
|
||
```
|
||
|
||
## 🛑 拦截控制详解
|
||
|
||
### 拦截消息 (intercept_message = True)
|
||
|
||
```python
|
||
class AdminCommand(BaseCommand):
|
||
command_pattern = r"^/admin\s+.+"
|
||
command_help = "管理员命令"
|
||
intercept_message = True # 拦截，不继续处理
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
# 执行管理操作
|
||
await self.send_text("执行管理命令")
|
||
# 消息不会继续传递给其他组件
|
||
return True, "管理命令执行完成"
|
||
```
|
||
|
||
### 不拦截消息 (intercept_message = False)
|
||
|
||
```python
|
||
class LogCommand(BaseCommand):
|
||
command_pattern = r"^/log\s+.+"
|
||
command_help = "记录日志"
|
||
intercept_message = False # 不拦截，继续处理
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
# 记录日志但不阻止后续处理
|
||
await self.send_text("已记录到日志")
|
||
# 消息会继续传递，可能触发Action等其他组件
|
||
return True, "日志记录完成"
|
||
```
|
||
|
||
### 拦截控制的用途
|
||
|
||
| 场景 | intercept_message | 说明 |
|
||
|-----|------------------|------|
|
||
| 系统命令 | True | 防止命令被当作普通消息处理 |
|
||
| 查询命令 | True | 直接返回结果，无需后续处理 |
|
||
| 日志命令 | False | 记录但允许消息继续流转 |
|
||
| 监控命令 | False | 监控但不影响正常聊天 |
|
||
|
||
## 🎨 完整Command示例
|
||
|
||
### 用户管理Command
|
||
|
||
```python
|
||
from src.plugin_system import BaseCommand
|
||
from typing import Tuple, Optional
|
||
|
||
class UserManagementCommand(BaseCommand):
|
||
"""用户管理Command - 展示复杂参数处理"""
|
||
|
||
command_pattern = r"^/user\s+(?P<action>add|del|list|info)\s*(?P<username>\w+)?(?:\s+--(?P<options>.+))?$"
|
||
command_help = "用户管理命令，支持添加、删除、列表、信息查询"
|
||
command_examples = [
|
||
"/user add 张三",
|
||
"/user del 李四",
|
||
"/user list",
|
||
"/user info 王五",
|
||
"/user add 赵六 --role=admin"
|
||
]
|
||
intercept_message = True
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
"""执行用户管理命令"""
|
||
try:
|
||
action = self.matched_groups.get("action")
|
||
username = self.matched_groups.get("username")
|
||
options = self.matched_groups.get("options")
|
||
|
||
# 解析选项
|
||
parsed_options = self._parse_options(options) if options else {}
|
||
|
||
if action == "add":
|
||
return await self._add_user(username, parsed_options)
|
||
elif action == "del":
|
||
return await self._delete_user(username)
|
||
elif action == "list":
|
||
return await self._list_users()
|
||
elif action == "info":
|
||
return await self._show_user_info(username)
|
||
else:
|
||
await self.send_text("❌ 不支持的操作")
|
||
return False, f"不支持的操作: {action}"
|
||
|
||
except Exception as e:
|
||
await self.send_text(f"❌ 命令执行失败: {str(e)}")
|
||
return False, f"执行失败: {e}"
|
||
|
||
def _parse_options(self, options_str: str) -> dict:
|
||
"""解析命令选项"""
|
||
options = {}
|
||
if options_str:
|
||
for opt in options_str.split():
|
||
if "=" in opt:
|
||
key, value = opt.split("=", 1)
|
||
options[key] = value
|
||
return options
|
||
|
||
async def _add_user(self, username: str, options: dict) -> Tuple[bool, str]:
|
||
"""添加用户"""
|
||
if not username:
|
||
await self.send_text("❌ 请指定用户名")
|
||
return False, "缺少用户名参数"
|
||
|
||
# 检查用户是否已存在
|
||
existing_users = await self._get_user_list()
|
||
if username in existing_users:
|
||
await self.send_text(f"❌ 用户 {username} 已存在")
|
||
return False, f"用户已存在: {username}"
|
||
|
||
# 添加用户逻辑
|
||
role = options.get("role", "user")
|
||
await self.send_text(f"✅ 成功添加用户 {username}，角色: {role}")
|
||
return True, f"添加用户成功: {username}"
|
||
|
||
async def _delete_user(self, username: str) -> Tuple[bool, str]:
|
||
"""删除用户"""
|
||
if not username:
|
||
await self.send_text("❌ 请指定用户名")
|
||
return False, "缺少用户名参数"
|
||
|
||
await self.send_text(f"✅ 用户 {username} 已删除")
|
||
return True, f"删除用户成功: {username}"
|
||
|
||
async def _list_users(self) -> Tuple[bool, str]:
|
||
"""列出所有用户"""
|
||
users = await self._get_user_list()
|
||
if users:
|
||
user_list = "\n".join([f"• {user}" for user in users])
|
||
await self.send_text(f"📋 用户列表:\n{user_list}")
|
||
else:
|
||
await self.send_text("📋 暂无用户")
|
||
return True, "显示用户列表"
|
||
|
||
async def _show_user_info(self, username: str) -> Tuple[bool, str]:
|
||
"""显示用户信息"""
|
||
if not username:
|
||
await self.send_text("❌ 请指定用户名")
|
||
return False, "缺少用户名参数"
|
||
|
||
# 模拟用户信息
|
||
user_info = f"""
|
||
👤 用户信息: {username}
|
||
📧 邮箱: {username}@example.com
|
||
🕒 注册时间: 2024-01-01
|
||
🎯 角色: 普通用户
|
||
""".strip()
|
||
|
||
await self.send_text(user_info)
|
||
return True, f"显示用户信息: {username}"
|
||
|
||
async def _get_user_list(self) -> list:
|
||
"""获取用户列表（示例）"""
|
||
return ["张三", "李四", "王五"]
|
||
```
|
||
|
||
### 系统信息Command
|
||
|
||
```python
|
||
class SystemInfoCommand(BaseCommand):
|
||
"""系统信息Command - 展示系统查询功能"""
|
||
|
||
command_pattern = r"^/(?:status|info)(?:\s+(?P<type>system|memory|plugins|all))?$"
|
||
command_help = "查询系统状态信息"
|
||
command_examples = [
|
||
"/status",
|
||
"/info system",
|
||
"/status memory",
|
||
"/info plugins"
|
||
]
|
||
intercept_message = True
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
"""执行系统信息查询"""
|
||
info_type = self.matched_groups.get("type", "all")
|
||
|
||
try:
|
||
if info_type in ["system", "all"]:
|
||
await self._show_system_info()
|
||
|
||
if info_type in ["memory", "all"]:
|
||
await self._show_memory_info()
|
||
|
||
if info_type in ["plugins", "all"]:
|
||
await self._show_plugin_info()
|
||
|
||
return True, f"显示了{info_type}类型的系统信息"
|
||
|
||
except Exception as e:
|
||
await self.send_text(f"❌ 获取系统信息失败: {str(e)}")
|
||
return False, f"查询失败: {e}"
|
||
|
||
async def _show_system_info(self):
|
||
"""显示系统信息"""
|
||
import platform
|
||
import datetime
|
||
|
||
system_info = f"""
|
||
🖥️ **系统信息**
|
||
📱 平台: {platform.system()} {platform.release()}
|
||
🐍 Python: {platform.python_version()}
|
||
⏰ 运行时间: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
|
||
""".strip()
|
||
|
||
await self.send_text(system_info)
|
||
|
||
async def _show_memory_info(self):
|
||
"""显示内存信息"""
|
||
import psutil
|
||
|
||
memory = psutil.virtual_memory()
|
||
memory_info = f"""
|
||
💾 **内存信息**
|
||
📊 总内存: {memory.total // (1024**3)} GB
|
||
🟢 可用内存: {memory.available // (1024**3)} GB
|
||
📈 使用率: {memory.percent}%
|
||
""".strip()
|
||
|
||
await self.send_text(memory_info)
|
||
|
||
async def _show_plugin_info(self):
|
||
"""显示插件信息"""
|
||
# 通过配置获取插件信息
|
||
plugins = await self._get_loaded_plugins()
|
||
|
||
plugin_info = f"""
|
||
🔌 **插件信息**
|
||
📦 已加载插件: {len(plugins)}
|
||
🔧 活跃插件: {len([p for p in plugins if p.get('active', False)])}
|
||
""".strip()
|
||
|
||
await self.send_text(plugin_info)
|
||
|
||
async def _get_loaded_plugins(self) -> list:
|
||
"""获取已加载的插件列表"""
|
||
# 这里可以通过配置或API获取实际的插件信息
|
||
return [
|
||
{"name": "core_actions", "active": True},
|
||
{"name": "example_plugin", "active": True},
|
||
]
|
||
```
|
||
|
||
### 自定义前缀Command
|
||
|
||
```python
|
||
class CustomPrefixCommand(BaseCommand):
|
||
"""自定义前缀Command - 展示非/前缀的命令"""
|
||
|
||
# 使用!前缀而不是/前缀
|
||
command_pattern = r"^[!！](?P<command>roll|dice)\s*(?P<count>\d+)?$"
|
||
command_help = "骰子命令，使用!前缀"
|
||
command_examples = ["!roll", "!dice 6", "！roll 20"]
|
||
intercept_message = True
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
"""执行骰子命令"""
|
||
import random
|
||
|
||
command = self.matched_groups.get("command")
|
||
count = int(self.matched_groups.get("count", "6"))
|
||
|
||
# 限制骰子面数
|
||
if count > 100:
|
||
await self.send_text("❌ 骰子面数不能超过100")
|
||
return False, "骰子面数超限"
|
||
|
||
result = random.randint(1, count)
|
||
await self.send_text(f"🎲 投掷{count}面骰子，结果: {result}")
|
||
|
||
return True, f"投掷了{count}面骰子，结果{result}"
|
||
```
|
||
|
||
## 🔧 新API格式使用指南
|
||
|
||
### 消息发送
|
||
|
||
```python
|
||
# 新API格式 ✅
|
||
await self.send_text("消息内容")
|
||
await self.send_emoji("😊")
|
||
|
||
# 旧API格式 ❌
|
||
await self.api.send_text_to_group("消息内容", group_id, "qq")
|
||
```
|
||
|
||
### 配置访问
|
||
|
||
```python
|
||
# 新API格式 ✅
|
||
config_value = self.get_config("section.key", "default_value")
|
||
|
||
# 旧API格式 ❌
|
||
config_value = self.api.get_config("section.key", "default_value")
|
||
```
|
||
|
||
### 用户信息获取
|
||
|
||
```python
|
||
# 新API格式 ✅
|
||
user_id = self.user_id
|
||
user_nickname = self.user_nickname
|
||
is_group_chat = self.is_group
|
||
|
||
# 旧API格式 ❌
|
||
user_id = self.message.message_info.user_info.user_id
|
||
```
|
||
|
||
### 动作记录
|
||
|
||
```python
|
||
# 新API格式 ✅ (在Action中)
|
||
await self.store_action_info(
|
||
action_build_into_prompt=True,
|
||
action_prompt_display="执行了某操作",
|
||
action_done=True
|
||
)
|
||
|
||
# 旧API格式 ❌
|
||
await self.api.store_action_info(...)
|
||
```
|
||
|
||
## 📊 性能优化建议
|
||
|
||
### 1. 正则表达式优化
|
||
|
||
```python
|
||
# ✅ 好的做法 - 简单直接
|
||
command_pattern = r"^/ping$"
|
||
|
||
# ❌ 避免 - 过于复杂
|
||
command_pattern = r"^/(?:ping|pong|test|check|status|info|help|...)"
|
||
|
||
# ✅ 好的做法 - 分离复杂逻辑
|
||
```
|
||
|
||
### 2. 参数验证
|
||
|
||
```python
|
||
# ✅ 好的做法 - 早期验证
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
username = self.matched_groups.get("username")
|
||
if not username:
|
||
await self.send_text("❌ 请提供用户名")
|
||
return False, "缺少参数"
|
||
|
||
# 继续处理...
|
||
```
|
||
|
||
### 3. 错误处理
|
||
|
||
```python
|
||
# ✅ 好的做法 - 完整错误处理
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
try:
|
||
# 主要逻辑
|
||
result = await self._process_command()
|
||
return True, "执行成功"
|
||
except ValueError as e:
|
||
await self.send_text(f"❌ 参数错误: {e}")
|
||
return False, f"参数错误: {e}"
|
||
except Exception as e:
|
||
await self.send_text(f"❌ 执行失败: {e}")
|
||
return False, f"执行失败: {e}"
|
||
```
|
||
|
||
通过新的API格式，Command开发变得更加简洁和直观！
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 命令设计原则
|
||
|
||
```python
|
||
# ✅ 好的命令设计
|
||
"/user add 张三" # 动作 + 对象 + 参数
|
||
"/config set key=value" # 动作 + 子动作 + 参数
|
||
"/help command" # 动作 + 可选参数
|
||
|
||
# ❌ 避免的设计
|
||
"/add_user_with_name_张三" # 过于冗长
|
||
"/u a 张三" # 过于简写
|
||
```
|
||
|
||
### 2. 帮助信息
|
||
|
||
```python
|
||
class WellDocumentedCommand(BaseCommand):
|
||
command_pattern = r"^/example\s+(?P<param>\w+)$"
|
||
command_help = "示例命令：处理指定参数并返回结果"
|
||
command_examples = [
|
||
"/example test",
|
||
"/example debug",
|
||
"/example production"
|
||
]
|
||
```
|
||
|
||
### 3. 错误处理
|
||
|
||
```python
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
param = self.matched_groups.get("param")
|
||
|
||
# 参数验证
|
||
if param not in ["test", "debug", "production"]:
|
||
await self.send_text("❌ 无效的参数，支持: test, debug, production")
|
||
return False, "无效参数"
|
||
|
||
# 执行逻辑
|
||
try:
|
||
result = await self._process_param(param)
|
||
await self.send_text(f"✅ 处理完成: {result}")
|
||
return True, f"处理{param}成功"
|
||
except Exception as e:
|
||
await self.send_text("❌ 处理失败，请稍后重试")
|
||
return False, f"处理失败: {e}"
|
||
```
|
||
|
||
### 4. 配置集成
|
||
|
||
```python
|
||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||
# 从配置读取设置
|
||
max_items = self.api.get_config("command.max_items", 10)
|
||
timeout = self.api.get_config("command.timeout", 30)
|
||
|
||
# 使用配置进行处理
|
||
...
|
||
```
|
||
|
||
## 📝 Command vs Action 选择指南
|
||
|
||
### 使用Command的场景
|
||
|
||
- ✅ 用户需要明确调用特定功能
|
||
- ✅ 需要精确的参数控制
|
||
- ✅ 管理和配置操作
|
||
- ✅ 查询和信息显示
|
||
- ✅ 系统维护命令
|
||
|
||
### 使用Action的场景
|
||
|
||
- ✅ 增强麦麦的智能行为
|
||
- ✅ 根据上下文自动触发
|
||
- ✅ 情绪和表情表达
|
||
- ✅ 智能建议和帮助
|
||
- ✅ 随机化的互动
|
||
|
||
---
|
||
|
||
🎉 **现在你已经掌握了Command组件开发的完整知识！继续学习 [API参考](api/) 来了解所有可用的接口。** |