BareAgent

纯 Python 终端代码智能体 — 可插拔 LLM、细粒度权限、多智能体协调、可扩展技能系统

✨ 核心特性

🏗️ 架构概览

核心循环 agent_loop() 是中央调度器：调用 LLM → 解析工具调用 → 权限检查 → 执行处理器 → 收集结果，最多迭代 200 次。支持流式输出和长对话消息自动压缩。

🚀 快速开始

环境要求

• Python 3.12+
• uv（推荐）

安装

作为命令行工具使用（推荐，隔离安装，安装后全局可用 bareagent）：

uv tool install bareagent-cli      # 或: pipx install bareagent-cli

从源码开发（可编辑安装）：

uv pip install -e ".[dev]"

发布到 PyPI / 自动发布流程见 docs/releasing.md。

配置

API Key 设置

# Linux / macOS
export OPENAI_API_KEY="your-key-here"

# Windows PowerShell（当前会话）
$env:OPENAI_API_KEY="your-key-here"

# Windows PowerShell（永久生效）
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-key-here", "User")

配置文件

默认配置随包内置（只读），本地覆盖写入当前工作目录的 config.local.toml（已 git-ignore； bareagent init 会帮你生成）。源码仓库里的 src/bareagent/config.toml 只是开发模板，普通安装用户不需要编辑它。也可用 --config <path> / BAREAGENT_CONFIG 指定其他配置文件：

[provider]
name = "openai"
model = "gpt-4.1"
api_key_env = "OPENAI_API_KEY"

[permission]
mode = "default"

[ui]
stream = true
theme = "dark"

[thinking]
mode = "adaptive"
budget_tokens = 10000

[subagent]
max_depth = 3
default_type = "general-purpose"

环境变量

配置优先级：config.toml → config.local.toml → 环境变量 / CLI 参数（优先级递增）。

运行

bareagent
# 或
python -m bareagent.main

CLI 参数

bareagent --provider anthropic --model claude-sonnet-4-20250514
bareagent --provider openai --model gpt-4.1
bareagent --config ~/my_config.toml

💻 REPL 命令速查

快捷键：

图片输入：/attach <path> 或 Ctrl+V 粘贴的图片会落在 workspace 内的 .bareagent_attachments/（建议加进 .gitignore），提交时自动提示模型用 read_file 查看。非 vision 模型读图会返回友好错误——换 vision 模型，或在 [capabilities] 设 image_in = true（详见 config.toml）。剪贴板粘贴需装 uv pip install -e ".[clipboard]"； 未装时 /attach 仍可用。

🔐 权限模式

切换方式：/default、/auto、/plan、/bypass、/mode 或 Shift+Tab。

📁 项目结构

src/bareagent/
├── main.py                # 入口与 REPL 循环
├── core/                  # 智能体循环、工具注册、Schema、沙箱
│   ├── loop.py            #   核心 agent_loop()
│   ├── tools.py           #   工具注册与分发
│   ├── schema.py          #   工具 Schema 定义
│   ├── context.py         #   系统提示组装
│   ├── sandbox.py         #   路径安全检查
│   ├── fileutil.py        #   文件工具函数
│   └── handlers/          #   各工具处理器实现
├── provider/              # LLM 提供商抽象
│   ├── base.py            #   BaseLLMProvider
│   ├── anthropic.py       #   Anthropic 实现
│   ├── openai.py          #   OpenAI 实现
│   └── factory.py         #   工厂
├── permission/            # 权限守卫
│   ├── guard.py           #   PermissionGuard（4 种模式）
│   └── rules.py           #   权限规则解析
├── memory/                # 消息压缩与会话管理
│   ├── compact.py         #   Compactor（微压缩 + LLM 摘要）
│   ├── token_counter.py   #   Token 估算
│   └── transcript.py      #   会话转录管理
├── planning/              # 任务、TODO、技能、子智能体
│   ├── agent_types.py     #   智能体类型系统
│   ├── subagent.py        #   子智能体委派
│   ├── tasks.py           #   持久化任务管理
│   ├── todo.py            #   会话级 TODO
│   └── skills.py          #   技能发现与加载
├── skills/                # 内置技能模块
├── team/                  # 多智能体协调
│   ├── mailbox.py         #   JSONL 消息总线
│   ├── autonomous.py      #   自治智能体守护进程
│   ├── manager.py         #   TeammateManager
│   └── protocols.py       #   请求-响应协议
├── concurrency/           # 后台执行与通知
│   ├── background.py      #   BackgroundManager
│   └── notification.py    #   后台通知
└── ui/                    # 终端 UI（rich + 流式）
    ├── console.py         #   AgentConsole
    └── stream.py          #   StreamPrinter
tests/                     # pytest 测试

🔗 完整文档

项目提供基于 VitePress 的完整文档，涵盖架构设计、模块详解、开发指南等 15 个章节：

cd docs
npm install
npm run docs:dev

文档源码位于 docs/ 目录。

🛠️ 开发

# Python 质量门
uv run ruff check src tests
uv run ruff format --check src tests
uv run pyright
uv run pytest                              # 默认测试（排除 manual）
uv run pytest -m socket                    # localhost socket 专项

# 定向测试 / 本地格式化
uv run pytest tests/test_loop.py
uv run pytest tests/test_loop.py -k "test_name"
uv run ruff check --fix src tests
uv run ruff format src tests

# 文档构建
cd docs
npm run docs:build

本地 CI 闸（pre-push hook）

仓库自带一个 push 前的本地核心检查闸（ruff check、format check、pyright、默认 pytest 全部经 uv run）， 在代码推上去变红之前先在本地拦下来。用 uv run 而非 python -m pytest——后者会把当前目录前插到 sys.path，掩盖只有 CI 裸 uv run pytest 才暴露的导入差异。

# 一次性启用（committed hook 不会自动生效，每个新 clone 装一次）
bash scripts/setup-hooks.sh        # 等价于 git config core.hooksPath .githooks

# 手动跑一遍 CI 同款检查
bash scripts/ci-check.sh

# 临时跳过本地闸（例如只推 journal）
BAREAGENT_PREPUSH_SKIP=1 git push  # 或 git push --no-verify

socket 专项与文档构建按上面的命令单独运行；PR/main CI 会额外阻塞 socket suite。万一本地闸被绕过、 main 仍变红，CI 会自动开一个 ci-failure issue 跟踪，恢复后自动关闭。tag/TestPyPI 发布也会先复用 完整 CI 门，详细发布路径见 docs/releasing.md。

提交信息遵循 Conventional Commits：Fix:、Feat:、Refactor:、Test:、Docs:

📄 许可证

MIT