feat: 重构为 agent / channels / flows / db 分层架构

- agent: 新增 base.py 执行基类、execution.py 执行器、web.py 网络工具,
  middlewares/steering.py 中间件;移除旧的 agent.py
- channels: 新增 ChannelManager、registry、models 与 IM 渠道(企业微信),
  扩展 base.py
- flows: 新增 agent_task / bus / cron / scheduler / service / stream / rpc /
  processor / tasks / model_settings / builtin;移除旧的 task.py
- db: 新增 sqlite schema 与 repo 层
- docs: 新增架构说明、Channel × EventBus 设计、任务编写教程
- 依赖新增 aiosqlite / httpx / langgraph / primp / pydantic / ripgrep /
  wecom-aibot-sdk;新增 bot 命令入口
- 测试:232 passed
This commit is contained in:
openbot committed 2026-11-09 20:32:25 +08:00
1 parent 94421e5c2b
commit fbb01c4c83
65 files changed
+15322 -173

No files matched your search

+156 -12
View File
@@ -1,36 +1,175 @@
# bot042
基于 [deepagents](https://github.com/langchain-ai/deepagents) 的自主行动机器人原型:理解任务、自主规划(todo)、调用机器人工具在模拟环境中行动。
基于 [deepagents](https://github.com/langchain-ai/deepagents) 的自主行动机器人原型:理解任务、自主规划、调用机器人工具在模拟环境中行动。
## 特性
- 深度智能体:内置任务规划 / 子智能体 / 工具调用循环(deepagents)
- 全异步运行时:通道、流程、智能体调用(`ainvoke`)与工具均为 `async`,CLI 入口用 `asyncio.run` 包裹
- 机器人工具:感知 `perceive`、移动 `move`、播报 `speak`,附带简易虚拟世界状态
- 本地执行:`execute` 跑 shell 命令、`run_python` 跑 Python 代码,直接作用于宿主机(无沙箱隔离)
- 本地存储:`bot init` 初始化 home 目录结构(默认 `~/.bot042`)与 SQLite 数据库 `bot.db`,数据库访问全程 aiosqlite 异步
- uv 管理依赖与 Python,国内镜像加速(见 `uv.toml`)
- CLI 入口:单次任务 / 交互模式
- CLI:`bot init` / 单次任务 / 交互模式
- IM 闭环:`bot serve` 常驻运行企业微信等渠道,`平台消息 → 事件总线 → 任务 → 智能体 → 回复`
- 文件检索:随依赖安装 `ripgrep`,deepagents 的 `grep` 工具走 `rg`(遵守 `.gitignore`,约 4 MB)
## 快速开始
```bash
uv sync
$env:OPENAI_API_KEY = "sk-..." # PowerShell;bash 用 export
uv run bot042 "感知环境,然后向北移动 2 步并播报状态"
uv run bot init # 初始化 ~/.bot042 目录结构与 bot.db
uv run bot init D:\bot_home # 自定义 home 目录(可选)
$env:OPENAI_API_KEY = "sk-..." # PowerShell;bash 用 export
uv run bot "感知环境,然后向北移动 2 步并播报状态"
```
交互模式:
```bash
uv run bot042 -i
uv run bot -i
```
## 初始化与数据库
`bot init [home]` 创建 home 目录(默认 `~/.bot042`)、目录结构与数据库 `bot.db`,重复执行安全(幂等,不会覆盖已有数据)。
```
【bot_home】/
wiki/ 公共知识库
logs/ 日志文件
tmp/ 临时文件
data/ 运行时文件
scripts/ 运行时脚本
bot.db SQLite 数据库(schema v1)
```
旧版本的 `bot042.db` 会在初始化时自动重命名为 `bot.db`。
| 表 | 用途 |
| --- | --- |
| `providers` | 大模型提供商配置(名称、协议类型、`base_url`、API Key) |
| `models` | 模型参数(上下文窗口、最大输出、温度、是否默认等) |
| `sessions` | 会话记录(通道、标题、状态、所用模型) |
| `channels` | 通道配置(CLI 等,JSON 配置) |
| `settings` | 系统参数(默认模型、最大步数、日志级别) |
schema 版本记录在 `PRAGMA user_version`(当前 v2),后续升级在 `db/schema.py` 内演进。
- API Key 直接存放在 `providers.api_key`;`bot db --provider --list` 掩码显示,`--show` 显示完整值
- 初始化种子时,若存在 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` 环境变量,会自动回填到对应提供商
- v1 旧库(`api_key_env` 列)初始化时自动迁移到 v2 并做同样回填
## 数据库管理(bot db)
```bash
# 提供商
bot db --provider --list
bot db --provider --add --name openai --kind openai --base-url https://api.openai.com/v1 --api-key sk-xxx
bot db --provider --update --id 1 --base-url https://proxy/v1
bot db --provider --delete --id 1
# 模型(--provider-name 指定所属提供商,--default 设为默认)
bot db --model --add --provider-name openai --name gpt-4o-mini --context-window 128000 --default
bot db --model --list --provider-name openai
bot db --model --update --id 1 --temperature 0.3
bot db --model --delete --id 1
# 会话(--id 为 uuid,可省略自动生成)
bot db --session --add --channel-name cli --title "调试"
bot db --session --list --status active
bot db --session --update --id <uuid> --status closed
bot db --session --delete --id <uuid>
# 通道
bot db --channel --add --name http --kind http --config '{"port": 8000}'
bot db --channel --update --name http --enabled 0
bot db --channel --delete --name http
# 系统参数
bot db --setting --add --key agent.max_steps --value 80 --description "最大步数"
bot db --setting --show --key agent.max_steps
bot db --setting --update --key agent.max_steps --value 100
bot db --setting --delete --key agent.max_steps
```
操作默认为 `--list`,另有 `--add` / `--update` / `--delete` / `--show`。
关联同步规则:
- 删除 provider:其 models 由外键级联删除,引用这些模型的 `sessions.model_id` 自动置空
- 删除 model:`sessions.model_id` 置空(保留会话记录)
- 设置模型 `--default`:其他模型的 `is_default` 自动置 0(至多一个默认)
- 新增/更新 session 时校验 `model_id` 是否存在
- 删除 channel 不影响历史会话(`sessions.channel` 为文本标识)
## IM 常驻服务(bot serve)
把 IM 渠道接到智能体上,形成 `平台消息 → 事件总线 → 任务 → 智能体 → 回复` 的闭环:
```bash
# 1. 登记企业微信渠道(config 是该 kind 的 JSON 配置)
bot db --channel --add --name wecom --kind wecom \
--config '{"bot_id": "YOUR_BOT_ID", "secret": "YOUR_SECRET"}'
# 2. 启动服务(默认只跑 IM 渠道,虚拟的 cli 会被排除)
bot serve
bot serve --kind wecom # 只启动指定类型
bot serve --channel wecom # 只启动指定渠道名
```
- **会话串行**:同一用户/群按 `session_key` 分区串行,不同用户并行
- **即时回执**:收到消息先回「收到,正在处理…」,不让用户对着空气等
- **流式输出**:支持流式的渠道(企业微信)边生成边覆盖同一条消息;
超过平台 10 分钟存活上限时自动「定稿 + 续开」,用户看到首尾相接的两条
- **插话(steer)**:回复过程中继续发消息不会被排队或丢弃,而是在智能体下一轮
推理前并入上下文,可以中途改方向
- **回复路径**:入站上下文(IM 帧 / `response_url`)随出站 RPC 回传,优先走平台被动回复;
上下文缺失(定时推送等)自动退化为主动发送
- **优雅关停**:`Ctrl+C` 后先停止接收,再冲刷在途消息(默认最多 30 秒),最后断开连接
- **会话历史**:落库在 `sessions` / `messages` 表,重启后可继续对话;插话同样补记为 user 消息
- **模型凭据**:可写在 `providers` / `models` 表(见上一节),不必设环境变量
同一份运行时装配也用于 `bot -i` 交互模式(`flows/runtime.py`),两条入口只有
"生命周期怎么结束"不同。
## 模型配置(环境变量或数据库)
模型与凭据有两个来源,优先级:**环境变量 > 数据库 > 内置默认**。
只用数据库配置(推荐,密钥不落到 shell 历史里):
```bash
# 1. 登记一个 OpenAI 兼容网关(示例:自建代理 / Kimi / 其他厂商)
bot db --provider --add --name gateway --kind openai \
--base-url https://your-gateway/v1 --api-key sk-xxx
# 2. 登记模型并设为默认(is_default 全局唯一)
bot db --model --add --provider-name gateway --name your-model --default
# 3. 启动服务
bot serve --channel wecom
```
规则:
- 未设置 `BOT042_MODEL` 时,使用 `models` 表中 `is_default=1` 的模型;
- 单次任务步数上限同理:`settings.agent.max_steps`(默认 200),`BOT042_MAX_STEPS` 优先;
联网检索类任务步数消耗快,触顶会抛 `GraphRecursionError`,表现为「处理消息时出错」;
- `OPENAI_API_KEY` / `OPENAI_BASE_URL` 为空时,从该模型所属 `providers` 行补齐;
- 环境变量指定的模型与库中默认模型**不一致**时,不会套用库里的密钥
(错用别的 key 只会得到 401);
- 已存在的 provider 改配置用 `bot db --provider --update --id <id>`。
## 配置(环境变量)
| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `BOT042_HOME` | home 目录 | `~/.bot042` |
| `BOT042_MODEL` | langchain 模型标识(`provider:model`) | `openai:gpt-4o-mini` |
| `OPENAI_API_KEY` | OpenAI 兼容 API Key | — |
| `OPENAI_BASE_URL` | 兼容网关地址(DeepSeek / Kimi 等均可) | 官方地址 |
| `BOT042_MAX_STEPS` | 单次任务最大步数(recursion_limit) | `50` |
| `BOT042_MAX_STEPS` | 单次任务最大步数(recursion_limit) | `200` |
| `BOT042_LOG_LEVEL` | 日志级别 | `INFO` |
使用 DeepSeek 等 OpenAI 兼容服务示例:
@@ -45,16 +184,21 @@ $env:BOT042_MODEL = "openai:deepseek-chat"
```
src/bot042/
__main__.py # CLI 入口(uv run bot042)
__main__.py # CLI 入口(bot init / db / 任务 / 交互)
cli.py # bot db 管理命令
config.py # 环境变量配置
agent/ # 智能体:组装(agent.py)、提示词(prompts.py)、工具(tools.py)
channels/ # 通道:与外部世界交互,base.py 定义协议,cli.py 为 CLI 实现
flows/ # 编排:单任务流程(task.py)、交互会话流程(session.py)
tests/ # 冒烟测试
home.py # home 目录解析与初始化
db/ # SQLite(aiosqlite):schema.py(建表)、repo.py(异步 CRUD 与关联同步)
agent/ # 智能体:组装(base.py)、提示词(prompts.py)、工具(tools.py)
middlewares/ # 自定义中间件扩展位
channels/ # 通道:base.py 协议与三层出站、manager.py 编排、im/ 平台适配
flows/ # 编排:bus.py 事件总线、rpc.py 请求-响应、tasks.py 任务与分区串行
# runtime.py 运行时装配、session.py 交互会话、service.py 常驻服务
tests/ # 测试
uv.toml # 国内镜像配置(TUNA PyPI + npmmirror Python)
```
分层关系:`channels`(收/发消息)→ `flows`(组织流程)→ `agent`(智能体与工具)。新增通道实现 `channels.base.Channel` 协议即可复用现有 flows。
分层关系:`channels`(收/发消息)→ `flows`(组织流程)→ `agent`(智能体与工具);`db` 与 `home` 提供本地持久化。
## 开发