项目介绍
HyperChat 中文文档
HyperChat
🌟 本地AI代理平台 - 引领AI即代码的概念，为每个项目赋予独特的AI大脑
HyperChat 是一款革命性的本地AI代理平台，通过配置文件驱动的方式，完全本地化、迁移和版本控制AI能力。告别云依赖，拥有自己的项目级别的AI专家。
🎯 核心特性
- 🏠 完全本地化 数据无法导出本地，隐私和安全可控
- 🧠 代理记忆 AI代理理解并记住你的项目上下文
- 📁 配置即代码 所有AI能力都通过文件配置，并支持Git管理
- 🔧 深度工具集成 支持MCP协议，可以直接操作本地文件系统
- 📦 一键迁移 完整
.hyperchat/配置目录，随项目迁移 - 📂 多个@文件路径 智能识别多个文件引用，支持复杂文件操作 ✨新功能
- 🎯 代理自定义命令 Markdown模板驱动快捷命令系统 ✨新功能
🎯 项目愿景
HyperChat 1.0 是一个完全手动编写的项目，目前正在迁移到2.0版本。
HyperChat 2.0 让我们一起Vibe编码 欢迎与Claude Code和GitHub Copilot等AI工具一起开发。
🎯 双层架构设计
创新双模式架构 - 根据不同的使用场景优化用户体验
🌐 Web前端：多工作区协作中心
设计理念 项目级协作，统一资源管理
- 🗂️ 多工作区标签管理 同时打开多个项目工作区，只需点击即可切换
- 👥 团队协作优化 工作区级别的代理集合，MCP服务池
- 📊 视觉管理界面 图形配置，实时监控，数据统计
- 💼 适用场景 项目开发，团队协作，工作区管理，可视化操作
💻 CLI前端：代理优先快速交互
设计理念 代理集中，单个智能代理快速启动
- ⚡ 快速启动 直接选择代理，并根据需要从工作区加载MCP工具
- 🎯 对话专注 代理独占记忆，上下文，聊天历史
- 🔧 灵活工具链 代理内置MCP工具，回退到工作区共享资源
- 🚀 适用场景 快速对话，自动化脚本，命令行工作流，CI/CD集成
📋 架构对比
| 功能特性 | 🌐 Web多工作区模式 | 💻 CLI代理优先模式 |
|---|---|---|
| 核心概念 | ||
| 设计中心 | 🗂️ 工作区协作中心 | 🤖 代理直接交互 |
| 资源管理 | 工作区统一MCP池 | 代理按需启动MCP |
| 使用 | 多标签并发管理 | 单个代理快速启动 |
| 界面体验 | ||
| 界面风格 | 🖥️ 现代Web界面 | 📟 命令行+🎨 TUI |
| 交互模式 | 鼠标点击+表单操作 | 键盘输入+命令参数 |
| 实时更新 | ✅ SSE流式推送 | ✅ 终端流式输出 |
| 适用场景 | ||
| 主要目的 | 项目开发，团队协作 | 快速对话，脚本集成 |
| 使用环境 | 桌面浏览器，开发IDE | 终端，服务器CI/CD |
| 工作流程 | 长期项目管理 | 临时对话处理 |
🚀 快速体验
⌨️ 命令行快速启动
# 全局安装
npm install -g @dadigua/hyperchat
# 或直接运行
npx -y @dadigua/hyperchat
快速配置环境变量：
# 基础配置 - 设置默认AI模型
export HyperChat_API_KEY=your-api-key # API密钥
export HyperChat_API_URL=your-api-url # API端点URL
export HyperChat_AI_Provider=openai # AI提供商 (openai/claude/gemini/kimi/qwen等)
export HyperChat_AI_Model=gpt-4o # 默认模型名称
# 然后直接使用
hyperchat "你好，世界！" # 使用配置的默认模型
🌐 使用Web多工作区模式示例
# 启动多工作区Web界面
hyperchat serve # 访问: http://localhost:16100
# Web界面功能特色：
# ✅ 多工作区标签页管理
# ✅ 每个标签页独立的代理集合、MCP服务、聊天记录
# ✅ 可视化配置和实时监控
# ✅ 团队协作和项目管理
💻 使用CLI代理优先模式示例
# 🚀 代理优先快速启动 - 核心特色
hyperchat agent list # 发现可用代理（全局 + 工作区）
hyperchat agent mybot "你好" # 🎯 直接启动代理，按需加载MCP
hyperchat agent mybot chat # 🎯 代理专属对话会话
# 快速AI聊天（使用默认代理）
hyperchat "你好，今天怎么样？" # 直接与默认模型聊天
hyperchat chat "写一个Python脚本" # 聊天命令
hyperchat chat # 交互式聊天模式
# 📁 智能文件处理 - 多@符号支持 ✨新功能
hyperchat "分析 @./src/index.ts 的代码质量"
hyperchat "对比 @./package.json 和 @./yarn.lock"
hyperchat "请比较 @./src/components/ 和 @./docs/ 的结构"
# 🎯 代理自定义命令 - 快捷输入专业提示词 ✨新功能
hyperchat agent coder "/bug-fix @./src/login.ts 登录功能异常"
hyperchat agent coder "/review @./src/api/user.js"
hyperchat agent coder "/optimize 这段代码性能不好"
# 代理管理（在当前工作区或全局）
hyperchat agent create mybot # 创建新代理
hyperchat agent delete mybot # 删除代理
# 工作区管理
hyperchat workspace create # 在当前目录创建工作区
# 全局选项和工作区指定
hyperchat chat --workspace /path/to/project # 使用特定工作区
hyperchat --verbose chat "你好" # 详细日志
hyperchat --help # 显示帮助
# CLI模式优势：
# ⚡ 代理直接启动，无需切换界面
# 🔧 按需从工作区加载MCP工具
# 💾 代理专属记忆和聊天历史
# 🚀 适合脚本集成和自动化
🔄 双模式协作工作
# 场景1：开发时使用Web
hyperchat serve # 启动Web界面管理项目
# 场景2：CI/CD自动化使用CLI
hyperchat agent test-runner "运行所有测试并生成报告"
# 场景3：团队协作使用Web
# 在Web界面中管理多个项目工作区，配置共享的代理和MCP服务
🔧 环境变量配置
HyperChat 2.0 实现了强大的五层优先级环境变量系统，使配置管理更加灵活：
优先级顺序（从低到高）：
- 默认值 - 内置默认配置在代码中
- process.env - 系统环境变量
- Global.env -
~/Documents/HyperChat/.env - Workplace.env - 项目目录下的
.env文件 - CLI参数 - 从命令行传递的参数（最高优先级）
核心环境变量支持：
# 快速配置 - 默认AI模型
HyperChat_API_KEY=your-api-key # 默认API密钥
HyperChat_API_URL=your-api-url # 默认API端点
HyperChat_AI_Provider=openai # 默认AI提供商
HyperChat_AI_Model=gpt-4o # 默认模型名称
# 服务配置
HYPERCHAT_WEB_PASSWORD=your-web-password # Web界面访问密码
HYPERCHAT_PORT=11600 # Web服务端口
HYPERCHAT_HOST=localhost # 服务绑定地址
# 界面配置
HYPERCHAT_LANGUAGE=zh # 界面语言 (zh/en)
HYPERCHAT_LOG_LEVEL=info # 日志级别
# 自定义API端点
HYPERCHAT_OPENAI_BASE_URL=https://api.openai.com/v1
HYPERCHAT_CLAUDE_BASE_URL=https://api.anthropic.com
使用示例：
# 方法1：快速配置默认模型
export HyperChat_API_KEY=sk-1234567890
export HyperChat_AI_Provider=openai
export HyperChat_AI_Model=gpt-4o
hyperchat "你好" # 直接使用默认配置
# 方法2：Web服务配置
export HYPERCHAT_WEB_PASSWORD=mypassword
hyperchat serve
# 方法3：项目 .env 文件
echo "HyperChat_API_KEY=your-key" > .env
echo "HyperChat_AI_Provider=claude" >> .env
hyperchat chat
# 方法4：CLI参数（最高优先级）
hyperchat serve --password=clipass
# 方法5：全局配置文件
echo "HyperChat_API_KEY=global-key" > ~/Documents/HyperChat/.env
echo "HyperChat_AI_Provider=gemini" >> ~/Documents/HyperChat/.env
🛠️ 技术架构
🎯 双层架构技术实现
HyperChat 2.0 采用双层架构设计，根据不同的使用场景提供优化体验：
🌐 Web层：工作区中心架构
// Web前端：工作区统一MCP管理
const workspace = workspaceManager.get(workspacePath);
const mcpManager = workspace.getMcpManager();
const client = mcpManager.getClient(clientName);
技术特点：
- 🗂️ 多工作区并发管理：
WorkspaceManager-enhanced支持缓存多个工作区实例 - 🔌 工作区MCP服务池 统一MCP客户端管理
- 📊 实时数据同步 SSE流式推送，多标签页独立状态管理
- 🔄配置合并机制 智能合并全局配置和工作区配置
💻 CLI层：代理优先架构
// CLI前端：代理专属MCP访问
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);
// 回退到工作区共享MCP（如果需要）
技术特点：
- ⚡ 代理直接启动 省略工作区初始化，直接访问代理实例
- 🔧 工具链按需加载 从代理内置工具逐步加载到工作区共享资源
- 💾 专属上下文 代理独立记忆，聊天历史，配置管理
- 🚀 快速响应 无UI渲染开销，适合脚本和自动化
HyperChat双层架构/
├── packages/
│ ├── shared/ # 共享代码和类型定义
│ ├── core/ # Node.js核心服务 + CLI代理优先层
│ │ ├── src/cli/ # 💻 CLI代理直接交互层
│ │ ├── src/workspace/ # 双层工作区管理系统
│ │ │ ├── workspaceManager-enhanced.mts # 🌐 多工作区并发管理
│ │ ├── src/mcp/ # MCP协议实现
│ │ └── src/commands/ # Web API命令系统
│ ├── web/ # 🌐 React Web多工作区层
│ │ ├── src/pages/workspace/ # 多工作区管理组件
│ │ │ ├── WorkspaceManage.tsx # 多标签页管理器
│ │ │ └── workspace.tsx # 单工作区实例组件
│ │ └── src/hooks/useChatStream.ts # workspacePath参数化
│ └── electron/ # Electron应用封装
└── docs/ # 双层架构文档
💼 双层架构配置管理
🌐 Web多工作区模式配置：
项目目录/
├── .hyperchat/ # 工作区统一配置目录
│ ├── mcp.json # 🔌 工作区级MCP服务池
│ ├── ai_models.json # 🤖 工作区AI模型配置
│ ├── .env # 工作区环境变量
│ └── agents/ # 🗂️ 工作区代理集合
│ ├── project-assistant/ # 项目专用代理
│ │ ├── agent.yaml # 代理配置
│ │ ├── memory.md # 项目上下文记忆
│ │ └── chatlogs/ # 团队对话历史
│ └── code-reviewer/ # 代码审查代理
├── .git/ # 版本控制
└── package.json # 项目配置
💻 CLI代理优先模式访问：
全局配置/
~/Documents/HyperChat/
.hyperchat/
├── mcp.json # 🌍 全局MCP服务池
├── .env # 全局环境变量
└── agents/ # 🚀 全局代理库
├── personal-assistant/ # 个人助手代理
│ ├── agent.yaml # 代理配置
│ ├── memory.md # 个人上下文记忆
│ └── chatlogs/ # 个人对话历史
└── code-expert/ # 专业代码代理
双层配置的核心优势：
- 🌐 Web模式 集中式工作区，适用于项目级管理和团队协作
- 💻 CLI模式 代理集中，支持跨项目个人工具使用
- 🔄 智能合并 五层优先级管理全局配置和工作区配置
- 💾 数据隔离 项目级和个人级数据完全分离，互不干扰
## 🌟 AI即代码的革命性优势
### 🔄 双层架构下的智能管理
#### 🌐 Web模式：团队协作版本控制
```bash
# 📁 项目级AI配置版本管理
git add .hyperchat/agents/project-assistant/
git commit -m "添加项目专用AI助手"
git push origin feature/project-ai
# 👥 团队AI最佳实践分享
git clone https://github.com/team/ai-workspace-templates.git
cp -r ai-workspace-templates/react-fullstack/.hyperchat ./
# 🔄 项目AI配置回滚
git checkout HEAD~1 -- .hyperchat/
💻 CLI模式：个人工具管理
# 🚀 快速部署个人代理
hyperchat agent create personal-coder --template ~/ai-templates/
# 🌍 跨项目使用个人代理
cd /project-a && hyperchat agent personal-coder "分析这个项目"
cd /project-b && hyperchat agent personal-coder "分析这个项目"
# 💾 代理记忆和上下文自动切换
# personal-coder 会记住不同项目的特点和上下文
代理配置和自定义命令 ✨新功能
代理基本配置
# .hyperchat/agents/project-assistant/agent.yaml
name: "项目助手"
description: "专门为本项目设计的React + Node.js全栈助手"
modelKey: "claude-3-5-sonnet"
isConfirmCallTool: false
# 🔌 使用工作区级MCP服务池
allowMCPs: ["filesystem", "git", "npm", "database"]
prompt: |
你是本项目的专属AI助手，熟悉：
- 项目架构：React + TypeScript + Node.js
- 业务领域：电商平台开发
- 团队规范：ESLint + Prettier + Jest
请基于项目上下文提供专业建议。
tags: ["project", "fullstack", "ecommerce"]
代理自定义命令目录结构 ✨新功能
.hyperchat/agents/project-assistant/
├── agent.yaml # 代理配置
├── memory.md # 代理记忆
├── commands/ # 🎯 自定义命令目录
│ ├── bug-fix.md # 修复bug命令
│ ├── review.md # 代码审查命令
│ ├── explain.md # 代码解释命令
│ ├── test.md # 测试用例命令
│ ├── optimize.md # 代码优化命令
│ └── document.md # 文档生成命令
└── chatlogs/ # 聊天记录
命令模板示例（纯Markdown）
# commands/bug-fix.md
请帮我修复以下代码中的bug：
$ARG
要求：
1. 仔细分析问题的根本原因
2. 提供详细的修复方案
3. 给出修复后的完整代码
4. 解释修复的原理和最佳实践
5. 提供预防类似问题的建议
# commands/review.md
请对以下代码进行全面的code review：
$ARG
Review要点：
1. **代码质量**：可读性、维护性、命名规范
2.