Metadata-Version: 2.5
Name: zhihu-search
Version: 2.0.0
Summary: 知乎开放平台的 Skill、CLI、MCP 与 OpenAPI 工具
Project-URL: Homepage, https://github.com/klarkxy/zhihu-search
Project-URL: Repository, https://github.com/klarkxy/zhihu-search
Project-URL: Issues, https://github.com/klarkxy/zhihu-search/issues
Project-URL: Documentation, https://github.com/klarkxy/zhihu-search#readme
Author-email: Klarkxy <278370456@qq.com>
License:             The Star And Thank Author License (SATA)
                            Version 2.0, April 2021
        
        Copyright © 2026 Klarkxy(278370456@qq.com)
        
        Project Url: https://github.com/klarkxy/zhihu-search
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        And wait, the most important, you should star/+1/like the project(s) in project url
        section above first, and then thank the author(s) in Copyright section.
        
        Here are some suggested ways:
        
         - Email the authors a thank-you letter, and make friends with him/her/them.
         - Report bugs or issues.
         - Tell friends what a wonderful project this is.
         - And, sure, you can just express thanks in your mind without telling the world.
        
        Contributors of this project by forking have the option to add his/her name and
        forked project url at copyright and project url sections, but shall not delete
        or modify anything else in these two sections.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=3.4.0
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# zhihu-search

用一个命令调用知乎开放平台：搜索、直答、热榜、官方额度、用户公开数据、
知识库、PDF 解析、PPT 生成和 OAuth 辅助流程。

## 2.0 迁移提示

额度现在完全以知乎官方 `GET /api/v1/quota` 为准。`quota` 与 `--quota`
查询官方总额度、已用额度和剩余额度；本地计数、熔断、`--reset-quota`，以及
CLI JSON、Python `ApiResult` / `CommandResult`、OpenAPI 响应中的本地
`quota` 字段均已移除。已有的本机 `quota.json` 不会被删除，但不再读取。

推荐按下面的顺序选择入口：

| 顺序 | 方式 | 适合场景 |
|---:|---|---|
| 1 | **DSH 插件** | DeepSeek Harness 用户；把同一份 Skill 装进 profile |
| 2 | **Skill** | 其他 Agent；主动识别任务，按需 CLI，已有 MCP 才复用 |
| 3 | **CLI** | 临时查询、脚本和调试 |
| 4 | **MCP** | 在 AI 客户端中高频、持续调用 |
| 5 | **OpenWebUI** | 少数需要 HTTP 工具服务器的场景 |

## 1. DeepSeek Harness 插件

DSH 用户直接安装声明式 bundle。它把同一份 `zhihu-search` Skill 挂进目标
profile，查询仍按需执行 `uvx zhihu-search`，不拉起常驻 MCP 进程。
Access Secret 仍由 Python 的用户级凭证文件读取，不进入 DSH 配置。

```bash
dsh plugin --profile web add "github:klarkxy/zhihu-search"
```

安装前先在本机终端 `--save-token`，并确认 `uvx` 对启动 DSH 的同一系统
用户可用。安装、验证、更新和移除见 [DSH 指南](setup/dsh.md)。

## 2. Skill（推荐）

安装 Skill：

```bash
uvx zhihu-search install-skill
```

该命令调用官方 `npx skills`，默认把 Skill 全局安装给 Codex。skills CLI
会以 `~/.agents/skills` 作为统一来源，并为目标 Agent 建立所需入口。只有明确
需要项目隔离时才使用 `uvx zhihu-search install-skill --project`，安装到当前
项目的 `.agents/skills`。也可重复传入 `--agent`，例如：

```bash
uvx zhihu-search install-skill --agent codex --agent claude-code
```

需要直接调用底层命令时，等价命令为：

```bash
npx skills add klarkxy/zhihu-search --skill zhihu-search -g -a codex -y
```

