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 受信エンドポイント、署名検証、重複排除、Android との同期は、独立したサービスが実装します。
• 環境変数 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" は、ユーザーが指定したリンクをそのまま説明に書き込みます。タスクごとに作成するカードは 1 枚です。

通常の宿題には、--type normal --task "完成第一课练习" --link "https://実際の宿題URL" を使用できます（種類には 普通作业 も指定できます）。--task は宿題の内容、--link はユーザーが指定した元のリンク先 URL です。入力が Markdown リンクの場合は、括弧内の URL を抽出し、Markdown 全体を渡さないでください。共通の説明は --desc に記載します。CLI は説明を保持し、次を追加します。

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

リンクがない場合は --link を省略し、説明から「作业链接」の行も省略します。--link は通常の宿題にのみ使用でき、空でない --task も必ず指定してください。リンクに改行を含めることはできません。通常の宿題で --task と --link を渡さない場合は、従来どおり --desc をそのまま使用します。既存の通常の宿題を更新する場合は、card update --desc で説明全体を送信します。更新コマンドには --type、--task、--link の各パラメーターはありません。

暗算には --type arithmetic --task <複数行の問題> を使用します（種類には 口算 も指定できます）。--task には、実際の改行を使って 1 行に 1 問ずつ記載します。問題集のタイトル、氏名欄、答え、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 を呼び出します。Feishu で表示する必要がある場合は、--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 を直接 Feishu に送信したりしないでください。呼び出し元がインラインデータを明示的に必要とする場合に限り --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 を追加すると、人が読みやすいテキストレポートを出力します。タイムアウト時の再試行が組み込まれており、1 枚のカードで失敗しても処理は中断しません。

録音添付ファイルには、ファイル名のプレフィックス 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 を実行したり、Feishu に送信したりしてはいけません（ブラウザーのセッションがなければ 401/403 になります）。レポート内の添付ファイルを 1 件ずつ確認してください。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。