zhihu-search

用一个命令调用知乎开放平台：搜索、直答、热榜、用户公开数据、知识库、 PDF 解析、PPT 生成和 OAuth 辅助流程。

推荐按下面的顺序选择入口：

顺序	方式	适合场景
1	DSH 插件	DeepSeek Harness 用户；把同一份 Skill 装进 profile
2	Skill	其他 Agent；主动识别任务，按需 CLI，已有 MCP 才复用
3	CLI	临时查询、脚本和调试
4	MCP	在 AI 客户端中高频、持续调用
5	OpenWebUI	少数需要 HTTP 工具服务器的场景

1. DeepSeek Harness 插件

DSH 用户直接安装声明式 bundle。它把同一份 zhihu-search Skill 挂进目标 profile，查询仍按需执行 uvx zhihu-search，不拉起常驻 MCP 进程。 Access Secret 仍由 Python 的用户级凭证文件读取，不进入 DSH 配置。

dsh plugin --profile web add "github:klarkxy/zhihu-search"

安装前先在本机终端 --save-token，并确认 uvx 对启动 DSH 的同一系统 用户可用。安装、验证、更新和移除见 DSH 指南。

2. Skill（推荐）

安装 Skill：

uvx zhihu-search install-skill

该命令调用官方 npx skills，默认把 Skill 全局安装给 Codex。skills CLI 会以 ~/.agents/skills 作为统一来源，并为目标 Agent 建立所需入口。只有明确 需要项目隔离时才使用 uvx zhihu-search install-skill --project，安装到当前 项目的 .agents/skills。也可重复传入 --agent，例如：

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

需要直接调用底层命令时，等价命令为：

npx skills add klarkxy/zhihu-search --skill zhihu-search -g -a codex -y

具体范围规则见 skills CLI 安装范围。 Skill 在已注册 zhihu MCP 时优先调用 search、ask、trending， MCP 不可用时才回退 uvx zhihu-search。因此本机还需安装 uv。uvx 会按需 创建隔离环境，无需长期安装 Python 包。

首次使用只需在自己的终端保存并验证 Access Secret：

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

Access Secret 在 知乎开放平台个人中心创建。不要把它 发到聊天、截图或仓库。

3. CLI

不需要 Agent 时，直接用 uvx：

uvx zhihu-search search "RAG 评测方法" --count 5
uvx zhihu-search ask "什么是 ReAct Agent？" --model thinking
uvx zhihu-search trending --limit 10

用户数据、知识库、PDF、PPT 和 OAuth 也都可以从 CLI 调用：

uvx zhihu-search user-contents --content-type article --limit 10
uvx zhihu-search knowledge-bases --scope all
uvx zhihu-search knowledge-search "退款规则" --recall-scope personal
uvx zhihu-search pdf-upload "./report.pdf"
uvx zhihu-search pdf-create "file_..."
uvx zhihu-search ppt-create "https://zhuanlan.zhihu.com/p/123" --pages 12
uvx zhihu-search oauth-url "<app_id>" "<redirect_uri>"

所有业务命令支持 --format json。完整参数见：

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

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

4. MCP（高频集成）

MCP 默认使用 compact，只暴露三个常用工具和一个按需入口：

Codex 的普通、低频查询应安装 Skill 后按需运行 CLI，不需要全局注册 MCP。 只有用户明确要求高频常驻集成，并接受客户端的进程生命周期时才配置 MCP。 Codex 专用说明见 setup/codex.md。其他 MCP 客户端可启动：

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

档位	暴露内容
compact（默认）	search、ask、trending、other
knowledge	compact 加 3 个知识库工具
user	compact 加 5 个用户数据工具
office	compact 加 2 个 PDF 和 2 个 PPT 工具
full	全部 16 个工具

档位和工具名可以逗号混写，结果取并集，例如 knowledge,user 或 compact,knowledge_search。只写工具名则是严格 allowlist，例如 search,ask,pdf_status。

other 管理当前 MCP 会话中的低频工具：

• enable：展开 5 个用户数据工具、3 个知识库工具、2 个 PDF 工具和 2 个 PPT 工具。
• disable：收起这 12 个工具。
• reset：恢复启动时的工具集合。

只要选择里出现档位名，other 就能管理全部 12 个低频工具；纯工具名的严格 allowlist 下，它只能管理列表里已经允许的低频工具，不能越过开关。

也可以用 ZHIHU_MCP_TOOLS 设置默认配置；命令行 --tools 优先于环境 变量。常用写法：

uvx zhihu-search serve --tools knowledge   # 自建知识库检索常驻可见
uvx zhihu-search serve --tools full        # 一次暴露全部显式工具

通用 JSON 配置：

…