Agent Skills › lichtblick-suite/lichtblick › message-path

message-path

GitHub

提供ROS/Foxglove消息路径的DSL解析、语法说明及数据提取指南，涵盖AST构建、性能优化与React Hook集成，服务于Plot等面板的数据展示。

.github/skills/message-path/SKILL.md lichtblick-suite/lichtblick

Trigger Scenarios

需要解析或理解message-path语法时实现基于消息路径的数据提取功能时优化消息数据处理性能时

Install

npx skills add lichtblick-suite/lichtblick --skill message-path -g -y

More Options

Non-standard path

npx skills add https://github.com/lichtblick-suite/lichtblick/tree/develop/.github/skills/message-path -g -y

Use without installing

npx skills use lichtblick-suite/lichtblick@message-path

指定 Agent (Claude Code)

npx skills add lichtblick-suite/lichtblick --skill message-path -a claude-code -g -y

安装 repo 全部 skill

npx skills add lichtblick-suite/lichtblick --all -g -y

预览 repo 内 skill

npx skills add lichtblick-suite/lichtblick --list

SKILL.md

Frontmatter

{
    "name": "message-path",
    "description": "Deep knowledge about the message-path package: path syntax, parsing grammar, data extraction from nested messages, and React hook integration. Shared across Plot, RawMessages, StateTransitions, and general panel agents."
}

Message Path Skill

Overview

The message-path package (packages/message-path/) provides a DSL for addressing fields within ROS/Foxglove messages. It's the foundation for user-defined data extraction in multiple panels.

⚠️ Code is split across two locations: parsing/grammar lives in packages/message-path/src/ (e.g. parseMessagePath.ts), but the data-extraction helpers (simpleGetMessagePathDataItems.ts, useCachedGetMessagePathDataItems.ts) live in packages/suite-base/src/components/MessagePathSyntax/.

Path Syntax

/topic.field.nested_field
/topic.field[:]{value==42}
/topic.field[0]
/topic.field.@length

Components

Topic: /topic_name — selects messages from a topic
Field access: .field — navigates into message fields
Array index: [0], [1] — selects specific array element
Array slice: [:] — iterates over all array elements
Filter: {field_name==value} — filters array elements by field value
Special: .@length — returns array length instead of elements

Parsing

Located in packages/message-path/src/parseMessagePath.ts:

Uses nearley grammar for parsing (context-free grammar)
Parses path string → MessagePath AST
Results are cached (same string → same parsed object)

MessagePath Type

type MessagePath = {
  topicName: string;
  topicNameRepr: string;
  messagePath: MessagePathPart[];
  modifier?: string;
};

type MessagePathPart =
  | { type: "name"; name: string; repr: string }
  | { type: "slice"; start?: number; end?: number }
  | { type: "filter"; path: string[]; value: unknown; repr: string };

Data Extraction

packages/suite-base/src/components/MessagePathSyntax/simpleGetMessagePathDataItems.ts:

function simpleGetMessagePathDataItems(
  messages: MessageEvent[],
  path: MessagePath,
): MessagePathDataItem[];

Recursively traverses message objects following the parsed path
Handles nested fields, array slicing, filtering
Returns { value, path, constantName? } for each extracted datum

Performance Characteristics

Recursive traversal — depth depends on path complexity
Array slicing with filter can be O(n) per message
Used in hot paths (every render frame for Plot panel)
Memoization is critical — see React integration below

React Integration

packages/suite-base/src/components/MessagePathSyntax/useCachedGetMessagePathDataItems.ts:

function useCachedGetMessagePathDataItems(paths: string[]): CachedGetMessagePathDataItems;

React hook that caches extraction results
Uses global variable filling pattern for performance (avoids closure allocations)
Results are memoized per (path + message identity) — same messages + same path = cached result
Critical for panels displaying multiple paths (Plot with 10+ series)

Usage by Panels

Panel	How it uses message-path
Plot	Extracts numeric time series from messages for each configured path
RawMessages	Navigates to specific fields for display/filtering
StateTransitions	Extracts discrete state values for timeline visualization
General panels	Any panel using `useMessagesByPath` or `useMessageDataItem`

Common Patterns

Panel settings with message paths

// User configures paths in panel settings
config.paths = ["/odom.pose.position.x", "/odom.twist.linear.x"];

Extracting data in a panel

const pathItems = useCachedGetMessagePathDataItems(config.paths);
// Returns extracted values for each path, memoized

Performance Tips

Parse paths once and reuse the MessagePath object (parsing uses nearley, not free)
Use useCachedGetMessagePathDataItems over manual extraction (handles memoization)
Avoid deeply nested paths with array filters on high-frequency topics
Path changes trigger full re-extraction — minimize path reconfiguration during playback