@9000ai/cli 0.1.0

package/skills/douyin-topic-discovery/references/endpoints.md

@@ -0,0 +1,127 @@
+# 抖音选题发现接口
+
+基础地址默认：
+
+```text
+http://127.0.0.1:8025
+```
+
+所有接口都需要：
+
+```text
+X-API-Key: <你的 key>
+```
+
+本地固定配置文件：
+
+```text
+douyin-topic-discovery-9000AI/local/config.json
+```
+
+## 查看当前调用方
+
+```text
+GET /api/v1/auth/me
+```
+
+## 查看当前已开通能力
+
+```text
+GET /api/v1/auth/capability-permissions
+```
+
+## 获取热榜
+
+```text
+GET /api/v1/douyin/discovery/hot-board?type=society&count=20
+```
+
+可选参数：
+
+- `type`: `hot | city | seeding | entertainment | society | challenge`
+- `count`: `1-50`
+- `city`: 仅 `type=city` 时使用
+
+## 同步关键词试搜
+
+```text
+POST /api/v1/douyin/discovery/search-videos
+```
+
+这个接口现在实际走的是 `search_general_v3`。
+
+请求体：
+
+```json
+{
+  "keywords": ["AI创业", "副业"],
+  "count": 30,
+  "sort": 0,
+  "time": 0,
+  "content_type": 1,
+  "filter_duration": "0",
+  "min_likes": 0,
+  "min_comments": 0,
+  "max_concurrent": 3
+}
+```
+
+说明：
+
+- `count` 现在支持到 `30`
+- 后端会基于 `search_general_v3` 自动翻页聚合，不需要自己传 `cursor`
+- skill 层的 `search` 命令不会把这些执行参数全部暴露给 agent
+- skill 默认按每个关键词 `30` 条提交
+- `max_concurrent` 由后端执行策略控制，不建议 agent 自己调
+
+## 异步批量搜索
+
+提交：
+
+```text
+POST /api/v1/douyin/discovery/search-videos/batch
+```
+
+查询聚合结果：
+
+```text
+GET /api/v1/douyin/discovery/search-videos/batch/{batch_id}/results
+```
+
+skill 工作流：
+
+1. `search` 只提交 batch，立即返回 `batch_id`
+2. `batch-result` 单独查询结果
+3. 查询成功后，skill 再落 `latest_search.json/tsv`
+
+## Skill output 文件
+
+热榜结果：
+
+```text
+douyin-topic-discovery-9000AI/output/latest_hot.json
+douyin-topic-discovery-9000AI/output/latest_hot.tsv
+```
+
+搜索流结果：
+
+```text
+douyin-topic-discovery-9000AI/output/latest_search.json
+douyin-topic-discovery-9000AI/output/latest_search.tsv
+```
+
+每条搜索结果会带：
+
+- `row_no`
+- `video_id`
+- `title`
+- `author_name`
+- `author_uid`
+- `author_sec_uid`
+- `author_unique_id`
+- `video_url`
+- `play_url`
+- `download_url`
+- `media_url`
+- `duration`
+- `likes/comments/shares/collects/plays`

package/skills/douyin-topic-discovery/scripts/douyin_topic_discovery_api.py

