跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

langium

A comprehensive skill to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration

eclipse-langium · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add eclipse-langium/langium-ai --skill langium

技能说明


name: langium description: A comprehensive skill to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration user-invocable: false

Langium SKILL.md

A comprehensive guide to understanding how Langium-based projects work — from grammar definition through code generation, runtime parsing, linking, validation, and LSP integration. Reading this document should make an agent fully proficient at navigating, debugging, and extending any Langium DSL project.


Table of Contents

  1. High-Level Architecture
  2. The Grammar Language
  3. Code Generation (Build Time)
  4. Dependency Injection System
  5. Lexing
  6. Parsing: Tokens → CST → AST
  7. The Document Lifecycle (DocumentState Pipeline)
  8. Scope Computation
  9. Scope Provider and Name Resolution
  10. Linking and Cross-Reference Resolution
  11. Validation
  12. Workspace Management
  13. LSP Integration
  14. Common Customization Patterns
  15. End-to-End Runtime Flow

1. High-Level Architecture

Langium is a language engineering framework that takes a .langium grammar file and produces a fully operational TypeScript-based DSL toolkit with LSP support. The architecture has two major phases:

Build time — langium-cli reads .langium grammars and generates:

  • ast.ts — TypeScript interfaces for every AST node, type guards, and an AstReflection class
  • grammar.ts — The grammar serialized as JSON, lazy-loaded at runtime
  • module.ts — A DI module providing Grammar, LanguageMetaData, and AstReflection services

Runtime — A service-oriented architecture driven by dependency injection:

  • All components (parser, lexer, linker, scope provider, validator, LSP handlers) are registered as services
  • Two service layers: shared services (cross-language: workspace, index, document management) and language-specific services (parser, references, validation — one set per language)
  • Users customize behavior by providing partial DI modules that override default service factories

Key dependency: Chevrotain (parser generator library) powers the lexer and parser at runtime.


2. The Grammar Language

A .langium file defines the DSL's syntax and implicitly its AST structure. Key constructs:

Parser Rules

// entry rule — the root of the AST
entry Model:
    (elements+=Element)*;

// regular rule — creates an AST node of type 'Element'
Element:
    'element' name=ID '{' attributes+=Attribute* '}';
  • entry marks the grammar's starting rule (one per grammar)
  • Assignments: = (single value), += (array append), ?= (boolean flag)
  • name=ID assigns the matched ID terminal to the name property

Cross-References

Reference:
    'ref' target=[Element:ID] ';';
  • [Element:ID] — references an Element node by matching the ID terminal
  • At parse time, creates a lazy Reference object with $refText set to the matched text
  • At link time, the ScopeProvider resolves the text to the actual target node

Actions (Type Changing)

Expression:
    Primary ({BinaryExpression.left=current} operator=('+' | '-') right=Primary)*;
  • {BinaryExpression.left=current} creates a new BinaryExpression node, assigning the previously parsed node to its left property
  • Enables left-recursive expression patterns

Infix Rules

infix Expression:
    Primary
    ('+' | '-')         // precedence 0 (lowest)
    ('*' | '/')         // precedence 1
    ('**' right-assoc); // precedence 2, right-associative
  • Declarative operator precedence and associativity
  • Operators listed top-to-bottom from lowest to highest precedence

Terminal Rules

terminal ID: /[_a-zA-Z][\w_]*/;
terminal STRING: /"(\\.|[^"\\])*"|'(\\.|[^'\\])*'/;
hidden terminal WS: /\s+/;
hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
  • hidden terminals (whitespace, comments) are excluded from the main token stream
  • Terminal order affects lexer priority; keywords always take precedence over terminals

Fragment Rules

fragment NamedElement:
    name=ID;
  • Fragments contribute properties to the calling rule's AST node without creating a new node type

Type Declarations

interface Declaration {
    name: string
}

type Literal = StringLiteral | NumberLiteral;
  • Explicit AST type declarations (alternative to grammar-inferred types)
  • returns / infers keywords control which type a parser rule produces

Imports

import './other-grammar'
  • Multi-file grammars with shared rules and types

3. Code Generation (Build Time)

The langium-cli generates three files from each grammar. Understanding what's generated is critical to understanding the runtime.

3.1 ast.ts — AST Type Definitions

For each grammar rule/type, generates:

TypeScript interface:

export interface Element extends langium.AstNode {
  readonly $type: "Element";
  name: string;
  attributes: Array<Attribute>;
}

Const object (property name literals):

export const Element = {
  $type: "Element",
  name: "name",
  attributes: "attributes",
} as const;

Type guard:

export function isElement(item: unknown): item is Element {
  return reflection.isInstance(item, Element.$type);
}

Terminal regexes and keyword types:

export const MyLangTerminals = {
  ID: /[_a-zA-Z][\w_]*/,
  STRING: /
阅读完整来源 ↗