ATProtocol Annotations 用于在 ATProtocol 上读写 W3C Web Annotations，采用 at.margin.annotation 词法（lexicon）。注释是公开、可移植的，并与你的 ATProtocol 身份绑定。
用途
该工具面向为 URL 添加注释、为网页撰写阅读笔记，以及将注释锚定到页面特定文本片段等场景。
前置条件
需要一个带应用密码的 ATProtocol（Bluesky）账号。需设置环境变量：export BLUESKY_CO_APP_PASSWORD=your-app-password。注意：source .env 不会导出变量，运行前应使用 export $(grep BLUESKY_CO_APP_PASSWORD ~/lettabot/.env)。
主要能力与使用方式
写入单条注释：python scripts/annotate.py write "https://example.com/article" "My observation about this article"
带文本引用（锚定到特定段落）写入：python scripts/annotate.py write "https://example.com/article" "This is significant because..." --quote "exact text from the page"
带动机写入（默认 commenting）：python scripts/annotate.py write "https://example.com/article" "Key passage" --motivation highlighting
批量注释（推荐对同一 URL 的多条注释使用）：准备 JSONL 文件，每行一条注释，例如 {"text": "First observation about this page"}、{"text": "Second observation", "quote": "anchored to this text"}、{"text": "A highlight", "motivation": "highlighting"}。然后运行：python scripts/annotate.py batch "https://example.com/article" annotations.jsonl。也可从标准输入管道传入：echo '{"text": "Quick note"}' | python scripts/annotate.py batch "https://example.com/article" -。批量写入的原因：单条注释每次会发起 3 个 HTTP 请求（认证 + 获取标题 + 创建），而批量无论数量多少总共只发 3 个请求（1 次认证 + 1 次标题 + 1 次 applyWrites）。例如 10 条注释为 3 个请求而非 30 个。
列出自己的注释：python scripts/annotate.py list --limit 20
读取他人的注释：python scripts/annotate.py read "handle.bsky.social" --limit 20 或 python scripts/annotate.py read "did:plc:abc123" --limit 20。跨 PDS 解析是自动的，适用于任何 PDS（bsky.social、自定义 PDS 等）上的句柄。
注释工作流
注释文档或网页时：先获取并阅读完整内容；识别关键观察、模式、评论；将注释写成 JSONL 文件（每行一条）；在一次调用中批量写入所有注释。每条注释应是独立的观察。在相关时使用引用将注释锚定到特定段落。
动机（Motivations）
支持以下 W3C Web Annotation 动机：commenting（默认，一般观察）、highlighting（标记重要段落）、describing（描述某物是什么）、classifying（对内容分类）、questioning（对内容提出问题）。
记录格式
注释以 at.margin.annotation 记录形式存储在你的 ATProtocol PDS 中。每条记录包含：target.source（被注释的 URL）、target.sourceHash（URL 的 SHA256）、target.title（页面标题，自动获取）、target.selector（可选的 TextQuoteSelector，用于锚定）、body.value（注释文本）、motivation（W3C 动机类型）。
配置
编辑 scripts/annotate.py 中的常量以更改账号：PDS（PDS 端点，默认 bsky.social）、HANDLE（你的 ATProtocol 句柄）、PASSWORD（从 BLUESKY_CO_APP_PASSWORD 环境变量读取）。