aacode

[English](README_en.md) | 

# 🤖 AACode - CLI编程Agent

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)

> 🚀 **基于DeepSeek的智能编程助手** - 借鉴和采用当前流行Agent的先进理念的轻量化ReAct架构

## 设计原则
* 少脚手架，多信任模型：核心逻辑简单，依赖模型自身能力
* 文件化上下文：动态发现，Markdown等文件作为主要存储
* bash万能适配器：通过安全护栏提供灵活的系统访问
* 上下文管理：借鉴了DeepSeek和Manus的智能缩减策略
* 异步设计：所有阻塞操作都是异步的
* 分层工具系统：原子工具、代码包、skills等多层架构
* 安全护栏：全面的命令和路径安全检查
* 可扩展架构：支持自定义工具和模型后端

## 🎯 快速开始
### 操作系统
该项目主要在Linux和MacOS开发和测试，建议使用Linux或MacOS。Windows环境下有人反馈可能会存在python路径问题（个别情况，且容易解决），请自行配置解决。另外，Windows小部分系统命令会有点不同，可能会让Agent一开始有一点受阻，但它很快会自主找到解决方法，整体不影响Agent自由发挥。

### 一键初始化

```bash
git clone https://github.com/kandada/aacode.git
cd aacode
python3 init.py  # 建议最好是3.12版本
# 此时观察一下有没有进入.venv环境，如果没有，请执行:
source .venv/bin/activate
```

### 开始使用
**特别说明**：启动任务之前，你可以在你的任务目录中建一个init.md文件，作为任务详细描述文件，尽可能详细描述你的设计思路等，会能得到更好的结果

```bash
# 使用便捷启动脚本
./run.sh -p examples/my_project "创建一个简单的计算器程序"

# 或手动运行
source .venv/bin/activate
export LLM_API_KEY="your-api-key"
export LLM_API_URL="your-api-url"
export LLM_MODEL_NAME="your-model-name"
python3 main.py -p examples/my_project "你的任务描述"

# 高级模式
## 规划优先模式
python main.py -p examples/my_project "复杂任务" --plan-first
## 交互式连续对话
python main.py -p examples/my_project "初始任务" --interactive
## 指定会话
python main.py --session session_20250128_123456_0 "继续任务"

```


### 或pip 安装（推荐）
pip 安装后可使用aacode命令

```bash
# 安装
pip install aacode

# 初始化配置
aacode init

# 运行
aacode run -p /your/project/path "your task"
```

### 🖥️ 桌面客户端

如果你更喜欢图形界面，可以使用 AACode Desktop 客户端：

| 平台 | 下载 |
|------|------|
| macOS (Apple Silicon) | [AACode_1.6.1_aarch64.dmg](https://github.com/kandada/aacode/raw/main/desktop/AACode_1.6.1_aarch64.dmg) |
| Windows | [aacode-desktop-1.6.1.exe](https://github.com/kandada/aacode/raw/main/desktop/aacode-desktop-1.6.1.exe) |

> 桌面客户端仍需要 Python 环境和依赖库，详细安装步骤请参考 👉 [DESKTOP.md](DESKTOP.md)


## 🔧 配置说明

### 大语言模型（支持deepseek、openai等，不做预配置，需要用户自主配置）
```bash
# OpenAI
export LLM_API_KEY="your-openai-key"
export L