docs: 更新项目文档
This commit is contained in:
@@ -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)
|
||||
Reference in New Issue
Block a user