### Local Development Setup

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Commands to set up the HyperChat project locally. Includes cloning the repository, installing dependencies for the main project and sub-packages, and starting the development server.

```bash
# 克隆项目
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
```

--------------------------------

### HyperChat Usage Examples

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Demonstrates various methods for configuring and running HyperChat, including default model configuration, web service setup, .env file usage, CLI parameters, and global configuration.

```bash
# 方式1：快速配置默认模型
export HyperChat_API_KEY=sk-1234567890
export HyperChat_AI_Provider=openai
export HyperChat_AI_Model=gpt-4o
hyperchat "你好"                            # 直接使用默认配置
```

```bash
# 方式2：Web 服务配置
export HYPERCHAT_WEB_PASSWORD=mypassword
hyperchat serve
```

```bash
# 方式3：项目 .env 文件
echo "HyperChat_API_KEY=your-key" > .env
echo "HyperChat_AI_Provider=claude" >> .env
hyperchat chat
```

```bash
# 方式4：CLI 参数（最高优先级）
hyperchat serve --password=clipass
```

```bash
# 方式5：全局配置文件
echo "HyperChat_API_KEY=global-key" > ~/Documents/HyperChat/.env
echo "HyperChat_AI_Provider=gemini" >> ~/Documents/HyperChat/.env
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Examples of how to use the HyperChat CLI for various tasks, including direct AI chat, starting the web server, listing agents, and interacting with specific agents.

```bash
# 直接运行
node packages/core/dist/cli/index.mjs --help

# 安装后使用 (如果全局安装core包)
hyperchat --help
hc workspace current

# 常用命令
hyperchat chat                  # 直接AI对话
hyperchat "你好"                    # 直接AI对话
hyperchat serve                   # 启动Web服务器 (包含 Web 界面)
hyperchat agent list              # 列出AI代理
hyperchat agent [agent_name] "你好"          # 使用某个agent直接AI对话
hyperchat agent [agent_name] chat          # 使用某个agent进行对话
```

--------------------------------

### Running TaskQueue Examples

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/core/src/utils/taskQueue.README.md

Command to run the example scripts for the TaskQueue implementation using tsx.

```bash
npx tsx src/utils/taskQueue.example.mts
```

--------------------------------

### MCP Tool Example: write_file

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

TypeScript example demonstrating the `write_file` MCP tool. It shows how to write content to a specified file path, with an option to automatically create parent directories if they don't exist.

```typescript
// MCP 工具调用示例
const result = await agentInstance.callTool(
  "hyper_system",
  "write_file",
  {
    reason: "创建新的配置文件",
    absolute_path: "/path/to/project/config/settings.json",
    content: JSON.stringify({
      debug: true,
      port: 3000,
      database: "mongodb://localhost:27017/myapp"
    }, null, 2),
    create_directories: true  // 自动创建不存在的父目录
  }
);

// 返回结果
// {
//   content: [{ type: "text", text: "Successfully created file: /path/to/project/config/settings.json" }],
//   summary: "Created file: /path/to/project/config/settings.json (156 bytes, 6 lines)"
// }
```

--------------------------------

### Workspace Initialization Scenarios

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Demonstrates different ways to initialize and start a workspace based on the required level of service, from quick configuration checks to full service startup.

```typescript
// 🚀 场景 1: 快速查询（只需配置）
await workspaceManager.initialize();           // agent list, task list
const agents = workspace.getAgents();

// 🔥 场景 2: 完整服务（需要网络连接）  
await workspaceManager.initialize();           // hyperchat run
await workspaceManager.start();                // task trigger, MCP 调用

// 🔧 场景 3: 向后兼容（一步完成）
await workspaceManager.init();                 // 现有代码迁移

```

--------------------------------

### Start Web Server

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Starts the HyperChat web server, which includes the web interface. This command is used to access the application through a browser.

```bash
hyperchat serve
```

--------------------------------

### MCP Tool Example: read_file

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

TypeScript example demonstrating how to use the `read_file` MCP tool via an agent instance. It shows how to specify the file path, optional line offsets, and limits to read file content.

```typescript
// MCP 工具调用示例
const result = await agentInstance.callTool(
  "hyper_system",        // MCP 服务器名称
  "read_file",           // 工具名称
  {
    reason: "读取配置文件以分析项目结构",
    absolute_path: "/path/to/project/package.json",
    offset: 0,           // 可选：起始行号（0-based）
    limit: 100           // 可选：读取的最大行数
  }
);

