321 lines
6.3 KiB
Markdown
321 lines
6.3 KiB
Markdown
# @ai-assistant/cli
|
||
|
||
AI Terminal Assistant 的命令行界面 - 直接从终端与 AI 交互。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
# 全局安装
|
||
pnpm add -g @ai-assistant/cli
|
||
|
||
# 或直接使用 npx/bunx 运行
|
||
npx @ai-assistant/cli
|
||
bunx @ai-assistant/cli
|
||
```
|
||
|
||
## 🌟 功能特性
|
||
|
||
- **双模式** - 服务器模式和客户端附加模式
|
||
- **交互式对话** - 带语法高亮的丰富终端界面
|
||
- **流式响应** - 实时 AI 响应
|
||
- **文件附件** - 支持将文件附加到消息
|
||
- **命令历史** - 浏览之前的命令
|
||
- **自动补全** - Tab 键补全命令
|
||
- **彩色输出** - 美观的终端格式
|
||
- **会话管理** - 持久化对话历史
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 服务器模式
|
||
|
||
启动本地 AI 服务器：
|
||
|
||
```bash
|
||
# 在默认端口 3000 启动服务器
|
||
ai-assist serve
|
||
|
||
# 在自定义端口启动
|
||
ai-assist serve --port 8080
|
||
|
||
# 使用特定模型
|
||
ai-assist serve --model claude-haiku-3-20251120
|
||
|
||
# 启用详细日志
|
||
ai-assist serve --verbose
|
||
```
|
||
|
||
### 客户端模式
|
||
|
||
连接到运行中的 AI 服务器：
|
||
|
||
```bash
|
||
# 连接到本地服务器
|
||
ai-assist attach
|
||
|
||
# 连接到远程服务器
|
||
ai-assist attach https://ai-server.example.com
|
||
|
||
# 带身份验证连接
|
||
ai-assist attach https://ai-server.example.com --token YOUR_TOKEN
|
||
|
||
# 连接到特定会话
|
||
ai-assist attach --session my-session-id
|
||
```
|
||
|
||
## 📚 命令
|
||
|
||
### 全局选项
|
||
|
||
```bash
|
||
ai-assist [command] [options]
|
||
|
||
选项：
|
||
-h, --help 显示帮助
|
||
-v, --version 显示版本
|
||
--config <path> 配置文件路径
|
||
--verbose 启用详细日志
|
||
```
|
||
|
||
### 服务器命令
|
||
|
||
```bash
|
||
ai-assist serve [options]
|
||
|
||
选项：
|
||
-p, --port <port> 服务器端口（默认：3000）
|
||
-h, --host <host> 服务器主机（默认：localhost）
|
||
--api-key <key> Anthropic API 密钥（或使用 ANTHROPIC_API_KEY 环境变量）
|
||
--model <model> 使用的 AI 模型
|
||
--max-tokens <n> 最大响应令牌数
|
||
--no-auth 禁用身份验证
|
||
--cors-origin <origin> CORS 允许的来源
|
||
```
|
||
|
||
### 附加命令
|
||
|
||
```bash
|
||
ai-assist attach [server-url] [options]
|
||
|
||
参数：
|
||
server-url 服务器 URL（默认：http://localhost:3000）
|
||
|
||
选项：
|
||
-s, --session <id> 要附加的会话 ID
|
||
-t, --token <token> 身份验证令牌
|
||
--no-history 不加载会话历史
|
||
--stream 启用流模式
|
||
```
|
||
|
||
## ⌨️ 交互式命令
|
||
|
||
连接后，可以在对话界面中使用这些命令：
|
||
|
||
```
|
||
/help 显示可用命令
|
||
/clear 清屏
|
||
/history 显示消息历史
|
||
/attach <file> 将文件附加到下一条消息
|
||
/model <name> 切换 AI 模型
|
||
/session new 开始新会话
|
||
/session list 列出可用会话
|
||
/session switch <id> 切换到另一个会话
|
||
/export <file> 导出对话到文件
|
||
/quit 退出 CLI
|
||
```
|
||
|
||
## 🎨 终端界面功能
|
||
|
||
### 消息显示
|
||
- **用户消息** - 以青色 `>` 前缀显示
|
||
- **AI 响应** - 带语法高亮的格式化显示
|
||
- **代码块** - 基于语言的语法高亮
|
||
- **Markdown** - 终端格式渲染
|
||
- **进度指示器** - 处理时的动画加载
|
||
|
||
### 键盘快捷键
|
||
- `↑/↓` - 浏览消息历史
|
||
- `Tab` - 自动补全命令
|
||
- `Ctrl+C` - 取消当前操作
|
||
- `Ctrl+D` - 退出（同 /quit）
|
||
- `Ctrl+L` - 清屏（同 /clear）
|
||
- `PgUp/PgDn` - 滚动长响应
|
||
|
||
## 🔧 配置
|
||
|
||
### 配置文件
|
||
|
||
创建 `~/.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
|
||
}
|
||
}
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
```bash
|
||
# API 配置
|
||
export ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||
export AI_MODEL=claude-sonnet-4-20250514
|
||
|
||
# CLI 配置
|
||
export AI_CLI_SERVER=http://localhost:3000
|
||
export AI_CLI_SESSION=my-session
|
||
export AI_CLI_TOKEN=auth-token
|
||
|
||
# 显示配置
|
||
export AI_CLI_COLOR=true
|
||
export AI_CLI_EDITOR=vim
|
||
```
|
||
|
||
## 🔌 脚本和自动化
|
||
|
||
### 管道输入
|
||
|
||
```bash
|
||
# 发送单条消息
|
||
echo "什么是 TypeScript？" | ai-assist attach
|
||
|
||
# 处理文件
|
||
cat code.ts | ai-assist attach --message "审查这段代码"
|
||
|
||
# 与其他命令链接
|
||
git diff | ai-assist attach --message "解释这些更改"
|
||
```
|
||
|
||
### 脚本模式
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
# 创建批处理脚本
|
||
ai-assist attach <<EOF
|
||
/session new
|
||
分析以下日志文件
|
||
/attach /var/log/application.log
|
||
主要错误是什么？
|
||
/export analysis.md
|
||
/quit
|
||
EOF
|
||
```
|
||
|
||
### JSON 输出
|
||
|
||
```bash
|
||
# 获取 JSON 响应以便解析
|
||
ai-assist attach --json --message "列出 TypeScript 特性" | jq '.response.content'
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行测试
|
||
pnpm test
|
||
|
||
# 运行覆盖率测试
|
||
pnpm test:coverage
|
||
|
||
# 运行特定测试套件
|
||
pnpm test -- cli.test.ts
|
||
```
|
||
|
||
## 🚀 高级用法
|
||
|
||
### 自定义工具
|
||
|
||
在配置中注册自定义工具：
|
||
|
||
```json
|
||
{
|
||
"tools": [
|
||
{
|
||
"name": "deploy",
|
||
"command": "kubectl apply -f",
|
||
"description": "部署到 Kubernetes"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 插件
|
||
|
||
安装和使用 CLI 插件：
|
||
|
||
```bash
|
||
# 安装插件
|
||
ai-assist plugin install @ai-assistant/plugin-git
|
||
|
||
# 列出插件
|
||
ai-assist plugin list
|
||
|
||
# 使用插件命令
|
||
ai-assist git analyze
|
||
```
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 连接问题
|
||
|
||
```bash
|
||
# 测试服务器连接
|
||
ai-assist test-connection http://localhost:3000
|
||
|
||
# 检查服务器状态
|
||
curl http://localhost:3000/api/health
|
||
```
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
# 启用调试日志
|
||
DEBUG=* ai-assist attach
|
||
|
||
# 保存调试日志
|
||
ai-assist attach --debug 2> debug.log
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
1. **"无法连接到服务器"**
|
||
- 检查服务器是否正在运行
|
||
- 验证服务器 URL 和端口
|
||
- 检查防火墙设置
|
||
|
||
2. **"身份验证失败"**
|
||
- 验证 API 密钥是否设置
|
||
- 检查令牌是否过期
|
||
- 确保服务器身份验证已配置
|
||
|
||
3. **"会话未找到"**
|
||
- 会话可能已过期
|
||
- 使用 `/session list` 查看可用会话
|
||
- 使用 `/session new` 创建新会话
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献！请查看主仓库的贡献指南。
|
||
|
||
## 📄 许可证
|
||
|
||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||
|
||
## 🔗 链接
|
||
|
||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||
- [文档](https://docs.example.com/cli)
|
||
- [问题跟踪](https://github.com/username/ai-terminal-assistant/issues) |