hyperchat/packages/web/README-settings-usage.md

HyperChat 设置系统使用指南

概述

HyperChat 现在具备了完整的双层设置系统：

🏢 应用设置 (App Settings)

• 范围: 全局软件设置
• 影响: 整个应用的行为和外观
• 访问: 点击工作区界面右上角的"应用设置"按钮
• 存储: AppData/app-settings.jsonc

🏗️ 工作区设置 (Workspace Settings)

• 范围: 特定工作区设置
• 影响: 仅影响该工作区
• 访问: 工作区标签下拉菜单 → "工作区设置"
• 存储: 工作区/.hyperchat/settings.jsonc

使用方法

应用设置

1. 打开设置

   • 点击工作区界面右上角的"应用设置"按钮
   • 或者使用快捷键 (如果有配置)

2. 设置分类

   • 外观: 主题、字体、语言、关闭行为
   • 网络: 代理、同步、WebDAV 配置
   • 系统: 密码、任务、窗口尺寸
   • 开发者: 调试、遥测、实验功能

3. 操作功能

   • 保存: 保存当前更改
   • 重置: 恢复默认设置
   • 导出: 导出为 JSON 文件
   • 导入: 从 JSON 文件导入

工作区设置

1. 打开设置

   • 右键点击工作区标签 → "工作区设置"
   • 或点击工作区标签右侧的三点菜单 → "工作区设置"

2. 设置分类

   • 外观: 夜间模式、主题、字体、语言
   • 编辑器: 自动保存、换行、Tab 大小
   • AI: 默认模型、Agent、参数配置
   • 高级: 遥测、调试、实验功能

3. 操作功能

   • 保存: 保存当前更改
   • 重置: 恢复默认设置
   • 导出: 导出工作区设置
   • 导入: 导入工作区设置

实际使用场景

场景一：个人使用

1. 在应用设置中配置全局偏好（主题、语言等）
2. 在不同工作区中设置项目特定的 AI 模型和参数
3. 为不同项目配置不同的编辑器设置

场景二：团队协作

1. 导出工作区设置并分享给团队成员
2. 团队成员导入相同的工作区设置保持一致性
3. 个人在应用设置中保持个人偏好

场景三：多环境使用

1. 开发环境：启用调试模式和实验功能
2. 生产环境：关闭调试模式，使用稳定设置
3. 演示环境：使用较大字体和明亮主题

设置优先级

1. 工作区设置 > 应用设置 > 系统默认
2. 工作区设置会覆盖应用设置中的同名项
3. 应用设置会覆盖系统默认值

故障排除

设置不生效

1. 检查是否点击了"保存"按钮
2. 确认设置层级（工作区 vs 应用）
3. 重启应用使某些设置生效

设置丢失

1. 检查设置文件是否存在
2. 查看日志中的错误信息
3. 尝试重置设置并重新配置

导入失败

1. 检查 JSON 文件格式是否正确
2. 确认文件编码为 UTF-8
3. 验证设置结构是否与当前版本兼容

技术细节

文件格式

• 使用 JSONC 格式，支持注释
• 自动生成 JSON Schema 文件
• 支持编辑器智能提示

验证机制

• 使用 Zod 进行运行时验证
• 类型安全的 TypeScript 支持
• 错误处理和用户友好的提示

性能考虑

• 设置修改后立即保存
• 懒加载设置界面
• 最小化不必要的重新渲染

常见配置示例

夜间模式开发者设置

{
  "appearance": {
    "darkTheme": true,
    "theme": "dark",
    "fontSize": "medium"
  },
  "developer": {
    "enableDebugMode": true,
    "experimentalFeatures": true
  }
}

团队协作工作区设置

{
  "ai": {
    "defaultModel": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 4000
  },
  "editor": {
    "autoSave": true,
    "tabSize": 2
  }
}

这样的设置系统为 HyperChat 提供了极高的灵活性和可定制性，满足不同用户和使用场景的需求。