Metadata-Version: 2.5
Name: yby-search
Version: 0.1.0
Summary: yby — command-line client for Tencent Yuanbao Search (元宝搜索) web search API
Project-URL: Homepage, https://cloud.tencent.com/developer/mcp/server/11764
Project-URL: Documentation, https://cloud.tencent.com/developer/mcp/server/11764
Author: yby contributors
License: MIT
License-File: LICENSE
Keywords: cli,mcp,search,tencent,web-search,wsa,yuanbao
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# yby — 元宝搜索命令行工具

`yby` 是腾讯云**元宝搜索**（Tencent Yuanbao Search / WSA）的命令行客户端，
在终端里一行命令完成联网搜索，返回标题、来源站点、发布时间、链接和正文摘要。

它调用元宝搜索的托管 MCP 接口（`https://api.wsa.cloud.tencent.com/Mcp`，
JSON-RPC 2.0 over Streamable HTTP）的 `SearchPro` 工具。
纯 Python 标准库实现，**零第三方依赖**。

## 安装

```bash
# 直接运行（不安装）
uvx --from yby-search yby "南京明天天气" --mode 1

# 用 uv 装成常驻命令
uv tool install yby-search

# 或者用 pip
pip install yby-search
```

装好后命令名就是 `yby`。

## 准备 API KEY

1. 登录[腾讯云元宝搜索控制台](https://console.cloud.tencent.com/wsa)，开通元宝搜索服务；
2. 在控制台创建**服务 API KEY** 并保存（不是云 API 的 SecretId/SecretKey）；
3. 把 KEY 放进环境变量：

```bash
export YBY_API_KEY="你的 API KEY"
```

也可以用 `TENCENT_WSA_API_KEY`，或临时用 `--api-key` 参数传入（不推荐，命令行参数会留在 shell 历史里）。

## 用法

```bash
# 普通搜索
yby "SNH48 水上运动会 名单"

# 权威垂直信源（天气、金价、股价等实时信息）
yby "上海今天天气" --mode 1

# 只搜某个站点、只要最近 7 天、要 20 条
yby "大模型 最新进展" --site zhihu.com --freshness d7 --cnt 20

# 垂直领域：gov / news / acad / finance
yby "最新产业政策" --industry gov

# 输出完整 JSON（方便接管道和脚本）
yby "腾讯股价" --mode 1 --json | jq .
```

## 参数

| 参数 | 说明 |
|---|---|
| `query` | 搜索词，必填，约 500 字以内 |
| `--mode` | 0 公开网页信源（默认）；1 优质权威垂直信源（天气、金价、股价等实时信息）；2 混合 |
| `--site` | 限定站点，如 `zhihu.com` |
| `--freshness` | 时效范围：`d[N]` 最近 N 天（1–30）、`m[N]` 最近 N 月（1–12）、`y[N]` 最近 N 年（1–5） |
| `--cnt` | 返回条数：10 / 20 / 30 / 40 / 50 |
| `--industry` | 垂直领域：`gov` 党政机关、`news` 权威媒体、`acad` 学术、`finance` 金融 |
| `--json` | 输出完整 JSON 响应 |
| `--api-key` | 直接传 API KEY（优先用环境变量） |

退出码：`0` 成功；`1` 接口或搜索错误；`2` 缺少 API KEY 等用法错误。

## 常见报错

- `UnauthorizedOperation`：API KEY 不正确、已被删除，或服务未开通——去控制台检查；
- `ResourceNotFound`：服务未开通，在控制台开通后等几分钟生效；
- `ResourceUnavailable`：账号欠费，去费用中心冲正；
- `RequestLimitExceeded`：请求过于频繁，稍后再试。

## English summary

`yby` is a zero-dependency command-line client for Tencent Yuanbao Search.
Install with `uv tool install yby-search` (or `pip install yby-search`),
set `YBY_API_KEY` to an API key created in the Tencent Cloud Yuanbao Search
console, then run `yby "your query"`.

## License

MIT
