适配OneBot v11协议、功能模块化、易于扩展、高效的QQ机器人及框架
- 框架（即 hyper-bot /
hyperot核心）已在 HyperBotCore 仓库继续独立维护，本仓库不再包含框架源码，仅作为 bot 本体使用。 - 本仓库已迁移至 uv 管理依赖（Python 3.11）。
HyperAG— 核心能力（自主 Agent、消息收集、工具调用）已合并至本仓库modules/Agent.py，该项目不再单独维护（或许）。
HypeR Bot是一个适配 OneBot 和 Milky 协议并支持拓展自定义协议的机器人框架，旨在提供一个简洁、高效、可扩展的机器人运行结构。
- Python 3.12
- uv（依赖管理，
uv.lock锁定全部版本）
uv sync # 安装运行时与开发依赖到 .venv
uv run patchright install chromium # 安装网页阅读使用的 Chromium
uv run python main.py首次运行会自动生成 config.json，编辑后重启即可。
uv run ruff check # lint
uv run ruff format # 格式化
uv run pyrefly check # 类型检查（strict 预设，无参数的项目模式）功能模块位于 modules/ 目录，由 modules/__init__.py 自动发现加载（.py 文件与子目录均可）。禁用模块：将 .py 重命名为 .dis。
config.json:
{
"protocol": "OneBot",
"owner": [],
"black_list": [],
"silents": [],
"connection": {
"mode": "FWS",
"ob_auto_startup": false,
"ob_exec": "./Lagrange.OneBot/Lagrange.OneBot",
"ob_startup_path": "./Lagrange.OneBot/",
"host": "127.0.0.1",
"port": 5004
},
"log_level": "INFO",
"log_use_nf": true,
"uin": 0,
"max_workers": 25,
"others": { ... }
}
其中：
owner：机器人主人的QQ号，填写在这个列表中的QQ号所发送的消息会被标记is_owner = True；black_list：黑名单，填写在这个列表中的QQ号所发送的的消息会被标记blocked = True；connection：连接信息，包括主机地址、端口以及自动启动OneBot实现的配置；log_level：日志等级，可选值为DEBUG、TRACE、INFO、WARNING、ERROR、CRITICAL；others：其他配置项；log_use_nf：是否为日志输出启用NerdFont;protocol：适配的协议，目前仅支持OneBot.
AI 聊天模块（.chat）需要在 others 中配置后端：
"others": {
"enable": "gemini",
"gemini_key": "",
"ds_ck": "",
"ds_auth": "",
"white": []
}enable 可选 gemini / deepseek / openai；white 为聊天白名单。(注：Deepseek为逆向工程实现，并非官方API,要使用DeepSeek API, 请选择 openai)
自主 Agent 模块（modules/Agent.py）：群内白名单驱动 + 工具调用，支持动态人设、上下文管理、RAG 长期记忆与调用其他功能模块。
others 中的 Agent 配置：
"others": {
"agent_white": {},
"agent_profile": "cat",
"agent_memory_limit": 500,
"agent_module_deny": []
}LLM 连接配置保存在 api_profiles.json，支持多个 OpenAI 兼容服务商和精确模型名：
{
"version": 1,
"active_profile": "default",
"profiles": {
"default": {
"base_url": "https://api.deepseek.com",
"api_key": "",
"model": "deepseek-chat",
"api_mode": "chat",
"reasoning_effort": "low",
"web_search": true,
"native_multimodal": true,
"headers": {}
}
}
}旧的 openai_key / openai_endpoint / openai_model / agent_api / agent_reasoning_effort / agent_web_search / agent_native_multimodal 会在 Agent 加载时自动迁移到 default profile，并从 config.json 删除旧键。
base_url：OpenAI 兼容 API 地址；留空使用 SDK 默认地址；api_key：服务商密钥；model：原样传给 API，支持Claude Fable 5.1这类包含空格的名称；api_mode：chat或responses；reasoning_effort：模型推理强度；web_search：Responses 模式下的服务端搜索；native_multimodal：是否把用户图片作为原生图片输入；agent_profile_switch_summary：切换人设前是否归档全部 Main 上下文，默认true；agent_profile_switch_keep_turns控制保留多少轮原文，默认 6；长历史分块大小和最终摘要上限分别由agent_profile_summary_chunk_chars、agent_profile_summary_max_tokens控制；
"agent_profile_switch_summary": true,
"agent_profile_switch_keep_turns": 6,
"agent_profile_summary_chunk_chars": 24000,
"agent_profile_summary_max_tokens": 3000agent_content_*：大型工具结果自动保存到temps/agent_content/，模型通过content_search/content_read检索完整内容；默认保留 7 天、单上下文最多 300 条、全局最多 512 MB，启动时清理并按写入惰性回收；
"agent_content_inline_chars": 4000,
"agent_content_preview_chars": 1200,
"agent_content_read_chars": 12000,
"agent_content_max_item_chars": 10000000,
"agent_content_ttl_hours": 168,
"agent_content_max_items": 300,
"agent_content_max_mb": 512,
"agent_content_cleanup_interval": 60agent_document_*：QQ 文件与文档阅读限制；默认单文件 50 MB、压缩包解压上限 100 MB、单文档最多提取 1000 万字符，扫描版 PDF 默认取前 5 页交给视觉模型；
"agent_document_max_mb": 50,
"agent_archive_max_mb": 100,
"agent_document_max_chars": 10000000,
"agent_document_vision_pages": 5,
"agent_document_vision_threshold": 200agent_white：各群白名单（群号 → QQ 列表），白名单成员发言触发自动处理，被 @ 时无视白名单立即处理；agent_profile：当前人设名（来自profiles.json，不存在则自动生成）；agent_memory_limit：RAG 记忆容量上限；profiles.json人设条目支持{"prompt": "人设文本", "inject_master": true|false}：inject_master=true时在系统提示词中注入「User_id in [ulist]是你的主人」，false则不注入；省略时默认true（兼容旧的纯文本条目格式）。agent_module_deny：禁止 Agent 调用的功能模块黑名单。
Agent 命令（支持点号/空格两种写法；简写 ag=agent、pf=profile、ctx=context、ad=add、rm=remove、sum=summary、clr=clear）：
.agent.on / .agent.off # 加入/移出当前群白名单
.agent.status # 白名单状态
.agent.profile # 列出人设（来自 profiles.json）
.agent.profile <名称> # 切换人设（仅主人；切换前自动总结当前上下文）
.agent.profile.add <名称> <内容> # 添加/更新人设（仅主人）
.agent.profile.remove <名称> # 删除人设（仅主人）
.agent.profile.master <名称> [on/off] # 查看/设置是否注入主人设定（设置仅主人，简写 .ag.pf.ma）
.agent.context # 查看上下文状态（仅主人）
.agent.context.clear # 清空上下文历史（仅主人）
.agent.context.summary <内容> # 用总结替换上下文历史（仅主人）
API profile 命令（仅主人；新增、修改、删除必须在私聊中执行）：
.ag.api # 查看 profile 和当前项
.ag.api <profile> # 立即切换服务商和该 profile 的模型
.ag.api.add # 启动询问式新增向导
.ag.api.set <profile> [字段] # 启动询问式修改向导
.ag.api.rm <profile> # 确认后删除
.ag.api.show <profile> # 查看脱敏详情(.ag.api.sh)
.ag.api.reload # 重载 api_profiles.json(.ag.api.rl)
.ag.model [完整模型名] # 查看或切换当前模型(.ag.md)
向导支持 back、skip、show、cancel、confirm。API Key 只在主人私聊中录入，不会回显到日志或状态输出。
Agent 内置能力：人设切换（bot 工具 switch_profile 与命令 .agent.profile 同一入口）、上下文总结（bot 工具 summary 与命令 .agent.context.summary 同一入口）、RAG 长期记忆（本地 BGE 向量检索，mem_add/mem_query/mem_list/mem_del，相关记忆自动注入）、调用其他功能模块（run_module/list_modules/get_module_source，模块输出以段 JSON 移交 Agent 决定是否转发）。
- Python 3.11（
.python-version锁定；pyproject.toml声明requires-python = ">=3.11,<3.13"） - 依赖声明于
pyproject.toml，版本锁定于uv.lock - 代码质量：ruff（lint + format）与 pyrefly（strict 类型检查），配置均在
pyproject.toml