具体范围规则见 [skills CLI 安装范围](https://github.com/vercel-labs/skills#installation-scope)。
Skill 在已注册 `zhihu` MCP 时优先调用 `search`、`ask`、`trending`，
MCP 不可用时才回退 `uvx zhihu-search`。因此本机还需安装
[uv](https://docs.astral.sh/uv/getting-started/installation/)。`uvx` 会按需
创建隔离环境，无需长期安装 Python 包。

首次使用只需在自己的终端保存并验证 Access Secret：

```bash
uvx zhihu-search --save-token "<你的 Access Secret>"
uvx zhihu-search --probe
```

Access Secret 在
[知乎开放平台个人中心](https://developer.zhihu.com/personal)创建。不要把它
发到聊天、截图或仓库。

## 3. CLI

不需要 Agent 时，直接用 `uvx`：

```bash
uvx zhihu-search search "RAG 评测方法" --count 5
uvx zhihu-search ask "什么是 ReAct Agent？" --model thinking
uvx zhihu-search trending --limit 10
uvx zhihu-search quota --api-id knowledge
```

用户数据、知识库、PDF、PPT 和 OAuth 也都可以从 CLI 调用：

```bash
uvx zhihu-search user-contents --content-type article --limit 10
uvx zhihu-search knowledge-bases --scope all
uvx zhihu-search knowledge-search "退款规则" --recall-scope personal
uvx zhihu-search pdf-upload "./report.pdf"
uvx zhihu-search pdf-create "file_..."
uvx zhihu-search ppt-create "https://zhuanlan.zhihu.com/p/123" --pages 12
uvx zhihu-search oauth-url "<app_id>" "<redirect_uri>"
```

所有业务命令支持 `--format json`。完整参数见：

```bash
uvx zhihu-search --help
uvx zhihu-search <command> --help
```

在仓库目录验证尚未发布的代码时，把命令开头改为
`uvx --from . zhihu-search`。

## 4. MCP（高频集成）

MCP 默认使用 `compact`，只暴露三个常用工具和一个按需入口：

Codex 的普通、低频查询应安装 Skill 后按需运行 CLI，不需要全局注册 MCP。
只有用户明确要求高频常驻集成，并接受客户端的进程生命周期时才配置 MCP。
Codex 专用说明见 [setup/codex.md](setup/codex.md)。其他 MCP 客户端可启动：

```text
command: uvx
args:    zhihu-search serve --tools compact
```

| 档位 | 暴露内容 |
|---|---|
| `compact`（默认） | `search`、`ask`、`trending`、`other` |
| `knowledge` | compact 加 3 个知识库工具 |
| `user` | compact 加 5 个用户数据工具 |
| `office` | compact 加 2 个 PDF 和 2 个 PPT 工具 |
| `full` | 全部 17 个工具 |

档位和工具名可以逗号混写，结果取并集，例如 `knowledge,user` 或
`compact,knowledge_search`。只写工具名则是严格 allowlist，例如
`search,ask,pdf_status`。

`other` 管理当前 MCP 会话中的低频工具：

- `enable`：展开官方额度、5 个用户数据、3 个知识库、2 个 PDF 和 2 个 PPT 工具。
- `disable`：收起这 13 个工具。
- `reset`：恢复启动时的工具集合。

只要选择里出现档位名，`other` 就能管理全部 13 个低频工具；纯工具名的严格
allowlist 下，它只能管理列表里已经允许的低频工具，不能越过开关。

也可以用 `ZHIHU_MCP_TOOLS` 设置默认配置；命令行 `--tools` 优先于环境
变量。常用写法：

```bash
uvx zhihu-search serve --tools knowledge   # 自建知识库检索常驻可见
uvx zhihu-search serve --tools full        # 一次暴露全部显式工具
```

通用 JSON 配置：

```json
{
  "mcpServers": {
    "zhihu": {
      "command": "uvx",
      "args": ["zhihu-search", "serve", "--tools", "compact"]
    }
  }
}
```

注册 MCP 后，`zhihu-search` Skill 会优先使用这三个核心工具，避免重复执行
同一条 CLI 查询。

客户端指南：

- [Codex](setup/codex.md)
- [Claude Code](setup/claude-code.md)
- [OpenCode](setup/opencode.md)
- [HanaAgent](setup/hanako-agent.md)

PDF / 知识库本机上传和 OAuth token 交换仍只允许 CLI/Python 执行，不会
成为模型可调用的工具。

## 5. OpenWebUI（少数场景）

只有需要 HTTP OpenAPI 工具服务器时才使用：

```bash
uvx zhihu-search openwebui \
  --host 0.0.0.0 --port 8000 --api-key "<服务访问口令>"
```

在 Open WebUI 中添加 External Tool Server：

- URL：`http://<server>:8000`
- Authentication：Bearer token

也可用 `ZHIHU_OPENWEBUI_API_KEY` 设置访问口令。未配置口令时服务不做
入站认证，只能用于 localhost 或受控私网。

更完整的安装说明见 [setup/README.md](setup/README.md)。

## 能力覆盖

| 能力 | 端点数 | 说明 |
|---|---:|---|
| 搜索、直答、热榜 | 4 | 知乎搜索、全网搜索、直答、热榜 |
| 官方额度 | 1 | 查询各 API 的总额度、已用额度和剩余额度 |
| 用户公开数据 | 5 | 创作、关注、近期收藏和收藏夹 |
| 知识库 | 4 | 列表、内容、上传、检索 |
| PDF 解析 | 3 | 上传、创建任务、查询状态 |
| PPT 生成 | 2 | 创建任务、查询状态 |
| OAuth 辅助 | 2 | 授权 URL、授权码换 token |

逐端点说明、官方文档差异和安全边界见
[API_COVERAGE.md](docs/API_COVERAGE.md)。

## 凭证与诊断

Access Secret 读取顺序：

1. `ZHIHU_ACCESS_SECRET`
2. `~/.config/zhihu-search/credentials.json`

```bash
uvx zhihu-search --check-token
uvx zhihu-search --probe
uvx zhihu-search --quota
uvx zhihu-search --clear-token
```

`--check-token` 只报告是否已配置及凭证来源，不输出 Secret 片段或本机凭证
路径；`--probe` 会真实调用一次 `hot_list(limit=1)` 并消耗一次请求额度；
`--quota` 调用官方额度接口，查询本身不消耗业务额度，也不再使用本地计数。

常见问题：

| 现象 | 处理 |
|---|---|
| 找不到 `uvx` | 安装 uv 后重开终端 |
| 凭证不存在或失效 | 回个人中心创建并重新保存 Access Secret |
| `Code=30002` | 运行 `--quota` 查看官方剩余额度，再检查接口权限 |
| MCP 工具未出现 | 检查配置后重启客户端 |
| PDF/PPT 长时间处理中 | 稍后再查状态，不要紧密轮询 |
| 知识库列表为空 | 先登录 [直答知识库](https://zhida.zhihu.com/repositories/square) 完成初始化 |

Agent 代为安装和验证时，参见 [AGENT_SETUP.md](AGENT_SETUP.md)。

## 开发

```bash
git clone https://github.com/klarkxy/zhihu-search
cd zhihu-search
uv sync --extra dev
uv run pytest
uv build
```

## 许可证

[SATA License v2.0](LICENSE)
