Zhihu Search

zhihu-search

Use the zhihu-search Skill as the single entry point for Chinese-community research while keeping repository-local work local. After the Skill routes the request, reuse a matching zhihu MCP tool when the current catalog already exposes it; otherwise run one narrow uvx zhihu-search command on demand. Never add a persistent MCP server merely to complete an occasional request. Read references/setup.md only for installation, credentials, optional high-frequency MCP integration, or diagnostics.

Route the request

Choose exactly one core route unless the user needs both evidence and synthesis:

Apply this table independently to every item in a multi-part request. For an eligible explanation, synthesis, or analysis item that needs Chinese-community evidence, run ask 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.

Use visible MCP tools when available

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:

• official account quota: quota
• 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. Do not register or start a persistent MCP server unless the user explicitly asks for high-frequency MCP integration.

Otherwise run one command on demand

Check credentials before any operation except oauth-url and oauth-token:

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 exactly one narrow command for the routed intent:

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

Never invoke bare uvx zhihu-search: without a subcommand it starts the MCP server. Use --filter 'host=="example.com"' only with web search. Keep --search-db all unless the user explicitly asks for realtime or static.

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 quota, knowledge, user-data, PDF, or PPT tool. If MCP cannot expose the tool, use the CLI.

Official quota

Use Zhihu's official quota endpoint as the only quota source. Do not infer usage from local calls, maintain a local counter, or impose a client-side circuit breaker. The query itself does not consume business quota.

uvx zhihu-search quota
uvx zhihu-search quota --api-id knowledge --api-id tools

Preserve TotalQuota, TotalUsed, and RemainingQuota as returned. Do not invent a reset time; the official documentation describes a natural-day quota but does not specify its timezone or exact reset instant.

Authorized user data

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.

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.

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.

PDF and PPT tasks

Upload only a local PDF explicitly placed in scope; the maximum size is 100 MB.

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.

OAuth helpers

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.

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, and task state. For quota requests, report the official total, used, and remaining values.
• State clearly when results are weak or empty.