Skip to content
Projects

ydflow/Trail has 208 GitHub stars and 37 forks. GitHot measured 0 stars in 24 hours, +1 in 7 days, and +3 in 15 days. Last checked 2026-11-17 00:19 UTC. Last push 2026-11-11.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
+1
in 15 days
+3
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

研迹 Trail|本地优先的 AI 投资研究工作台。连接行情、K 线与深度研究,让判断可追溯、风险可复核。Local-first AI investment research desktop with an evidence-grounded copilot.

AI

README.en.md

Original

Trail · 研迹

Trail · 研迹

English · 简体中文

From market signals to investment theses. Keep the evidence behind every decision.
A local-first AI research desktop connecting market data, charts, agents, evidence and ongoing review.

Preview · Capabilities · Quick start · Architecture · Contributing

Main checks 0.4.0-beta.2 source channel Electron, React and TypeScript

Why Trail

Quotes, news, financial statements and chat answers often live in separate windows. Once research is over, the conclusion survives but its assumptions, source freshness and reasons for revision are harder to reconstruct.

Trail brings that workflow into one desktop: discover a signal → inspect a security → run research → check evidence → save a thesis → review what changed. It serves individual public-market researchers and offers an inspectable implementation for developers building agent applications.

研迹 (yán jì) combines research and traces. A trail is a research path you can follow again, back to the evidence behind a judgment.

Beta, with Windows x64 installer and portable downloads. Trail provides read-only research and decision support, with no order placement or automated trading. Model analysis and confidence scores are not guarantees of accuracy or investment returns.

Product preview

Deep Research: charts, evidence and judgment in one workspace

New Deep Research workspace with NVDA chart, evidence table and decision rail

Inspect a security alongside its chart, evidence and decision rail. Completed reports include section findings, risks and catalysts, with an action to save the research as a thesis.

Securities workspace and AI copilot

Live Longbridge chart and a DeepSeek copilot answer with source links

Watchlists, quotes, financials, news and charts share the focused security. The copilot retrieves structured data and streams explanations, with sources accessible beside its answer.

Inspect the source behind a claim

Source Inspector showing financial values, provider, timestamps, lineage and snapshot hash

Open a citation to inspect values, provider, retrieval time, normalization lineage and snapshot hash. Missing quote timestamps, stale sources and unavailable data retain visible states.

More workspaces

Today Discover
Today overview Discovery task catalog
Watchlist moves, events, briefs and research entry points. Market, fundamental, technical and event screening tasks.
Portfolio Events & catalysts
Sample portfolio Events
Allocation, holdings and actions to start research. Earnings and macro events with research context.
Skills Evaluation
Skill hub Evaluation Center
Readiness based on capability dependencies. Experiments, baselines, failure modes and feedback.
Settings Tracing & privacy
Settings Evaluation settings
Models, language, themes, connections and diagnostics. Optional Langfuse / LangSmith configuration and privacy controls.

Profile and security workspace health checks

Structured answers: quotes, holdings and risk

Current copilot metric cards and time series with explicit sample data labels

Portfolio holdings table Portfolio risk comparison
Structured portfolio answer Structured risk answer

All three answers were executed in the current Electron client with the deterministic local agent and sample data, including source and evidence entry points.

Screenshot provenance: These are actual Windows Electron screens built from the current source. Research, the securities workspace and Source Inspector use public Longbridge data and a configured DeepSeek model. Today, Portfolio, Discover and Events use built-in sample content in a separate demonstration profile; balances and holdings are not a real account. Evaluation shows a 15-case offline fixture experiment; Settings shows configuration surfaces. Neither demonstrates live-model quality or verified cloud tracing. Prices, news, report stance and confidence are capture-time snapshots. See the capture and verification record.

Core capabilities

1. A workspace centered on securities

  • Watchlists and security search connect quotes, charts, overview, financials and news.
  • Multiple chart periods, OHLCV readouts and moving averages; persistent refresh, light/dark theme and copilot controls.
  • The research workspace brings chart, evidence table, stance, confidence, risks and next actions together. Unestablished targets and horizons remain —.
  • Compare 2–4 securities across valuation, growth, profitability, dividends, ratings and momentum, subject to provider coverage.

