ForcePilot/backend/package/yuxi/channels/plugins/qqbot/_constants.py

"""QQ Bot 渠道插件共享常量。

集中定义在多个模块间共享的配置默认值、依赖标识与渠道标识，避免重复
定义导致的不一致风险（P2-3 常量去重）。

仅汇集真正跨模块共享的常量；仅单一模块使用的常量仍保留在各自模块内。
所有常量值需与 ``manifest.json`` 中 ``config_schema`` 的 ``default`` 字段
及 ``resource_quota`` 保持一致（F-03 manifest 单真相源），本模块的常量
作为 ConfigPort 未命中时的本地回退默认值。

依赖方向：仅标准库，不 import 任何框架层或同插件模块，避免循环依赖。
"""

from __future__ import annotations

# ---------------------------------------------------------------------------
# 渠道与依赖标识
# ---------------------------------------------------------------------------

# 渠道标识，用于 ConfigPort CHANNEL 作用域 target（与 manifest.json
# channel_type / provides 对齐）
CHANNEL_TARGET = "qqbot"

# QQ Bot API 依赖标识，统一用于 ``DependencyError.dep`` 字段
QQBOT_API_DEP = "qqbot_api"

# ---------------------------------------------------------------------------
# QQ Bot API 端点与默认值
# ---------------------------------------------------------------------------

# QQ Bot API 基础地址（对齐 manifest.json config_schema api_base.default）
API_BASE_URL = "https://api.sgroup.qq.com"

# token 获取端点路径（POST /app/getAppAccessToken）
TOKEN_ENDPOINT_PATH = "/app/getAppAccessToken"

# Gateway 获取端点路径（GET /gateway）
GATEWAY_ENDPOINT_PATH = "/gateway"

# 用户信息查询端点路径前缀（GET /users/{openid}）
USERS_ENDPOINT_PREFIX = "/users"

# 消息发送端点路径前缀
# C2C: POST /v2/users/{openid}/messages
# Group: POST /v2/groups/{group_openid}/messages
C2C_MESSAGES_PREFIX = "/v2/users"
GROUP_MESSAGES_PREFIX = "/v2/groups"
MESSAGES_SUFFIX = "/messages"

# 富媒体上传端点路径后缀
# C2C: POST /v2/users/{openid}/files
# Group: POST /v2/groups/{group_openid}/files
FILES_SUFFIX = "/files"

# 互动回调回应端点路径前缀（PUT /interactions/{interaction_id}）
INTERACTIONS_PREFIX = "/interactions"

# ---------------------------------------------------------------------------
# HTTP 客户端配置（lifecycle 与 qqbot_client 共享）
# ---------------------------------------------------------------------------

# HTTP 客户端默认超时（秒），对齐 manifest.json config_schema
# http_timeout_ms.default=30000
HTTP_TIMEOUT_SECONDS = 30.0

# HTTP 连接池最大连接数，对齐 manifest.json
# resource_quota.max_connections=20
HTTP_MAX_CONNECTIONS = 20

# HTTP 连接池 keepalive 连接数上限
HTTP_MAX_KEEPALIVE_CONNECTIONS = 5

# ---------------------------------------------------------------------------
# WebSocket 与传输引擎配置
# ---------------------------------------------------------------------------

# WebSocket 心跳间隔默认值（毫秒），对齐 manifest.json config_schema
# ws_heartbeat_interval_ms.default=30000
WS_HEARTBEAT_INTERVAL_MS = 30000

# WebSocket 卡死检测超时（毫秒），对齐 manifest.json config_schema
# ws_stall_timeout_ms.default=120000
WS_STALL_TIMEOUT_MS = 120000

# 连接建立超时（毫秒）
CONNECT_TIMEOUT_MS = 10000

# ---------------------------------------------------------------------------
# Token 与缓存配置
# ---------------------------------------------------------------------------

# access_token 刷新提前量（秒），到期前 60s 刷新（设计文档 §5.4）
TOKEN_REFRESH_LEAD_TIME_SEC = 60

# access_token 默认 TTL（秒），QQ Bot 有效期 7200s（2 小时）
TOKEN_DEFAULT_TTL = 7200

# 用户信息缓存默认 TTL（秒），对齐 manifest.json config_schema
# user_cache_ttl.default=3600
USER_CACHE_TTL = 3600

# 身份解析缓存 TTL（秒），契约规定 60s
IDENTITY_CACHE_TTL = 60

# channel_msg_id → account_id 反向映射缓存 TTL（秒）
MSG_CACHE_TTL_SECONDS = 86400

# ---------------------------------------------------------------------------
# Intents 默认值（设计文档 §1.3）
# ---------------------------------------------------------------------------

