名称： instapaper
描述： "当操作 instapaper-cli (ip) 工具或对其进行故障排除时使用：包括身份验证、列出/导出/导入书签、批量操作、文件夹/高亮/文本处理、选择输出格式（ndjson/json/plain）、基于游标的同步，以及为自动化目的解释 stderr-json/退出码。"

Instapaper CLI

概述

当你需要通过 ip 命令行工具（必须已安装并可在 PATH 中找到）处理 Instapaper 操作时，请使用此技能。尤其适用于需要可靠的自动化、结构化输出或故障排除指导的场景。

安装 CLI

• Go 安装：go install github.com/vburojevic/instapaper-cli/cmd/ip@latest
• Homebrew：brew tap vburojevic/tap && brew install instapaper-cli
• 从源码构建：go build ./cmd/ip（运行 ./ip）

工作流程（快速路径）

1. 验证设置

   • 确保 INSTAPAPER_CONSUMER_KEY 和 INSTAPAPER_CONSUMER_SECRET 环境变量已设置或在登录时传入。
   • 身份验证优先使用 --password-stdin；切勿存储密码。
   • 在执行长时间任务前，运行 ip doctor --json（或 ip auth status）。

2. 为自动化选择输出格式

   • 默认格式为 --ndjson（流式输出，每行一个 JSON 对象）。
   • 使用 --json 获取单个对象或紧凑的 JSON 数组。
   • 使用 --plain 获取稳定的、面向行的文本输出。
   • 添加 --stderr-json 获取结构化的错误信息，添加 --progress-json 用于长时间运行的任务。

3. 确定性地读取数据

   • 使用 list 或 export 命令时，结合 --cursor/--cursor-dir 或 --since/--until 参数来限定范围。
   • 使用 --updated-since 进行增量同步。
   • 当 API 不支持某些过滤时，使用 --select 进行客户端过滤。

4. 安全地进行数据变更

   • 尽可能使用 --dry-run（试运行）或 --idempotent（幂等）模式。
   • 对于批量操作，使用 --ids 或 --stdin 参数，并考虑使用 --batch。
   • 删除操作需要显式的确认标志。

5. 处理额外功能

   • 文本视图：使用 ip text 获取文章 HTML。
   • 高亮：使用 ip highlights list/add/delete。
   • 文件夹：使用 ip folders list/add/delete/order。

6. 故障排除

   • 使用 --debug 标志查看请求时间和状态。
   • 使用 --stderr-json 并将 exit_code 映射到相应的处理动作。

命令参考

当你需要确切的标志、格式或示例时，请阅读以下内容：

• references/commands.md：按命令分类的示例，涵盖身份验证、列出/导出/导入书签、数据变更、文件夹、高亮和文本处理。
• references/output-and-sync.md：输出格式、进度流、游标/范围语法和过滤。
• references/errors.md：退出码和结构化的 stderr 错误码。

注意事项

• 避免使用 --format table 进行解析；它仅供人工阅读。
• 对于大型导出，使用 --output 或 --output-dir 参数，避免对标准输出造成压力。
• 在 Windows 上，优先使用 --password-stdin 以避免密码回显。