yao-weread-skill

Yao WeRead Skill

Generate a finely typeset Chinese HTML report from WeRead account data. The default range is the most recent 24 months up to today.

Input

• Environment variable WEREAD_API_KEY, with the format following the requirements of the WeRead skill.
• Optional report range:--years、--start or --end。
• Optional notes depth:--max-note-books; when omitted or passed 0 , process all note books returned by WeRead.
• Optional output directory.
• Optional sample mode:--sample-ai-founder --sample-scale 5, does not require WEREAD_API_KEY。

Output

The process will generate:

• weread-report.html: an interactive HTML report referencing the kami typesetting style.
• weread-report-data.json: aggregated chart data.
• weread-raw-summary.json: an API structure and count summary without keys, for review.

The report will also generate a reader profile module: a poetic summary at the top, 1 profile quote, and up to 20 high-value sentences selected from the past two years of highlights. Raw highlights and thoughts are used only for aggregate analysis and profile selection. Unless the user explicitly requests sharing or publishing, report artifacts should be treated as private content.

Workflow

1. Before calling the API, first read the WeRead skill documentation:
   • shelf.md: bookshelf counts, public/private rules.
   • readdata.md: reading duration units, period rules, annual/monthly fields.
   • notes.md: note pagination, note count calculation, highlight/thought text.
   • book.md: use only when book details or reading progress are needed.
2. Run scripts/generate_weread_report.py。
3. Check that the generated HTML contains at least 20 chart panels and has no TODO, placeholder text, or embedded API key.
4. Check that high-density charts such as treemaps, heatmaps, and horizontal bar charts are not compressed by default margins, and that there is no right-side blank space causing label truncation.
5. Check the reader profile module: the quote must come from the first item in the profile highlight list; in real account mode, do not fabricate highlights, and when there are fewer than 20 highlights, display fewer truthfully.
6. If the user requests visual verification, or if there are substantive changes to the report layout, use a browser to open the generated HTML and check desktop, tablet width, and narrow screen width.

Commands

python3 scripts/generate_weread_report.py --output reports/generated

Common options:

python3 scripts/generate_weread_report.py \
  --years 2 \
  --max-note-books 0 \
  --output reports/generated

AI entrepreneur sample report:

python3 scripts/generate_weread_report.py \
  --years 2 \
  --sample-ai-founder \
  --sample-scale 5 \
  --output reports/generated/ai-founder-sample

Report Design

• The visual system follows references/report-design.md。
• The chart module follows references/chart-catalog.md。
• API field semantics and fallback rules follow references/data-contract.md。
• High-density charts must explicitly set full container fill, label wrapping/hiding strategy, and resize listeners to avoid blank space left by ECharts default layout.
• The content profile must be generated based on real highlight text; the top summary may use statistical framing to generate a warm, poetic description without impersonating the user's original words.

Boundaries

• In real account mode, do not fabricate reading events, note text, ratings, or categories that do not exist in the WeRead response.
• The AI entrepreneur sample mode is used to generate a reusable sample report without connecting to a real account.
• Do not export the full text of books; use only the user's own highlights/thoughts and metadata accessible through the WeRead skill.
• Do not store or print WEREAD_API_KEY。
• When precise rolling date boundaries cannot be obtained, the monthly or annual approximate basis must be clearly indicated.