# zhihu-go

**Repository Path**: MM-Q/zhihu-go

## Basic Information

- **Project Name**: zhihu-go
- **Description**: 知乎数据开放平台的 Go 语言 SDK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言, 知乎

## README

<h1 align="center">zhihu-go · 知乎开放平台 Go SDK</h1>

<p align="center">
  <b>知乎数据开放平台的 Go 语言 SDK — 零外部依赖，简洁高效</b>
</p>

<p align="center">
  <a href="https://gitee.com/MM-Q/zhihu-go">
    <img src="https://img.shields.io/badge/repo-gitee.com%2FMM--Q%2Fzhihu-go-blue?style=flat-square&logo=gitee" alt="repo"/>
  </a>
  <a href="https://pkg.go.dev/gitee.com/MM-Q/zhihu-go">
    <img src="https://img.shields.io/badge/go-v1.25+-00ADD8?style=flat-square&logo=go" alt="go version"/>
  </a>
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license"/>
  <img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" alt="build"/>
  <img src="https://img.shields.io/badge/dependencies-zero-orange?style=flat-square" alt="dependencies"/>
  <img src="https://img.shields.io/badge/status-stable-2ea44f?style=flat-square" alt="status"/>
</p>

---

## 📖 项目简介

**zhihu-go** 是[知乎开放平台](https://developer.zhihu.com)数据接口的 Go 语言 SDK。它提供简洁统一的编程接口，让 Go 开发者能够快速集成知乎的直答对话、内容搜索和热榜等数据能力。

> **仓库地址：** [https://gitee.com/MM-Q/zhihu-go](https://gitee.com/MM-Q/zhihu-go)

> ⚠️ **免责声明：** 本库仅供学习、研究和测试使用。请遵守知乎开放平台的服务条款和法律法规，禁止用于任何非法、违规或未经授权的用途。使用者需自行承担一切法律责任。

---

## ✨ 核心特性

- ✅ **零外部依赖** — 全部基于 Go 标准库实现，`go get` 即用
- 🔐 **自动鉴权** — Bearer Token + 时间戳自动注入，无需手动处理认证
- 💬 **直答 API** — 支持非流式和流式（SSE）两种模式，含 `reasoning_content` 思考过程
- 🔍 **知乎搜索** — 站内内容搜索，支持数量控制
- 🌐 **全网搜索** — 全网内容搜索，支持高级 Filter 语法和索引库选择
- 🔥 **知乎热榜** — 实时获取热榜数据
- 🧪 **CLI 工具** — 内置命令行测试工具，开箱即用
- 🧩 **模块化设计** — 每个 API 独立文件，按需引用，易于扩展

---

## 📦 安装

### 前提条件

- Go 1.25 或更高版本

### 安装 SDK

```bash
go get gitee.com/MM-Q/zhihu-go
```

### 安装 CLI 工具（可选）

```bash
go install gitee.com/MM-Q/zhihu-go/cmd/zhihu-cli@latest
```

---

## 🚀 快速开始

### 获取 Access Secret

在[知乎开放平台个人中心](https://developer.zhihu.com/profile)获取你的 Access Secret。

### 基础用法

```go
package main

import (
    "context"
    "fmt"
    "log"

    "gitee.com/MM-Q/zhihu-go"
)

func main() {
    // 创建客户端（默认使用 https://developer.zhihu.com）
    client := zhihu.NewClient("your-access-secret")
    ctx := context.Background()

    // 获取知乎热榜
    hotData, err := client.GetHotList(ctx, 5)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("热榜共 %d 条\n", hotData.Total)
    for _, item := range hotData.Items {
        fmt.Printf("- %s\n", item.Title)
    }
}
```

### 直答 — 非流式

```go
resp, err := client.CreateChatCompletion(ctx, &zhihu.ChatRequest{
    Model: "zhida-thinking-1p5",
    Messages: []zhihu.ChatMessage{
        {Role: "user", Content: "用三句话解释什么是量子计算"},
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Choices[0].Message.Content)
```

### 直答 — 流式

```go
ch, err := client.CreateChatCompletionStream(ctx, &zhihu.ChatRequest{
    Model: "zhida-fast-1p5",
    Messages: []zhihu.ChatMessage{
        {Role: "user", Content: "讲一个关于 AI 的科幻小故事"},
    },
})
if err != nil {
    log.Fatal(err)
}

for event := range ch {
    if event.Error != nil {
        log.Fatal(event.Error)
    }
    if event.ReasoningContent != "" {
        fmt.Printf("[思考] %s\n", event.ReasoningContent)
    }
    fmt.Print(event.Delta)
}
```

### 知乎搜索

```go
result, err := client.SearchZhihu(ctx, "Go语言", 5)
if err != nil {
    log.Fatal(err)
}
for _, item := range result.Items {
    fmt.Printf("[%s] %s (👍 %d)\n", item.ContentType, item.Title, item.VoteUpCount)
}
```

### 全网搜索（高级过滤）

```go
result, err := client.SearchGlobal(ctx,
    "ChatGPT",           // 查询关键词
    10,                  // 返回数量（最大 20）
    `host=="zhihu.com"`, // 筛选表达式
    zhihu.SearchDBAll,   // 索引库（all / realtime / static）
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("共 %d 条结果\n", len(result.Items))
```

---

## 🧪 CLI 工具

zhihu-go 内置了一个命令行测试工具，方便在终端中快速调用各 API。

### 使用方式

```bash
# 设置 Access Secret（也可通过 --access-secret 传入）
export ZHIHU_ACCESS_SECRET=your_secret

# 查看帮助
go run ./cmd/zhihu-cli/ help

# 知乎热榜
go run ./cmd/zhihu-cli/ hot --limit 10

# 知乎搜索
go run ./cmd/zhihu-cli/ search --query "Go语言" --count 5

# 全网搜索
go run ./cmd/zhihu-cli/ global --query "ChatGPT" --count 5 --filter 'host=="zhihu.com"'

# 直答非流式
go run ./cmd/zhihu-cli/ chat --model zhida-thinking-1p5 --message "你好"

# 直答流式
go run ./cmd/zhihu-cli/ chat --model zhida-fast-1p5 --message "讲个故事" --stream
```

### CLI 选项

| 命令 | 功能 | 主要选项 |
|------|------|---------|
| `hot` | 知乎热榜 | `--limit`（默认 30，最大 30） |
| `search` | 知乎搜索 | `--query`, `--count`（默认 10，最大 10） |
| `global` | 全网搜索 | `--query`, `--count`, `--filter`, `--search-db` |
| `chat` | 直答对话 | `--model`, `--message`, `--stream` |
| `help` | 显示帮助 | — |

所有命令支持全局选项：
- `--access-secret`：Access Secret（优先级高于环境变量）
- `--base-url`：自定义 Base URL

---

## 📚 API 文档概述

### Client 构造函数

| 函数 | 说明 |
|------|------|
| `NewClient(accessSecret string)` | 使用默认 Base URL 创建客户端 |
| `NewClientWithBaseURL(accessSecret, baseURL string)` | 使用自定义 Base URL 创建客户端 |

### Client 方法

| 方法 | 说明 | 底层接口 |
|------|------|---------|
| `CreateChatCompletion(ctx, req)` | 直答 — 非流式 | `POST /v1/chat/completions` |
| `CreateChatCompletionStream(ctx, req)` | 直答 — 流式 | `POST /v1/chat/completions` (stream=true) |
| `SearchZhihu(ctx, query, count)` | 知乎站内搜索 | `GET /api/v1/content/zhihu_search` |
| `SearchGlobal(ctx, query, count, filter, searchDB)` | 全网搜索 | `GET /api/v1/content/global_search` |
| `GetHotList(ctx, limit)` | 知乎热榜 | `GET /api/v1/content/hot_list` |

### 核心类型

#### 通用响应

```go
type APIResponse[T any] struct {
    Code    int    `json:"Code"`
    Message string `json:"Message"`
    Data    T      `json:"Data,omitempty"`
}
```

`Code == 0` 表示成功，非零值通过 `*ZhihuError` 返回。

#### 直答请求

```go
type ChatRequest struct {
    Model    string        `json:"model"`              // 模型档位
    Messages []ChatMessage `json:"messages"`           // 消息列表
    Stream   bool          `json:"stream,omitempty"`   // 是否流式
}

type ChatMessage struct {
    Role    string `json:"role"`    // user / assistant
    Content string `json:"content"` // 消息内容
}
```

**模型档位：** `zhida-fast-1p5`（快速回答）、`zhida-thinking-1p5`（深度思考）、`zhida-agent`（智能思考）

#### 流式事件

```go
type StreamEvent struct {
    Delta            string // 内容片段
    ReasoningContent string // 思考过程
    FinishReason     string // 结束原因（stop / error）
    Error            error  // 错误信息
}
```

#### 搜索条目

```go
type SearchItem struct {
    Title           string        `json:"Title"`
    ContentType     string        `json:"ContentType"`     // Answer / Article
    ContentID       string        `json:"ContentID"`
    ContentText     string        `json:"ContentText"`
    Url             string        `json:"Url"`
    CommentCount    int32         `json:"CommentCount"`
    VoteUpCount     int32         `json:"VoteUpCount"`
    AuthorName      string        `json:"AuthorName"`
    EditTime        int64         `json:"EditTime"`
    CommentInfoList []CommentInfo `json:"CommentInfoList,omitempty"`
    AuthorityLevel  string        `json:"AuthorityLevel"`
    RankingScore    float32       `json:"RankingScore"`
}
```

#### 全网搜索索引库

| 常量 | 值 | 说明 |
|------|-----|------|
| `SearchDBAll` | `all` | 全部索引库（默认） |
| `SearchDBRealtime` | `realtime` | 仅实时库 |
| `SearchDBStatic` | `static` | 仅静态库 |

#### 热榜条目

```go
type HotItem struct {
    Title        string `json:"Title"`
    Url          string `json:"Url"`
    ThumbnailUrl string `json:"ThumbnailUrl"`
    Summary      string `json:"Summary"`
}
```

---

## ⚙️ 配置说明

### 鉴权

SDK 自动在每个请求中注入以下 HTTP 头：

| 请求头 | 说明 |
|--------|------|
| `Authorization: Bearer <secret>` | Bearer Token 鉴权 |
| `X-Request-Timestamp: <unix_seconds>` | 当前 Unix 秒级时间戳 |
| `Content-Type: application/json` | 有请求体时自动添加 |

### 自定义 Base URL

适用于使用代理或私有部署场景：

```go
client := zhihu.NewClientWithBaseURL("your-secret", "https://your-proxy.example.com")
```

---

## 📁 项目结构

```
zhihu-go/
├── client.go          # Client 结构体、鉴权、底层 HTTP 请求
├── models.go          # 数据模型与自定义错误类型
├── chat.go            # 直答 API（非流式 + 流式 SSE）
├── search.go          # 知乎搜索 API
├── globalsearch.go    # 全网搜索 API
├── hotlist.go         # 知乎热榜 API
├── cmd/
│   └── zhihu-cli/
│       └── main.go    # CLI 命令行测试工具
├── docs/              # 上游 API 文档
├── go.mod             # Go 模块定义
└── README.md          # 本文件
```

---

## 🧪 测试

当前 SDK 通过 `go build` 和 `go vet` 验证：

```bash
go build ./...      # 编译验证
go vet ./...        # 静态分析
go vet ./cmd/zhihu-cli/  # CLI 工具静态分析
```

> 💡 单元测试正在建设中，欢迎贡献。

---

## 🤝 贡献指南

欢迎通过以下方式参与贡献：

1. 🐛 **报告 Bug** — 在 [Issues](https://gitee.com/MM-Q/zhihu-go/issues) 提交问题
2. 💡 **功能建议** — 提交 Issue 描述你的想法
3. 🔧 **提交代码** — Fork 仓库后提交 Pull Request

### 开发流程

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feat/your-feature`
3. 提交变更：`git commit -m 'feat: add some feature'`
4. 推送分支：`git push origin feat/your-feature`
5. 提交 Pull Request

---

## 📄 许可证

本项目基于 MIT 许可证开源。详见 [LICENSE](LICENSE) 文件。

---

## 🔗 相关链接

- **仓库地址：** [https://gitee.com/MM-Q/zhihu-go](https://gitee.com/MM-Q/zhihu-go)
- **知乎开放平台：** [https://developer.zhihu.com](https://developer.zhihu.com)
- **开放平台控制台：** [https://developer.zhihu.com/profile](https://developer.zhihu.com/profile)
- **Go 官方文档：** [https://go.dev/doc/](https://go.dev/doc/)
- **Issue 反馈：** [https://gitee.com/MM-Q/zhihu-go/issues](https://gitee.com/MM-Q/zhihu-go/issues)

---

<p align="center">
  <sub>Built with ❤️ for the Go community</sub>
  <br>
  <sub>© 2026 MM-Q · 仓库：<a href="https://gitee.com/MM-Q/zhihu-go">gitee.com/MM-Q/zhihu-go</a></sub>
</p>