HyperChat 中文文档

HyperChat

🌟 本地 AI 代理平台 - 首创 AI as Code 理念，让每个项目都有专属的 AI 大脑

HyperChat 是一个革命性的本地 AI 代理平台，通过配置文件驱动的方式，让 AI 能力完全本地化、可迁移、可版本控制。告别云端依赖，拥有真正属于自己的项目级 AI 专家。

🎯 核心特色

• 🏠 完全本地化：数据不出本地，隐私安全可控
• 🧠 Agent记忆：AI 代理理解并记住你的项目上下文
• 📁 配置即代码：所有 AI 能力通过文件配置，支持 Git 管理
• 🔧 深度工具集成：MCP 协议支持，可直接操作本地文件系统
• 📦 一键迁移：完整的 .hyperchat/ 配置目录，随项目迁移
• 📂 多@文件路径：智能识别多个文件引用，支持复杂文件操作 ✨新功能
• 🎯 Agent自定义命令：Markdown模板驱动的快捷命令系统 ✨新功能

🎯 项目愿景

HyperChat 1.0 是一个完全手工编写的项目，正在迁移到2.0。

HyperChat 2.0 大家一起 Vibe Coding，欢迎使用 Claude Code 和 GitHub Copilot 等 AI 工具一起开发。

🎯 双层架构设计

创新的双模式架构 - 根据不同使用场景优化用户体验

🌐 Web 前端：多工作区协作中心

设计理念：项目级协作，统一资源管理

• 🗂️ 多工作区标签页管理：同时打开多个项目工作区，一键切换
• 👥 团队协作优化：工作区级别的 Agent 集合、MCP 服务池
• 📊 可视化管理界面：图形化配置、实时监控、数据统计
• 💼 适用场景：项目开发、团队协作、工作区管理、可视化操作

💻 CLI 前端：Agent 优先快速交互

设计理念：Agent 中心化，极速启动单个智能体

• ⚡ 快速启动：直接选择 Agent，从工作区按需加载 MCP 工具
• 🎯 专注对话：Agent 专属记忆、上下文、聊天历史
• 🔧 灵活工具链：Agent 内置 MCP 工具，回退到工作区共享资源
• 🚀 适用场景：快速对话、自动化脚本、命令行工作流、CI/CD 集成

📋 架构对比

功能特性	🌐 Web 多工作区模式	💻 CLI Agent 优先模式
核心理念
设计中心	🗂️ 工作区协作中心	🤖 Agent 直接交互
资源管理	工作区统一 MCP 池	Agent按需启动MCP
使用方式	多标签页并发管理	单 Agent 快速启动
界面体验
界面风格	🖥️ 现代 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 界面功能特色：
# ✅ 多工作区标签页管理
# ✅ 每个标签页独立的 Agent 集合、MCP 服务、聊天记录
# ✅ 可视化配置和实时监控
# ✅ 团队协作和项目管理

💻 CLI Agent 优先模式使用示例

# 🚀 Agent 优先快速启动 - 核心特色
hyperchat agent list                   # 发现可用 Agent（全局 + 工作区）
hyperchat agent mybot "你好"           # 🎯 直接启动 Agent，按需加载 MCP
hyperchat agent mybot chat             # 🎯 Agent 专属对话会话

# 快速 AI 聊天（使用默认 Agent）
hyperchat "你好，今天怎么样？"           # 直接与默认模型聊天
hyperchat chat "写一个 Python 脚本"     # 聊天命令
hyperchat chat                         # 交互式聊天模式

# 📁 智能文件处理 - 多@符号支持 ✨新功能
hyperchat "分析 @./src/index.ts 的代码质量"
hyperchat "对比 @./package.json 和 @./yarn.lock"
hyperchat "请比较 @./src/components/ 和 @./docs/ 的结构"

# 🎯 Agent自定义命令 - 快捷输入专业提示词 ✨新功能
hyperchat agent coder "/bug-fix @./src/login.ts 登录功能异常"
hyperchat agent coder "/review @./src/api/user.js"
hyperchat agent coder "/optimize 这段代码性能不好"

# Agent 管理（在当前工作区或全局）
hyperchat agent create mybot           # 创建新 Agent
hyperchat agent delete mybot           # 删除 Agent

# 工作区管理
hyperchat workspace create             # 在当前目录创建工作区


# 全局选项和工作区指定
hyperchat chat --workspace /path/to/project  # 使用特定工作区
hyperchat --verbose chat "你好"             # 详细日志
hyperchat --help                            # 显示帮助

# CLI 模式优势：
# ⚡ Agent 直接启动，无需切换界面
# 🔧 按需从工作区加载 MCP 工具
# 💾 Agent 专属记忆和聊天历史
# 🚀 适合脚本集成和自动化