# GROUP_AND_C2C_EVENT (1<<25) + INTERACTION (1<<26)
# 对齐 manifest.json config_schema intents.default=0x06000000
DEFAULT_INTENTS = 0x06000000

# ---------------------------------------------------------------------------
# 被动消息频控默认值（设计文档 §4.5）
# ---------------------------------------------------------------------------

# C2C 被动消息 60 分钟最大回复次数
PASSIVE_REPLY_LIMIT_C2C = 4

# Group 被动消息 5 分钟最大回复次数
PASSIVE_REPLY_LIMIT_GROUP = 5

# C2C 被动消息有效期（毫秒，默认 60 分钟）
PASSIVE_REPLY_TTL_C2C_MS = 3600000

# Group 被动消息有效期（毫秒，默认 5 分钟）
PASSIVE_REPLY_TTL_GROUP_MS = 300000

# Group 主动消息账号维度 qpm（认证账号）
GROUP_ACTIVE_QPM_ACCOUNT_VERIFIED = 60

# Group 主动消息账号维度 qpm（未认证账号）
GROUP_ACTIVE_QPM_ACCOUNT_UNVERIFIED = 30

# Group 主动消息单群维度 qpm
GROUP_ACTIVE_QPM_PER_GROUP = 20

# ---------------------------------------------------------------------------
# 消息撤回时限（秒，C2C/Group 均 2 分钟）
# ---------------------------------------------------------------------------

RECALL_TIME_LIMIT_SECONDS = 120

# ---------------------------------------------------------------------------
# 频控缓存 key 前缀
# ---------------------------------------------------------------------------

# 被动消息计数 key 前缀：qqbot:passive:{account_id}:{peer_id}
PASSIVE_COUNTER_KEY_PREFIX = "qqbot:passive:"

# 主动消息 QPM 计数 key 前缀：qqbot:active_qpm:{account_id}
ACTIVE_QPM_KEY_PREFIX = "qqbot:active_qpm:"

# 群主动消息 QPM 计数 key 前缀：qqbot:active_qpm_group:{account_id}:{group_openid}
ACTIVE_QPM_GROUP_KEY_PREFIX = "qqbot:active_qpm_group:"

# ---------------------------------------------------------------------------
# 互动回调回应超时（秒，QQ Bot 客户端 loading 超时 3s）
# ---------------------------------------------------------------------------

INTERACTION_ACK_TIMEOUT_SECONDS = 3.0

# ---------------------------------------------------------------------------
# 消息大小上限（字符数，决策 5）
# ---------------------------------------------------------------------------

MAX_MESSAGE_LENGTH = 4000


__all__ = [
    "CHANNEL_TARGET",
    "QQBOT_API_DEP",
    "API_BASE_URL",
    "TOKEN_ENDPOINT_PATH",
    "GATEWAY_ENDPOINT_PATH",
    "USERS_ENDPOINT_PREFIX",
    "C2C_MESSAGES_PREFIX",
    "GROUP_MESSAGES_PREFIX",
    "MESSAGES_SUFFIX",
    "FILES_SUFFIX",
    "INTERACTIONS_PREFIX",
    "HTTP_TIMEOUT_SECONDS",
    "HTTP_MAX_CONNECTIONS",
    "HTTP_MAX_KEEPALIVE_CONNECTIONS",
    "WS_HEARTBEAT_INTERVAL_MS",
    "WS_STALL_TIMEOUT_MS",
    "CONNECT_TIMEOUT_MS",
    "TOKEN_REFRESH_LEAD_TIME_SEC",
    "TOKEN_DEFAULT_TTL",
    "USER_CACHE_TTL",
    "IDENTITY_CACHE_TTL",
    "MSG_CACHE_TTL_SECONDS",
    "DEFAULT_INTENTS",
    "PASSIVE_REPLY_LIMIT_C2C",
    "PASSIVE_REPLY_LIMIT_GROUP",
    "PASSIVE_REPLY_TTL_C2C_MS",
    "PASSIVE_REPLY_TTL_GROUP_MS",
    "GROUP_ACTIVE_QPM_ACCOUNT_VERIFIED",
    "GROUP_ACTIVE_QPM_ACCOUNT_UNVERIFIED",
    "GROUP_ACTIVE_QPM_PER_GROUP",
    "RECALL_TIME_LIMIT_SECONDS",
    "PASSIVE_COUNTER_KEY_PREFIX",
    "ACTIVE_QPM_KEY_PREFIX",
    "ACTIVE_QPM_GROUP_KEY_PREFIX",
    "INTERACTION_ACK_TIMEOUT_SECONDS",
    "MAX_MESSAGE_LENGTH",
]