LobeHub Feature Development Complete Guide
This document aims to guide developers on how to develop a complete feature in LobeHub.
We will use RFC 021 - Custom Assistant Opening Guidance as an example to illustrate the complete implementation process.
1. Update Schema
LobeHub uses a PostgreSQL database, with Drizzle ORM to operate the database.
All schemas are located in packages/database/src/schemas/. We need to adjust the agents table to add two fields corresponding to the configuration items:
Note that sometimes we may also need to update the index, but for this feature, we don't have any related performance bottleneck issues, so we don't need to update the index.
Database Migration
After adjusting the schema, you need to generate and optimize migration files. See the Database Migration Guide for detailed steps.
2. Update Data Model
Data models are defined in packages/types/src/. We don't directly use the types exported from the Drizzle schema (e.g., typeof agents.$inferInsert), but instead define independent data models based on frontend requirements.
Update the LobeAgentConfig type in packages/types/src/agent/index.ts:
3. Service / Model Layer Implementation
The project is divided into multiple frontend and backend layers by responsibility:
Client Service is frontend code that encapsulates reusable business logic, calling the backend via tRPC client. For agent configuration updates, see src/services/agent.ts:
tRPC Router is the backend entry point. The agent.updateAgentConfig procedure in apps/server/src/routers/lambda/agent/config.ts validates the input, enforces edit permissions and workspace policies, checks collaborative edit locks, and calls ctx.agentService.updateAgentConfig.
Configuration changes go through the agent service using an agent ID. Check the current agent service and model implementation when adding fields; do not introduce a session-based configuration update path.
4. Frontend Implementation
Data Flow Store Implementation
LobeHub uses zustand as the global state management framework. For detailed practices on state management, refer to State Management Best Practices.
There are two stores related to the agent:
src/features/AgentSetting/storeserves the local store for agent settingssrc/store/agentis used to get the current session agent's store
The latter listens for and updates the current session's agent configuration through the onConfigChange in the AgentSettings component in src/features/AgentSetting/AgentSettings.tsx.
Update AgentSetting/store
First, we update the initialState. After reading src/features/AgentSetting/store/initialState.ts, we learn that the initial agent configuration is saved in DEFAULT_AGENT_CONFIG in packages/const/src/settings/agent.ts:
Actually, you don't even need to update this since the openingQuestions type is already optional. I'm not updating openingMessage here.
Because we've added two new fields, to facilitate component access in src/features/AgentSetting/AgentOpening and for performance optimization, we add related selectors in src/features/AgentSetting/store/selectors.ts:
We won't add additional actions to update the agent config here, as existing code also directly uses the unified setAgentConfig:
Update store/agent
In the display component we use src/store/agent to get the current agent configuration. Simply add two selectors:
Update src/store/agent/selectors/selectors.ts:
i18n Handling
LobeHub is an internationalized project using react-i18next. Newly added UI text needs to:
- Add keys to the corresponding namespace file in
packages/locales/src/default/(default language is English):
- If a new namespace is added, export it in
packages/locales/src/default/index.ts - For dev preview: manually translate the corresponding JSON files in
locales/zh-CN/andlocales/en-US/ - CI will automatically run
bun run i18nto generate translations for other languages
Key naming convention uses flat dot notation: {feature}.{context}.{action|status}.
UI Implementation and Action Binding
We're adding a new category of settings. In src/features/AgentSetting, various UI components for agent settings are defined. We'll add an AgentOpening folder for opening settings components.
Taking the subcomponent OpeningQuestions.tsx as an example, here's the key logic (style code omitted):
Key points:
- Read store config via
selectors - Update config via the
setAgentConfigaction - Use
useTranslation('setting')for i18n text
We also need to display the opening configuration set by the user on the chat page. Agent chat uses src/features/AgentHome (AgentInfo.tsx for openingMessage, OpeningQuestions.tsx for questions). Group chat has a parallel welcome under src/routes/(main)/group/features/Conversation/AgentWelcome. Do not use src/features/Onboarding/Agent/WelcomeMessage.tsx — that is the onboarding flow only.
5. Testing
The project uses Vitest for unit testing. See the Testing Skill Guide for details.
Running tests:
Testing suggestions for new features:
Since our two new configuration fields are both optional, theoretically tests would pass without updates. However, if you modified default config (e.g., added openingQuestions to DEFAULT_AGENT_CONFIG), some test snapshots may become stale and need updating.
It's recommended to run related tests locally first to see which fail, then update as needed. For example:
If you just want to check whether existing tests pass without running locally, you can also check the GitHub Actions test results directly.
More testing scenario guides:
- DB Model testing:
.agents/skills/testing/references/db-model-test.md - Zustand Store Action testing:
.agents/skills/testing/references/zustand-store-action-test.md - Electron IPC testing:
.agents/skills/testing/references/electron-ipc-test.md
Summary
The above is the complete implementation process for the LobeHub opening settings feature, covering the full chain from database schema → data model → Service/Model → Store → i18n → UI → testing. Developers can refer to this document for developing related features.