# AI Terminal Assistant

<div align="center">
  <h3>🤖 基于 Claude API 的强大终端 AI 编程助手</h3>
  <p>
    <a href="#特性">特性</a> •
    <a href="#快速开始">快速开始</a> •
    <a href="#文档">文档</a> •
    <a href="#包结构">包结构</a>
  </p>
  <p>
    <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
    <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18.0.0-green">
    <img alt="pnpm" src="https://img.shields.io/badge/pnpm-%3E%3D8.0.0-orange">
  </p>
</div>

## 🌟 项目概述

AI Terminal Assistant 是一个综合性的 AI 驱动开发工具包，帮助开发者更高效地编写代码、调试问题和管理项目。作为模块化的 monorepo 架构，它提供多种界面（CLI、Web、Desktop）与 Claude AI 交互，完成各种编程任务。

## ✨ 特性

### 核心功能
- 🧠 **高级 AI 代理** - 基于 Claude API 的流式响应
- 🔧 **丰富的工具系统** - 文件操作、bash 命令、代码搜索等
- 📝 **智能代码编辑** - 多种编辑模式（整体、差异、搜索替换）
- 🔍 **语言服务协议** - 类 IDE 的代码智能提示
- 💾 **检查点系统** - Shadow Git 安全实验
- 🔌 **模型上下文协议** - 可扩展的工具集成
- 🎣 **钩子系统** - 执行前后的自定义处理

### 用户界面
- 🖥️ **CLI** - 原生终端体验，支持 serve/attach 模式
- 🌐 **Web UI** - 现代化 React 界面，实时更新
- 🖱️ **桌面应用** - 基于 Tauri 的原生应用（即将推出）

### 开发体验
- 📦 **Monorepo 架构** - 清晰的关注点分离
- 🚀 **基于 Bun 构建** - 快速运行时和打包
- 🔥 **热重载** - 即时反馈的开发体验
- 🧪 **全面的测试** - 单元测试和集成测试
- 📊 **类型安全** - 完整的 TypeScript 支持

## 🚀 快速开始

### 前置要求
- Node.js 18+ 或 Bun 1.0+
- pnpm 8.0+
- Anthropic API Key

### 安装

```bash
# 克隆仓库
git clone <repository-url>
cd ai-terminal-assistant

# 安装依赖
pnpm install

# 设置环境变量
cp .env.example .env
# 编辑 .env 文件，添加你的 ANTHROPIC_API_KEY

# 构建所有包
pnpm build
```

### 运行应用

#### 选项 1：Web 界面
```bash
# 启动服务器
pnpm server:dev

# 在另一个终端，启动 Web UI
pnpm web:dev

# 在浏览器中打开 http://localhost:5173
```

#### 选项 2：CLI 模式
```bash
# 启动服务器
cd packages/cli && bun run src/index.ts serve --port 3000

# 在另一个终端，连接到服务器
cd packages/cli && bun run src/index.ts attach http://localhost:3000
```

## 📦 包结构

这个 monorepo 包含四个主要包：

| 包名 | 描述 | 状态 |
|---------|-------------|--------|
| [@ai-assistant/core](./packages/core) | 核心代理引擎、工具和集成 | ✅ 稳定 |
| [@ai-assistant/server](./packages/server) | HTTP/WebSocket 服务器，提供 REST API | ✅ 稳定 |
| [@ai-assistant/cli](./packages/cli) | 命令行界面 | ✅ 稳定 |
| [@ai-assistant/web](./packages/web) | 基于 React 的 Web 界面 | ✅ 稳定 |
| [@ai-assistant/desktop](./packages/desktop) | 基于 Tauri 的桌面应用 | 🚧 开发中 |

## 🏗️ 架构

```mermaid
graph TD
    Web[Web UI] --> Server
    CLI[CLI] --> Server
    Desktop[桌面应用] --> Server
    Server --> Core[核心引擎]
    Core --> Tools[工具系统]
    Core --> LSP[语言服务器]
    Core --> MCP[模型上下文协议]
    Core --> Checkpoint[检查点系统]
```

### 技术栈

- **运行时**: Bun / Node.js
- **语言**: TypeScript
- **服务器**: Hono + Bun WebSocket
- **前端**: React + Vite + Tailwind CSS
- **桌面**: Tauri (Rust + WebView)
- **测试**: Vitest
- **包管理**: pnpm (monorepo)

## 📖 文档

详细文档位于 [docs](./docs) 目录：

- [架构概览](./docs/design/architecture/gui-server-client.md)
- [API 参考](./docs/api/README.md)
- [开发指南](./docs/development/README.md)
- [配置指南](./docs/configuration/README.md)

## 🛠️ 开发

### 常用命令

```bash
# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行测试
pnpm test
pnpm test:coverage

# 代码检查
pnpm lint

# 类型检查
pnpm typecheck

# 清理构建产物
pnpm clean
```

### 特定包开发

```bash
# 开发特定包
pnpm --filter @ai-assistant/core dev
pnpm --filter @ai-assistant/server test
pnpm --filter @ai-assistant/web build
```

## 🔧 配置

### 环境变量

在根目录创建 `.env` 文件：

```env
# 必需
ANTHROPIC_API_KEY=sk-ant-xxxxx

# 可选
AI_MODEL=claude-sonnet-4-20250514
AI_MAX_TOKENS=4096
SERVER_PORT=3000
SERVER_HOST=localhost
```

### 支持的模型

- `claude-sonnet-4-20250514` (默认)
- `claude-haiku-3-20251120`
- 其他 Claude 模型

## 🤝 贡献

欢迎贡献！请查看我们的[贡献指南](./CONTRIBUTING.md)了解详情。

1. Fork 仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。

## 🙏 致谢

- 基于 Anthropic 的 [Claude API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) 构建
- 由 [Bun](https://bun.sh) 提供快速 JavaScript 运行时
- UI 组件来自 [Tailwind CSS](https://tailwindcss.com)
- 桌面应用基于 [Tauri](https://tauri.app) 构建

## 📞 支持

- 📧 邮箱：support@example.com
- 💬 Discord：[加入我们的社区](https://discord.gg/example)
- 🐛 问题反馈：[GitHub Issues](https://github.com/username/repo/issues)

---

<div align="center">
  由 AI Terminal Assistant 团队用 ❤️ 制作
</div>