kurihada/ai-terminal-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新项目文档

Browse Source
This commit is contained in:
kurihada
2025-12-12 14:28:34 +08:00
parent 2fe1c55997
commit b17649930b
6 changed files with 1894 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+172 -128
View File
@@ -1,180 +1,224 @@
# AI Terminal Assistant
**由 kurihada 开发**
<div align="center">
<h3>🤖 A powerful terminal-based AI coding assistant powered by Claude API</h3>
<p>
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#documentation">Documentation</a> •
<a href="#packages">Packages</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 编程助手，基于 Claude API 构建。可以帮助您读取和写入文件、执行 bash 命令、搜索代码和文件、回答编程问题等。
## 🌟 Overview
## ✨ 特性
AI Terminal Assistant is a comprehensive AI-powered development toolkit that helps developers write code, debug issues, and manage projects more efficiently. Built as a modular monorepo, it provides multiple interfaces (CLI, Web, Desktop) to interact with Claude AI for various programming tasks.
- 🚀 **终端原生体验**：直接在终端中与 AI 交互
- 🔧 **强大的工具集**：
- 文件读写操作
- Bash 命令执行
- 目录列表和文件搜索
- 代码分析和建议
- 🛡️ **安全第一**：在执行可能有风险的命令前会请求确认
- 💬 **两种模式**：
- 交互模式：持续对话
- 单次提问模式：快速获取答案
- ⚙️ **可配置**：支持多种 AI 模型和参数配置
## ✨ Features
## 📦 安装
### Core Capabilities
- 🧠 **Advanced AI Agent** - Powered by Claude API with streaming responses
- 🔧 **Rich Tool System** - File operations, bash commands, code search, and more
- 📝 **Smart Code Editing** - Multiple edit modes (whole, diff, search-replace)
- 🔍 **Language Server Protocol** - IDE-like code intelligence
- 💾 **Checkpoint System** - Shadow Git for safe experimentation
- 🔌 **Model Context Protocol** - Extensible tool integration
- 🎣 **Hook System** - Pre/post execution customization
### 前提条件
- Node.js 18+
### User Interfaces
- 🖥️ **CLI** - Terminal-native experience with serve/attach modes
- 🌐 **Web UI** - Modern React interface with real-time updates
- 🖱️ **Desktop App** - Tauri-based native application (Coming soon)
### Developer Experience
- 📦 **Monorepo Architecture** - Clean separation of concerns
- 🚀 **Built with Bun** - Fast runtime and bundling
- 🔥 **Hot Reload** - Development with instant feedback
- 🧪 **Comprehensive Testing** - Unit and integration tests
- 📊 **Type Safety** - Full TypeScript support
## 🚀 Quick Start
### Prerequisites
- Node.js 18+ or Bun 1.0+
- pnpm 8.0+
- Anthropic API Key
### 全局安装
```bash
npm install -g .
```
### Installation
### 本地开发
```bash
# 克隆项目
git clone <your-repo-url>
# Clone the repository
git clone <repository-url>
cd ai-terminal-assistant
# 安装依赖
npm install
# Install dependencies
pnpm install
# 构建项目
npm run build
# Set up environment variables
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY
# 链接到全局
npm link
# Build all packages
pnpm build
```
## 🚀 快速开始
### Running the Application
### 1. 初始化配置
#### Option 1: Web Interface
```bash
ai-assist init
```
按照提示设置您的 Anthropic API Key。
# Start the server
pnpm server:dev
### 2. 启动交互模式
# In another terminal, start the web UI
pnpm web:dev
# Open http://localhost:5173 in your browser
```
#### Option 2: CLI Mode
```bash
ai-assist
# Start the server
cd packages/cli && bun run src/index.ts serve --port 3000
# In another terminal, attach to the server
cd packages/cli && bun run src/index.ts attach http://localhost:3000
```
### 3. 单次提问模式
## 📦 Packages
This monorepo contains four main packages:
| Package | Description | Status |
|---------|-------------|--------|
| [@ai-assistant/core](./packages/core) | Core agent engine, tools, and integrations | ✅ Stable |
| [@ai-assistant/server](./packages/server) | HTTP/WebSocket server with REST API | ✅ Stable |
| [@ai-assistant/cli](./packages/cli) | Command-line interface | ✅ Stable |
| [@ai-assistant/web](./packages/web) | React-based web interface | ✅ Stable |
## 🏗️ Architecture
```mermaid
graph TD
Web[Web UI] --> Server
CLI[CLI] --> Server
Desktop[Desktop App] --> Server
Server --> Core[Core Engine]
Core --> Tools[Tool System]
Core --> LSP[Language Server]
Core --> MCP[Model Context Protocol]
Core --> Checkpoint[Checkpoint System]
```
### Technology Stack
- **Runtime**: Bun / Node.js
- **Language**: TypeScript
- **Server**: Hono + Bun WebSocket
- **Frontend**: React + Vite + Tailwind CSS
- **Desktop**: Tauri (Rust + WebView)
- **Testing**: Vitest
- **Package Manager**: pnpm (monorepo)
## 📖 Documentation
Detailed documentation is available in the [docs](./docs) directory:
- [Architecture Overview](./docs/design/architecture/gui-server-client.md)
- [API Reference](./docs/api/README.md)
- [Development Guide](./docs/development/README.md)
- [Configuration Guide](./docs/configuration/README.md)
## 🛠️ Development
### Common Commands
```bash
ai-assist ask "如何读取当前目录下的所有文件？"
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test
pnpm test:coverage
# Linting
pnpm lint
# Type checking
pnpm typecheck
# Clean build artifacts
pnpm clean
```
## 🎯 使用示例
### Package-specific Development
### 文件操作
```
用户：读取 package.json 文件
AI：正在读取 package.json...
（显示文件内容）
用户：修改版本号为 1.0.1
AI：确认要修改 package.json 吗？ (y/n)
```bash
# Work on a specific package
pnpm --filter @ai-assistant/core dev
pnpm --filter @ai-assistant/server test
pnpm --filter @ai-assistant/web build
```
### 代码分析
```
用户：帮我分析 src/index.ts 中的主要功能
AI：正在读取文件...
（分析代码结构，解释主要功能）
```
## 🔧 Configuration
### 系统命令
```
用户：查看当前目录的文件列表
AI：正在执行 ls -la...
（显示目录内容）
用户：安装 lodash 包
AI：确认要执行 npm install lodash 吗？ (y/n)
```
### Environment Variables
## 🔧 配置
### 环境变量
创建 `.env` 文件（参考 `.env.example`）：
Create a `.env` file in the root directory:
```env
# Anthropic API Key (必需)
# Required
ANTHROPIC_API_KEY=sk-ant-xxxxx
# 可选配置
# Optional
AI_MODEL=claude-sonnet-4-20250514
AI_MAX_TOKENS=4096
SERVER_PORT=3000
SERVER_HOST=localhost
```
### 支持的 AI 模型
- `claude-sonnet-4-20250514` (默认)
### Supported Models
- `claude-sonnet-4-20250514` (default)
- `claude-haiku-3-20251120`
- 其他 Claude 模型
- Other Claude models
## 📁 项目结构
## 🤝 Contributing
```
ai-terminal-assistant/
├── src/
│ ├── core/ # 核心代理逻辑
│ ├── tools/ # 工具函数
│ │ ├── bash.ts # Bash 命令工具
│ │ ├── file.ts # 文件操作工具
│ │ └── index.ts # 工具导出
│ ├── ui/ # 用户界面
│ ├── utils/ # 工具函数
│ └── index.ts # 主入口文件
├── dist/ # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
## 🛠️ 开发
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### 构建项目
```bash
npm run build
```
## 📄 License
### 开发模式
```bash
npm run dev
```
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
### 代码检查
```bash
npm run lint
```
## 🙏 Acknowledgments
## ⚠️ 安全注意事项
- Built with [Claude API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) by Anthropic
- Powered by [Bun](https://bun.sh) for fast JavaScript runtime
- UI components from [Tailwind CSS](https://tailwindcss.com)
- Desktop app built with [Tauri](https://tauri.app)
1. **API Key 安全**：不要将 `.env` 文件提交到版本控制
2. **命令确认**：AI 在执行修改文件或运行系统命令前会请求确认
3. **权限管理**：确保 AI 助手只有必要的文件访问权限
## 📞 Support
## 📝 许可证
MIT License
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 🐛 问题反馈
如果您遇到任何问题，请：
1. 检查 API Key 是否正确配置
2. 确保有足够的 API 额度
3. 查看终端错误信息
4. 在 GitHub 上提交 Issue
## 📚 相关技术
- [Claude API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api)
- [Node.js](https://nodejs.org/)
- [TypeScript](https://www.typescriptlang.org/)
- [Commander.js](https://github.com/tj/commander.js) - CLI 框架
- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) - 交互式命令行界面
- 📧 Email: support@example.com
- 💬 Discord: [Join our community](https://discord.gg/example)
- 🐛 Issues: [GitHub Issues](https://github.com/username/repo/issues)
---
**提示**：AI 助手会尽力帮助您，但请始终审查它建议的代码更改和命令执行，特别是在生产环境中。
<div align="center">
Made with ❤️ by the AI Terminal Assistant Team
</div>