Metadata-Version: 2.4
Name: bareagent-cli
Version: 0.1.0
Summary: A pure Python terminal code agent — pluggable LLM providers, fine-grained permissions, multi-agent coordination, and an extensible skill system.
Project-URL: Homepage, https://github.com/525300887039/BareAgent
Project-URL: Repository, https://github.com/525300887039/BareAgent
Project-URL: Issues, https://github.com/525300887039/BareAgent/issues
Author-email: ducat <no.525350@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,anthropic,cli,coding-agent,llm,openai,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.52
Requires-Dist: httpx>=0.27
Requires-Dist: openai>=1.70
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich>=14.0
Provides-Extra: all-tracing
Requires-Dist: langfuse>=2.0; extra == 'all-tracing'
Requires-Dist: opentelemetry-api>=1.20; extra == 'all-tracing'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == 'all-tracing'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all-tracing'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: fastembed>=0.8; extra == 'embeddings'
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Provides-Extra: lsp
Requires-Dist: multilspy>=0.0.15; extra == 'lsp'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == 'pdf'
Description-Content-Type: text/markdown

# BareAgent

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

<!-- badges placeholder -->
![Python](https://img.shields.io/badge/Python-3.12%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)

---

## ✨ 核心特性

<p align="center">
  <img src="https://raw.githubusercontent.com/525300887039/BareAgent/main/docs/public/readme-features-overview.png" alt="BareAgent 核心特性概览" width="720" />
</p>

| 特性 | 说明 |
|------|------|
| **多提供商支持** | Anthropic / OpenAI / DeepSeek，统一接口，流式与非流式输出自由切换 |
| **内置工具** | bash、文件读写编辑、glob、grep 等开箱即用，延迟加载按需注册 |
| **权限守卫** | 四种模式（DEFAULT / AUTO / PLAN / BYPASS），危险命令自动拦截 |
| **多智能体协调** | 基于 JSONL 邮箱的消息总线，守护进程式自治智能体，请求-响应协议 |
| **子智能体委派** | 隔离上下文、递归深度限制、类型化智能体（explore/plan/code-review）、后台异步执行 |
| **技能系统** | 从 `skills/*/SKILL.md` 自动发现，按需加载（code-review、git、test） |
| **任务管理** | 持久化任务 + 会话级 TODO，支持依赖追踪和优先级 |
| **消息压缩** | 微压缩 + LLM 摘要，基于 token 阈值（50k）触发，支撑超长对话 |
| **会话管理** | 会话转录持久化，支持列出历史会话和恢复上下文 |
| **运行时切换** | 斜杠命令或 `Shift+Tab` 快捷键实时切换权限模式，无需重启 |

---

## 🏗️ 架构概览

<p align="center">
  <img src="https://raw.githubusercontent.com/525300887039/BareAgent/main/docs/guide/images/ch01-architecture.png" alt="BareAgent 架构图" width="720" />
</p>

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

---

## 🚀 快速开始

### 环境要求

- Python 3.12+
- [uv](https://github.com/astral-sh/uv)（推荐）

### 安装

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

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

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

```bash
uv pip install -e ".[dev]"
```

> 发布到 PyPI / 自动发布流程见 [`docs/releasing.md`](docs/releasing.md)。

### 配置

#### API Key 设置

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

```powershell
# 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` 会帮你生成）。也可用 `--config <path>` / `BAREAGENT_CONFIG` 指定其他配置文件：

```toml
[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"
```

#### 环境变量

<p align="center">
  <img src="https://raw.githubusercontent.com/525300887039/BareAgent/main/docs/public/readme-config-flow.png" alt="配置流程图" width="640" />
</p>

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

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `BAREAGENT_PROVIDER` | 提供商名称 | `openai` |
| `BAREAGENT_MODEL` | 模型名称 | `gpt-4.1` |
| `BAREAGENT_API_KEY` | 明文 API 密钥（优先于 `api_key_env`） | — |
| `BAREAGENT_API_KEY_ENV` | API 密钥环境变量名 | 按提供商自动设置 |
| `BAREAGENT_BASE_URL` | 自定义 API 基础 URL | — |
| `BAREAGENT_PERMISSION_MODE` | 权限模式 | `default` |
| `BAREAGENT_UI_STREAM` | 是否流式输出 | `true` |
| `BAREAGENT_UI_THEME` | UI 主题 | `dark` |
| `BAREAGENT_THINKING_MODE` | 思考模式（adaptive/enabled/disabled） | `adaptive` |
| `BAREAGENT_THINKING_BUDGET_TOKENS` | 思考 token 预算 | `10000` |
| `BAREAGENT_SKILLS_DIR` | 技能目录路径 | 自动发现 |
| `BAREAGENT_SUBAGENT_MAX_DEPTH` | 子智能体最大递归深度 | `3` |
| `BAREAGENT_SUBAGENT_DEFAULT_TYPE` | 子智能体默认类型 | `general-purpose` |

### 运行

```bash
bareagent
# 或
python -m bareagent.main
```

#### CLI 参数

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

| 参数 | 说明 |
|------|------|
| `--provider` | 覆盖配置文件中的 LLM 提供商（anthropic / openai / deepseek） |
| `--model` | 覆盖配置文件中的模型名称 |
| `--config` | 指定 TOML 配置文件路径（默认 `config.toml`，支持 `~` 扩展） |

---

## 💻 REPL 命令速查

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助信息，列出所有可用命令 |
| `/exit` | 退出 BareAgent，广播关闭信号给所有团队成员 |
| `/clear` | 清屏并启动新对话（重置消息历史和会话 ID） |
| `/new` | 启动新对话（仅重置消息，不清屏） |
| `/compact` | 压缩对话上下文，生成 LLM 摘要释放 token |
| `/default` | 切换到 DEFAULT 权限模式 |
| `/auto` | 切换到 AUTO 权限模式 |
| `/plan` | 切换到 PLAN 权限模式（只读） |
| `/bypass` | 切换到 BYPASS 权限模式（无确认） |
| `/mode` | 交互式权限模式选择菜单 |
| `/sessions` | 列出已保存的历史会话 |
| `/resume [id]` | 恢复上一个会话（可选指定会话 ID） |
| `/team` | 管理团队智能体（子命令：`list`、`spawn <name>`、`send <name> <msg>`） |

**快捷键：**

| 按键 | 功能 |
|------|------|
| `Shift+Tab` | 循环切换权限模式（DEFAULT → AUTO → PLAN → BYPASS） |
| `Ctrl+C` | 中断当前操作（按两次退出） |
| `Ctrl+Z` | 立即退出 REPL |

---

## 🔐 权限模式

| 模式 | 行为 | 适用场景 |
|------|------|---------|
| **DEFAULT** | 写操作需用户确认，安全工具自动批准 | 日常使用（默认） |
| **AUTO** | 安全命令（ls、cat、git status、pytest 等）自动通过，仅拦截危险命令 | 信任环境下的高效开发 |
| **PLAN** | 只允许只读工具，所有写操作被阻止 | 代码审查、方案设计 |
| **BYPASS** | 所有操作自动批准，无任何确认 | 完全信任的自动化场景 |

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

---

## 📁 项目结构

<p align="center">
  <img src="https://raw.githubusercontent.com/525300887039/BareAgent/main/docs/public/readme-project-layers.png" alt="项目分层架构图" width="640" />
</p>

```
src/
├── 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          #   技能发现与加载
├── 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
skills/                    # 可扩展技能模块
tests/                     # pytest 测试
```

---

## 🔗 完整文档

项目提供基于 [VitePress](https://vitepress.dev/) 的完整文档，涵盖架构设计、模块详解、开发指南等 15 个章节：

```bash
cd docs
npm install
npm run docs:dev
```

文档源码位于 [`docs/`](docs/) 目录。

---

## 🛠️ 开发

```bash
# 测试
pytest                             # 全部测试
pytest tests/test_loop.py          # 单个文件
pytest tests/test_loop.py -k "test_name"  # 单个测试

# 代码检查与格式化
ruff check src tests               # 检查
ruff check --fix src tests          # 自动修复
ruff format src tests               # 格式化
```

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

---

## 📄 许可证

[MIT](LICENSE)
