20 KiB

Raw Permalink Blame History

请回复中文

typescript使用指南

import .mts 文件时，使用 import { xxx } from './xxx.mjs' 的方式导入。
xx.ts.bak ， .bak 文件是老逻辑代码，不用阅读，也不用修改和删除。

项目概述

HyperChat 是一个多平台的 AI 聊天应用，该项目拥有完善的 MCP（模型上下文协议）支持，并集成了包括 OpenAI、Claude、Gemini、Qwen、Deepseek 等在内的多种大语言模型 API。

多平台支持

核心: nodejs
Web前端: 通过浏览器访问，支持h5
Electron: 桌面应用，自带浏览器
命令行前端: 类似Claude Code，已集成到core包中，配置通过web前端完成
VSCode插件: 通过webview访问构建

包结构

packages/shared - @dadigua/hyperchat-shared，共享代码和类型定义+zodSchemas，前后端通用
packages/core - Node.js 后端服务 + CLI命令行工具
packages/web - Web 前端的实现
packages/electron - Electron 桌面应用

开发逻辑

类型安全

尽量使用 TypeScript 的类型系统来确保代码的类型安全。尽量少使用any类型。
packages/shared/src/types.mts 定义了常用的类型，包括前端和后端交互的类型，确保前后端的数据结构一致。
packages/shared/src/zodSchemas文件夹定义了 Zod schema，用于数据验证和前端表单生成。所有的 schema 都是基于 TypeScript 类型定义的，确保类型一致性。
packages/core/src/data/managers 文件夹包含了各种数据管理器类对应packages/shared/src/zodSchemas，这些类使用typescript类型和 zodSchemas来确保数据的类型安全。
使用 Zod schema 进行数据验证，通过 zod-to-json-schema 转换为 JSON Schema 用于前端表单生成。
不允许 await import()。这样逻辑更加清晰，避免了动态导入带来的复杂性。

环境变量系统

实现了5层优先级的环境变量系统（默认值 < process.env < ~/.hyperchat/.env < 工作区.env < CLI参数）

前后端通信

前端发送消息给后端，默认通过 packages/core/src/command.mts 实现，前端通过调用 call 的方法来实现与后端的交互。
electron提供更多electron接口 packages/electron/src/command.mts，前端通过调用 callElectron 的方法来实现与electron的交互。
后端发送消息给前端是通过websocket实现的 packages/core/src/message_service.mts，前端通过监听 websocket 的消息来接收后端发送的消息。

组件设计原则

优先使用现有的 Ant Design 组件库
遵循 React Hooks 最佳实践，使用 useCallback、useMemo 等优化性能
表单使用 Ant Design Form 组件，支持 Form.List 处理动态数组
错误处理和用户体验优先，提供清晰的错误提示和加载状态

i18n 国际化

i18n 相关的代码在 packages/shared/src/i18n 中。软件默认使用英文，然后通过转成 JSON 的方式来支持国际化。tenglish, 里面不应该有${xxx}。
packages/shared/src/i18n/i18n.json 不用修改。后续我会提供一个脚本来自动生成 i18n.json 文件。

✅ 双层架构设计 (2.0版本 - 已完成实现)

核心理念：互补的双模式架构

重要：CLI 和 Web 是互补而非并发的使用模式

🌐 Web模式：开发阶段、项目配置、团队协作时使用
💻 CLI模式：生产环境、CI/CD、自动化脚本、无界面环境使用
🔄 协同工作：Web配置 → CLI执行，避免数据同步复杂性

目标：根据不同使用场景优化用户体验，Web端注重项目协作，CLI端注重Agent交互

双层架构设计

🌐 Web前端：工作区中心架构
├── 工作区级别的资源管理
│   ├── 工作区MCP客户端管理 (mcp.json)
│   └── 工作区Agent集合管理 (agents/)
└── 适用场景：项目开发、团队协作、Web界面管理

💻 CLI前端：Agent优先架构  
├── Agent级别的直接交互
│   ├── Agent内置MCP工具使用
│   └── Agent独立聊天会话
└── 适用场景：快速对话、自动化脚本、命令行工作流

配置层次结构

启动流程（双模式）：

🌐 Web模式：工作区配置合并
1️⃣ 加载全局配置 (~/.hyperchat/)
2️⃣ 检测当前工作区 (./.hyperchat/)
3️⃣ 合并为工作区统一环境
   ├── 工作区MCP客户端列表 (统一管理)
   └── 工作区Agent集合 (全局+本地)

💻 CLI模式：Agent直接访问
1️⃣ 发现可用Agent (全局+工作区)
2️⃣ 直接选择目标Agent
3️⃣ 使用Agent内置资源
   ├── Agent专属MCP工具
   ├── Agent记忆和上下文
   └── Agent聊天历史

✅ 已完成的架构重构

