supsub-focus

supsub-focus スキル

「フォーカス」（focus）は、SupSub でテーマごとに集約されたコンテンツフィードです。複数のソース（WeChat公式アカウント MP、ウェブサイト WEBSITE、Twitter X）を横断して、同じテーマの記事をまとめます。このスキルでは、フォーカスの一覧の確認、フォーカス内のコンテンツの閲覧（既読／未読の区別）、およびフォーカスの削除を行います。

supsub-sub との違い：sub は「購読元」（特定の公式アカウント／ウェブサイトと、その配下の記事）を管理し、focus は「テーマ別の集約ビュー」（複数のソースを横断するコンテンツフィード）を管理します。混同しないでください。 supsub-search との違い：search はキーワードによる一回限りの全文検索で、focus は既存の、継続的に更新されるテーマ別フィードを閲覧する機能です。

前提条件

• インストール：curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash（native インストール。~/.local にインストールされ、バックグラウンドでの自動更新に対応）；またはパッケージマネージャーで npm i -g @supsub/cli / pnpm add -g @supsub/cli
• ログイン済みであること：supsub auth status に Authenticated と表示されること（初回利用時は、まず supsub auth login を実行してください）
• 未認証（exit 2 / UNAUTHORIZED）の場合、「ログインしていません」と伝えるだけで終わらせないでください：supsub auth login を直接実行して、ユーザーのブラウザーで認証を開始します（コマンドは自動的にブラウザーを開き、認証が完了するまで待機します。十分に長いタイムアウト（10 分など）を設定してください。ユーザーはブラウザーで確認ボタンをクリックするだけで、ターミナルでの入力は不要です）。認証に成功したら、元のコマンドを再試行してください。ブラウザーがない環境／ヘッドレス環境では、SUPSUB_NO_BROWSER=1 supsub auth login をユーザーに案内してください。

コマンド

フォーカスの一覧

supsub focus list

引数はありません。各行のフィールド：id、icon（絵文字）、title、unreadCount。

# 列出全部关注点
supsub focus list

# JSON 输出
supsub focus list -o json

JSON 形式：{"success":true,"data":[{"id":42,"icon":"🤖","title":"...","unreadCount":3}, ...]}

既読／未読：各フォーカスの unreadCount は、そのフォーカス内に現在ある未読項目数です。「どのフォーカスに未読があるか／各フォーカスにあといくつ未読があるか」と尋ねられた場合は、このフィールドを直接参照してください。contents を開く必要はありません。

---

フォーカス内のコンテンツを閲覧

supsub focus contents --id <focusId> [--unread | --all] [--brief] [--page <n>] [--page-size <n>]

フラグ	デフォルト	説明
--id	必須	フォーカス ID（正の整数）。supsub focus list の id を指定します
--unread	（デフォルト）	未読コンテンツのみを返します
--all	—	すべてのコンテンツ（既読＋未読）を返します
--brief	—	簡潔な出力：contentId / title / sourceType / sourceName / publishedAt(+Text) / isRead のみを含めます
--page	1	ページ番号（正の整数）
--page-size	20	1ページあたりの件数。1～100

⚠️ --unread と --all は同時に指定できません：両方指定すると INVALID_ARGS が発生します。どちらも指定しない場合、デフォルトの動作は --unread と同じです。

⚠️ 「最近」は「未読」と同じではありません：「最近の X のコンテンツを見せて」「X のフォーカスに最近何があった？」のような時間軸での閲覧を求めるリクエストには、--all を使用してください。 isRead は注記（「そのうち N 件はまだ読んでいません」）として扱い、フィルター条件にはしないでください。ユーザーが「未読／まだ読んでいない／未読があといくつある」と明示した場合にのみ、デフォルトを使用します。 そうしないと、そのフォーカスを読み終えた後に空の配列が返り、「コンテンツはありません」と回答することになります。しかし、ユーザーが尋ねているのは「最近」であり、「未読」ではありません。

フォーカスには複数のソースのコンテンツが集約されるため、どのアカウント／ウェブサイト／Twitter からのコンテンツかを判別できるよう、各行に sourceType / sourceName が含まれます。

各行のフィールド：contentId、url、title、coverImage、keywords[]、tags[]、summary、sourceType、sourceName、publishedAt、isRead。

# 默认（仅未读）—— 等价于 --unread
supsub focus contents --id 42

# 全部内容（含已读）
supsub focus contents --id 42 --all

# 翻到第 2 页 / 一次多拿一些（上限 100）
supsub focus contents --id 42 --page 2
supsub focus contents --id 42 --page-size 100 -o json

# 全部 + JSON
supsub focus contents --id 42 --all -o json

JSON 形式：{"success":true,"data":[{"contentId":"...","url":"...","title":"...","coverImage":"...","keywords":[...],"tags":[...],"summary":"...","sourceType":"MP","sourceName":"...","publishedAt":<timestamp または文字列>,"isRead":false}, ...]}