// 返回结果
// {
//   content: [{ type: "text", text: "文件内容..." }],
//   summary: "Read file: /path/to/project/package.json (1234 bytes)"
// }
```

--------------------------------

### Install HyperChat CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Install the HyperChat CLI globally using npm or run it directly with npx.

```bash
# 全局安装
npm install -g @dadigua/hyperchat

# 或直接运行
npx -y @dadigua/hyperchat
```

--------------------------------

### Run CLI After Global Installation

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Executes the CLI tool using its globally installed command name. This assumes the 'core' package has been installed globally.

```bash
hyperchat --help
```

```bash
hc workspace current
```

--------------------------------

### Install HyperChat CLI Globally

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

Install the HyperChat CLI tool globally for command-line AI interaction. Alternatively, use npx to run it directly without installation. Configure environment variables for API key, URL, provider, and model.

```bash
# 全局安装
npm install -g @dadigua/hyperchat

# 或直接运行（无需安装）
npx -y @dadigua/hyperchat

# 配置环境变量
export HyperChat_API_KEY=your-api-key
export HyperChat_API_URL=https://api.openai.com/v1
export HyperChat_AI_Provider=openai
export HyperChat_AI_Model=gpt-4o
```

--------------------------------

### Workspace Initialization Scenarios (TypeScript)

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Demonstrates different ways to initialize and start a workspace using the WorkspaceManager in TypeScript. These scenarios cater to varying needs, from quick configuration checks to full service startup.

```typescript
// 🚀 场景 1: 快速查询（只需配置）
await workspaceManager.initialize();           // agent list
const agents = workspace.getAgents();

// 🔥 场景 2: 完整服务（需要网络连接）  
await workspaceManager.initialize();           // hyperchat serve
await workspaceManager.start();                // MCP 调用

// 🔧 场景 3: 向后兼容（一步完成）
await workspaceManager.init();                 // 现有代码迁移

```

--------------------------------

### Start Core Service

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Starts the core backend service without the web interface. This is suitable for running HyperChat in the background or as a headless service.

```bash
hyperchat run
```

--------------------------------

### Development Mode for Core Backend and CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Starts the core backend service and CLI in development mode. This allows for rapid backend development and testing.

```bash
npm run dev:core
```

--------------------------------

### Add stdio MCP Server

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/docs/guide/mcp.md

Configure the 'command' and 'args' to install the MCP server for stdio type. Ensure the AMAP_MAPS_API_KEY environment variable is set.

```json
{
      "command": "npx",
      "args": [
        "-y",
        "@amap/amap-maps-mcp-server"
      ],
      "env": {
        "AMAP_MAPS_API_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxx"
      },
}
```

--------------------------------

### Example of Dual Mode Collaboration

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Illustrates how to use HyperChat in different scenarios, such as development with the Web UI and CI/CD automation with the CLI.

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

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

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

--------------------------------

### Start Chat Session with Agent

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Starts an interactive chat session with a specified AI agent. This allows for a back-and-forth conversation with the agent.

```bash
hyperchat agent [agent_name] chat
```

--------------------------------

### Start HyperChat Web Multi-Workspace Mode

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Launch the HyperChat web interface for multi-workspace collaboration. Access it at http://localhost:16100.

```bash
# 启动多工作区 Web 界面
hyperchat serve                        # 访问: http://localhost:16100

# Web 界面功能特色：
# ✅ 多工作区标签页管理
# ✅ 每个标签页独立的 Agent 集合、MCP 服务、聊天记录
# ✅ 可视化配置和实时监控
# ✅ 团队协作和项目管理
```

--------------------------------

### Agent Configuration (agent.yaml)

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

An example agent configuration file ('agent.yaml') for a personal coding assistant. It specifies the agent's name, description, model, confirmation settings, allowed MCPs, and a detailed prompt.

```yaml
# ~/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"]
```

--------------------------------

### Development Mode for Shared Package

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Starts the shared package in development mode with watch capabilities. Changes in this package will trigger automatic rebuilding.

```bash
npm run dev:shared
```

--------------------------------

### MCP Server Configuration

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

JSON configuration for MCP (Model Context Protocol) servers. This example shows how to set up different server types (stdio, sse, streamableHttp) with their respective commands, arguments, and environment variables.

```json
// .hyperchat/mcp.json
{
  "mcpServers": {
    "amap-maps": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your-amap-api-key"
      }
    },
    "custom-api": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    },
    "http-server": {
      "type": "streamableHttp",
      "url": "http://localhost:3002/mcp"
    }
  }
}
```

--------------------------------

### DirectoryPicker Component Usage

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/web/src/components/DirectoryPicker.md

Basic and advanced usage examples for the DirectoryPicker component, including form integration and custom styling.

```APIDOC
## DirectoryPicker Component Usage

