> For AI agents: the complete documentation index is available at https://open-spaced-repetition.github.io/ts-fsrs/zh-CN/llms.txt, the full documentation bundle is available at https://open-spaced-repetition.github.io/ts-fsrs/zh-CN/llms-full.txt.

# 快速开始

已有应用升级请参阅 [v5 → v6 与 FSRS-7 迁移指南](https://open-spaced-repetition.github.io/ts-fsrs/zh-CN/guide/migration.md)。

## 安装

`ts-fsrs` 需要 Node.js 24 或更高版本。


```sh [npm]
npm install ts-fsrs
```

```sh [yarn]
yarn add ts-fsrs
```

```sh [pnpm]
pnpm add ts-fsrs
```

```sh [bun]
bun add ts-fsrs
```

```sh [deno]
deno add npm:ts-fsrs
```

只有在训练 FSRS 参数或转换复习日志 CSV 时，才需要额外安装 `@open-spaced-repetition/binding`。

## 从 DefaultScheduler 开始

`DefaultScheduler()` 是接入 FSRS 调度最快的方式。它默认使用 FSRS-7，并包含目标保留率、统计、学习步骤、最大间隔、单调间隔和已调度天数等标准策略；模糊可通过选项启用。

```ts twoslash file="../../snippets/run-code/default-scheduler.ts"
import { DefaultScheduler, Rating } from 'ts-fsrs'

const now = new Date('2026-01-01T00:00:00.000Z')
const scheduler = await DefaultScheduler({
  version: 'FSRS-7',
  desiredRetention: 0.9,
  enableShortTerm: true,
  learningSteps: ['1m', '10m'],
  relearningSteps: ['10m'],
  enableFuzz: false,
  maximumInterval: 36_500,
})
const card = scheduler.newCard({ cardId: 'quick-start', now })
const result = scheduler.review({ card, grade: Rating.Good, now })

console.log(
  JSON.stringify(
    {
      state: result.card.state,
      dueAt: result.card.dueAt,
      stability: result.card.stability,
      stabilityFast: result.card.stabilityFast,
      difficulty: result.card.difficulty,
      rating: result.revlog.rating,
    },
    null,
    2
  )
)

```


▶ 运行代码

示例显式列出了常用默认值。可以根据产品调整 `desiredRetention`、学习和重新学习步骤、模糊或 `maximumInterval`；省略 `weights` 即使用所选 FSRS 版本的预设权重。

## 创建调度器

需要选择模型或时间系统，或者自行组合 middleware 时，再使用 `defineScheduler`。它会创建可复用的 definition；`.create()` 会校验配置并返回独立的调度器。

`chrono` 定义时间的表示方式、在卡片和复习日志中的存储方式，以及如何参与调度计算，支持使用 JavaScript `Date`、Temporal 或数值表示时间。 `chrono.normalize` 使用 `ChronoTimeNormalizer` schema，将卡片或复习日志的时间字段转换为 `{ previous, current }`，供调度和撤销使用。

```ts twoslash file="../../snippets/run-code/define-scheduler.ts"
import { dateChrono, defineScheduler, Rating } from 'ts-fsrs'
import { FSRS7_DEFAULT_WEIGHTS, FSRS7Model } from 'ts-fsrs/models/fsrs-7'

// Reuse this definition as the program's scheduling preset.
const schedulerDefinition = defineScheduler({
  model: FSRS7Model,
  chrono: dateChrono,
})

// Create an independent scheduler when a user's config is available.
const scheduler = schedulerDefinition.create({
  config: {
    weights: FSRS7_DEFAULT_WEIGHTS,
    fractionalDays: true,
  },
})

const now = new Date('2026-01-01T00:00:00.000Z')
const card = scheduler.newCard({ now })
const result = scheduler.review({ card, grade: Rating.Good, now })

console.log(
  JSON.stringify(
    {
      state: result.card.state,
      dueAt: result.card.dueAt,
      stability: result.card.stability,
      difficulty: result.card.difficulty,
      stabilityFast: result.card.stabilityFast,
      rating: result.revlog.rating,
    },
    null,
    2
  )
)

```


▶ 运行代码

:::note 复用调度器定义
将 `defineScheduler(...)` 的结果（包括通过 `.use(...)` 组合好的 middleware）保留为程序级预设。用户或集合需要调度器时，再调用 `schedulerDefinition.create({ config })`；每次调用都会校验该配置并返回独立实例。
:::

代码块自带的复制按钮会复制原始源码；也可以直接在专用 Worker 中运行。固定的 `now` 让输出保持可复现。

- `newCard()` 创建符合该调度器默认结构的新卡片。
- `review()` 返回新的卡片和复习日志，不会修改输入卡片。
- 在可复用 definition 上通过 `.use(...)` 组合策略 middleware，再创建用户专属的调度器。