- 🧩 高度解耦：统一的消息对象模型，实现多端一致的业务逻辑处理。
- 🔀 规则引擎：基于前缀的极简四分支路由（
普通问答、搜索、记忆写入、记忆回顾）。 - 🧠 长短期记忆：以追加式机制管理长期记忆，配合 JSONL 格式实现轻量级的多轮会话贯穿。
- 🔍 智能搜索：内置 Web Search 支持（涵盖 百度 AI 搜索、DuckDuckGo、Serper）。
- 🔌 多端接入：
- Console 调试通道（快速本地校验）
- QQ 官方 Bot 直连（WebSocket + OpenAPI，天然穿透局域网）
- OneBot V11 通道（完美对接 NapCatQQ 等框架部署普通 QQ 号）
- 🤖 模型兼容：开箱即支持完整的 OpenAI 兼容 API 调用。
D:\mybot
├── README.md # 📖 项目说明文档
├── pyproject.toml # 📦 依赖管理与项目配置
├── .gitignore # 🙈 Git 提交忽略规范
├── .env # 🔑 本地敏感环境变量（需手动创建）
├── config/ # ⚙️ 核心配置目录存放配置文件模板
├── logs/ # 📝 系统运行日志
├── memory/ # 📥 Bot 自我认知的长期记忆库
├── sessions/ # 💬 历史对话缓存目录
├── sandbox/ # 🏝️ 各类练习、草稿代码及无关零散文件暂存区
├── mybot/ # 💻 框架主源码实现
├── skills/ # 🛠️ 预置的子功能与分支处理逻辑
├── tests/ # 🧪 基础自动化测试套件
└── scripts/ # 📜 环境与校园网辅助监控脚本
通过内置的样例生成自己的配置文件：
cp config/config.example.json config/config.json🔑 安全推荐： 使用项目根目录下的 .env 环境变量替代 JSON 明文写入：
MYBOT_QQ_APP_ID=你的AppID
MYBOT_QQ_SECRET=你的Secret
MYBOT_API_KEY=大模型APIKEY
MYBOT_SEARCH_API_KEY=搜索引擎APIKEY使用 pip 或虚拟环境安装当前工程：
pip install -e .最快的调试方式是使用本地交互模式：
mybot agent在交互界面的测试指令参考：
搜索 Python dataclass记住 我偏好简洁的回答风格回忆 回答风格（直接提问任何问题...）
配置好对应 Channel 后，即可启动网关：
# 自动读取 config.json 并拉起监听
mybot gateway🔗 1. 使用 QQ 官方 Bot 模式直连
- 在 QQ 开放平台 申请创建，获取
appId与secret。 - 将配置文件
channels.qq.type设置为qq_official（如果仅配置 AppID/Secret，系统会自动降级推断该模式）。 - 权限及 ID 说明： 官方机制使用
OpenID交互而非数字 QQ 号。allowFrom或startupNotify.to请查阅终端收到的第一条消息的日志（打印为乱码字符串即 OpenID），再将其白名单化补回原文件。
🔗 2. 使用 OneBot V11 对接自己的普通 QQ
- 根据根目录的
config/onebot.example.json修改。 - 将
type改回onebot_v11，配合 NapCatQQ 发出的反向 WS (ws://127.0.0.1:3000) 对接即可接管日常 QQ 号对话。
🛡️ 3. 应对校园网强制踢线（心跳自动重连）
如果你部署在宿舍中并偶发“网关掉线”，可以用自带诊断工具排查：
mybot doctor如果确定是断网引起的，可通过提供的 CLI 无头登录脚本重新认证校园网：
$env:MYBOT_CAMPUS_USERNAME = '校园网用户名'
$env:MYBOT_CAMPUS_PASSWORD = '密码'
python -m mybot campus-login(为保障安全，不要把账密写入代码中。如有需要，可在根目录运行 .\scripts\campus_gateway_watch.ps1 实现“检测断网->自动登录->重启网关”无人值守闭环。)
欢迎提交 Issue 和 Pull Request，我们一起来完善这个最小化的机器人设计思路！
- 把 channel.type 改成 onebot_v11
- 设置 api_base 指向 NapCat 或 go-cqhttp 的 HTTP API
- 如需启动后主动私聊问候，配置 channels.qq.startupNotify.enabled、to、message
- 设置模型 base_url、api_key、model
- 启动：
mybot gateway --config config/onebot.example.json
也兼容直接使用 Python：
python app.py agent python app.py gateway --config config/config.json python app.py status
- 以“搜索”或“search”开头: 强制搜索
- 以“记住”或“记一下”开头: 写入长期记忆
- 以“回忆”“回顾”“记得我什么”开头: 读取长期记忆
- 其他内容: 普通问答
- 当前默认配置已经兼容 nanobot 风格的 agents/providers/channels/tools 结构。
- 当前已支持子命令风格启动：mybot gateway、mybot agent、mybot status。
- 当前已支持两种 QQ 接入：官方 QQ Bot 直连和 OneBot v11 Webhook。
- 当 channels.qq 含有 appId/secret 且没有 apiBase 时，会默认按官方 QQ Bot 直连处理；有 apiBase 时，默认按 OneBot v11 处理。
- 官方 QQ Bot 直连基于 qq-botpy，走官方 WebSocket + OpenAPI；当前已接入频道 @ 消息、频道私信、QQ群 @ 消息、消息列表单聊消息。
- 在官方群聊/单聊场景，若机器人回复中包含图片链接，会自动调用官方媒体接口发送图片，并将图片归档到
managed_files/images/qq_official/。 - 官方 QQ Bot 的 allowFrom 和 startupNotify.to 使用的是官方事件中的用户标识或 openid，不是普通 QQ 号。
- gateway 启动后支持按 channels.qq.startupNotify 配置主动发送启动问候；官方直连下未加前缀的 target 默认按 c2c openid 发送，也支持 group: 和 channel: 前缀。
- 新增受控文件目录
managed_files/，文件管理命令只允许访问该目录，且默认禁止删除。 - 新增技能审批机制：从 GitHub/ClawHub 下载的技能默认待审批，未审批不会生效。
- exconfig.json 现在保留为旧配置参考文件，不作为默认启动配置。
- 默认搜索 provider 已切到百度 AI 搜索，对应接口为 https://qianfan.baidubce.com/v2/ai_search/chat/completions。
- 百度 AI 搜索使用 API Key 鉴权，请把 tools.web.search.apiKey 填成你的千帆 API Key，请求头使用 X-Appbuilder-Authorization: Bearer 。
- 默认百度搜索参数使用 searchSource=baidu_search_v2、searchMode=required、resource_type_filter=web top_k=maxResults；如果 model 留空，则更接近“百度搜索”模式，如果填写模型名，则会走“智能搜索生成”。
- 当前环境里 DuckDuckGo 直连测试超时。如果你在国内使用，优先考虑百度 AI 搜索、代理，或者其他国内可达搜索服务。
- 运行时会额外写入 logs/audit.log，用于记录消息入口、模型完成、记忆写入、图片/视频任务等审计事件。