### Basic Usage

This example demonstrates the fundamental way to use the `DirectoryPicker` component.

```tsx
import { DirectoryPicker } from "../../components/DirectoryPicker";

function MyComponent() {
  const handleDirectorySelect = (path: string, handle?: FileSystemDirectoryHandle) => {
    console.log("Selected directory:", path);
    if (handle) {
      console.log("Directory handle:", handle);
    }
  };

  return (
    <DirectoryPicker onDirectorySelect={handleDirectorySelect}>
      Select Project Directory
    </DirectoryPicker>
  );
}
```

### Form Integration

Integrate `DirectoryPicker` with Ant Design forms to easily capture directory paths.

```tsx
import { Form, Input } from "antd";
import { DirectoryPicker } from "../../components/DirectoryPicker";

function WorkspaceForm() {
  const [form] = Form.useForm();

  const handleDirectorySelect = (path: string) => {
    form.setFieldsValue({ workspacePath: path });
  };

  return (
    <Form form={form}>
      <Form.Item name="workspacePath" label="Workspace Path">
        <Input.Group compact>
          <Input style={{ width: "calc(100% - 100px)" }} readOnly />
          <DirectoryPicker onDirectorySelect={handleDirectorySelect}>
            Select Directory
          </DirectoryPicker>
        </Input.Group>
      </Form.Item>
    </Form>
  );
}
```

### Custom Styling

Customize the appearance of the `DirectoryPicker` button using Ant Design props and CSS classes.

```tsx
<DirectoryPicker
  type="primary"
  size="large"
  onDirectorySelect={handleDirectorySelect}
  className="my-custom-class"
  showTooltip={false}
>
  <FolderOpenOutlined /> Select Working Directory
</DirectoryPicker>
```
```

--------------------------------

### Run CLI Directly

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Executes the CLI tool directly using Node.js. This is useful for testing the CLI without installing it globally.

```bash
node packages/core/dist/cli/index.mjs --help
```

--------------------------------

### Create and Manage Agent Instances with AgentInstance API

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

Use the AgentInstance API to create, initialize, configure, and manage agent instances. This includes starting and stopping MCP clients, calling tools, and handling chat logs.

```typescript
import { AgentInstance, Workspace } from '@dadigua/hyperchat';

// 创建 Agent
const agentConfig = {
  name: 'code-assistant',
  prompt: '你是一个专业的代码助手',
  description: '代码审查和优化专家',
  allowMCPs: ['hyper_system', 'git'],
  isConfirmCallTool: false,
  temperature: 0.7,
  maxTokens: 4000,
  tags: ['coding', 'review']
};

const agent = await AgentInstance.createAgent(
  '/path/to/.hyperchat/agents/code-assistant',
  agentConfig
);

// 初始化 Agent（延迟初始化）
await agent.init();

// 获取 Agent 配置
const config = agent.getConfig();

// 更新配置
await agent.updateConfig({
  temperature: 0.8,
  maxTokens: 8000
});

// 启动 MCP 客户端
await agent.startMCPClients();

// 获取可用的 MCP 工具
const { allowedMCPsCount, availableTools } = agent.getMCPTools();
console.log(`Available tools: ${availableTools.length}`);

// 调用 MCP 工具
const result = await agent.callTool(
  'hyper_system',
  'read_file',
  { absolute_path: '/path/to/file.txt', reason: '读取文件' }
);

// 管理聊天记录
await agent.setChatLog({
  key: 'chat-001',
  label: '代码审查对话',
  messages: [...],
  agentName: 'code-assistant',
  dateTime: Date.now(),
  chatType: 'user'
});

