Bring! 购物清单

通过非官方 REST API 管理 Bring! 购物清单。需要 curl 和 jq。

安全与数据处理

需向用户明确说明该技能访问和存储的内容：

• 网络通信：仅连接 Bring! 官方 API（api.getbring.com），不涉及任何第三方服务、遥测（telemetry）或其它主机。
• 本地写入的文件：
  • ~/.config/bring/credentials.json — 用户的 Bring! 邮箱地址与密码（权限设为 chmod 600，仅属主可读写）。
  • ~/.cache/bring/token.json — 缓存的访问令牌（access token）与刷新令牌（refresh token）。
• 为何需存储密码：Bring! 的非官方 API 不支持纯 Token 登录方式。本技能虽会缓存并自动刷新 Token，但当访问令牌 及 刷新令牌均过期后，仍需凭原始密码重新登录。因此，本地存储的密码实质上赋予了本机对用户 Bring! 账户的持续访问权限 —— 请将 credentials.json 视为敏感密钥（secret）妥善保护。
• 破坏性操作：remove / remove-multi 命令将永久删除条目；且所有变更会立即同步至共享该清单的所有用户设备。执行删除前务必向用户确认，尤其在共享清单场景下。

智能体配置指南

当用户首次请求配置或使用 Bring! 时，请按以下步骤操作：

步骤 1：检查是否已配置

首先运行 scripts/bring.sh lists。若命令成功执行，则表示配置已完成 —— 可直接跳至使用说明部分。

步骤 2：配置凭证

Bring! 需要邮箱地址与密码。若用户尚未注册账号，可免费在 getbring.com 或 Bring! App 中创建。

若用户通过 Google/Apple 注册：需先在 Bring! App 中设置独立密码（设置 → 账户 → 更改密码），API 方可正常工作。

请询问用户希望以何种方式提供凭证，并清晰说明两种方式的权衡 —— 若用户选择聊天输入方式，切勿暗示其凭证不会保留在对话记录中：

“我需要您的 Bring! 邮箱地址和密码。有两种方式： • 终端方式（推荐，最私密）：您在自己的终端中输入，凭证不会出现在本对话中。 • 聊天方式（便捷）：您在此处粘贴。⚠️ 注意：所有在聊天中输入的内容都会成为本次对话历史的一部分，并可能被日志或备份保留。我会立即将其写入本地配置文件，且绝不会重复显示，但我无法撤回已发送的聊天消息。

您倾向于哪种方式？”

选项 A — 终端方式（推荐）： 向用户提供以下命令，由其在自身终端中执行。凭证全程不经过聊天通道：

mkdir -p ~/.config/bring
read -rp "Bring! Email: " BEMAIL
read -rsp "Bring! Password: " BPASS && echo
jq -n --arg e "$BEMAIL" --arg p "$BPASS" '{email: $e, password: $p}' > ~/.config/bring/credentials.json
chmod 600 ~/.config/bring/credentials.json
unset BEMAIL BPASS

告知用户：“请在您的终端中运行上述命令，完成后返回，我将继续完成配置。”

选项 B — 聊天方式（便捷，但凭证经由聊天通道传输）： 仅当用户在阅读上方警告后**明确选择此方式**时才使用。用户在聊天中提供邮箱与密码；使用 jq 直接写入配置文件（确保 JSON 安全编码，避免特殊字符注入），且绝不回显：

mkdir -p ~/.config/bring
jq -n --arg e "USER_EMAIL" --arg p "USER_PASSWORD" '{email: $e, password: $p}' > ~/.config/bring/credentials.json
chmod 600 ~/.config/bring/credentials.json

写入完成后确认：“已完成 —— 已保存至本地配置文件（权限 chmod 600），我不会重复显示。请注意，这些信息现已存在于本聊天的历史记录中 —— 您可在本地自行清除。”

⚠️ 请勿使用 scripts/bring.sh setup —— 该命令依赖交互式终端（TTY），而智能体环境不支持。请始终如步骤 3 所示，手动创建凭证文件。

步骤 3：保存凭证并测试登录

mkdir -p ~/.config/bring
jq -n --arg e "USER_EMAIL" --arg p "USER_PASSWORD" '{email: $e, password: $p}' > ~/.config/bring/credentials.json
chmod 600 ~/.config/bring/credentials.json
scripts/bring.sh login

若登录失败：请用户再次核对邮箱与密码。用户可能需使用其 Bring! 账户的独立密码（而非 Google/Apple SSO 凭据 —— Bring! API 要求直接账户密码）。

步骤 4：显示现有清单并询问默认清单

scripts/bring.sh lists

该命令将列出用户所有的 Bring! 清单。用户可能拥有多个清单，例如：

• Einkaufsliste（主杂货清单）
• Drogerie（药妆店物品）
• Baumarkt（五金店）
• 与伴侣/家人共享的清单