🔄 双模式协同工作

# 场景1：开发时 Web
hyperchat serve                       # 启动 Web 界面管理项目

# 场景2：CI/CD 自动化使用 CLI
hyperchat agent test-runner "运行所有测试并生成报告"

# 场景3：团队协作使用 Web
# 在 Web 界面中管理多个项目工作区，配置共享的 Agent 和 MCP 服务

🔧 环境变量配置

HyperChat 2.0 实现了强大的5层优先级环境变量系统，让配置管理更加灵活：

优先级顺序（从低到高）：

1. 默认值 - 代码中的内置默认配置
2. process.env - 系统环境变量
3. 全局 .env - ~/Documents/HyperChat/.env
4. 工作区 .env - 项目目录下的 .env 文件
5. 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=16100                        # 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 层：Agent 优先架构

// CLI 前端：Agent 专属 MCP 访问
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);
// 回退到工作区共享 MCP（如果需要）

技术特点：

• ⚡ Agent 直接启动：省略工作区初始化，直接访问 Agent 实例
• 🔧 工具链按需加载：从 Agent 内置工具到工作区共享资源的渐进式加载
• 💾 专属上下文：Agent 独立记忆、聊天历史、配置管理
• 🚀 极速响应：无 UI 渲染开销，适合脚本和自动化

HyperChat 双层架构/
├── packages/
│   ├── shared/              # 共享代码和类型定义
│   ├── core/                # Node.js 核心服务 + CLI Agent 优先层
│   │   ├── src/cli/         # 💻 CLI Agent 直接交互层
│   │   ├── 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/                    # 🗂️ 工作区 Agent 集合
│       ├── project-assistant/     # 项目专用 Agent
│       │   ├── agent.yaml         # Agent 配置
│       │   ├── memory.md          # 项目上下文记忆
│       │   └著 chatlogs/          # 团队对话历史
│       └著 code-reviewer/         # 代码审查 Agent
├著 .git/                         # 版本控制
└著 package.json                  # 项目配置

💻 CLI Agent 优先模式访问：
全局配置/
~/Documents/HyperChat/
  .hyperchat/
  ├── mcp.json                     # 🌍 全局 MCP 服务池
  ├── .env                         # 全局环境变量
  └著 agents/                      # 🚀 全局 Agent 库
      ├── personal-assistant/      # 个人助手 Agent
      │   ├── agent.yaml           # Agent 配置
      │   ├── memory.md            # 个人上下文记忆
      │   └著 chatlogs/            # 个人对话历史
      └著 code-expert/             # 专业代码 Agent

双层配置的核心优势：

• 🌐 Web 模式：工作区中心化，适合项目级管理和团队协作
• 💻 CLI 模式：Agent 中心化，支持跨项目的个人工具使用
• 🔄 智能合并：全局配置 + 工作区配置的 5 层优先级管理
• 💾 数据隔离：项目级和个人级数据完全分离，互不干扰

## 🌟 AI as Code 的革命性优势

### 🔄 双层架构下的智能管理

#### 🌐 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 模式：个人工具管理

# 🚀 快速部署个人 Agent
hyperchat agent create personal-coder --template ~/ai-templates/

# 🌍 跨项目使用个人 Agent
cd /project-a && hyperchat agent personal-coder "分析这个项目"
cd /project-b && hyperchat agent personal-coder "分析这个项目"

# 💾 Agent 记忆和上下文自动切换
# personal-coder 会记住不同项目的特点和上下文

Agent 配置与自定义命令 ✨新功能

Agent 基础配置

# .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"]

Agent 自定义命令目录结构 ✨新功能

.hyperchat/agents/project-assistant/
├著 agent.yaml              # Agent 配置
├著 memory.md               # Agent 记忆
├著 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. **性能问题**：算法效率、内存使用、潜在瓶颈
3. **安全隐患**：输入验证、权限控制、数据泄露风险
4. **最佳实践**：设计模式、架构原则、团队规范
5. **改进建议**：具体的优化方案和替代实现

请提供具体的修改建议和代码示例。

使用示例

# 使用自定义命令进行bug修复
hyperchat agent project-assistant "/bug-fix @./src/login.ts 用户登录后跳转异常"

# 实际发送给AI的内容：
# 请帮我修复以下代码中的bug：
# @./src/login.ts 用户登录后跳转异常
# 要求：
# 1. 仔细分析问题的根本原因
# 2. 提供详细的修复方案
# 3. 给出修复后的完整代码
# 4. 解释修复的原理和最佳实践
# 5. 提供预防类似问题的建议

# 使用代码审查命令
hyperchat agent project-assistant "/review @./src/components/UserProfile.tsx"

