# @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)