bestblogs-capture

bestblogs-capture — favorites / highlights / notes / history

When to use

The user wants to favorite a piece of content (optionally with a remark / tag / folder).
The user wants to highlight a passage of the original text; if noteis passed, it is equivalent to a "note".
The user wants to review their own highlight list or note list (both share the underlying entity UserHighlightEntity, distinguished by entryType ).
The user wants to manage reading history (view / delete a single entry / clear all).

Data model key points (must understand)

note and highlight are the same table with different entryType：

entryType=highlight：note is empty
entryType=note：note is not empty

They are not two independent interfaces. goes through GET /me/highlights?entryType=highlight or ?entryType=note for server-side filtering (supported since v2.0.7).

Primitives

Primitive	CLI	Description
`bestblogs.bookmark.create`	`bestblogs capture bookmark add <id> --note ...`	Idempotent
`bestblogs.bookmark.list`	`bestblogs capture bookmark list --json`	Pagination
`bestblogs.bookmark.update`	`bestblogs capture bookmark update <id> --note ...`
`bestblogs.bookmark.delete`	`bestblogs capture bookmark remove <id>`
`bestblogs.highlight.create`	`bestblogs capture highlight add -r <id> -t "..." -n "..."`	Has `-n` means it is a note
`bestblogs.highlight.list`	`bestblogs capture highlights --json`	`entryType=highlight`
`bestblogs.note.list`	`bestblogs capture notes --json`	`entryType=note`
`bestblogs.highlight.update`	`bestblogs capture highlight update <highlightId> -n ...`
`bestblogs.highlight.delete`	`bestblogs capture highlight remove <highlightId>`
`bestblogs.history.list`	`bestblogs capture history list --json`	Pagination
`bestblogs.history.delete`	`bestblogs capture history remove <resourceId>`
`bestblogs.history.clear`	`bestblogs capture history clear --yes`	Dangerous, requires confirmation

Action examples

Favorite (idempotent)

bestblogs capture bookmark add RAW_xxx --note "值得反复读" --json

Repeatedly adding an already-favorited resource will not error; it returns the existing record.

Highlight + note

# 纯划线（entryType=highlight）
bestblogs capture highlight add -r RAW_xxx -t "精彩段落原文" --json

# 划线 + 笔记（entryType=note）
bestblogs capture highlight add -r RAW_xxx -t "精彩段落原文" -n "我的思考" --color "#FFEB3B" --json

View separately

bestblogs capture highlights --resource RAW_xxx --json   # 只看该资源的划线
bestblogs capture notes --limit 20 --json                # 全部笔记（note 非空）

History

bestblogs capture history list --limit 30 --json
bestblogs capture history remove RAW_xxx --json          # 删一条
bestblogs capture history clear --yes --json             # 清空（危险）

Error handling

409 / CONFLICT on highlight create duplicate → tell the user that passage is already highlighted
404 / NOT_FOUND on remove/delete → treat as idempotent, tell the user "it no longer exists", do not treat as a process failure
401 → not logged in, prompt bestblogs auth login

Combination suggestions

After deeply reading a piece of content (bestblogs-read):

If it is valuable overall → bookmark.create
If there are specific golden quotes → highlight.create(optional note)
Review the next day → note.list / bookmark.list
Do not want to see read content again → history.delete