docs: 添加中文文档
This commit is contained in:
@@ -0,0 +1,321 @@
|
||||
# @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)
|
||||
Reference in New Issue
Block a user