home / skills / lobehub / lobe-chat / debug

debug skill

safe

This skill helps you implement and interpret debug logging with namespace conventions and format specifiers for efficient troubleshooting.

npx playbooks add skill lobehub/lobe-chat --skill debug

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
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.
user-invocable: false
---

# Debug Package Usage Guide

## Basic Usage

```typescript
import debug from 'debug';

// Format: lobe-[module]:[submodule]
const log = debug('lobe-server:market');

log('Simple message');
log('With variable: %O', object);
log('Formatted number: %d', number);
```

## Namespace Conventions

- Desktop: `lobe-desktop:[module]`
- Server: `lobe-server:[module]`
- Client: `lobe-client:[module]`
- Router: `lobe-[type]-router:[module]`

## Format Specifiers

- `%O` - Object expanded (recommended for complex objects)
- `%o` - Object
- `%s` - String
- `%d` - Number

## Enable Debug Output

### Browser

```javascript
localStorage.debug = 'lobe-*';
```

### Node.js

```bash
DEBUG=lobe-* npm run dev
DEBUG=lobe-* pnpm dev
```

### Electron

```typescript
process.env.DEBUG = 'lobe-*';
```

## Example

```typescript
// src/server/routers/edge/market/index.ts
import debug from 'debug';

const log = debug('lobe-edge-router:market');

log('getAgent input: %O', input);
```

Overview

This skill documents how to use the debug package for consistent, namespaced logging across the codebase. It explains namespace conventions, format specifiers, and how to enable debug output in browser, Node, and Electron environments. Use it to add targeted debug statements without cluttering production logs.

How this skill works

It shows how to create a logger with debug('lobe-[component]:[module]') and then call log(...) with format specifiers for structured output. The guide defines standard namespaces for desktop, server, client, and routers so log output can be filtered by area. It also covers enabling debug output via localStorage, environment variables, or process.env depending on runtime.

When to use it

Adding debug logging during feature development or troubleshooting
Instrumenting request handlers, routers, and background tasks
Inspecting complex objects or function inputs/outputs
Filtering logs by subsystem during local dev or CI debugging
Implementing per-module debug flags in Electron apps

Best practices

Use the lobe-[component]:[module] convention to keep namespaces consistent
Prefer %O for complex objects to get expanded, inspectable output
Keep debug calls lightweight; avoid heavy synchronous work inside log statements
Enable debug only in development or targeted runs (DEBUG or localStorage) to avoid noise
Document new namespaces when adding modules so team members can enable them easily

Example use cases

Server router: const log = debug('lobe-server:market'); log('getAgent input: %O', input)
Desktop component: debug('lobe-desktop:auth') to trace auth flows and UI triggers
Client feature flagging: debug('lobe-client:featureX') to confirm client-side behavior
Edge router development in Electron: process.env.DEBUG = 'lobe-*' for full trace during manual testing
Ad-hoc local debugging: localStorage.debug = 'lobe-server:market' to focus only on market logs

FAQ

How do I see logs only for one module?

Set the debug filter to that namespace, e.g., DEBUG=lobe-server:market or localStorage.debug = 'lobe-server:market' in the browser.

Which format specifier should I use for objects?

Use %O for expanded, detailed object output; %o is a compact object, %s for strings, %d for numbers.