Back to Details

zhihu-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

zhihu-search

zhihu-search

Use 
zhihu-search
as a proactive external-information source while keeping repository-local work local. Prefer an available 
zhihu
MCP tool; fall back to 
uvx zhihu-search
only when that MCP tool is unavailable or fails to start. Read references/setup.md only for installation, credentials, MCP configuration, or diagnostics.
在保持仓库本地工作本地化的同时，将
zhihu-search
作为主动获取外部信息的来源。优先使用可用的
zhihu
MCP工具；仅当该MCP工具不可用或启动失败时，才退而使用
uvx zhihu-search
。仅在安装、凭证配置、MCP设置或诊断时阅读references/setup.md。

Route the request

路由请求

Choose exactly one core route unless the user needs both evidence and synthesis:
User intentRouteDefault behavior
Titles, links, sources, current information, experiences, reviews, comparisons, tutorials
search
Prefer 
scope=zhihu
for community viewpoints and 
scope=web
for web-wide research
A direct explanation, synthesis, or analysis
ask
Use 
fast
; use 
thinking
for genuinely complex analysis
Recent hot topics, hot list, or “what people are discussing now”
trending
Return the most relevant current items
Apply this table independently to every item in a multi-part request. For an eligible explanation, synthesis, or analysis item, call 
ask
when its MCP tool is available instead of answering only from model memory.
Prefer 
search
over 
ask
when the user expects inspectable links or source evidence. Use 
ask(model=agent)
only when the user explicitly accepts a slower agent request.
Do not use external Zhihu tools for repository-local code questions, pure math or logic, translation, or transformations limited to text/files the user already provided unless the user also requests external verification.
除非用户同时需要证据和综合内容，否则请选择恰好一个核心路由：
用户意图路由默认行为
标题、链接、来源、实时信息、体验、评价、对比、教程
search
若需社区观点优先使用
scope=zhihu
，若需全网调研则使用
scope=web
直接解释、综合或分析
ask
使用
fast
模式；针对真正复杂的分析使用
thinking
模式
近期热点话题、热榜或“大家现在在讨论什么”
trending
返回最相关的实时内容
对多部分请求中的每个条目独立应用此表格。对于符合条件的解释、综合或分析条目，当对应的MCP工具可用时，请调用
ask
，而非仅依赖模型记忆回答。
当用户期望可查看的链接或来源证据时，优先使用
search
而非
ask
。仅当用户明确接受较慢的agent请求时，才使用
ask(model=agent)
。
请勿针对仓库本地代码问题、纯数学或逻辑问题、翻译或仅限用户提供的文本/文件的转换操作使用外部知乎工具，除非用户同时要求外部验证。

Use MCP first

优先使用MCP

When the MCP catalog exposes the 
zhihu
server, call its matching core tool directly:
  • search(query, scope, count, filter, search_db)
  • ask(query, model)
  • trending(limit)
If the catalog already shows a matching capability tool, call it instead of 
other
or the CLI:
  • knowledge
    profile: 
    knowledge_bases
    , 
    knowledge_items
    , 
    knowledge_search
  • user
    profile: 
    user_contents
    , 
    user_followees
    , 
    user_collections
    , 
    user_favlists
    , 
    favlist_contents
  • office
    profile: 
    pdf_create
    , 
    pdf_status
    , 
    ppt_create
    , 
    ppt_status
Do not run a duplicate CLI request after a successful MCP call. If the matching MCP tool is not available or the server cannot start, use the CLI fallback below.
当MCP目录提供
zhihu
服务时，请直接调用其匹配的核心工具：
  • search(query, scope, count, filter, search_db)
  • ask(query, model)
  • trending(limit)
如果目录已显示匹配的功能工具，请调用该工具而非
other
或CLI：
  • knowledge
    配置文件：
    knowledge_bases
    , 
    knowledge_items
    , 
    knowledge_search
  • user
    配置文件：
    user_contents
    , 
    user_followees
    , 
    user_collections
    , 
    user_favlists
    , 
    favlist_contents
  • office
    配置文件：
    pdf_create
    , 
    pdf_status
    , 
    ppt_create
    , 
    ppt_status
成功调用MCP后，请勿重复执行CLI请求。若匹配的MCP工具不可用或服务无法启动，请使用下方的CLI备选方案。

