Back to Details

highlight-graph

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
You are building an interactive 2D force-graph visualization of the user's Readwise highlights, showing how ideas connect across books, articles, and other sources. Think Obsidian's graph view, but for highlights.
你需要为用户的Readwise高亮内容构建一个交互式2D force-graph可视化图形，展示不同书籍、文章及其他来源中观点的关联方式。可以把它想象成Obsidian的图谱视图，但专门用于高亮内容。

Readwise Access

Readwise 访问权限

Check if Readwise MCP tools are available (e.g. 
mcp__readwise__readwise_list_highlights
). If they are, use them throughout. If not, use the equivalent 
readwise
CLI commands instead.
检查是否有Readwise MCP工具可用（例如
mcp__readwise__readwise_list_highlights
）。如果可用，请全程使用这些工具；如果不可用，则改用等效的
readwise
CLI命令。

Process

流程

Step 1: Fetch Highlights

步骤1：获取高亮内容

Open with:
Highlight Graph · Readwise
I'll pull your recent highlights, find connections between them, and build a graph you can explore. Give me a moment.
Fetch the user's most recent highlights using 
readwise_list_highlights
with 
page_size=100
. Fetch 2 pages (200 highlights) for a good starting graph. Each page returns highlights from most recent to least recent — use 
page=1
, then 
page=2
.
开头输出：
高亮图谱 · Readwise
我将提取你最近的高亮内容，找出它们之间的关联，并构建一个可供你探索的图谱。请稍候片刻。
使用
readwise_list_highlights
并设置
page_size=100
来获取用户最近的高亮内容。获取2页（共200条高亮）作为图谱的初始数据。每页返回的高亮内容按从新到旧排序——先使用
page=1
，再使用
page=2
。

Step 2: Prepare Highlight Data

步骤2：准备高亮数据

Parse the API responses and build a JSON array of highlights. Each highlight needs:
json
{
  "id": "12345",
  "text": "The actual highlight text...",
  "note": "User's note if any",
  "book_id": 58741401,
  "source_title": "The Goal",
  "source_author": "Eliyahu Goldratt",
  "url": "https://..."
}
Important: The Readwise API returns 
book_id
but does NOT return the book/article title or author with each highlight. You must identify the source title and author yourself by reading the highlight texts and any available metadata (URLs, content patterns). Group highlights by 
book_id
and infer the source from context. It's fine to use "Unknown" for author when unsure, but try to identify the title.
Write this array to a temp file: 
/tmp/highlights.json
解析API响应并构建高亮内容的JSON数组。每条高亮内容需要包含以下字段：
json
{
  "id": "12345",
  "text": "实际的高亮文本...",
  "note": "用户的备注（如果有）",
  "book_id": 58741401,
  "source_title": "The Goal",
  "source_author": "Eliyahu Goldratt",
  "url": "https://..."
}
重要提示： Readwise API会返回
book_id
，但不会在每条高亮内容中附带书籍/文章的标题或作者信息。你需要通过阅读高亮文本及任何可用的元数据（URL、内容模式）自行识别来源标题和作者。按
book_id
对高亮内容分组，并通过上下文推断来源信息。如果不确定作者，可以使用“Unknown”，但请尽量识别出标题。
将该数组写入临时文件：
/tmp/highlights.json

Step 3: Initial Render (No Connections)

步骤3：初始渲染（无关联）

Write an empty connections file and run the build script to give the user something to look at immediately:
bash
echo '[]' > /tmp/connections.json
python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html
Tell the user:
Graph is open with {N} highlights across {N} sources. Finding connections between ideas now...
创建一个空的关联文件并运行构建脚本，让用户可以立即看到初始效果：
bash
echo '[]' > /tmp/connections.json
python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html
告知用户：
图谱已打开，包含**{N}条高亮内容**，覆盖**{N}个来源**。正在查找观点之间的关联...

Step 4: Find Cross-Source Connections

步骤4：跨来源关联查找

Launch parallel subagents (3-5 agents) to find semantic connections between highlights from different sources. Each agent should analyze a batch of highlights and return connections.
Batching strategy:
  1. Group highlights by source (book_id).
  2. Split sources into batches of ~8 sources each.
  3. For each batch pair (including within-batch), launch an agent with the highlight texts from those sources.
  4. Each agent should find 5-10 genuine conceptual connections — shared themes, ideas, or language across different sources.
