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

# 快速開始

既有應用程式升級請參閱 [v5 → v6 與 FSRS-7 遷移指南](https://open-spaced-repetition.github.io/ts-fsrs/zh-TW/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，再建立使用者專屬的排程器。