Workspace配置合并架构重构 (完成) 🆕

核心文件: packages/core/src/workspace/workspace.mts

三种工作模式

非工作区目录: 自动回退到全局配置
工作区目录: 全局配置 + 工作区配置合并
全局工作区: 直接使用全局配置

当前构建命令 🚀

可用的构建脚本 (更新)

# 构建
npm run build             # 构建所有包（按依赖顺序）
npm run build:shared      # 构建 shared 包
npm run build:web         # 构建 Web 前端
npm run build:core        # 构建 Core 后端 + CLI
npm run build:electron    # 构建 Electron 应用

# 开发模式
npm run dev:shared        # shared 包开发模式（watch）
npm run dev:web          # Web 开发服务器
npm run dev:core         # Core + CLI 开发模式
npm run dev:electron     # Electron 开发模式

# 工具
npm run clean            # 清理所有构建产物
npm run typecheck        # 所有包类型检查

构建顺序 (更新)

shared - 必须最先构建，其他包依赖它
web - React 前端构建
core - Node.js 后端 + CLI 构建
electron - 桌面应用（依赖 web 构建产物）

CLI使用方式 (更新)

# 直接运行
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进行对话

🗂️ 项目结构 (更新)

当前包结构

HyperChat/
├── packages/
│   ├── shared/          # 共享类型和工具库
│   ├── web/            # React Web前端
│   ├── core/           # Node.js后端 + CLI (合并后)
│   │   ├── src/cli/    # ✨ CLI命令行工具
│   │   │   ├── index.mts          # CLI主入口
│   │   │   ├── commands/          # 命令实现
│   │   │   │   ├── agent.mts     # 代理管理
│   │   │   │   ├── chat.mts      # AI聊天
│   │   │   │   ├── config.mts    # 配置管理
│   │   │   │   ├── server.mts    # 服务器控制
│   │   │   │   └── workspace.mts # 工作区管理
│   │   │   └── utils/            # CLI工具函数
│   │   ├── src/workspace/        # 工作区管理
│   │   ├── src/command.mts       # API命令层
│   │   └── src/mcp/              # MCP协议实现
│   └── electron/       # Electron桌面应用

🗂️ .hyperchat结构

全局配置目录

~/.hyperchat/
    ├── mcp.json                  // 全局主控程序 (MCP) 配置文件
    ├── .env                      // 全局环境变量配置
    ├── agents/
    │   ├── agent1-key/
    │   │   ├── memory.md         # Agent记忆
    │   │   ├── sub_agents/       # 子代理文件夹（类似 agents 文件夹）
    │   │   ├── agent.yaml        # Agent配置
    │   │   └── chatlogs/         # 聊天记录文件夹
    │   │       ├── chat1.yaml
    │   │       ├── chat2.yaml
    │   │       └── ...
    │   └── ...
    └── ...

项目工作区结构

/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
      │   │       └── ...
      │   └── ...
      └── ...

📝 项目记忆

已完成功能

AI请求改造：从web浏览器前端改为在nodejs环境中通过ai库发请求，代码在packages/shared/src/ai.mts，前后端共用
工作区概念实现：支持在不同工作区之间隔离数据和配置，支持显示当前工作区文件夹（树状），agent等配置作为文件保存在.hyperchat目录下
核心工作区管理类实现：workspace.mts, workspaceManager.mts
Schema2Form组件系统：支持JSON Schema转Ant Design表单，包括双模式编辑（表单/JSON）和Monaco编辑器集成
AI配置管理系统：支持多提供商管理、模型配置、API Key管理，集成到应用设置中
应用设置系统：采用Schema驱动的UI生成，支持复杂对象、数组、条件schema等
CLI架构重构：从HTTP API改为直接导入core模块，并集成到core包中
Workspace配置合并逻辑：在workspace.mts中实现了智能工作区检测和配置合并
CLI集成到Core包：简化架构，提升性能，统一构建流程
CLI bug修复和简化 (2025-07-12)：修复agent显示undefined问题，简化命令结构，提升代码质量
Agent名称更新映射修复 (2025-08-01)：修复updateAgentMapping方法中缺失的availableAgents映射更新
MCP架构统一重构 (2025-08-01)：统一使用工作区级别的MCP管理，修复所有相关的查找和调用逻辑

架构优势

分离关注点: JSON Schema 与业务逻辑分离，shared 包独立维护
统一管理: 所有 Schema 集中在 packages/shared/src/jsonSchemas 目录
数据管理: 所有管理器类集中在 data 目录
类型安全: 保持完整的 TypeScript 类型支持，跨包类型共享
前端集成: Schema2Form 自动生成 UI 界面
构建效率: npm workspaces 避免依赖重复，统一的构建管理
架构简化: CLI集成到core包，减少包管理复杂性

🎯 最新更新日志