2. Deep Research: collect facts, then synthesize

  • 8 strategies: comprehensive, value, growth, technical, earnings, event-driven, risk review and income.
  • Strategy presets select typed capability plans. Bounded concurrent retrieval feeds agent synthesis, with timeout, cancellation and partial-completion states.
  • Reports contain stance, confidence, section verdicts, bull/bear cases, catalysts, risks and links to capability evidence.
  • Report history and Research Diff track changes in conclusions, valuation, risks and confidence. Export Markdown or a share card.
  • Durable checkpoints save the plan and completed evidence. Interrupted runs can resume, restart or be discarded; resume reuses saved results and retains uncertain-read retry and budget records. Recovery design

3. A context-aware agent copilot

  • Pi runtime powers persistent conversations, streaming, model selection, thinking levels and stop controls. A deterministic local runtime supports development and demonstrations.
  • The active security, page and selected position supply workspace context.
  • Markdown, structured quote/portfolio cards, tool progress and run tracing; invalid structured blocks fall back to text.
  • The main process owns sessions, messages and runs, which can reload after restart. Internal research synthesis sessions stay out of the visible chat history.

4. Citations and evidence lineage

  • Providers normalize financial data into a shared capability contract consumed by both UI and agent tools.
  • Citations resolve to tool sources. Source Inspector exposes values, provider, timestamps, freshness, lineage and snapshot hashes.
  • Missing data, failed capabilities and partial reports remain explicit, preventing missing evidence from being treated as a negative finding.
  • External news is treated as untrusted input. See the prompt injection defenses and verification scope.

5. Discovery and ongoing review

  • 17 deterministic screening tasks cover movers, fundamentals, technicals and events. Candidates carry evidence into research, comparison or watchlists. Rules operate on the selected security universe, not an unrestricted market-wide scan.
  • Today brings together watchlist moves, market pulse, portfolio attention, alerts, events, recent research and theses due for review.
  • Save reports as editable theses and reassess them with new data. Alert rules cover price, news, earnings, ratings, dividends, position weight and drawdown.
  • Read-only broker portfolio access and manual imports support allocation, concentration, large positions, exposure and risk review.

6. Extension and evaluation surfaces

  • A single capability registry connects providers, agent tools, research workflows, UI and skill readiness.
  • SKILL.md packages declare dependencies, support enable/disable and load instructions and references progressively.
  • Evaluation Center exposes experiments, baselines, model comparisons, failure modes, case details and feedback. The trail-agent-v1 dataset contains 86 cases, alongside a separate Deep Research gold dataset.
  • Fixture evaluation and live-model experiments are separate validation modes. Langfuse / LangSmith tracing is optional; evaluation workflows currently run manually. Evaluation · Langfuse integration

How it works

flowchart TB
  UI[React workspace and Copilot] <-->|Allowlisted IPC and events| HOST[Electron main process · AgentKernelHost]
  HOST --> KERNEL[AgentKernel · Sessions / Runs / Events]
  KERNEL --> PI[Pi Runtime · LLM providers]
  KERNEL --> LOCAL[Deterministic local runtime]
  HOST --> WORK[Research / Screening / Compare / Theses / Alerts]
  WORK --> CAP[Typed capability registry]
  PI -->|Tools| CAP
  CAP --> ROUTER[Provider Router]
  ROUTER --> LB[Longbridge · Market data and read-only accounts]
  ROUTER --> MASSIVE[Massive · Selected US data]
  HOST --> STORE[Local JSON stores / Research checkpoints]
  PI --> SESSIONS[Pi JSONL sessions]
  HOST -. Optional tracing .-> OBS[Langfuse / LangSmith]

The main process owns business state; the renderer presents it. React/Jotai acts as the view layer behind an allowlisted preload bridge. Providers integrate through shared capability contracts, with vendor details contained in adapters. Sessions and research use local file persistence; credentials are managed in the main process with Electron safeStorage encryption. Architecture

Directory Responsibility
apps/electron Main process, preload, renderer entry and E2E
packages/core Domain models and capability/provider contracts
packages/shared Kernel, runtimes, storage, research and product services
packages/ui React/Jotai workbench, charts and copilot
packages/longbridge-tools Longbridge CLI execution, validation and integration
packages/pi-extension Pi tools and synthesis boundary
packages/skill-hub · skills Skill discovery, dependencies and progressive loading
packages/i18n Chinese/English resources and language preferences

Quick start

Windows downloads

Get v0.4.0-beta.2: Installer · Portable · Release notes and SHA-256.

These Windows packages are unsigned; Windows may report an unknown publisher. Install Bun and configure a model for AI features; install and authorize Longbridge CLI separately for market data. The desktop app, 13 skills and Pi extensions are included. Pi may download its runtime on first use. See the Windows release record.

