Back to Details

readwise-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Readwise API

Readwise API

Connect to Readwise APIs to fetch and analyze reading activity.
对接Readwise API以获取并分析阅读活动。

Overview

概述

Fetch saved articles, highlights, and identify most-highlighted content from user's Readwise account for any date range. Uses Readwise v2 Highlights API and v3 Reader API.
Default behavior: Last 7 days (when no date flags specified)
从用户的Readwise账户中获取任意日期范围内的已保存文章、高亮内容，并识别高亮最多的内容。使用Readwise v2 Highlights API和v3 Reader API。
默认行为：过去7天（未指定日期标志时）

Prerequisites

前置条件

API Token: Set 
READWISE_API_TOKEN
environment variable
Dependencies: Installed via pnpm (auto on first use)
  • chalk (terminal colors)
  • ora (spinners)
  • TypeScript support
API令牌：设置
READWISE_API_TOKEN
环境变量
依赖项：通过pnpm安装（首次使用时自动安装）
  • chalk（终端颜色工具）
  • ora（加载动画工具）
  • TypeScript支持

Date Range Options

日期范围选项

All commands support flexible date ranges via flags:
所有命令都支持通过标志设置灵活的日期范围：

Preset Shortcuts

预设快捷方式

  • --today
    : Midnight today → now
  • --yesterday
    : Yesterday (full day)
  • --last-week
    : Last 7 days (default when no flags specified)
  • --last-month
    : Last 30 days
  • --today
    ：今日零点至今
  • --yesterday
    ：昨日全天
  • --last-week
    ：过去7天（未指定标志时的默认值）
  • --last-month
    ：过去30天

Custom Ranges

自定义范围

  • --from YYYY-MM-DD
    : Start date (inclusive)
  • --to YYYY-MM-DD
    : End date (inclusive)
  • Can use together: 
    --from 2025-01-01 --to 2025-01-07
  • --from YYYY-MM-DD
    ：起始日期（包含）
  • --to YYYY-MM-DD
    ：结束日期（包含）
  • 可组合使用：
    --from 2025-01-01 --to 2025-01-07

Examples

示例

bash
undefined
bash
undefined

Today only

仅今日

pnpm tsx scripts/fetch-todays-activity.ts articles --today
pnpm tsx scripts/fetch-todays-activity.ts articles --today

Yesterday

昨日

pnpm tsx scripts/fetch-todays-activity.ts highlights --yesterday
pnpm tsx scripts/fetch-todays-activity.ts highlights --yesterday

Custom range

自定义范围

pnpm tsx scripts/fetch-todays-activity.ts all --from 2025-01-01 --to 2025-01-07
pnpm tsx scripts/fetch-todays-activity.ts all --from 2025-01-01 --to 2025-01-07

Default (no flags) = last 7 days

默认（无标志）= 过去7天

pnpm tsx scripts/fetch-todays-activity.ts all

**Note**: Reader API doesn't support end dates natively. Articles filtered client-side for accurate date ranges.
pnpm tsx scripts/fetch-todays-activity.ts all

**注意**：Reader API本身不支持结束日期。文章会在客户端进行过滤以确保日期范围准确。

Core Capabilities

核心功能

Default: Comprehensive Activity Summary

默认：全面活动汇总

Command:
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all [date-flags]
Output: Four-section analysis w/ insights-first approach:
  1. 🧠 Key Learnings
    • Top 5 insights extracted from highlight content
    • Domain-tagged bullets (emoji + category: insight)
    • Reading context paragraph (pattern + domain mix)
  2. 📈 Activity Timeline
    • Daily breakdown w/ visual bars (unicode blocks)
    • Peak days identified
    • Reading pattern analysis (consistent/burst/weekend/weekday)
  3. 📂 By Category
    • Domain grouping w/ visual bars + percentages
    • Auto-inferred from content (Architecture, Performance, Psychology, etc.)
    • Top 2 focus areas highlighted
  4. 📊 Stats Dashboard
    • Articles saved, highlights created
    • Unique sources, avg/day
    • Top source by highlight count
