xoai-frontend 20260401.2

小鸥智能前端web页面

🏠 小鸥智能前端

让智能家居更懂你

---

📖 简介

小鸥智能前端是基于 HAss 深度定制的控制界面。我们致力于为中文用户提供更友好、更智能的控制体验。

🌟 核心特性

• 🇨🇳 原生中文支持 - 默认使用简体中文，无需额外配置
• 🔄 自动更新 - 智能合并上游更新，保留自定义修改
• 🎨 界面优化 - 针对中文用户优化的界面布局和交互
• 🚀 性能提升 - 优化的构建配置，更快的加载速度
• 🔧 易于维护 - 完善的文档和自动化脚本
• 🛡️ 稳定可靠 - 经过严格测试，确保稳定性

---

🎯 为什么选择小鸥智能？

与原版 HAss 的对比

特性	HAss 原版	小鸥智能
默认语言	英文	简体中文
中文翻译	部分缺失	完整翻译
更新方式	手动更新	自动更新
自定义修改	需要手动合并	智能合并
文档支持	英文文档	中文文档
社区支持	国际社区	中文社区

💡 优势

1. 开箱即用 - 无需任何配置，默认就是中文界面
2. 持续更新 - 自动跟踪 HAss 官方更新，获取最新功能
3. 保留定制 - 智能合并策略，保留所有自定义修改
4. 文档完善 - 详细的中文文档和教程
5. 社区支持 - 专注于中文用户的社区支持

---

📚 文档

核心文档

• 📖 项目结构说明 - 了解项目目录结构
• 📘 实际示例教程 - 10 个完整的操作示例
• 📗 模板仓库使用指南 - 完整的使用指南
• 📙 配置文件说明 - merge-rules.json 详细说明
• 📕 自定义修改指南 - 如何添加自定义修改
• 📗 更新流程文档 - 更新流程详解
• 📔 后端修改方案 - Supervisor 修改方案

快速链接

• Home Assistant 官方文档
• Home Assistant 开发者文档
• Home Assistant 论坛
• Home Assistant Discord

---

🛠️ 开发指南

环境要求

• Node.js >= 18
• Yarn >= 1.22
• Git

开发流程

# 1. 克隆仓库
git clone https://github.com/yuanzhou029/xoai-frontend.git
cd xoai-frontend

# 2. 安装依赖
yarn install

# 3. 启动开发服务器
yarn run start

# 4. 访问开发界面
# 打开浏览器访问 http://localhost:5000

构建生产版本

# 1. 应用自定义修改
yarn run apply-custom-changes

# 2. 构建项目
yarn run build

# 3. 输出目录
# hass_frontend/

---

🔄 更新策略

智能合并

小鸥智能使用智能合并策略，确保：

• ✅ 保留自定义修改 - 翻译、组件、配置等自定义内容不会被覆盖
• ✅ 接受上游更新 - 自动获取 HAss 官方的 bug 修复和新功能
• ✅ 减少冲突 - 智能合并算法，最小化手动合并工作

合并规则

配置文件 config/merge-rules.json 定义了详细的合并策略：

{
  "rules": [
    {
      "path": "src/translations/",
      "action": "merge",
      "strategy": "custom-first",
      "description": "翻译文件：自定义优先"
    }
  ]
}

详细说明请参考：配置文件说明

---

🎨 自定义修改

添加自定义翻译

// src/translations/zh-Hans.json
{
  "ui": {
    "custom": {
      "my_feature": {
        "title": "我的功能",
        "description": "功能描述"
      }
    }
  }
}

添加自定义组件

// custom/components/my-component.ts
import { LitElement } from "lit";

export class MyComponent extends LitElement {
  // 你的组件代码
}

详细教程请参考：实际示例教程

---

🤝 贡献

我们欢迎任何形式的贡献！

贡献方式

1. 🐛 报告 Bug - 在 Issues 中报告问题
2. 💡 提出建议 - 在 Issues 中提出新功能建议
3. 🔧 提交代码 - 提交 Pull Request
4. 📖 改进文档 - 完善文档和教程

贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

---

📄 许可证

本项目基于 Apache 2.0 许可证开源。

Copyright 2024 XOAI

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

🙏 致谢

感谢以下项目和社区：

• HAss - 优秀的开源智能家居平台
• Open Home Foundation - 推动智能家居开放标准
• 所有贡献者 - 感谢你们的贡献和支持

---

📞 联系我们

• 🌐 官方网站: https://github.com/yuanzhou029/xoai-frontend
• 📧 邮箱: [e-mail]
• 💬 社区: GitHub Discussions
• 🐦 Twitter: @xoai_frontend

---

🌟 Star History

如果这个项目对你有帮助，请给我们一个 ⭐️

---

Home Assistant - A project from the Open Home Foundation

让智能家居更简单，让生活更美好 🏠✨