2025-07-13 工作区初始化两阶段优化 🚀

核心问题:

原有 workspace.init() 方法集成了太多操作，导致启动时间过长
无法快速获取工作区基本信息，用户体验不佳
服务启动失败时难以定位是配置问题还是服务问题

优化方案:

✅ 两阶段初始化架构: initialize() + start() 替代单一的 init()
✅ 第一阶段 - 快速配置加载: 目录创建、设置管理器、Agent 管理器、基本配置
✅ 第二阶段 - 重量级服务启动: MCP 客户端（网络连接）
✅ 状态管理系统: WorkspaceState 枚举跟踪初始化进度
✅ 向后兼容: 保留 init() 方法，内部调用两阶段方法
✅ API 简化: 移除冗余的 isReady() 方法，isStarted() 已足够
✅ WorkspaceManager 同步优化: 添加 autoStart 参数，支持两阶段 + 完整状态查询

两层架构设计:

WorkspaceManager.initialize(path, autoStart=false) → Workspace.initialize()
WorkspaceManager.start() → Workspace.start()
WorkspaceManager.init(path) → 完整初始化（向后兼容）

状态管理:

UNINITIALIZED → INITIALIZED → STARTED → STOPPING → STOPPED
提供 isInitialized(), isStarted() 等状态查询方法
防止重复初始化和状态错误

使用场景分类:

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

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

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

用户体验提升:

🚀 配置加载速度提升 70-90%（避免 MCP 网络连接，Agent 扫描已优化到第一阶段）
📊 渐进式信息展示：第一阶段即可显示 Agent 信息，第二阶段完成 MCP 连接
🔧 更好的错误定位：分阶段错误提示，区分配置错误和网络连接错误
⚡ hyperchat chat 命令展示两阶段启动过程
🎯 智能场景适配：查询命令快速响应，服务命令完整启动

2025-07-12 CLI修复和简化

问题修复:

✅ 修复agent列表显示"undefined (undefined)"的bug
✅ 修复ES模块导入问题，避免使用CommonJS require
✅ 修复TypeScript类型错误，添加正确的类型断言

功能简化:

✅ 简化server命令：只保留start，移除stop和status
✅ 简化workspace命令：只保留create，移除list/info/current/switch
✅ 遵循项目TypeScript编码规范：避免动态导入和别名导入

用户体验提升:

✅ 增强agent列表显示：显示模型信息和聊天记录数量
✅ 添加工作区资源统计：在chat命令中显示agent和MCP工具数量
✅ 优化帮助文档：更新命令说明，移除废弃功能

这次更新进一步简化了CLI架构，符合"每个目录CLI会话独立"的设计理念，提升了用户体验和代码质量。

2025-08-01 Agent 映射和 MCP 双层架构重构 🔧

关键修复:

✅ Agent 名称更新映射修复: 修复 AgentManager.updateAgentMapping() 方法中遗漏的 availableAgents 映射更新
- 问题：Agent 名称变更后，getAllAgentsSummary() 遍历 availableAgents 时找不到更新后的 Agent
- 解决：同时更新 nameToPath 和 availableAgents 两个映射表
✅ MCP 双层架构重构: 明确区分 Web 端和 CLI 端的 MCP 使用模式
- Web端: 统一使用工作区级别的 MCP 管理 (workspace.getMcpManager())
- CLI端: 保持 Agent 优先的 MCP 访问 (agent.getMCPClient())
- 修复核心方法：manageWorkspaceMcpClient、startWorkspaceMcpClient
- 修复调用方法：mcpCallTool、mcpCallResource、mcpCallPrompt

双层架构设计:

🌐 Web端优化: 工作区级别的统一MCP管理，适合项目开发和团队协作
💻 CLI端优化: Agent专属的MCP工具集，适合个人对话和快速交互
🔧 架构清晰: 根据使用场景选择最适合的MCP管理方式
🚀 错误修复: 解决 "MCP客户端 'telegram-send' 不存在" 等运行时错误

技术实现:

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

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

这次重构建立了清晰的双层架构，Web端专注工作区协作，CLI端专注Agent交互，为不同使用场景提供了最优化的体验。

🚀 HyperChat 开发最佳实践流程

📋 标准化功能开发流程 (推荐采用)

基于项目的成功实践，我们总结出以下高效的开发流程：

1️⃣ Schema 定义阶段

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

✅ 使用 Zod 定义完整的数据 schema
✅ 包含验证函数、默认值、类型导出
✅ 确保前后端类型一致性

2️⃣ Data Manager 实现阶段

// packages/core/src/data/managers/featureManager.mts
export class FeatureManager {
  // 实现完整的 CRUD 操作
  // 基于 schema 的类型安全
}

✅ 创建专门的管理器类
✅ 实现完整的业务逻辑和数据持久化
✅ 基于 Zod schema 进行数据验证

