"""nanobot 配置 Schema（基于 Pydantic）。 这份文件是“配置系统的单一结构定义”： 1. 定义配置长什么样（字段、默认值、嵌套结构） 2. 负责配置的类型校验与兼容（camelCase / snake_case） 3. 提供若干读取辅助方法（如 provider 匹配、api_key/api_base 解析） 你可以把它理解为： - `loader.py` 负责“读写配置文件” - `schema.py` 负责“配置对象的结构和规则” """ from pathlib import Path from typing import Literal from pydantic import BaseModel, ConfigDict, Field from pydantic.alias_generators import to_camel from pydantic_settings import BaseSettings class Base(BaseModel): """所有配置模型的基类。 关键点： - `alias_generator=to_camel`：自动把 `api_key` 这种字段映射到 `apiKey` - `populate_by_name=True`：读取时同时接受 snake_case 和 camelCase 结果： - Python 代码内部统一使用 snake_case，便于可读性和一致性 - 配置文件对外保持 camelCase，贴近 README 和用户习惯 """ model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True) class WhatsAppConfig(Base): """WhatsApp 渠道配置。 说明： - nanobot 通过单独的 bridge 进程与 WhatsApp 交互 - 这里配置的是 bridge 的连接地址和访问控制 """ enabled: bool = False bridge_url: str = "ws://localhost:3001" bridge_token: str = "" # Shared token for bridge auth (optional, recommended) allow_from: list[str] = Field(default_factory=list) # Allowed phone numbers class TelegramConfig(Base): """Telegram 渠道配置。 常用字段： - token：机器人凭证（必须） - allow_from：白名单（可选，空列表表示不限制） - proxy：在网络受限场景下可配置代理 """ enabled: bool = False token: str = "" # Bot token from @BotFather allow_from: list[str] = Field(default_factory=list) # Allowed user IDs or usernames proxy: str | None = None # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080" reply_to_message: bool = False # If true, bot replies quote the original message class FeishuConfig(Base): """飞书/Lark 渠道配置（基于长连接模式）。""" enabled: bool = False app_id: str = "" # App ID from Feishu Open Platform app_secret: str = "" # App Secret from Feishu Open Platform encrypt_key: str = "" # Encrypt Key for event subscription (optional) verification_token: str = "" # Verification Token for event subscription (optional) allow_from: list[str] = Field(default_factory=list) # Allowed user open_ids class DingTalkConfig(Base): """钉钉渠道配置（Stream 模式）。""" enabled: bool = False client_id: str = "" # AppKey client_secret: str = "" # AppSecret allow_from: list[str] = Field(default_factory=list) # Allowed staff_ids class DiscordConfig(Base): """Discord 渠道配置。""" enabled: bool = False token: str = "" # Bot token from Discord Developer Portal allow_from: list[str] = Field(default_factory=list) # Allowed user IDs gateway_url: str = "wss://gateway.discord.gg/?v=10&encoding=json" intents: int = 37377 # GUILDS + GUILD_MESSAGES + DIRECT_MESSAGES + MESSAGE_CONTENT class MatrixConfig(Base): """Matrix (Element) 渠道配置。""" enabled: bool = False homeserver: str = "https://matrix.org" access_token: str = "" user_id: str = "" # @bot:matrix.org device_id: str = "" e2ee_enabled: bool = True # Enable Matrix E2EE support (encryption + encrypted room handling). sync_stop_grace_seconds: int = ( 2 # Max seconds to wait for sync_forever to stop gracefully before cancellation fallback. ) max_media_bytes: int = ( 20 * 1024 * 1024 ) # Max attachment size accepted for Matrix media handling (inbound + outbound). allow_from: list[str] = Field(default_factory=list) group_policy: Literal["open", "mention", "allowlist"] = "open" group_allow_from: list[str] = Field(default_factory=list) allow_room_mentions: bool = False class EmailConfig(Base): """Email 渠道配置（IMAP 收件 + SMTP 发件）。 设计思路： - IMAP 负责拉取新邮件 - SMTP 负责自动回复 - 行为参数控制轮询频率、正文截断、标记已读等策略 """ enabled: bool = False consent_granted: bool = False # Explicit owner permission to access mailbox data # IMAP (receive) imap_host: str = "" imap_port: int = 993 imap_username: str = "" imap_password: str = "" imap_mailbox: str = "INBOX" imap_use_ssl: bool = True # SMTP (send) smtp_host: str = "" smtp_port: int = 587 smtp_username: str = "" smtp_password: str = "" smtp_use_tls: bool = True smtp_use_ssl: bool = False from_address: str = "" # Behavior auto_reply_enabled: bool = True # If false, inbound email is read but no automatic reply is sent poll_interval_seconds: int = 30 mark_seen: bool = True max_body_chars: int = 12000 subject_prefix: str = "Re: " allow_from: list[str] = Field(default_factory=list) # Allowed sender email addresses class MochatMentionConfig(Base): """Mochat 提及（mention）规则。""" require_in_groups: bool = False class MochatGroupRule(Base): """Mochat 群组级别规则（可按群单独配置是否必须 @）。""" require_mention: bool = False class MochatConfig(Base): """Mochat 渠道配置。 包含三类参数： - 连接参数：base_url / socket_url / socket_path - 重连与轮询参数：各类 *_ms 与 retry 相关字段 - 权限与会话参数：allow_from / sessions / panels / mention / groups """ enabled: bool = False base_url: str = "https://mochat.io" socket_url: str = "" socket_path: str = "/socket.io" socket_disable_msgpack: bool = False socket_reconnect_delay_ms: int = 1000 socket_max_reconnect_delay_ms: int = 10000 socket_connect_timeout_ms: int = 10000 refresh_interval_ms: int = 30000 watch_timeout_ms: int = 25000 watch_limit: int = 100 retry_delay_ms: int = 500 max_retry_attempts: int = 0 # 0 means unlimited retries claw_token: str = "" agent_user_id: str = "" sessions: list[str] = Field(default_factory=list) panels: list[str] = Field(default_factory=list) allow_from: list[str] = Field(default_factory=list) mention: MochatMentionConfig = Field(default_factory=MochatMentionConfig) groups: dict[str, MochatGroupRule] = Field(default_factory=dict) reply_delay_mode: str = "non-mention" # off | non-mention reply_delay_ms: int = 120000 class SlackDMConfig(Base): """Slack 私聊（DM）策略配置。""" enabled: bool = True policy: str = "open" # "open" or "allowlist" allow_from: list[str] = Field(default_factory=list) # Allowed Slack user IDs class SlackConfig(Base): """Slack 渠道配置。""" enabled: bool = False mode: str = "socket" # "socket" supported webhook_path: str = "/slack/events" bot_token: str = "" # xoxb-... app_token: str = "" # xapp-... user_token_read_only: bool = True reply_in_thread: bool = True react_emoji: str = "eyes" group_policy: str = "mention" # "mention", "open", "allowlist" group_allow_from: list[str] = Field(default_factory=list) # Allowed channel IDs if allowlist dm: SlackDMConfig = Field(default_factory=SlackDMConfig) class QQConfig(Base): """QQ 渠道配置（botpy SDK）。""" enabled: bool = False app_id: str = "" # 机器人 ID (AppID) from q.qq.com secret: str = "" # 机器人密钥 (AppSecret) from q.qq.com allow_from: list[str] = Field(default_factory=list) # Allowed user openids (empty = public access) class ChannelsConfig(Base): """所有聊天渠道的总配置。 除了具体渠道参数外，还有两个全局开关： - send_progress：是否把“处理中进度”推送到渠道 - send_tool_hints：是否把“工具调用提示”推送到渠道 """ send_progress: bool = True # stream agent's text progress to the channel send_tool_hints: bool = False # stream tool-call hints (e.g. read_file("…")) whatsapp: WhatsAppConfig = Field(default_factory=WhatsAppConfig) telegram: TelegramConfig = Field(default_factory=TelegramConfig) discord: DiscordConfig = Field(default_factory=DiscordConfig) feishu: FeishuConfig = Field(default_factory=FeishuConfig) mochat: MochatConfig = Field(default_factory=MochatConfig) dingtalk: DingTalkConfig = Field(default_factory=DingTalkConfig) email: EmailConfig = Field(default_factory=EmailConfig) slack: SlackConfig = Field(default_factory=SlackConfig) qq: QQConfig = Field(default_factory=QQConfig) matrix: MatrixConfig = Field(default_factory=MatrixConfig) class AgentDefaults(Base): """Agent 默认行为配置。 关键参数建议理解： - model：主模型标识 - max_tokens：单次回复上限 - max_tool_iterations：一次请求里最多工具循环次数 - memory_window：每次送给模型的历史窗口大小 """ workspace: str = "~/.nanobot/workspace" model: str = "anthropic/claude-opus-4-5" max_tokens: int = 8192 temperature: float = 0.1 max_tool_iterations: int = 40 memory_window: int = 100 class AgentsConfig(Base): """Agent 顶层配置（当前主要是 defaults）。""" defaults: AgentDefaults = Field(default_factory=AgentDefaults) class ProviderConfig(Base): """单个 LLM Provider 的通用配置结构。 字段说明： - api_key：访问凭证 - api_base：可选自定义网关/代理地址 - extra_headers：额外 HTTP 头（某些网关会要求） """ api_key: str = "" api_base: str | None = None extra_headers: dict[str, str] | None = None # Custom headers (e.g. APP-Code for AiHubMix) class ProvidersConfig(Base): """所有 Provider 的配置集合。 这里的字段名必须和 `providers/registry.py` 里的 ProviderSpec.name 对齐。 这样 `_match_provider()` 才能通过 `getattr(self.providers, spec.name)` 正确取值。 """ custom: ProviderConfig = Field(default_factory=ProviderConfig) # Any OpenAI-compatible endpoint anthropic: ProviderConfig = Field(default_factory=ProviderConfig) openai: ProviderConfig = Field(default_factory=ProviderConfig) openrouter: ProviderConfig = Field(default_factory=ProviderConfig) deepseek: ProviderConfig = Field(default_factory=ProviderConfig) groq: ProviderConfig = Field(default_factory=ProviderConfig) zhipu: ProviderConfig = Field(default_factory=ProviderConfig) dashscope: ProviderConfig = Field(default_factory=ProviderConfig) # 阿里云通义千问 vllm: ProviderConfig = Field(default_factory=ProviderConfig) gemini: ProviderConfig = Field(default_factory=ProviderConfig) moonshot: ProviderConfig = Field(default_factory=ProviderConfig) minimax: ProviderConfig = Field(default_factory=ProviderConfig) aihubmix: ProviderConfig = Field(default_factory=ProviderConfig) # AiHubMix API gateway siliconflow: ProviderConfig = Field(default_factory=ProviderConfig) # SiliconFlow (硅基流动) API gateway volcengine: ProviderConfig = Field(default_factory=ProviderConfig) # VolcEngine (火山引擎) API gateway openai_codex: ProviderConfig = Field(default_factory=ProviderConfig) # OpenAI Codex (OAuth) github_copilot: ProviderConfig = Field(default_factory=ProviderConfig) # Github Copilot (OAuth) class GatewayConfig(Base): """Gateway 服务监听配置。""" host: str = "0.0.0.0" port: int = 18790 class WebSearchConfig(Base): """Web 搜索工具配置（当前主要是 Brave Search）。""" api_key: str = "" # Brave Search API key max_results: int = 5 class WebToolsConfig(Base): """Web 工具总配置。""" search: WebSearchConfig = Field(default_factory=WebSearchConfig) class ExecToolConfig(Base): """Shell 执行工具配置。""" timeout: int = 60 class MCPServerConfig(Base): """单个 MCP 服务器配置（支持 stdio 与 HTTP 两种连接方式）。 使用方式： - stdio：配置 `command + args + env` - HTTP：配置 `url + headers` """ command: str = "" # Stdio: command to run (e.g. "npx") args: list[str] = Field(default_factory=list) # Stdio: command arguments env: dict[str, str] = Field(default_factory=dict) # Stdio: extra env vars url: str = "" # HTTP: streamable HTTP endpoint URL headers: dict[str, str] = Field(default_factory=dict) # HTTP: Custom HTTP Headers auth_mode: str = "none" # none | oauth_backend_token auth_audience: str = "" auth_scopes: list[str] = Field(default_factory=list) tool_timeout: int = 30 # Seconds before a tool call is cancelled sensitive: bool = False # Redact secrets/args from Web views and process events class A2AConfig(Base): """A2A agent 委派配置。""" # 总开关，预留给未来需要完全禁用远程委派的场景。 enabled: bool = True # 单次远程任务的最长等待时间（秒）。 timeout_seconds: int = 30 # 非流式任务轮询间隔（秒）。 poll_interval_seconds: int = 2 # agent card 本地缓存 TTL，避免每次委派都重新拉远端元数据。 card_cache_ttl_seconds: int = 300 # group delegation 并发上限，防止一次性打爆本地或远端资源。 max_parallel_agents: int = 4 # 是否允许从 skill 元数据里暴露 agent cards。 allow_skill_cards: bool = True # 是否允许读取 workspace/agents/registry.json 中的手工登记 agent。 allow_workspace_agents: bool = True # 允许访问的远端 host 白名单；为空表示不限制。 allowed_hosts: list[str] = Field(default_factory=list) class ToolsConfig(Base): """工具层总配置。 关键安全字段： - restrict_to_workspace：开启后，工具访问将被限制在 workspace 内 """ web: WebToolsConfig = Field(default_factory=WebToolsConfig) exec: ExecToolConfig = Field(default_factory=ExecToolConfig) restrict_to_workspace: bool = False # If true, restrict all tool access to workspace directory mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict) a2a: A2AConfig = Field(default_factory=A2AConfig) class AuthzConfig(Base): """外部 AuthZ/OAuth 服务配置。""" enabled: bool = False base_url: str = "http://127.0.0.1:19090" request_timeout_seconds: int = 10 outlook_mcp_url: str = "" class BackendIdentityConfig(Base): """当前 backend 在 AuthZ 服务里的身份配置。""" backend_id: str = "" client_id: str = "" client_secret: str = "" name: str = "Local Backend" public_base_url: str = "" class Config(BaseSettings): """nanobot 根配置对象。 这是业务代码中最常使用的配置入口： - `config.agents.defaults.model` - `config.channels.telegram.token` - `config.tools.restrict_to_workspace` 等都会从这里往下访问。 """ agents: AgentsConfig = Field(default_factory=AgentsConfig) channels: ChannelsConfig = Field(default_factory=ChannelsConfig) providers: ProvidersConfig = Field(default_factory=ProvidersConfig) gateway: GatewayConfig = Field(default_factory=GatewayConfig) tools: ToolsConfig = Field(default_factory=ToolsConfig) authz: AuthzConfig = Field(default_factory=AuthzConfig) backend_identity: BackendIdentityConfig = Field(default_factory=BackendIdentityConfig) @property def workspace_path(self) -> Path: """返回展开后的 workspace 绝对路径对象。 `~` 会被替换成用户 home 目录，避免下游代码重复处理路径展开。 """ return Path(self.agents.defaults.workspace).expanduser() def _match_provider(self, model: str | None = None) -> tuple["ProviderConfig | None", str | None]: """根据模型名与当前配置，匹配最合适的 provider。 返回值： - ProviderConfig | None：匹配到的配置项（含 api_key/api_base） - str | None：provider 的 registry 名称（例如 openrouter/deepseek） 匹配优先级（非常重要）： 1. 显式前缀匹配：`github-copilot/...` 这种明确前缀优先 2. 关键字匹配：按 PROVIDERS 顺序匹配关键词 3. 兜底匹配：选第一个“已配置 api_key 的非 OAuth provider” """ from nanobot.providers.registry import PROVIDERS # 统一做小写与连字符归一化，减少字符串匹配分歧。 model_lower = (model or self.agents.defaults.model).lower() model_normalized = model_lower.replace("-", "_") model_prefix = model_lower.split("/", 1)[0] if "/" in model_lower else "" normalized_prefix = model_prefix.replace("-", "_") # 关键字匹配函数：同时兼容 dash/underscore 两种写法。 def _kw_matches(kw: str) -> bool: kw = kw.lower() return kw in model_lower or kw.replace("-", "_") in model_normalized # 第 1 轮：显式前缀优先 # 例如 `github-copilot/gpt-5.3-codex`，必须匹配 github_copilot， # 不能被 `codex` 关键字误匹配成 openai_codex。 for spec in PROVIDERS: p = getattr(self.providers, spec.name, None) if p and model_prefix and normalized_prefix == spec.name: if spec.is_oauth or p.api_key: return p, spec.name # 第 2 轮：按关键字匹配（顺序由 PROVIDERS 决定） # 顺序很关键：registry 里前面的 provider 具有更高优先级。 for spec in PROVIDERS: p = getattr(self.providers, spec.name, None) if p and any(_kw_matches(kw) for kw in spec.keywords): if spec.is_oauth or p.api_key: return p, spec.name # 第 3 轮：兜底匹配 # 规则：仅考虑“非 OAuth + 有 api_key”的 provider。 # 原因：OAuth provider 需要显式模型选择，不能静默兜底。 for spec in PROVIDERS: if spec.is_oauth: continue p = getattr(self.providers, spec.name, None) if p and p.api_key: return p, spec.name return None, None def get_provider(self, model: str | None = None) -> ProviderConfig | None: """获取匹配到的 ProviderConfig（含 api_key/api_base/extra_headers）。""" p, _ = self._match_provider(model) return p def get_provider_name(self, model: str | None = None) -> str | None: """获取匹配到的 provider 名称（例如 deepseek/openrouter）。""" _, name = self._match_provider(model) return name def get_api_key(self, model: str | None = None) -> str | None: """获取当前模型对应的 API key（无则返回 None）。""" p = self.get_provider(model) return p.api_key if p else None def get_api_base(self, model: str | None = None) -> str | None: """获取当前模型的 api_base。 规则： 1. 若用户显式配置了 api_base，优先返回用户值 2. 否则若匹配到的是 gateway provider，则可回退到 registry 默认 base 3. 标准 provider（非 gateway）默认不在这里强制写 api_base """ from nanobot.providers.registry import find_by_name p, name = self._match_provider(model) if p and p.api_base: return p.api_base # 仅 gateway 在此处应用默认 api_base。 # 标准 provider（如 moonshot）通常在 provider 初始化时通过环境变量处理， # 避免污染全局 litellm.api_base。 if name: spec = find_by_name(name) if spec and spec.is_gateway and spec.default_api_base: return spec.default_api_base return None # BaseSettings 相关： # - env_prefix="NANOBOT_"：环境变量前缀，例如 NANOBOT_AGENTS__DEFAULTS__MODEL # - env_nested_delimiter="__"：双下划线用于拆分嵌套层级 model_config = ConfigDict(env_prefix="NANOBOT_", env_nested_delimiter="__")