diff --git a/docs/plugins/api/config-api.md b/docs/plugins/api/config-api.md index e61bb6962..2a5691fc4 100644 --- a/docs/plugins/api/config-api.md +++ b/docs/plugins/api/config-api.md @@ -6,178 +6,47 @@ ```python from src.plugin_system.apis import config_api +# 或者 +from src.plugin_system import config_api ``` ## 主要功能 -### 1. 配置访问 +### 1. 访问全局配置 -#### `get_global_config(key: str, default: Any = None) -> Any` -安全地从全局配置中获取一个值 - -**参数:** -- `key`:配置键名,支持嵌套访问如 "section.subsection.key" -- `default`:如果配置不存在时返回的默认值 - -**返回:** -- `Any`:配置值或默认值 - -**示例:** ```python -# 获取机器人昵称 +def get_global_config(key: str, default: Any = None) -> Any: +``` + +**Args**: +- `key`: 命名空间式配置键名,使用嵌套访问,如 "section.subsection.key",大小写敏感 +- `default`: 如果配置不存在时返回的默认值 + +**Returns**: +- `Any`: 配置值或默认值 + +#### 示例: +获取机器人昵称 +```python bot_name = config_api.get_global_config("bot.nickname", "MaiBot") - -# 获取嵌套配置 -llm_model = config_api.get_global_config("model.default.model_name", "gpt-3.5-turbo") - -# 获取不存在的配置 -unknown_config = config_api.get_global_config("unknown.config", "默认值") ``` -#### `get_plugin_config(plugin_config: dict, key: str, default: Any = None) -> Any` -从插件配置中获取值,支持嵌套键访问 +### 2. 获取插件配置 -**参数:** -- `plugin_config`:插件配置字典 -- `key`:配置键名,支持嵌套访问如 "section.subsection.key" -- `default`:如果配置不存在时返回的默认值 - -**返回:** -- `Any`:配置值或默认值 - -**示例:** ```python -# 在插件中使用 -class MyPlugin(BasePlugin): - async def handle_action(self, action_data, chat_stream): - # 获取插件配置 - api_key = config_api.get_plugin_config(self.config, "api.key", "") - timeout = config_api.get_plugin_config(self.config, "timeout", 30) - - if not api_key: - logger.warning("API密钥未配置") - return False +def get_plugin_config(plugin_config: dict, key: str, default: Any = None) -> Any: ``` +**Args**: +- `plugin_config`: 插件配置字典 +- `key`: 配置键名,支持嵌套访问如 "section.subsection.key",大小写敏感 +- `default`: 如果配置不存在时返回的默认值 -### 2. 用户信息API - -#### `get_user_id_by_person_name(person_name: str) -> tuple[str, str]` -根据用户名获取用户ID - -**参数:** -- `person_name`:用户名 - -**返回:** -- `tuple[str, str]`:(平台, 用户ID) - -**示例:** -```python -platform, user_id = await config_api.get_user_id_by_person_name("张三") -if platform and user_id: - print(f"用户张三在{platform}平台的ID是{user_id}") -``` - -#### `get_person_info(person_id: str, key: str, default: Any = None) -> Any` -获取用户信息 - -**参数:** -- `person_id`:用户ID -- `key`:信息键名 -- `default`:默认值 - -**返回:** -- `Any`:用户信息值或默认值 - -**示例:** -```python -# 获取用户昵称 -nickname = await config_api.get_person_info(person_id, "nickname", "未知用户") - -# 获取用户印象 -impression = await config_api.get_person_info(person_id, "impression", "") -``` - -## 使用示例 - -### 配置驱动的插件开发 -```python -from src.plugin_system.apis import config_api -from src.plugin_system.base import BasePlugin - -class WeatherPlugin(BasePlugin): - async def handle_action(self, action_data, chat_stream): - # 从全局配置获取API配置 - api_endpoint = config_api.get_global_config("weather.api_endpoint", "") - default_city = config_api.get_global_config("weather.default_city", "北京") - - # 从插件配置获取特定设置 - api_key = config_api.get_plugin_config(self.config, "api_key", "") - timeout = config_api.get_plugin_config(self.config, "timeout", 10) - - if not api_key: - return {"success": False, "message": "Weather API密钥未配置"} - - # 使用配置进行天气查询... - return {"success": True, "message": f"{default_city}今天天气晴朗"} -``` - -### 用户信息查询 -```python -async def get_user_by_name(user_name: str): - """根据用户名获取完整的用户信息""" - - # 获取用户的平台和ID - platform, user_id = await config_api.get_user_id_by_person_name(user_name) - - if not platform or not user_id: - return None - - # 构建person_id - from src.person_info.person_info import PersonInfoManager - person_id = PersonInfoManager.get_person_id(platform, user_id) - - # 获取用户详细信息 - nickname = await config_api.get_person_info(person_id, "nickname", user_name) - impression = await config_api.get_person_info(person_id, "impression", "") - - return { - "platform": platform, - "user_id": user_id, - "nickname": nickname, - "impression": impression - } -``` - -## 配置键名说明 - -### 常用全局配置键 -- `bot.nickname`:机器人昵称 -- `bot.qq_account`:机器人QQ号 -- `model.default`:默认LLM模型配置 -- `database.path`:数据库路径 - -### 嵌套配置访问 -配置支持点号分隔的嵌套访问: -```python -# config.toml 中的配置: -# [bot] -# nickname = "MaiBot" -# qq_account = "123456" -# -# [model.default] -# model_name = "gpt-3.5-turbo" -# temperature = 0.7 - -# API调用: -bot_name = config_api.get_global_config("bot.nickname") -model_name = config_api.get_global_config("model.default.model_name") -temperature = config_api.get_global_config("model.default.temperature") -``` +**Returns**: +- `Any`: 配置值或默认值 ## 注意事项 1. **只读访问**:配置API只提供读取功能,插件不能修改全局配置 -2. **异步函数**:用户信息相关的函数是异步的,需要使用`await` -3. **错误处理**:所有函数都有错误处理,失败时会记录日志并返回默认值 -4. **安全性**:插件通过此API访问配置是安全和隔离的 -5. **性能**:频繁访问的配置建议在插件初始化时获取并缓存 \ No newline at end of file +2. **错误处理**:所有函数都有错误处理,失败时会记录日志并返回默认值 +3. **安全性**:插件通过此API访问配置是安全和隔离的 +4. **性能**:频繁访问的配置建议在插件初始化时获取并缓存 \ No newline at end of file diff --git a/src/plugin_system/apis/config_api.py b/src/plugin_system/apis/config_api.py index 6ec492caf..05556414e 100644 --- a/src/plugin_system/apis/config_api.py +++ b/src/plugin_system/apis/config_api.py @@ -10,7 +10,6 @@ from typing import Any from src.common.logger import get_logger from src.config.config import global_config -from src.person_info.person_info import get_person_info_manager logger = get_logger("config_api") @@ -26,7 +25,7 @@ def get_global_config(key: str, default: Any = None) -> Any: 插件应使用此方法读取全局配置,以保证只读和隔离性。 Args: - key: 命名空间式配置键名,支持嵌套访问,如 "section.subsection.key",大小写敏感 + key: 命名空间式配置键名,使用嵌套访问,如 "section.subsection.key",大小写敏感 default: 如果配置不存在时返回的默认值 Returns: @@ -76,50 +75,3 @@ def get_plugin_config(plugin_config: dict, key: str, default: Any = None) -> Any except Exception as e: logger.warning(f"[ConfigAPI] 获取插件配置 {key} 失败: {e}") return default - - -# ============================================================================= -# 用户信息API函数 -# ============================================================================= - - -async def get_user_id_by_person_name(person_name: str) -> tuple[str, str]: - """根据内部用户名获取用户ID - - Args: - person_name: 用户名 - - Returns: - tuple[str, str]: (平台, 用户ID) - """ - try: - person_info_manager = get_person_info_manager() - person_id = person_info_manager.get_person_id_by_person_name(person_name) - user_id: str = await person_info_manager.get_value(person_id, "user_id") # type: ignore - platform: str = await person_info_manager.get_value(person_id, "platform") # type: ignore - return platform, user_id - except Exception as e: - logger.error(f"[ConfigAPI] 根据用户名获取用户ID失败: {e}") - return "", "" - - -async def get_person_info(person_id: str, key: str, default: Any = None) -> Any: - """获取用户信息 - - Args: - person_id: 用户ID - key: 信息键名 - default: 默认值 - - Returns: - Any: 用户信息值或默认值 - """ - try: - person_info_manager = get_person_info_manager() - response = await person_info_manager.get_value(person_id, key) - if not response: - raise ValueError(f"[ConfigAPI] 获取用户 {person_id} 的信息 '{key}' 失败,返回默认值") - return response - except Exception as e: - logger.error(f"[ConfigAPI] 获取用户信息失败: {e}") - return default