docs: 添加中文文档

2025-12-12 15:31:38 +08:00
parent 4ca8c413a6
commit 563224fa73
6 changed files with 1947 additions and 0 deletions
@@ -0,0 +1,225 @@
+# 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>