@@ -0,0 +1,497 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+HUB_ROOT = REPO_ROOT / "9000AI-hub-9000AI"
+if str(HUB_ROOT) not in sys.path:
+    sys.path.insert(0, str(HUB_ROOT))
+
+from shared.runner import (  # noqa: E402
+    ModuleSpec,
+    configure_stdout_encoding,
+    ensure_output_dir as runner_ensure_output_dir,
+    print_json,
+    request_json,
+    resolve_api_key,
+    resolve_base_url,
+    save_local_config,
+)
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+SEARCH_RESULT_COUNT = 30
+MODULE_SPEC = ModuleSpec(
+    module="douyin-topic-discovery",
+    skill_root=SKILL_ROOT,
+)
+
+
+def ensure_output_dir() -> Path:
+    return runner_ensure_output_dir(MODULE_SPEC)
+
+
+def timestamp_slug() -> str:
+    return datetime.now().strftime("%Y%m%d_%H%M%S")
+
+
+def build_hot_bundle(api_response: dict[str, Any], *, board_type: str, count: int, city: str | None) -> dict[str, Any]:
+    data = api_response.get("data", {})
+    items = []
+    for item in data.get("items", []):
+        items.append(
+            {
+                "row_no": len(items) + 1,
+                "rank": item.get("rank"),
+                "topic": item.get("word", ""),
+                "hot_value": item.get("hot_value", 0),
+                "view_count": item.get("view_count", 0),
+                "video_count": item.get("video_count", 0),
+                "source_id": item.get("sentence_id", ""),
+            }
+        )
+
+    return {
+        "bundle_type": "douyin_hot_board",
+        "saved_at": datetime.now().astimezone().isoformat(),
+        "query": {
+            "board_type": board_type,
+            "board_name": data.get("board_name"),
+            "city": city,
+            "count": count,
+        },
+        "response_meta": {
+            "message": api_response.get("message"),
+            "trace_id": api_response.get("trace_id"),
+            "total": data.get("total", len(items)),
+        },
+        "items": items,
+    }
+
+
+def normalize_search_item(item: dict[str, Any], row_no: int) -> dict[str, Any]:
+    play_url = item.get("play_url")
+    download_url = item.get("download_url")
+    return {
+        "row_no": row_no,
+        "keyword": item.get("keyword", ""),
+        "item_type": item.get("type", 0),
+        "video_id": item.get("aweme_id"),
+        "title": item.get("desc", ""),
+        "desc": item.get("desc", ""),
+        "create_time": item.get("create_time"),
+        "author_name": item.get("author_name", ""),
+        "author_uid": item.get("author_uid"),
+        "author_sec_uid": item.get("author_sec_uid"),
+        "author_unique_id": item.get("author_unique_id"),
+        "video_url": item.get("video_url", ""),
+        "play_url": play_url,
+        "download_url": download_url,
+        "media_url": play_url,
+        "media_is_ephemeral": bool(play_url),
+        "duration": item.get("duration", 0),
+        "image_count": item.get("image_count", 0),
+        "aweme_type": item.get("aweme_type"),
+        "media_type": item.get("media_type"),
+        "stats": {
+            "likes": item.get("likes", 0),
+            "comments": item.get("comments", 0),
+            "shares": item.get("shares", 0),
+            "collects": item.get("collects", 0),
+            "plays": item.get("plays", 0),
+        },
+    }
+
+
+def build_search_batch_bundle(api_response: dict[str, Any], *, request_payload: dict[str, Any], batch_id: str) -> dict[str, Any]:
+    data = api_response.get("data", {})
+    items = []
+    for item in data.get("items", []):
+        items.append(normalize_search_item(item, len(items) + 1))
+
+    task_results = []
+    for task in data.get("tasks", []):
+        task_results.append(
+            {
+                "task_id": task.get("task_id"),
+                "keyword": task.get("keyword", ""),
+                "status": task.get("status", ""),
+                "error": task.get("error"),
+                "item_count": task.get("item_count", 0),
+            }
+        )
+
+    return {
+        "bundle_type": "douyin_video_search",
+        "saved_at": datetime.now().astimezone().isoformat(),
+        "query": request_payload,
+        "response_meta": {
+            "mode": "async_batch",
+            "search_endpoint": "search_general_v3",
+            "message": api_response.get("message"),
+            "trace_id": api_response.get("trace_id"),
+            "batch_id": batch_id,
+            "status": data.get("status"),
+            "total_tasks": data.get("total_tasks", 0),
+            "completed_tasks": data.get("completed_tasks", 0),
+            "success_tasks": data.get("success_tasks", 0),
+            "failed_tasks": data.get("failed_tasks", 0),
+            "total": data.get("total_items", len(items)),
+            "failed_keywords": data.get("failed_keywords", []),
+            "successful_keywords": data.get("successful_keywords", []),
+            "task_results": task_results,
+        },
+        "items": items,
+    }
+
+
+def write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def write_hot_tsv(path: Path, bundle: dict[str, Any]) -> None:
+    with path.open("w", encoding="utf-8-sig", newline="") as handle:
+        writer = csv.DictWriter(
+            handle,
+            fieldnames=["row_no", "rank", "topic", "hot_value", "view_count", "video_count", "source_id"],
+            delimiter="\t",
+        )
+        writer.writeheader()
+        for item in bundle["items"]:
+            writer.writerow(item)
+
+
+def write_search_tsv(path: Path, bundle: dict[str, Any]) -> None:
+    with path.open("w", encoding="utf-8-sig", newline="") as handle:
+        writer = csv.DictWriter(
+            handle,
+            fieldnames=[
+                "row_no",
+                "keyword",
+                "video_id",
+                "title",
+                "author_name",
+                "author_uid",
+                "author_sec_uid",
+                "author_unique_id",
+                "likes",
+                "comments",
+                "shares",
+                "collects",
+                "plays",
+                "duration",
+                "image_count",
+                "video_url",
+                "play_url",
+                "download_url",
+                "media_url",
+                "media_is_ephemeral",
+            ],
+            delimiter="\t",
+        )
+        writer.writeheader()
+        for item in bundle["items"]:
+            writer.writerow(
+                {
+                    "row_no": item["row_no"],
+                    "keyword": item["keyword"],
+                    "video_id": item["video_id"],
+                    "title": item["title"],
+                    "author_name": item["author_name"],
+                    "author_uid": item["author_uid"],
+                    "author_sec_uid": item["author_sec_uid"],
+                    "author_unique_id": item["author_unique_id"],
+                    "likes": item["stats"]["likes"],
+                    "comments": item["stats"]["comments"],
+                    "shares": item["stats"]["shares"],
+                    "collects": item["stats"]["collects"],
+                    "plays": item["stats"]["plays"],
+                    "duration": item["duration"],
+                    "image_count": item["image_count"],
+                    "video_url": item["video_url"],
+                    "play_url": item["play_url"],
+                    "download_url": item["download_url"],
+                    "media_url": item["media_url"],
+                    "media_is_ephemeral": item["media_is_ephemeral"],
+                }
+            )
+
+
+def save_bundle(bundle: dict[str, Any], *, latest_name: str) -> dict[str, str]:
+    output_dir = ensure_output_dir()
+    stamp = timestamp_slug()
+    json_latest = output_dir / f"{latest_name}.json"
+    tsv_latest = output_dir / f"{latest_name}.tsv"
+    json_snapshot = output_dir / f"{latest_name}_{stamp}.json"
+    tsv_snapshot = output_dir / f"{latest_name}_{stamp}.tsv"
+
+    write_json(json_latest, bundle)
+    write_json(json_snapshot, bundle)
+    if bundle["bundle_type"] == "douyin_hot_board":
+        write_hot_tsv(tsv_latest, bundle)
+        write_hot_tsv(tsv_snapshot, bundle)
+    else:
+        write_search_tsv(tsv_latest, bundle)
+        write_search_tsv(tsv_snapshot, bundle)
+
+    return {
+        "json_latest": str(json_latest),
+        "tsv_latest": str(tsv_latest),
+        "json_snapshot": str(json_snapshot),
+        "tsv_snapshot": str(tsv_snapshot),
+    }
+
+
+def resolve_output_path(value: str) -> Path:
+    output_dir = ensure_output_dir()
+    aliases = {
+        "latest_hot": output_dir / "latest_hot.json",
+        "latest_search": output_dir / "latest_search.json",
+    }
+    if value in aliases:
+        return aliases[value]
+    candidate = Path(value)
+    if candidate.exists():
+        return candidate
+    fallback = output_dir / value
+    if fallback.exists():
+        return fallback
+    raise SystemExit(f"找不到结果文件: {value}")
+
+
+def load_bundle(path_value: str) -> dict[str, Any]:
+    path = resolve_output_path(path_value)
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--base-url", default=None)
+    common.add_argument("--api-key", default=None)
+
+    parser = argparse.ArgumentParser(description="Douyin topic discovery API client", parents=[common])
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("configure", help="写入本地配置文件", parents=[common])
+    subparsers.add_parser("whoami", help="查看当前 key 对应的调用方", parents=[common])
+    subparsers.add_parser("capabilities", help="查看当前 key 已开通的能力", parents=[common])
+
+    hot = subparsers.add_parser("hot", help="查询抖音热点榜并落 output 文件", parents=[common])
+    hot.add_argument("--type", default="hot", choices=["hot", "city", "seeding", "entertainment", "society", "challenge"])
+    hot.add_argument("--count", type=int, default=20)
+    hot.add_argument("--city", default=None)
+
+    search = subparsers.add_parser("search", help="按关键词异步提交抖音搜索流批次任务", parents=[common])
+    search.add_argument("keywords", nargs="+")
+    search.add_argument("--sort", type=int, default=0)
+    search.add_argument("--time", type=int, default=0)
+    search.add_argument("--content-type", type=int, default=0, choices=[0, 1, 2])
+    search.add_argument("--filter-duration", default="")
+    search.add_argument("--min-likes", type=int, default=0)
+    search.add_argument("--min-comments", type=int, default=0)
+
+    batch_status = subparsers.add_parser("batch-result", help="按 batch_id 查看异步搜索批次结果并落 output 文件", parents=[common])
+    batch_status.add_argument("--batch-id", required=True)
+
+    subparsers.add_parser("list-output", help="查看 output 目录下的结果文件")
+
+    show_result = subparsers.add_parser("show-result", help="按行查看结果文件中的单条记录")
+    show_result.add_argument("--input", default="latest_search")
+    show_result.add_argument("--row", type=int, required=True)
+
+    export_media = subparsers.add_parser("export-media", help="输出某一行的媒体引用，供后续脚本使用")
+    export_media.add_argument("--input", default="latest_search")
+    export_media.add_argument("--row", type=int, required=True)
+    return parser
+
+
+def main() -> None:
+    configure_stdout_encoding()
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "configure":
+        if not args.base_url or not args.api_key:
+            raise SystemExit("configure 需要同时传 --base-url 和 --api-key")
+        runner_save_local_config = save_local_config
+        runner_save_local_config(MODULE_SPEC, base_url=args.base_url, api_key=args.api_key)
+        print_json({"message": "配置已写入", "config_path": str(MODULE_SPEC.config_path)})
+        return
+
+    if args.command == "list-output":
+        output_dir = ensure_output_dir()
+        files = [
+            {"name": path.name, "path": str(path), "size": path.stat().st_size}
+            for path in sorted(output_dir.glob("*"))
+            if path.is_file()
+        ]
+        print_json({"output_dir": str(output_dir), "files": files})
+        return
+
+    if args.command == "show-result":
+        bundle = load_bundle(args.input)
+        row = next((item for item in bundle.get("items", []) if item.get("row_no") == args.row), None)
+        if not row:
+            raise SystemExit(f"结果文件里不存在 row={args.row}")
+        print_json(row)
+        return
+
+    if args.command == "export-media":
+        bundle = load_bundle(args.input)
+        row = next((item for item in bundle.get("items", []) if item.get("row_no") == args.row), None)
+        if not row:
+            raise SystemExit(f"结果文件里不存在 row={args.row}")
+        payload = {
+            "row_no": row.get("row_no"),
+            "video_id": row.get("video_id"),
+            "author_uid": row.get("author_uid"),
+            "author_sec_uid": row.get("author_sec_uid"),
+            "author_unique_id": row.get("author_unique_id"),
+            "video_url": row.get("video_url"),
+            "play_url": row.get("play_url"),
+            "download_url": row.get("download_url"),
+            "media_url": row.get("media_url"),
+            "media_is_ephemeral": row.get("media_is_ephemeral"),
+        }
+        print_json(payload)
+        return
+
+    base_url = resolve_base_url(MODULE_SPEC, args.base_url)
+    api_key = resolve_api_key(MODULE_SPEC, args.api_key)
+
+    if args.command == "whoami":
+        print_json(
+            request_json(MODULE_SPEC, method="GET", base_url=base_url, api_key=api_key, path="/api/v1/auth/me")
+        )
+        return
+
+    if args.command == "capabilities":
+        print_json(
+            request_json(
+                MODULE_SPEC,
+                method="GET",
+                base_url=base_url,
+                api_key=api_key,
+                path="/api/v1/auth/capability-permissions",
+            )
+        )
+        return
+
+    if args.command == "hot":
+        path = f"/api/v1/douyin/discovery/hot-board?type={args.type}&count={args.count}"
+        if args.city:
+            path += f"&city={args.city}"
+        api_response = request_json(MODULE_SPEC, method="GET", base_url=base_url, api_key=api_key, path=path)
+        bundle = build_hot_bundle(api_response, board_type=args.type, count=args.count, city=args.city)
+        saved = save_bundle(bundle, latest_name="latest_hot")
+        summary = [
+            {
+                "row_no": item["row_no"],
+                "rank": item["rank"],
+                "topic": item["topic"],
+                "hot_value": item["hot_value"],
+            }
+            for item in bundle["items"][:10]
+        ]
+        print_json(
+            {
+                "status": "completed",
+                "message": "已返回抖音热点榜结果",
+                "artifacts": [saved["json_latest"], saved["tsv_latest"]],
+                "data": {"saved": saved, "summary": summary, "total": bundle["response_meta"]["total"]},
+            }
+        )
+        return
+
+    if args.command == "batch-result":
+        api_response = request_json(
+            MODULE_SPEC,
+            method="GET",
+            base_url=base_url,
+            api_key=api_key,
+            path=f"/api/v1/douyin/discovery/search-videos/batch/{args.batch_id}/results",
+        )
+        bundle = build_search_batch_bundle(api_response, request_payload={"batch_id": args.batch_id}, batch_id=args.batch_id)
+        saved = None
+        status_value = str(bundle["response_meta"].get("status") or "").lower()
+        artifacts: list[str] = []
+        if status_value in {"completed", "partial_success", "failed"}:
+            saved = save_bundle(bundle, latest_name="latest_search")
+            artifacts = [saved["json_latest"], saved["tsv_latest"]]
+        print_json(
+            {
+                "status": status_value or "running",
+                "message": "已查询批次结果",
+                "batch_id": args.batch_id,
+                "artifacts": artifacts,
+                "data": {
+                    "saved": saved,
+                    "status": bundle["response_meta"].get("status"),
+                    "total": bundle["response_meta"].get("total"),
+                    "success_tasks": bundle["response_meta"].get("success_tasks"),
+                    "failed_tasks": bundle["response_meta"].get("failed_tasks"),
+                    "failed_keywords": bundle["response_meta"].get("failed_keywords"),
+                    "summary": [
+                        {
+                            "row_no": item["row_no"],
+                            "keyword": item["keyword"],
+                            "title": item["title"],
+                            "author_name": item["author_name"],
+                            "author_sec_uid": item["author_sec_uid"],
+                            "likes": item["stats"]["likes"],
+                            "video_id": item["video_id"],
+                        }
+                        for item in bundle["items"][:10]
+                    ],
+                },
+            }
+        )
+        return
+
+    if args.command == "search":
+        payload = {
+            "keywords": args.keywords,
+            "count": SEARCH_RESULT_COUNT,
+            "sort": args.sort,
+            "time": args.time,
+            "content_type": args.content_type,
+            "filter_duration": args.filter_duration,
+            "min_likes": args.min_likes,
+            "min_comments": args.min_comments,
+        }
+        submit_response = request_json(
+            MODULE_SPEC,
+            method="POST",
+            base_url=base_url,
+            api_key=api_key,
+            path="/api/v1/douyin/discovery/search-videos/batch",
+            payload=payload,
+        )
+        submit_data = submit_response.get("data", {})
+        batch_id = submit_data.get("batch_id")
+        if not batch_id:
+            raise SystemExit(json.dumps(submit_response, ensure_ascii=False, indent=2))
+        print_json(
+            {
+                "status": "submitted",
+                "message": "批次已提交。稍后用 batch-result --batch-id <batch_id> 查询并落 latest_search 文件。",
+                "batch_id": batch_id,
+                "artifacts": [],
+                "data": {
+                    "submitted_keywords": args.keywords,
+                    "tasks": submit_data.get("tasks", []),
+                    "total_tasks": submit_data.get("total_tasks"),
+                    "result_count_per_keyword": SEARCH_RESULT_COUNT,
+                },
+            }
+        )
+        return
+
+
+if __name__ == "__main__":
+    main()