--- title: LobeHub Feature Development Complete Guide description: A comprehensive guide for developers on implementing features in LobeHub. tags: - LobeHub - Feature Development - Developer Guide - Postgres - Drizzle ORM --- # 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](https://github.com/lobehub/lobehub/discussions/891) as an example to illustrate the complete implementation process. ## 1. Update Schema LobeHub uses a PostgreSQL database, with [Drizzle ORM](https://orm.drizzle.team/) 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: ```diff // packages/database/src/schemas/agent.ts export const agents = pgTable( 'agents', { id: text('id') .primaryKey() .$defaultFn(() => idGenerator('agents')) .notNull(), avatar: text('avatar'), backgroundColor: text('background_color'), plugins: jsonb('plugins').$type().default([]), // ... tts: jsonb('tts').$type(), + openingMessage: text('opening_message'), + openingQuestions: text('opening_questions').array().default([]), ...timestamps, }, (t) => ({ // ... // !: update index here }), ); ``` 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](https://github.com/lobehub/lobehub/blob/main/.agents/skills/drizzle/references/db-migrations.md) 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`: ```diff export interface LobeAgentConfig { // ... chatConfig: LobeAgentChatConfig; /** * The language model used by the agent * @default gpt-4o-mini */ model: string; + /** + * Opening message + */ + openingMessage?: string; + /** + * Opening questions + */ + openingQuestions?: string[]; /** * Language model parameters */ params: LLMParams; // ... } ``` ## 3. Service / Model Layer Implementation The project is divided into multiple frontend and backend layers by responsibility: ```plaintext +-------------------+--------------------------------------+------------------------------------------------------+ | Layer | Location | Responsibility | +-------------------+--------------------------------------+------------------------------------------------------+ | Client Service | src/services/ | Reusable frontend business logic, often multiple tRPC | | WebAPI | src/app/(backend)/webapi/ | REST API endpoints | | tRPC Router | src/server/routers/ | tRPC entry, validates input, routes to service | | Server Service | src/server/services/ | Server-side business logic, with DB access | | Server Module | src/server/modules/ | Server-side modules, no direct DB access | | Repository | packages/database/src/repositories/ | Complex queries, cross-table operations | | DB Model | packages/database/src/models/ | Single-table CRUD operations | +-------------------+--------------------------------------+------------------------------------------------------+ ``` **Client Service** is frontend code that encapsulates reusable business logic, calling the backend via tRPC client. For example, `src/services/session/index.ts`: ```typescript export class SessionService { updateSessionConfig = (id: string, config: PartialDeep, signal?: AbortSignal) => { return lambdaClient.session.updateSessionConfig.mutate({ id, value: config }, { signal }); }; } ``` **tRPC Router** is the backend entry point (`src/server/routers/lambda/`), validates input and calls Server Service for business logic: ```typescript export const sessionRouter = router({ updateSessionConfig: sessionProcedure .input( z.object({ id: z.string(), value: z.object({}).passthrough().partial(), }), ) .mutation(async ({ input, ctx }) => { const session = await ctx.sessionModel.findByIdOrSlug(input.id); // ... const mergedValue = merge(session.agent, input.value); return ctx.sessionModel.updateConfig(session.agent.id, mergedValue); }), }); ``` For this feature, `updateSessionConfig` simply merges config without field-level granularity, so none of the layers need modification. ## 4. Frontend Implementation ### Data Flow Store Implementation LobeHub uses [zustand](https://zustand.docs.pmnd.rs/getting-started/introduction) as the global state management framework. For detailed practices on state management, refer to [State Management Best Practices](/docs/development/state-management/state-management-intro). There are two stores related to the agent: - `src/features/AgentSetting/store` serves the local store for agent settings - `src/store/agent` is 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 `src/const/settings/agent.ts`: ```diff export const DEFAULT_AGENT_CONFIG: LobeAgentConfig = { chatConfig: DEFAULT_AGENT_CHAT_CONFIG, model: DEFAULT_MODEL, + openingQuestions: [], params: { frequency_penalty: 0, presence_penalty: 0, temperature: 1, top_p: 1, }, plugins: [], provider: DEFAULT_PROVIDER, systemRole: '', tts: DEFAUTT_AGENT_TTS_CONFIG, }; ``` 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`: ```diff +export const DEFAULT_OPENING_QUESTIONS: string[] = []; export const selectors = { chatConfig, + openingMessage: (s: Store) => s.config.openingMessage, + openingQuestions: (s: Store) => s.config.openingQuestions || DEFAULT_OPENING_QUESTIONS, }; ``` We won't add additional actions to update the agent config here, as existing code also directly uses the unified `setAgentConfig`: ```typescript export const store: StateCreator = (set, get) => ({ setAgentConfig: (config) => { get().dispatchConfig({ config, type: 'update' }); }, }); ``` #### 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/slices/chat/selectors/agent.ts`: ```diff +const openingQuestions = (s: AgentStoreState) => + currentAgentConfig(s).openingQuestions || DEFAULT_OPENING_QUESTIONS; +const openingMessage = (s: AgentStoreState) => currentAgentConfig(s).openingMessage || ''; export const agentSelectors = { // ... isInboxSession, + openingMessage, + openingQuestions, }; ``` ### i18n Handling LobeHub is an internationalized project using [react-i18next](https://github.com/i18next/react-i18next). Newly added UI text needs to: 1. Add keys to the corresponding namespace file in `src/locales/default/` (default language is English): ```typescript // src/locales/default/setting.ts export default { // ... 'settingOpening.title': 'Opening Settings', 'settingOpening.openingMessage.title': 'Opening Message', 'settingOpening.openingMessage.placeholder': 'Enter a custom opening message...', 'settingOpening.openingQuestions.title': 'Opening Questions', 'settingOpening.openingQuestions.placeholder': 'Enter a guiding question', 'settingOpening.openingQuestions.empty': 'No opening questions yet', 'settingOpening.openingQuestions.repeat': 'Question already exists', }; ``` 2. If a new namespace is added, export it in `src/locales/default/index.ts` 3. For dev preview: manually translate the corresponding JSON files in `locales/zh-CN/` and `locales/en-US/` 4. CI will automatically run `pnpm i18n` to 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): ```typescript // src/features/AgentSetting/AgentOpening/OpeningQuestions.tsx 'use client'; import { memo, useCallback, useMemo, useState } from 'react'; import { useTranslation } from 'react-i18next'; import { useStore } from '../store'; import { selectors } from '../store/selectors'; const OpeningQuestions = memo(() => { const { t } = useTranslation('setting'); const [questionInput, setQuestionInput] = useState(''); // Use selector to access corresponding configuration const openingQuestions = useStore(selectors.openingQuestions); // Use action to update configuration const updateConfig = useStore((s) => s.setAgentConfig); const setQuestions = useCallback( (questions: string[]) => { updateConfig({ openingQuestions: questions }); }, [updateConfig], ); const addQuestion = useCallback(() => { if (!questionInput.trim()) return; setQuestions([...openingQuestions, questionInput.trim()]); setQuestionInput(''); }, [openingQuestions, questionInput, setQuestions]); const removeQuestion = useCallback( (content: string) => { const newQuestions = [...openingQuestions]; const index = newQuestions.indexOf(content); newQuestions.splice(index, 1); setQuestions(newQuestions); }, [openingQuestions, setQuestions], ); // Render Input + SortableList, see component library docs for UI details // ... }); ``` Key points: - Read store config via `selectors` - Update config via the `setAgentConfig` action - Use `useTranslation('setting')` for i18n text We also need to display the opening configuration set by the user on the chat page. The corresponding component is in `src/app/[variants]/(main)/chat/(workspace)/@conversation/features/ChatList/WelcomeChatItem/WelcomeMessage.tsx`: ```typescript const WelcomeMessage = () => { const { t } = useTranslation('chat'); // Get current opening configuration from store/agent const openingMessage = useAgentStore(agentSelectors.openingMessage); const openingQuestions = useAgentStore(agentSelectors.openingQuestions); const meta = useSessionStore(sessionMetaSelectors.currentAgentMeta, isEqual); const message = useMemo(() => { // Use user-set message if available if (openingMessage) return openingMessage; return !!meta.description ? agentSystemRoleMsg : agentMsg; }, [openingMessage, agentSystemRoleMsg, agentMsg, meta.description]); return openingQuestions.length > 0 ? ( {/* Render guiding questions */} ) : ( ); }; ``` ## 5. Testing The project uses Vitest for unit testing. See the [Testing Skill Guide](https://github.com/lobehub/lobehub/blob/main/.agents/skills/testing/SKILL.md) for details. **Running tests:** ```bash # Run specific test file (never run bun run test — full suite is very slow) bunx vitest run --silent='passed-only' '[file-path]' # Database package tests cd packages/database && bunx vitest run --silent='passed-only' '[file]' ``` **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: ```bash bunx vitest run --silent='passed-only' 'src/store/agent/slices/chat/selectors/agent.test.ts' ``` 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.