publishedAt の元の形式はバックエンドのバージョンによって異なります（Unix 秒の数値／"YYYY-MM-DD HH:mm:ss" 形式の文字列）。 自分で形式の違いに対応する必要はありません。CLI が補完した publishedAtText をそのまま参照してください（常に "YYYY-MM-DD HH:mm" 形式です）。 sourceType には MP / WEBSITE / X（Twitter）が含まれる場合があります。

一括列挙では必ず --brief を付けてください：完全な出力では各項目に summary / keywords / tags が含まれるため、100 件で約 90KB となり、ツールの出力上限を超えてファイルへの保存が必要になります。--brief なら、100 件でも約 14KB です。ユーザーに内容を説明する必要がある場合のみ、完全な出力を使用してください。

ページ送りの方針：閲覧リクエストでは1ページ目のみを取得し、合計件数を伝えてください。「すべて／集計／エクスポート」のリクエストでは --page-size 100 を指定して自動的にページを繰り返し取得し、ページごとにユーザーに確認しないでください。詳しくは supsub-unread を参照してください。

---

フォーカス全体を既読にする

supsub focus mark-read --id <focusId> --all

フラグ	必須	説明
--id	はい	フォーカス ID（正の整数）
--all	はい	フォーカス全体を既読にすることを確認します（取り消し不可）

⚠️ 対応しているのはフォーカス全体の既読化のみで、個別記事の既読化には対応していません。 記事には「詳細／閲覧」の手順がなく、個別記事の既読イベントが自然に発生しないため、CLI ではユーザーが明確に「このフォーカスを読み終えました」と表明した場合のみ対応しています。--content-id / --type / --source-type を渡すと INVALID_ARGS が発生します。ユーザーから「この記事を既読にして」と言われた場合は、対応していないことをそのまま伝えてください。

⚠️ --all は必須で、操作は取り消せません（mark-as-unread はありません）。実行前に必ずユーザーに再確認してください。フォーカスのタイトルと現在の unreadCount を伝え、明確な同意を得てから実行してください。

CLI から再確認されることはありません：このコマンド（および focus remove）には対話式の確認プロンプトがなく、実行するとすぐに反映されます。ユーザー自身がターミナルでコマンドを実行するよう案内する場合、 「実行後に CLI が確認を求めます」と言わないでください——そのような安全策はありません。

# 整个关注点已读（需用户确认后执行）
supsub focus mark-read --id 42 --all -o json

JSON 形式：{"success":true,"data":{"message":"已标记该关注点全部内容为已读（不可逆）"}}

---

フォーカスを削除

supsub focus remove --id <focusId>

フラグ	必須	説明
--id	はい	フォーカス ID（正の整数）

supsub focus remove --id 42
supsub focus remove --id 42 -o json

JSON 形式：{"success":true,"data":{"message":"..."}}

⚠️ 破壊的で、取り消しできません：削除後、CLI にはフォーカスを新規作成するコマンドがありません（focus add はありません）。削除すると再作成できません。実行前に必ずユーザーの確認を得てください。

---

已读 / 未读（重点）

已读状态由服务端维护，CLI 既能读取也能标记（只能标为已读，不能标回未读）：

• focus list 每项的 unreadCount = 该关注点的未读条目数。这是判断「哪个关注点还有没看的」的最快入口。
• focus contents 默认（或显式 --unread）只返回未读条目；--all 返回全部（已读 + 未读）。
• focus contents 每条的 isRead（布尔）= 该条目是否已读：表格里渲染为 read 列（已读显示 ✓，未读为空）。
• 标记已读用 focus mark-read --all：只有「整个关注点已读」一档，没有单篇已读。
• 没有取消已读的命令：标错了无法在 CLI 里恢复。--all 级操作不可逆，执行前必须向用户二次确认。
• 跨订阅源 + 关注点的未读概览与「清未读」工作流见 supsub-unread（supsub unread 一条命令看全）。

Agent Usage Notes

• 解析数据时统一用 -o json；表格输出有截断、列宽限制，不适合做下游处理。
• 所有 JSON 响应都是 {"success":true,"data":<payload>} 结构（来自 src/ui/output.ts）。
• 拿 focusId 的唯一来源是 supsub focus list 的 id（正整数）；--id 非正整数会报 INVALID_ARGS (exit 64)，且不会发起请求。
• 用户问「这个关注点里都有哪些内容/文章」通常意味着 --all（含已读）；问「还有哪些没看 / 未读」用默认 --unread。
• focus contents 默认每页 20 条，用 --page / --page-size（上限 100）翻页取更早的内容。
• focus mark-read 只做整个关注点已读（单篇已读不支持：文章没有详情/阅读这一步）；--all 必填且不可逆，执行前必须向用户二次确认。
• 本 skill 不负责：订阅源增删查（→ supsub-sub）、订阅分组（→ supsub-group）、跨源未读概览与清未读工作流（→ supsub-unread）、按关键词全文搜索（→ supsub-search）、发现新公众号（→ supsub-mp）。focus 没有 add。
• Exit codes：0 OK，2 UNAUTHORIZED，64 INVALID_ARGS（--id / --page / --page-size 校验失败、--all 与 --unread 互斥、mark-read 未给 --all 或误传单篇参数），1 业务错误（后端 4xx，如关注点不存在），10 网络错误，11 服务端错误（5xx）。