docs: 添加中文文档
This commit is contained in:
+225
@@ -0,0 +1,225 @@
|
||||
# AI Terminal Assistant
|
||||
|
||||
<div align="center">
|
||||
<h3>🤖 基于 Claude API 的强大终端 AI 编程助手</h3>
|
||||
<p>
|
||||
<a href="#特性">特性</a> •
|
||||
<a href="#快速开始">快速开始</a> •
|
||||
<a href="#文档">文档</a> •
|
||||
<a href="#包结构">包结构</a>
|
||||
</p>
|
||||
<p>
|
||||
<img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
|
||||
<img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18.0.0-green">
|
||||
<img alt="pnpm" src="https://img.shields.io/badge/pnpm-%3E%3D8.0.0-orange">
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## 🌟 项目概述
|
||||
|
||||
AI Terminal Assistant 是一个综合性的 AI 驱动开发工具包，帮助开发者更高效地编写代码、调试问题和管理项目。作为模块化的 monorepo 架构，它提供多种界面（CLI、Web、Desktop）与 Claude AI 交互，完成各种编程任务。
|
||||
|
||||
## ✨ 特性
|
||||
|
||||
### 核心功能
|
||||
- 🧠 **高级 AI 代理** - 基于 Claude API 的流式响应
|
||||
- 🔧 **丰富的工具系统** - 文件操作、bash 命令、代码搜索等
|
||||
- 📝 **智能代码编辑** - 多种编辑模式（整体、差异、搜索替换）
|
||||
- 🔍 **语言服务协议** - 类 IDE 的代码智能提示
|
||||
- 💾 **检查点系统** - Shadow Git 安全实验
|
||||
- 🔌 **模型上下文协议** - 可扩展的工具集成
|
||||
- 🎣 **钩子系统** - 执行前后的自定义处理
|
||||
|
||||
### 用户界面
|
||||
- 🖥️ **CLI** - 原生终端体验，支持 serve/attach 模式
|
||||
- 🌐 **Web UI** - 现代化 React 界面，实时更新
|
||||
- 🖱️ **桌面应用** - 基于 Tauri 的原生应用（即将推出）
|
||||
|
||||
### 开发体验
|
||||
- 📦 **Monorepo 架构** - 清晰的关注点分离
|
||||
- 🚀 **基于 Bun 构建** - 快速运行时和打包
|
||||
- 🔥 **热重载** - 即时反馈的开发体验
|
||||
- 🧪 **全面的测试** - 单元测试和集成测试
|
||||
- 📊 **类型安全** - 完整的 TypeScript 支持
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 前置要求
|
||||
- Node.js 18+ 或 Bun 1.0+
|
||||
- pnpm 8.0+
|
||||
- Anthropic API Key
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone <repository-url>
|
||||
cd ai-terminal-assistant
|
||||
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 设置环境变量
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，添加你的 ANTHROPIC_API_KEY
|
||||
|
||||
# 构建所有包
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 运行应用
|
||||
|
||||
#### 选项 1：Web 界面
|
||||
```bash
|
||||
# 启动服务器
|
||||
pnpm server:dev
|
||||
|
||||
# 在另一个终端，启动 Web UI
|
||||
pnpm web:dev
|
||||
|
||||
# 在浏览器中打开 http://localhost:5173
|
||||
```
|
||||
|
||||
#### 选项 2：CLI 模式
|
||||
```bash
|
||||
# 启动服务器
|
||||
cd packages/cli && bun run src/index.ts serve --port 3000
|
||||
|
||||
# 在另一个终端，连接到服务器
|
||||
cd packages/cli && bun run src/index.ts attach http://localhost:3000
|
||||
```
|
||||
|
||||
## 📦 包结构
|
||||
|
||||
这个 monorepo 包含四个主要包：
|
||||
|
||||
| 包名 | 描述 | 状态 |
|
||||
|---------|-------------|--------|
|
||||
| [@ai-assistant/core](./packages/core) | 核心代理引擎、工具和集成 | ✅ 稳定 |
|
||||
| [@ai-assistant/server](./packages/server) | HTTP/WebSocket 服务器，提供 REST API | ✅ 稳定 |
|
||||
| [@ai-assistant/cli](./packages/cli) | 命令行界面 | ✅ 稳定 |
|
||||
| [@ai-assistant/web](./packages/web) | 基于 React 的 Web 界面 | ✅ 稳定 |
|
||||
| [@ai-assistant/desktop](./packages/desktop) | 基于 Tauri 的桌面应用 | 🚧 开发中 |
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Web[Web UI] --> Server
|
||||
CLI[CLI] --> Server
|
||||
Desktop[桌面应用] --> Server
|
||||
Server --> Core[核心引擎]
|
||||
Core --> Tools[工具系统]
|
||||
Core --> LSP[语言服务器]
|
||||
Core --> MCP[模型上下文协议]
|
||||
Core --> Checkpoint[检查点系统]
|
||||
```
|
||||
|
||||
### 技术栈
|
||||
|
||||
- **运行时**: Bun / Node.js
|
||||
- **语言**: TypeScript
|
||||
- **服务器**: Hono + Bun WebSocket
|
||||
- **前端**: React + Vite + Tailwind CSS
|
||||
- **桌面**: Tauri (Rust + WebView)
|
||||
- **测试**: Vitest
|
||||
- **包管理**: pnpm (monorepo)
|
||||
|
||||
## 📖 文档
|
||||
|
||||
详细文档位于 [docs](./docs) 目录：
|
||||
|
||||
- [架构概览](./docs/design/architecture/gui-server-client.md)
|
||||
- [API 参考](./docs/api/README.md)
|
||||
- [开发指南](./docs/development/README.md)
|
||||
- [配置指南](./docs/configuration/README.md)
|
||||
|
||||
## 🛠️ 开发
|
||||
|
||||
### 常用命令
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 构建所有包
|
||||
pnpm build
|
||||
|
||||
# 运行测试
|
||||
pnpm test
|
||||
pnpm test:coverage
|
||||
|
||||
# 代码检查
|
||||
pnpm lint
|
||||
|
||||
# 类型检查
|
||||
pnpm typecheck
|
||||
|
||||
# 清理构建产物
|
||||
pnpm clean
|
||||
```
|
||||
|
||||
### 特定包开发
|
||||
|
||||
```bash
|
||||
# 开发特定包
|
||||
pnpm --filter @ai-assistant/core dev
|
||||
pnpm --filter @ai-assistant/server test
|
||||
pnpm --filter @ai-assistant/web build
|
||||
```
|
||||
|
||||
## 🔧 配置
|
||||
|
||||
### 环境变量
|
||||
|
||||
在根目录创建 `.env` 文件：
|
||||
|
||||
```env
|
||||
# 必需
|
||||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
|
||||
# 可选
|
||||
AI_MODEL=claude-sonnet-4-20250514
|
||||
AI_MAX_TOKENS=4096
|
||||
SERVER_PORT=3000
|
||||
SERVER_HOST=localhost
|
||||
```
|
||||
|
||||
### 支持的模型
|
||||
|
||||
- `claude-sonnet-4-20250514` (默认)
|
||||
- `claude-haiku-3-20251120`
|
||||
- 其他 Claude 模型
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献！请查看我们的[贡献指南](./CONTRIBUTING.md)了解详情。
|
||||
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
||||
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
||||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||||
5. 开启 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- 基于 Anthropic 的 [Claude API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) 构建
|
||||
- 由 [Bun](https://bun.sh) 提供快速 JavaScript 运行时
|
||||
- UI 组件来自 [Tailwind CSS](https://tailwindcss.com)
|
||||
- 桌面应用基于 [Tauri](https://tauri.app) 构建
|
||||
|
||||
## 📞 支持
|
||||
|
||||
- 📧 邮箱：support@example.com
|
||||
- 💬 Discord：[加入我们的社区](https://discord.gg/example)
|
||||
- 🐛 问题反馈：[GitHub Issues](https://github.com/username/repo/issues)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
由 AI Terminal Assistant 团队用 ❤️ 制作
|
||||
</div>
|
||||
@@ -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)
|
||||
@@ -0,0 +1,245 @@
|
||||
# @ai-assistant/core
|
||||
|
||||
AI Terminal Assistant 的核心引擎包 - 提供 AI 代理、工具和集成功能。
|
||||
|
||||
## 📦 安装
|
||||
|
||||
```bash
|
||||
pnpm add @ai-assistant/core
|
||||
```
|
||||
|
||||
## 🌟 功能特性
|
||||
|
||||
- **AI 代理引擎** - 使用 Claude API 进行流式文本生成
|
||||
- **工具系统** - 带有 Zod 验证的可扩展工具注册表
|
||||
- **编辑器模式** - 多种编辑策略（整体、差异、搜索替换）
|
||||
- **语言服务协议** - 代码智能和分析
|
||||
- **检查点系统** - Shadow Git 安全实验
|
||||
- **钩子系统** - 执行前后的自定义处理
|
||||
- **模型上下文协议** - 外部工具的 MCP 客户端
|
||||
- **仓库映射** - 基于 Tree-sitter 的代码分析
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/
|
||||
│ ├── agent.ts # 主要的 Agent 类，支持流式处理
|
||||
│ ├── config.ts # 配置管理
|
||||
│ └── types.ts # 核心类型定义
|
||||
├── tools/
|
||||
│ ├── registry.ts # 工具注册系统
|
||||
│ ├── bash.ts # Bash 命令执行
|
||||
│ ├── file.ts # 文件操作
|
||||
│ ├── search.ts # 代码搜索工具
|
||||
│ └── index.ts # 工具导出
|
||||
├── editors/
|
||||
│ ├── base.ts # 基础编辑器接口
|
||||
│ ├── whole.ts # 整体文件替换
|
||||
│ ├── diff.ts # 基于差异的编辑
|
||||
│ └── search-replace.ts # 搜索和替换
|
||||
├── lsp/
|
||||
│ ├── client.ts # LSP 客户端实现
|
||||
│ └── server.ts # LSP 服务器管理
|
||||
├── checkpoint/
|
||||
│ ├── manager.ts # 检查点管理
|
||||
│ └── git.ts # Shadow Git 操作
|
||||
├── hooks/
|
||||
│ ├── manager.ts # 钩子执行系统
|
||||
│ └── types.ts # 钩子类型定义
|
||||
├── mcp/
|
||||
│ ├── client.ts # MCP 客户端实现
|
||||
│ └── protocol.ts # 协议定义
|
||||
└── repomap/
|
||||
├── generator.ts # 仓库映射生成
|
||||
└── parser.ts # Tree-sitter 解析
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 基本用法
|
||||
|
||||
```typescript
|
||||
import { Agent, toolRegistry } from '@ai-assistant/core';
|
||||
|
||||
// 创建代理实例
|
||||
const agent = new Agent({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY,
|
||||
model: 'claude-sonnet-4-20250514',
|
||||
maxTokens: 4096
|
||||
});
|
||||
|
||||
// 与代理对话
|
||||
const response = await agent.chat('帮我编写一个 TypeScript 函数', {
|
||||
onChunk: (chunk) => console.log(chunk),
|
||||
onComplete: (response) => console.log('完成:', response)
|
||||
});
|
||||
```
|
||||
|
||||
### 工具注册
|
||||
|
||||
```typescript
|
||||
import { toolRegistry } from '@ai-assistant/core/tools';
|
||||
import { z } from 'zod';
|
||||
|
||||
// 注册自定义工具
|
||||
toolRegistry.register({
|
||||
name: 'my_tool',
|
||||
description: '执行有用的操作',
|
||||
parameters: z.object({
|
||||
input: z.string().describe('输入参数')
|
||||
}),
|
||||
execute: async (params) => {
|
||||
// 工具实现
|
||||
return { success: true, result: params.input.toUpperCase() };
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 编辑器模式
|
||||
|
||||
```typescript
|
||||
import { createEditor } from '@ai-assistant/core/editors';
|
||||
|
||||
// 整体文件替换
|
||||
const wholeEditor = createEditor('whole');
|
||||
await wholeEditor.edit('file.ts', '新内容');
|
||||
|
||||
// 基于差异的编辑
|
||||
const diffEditor = createEditor('diff');
|
||||
await diffEditor.edit('file.ts', '--- old\n+++ new\n...');
|
||||
|
||||
// 搜索和替换
|
||||
const searchEditor = createEditor('search-replace');
|
||||
await searchEditor.edit('file.ts', {
|
||||
search: 'oldFunction',
|
||||
replace: 'newFunction'
|
||||
});
|
||||
```
|
||||
|
||||
### 检查点系统
|
||||
|
||||
```typescript
|
||||
import { CheckpointManager } from '@ai-assistant/core/checkpoint';
|
||||
|
||||
const manager = new CheckpointManager('/project/path');
|
||||
|
||||
// 创建检查点
|
||||
await manager.create('重构前');
|
||||
|
||||
// 进行更改...
|
||||
|
||||
// 需要时恢复
|
||||
await manager.restore('重构前');
|
||||
|
||||
// 列出检查点
|
||||
const checkpoints = await manager.list();
|
||||
```
|
||||
|
||||
### 语言服务协议
|
||||
|
||||
```typescript
|
||||
import { LSPClient } from '@ai-assistant/core/lsp';
|
||||
|
||||
const lsp = new LSPClient({
|
||||
serverCommand: 'typescript-language-server',
|
||||
serverArgs: ['--stdio']
|
||||
});
|
||||
|
||||
await lsp.initialize('/project/path');
|
||||
|
||||
// 获取诊断信息
|
||||
const diagnostics = await lsp.getDiagnostics('file.ts');
|
||||
|
||||
// 获取代码补全
|
||||
const completions = await lsp.getCompletions('file.ts', { line: 10, character: 5 });
|
||||
|
||||
// 跳转到定义
|
||||
const definition = await lsp.getDefinition('file.ts', { line: 10, character: 5 });
|
||||
```
|
||||
|
||||
## 🔧 配置
|
||||
|
||||
```typescript
|
||||
interface AgentConfig {
|
||||
apiKey: string; // Anthropic API 密钥
|
||||
model?: string; // 模型名称（默认：claude-sonnet-4-20250514）
|
||||
maxTokens?: number; // 最大响应令牌数（默认：4096）
|
||||
temperature?: number; // 采样温度（默认：0.7）
|
||||
systemPrompt?: string; // 系统提示词
|
||||
tools?: Tool[]; // 可用工具
|
||||
hooks?: HookConfig; // 钩子配置
|
||||
checkpointDir?: string; // 检查点目录
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 API 参考
|
||||
|
||||
### Agent
|
||||
|
||||
```typescript
|
||||
class Agent {
|
||||
constructor(config: AgentConfig);
|
||||
|
||||
chat(message: string, options?: ChatOptions): Promise<Response>;
|
||||
streamChat(message: string, options?: StreamOptions): AsyncIterator<Chunk>;
|
||||
reset(): void;
|
||||
getHistory(): Message[];
|
||||
}
|
||||
```
|
||||
|
||||
### 工具注册表
|
||||
|
||||
```typescript
|
||||
class ToolRegistry {
|
||||
register(tool: ToolDefinition): void;
|
||||
unregister(name: string): void;
|
||||
get(name: string): Tool | undefined;
|
||||
list(): Tool[];
|
||||
execute(name: string, params: any): Promise<ToolResult>;
|
||||
}
|
||||
```
|
||||
|
||||
### 编辑器接口
|
||||
|
||||
```typescript
|
||||
interface Editor {
|
||||
edit(path: string, content: string | EditParams): Promise<void>;
|
||||
validate(content: string): boolean;
|
||||
preview(path: string, content: string): string;
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
```bash
|
||||
# 运行测试
|
||||
pnpm test
|
||||
|
||||
# 运行覆盖率测试
|
||||
pnpm test:coverage
|
||||
|
||||
# 监视模式
|
||||
pnpm test:watch
|
||||
```
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献！请按照以下步骤：
|
||||
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支
|
||||
3. 进行更改
|
||||
4. 为新功能添加测试
|
||||
5. 确保所有测试通过
|
||||
6. 提交 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||||
|
||||
## 🔗 链接
|
||||
|
||||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||||
- [API 文档](https://docs.example.com/core)
|
||||
- [问题跟踪](https://github.com/username/ai-terminal-assistant/issues)
|
||||
@@ -0,0 +1,436 @@
|
||||
# @ai-assistant/desktop
|
||||
|
||||
AI Terminal Assistant 的原生桌面应用 - 基于 Tauri 构建，实现跨平台支持。
|
||||
|
||||
## 📦 安装
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 开发
|
||||
pnpm dev
|
||||
|
||||
# 构建当前平台版本
|
||||
pnpm build
|
||||
|
||||
# 构建所有平台版本
|
||||
pnpm build:all
|
||||
```
|
||||
|
||||
## 🌟 功能特性
|
||||
|
||||
- **原生性能** - 使用 Rust 和 Tauri 构建，速度极快
|
||||
- **跨平台** - 支持 Windows、macOS 和 Linux
|
||||
- **小体积** - ~10MB 安装包，~30MB 安装后大小
|
||||
- **系统集成** - 原生菜单、通知和系统托盘
|
||||
- **默认安全** - 沙盒化，最小权限
|
||||
- **自动更新** - 内置更新机制
|
||||
- **本地存储** - 使用 SQLite 存储离线数据
|
||||
- **基于 WebView** - 现代 Web UI 配合原生包装
|
||||
- **全局快捷键** - 系统级键盘快捷键
|
||||
- **文件系统访问** - 原生文件对话框和操作
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
src-tauri/
|
||||
├── src/
|
||||
│ ├── main.rs # 主入口点
|
||||
│ ├── app.rs # 应用设置
|
||||
│ ├── commands/ # Tauri 命令
|
||||
│ │ ├── chat.rs # 对话操作
|
||||
│ │ ├── file.rs # 文件操作
|
||||
│ │ ├── system.rs # 系统集成
|
||||
│ │ └── window.rs # 窗口管理
|
||||
│ ├── menu.rs # 原生菜单设置
|
||||
│ ├── tray.rs # 系统托盘
|
||||
│ ├── updater.rs # 自动更新逻辑
|
||||
│ ├── store.rs # 本地数据存储
|
||||
│ └── utils/ # 工具函数
|
||||
├── Cargo.toml # Rust 依赖
|
||||
├── tauri.conf.json # Tauri 配置
|
||||
└── icons/ # 应用图标
|
||||
|
||||
src/
|
||||
├── App.tsx # React 应用入口
|
||||
├── components/ # UI 组件（与 web 共享）
|
||||
├── hooks/ # 自定义 Hooks
|
||||
├── services/ # 桌面特定服务
|
||||
│ ├── ipc.ts # Tauri IPC 通信
|
||||
│ ├── storage.ts # 本地存储
|
||||
│ └── shortcuts.ts # 键盘快捷键
|
||||
└── styles/ # 桌面特定样式
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- **Node.js** 18+ 和 pnpm
|
||||
- **Rust** 1.70+（从 [rustup.rs](https://rustup.rs) 安装）
|
||||
- **平台工具**：
|
||||
- **Windows**：Visual Studio C++ 生成工具
|
||||
- **macOS**：Xcode 命令行工具
|
||||
- **Linux**：`build-essential`、`libwebkit2gtk-4.0-dev`、`libssl-dev`
|
||||
|
||||
### 开发设置
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone <repository-url>
|
||||
cd ai-terminal-assistant/packages/desktop
|
||||
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 启动开发服务器
|
||||
pnpm dev
|
||||
|
||||
# 应用将自动打开，支持热重载
|
||||
```
|
||||
|
||||
### 生产构建
|
||||
|
||||
```bash
|
||||
# 构建当前平台
|
||||
pnpm build
|
||||
|
||||
# 构建特定平台
|
||||
pnpm build:windows
|
||||
pnpm build:mac
|
||||
pnpm build:linux
|
||||
|
||||
# 构建 macOS 通用二进制文件
|
||||
pnpm build:mac-universal
|
||||
|
||||
# 构建并签名（需要证书）
|
||||
pnpm build:signed
|
||||
```
|
||||
|
||||
## 🖥️ 平台功能
|
||||
|
||||
### Windows
|
||||
- **安装程序类型**：MSI、NSIS、便携版
|
||||
- **系统启动时自动启动**
|
||||
- **Windows Store** 分发就绪
|
||||
- **原生通知**
|
||||
- **跳转列表**集成
|
||||
|
||||
### macOS
|
||||
- **格式**：DMG、App Bundle
|
||||
- **代码签名**和公证
|
||||
- **macOS App Store** 就绪
|
||||
- **Touch Bar** 支持
|
||||
- **原生菜单栏**
|
||||
|
||||
### Linux
|
||||
- **包格式**：AppImage、Deb、RPM
|
||||
- **系统托盘**支持
|
||||
- **桌面条目**创建
|
||||
- **Snap/Flatpak** 就绪
|
||||
- **Wayland/X11** 兼容
|
||||
|
||||
## ⚙️ 配置
|
||||
|
||||
### Tauri 配置
|
||||
|
||||
`src-tauri/tauri.conf.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"package": {
|
||||
"productName": "AI Terminal Assistant",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false,
|
||||
"shell": {
|
||||
"execute": true,
|
||||
"open": true
|
||||
},
|
||||
"fs": {
|
||||
"all": true,
|
||||
"scope": ["$HOME/**", "$RESOURCE/**"]
|
||||
},
|
||||
"http": {
|
||||
"all": true,
|
||||
"scope": ["http://localhost/*", "https://api.anthropic.com/*"]
|
||||
},
|
||||
"notification": {
|
||||
"all": true
|
||||
},
|
||||
"globalShortcut": {
|
||||
"all": true
|
||||
}
|
||||
},
|
||||
"windows": [{
|
||||
"title": "AI Terminal Assistant",
|
||||
"width": 1200,
|
||||
"height": 800,
|
||||
"resizable": true,
|
||||
"fullscreen": false
|
||||
}],
|
||||
"systemTray": {
|
||||
"iconPath": "icons/icon.png",
|
||||
"menuOnLeftClick": false
|
||||
},
|
||||
"updater": {
|
||||
"active": true,
|
||||
"endpoints": ["https://updates.example.com/check"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔌 Tauri 命令
|
||||
|
||||
### IPC 通信
|
||||
|
||||
```typescript
|
||||
// 前端（TypeScript）
|
||||
import { invoke } from '@tauri-apps/api/tauri';
|
||||
|
||||
// 调用 Rust 命令
|
||||
const result = await invoke('send_message', {
|
||||
message: '来自前端的消息'
|
||||
});
|
||||
|
||||
// 监听事件
|
||||
import { listen } from '@tauri-apps/api/event';
|
||||
|
||||
const unlisten = await listen('chat-update', (event) => {
|
||||
console.log('新消息:', event.payload);
|
||||
});
|
||||
```
|
||||
|
||||
```rust
|
||||
// 后端（Rust）
|
||||
#[tauri::command]
|
||||
fn send_message(message: String) -> Result<String, String> {
|
||||
// 处理消息
|
||||
Ok(format!("收到: {}", message))
|
||||
}
|
||||
|
||||
// 发送事件
|
||||
app.emit_all("chat-update", Payload {
|
||||
message: "新更新"
|
||||
}).unwrap();
|
||||
```
|
||||
|
||||
## 🎨 原生功能
|
||||
|
||||
### 系统托盘
|
||||
|
||||
```typescript
|
||||
import { createTray } from './services/tray';
|
||||
|
||||
const tray = await createTray({
|
||||
icon: '/icons/tray.png',
|
||||
menu: [
|
||||
{ label: '显示', action: () => showWindow() },
|
||||
{ label: '隐藏', action: () => hideWindow() },
|
||||
{ separator: true },
|
||||
{ label: '退出', action: () => app.quit() }
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### 全局快捷键
|
||||
|
||||
```typescript
|
||||
import { register } from '@tauri-apps/api/globalShortcut';
|
||||
|
||||
// 注册全局热键
|
||||
await register('CommandOrControl+Shift+A', () => {
|
||||
console.log('快捷键触发！');
|
||||
window.show();
|
||||
});
|
||||
```
|
||||
|
||||
### 文件操作
|
||||
|
||||
```typescript
|
||||
import { open, save } from '@tauri-apps/api/dialog';
|
||||
import { readTextFile, writeFile } from '@tauri-apps/api/fs';
|
||||
|
||||
// 打开文件对话框
|
||||
const selected = await open({
|
||||
multiple: false,
|
||||
filters: [{
|
||||
name: '文本',
|
||||
extensions: ['txt', 'md']
|
||||
}]
|
||||
});
|
||||
|
||||
// 读取文件
|
||||
const content = await readTextFile(selected);
|
||||
|
||||
// 保存文件对话框
|
||||
const savePath = await save({
|
||||
filters: [{ name: '文本', extensions: ['txt'] }]
|
||||
});
|
||||
|
||||
await writeFile(savePath, '内容');
|
||||
```
|
||||
|
||||
### 通知
|
||||
|
||||
```typescript
|
||||
import { sendNotification } from '@tauri-apps/api/notification';
|
||||
|
||||
await sendNotification({
|
||||
title: 'AI Assistant',
|
||||
body: '任务成功完成！',
|
||||
icon: '/icons/icon.png'
|
||||
});
|
||||
```
|
||||
|
||||
## 🔐 安全
|
||||
|
||||
### 权限
|
||||
- 最小权限模型
|
||||
- 限定范围的文件系统访问
|
||||
- 受控的 Shell 执行
|
||||
- 强制 CSP 头
|
||||
|
||||
### 代码签名
|
||||
```bash
|
||||
# macOS
|
||||
codesign --deep --force --verify --verbose \
|
||||
--sign "Developer ID Application: Your Name" \
|
||||
target/release/bundle/osx/AI\ Terminal\ Assistant.app
|
||||
|
||||
# Windows（使用 SignTool）
|
||||
signtool sign /a /tr http://timestamp.digicert.com \
|
||||
/td SHA256 /fd SHA256 \
|
||||
target/release/bundle/msi/AI_Terminal_Assistant.msi
|
||||
```
|
||||
|
||||
## 🚢 分发
|
||||
|
||||
### 自动更新
|
||||
|
||||
```rust
|
||||
// src-tauri/src/updater.rs
|
||||
use tauri::updater::builder::UpdateBuilder;
|
||||
|
||||
pub fn check_for_updates(app: &tauri::App) {
|
||||
let update = UpdateBuilder::new()
|
||||
.current_version(&app.package_info().version)
|
||||
.url("https://updates.example.com/check")
|
||||
.build()
|
||||
.unwrap();
|
||||
|
||||
if update.should_update {
|
||||
update.download_and_install().unwrap();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### GitHub 发布
|
||||
|
||||
```yaml
|
||||
# .github/workflows/release.yml
|
||||
name: Release
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
|
||||
jobs:
|
||||
release:
|
||||
strategy:
|
||||
matrix:
|
||||
platform: [macos-latest, ubuntu-latest, windows-latest]
|
||||
runs-on: ${{ matrix.platform }}
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: tauri-apps/tauri-action@v0
|
||||
with:
|
||||
tagName: v__VERSION__
|
||||
releaseName: 'v__VERSION__'
|
||||
releaseBody: '查看 CHANGELOG.md'
|
||||
releaseDraft: true
|
||||
prerelease: false
|
||||
```
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
```bash
|
||||
# 单元测试（Rust）
|
||||
cd src-tauri
|
||||
cargo test
|
||||
|
||||
# 集成测试
|
||||
pnpm test:integration
|
||||
|
||||
# 使用 WebDriver 的端到端测试
|
||||
pnpm test:e2e
|
||||
```
|
||||
|
||||
## 📊 性能
|
||||
|
||||
### 优化技巧
|
||||
|
||||
1. **懒加载** - 按需加载功能
|
||||
2. **IPC 批处理** - 批量处理多个命令
|
||||
3. **资源优化** - 压缩图片/字体
|
||||
4. **内存管理** - 清理监听器
|
||||
5. **后台任务** - 使用 Web Workers
|
||||
|
||||
### 基准测试
|
||||
|
||||
| 指标 | 值 |
|
||||
|--------|-------|
|
||||
| 启动时间 | < 500ms |
|
||||
| 内存使用 | ~50MB 空闲 |
|
||||
| 包大小 | ~10MB 压缩 |
|
||||
| CPU 使用 | < 5% 空闲 |
|
||||
|
||||
## 🐛 调试
|
||||
|
||||
### 开发工具
|
||||
|
||||
```bash
|
||||
# 启用开发工具
|
||||
pnpm dev -- --features devtools
|
||||
|
||||
# Rust 调试
|
||||
RUST_LOG=debug pnpm dev
|
||||
|
||||
# WebView 调试
|
||||
# 在应用窗口中按 F12
|
||||
```
|
||||
|
||||
### 日志记录
|
||||
|
||||
```rust
|
||||
// Rust 日志
|
||||
use log::{info, error};
|
||||
|
||||
info!("应用已启动");
|
||||
error!("加载失败: {}", error);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// 前端日志
|
||||
import { info, error } from '@tauri-apps/api/log';
|
||||
|
||||
await info('应用已启动');
|
||||
await error(`加载失败: ${error}`);
|
||||
```
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
请查看主仓库的贡献指南了解详情。
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||||
|
||||
## 🔗 链接
|
||||
|
||||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||||
- [Tauri 文档](https://tauri.app/v1/guides/)
|
||||
- [下载发布版](https://github.com/username/ai-terminal-assistant/releases)
|
||||
@@ -0,0 +1,354 @@
|
||||
# @ai-assistant/server
|
||||
|
||||
AI Terminal Assistant 的 HTTP/WebSocket 服务器 - 提供 REST API、WebSocket 和 SSE 端点。
|
||||
|
||||
## 📦 安装
|
||||
|
||||
```bash
|
||||
pnpm add @ai-assistant/server
|
||||
```
|
||||
|
||||
## 🌟 功能特性
|
||||
|
||||
- **REST API** - 会话和工具的完整 CRUD 操作
|
||||
- **WebSocket** - 实时双向通信
|
||||
- **服务器推送事件** - 流式状态更新
|
||||
- **身份验证** - 非本地访问的令牌认证
|
||||
- **会话管理** - 持久化会话处理
|
||||
- **CORS 支持** - 可配置的跨域访问
|
||||
- **基于 Hono 构建** - 轻量级、快速的 Web 框架
|
||||
- **Bun 运行时** - 原生 WebSocket 和高性能
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # 使用 Hono 的主服务器设置
|
||||
├── routes/
|
||||
│ ├── sessions.ts # 会话管理端点
|
||||
│ ├── tools.ts # 工具执行端点
|
||||
│ ├── config.ts # 配置端点
|
||||
│ └── health.ts # 健康检查端点
|
||||
├── ws.ts # WebSocket 处理器
|
||||
├── sse.ts # 服务器推送事件处理器
|
||||
├── agent/
|
||||
│ ├── adapter.ts # 核心代理适配器
|
||||
│ └── session.ts # 会话管理
|
||||
├── auth/
|
||||
│ ├── token.ts # 令牌生成/验证
|
||||
│ └── middleware.ts # 认证中间件
|
||||
├── middleware/
|
||||
│ ├── cors.ts # CORS 配置
|
||||
│ ├── error.ts # 错误处理
|
||||
│ └── logging.ts # 请求日志
|
||||
└── types/
|
||||
└── index.ts # TypeScript 定义
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 基本服务器设置
|
||||
|
||||
```typescript
|
||||
import { createServer } from '@ai-assistant/server';
|
||||
|
||||
const server = createServer({
|
||||
port: 3000,
|
||||
host: 'localhost',
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
});
|
||||
|
||||
await server.start();
|
||||
console.log('服务器运行在 http://localhost:3000');
|
||||
```
|
||||
|
||||
### 独立使用
|
||||
|
||||
```bash
|
||||
# 开发模式（热重载）
|
||||
pnpm start:dev
|
||||
|
||||
# 生产模式
|
||||
pnpm start
|
||||
|
||||
# 自定义配置
|
||||
ANTHROPIC_API_KEY=sk-ant-xxx SERVER_PORT=8080 pnpm start
|
||||
```
|
||||
|
||||
## 📡 API 端点
|
||||
|
||||
### REST API
|
||||
|
||||
#### 会话管理
|
||||
```typescript
|
||||
// 创建会话
|
||||
POST /api/sessions
|
||||
响应: { id: string, status: 'idle' | 'busy', createdAt: string }
|
||||
|
||||
// 获取会话
|
||||
GET /api/sessions/:id
|
||||
响应: { id: string, status: string, messages: Message[] }
|
||||
|
||||
// 列出会话
|
||||
GET /api/sessions
|
||||
响应: Session[]
|
||||
|
||||
// 删除会话
|
||||
DELETE /api/sessions/:id
|
||||
响应: { success: boolean }
|
||||
```
|
||||
|
||||
#### 工具
|
||||
```typescript
|
||||
// 列出可用工具
|
||||
GET /api/tools
|
||||
响应: Tool[]
|
||||
|
||||
// 执行工具
|
||||
POST /api/tools/:name/execute
|
||||
请求体: { params: any, sessionId?: string }
|
||||
响应: { result: any }
|
||||
```
|
||||
|
||||
#### 配置
|
||||
```typescript
|
||||
// 获取配置
|
||||
GET /api/config
|
||||
响应: { model: string, maxTokens: number, ... }
|
||||
|
||||
// 更新配置
|
||||
PUT /api/config
|
||||
请求体: { model?: string, maxTokens?: number, ... }
|
||||
响应: { success: boolean, config: Config }
|
||||
```
|
||||
|
||||
### WebSocket 协议
|
||||
|
||||
```typescript
|
||||
// 连接
|
||||
ws://localhost:3000/api/ws/:sessionId
|
||||
|
||||
// 客户端 → 服务器消息
|
||||
{
|
||||
type: 'message',
|
||||
payload: {
|
||||
content: string,
|
||||
attachments?: Attachment[]
|
||||
}
|
||||
}
|
||||
|
||||
// 服务器 → 客户端消息
|
||||
{
|
||||
type: 'chunk' | 'done' | 'error' | 'status',
|
||||
payload: {
|
||||
content?: string, // chunk 类型时
|
||||
response?: Message, // done 类型时
|
||||
error?: string, // error 类型时
|
||||
status?: string // status 类型时
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 服务器推送事件
|
||||
|
||||
```typescript
|
||||
// 连接以获取状态更新
|
||||
GET /api/sse/:sessionId
|
||||
Accept: text/event-stream
|
||||
|
||||
// 事件格式
|
||||
event: status
|
||||
data: { "status": "processing", "progress": 0.5 }
|
||||
|
||||
event: complete
|
||||
data: { "result": "任务完成" }
|
||||
```
|
||||
|
||||
## 🔧 配置
|
||||
|
||||
### 环境变量
|
||||
|
||||
```env
|
||||
# 必需
|
||||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
|
||||
# 可选
|
||||
SERVER_PORT=3000
|
||||
SERVER_HOST=localhost
|
||||
SERVER_CORS_ORIGIN=http://localhost:5173
|
||||
SERVER_AUTH_ENABLED=auto
|
||||
SERVER_LOG_LEVEL=info
|
||||
AI_MODEL=claude-sonnet-4-20250514
|
||||
AI_MAX_TOKENS=4096
|
||||
```
|
||||
|
||||
### 程序化配置
|
||||
|
||||
```typescript
|
||||
interface ServerConfig {
|
||||
port?: number; // 服务器端口（默认：3000）
|
||||
host?: string; // 服务器主机（默认：localhost）
|
||||
apiKey: string; // Anthropic API 密钥
|
||||
cors?: {
|
||||
origin: string | string[];
|
||||
credentials?: boolean;
|
||||
};
|
||||
auth?: {
|
||||
enabled: boolean | 'auto'; // auto 为非本地访问自动启用
|
||||
tokenSecret?: string;
|
||||
};
|
||||
agent?: {
|
||||
model?: string;
|
||||
maxTokens?: number;
|
||||
temperature?: number;
|
||||
};
|
||||
logging?: {
|
||||
level: 'debug' | 'info' | 'warn' | 'error';
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 🔐 身份验证
|
||||
|
||||
当从非本地地址访问时，服务器会自动启用令牌认证：
|
||||
|
||||
```typescript
|
||||
// 生成令牌
|
||||
POST /api/auth/token
|
||||
请求体: { password?: string }
|
||||
响应: { token: string, expiresIn: number }
|
||||
|
||||
// 在请求中使用令牌
|
||||
Authorization: Bearer <token>
|
||||
|
||||
// 或在 WebSocket 中
|
||||
ws://server/api/ws/:sessionId?token=<token>
|
||||
```
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
```bash
|
||||
# 运行测试
|
||||
pnpm test
|
||||
|
||||
# 运行覆盖率测试
|
||||
pnpm test:coverage
|
||||
|
||||
# 端到端测试
|
||||
pnpm test:e2e
|
||||
```
|
||||
|
||||
### 测试示例
|
||||
|
||||
```typescript
|
||||
import { testClient } from '@ai-assistant/server/test';
|
||||
|
||||
describe('服务器 API', () => {
|
||||
const client = testClient({ port: 3001 });
|
||||
|
||||
beforeAll(() => client.start());
|
||||
afterAll(() => client.stop());
|
||||
|
||||
test('创建会话', async () => {
|
||||
const session = await client.post('/api/sessions');
|
||||
expect(session.id).toBeDefined();
|
||||
expect(session.status).toBe('idle');
|
||||
});
|
||||
|
||||
test('WebSocket 对话', async () => {
|
||||
const ws = client.ws('/api/ws/test-session');
|
||||
|
||||
ws.send({ type: 'message', payload: { content: '你好' } });
|
||||
|
||||
const response = await ws.waitFor('done');
|
||||
expect(response.payload.response).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## 🔌 集成示例
|
||||
|
||||
### 与 Express 集成
|
||||
|
||||
```typescript
|
||||
import express from 'express';
|
||||
import { createMiddleware } from '@ai-assistant/server';
|
||||
|
||||
const app = express();
|
||||
app.use('/ai', createMiddleware({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
}));
|
||||
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
### 与 Next.js 集成
|
||||
|
||||
```typescript
|
||||
// app/api/ai/[...path]/route.ts
|
||||
import { handleRequest } from '@ai-assistant/server/next';
|
||||
|
||||
export const { GET, POST, PUT, DELETE } = handleRequest({
|
||||
apiKey: process.env.ANTHROPIC_API_KEY
|
||||
});
|
||||
```
|
||||
|
||||
## 📊 监控
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
# 响应: { status: 'healthy', uptime: 123456, sessions: 5 }
|
||||
```
|
||||
|
||||
### 指标端点
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/api/metrics
|
||||
# 响应: Prometheus 格式的指标
|
||||
```
|
||||
|
||||
## 🚀 部署
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM oven/bun:1.0
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN bun install
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
CMD ["bun", "run", "start"]
|
||||
```
|
||||
|
||||
### PM2
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": [{
|
||||
"name": "ai-server",
|
||||
"script": "bun",
|
||||
"args": "run start",
|
||||
"env": {
|
||||
"SERVER_PORT": 3000,
|
||||
"ANTHROPIC_API_KEY": "sk-ant-xxx"
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献！请遵循主仓库中的贡献指南。
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||||
|
||||
## 🔗 链接
|
||||
|
||||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||||
- [API 文档](https://docs.example.com/server)
|
||||
- [OpenAPI 规范](https://api.example.com/openapi.json)
|
||||
@@ -0,0 +1,366 @@
|
||||
# @ai-assistant/web
|
||||
|
||||
AI Terminal Assistant 的现代 Web 界面 - 基于 React、Vite 和 Tailwind CSS 构建。
|
||||
|
||||
## 📦 安装
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 启动开发服务器
|
||||
pnpm dev
|
||||
|
||||
# 构建生产版本
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## 🌟 功能特性
|
||||
|
||||
- **现代化界面** - 简洁、响应式界面，支持深色/浅色主题
|
||||
- **实时对话** - 基于 WebSocket 的即时消息
|
||||
- **代码编辑器** - 使用 Monaco Editor 的语法高亮
|
||||
- **文件浏览器** - 浏览和编辑项目文件
|
||||
- **终端集成** - 嵌入式终端执行命令
|
||||
- **Markdown 渲染** - AI 响应的富文本格式
|
||||
- **PWA 支持** - 可安装为桌面/移动应用
|
||||
- **移动响应式** - 适配所有屏幕尺寸
|
||||
- **键盘快捷键** - 高效导航和操作
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ ├── Chat/ # 对话界面组件
|
||||
│ │ ├── ChatWindow.tsx
|
||||
│ │ ├── MessageList.tsx
|
||||
│ │ ├── MessageInput.tsx
|
||||
│ │ └── CodeBlock.tsx
|
||||
│ ├── Editor/ # 代码编辑器组件
|
||||
│ │ ├── MonacoEditor.tsx
|
||||
│ │ └── EditorToolbar.tsx
|
||||
│ ├── FileBrowser/ # 文件导航
|
||||
│ │ ├── FileTree.tsx
|
||||
│ │ └── FilePreview.tsx
|
||||
│ ├── Terminal/ # 终端模拟器
|
||||
│ │ └── XTerminal.tsx
|
||||
│ ├── Layout/ # 布局组件
|
||||
│ │ ├── Sidebar.tsx
|
||||
│ │ ├── Header.tsx
|
||||
│ │ └── Tabs.tsx
|
||||
│ └── Common/ # 共享组件
|
||||
│ ├── Button.tsx
|
||||
│ ├── Modal.tsx
|
||||
│ └── Loading.tsx
|
||||
├── hooks/ # 自定义 React Hooks
|
||||
│ ├── useChat.ts
|
||||
│ ├── useWebSocket.ts
|
||||
│ ├── useTheme.ts
|
||||
│ └── useKeyboard.ts
|
||||
├── services/ # API 和服务层
|
||||
│ ├── api.ts
|
||||
│ ├── websocket.ts
|
||||
│ └── storage.ts
|
||||
├── store/ # 状态管理
|
||||
│ ├── chat.store.ts
|
||||
│ ├── editor.store.ts
|
||||
│ └── settings.store.ts
|
||||
├── styles/ # 全局样式
|
||||
│ └── index.css
|
||||
├── types/ # TypeScript 定义
|
||||
├── utils/ # 工具函数
|
||||
├── App.tsx # 主应用组件
|
||||
└── main.tsx # 入口文件
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 开发
|
||||
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
pnpm dev
|
||||
|
||||
# 应用将在 http://localhost:5173 可用
|
||||
# 热模块替换已启用，可即时更新
|
||||
```
|
||||
|
||||
### 生产构建
|
||||
|
||||
```bash
|
||||
# 创建优化构建
|
||||
pnpm build
|
||||
|
||||
# 预览生产构建
|
||||
pnpm preview
|
||||
|
||||
# 构建输出在 dist/ 目录
|
||||
```
|
||||
|
||||
## 🎨 用户界面
|
||||
|
||||
### 主要功能
|
||||
|
||||
#### 对话界面
|
||||
- **消息历史** - 可滚动的持久化对话历史
|
||||
- **代码高亮** - 代码块语法高亮
|
||||
- **文件附件** - 拖拽文件支持
|
||||
- **消息操作** - 复制、编辑、重新生成响应
|
||||
- **流式响应** - 实时 AI 响应流
|
||||
|
||||
#### 代码编辑器
|
||||
- **Monaco 编辑器** - VS Code 的编辑器引擎
|
||||
- **多文件标签** - 同时处理多个文件
|
||||
- **语法高亮** - 100+ 语言支持
|
||||
- **智能感知** - 代码补全和提示
|
||||
- **差异视图** - 并排代码比较
|
||||
|
||||
#### 文件浏览器
|
||||
- **树形视图** - 分层文件结构
|
||||
- **快速操作** - 创建、重命名、删除文件
|
||||
- **搜索** - 快速文件搜索，支持模糊匹配
|
||||
- **预览** - 快速预览文件无需打开
|
||||
- **右键菜单** - 右键操作
|
||||
|
||||
#### 终端
|
||||
- **XTerm.js** - 完整终端模拟
|
||||
- **命令历史** - 浏览之前的命令
|
||||
- **复制/粘贴** - 标准剪贴板操作
|
||||
- **主题** - 多种配色方案
|
||||
|
||||
## 🎯 组件示例
|
||||
|
||||
### 使用对话组件
|
||||
|
||||
```tsx
|
||||
import { Chat } from '@ai-assistant/web/components';
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<Chat
|
||||
serverUrl="http://localhost:3000"
|
||||
sessionId="my-session"
|
||||
onMessage={(message) => console.log('新消息:', message)}
|
||||
theme="dark"
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义 Hook 用法
|
||||
|
||||
```tsx
|
||||
import { useChat } from '@ai-assistant/web/hooks';
|
||||
|
||||
function MyComponent() {
|
||||
const { messages, sendMessage, isLoading } = useChat({
|
||||
serverUrl: 'http://localhost:3000',
|
||||
sessionId: 'my-session'
|
||||
});
|
||||
|
||||
return (
|
||||
<div>
|
||||
{messages.map(msg => (
|
||||
<div key={msg.id}>{msg.content}</div>
|
||||
))}
|
||||
<button onClick={() => sendMessage('你好 AI！')}>
|
||||
发送消息
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## ⚙️ 配置
|
||||
|
||||
### 环境变量
|
||||
|
||||
创建 `.env` 文件：
|
||||
|
||||
```env
|
||||
# API 配置
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_WS_URL=ws://localhost:3000
|
||||
VITE_AUTH_TOKEN=your-token-here
|
||||
|
||||
# 功能开关
|
||||
VITE_ENABLE_TERMINAL=true
|
||||
VITE_ENABLE_FILE_BROWSER=true
|
||||
VITE_ENABLE_CODE_EDITOR=true
|
||||
|
||||
# 主题
|
||||
VITE_DEFAULT_THEME=dark
|
||||
```
|
||||
|
||||
### 构建配置
|
||||
|
||||
`vite.config.ts`：
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': 'http://localhost:3000'
|
||||
}
|
||||
},
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
sourcemap: true,
|
||||
minify: 'esbuild'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 🎹 键盘快捷键
|
||||
|
||||
| 快捷键 | 操作 |
|
||||
|----------|--------|
|
||||
| `Ctrl/Cmd + Enter` | 发送消息 |
|
||||
| `Ctrl/Cmd + K` | 清空对话 |
|
||||
| `Ctrl/Cmd + /` | 切换侧边栏 |
|
||||
| `Ctrl/Cmd + ,` | 打开设置 |
|
||||
| `Ctrl/Cmd + Shift + P` | 命令面板 |
|
||||
| `Ctrl/Cmd + B` | 切换文件浏览器 |
|
||||
| `Ctrl/Cmd + J` | 切换终端 |
|
||||
| `Esc` | 关闭模态框/弹窗 |
|
||||
|
||||
## 📱 渐进式 Web 应用
|
||||
|
||||
应用可以安装为 PWA：
|
||||
|
||||
1. 在 Chrome/Edge 中打开
|
||||
2. 点击地址栏中的安装图标
|
||||
3. 或使用浏览器菜单："安装应用"
|
||||
|
||||
功能：
|
||||
- 使用 Service Worker 的离线支持
|
||||
- 桌面/移动应用体验
|
||||
- 推送通知（即将推出）
|
||||
- 后台同步
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
```bash
|
||||
# 运行单元测试
|
||||
pnpm test
|
||||
|
||||
# 运行覆盖率测试
|
||||
pnpm test:coverage
|
||||
|
||||
# 运行端到端测试
|
||||
pnpm test:e2e
|
||||
|
||||
# 组件测试
|
||||
pnpm test:components
|
||||
```
|
||||
|
||||
### 测试示例
|
||||
|
||||
```tsx
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { Chat } from './Chat';
|
||||
|
||||
test('渲染对话界面', () => {
|
||||
render(<Chat serverUrl="http://localhost:3000" />);
|
||||
expect(screen.getByPlaceholderText('输入消息...')).toBeInTheDocument();
|
||||
});
|
||||
```
|
||||
|
||||
## 🎨 主题设置
|
||||
|
||||
### 自定义主题
|
||||
|
||||
```css
|
||||
/* src/styles/themes/custom.css */
|
||||
:root[data-theme="custom"] {
|
||||
--primary: #6366f1;
|
||||
--background: #0f172a;
|
||||
--foreground: #f8fafc;
|
||||
--border: #334155;
|
||||
--accent: #8b5cf6;
|
||||
}
|
||||
```
|
||||
|
||||
### 应用主题
|
||||
|
||||
```tsx
|
||||
import { useTheme } from '@ai-assistant/web/hooks';
|
||||
|
||||
function ThemeToggle() {
|
||||
const { theme, setTheme } = useTheme();
|
||||
|
||||
return (
|
||||
<button onClick={() => setTheme('custom')}>
|
||||
使用自定义主题
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 性能优化
|
||||
|
||||
### 优化技巧
|
||||
|
||||
1. **代码分割** - 路由懒加载
|
||||
2. **图片优化** - WebP 格式带后备方案
|
||||
3. **包大小** - 启用 Tree Shaking
|
||||
4. **缓存** - Service Worker 缓存
|
||||
5. **虚拟滚动** - 长列表优化
|
||||
|
||||
### 包分析
|
||||
|
||||
```bash
|
||||
# 分析包大小
|
||||
pnpm build:analyze
|
||||
|
||||
# 在浏览器中打开可视化
|
||||
```
|
||||
|
||||
## 🚀 部署
|
||||
|
||||
### Vercel
|
||||
|
||||
```bash
|
||||
# 部署到 Vercel
|
||||
vercel deploy --prod
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM nginx:alpine
|
||||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||||
EXPOSE 80
|
||||
```
|
||||
|
||||
### 静态托管
|
||||
|
||||
`dist/` 中的构建输出可由任何静态主机服务：
|
||||
- Netlify
|
||||
- GitHub Pages
|
||||
- CloudFlare Pages
|
||||
- AWS S3 + CloudFront
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
请查看主仓库的贡献指南了解详情。
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||||
|
||||
## 🔗 链接
|
||||
|
||||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||||
- [组件 Storybook](https://storybook.example.com)
|
||||
- [设计系统](https://design.example.com)
|
||||
Reference in New Issue
Block a user