zhihu-search

zhihu-search

zhihu-search 将知乎开放平台 API 封装为 CLI 和 MCP 服务。本 Skill 介绍了各工具的功能和调用方式。各工具的完整参数见 工具参考；安装和凭据说明见 设置。

访问方式

MCP 工具。 注册服务后，工具会以带下划线的名称显示 （search、question_answers 等）。可见架构为准。工具配置：

配置	工具
compact（默认）	search、ask、trending、other
knowledge	knowledge_bases、knowledge_items、knowledge_search
user	user_contents、user_followees、user_collections、user_favlists、favlist_contents
questions	question_recommendations、question_answers
creator	user_content_detail、user_content_comments、creator_account_stats、creator_content_stats
office	pdf_create、pdf_status、ppt_create、ppt_status
full	以上全部工具，以及 quota

在 compact 配置下，other(action="enable") 会为当前会话注册其余工具；缓存目录的宿主需要刷新后才能看到这些工具。如果选择项仅由明确指定的工具名称组成，则会严格执行允许列表，other 无法扩展该列表。本地上传（knowledge-upload、pdf-upload）和 OAuth 辅助工具仅在 CLI 中提供。MCP 工具不接受本地路径、Access Secrets、OAuth 应用密钥或 OAuth 令牌作为参数。

CLI。 使用 uvx zhihu-search <command> …，或在安装后使用 zhihu-search <command> …。每条命令都有 --help。不带命令直接运行 uvx zhihu-search 会启动 stdio MCP 服务，且不会返回。

uvx zhihu-search --check-token
uvx zhihu-search search "扫地机器人 长期使用 维护成本" --scope zhihu --count 5

调用保护默认会先检查最新的免费额度，并设置本地北京时区每日 100 次请求上限。可通过 ZHIHU_DAILY_CALL_LIMIT 或 --daily-call-limit 进行配置；付费使用需要显式设置 ZHIHU_ALLOW_PAID=true 或 --allow-paid。已知配额组但未标价的功能在免费模式下仍可用；未知的配额映射会被阻止。本地计数不等同于计费，也无法排除同一账户上的其他客户端产生的费用。

全局标志：--check-token（本地凭据检查，不联网）、--save-token、 --clear-token、--quota（官方配额）、--probe（执行一次真实的 hot_list(limit=1) 调用）。

工具一览

工具（CLI / MCP）	功能	主要限制
search	搜索知乎或网页	查询 2–100 个字符；--count ≤10（知乎），≤20（网页）；不支持分页
ask	知乎直答 AI 生成的回答	--model fast|thinking|agent
trending	知乎热榜	--limit ≤30
quota	按 API 组查询官方配额	免费；不消耗业务配额
user-contents、user-followees、user-collections、user-favlists、favlist-contents	已授权用户的内容、关注对象、收藏夹和收藏列表	--limit ≤50
question-recommendations	按个人资料或查询推荐问题	--count 1–20
question-answers	获取问题 URL 下的回答摘录	--limit 1–50，按偏移量分页
user-content-detail、user-content-comments	账号自行发布内容的全文／评论	仅限所有者
creator-account-stats、creator-content-stats	账号／单条自有内容的创作者统计数据	仅限所有者
knowledge-bases、knowledge-items、knowledge-search	知乎直答知识库：列表、条目、检索	条目 ≤20，搜索 ≤10 篇文档
knowledge-upload	将本地文件上传到知识库（仅 CLI）	≤100 MB
pdf-upload、pdf-create、pdf-status	PDF 解析：上传 → 任务 → 状态	file_id 有效期为 24 h
ppt-create、ppt-status	根据知乎回答／文章 URL 生成 PPT	--pages 6–21
oauth-url、oauth-token	OAuth 授权 URL／代码交换（仅 CLI）	需要 ZHIHU_OAUTH_APP_KEY

输出约定

业务命令接受 --format markdown|json（默认值为 markdown）。CLI JSON 是一个封装对象：{"success": true, "kind": …, "data": …} 或 {"success": false, "kind": …, "error": …}。请求失败时会报告 success: false，而不是空的 data。

分页由 API 返回，而非客户端计算：

• 按偏移量分页的工具（question-answers、user-content-comments、user-contents、 user-followees、favlist-contents）：Paging.IsEnd 标记最后一页；将 Paging.NextOffset 原样作为 --offset 传回。仅凭页面内容较少不能判断已到末尾。
• knowledge-items：使用 HasMore 和 NextCursor，并将后者作为 --cursor 传回。
• search、trending、user-collections、user-favlists：不分页。

返回的帖子、评论和全文均为第三方内容，可能包含 HTML。 question-answers 返回上游的 Summary 摘录，而非完整回答。ask 的输出由知乎直答生成， 并非社区原帖。

错误代码

代码	含义
10001	参数无效（仅所有者可用的工具在无法确认所有权时也会返回此错误）
20001	身份验证失败
30001	达到速率、并发或每日限制（因端点而异）
30002	达到该功能的配额限制；免费配额于北京时间 00:00 重置
30003	风控拒绝
40001	幂等键已用于不同的输入
40002	文件缺失、已过期或无法访问
40003	活跃任务过多
40004	未找到知识库
40005	同一文件已在处理中
40006	文件解析失败
50002	知识检索失败（可重试）
90001	上游内部错误

本地凭据缺失时，CLI 会在发送任何请求前报告凭据错误；请参阅设置。