feat: add yaml output for agent workflows

Author: jackwener

README.md

@@ -20,7 +20,7 @@ A CLI for Bilibili — browse videos, users, favorites from the terminal 📺
 - 📂 **Favorites** — browse favorite folders, watch-later, and watch history
 - 👍 **Interactions** — like, coin, triple (一键三连)
 - 🔐 **Smart auth** — auto-extracts cookies from Chrome/Firefox, or QR code login
-- 📊 **JSON output** — major query commands support `--json` for scripting
+- 📊 **Structured output** — major query commands support `--yaml` and `--json`
 
 ## Installation
 
@@ -67,6 +67,7 @@ bili video BV1ABcsztEcY --subtitle      # With subtitles
 bili video BV1ABcsztEcY --ai            # AI summary
 bili video BV1ABcsztEcY --comments      # Top comments
 bili video BV1ABcsztEcY --related       # Related videos
+bili video BV1ABcsztEcY --yaml          # Agent-friendly YAML
 bili video BV1ABcsztEcY --json          # Raw JSON
 
 # Users
@@ -127,6 +128,24 @@ Audio extraction requires the optional `audio` dependency group (`av`).
 
 bilibili-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.
 
+### Agent Output Recommendation
+
+If an AI agent needs machine-readable output, prefer `--yaml` first:
+
+- `--yaml` is usually more token-efficient than pretty-printed JSON
+- It is still easy to parse for agents and scripts
+- Keep `--json` for `jq`, strict JSON-only tooling, or exact downstream schemas
+
+Examples:
+
+```bash
+bili video BV1ABcsztEcY --yaml
+bili hot --max 5 --yaml
+bili user-videos 946974 --max 3 --yaml
+```
+
+For agent usage, also prefer narrower queries (`--max`, `--page`, `--offset`) to avoid wasting context on oversized payloads.
+
 ### Claude Code / Antigravity
 
 ```bash
@@ -169,7 +188,7 @@ All bilibili-cli commands are available in OpenClaw after installation.
 - 📂 **收藏** — 收藏夹浏览、稍后再看、观看历史
 - 👍 **互动** — 点赞、投币、一键三连
 - 🔐 **智能认证** — 自动提取浏览器 Cookie，或扫码登录
-- 📊 **JSON 输出** — 主要查询命令支持 `--json`，方便脚本调用
+- 📊 **结构化输出** — 主要查询命令支持 `--yaml` 和 `--json`
 
 ## 安装
 
@@ -208,6 +227,8 @@ bili video BV1ABcsztEcY --subtitle      # 显示字幕
 bili video BV1ABcsztEcY --ai            # AI 总结
 bili video BV1ABcsztEcY --comments      # 热门评论
 bili video BV1ABcsztEcY --related       # 相关推荐
+bili video BV1ABcsztEcY --yaml          # 适合 AI Agent 的 YAML
+bili video BV1ABcsztEcY --json          # 原始 JSON
 
 # 用户
 bili user 946974                        # UP 主资料
@@ -259,6 +280,24 @@ bilibili-cli 采用三级认证策略：
 
 大部分命令无需登录。字幕、收藏夹、动态和互动操作需要登录。写操作（like/coin/triple/unfollow/dynamic-post/dynamic-delete）需要可写凭证（包含 `bili_jct`）。
 
+## AI Agent 使用建议
+
+如果 AI Agent 需要机器可读输出，默认优先 `--yaml`：
+
+- `--yaml` 通常比格式化 JSON 更省 token
+- 对 agent 来说仍然容易解析
+- 只有在要配合 `jq` 或下游必须是 JSON 时，再使用 `--json`
+
+示例：
+
+```bash
+bili video BV1ABcsztEcY --yaml
+bili hot --max 5 --yaml
+bili user-videos 946974 --max 3 --yaml
+```
+
+另外，agent 应尽量配合 `--max`、`--page`、`--offset` 缩小结果集，避免把不必要的数据带进上下文。
+
 音频提取功能需要安装可选依赖组 `audio`（即 `av`）。
 
 ## 作为 AI Agent Skill 使用

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bilibili-cli
-description: CLI skill for Bilibili (哔哩哔哩, B站) to browse videos, users, search, trending, dynamics, favorites, and interactions from the terminal
+description: CLI skill for Bilibili (哔哩哔哩, B站) with token-efficient YAML output for AI agents to browse videos, users, search, trending, dynamics, favorites, and interactions from the terminal
 author: jackwener
 version: "1.0.0"
 tags:
@@ -16,6 +16,15 @@ tags:
 
 A CLI tool for interacting with Bilibili (哔哩哔哩). Use it to fetch video info, search content, browse user profiles, and perform interactions like liking or triple-clicking.
 
+## Agent Defaults
+
+When you need machine-readable output:
+
+1. Prefer `--yaml` first because it is usually more token-efficient than pretty JSON.
+2. Use `--json` only when downstream tooling strictly requires JSON.
+3. Keep result sets small with `--max`, `--page`, or `--offset`.
+4. Prefer specific commands over broad ones. Example: use `bili user-videos 946974 --max 3 --yaml` instead of fetching large timelines.
+
 ## Prerequisites
 
 ```bash
