docs: 更新项目文档
This commit is contained in:
@@ -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>
|
||||
@@ -0,0 +1,321 @@
|
||||
# @ai-assistant/cli
|
||||
|
||||
Command-line interface for AI Terminal Assistant - interact with AI directly from your terminal.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Global installation
|
||||
pnpm add -g @ai-assistant/cli
|
||||
|
||||
# Or run directly with npx/bunx
|
||||
npx @ai-assistant/cli
|
||||
bunx @ai-assistant/cli
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **Dual Modes** - Server mode and client attach mode
|
||||
- **Interactive Chat** - Rich terminal UI with syntax highlighting
|
||||
- **Streaming Responses** - Real-time AI responses
|
||||
- **File Attachments** - Attach files to messages
|
||||
- **Command History** - Navigate through previous commands
|
||||
- **Auto-completion** - Tab completion for commands
|
||||
- **Colored Output** - Beautiful terminal formatting
|
||||
- **Session Management** - Persistent conversation history
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Server Mode
|
||||
|
||||
Start a local AI server:
|
||||
|
||||
```bash
|
||||
# Start server on default port 3000
|
||||
ai-assist serve
|
||||
|
||||
# Start on custom port
|
||||
ai-assist serve --port 8080
|
||||
|
||||
# With specific model
|
||||
ai-assist serve --model claude-haiku-3-20251120
|
||||
|
||||
# With verbose logging
|
||||
ai-assist serve --verbose
|
||||
```
|
||||
|
||||
### Client Mode
|
||||
|
||||
Attach to a running AI server:
|
||||
|
||||
```bash
|
||||
# Attach to local server
|
||||
ai-assist attach
|
||||
|
||||
# Attach to remote server
|
||||
ai-assist attach https://ai-server.example.com
|
||||
|
||||
# Attach with authentication
|
||||
ai-assist attach https://ai-server.example.com --token YOUR_TOKEN
|
||||
|
||||
# Attach to specific session
|
||||
ai-assist attach --session my-session-id
|
||||
```
|
||||
|
||||
## 📚 Commands
|
||||
|
||||
### Global Options
|
||||
|
||||
```bash
|
||||
ai-assist [command] [options]
|
||||
|
||||
Options:
|
||||
-h, --help Show help
|
||||
-v, --version Show version
|
||||
--config <path> Path to config file
|
||||
--verbose Enable verbose logging
|
||||
```
|
||||
|
||||
### Server Command
|
||||
|
||||
```bash
|
||||
ai-assist serve [options]
|
||||
|
||||
Options:
|
||||
-p, --port <port> Server port (default: 3000)
|
||||
-h, --host <host> Server host (default: localhost)
|
||||
--api-key <key> Anthropic API key (or use ANTHROPIC_API_KEY env)
|
||||
--model <model> AI model to use
|
||||
--max-tokens <n> Maximum response tokens
|
||||
--no-auth Disable authentication
|
||||
--cors-origin <origin> CORS allowed origins
|
||||
```
|
||||
|
||||
### Attach Command
|
||||
|
||||
```bash
|
||||
ai-assist attach [server-url] [options]
|
||||
|
||||
Arguments:
|
||||
server-url Server URL (default: http://localhost:3000)
|
||||
|
||||
Options:
|
||||
-s, --session <id> Session ID to attach to
|
||||
-t, --token <token> Authentication token
|
||||
--no-history Don't load session history
|
||||
--stream Enable streaming mode
|
||||
```
|
||||
|
||||
## ⌨️ Interactive Commands
|
||||
|
||||
Once connected, use these commands in the chat interface:
|
||||
|
||||
```
|
||||
/help Show available commands
|
||||
/clear Clear the screen
|
||||
/history Show message history
|
||||
/attach <file> Attach a file to the next message
|
||||
/model <name> Switch AI model
|
||||
/session new Start a new session
|
||||
/session list List available sessions
|
||||
/session switch <id> Switch to another session
|
||||
/export <file> Export conversation to file
|
||||
/quit Exit the CLI
|
||||
```
|
||||
|
||||
## 🎨 Terminal UI Features
|
||||
|
||||
### Message Display
|
||||
- **User messages** - Displayed with `>` prefix in cyan
|
||||
- **AI responses** - Formatted with syntax highlighting
|
||||
- **Code blocks** - Highlighted based on language
|
||||
- **Markdown** - Rendered with terminal formatting
|
||||
- **Progress indicators** - Animated spinners during processing
|
||||
|
||||
### Keyboard Shortcuts
|
||||
- `↑/↓` - Navigate message history
|
||||
- `Tab` - Auto-complete commands
|
||||
- `Ctrl+C` - Cancel current operation
|
||||
- `Ctrl+D` - Exit (same as /quit)
|
||||
- `Ctrl+L` - Clear screen (same as /clear)
|
||||
- `PgUp/PgDn` - Scroll through long responses
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Configuration File
|
||||
|
||||
Create `~/.ai-assistant/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"defaultServer": "http://localhost:3000",
|
||||
"apiKey": "sk-ant-xxxxx",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"theme": "dark",
|
||||
"editor": "vim",
|
||||
"history": {
|
||||
"enabled": true,
|
||||
"maxSize": 1000
|
||||
},
|
||||
"display": {
|
||||
"showTimestamps": true,
|
||||
"syntax_highlighting": true,
|
||||
"word_wrap": true,
|
||||
"max_width": 120
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# API Configuration
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
export AI_MODEL=claude-sonnet-4-20250514
|
||||
|
||||
# CLI Configuration
|
||||
export AI_CLI_SERVER=http://localhost:3000
|
||||
export AI_CLI_SESSION=my-session
|
||||
export AI_CLI_TOKEN=auth-token
|
||||
|
||||
# Display Configuration
|
||||
export AI_CLI_COLOR=true
|
||||
export AI_CLI_EDITOR=vim
|
||||
```
|
||||
|
||||
## 🔌 Scripting and Automation
|
||||
|
||||
### Pipe Input
|
||||
|
||||
```bash
|
||||
# Send a single message
|
||||
echo "What is TypeScript?" | ai-assist attach
|
||||
|
||||
# Process a file
|
||||
cat code.ts | ai-assist attach --message "Review this code"
|
||||
|
||||
# Chain with other commands
|
||||
git diff | ai-assist attach --message "Explain these changes"
|
||||
```
|
||||
|
||||
### Script Mode
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Create a script for batch processing
|
||||
ai-assist attach <<EOF
|
||||
/session new
|
||||
Analyze the following log file
|
||||
/attach /var/log/application.log
|
||||
What are the main errors?
|
||||
/export analysis.md
|
||||
/quit
|
||||
EOF
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
```bash
|
||||
# Get JSON response for parsing
|
||||
ai-assist attach --json --message "List TypeScript features" | jq '.response.content'
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Run specific test suite
|
||||
pnpm test -- cli.test.ts
|
||||
```
|
||||
|
||||
## 🚀 Advanced Usage
|
||||
|
||||
### Custom Tools
|
||||
|
||||
Register custom tools in your config:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"name": "deploy",
|
||||
"command": "kubectl apply -f",
|
||||
"description": "Deploy to Kubernetes"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Plugins
|
||||
|
||||
Install and use CLI plugins:
|
||||
|
||||
```bash
|
||||
# Install a plugin
|
||||
ai-assist plugin install @ai-assistant/plugin-git
|
||||
|
||||
# List plugins
|
||||
ai-assist plugin list
|
||||
|
||||
# Use plugin command
|
||||
ai-assist git analyze
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
```bash
|
||||
# Test server connection
|
||||
ai-assist test-connection http://localhost:3000
|
||||
|
||||
# Check server status
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
DEBUG=* ai-assist attach
|
||||
|
||||
# Save debug log
|
||||
ai-assist attach --debug 2> debug.log
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Cannot connect to server"**
|
||||
- Check if server is running
|
||||
- Verify server URL and port
|
||||
- Check firewall settings
|
||||
|
||||
2. **"Authentication failed"**
|
||||
- Verify API key is set
|
||||
- Check token expiration
|
||||
- Ensure server auth is configured
|
||||
|
||||
3. **"Session not found"**
|
||||
- Session may have expired
|
||||
- Use `/session list` to see available sessions
|
||||
- Create new session with `/session new`
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! See the main repository's contributing guide.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [Documentation](https://docs.example.com/cli)
|
||||
- [Issue Tracker](https://github.com/username/ai-terminal-assistant/issues)
|
||||
@@ -0,0 +1,245 @@
|
||||
# @ai-assistant/core
|
||||
|
||||
Core engine package for AI Terminal Assistant - provides the AI agent, tools, and integrations.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
pnpm add @ai-assistant/core
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **AI Agent Engine** - Streaming text generation with Claude API
|
||||
- **Tool System** - Extensible tool registry with Zod validation
|
||||
- **Editor Modes** - Multiple editing strategies (whole, diff, search-replace)
|
||||
- **Language Server Protocol** - Code intelligence and analysis
|
||||
- **Checkpoint System** - Shadow Git for safe experimentation
|
||||
- **Hook System** - Pre/post execution customization
|
||||
- **Model Context Protocol** - MCP client for external tools
|
||||
- **Repository Mapping** - Tree-sitter based code analysis
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/
|
||||
│ ├── agent.ts # Main Agent class with streaming
|
||||
│ ├── config.ts # Configuration management
|
||||
│ └── types.ts # Core type definitions
|
||||
├── tools/
|
||||
│ ├── registry.ts # Tool registration system
|
||||
│ ├── bash.ts # Bash command execution
|
||||
│ ├── file.ts # File operations
|
||||
│ ├── search.ts # Code search utilities
|
||||
│ └── index.ts # Tool exports
|
||||
├── editors/
|
||||
│ ├── base.ts # Base editor interface
|
||||
│ ├── whole.ts # Whole file replacement
|
||||
│ ├── diff.ts # Diff-based editing
|
||||
│ └── search-replace.ts # Search and replace
|
||||
├── lsp/
|
||||
│ ├── client.ts # LSP client implementation
|
||||
│ └── server.ts # LSP server management
|
||||
├── checkpoint/
|
||||
│ ├── manager.ts # Checkpoint management
|
||||
│ └── git.ts # Shadow Git operations
|
||||
├── hooks/
|
||||
│ ├── manager.ts # Hook execution system
|
||||
│ └── types.ts # Hook type definitions
|
||||
├── mcp/
|
||||
│ ├── client.ts # MCP client implementation
|
||||
│ └── protocol.ts # Protocol definitions
|
||||
└── repomap/
|
||||
├── generator.ts # Repository map generation
|
||||
└── parser.ts # Tree-sitter parsing
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
import { Agent, toolRegistry } from '@ai-assistant/core';
|
||||
|
||||
// Create an agent instance
|
||||
const agent = new Agent({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY,
|
||||
model: 'claude-sonnet-4-20250514',
|
||||
maxTokens: 4096
|
||||
});
|
||||
|
||||
// Chat with the agent
|
||||
const response = await agent.chat('Help me write a TypeScript function', {
|
||||
onChunk: (chunk) => console.log(chunk),
|
||||
onComplete: (response) => console.log('Done:', response)
|
||||
});
|
||||
```
|
||||
|
||||
### Tool Registration
|
||||
|
||||
```typescript
|
||||
import { toolRegistry } from '@ai-assistant/core/tools';
|
||||
import { z } from 'zod';
|
||||
|
||||
// Register a custom tool
|
||||
toolRegistry.register({
|
||||
name: 'my_tool',
|
||||
description: 'Does something useful',
|
||||
parameters: z.object({
|
||||
input: z.string().describe('Input parameter')
|
||||
}),
|
||||
execute: async (params) => {
|
||||
// Tool implementation
|
||||
return { success: true, result: params.input.toUpperCase() };
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Editor Modes
|
||||
|
||||
```typescript
|
||||
import { createEditor } from '@ai-assistant/core/editors';
|
||||
|
||||
// Whole file replacement
|
||||
const wholeEditor = createEditor('whole');
|
||||
await wholeEditor.edit('file.ts', 'new content');
|
||||
|
||||
// Diff-based editing
|
||||
const diffEditor = createEditor('diff');
|
||||
await diffEditor.edit('file.ts', '--- old\n+++ new\n...');
|
||||
|
||||
// Search and replace
|
||||
const searchEditor = createEditor('search-replace');
|
||||
await searchEditor.edit('file.ts', {
|
||||
search: 'oldFunction',
|
||||
replace: 'newFunction'
|
||||
});
|
||||
```
|
||||
|
||||
### Checkpoint System
|
||||
|
||||
```typescript
|
||||
import { CheckpointManager } from '@ai-assistant/core/checkpoint';
|
||||
|
||||
const manager = new CheckpointManager('/project/path');
|
||||
|
||||
// Create a checkpoint
|
||||
await manager.create('before-refactoring');
|
||||
|
||||
// Make changes...
|
||||
|
||||
// Restore if needed
|
||||
await manager.restore('before-refactoring');
|
||||
|
||||
// List checkpoints
|
||||
const checkpoints = await manager.list();
|
||||
```
|
||||
|
||||
### Language Server Protocol
|
||||
|
||||
```typescript
|
||||
import { LSPClient } from '@ai-assistant/core/lsp';
|
||||
|
||||
const lsp = new LSPClient({
|
||||
serverCommand: 'typescript-language-server',
|
||||
serverArgs: ['--stdio']
|
||||
});
|
||||
|
||||
await lsp.initialize('/project/path');
|
||||
|
||||
// Get diagnostics
|
||||
const diagnostics = await lsp.getDiagnostics('file.ts');
|
||||
|
||||
// Get completions
|
||||
const completions = await lsp.getCompletions('file.ts', { line: 10, character: 5 });
|
||||
|
||||
// Go to definition
|
||||
const definition = await lsp.getDefinition('file.ts', { line: 10, character: 5 });
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
```typescript
|
||||
interface AgentConfig {
|
||||
apiKey: string; // Anthropic API key
|
||||
model?: string; // Model name (default: claude-sonnet-4-20250514)
|
||||
maxTokens?: number; // Max response tokens (default: 4096)
|
||||
temperature?: number; // Sampling temperature (default: 0.7)
|
||||
systemPrompt?: string; // System prompt
|
||||
tools?: Tool[]; // Available tools
|
||||
hooks?: HookConfig; // Hook configuration
|
||||
checkpointDir?: string; // Checkpoint directory
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 API Reference
|
||||
|
||||
### Agent
|
||||
|
||||
```typescript
|
||||
class Agent {
|
||||
constructor(config: AgentConfig);
|
||||
|
||||
chat(message: string, options?: ChatOptions): Promise<Response>;
|
||||
streamChat(message: string, options?: StreamOptions): AsyncIterator<Chunk>;
|
||||
reset(): void;
|
||||
getHistory(): Message[];
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Registry
|
||||
|
||||
```typescript
|
||||
class ToolRegistry {
|
||||
register(tool: ToolDefinition): void;
|
||||
unregister(name: string): void;
|
||||
get(name: string): Tool | undefined;
|
||||
list(): Tool[];
|
||||
execute(name: string, params: any): Promise<ToolResult>;
|
||||
}
|
||||
```
|
||||
|
||||
### Editor Interface
|
||||
|
||||
```typescript
|
||||
interface Editor {
|
||||
edit(path: string, content: string | EditParams): Promise<void>;
|
||||
validate(content: string): boolean;
|
||||
preview(path: string, content: string): string;
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Watch mode
|
||||
pnpm test:watch
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please follow these steps:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests for new functionality
|
||||
5. Ensure all tests pass
|
||||
6. Submit a pull request
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [API Documentation](https://docs.example.com/core)
|
||||
- [Issue Tracker](https://github.com/username/ai-terminal-assistant/issues)
|
||||
@@ -0,0 +1,436 @@
|
||||
# @ai-assistant/desktop
|
||||
|
||||
Native desktop application for AI Terminal Assistant - built with Tauri for cross-platform support.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Development
|
||||
pnpm dev
|
||||
|
||||
# Build for current platform
|
||||
pnpm build
|
||||
|
||||
# Build for all platforms
|
||||
pnpm build:all
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **Native Performance** - Built with Rust and Tauri for speed
|
||||
- **Cross-Platform** - Windows, macOS, and Linux support
|
||||
- **Small Bundle Size** - ~10MB installer, ~30MB installed
|
||||
- **System Integration** - Native menus, notifications, and tray
|
||||
- **Secure by Default** - Sandboxed with minimal permissions
|
||||
- **Auto Updates** - Built-in update mechanism
|
||||
- **Local Storage** - SQLite for offline data
|
||||
- **WebView Based** - Modern web UI with native wrapper
|
||||
- **Global Shortcuts** - System-wide keyboard shortcuts
|
||||
- **File System Access** - Native file dialogs and operations
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src-tauri/
|
||||
├── src/
|
||||
│ ├── main.rs # Main entry point
|
||||
│ ├── app.rs # Application setup
|
||||
│ ├── commands/ # Tauri commands
|
||||
│ │ ├── chat.rs # Chat operations
|
||||
│ │ ├── file.rs # File operations
|
||||
│ │ ├── system.rs # System integration
|
||||
│ │ └── window.rs # Window management
|
||||
│ ├── menu.rs # Native menu setup
|
||||
│ ├── tray.rs # System tray
|
||||
│ ├── updater.rs # Auto-updater logic
|
||||
│ ├── store.rs # Local data storage
|
||||
│ └── utils/ # Utility functions
|
||||
├── Cargo.toml # Rust dependencies
|
||||
├── tauri.conf.json # Tauri configuration
|
||||
└── icons/ # App icons
|
||||
|
||||
src/
|
||||
├── App.tsx # React app entry
|
||||
├── components/ # UI components (shared with web)
|
||||
├── hooks/ # Custom hooks
|
||||
├── services/ # Desktop-specific services
|
||||
│ ├── ipc.ts # Tauri IPC communication
|
||||
│ ├── storage.ts # Local storage
|
||||
│ └── shortcuts.ts # Keyboard shortcuts
|
||||
└── styles/ # Desktop-specific styles
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** 18+ and pnpm
|
||||
- **Rust** 1.70+ (install from [rustup.rs](https://rustup.rs))
|
||||
- **Platform Tools**:
|
||||
- **Windows**: Visual Studio C++ Build Tools
|
||||
- **macOS**: Xcode Command Line Tools
|
||||
- **Linux**: `build-essential`, `libwebkit2gtk-4.0-dev`, `libssl-dev`
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone <repository-url>
|
||||
cd ai-terminal-assistant/packages/desktop
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# App will open automatically with hot reload enabled
|
||||
```
|
||||
|
||||
### Building for Production
|
||||
|
||||
```bash
|
||||
# Build for current platform
|
||||
pnpm build
|
||||
|
||||
# Build for specific platform
|
||||
pnpm build:windows
|
||||
pnpm build:mac
|
||||
pnpm build:linux
|
||||
|
||||
# Build universal binary for macOS
|
||||
pnpm build:mac-universal
|
||||
|
||||
# Build and sign (requires certificates)
|
||||
pnpm build:signed
|
||||
```
|
||||
|
||||
## 🖥️ Platform Features
|
||||
|
||||
### Windows
|
||||
- **Installer Types**: MSI, NSIS, Portable
|
||||
- **Auto-start** on system boot
|
||||
- **Windows Store** distribution ready
|
||||
- **Native notifications**
|
||||
- **Jump list** integration
|
||||
|
||||
### macOS
|
||||
- **Formats**: DMG, App Bundle
|
||||
- **Code signing** and notarization
|
||||
- **macOS App Store** ready
|
||||
- **Touch Bar** support
|
||||
- **Native menu bar**
|
||||
|
||||
### Linux
|
||||
- **Packages**: AppImage, Deb, RPM
|
||||
- **System tray** support
|
||||
- **Desktop entry** creation
|
||||
- **Snap/Flatpak** ready
|
||||
- **Wayland/X11** compatible
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Tauri Configuration
|
||||
|
||||
`src-tauri/tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"package": {
|
||||
"productName": "AI Terminal Assistant",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false,
|
||||
"shell": {
|
||||
"execute": true,
|
||||
"open": true
|
||||
},
|
||||
"fs": {
|
||||
"all": true,
|
||||
"scope": ["$HOME/**", "$RESOURCE/**"]
|
||||
},
|
||||
"http": {
|
||||
"all": true,
|
||||
"scope": ["http://localhost/*", "https://api.anthropic.com/*"]
|
||||
},
|
||||
"notification": {
|
||||
"all": true
|
||||
},
|
||||
"globalShortcut": {
|
||||
"all": true
|
||||
}
|
||||
},
|
||||
"windows": [{
|
||||
"title": "AI Terminal Assistant",
|
||||
"width": 1200,
|
||||
"height": 800,
|
||||
"resizable": true,
|
||||
"fullscreen": false
|
||||
}],
|
||||
"systemTray": {
|
||||
"iconPath": "icons/icon.png",
|
||||
"menuOnLeftClick": false
|
||||
},
|
||||
"updater": {
|
||||
"active": true,
|
||||
"endpoints": ["https://updates.example.com/check"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔌 Tauri Commands
|
||||
|
||||
### IPC Communication
|
||||
|
||||
```typescript
|
||||
// Frontend (TypeScript)
|
||||
import { invoke } from '@tauri-apps/api/tauri';
|
||||
|
||||
// Call Rust command
|
||||
const result = await invoke('send_message', {
|
||||
message: 'Hello from frontend'
|
||||
});
|
||||
|
||||
// Listen to events
|
||||
import { listen } from '@tauri-apps/api/event';
|
||||
|
||||
const unlisten = await listen('chat-update', (event) => {
|
||||
console.log('New message:', event.payload);
|
||||
});
|
||||
```
|
||||
|
||||
```rust
|
||||
// Backend (Rust)
|
||||
#[tauri::command]
|
||||
fn send_message(message: String) -> Result<String, String> {
|
||||
// Process message
|
||||
Ok(format!("Received: {}", message))
|
||||
}
|
||||
|
||||
// Emit events
|
||||
app.emit_all("chat-update", Payload {
|
||||
message: "New update"
|
||||
}).unwrap();
|
||||
```
|
||||
|
||||
## 🎨 Native Features
|
||||
|
||||
### System Tray
|
||||
|
||||
```typescript
|
||||
import { createTray } from './services/tray';
|
||||
|
||||
const tray = await createTray({
|
||||
icon: '/icons/tray.png',
|
||||
menu: [
|
||||
{ label: 'Show', action: () => showWindow() },
|
||||
{ label: 'Hide', action: () => hideWindow() },
|
||||
{ separator: true },
|
||||
{ label: 'Quit', action: () => app.quit() }
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### Global Shortcuts
|
||||
|
||||
```typescript
|
||||
import { register } from '@tauri-apps/api/globalShortcut';
|
||||
|
||||
// Register global hotkey
|
||||
await register('CommandOrControl+Shift+A', () => {
|
||||
console.log('Shortcut triggered!');
|
||||
window.show();
|
||||
});
|
||||
```
|
||||
|
||||
### File Operations
|
||||
|
||||
```typescript
|
||||
import { open, save } from '@tauri-apps/api/dialog';
|
||||
import { readTextFile, writeFile } from '@tauri-apps/api/fs';
|
||||
|
||||
// Open file dialog
|
||||
const selected = await open({
|
||||
multiple: false,
|
||||
filters: [{
|
||||
name: 'Text',
|
||||
extensions: ['txt', 'md']
|
||||
}]
|
||||
});
|
||||
|
||||
// Read file
|
||||
const content = await readTextFile(selected);
|
||||
|
||||
// Save file dialog
|
||||
const savePath = await save({
|
||||
filters: [{ name: 'Text', extensions: ['txt'] }]
|
||||
});
|
||||
|
||||
await writeFile(savePath, 'content');
|
||||
```
|
||||
|
||||
### Notifications
|
||||
|
||||
```typescript
|
||||
import { sendNotification } from '@tauri-apps/api/notification';
|
||||
|
||||
await sendNotification({
|
||||
title: 'AI Assistant',
|
||||
body: 'Task completed successfully!',
|
||||
icon: '/icons/icon.png'
|
||||
});
|
||||
```
|
||||
|
||||
## 🔐 Security
|
||||
|
||||
### Permissions
|
||||
- Minimal permission model
|
||||
- Scoped file system access
|
||||
- Controlled shell execution
|
||||
- CSP headers enforced
|
||||
|
||||
### Code Signing
|
||||
```bash
|
||||
# macOS
|
||||
codesign --deep --force --verify --verbose \
|
||||
--sign "Developer ID Application: Your Name" \
|
||||
target/release/bundle/osx/AI\ Terminal\ Assistant.app
|
||||
|
||||
# Windows (using SignTool)
|
||||
signtool sign /a /tr http://timestamp.digicert.com \
|
||||
/td SHA256 /fd SHA256 \
|
||||
target/release/bundle/msi/AI_Terminal_Assistant.msi
|
||||
```
|
||||
|
||||
## 🚢 Distribution
|
||||
|
||||
### Auto Updates
|
||||
|
||||
```rust
|
||||
// src-tauri/src/updater.rs
|
||||
use tauri::updater::builder::UpdateBuilder;
|
||||
|
||||
pub fn check_for_updates(app: &tauri::App) {
|
||||
let update = UpdateBuilder::new()
|
||||
.current_version(&app.package_info().version)
|
||||
.url("https://updates.example.com/check")
|
||||
.build()
|
||||
.unwrap();
|
||||
|
||||
if update.should_update {
|
||||
update.download_and_install().unwrap();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### GitHub Releases
|
||||
|
||||
```yaml
|
||||
# .github/workflows/release.yml
|
||||
name: Release
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
|
||||
jobs:
|
||||
release:
|
||||
strategy:
|
||||
matrix:
|
||||
platform: [macos-latest, ubuntu-latest, windows-latest]
|
||||
runs-on: ${{ matrix.platform }}
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: tauri-apps/tauri-action@v0
|
||||
with:
|
||||
tagName: v__VERSION__
|
||||
releaseName: 'v__VERSION__'
|
||||
releaseBody: 'See CHANGELOG.md'
|
||||
releaseDraft: true
|
||||
prerelease: false
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Unit tests (Rust)
|
||||
cd src-tauri
|
||||
cargo test
|
||||
|
||||
# Integration tests
|
||||
pnpm test:integration
|
||||
|
||||
# E2E tests with WebDriver
|
||||
pnpm test:e2e
|
||||
```
|
||||
|
||||
## 📊 Performance
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Lazy Loading** - Load features on demand
|
||||
2. **IPC Batching** - Batch multiple commands
|
||||
3. **Asset Optimization** - Compress images/fonts
|
||||
4. **Memory Management** - Clean up listeners
|
||||
5. **Background Tasks** - Use Web Workers
|
||||
|
||||
### Benchmarks
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Startup Time | < 500ms |
|
||||
| Memory Usage | ~50MB idle |
|
||||
| Bundle Size | ~10MB compressed |
|
||||
| CPU Usage | < 5% idle |
|
||||
|
||||
## 🐛 Debugging
|
||||
|
||||
### Development Tools
|
||||
|
||||
```bash
|
||||
# Enable dev tools
|
||||
pnpm dev -- --features devtools
|
||||
|
||||
# Rust debugging
|
||||
RUST_LOG=debug pnpm dev
|
||||
|
||||
# WebView debugging
|
||||
# Press F12 in the app window
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
```rust
|
||||
// Rust logging
|
||||
use log::{info, error};
|
||||
|
||||
info!("Application started");
|
||||
error!("Failed to load: {}", error);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Frontend logging
|
||||
import { info, error } from '@tauri-apps/api/log';
|
||||
|
||||
await info('Application started');
|
||||
await error(`Failed to load: ${error}`);
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
See the main repository's contributing guide for details.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [Tauri Documentation](https://tauri.app/v1/guides/)
|
||||
- [Release Downloads](https://github.com/username/ai-terminal-assistant/releases)
|
||||
@@ -0,0 +1,354 @@
|
||||
# @ai-assistant/server
|
||||
|
||||
HTTP/WebSocket server for AI Terminal Assistant - provides REST API, WebSocket, and SSE endpoints.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
pnpm add @ai-assistant/server
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **REST API** - Full CRUD operations for sessions and tools
|
||||
- **WebSocket** - Real-time bidirectional communication
|
||||
- **Server-Sent Events** - Streaming status updates
|
||||
- **Authentication** - Token-based auth for non-localhost
|
||||
- **Session Management** - Persistent session handling
|
||||
- **CORS Support** - Configurable cross-origin access
|
||||
- **Built with Hono** - Lightweight, fast web framework
|
||||
- **Bun Runtime** - Native WebSocket and performance
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Main server setup with Hono
|
||||
├── routes/
|
||||
│ ├── sessions.ts # Session management endpoints
|
||||
│ ├── tools.ts # Tool execution endpoints
|
||||
│ ├── config.ts # Configuration endpoints
|
||||
│ └── health.ts # Health check endpoint
|
||||
├── ws.ts # WebSocket handler
|
||||
├── sse.ts # Server-Sent Events handler
|
||||
├── agent/
|
||||
│ ├── adapter.ts # Core agent adapter
|
||||
│ └── session.ts # Session management
|
||||
├── auth/
|
||||
│ ├── token.ts # Token generation/validation
|
||||
│ └── middleware.ts # Auth middleware
|
||||
├── middleware/
|
||||
│ ├── cors.ts # CORS configuration
|
||||
│ ├── error.ts # Error handling
|
||||
│ └── logging.ts # Request logging
|
||||
└── types/
|
||||
└── index.ts # TypeScript definitions
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Basic Server Setup
|
||||
|
||||
```typescript
|
||||
import { createServer } from '@ai-assistant/server';
|
||||
|
||||
const server = createServer({
|
||||
port: 3000,
|
||||
host: 'localhost',
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
});
|
||||
|
||||
await server.start();
|
||||
console.log('Server running on http://localhost:3000');
|
||||
```
|
||||
|
||||
### Standalone Usage
|
||||
|
||||
```bash
|
||||
# Development mode with hot reload
|
||||
pnpm start:dev
|
||||
|
||||
# Production mode
|
||||
pnpm start
|
||||
|
||||
# With custom configuration
|
||||
ANTHROPIC_API_KEY=sk-ant-xxx SERVER_PORT=8080 pnpm start
|
||||
```
|
||||
|
||||
## 📡 API Endpoints
|
||||
|
||||
### REST API
|
||||
|
||||
#### Sessions
|
||||
```typescript
|
||||
// Create session
|
||||
POST /api/sessions
|
||||
Response: { id: string, status: 'idle' | 'busy', createdAt: string }
|
||||
|
||||
// Get session
|
||||
GET /api/sessions/:id
|
||||
Response: { id: string, status: string, messages: Message[] }
|
||||
|
||||
// List sessions
|
||||
GET /api/sessions
|
||||
Response: Session[]
|
||||
|
||||
// Delete session
|
||||
DELETE /api/sessions/:id
|
||||
Response: { success: boolean }
|
||||
```
|
||||
|
||||
#### Tools
|
||||
```typescript
|
||||
// List available tools
|
||||
GET /api/tools
|
||||
Response: Tool[]
|
||||
|
||||
// Execute tool
|
||||
POST /api/tools/:name/execute
|
||||
Body: { params: any, sessionId?: string }
|
||||
Response: { result: any }
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
```typescript
|
||||
// Get configuration
|
||||
GET /api/config
|
||||
Response: { model: string, maxTokens: number, ... }
|
||||
|
||||
// Update configuration
|
||||
PUT /api/config
|
||||
Body: { model?: string, maxTokens?: number, ... }
|
||||
Response: { success: boolean, config: Config }
|
||||
```
|
||||
|
||||
### WebSocket Protocol
|
||||
|
||||
```typescript
|
||||
// Connect
|
||||
ws://localhost:3000/api/ws/:sessionId
|
||||
|
||||
// Client → Server Messages
|
||||
{
|
||||
type: 'message',
|
||||
payload: {
|
||||
content: string,
|
||||
attachments?: Attachment[]
|
||||
}
|
||||
}
|
||||
|
||||
// Server → Client Messages
|
||||
{
|
||||
type: 'chunk' | 'done' | 'error' | 'status',
|
||||
payload: {
|
||||
content?: string, // For chunk
|
||||
response?: Message, // For done
|
||||
error?: string, // For error
|
||||
status?: string // For status
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Server-Sent Events
|
||||
|
||||
```typescript
|
||||
// Connect for status updates
|
||||
GET /api/sse/:sessionId
|
||||
Accept: text/event-stream
|
||||
|
||||
// Event format
|
||||
event: status
|
||||
data: { "status": "processing", "progress": 0.5 }
|
||||
|
||||
event: complete
|
||||
data: { "result": "Task completed" }
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```env
|
||||
# Required
|
||||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
|
||||
# Optional
|
||||
SERVER_PORT=3000
|
||||
SERVER_HOST=localhost
|
||||
SERVER_CORS_ORIGIN=http://localhost:5173
|
||||
SERVER_AUTH_ENABLED=auto
|
||||
SERVER_LOG_LEVEL=info
|
||||
AI_MODEL=claude-sonnet-4-20250514
|
||||
AI_MAX_TOKENS=4096
|
||||
```
|
||||
|
||||
### Programmatic Configuration
|
||||
|
||||
```typescript
|
||||
interface ServerConfig {
|
||||
port?: number; // Server port (default: 3000)
|
||||
host?: string; // Server host (default: localhost)
|
||||
apiKey: string; // Anthropic API key
|
||||
cors?: {
|
||||
origin: string | string[];
|
||||
credentials?: boolean;
|
||||
};
|
||||
auth?: {
|
||||
enabled: boolean | 'auto'; // Auto enables for non-localhost
|
||||
tokenSecret?: string;
|
||||
};
|
||||
agent?: {
|
||||
model?: string;
|
||||
maxTokens?: number;
|
||||
temperature?: number;
|
||||
};
|
||||
logging?: {
|
||||
level: 'debug' | 'info' | 'warn' | 'error';
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
The server automatically enables token authentication when accessed from non-localhost addresses:
|
||||
|
||||
```typescript
|
||||
// Generate token
|
||||
POST /api/auth/token
|
||||
Body: { password?: string }
|
||||
Response: { token: string, expiresIn: number }
|
||||
|
||||
// Use token in requests
|
||||
Authorization: Bearer <token>
|
||||
|
||||
// Or in WebSocket
|
||||
ws://server/api/ws/:sessionId?token=<token>
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# E2E tests
|
||||
pnpm test:e2e
|
||||
```
|
||||
|
||||
### Test Examples
|
||||
|
||||
```typescript
|
||||
import { testClient } from '@ai-assistant/server/test';
|
||||
|
||||
describe('Server API', () => {
|
||||
const client = testClient({ port: 3001 });
|
||||
|
||||
beforeAll(() => client.start());
|
||||
afterAll(() => client.stop());
|
||||
|
||||
test('create session', async () => {
|
||||
const session = await client.post('/api/sessions');
|
||||
expect(session.id).toBeDefined();
|
||||
expect(session.status).toBe('idle');
|
||||
});
|
||||
|
||||
test('websocket chat', async () => {
|
||||
const ws = client.ws('/api/ws/test-session');
|
||||
|
||||
ws.send({ type: 'message', payload: { content: 'Hello' } });
|
||||
|
||||
const response = await ws.waitFor('done');
|
||||
expect(response.payload.response).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## 🔌 Integration Examples
|
||||
|
||||
### With Express
|
||||
|
||||
```typescript
|
||||
import express from 'express';
|
||||
import { createMiddleware } from '@ai-assistant/server';
|
||||
|
||||
const app = express();
|
||||
app.use('/ai', createMiddleware({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
}));
|
||||
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
### With Next.js
|
||||
|
||||
```typescript
|
||||
// app/api/ai/[...path]/route.ts
|
||||
import { handleRequest } from '@ai-assistant/server/next';
|
||||
|
||||
export const { GET, POST, PUT, DELETE } = handleRequest({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
});
|
||||
```
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
# Response: { status: 'healthy', uptime: 123456, sessions: 5 }
|
||||
```
|
||||
|
||||
### Metrics Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/api/metrics
|
||||
# Response: Prometheus-formatted metrics
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM oven/bun:1.0
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN bun install
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
CMD ["bun", "run", "start"]
|
||||
```
|
||||
|
||||
### PM2
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": [{
|
||||
"name": "ai-server",
|
||||
"script": "bun",
|
||||
"args": "run start",
|
||||
"env": {
|
||||
"SERVER_PORT": 3000,
|
||||
"ANTHROPIC_API_KEY": "sk-ant-xxx"
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please follow the contribution guidelines in the main repository.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [API Documentation](https://docs.example.com/server)
|
||||
- [OpenAPI Spec](https://api.example.com/openapi.json)
|
||||
@@ -0,0 +1,366 @@
|
||||
# @ai-assistant/web
|
||||
|
||||
Modern web interface for AI Terminal Assistant - built with React, Vite, and Tailwind CSS.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **Modern UI** - Clean, responsive interface with dark/light themes
|
||||
- **Real-time Chat** - WebSocket-based instant messaging
|
||||
- **Code Editor** - Syntax highlighting with Monaco Editor
|
||||
- **File Browser** - Browse and edit project files
|
||||
- **Terminal Integration** - Embedded terminal for command execution
|
||||
- **Markdown Rendering** - Rich text formatting for AI responses
|
||||
- **PWA Support** - Install as desktop/mobile app
|
||||
- **Mobile Responsive** - Optimized for all screen sizes
|
||||
- **Keyboard Shortcuts** - Efficient navigation and actions
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ ├── Chat/ # Chat interface components
|
||||
│ │ ├── ChatWindow.tsx
|
||||
│ │ ├── MessageList.tsx
|
||||
│ │ ├── MessageInput.tsx
|
||||
│ │ └── CodeBlock.tsx
|
||||
│ ├── Editor/ # Code editor components
|
||||
│ │ ├── MonacoEditor.tsx
|
||||
│ │ └── EditorToolbar.tsx
|
||||
│ ├── FileBrowser/ # File navigation
|
||||
│ │ ├── FileTree.tsx
|
||||
│ │ └── FilePreview.tsx
|
||||
│ ├── Terminal/ # Terminal emulator
|
||||
│ │ └── XTerminal.tsx
|
||||
│ ├── Layout/ # Layout components
|
||||
│ │ ├── Sidebar.tsx
|
||||
│ │ ├── Header.tsx
|
||||
│ │ └── Tabs.tsx
|
||||
│ └── Common/ # Shared components
|
||||
│ ├── Button.tsx
|
||||
│ ├── Modal.tsx
|
||||
│ └── Loading.tsx
|
||||
├── hooks/ # Custom React hooks
|
||||
│ ├── useChat.ts
|
||||
│ ├── useWebSocket.ts
|
||||
│ ├── useTheme.ts
|
||||
│ └── useKeyboard.ts
|
||||
├── services/ # API and service layer
|
||||
│ ├── api.ts
|
||||
│ ├── websocket.ts
|
||||
│ └── storage.ts
|
||||
├── store/ # State management
|
||||
│ ├── chat.store.ts
|
||||
│ ├── editor.store.ts
|
||||
│ └── settings.store.ts
|
||||
├── styles/ # Global styles
|
||||
│ └── index.css
|
||||
├── types/ # TypeScript definitions
|
||||
├── utils/ # Utility functions
|
||||
├── App.tsx # Main app component
|
||||
└── main.tsx # Entry point
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# The app will be available at http://localhost:5173
|
||||
# Hot module replacement is enabled for instant updates
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
# Create optimized build
|
||||
pnpm build
|
||||
|
||||
# Preview production build
|
||||
pnpm preview
|
||||
|
||||
# Build output in dist/ directory
|
||||
```
|
||||
|
||||
## 🎨 User Interface
|
||||
|
||||
### Main Features
|
||||
|
||||
#### Chat Interface
|
||||
- **Message History** - Scrollable chat with persistent history
|
||||
- **Code Highlighting** - Syntax highlighting for code blocks
|
||||
- **File Attachments** - Drag & drop file support
|
||||
- **Message Actions** - Copy, edit, regenerate responses
|
||||
- **Streaming Responses** - Real-time AI response streaming
|
||||
|
||||
#### Code Editor
|
||||
- **Monaco Editor** - VS Code's editor engine
|
||||
- **Multi-file Tabs** - Work with multiple files
|
||||
- **Syntax Highlighting** - 100+ language support
|
||||
- **IntelliSense** - Code completion and hints
|
||||
- **Diff View** - Side-by-side code comparison
|
||||
|
||||
#### File Browser
|
||||
- **Tree View** - Hierarchical file structure
|
||||
- **Quick Actions** - Create, rename, delete files
|
||||
- **Search** - Fast file search with fuzzy matching
|
||||
- **Preview** - Quick file preview without opening
|
||||
- **Context Menu** - Right-click actions
|
||||
|
||||
#### Terminal
|
||||
- **XTerm.js** - Full terminal emulation
|
||||
- **Command History** - Navigate previous commands
|
||||
- **Copy/Paste** - Standard clipboard operations
|
||||
- **Themes** - Multiple color schemes
|
||||
|
||||
## 🎯 Component Examples
|
||||
|
||||
### Using the Chat Component
|
||||
|
||||
```tsx
|
||||
import { Chat } from '@ai-assistant/web/components';
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<Chat
|
||||
serverUrl="http://localhost:3000"
|
||||
sessionId="my-session"
|
||||
onMessage={(message) => console.log('New message:', message)}
|
||||
theme="dark"
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Hook Usage
|
||||
|
||||
```tsx
|
||||
import { useChat } from '@ai-assistant/web/hooks';
|
||||
|
||||
function MyComponent() {
|
||||
const { messages, sendMessage, isLoading } = useChat({
|
||||
serverUrl: 'http://localhost:3000',
|
||||
sessionId: 'my-session'
|
||||
});
|
||||
|
||||
return (
|
||||
<div>
|
||||
{messages.map(msg => (
|
||||
<div key={msg.id}>{msg.content}</div>
|
||||
))}
|
||||
<button onClick={() => sendMessage('Hello AI!')}>
|
||||
Send Message
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create `.env` file:
|
||||
|
||||
```env
|
||||
# API Configuration
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_WS_URL=ws://localhost:3000
|
||||
VITE_AUTH_TOKEN=your-token-here
|
||||
|
||||
# Feature Flags
|
||||
VITE_ENABLE_TERMINAL=true
|
||||
VITE_ENABLE_FILE_BROWSER=true
|
||||
VITE_ENABLE_CODE_EDITOR=true
|
||||
|
||||
# Theme
|
||||
VITE_DEFAULT_THEME=dark
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
|
||||
`vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': 'http://localhost:3000'
|
||||
}
|
||||
},
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
sourcemap: true,
|
||||
minify: 'esbuild'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 🎹 Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl/Cmd + Enter` | Send message |
|
||||
| `Ctrl/Cmd + K` | Clear chat |
|
||||
| `Ctrl/Cmd + /` | Toggle sidebar |
|
||||
| `Ctrl/Cmd + ,` | Open settings |
|
||||
| `Ctrl/Cmd + Shift + P` | Command palette |
|
||||
| `Ctrl/Cmd + B` | Toggle file browser |
|
||||
| `Ctrl/Cmd + J` | Toggle terminal |
|
||||
| `Esc` | Close modal/popup |
|
||||
|
||||
## 📱 Progressive Web App
|
||||
|
||||
The app can be installed as a PWA:
|
||||
|
||||
1. Open in Chrome/Edge
|
||||
2. Click install icon in address bar
|
||||
3. Or use browser menu: "Install App"
|
||||
|
||||
Features:
|
||||
- Offline support with service worker
|
||||
- Desktop/mobile app experience
|
||||
- Push notifications (coming soon)
|
||||
- Background sync
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run unit tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Run E2E tests
|
||||
pnpm test:e2e
|
||||
|
||||
# Component testing
|
||||
pnpm test:components
|
||||
```
|
||||
|
||||
### Testing Examples
|
||||
|
||||
```tsx
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { Chat } from './Chat';
|
||||
|
||||
test('renders chat interface', () => {
|
||||
render(<Chat serverUrl="http://localhost:3000" />);
|
||||
expect(screen.getByPlaceholderText('Type a message...')).toBeInTheDocument();
|
||||
});
|
||||
```
|
||||
|
||||
## 🎨 Theming
|
||||
|
||||
### Custom Theme
|
||||
|
||||
```css
|
||||
/* src/styles/themes/custom.css */
|
||||
:root[data-theme="custom"] {
|
||||
--primary: #6366f1;
|
||||
--background: #0f172a;
|
||||
--foreground: #f8fafc;
|
||||
--border: #334155;
|
||||
--accent: #8b5cf6;
|
||||
}
|
||||
```
|
||||
|
||||
### Apply Theme
|
||||
|
||||
```tsx
|
||||
import { useTheme } from '@ai-assistant/web/hooks';
|
||||
|
||||
function ThemeToggle() {
|
||||
const { theme, setTheme } = useTheme();
|
||||
|
||||
return (
|
||||
<button onClick={() => setTheme('custom')}>
|
||||
Use Custom Theme
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Performance
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Code Splitting** - Routes are lazy loaded
|
||||
2. **Image Optimization** - WebP with fallbacks
|
||||
3. **Bundle Size** - Tree shaking enabled
|
||||
4. **Caching** - Service worker caching
|
||||
5. **Virtual Scrolling** - For long lists
|
||||
|
||||
### Bundle Analysis
|
||||
|
||||
```bash
|
||||
# Analyze bundle size
|
||||
pnpm build:analyze
|
||||
|
||||
# Opens visualization in browser
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Vercel
|
||||
|
||||
```bash
|
||||
# Deploy to Vercel
|
||||
vercel deploy --prod
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM nginx:alpine
|
||||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||||
EXPOSE 80
|
||||
```
|
||||
|
||||
### Static Hosting
|
||||
|
||||
Build output in `dist/` can be served by any static host:
|
||||
- Netlify
|
||||
- GitHub Pages
|
||||
- CloudFlare Pages
|
||||
- AWS S3 + CloudFront
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
See the main repository's contributing guide for details.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [Component Storybook](https://storybook.example.com)
|
||||
- [Design System](https://design.example.com)
|
||||
Reference in New Issue
Block a user