zhihu-search

Zhihu Search Plugin Usage Guide

This plugin wraps four core APIs of the Zhihu Open Platform: Zhihu Search, Web-wide Search, Zhihu Direct Answer, and Hot List. The plugin automatically tracks the daily free quota (1000 times/day, shared between zhihu_search + global_search), and intelligently selects the search source based on question characteristics.

Step 1: Configure the key

Before using any search tool for the first time, you must configure the Access Secret:

1. Guide the user to go to https://developer.zhihu.com/profile to obtain the Access Secret
2. Call the set_zhihu_api_key tool, passing in the accessSecret parameter
3. The tool will automatically verify the validity of the key

The key will be persistently saved in the plugin's data directory, and no repeated configuration is needed afterward.

Tool list and selection strategy

Tool	Purpose	Quota	Suitable scenarios
zhihu_search	Zhihu on-site search	Shared 1000 times per day	General Zhihu content search
global_search	Web-wide search (including Zhihu content)	Shared 1000 times per day	When off-site information or the latest news is needed
zhida	Zhihu Direct Answer (in-depth Q&A)	Independent quota	Complex, analytical questions
hot_list	Zhihu real-time hot list	Not counted toward the limit	Use only when the user explicitly requests it
query_zhihu_quota	Query quota usage	—	Query the remaining number of times today

Intelligent selection logic

When the user makes a search-type request, judge according to the following priority:

1. Check the quota first — If the daily free quota (zhihu_search + global_search) still has remaining
   • Ordinary question → zhihu_search(Zhihu on-site search)
   • Need the latest/web-wide information → global_search(Web-wide search)
2. When the quota is exhausted → automatically switch to zhida(Zhihu Direct Answer), which uses an independent quota
3. Complex question — Regardless of whether the quota is sufficient, if the question has the following characteristics, directly use zhida：
   • The question length exceeds 80 characters
   • Contains multiple question marks or clauses
   • Contains analytical keywords: why, how, principle, mechanism, analysis, comparison, difference, pros and cons, impact, relationship, argumentation, explanation, trend, etc.
4. Hot list —— hot_list Call it only when the user explicitly requests to view the hot list, and must not proactively push or periodically scrape hot list content
5. Quota query — When the user asks "how much quota is left" or "how many times can I search per day", use query_zhihu_quota

Comprehensive examples

User asks: "What is the principle of quantum computing?" → This is a complex question → call zhida

User asks: "What hot news is there recently?" → This is a search need → check the quota:

• Quota available → global_search(Web-wide search)
• Quota exhausted → zhida

User asks: "What's on the Zhihu hot list today?" → User explicitly requests the hot list → call hot_list

User asks: "How many more searches can I do today?" → call query_zhihu_quota

Notes

• All search tools depend on the Access Secret; if it is not configured, a clear message is returned
• API calls carry a Bearer Token and a second-level Unix timestamp; the plugin handles this automatically
• Quota data resets automatically every day (Beijing time)
• zhida does not count toward the free quota, but may have separate billing rules
• hot_list Only call when the user explicitly requests it—do not trigger the hot list on your own within tool calls
• If the user has not provided a key, do not attempt to call the API with an empty key; ask the user to provide it first