From 6a57ec1d5dc83e5a25b13c856dc900fbe8ddccd2 Mon Sep 17 00:00:00 2001 From: UnCLAS-Prommer Date: Sun, 27 Jul 2025 22:32:19 +0800 Subject: [PATCH] person_api_doc --- docs/plugins/api/person-api.md | 305 +++++---------------------------- 1 file changed, 41 insertions(+), 264 deletions(-) diff --git a/docs/plugins/api/person-api.md b/docs/plugins/api/person-api.md index 3e1bafaf7..f97498dcc 100644 --- a/docs/plugins/api/person-api.md +++ b/docs/plugins/api/person-api.md @@ -6,59 +6,65 @@ ```python from src.plugin_system.apis import person_api +# 或者 +from src.plugin_system import person_api ``` ## 主要功能 -### 1. Person ID管理 - -#### `get_person_id(platform: str, user_id: int) -> str` +### 1. Person ID 获取 +```python +def get_person_id(platform: str, user_id: int) -> str: +``` 根据平台和用户ID获取person_id -**参数：** +**Args:** - `platform`：平台名称，如 "qq", "telegram" 等 - `user_id`：用户ID -**返回：** +**Returns:** - `str`：唯一的person_id（MD5哈希值） -**示例：** +#### 示例 ```python person_id = person_api.get_person_id("qq", 123456) -print(f"Person ID: {person_id}") ``` ### 2. 用户信息查询 +```python +async def get_person_value(person_id: str, field_name: str, default: Any = None) -> Any: +``` +查询单个用户信息字段值 -#### `get_person_value(person_id: str, field_name: str, default: Any = None) -> Any` -根据person_id和字段名获取某个值 - -**参数：** +**Args:** - `person_id`：用户的唯一标识ID -- `field_name`：要获取的字段名，如 "nickname", "impression" 等 -- `default`：当字段不存在或获取失败时返回的默认值 +- `field_name`：要获取的字段名 +- `default`：字段值不存在时的默认值 -**返回：** +**Returns:** - `Any`：字段值或默认值 -**示例：** +#### 示例 ```python nickname = await person_api.get_person_value(person_id, "nickname", "未知用户") impression = await person_api.get_person_value(person_id, "impression") ``` -#### `get_person_values(person_id: str, field_names: list, default_dict: dict = None) -> dict` +### 3. 批量用户信息查询 +```python +async def get_person_values(person_id: str, field_names: list, default_dict: Optional[dict] = None) -> dict: +``` 批量获取用户信息字段值 -**参数：** +**Args:** - `person_id`：用户的唯一标识ID - `field_names`：要获取的字段名列表 - `default_dict`：默认值字典，键为字段名，值为默认值 -**返回：** +**Returns:** - `dict`：字段名到值的映射字典 -**示例：** +#### 示例 ```python values = await person_api.get_person_values( person_id, @@ -67,204 +73,31 @@ values = await person_api.get_person_values( ) ``` -### 3. 用户状态查询 - -#### `is_person_known(platform: str, user_id: int) -> bool` +### 4. 判断用户是否已知 +```python +async def is_person_known(platform: str, user_id: int) -> bool: +``` 判断是否认识某个用户 -**参数：** +**Args:** - `platform`：平台名称 - `user_id`：用户ID -**返回：** +**Returns:** - `bool`：是否认识该用户 -**示例：** +### 5. 根据用户名获取Person ID ```python -known = await person_api.is_person_known("qq", 123456) -if known: - print("这个用户我认识") +def get_person_id_by_name(person_name: str) -> str: ``` - -### 4. 用户名查询 - -#### `get_person_id_by_name(person_name: str) -> str` 根据用户名获取person_id -**参数：** +**Args:** - `person_name`：用户名 -**返回：** +**Returns:** - `str`：person_id，如果未找到返回空字符串 -**示例：** -```python -person_id = person_api.get_person_id_by_name("张三") -if person_id: - print(f"找到用户: {person_id}") -``` - -## 使用示例 - -### 1. 基础用户信息获取 - -```python -from src.plugin_system.apis import person_api - -async def get_user_info(platform: str, user_id: int): - """获取用户基本信息""" - - # 获取person_id - person_id = person_api.get_person_id(platform, user_id) - - # 获取用户信息 - user_info = await person_api.get_person_values( - person_id, - ["nickname", "impression", "know_times", "last_seen"], - { - "nickname": "未知用户", - "impression": "", - "know_times": 0, - "last_seen": 0 - } - ) - - return { - "person_id": person_id, - "nickname": user_info["nickname"], - "impression": user_info["impression"], - "know_times": user_info["know_times"], - "last_seen": user_info["last_seen"] - } -``` - -### 2. 在Action中使用用户信息 - -```python -from src.plugin_system.base import BaseAction - -class PersonalizedAction(BaseAction): - async def execute(self, action_data, chat_stream): - # 获取发送者信息 - user_id = chat_stream.user_info.user_id - platform = chat_stream.platform - - # 获取person_id - person_id = person_api.get_person_id(platform, user_id) - - # 获取用户昵称和印象 - nickname = await person_api.get_person_value(person_id, "nickname", "朋友") - impression = await person_api.get_person_value(person_id, "impression", "") - - # 根据用户信息个性化回复 - if impression: - response = f"你好 {nickname}！根据我对你的了解：{impression}" - else: - response = f"你好 {nickname}！很高兴见到你。" - - return { - "success": True, - "response": response, - "user_info": { - "nickname": nickname, - "impression": impression - } - } -``` - -### 3. 用户识别和欢迎 - -```python -async def welcome_user(chat_stream): - """欢迎用户，区分新老用户""" - - user_id = chat_stream.user_info.user_id - platform = chat_stream.platform - - # 检查是否认识这个用户 - is_known = await person_api.is_person_known(platform, user_id) - - if is_known: - # 老用户，获取详细信息 - person_id = person_api.get_person_id(platform, user_id) - nickname = await person_api.get_person_value(person_id, "nickname", "老朋友") - know_times = await person_api.get_person_value(person_id, "know_times", 0) - - welcome_msg = f"欢迎回来，{nickname}！我们已经聊过 {know_times} 次了。" - else: - # 新用户 - welcome_msg = "你好！很高兴认识你，我是MaiBot。" - - return welcome_msg -``` - -### 4. 用户搜索功能 - -```python -async def find_user_by_name(name: str): - """根据名字查找用户""" - - person_id = person_api.get_person_id_by_name(name) - - if not person_id: - return {"found": False, "message": f"未找到名为 '{name}' 的用户"} - - # 获取用户详细信息 - user_info = await person_api.get_person_values( - person_id, - ["nickname", "platform", "user_id", "impression", "know_times"], - {} - ) - - return { - "found": True, - "person_id": person_id, - "info": user_info - } -``` - -### 5. 用户印象分析 - -```python -async def analyze_user_relationship(chat_stream): - """分析用户关系""" - - user_id = chat_stream.user_info.user_id - platform = chat_stream.platform - person_id = person_api.get_person_id(platform, user_id) - - # 获取关系相关信息 - relationship_info = await person_api.get_person_values( - person_id, - ["nickname", "impression", "know_times", "relationship_level", "last_interaction"], - { - "nickname": "未知", - "impression": "", - "know_times": 0, - "relationship_level": "stranger", - "last_interaction": 0 - } - ) - - # 分析关系程度 - know_times = relationship_info["know_times"] - if know_times == 0: - relationship = "陌生人" - elif know_times < 5: - relationship = "新朋友" - elif know_times < 20: - relationship = "熟人" - else: - relationship = "老朋友" - - return { - "nickname": relationship_info["nickname"], - "relationship": relationship, - "impression": relationship_info["impression"], - "interaction_count": know_times - } -``` - ## 常用字段说明 ### 基础信息字段 @@ -274,69 +107,13 @@ async def analyze_user_relationship(chat_stream): ### 关系信息字段 - `impression`：对用户的印象 -- `know_times`：交互次数 -- `relationship_level`：关系等级 -- `last_seen`：最后见面时间 -- `last_interaction`：最后交互时间 +- `points`: 用户特征点 -### 个性化字段 -- `preferences`：用户偏好 -- `interests`：兴趣爱好 -- `mood_history`：情绪历史 -- `topic_interests`：话题兴趣 - -## 最佳实践 - -### 1. 错误处理 -```python -async def safe_get_user_info(person_id: str, field: str): - """安全获取用户信息""" - try: - value = await person_api.get_person_value(person_id, field) - return value if value is not None else "未设置" - except Exception as e: - logger.error(f"获取用户信息失败: {e}") - return "获取失败" -``` - -### 2. 批量操作 -```python -async def get_complete_user_profile(person_id: str): - """获取完整用户档案""" - - # 一次性获取所有需要的字段 - fields = [ - "nickname", "impression", "know_times", - "preferences", "interests", "relationship_level" - ] - - defaults = { - "nickname": "用户", - "impression": "", - "know_times": 0, - "preferences": "{}", - "interests": "[]", - "relationship_level": "stranger" - } - - profile = await person_api.get_person_values(person_id, fields, defaults) - - # 处理JSON字段 - try: - profile["preferences"] = json.loads(profile["preferences"]) - profile["interests"] = json.loads(profile["interests"]) - except: - profile["preferences"] = {} - profile["interests"] = [] - - return profile -``` +其他字段可以参考`PersonInfo`类的属性（位于`src.common.database.database_model`） ## 注意事项 -1. **异步操作**：大部分查询函数都是异步的，需要使用`await` -2. **错误处理**：所有函数都有错误处理，失败时记录日志并返回默认值 -3. **数据类型**：返回的数据可能是字符串、数字或JSON，需要适当处理 -4. **性能考虑**：批量查询优于单个查询 -5. **隐私保护**：确保用户信息的使用符合隐私政策 -6. **数据一致性**：person_id是用户的唯一标识，应妥善保存和使用 \ No newline at end of file +1. **异步操作**：部分查询函数都是异步的，需要使用`await` +2. **性能考虑**：批量查询优于单个查询 +3. **隐私保护**：确保用户信息的使用符合隐私政策 +4. **数据一致性**：person_id是用户的唯一标识，应妥善保存和使用 \ No newline at end of file