知乎搜索 klarkxy/zhihu-search

zhihu-search

让智能体按需查找知乎与中文社区信息，也可以直接调用知乎开放平台的搜索、直答、热榜、额度、本人公开数据、问题发现、创作能力、知识库、PDF、PPT 和 OAuth 辅助能力。

从技能开始

对大多数人来说，安装技能就够了。它会在需要中文社区观点、真实体验、口碑、避坑信息或国内热点时选择合适的查询方式，不会仅因为问题是中文就触发；平时不会启动常驻服务。

1. 安装技能

这一步需要 uvx 和 npx。如果还没有，请先安装
uv 和
Node.js；安装后重新打开终端。

uvx zhihu-search install-skill

默认会通过官方 npx skills 全局安装给 Codex。安装完成后，新建一个 Codex 任务，让客户端重新加载技能。

2. 保存知乎 Access Secret

在知乎开放平台个人中心创建 Access Secret，然后只在自己的终端执行：

uvx zhihu-search --save-token "<你的 Access Secret>" uvx zhihu-search --check-token

不要把 Access Secret 发到聊天、截图或仓库。--check-token 不发请求；想确认端到端连通时，可以选做一次 uvx zhihu-search --probe，它会真实请求一次知乎热榜并消耗一次 hot_list 额度，不要循环执行。

3. 直接告诉智能体你想查什么

例如：

帮我查一下最近主流的 RAG 评测方法在中文开发者社区的讨论，返回 3 条并附来源链接。

技能会按所需证据选择搜索、直答或热榜：先查一次，证据够就直接回答，只有关键缺口时才定向补查。如果当前客户端已经提供匹配的 zhihu MCP 工具，它会直接复用，不会再走命令行重复查询。

需要安装到其他智能体，或只安装到当前项目时：

uvx zhihu-search install-skill --agent codex --agent claude-code
uvx zhihu-search install-skill --project

完整的安装范围和验收方法见安装与配置；由智能体代为配置时，请看 智能体安装与验证指南。

高频使用时再配置 MCP

如果你会在同一个 AI 客户端里持续、高频调用知乎能力，可以把 MCP 作为第二选择。偶尔查询不需要配置它：技能本身不依赖 MCP，而且常驻 stdio 服务会跟随客户端的进程生命周期。

通用启动配置：

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

compact 默认只展示三个核心工具和一个会话内开关：

- search：知乎或全网搜索；
- ask：知乎直答；
- trending：知乎热榜；
- other：在当前会话内展开、收起或复原低频工具。

按长期需要选择档位：

| 档位 | 常驻可见的能力 |
| compact（默认） | search、ask、trending、other |
| knowledge | compact 加 3 个知识库工具 |
| user | compact 加 5 个用户数据工具 |
| questions | compact 加问题推荐和问题回答摘要 |
| creator | compact 加全文、评论和 2 个创作统计工具 |
| office | compact 加 2 个 PDF 和 2 个 PPT 工具 |
| full | 22 个业务/账号工具加 other，共 23 个 |

档位和工具名可以用逗号组合，例如 knowledge,user 或 compact,knowledge_search。只写工具名时是严格 allowlist，例如 search,ask,pdf_status。ZHIHU_MCP_TOOLS 可以设置默认值，命令行 --tools 的优先级更高。

other 的 enable、disable、reset 只影响当前 MCP 会话。使用档位时，它能管理全部 19 个低频工具；使用纯工具名 allowlist 时，它不能越过启动时的允许范围。

客户端配置：

- Codex
- Claude Code
- OpenCode
- HanaAgent / OpenHanako

PDF/知识库本机上传和 OAuth token 交换不会暴露为模型可调用工具，只能从命令行或 Python 执行。

其他入口

这些方式解决的是特定需求，不需要和技能一起全部安装。

直接使用命令行

适合临时查询、脚本和调试：

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

低频能力同样可以直接调用：

uvx zhihu-search user-contents --content-type article --limit 10
uvx zhihu-search question-recommendations --query "AI Agent" --count 5
uvx zhihu-search question-answers "https://www.zhihu.com/question/123"
uvx zhihu-search user-content-detail "https://zhuanlan.zhihu.com/p/123"
uvx zhihu-search creator-account-stats --content-type all
uvx zhihu-search knowledge-search "退款规则" --recall-scope personal uvx zhihu-search pdf-upload "./report.pdf" uvx zhihu-search ppt-create "https://zhuanlan.zhihu.com/p/123" --pages 12

所有业务命令都支持 --format json。完整参数以帮助信息为准：

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

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

DeepSeek Harness

DSH 插件已迁到 plugins/dsh-zhihu，本仓库不再维护它：

dsh plugin --profile web add @klarkxy/dsh-zhihu

安装和从旧安装包切换的步骤见 DSH 指南。

OpenWebUI

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

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

