From 563224fa73a60a90708d27110fec8d8d1148fc26 Mon Sep 17 00:00:00 2001 From: kurihada Date: Fri, 12 Dec 2025 15:31:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.zh-CN.md | 225 ++++++++++++++++ packages/cli/README.zh-CN.md | 321 +++++++++++++++++++++++ packages/core/README.zh-CN.md | 245 +++++++++++++++++ packages/desktop/README.zh-CN.md | 436 +++++++++++++++++++++++++++++++ packages/server/README.zh-CN.md | 354 +++++++++++++++++++++++++ packages/web/README.zh-CN.md | 366 ++++++++++++++++++++++++++ 6 files changed, 1947 insertions(+) create mode 100644 README.zh-CN.md create mode 100644 packages/cli/README.zh-CN.md create mode 100644 packages/core/README.zh-CN.md create mode 100644 packages/desktop/README.zh-CN.md create mode 100644 packages/server/README.zh-CN.md create mode 100644 packages/web/README.zh-CN.md diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..1134200 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,225 @@ +# AI Terminal Assistant + +
+

🤖 基于 Claude API 的强大终端 AI 编程助手

+

+ 特性 • + 快速开始 • + 文档 • + 包结构 +

+

+ License + Node + pnpm +

+
+ +## 🌟 项目概述 + +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 +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) + +--- + +
+ 由 AI Terminal Assistant 团队用 ❤️ 制作 +
\ No newline at end of file diff --git a/packages/cli/README.zh-CN.md b/packages/cli/README.zh-CN.md new file mode 100644 index 0000000..23cc6f9 --- /dev/null +++ b/packages/cli/README.zh-CN.md @@ -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 配置文件路径 + --verbose 启用详细日志 +``` + +### 服务器命令 + +```bash +ai-assist serve [options] + +选项： + -p, --port 服务器端口（默认：3000） + -h, --host 服务器主机（默认：localhost） + --api-key Anthropic API 密钥（或使用 ANTHROPIC_API_KEY 环境变量） + --model 使用的 AI 模型 + --max-tokens 最大响应令牌数 + --no-auth 禁用身份验证 + --cors-origin CORS 允许的来源 +``` + +### 附加命令 + +```bash +ai-assist attach [server-url] [options] + +参数： + server-url 服务器 URL（默认：http://localhost:3000） + +选项： + -s, --session 要附加的会话 ID + -t, --token 身份验证令牌 + --no-history 不加载会话历史 + --stream 启用流模式 +``` + +## ⌨️ 交互式命令 + +连接后，可以在对话界面中使用这些命令： + +``` +/help 显示可用命令 +/clear 清屏 +/history 显示消息历史 +/attach 将文件附加到下一条消息 +/model 切换 AI 模型 +/session new 开始新会话 +/session list 列出可用会话 +/session switch 切换到另一个会话 +/export 导出对话到文件 +/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 < 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) \ No newline at end of file diff --git a/packages/core/README.zh-CN.md b/packages/core/README.zh-CN.md new file mode 100644 index 0000000..d7ceb8c --- /dev/null +++ b/packages/core/README.zh-CN.md @@ -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; + streamChat(message: string, options?: StreamOptions): AsyncIterator; + 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; +} +``` + +### 编辑器接口 + +```typescript +interface Editor { + edit(path: string, content: string | EditParams): Promise; + 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) \ No newline at end of file diff --git a/packages/desktop/README.zh-CN.md b/packages/desktop/README.zh-CN.md new file mode 100644 index 0000000..fb69f62 --- /dev/null +++ b/packages/desktop/README.zh-CN.md @@ -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 +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 { + // 处理消息 + 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) \ No newline at end of file diff --git a/packages/server/README.zh-CN.md b/packages/server/README.zh-CN.md new file mode 100644 index 0000000..ca7d0c0 --- /dev/null +++ b/packages/server/README.zh-CN.md @@ -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 + +// 或在 WebSocket 中 +ws://server/api/ws/:sessionId?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) \ No newline at end of file diff --git a/packages/web/README.zh-CN.md b/packages/web/README.zh-CN.md new file mode 100644 index 0000000..fa79e22 --- /dev/null +++ b/packages/web/README.zh-CN.md @@ -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 ( + 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 ( +
+ {messages.map(msg => ( +
{msg.content}
+ ))} + +
+ ); +} +``` + +## ⚙️ 配置 + +### 环境变量 + +创建 `.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(); + 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 ( + + ); +} +``` + +## 📊 性能优化 + +### 优化技巧 + +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) \ No newline at end of file