OpenInsightDev 开源 trajs：将 AI 模型会话记录为轨迹

Record, version and analyze AI model sessions as trajectories.

A session with an AI model is recorded for evaluation, debugging and analysis. trajs records the conversation a model ran on — the messages it was given and the parts it returned — as a trajectory that stays attached to the toolkit and metadata it was recorded with, so it can be stored, replayed and inspected.

A trajectory is a stream of parts — the messages sent to a model, the responses it returned, and the session declarations that mark where a session starts and what it continues from — sharing one total order. trajs is built on Effect and reuses the vocabulary of effect/ai: a Trajectory is a Stream, and tools are Tools collected into a Toolkit.

trajs targets the same problem as ATIF, the Agent Trajectory Interchange Format, and aims to be a strict superset. Where ATIF models a run as a document, trajs models it as a stream of parts that stays attached to the context it was recorded in.

Highlights

• A trajectory is a stream, not a document. Prompt parts, response parts and session declarations share one total order, so a consumer that only knows about messages cannot silently drop the rest.
• Toolkits round-trip. A toolkit serializes to draft-07 JSON Schema, and a recording made against an empty or older toolkit is decoded again against the tools it actually refers to, regaining their exact names, parameters and results.
• Tolerant by design. Tools outside the toolkit decode to unconstrained parts instead of failing, so loading recorded history never depends on the tools installed today.
• Sessions derive. A session records where it continues from, so forks, resumes and sub-agents can be reconstructed from the recording.
• Tool calls come with their results. Toolkit.toolTurns correlates each recorded tool call with the result that answers it, narrowed to the tool's types.
• One interchange format. A .trajs file is newline-delimited JSON with the header first.

Install

Important

trajs is pre-release: the packages are not on npm yet and the API can still change. The package will be installed with:

pnpm add @trajs/core effect

Until then, work in this repository and import the package from the workspace.

Quick start

Record a prompt and encode the trajectory as a .trajs file:

import { Effect, Stream } from "effect";
import { Prompt, Toolkit } from "effect/ai";
import { Persist, Trajectory } from "@trajs/core";

const trajectory = Trajectory.make(
  Stream.make(Trajectory.promptPart(Prompt.make("Hello"))),
  Toolkit.empty,
  Trajectory.Metadata.make({ name: "greeting" }),
);

const records = await Effect.runPromise(Stream.runCollect(Persist.encode(trajectory)));

Load a recording with Persist.decode, Persist.read or Persist.encode.

The .trajs format

A recording is plain JSONL: line 1 is a header carrying the metadata (including its version, the @trajs/core version that wrote the recording) and the serialized toolkit; every later line is a part, discriminated by _tag. The header carries no _tag — _tag means "this is a part" — so the two are impossible to confuse.

{"metadata":{"version":"<trajs version>"},"toolkit":{}}
{"_tag":"Prompt","uuid":"0192...","timestamp":"...","messages":[]}
{"_tag":"Response","uuid":"0192...","timestamp":"...","response":{}}

Documentation

The full documentation lives at openinsightdev.github.io/trajs (a tra.js.org domain is pending approval):

• Getting started
• Trajectories
• Toolkits and recorded tools
• The .trajs format
• Vision and roadmap
• API reference

The site is built with Astro Starlight from apps/website/src/content/docs and published by .github/workflows/deploy.yml.

Repository layout

Each public module of packages/core is a namespace and a subpath import, such as @trajs/core/Trajectory or @trajs/core/Persist; everything under @trajs/core/internal/* is private.

Development

Requires Node.js >=22.18.0. The repository uses Vite+ (vp) with pnpm; run vp install once after cloning.

vp install        # install dependencies
vp check          # format, lint and type-check
vp run -r test    # run the test suites
vp run -r build   # build every package and the docs site
vp run ready      # check + tests + builds, the aggregate gate
vp run dev        # docs dev server (vp run website#dev)

Status

trajs is an early, pre-release project. The library lives in packages/core, and the remaining design questions — including ATIF interoperability — are tracked in the vision and roadmap.

License

MIT.