When to use: User asks "Show my Readwise activity", "What have I been learning?", "My reading summary"
命令：
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all [date-flags]
输出：四部分分析，以见解为优先的呈现方式：
  1. 🧠 核心知识点
    • 从高亮内容中提取的前5条核心见解
    • 带领域标签的项目符号（表情符号 + 分类：见解）
    • 阅读上下文段落（模式 + 领域混合）
  2. 📈 活动时间线
    • 每日细分，搭配可视化进度条（Unicode块）
    • 识别高峰日期
    • 阅读模式分析（持续型/爆发型/周末型/工作日型）
  3. 📂 按分类划分
    • 领域分组，搭配可视化进度条 + 占比
    • 根据内容自动推断分类（架构、性能、心理学等）
    • 突出显示前2个重点领域
  4. 📊 数据仪表盘
    • 已保存文章数、已创建高亮数
    • 唯一来源数、日均数量
    • 高亮数最多的来源
适用场景：用户询问“展示我的Readwise活动”、“我最近在学什么？”、“我的阅读汇总”

Individual Modes

独立模式

1. Key Learnings Only

1. 仅核心知识点

Command:
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings [date-flags]
Output: Insights + context only (no timeline/stats)
When to use: User wants just the learnings/insights
命令：
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings [date-flags]
输出：仅包含见解 + 上下文（无时间线/统计数据）
适用场景：用户仅需知识点/见解

2. Activity Timeline Only

2. 仅活动时间线

Command:
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline [date-flags]
Output: Daily activity visualization + peaks + pattern
When to use: User asks "When am I most active?" or "Show my reading schedule"
命令：
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline [date-flags]
输出：每日活动可视化 + 高峰识别 + 模式分析
适用场景：用户询问“我什么时候最活跃？”或“展示我的阅读日程”

3. Category Breakdown Only

3. 仅分类细分

Command:
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories [date-flags]
Output: Domain distribution w/ visual bars
When to use: User asks "What topics am I focusing on?" or "My reading categories"
命令：
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories [date-flags]
输出：领域分布搭配可视化进度条
适用场景：用户询问“我关注哪些主题？”或“我的阅读分类”

4. Stats Dashboard Only

4. 仅数据仪表盘

Command:
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard [date-flags]
Output: Stats summary box
When to use: User wants quick metrics only
命令：
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard [date-flags]
输出：统计数据汇总框
适用场景：用户仅需快速查看指标

Legacy Modes (Still Available)

遗留模式（仍可用）

Articles

文章

Command: 
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts articles [date-flags]
Output: List of saved articles w/ categories, titles, authors, URLs
命令：
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts articles [date-flags]
输出：已保存文章列表，包含分类、标题、作者、URL

Highlights

高亮内容

Command: 
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts highlights [date-flags]
Output: All highlights grouped by source, showing text + notes
命令：
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts highlights [date-flags]
输出：所有高亮内容按来源分组，显示文本 + 笔记

Top Highlighted

高亮最多的内容

Command: 
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts top-highlighted [N] [date-flags]
Output: Top N sources ranked by highlight count
命令：
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts top-highlighted [N] [date-flags]
输出：按高亮数排名的前N个来源

Usage Examples

使用示例

Example 1: "What have I been learning on Readwise this week?"

示例1：“我这周在Readwise上学到了什么？”

bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all
Returns comprehensive analysis: insights, timeline, categories, stats (default = last 7 days)
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts all
返回全面分析：见解、时间线、分类、统计数据（默认=过去7天）

Example 2: "Show my key insights from today"

示例2：“展示我今天的核心见解”

bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings --today
Returns top 5 insights extracted from today's highlights + reading context
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts learnings --today
返回从今日高亮内容中提取的前5条见解 + 阅读上下文

Example 3: "When am I most active on Readwise?"

示例3：“我在Readwise上什么时候最活跃？”

bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline --last-month
Returns daily activity visualization for last 30 days w/ peak identification
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts timeline --last-month
返回过去30天的每日活动可视化 + 高峰识别

Example 4: "What topics am I focusing on?"

示例4：“我关注哪些主题？”

bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories
Returns domain distribution w/ visual bars (default = last 7 days)
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts categories
返回领域分布搭配可视化进度条（默认=过去7天）

Example 5: "Show Readwise stats from Jan 1-7"

示例5：“展示我1月1日至7日的Readwise统计数据”

bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard --from 2025-01-01 --to 2025-01-07
Returns metrics dashboard for custom date range
bash
pnpm tsx skills/readwise-api/scripts/fetch-todays-activity.ts dashboard --from 2025-01-01 --to 2025-01-07
返回自定义日期范围的指标仪表盘

