9ce0ba0e13bfca881cc4ab59ef153f36a6a45810
媒体功能是上一轮智能体自改代码时留下的 WIP(那轮步数耗尽被中断)。 本次把手头完成度较高的部分整理到可提交状态,并修掉其中两处判定 bug。 入站(已可用): - 新增 flows/media_input.py:附件先落盘再进上下文,小图内联为 base64, 大图与音视频退化为「路径 + 元信息」,附件级失败只降级为说明而不打断整轮 - processor 改用 prepare_inbound,文本 / 多模态输入据此决定发纯文本还是 content blocks 出站(骨架就位,尚未接线): - 新增 agent/outbox.py、channels/media.py(大小与类型校验、限长下载 / 读取) - 新增 send_image / send_file 工具、ChannelServices.send_content、 MessageEvent.content_event / media_event - 目前还没有任何调用方创建 MediaOutbox,因此这两个工具一律返回 「当前不在渠道会话中」;渠道侧的 _send_media 由各平台子类实现 修复: - prepare_inbound 不再塞「(无内容)」占位块:占位块会让 has_content 恒真, 空消息也能一路跑到 run_task,白烧一次模型调用 - 新增 PreparedInbound.is_multimodal 取代 len(blocks) > 1 的猜测: 「只有一张图、没有正文」时 blocks 只有 1 个,原逻辑会把附件丢掉 - 附件全部接收失败时回「附件未能接收:<原因>」,不再误报「空消息」 - 顺手清掉 ruff 告警(未用导入、__all__ 未排序、嵌套 if / with) 测试:test_processor 拆成三个用例(空消息 / 附件全失败 / 仅附件必须发 blocks,最后一条是防回潮的回归测试),全量 243 passed,ruff 全绿。
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
Description
Autonomous robot prototype built on deepagents
712 KiB
0 Stars
1 Watchers
0 Forks
Languages
Python
100%