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

9.8 KiB
Raw Permalink Blame History

bot042

基于 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)

快速开始

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 步并播报状态"

交互模式:

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)

# 提供商
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 渠道接到智能体上,形成 平台消息 → 事件总线 → 任务 → 智能体 → 回复 的闭环:

# 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 历史里):

# 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 兼容服务示例:

$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 提供本地持久化。

开发

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