Run from source

Install Git, Bun and Node.js (used by Electron E2E scripts). The current version is 0.4.0-beta.2, available as source and Windows packages.

git clone https://github.com/ydflow/Trail.git
cd Trail
bun install
bun run build:electron

Windows CMD:

start-trail.cmd

The launcher discovers Longbridge in its standard user directory and prefers a native bunx.exe that Pi subprocesses can execute. Bun workspace installation on Windows needs symlink permissions; enabling Developer Mode is recommended.

macOS / Linux source entry point:

FINAGENT_FORCE_PROD_LOAD=1 bunx electron apps/electron/src/main/index.js

This is a source launch command, not cross-platform packaging acceptance. bun run dev starts only the Vite renderer server. For hot reload, run bunx electron apps/electron/src/main/index.js in another terminal with FINAGENT_FORCE_PROD_LOAD unset. Opening Vite in a regular browser does not provide the full Electron IPC bridge.

Connect a model and market data

  1. Configure, test and select a model under Settings → LLM. Built-in and custom compatible providers are supported; the Pi CLI/runtime must be executable by the current process.
  2. Install the official Longbridge CLI, then authorize it through Settings → Connections or longbridge auth login.
  3. Open a security from the watchlist, inspect its chart or enter Research, choose a strategy and start Deep Research.
  4. Inspect report evidence or chat sources, then save a judgment as a Thesis for later review.

Some product surfaces fall back to built-in samples before services are connected. Data outside sample coverage keeps an empty/error state. Real market coverage, delay, financials and account permissions depend on the provider and account authorization.

For a deterministic local agent on Windows CMD:

set "FINAGENT_AGENT_PROVIDER=local"
start-trail.cmd

Optionally set FINAGENT_DEMO_DATA=1 for capability-level sample fallback when real providers are unavailable. Clear these variables to return to the configured live runtime.

Development commands

Command Purpose
bun run dev Vite renderer development server
bun run build Workspace packages and Electron build
bun run typecheck Workspace type checking
bun run test:unit Isolated unit/integration suite
bun run test:e2e Electron golden-path E2E
bun run --cwd apps/electron test:typed-blocks Structured answer block Electron verification
bun run i18n:check Chinese/English resource parity
bun run eval:smoke -- --mode fixture Deterministic offline evaluation
bun run eval:full Full evaluation entry; live mode requires separate configuration
bun run release:check Release gates
bun run release:package Current macOS arm64 packaging workflow

Engineering and current boundaries

  • Local-first: sessions, messages, reports and checkpoints live on the device. Configured models, market providers and enabled tracing still receive their respective requests; local-first does not mean all processing is offline.
  • Desktop isolation: context isolation, disabled Node integration, sandboxing and an allowlisted preload bridge. Credentials stay in the main process.
  • Recoverable execution: checksummed checkpoints, atomic writes, saved-evidence reuse, configuration identity checks and persistent budgets. Remote reads may be retried; neither exactly-once execution nor every power-loss scenario is guaranteed.
  • Inspectable output: tool progress, source inspection, report export and optional tracing. Tracing defaults off, with separate privacy and credential settings.
  • Visible gaps: live research can be partial. Pre-market, delayed and timestamp-free quotes require source context. Model output can trigger structured-block fallback, and report language depends on the model response.
  • Delivery scope: Windows x64 Beta installer and portable builds have been checked for installation outside the repo, a live-model quote response and persistent records; see the Windows release record. Windows packages are unsigned. macOS arm64 packaging is configured, with no accepted installer for this version. Product screenshots have a separate verification record.

Documentation and contributing

Document Contents
Architecture Processes, kernel, IPC, runtimes and persistence
Product requirements · UI system Product goals and interface conventions
Longbridge auth · Skill setup Provider and capability configuration
Research recovery · Existing acceptance report Recovery design and distinct validation layers
Evaluation · Benchmark Datasets, evaluators and experiments
Langfuse tracing Optional tracing and privacy boundaries
Release gates · Provider coverage Delivery checks and known limits
Contributing Commit conventions, test evidence and screenshots

Issues and focused contributions are welcome around provider adapters, research quality, evidence inspection, desktop interaction and reproducible regressions. Priorities include broader provider coverage, report reading/comparison, more reliable model output contracts and cross-platform distribution.


Trail · 研迹 — Research that leaves a trace.