Each agent should return a JSON array of connections:
json
[
  {
    "a_id": "12345",
    "b_id": "67890",
    "label": "Feedback loops",
    "why": "Both highlights discuss how tight feedback loops improve quality"
  }
]
Quality over quantity. Only create connections when the link is real and would be interesting. 15-30 total cross-source connections for 200 highlights is ideal.
启动并行子Agent（3-5个）来查找不同来源高亮内容之间的语义关联。每个Agent应分析一批高亮内容并返回关联结果。
分批策略：
  1. 按来源（book_id）对高亮内容分组。
  2. 将来源分成每组约8个的批次。
  3. 对于每一对批次（包括批次内部），启动一个Agent并传入这些来源的高亮文本。
  4. 每个Agent应找出5-10个真实的概念关联——不同来源之间共有的主题、观点或表述。
每个Agent应返回一个关联结果的JSON数组：
json
[
  {
    "a_id": "12345",
    "b_id": "67890",
    "label": "Feedback loops",
    "why": "Both highlights discuss how tight feedback loops improve quality"
  }
]
质量优先于数量。只有当关联真实且有价值时才创建关联。对于200条高亮内容，理想的跨来源关联数量为15-30个。

Step 5: Rebuild with Connections

步骤5：关联后重建图谱

Merge all agent results into a single connections JSON array, write to 
/tmp/connections.json
, and re-run the build script:
bash
python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html
Present a summary:
Built a graph of {N} highlights across {N} sources, with {N} connections between ideas.
A few interesting connections I found:
  • "{highlight A snippet}" ↔ "{highlight B snippet}" — {connection label}
  • ...
The graph is open in your browser. Want to add more highlights?
将所有Agent的结果合并为一个关联JSON数组，写入
/tmp/connections.json
，然后重新运行构建脚本：
bash
python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html
展示总结信息：
已构建包含**{N}条高亮内容**、覆盖**{N}个来源的图谱，其中包含{N}个观点关联**。
我发现了一些有趣的关联：
  • "{高亮A片段}" ↔ "{高亮B片段}" — {关联标签}
  • ...
图谱已在你的浏览器中打开。需要添加更多高亮内容吗？

Step 6: Iterate

步骤6：迭代优化

  • More highlights: Fetch additional pages (
    page=3
    , 
    page=4
    , etc.), re-run source identification, find new connections, rebuild.
  • Filter by topic: Use 
    readwise_search_highlights
    to pull highlights on a specific topic or from a specific book, rebuild with just those.
  • 添加更多高亮内容： 获取更多页面（
    page=3
    、
    page=4
    等），重新识别来源，查找新的关联，然后重建图谱。
  • 按主题筛选： 使用
    readwise_search_highlights
    提取特定主题或特定书籍的高亮内容，仅用这些内容重建图谱。

The Build Script

构建脚本

build_graph.py
(in this skill's directory) handles all the visualization logic. It takes two JSON files and outputs a self-contained HTML file:
python3 build_graph.py --highlights highlights.json --connections connections.json --output output.html
highlights.json: Array of 
{id, text, note, book_id, source_title, source_author, url}
connections.json: Array of 
{a_id, b_id, label, why}
The script handles:
  • Deduplication and filtering of highlights
  • Color assignment per source (rose-pine palette)
  • Same-source full pairwise connectivity (all highlights from same book linked)
  • Cross-source semantic connections (dashed purple edges with particles)
  • Interactive sidebar panel with connected ideas and same-book highlights
  • Label overlap prevention
  • Screen-relative text scaling (consistent size at any zoom level)
  • Source legend with click-to-filter
  • Hover isolation and selection persistence
The output is a single HTML file using force-graph from CDN. No server needed — just open in a browser.
build_graph.py
（位于本技能的目录中）负责所有可视化逻辑。它接收两个JSON文件并输出一个独立的HTML文件：
python3 build_graph.py --highlights highlights.json --connections connections.json --output output.html
highlights.json： 包含
{id, text, note, book_id, source_title, source_author, url}
的数组 connections.json： 包含
{a_id, b_id, label, why}
的数组
该脚本处理以下内容：
  • 高亮内容的去重与过滤
  • 为每个来源分配颜色（rose-pine调色板）
  • 同一来源内的全两两关联（同一书籍的所有高亮内容相互链接）
  • 跨来源的语义关联（带粒子效果的紫色虚线）
  • 包含关联观点和同书籍高亮内容的交互式侧边栏面板
  • 标签重叠避免
  • 相对于屏幕的文本缩放（任何缩放级别下大小一致）
  • 可点击筛选的来源图例
  • 悬停隔离与选择持久化
输出是一个使用CDN上的force-graph的单HTML文件。无需服务器——直接在浏览器中打开即可。

SKILL_DIR

SKILL_DIR

Replace 
SKILL_DIR
in commands above with the actual path to this skill's directory (where 
build_graph.py
lives).
将上述命令中的
SKILL_DIR
替换为该技能目录的实际路径（即
build_graph.py
所在的目录）。