Files
openbot 5da55f8d17 fix(flows): 步数预算与图硬上限分离,预算耗尽时优雅收尾
max_steps 以前同时充当软预算和 recursion_limit,于是预算耗尽的那一刻
必然触发 GraphRecursionError:模型连一句收尾都来不及说,用户只收到
「处理消息时出错,请稍后再试」,已产出的内容也不会落库。

- 新增 StepBudgetMiddleware:按模型调用轮数计账(agent_rounds =
  max_steps // 2),剩余 <=4 轮时注入一次「立刻停止调用工具、给出结论」
  的收尾提示,只提醒一次
- 新增 STEP_GRACE(20),recursion_limit = max_steps + STEP_GRACE,把余量
  留给收尾动作
- GraphRecursionError 统一转成 StepBudgetExceeded,ainvoke 与流式两条
  路径都覆盖
- AgentReply 把「步数用尽」渲染成可操作说明,接在已产出内容之后一并
  下发并落库;用 _reported 标记让 on_error 不再补发通用错误文案,任务
  状态仍如实记 failed
- 同步 README / docs/architecture.md / db/schema.py 中 max_steps 的语义

测试:新增 tests/test_budget.py(7 个用例),全量 241 passed。
2026-11-09 21:32:29 +08:00

219 lines
9.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 优先;
预算将尽时智能体先收到一条「立刻收尾」提示,把已完成的部分总结出来;交给 LangGraph
的硬上限是 `max_steps + 20` 个图步,真撞上时用户看到的是「本轮执行步数用尽(上限 N 步)」
加已产出的内容,而不是笼统的「处理消息时出错」;
- `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` | 单次任务步数预算(软上限,硬上限为其 +20) | `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`