config_api_doc
This commit is contained in:
UnCLAS-Prommer
@@ -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. **性能**：频繁访问的配置建议在插件初始化时获取并缓存
|
||||
2. **错误处理**：所有函数都有错误处理，失败时会记录日志并返回默认值
|
||||
3. **安全性**：插件通过此API访问配置是安全和隔离的
|
||||
4. **性能**：频繁访问的配置建议在插件初始化时获取并缓存
|
||||
Reference in New Issue
Block a user