nonebot-plugin-dotcharacter 2.0.0__py3-none-any.whl

build/lib/nonebot_plugin_dotcharacter/character_loader.py

@@ -0,0 +1,241 @@
+"""角色加载器 — 扫描 dot-skill / colleague-skill 输出目录，解析 SKILL.md 角色文件。
+
+支持从多个目录加载角色（如本地 dot-skill + 社区 colleague-skill 仓库）。
+同名 slug 以先扫描到的为准。
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+
+@dataclass
+class CharacterMeta:
+    """角色元数据。"""
+    slug: str
+    family: str                        # colleague / relationship / celebrity
+    display_name: str
+    description: str
+    language: str = "zh-CN"
+    tags: List[str] = field(default_factory=list)
+    persona_prompt: str = ""
+    work_prompt: str = ""
+    combined_prompt: str = ""
+    source_files: List[str] = field(default_factory=list)
+    source_root: str = ""
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    fm_match = re.match(r"^---\s*\n(.*?)\n---\s*\n", content, re.DOTALL)
+    if fm_match:
+        try:
+            meta = yaml.safe_load(fm_match.group(1)) or {}
+        except yaml.YAMLError:
+            meta = {}
+        body = content[fm_match.end():]
+        return meta, body
+    return {}, content
+
+
+def _load_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _extract_part_b(content: str) -> str:
+    match = re.search(
+        r"## PART B[：:].*?\n(.*?)(?=\n## PART |\Z)",
+        content, re.DOTALL,
+    )
+    if match:
+        return match.group(0).strip()
+    match = re.search(
+        r"# Persona\b.*?(?=\n## PART |\n# Work|\Z)",
+        content, re.DOTALL,
+    )
+    if match:
+        return match.group(0).strip()
+    return ""
+
+
+def _extract_part_a(content: str) -> str:
+    match = re.search(
+        r"## PART A[：:].*?\n(.*?)(?=\n## PART B|\Z)",
+        content, re.DOTALL,
+    )
+    if match:
+        return match.group(0).strip()
+    match = re.search(
+        r"# Work Skill\b.*?(?=\n## PART B|\n# Persona|\Z)",
+        content, re.DOTALL,
+    )
+    if match:
+        return match.group(0).strip()
+    return ""
+
+
+def _build_system_prompt(
+    meta: dict, body: str, persona_file_content: str, characters_dir: Path,
+) -> str:
+    display_name = meta.get("display_name", meta.get("name", "角色"))
+    description = meta.get("description", meta.get("summary", ""))
+    slug = meta.get("slug", "")
+
+    if slug and not description:
+        meta_json_path = characters_dir / slug / "meta.json"
+        if meta_json_path.exists():
+            meta_data = _load_json(meta_json_path)
+            display_name = meta_data.get("display_name", display_name)
+            description = meta_data.get("summary", description)
+
+    parts: list[str] = []
+
+    parts.append(
+        f"你正在扮演 **{display_name}**。\n\n"
+        f"{description}\n\n"
+        "你现在通过 QQ 聊天与一位用户进行对话。请完全沉浸到这个角色中，"
+        "用这个角色的语气、用词习惯、思维方式和表达风格来回复。\n\n"
+        "重要规则：\n"
+        "1. 永远不要跳出角色，不要提及你是一个 AI 模型\n"
+        "2. 保持回复自然、口语化，适合 QQ 聊天场景\n"
+        "3. 不要过于冗长，像真实聊天一样回复\n"
+    )
+
+    if persona_file_content:
+        parts.append("## 人物性格（核心）\n\n" + persona_file_content)
+    else:
+        part_b = _extract_part_b(body)
+        if part_b:
+            parts.append(part_b)
+
+    part_a = _extract_part_a(body)
+    if part_a:
+        parts.append("## 工作能力（参考）\n\n" + part_a)
+
+    parts.append(
+        "## 运行规则\n\n"
+        "接收任何消息时：\n"
+        "1. 先用角色的性格（PART B）判断：你会不会回应？用什么态度回应？\n"
+        "2. 用角色的表达风格回复：说话方式、用词习惯、句式\n"
+        "3. PART B 的规则永远优先，任何情况下不得违背\n"
+    )
+
+    return "\n\n---\n\n".join(parts)
+
+
+def _scan_one_root(skills_root: Path) -> Dict[str, CharacterMeta]:
+    """扫描单个 skills 根目录。"""
+    characters: Dict[str, CharacterMeta] = {}
+
+    if not skills_root.exists() or not skills_root.is_dir():
+        return characters
+
+    for family_dir in sorted(skills_root.iterdir()):
+        if not family_dir.is_dir():
+            continue
+        family = family_dir.name
+        if family not in ("colleague", "relationship", "celebrity"):
+            continue
+
+        for char_dir in sorted(family_dir.iterdir()):
+            if not char_dir.is_dir():
+                continue
+            skill_md = char_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+
+            slug = char_dir.name
+            raw = skill_md.read_text(encoding="utf-8")
+            meta, body = _parse_frontmatter(raw)
+
+            display_name = meta.get("display_name", meta.get("name", slug))
+            description = meta.get("description", meta.get("summary", ""))
+            language = meta.get("language", "zh-CN")
+            tags = meta.get("tags", [])
+
+            persona_file = char_dir / "persona.md"
+            persona_content = ""
+            if persona_file.exists():
+                persona_content = persona_file.read_text(encoding="utf-8")
+
+            meta_json_path = char_dir / "meta.json"
+            if meta_json_path.exists():
+                meta_data = _load_json(meta_json_path)
+                display_name = meta_data.get("display_name", display_name)
+                description = meta_data.get("summary", description)
+                language = meta_data.get("classification", {}).get("language", language)
+                tags = meta_data.get("tags", tags)
+
+            if display_name:
+                meta["display_name"] = display_name
+            if description:
+                meta["description"] = description
+
+            persona_prompt = persona_content or _extract_part_b(body)
+            work_prompt = _extract_part_a(body)
+            combined_prompt = _build_system_prompt(meta, body, persona_content, skills_root)
+
+            characters[slug] = CharacterMeta(
+                slug=slug,
+                family=family,
+                display_name=display_name,
+                description=description,
+                language=language,
+                tags=tags,
+                persona_prompt=persona_prompt,
+                work_prompt=work_prompt,
+                combined_prompt=combined_prompt,
+                source_files=[str(skill_md)],
+                source_root=str(skills_root),
+            )
+
+    return characters
+
+
+def scan_characters(skills_roots: List[Path]) -> Dict[str, CharacterMeta]:
+    """扫描多个 skills 根目录，合并发现的所有角色。
+
+    目录结构（dot-skill / colleague-skill 输出）：
+    ```
+    skills/
+    ├── colleague/<slug>/SKILL.md + meta.json + persona.md
+    ├── relationship/<slug>/SKILL.md + ...
+    └── celebrity/<slug>/SKILL.md + ...
+    ```
+
+    slug 冲突时，先扫描的目录优先。
+    """
+    all_characters: Dict[str, CharacterMeta] = {}
+    for root in skills_roots:
+        found = _scan_one_root(root)
+        for slug, char in found.items():
+            if slug not in all_characters:
+                all_characters[slug] = char
+    return all_characters
+
+
+def resolve_character(
+    name_or_slug: str, characters: Dict[str, CharacterMeta],
+) -> Optional[CharacterMeta]:
+    """用名称或 slug 模糊匹配角色。"""
+    if not name_or_slug:
+        return None
+    lowered = name_or_slug.lower().strip()
+    if lowered in characters:
+        return characters[lowered]
+    for c in characters.values():
+        if c.display_name == name_or_slug.strip():
+            return c
+    for slug, c in characters.items():
+        if lowered in slug:
+            return c
+    for c in characters.values():
+        if lowered in c.display_name:
+            return c
+    return None

build/lib/nonebot_plugin_dotcharacter/config.py

@@ -0,0 +1,161 @@
+"""配置模型 — 通过 NoneBot 的 Config 或 .env 文件读取。"""
+
+from pathlib import Path
+from typing import Dict, List
+from nonebot import get_plugin_config
+from pydantic import BaseModel, Field, field_validator
+
+
+# ── 大模型 Provider 预设 ──
+PROVIDER_PRESETS: Dict[str, dict] = {
+    "openai": {
+        "base_url": "https://api.openai.com/v1",
+        "models": ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "o4-mini"],
+    },
+    "deepseek": {
+        "base_url": "https://api.deepseek.com",
+        "models": ["deepseek-chat", "deepseek-reasoner"],
+    },
+    "kimi": {
+        "base_url": "https://api.moonshot.cn/v1",
+        "models": ["moonshot-v1-8k", "moonshot-v1-32k", "moonshot-v1-128k"],
+    },
+    "qwen": {
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "models": ["qwen-plus", "qwen-max", "qwen-turbo"],
+    },
+    "zhipu": {
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "models": ["glm-4-plus", "glm-4-flash", "glm-4-air"],
+    },
+    "siliconflow": {
+        "base_url": "https://api.siliconflow.cn/v1",
+        "models": ["Qwen/Qwen2.5-72B-Instruct", "deepseek-ai/DeepSeek-V3"],
+    },
+    "groq": {
+        "base_url": "https://api.groq.com/openai/v1",
+        "models": ["llama-3.3-70b-versatile", "mixtral-8x7b-32768"],
+    },
+    "ollama": {
+        "base_url": "http://localhost:11434/v1",
+        "models": ["llama3", "qwen2.5", "mistral"],
+    },
+    "custom": {
+        "base_url": "https://api.openai.com/v1",
+        "models": ["gpt-4o-mini"],
+    },
+}
+
+
+class DotCharacterConfig(BaseModel):
+    """dot-skill 角色扮演插件配置。"""
+
+    # ── LLM Provider ──
+    dotcharacter_provider: str = Field(
+        default="custom",
+        description="大模型 Provider 预设：openai / deepseek / kimi / qwen / zhipu / siliconflow / groq / ollama / custom",
+    )
+    dotcharacter_api_base: str = Field(
+        default="https://api.openai.com/v1",
+        description="API 地址（provider=custom 时使用）",
+    )
+    dotcharacter_api_key: str = Field(
+        default="",
+        description="API Key",
+    )
+    dotcharacter_model: str = Field(
+        default="gpt-4o-mini",
+        description="模型名称",
+    )
+    dotcharacter_temperature: float = Field(
+        default=0.8, ge=0.0, le=2.0,
+    )
+    dotcharacter_max_tokens: int = Field(
+        default=1024, ge=1, le=32768,
+    )
+    dotcharacter_timeout: int = Field(
+        default=60, ge=5,
+    )
+
+    # ── 角色目录（逗号分隔多个路径）──
+    dotcharacter_skills_path: str = Field(
+        default="",
+        description="dot-skill / colleague-skill 角色目录，逗号分隔",
+    )
+
+    # ── 对话 ──
+    dotcharacter_max_history: int = Field(
+        default=20, ge=0, le=100,
+    )
+
+    # ── 权限 ──
+    dotcharacter_admin_qq: str = Field(default="")
+    dotcharacter_allowed_groups: str = Field(default="")
+
+    def get_admin_qqs(self) -> List[str]:
+        return [q.strip() for q in str(self.dotcharacter_admin_qq).split(",") if q.strip()]
+
+    def get_allowed_groups(self) -> List[str]:
+        return [g.strip() for g in str(self.dotcharacter_allowed_groups).split(",") if g.strip()]
+
+    @field_validator("dotcharacter_admin_qq", "dotcharacter_allowed_groups", mode="before")
+    @classmethod
+    def _coerce_to_str(cls, v):
+        return str(v) if v is not None else ""
+
+    def get_api_base(self) -> str:
+        if self.dotcharacter_provider and self.dotcharacter_provider != "custom":
+            preset = PROVIDER_PRESETS.get(self.dotcharacter_provider)
+            if preset:
+                return preset["base_url"]
+        return self.dotcharacter_api_base
+
+    def get_available_models(self) -> List[str]:
+        if self.dotcharacter_provider and self.dotcharacter_provider != "custom":
+            preset = PROVIDER_PRESETS.get(self.dotcharacter_provider)
+            if preset:
+                return preset["models"]
+        return [self.dotcharacter_model]
+
+    def resolve_skills_paths(self) -> List[Path]:
+        """解析所有角色目录，支持逗号分隔 + 自动发现。
+
+        检测顺序：
+        1. DOTCHARACTER_SKILLS_PATH 指定的路径（逗号分隔）
+        2. Claude Code / Hermes / OpenClaw 默认位置
+        3. colleague-skill 仓库常见克隆位置
+        """
+        candidates: List[Path] = []
+
+        if self.dotcharacter_skills_path:
+            for p in self.dotcharacter_skills_path.split(","):
+                p = p.strip()
+                if p:
+                    candidates.append(Path(p))
+
+        home = Path.home()
+        candidates.append(home / ".claude" / "skills" / "dot-skill" / "skills")
+        candidates.append(home / ".hermes" / "skills" / "dot-skill" / "skills")
+        candidates.append(home / ".openclaw" / "workspace" / "skills" / "dot-skill" / "skills")
+        candidates.append(home / "colleague-skill" / "skills")
+        candidates.append(home / "dot-skill" / "skills")
+        candidates.append(home / "Documents" / "colleague-skill" / "skills")
+        candidates.append(home / "code" / "colleague-skill" / "skills")
+        candidates.append(home / "projects" / "colleague-skill" / "skills")
+
+        seen: set = set()
+        result: List[Path] = []
+        for p in candidates:
+            try:
+                resolved = p.resolve()
+            except OSError:
+                continue
+            key = str(resolved)
+            if resolved.exists() and resolved.is_dir() and key not in seen:
+                seen.add(key)
+                result.append(resolved)
+        return result
+
+
+def get_config() -> DotCharacterConfig:
+    return get_plugin_config(DotCharacterConfig)

build/lib/nonebot_plugin_dotcharacter/conversation.py

@@ -0,0 +1,107 @@
+"""会话管理 — 每个用户 × 每个角色维护独立对话历史。"""
+
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ConversationSession:
+    """单个用户对单个角色的对话会话。"""
+    user_id: str
+    character_slug: str
+    messages: List[dict] = field(default_factory=list)  # [{"role":"user"|"assistant","content":"..."}]
+    created_at: float = field(default_factory=time.time)
+    last_active_at: float = field(default_factory=time.time)
+
+    def add_user_message(self, content: str) -> None:
+        self.messages.append({"role": "user", "content": content})
+        self.last_active_at = time.time()
+
+    def add_assistant_message(self, content: str) -> None:
+        self.messages.append({"role": "assistant", "content": content})
+        self.last_active_at = time.time()
+
+    def trim(self, max_history: int) -> None:
+        """保留最近 N 轮对话（每轮 = user + assistant）。"""
+        if max_history <= 0:
+            self.messages.clear()
+            return
+        # max_history 指的是消息数，保留最后 N 条
+        if len(self.messages) > max_history:
+            self.messages = self.messages[-max_history:]
+
+    @property
+    def is_empty(self) -> bool:
+        return len(self.messages) == 0
+
+
+class ConversationManager:
+    """管理所有用户的会话。
+
+    内部使用 OrderedDict 做简单的 LRU 淘汰，
+    避免长时间运行时内存无限增长。
+    """
+
+    MAX_SESSIONS = 500  # 最多保留 500 个会话
+
+    def __init__(self) -> None:
+        self._sessions: OrderedDict[str, ConversationSession] = OrderedDict()
+        self._active_character: Dict[str, str] = {}  # user_id → slug
+
+    def _make_key(self, user_id: str, slug: str) -> str:
+        return f"{user_id}::{slug}"
+
+    def get_session(self, user_id: str, slug: str) -> ConversationSession:
+        """获取或创建会话。"""
+        key = self._make_key(user_id, slug)
+        if key not in self._sessions:
+            if len(self._sessions) >= self.MAX_SESSIONS:
+                # 淘汰最老的会话
+                self._sessions.popitem(last=False)
+            self._sessions[key] = ConversationSession(
+                user_id=user_id,
+                character_slug=slug,
+            )
+        else:
+            # 移到末尾（最近使用）
+            self._sessions.move_to_end(key)
+        return self._sessions[key]
+
+    def reset_session(self, user_id: str, slug: str) -> None:
+        """重置某用户对某角色的对话。"""
+        key = self._make_key(user_id, slug)
+        self._sessions.pop(key, None)
+
+    def set_active_character(self, user_id: str, slug: str) -> None:
+        self._active_character[user_id] = slug
+
+    def get_active_character(self, user_id: str) -> Optional[str]:
+        return self._active_character.get(user_id)
+
+    def clear_active_character(self, user_id: str) -> None:
+        self._active_character.pop(user_id, None)
+
+    def cleanup_stale(self, max_age_seconds: float = 3600.0) -> int:
+        """清理超过 max_age_seconds 未活跃的会话。返回清理数量。"""
+        now = time.time()
+        stale_keys = [
+            key
+            for key, session in self._sessions.items()
+            if now - session.last_active_at > max_age_seconds
+        ]
+        for key in stale_keys:
+            self._sessions.pop(key, None)
+        return len(stale_keys)
+
+
+# 全局单例
+_conversation_manager: Optional[ConversationManager] = None
+
+
+def get_conversation_manager() -> ConversationManager:
+    global _conversation_manager
+    if _conversation_manager is None:
+        _conversation_manager = ConversationManager()
+    return _conversation_manager

build/lib/nonebot_plugin_dotcharacter/llm_client.py

@@ -0,0 +1,91 @@
+"""LLM 客户端 — 调用 OpenAI 兼容 API 进行角色对话。
+
+支持所有 OpenAI Chat Completions 兼容的 API：
+OpenAI / DeepSeek / Kimi / Qwen / Zhipu / SiliconFlow / Groq / Ollama / 自定义
+"""
+
+from typing import List, Optional
+
+import httpx
+
+from .config import DotCharacterConfig
+
+
+def _msg(role: str, content: str) -> dict:
+    return {"role": role, "content": content}
+
+
+def system_msg(content: str) -> dict:
+    return _msg("system", content)
+
+
+def user_msg(name: str, content: str) -> dict:
+    return _msg("user", f"{name}: {content}")
+
+
+def assistant_msg(content: str) -> dict:
+    return _msg("assistant", content)
+
+
+async def chat_completion(
+    config: DotCharacterConfig,
+    messages: List[dict],
+    max_tokens: Optional[int] = None,
+) -> str:
+    """发送聊天请求到 LLM，返回助手回复文本。
+
+    自动根据 Provider 预设或自定义 api_base 构造请求 URL。
+    兼容所有 OpenAI Chat Completions 格式的 API。
+    """
+    api_key = config.dotcharacter_api_key
+    if not api_key or api_key.startswith("sk-your-"):
+        raise ValueError(
+            "未配置有效的 DOTCHARACTER_API_KEY。"
+            "请在 .env 中设置真实的 API Key。"
+        )
+
+    base_url = config.get_api_base().rstrip("/")
+    url = f"{base_url}/chat/completions"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "model": config.dotcharacter_model,
+        "messages": messages,
+        "temperature": config.dotcharacter_temperature,
+        "max_tokens": max_tokens or config.dotcharacter_max_tokens,
+    }
+
+    async with httpx.AsyncClient(timeout=config.dotcharacter_timeout) as client:
+        response = await client.post(url, json=payload, headers=headers)
+
+        if response.status_code != 200:
+            err_detail = response.text[:500]
+            raise RuntimeError(
+                f"LLM API 返回错误 (HTTP {response.status_code}): {err_detail}"
+            )
+
+        data = response.json()
+        choices = data.get("choices", [])
+        if not choices:
+            raise RuntimeError(f"LLM API 返回空 choices: {data}")
+
+        content = choices[0].get("message", {}).get("content", "")
+        return content.strip()
+
+
+async def test_api_connection(config: DotCharacterConfig) -> bool:
+    """快速测试 API 连接是否正常。"""
+    try:
+        result = await chat_completion(
+            config,
+            messages=[
+                system_msg("回复 OK，只输出这两个字母。"),
+                user_msg("test", "ping"),
+            ],
+            max_tokens=10,
+        )
+        return "OK" in result.upper()
+    except Exception:
+        return False