const chatLogs = await agent.getChatLogs(10);
const chatLog = await agent.getChatLog('chat-001');

// 执行自定义命令
const expandedContent = await agent.executeCommand('review', '@./src/api.ts');

// 停止 MCP 客户端
await agent.stopMCPClients();
```

--------------------------------

### Create Web Frontend Management Component in TypeScript

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Example of creating a management component for the Web frontend that supports full UI operations and integrates into the workspace panel system. Handles frontend-backend data synchronization.

```typescript
// packages/web/src/components/FeatureManagement.tsx
// packages/web/src/pages/workspace/types.ts
```

--------------------------------

### Build All Packages

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Use this command to build all packages in the project, respecting their dependencies. This is typically done before deploying or running the application.

```bash
npm run build
```

--------------------------------

### Managing Personal Agents Across Projects

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Illustrates how to create and deploy personal agents using HyperChat CLI, and how these agents can be used across different projects, automatically managing their context and memory.

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

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

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

--------------------------------

### Manage Workspaces with WorkspaceManager API

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

Utilize the WorkspaceManager API to initialize, get, and manage different project workspaces. This includes retrieving agent summaries, getting specific agent instances, and creating or deleting agents within a workspace.

```typescript
import { workspaceManager, getWorkspaceManager } from '@dadigua/hyperchat';

// 初始化工作区（基于当前工作目录）
const workspace = await workspaceManager.initialize(process.cwd());

// 获取当前工作区
const currentWorkspace = workspaceManager.getCurrentWorkspace();

// 获取或创建指定路径的工作区
const projectWorkspace = await workspaceManager.get('/path/to/project', true);

// 确保工作区已初始化
if (!projectWorkspace.isInitialized()) {
  await projectWorkspace.initialize();
}

// 获取工作区中的所有 Agent
const agents = await currentWorkspace.getAllAgentsSummary();
agents.forEach(agent => {
  console.log(`Agent: ${agent.config.name}`);
  console.log(`  Description: ${agent.config.description}`);
  console.log(`  Chat logs: ${agent.chatLogsCount}`);
});

// 获取特定 Agent 实例
const agentInstance = currentWorkspace.getAgentInstance('Hyper');

// 创建新 Agent
const newAgent = await currentWorkspace.createAgent({
  name: 'my-assistant',
  prompt: '你是我的个人助手',
  allowMCPs: ['hyper_system']
});

// 删除 Agent
await currentWorkspace.deleteAgent('my-assistant');

// 获取工作区 MCP 管理器
const mcpManager = currentWorkspace.getMcpManager();
```

--------------------------------

### Version Control for Project AI Configuration

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Demonstrates using Git to manage and version AI configurations within a project's .hyperchat directory, including adding, committing, pushing, and rolling back changes.

```bash
# 📁 项目级 AI 配置版本管理
git add .hyperchat/agents/project-assistant/
git commit -m "添加项目专用 AI 助手"
git push origin feature/project-ai
```

```bash
# 👥 团队 AI 最佳实践分享
git clone https://github.com/team/ai-workspace-templates.git
cp -r ai-workspace-templates/react-fullstack/.hyperchat ./
```

```bash
# 🔄 项目 AI 配置回滚
git checkout HEAD~1 -- .hyperchat/
```

--------------------------------

### Basic DirectoryPicker Usage

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/web/src/components/DirectoryPicker.md

Demonstrates how to use the DirectoryPicker component to select a directory and log the path and handle. Ensure the component is correctly imported.

```tsx
import { DirectoryPicker } from "../../components/DirectoryPicker";

function MyComponent() {
  const handleDirectorySelect = (path: string, handle?: FileSystemDirectoryHandle) => {
    console.log("选择的目录:", path);
    if (handle) {
      console.log("目录句柄:", handle);
    }
  };

  return (
    <DirectoryPicker onDirectorySelect={handleDirectorySelect}>
      选择项目目录
    </DirectoryPicker>
  );
}
```

--------------------------------

### Development Mode for Web Frontend

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Launches the development server for the web frontend. This provides hot-reloading and other development-specific features for faster UI iteration.

```bash
npm run dev:web
```

--------------------------------

### Define Feature Schema with Zod

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Example of defining a feature schema using Zod for data structure and validation, ensuring type consistency between frontend and backend.

```typescript
// packages/shared/src/zodSchemas/featureSchema.mts
export const FeatureSchema = z.object({
  // 定义数据结构
  // 包含验证规则、默认值、类型导出
});

