- 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
217 lines
9.6 KiB
Markdown
217 lines
9.6 KiB
Markdown
# bot042
|
||
|
||
基于 [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:`bot init` / 单次任务 / 交互模式
|
||
- IM 闭环:`bot serve` 常驻运行企业微信等渠道,`平台消息 → 事件总线 → 任务 → 智能体 → 回复`
|
||
- 文件检索:随依赖安装 `ripgrep`,deepagents 的 `grep` 工具走 `rg`(遵守 `.gitignore`,约 4 MB)
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
uv sync
|
||
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 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) | `200` |
|
||
| `BOT042_LOG_LEVEL` | 日志级别 | `INFO` |
|
||
|
||
使用 DeepSeek 等 OpenAI 兼容服务示例:
|
||
|
||
```bash
|
||
$env:OPENAI_BASE_URL = "https://api.deepseek.com/v1"
|
||
$env:OPENAI_API_KEY = "sk-..."
|
||
$env:BOT042_MODEL = "openai:deepseek-chat"
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/bot042/
|
||
__main__.py # CLI 入口(bot init / db / 任务 / 交互)
|
||
cli.py # bot db 管理命令
|
||
config.py # 环境变量配置
|
||
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`(智能体与工具);`db` 与 `home` 提供本地持久化。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
uv run pytest # 运行测试
|
||
uv run ruff check # 代码检查
|
||
uv run ruff format # 格式化
|
||
```
|
||
|
||
## 镜像源
|
||
|
||
`uv.toml` 已配置国内镜像,`uv sync` / `uv python install` 均自动生效:
|
||
|
||
- PyPI 包:清华大学 TUNA — `https://pypi.tuna.tsinghua.edu.cn/simple`
|
||
- Python(python-build-standalone):npmmirror — `https://registry.npmmirror.com/-/binary/python-build-standalone`
|