trello

Trello 任务看板

使用 cyeam trello，不要自行拼装 Trello HTTP 请求。首次使用先运行 cyeam trello login --key <api-key>，在浏览器授权后把页面显示的 Token 粘贴回 CLI；CLI 验证并存入系统钥匙串，钥匙串不可用时回退到权限为 0600 的 ~/.cyeam/trello.json。绝不输出凭据。

规则

• 不知道 ID 时，先 boards，再 lists <board-id>；不要按名称猜测 ID。
• 查询当天任务使用 cards --board <board-id> --today；按本机时区和 due 筛选。
• 创建、修改、移动、上传附件及 Webhook 增删会改变外部状态，必须先获得用户明确确认。
• Webhook 命令只管理订阅；公网 HTTPS 接收端、验签、去重和安卓同步由独立服务实现。
• 环境变量 TRELLO_API_KEY 和 TRELLO_TOKEN 仅用于 CI 或临时覆盖；设置其中一个时必须同时设置另一个。

命令

cyeam trello login --key <api-key>
cyeam trello status
cyeam trello logout

cyeam trello boards
cyeam trello lists <board-id>
cyeam trello cards --list <list-id> [--today]
cyeam trello cards --board <board-id> [--today]
cyeam trello status-changes --board <board-id>
    [--date <YYYY-MM-DD>] [--to-list <list-id>] [--limit 1000]
cyeam trello homework --board <board-id>
    [--date <YYYY-MM-DD> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>]
    [--include-actions] [--audio-only] [--dir <目录>]
    [--max-width 1200] [--max-bytes <bytes>]

cyeam trello card create --list <list-id> --name <title>
    [--desc <text>] [--due <RFC3339>] [--labels <label-id,...>]
    [--type normal|word_memorization|english_reading|arithmetic] [--task <text>]
    [--link <url>]
cyeam trello card update <card-id>
    [--name <title>] [--desc <text>] [--due <RFC3339>] [--complete=true|false]
cyeam trello card move <card-id> --list <target-list-id>
cyeam trello card attach <card-id> --file <local-path> [--name <display-name>]
cyeam trello card attachments <card-id>
cyeam trello card attachment get <card-id> <attachment-id>
    [--out <local-path>] [--max-width <px>] [--max-bytes <bytes>]
cyeam trello card actions <card-id> [--limit 50]

cyeam trello webhook create --callback-url <https-url> --model-id <id>
    [--description <text>]
cyeam trello webhook delete <webhook-id>

card update --due "" 清除截止时间；未传 --complete 时不改变任务完成标记。默认输出是 JSON 信封，--pretty 输出响应 JSON。

创建家庭作业卡片时，--type 默认 normal，与原先直接传 --desc 的行为一致。--type word_memorization --task "bedroom, armchair" 会将单词和自动生成的翻译链接写入描述；--type english_reading --task "/ai/translate?textbook=0&article=4" 会将用户提供的链接原样写入描述。每个任务只创建一张卡片。

普通作业支持 --type normal --task "完成第一课练习" --link "https://实际的作业网址"（类型也接受 普通作业）。--task 为作业内容，--link 为用户提供的原始目标网址；若输入为 Markdown 链接，提取括号中的网址，不传整段 Markdown。通用说明放在 --desc。CLI 保留说明并追加：