```

--------------------------------

### Define Feature Schema with Zod in TypeScript

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Example of defining a feature schema using Zod in TypeScript for data structure definition, validation, and type export. Ensures consistency between frontend and backend.

```typescript
// packages/shared/src/zodSchemas/featureSchema.mts
export const FeatureSchema = z.object({
  // 定义数据结构
  // 包含验证规则、默认值、类型导出
});
```

--------------------------------

### 目标架构目录结构

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/AGENT_CENTRIC_PLAN.md

展示了改造后Agent中心架构的文件和目录组织方式，每个Agent拥有独立的MCP和任务配置。

```bash
.hyperchat/
└── agents/               # 工作区 = Agent发现路径
    ├── agent1/
    │   ├── agent.yaml    # Agent配置
    │   ├── memory.md     # Agent记忆
    │   ├── chatlogs/     # 聊天记录
    │   ├── mcp.json      # Agent专属MCP配置 (新增)
    │   └── tasks/        # Agent专属任务 (新增)
    │       ├── task1.yaml
    │       └── task2.yaml
    └── agent2/
        └── ...

```

--------------------------------

### TaskQueue Control Operations

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/core/src/utils/taskQueue.README.md

Provides examples of controlling the TaskQueue's state, including pausing, resuming, clearing, draining, and stopping the queue. These operations allow for dynamic management of task execution.

```typescript
const queue = new TaskQueue({ concurrency: 1 });

// 暂停队列
queue.pause();

// 恢复队列
queue.resume();

// 清空队列（不影响正在运行的任务）
queue.clear();

// 等待所有任务完成
await queue.drain();

// 停止队列并清理所有任务
await queue.stop();
```

--------------------------------

### Manage Agents and Workspaces via CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Create, delete, and manage Agents and Workspaces directly from the command line interface.

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

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

--------------------------------

### Custom Agent Commands with Markdown Templates

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Define and use custom commands for Agents using Markdown templates for quick input of professional prompts.

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

--------------------------------

### Manage MCP Servers with MCPManager API

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

The MCPManager API allows for the management of MCP server connections, including starting and stopping clients, adding new server configurations, and restarting or disabling/enabling clients.

```typescript
import { MCPManager } from '@dadigua/hyperchat';

// 创建 MCP 管理器
const mcpManager = new MCPManager('/path/to/.hyperchat', {
  enableLogging: true,
  allowMCPs: ['hyper_system', 'custom-server']
});

// 启动所有配置的 MCP 客户端
const clients = await mcpManager.startClients();
console.log(`Started ${clients.length} MCP clients`);

// 获取所有客户端
const allClients = mcpManager.getAllClients();
allClients.forEach(client => {
  console.log(`${client.serverName}: ${client.status}`);
  console.log(`  Tools: ${client.tools.map(t => t.name).join(', ')}`);
});

// 获取特定客户端
const client = mcpManager.getClient('hyper_system');

// 添加新的 MCP 服务器配置
await mcpManager.setServerConfig('new-server', {
  type: 'stdio',
  command: 'node',
  args: ['./my-mcp-server.js']
});

// 重启客户端
await mcpManager.restartClient('new-server');

// 禁用/启用客户端
await mcpManager.disableClient('new-server');
await mcpManager.enableClient('new-server');

// 删除服务器配置
await mcpManager.deleteServerConfig('new-server');

// 强制重新加载配置
await mcpManager.forceReloadWorkspaceConfig();

// 停止所有客户端
await mcpManager.stopClients();

// 销毁管理器
await mcpManager.destroy();
```

--------------------------------

### Basic HyperChat CLI Commands

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

Interact with HyperChat via the command line. You can send direct messages, enter interactive chat mode, start the web service with a UI, or view help information.

```bash
# 直接聊天
hyperchat "你好，今天怎么样？"

# 交互式聊天模式
hyperchat chat

# 启动 Web 服务（包含 Web UI）
hyperchat serve

