6.3 KiB
6.3 KiB
@ai-assistant/cli
AI Terminal Assistant 的命令行界面 - 直接从终端与 AI 交互。
📦 安装
# 全局安装
pnpm add -g @ai-assistant/cli
# 或直接使用 npx/bunx 运行
npx @ai-assistant/cli
bunx @ai-assistant/cli
🌟 功能特性
- 双模式 - 服务器模式和客户端附加模式
- 交互式对话 - 带语法高亮的丰富终端界面
- 流式响应 - 实时 AI 响应
- 文件附件 - 支持将文件附加到消息
- 命令历史 - 浏览之前的命令
- 自动补全 - Tab 键补全命令
- 彩色输出 - 美观的终端格式
- 会话管理 - 持久化对话历史
🚀 快速开始
服务器模式
启动本地 AI 服务器：
# 在默认端口 3000 启动服务器
ai-assist serve
# 在自定义端口启动
ai-assist serve --port 8080
# 使用特定模型
ai-assist serve --model claude-haiku-3-20251120
# 启用详细日志
ai-assist serve --verbose
客户端模式
连接到运行中的 AI 服务器：
# 连接到本地服务器
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
📚 命令
全局选项
ai-assist [command] [options]
选项：
-h, --help 显示帮助
-v, --version 显示版本
--config <path> 配置文件路径
--verbose 启用详细日志
服务器命令
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 允许的来源
附加命令
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：
{
"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
}
}
环境变量
# 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
🔌 脚本和自动化
管道输入
# 发送单条消息
echo "什么是 TypeScript？" | ai-assist attach
# 处理文件
cat code.ts | ai-assist attach --message "审查这段代码"
# 与其他命令链接
git diff | ai-assist attach --message "解释这些更改"
脚本模式
#!/bin/bash
# 创建批处理脚本
ai-assist attach <<EOF
/session new
分析以下日志文件
/attach /var/log/application.log
主要错误是什么？
/export analysis.md
/quit
EOF
JSON 输出
# 获取 JSON 响应以便解析
ai-assist attach --json --message "列出 TypeScript 特性" | jq '.response.content'
🧪 测试
# 运行测试
pnpm test
# 运行覆盖率测试
pnpm test:coverage
# 运行特定测试套件
pnpm test -- cli.test.ts
🚀 高级用法
自定义工具
在配置中注册自定义工具：
{
"tools": [
{
"name": "deploy",
"command": "kubectl apply -f",
"description": "部署到 Kubernetes"
}
]
}
插件
安装和使用 CLI 插件：
# 安装插件
ai-assist plugin install @ai-assistant/plugin-git
# 列出插件
ai-assist plugin list
# 使用插件命令
ai-assist git analyze
🐛 故障排除
连接问题
# 测试服务器连接
ai-assist test-connection http://localhost:3000
# 检查服务器状态
curl http://localhost:3000/api/health
调试模式
# 启用调试日志
DEBUG=* ai-assist attach
# 保存调试日志
ai-assist attach --debug 2> debug.log
常见问题
-
"无法连接到服务器"
- 检查服务器是否正在运行
- 验证服务器 URL 和端口
- 检查防火墙设置
-
"身份验证失败"
- 验证 API 密钥是否设置
- 检查令牌是否过期
- 确保服务器身份验证已配置
-
"会话未找到"
- 会话可能已过期
- 使用
/session list查看可用会话 - 使用
/session new创建新会话
🤝 贡献
欢迎贡献！请查看主仓库的贡献指南。
📄 许可证
MIT 许可证 - 查看 LICENSE 了解详情。