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:
1 parent
94421e5c2b
commit
fbb01c4c83
65 files changed
+15322
-173
No files matched your search
@@ -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` 提供本地持久化。
|
||||
|
||||
## 开发
|
||||
|
||||
|
||||
Reference in new issue
Block a user