# 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 --status closed bot db --session --delete --id # 通道 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 `。 ## 配置(环境变量) | 变量 | 说明 | 默认值 | | --- | --- | --- | | `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`