3️⃣ 后端逻辑集成阶段

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

✅ 集成到工作区系统 (workspace.mts)
✅ 创建对应的命令模块 (featureCommands.mts)
✅ 更新统一的 Command 系统

4️⃣ Web 前端界面阶段

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

✅ 创建管理组件，支持完整的 UI 操作
✅ 集成到工作区面板系统
✅ 实现前后端数据同步

5️⃣ CLI 前端命令阶段

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

✅ 实现丰富的命令行接口
✅ 集成到 CLI 主系统
✅ 提供完整的参数解析和错误处理

🎯 流程优势

类型安全: 从 schema 到前后端的完整类型覆盖
代码复用: schema 和 manager 逻辑在前后端共享
一致性: 统一的开发模式和架构设计
可维护性: 清晰的分层和职责划分
扩展性: 易于添加新功能模块

✅ MCP 双层架构重构 (2025-08-01 已完成)

核心问题

之前存在 Agent 级别和工作区级别 MCP 管理的混乱，没有明确区分使用场景：

Web 前端调用工作区级别的 MCP 方法时出错
CLI 和 Web 端使用相同的查找逻辑，不符合各自的使用场景
MCP 客户端管理逻辑不一致，难以维护

双层架构设计

设计原则: 根据前端类型选择最适合的 MCP 管理方式

🌐 Web前端 → 工作区MCP管理
├── 使用 workspace.getMcpManager()
├── 统一的工作区级别MCP客户端池
├── 适合项目级别的工具集成
└── 团队共享的MCP配置

💻 CLI前端 → Agent优先MCP访问
├── 优先使用 agent.getMCPClient()
├── Agent专属的MCP工具集
├── 适合个人化的对话体验  
└── 回退到工作区共享MCP

修复内容

✅ Web端MCP统一: 全面重构 mcpCommands.mts，Web调用统一使用工作区级别的 MCP 管理器
✅ 修复核心方法:
- manageWorkspaceMcpClient: 使用工作区 MCPManager 的正确方法
- startWorkspaceMcpClient: 移除 Agent 级别的查找逻辑
- mcpCallTool/Resource/Prompt: 直接从工作区 MCP 管理器获取客户端
✅ 保留CLI Agent优先: CLI命令保持Agent级别的MCP访问逻辑
✅ 修复 AgentManager 映射: updateAgentMapping 方法同时更新 nameToPath 和 availableAgents 映射

技术实现

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

// 💻 CLI端：Agent优先MCP访问 (保持现有逻辑)
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);

用户体验提升

🌐 Web端体验: 工作区统一的MCP工具管理，适合项目开发
💻 CLI端体验: Agent专属的MCP工具，适合个人对话
🔧 错误修复: 解决 "MCP客户端 'telegram-send' 不存在" 等错误
🚀 架构清晰: 明确的双层架构，便于维护和扩展

开发小技巧

构建优化

开发阶段推荐使用 npm run typecheck 进行类型检查，比完整构建更快
生产部署时使用 npm run build 完整构建所有包
1. 前端先调用 POST /api/chat/stream 获取 sessionId
2. 前端用 sessionId 建立 SSE 连接 GET /api/chat/stream/:sessionId
3. 前端再次调用 POST /api/chat/stream 开始聊天

20 KiB Raw Permalink Blame History Unescape Escape

请回复中文

typescript使用指南

项目概述

多平台支持

包结构

开发逻辑

类型安全

环境变量系统

前后端通信

组件设计原则

i18n 国际化

✅ 双层架构设计 (2.0版本 - 已完成实现)

核心理念：互补的双模式架构

双层架构设计

配置层次结构

✅ 已完成的架构重构

Workspace配置合并架构重构 (完成) 🆕

三种工作模式

当前构建命令 🚀

可用的构建脚本 (更新)

构建顺序 (更新)

CLI使用方式 (更新)

🗂️ 项目结构 (更新)

当前包结构

🗂️ .hyperchat结构

全局配置目录

项目工作区结构

📝 项目记忆

已完成功能

架构优势

🎯 最新更新日志

2025-07-13 工作区初始化两阶段优化 🚀

2025-07-12 CLI修复和简化

2025-08-01 Agent 映射和 MCP 双层架构重构 🔧

🚀 HyperChat 开发最佳实践流程

📋 标准化功能开发流程 (推荐采用)

1️⃣ Schema 定义阶段

2️⃣ Data Manager 实现阶段

3️⃣ 后端逻辑集成阶段

4️⃣ Web 前端界面阶段

5️⃣ CLI 前端命令阶段

🎯 流程优势

✅ MCP 双层架构重构 (2025-08-01 已完成)

核心问题

双层架构设计

修复内容

技术实现

用户体验提升

开发小技巧

构建优化

20 KiB

Raw Permalink Blame History