类型: 普通作业
作业内容: 完成第一课练习
作业链接: [https://实际的作业网址](https://实际的作业网址)

没有链接时省略 --link，描述中也省略“作业链接”一行。--link 仅用于普通作业，必须同时提供非空 --task，链接不允许包含换行。不传 --task、--link 的普通作业仍原样使用 --desc。更新已有普通作业时，使用 card update --desc 提交完整描述；更新命令没有 --type、--task 或 --link 参数。

口算使用 --type arithmetic --task <多行题目>（类型也接受 口算）。--task 每行一道题，使用真实换行；不放题单标题、姓名栏、答案、Markdown 表格或多栏排版。预计用时等说明放在 --desc，例如 预计用时: 5。CLI 保留说明并追加 作业类型：口算、作业内容： 和完整题目；平板读取题目并自动排版。

cyeam trello card create --list <list-id> --name "口算20题（第N天）" --due <RFC3339> \
  --type arithmetic --task '26 + 17 = ___
54 − 28 = ___' --desc '预计用时: 5'

更新已有口算卡片时，card update 仍使用 --desc 提交完整描述（包括类型、预计用时、作业内容： 和全部题目）；该命令没有 --type 或 --task 参数。通用说明写在 作业内容： 之前，后面只放题目。

获取图片时先用 card attachments <card-id> 找到 attachment-id、文件名和 MIME 类型，再调用 card attachment get。需要在飞书展示时优先传 --out <local-path>：CLI 会使用已保存的 Trello 凭据下载受保护附件，并把图片字节直接写入文件，返回 saved_to、name、mime_type 和 size_bytes；Agent 随后上传该本地文件。默认下载原图，图太大时加 --max-width <px> 下载服务端预览图（WebP，体积小得多，内容为 WebP 时 mime_type 为 image/webp）。不要自行解析 JSON、解码 Base64，也不要把受保护 URL 直接发给飞书。仅在调用方明确需要内联数据时省略 --out，此时响应才包含 base64。附件默认上限为 25 MiB。

status-changes 按本机时区查询某一天的卡片列表流转记录，默认查询今天，返回卡片、流转前后列表、操作者和 changed_at。整理每日完成任务时，必须先用 lists <board-id> 找到完成列表 ID，再传 --to-list <list-id>；不要按列表名称猜测。

查某一天的作业进度和提交附件，使用完整命令 cyeam trello homework --board <board-id>：筛出 due 当天的卡片，返回每张卡片所在列表并下载全部附件到本地目录（默认 homework-<date>/）。这是只读报告命令，不创建或追加作业；不要写成不存在的 cyeam homework，新增作业请使用 cyeam trello card create。默认下载不超过 --max-width（1200）宽的最大图片预览；传 --max-width 0 下载原始文件。JSON 报告里每个附件带 saved_to 路径和 homework_photo_url 链接（形如 https://trello.com/1/cards/<card-id>/attachments/<attachment-id>/download/<filename>，浏览器登录 Trello 后可直接打开）；加 --pretty 输出人可读的文本报告。内置超时重试，单卡片失败不中断。

录音附件使用文件名前缀 homework-audio- 标记，命名格式为 homework-audio-{提交ID}-{序号}.{扩展名}。trello homework 会像其他附件一样列出并下载录音；只提取录音时加 --audio-only，例如 cyeam trello homework --board <board-id> --from <YYYY-MM-DD> --to <YYYY-MM-DD> --audio-only。录音保存在报告目录下对应卡片的子目录，路径见附件的 saved_to 字段；下载需要有效的 Trello CLI 授权。

提取图片的硬性规则：查看或转发图片一律用 saved_to 本地文件，用读图工具打开确认内容后再展示；homework_photo_url 链接仅作展示，禁止对它 curl/wget 或发给飞书（无浏览器会话会 401/403）。逐个附件检查报告：error 非空或 size_bytes 为 0 表示下载失败，用 card attachment get <card-id> <attachment-id> --out <path> 单独补下（默认下载原图，加 --max-width 1200 下载小体积预览图）。

作业总结可用 cyeam trello homework --board <board-id> --from <YYYY-MM-DD> --to <YYYY-MM-DD> --include-actions 一次批量读取多天材料。起止日期含首尾，与 --date 互斥；省略日期仍查今天。按截止日期筛选当前未归档卡片，不是按提交时间筛选；无截止日期及归档卡片不在报告内。报告增加 from、to 和每张卡的 desc 原题描述；--include-actions 额外返回每卡最近最多 1000 条 actions（含评论），读取失败写入 actions_error，不阻断图片下载。历史达到 1000 条时应声明可能截断。附件目录包含卡片 ID，避免同名作业混淆。模型批改和复习记录流程见 homework skill；CLI 不自行评分。

发布作业批改（协议 v1）

cyeam trello card review <card-id> --text <纯文本> [--review-id <UUID>]
cyeam trello card review <card-id> --text-file <UTF-8文件> [--review-id <UUID>]
cyeam trello card review <card-id> --image <本地图片> [--review-id <UUID>]
cyeam trello card review <card-id> --audio <本地音频> [--review-id <UUID>]

这四个内容参数必须且只能选一个。不自动评分。始终写原卡片，不创建卡、不修改原题描述。可选 --has-errors=true|false 明确发布是否有错：true 转入「待改错」并清除 dueComplete；false 批改通过，当前为「已改错」时保留该状态，否则进入「已完成」，dueComplete=true。省略时只发布批改内容，不移动列表或修改完成标记。目标列表按卡片看板查询 ID，缺少时自动创建。每次发布一条以 作业批改： 开头的 JSON 评论；图片/音频先上传为原生文件附件，再以附件 ID 发布评论。图片扩展名支持 jpg/jpeg/png/webp/gif；音频支持 m4a/mp3/wav/aac/ogg/opus/amr/3gp。文件必须非空，最大 50 MiB；扩展名应与真实文件格式一致，音频优先 M4A/AAC 或 MP3。

默认生成 UUID，执行时在 stderr 输出 review_id 和 state_file；也可首次提交就显式指定 UUID。成功响应包含 review_id、card_id、action_id、state_file，媒体还包含 attachment_id。状态保存在 ~/.cyeam/trello-reviews/<UUID>.json（0600），包括正文、附件 ID、action ID，不包含 Token。不要删除仍可能重试的状态文件。

失败后用同一 UUID、同一卡片、完全相同内容重跑命令。CLI 先查同名原生附件及卡片评论（分页），恢复已成功的上传/发布；已成功的本地记录直接返回，不重复发评论。同一 UUID 改内容或是否有错（包括省略该参数）会报错。评论成功但状态更新失败时，使用完全相同参数和 UUID 重试，只补状态，不重发评论；整个流程成功后重跑不重放状态。评论恢复排除发布前已存在的同文评论，因此新 UUID 可发布相同文案作为新一轮历史。

如果请求结果未知且查询仍未发现匹配记录，CLI 默认停止，不盲目重复 POST。稍后继续用同一 UUID 重试核对；仅在人工确认之前的写入失败后，才可加 --retry-uncertain 允许再次 POST（仍有重复风险）。此选项必须显式传原 --review-id。如果进程崩溃留下 .lock，先确认该提交没有进程仍在运行，再移除对应锁文件；保留 JSON 状态。

新一轮批改使用新 UUID 保留历史；不要删除旧评论引用的附件。命令不提供设备 Token、不上传外链、不修改原评论。完整用法与验收边界见仓库 docs/trello-review.md。

作业统一使用四个列表状态：待完成 → 已完成 → 待改错 → 已改错。已改错表示孩子提交了订正，尚不代表复批通过；复批仍错回待改错，通过保留已改错。homework 报告新增 status：todo/completed/needs_correction/corrected，非上述列表为 unknown；list_name 保留原名，不从 due_complete 猜测正确率。发布前依据最新一轮提交判读；有待判定内容且无法确认整份作业通过时，省略 --has-errors。