Error Handling

错误处理

Missing API token: Clear error with link to get token
Rate limits: Automatic 3s delays between paginated requests (20 req/min limit)
Network errors: Graceful failure with error messages via spinner
Empty results: Friendly "no activity yet" messages
缺失API令牌：清晰的错误提示，附带获取令牌的链接
速率限制：分页请求之间自动添加3秒延迟（限制为20请求/分钟）
网络错误：通过加载动画优雅地返回错误消息
空结果：友好的“暂无活动”提示

API Details

API详情

Rate Limits: 20 requests/minute per access token
  • Script auto-throttles with 3s delays between requests
  • Pagination handled automatically
Date Filtering:
  • Presets: today, yesterday, last-week (7d), last-month (30d)
  • Custom ranges via --from/--to flags (ISO 8601: YYYY-MM-DD)
  • Default: last 7 days
  • Timezone: Local (dates converted to UTC for API)
Reader API Limitation:
  • Supports only start date (
    updatedAfter
    ), no end date
  • End date filtering done client-side after fetch
  • May fetch extra data that gets filtered locally
Pagination: Automatically follows 
next
URLs (v2) and 
pageCursor
(v3)
速率限制：每个访问令牌每分钟20次请求
  • 脚本自动添加3秒延迟进行限流
  • 自动处理分页
日期过滤：
  • 预设：今日、昨日、上周（7天）、上月（30天）
  • 通过--from/--to标志设置自定义范围（ISO 8601格式：YYYY-MM-DD）
  • 默认：过去7天
  • 时区：本地时区（日期会转换为UTC格式用于API请求）
Reader API限制：
  • 仅支持起始日期（
    updatedAfter
    ），不支持结束日期
  • 结束日期过滤在获取数据后于客户端完成
  • 可能会获取额外数据并在本地过滤
分页：自动跟随v2的
next
链接和v3的
pageCursor

Implementation

实现细节

API Client: 
scripts/readwise-client.ts
  • Pure functions, typed errors
  • Handles pagination and rate limiting
  • Returns 
    ApiResult<T>
    with success/error
Analysis: 
scripts/analyze-highlights.ts
  • Daily grouping + peak detection
  • Domain inference (14 categories: Architecture, Performance, Psychology, etc.)
  • NLP-style insight extraction (sentence scoring, clustering, ranking)
  • Pattern analysis (consistent/burst/weekend/weekday reader)
  • Pure functions, immutable transformations
CLI: 
scripts/fetch-todays-activity.ts
  • Human-readable terminal output w/ unicode visual bars
  • Colored text via chalk, spinners via ora
  • Eight modes: learnings, timeline, categories, dashboard, articles, highlights, top-highlighted, all
  • Default order: insights → timeline → categories → stats
Tests: 
scripts/__tests__/analyze-highlights.test.ts
  • Comprehensive coverage (52 tests)
  • Edge cases: empty data, date boundaries, pattern detection
API客户端：
scripts/readwise-client.ts
  • 纯函数类型，带类型化错误
  • 处理分页和速率限制
  • 返回包含成功/错误信息的
    ApiResult<T>
分析模块：
scripts/analyze-highlights.ts
  • 每日分组 + 高峰检测
  • 领域推断（14个分类：架构、性能、心理学等）
  • 类NLP的见解提取（句子评分、聚类、排名）
  • 模式分析（持续型/爆发型/周末型/工作日型读者）
  • 纯函数，不可变转换
命令行界面：
scripts/fetch-todays-activity.ts
  • 人类可读的终端输出，搭配Unicode可视化进度条
  • 通过chalk实现彩色文本，通过ora实现加载动画
  • 8种模式：learnings、timeline、categories、dashboard、articles、highlights、top-highlighted、all
  • 默认展示顺序：见解 → 时间线 → 分类 → 统计数据
测试：
scripts/__tests__/analyze-highlights.test.ts
  • 全面覆盖（52个测试用例）
  • 边缘场景：空数据、日期边界、模式检测

References

参考资料

Detailed API documentation: 
references/api_reference.md
  • Endpoint details
  • Authentication
  • Rate limits
  • Request/response formats
  • Example code
详细API文档：
references/api_reference.md
  • 端点详情
  • 认证方式
  • 速率限制
  • 请求/响应格式
  • 示例代码