From 7253fd5122f5e4b99dd1670d16bc723ac638a4e5 Mon Sep 17 00:00:00 2001 From: CanisMinor Date: Thu, 18 Jan 2024 23:50:14 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20Add=20text-to-image=20fe?= =?UTF-8?q?at=20(#1089)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 docs: Add text-to-image feat * 🔧 chore: Fix readmeWorkflow * 📝 docs: Update readme * 📝 docs: Update readme * 🔧 chore: Replace ts-node, bun with tsx * 📝 docs: Sync latest plugin list * 📝 docs: Fix emoji * 📝 docs: Update docs --- README.md | 66 ++++-- README.zh-CN.md | 76 ++++-- docs/Deployment/Upstream-Sync.md | 10 +- docs/Deployment/Upstream-Sync.zh-CN.md | 12 +- docs/Development/Add-New-Locale.md | 10 +- docs/Development/Add-New-Locale.zh-CN.md | 10 +- docs/Development/Contributing-Guidelines.md | 83 +++++++ .../Contributing-Guidelines.zh-CN.md | 13 + .../Internationalization-Implementation.md | 125 ++++++++++ ...ternationalization-Implementation.zh-CN.md | 10 +- docs/Development/State-Management/index.md | 224 ++++++++++++++++++ .../State-Management/index.zh-CN.md | 7 + docs/Home.md | 15 +- docs/_Sidebar.md | 15 +- package.json | 10 +- scripts/docsWorkflow/const.ts | 2 +- scripts/docsWorkflow/index.ts | 12 +- scripts/readmeWorkflow/syncAgentIndex.ts | 4 +- scripts/readmeWorkflow/syncPluginIndex.ts | 4 +- 19 files changed, 627 insertions(+), 81 deletions(-) create mode 100644 docs/Development/Contributing-Guidelines.md create mode 100644 docs/Development/Internationalization-Implementation.md create mode 100644 docs/Development/State-Management/index.md diff --git a/README.md b/README.md index 8036f9d73993..c345aa3e9987 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Supports one-click free deployment of your private ChatGPT/LLM web application. ## 👋🏻 Getting Started & Join Our Community -Please be aware that LobeChat is currently under active development, and feedback is welcome for any [issues][issues-link] encountered. +We are a group of e/acc design-engineers, hoping to provide modern design components and tools for AIGC. Whether for users or professional developers, LobeHub will be your AI Agent playground. Please be aware that LobeChat is currently under active development, and feedback is welcome for any [issues][issues-link] encountered. | [![][vercel-shield-badge]][vercel-link] | No installation or registration necessary! Visit our website to experience it firsthand. | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | @@ -143,9 +143,23 @@ Users can choose the voice that suits their personal preferences or specific sce +![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/297746445-0ff762b9-aa08-4337-afb7-12f932b6efbb.png) + +#### `3` Text to Image + +With support for the latest text-to-image generation technology, LobeChat now allows users to invoke image creation tools directly within conversations with the agent. By leveraging the capabilities of AI tools such as [`DALL-E 3`](https://openai.com/dall-e-3), [`MidJourney`](https://www.midjourney.com/), and [`Pollinations`](https://pollinations.ai/), the agents are now equipped to transform your ideas into images. + +This enables a more private and immersive creative process, allowing for the seamless integration of visual storytelling into your personal dialogue with the agent. + +
+ +[![][back-to-top]](#readme-top) + +
+ ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/268670883-33c43a5c-a512-467e-855c-fa299548cce5.png) -#### `3` Function Calling Plugin System +#### `4` Function Calling Plugin System The plugin ecosystem of LobeChat is a significant extension of its core functionalities, greatly enhancing the practicality and flexibility of ChatGPT. By leveraging plugins, ChatGPT can perform real-time information retrieval and processing, @@ -153,7 +167,7 @@ such as automatically fetching the latest news headlines to provide users with i Moreover, these plugins are not limited to news aggregation but can also extend to other practical functions, such as quick document retrieval, e-commerce platform data access, and various third-party services. -[Learn More →](./docs/Usage/Plugins.md) +> Learn More in [📘 Plugin Usage](https://github.com/lobehub/lobe-chat/wiki/Plugins) @@ -170,14 +184,14 @@ e-commerce platform data access, and various third-party services. -| Recent Submits | Description | -| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| [GIF Search](https://chat-preview.lobehub.com/settings/agent)
By **giphy** on **2024-01-17** | Search through a wide range of gifs - Powered by Giphy.
`gif` `image` `search` | -| [Asset Ovi](https://chat-preview.lobehub.com/settings/agent)
By **assetovi** on **2024-01-17** | Search and preview millions of 3D assets for games, AIGC, AR/VR and others.
`3-d` `assets` `search` | -| [Astrodaily](https://chat-preview.lobehub.com/settings/agent)
By **360macky** on **2024-01-17** | Search and discover NASA images.
`nasa` `search` `image` | -| [Boolio Invest](https://chat-preview.lobehub.com/settings/agent)
By **boolio** on **2024-01-17** | Analyze stock investments from any country, with Boolio's state-of-the-art engine.
`stock` `analyze` | +| Recent Submits | Description | +| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Midjourney](https://chat-preview.lobehub.com/settings/agent)
By **LobeHub** on **2024-01-18** | Unleash creativity with Midjourney, effortlessly generating unique AI-driven images through simple prompts. Add visual flair to your conversations with Midjourney's artistic touch.
`ai-image-generation` `midjourney` `visualization` | +| [GIF Search](https://chat-preview.lobehub.com/settings/agent)
By **giphy** on **2024-01-17** | Search through a wide range of gifs - Powered by Giphy.
`gif` `image` `search` | +| [Asset Ovi](https://chat-preview.lobehub.com/settings/agent)
By **assetovi** on **2024-01-17** | Search and preview millions of 3D assets for games, AIGC, AR/VR and others.
`3-d` `assets` `search` | +| [Astrodaily](https://chat-preview.lobehub.com/settings/agent)
By **360macky** on **2024-01-17** | Search and discover NASA images.
`nasa` `search` `image` | -> 📊 Total plugins: [**20**](https://github.com/lobehub/lobe-chat-plugins) +> 📊 Total plugins: [**21**](https://github.com/lobehub/lobe-chat-plugins) @@ -189,7 +203,7 @@ e-commerce platform data access, and various third-party services. ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/268670869-f1ffbf66-42b6-42cf-a937-9ce1f8328514.png) -#### `4` Agent Market +#### `5` Agent Market In the LobeChat Agent Marketplace, creators can discover a vibrant and innovative community that brings together a multitude of well-designed agents, which not only play an important role in work scenarios but also offer great convenience in learning processes. @@ -209,14 +223,14 @@ Our marketplace is not just a showcase platform but also a collaborative space. -| Recent Submits | Description | | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Code Companion](https://chat-preview.lobehub.com/market?agent=code-companion)
By **[110rever](https://github.com/110rever)** on **2024-01-18** | The best companion for programmers
`code` `dev` `program` | | | -| [William](https://chat-preview.lobehub.com/market?agent=unreal-engine-development-engineer)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-16** | Unreal Engine expert, proficient in C++ programming, rendering, memory, thread and other pipeline architectures, UE application on Android platform, comprehensive artistic cognition, familiar with Shader writing, proficient in 3D art asset production process and tools.
`unreal-engine` `c-programming` `rendering-pipeline` `memory-management` `thread-architecture` | | | -| [Chad](https://chat-preview.lobehub.com/market?agent=chad)
By **[HerIsDia](https://github.com/HerIsDia)** on **2024-01-15** | Just chad
`humor` `funny` | | | -| \[SEO Optimized Blog | Human Written | 100% Unique]\()
By **[Soyeb](https://github.com/sekhsoyebali)** on **2024-01-15** | An experienced SEO expert and content writer who specializes in creating 100% unique, human-written blog posts tailored to user requirements.
`blog` `seo` `writing` `article-writing` `seo-optimized-blog` `content-writing` `100-unique-blog` `human-written-blog` | +| Recent Submits | Description | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [AE Script Development Expert](https://chat-preview.lobehub.com/market?agent=ae-script-development)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-18** | An expert in AE script development, proficient in JavaScript programming, understanding of AE software principles, capable of debugging and optimizing scripts.
`script-development` `programmer` `adobe-after-effects` `java-script` `algorithm-design` `debugging` `optimization` `coding-standards` `user-communication` `script-usage-instructions` | +| [Code Companion](https://chat-preview.lobehub.com/market?agent=code-companion)
By **[110rever](https://github.com/110rever)** on **2024-01-18** | The best companion for programmers
`code` `dev` `program` | +| [William](https://chat-preview.lobehub.com/market?agent=unreal-engine-development-engineer)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-16** | Unreal Engine expert, proficient in C++ programming, rendering, memory, thread and other pipeline architectures, UE application on Android platform, comprehensive artistic cognition, familiar with Shader writing, proficient in 3D art asset production process and tools.
`unreal-engine` `c-programming` `rendering-pipeline` `memory-management` `thread-architecture` | +| [Chad](https://chat-preview.lobehub.com/market?agent=chad)
By **[HerIsDia](https://github.com/HerIsDia)** on **2024-01-15** | Just chad
`humor` `funny` | -> 📊 Total agents: [**100** ](https://github.com/lobehub/lobe-chat-agents) +> 📊 Total agents: [**101** ](https://github.com/lobehub/lobe-chat-agents) @@ -228,7 +242,7 @@ Our marketplace is not just a showcase platform but also a collaborative space. ![](https://gw.alipayobjects.com/zos/kitchen/69x6bllkX3/pwa.webp) -#### `5` Progress Web App +#### `6` Progress Web App We deeply understand the importance of providing a seamless experience for users in today's multi-device environment. Therefore, we have adopted Progressive Web Application ([PWA](https://support.google.com/chrome/answer/9658361)) technology, @@ -255,7 +269,7 @@ providing smooth animations, responsive layouts, and adapting to different devic ![](https://gw.alipayobjects.com/zos/kitchen/R441AuFS4W/mobile.webp) -#### `6` Mobile Device Adaptation +#### `7` Mobile Device Adaptation We have carried out a series of optimization designs for mobile devices to enhance the user's mobile experience. Currently, we are iterating on the mobile user experience to achieve smoother and more intuitive interactions. If you have any suggestions or ideas, we welcome you to provide feedback through GitHub Issues or Pull Requests. @@ -267,7 +281,7 @@ We have carried out a series of optimization designs for mobile devices to enhan ![](https://gw.alipayobjects.com/zos/kitchen/pvus1lo%26Z7/darkmode.webp) -#### `7` Theme Mode Selection +#### `8` Theme Mode Selection As a design-engineering-oriented application, LobeChat places great emphasis on users' personalized experiences, hence introducing flexible and diverse theme modes, including a light mode for daytime and a dark mode for nighttime. @@ -466,7 +480,7 @@ $ pnpm install $ pnpm dev ``` -If you would like to learn more details, please feel free to look at our [LobeChat Development Guide](https://github.com/lobehub/lobe-chat/wiki/index) +If you would like to learn more details, please feel free to look at our [📘 Development Guide](https://github.com/lobehub/lobe-chat/wiki/index)
@@ -478,6 +492,14 @@ If you would like to learn more details, please feel free to look at our [LobeCh Contributions of all types are more than welcome; if you are interested in contributing code, feel free to check out our GitHub [Issues][github-issues-link] and [Projects][github-project-link] to get stuck in to show us what you’re made of. +> \[!TIP] +> +> We are creating a technology-driven forum, fostering knowledge interaction and the exchange of ideas that may culminate in mutual inspiration and collaborative innovation. +> +> Help us make LobeChat better. Welcome to provide product design feedback, user experience discussions directly to us. +> +> **Principal Maintainers:** [@arvinxx](https://github.com/arvinxx) [@canisminor1990](https://github.com/canisminor1990) + [![][pr-welcome-shield]][pr-welcome-link] [![][submit-agents-shield]][submit-agents-link] [![][submit-plugin-shield]][submit-plugin-link] diff --git a/README.zh-CN.md b/README.zh-CN.md index e43affa0c188..d5f2dee252b0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -38,6 +38,8 @@ LobeChat 是开源的高性能聊天机器人框架，支持语音合成、多 [![][share-weibo-shield]][share-weibo-link] [![][share-mastodon-shield]][share-mastodon-link] +探索私人生产力的未来。在个体崛起的时代中为你打造. + ![](https://gw.alipayobjects.com/zos/kitchen/RKnWrrfuMl/welcome.webp)
@@ -70,7 +72,8 @@ LobeChat 是开源的高性能聊天机器人框架，支持语音合成、多 ## 👋🏻 开始使用 & 交流 -我们是一群充满热情的设计工程师，希望为 AIGC 提供现代化的设计组件和工具，并以开源的方式分享，以促进它们在更广泛的社区中的发展和采用，LobeChat 目前正在积极开发中，有需求或者问题，欢迎提交 [issues][issues-link] +我们是一群充满热情的设计工程师，希望为 AIGC 提供现代化的设计组件和工具，并以开源的方式分享。不论普通用户与专业开发者 +LobeHub 旨在成为所有人的 AI Agent 实验场，LobeChat 目前正在积极开发中，有需求或者问题，欢迎提交 [issues][issues-link] | [![][vercel-shield-badge]][vercel-link] | 无需安装或注册！访问我们的网站，快速体验 | | :---------------------------------------- | :--------------------------------------------------------------------------- | @@ -91,10 +94,10 @@ LobeChat 是开源的高性能聊天机器人框架，支持语音合成、多 ## ✨ 特性一览 -#### `1` GPT 视觉认知 - ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/284072129-382bdf30-e3d6-4411-b5a0-249710b8ba08.png) +#### `1` GPT 视觉认知 + LobeChat 已经支持 OpenAI 最新的 [`gpt-4-vision`](https://platform.openai.com/docs/guides/vision) 支持视觉识别的模型，这是一个具备视觉识别能力的多模态智能。 用户可以轻松上传图片或者拖拽图片到对话框中，助手将能够识别图片内容，并在此基础上进行智能对话，构建更智能、更多元化的聊天场景。 @@ -106,10 +109,10 @@ LobeChat 已经支持 OpenAI 最新的 [`gpt-4-vision`](https://platform.openai. -#### `2` TTS & STT 语音会话 - ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/284072124-c9853d8d-f1b5-44a8-a305-45ebc0f6d19a.png) +#### `2` TTS & STT 语音会话 + LobeChat 支持文字转语音（Text-to-Speech，TTS）和语音转文字（Speech-to-Text，STT）技术，我们的应用能够将文本信息转化为清晰的语音输出，用户可以像与真人交谈一样与我们的对话代理进行交流。 用户可以从多种声音中选择，给助手搭配合适的音源。 同时，对于那些倾向于听觉学习或者想要在忙碌中获取信息的用户来说，TTS 提供了一个极佳的解决方案。 @@ -129,14 +132,28 @@ LobeChat 支持文字转语音（Text-to-Speech，TTS）和语音转文字（Spe +![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/297746445-0ff762b9-aa08-4337-afb7-12f932b6efbb.png) + +#### `3` Text to Image 文生图 + +支持最新的文本到图片生成技术，LobeChat 现在能够让用户在与助手对话中直接调用文成图工具进行创作。 +通过利用 [`DALL-E 3`](https://openai.com/dall-e-3)、[`MidJourney`](https://www.midjourney.com/) 和 [`Pollinations`](https://pollinations.ai/) 等 AI 工具的能力， 助手们现在可以将你的想法转化为图像。 +同时可以更私密和沉浸式的完成你的创造过程。 + +
+ +[![][back-to-top]](#readme-top) + +
+ ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/268670883-33c43a5c-a512-467e-855c-fa299548cce5.png) -#### `3` Function Calling 插件系统 +#### `4` Function Calling 插件系统 LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地增强了 ChatGPT 的实用性和灵活性。通过利用插件，ChatGPT 能够实现实时信息的获取和处理，例如自动获取最新新闻头条，为用户提供即时且相关的资讯。 此外，这些插件不仅局限于新闻聚合，还可以扩展到其他实用的功能，如快速检索文档、获取电商平台数据、以及其他各式各样的第三方服务。 -[了解更多 →](./docs/Usage/Plugins.zh-CN.md) +> 通过 Wiki 了解更多 [📘 插件使用](https://github.com/lobehub/lobe-chat/wiki/Plugins.zh-CN) @@ -151,14 +168,14 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 -| 最近新增 | 插件描述 | -| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| [GIF 搜索](https://chat-preview.lobehub.com/settings/agent)
By **giphy** on **2024-01-17** | 搜索各种各样的 GIF - 由 Giphy 提供动力。
`gif` `图片` `搜索` | -| [Asset Ovi](https://chat-preview.lobehub.com/settings/agent)
By **assetovi** on **2024-01-17** | 搜索和预览数百万款用于游戏、AIGC、AR/VR 等领域的 3D 资产。
`3-d` `资产` `搜索` | -| [Astrodaily](https://chat-preview.lobehub.com/settings/agent)
By **360macky** on **2024-01-17** | 搜索和发现 NASA 图像。
`nasa` `搜索` `图像` | -| [Boolio Invest](https://chat-preview.lobehub.com/settings/agent)
By **boolio** on **2024-01-17** | 使用 Boolio 的先进引擎分析来自任何国家的股票投资。
`股票` `分析` | +| 最近新增 | 插件描述 | +| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Midjourney](https://chat-preview.lobehub.com/settings/agent)
By **LobeHub** on **2024-01-18** | 通过简单的提示轻松释放创造力，利用 Midjourney 生成独特的 AI 驱动图像。通过 Midjourney 的艺术触感为您的对话增添视觉魅力。
`ai-image-generation` `midjourney` `visualization` | +| [GIF 搜索](https://chat-preview.lobehub.com/settings/agent)
By **giphy** on **2024-01-17** | 搜索各种各样的 GIF - 由 Giphy 提供动力。
`gif` `图片` `搜索` | +| [Asset Ovi](https://chat-preview.lobehub.com/settings/agent)
By **assetovi** on **2024-01-17** | 搜索和预览数百万款用于游戏、AIGC、AR/VR 等领域的 3D 资产。
`3-d` `资产` `搜索` | +| [Astrodaily](https://chat-preview.lobehub.com/settings/agent)
By **360macky** on **2024-01-17** | 搜索和发现 NASA 图像。
`nasa` `搜索` `图像` | -> 📊 Total plugins: [**20**](https://github.com/lobehub/lobe-chat-plugins) +> 📊 Total plugins: [**21**](https://github.com/lobehub/lobe-chat-plugins) @@ -170,7 +187,7 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/268670869-f1ffbf66-42b6-42cf-a937-9ce1f8328514.png) -#### `4` 助手市场 +#### `5` 助手市场 在 LobeChat 的助手市场中，创作者们可以发现一个充满活力和创新的社区，它汇聚了众多精心设计的助手，这些助手不仅在工作场景中发挥着重要作用，也在学习过程中提供了极大的便利。 我们的市场不仅是一个展示平台，更是一个协作的空间。在这里，每个人都可以贡献自己的智慧，分享个人开发的助手。 @@ -186,14 +203,14 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 -| 最近新增 | 助手说明 | | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Code Companion](https://chat-preview.lobehub.com/market?agent=code-companion)
By **[110rever](https://github.com/110rever)** on **2024-01-18** | 程序员的最佳伴侣
`code` `dev` `program` | | | -| [William](https://chat-preview.lobehub.com/market?agent=unreal-engine-development-engineer)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-16** | 虚幻引擎专家，精通 C++ 编程，渲染、内存、线程等管线架构，UE 在安卓平台应用，全面的美术认知，熟悉 Shader 编写，熟练掌握 3D 美术资产制作流程与工具。
`虚幻引擎` `c-编程` `渲染管线` `内存管理` `线程架构` | | | -| [乍得](https://chat-preview.lobehub.com/market?agent=chad)
By **[HerIsDia](https://github.com/HerIsDia)** on **2024-01-15** | 只是乍得
`幽默` `搞笑` | | | -| \[经过 SEO 优化的博客 | 人工撰写 | 100% 独特]\()
By **[Soyeb](https://github.com/sekhsoyebali)** on **2024-01-15** | 一位经验丰富的 SEO 专家和内容撰写人员，专门致力于创建 100% 独特、人工撰写的博客文章，以满足用户需求。
`博客` `seo` `撰写` `文章撰写` `经过seo优化的博客` `内容撰写` `100-独特的博客` `人工撰写的博客` | +| 最近新增 | 助手说明 | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [AE 脚本开发专家](https://chat-preview.lobehub.com/market?agent=ae-script-development)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-18** | AE 脚本开发专家，精通 JavaScript 编程，理解 AE 软件工作原理，能够调试和优化脚本。
`脚本开发` `程序员` `adobe-after-effects` `java-script` `算法设计` `调试` `优化` `编程规范` `用户沟通` `脚本使用说明` | +| [Code Companion](https://chat-preview.lobehub.com/market?agent=code-companion)
By **[110rever](https://github.com/110rever)** on **2024-01-18** | 程序员的最佳伴侣
`code` `dev` `program` | +| [William](https://chat-preview.lobehub.com/market?agent=unreal-engine-development-engineer)
By **[Wutpeach](https://github.com/Wutpeach)** on **2024-01-16** | 虚幻引擎专家，精通 C++ 编程，渲染、内存、线程等管线架构，UE 在安卓平台应用，全面的美术认知，熟悉 Shader 编写，熟练掌握 3D 美术资产制作流程与工具。
`虚幻引擎` `c-编程` `渲染管线` `内存管理` `线程架构` | +| [乍得](https://chat-preview.lobehub.com/market?agent=chad)
By **[HerIsDia](https://github.com/HerIsDia)** on **2024-01-15** | 只是乍得
`幽默` `搞笑` | -> 📊 Total agents: [**100** ](https://github.com/lobehub/lobe-chat-agents) +> 📊 Total agents: [**101** ](https://github.com/lobehub/lobe-chat-agents) @@ -205,7 +222,7 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 ![](https://gw.alipayobjects.com/zos/kitchen/69x6bllkX3/pwa.webp) -#### `5` PWA 渐进式 Web 应用 +#### `6` PWA 渐进式 Web 应用 我们利深知在当今多设备环境下为用户提供无缝体验的重要性。为此，我们采用了渐进式 Web 应用 [PWA](https://support.google.com/chrome/answer/9658361) 技术， 这是一种能够将网页应用提升至接近原生应用体验的现代 Web 技术。通过 PWA，LobeChat 能够在桌面和移动设备上提供高度优化的用户体验，同时保持轻量级和高性能的特点。 @@ -228,7 +245,7 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 ![](https://gw.alipayobjects.com/zos/kitchen/R441AuFS4W/mobile.webp) -#### `6` 移动设备适配 +#### `7` 移动设备适配 针对移动设备进行了一系列的优化设计，以提升用户的移动体验。目前，我们正在对移动端的用户体验进行版本迭代，以实现更加流畅和直观的交互。如果您有任何建议或想法，我们非常欢迎您通过 GitHub Issues 或者 Pull Requests 提供反馈。 @@ -240,7 +257,7 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地 ![](https://gw.alipayobjects.com/zos/kitchen/pvus1lo%26Z7/darkmode.webp) -#### `7` 主题模式选择 +#### `8` 自定义主题 作为设计工程师出身 LobeChat 在界面设计上十分考虑用户的个性化体验，因此引入了灵活多变的主题模式，其中包括日间的亮色模式和夜间的深色模式。 除了主题模式的切换，提供了一系列的颜色定制选项，允许用户根据自己的喜好来调整应用的主题色彩。无论是想要沉稳的深蓝，还是希望活泼的桃粉，或者是专业的灰白，用户都能够在 LobeChat 中找到匹配自己风格的颜色选择。 @@ -480,7 +497,7 @@ $ pnpm install $ pnpm run dev ``` -如果你希望了解更多详情，欢迎可以查阅我们的 [LobeChat 开发指南](https://github.com/lobehub/lobe-chat/wiki/index.zh-CN) +如果你希望了解更多详情，欢迎可以查阅我们的 [📘 开发指南](https://github.com/lobehub/lobe-chat/wiki/index.zh-CN)
@@ -492,6 +509,13 @@ $ pnpm run dev 我们非常欢迎各种形式的贡献。如果你对贡献代码感兴趣，可以查看我们的 GitHub [Issues][github-issues-link] 和 [Projects][github-project-link]，大展身手，向我们展示你的奇思妙想。 +> \[!TIP] +> +> 我们希望创建一个技术分享型社区，一个可以促进知识共享、想法交流，激发彼此鼓励和协作的环境。 +> 同时欢迎联系我们提供产品功能和使用体验反馈，帮助我们将 LobeChat 建设得更好。 +> +> **组织维护者:** [@arvinxx](https://github.com/arvinxx) [@canisminor1990](https://github.com/canisminor1990) + [![][pr-welcome-shield]][pr-welcome-link] [![][submit-agents-shield]][submit-agents-link] [![][submit-plugin-shield]][submit-plugin-link] diff --git a/docs/Deployment/Upstream-Sync.md b/docs/Deployment/Upstream-Sync.md index 8217bbfe16bc..165a142e5bb8 100644 --- a/docs/Deployment/Upstream-Sync.md +++ b/docs/Deployment/Upstream-Sync.md @@ -1,6 +1,12 @@ # Upstream Sync -# A. Vercel / Zeabur Deployment +## TOC + +- [`A` Vercel / Zeabur Deployment](#a-vercel--zeabur-deployment) +- [Enabling Automatic Updates](#enabling-automatic-updates) +- [`B` Docker Deployment](#b-docker-deployment) + +## `A` Vercel / Zeabur Deployment If you have deployed your own project following the one-click deployment steps in the README, you might encounter constant prompts indicating "updates available". This is because Vercel defaults to creating a new project instead of forking this one, resulting in an inability to accurately detect updates. We suggest you redeploy using the following steps: @@ -19,7 +25,7 @@ Once you have forked the project, due to Github restrictions, you will need to m ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985117-4d48fe7b-0412-4667-8129-b25ebcf2c9de.png) ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985177-7677b4ce-c348-4145-9f60-829d448d5be6.png) -# B. Docker Deployment +## `B` Docker Deployment Upgrading the Docker deployment version is very simple, just redeploy the latest image of LobeChat. Here are the instructions to perform these steps: diff --git a/docs/Deployment/Upstream-Sync.zh-CN.md b/docs/Deployment/Upstream-Sync.zh-CN.md index 3bd44e6078d0..c121694565e2 100644 --- a/docs/Deployment/Upstream-Sync.zh-CN.md +++ b/docs/Deployment/Upstream-Sync.zh-CN.md @@ -1,6 +1,12 @@ # 自部署保持更新 -# `A` Vercel / Zeabur 部署 +## TOC + +- [`A` Vercel\`\` / Zeabur 部署](#a-vercel--zeabur-部署) + - [启动自动更新](#启动自动更新) +- [`B` Docker 部署](#b-docker-部署) + +## `A` Vercel\`\` / Zeabur 部署 如果你根据 README 中的一键部署步骤部署了自己的项目，你可能会发现总是被提示 “有可用更新”。这是因为 Vercel 默认为你创建新项目而非 fork 本项目，这将导致无法准确检测更新。我们建议按照以下步骤重新部署： @@ -8,7 +14,7 @@ - 使用页面右上角的 Fork 按钮，Fork 本项目； - 在 `Vercel` 上重新选择并部署。 -## 启动自动更新 +### 启动自动更新 > \[!NOTE] > @@ -19,7 +25,7 @@ ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985117-4d48fe7b-0412-4667-8129-b25ebcf2c9de.png) ![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985177-7677b4ce-c348-4145-9f60-829d448d5be6.png) -# `B` Docker 部署 +## `B` Docker 部署 Docker 部署版本的升级非常简单，只需要重新部署 LobeChat 的最新镜像即可。 以下是执行这些步骤所需的指令： diff --git a/docs/Development/Add-New-Locale.md b/docs/Development/Add-New-Locale.md index d4970821fd9d..ba2c4e90efac 100644 --- a/docs/Development/Add-New-Locale.md +++ b/docs/Development/Add-New-Locale.md @@ -1,7 +1,15 @@ -# LobeChat New Locale Guide +# New Locale Guide LobeChat uses [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) as the i18n solution, which allows for quick addition of new language support in the application. +## TOC + +- [Adding New Language Support](#adding-new-language-support) + - [Step 1: Update the Internationalization Configuration File](#step-1-update-the-internationalization-configuration-file) + - [Step 2: Automatically Translate Language Files](#step-2-automatically-translate-language-files) + - [Step 3: Submit and Review Your Changes](#step-3-submit-and-review-your-changes) + - [Additional Information](#additional-information) + ## Adding New Language Support To add new language internationalization support in LobeChat (for example, adding Vietnamese `vi-VN`), please follow the steps below: diff --git a/docs/Development/Add-New-Locale.zh-CN.md b/docs/Development/Add-New-Locale.zh-CN.md index d1c44f91a495..6072e169140f 100644 --- a/docs/Development/Add-New-Locale.zh-CN.md +++ b/docs/Development/Add-New-Locale.zh-CN.md @@ -1,7 +1,15 @@ -# LobeChat 新语种添加指南 +# 新语种添加指南 LobeChat 使用 [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) 作为 i18n 解决方案，可以在应用中快速添加新的语言支持。 +## TOC + +- [添加新的语言支持](#添加新的语言支持) + - [步骤 1: 更新国际化配置文件](#步骤-1-更新国际化配置文件) + - [步骤 2: 自动翻译语言文件](#步骤-2-自动翻译语言文件) + - [步骤 3: 提交和审查你的更改](#步骤-3-提交和审查你的更改) + - [附加信息](#附加信息) + ## 添加新的语言支持 为了在 LobeChat 中添加新的语言国际化支持，（例如添加越南语 `vi-VN`)，请按照以下步骤操作： diff --git a/docs/Development/Contributing-Guidelines.md b/docs/Development/Contributing-Guidelines.md new file mode 100644 index 000000000000..85ee16c4c4fb --- /dev/null +++ b/docs/Development/Contributing-Guidelines.md @@ -0,0 +1,83 @@ +# Code Style and Contribution Guidelines + +Welcome to the Code Style and Contribution Guidelines for LobeChat. This guide will help you understand our code standards and contribution process, ensuring code consistency and smooth project progression. + +## TOC + +- [Code Style](#code-style) + - [ESLint](#eslint) + - [Prettier](#prettier) + - [remarklint](#remarklint) + - [stylelint](#stylelint) +- [Contribution Process](#contribution-process) + - [Gitmoji](#gitmoji) + - [Semantic Release](#semantic-release) + - [Commitlint](#commitlint) + - [How to Contribute](#how-to-contribute) + +## Code Style + +In LobeChat, we use the `@lobehub/lint` package to maintain a unified code style. This package incorporates configurations for `ESLint`, `Prettier`, `remarklint`, and `stylelint` to ensure that our JavaScript, Markdown, and CSS files adhere to the same coding standards. + +### ESLint + +We use ESLint to check for issues in our JavaScript code. You can find the `.eslintrc.js` file in the project's root directory, which contains our extensions and custom rules for the ESLint configuration of `@lobehub/lint`. + +To ensure your code aligns with the project's standards, run ESLint before committing your code. + +### Prettier + +Prettier is responsible for code formatting to maintain consistency. Our Prettier configuration can be found in `.prettierrc.js`, imported from `@lobehub/lint`. + +It's recommended to configure your editor to run Prettier automatically upon saving files or manually run it before committing. + +### remarklint + +For Markdown files, we use remarklint to ensure consistent document formatting. You can find the corresponding configuration file in the project. + +### stylelint + +We utilize stylelint to standardize the style of our CSS code. In the configuration file for stylelint, we have made some custom rule adjustments based on `@lobehub/lint` configuration. + +Ensure that your style code passes stylelint checks before committing. + +## Contribution Process + +LobeChat follows the gitmoji and semantic release as our code submission and release process. + +### Gitmoji + +When committing code, please use gitmoji to label your commit messages. This helps other contributors quickly understand the content and purpose of your submission. + +Gitmoji commit messages use specific emojis to represent the type or intent of the commit. Here's an example: + +``` +📝 Update README with contribution guidelines + +- Added section about code style preferences +- Included instructions for running tests +- Corrected typos and improved formatting +``` + +In this example, the 📝 emoji represents a documentation update. The commit message clearly describes the changes and provides specific details. + +### Semantic Release + +We use semantic release to automate version control and release processes. Ensure that your commit messages adhere to the semantic release specifications so that when the code is merged into the main branch, the system can automatically create a new version and release it. + +### Commitlint + +To ensure consistency in commit messages, we use `commitlint` to check the format of commit messages. You can find the relevant rules in the `.commitlintrc.js` configuration file. + +Before committing your code, ensure that your commit messages adhere to our standards. + +### How to Contribute + +1. Fork the project to your account. +2. Create a new branch for development. +3. After completing the development, ensure that your code passes the aforementioned code style checks. +4. Commit your changes and use appropriate gitmoji to label your commit message. +5. Create a Pull Request to the main branch of the original project. +6. Await code review and make necessary modifications based on feedback. + +Thank you for following these guidelines, as they help us maintain the quality and consistency of the project. We look forward to your contributions! diff --git a/docs/Development/Contributing-Guidelines.zh-CN.md b/docs/Development/Contributing-Guidelines.zh-CN.md index 7486df488087..3e68199ff592 100644 --- a/docs/Development/Contributing-Guidelines.zh-CN.md +++ b/docs/Development/Contributing-Guidelines.zh-CN.md @@ -2,6 +2,19 @@ 欢迎来到 LobeChat 的代码风格与贡献指南。本指南将帮助您理解我们的代码规范和贡献流程，确保代码的一致性和项目的顺利进行。 +## TOC + +- [代码风格](#代码风格) + - [ESLint](#eslint) + - [Prettier](#prettier) + - [remarklint](#remarklint) + - [stylelint](#stylelint) +- [贡献流程](#贡献流程) + - [Gitmoji](#gitmoji) + - [Semantic Release](#semantic-release) + - [Commitlint](#commitlint) + - [如何贡献](#如何贡献) + ## 代码风格 在 LobeChat 中，我们使用 `@lobehub/lint` 程序包来统一代码风格。该程序包内置了 `ESLint`、`Prettier`、`remarklint` 和 `stylelint` 的配置，以确保我们的 JavaScript、Markdown 和 CSS 文件遵循相同的编码标准。 diff --git a/docs/Development/Internationalization-Implementation.md b/docs/Development/Internationalization-Implementation.md new file mode 100644 index 000000000000..c5b3f8d705ee --- /dev/null +++ b/docs/Development/Internationalization-Implementation.md @@ -0,0 +1,125 @@ +# Internationalization Implementation Guide + +Welcome to the LobeChat Internationalization Implementation Guide. This document will guide you through understanding the internationalization mechanism of LobeChat, including file structure and how to add new languages. LobeChat uses `i18next` and `lobe-i18n` as the internationalization solution, aiming to provide users with seamless multilingual support. + +## TOC + +- [Internationalization Overview](#internationalization-overview) +- [File Structure](#file-structure) +- [Core Implementation Logic](#core-implementation-logic) +- [Adding Support for New Languages](#adding-support-for-new-languages) +- [Resources and Further Reading](#resources-and-further-reading) + +## Internationalization Overview + +Internationalization (i18n for short) is the process of enabling an application to adapt to different languages and regions. In LobeChat, we support multiple languages and achieve dynamic language switching and content localization through the `i18next` library. Our goal is to provide a localized experience for global users. + +## File Structure + +In the LobeChat project, internationalization-related files are organized as follows: + +- `src/locales/default`: Contains translation files for the default development language (Chinese), which we use as Chinese. +- `locales`: Contains folders for all supported languages, with each language folder containing the respective translation files generated by lobe-i18n. + +In the directory structure of `src/locales`, the `default` folder contains the original translation files (Chinese), while each other language folder contains JSON translation files for the respective language. The files in each language folder correspond to the TypeScript files in the `default` folder, ensuring consistency in the structure of translation files across languages. + +``` +src/locales +├── create.ts +├── default +│ ├── chat.ts +│ ├── common.ts +│ ├── error.ts +│ ├── index.ts +│ ├── market.ts +│ ├── migration.ts +│ ├── plugin.ts +│ ├── setting.ts +│ ├── tool.ts +│ └── welcome.ts +└── resources.ts +``` + +The file structure generated by lobe-i18n is as follows: + +``` +locales +├── ar +│ ├── chat.json +│ ├── common.json +│ ├── error.json +│ └── ... (other translation files) +├── de-DE +│ ├── chat.json +│ ├── common.json +│ ├── error.json +│ └── ... (other translation files) +├── en-US +├── ... (other language directories) +├── zh-CN +└── zh-TW +``` + +## Core Implementation Logic + +The internationalization core implementation logic of LobeChat is as follows: + +- Initialize and configure using the `i18next` library. +- Automatically detect the user's language preference using `i18next-browser-languagedetector`. +- Dynamically load translation resources using `i18next-resources-to-backend`. +- Set the direction of the HTML document (LTR or RTL) based on the user's language preference. + +Here is a simplified pseudo code example to illustrate the core implementation logic of internationalization in LobeChat: + +```ts +import i18n from 'i18next'; +import LanguageDetector from 'i18next-browser-languagedetector'; +import resourcesToBackend from 'i18next-resources-to-backend'; +import { isRtlLang } from 'rtl-detect'; + +// Create i18n instance and configure +const createI18nInstance = (lang) => { + const i18nInstance = i18n + .use(LanguageDetector) // Use language detection + .use( + resourcesToBackend((language, namespace) => { + // Dynamically load translation resources for the corresponding language + return import(`path/to/locales/${language}/${namespace}.json`); + }), + ); + + // Listen for language change events and dynamically set document direction + i18nInstance.on('languageChanged', (language) => { + const direction = isRtlLang(language) ? 'rtl' : 'ltr'; + document.documentElement.dir = direction; // Set HTML document direction + }); + + // Initialize i18n instance + i18nInstance.init({ + // Relevant configurations + }); + + return i18nInstance; +}; +``` + +In this example, we demonstrate how to use `i18next` and related plugins to initialize internationalization settings. We dynamically import translation resources and respond to language change events to adjust the text direction of the page. This process provides LobeChat with flexible multilingual support capabilities. + +## Adding Support for New Languages + +We have already supported a variety of languages globally through the following efforts: + +- [✨ feat: adding Arabic Language Support #1049](https://github.com/lobehub/lobe-chat/pull/1049) +- [🌐 style: Add Vietnamese files and add the vi-VN option in the General Settings #860](https://github.com/lobehub/lobe-chat/pull/860) +- [🌐 style: support it-IT nl-NL and pl-PL locales #759](https://github.com/lobehub/lobe-chat/pull/759) +- [🌐 feat(locale): Add fr-FR (#637) #645](https://github.com/lobehub/lobe-chat/pull/645) +- [🌐 Add russian localy #137](https://github.com/lobehub/lobe-chat/pull/137) + +To add support for new languages, please refer to the detailed steps in the [New Locale Addition Guide](Add-New-Locale.en-US). + +## Resources and Further Reading + +- [i18next Official Documentation](https://www.i18next.com/) +- [lobe-i18n Tool Description](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) + +By following this guide, you can better understand and participate in the internationalization work of LobeChat, providing a seamless multilingual experience for global users. diff --git a/docs/Development/Internationalization-Implementation.zh-CN.md b/docs/Development/Internationalization-Implementation.zh-CN.md index 7c5bb6021d0a..f5136628d1f6 100644 --- a/docs/Development/Internationalization-Implementation.zh-CN.md +++ b/docs/Development/Internationalization-Implementation.zh-CN.md @@ -1,7 +1,15 @@ -# LobeChat 国际化实现指南 +# 国际化实现指南 欢迎阅读 LobeChat 国际化实现指南。本文档将指导你了解 LobeChat 的国际化机制，包括文件结构、如何添加新语种。LobeChat 采用 `i18next` 和 `lobe-i18n` 作为国际化解决方案，旨在为用户提供流畅的多语言支持。 +## TOC + +- [国际化概述](#国际化概述) +- [文件结构](#文件结构) +- [核心实现逻辑](#核心实现逻辑) +- [添加新的语言支持](#添加新的语言支持) +- [资源和进一步阅读](#资源和进一步阅读) + ## 国际化概述 国际化（Internationalization，简称为 i18n）是一个让应用能够适应不同语言和地区的过程。在 LobeChat 中，我们支持多种语言，并通过 `i18next` 库来实现语言的动态切换和内容的本地化。我们的目标是让 LobeChat 能够为全球用户提供本地化的体验。 diff --git a/docs/Development/State-Management/index.md b/docs/Development/State-Management/index.md new file mode 100644 index 000000000000..9529413613c6 --- /dev/null +++ b/docs/Development/State-Management/index.md @@ -0,0 +1,224 @@ +# Best Practices for State Management + +LobeChat differs from traditional CRUD web applications in that it involves a large amount of rich interactive capabilities. Therefore, it is crucial to design a data flow architecture that is easy to develop and maintain. This document will introduce the best practices for data flow management in LobeChat. + +## TOC + +- [Key Concepts](#key-concepts) +- [Hierarchical Structure](#hierarchical-structure) + - [Best Practices for LobeChat SessionStore Directory Structure](#best-practices-for-lobechat-sessionstore-directory-structure) +- [Implementation of SessionStore](#implementation-of-sessionstore) + +## Key Concepts + +| Concept | Explanation | +| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| store | The store contains the application's state and actions. It allows access to and modification of the state during application rendering. | +| state | State refers to the data of the application, storing the current state of the application. Any change in the state will **trigger a re-rendering** to reflect the new state. | +| action | An action is an operation function that describes the interactive events occurring in the application. Actions are typically triggered by user interactions, network requests, or timers. Actions can be **synchronous** or **asynchronous**. | +| reducer | A reducer is a pure function that takes the current state and action as parameters and returns a new state. It is used to update the application's state based on the action type. A reducer is a pure function with no side effects, therefore it is always a **synchronous** function. | +| selector | A selector is a function used to retrieve specific data from the application's state. It takes the application's state as a parameter and returns computed or transformed data. Selectors can combine parts of the state or multiple states to generate derived data. Selectors are commonly used to map the application's state to a component's props for the component's use. | +| slice | A slice is a concept used to express a part of the data model state. It specifies a state slice and its related state, action, reducer, and selector. Using slices, a large store can be divided into smaller, maintainable subtypes. | + +## Hierarchical Structure + +The structure of the Store can vary greatly depending on the complexity: + +- **Low Complexity**: Generally includes 2 to 5 states and 3 to 4 actions. In this case, the structure usually consists of a `store.ts` and an `initialState.ts`. + +```bash +DataFill/store +├── index.ts +└── initialState.ts +``` + +- **Moderate Complexity**: Typically involves 5 to 15 states and 5 to 10 actions, with the possibility of selectors for derived states and reducers to simplify data changes. The structure usually includes a `store.ts`, an `initialState.ts`, and a `selectors.ts`/`reducer.ts`. + +```bash +IconPicker/store +├── index.ts +├── initialState.ts +├── selectors.ts +└── store.ts +``` + +```bash +SortableList/store +├── index.ts +├── initialState.ts +├── listDataReducer.ts +└── store.ts +``` + +- **Medium Complexity**: Involves 15 to 30 states and 10 to 20 actions, often requiring the use of multiple slices to manage different actions. The following code represents the internal data flow of the `SortableTree` component: + +```bash +SortableTree/store +├── index.ts +├── initialState.ts +├── selectors.ts +├── slices +│ ├── crudSlice.ts +│ ├── dndSlice.ts +│ └── selectionSlice.ts +├── store.ts +└── treeDataReducer.ts +``` + +- **High Complexity**: Involves over 30 states and 20 actions, requiring modular cohesion using slices. Each slice declares its own initState, actions, reducers, and selectors. + +The directory structure of the previous version of SessionStore for LobeChat, with high complexity, implements a large amount of business logic. However, with the modularization of slices and the fractal architecture, it is easy to find the corresponding modules, making it easy to maintain and iterate on new features. + +```bash +LobeChat SessionStore +├── index.ts +├── initialState.ts +├── selectors.ts +├── slices +│ ├── agentConfig +│ │ ├── action.ts +│ │ ├── index.ts +│ │ ├── initialState.ts +│ │ └── selectors.ts +│ ├── chat +│ │ ├── actions +│ │ │ ├── index.ts +│ │ │ ├── message.ts +│ │ │ └── topic.ts +│ │ ├── index.ts +│ │ ├── initialState.ts +│ │ ├── reducers +│ │ │ ├── message.ts +│ │ │ └── topic.ts +│ │ ├── selectors +│ │ │ ├── chat.ts +│ │ │ ├── index.ts +│ │ │ ├── token.ts +│ │ │ ├── topic.ts +│ │ │ └── utils.ts +│ │ └── utils.ts +│ └── session +│ ├── action.ts +│ ├── index.ts +│ ├── initialState.ts +│ ├── reducers +│ │ └── session.ts +│ └── selectors +│ ├── export.ts +│ ├── index.ts +│ └── list.ts +└── store.ts +``` + +Based on the provided directory structure of LobeChat SessionStore, we can update the previous document and convert the examples to the implementation of LobeChat's SessionStore. The following is a portion of the updated document: + +### Best Practices for LobeChat SessionStore Directory Structure + +In the LobeChat application, session management is a complex functional module, so we use the Slice pattern to organize the data flow. Below is the directory structure of LobeChat SessionStore, where each directory and file has its specific purpose: + +```bash +src/store/session +├── helpers.ts # Helper functions +├── hooks # Custom React hooks +│   ├── index.ts # Export file for hooks +│   ├── useEffectAfterHydrated.ts # Hook for effects after session hydration +│   ├── useOnFinishHydrationSession.ts # Hook for session hydration completion +│   ├── useSessionChatInit.ts # Hook for session chat initialization +│   └── useSessionHydrated.ts # Hook for session hydration status +├── index.ts # Aggregated export file for SessionStore +├── initialState.ts # Aggregated initialState for all slices +├── selectors.ts # Selectors exported from various slices +├── slices # Separated functional modules +│   ├── agent # State and operations related to agents +│   │   ├── action.ts # Action definitions related to agents +│   │   ├── index.ts # Entry file for agent slice +│   │   ├── selectors.test.ts # Tests for agent-related selectors +│   │   └── selectors.ts # Selector definitions related to agents +│   └── session # State and operations related to sessions +│   ├── action.test.ts # Tests for session-related actions +│   ├── action.ts # Action definitions related to sessions +│   ├── helpers.ts # Helper functions related to sessions +│   ├── initialState.ts # Initial state for session slice +│   └── selectors # Session-related selectors and their tests +│   ├── export.ts # Aggregated export for session selectors +│   ├── index.ts # Entry file for session selectors +│   ├── list.test.ts # Tests for list selectors +│   └── list.ts # Definitions for list-related selectors +└── store.ts # Creation and usage of SessionStore +``` + +## Implementation of SessionStore + +In LobeChat, the SessionStore is designed as the core module for managing session state and logic. It consists of multiple Slices, with each Slice managing a relevant portion of state and logic. Below is a simplified example of the SessionStore implementation: + +#### store.ts + +```ts +import { PersistOptions, devtools, persist, subscribeWithSelector } from 'zustand/middleware'; +import { shallow } from 'zustand/shallow'; +import { devtools } from 'zustand/middleware'; +import { createWithEqualityFn } from 'zustand/traditional'; + +import { SessionStoreState, initialState } from './initialState'; +import { AgentAction, createAgentSlice } from './slices/agent/action'; +import { SessionAction, createSessionSlice } from './slices/session/action'; + +// =============== Aggregate createStoreFn ============ // + +export type SessionStore = SessionAction & AgentAction & SessionStoreState; +const createStore: StateCreator = (...parameters) => ({ + ...initialState, + ...createAgentSlice(...parameters), + ...createSessionSlice(...parameters), +}); + + + +// =============== Implement useStore ============ // + +export const useSessionStore = createWithEqualityFn()( + persist( + subscribeWithSelector( + devtools(createStore, { + name: 'LobeChat_Session' + (isDev ? '_DEV' : ''), + }), + ), + persistOptions, + ), + shallow, +); + +``` + +In this `store.ts` file, we create a `useSessionStore` hook that uses the `zustand` library to create a global state manager. We merge the initialState and the state and actions of each Slice to create a complete SessionStore. + +#### slices/session/action.ts + +```ts +import { StateCreator } from 'zustand'; + +import { SessionStore } from '@/store/session'; + +export interface SessionActions { + /** + * A custom hook that uses SWR to fetch sessions data. + */ + useFetchSessions: () => SWRResponse; +} + +export const createSessionSlice: StateCreator< + SessionStore, + [['zustand/devtools', never]], + [], + SessionAction +> = (set, get) => ({ + useFetchSessions: () => { + // ...logic for initializing sessions + }, + // ...implementation of other actions +}); +``` + +In the `action.ts` file, we define a `SessionActions` interface to describe session-related actions and implement a `useFetchSessions` function to create these actions. Then, we merge these actions with the initial state to form the session-related Slice. + +Through this layered and modular approach, we can ensure that LobeChat's SessionStore is clear, maintainable, and easy to extend and test. diff --git a/docs/Development/State-Management/index.zh-CN.md b/docs/Development/State-Management/index.zh-CN.md index 2cbb1210d8e0..a0fffa764af0 100644 --- a/docs/Development/State-Management/index.zh-CN.md +++ b/docs/Development/State-Management/index.zh-CN.md @@ -2,6 +2,13 @@ LobeChat 不同于传统 CRUD 的网页，存在大量的富交互能力，如何设计一个易于开发与易于维护的数据流架构非常重要。本篇文档将介绍 LobeChat 中的数据流管理最佳实践。 +## TOC + +- [概念要素](#概念要素) +- [结构分层](#结构分层) + - [LobeChat SessionStore 目录结构最佳实践](#lobechat-sessionstore-目录结构最佳实践) +- [SessionStore 的实现](#sessionstore-的实现) + ## 概念要素 | 概念名词 | 解释 | diff --git a/docs/Home.md b/docs/Home.md index e26027fb3f44..d9782be49528 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -17,6 +17,7 @@ LobeChat is a open-source, extensible ([Function Calling][fc-url]), high-perform ### 🤯 Usage - [Custom Agents Guide](https://github.com/lobehub/lobe-chat/wiki/Usage-Agents) | [自定义助手指南](https://github.com/lobehub/lobe-chat/wiki/Usage-Agents.zh-CN) +- [Plugin Usage](https://github.com/lobehub/lobe-chat/wiki/Plugins) | [插件使用](https://github.com/lobehub/lobe-chat/wiki/Plugins.zh-CN) - [Topic Guide](https://github.com/lobehub/lobe-chat/wiki/Usage-Topics) | [话题指南](https://github.com/lobehub/lobe-chat/wiki/Usage-Topics.zh-CN)
@@ -27,7 +28,7 @@ LobeChat is a open-source, extensible ([Function Calling][fc-url]), high-perform - [Deploying with Azure OpenAI](https://github.com/lobehub/lobe-chat/wiki/Deploy-with-Azure-OpenAI) | [使用 Azure OpenAI 部署](https://github.com/lobehub/lobe-chat/wiki/Deploy-with-Azure-OpenAI.zh-CN) - [Environment Variables](https://github.com/lobehub/lobe-chat/wiki/Environment-Variable) | [环境变量](https://github.com/lobehub/lobe-chat/wiki/Environment-Variable.zh-CN) - [Upstream Sync](https://github.com/lobehub/lobe-chat/wiki/Upstream-Sync) | [自部署保持更新](https://github.com/lobehub/lobe-chat/wiki/Upstream-Sync.zh-CN) -- [Common Error](https://github.com/lobehub/lobe-chat/wiki/Common-Error) | [常见问题](https://github.com/lobehub/lobe-chat/wiki/Common-Error.zh-CN) +- [Frequently Asked Questions](https://github.com/lobehub/lobe-chat/wiki/Common-Error) | [常见问题](https://github.com/lobehub/lobe-chat/wiki/Common-Error.zh-CN) - [Data Statistics](https://github.com/lobehub/lobe-chat/wiki/Analytics) | [数据统计](https://github.com/lobehub/lobe-chat/wiki/Analytics.zh-CN)
@@ -35,22 +36,24 @@ LobeChat is a open-source, extensible ([Function Calling][fc-url]), high-perform ### ⌨️ Development - [Technical Development Getting Started Guide](https://github.com/lobehub/lobe-chat/wiki/index) | [技术开发上手指南](https://github.com/lobehub/lobe-chat/wiki/index.zh-CN) -- [Environment Setup Guide](https://github.com/lobehub/lobe-chat/wiki/Setup-Development) | [开发环境设置](https://github.com/lobehub/lobe-chat/wiki/Setup-Development.zh-CN) +- [Code Style and Contribution Guidelines](https://github.com/lobehub/lobe-chat/wiki/Contributing-Guidelines) | [代码风格与贡献指南](https://github.com/lobehub/lobe-chat/wiki/Contributing-Guidelines.zh-CN) +- [Environment Setup Guide](https://github.com/lobehub/lobe-chat/wiki/Setup-Development) | [环境设置指南](https://github.com/lobehub/lobe-chat/wiki/Setup-Development.zh-CN) - [Architecture Design](https://github.com/lobehub/lobe-chat/wiki/Architecture) | [架构设计](https://github.com/lobehub/lobe-chat/wiki/Architecture.zh-CN) - [Directory Structure](https://github.com/lobehub/lobe-chat/wiki/Folder-Structure) | [目录架构](https://github.com/lobehub/lobe-chat/wiki/Folder-Structure.zh-CN) -- [State-Management](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [状态管理](https://github.com/lobehub/lobe-chat/wiki/State-Management.zh-CN) - - [Selectors](https://github.com/lobehub/lobe-chat/wiki/State-Management/Selectors) | [取数模块](https://github.com/lobehub/lobe-chat/wiki/State-Management/Selectors.zh-CN) +- [Best Practices for State Management](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [状态管理最佳实践](https://github.com/lobehub/lobe-chat/wiki/State-Management) + - [Data Store Selector](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [数据存储取数模块](https://github.com/lobehub/lobe-chat/wiki/State-Management) - [Conversation API Implementation Logic](https://github.com/lobehub/lobe-chat/wiki/Chat-API) | [会话 API 实现逻辑](https://github.com/lobehub/lobe-chat/wiki/Chat-API.zh-CN) - [How to Develop a New Feature](https://github.com/lobehub/lobe-chat/wiki/Feature-Development) | [如何开发一个新功能](https://github.com/lobehub/lobe-chat/wiki/Feature-Development.zh-CN) -- [Testing Guide](https://github.com/lobehub/lobe-chat/wiki/Test) | [测试指南](https://github.com/lobehub/lobe-chat/wiki/Test.zh-CN) +- [Internationalization Implementation Guide](https://github.com/lobehub/lobe-chat/wiki/Internationalization-Implementation) | [国际化实现指南](https://github.com/lobehub/lobe-chat/wiki/Internationalization-Implementation.zh-CN) - [New Locale Guide](https://github.com/lobehub/lobe-chat/wiki/Add-New-Locale) | [新语种添加指南](https://github.com/lobehub/lobe-chat/wiki/Add-New-Locale.zh-CN) +- [Testing Guide](https://github.com/lobehub/lobe-chat/wiki/Test) | [测试指南](https://github.com/lobehub/lobe-chat/wiki/Test.zh-CN) - [Resources and References](https://github.com/lobehub/lobe-chat/wiki/Resources) | [资源与参考](https://github.com/lobehub/lobe-chat/wiki/Resources.zh-CN)
### 🤖 Agents -- [Agent Index and Submit](https://github.com/lobehub/lobe-chat-agents) | [助手市场与提交](https://github.com/lobehub/lobe-chat-agents/blob/main/README.zh-CN.md) +- [Agent Index and Submit](https://github.com/lobehub/lobe-chat-agents) | [助手索引与提交](https://github.com/lobehub/lobe-chat-agents/blob/main/README.zh-CN.md)
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 98e41f734037..9a6724643d97 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -9,6 +9,7 @@ #### 🤯 Usage - [Custom Agents Guide](https://github.com/lobehub/lobe-chat/wiki/Usage-Agents) | [自定义助手指南](https://github.com/lobehub/lobe-chat/wiki/Usage-Agents.zh-CN) +- [Plugin Usage](https://github.com/lobehub/lobe-chat/wiki/Plugins) | [插件使用](https://github.com/lobehub/lobe-chat/wiki/Plugins.zh-CN) - [Topic Guide](https://github.com/lobehub/lobe-chat/wiki/Usage-Topics) | [话题指南](https://github.com/lobehub/lobe-chat/wiki/Usage-Topics.zh-CN) #### 🛳 Self-Hosting @@ -17,26 +18,28 @@ - [Deploying with Azure OpenAI](https://github.com/lobehub/lobe-chat/wiki/Deploy-with-Azure-OpenAI) | [使用 Azure OpenAI 部署](https://github.com/lobehub/lobe-chat/wiki/Deploy-with-Azure-OpenAI.zh-CN) - [Environment Variables](https://github.com/lobehub/lobe-chat/wiki/Environment-Variable) | [环境变量](https://github.com/lobehub/lobe-chat/wiki/Environment-Variable.zh-CN) - [Upstream Sync](https://github.com/lobehub/lobe-chat/wiki/Upstream-Sync) | [自部署保持更新](https://github.com/lobehub/lobe-chat/wiki/Upstream-Sync.zh-CN) -- [Common Error](https://github.com/lobehub/lobe-chat/wiki/Common-Error) | [常见问题](https://github.com/lobehub/lobe-chat/wiki/Common-Error.zh-CN) +- [Frequently Asked Questions](https://github.com/lobehub/lobe-chat/wiki/Common-Error) | [常见问题](https://github.com/lobehub/lobe-chat/wiki/Common-Error.zh-CN) - [Data Statistics](https://github.com/lobehub/lobe-chat/wiki/Analytics) | [数据统计](https://github.com/lobehub/lobe-chat/wiki/Analytics.zh-CN) #### ⌨️ Development - [Technical Development Getting Started Guide](https://github.com/lobehub/lobe-chat/wiki/index) | [技术开发上手指南](https://github.com/lobehub/lobe-chat/wiki/index.zh-CN) -- [Environment Setup Guide](https://github.com/lobehub/lobe-chat/wiki/Setup-Development) | [开发环境设置](https://github.com/lobehub/lobe-chat/wiki/Setup-Development.zh-CN) +- [Code Style and Contribution Guidelines](https://github.com/lobehub/lobe-chat/wiki/Contributing-Guidelines) | [代码风格与贡献指南](https://github.com/lobehub/lobe-chat/wiki/Contributing-Guidelines.zh-CN) +- [Environment Setup Guide](https://github.com/lobehub/lobe-chat/wiki/Setup-Development) | [环境设置指南](https://github.com/lobehub/lobe-chat/wiki/Setup-Development.zh-CN) - [Architecture Design](https://github.com/lobehub/lobe-chat/wiki/Architecture) | [架构设计](https://github.com/lobehub/lobe-chat/wiki/Architecture.zh-CN) - [Directory Structure](https://github.com/lobehub/lobe-chat/wiki/Folder-Structure) | [目录架构](https://github.com/lobehub/lobe-chat/wiki/Folder-Structure.zh-CN) -- [State-Management](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [状态管理](https://github.com/lobehub/lobe-chat/wiki/State-Management.zh-CN) - - [Data Store Selector](https://github.com/lobehub/lobe-chat/wiki/State-Management/Selectors) | [取数模块](https://github.com/lobehub/lobe-chat/wiki/State-Management/Selectors.zh-CN) +- [Best Practices for State Management](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [状态管理最佳实践](https://github.com/lobehub/lobe-chat/wiki/State-Management) + - [Data Store Selector](https://github.com/lobehub/lobe-chat/wiki/State-Management) | [数据存储取数模块](https://github.com/lobehub/lobe-chat/wiki/State-Management) - [Conversation API Implementation Logic](https://github.com/lobehub/lobe-chat/wiki/Chat-API) | [会话 API 实现逻辑](https://github.com/lobehub/lobe-chat/wiki/Chat-API.zh-CN) - [How to Develop a New Feature](https://github.com/lobehub/lobe-chat/wiki/Feature-Development) | [如何开发一个新功能](https://github.com/lobehub/lobe-chat/wiki/Feature-Development.zh-CN) -- [Testing Guide](https://github.com/lobehub/lobe-chat/wiki/Test) | [测试指南](https://github.com/lobehub/lobe-chat/wiki/Test.zh-CN) +- [Internationalization Implementation Guide](https://github.com/lobehub/lobe-chat/wiki/Internationalization-Implementation) | [国际化实现指南](https://github.com/lobehub/lobe-chat/wiki/Internationalization-Implementation.zh-CN) - [New Locale Guide](https://github.com/lobehub/lobe-chat/wiki/Add-New-Locale) | [新语种添加指南](https://github.com/lobehub/lobe-chat/wiki/Add-New-Locale.zh-CN) +- [Testing Guide](https://github.com/lobehub/lobe-chat/wiki/Test) | [测试指南](https://github.com/lobehub/lobe-chat/wiki/Test.zh-CN) - [Resources and References](https://github.com/lobehub/lobe-chat/wiki/Resources) | [资源与参考](https://github.com/lobehub/lobe-chat/wiki/Resources.zh-CN) #### 🤖 Agents -- [Agent Index and Submit](https://github.com/lobehub/lobe-chat-agents) | [助手市场与提交](https://github.com/lobehub/lobe-chat-agents/blob/main/README.zh-CN.md) +- [Agent Index and Submit](https://github.com/lobehub/lobe-chat-agents) | [助手索引与提交](https://github.com/lobehub/lobe-chat-agents/blob/main/README.zh-CN.md) #### 🧩 Plugins diff --git a/package.json b/package.json index 75f7bad9b4b9..5e29735d989a 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,7 @@ "dev": "next dev -p 3010", "docs": "lobe-i18n md && npm run workflow:docs", "i18n": "npm run workflow:i18n && lobe-i18n", - "i18n-md": "lobe-i18n md", + "i18n:docs": "lobe-i18n md && npm run workflow:docs", "lint": "npm run lint:ts && npm run lint:style && npm run type-check && npm run lint:circular", "lint:circular": "dpdm src/**/*.ts --warning false --tree false --exit-code circular:1 -T true", "lint:md": "remark . --quiet --frail --output", @@ -51,9 +51,9 @@ "test:coverage-local": "vitest run --coverage", "test:update": "vitest -u", "type-check": "tsc --noEmit", - "workflow:docs": "bun scripts/docsWorkflow/index.ts", - "workflow:i18n": "ts-node --project ./tsconfig.json scripts/i18nWorkflow/index.ts", - "workflow:readme": "bun scripts/readmeWorkflow/index.ts" + "workflow:docs": "tsx scripts/docsWorkflow/index.ts", + "workflow:i18n": "tsx scripts/i18nWorkflow/index.ts", + "workflow:readme": "tsx scripts/readmeWorkflow/index.ts" }, "lint-staged": { "*.md": [ @@ -179,7 +179,7 @@ "remark-parse": "^10", "semantic-release": "^21", "stylelint": "^15", - "ts-node": "^10", + "tsx": "^4", "typescript": "^5", "unified": "^11", "unist-util-visit": "^5", diff --git a/scripts/docsWorkflow/const.ts b/scripts/docsWorkflow/const.ts index 6e97685c36a3..b551dd10f083 100644 --- a/scripts/docsWorkflow/const.ts +++ b/scripts/docsWorkflow/const.ts @@ -6,7 +6,7 @@ export const ROOT = resolve(__dirname, '../..'); export const DOCS_DIR = resolve(ROOT, 'docs'); export const HOME_PATH = resolve(DOCS_DIR, 'Home.md'); export const SIDEBAR_PATH = resolve(DOCS_DIR, '_Sidebar.md'); -export const docsFiles = globSync(resolve(DOCS_DIR, '**/*.md'), { +export const docsFiles = globSync(resolve(DOCS_DIR, '**/*.md').replaceAll('\\', '/'), { ignore: ['Home.md', '_Sidebar.md', '_Footer.md'], nodir: true, }).filter((file) => !file.includes('.zh-CN.md')); diff --git a/scripts/docsWorkflow/index.ts b/scripts/docsWorkflow/index.ts index dcf55acb94a2..3426b0b4c822 100644 --- a/scripts/docsWorkflow/index.ts +++ b/scripts/docsWorkflow/index.ts @@ -20,9 +20,15 @@ const run = async () => { const links = { cn: urlJoin( WIKI_URL, - relative(DOCS_DIR, paths.cn).split('/')[1].replace('.zh-CN.md', '.zh-CN'), + relative(DOCS_DIR, paths.cn) + .replaceAll('\\', '/') + .split('/')[1] + .replace('.zh-CN.md', '.zh-CN'), + ), + en: urlJoin( + WIKI_URL, + relative(DOCS_DIR, paths.en).replaceAll('\\', '/').split('/')[1].replace('.md', ''), ), - en: urlJoin(WIKI_URL, relative(DOCS_DIR, paths.en).split('/')[1].replace('.md', '')), }; const titles = { cn: await getTitle(paths.cn), @@ -59,7 +65,7 @@ const run = async () => { child.links.cn, )}\n`; sidebarContent += `- ${genMdLink(child.titles.en, child.links.en)} | ${genMdLink( - '中文', + child.titles.cn, child.links.cn, )}\n`; }); diff --git a/scripts/readmeWorkflow/syncAgentIndex.ts b/scripts/readmeWorkflow/syncAgentIndex.ts index 157ad72ebbf6..7dcc8c1004d2 100644 --- a/scripts/readmeWorkflow/syncAgentIndex.ts +++ b/scripts/readmeWorkflow/syncAgentIndex.ts @@ -10,7 +10,7 @@ const genAgentTable = (data: DataItem[], lang: string) => { const content = data.slice(0, 4).map((item) => [ [ genLink( - item.meta.title, + item.meta.title.replaceAll('|', ','), qs.stringifyUrl({ query: { agent: item.identifier }, url: MARKET_URL, @@ -18,7 +18,7 @@ const genAgentTable = (data: DataItem[], lang: string) => { ), `By **${genLink(item.author, item.homepage)}** on **${(item as any).createAt}**`, ].join('
'), - [item.meta.description, genTags(item.meta.tags)].join('
'), + [item.meta.description.replaceAll('|', ','), genTags(item.meta.tags)].join('
'), ]); return markdownTable([ isCN ? ['最近新增', '助手说明'] : ['Recent Submits', 'Description'], diff --git a/scripts/readmeWorkflow/syncPluginIndex.ts b/scripts/readmeWorkflow/syncPluginIndex.ts index cc480310263a..b659fb6bcf79 100644 --- a/scripts/readmeWorkflow/syncPluginIndex.ts +++ b/scripts/readmeWorkflow/syncPluginIndex.ts @@ -10,10 +10,10 @@ const genPluginTable = (data: DataItem[], lang: string) => { .slice(0, 4) .map((item) => [ [ - genLink(item.meta.title, PLGUIN_URL), + genLink(item.meta.title.replaceAll('|', ','), PLGUIN_URL), `By **${item.author}** on **${item.createdAt}**`, ].join('
'), - [item.meta.description, genTags(item.meta.tags)].join('
'), + [item.meta.description.replaceAll('|', ','), genTags(item.meta.tags)].join('
'), ]); return markdownTable([ isCN ? ['最近新增', '插件描述'] : ['Recent Submits', 'Description'],