CLI fallback

CLI备选方案

Check credentials before any fallback operation except 
oauth-url
and 
oauth-token
:
bash
uvx zhihu-search --check-token
This command must report only whether credentials are configured and their source. Never echo a secret fragment or a user-specific credentials path into chat or logs. Use 
--probe
only when an end-to-end upstream check is necessary because it performs one real request.
Then run the narrowest command:
bash
uvx zhihu-search search "<query>" --scope zhihu --count 5
uvx zhihu-search search "<query>" --scope web --count 10
uvx zhihu-search ask "<question>" --model fast
uvx zhihu-search trending --limit 10
Use 
--filter 'host=="example.com"'
only with web search. Keep 
--search-db all
unless the user explicitly asks for 
realtime
or 
static
.
在执行任何备选操作前（除
oauth-url
和
oauth-token
外），请检查凭证：
bash
uvx zhihu-search --check-token
此命令仅需报告凭证是否已配置及其来源。切勿在聊天或日志中输出密钥片段或用户特定的凭证路径。仅当需要端到端上游检查时才使用
--probe
，因为它会执行一次真实请求。
然后运行最精简的命令：
bash
uvx zhihu-search search "<query>" --scope zhihu --count 5
uvx zhihu-search search "<query>" --scope web --count 10
uvx zhihu-search ask "<question>" --model fast
uvx zhihu-search trending --limit 10
仅在全网搜索时使用
--filter 'host=="example.com"'
。除非用户明确要求
realtime
或
static
，否则保持
--search-db all
。

Low-frequency explicit workflows

低频明确工作流

Use these only when the user explicitly asks for the corresponding Zhihu capability. If the matching MCP tool is already visible (for example after 
--tools knowledge
, 
--tools user
, 
--tools office
, or 
--tools full
), call it directly. In compact mode, use 
other(action="enable")
first; do not silently substitute 
search
or 
ask
for a hidden knowledge, user-data, PDF, or PPT tool. If MCP cannot expose the tool, use the CLI.
仅当用户明确请求相应的知乎功能时才使用这些流程。若匹配的MCP工具已可见（例如在执行
--tools knowledge
、
--tools user
、
--tools office
或
--tools full
后），请直接调用该工具。在紧凑模式下，先使用
other(action="enable")
；请勿静默地用
search
或
ask
替代隐藏的知识库、用户数据、PDF或PPT工具。若MCP无法提供该工具，请使用CLI。

Authorized user data

授权用户数据

bash
uvx zhihu-search user-contents --content-type all --limit 20
uvx zhihu-search user-followees --limit 20
uvx zhihu-search user-collections --limit 20
uvx zhihu-search user-favlists --limit 20
uvx zhihu-search favlist-contents --url-token 123456789 --limit 20
Without 
ZHIHU_OAUTH_TOKEN
, these commands query the calling developer's own data. Pass 
Paging.NextOffset
back unchanged through 
--offset
. Official 
favlist-contents
now requires 
--url-token
; 
--id
is kept only for compatibility.
bash
uvx zhihu-search user-contents --content-type all --limit 20
uvx zhihu-search user-followees --limit 20
uvx zhihu-search user-collections --limit 20
uvx zhihu-search user-favlists --limit 20
uvx zhihu-search favlist-contents --url-token 123456789 --limit 20
若无
ZHIHU_OAUTH_TOKEN
，这些命令将查询调用开发者自身的数据。将
Paging.NextOffset
原样通过
--offset
传递。官方的
favlist-contents
现在需要
--url-token
；保留
--id
仅为兼容。

Knowledge bases

知识库