若用户尚无任何清单：请用户先在 Bring! App 中创建一个。API 不支持创建或删除清单 —— 此类操作必须在 App 内完成。待用户创建清单后，继续后续配置流程。

请用户指定一个默认清单。此举可使其后续无需每次都输入清单名称。

若用户仅有 一个 清单：自动将其设为默认，并通知用户。 若用户有 多个 清单：展示清单名称列表，并询问其希望将哪一个设为默认。同时说明，用户仍可通过名称显式指定其他清单（例如：“把钉子加入 Baumarkt 清单”）。

步骤 5：设置默认清单

更新凭证文件，加入所选默认清单字段：

# 读取现有配置并添加 default_list 字段
jq --arg list "CHOSEN_LIST_NAME" '. + {default_list: $list}' ~/.config/bring/credentials.json > /tmp/bring_conf.json && mv /tmp/bring_conf.json ~/.config/bring/credentials.json
chmod 600 ~/.config/bring/credentials.json

步骤 6：确认配置完成

显示当前清单内容，验证全部功能正常：

scripts/bring.sh show

告知用户：“配置已完成！您现在可以说‘把牛奶加入清单’或‘购物清单上有什么？’等指令。”

重要提示：清单仅可在 App 中管理

Bring! API 不支持创建或删除清单。若用户要求新建或删除清单，请回复： “清单只能在 Bring! App 中创建和删除。您在 App 中完成相应操作后，我即可立即使用新清单。”

共享清单处理

Bring! 清单常由家庭成员或伴侣共享。智能体所做的任何变更会即时同步至所有共享该清单的设备。请向用户说明：

• “我添加的任何条目会立即出现在所有共享该清单的手机上。”
• 这通常是期望行为（例如伴侣可实时看到更新的杂货清单），但仍值得明确告知。

手动配置（参考）

凭证可通过环境变量 BRING_EMAIL + BRING_PASSWORD 提供，或通过配置文件 ~/.config/bring/credentials.json：

{"email": "user@example.com", "password": "YOUR_BRING_PASSWORD", "default_list": "Einkaufsliste"}

交互式配置（需 TTY）：scripts/bring.sh setup

命令

所有命令均接受清单名称（支持模糊匹配）或 UUID。若已配置 default_list，则可省略清单参数。

# 列出所有购物清单
scripts/bring.sh lists

# 显示某清单中的条目（若未指定清单，则显示默认清单）
scripts/bring.sh show
scripts/bring.sh show "Einkaufsliste"

# 添加条目（支持可选规格/数量）
scripts/bring.sh add "Milch" "fettarm, 1L"
scripts/bring.sh add "Einkaufsliste" "Milch" "fettarm, 1L"

# 一次性添加多个条目（使用 "item|spec" 格式指定规格）
scripts/bring.sh add-multi "Brot" "Käse|Gouda" "Butter|irische"

# 完成/勾选条目（移至“最近购买”列表）
scripts/bring.sh complete "Milch"

# 一次性完成多个条目
scripts/bring.sh complete-multi "Milch" "Brot" "Käse"

# 将条目从“最近购买”列表移回待购清单
scripts/bring.sh uncomplete "Milch"

# 彻底删除条目
scripts/bring.sh remove "Milch"

# 一次性彻底删除多个条目
scripts/bring.sh remove-multi "Milch" "Brot" "Käse"

指定特定清单

当用户拥有多个清单时，可通过名称指定目标清单：

• “把钉子加入 Baumarkt 清单” → scripts/bring.sh add "Baumarkt" "Nails"
• “Drogerie 清单上有什么？” → scripts/bring.sh show "Drogerie"

清单名称支持大小写不敏感的模糊匹配，因此 “einkauf” 可匹配 “Einkaufsliste”。

若未指定清单，则使用配置文件中的 default_list。

JSON 输出

对 lists 和 show 命令追加 --json 参数，可获取原始 JSON 输出：

scripts/bring.sh lists --json
scripts/bring.sh show --json
scripts/bring.sh show "Einkaufsliste" --json

备注

• 规格（specifications）指条目下方的小字描述（如数量、品牌）
• complete 将条目移至“最近购买”列表（类似在 App 中勾选）
• remove 将条目从清单中彻底删除
• Token 缓存在 ~/.cache/bring/token.json 并自动刷新
• 所有变更会即时同步至共享该清单的所有设备
• 支持含特殊字符（引号、变音符号、emoji）的条目名称
• Bring! 要求使用独立账户密码 —— Google/Apple SSO 登录方式不适用于 API
• credentials.json 中的 country 字段控制商品目录语言（默认值：DE）
• 向用户展示条目时，建议默认仅显示“TO BUY”（待购）部分；除非用户明确要求查看“最近完成”条目 —— 后者可能非常长
• 若 remove 失败并提示“not found”，建议用户先用 show 命令确认条目的精确名称
• Bring! API 不支持创建或删除清单 —— 用户必须在 Bring! App 中管理清单