mirror of
https://github.com/lobehub/lobe-chat.git
synced 2026-06-14 03:30:19 +00:00
📝 docs(skills): frontmatter cleanup + argument-hint (#14683)
* 🔨 chore: control skill triggering via frontmatter flags - Rename debug skill to debug-package (avoid confusion with debugging workflows) - Add disable-model-invocation to add-* skills so they are manual-only - Add user-invocable: false to reference/architecture skills so they auto-load only when relevant * 🔨 chore: rename skill reference dirs to plural references Align with the skill-creator convention (scripts/, references/, assets/). * 📝 docs(skills): split oversized SKILL.md files and refine triggers - upstash-workflow: 1126L → 189L, extract implementation / best-practices / examples references - data-fetching: 854L → 613L, move parent-keyed-map walkthrough to references - store-data-structures: 625L → 314L, extract types and reducer references - upstash-workflow/cloud.md, version-release/release-notes-style.md: add TOCs - linear: rewrite ALL-CAPS MUSTs into prose explaining why; mark user-invocable: false - version-release: mark disable-model-invocation: true (manual /version-release only) - debug-package: expand description with concrete trigger phrases and tokens * 📝 docs(skills): regularize microcopy structure Move language-specific guidelines into references/zh.md and references/en.md so SKILL.md can point to them via the standard progressive-disclosure pattern. Previously the two files sat next to SKILL.md but were not referenced anywhere, making them invisible to Claude Code loading. * 📝 docs(skills): move builtin-tool refs into references subdir Aligns builtin-tool with the references/ layout used elsewhere (microcopy, store-data-structures). 3 md files move, SKILL.md links updated. * 📝 docs(skills): broaden trigger descriptions for core skills Adds concrete API names, file paths and natural-language phrases so auto-triggering catches more relevant prompts. Touches zustand, drizzle, i18n, react, typescript, modal, hotkey. * 📝 docs(skills): add argument-hint to user-only skills
This commit is contained in:
YuTengjing
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: add-provider-doc
|
||||
description: Guide for adding new AI provider documentation. Use when adding documentation for a new AI provider (like OpenAI, Anthropic, etc.), including usage docs, environment variables, Docker config, and image resources. Triggers on provider documentation tasks.
|
||||
disable-model-invocation: true
|
||||
argument-hint: '[provider-name]'
|
||||
---
|
||||
|
||||
# Adding New AI Provider Documentation
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: add-setting-env
|
||||
description: Guide for adding environment variables to configure user settings. Use when implementing server-side environment variables that control default values for user settings. Triggers on env var configuration or setting default value tasks.
|
||||
disable-model-invocation: true
|
||||
argument-hint: '[setting-name]'
|
||||
---
|
||||
|
||||
# Adding Environment Variable for User Settings
|
||||
|
||||
@@ -19,11 +19,11 @@ A builtin tool is a package the agent runtime can call. It ships **five faces**:
|
||||
|
||||
## Read These First
|
||||
|
||||
| Question | Doc |
|
||||
| ------------------------------------------------------------------------------------ | ---------------------------------- |
|
||||
| Where do files live? What does each face do? Wiring? | [architecture.md](architecture.md) |
|
||||
| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](tool-design.md) |
|
||||
| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](ui.md) |
|
||||
| Question | Doc |
|
||||
| ------------------------------------------------------------------------------------ | --------------------------------------------- |
|
||||
| Where do files live? What does each face do? Wiring? | [architecture.md](references/architecture.md) |
|
||||
| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md) |
|
||||
| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](references/ui.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +109,7 @@ Before opening the PR:
|
||||
- [ ] Placeholder added if the API has a perceivable execution lag (search, list, crawl).
|
||||
- [ ] Streaming added for APIs that emit incremental output (run command, write file, code execution).
|
||||
- [ ] Intervention added if `humanIntervention` is set in the manifest.
|
||||
- [ ] All registry files updated (see [architecture.md → Registry wiring](architecture.md#registry-wiring)).
|
||||
- [ ] All registry files updated (see [architecture.md → Registry wiring](references/architecture.md#registry-wiring)).
|
||||
- [ ] i18n keys in `src/locales/default/plugin.ts` plus dev seeds in `en-US`/`zh-CN`.
|
||||
- [ ] `bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>'` passes.
|
||||
- [ ] `bun run type-check` passes.
|
||||
|
||||
@@ -8,6 +8,7 @@ description: >
|
||||
(4) Send interactive cards or stream AI responses to chat platforms.
|
||||
Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "discord bot", "@chat-adapter",
|
||||
building bots that work across multiple chat platforms.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Chat SDK
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,244 @@
|
||||
# Walkthrough: Adding a New Feature End-to-End
|
||||
|
||||
This is a worked example of the canonical 6-step recipe applied to a new entity (`Dataset`), showing a variant of the main skill's pattern: **a list keyed by a parent id** (`datasetMap[benchmarkId]`), useful when the same shape appears under different parents.
|
||||
|
||||
If you only need the canonical (single-array) pattern, the main `SKILL.md` already shows it for `Benchmark`. Read this file when you need the parent-keyed Map variant, or when you want a checklist-style walkthrough.
|
||||
|
||||
## Step 1: Add Service methods
|
||||
|
||||
```typescript
|
||||
class AgentEvalService {
|
||||
async listDatasets(benchmarkId: string) {
|
||||
return lambdaClient.agentEval.listDatasets.query({ benchmarkId });
|
||||
}
|
||||
async getDataset(id: string) {
|
||||
return lambdaClient.agentEval.getDataset.query({ id });
|
||||
}
|
||||
async createDataset(params: CreateDatasetParams) {
|
||||
return lambdaClient.agentEval.createDataset.mutate(params);
|
||||
}
|
||||
// updateDataset / deleteDataset follow the same shape
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Reducer (optimistic updates)
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/dataset/reducer.ts
|
||||
export type DatasetDispatch =
|
||||
| { type: 'addDataset'; value: Dataset }
|
||||
| { type: 'updateDataset'; id: string; value: Partial<Dataset> }
|
||||
| { type: 'deleteDataset'; id: string };
|
||||
|
||||
export const datasetReducer = (state: Dataset[] = [], payload: DatasetDispatch): Dataset[] =>
|
||||
produce(state, (draft) => {
|
||||
switch (payload.type) {
|
||||
case 'addDataset':
|
||||
draft.unshift(payload.value);
|
||||
break;
|
||||
case 'updateDataset': {
|
||||
const i = draft.findIndex((item) => item.id === payload.id);
|
||||
if (i !== -1) draft[i] = { ...draft[i], ...payload.value };
|
||||
break;
|
||||
}
|
||||
case 'deleteDataset': {
|
||||
const i = draft.findIndex((item) => item.id === payload.id);
|
||||
if (i !== -1) draft.splice(i, 1);
|
||||
break;
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Step 3: Store slice
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/dataset/initialState.ts
|
||||
export interface DatasetData {
|
||||
currentPage: number;
|
||||
hasMore: boolean;
|
||||
isLoading: boolean;
|
||||
items: Dataset[];
|
||||
pageSize: number;
|
||||
total: number;
|
||||
}
|
||||
|
||||
export interface DatasetSliceState {
|
||||
// Map keyed by benchmarkId — multiple parent contexts share the slice
|
||||
datasetMap: Record<string, DatasetData>;
|
||||
// Single item for modal display
|
||||
datasetDetail: Dataset | null;
|
||||
isLoadingDatasetDetail: boolean;
|
||||
loadingDatasetIds: string[];
|
||||
}
|
||||
|
||||
export const datasetInitialState: DatasetSliceState = {
|
||||
datasetMap: {},
|
||||
datasetDetail: null,
|
||||
isLoadingDatasetDetail: false,
|
||||
loadingDatasetIds: [],
|
||||
};
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/dataset/action.ts
|
||||
const FETCH_DATASETS_KEY = 'FETCH_DATASETS';
|
||||
const FETCH_DATASET_DETAIL_KEY = 'FETCH_DATASET_DETAIL';
|
||||
|
||||
export const createDatasetSlice: StateCreator<EvalStore, any, [], DatasetAction> = (set, get) => ({
|
||||
// Cache key includes benchmarkId so each parent has its own SWR entry
|
||||
useFetchDatasets: (benchmarkId) =>
|
||||
useClientDataSWR(
|
||||
benchmarkId ? [FETCH_DATASETS_KEY, benchmarkId] : null,
|
||||
() => agentEvalService.listDatasets(benchmarkId!),
|
||||
{
|
||||
onSuccess: (data) => {
|
||||
set({
|
||||
datasetMap: {
|
||||
...get().datasetMap,
|
||||
[benchmarkId!]: {
|
||||
currentPage: 1,
|
||||
hasMore: false,
|
||||
isLoading: false,
|
||||
items: data,
|
||||
pageSize: data.length,
|
||||
total: data.length,
|
||||
},
|
||||
},
|
||||
});
|
||||
},
|
||||
},
|
||||
),
|
||||
|
||||
useFetchDatasetDetail: (id) =>
|
||||
useClientDataSWR(
|
||||
id ? [FETCH_DATASET_DETAIL_KEY, id] : null,
|
||||
() => agentEvalService.getDataset(id!),
|
||||
{
|
||||
onSuccess: (data) => set({ datasetDetail: data, isLoadingDatasetDetail: false }),
|
||||
},
|
||||
),
|
||||
|
||||
refreshDatasets: (benchmarkId) => mutate([FETCH_DATASETS_KEY, benchmarkId]),
|
||||
refreshDatasetDetail: (id) => mutate([FETCH_DATASET_DETAIL_KEY, id]),
|
||||
|
||||
// CREATE with optimistic update — note the temp id pattern
|
||||
createDataset: async (params) => {
|
||||
const tmpId = Date.now().toString();
|
||||
const { benchmarkId } = params;
|
||||
|
||||
get().internal_dispatchDataset(
|
||||
{ type: 'addDataset', value: { ...params, id: tmpId, createdAt: Date.now() } as any },
|
||||
benchmarkId,
|
||||
);
|
||||
get().internal_updateDatasetLoading(tmpId, true);
|
||||
|
||||
try {
|
||||
const result = await agentEvalService.createDataset(params);
|
||||
await get().refreshDatasets(benchmarkId);
|
||||
return result;
|
||||
} finally {
|
||||
get().internal_updateDatasetLoading(tmpId, false);
|
||||
}
|
||||
},
|
||||
|
||||
// UPDATE / DELETE follow the same optimistic + refresh pattern as BenchmarkSlice
|
||||
// (see the main SKILL.md)
|
||||
|
||||
// Internal — dispatch reducer scoped to a parent
|
||||
internal_dispatchDataset: (payload, benchmarkId) => {
|
||||
const currentData = get().datasetMap[benchmarkId];
|
||||
const nextItems = datasetReducer(currentData?.items, payload);
|
||||
|
||||
// Skip set when nothing changed — avoids unnecessary re-renders
|
||||
if (isEqual(nextItems, currentData?.items)) return;
|
||||
|
||||
set({
|
||||
datasetMap: {
|
||||
...get().datasetMap,
|
||||
[benchmarkId]: {
|
||||
...currentData,
|
||||
currentPage: currentData?.currentPage ?? 1,
|
||||
hasMore: currentData?.hasMore ?? false,
|
||||
isLoading: false,
|
||||
items: nextItems,
|
||||
pageSize: currentData?.pageSize ?? nextItems.length,
|
||||
total: currentData?.total ?? nextItems.length,
|
||||
},
|
||||
},
|
||||
});
|
||||
},
|
||||
|
||||
internal_updateDatasetLoading: (id, loading) => {
|
||||
set((state) => ({
|
||||
loadingDatasetIds: loading
|
||||
? [...state.loadingDatasetIds, id]
|
||||
: state.loadingDatasetIds.filter((i) => i !== id),
|
||||
}));
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Step 4: Wire into the store
|
||||
|
||||
```typescript
|
||||
// src/store/eval/store.ts
|
||||
export type EvalStore = EvalStoreState & BenchmarkAction & DatasetAction & RunAction;
|
||||
|
||||
const createStore: StateCreator<EvalStore, [['zustand/devtools', never]]> = (set, get, store) => ({
|
||||
...initialState,
|
||||
...createBenchmarkSlice(set, get, store),
|
||||
...createDatasetSlice(set, get, store),
|
||||
...createRunSlice(set, get, store),
|
||||
});
|
||||
|
||||
// src/store/eval/initialState.ts
|
||||
export const initialState: EvalStoreState = {
|
||||
...benchmarkInitialState,
|
||||
...datasetInitialState,
|
||||
...runInitialState,
|
||||
};
|
||||
```
|
||||
|
||||
## Step 5: Selectors (optional but recommended)
|
||||
|
||||
```typescript
|
||||
export const datasetSelectors = {
|
||||
getDatasetData: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId],
|
||||
getDatasets: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId]?.items ?? [],
|
||||
isLoadingDataset: (id: string) => (s: EvalStore) => s.loadingDatasetIds.includes(id),
|
||||
};
|
||||
```
|
||||
|
||||
## Step 6: Use in component
|
||||
|
||||
```tsx
|
||||
// List scoped to a parent
|
||||
const DatasetList = ({ benchmarkId }: { benchmarkId: string }) => {
|
||||
const useFetchDatasets = useEvalStore((s) => s.useFetchDatasets);
|
||||
const datasets = useEvalStore(datasetSelectors.getDatasets(benchmarkId));
|
||||
const datasetData = useEvalStore(datasetSelectors.getDatasetData(benchmarkId));
|
||||
|
||||
useFetchDatasets(benchmarkId);
|
||||
|
||||
if (datasetData?.isLoading) return <Loading />;
|
||||
return (
|
||||
<div>
|
||||
<h2>Total: {datasetData?.total ?? 0}</h2>
|
||||
<List data={datasets} />
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
// Single item for modal — conditional fetching pattern
|
||||
const DatasetImportModal = ({ open, datasetId }: Props) => {
|
||||
const useFetchDatasetDetail = useEvalStore((s) => s.useFetchDatasetDetail);
|
||||
const dataset = useEvalStore((s) => s.datasetDetail);
|
||||
const isLoading = useEvalStore((s) => s.isLoadingDatasetDetail);
|
||||
|
||||
// Only fetch when modal is open AND id present
|
||||
useFetchDatasetDetail(open && datasetId ? datasetId : undefined);
|
||||
|
||||
return <Modal open={open}>{isLoading ? <Loading /> : <div>{dataset?.name}</div>}</Modal>;
|
||||
};
|
||||
```
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: db-migrations
|
||||
description: 'Use when generating or regenerating Drizzle migration files, changing database schema tables or columns, resolving migration sequence conflicts after rebase, reviewing migration SQL for idempotent patterns, or renaming migration files.'
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Database Migrations Guide
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: debug
|
||||
description: Debug package usage guide. Use when adding debug logging, understanding log namespaces, or implementing debugging features. Triggers on debug logging requests or logging implementation.
|
||||
name: debug-package
|
||||
description: "Guide for the `debug` npm package and LobeHub log namespaces (lobe-server:*, lobe-desktop:*, lobe-client:*, lobe-*-router:*). Use whenever adding a `debug(...)` logger, picking a namespace for new server/desktop/client/router code, troubleshooting why DEBUG=lobe-* logs don't show up, or when the user asks to 'add logging', 'add a logger', 'instrument this', 'trace this call', 'why isn't my log printing', or mentions `debug(`, `DEBUG=`, `localStorage.debug`, or log format specifiers like %O / %o / %s / %d in a LobeHub codebase."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: drizzle
|
||||
description: Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.
|
||||
description: "Drizzle ORM schema authoring and query style for LobeHub (postgres, strict mode). Use when editing anything under `src/database/schemas/`, defining `pgTable` columns/indexes/junction tables, spreading `...timestamps`, generating `createInsertSchema`/`$inferSelect`/`$inferInsert` types, writing `db.select().from(...).leftJoin(...)` queries, or deciding when to split a relational `with:` into two queries. Triggers on `pgTable`, `db.select`, `db.query`, `eq()`/`and()`/`inArray()`, `uniqueIndex`, `primaryKey`, `references({ onDelete })`, 'add a column', 'new table', 'foreign key', 'junction table', 'schema field'. For migration files specifically, see the `db-migrations` skill."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Drizzle ORM Schema Style Guide
|
||||
@@ -125,11 +126,7 @@ The relational API generates complex lateral joins with `json_build_array` that
|
||||
|
||||
```typescript
|
||||
// ✅ Good
|
||||
const [result] = await this.db
|
||||
.select()
|
||||
.from(agents)
|
||||
.where(eq(agents.id, id))
|
||||
.limit(1);
|
||||
const [result] = await this.db.select().from(agents).where(eq(agents.id, id)).limit(1);
|
||||
return result;
|
||||
|
||||
// ❌ Bad: relational API
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: hotkey
|
||||
description: Guide for adding keyboard shortcuts. Use when implementing new hotkeys, registering shortcuts, or working with keyboard interactions. Triggers on hotkey implementation or keyboard shortcut tasks.
|
||||
description: "Adding or editing keyboard shortcuts in LobeHub. Use when registering a new hotkey, changing a key combo, scoping a shortcut to chat vs global, or wiring a hotkey hook + tooltip. Covers the 5-step flow: add to `HotkeyEnum` in `src/types/hotkey.ts`, register in `HOTKEYS_REGISTRATION` (`src/const/hotkeys.ts`) with `combineKeys([Key.Mod, …])`, add i18n in `src/locales/default/hotkey.ts`, expose via `useHotkeyById` in `src/hooks/useHotkeys/`, and render `<Tooltip hotkey={…}>`. Triggers on `HotkeyEnum`, `HOTKEYS_REGISTRATION`, `useHotkeyById`, `combineKeys`, `Key.Mod`/`Key.Shift`, 'add a hotkey', 'add a shortcut', '加快捷键', '快捷键', 'Cmd+K', 'keyboard shortcut', 'hotkey scope', 'hotkey conflict'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Adding Keyboard Shortcuts Guide
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: i18n
|
||||
description: Internationalization guide using react-i18next. Use when adding translations, creating i18n keys, or working with localized text in React components (.tsx files). Triggers on translation tasks, locale management, or i18n implementation.
|
||||
description: "LobeHub internationalization with react-i18next. Use when adding any user-facing string in `.tsx`/`.ts` files, creating or renaming a key under `src/locales/default/{namespace}.ts`, deciding the `{feature}.{context}.{action}` flat-key pattern, wiring a new namespace into `src/locales/default/index.ts`, or translating zh-CN/en-US JSON for dev preview. Triggers on `useTranslation`, `t('foo.bar')`, `i18next.t`, `{{variable}}` interpolation, hardcoded UI strings (zh or en) that should be extracted, 'add i18n', '加 i18n key', '翻译', 'locale key', 'namespace', 'pnpm i18n'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub Internationalization Guide
|
||||
|
||||
@@ -1,55 +1,55 @@
|
||||
---
|
||||
name: linear
|
||||
description: "Linear issue management. MUST USE when: (1) user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), (2) user says 'linear', 'linear issue', 'link linear', (3) creating PRs that reference Linear issues. Provides workflows for retrieving issues, updating status, and adding comments."
|
||||
description: "Linear issue management. Use when the user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), says 'linear' / 'linear issue' / 'link linear', or when creating PRs that reference Linear issues. Covers retrieving issues, updating status, adding completion comments, and creating sub-issue trees."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Linear Issue Management
|
||||
|
||||
Before using Linear workflows, search for `linear` MCP tools. If not found, treat as not installed.
|
||||
|
||||
## ⚠️ CRITICAL: PR Creation with Linear Issues
|
||||
## PR Creation with Linear Issues
|
||||
|
||||
**When creating a PR that references Linear issues (LOBE-xxx), you MUST:**
|
||||
A PR that fixes a Linear issue has **two separate jobs to do**, and both matter:
|
||||
|
||||
1. Create the PR with magic keywords (`Fixes LOBE-xxx`)
|
||||
2. **IMMEDIATELY after PR creation**, add completion comments to ALL referenced Linear issues
|
||||
3. Do NOT consider the task complete until Linear comments are added
|
||||
1. **`Fixes LOBE-xxx` in the PR body** — Linear watches GitHub for these magic keywords and auto-links the PR and auto-closes the issue on merge. This is the machine-readable side.
|
||||
2. **A completion comment on the Linear issue** — gives the reviewer/PM/teammate landing in Linear a human-readable summary of what changed and why, without forcing them to click through to GitHub and read a diff.
|
||||
|
||||
This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
|
||||
If you only do step 1, Linear watchers (often non-engineers) hit the issue and see no context. So pair PR creation with the Linear comment as part of the same task — finish both before considering the work done.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
|
||||
2. **Read images**: If the issue description contains images, MUST use `mcp__linear-server__extract_images` to read image content for full context
|
||||
3. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
|
||||
4. **Mark as In Progress**: When starting to plan or implement an issue, immediately update status to **"In Progress"** via `mcp__linear-server__update_issue`
|
||||
2. **Read images** — issue descriptions often contain screenshots with critical context (mockups, error states, before/after). Use `mcp__linear-server__extract_images` so you actually see them; reading raw markdown alone misses what the reporter was looking at.
|
||||
3. **Check for sub-issues**: `mcp__linear-server__list_issues` with `parentId` filter
|
||||
4. **Mark as In Progress** at the moment you start planning or implementing — this signals to teammates the issue is owned, so they don't double-pick it up.
|
||||
5. **Update issue status** when completing: `mcp__linear-server__update_issue`
|
||||
6. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
|
||||
6. **Add completion comment** (see [format below](#completion-comment-format))
|
||||
|
||||
## Creating Issues
|
||||
|
||||
When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.
|
||||
When creating issues with `mcp__linear-server__create_issue`, add the `claude code` label. Reason: the label is how the team filters/audits AI-generated issues; without it those issues vanish into the general backlog and the team loses visibility into AI contribution patterns.
|
||||
|
||||
## Language
|
||||
|
||||
Issue titles, descriptions, and comments **MUST follow the language of the current conversation**, not default to English.
|
||||
Match the issue language to the conversation that produced it — if you're discussing in 中文，write the issue in 中文；if discussing in English, write it in English. Reason: the issue is a continuation of the conversation, and forcing a language switch creates translation friction for the collaborator who started the thread.
|
||||
|
||||
- Conversation in 中文 → issue body in 中文；technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
|
||||
- Conversation in English → issue body in English.
|
||||
Specifics:
|
||||
|
||||
- 中文 conversation → 中文 body; technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
|
||||
- English conversation → English body.
|
||||
- Code blocks, file paths, and quoted strings always stay in their original form regardless of surrounding language.
|
||||
- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; do not switch the issue language during a refactor (Chinese → English or vice versa).
|
||||
|
||||
Rationale: the issue is a continuation of the conversation. Forcing English when the discussion is in Chinese creates translation friction for the collaborator who came from that thread.
|
||||
- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; don't switch the issue language mid-refactor.
|
||||
|
||||
## Creating Sub-issue Trees
|
||||
|
||||
When breaking a parent issue into a tree of sub-issues (e.g., task decomposition for LOBE-xxx), follow these rules — they work around real limitations of the Linear MCP tools.
|
||||
|
||||
### 1. ALWAYS prefix titles with an ordering index
|
||||
### 1. Prefix titles with an ordering index
|
||||
|
||||
The Linear Sub-issues panel displays children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation will produce the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you cannot set order at create time.
|
||||
The Linear Sub-issues panel orders children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation produces the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you can't set order at create time.
|
||||
|
||||
**Workaround**: encode execution order in the title itself:
|
||||
Workaround: encode execution order in the title itself:
|
||||
|
||||
```plaintext
|
||||
[1] [db] add schema fields
|
||||
@@ -100,7 +100,7 @@ The implementer may open only the sub-issue, not the parent — don't rely on co
|
||||
|
||||
## Completion Comment Format
|
||||
|
||||
Every completed issue MUST have a comment summarizing work done:
|
||||
Each completed issue gets a comment summarizing the work, so reviewers and future readers don't have to reconstruct it from the PR diff:
|
||||
|
||||
```markdown
|
||||
## Changes Summary
|
||||
@@ -116,34 +116,28 @@ Every completed issue MUST have a comment summarizing work done:
|
||||
- ...
|
||||
```
|
||||
|
||||
This is critical for:
|
||||
This gives team visibility, code-review context, and a paper trail for future reference.
|
||||
|
||||
- Team visibility
|
||||
- Code review context
|
||||
- Future reference
|
||||
## PR Association
|
||||
|
||||
## PR Association (REQUIRED)
|
||||
|
||||
When creating PRs for Linear issues, include magic keywords in PR body:
|
||||
When creating PRs for Linear issues, include magic keywords in the PR body:
|
||||
|
||||
- `Fixes LOBE-123`
|
||||
- `Closes LOBE-123`
|
||||
- `Resolves LOBE-123`
|
||||
|
||||
These trigger Linear's auto-link + auto-close on merge.
|
||||
|
||||
## Per-Issue Completion Rule
|
||||
|
||||
When working on multiple issues, update EACH issue IMMEDIATELY after completing it:
|
||||
When working on multiple issues, close out **each one before starting the next** — don't batch all the Linear updates to the end. Batching is where comments get forgotten and issues stay stuck in "In Progress" days after the PR shipped.
|
||||
|
||||
For each issue:
|
||||
|
||||
1. Complete implementation
|
||||
2. Run `bun run type-check`
|
||||
3. Run related tests
|
||||
4. Create PR if needed
|
||||
5. Update status to **"In Review"** (NOT "Done")
|
||||
6. **Add completion comment immediately**
|
||||
7. Move to next issue
|
||||
|
||||
**Note:** Status → "In Review" when PR created. "Done" only after PR merged.
|
||||
|
||||
**❌ Wrong:** Complete all → Create PR → Forget Linear comments
|
||||
|
||||
**✅ Correct:** Complete → Create PR → Add Linear comments → Task done
|
||||
5. Update status to **"In Review"** (not "Done" — "Done" is for after the PR merges)
|
||||
6. Add the completion comment
|
||||
7. Move to the next issue
|
||||
|
||||
@@ -1,10 +1,16 @@
|
||||
---
|
||||
name: microcopy
|
||||
description: UI copy and microcopy guidelines. Use when writing UI text, buttons, error messages, empty states, onboarding, or any user-facing copy. Triggers on i18n translation, UI text writing, or copy improvement tasks. Supports both Chinese and English.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub UI Microcopy Guidelines
|
||||
|
||||
This file is the quick-reference summary. For full prompt-style guidelines with extensive examples (anti-patterns, tone matrices, scenario walk-throughs), load the language-specific reference:
|
||||
|
||||
- **中文文案** — [`references/zh.md`](./references/zh.md)
|
||||
- **English copy** — [`references/en.md`](./references/en.md)
|
||||
|
||||
Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not just "generation".
|
||||
|
||||
## Fixed Terminology
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: modal
|
||||
description: MUST use when creating, editing, or writing modal dialogs or imperative modals. Prefer createModal / useModalContext / confirmModal from @lobehub/ui/base-ui; root @lobehub/ui is legacy (antd Modal). Covers patterns, ModalHost, and migration notes.
|
||||
description: "LobeHub imperative-modal conventions. Use whenever creating, editing, opening, or migrating a modal/dialog/popup — prefer `createModal` / `confirmModal` / `useModalContext` from `@lobehub/ui/base-ui` (headless) over the legacy root `@lobehub/ui` `createModal` (antd Modal props) and over any declarative `open` state + `<Modal />` pattern. Covers required `ModalHost` mounting, the `Content` + `index.tsx` file layout, `content` vs `children` slot, i18n inside `createModal()` (`import { t } from 'i18next'`), and migration notes. Triggers on `createModal`, `confirmModal`, `useModalContext`, `ModalHost`, `antd Modal`, `<Modal open>`, 'open a modal', 'popup', 'dialog', 'confirm dialog', '弹框', '弹窗', '确认框', 'migrate to base-ui'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: project-overview
|
||||
description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub Project Overview
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: react
|
||||
description: React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.
|
||||
description: "LobeHub React/SPA component conventions: antd-style with `createStaticStyles` + `cssVar.*` (prefer zero-runtime over `createStyles` + `token`), `@lobehub/ui/base-ui` primitives before `@lobehub/ui` before antd, `Flexbox`/`Center` for layouts, react-router-dom navigation, and the `.desktop.tsx` sync rule. Use when writing or editing any `.tsx` under `src/**`, picking a styling helper, choosing a component (Select/Modal/Drawer/Button/Tooltip), wiring routes in `desktopRouter.config.tsx`/`.desktop.tsx`, or adding a `Link`/`useNavigate` call in the SPA. Triggers on `createStyles`/`createStaticStyles`, `cssVar`, `@lobehub/ui`, `antd-style`, `Flexbox`, `useNavigate`, `react-router-dom`, `Link`, 'new component', 'add a page', 'edit a layout', 'desktopRouter', 'componentMap.desktop'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# React Component Writing Guide
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: review-checklist
|
||||
description: 'Common recurring mistakes in LobeHub code review — console leftovers, missing return await, hardcoded secrets, hardcoded i18n strings, desktop router pair drift, antd vs @lobehub/ui, non-idempotent migrations, cloud impact red flags. Use as a quick checklist when reviewing PRs, diffs, or branch changes.'
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Review Checklist
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: spa-routes
|
||||
description: MUST use when editing src/routes/ segments, src/spa/router/desktopRouter.config.tsx or desktopRouter.config.desktop.tsx (always change both together), mobileRouter.config.tsx, or when moving UI/logic between routes and src/features/.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# SPA Routes and Features Guide
|
||||
@@ -84,10 +85,10 @@ Each feature should:
|
||||
|
||||
## 3a. Desktop router pair (`desktopRouter.config` × 2)
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `desktopRouter.config.tsx` | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
|
||||
| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling. |
|
||||
| File | Role |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `desktopRouter.config.tsx` | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
|
||||
| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling. |
|
||||
|
||||
Anything that changes the tree (new segment, renamed `path`, moved layout, new child route) must be reflected in **both** files in one PR or commit. Remove routes from both when deleting.
|
||||
|
||||
|
||||
@@ -1,257 +1,91 @@
|
||||
---
|
||||
name: store-data-structures
|
||||
description: Zustand store data structure patterns for LobeHub. Covers List vs Detail data structures, Map + Reducer patterns, type definitions, and when to use each pattern. Use when designing store state, choosing data structures, or implementing list/detail pages.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub Store Data Structures
|
||||
|
||||
This guide covers how to structure data in Zustand stores for optimal performance and user experience.
|
||||
How to structure data in Zustand stores for fast list rendering, multi-detail caching, and ergonomic optimistic updates.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### ✅ DO
|
||||
|
||||
1. **Separate List and Detail** - Use different structures for list pages and detail pages
|
||||
2. **Use Map for Details** - Cache multiple detail pages with `Record<string, Detail>`
|
||||
3. **Use Array for Lists** - Simple arrays for list display
|
||||
4. **Types from @lobechat/types** - Never use `@lobechat/database` types in stores
|
||||
5. **Distinguish List and Detail types** - List types may have computed UI fields
|
||||
1. **Separate List and Detail** — different structures for list pages and detail pages
|
||||
2. **Use Map for Details** — cache multiple detail pages with `Record<string, Detail>`
|
||||
3. **Use Array for Lists** — simple arrays for list display
|
||||
4. **Types from `@lobechat/types`** — never use `@lobechat/database` types in stores
|
||||
5. **Distinguish List and Detail types** — List types may have computed UI fields
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
1. **Don't use single detail object** - Can't cache multiple pages
|
||||
2. **Don't mix List and Detail types** - They have different purposes
|
||||
3. **Don't use database types** - Use types from `@lobechat/types`
|
||||
4. **Don't use Map for lists** - Simple arrays are sufficient
|
||||
1. **Don't use a single detail object** — can't cache multiple pages
|
||||
2. **Don't mix List and Detail types** — they have different purposes
|
||||
3. **Don't use database types** — use types from `@lobechat/types`
|
||||
4. **Don't use Map for lists** — simple arrays are sufficient
|
||||
|
||||
---
|
||||
|
||||
## Type Definitions
|
||||
|
||||
Types should be organized by entity in separate files:
|
||||
Each entity gets its own file under `@lobechat/types/`. Each file exports two types:
|
||||
|
||||
```
|
||||
@lobechat/types/src/eval/
|
||||
├── benchmark.ts # Benchmark types
|
||||
├── agentEvalDataset.ts # Dataset types
|
||||
├── agentEvalRun.ts # Run types
|
||||
└── index.ts # Re-exports
|
||||
```
|
||||
- **Detail type** — full entity, including heavy fields (rubrics, content, editor state, …)
|
||||
- **List item type** — a **subset** that excludes heavy fields, may add computed UI fields (counts, timestamps formatted for display)
|
||||
|
||||
### Example: Benchmark Types
|
||||
**Important:** the List type is a **subset**, not an `extends` of Detail. Extending pulls the heavy fields right back in.
|
||||
|
||||
```typescript
|
||||
// packages/types/src/eval/benchmark.ts
|
||||
import type { EvalBenchmarkRubric } from './rubric';
|
||||
|
||||
// ============================================
|
||||
// Detail Type - Full entity (for detail pages)
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Full benchmark entity with all fields including heavy data
|
||||
*/
|
||||
export interface AgentEvalBenchmark {
|
||||
createdAt: Date;
|
||||
description?: string | null;
|
||||
id: string;
|
||||
identifier: string;
|
||||
isSystem: boolean;
|
||||
metadata?: Record<string, unknown> | null;
|
||||
name: string;
|
||||
referenceUrl?: string | null;
|
||||
rubrics: EvalBenchmarkRubric[]; // Heavy field
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// List Type - Lightweight (for list display)
|
||||
// ============================================
|
||||
|
||||
/**
|
||||
* Lightweight benchmark item - excludes heavy fields
|
||||
* May include computed statistics for UI
|
||||
*/
|
||||
export interface AgentEvalBenchmarkListItem {
|
||||
createdAt: Date;
|
||||
description?: string | null;
|
||||
id: string;
|
||||
identifier: string;
|
||||
isSystem: boolean;
|
||||
name: string;
|
||||
// Note: rubrics NOT included (heavy field)
|
||||
|
||||
// Computed statistics for UI display
|
||||
datasetCount?: number;
|
||||
runCount?: number;
|
||||
testCaseCount?: number;
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Document Types (with heavy content)
|
||||
|
||||
```typescript
|
||||
// packages/types/src/document.ts
|
||||
|
||||
/**
|
||||
* Full document entity - includes heavy content fields
|
||||
*/
|
||||
export interface Document {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
content: string; // Heavy field - full markdown content
|
||||
editorData: any; // Heavy field - editor state
|
||||
metadata?: Record<string, unknown>;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Lightweight document item - excludes heavy content
|
||||
*/
|
||||
export interface DocumentListItem {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
// Note: content and editorData NOT included
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
|
||||
// Computed statistics
|
||||
wordCount?: number;
|
||||
lastEditedBy?: string;
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- **Detail types** include ALL fields from database (full entity)
|
||||
- **List types** are **subsets** that exclude heavy/large fields
|
||||
- List types may add computed statistics for UI (e.g., `testCaseCount`)
|
||||
- **Each entity gets its own file** (not mixed together)
|
||||
- **All types** exported from `@lobechat/types`, NOT `@lobechat/database`
|
||||
|
||||
**Heavy fields to exclude from List:**
|
||||
|
||||
- Large text content (`content`, `editorData`, `fullDescription`)
|
||||
- Complex objects (`rubrics`, `config`, `metrics`)
|
||||
- Binary data (`image`, `file`)
|
||||
- Large arrays (`messages`, `items`)
|
||||
> See [`references/types.md`](./references/types.md) for full worked examples (Benchmark, Document) and the heavy-field exclusion checklist.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Map vs Array
|
||||
|
||||
### Use Map + Reducer (for Detail Data)
|
||||
### Use Map + Reducer — for Detail Data
|
||||
|
||||
✅ **Detail page data caching** - Cache multiple detail pages simultaneously
|
||||
✅ **Optimistic updates** - Update UI before API responds
|
||||
✅ **Per-item loading states** - Track which items are being updated
|
||||
✅ **Multiple pages open** - User can navigate between details without refetching
|
||||
|
||||
**Structure:**
|
||||
✅ Detail page data caching — multiple detail pages cached simultaneously
|
||||
✅ Optimistic updates — update UI before API responds
|
||||
✅ Per-item loading states — track which items are being updated
|
||||
✅ Multi-page navigation — user can switch between details without refetching
|
||||
|
||||
```typescript
|
||||
benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
|
||||
```
|
||||
|
||||
**Example:** Benchmark detail pages, Dataset detail pages, User profiles
|
||||
Examples: benchmark detail pages, dataset detail pages, user profiles.
|
||||
|
||||
### Use Simple Array (for List Data)
|
||||
### Use Simple Array — for List Data
|
||||
|
||||
✅ **List display** - Lists, tables, cards
|
||||
✅ **Read-only or refresh-as-whole** - Entire list refreshes together
|
||||
✅ **No per-item updates** - No need to update individual items
|
||||
✅ **Simple data flow** - Easier to understand and maintain
|
||||
|
||||
**Structure:**
|
||||
✅ List display — lists, tables, cards
|
||||
✅ Refresh as a whole — entire list refreshes together
|
||||
✅ No per-item updates — no need to mutate individual rows in place
|
||||
✅ Simple data flow — fewer moving parts
|
||||
|
||||
```typescript
|
||||
benchmarkList: AgentEvalBenchmarkListItem[]
|
||||
benchmarkList: AgentEvalBenchmarkListItem[];
|
||||
```
|
||||
|
||||
**Example:** Benchmark list, Dataset list, User list
|
||||
Examples: benchmark list, dataset list, user list.
|
||||
|
||||
---
|
||||
|
||||
## State Structure Pattern
|
||||
|
||||
### Complete Example
|
||||
|
||||
```typescript
|
||||
// packages/types/src/eval/benchmark.ts
|
||||
import type { EvalBenchmarkRubric } from './rubric';
|
||||
|
||||
/**
|
||||
* Full benchmark entity (for detail pages)
|
||||
*/
|
||||
export interface AgentEvalBenchmark {
|
||||
id: string;
|
||||
name: string;
|
||||
description?: string | null;
|
||||
identifier: string;
|
||||
rubrics: EvalBenchmarkRubric[]; // Heavy field
|
||||
metadata?: Record<string, unknown> | null;
|
||||
isSystem: boolean;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Lightweight benchmark (for list display)
|
||||
* Excludes heavy fields like rubrics
|
||||
*/
|
||||
export interface AgentEvalBenchmarkListItem {
|
||||
id: string;
|
||||
name: string;
|
||||
description?: string | null;
|
||||
identifier: string;
|
||||
isSystem: boolean;
|
||||
createdAt: Date;
|
||||
// Note: rubrics excluded
|
||||
|
||||
// Computed statistics
|
||||
testCaseCount?: number;
|
||||
datasetCount?: number;
|
||||
runCount?: number;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/benchmark/initialState.ts
|
||||
import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
|
||||
|
||||
export interface BenchmarkSliceState {
|
||||
// ============================================
|
||||
// List Data - Simple Array
|
||||
// ============================================
|
||||
/**
|
||||
* List of benchmarks for list page display
|
||||
* May include computed fields like testCaseCount
|
||||
*/
|
||||
// List — simple array
|
||||
benchmarkList: AgentEvalBenchmarkListItem[];
|
||||
benchmarkListInit: boolean;
|
||||
|
||||
// ============================================
|
||||
// Detail Data - Map for Caching
|
||||
// ============================================
|
||||
/**
|
||||
* Map of benchmark details keyed by ID
|
||||
* Caches detail page data for multiple benchmarks
|
||||
* Enables optimistic updates and per-item loading
|
||||
*/
|
||||
// Detail — map for multi-entity caching
|
||||
benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
|
||||
loadingBenchmarkDetailIds: string[]; // per-item loading
|
||||
|
||||
/**
|
||||
* Track which benchmark details are being loaded/updated
|
||||
* For showing spinners on specific items
|
||||
*/
|
||||
loadingBenchmarkDetailIds: string[];
|
||||
|
||||
// ============================================
|
||||
// Mutation States
|
||||
// ============================================
|
||||
// Mutation states (drive form-level UI)
|
||||
isCreatingBenchmark: boolean;
|
||||
isUpdatingBenchmark: boolean;
|
||||
isDeletingBenchmark: boolean;
|
||||
@@ -272,180 +106,51 @@ export const benchmarkInitialState: BenchmarkSliceState = {
|
||||
|
||||
## Reducer Pattern (for Detail Map)
|
||||
|
||||
### Why Use Reducer?
|
||||
When the Detail Map needs optimistic updates (i.e. the user edits a row and the UI should reflect it before the server confirms), wire a typed reducer instead of inlining `set` calls. This keeps mutations testable and the dispatch surface small.
|
||||
|
||||
- **Immutable updates** - Immer ensures immutability
|
||||
- **Type-safe actions** - TypeScript discriminated unions
|
||||
- **Testable** - Pure functions easy to test
|
||||
- **Reusable** - Same reducer for optimistic updates and server data
|
||||
|
||||
### Reducer Structure
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/benchmark/reducer.ts
|
||||
import { produce } from 'immer';
|
||||
import type { AgentEvalBenchmark } from '@lobechat/types';
|
||||
|
||||
// ============================================
|
||||
// Action Types
|
||||
// ============================================
|
||||
|
||||
type SetBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'setBenchmarkDetail';
|
||||
value: AgentEvalBenchmark;
|
||||
};
|
||||
|
||||
type UpdateBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'updateBenchmarkDetail';
|
||||
value: Partial<AgentEvalBenchmark>;
|
||||
};
|
||||
|
||||
type DeleteBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'deleteBenchmarkDetail';
|
||||
};
|
||||
|
||||
export type BenchmarkDetailDispatch =
|
||||
| SetBenchmarkDetailAction
|
||||
| UpdateBenchmarkDetailAction
|
||||
| DeleteBenchmarkDetailAction;
|
||||
|
||||
// ============================================
|
||||
// Reducer Function
|
||||
// ============================================
|
||||
|
||||
export const benchmarkDetailReducer = (
|
||||
state: Record<string, AgentEvalBenchmark> = {},
|
||||
payload: BenchmarkDetailDispatch,
|
||||
): Record<string, AgentEvalBenchmark> => {
|
||||
switch (payload.type) {
|
||||
case 'setBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
draft[payload.id] = payload.value;
|
||||
});
|
||||
}
|
||||
|
||||
case 'updateBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
if (draft[payload.id]) {
|
||||
draft[payload.id] = { ...draft[payload.id], ...payload.value };
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
case 'deleteBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
delete draft[payload.id];
|
||||
});
|
||||
}
|
||||
|
||||
default:
|
||||
return state;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Internal Dispatch Methods
|
||||
|
||||
```typescript
|
||||
// In action.ts
|
||||
export interface BenchmarkAction {
|
||||
// ... other methods ...
|
||||
|
||||
// Internal methods - not for direct UI use
|
||||
internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
|
||||
internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
|
||||
}
|
||||
|
||||
export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
|
||||
// ... other methods ...
|
||||
|
||||
// Internal - Dispatch to reducer
|
||||
internal_dispatchBenchmarkDetail: (payload) => {
|
||||
const currentMap = get().benchmarkDetailMap;
|
||||
const nextMap = benchmarkDetailReducer(currentMap, payload);
|
||||
|
||||
// Only update if changed
|
||||
if (isEqual(nextMap, currentMap)) return;
|
||||
|
||||
set(
|
||||
{ benchmarkDetailMap: nextMap },
|
||||
false,
|
||||
`dispatchBenchmarkDetail/${payload.type}`,
|
||||
);
|
||||
},
|
||||
|
||||
// Internal - Update loading state
|
||||
internal_updateBenchmarkDetailLoading: (id, loading) => {
|
||||
set(
|
||||
(state) => {
|
||||
if (loading) {
|
||||
return { loadingBenchmarkDetailIds: [...state.loadingBenchmarkDetailIds, id] };
|
||||
}
|
||||
return {
|
||||
loadingBenchmarkDetailIds: state.loadingBenchmarkDetailIds.filter((i) => i !== id),
|
||||
};
|
||||
},
|
||||
false,
|
||||
'updateBenchmarkDetailLoading',
|
||||
);
|
||||
},
|
||||
});
|
||||
```
|
||||
> See [`references/reducer.md`](./references/reducer.md) for the full discriminated-union action types, the `produce`-based reducer, and the `internal_dispatch*` slice methods that connect them to Zustand.
|
||||
|
||||
---
|
||||
|
||||
## Data Structure Comparison
|
||||
|
||||
### ❌ WRONG - Single Detail Object
|
||||
### ❌ WRONG — Single Detail Object
|
||||
|
||||
```typescript
|
||||
interface BenchmarkSliceState {
|
||||
// ❌ Can only cache one detail
|
||||
benchmarkDetail: AgentEvalBenchmark | null;
|
||||
|
||||
// ❌ Global loading state
|
||||
isLoadingBenchmarkDetail: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
Problems:
|
||||
|
||||
- Can only cache one detail page at a time
|
||||
- Switching between details causes unnecessary refetches
|
||||
- Switching between details forces refetch
|
||||
- No optimistic updates
|
||||
- No per-item loading states
|
||||
|
||||
### ✅ CORRECT - Separate List and Detail
|
||||
### ✅ CORRECT — Separate List and Detail
|
||||
|
||||
```typescript
|
||||
import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
|
||||
|
||||
interface BenchmarkSliceState {
|
||||
// ✅ List data - simple array
|
||||
benchmarkList: AgentEvalBenchmarkListItem[];
|
||||
benchmarkListInit: boolean;
|
||||
|
||||
// ✅ Detail data - map for caching
|
||||
benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
|
||||
|
||||
// ✅ Per-item loading
|
||||
loadingBenchmarkDetailIds: string[];
|
||||
|
||||
// ✅ Mutation states
|
||||
isCreatingBenchmark: boolean;
|
||||
isUpdatingBenchmark: boolean;
|
||||
isDeletingBenchmark: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
Benefits:
|
||||
|
||||
- Cache multiple detail pages
|
||||
- Fast navigation between cached details
|
||||
- Optimistic updates with reducer
|
||||
- Optimistic updates via reducer
|
||||
- Per-item loading states
|
||||
- Clear separation of concerns
|
||||
|
||||
@@ -455,22 +160,16 @@ interface BenchmarkSliceState {
|
||||
|
||||
### Accessing List Data
|
||||
|
||||
```typescript
|
||||
```tsx
|
||||
const BenchmarkList = () => {
|
||||
// Simple array access
|
||||
const benchmarks = useEvalStore((s) => s.benchmarkList);
|
||||
const isInit = useEvalStore((s) => s.benchmarkListInit);
|
||||
|
||||
if (!isInit) return <Loading />;
|
||||
|
||||
return (
|
||||
<div>
|
||||
{benchmarks.map(b => (
|
||||
<BenchmarkCard
|
||||
key={b.id}
|
||||
name={b.name}
|
||||
testCaseCount={b.testCaseCount} // Computed field
|
||||
/>
|
||||
{benchmarks.map((b) => (
|
||||
<BenchmarkCard key={b.id} name={b.name} testCaseCount={b.testCaseCount} />
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
@@ -479,22 +178,18 @@ const BenchmarkList = () => {
|
||||
|
||||
### Accessing Detail Data
|
||||
|
||||
```typescript
|
||||
```tsx
|
||||
const BenchmarkDetail = () => {
|
||||
const { benchmarkId } = useParams<{ benchmarkId: string }>();
|
||||
|
||||
// Get from map
|
||||
const benchmark = useEvalStore((s) =>
|
||||
benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
|
||||
);
|
||||
|
||||
// Check loading
|
||||
const isLoading = useEvalStore((s) =>
|
||||
benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
|
||||
);
|
||||
|
||||
if (!benchmark) return <Loading />;
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>{benchmark.name}</h1>
|
||||
@@ -510,7 +205,6 @@ const BenchmarkDetail = () => {
|
||||
// src/store/eval/slices/benchmark/selectors.ts
|
||||
export const benchmarkSelectors = {
|
||||
getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
|
||||
|
||||
isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
|
||||
s.loadingBenchmarkDetailIds.includes(id),
|
||||
};
|
||||
@@ -524,7 +218,7 @@ const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(bench
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
```text
|
||||
Need to store data?
|
||||
│
|
||||
├─ Is it a LIST for display?
|
||||
@@ -547,43 +241,40 @@ Need to store data?
|
||||
|
||||
When designing store state structure:
|
||||
|
||||
- [ ] **Organize types by entity** in separate files (e.g., `benchmark.ts`, `agentEvalDataset.ts`)
|
||||
- [ ] **Organize types by entity** in separate files (e.g. `benchmark.ts`, `agentEvalDataset.ts`)
|
||||
- [ ] Create **Detail** type (full entity with all fields including heavy ones)
|
||||
- [ ] Create **ListItem** type:
|
||||
- [ ] Subset of Detail type (exclude heavy fields)
|
||||
- [ ] Subset of Detail (exclude heavy fields)
|
||||
- [ ] May include computed statistics for UI
|
||||
- [ ] **NOT** extending Detail type (it's a subset, not extension)
|
||||
- [ ] **NOT** `extends` Detail
|
||||
- [ ] Use **array** for list data: `xxxList: XxxListItem[]`
|
||||
- [ ] Use **Map** for detail data: `xxxDetailMap: Record<string, Xxx>`
|
||||
- [ ] Add per-item loading: `loadingXxxDetailIds: string[]`
|
||||
- [ ] Create **reducer** for detail map if optimistic updates needed
|
||||
- [ ] Add **internal dispatch** and **loading** methods
|
||||
- [ ] Create **selectors** for clean access (optional but recommended)
|
||||
- [ ] Document in comments:
|
||||
- [ ] What fields are excluded from List and why
|
||||
- [ ] What computed fields mean
|
||||
- [ ] What each Map is for
|
||||
- [ ] Per-item loading: `loadingXxxDetailIds: string[]`
|
||||
- [ ] **Reducer** for detail map if optimistic updates needed (see [`references/reducer.md`](./references/reducer.md))
|
||||
- [ ] **Internal dispatch** and **loading** methods
|
||||
- [ ] **Selectors** for clean access (optional but recommended)
|
||||
- [ ] Document in comments which fields are excluded from List and why
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **File organization** - One entity per file, not mixed together
|
||||
2. **List is subset** - ListItem excludes heavy fields, not extends Detail
|
||||
3. **Clear naming** - `xxxList` for arrays, `xxxDetailMap` for maps
|
||||
4. **Consistent patterns** - All detail maps follow same structure
|
||||
5. **Type safety** - Never use `any`, always use proper types
|
||||
6. **Document exclusions** - Comment which fields are excluded from List and why
|
||||
7. **Selectors** - Encapsulate access patterns
|
||||
8. **Loading states** - Per-item for details, global for lists
|
||||
9. **Immutability** - Use Immer in reducers
|
||||
1. **File organization** — one entity per file, not mixed
|
||||
2. **List is a subset** — ListItem excludes heavy fields, does not `extends` Detail
|
||||
3. **Clear naming** — `xxxList` for arrays, `xxxDetailMap` for maps
|
||||
4. **Consistent patterns** — all detail maps follow the same shape
|
||||
5. **Type safety** — never use `any`, always use proper types
|
||||
6. **Document exclusions** — comment which fields are excluded and why
|
||||
7. **Selectors** — encapsulate access patterns
|
||||
8. **Loading states** — per-item for details, global for mutations
|
||||
9. **Immutability** — use Immer in reducers
|
||||
|
||||
### Common Mistakes to Avoid
|
||||
|
||||
❌ **DON'T extend Detail in List:**
|
||||
|
||||
```typescript
|
||||
// Wrong - List should not extend Detail
|
||||
// Wrong — pulls heavy fields back in
|
||||
export interface BenchmarkListItem extends Benchmark {
|
||||
testCaseCount?: number;
|
||||
}
|
||||
@@ -592,7 +283,6 @@ export interface BenchmarkListItem extends Benchmark {
|
||||
✅ **DO create separate subset:**
|
||||
|
||||
```typescript
|
||||
// Correct - List is a subset with computed fields
|
||||
export interface BenchmarkListItem {
|
||||
id: string;
|
||||
name: string;
|
||||
@@ -603,14 +293,14 @@ export interface BenchmarkListItem {
|
||||
|
||||
❌ **DON'T mix entities in one file:**
|
||||
|
||||
```typescript
|
||||
// Wrong - all entities in agentEvalEntities.ts
|
||||
```text
|
||||
// Wrong — all entities in agentEvalEntities.ts
|
||||
```
|
||||
|
||||
✅ **DO separate by entity:**
|
||||
|
||||
```typescript
|
||||
// Correct - separate files
|
||||
```text
|
||||
// Correct — separate files
|
||||
// benchmark.ts
|
||||
// agentEvalDataset.ts
|
||||
// agentEvalRun.ts
|
||||
@@ -620,5 +310,5 @@ export interface BenchmarkListItem {
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `data-fetching` - How to fetch and update this data
|
||||
- `zustand` - General Zustand patterns
|
||||
- `data-fetching` — how to fetch and update this data
|
||||
- `zustand` — general Zustand patterns
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
# Reducer Pattern (for Detail Map)
|
||||
|
||||
## Why Use a Reducer?
|
||||
|
||||
- **Immutable updates** — Immer makes immutability easy
|
||||
- **Type-safe actions** — discriminated union of action types prevents typos
|
||||
- **Testable** — pure function, easy to unit test
|
||||
- **Reusable** — same reducer powers optimistic updates and server-data writes
|
||||
|
||||
## Reducer Structure
|
||||
|
||||
```typescript
|
||||
// src/store/eval/slices/benchmark/reducer.ts
|
||||
import { produce } from 'immer';
|
||||
import type { AgentEvalBenchmark } from '@lobechat/types';
|
||||
|
||||
// Action types — discriminated union
|
||||
type SetBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'setBenchmarkDetail';
|
||||
value: AgentEvalBenchmark;
|
||||
};
|
||||
|
||||
type UpdateBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'updateBenchmarkDetail';
|
||||
value: Partial<AgentEvalBenchmark>;
|
||||
};
|
||||
|
||||
type DeleteBenchmarkDetailAction = {
|
||||
id: string;
|
||||
type: 'deleteBenchmarkDetail';
|
||||
};
|
||||
|
||||
export type BenchmarkDetailDispatch =
|
||||
| SetBenchmarkDetailAction
|
||||
| UpdateBenchmarkDetailAction
|
||||
| DeleteBenchmarkDetailAction;
|
||||
|
||||
export const benchmarkDetailReducer = (
|
||||
state: Record<string, AgentEvalBenchmark> = {},
|
||||
payload: BenchmarkDetailDispatch,
|
||||
): Record<string, AgentEvalBenchmark> => {
|
||||
switch (payload.type) {
|
||||
case 'setBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
draft[payload.id] = payload.value;
|
||||
});
|
||||
}
|
||||
|
||||
case 'updateBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
if (draft[payload.id]) {
|
||||
draft[payload.id] = { ...draft[payload.id], ...payload.value };
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
case 'deleteBenchmarkDetail': {
|
||||
return produce(state, (draft) => {
|
||||
delete draft[payload.id];
|
||||
});
|
||||
}
|
||||
|
||||
default:
|
||||
return state;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Internal Dispatch Methods
|
||||
|
||||
The slice exposes two `internal_*` methods so the reducer and the loading state stay encapsulated behind a stable contract:
|
||||
|
||||
```typescript
|
||||
// In action.ts
|
||||
export interface BenchmarkAction {
|
||||
// ... other methods ...
|
||||
|
||||
// Internal — not for direct UI use
|
||||
internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
|
||||
internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
|
||||
}
|
||||
|
||||
export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
|
||||
// ... other methods ...
|
||||
|
||||
// Dispatch to reducer
|
||||
internal_dispatchBenchmarkDetail: (payload) => {
|
||||
const currentMap = get().benchmarkDetailMap;
|
||||
const nextMap = benchmarkDetailReducer(currentMap, payload);
|
||||
|
||||
// Skip set when nothing changed — avoids unnecessary re-renders
|
||||
if (isEqual(nextMap, currentMap)) return;
|
||||
|
||||
set(
|
||||
{ benchmarkDetailMap: nextMap },
|
||||
false,
|
||||
`dispatchBenchmarkDetail/${payload.type}`,
|
||||
);
|
||||
},
|
||||
|
||||
// Update loading state for a specific id
|
||||
internal_updateBenchmarkDetailLoading: (id, loading) => {
|
||||
set(
|
||||
(state) => ({
|
||||
loadingBenchmarkDetailIds: loading
|
||||
? [...state.loadingBenchmarkDetailIds, id]
|
||||
: state.loadingBenchmarkDetailIds.filter((i) => i !== id),
|
||||
}),
|
||||
false,
|
||||
'updateBenchmarkDetailLoading',
|
||||
);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The `internal_` prefix is a convention — UI components should call the public mutation methods (e.g. `updateBenchmark`), which in turn call `internal_dispatch*`. This keeps reducer dispatch shapes out of the component layer.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Type Definitions in Detail
|
||||
|
||||
The skill body's Type Definitions section covers the rules; this file holds the full worked examples to keep SKILL.md lean.
|
||||
|
||||
## Organization
|
||||
|
||||
Types should be organized by entity in separate files (not mixed):
|
||||
|
||||
```text
|
||||
@lobechat/types/src/eval/
|
||||
├── benchmark.ts # Benchmark types
|
||||
├── agentEvalDataset.ts # Dataset types
|
||||
├── agentEvalRun.ts # Run types
|
||||
└── index.ts # Re-exports
|
||||
```
|
||||
|
||||
## Example: Benchmark Types
|
||||
|
||||
```typescript
|
||||
// packages/types/src/eval/benchmark.ts
|
||||
import type { EvalBenchmarkRubric } from './rubric';
|
||||
|
||||
/**
|
||||
* Full benchmark entity with all fields including heavy data.
|
||||
*/
|
||||
export interface AgentEvalBenchmark {
|
||||
createdAt: Date;
|
||||
description?: string | null;
|
||||
id: string;
|
||||
identifier: string;
|
||||
isSystem: boolean;
|
||||
metadata?: Record<string, unknown> | null;
|
||||
name: string;
|
||||
referenceUrl?: string | null;
|
||||
rubrics: EvalBenchmarkRubric[]; // Heavy field
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Lightweight benchmark item — excludes heavy fields, may add computed stats.
|
||||
*/
|
||||
export interface AgentEvalBenchmarkListItem {
|
||||
createdAt: Date;
|
||||
description?: string | null;
|
||||
id: string;
|
||||
identifier: string;
|
||||
isSystem: boolean;
|
||||
name: string;
|
||||
// Note: rubrics NOT included (heavy field)
|
||||
|
||||
// Computed statistics for UI display
|
||||
datasetCount?: number;
|
||||
runCount?: number;
|
||||
testCaseCount?: number;
|
||||
}
|
||||
```
|
||||
|
||||
## Example: Document Types (with heavy content)
|
||||
|
||||
```typescript
|
||||
// packages/types/src/document.ts
|
||||
|
||||
/**
|
||||
* Full document entity — includes heavy content fields.
|
||||
*/
|
||||
export interface Document {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
content: string; // Heavy field — full markdown content
|
||||
editorData: any; // Heavy field — editor state
|
||||
metadata?: Record<string, unknown>;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Lightweight document item — excludes heavy content.
|
||||
*/
|
||||
export interface DocumentListItem {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
// Note: content and editorData NOT included
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
|
||||
// Computed statistics
|
||||
wordCount?: number;
|
||||
lastEditedBy?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Heavy Fields to Exclude from List
|
||||
|
||||
- Large text content (`content`, `editorData`, `fullDescription`)
|
||||
- Complex objects (`rubrics`, `config`, `metrics`)
|
||||
- Binary data (`image`, `file`)
|
||||
- Large arrays (`messages`, `items`)
|
||||
|
||||
The reason these belong only on Detail: list pages render many rows, so pulling heavy fields blows up payload size and slows render. Detail pages render one entity, so the full payload is fine.
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: testing
|
||||
description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub Testing Guide
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: trpc-router
|
||||
description: TRPC router development guide. Use when creating or modifying TRPC routers (src/server/routers/**), adding procedures, or working with server-side API endpoints. Triggers on TRPC router creation, procedure implementation, or API endpoint tasks.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# TRPC Router Guide
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: typescript
|
||||
description: TypeScript code style and optimization guidelines. MUST READ before writing or modifying any TypeScript code (.ts, .tsx, .mts files). Also use when reviewing code quality or implementing type-safe patterns. Triggers on any TypeScript file edit, code style discussions, or type safety questions.
|
||||
description: "TypeScript code style and type-safety guide for LobeHub. Read before writing or editing any `.ts` / `.tsx` / `.mts` — covers `interface` vs `type`, `Record<PropertyKey, unknown>` over `any`/`object`, `as const satisfies`, `@ts-expect-error` over `@ts-ignore`, `import type` (`separate-type-imports`), `async`/`await` + `Promise.all`, `for…of` over indexed `for`, and the no-silent-`.catch(() => fallback)` rule. Also use when reviewing type quality, deciding module augmentation (`declare module`) over `namespace`, or designing extensible types (e.g. `PipelineContext.metadata`). Triggers on any TypeScript file edit, 'fix the type', 'why is this `any`', 'should this be interface or type', 'eslint type-import', 'ts-expect-error'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# TypeScript Code Style Guide
|
||||
@@ -28,12 +29,16 @@ description: TypeScript code style and optimization guidelines. MUST READ before
|
||||
## Imports
|
||||
|
||||
- This project uses `simple-import-sort/imports` and `consistent-type-imports` (`fixStyle: 'separate-type-imports'`)
|
||||
|
||||
- **Separate type imports**: always use `import type { ... }` for type-only imports, NOT `import { type ... }` inline syntax
|
||||
|
||||
- When a file already has `import type { ... }` from a package and you need to add a value import, keep them as **two separate statements**:
|
||||
|
||||
```ts
|
||||
import type { ChatTopicBotContext } from '@lobechat/types';
|
||||
import { RequestTrigger } from '@lobechat/types';
|
||||
```
|
||||
|
||||
- Within each import statement, specifiers are sorted **alphabetically by name**
|
||||
|
||||
## Code Structure
|
||||
@@ -42,6 +47,7 @@ description: TypeScript code style and optimization guidelines. MUST READ before
|
||||
- Use consistent, descriptive naming; avoid obscure abbreviations
|
||||
- Replace magic numbers/strings with well-named constants
|
||||
- Defer formatting to tooling
|
||||
- Prefer **named exports** over `export default` — keeps refactor renames and IDE auto-import in sync, and avoids the `default` re-naming drift you get with `import Foo from './foo'`. Reserve `export default` for files where the framework requires it (Next.js page/route/layout, React.lazy targets, config files like `vitest.config.ts`)
|
||||
|
||||
## UI and Theming
|
||||
|
||||
@@ -51,7 +57,6 @@ description: TypeScript code style and optimization guidelines. MUST READ before
|
||||
|
||||
## Performance
|
||||
|
||||
- Prefer `for…of` loops over index-based `for` loops
|
||||
- Reuse existing utils in `packages/utils` or installed npm packages
|
||||
- Query only required columns from database
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,226 @@
|
||||
# Best Practices & Common Pitfalls
|
||||
|
||||
Apply these once your scaffold from `implementation.md` is in place.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Error Handling](#1-error-handling)
|
||||
2. [Logging](#2-logging)
|
||||
3. [Return Values](#3-return-values)
|
||||
4. [flowControl Configuration](#4-flowcontrol-configuration)
|
||||
5. [context.run() Best Practices](#5-contextrun-best-practices)
|
||||
6. [Payload Validation](#6-payload-validation)
|
||||
7. [Database Connection](#7-database-connection)
|
||||
8. [Testing](#8-testing)
|
||||
9. [Common Pitfalls](#common-pitfalls)
|
||||
|
||||
---
|
||||
|
||||
## 1. Error Handling
|
||||
|
||||
```typescript
|
||||
export const { POST } = serve<Payload>(
|
||||
async (context) => {
|
||||
const { itemId } = context.requestPayload ?? {};
|
||||
|
||||
if (!itemId) {
|
||||
return { success: false, error: 'Missing itemId in payload' };
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await context.run('step-name', () => doWork(itemId));
|
||||
return { success: true, itemId, result };
|
||||
} catch (error) {
|
||||
console.error('[workflow:error]', error);
|
||||
return {
|
||||
success: false,
|
||||
error: error instanceof Error ? error.message : 'Unknown error',
|
||||
};
|
||||
}
|
||||
},
|
||||
{ flowControl: { ... } },
|
||||
);
|
||||
```
|
||||
|
||||
## 2. Logging
|
||||
|
||||
Consistent prefixes make debugging much easier across QStash dashboards and grep:
|
||||
|
||||
```typescript
|
||||
console.log('[{workflow}:{layer}] Starting with payload:', payload);
|
||||
console.log('[{workflow}:{layer}] Processing items:', { count: items.length });
|
||||
console.log('[{workflow}:{layer}] Completed:', result);
|
||||
console.error('[{workflow}:{layer}:error]', error);
|
||||
```
|
||||
|
||||
## 3. Return Values
|
||||
|
||||
Pick the shape that matches the layer's purpose — entry points return statistics, execution layers return per-item results.
|
||||
|
||||
```typescript
|
||||
// Success
|
||||
return { success: true, itemId, result, message: 'Optional success message' };
|
||||
|
||||
// Error
|
||||
return { success: false, error: 'Error description', itemId };
|
||||
|
||||
// Statistics (entry point)
|
||||
return {
|
||||
success: true,
|
||||
totalEligible: 100,
|
||||
toProcess: 80,
|
||||
alreadyProcessed: 20,
|
||||
dryRun: true, // if applicable
|
||||
message: 'Summary message',
|
||||
};
|
||||
```
|
||||
|
||||
## 4. flowControl Configuration
|
||||
|
||||
Tune concurrency by layer — entry points are singletons, execution layers fan out.
|
||||
|
||||
```typescript
|
||||
// Layer 1: Entry — single instance to avoid duplicate processing
|
||||
flowControl: { key: '{workflow}.process', parallelism: 1, ratePerSecond: 1 }
|
||||
|
||||
// Layer 2: Pagination — moderate concurrency
|
||||
flowControl: { key: '{workflow}.paginate', parallelism: 20, ratePerSecond: 5 }
|
||||
|
||||
// Layer 3: Execution — higher concurrency for parallel item work
|
||||
flowControl: { key: '{workflow}.execute', parallelism: 10, ratePerSecond: 5 }
|
||||
```
|
||||
|
||||
**Why these defaults:**
|
||||
|
||||
- **Layer 1** always uses `parallelism: 1` so concurrent triggers don't both start the same batch.
|
||||
- **Layer 2** can fan out widely (10-20) since pagination is cheap.
|
||||
- **Layer 3** caps at 5-10 by default; raise/lower based on external API rate limits.
|
||||
|
||||
## 5. context.run() Best Practices
|
||||
|
||||
- Use descriptive step names with prefixes: `{workflow}:step-name`
|
||||
- Each step should be idempotent (safe to retry)
|
||||
- Don't nest `context.run()` calls — keep them flat
|
||||
- Use unique step names when processing multiple items:
|
||||
|
||||
```typescript
|
||||
// ✅ Unique step names
|
||||
await Promise.all(
|
||||
items.map((item) => context.run(`{workflow}:execute:${item.id}`, () => processItem(item))),
|
||||
);
|
||||
|
||||
// ❌ Same step name — Upstash de-dupes by step name and you'll lose data
|
||||
await Promise.all(items.map((item) => context.run(`{workflow}:execute`, () => processItem(item))));
|
||||
```
|
||||
|
||||
## 6. Payload Validation
|
||||
|
||||
Validate at the top so failures are explicit, not silent `undefined` cascades:
|
||||
|
||||
```typescript
|
||||
export const { POST } = serve<Payload>(
|
||||
async (context) => {
|
||||
const { itemId, configId } = context.requestPayload ?? {};
|
||||
|
||||
if (!itemId) return { success: false, error: 'Missing itemId in payload' };
|
||||
if (!configId) return { success: false, error: 'Missing configId in payload' };
|
||||
|
||||
// Proceed with work...
|
||||
},
|
||||
{ flowControl: { ... } },
|
||||
);
|
||||
```
|
||||
|
||||
## 7. Database Connection
|
||||
|
||||
Get the connection once per workflow — `getServerDB()` is async, repeating it inside each step adds latency:
|
||||
|
||||
```typescript
|
||||
export const { POST } = serve<Payload>(
|
||||
async (context) => {
|
||||
const db = await getServerDB();
|
||||
|
||||
const item = await context.run('get-item', () => itemModel.findById(db, itemId));
|
||||
const result = await context.run('save-result', () => resultModel.create(db, result));
|
||||
},
|
||||
{ flowControl: { ... } },
|
||||
);
|
||||
```
|
||||
|
||||
## 8. Testing
|
||||
|
||||
Integration tests should exercise both the dry-run statistics path and the full execution path:
|
||||
|
||||
```typescript
|
||||
describe('WorkflowName', () => {
|
||||
it('should process items successfully', async () => {
|
||||
const items = await createTestItems();
|
||||
await WorkflowClass.triggerProcessItems({ dryRun: false });
|
||||
await waitForCompletion();
|
||||
const results = await getResults();
|
||||
expect(results).toHaveLength(items.length);
|
||||
});
|
||||
|
||||
it('should support dryRun mode', async () => {
|
||||
const result = await WorkflowClass.triggerProcessItems({ dryRun: true });
|
||||
expect(result).toMatchObject({
|
||||
success: true,
|
||||
dryRun: true,
|
||||
totalEligible: expect.any(Number),
|
||||
toProcess: expect.any(Number),
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### ❌ Reusing `context.run()` step names
|
||||
|
||||
```typescript
|
||||
// Bad — Upstash dedupes by step name
|
||||
await Promise.all(items.map((item) => context.run('process', () => process(item))));
|
||||
|
||||
// Good
|
||||
await Promise.all(items.map((item) => context.run(`process:${item.id}`, () => process(item))));
|
||||
```
|
||||
|
||||
### ❌ Skipping payload validation
|
||||
|
||||
```typescript
|
||||
// Bad — undefined cascades into a confusing failure later
|
||||
const { itemId } = context.requestPayload ?? {};
|
||||
const result = await process(itemId);
|
||||
|
||||
// Good — fail fast with a clear error
|
||||
if (!itemId) return { success: false, error: 'Missing itemId' };
|
||||
```
|
||||
|
||||
### ❌ Skipping the filter step
|
||||
|
||||
```typescript
|
||||
// Bad — duplicates work for items that were already processed
|
||||
const allItems = await getAllItems();
|
||||
await Promise.all(allItems.map((item) => triggerExecute(item)));
|
||||
|
||||
// Good — keeps the pipeline idempotent
|
||||
const allItems = await getAllItems();
|
||||
const itemsNeedingProcessing = await filterExisting(allItems);
|
||||
await Promise.all(itemsNeedingProcessing.map((item) => triggerExecute(item)));
|
||||
```
|
||||
|
||||
### ❌ Inconsistent logging
|
||||
|
||||
```typescript
|
||||
// Bad — different prefixes, mixed formats
|
||||
console.log('Starting workflow');
|
||||
log.info('Processing item:', itemId);
|
||||
console.log(`Done with ${itemId}`);
|
||||
|
||||
// Good — uniform prefix lets you grep by workflow+layer
|
||||
console.log('[workflow:layer] Starting with payload:', payload);
|
||||
console.log('[workflow:layer] Processing item:', { itemId });
|
||||
console.log('[workflow:layer] Completed:', { itemId, result });
|
||||
```
|
||||
+22
-8
@@ -1,6 +1,20 @@
|
||||
# Cloud Project Workflow Configuration
|
||||
|
||||
This document covers cloud-specific workflow configurations and patterns for the lobehub-cloud project.
|
||||
Cloud-specific workflow configurations and patterns for the lobehub-cloud project.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Directory Structure](#directory-structure) — submodule + cloud layout
|
||||
3. [Cloud-Specific Patterns](#cloud-specific-patterns) — cloud-only workflows + re-export pattern
|
||||
4. [TypeScript Path Mappings](#typescript-path-mappings)
|
||||
5. [Workflow Class Location](#workflow-class-location) — cloud-only vs shared
|
||||
6. [Environment Variables](#environment-variables)
|
||||
7. [Best Practices](#best-practices) — decide cloud vs OSS, re-export rules, naming
|
||||
8. [Migration Guide](#migration-guide) — moving workflows from cloud to lobehub
|
||||
9. [Examples](#examples) — `welcome-placeholder`, `agent-eval-run`
|
||||
10. [Troubleshooting](#troubleshooting) — circular imports, 404s, type errors
|
||||
11. [Related Documentation](#related-documentation)
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -15,7 +29,7 @@ The lobehub-cloud project extends the open-source lobehub codebase with cloud-sp
|
||||
|
||||
### Lobehub Submodule (Open-source)
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub/
|
||||
└── src/
|
||||
├── app/(backend)/api/workflows/
|
||||
@@ -28,7 +42,7 @@ lobehub/
|
||||
|
||||
### Lobehub-cloud (Proprietary)
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub-cloud/
|
||||
└── src/
|
||||
├── app/(backend)/api/workflows/
|
||||
@@ -60,7 +74,7 @@ lobehub-cloud/
|
||||
|
||||
**Structure**:
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub-cloud/src/
|
||||
├── app/(backend)/api/workflows/
|
||||
│ └── feature-name/
|
||||
@@ -162,7 +176,7 @@ This allows cloud to override specific modules while using lobehub defaults.
|
||||
|
||||
Place workflow class in cloud:
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub-cloud/src/server/workflows/featureName/index.ts
|
||||
```
|
||||
|
||||
@@ -170,7 +184,7 @@ lobehub-cloud/src/server/workflows/featureName/index.ts
|
||||
|
||||
Place workflow class in lobehub, re-export in cloud if needed:
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub/src/server/workflows/featureName/index.ts
|
||||
```
|
||||
|
||||
@@ -245,7 +259,7 @@ For shared features:
|
||||
|
||||
Follow consistent naming across lobehub and cloud:
|
||||
|
||||
```
|
||||
```text
|
||||
# Both should use same structure
|
||||
lobehub/src/app/(backend)/api/workflows/feature-name/
|
||||
lobehub-cloud/src/app/(backend)/api/workflows/feature-name/
|
||||
@@ -306,7 +320,7 @@ import { Workflow } from 'lobehub/src/server/workflows/feature';
|
||||
|
||||
**Structure**:
|
||||
|
||||
```
|
||||
```text
|
||||
lobehub-cloud/
|
||||
├── src/app/(backend)/api/workflows/welcome-placeholder/
|
||||
│ ├── process-users/route.ts
|
||||
@@ -0,0 +1,91 @@
|
||||
# Worked Examples
|
||||
|
||||
Two real workflows already in the codebase that follow this skill's pattern verbatim. Skim them when you want to see the pattern applied to concrete entities.
|
||||
|
||||
## Example 1: Welcome Placeholder
|
||||
|
||||
**Use case:** Generate AI-powered welcome placeholders for users.
|
||||
|
||||
**Structure:**
|
||||
|
||||
- Layer 1: `process-users` — entry point, checks eligible users
|
||||
- Layer 2: `paginate-users` — paginates through active users
|
||||
- Layer 3: `generate-user` — generates placeholders for ONE user
|
||||
|
||||
**Key features:**
|
||||
|
||||
- Filters users who already have cached placeholders in Redis
|
||||
- `paidOnly` flag to scope to subscribed users
|
||||
- `dryRun` mode for statistics
|
||||
- Fan-out for large user batches (`CHUNK_SIZE=20`)
|
||||
|
||||
**Layer 3 shape:**
|
||||
|
||||
```typescript
|
||||
export const { POST } = serve<GenerateUserPlaceholderPayload>(async (context) => {
|
||||
const { userId } = context.requestPayload ?? {};
|
||||
|
||||
const workflow = new WelcomePlaceholderWorkflow(db, userId);
|
||||
const placeholders = await context.run('generate', () => workflow.generate());
|
||||
|
||||
return { success: true, userId, placeholdersCount: placeholders.length };
|
||||
});
|
||||
```
|
||||
|
||||
**Files:**
|
||||
|
||||
- `/api/workflows/welcome-placeholder/process-users/route.ts`
|
||||
- `/api/workflows/welcome-placeholder/paginate-users/route.ts`
|
||||
- `/api/workflows/welcome-placeholder/generate-user/route.ts`
|
||||
- `/server/workflows/welcomePlaceholder/index.ts`
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Agent Welcome
|
||||
|
||||
**Use case:** Generate welcome messages and open questions for AI agents.
|
||||
|
||||
**Structure:**
|
||||
|
||||
- Layer 1: `process-agents` — entry point, checks eligible agents
|
||||
- Layer 2: `paginate-agents` — paginates through active agents
|
||||
- Layer 3: `generate-agent` — generates welcome data for ONE agent
|
||||
|
||||
**Key features:**
|
||||
|
||||
- Filters agents who already have cached data in Redis
|
||||
- `paidOnly` flag for subscribed users' agents only
|
||||
- `dryRun` mode for statistics
|
||||
- Fan-out for large agent batches (`CHUNK_SIZE=20`)
|
||||
|
||||
**Layer 3 shape:**
|
||||
|
||||
```typescript
|
||||
export const { POST } = serve<GenerateAgentWelcomePayload>(async (context) => {
|
||||
const { agentId } = context.requestPayload ?? {};
|
||||
|
||||
const workflow = new AgentWelcomeWorkflow(db, agentId);
|
||||
const data = await context.run('generate', () => workflow.generate());
|
||||
|
||||
return { success: true, agentId, data };
|
||||
});
|
||||
```
|
||||
|
||||
**Files:**
|
||||
|
||||
- `/api/workflows/agent-welcome/process-agents/route.ts`
|
||||
- `/api/workflows/agent-welcome/paginate-agents/route.ts`
|
||||
- `/api/workflows/agent-welcome/generate-agent/route.ts`
|
||||
- `/server/workflows/agentWelcome/index.ts`
|
||||
|
||||
---
|
||||
|
||||
## What's identical, what differs
|
||||
|
||||
Both workflows are the **same pattern** — they only differ in:
|
||||
|
||||
- Entity type (users vs agents)
|
||||
- Business logic (placeholder generation vs welcome generation)
|
||||
- Data source (different database queries)
|
||||
|
||||
Everything else — the 3-layer split, dry-run handling, fan-out, filter-existing, flowControl tuning — is identical. That's the whole point: once you internalize the pattern, adding a new workflow is mostly entity-substitution.
|
||||
@@ -0,0 +1,333 @@
|
||||
# Implementation Patterns
|
||||
|
||||
Full code templates for the 3-layer architecture. Read this when actually writing workflow files.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Workflow Class](#workflow-class) — `src/server/workflows/{workflowName}/index.ts`
|
||||
2. [Layer 1: Entry Point](#layer-1-entry-point-process-) — `process-*` route
|
||||
3. [Layer 2: Pagination](#layer-2-pagination-paginate-) — `paginate-*` route
|
||||
4. [Layer 3: Execution](#layer-3-execution-execute--generate-) — `execute-*` / `generate-*` route
|
||||
|
||||
---
|
||||
|
||||
## Workflow Class
|
||||
|
||||
**Location:** `src/server/workflows/{workflowName}/index.ts`
|
||||
|
||||
```typescript
|
||||
import { Client } from '@upstash/workflow';
|
||||
import debug from 'debug';
|
||||
|
||||
const log = debug('lobe-server:workflows:{workflow-name}');
|
||||
|
||||
// Workflow paths
|
||||
const WORKFLOW_PATHS = {
|
||||
processItems: '/api/workflows/{workflow-name}/process-items',
|
||||
paginateItems: '/api/workflows/{workflow-name}/paginate-items',
|
||||
executeItem: '/api/workflows/{workflow-name}/execute-item',
|
||||
} as const;
|
||||
|
||||
// Payload types
|
||||
export interface ProcessItemsPayload {
|
||||
dryRun?: boolean;
|
||||
force?: boolean;
|
||||
}
|
||||
|
||||
export interface PaginateItemsPayload {
|
||||
cursor?: string;
|
||||
itemIds?: string[]; // For fanout chunks
|
||||
}
|
||||
|
||||
export interface ExecuteItemPayload {
|
||||
itemId: string;
|
||||
}
|
||||
|
||||
const getWorkflowUrl = (path: string): string => {
|
||||
const baseUrl = process.env.APP_URL;
|
||||
if (!baseUrl) throw new Error('APP_URL is required to trigger workflows');
|
||||
return new URL(path, baseUrl).toString();
|
||||
};
|
||||
|
||||
const getWorkflowClient = (): Client => {
|
||||
const token = process.env.QSTASH_TOKEN;
|
||||
if (!token) throw new Error('QSTASH_TOKEN is required to trigger workflows');
|
||||
|
||||
const config: ConstructorParameters<typeof Client>[0] = { token };
|
||||
if (process.env.QSTASH_URL) {
|
||||
(config as Record<string, unknown>).url = process.env.QSTASH_URL;
|
||||
}
|
||||
return new Client(config);
|
||||
};
|
||||
|
||||
export class {WorkflowName}Workflow {
|
||||
private static client: Client;
|
||||
|
||||
private static getClient(): Client {
|
||||
if (!this.client) this.client = getWorkflowClient();
|
||||
return this.client;
|
||||
}
|
||||
|
||||
static triggerProcessItems(payload: ProcessItemsPayload) {
|
||||
const url = getWorkflowUrl(WORKFLOW_PATHS.processItems);
|
||||
log('Triggering process-items workflow');
|
||||
return this.getClient().trigger({ body: payload, url });
|
||||
}
|
||||
|
||||
static triggerPaginateItems(payload: PaginateItemsPayload) {
|
||||
const url = getWorkflowUrl(WORKFLOW_PATHS.paginateItems);
|
||||
log('Triggering paginate-items workflow');
|
||||
return this.getClient().trigger({ body: payload, url });
|
||||
}
|
||||
|
||||
static triggerExecuteItem(payload: ExecuteItemPayload) {
|
||||
const url = getWorkflowUrl(WORKFLOW_PATHS.executeItem);
|
||||
log('Triggering execute-item workflow: %s', payload.itemId);
|
||||
return this.getClient().trigger({ body: payload, url });
|
||||
}
|
||||
|
||||
/**
|
||||
* Filter items that need processing (e.g. check Redis cache, database state).
|
||||
* Return only the ones that actually need work — keeps the pipeline idempotent.
|
||||
*/
|
||||
static async filterItemsNeedingProcessing(itemIds: string[]): Promise<string[]> {
|
||||
if (itemIds.length === 0) return [];
|
||||
// Check existing state and return items that need processing
|
||||
return itemIds;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layer 1: Entry Point (process-\*)
|
||||
|
||||
**Purpose:** Validates prerequisites, calculates statistics, supports dry-run mode.
|
||||
|
||||
```typescript
|
||||
import { serve } from '@upstash/workflow/nextjs';
|
||||
import { getServerDB } from '@/database/server';
|
||||
import { WorkflowClass, type ProcessPayload } from '@/server/workflows/{workflowName}';
|
||||
|
||||
export const { POST } = serve<ProcessPayload>(
|
||||
async (context) => {
|
||||
const { dryRun, force } = context.requestPayload ?? {};
|
||||
|
||||
console.log('[{workflow}:process] Starting with payload:', { dryRun, force });
|
||||
|
||||
const allItemIds = await context.run('{workflow}:get-all-items', async () => {
|
||||
const db = await getServerDB();
|
||||
// Query database for eligible items
|
||||
return items.map((item) => item.id);
|
||||
});
|
||||
|
||||
console.log('[{workflow}:process] Total eligible items:', allItemIds.length);
|
||||
|
||||
if (allItemIds.length === 0) {
|
||||
return { success: true, totalEligible: 0, message: 'No eligible items found' };
|
||||
}
|
||||
|
||||
const itemsNeedingProcessing = await context.run('{workflow}:filter-existing', () =>
|
||||
WorkflowClass.filterItemsNeedingProcessing(allItemIds),
|
||||
);
|
||||
|
||||
const result = {
|
||||
success: true,
|
||||
totalEligible: allItemIds.length,
|
||||
toProcess: itemsNeedingProcessing.length,
|
||||
alreadyProcessed: allItemIds.length - itemsNeedingProcessing.length,
|
||||
};
|
||||
|
||||
// Dry-run short-circuits before any side effects
|
||||
if (dryRun) {
|
||||
console.log('[{workflow}:process] Dry run mode, returning statistics only');
|
||||
return {
|
||||
...result,
|
||||
dryRun: true,
|
||||
message: `[DryRun] Would process ${itemsNeedingProcessing.length} items`,
|
||||
};
|
||||
}
|
||||
|
||||
if (itemsNeedingProcessing.length === 0) {
|
||||
return { ...result, message: 'All items already processed' };
|
||||
}
|
||||
|
||||
await context.run('{workflow}:trigger-paginate', () => WorkflowClass.triggerPaginateItems({}));
|
||||
|
||||
return {
|
||||
...result,
|
||||
message: `Triggered pagination for ${itemsNeedingProcessing.length} items`,
|
||||
};
|
||||
},
|
||||
{
|
||||
flowControl: {
|
||||
key: '{workflow}.process',
|
||||
parallelism: 1, // single instance — avoids duplicate processing
|
||||
ratePerSecond: 1,
|
||||
},
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layer 2: Pagination (paginate-\*)
|
||||
|
||||
**Purpose:** Handles cursor-based pagination, implements fan-out for large batches.
|
||||
|
||||
```typescript
|
||||
import { serve } from '@upstash/workflow/nextjs';
|
||||
import { chunk } from 'es-toolkit/compat';
|
||||
import { getServerDB } from '@/database/server';
|
||||
import { WorkflowClass, type PaginatePayload } from '@/server/workflows/{workflowName}';
|
||||
|
||||
const PAGE_SIZE = 50;
|
||||
const CHUNK_SIZE = 20;
|
||||
|
||||
export const { POST } = serve<PaginatePayload>(
|
||||
async (context) => {
|
||||
const { cursor, itemIds: payloadItemIds } = context.requestPayload ?? {};
|
||||
|
||||
console.log('[{workflow}:paginate] Starting:', {
|
||||
cursor,
|
||||
itemIdsCount: payloadItemIds?.length ?? 0,
|
||||
});
|
||||
|
||||
// If specific itemIds were passed in (from a fanout chunk), process them directly
|
||||
if (payloadItemIds && payloadItemIds.length > 0) {
|
||||
await Promise.all(
|
||||
payloadItemIds.map((itemId) =>
|
||||
context.run(`{workflow}:execute:${itemId}`, () =>
|
||||
WorkflowClass.triggerExecuteItem({ itemId }),
|
||||
),
|
||||
),
|
||||
);
|
||||
return { success: true, processedItems: payloadItemIds.length };
|
||||
}
|
||||
|
||||
// Paginate through all items
|
||||
const itemBatch = await context.run('{workflow}:get-batch', async () => {
|
||||
const db = await getServerDB();
|
||||
const items = await db.query(...);
|
||||
if (!items.length) return { ids: [] };
|
||||
const last = items.at(-1);
|
||||
return {
|
||||
ids: items.map((item) => item.id),
|
||||
cursor: last ? last.id : undefined,
|
||||
};
|
||||
});
|
||||
|
||||
const batchItemIds = itemBatch.ids;
|
||||
const nextCursor = 'cursor' in itemBatch ? itemBatch.cursor : undefined;
|
||||
|
||||
if (batchItemIds.length === 0) {
|
||||
return { success: true, message: 'Pagination complete' };
|
||||
}
|
||||
|
||||
const itemIds = await context.run('{workflow}:filter-existing', () =>
|
||||
WorkflowClass.filterItemsNeedingProcessing(batchItemIds),
|
||||
);
|
||||
|
||||
if (itemIds.length > 0) {
|
||||
if (itemIds.length > CHUNK_SIZE) {
|
||||
// Fan out — recursively re-enter pagination with each chunk
|
||||
const chunks = chunk(itemIds, CHUNK_SIZE);
|
||||
console.log('[{workflow}:paginate] Fanout mode:', {
|
||||
chunks: chunks.length,
|
||||
chunkSize: CHUNK_SIZE,
|
||||
});
|
||||
|
||||
await Promise.all(
|
||||
chunks.map((ids, idx) =>
|
||||
context.run(`{workflow}:fanout:${idx + 1}/${chunks.length}`, () =>
|
||||
WorkflowClass.triggerPaginateItems({ itemIds: ids }),
|
||||
),
|
||||
),
|
||||
);
|
||||
} else {
|
||||
// Process this page directly
|
||||
await Promise.all(
|
||||
itemIds.map((itemId) =>
|
||||
context.run(`{workflow}:execute:${itemId}`, () =>
|
||||
WorkflowClass.triggerExecuteItem({ itemId }),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Tail-call into the next page
|
||||
if (nextCursor) {
|
||||
await context.run('{workflow}:next-page', () =>
|
||||
WorkflowClass.triggerPaginateItems({ cursor: nextCursor }),
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
processedItems: itemIds.length,
|
||||
skippedItems: batchItemIds.length - itemIds.length,
|
||||
nextCursor: nextCursor ?? null,
|
||||
};
|
||||
},
|
||||
{
|
||||
flowControl: {
|
||||
key: '{workflow}.paginate',
|
||||
parallelism: 20,
|
||||
ratePerSecond: 5,
|
||||
},
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layer 3: Execution (execute-\* / generate-\*)
|
||||
|
||||
**Purpose:** Performs the actual business logic for exactly ONE item.
|
||||
|
||||
```typescript
|
||||
import { serve } from '@upstash/workflow/nextjs';
|
||||
import { getServerDB } from '@/database/server';
|
||||
import { WorkflowClass, type ExecutePayload } from '@/server/workflows/{workflowName}';
|
||||
|
||||
export const { POST } = serve<ExecutePayload>(
|
||||
async (context) => {
|
||||
const { itemId } = context.requestPayload ?? {};
|
||||
|
||||
if (!itemId) {
|
||||
return { success: false, error: 'Missing itemId' };
|
||||
}
|
||||
|
||||
const db = await getServerDB();
|
||||
|
||||
const item = await context.run('{workflow}:get-item', async () => {
|
||||
// Query database for item
|
||||
return item;
|
||||
});
|
||||
|
||||
if (!item) {
|
||||
return { success: false, error: 'Item not found' };
|
||||
}
|
||||
|
||||
const result = await context.run('{workflow}:process-item', async () => {
|
||||
const workflow = new WorkflowClass(db, itemId);
|
||||
return workflow.generate(); // or process(), execute(), etc.
|
||||
});
|
||||
|
||||
await context.run('{workflow}:save-result', async () => {
|
||||
const workflow = new WorkflowClass(db, itemId);
|
||||
return workflow.saveToRedis(result); // or saveToDatabase(), etc.
|
||||
});
|
||||
|
||||
return { success: true, itemId, result };
|
||||
},
|
||||
{
|
||||
flowControl: {
|
||||
key: '{workflow}.execute',
|
||||
parallelism: 10,
|
||||
ratePerSecond: 5,
|
||||
},
|
||||
},
|
||||
);
|
||||
```
|
||||
@@ -1,11 +1,13 @@
|
||||
---
|
||||
name: version-release
|
||||
description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. This skill is for release process and GitHub Release notes (not docs/changelog page writing)."
|
||||
disable-model-invocation: true
|
||||
argument-hint: '[minor|patch] [version?]'
|
||||
---
|
||||
|
||||
# Version Release Workflow
|
||||
|
||||
This skill is a router. The detailed steps live in `reference/`.
|
||||
This skill is a router. The detailed steps live in `references/`.
|
||||
|
||||
## Scope Boundary (Important)
|
||||
|
||||
@@ -30,12 +32,12 @@ The primary development branch is **canary**. All day-to-day development happens
|
||||
|
||||
Only two release types are used in practice (major releases are extremely rare and can be ignored):
|
||||
|
||||
| Type | Use Case | Frequency | Source Branch | PR Title Format | Version | Reference |
|
||||
| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | -------------------------------------- |
|
||||
| Minor | Feature iteration release | \~Every 4 weeks | canary | `🚀 release: v{x.y.0}` | Manually set | `reference/minor-release.md` |
|
||||
| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `reference/patch-release-scenarios.md` |
|
||||
| Type | Use Case | Frequency | Source Branch | PR Title Format | Version | Reference |
|
||||
| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | --------------------------------------- |
|
||||
| Minor | Feature iteration release | \~Every 4 weeks | canary | `🚀 release: v{x.y.0}` | Manually set | `references/minor-release.md` |
|
||||
| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `references/patch-release-scenarios.md` |
|
||||
|
||||
For writing the release-note body (any release type), see `reference/release-notes-style.md`.
|
||||
For writing the release-note body (any release type), see `references/release-notes-style.md`.
|
||||
|
||||
## Auto-Release Trigger Rules (`auto-tag-release.yml`)
|
||||
|
||||
@@ -85,9 +87,9 @@ Before creating the release branch, verify the source branch:
|
||||
|
||||
Pick the right reference and follow it end-to-end:
|
||||
|
||||
- **Minor release** → `reference/minor-release.md`
|
||||
- **Patch release** (weekly / hotfix / model launch / DB migration) → `reference/patch-release-scenarios.md`
|
||||
- **Writing the PR body / release notes** (any release type) → `reference/release-notes-style.md`
|
||||
- **Minor release** → `references/minor-release.md`
|
||||
- **Patch release** (weekly / hotfix / model launch / DB migration) → `references/patch-release-scenarios.md`
|
||||
- **Writing the PR body / release notes** (any release type) → `references/release-notes-style.md`
|
||||
|
||||
### Hard Rules (apply to every release type)
|
||||
|
||||
@@ -95,4 +97,4 @@ Pick the right reference and follow it end-to-end:
|
||||
- **Do NOT** manually create tags — CI handles them.
|
||||
- Minor PR title format is strict (`🚀 release: v{x.y.z}`).
|
||||
- Patch PRs do not need an explicit version number.
|
||||
- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `reference/release-notes-style.md` § Computing Inputs — never from memory or descriptions.
|
||||
- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `references/release-notes-style.md` § Computing Inputs — never from memory or descriptions.
|
||||
|
||||
+14
@@ -2,6 +2,20 @@
|
||||
|
||||
Use this guide for **GitHub Release notes** — the body of a release PR that becomes the GitHub Release after merge. Do **not** use it for `docs/changelog/*.mdx` website pages (load `../../docs-changelog/SKILL.md` instead).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Positioning](#positioning) — what this style optimizes for
|
||||
2. [Required Inputs Before Writing](#required-inputs-before-writing)
|
||||
3. [Computing Inputs (Hard Rules — Verify, Never Guess)](#computing-inputs-hard-rules--verify-never-guess) — base ref, PR refs, metrics, authors, pre-publish verification
|
||||
4. [Canonical Structure (Long-Form: Minor / Weekly)](#canonical-structure-long-form-minor--weekly)
|
||||
5. [Variants for Shorter Releases](#variants-for-shorter-releases) — hotfix, DB migration
|
||||
6. [Writing Rules (Hard)](#writing-rules-hard)
|
||||
7. [Style Rules (Long-Form)](#style-rules-long-form)
|
||||
8. [Release Size Heuristics](#release-size-heuristics) — when to use which variant
|
||||
9. [Contributor Ordering](#contributor-ordering)
|
||||
10. [Template](#template) — copy-paste skeleton
|
||||
11. [Quick Checklist](#quick-checklist) — long-form + hotfix
|
||||
|
||||
## Positioning
|
||||
|
||||
This release-note style is:
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: zustand
|
||||
description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
|
||||
description: "LobeHub Zustand store conventions: public/internal/dispatch action layers, optimistic update pattern, slice composition via `flattenActions`, and class-based action migration. Use whenever working under `src/store/**`, adding a `createXxxSlice`, writing `internal_*` or `internal_dispatch*` actions, designing `messagesMap`/`topicsMap` reducers, refactoring a `StateCreator` object slice into a `XxxActionImpl` class, or debugging stale store reads. Triggers on `useChatStore`/`useUserStore`/`useGlobalStore`, `createStore`, `flattenActions`, `StoreSetter`, `internal_dispatch`, 'add an action', 'zustand selector', 'store slice', 'class action', 'optimistic update'."
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# LobeHub Zustand State Management
|
||||
|
||||
Reference in New Issue
Block a user