First-time use requires initializing Zhihu Zhida knowledge bases at https://zhida.zhihu.com/repositories/square. Upload only a local file explicitly placed in scope; the maximum size is 100 MB.
bash
uvx zhihu-search knowledge-bases --scope all
uvx zhihu-search knowledge-items "<knowledge_base_id>" --limit 20
uvx zhihu-search knowledge-search "<query>" --recall-scope personal --limit 10
uvx zhihu-search knowledge-upload "<path>" --knowledge-base-id "<knowledge_base_id>"
Prefer the MCP 
knowledge_search
tool when it is already visible. Do not fall back to web 
search
for a private-document question. 
knowledge-search
needs at least one of 
--knowledge-base-id
or 
--recall-scope
. Pass 
NextCursor
back unchanged through 
--cursor
. Do not retry a timed-out or unknown upload.
首次使用需在https://zhida.zhihu.com/repositories/square初始化知乎知达知识库。仅上传明确纳入范围的本地文件；最大文件大小为100 MB。
bash
uvx zhihu-search knowledge-bases --scope all
uvx zhihu-search knowledge-items "<knowledge_base_id>" --limit 20
uvx zhihu-search knowledge-search "<query>" --recall-scope personal --limit 10
uvx zhihu-search knowledge-upload "<path>" --knowledge-base-id "<knowledge_base_id>"
当MCP的
knowledge_search
工具可见时，优先使用该工具。请勿针对私有文档问题退而使用全网
search
。
knowledge-search
至少需要
--knowledge-base-id
或
--recall-scope
中的一个。将
NextCursor
原样通过
--cursor
传递。请勿重试超时或未知的上传操作。

PDF and PPT tasks

PDF和PPT任务

Upload only a local PDF explicitly placed in scope; the maximum size is 100 MB.
bash
uvx zhihu-search pdf-upload "<path.pdf>" --format json
uvx zhihu-search pdf-create "<file_id>"
uvx zhihu-search pdf-status "<task_id>"
uvx zhihu-search ppt-create "<zhihu_resource_url>" --pages 12
uvx zhihu-search ppt-status "<task_id>"
Use an uploaded 
file_id
within 24 hours. The PPT source must be a supported Zhihu answer or article URL, and the page count must be 6–21. Preserve IDs exactly.
Use an idempotency key when retrying task creation and never reuse it for different inputs. Do not poll status aggressively. Treat successful result URLs as short-lived.
仅上传明确纳入范围的本地PDF；最大文件大小为100 MB。
bash
uvx zhihu-search pdf-upload "<path.pdf>" --format json
uvx zhihu-search pdf-create "<file_id>"
uvx zhihu-search pdf-status "<task_id>"
uvx zhihu-search ppt-create "<zhihu_resource_url>" --pages 12
uvx zhihu-search ppt-status "<task_id>"
需在24小时内使用已上传的
file_id
。PPT源必须是支持的知乎回答或文章URL，且页数必须为6–21。请原样保留ID。
重试任务创建时使用幂等键，且切勿将其用于不同输入。请勿频繁轮询状态。将成功的结果URL视为短期有效。

OAuth helpers

OAuth辅助工具

bash
uvx zhihu-search oauth-url "<app_id>" "<redirect_uri>"
uvx zhihu-search oauth-token "<app_id>" "<redirect_uri>" "<authorization_code>"
Require 
ZHIHU_OAUTH_APP_KEY
locally before token exchange. Never place it in arguments or chat. Do not invent undocumented state, scopes, PKCE, refresh/revoke, or user-info flows.
bash
uvx zhihu-search oauth-url "<app_id>" "<redirect_uri>"
uvx zhihu-search oauth-token "<app_id>" "<redirect_uri>" "<authorization_code>"
在本地进行令牌交换前，需确保存在
ZHIHU_OAUTH_APP_KEY
。切勿将其放入参数或聊天内容中。请勿创建未记录的状态、范围、PKCE、刷新/撤销或用户信息流程。

Safety and output

安全与输出

  • Never expose an Access Secret, OAuth app key, or OAuth token in chat, logs, screenshots, or commits.
  • Model-facing tools must never accept a local path, app key, or OAuth token.
  • Preserve opaque offsets, cursors, 
    file_id
    , 
    task_id
    , 
    KnowledgeBaseID
    , 
    RecallContentID
    , and expiring result URLs exactly.
  • Return useful titles, links, attribution, task state, and the quota line when present.
  • State clearly when results are weak or empty.
  • 切勿在聊天、日志、截图或提交记录中暴露访问密钥、OAuth应用密钥或OAuth令牌。
  • 面向模型的工具绝不能接受本地路径、应用密钥或OAuth令牌。
  • 原样保留不透明的偏移量、游标、
    file_id
    、
    task_id
    、
    KnowledgeBaseID
    、
    RecallContentID
    及过期的结果URL。
  • 返回有用的标题、链接、归属信息、任务状态及配额提示（若存在）。
  • 当结果薄弱或为空时，请明确说明。