在 Open WebUI 中添加 External Tool Server，地址填 http://<server>:8000，认证方式选择 Bearer token。未配置访问口令时，服务只能用于 localhost 或受控私网。

能做什么

| 能力 | 端点数 | 说明 |
| 搜索、直答、热榜 | 4 | 知乎搜索、全网搜索、直答、热榜 |
| 问题发现 | 2 | 适合回答的问题，以及问题下的回答摘要 |
| 官方额度 | 1 | 总额度、已用额度和剩余额度 |
| 本人公开数据 | 5 | 创作、关注、近期收藏和收藏夹 |
| 创作能力 | 4 | 本人全文、评论、账号统计和单篇统计 |
| 知识库 | 4 | 列表、内容、上传、检索 |
| PDF 解析 | 3 | 上传、创建任务、查询状态 |
| PPT 生成 | 2 | 创建任务、查询状态 |
| OAuth 辅助 | 2 | 授权 URL、授权码换 token |

逐端点说明、官方文档差异和安全边界见 API 覆盖与边界。

凭证与排障

Access Secret 的读取顺序是：

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

常用诊断命令：

uvx zhihu-search --check-token
uvx zhihu-search --probe # 可选，消耗一次 hot_list 额度 uvx zhihu-search --quota uvx zhihu-search --clear-token

--check-token 只显示配置状态和来源，不会输出 Secret 片段或本机凭证路径； --quota 查询知乎官方额度，不读取本地计数，也不消耗业务额度。

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

2.0 迁移说明

官方剩余额度以 GET /api/v1/quota 为准。旧的本地余额预测、 --reset-quota 以及各类响应中的本地 quota 字段已经移除。旧的本机 quota.json 不会被删除，但也不会再读取。

开发

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

许可证

SATA License v2.0

调用与费用保护（2026-10-13）

默认是免费保护模式：每个业务请求先即时查询对应的官方免费额度；查询失败、缺少有效额度、额度不足或映射未确认时，不发送业务请求。额度查询本身不递归预查、不消耗本地上限。工具名及业务路径保持原样；旧额度输入 question_answers 映射为 question_discovery，问题推荐和回答摘要共用该组。

本地北京时间每日上限默认 100 次，可设为 1–100000。计数口径是已持久化预留的业务请求：包括已发送后失败、取消或结果未知的请求；预查失败不占用上限。它与官方免费次数、已有本地工具使用统计、钱包和账单分别处理，不估算费用或余额。

免费模式可使用有可靠额度映射的 fast/thinking 直答、问题推荐以及 PDF/PPT 任务；缺少单价不影响使用已确认的免费额度。显式付费模式对未确认计费的能力保守拒绝，并提示切换回免费保护模式。通用资源文件上传尚无可靠额度映射，暂时阻止；知识库上传的 knowledge 映射已确认。
两个客户端共用 ~/.config/zhihu-search/call-policy/daily.json 和 request.lock；ZHIHU_SEARCH_HOME 可以改变根目录，ZHIHU_CALL_POLICY_DIR 可以显式指定共同保护目录。同目录内所有账号/进程共用一个本地上限，避免多 Secret 或多入口绕开计数；自定义目录时，需让两项目使用同一路径。锁覆盖预查与请求，状态先原子预留，不缓存额度、不自动重试。网络失败或取消后的未知请求保守占用对应免费容量，跨日仍保留这些未知预留。

本地保护不能承诺绝对零费用：同账号其他客户端可能在预查后竞争免费额度，平台扣费时间也不由本机控制。结果未知时先在官方控制台核对，不盲目重试。进程崩溃留下的锁不会自动抢占；确认两个客户端均无在途请求、核对未知请求后，才可手动移除 request.lock。损坏的计数文件会失败关闭，不自动清零。

鉴权和账号设置保持不变。不提供充值、权益兑换或钱包查询。官方依据：服务价格、免费额度、线上订购协议（V1.0，2026-10-10 生效）。API 计费不扩大内容访问或传播授权范围。

CLI、MCP 与 OpenAPI 配置

默认无需新配置。环境变量 ZHIHU_ALLOW_PAID=true 显式允许已确认计费能力付费续用，ZHIHU_DAILY_CALL_LIMIT=200 调整每日上限；未设置时分别为 false 和 100。CLI 全局参数也可用于本次进程：

zhihu-search --daily-call-limit 50 search "普通资料" zhihu-search --allow-paid --daily-call-limit 50 search "普通资料"

参数需放在子命令前。MCP/OpenAPI 服务通过启动环境配置这些选项，模型工具参数不能改变付费开关。门禁在共享 REST 调用层，涵盖 GET、POST、知识库上传、直答和任务请求。

官方额度更新也可能滞后：免费模式每次仍查询官方值，同时保留本机已消耗预留的容量上限，取更保守的值，不在当天自动补回；这个内部上限不会作为官方余额展示。次日按北京时间重置，结果未知的预留仍保留。