# 在交互式聊天中使用
hyperchat agent project-assistant chat
> /bug-fix 这个函数有内存泄漏问题
> /optimize @./src/utils/dataProcessor.js

# ~/Documents/HyperChat/.hyperchat/agents/personal-coder/agent.yaml
name: "个人编程助手"
description: "跨项目的通用编程助手，支持多种技术栈"
modelKey: "gpt-4o"
isConfirmCallTool: true
# ⚡ Agent 专属 MCP 工具 + 回退到工作区
allowMCPs: ["terminal", "browser", "calculator"]
prompt: |
  你是我的个人编程助手，擅长：
  - 多语言开发：Python, JavaScript, Go, Rust
  - 架构设计和代码审查
  - 快速原型开发和问题解决
  
  根据不同项目的上下文调整回答风格。
tags: ["personal", "general", "cross-project"]

🤖 AI 模型推荐

模型提供商	推荐程度	特色功能
Claude	⭐⭐⭐⭐⭐⭐	最强
Kimi k2	⭐⭐⭐⭐⭐	很不错

🔧 开发指南

💻 本地开发

# 克隆项目
git clone https://github.com/BigSweetPotatoStudio/HyperChat.git
cd HyperChat

# 安装依赖
npm install
cd packages/electron && npm install
cd packages/web && npm install
cd ../..

# 启动开发服务器
npm run dev



## 🤝 社区交流

- [Telegram](https://t.me/dadigua001)
- [QQ 群](https://qm.qq.com/cgi-bin/qm/qr?k=KrNWdu5sp7H3ves3ZPSd7ppKjQiPrAvZ&jump_from=webapi&authKey=xnW+Lcgk5KLh5NPh3lU0ddz9CFDbXgvjEy35wsYipUrCsqXFcqlvM5Yorh6jkGim)

## 📄 免责声明

本项目仅供学习交流使用。使用本项目进行的任何操作（如爬虫行为等）与项目开发者无关。

## 📜 许可证

本项目采用开源许可证，详情请查看 [LICENSE](LICENSE) 文件。

HyperChat 快速上手指南

HyperChat 是一个革命性的本地 AI Agent 平台，首创"AI as Code"理念。它通过配置文件驱动，让 AI 能力完全本地化、可迁移且支持版本控制，是真正属于你项目的专属 AI 专家。

🛠️ 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Windows, macOS, 或 Linux
• 运行时依赖：已安装 Node.js (推荐 v18 或更高版本)
• API 密钥：准备好你所选 AI 模型提供商的 API Key（如 OpenAI, Claude, Kimi, Qwen 等）

📦 安装步骤

你可以通过 npm 全局安装或直接使用 npx 运行，无需复杂配置。

方式一：全局安装（推荐）

适合频繁使用的开发者，安装后可在任何目录直接使用 hyperchat 命令。

npm install -g @dadigua/hyperchat

方式二：临时运行

适合快速体验或不想全局安装的用户。

npx -y @dadigua/hyperchat

🚀 基本使用

1. 配置环境变量

在使用前，需设置默认的 AI 模型信息。你可以选择临时导出或在项目中创建 .env 文件。

临时配置（当前终端会话有效）：

export HyperChat_API_KEY=your-api-key           # 替换为你的 API 密钥
export HyperChat_API_URL=your-api-url           # 替换为 API 端点（如有）
export HyperChat_AI_Provider=openai             # 提供商：openai/claude/kimi/qwen 等
export HyperChat_AI_Model=gpt-4o                # 模型名称

永久配置（项目级）： 在项目根目录创建 .env 文件，写入上述变量。HyperChat 会自动读取。

2. 快速对话 (CLI 模式)

配置完成后，即可直接在命令行与 AI 交互。

简单问答：

hyperchat "你好，世界！"

交互式聊天：

hyperchat chat

智能文件分析（支持多文件引用）： 使用 @ 符号直接引用本地文件，AI 将基于文件内容回答。

hyperchat "分析 @./src/index.ts 的代码质量"
hyperchat "对比 @./package.json 和 @./yarn.lock 的差异"

3. 启动 Web 协作界面

适合项目管理、多工作区切换及团队协作场景。

hyperchat serve

启动后访问：http://localhost:16100

• 功能亮点：多标签页管理不同项目、可视化配置 MCP 工具、实时监控对话状态。

4. 使用自定义 Agent 命令 ✨

HyperChat 支持通过 Markdown 模板定义快捷命令（如 /bug-fix, /review）。

# 使用预设命令修复 Bug
hyperchat agent coder "/bug-fix @./src/login.ts 登录功能异常"

# 代码审查
hyperchat agent coder "/review @./src/api/user.js"

提示：更多高级用法（如创建专属 Agent、配置 MCP 工具链）请参考完整文档或通过 hyperchat --help 查看。