raman/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Raman TUI: a Windows terminal application for controlling Raman spectrometers and filter wheels. The TUI accepts text commands (e.g. spec scan, filter connect f1) and also supports natural-language input via a DeepSeek LLM agent that translates prompts into those commands.

Build & Test Commands

# Build everything (solution file is roman.slnx, not .sln)
dotnet build roman.slnx

# Run all tests (xUnit)
dotnet test roman.slnx

# Run a single test project
dotnet test test/Roman.Host.Tests
dotnet test test/Raman.TUI.Tests

# Run a single test by filter
dotnet test test/Roman.Host.Tests --filter "FullyQualifiedName~DiscoverFiltersUseCaseTests"

# Run the TUI in simulation mode (no hardware needed)
dotnet run --project src/Raman.TUI -- --simulate

The target framework is net10.0. The solution uses the .slnx format (XML-based solution file).

Architecture

Layer structure (bottom to top)

Raman.Core — Hardware abstractions. Defines ISpectrometerDevice, IFilterWheelDevice, and their associated data types (settings, capabilities, spectra). No implementations here.

Spec.Sea — Spectrometer driver for the Sea SDK. Wraps a native C DLL (SeaSDK.dll) via LibraryImport P/Invoke in SeaSdkNativeMethods. SeaSdkGateway provides a managed facade; SeaSpectrometerDevice/SeaSpectrometerDiscovery implement the Core interfaces. Uses AllowUnsafeBlocks. The native DLL lives outside this repo at ../main/externals/SeaSDK.dll and is copied to output.

Filter.Ello — Filter wheel driver for Elliptec serial-protocol devices. Communicates over COM ports (System.IO.Ports). SerialProtocol encodes/decodes the Elliptec hex-based command format. Supports 4-slot and 6-slot wheels.

Raman.Simulator — In-memory fakes of both spectrometers and filter wheels. Used for development and testing without hardware. Activated by --simulate flag or RAMAN_TUI_SIMULATE=1 env var.

Roman.Host — Business logic orchestration layer. Contains:

• SpectrometerRuntimeWorkspace / FilterRuntimeWorkspace — stateful command dispatchers that manage device lifecycle (discover, connect, configure, acquire, disconnect).
• Request/response contracts (SpectrometerRequest/SpectrometerResponse, FilterRequest/FilterResponse) with command-kind enums.
• Filter discovery subsystem that scans COM ports for Elliptec devices.
• Filter configuration persistence (JSON-based FilterConfigurationStore).

Raman.TUI — The terminal application. Key components:

• ICommandSession — interface for command handlers. FilterCommandSession and SpectrometerCommandSession parse text commands and delegate to Roman.Host workspaces. CompositeCommandSession routes to the right handler.
• InlineConsoleApp — custom TUI rendering engine using low-level Console APIs and a Windows-specific ConsoleInputReader (reads raw input events). Manages a scrollable log of NotificationEntry items and a single-line input bar.
• DeepSeekLlmSession — LLM integration via Microsoft.Agents.AI.OpenAI. Configured from raman-agent.toml (TOML format, loaded from app base directory). Environment variables DEEPSEEK_API_KEY and DEEPSEEK_MODEL override the config file.

RamanTester — Standalone x86 console app for direct Sea SDK testing. Targets x86 (PlatformTarget=x86) because the native Sea SDK DLL is 32-bit.

Key patterns

• Commands flow as: user text -> ICommandSession.ExecuteAsync -> *RuntimeWorkspace.HandleAsync -> ISpectrometerDevice/IFilterWheelDevice method.
• All command sessions return IReadOnlyList<NotificationEntry> which the TUI renders as log lines.
• Background commands use publishAsync callback to stream entries to the UI incrementally.
• The LLM agent uses tool calling — TuiLlmCommandTool.RunTuiCommandAsync executes TUI commands on behalf of the LLM and returns results as text.

Code Conventions

• File-scoped namespaces (csharp_style_namespace_declarations = file_scoped).
• LF line endings, UTF-8, spaces for indentation.
• 2-space indent for XML/csproj files.
• Commit messages are in Chinese.
• The project language mixes English (code) and Chinese (UI strings, LLM instructions, commit messages).