@@ -53,6 +62,7 @@ bili video BV1ABcsztEcY --subtitle      # Show subtitles (AI or uploaded)
 bili video BV1ABcsztEcY --ai            # Show B站 AI summary
 bili video BV1ABcsztEcY --comments      # Show top comments
 bili video BV1ABcsztEcY --related       # Show related videos
+bili video BV1ABcsztEcY --yaml          # Token-efficient YAML output
 bili video BV1ABcsztEcY --json          # Raw JSON output
 ```
 
@@ -65,7 +75,7 @@ bili user "影视飓风"
 
 # List user's videos
 bili user-videos 946974 --max 20
-bili user-videos "影视飓风" --json
+bili user-videos "影视飓风" --yaml
 ```
 
 ### Search
@@ -134,19 +144,20 @@ bili unfollow 946974           # Unfollow by UID
 ```bash
 bili status                    # Quick login check
 bili whoami                    # Detailed profile info
+bili whoami --yaml              # Profile as YAML
 bili whoami --json              # Profile as JSON
 bili login                     # QR code login
 bili logout                    # Clear credentials
 ```
 
-## JSON Output
+## Structured Output
 
-Major query commands support `--json` for machine-readable output:
+Major query commands support both `--yaml` and `--json` for machine-readable output. Prefer YAML for agent use:
 
 ```bash
-bili video BV1ABcsztEcY --json | jq '.stat.view'    # Get view count
-bili hot --json | jq '.list[0].title'                # First trending title
-bili user 946974 --json | jq '.user_info.name'       # Username
+bili video BV1ABcsztEcY --yaml                       # Preferred for AI agents
+bili hot --max 5 --yaml                             # Smaller, token-efficient payload
+bili user 946974 --json | jq '.user_info.name'      # JSON when jq is needed
 ```
 
 ## Debugging
@@ -171,14 +182,14 @@ bili video BV1ABcsztEcY --comments
 # Segments are saved to /tmp/bilibili-cli/{title}/seg_000.wav, seg_001.wav, ...
 bili audio BV1ABcsztEcY --segment 25
 
-# Find a user's latest video BV ID
-bili user-videos 946974 --max 1 --json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['bvid'])"
+# Find a user's latest video BV ID with minimal payload
+bili user-videos 946974 --max 1 --yaml
 
 # Check if logged in before performing actions
 bili status && bili like BV1ABcsztEcY
 
-# Search and get first result
-bili search "topic" --type video --json | python3 -c "import sys,json; r=json.load(sys.stdin); print(r[0]['bvid'] if r else 'not found')"
+# Search and inspect the first few results
+bili search "topic" --type video --max 3 --yaml
 ```
 
 ### Workflow: Video Content Analysis

bili_cli/cli.py

@@ -2,9 +2,9 @@
 
 Usage:
     bili login / logout / status / whoami
-    bili video <BV号或URL> [--subtitle] [--ai] [--comments] [--related] [--json]
+    bili video <BV号或URL> [--subtitle] [--ai] [--comments] [--related] [--yaml|--json]
     bili user <UID或用户名>          bili user-videos <UID> [--max N]
-    bili search <关键词> [--type user|video] [--json]
+    bili search <关键词> [--type user|video] [--yaml|--json]
     bili hot / rank / feed / my-dynamics / following / history / watch-later / favorites
     bili dynamic-post <TEXT> / dynamic-delete <动态ID>
     bili like / coin / triple <BV号> / unfollow <UID>

bili_cli/commands/account.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import json
-
 import click
 from rich.panel import Panel
 
@@ -42,11 +40,14 @@ def status():
 
 
 @click.command()
-@click.option("--json", "as_json", is_flag=True, help="输出原始 JSON。")
-def whoami(as_json: bool):
+@click.option("--json", "as_json", is_flag=True, help="输出 JSON。")
+@click.option("--yaml", "as_yaml", is_flag=True, help="输出 YAML，推荐给 AI Agent。")
+def whoami(as_json: bool, as_yaml: bool):
     """查看当前登录用户的详细信息。"""
     from .. import client
 
+    output_format = common.resolve_output_format(as_json=as_json, as_yaml=as_yaml)
+
     cred = common.require_login(message="未登录。使用 [bold]bili login[/bold] 登录。")
 
     info = common.run_or_exit(client.get_self_info(cred), "获取用户信息失败")
@@ -56,8 +57,7 @@ def whoami(as_json: bool):
         "获取用户信息失败",
     )
 
-    if as_json:
-        click.echo(json.dumps({"info": info, "relation": relation}, ensure_ascii=False, indent=2))
+    if common.emit_structured({"info": info, "relation": relation}, output_format):
         return
 
     name = info.get("name", "unknown")