# 查看帮助
hyperchat --help
```

--------------------------------

### Global Options and Workspace Specification

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Use global options like `--workspace` to specify a working directory or `--verbose` for detailed logging.

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

--------------------------------

### Project Workspace Structure

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

This structure illustrates the organization of a project workspace within HyperChat, located under the /projects/ directory. It includes project-specific configurations like ai_models.json and agent setups, mirroring some global configurations.

```directory
/projects/
    project1/
      .hyperchat/
      ├── mcp.json                  // 全局主控程序 (MCP) 配置文件
      ├── ai_models.json            // AI 模型配置文件，包含所有可用的 AI 模型信息
      ├── agents/
      │   ├── agent1-name/
      │   │   ├── memory.md         # Agent记忆
      │   │   ├── sub_agents/       # 子代理文件夹（类似 agents 文件夹）
      │   │   ├── agent.yaml        # Agent配置
      │   │   └── chatlogs/         # 聊天记录文件夹
      │   │       ├── chat1.yaml
      │   │       ├── chat2.yaml
      │   │       └── ...
      │   └── ...
      └── ...

```

--------------------------------

### Build Web Frontend

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Builds the React-based web frontend for HyperChat. This package provides the browser-accessible interface.

```bash
npm run build:web
```

--------------------------------

### Build Electron Application

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Builds the Electron desktop application. This package bundles the web frontend and core backend into a standalone desktop application.

```bash
npm run build:electron
```

--------------------------------

### Configure HyperChat with Environment Variables

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

HyperChat uses a 5-tier environment variable system for configuration, ranging from default values to CLI arguments. This example shows common environment variables for AI model, service, and interface settings.

```bash
# AI 模型配置（快速配置）
HyperChat_API_KEY=your-api-key              # API 密钥
HyperChat_API_URL=https://api.openai.com/v1 # API 端点
HyperChat_AI_Provider=openai                # AI 提供商 (openai/claude/gemini/kimi/qwen)
HyperChat_AI_Model=gpt-4o                   # 默认模型名称

# 服务配置
HYPERCHAT_WEB_PASSWORD=your-web-password    # Web 界面访问密码
HYPERCHAT_PORT=16100                        # Web 服务端口
HYPERCHAT_HOST=localhost                    # 服务绑定地址

# 界面配置
HYPERCHAT_LANGUAGE=zh                       # 界面语言 (zh/en/ja/ko/fr/de)
HYPERCHAT_LOG_LEVEL=info                    # 日志级别

# 自定义 API 端点
HYPERCHAT_OPENAI_BASE_URL=https://api.openai.com/v1
HYPERCHAT_CLAUDE_BASE_URL=https://api.anthropic.com

# 项目级配置文件示例 (.env)
# ~/Documents/HyperChat/.env (全局)
# /path/to/project/.env (工作区)
```

--------------------------------

### Integrate Backend Logic into Workspace and Commands in TypeScript

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Shows how to integrate backend logic into the workspace system and create corresponding command modules. Ensures proper integration with the unified Command system.

```typescript
// packages/core/src/workspace/workspace.mts
// packages/core/src/commands/featureCommands.mts
```

--------------------------------

### Implement CLI Frontend Commands in TypeScript

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Demonstrates the implementation of rich command-line interfaces for the CLI frontend, integrating into the main CLI system with parameter parsing and error handling.

```typescript
// packages/core/src/cli/commands/feature.mts
// packages/core/src/cli/index.mts
```

--------------------------------

### Agent Custom Command Template: Code Review

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

A Markdown template for a custom 'review' command within an Agent. It guides the AI to perform a comprehensive code review, focusing on quality, performance, security, best practices, and improvement suggestions.

```markdown
# .hyperchat/agents/project-assistant/commands/review.md
请对以下代码进行全面的code review：

$ARG

Review要点：
1. **代码质量**：可读性、维护性、命名规范
2. **性能问题**：算法效率、内存使用、潜在瓶颈
3. **安全隐患**：输入验证、权限控制、数据泄露风险
4. **最佳实践**：设计模式、架构原则、团队规范
5. **改进建议**：具体的优化方案和替代实现
```

--------------------------------

### Using Custom Commands via CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Demonstrates how to invoke custom agent commands like 'bug-fix' and 'review' using the HyperChat CLI. Shows the command syntax and the expected AI input based on the command template.

```bash
# 使用自定义命令进行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
```

--------------------------------

### Build Core Backend and CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/GEMINI.md

Builds the Node.js backend service and the Command Line Interface (CLI) tool. This is essential for server-side operations and command-line interactions.

```bash
npm run build:core
```

--------------------------------

### Create and Manage HyperChat Workspace

Source: https://context7.com/bigsweetpotatostudio/hyperchat/llms.txt

Commands for initializing and managing HyperChat workspaces within a project directory. This includes creating a new workspace, listing existing ones, and checking the current workspace status.

```bash
# 在当前目录创建工作区
hyperchat workspace create

# 显示所有工作区信息
hyperchat workspace list

# 显示当前工作目录和工作区状态
hyperchat workspace current
```

--------------------------------

### Backend Usage of Core Module

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/core/src/README-structure.md

Illustrates how to use the AppSettingsManager from the core Node.js module for backend operations. This includes initialization and updating application settings.

```typescript
import { AppSettingsManager } from '../data/appSettingsManager.mjs';
import { AppSettingsSchema } from '../shared/appSettingsSchema.mjs';

// 创建管理器实例
const manager = new AppSettingsManager('/path/to/appdata');
await manager.init();

// 使用管理器操作设置
const settings = manager.getSettings();
await manager.updateSettings({ appearance: { darkTheme: true } });
```

--------------------------------

### Web vs. CLI MCP Client Access in TypeScript

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/CLAUDE.md

Demonstrates how to access MCP clients differently for Web (workspace-level) and CLI (agent-priority) contexts. Use workspace.getMcpManager() for Web and agent.getMCPClient() for CLI.

```typescript
// 🌐 Web端：工作区级别MCP管理
const mcpManager = workspace.getMcpManager();
const client = mcpManager.getClient(clientName);

// 💻 CLI端：Agent优先MCP访问
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);
```

--------------------------------

### Smart File Handling with Multi-@ Syntax

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Utilize the multi-@ symbol syntax for intelligent file referencing in commands, supporting complex file operations.

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

--------------------------------

### Interact with a Specific Agent via CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Directly launch a specific Agent (e.g., 'mybot') and initiate a conversation or command execution.

```bash
hyperchat agent mybot "你好"           # 🎯 直接启动 Agent，按需加载 MCP
hyperchat agent mybot chat             # 🎯 Agent 专属对话会话
```

--------------------------------

### List Available Agents with HyperChat CLI

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Discover available Agents, including global and workspace-specific ones, using the `agent list` command.

```bash
hyperchat agent list                   # 发现可用 Agent（全局 + 工作区）
```

--------------------------------

### Agent Basic Configuration

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Defines the basic configuration for an agent, including its name, description, model key, confirmation settings, allowed MCPs, and a detailed prompt.

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

--------------------------------

### Configure Custom API Endpoints for HyperChat

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/README.md

Set environment variables to define custom base URLs for AI providers like OpenAI and Anthropic.

```bash
HYPERCHAT_OPENAI_BASE_URL=https://api.openai.com/v1
HYPERCHAT_CLAUDE_BASE_URL=https://api.anthropic.com
```

--------------------------------

### 当前架构目录结构

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/AGENT_CENTRIC_PLAN.md

展示了HyperChat当前的工作区中心架构下的文件和目录组织方式。

```bash
.hyperchat/
├── mcp.json              # 工作区级MCP配置
├── tasks/                # 工作区级任务
│   ├── task1.yaml
│   └── task2.yaml
└── agents/               # Agent集合
    ├── agent1/
    │   ├── agent.yaml
    │   ├── memory.md
    │   └── chatlogs/
    └── agent2/
        └── ...

```

--------------------------------

### Basic TaskQueue Usage (Sequential Execution)

Source: https://github.com/bigsweetpotatostudio/hyperchat/blob/dev2/packages/core/src/utils/taskQueue.README.md

Demonstrates the basic usage of TaskQueue for sequential task execution by setting concurrency to 1. Imports the TaskQueue class and adds a single asynchronous task.

```typescript
import { TaskQueue } from './taskQueue.mjs';

// 创建一个顺序执行的队列（并发数为1）
const queue = new TaskQueue({ concurrency: 1 });

// 添加任务
const result = await queue.add(async () => {
    console.log('执行任务');
    await new Promise(resolve => setTimeout(resolve, 1000));
    return '任务结果';
});

console.log(result); // '任务结果'
```