Skip to content

README.zh.md

Latest commit

 

History

History
320 lines (255 loc) · 13.3 KB

README.zh.md

File metadata and controls

320 lines (255 loc) · 13.3 KB

Zread - AI 代码仓库阅读助手

中文 | English

Python zread MCP CLI Transport I18N PyPI Downloads License

Zread 让你和你的 AI 都更懂代码。代码不用看，直接问。连接 Zread.ai，AI 驱动的 GitHub 项目文档。

双重身份：

  • 🖥️ CLI 工具 - 直接在终端运行，无需配置
  • 🔌 MCP 服务器 - 与 Claude、Cline 等 AI 助手集成

核心特点：

  • 🔍 无需 Token 即可浏览文档、搜索代码、发现仓库
  • 🤖 支持 AI 智能问答（基于仓库文档训练）
  • 🌐 支持多种传输协议：stdio、HTTP、SSE
  • ⚡ 一行命令即可运行，零配置上手

功能

  • 📖 阅读文档 - 直接在终端浏览 GitHub 仓库文档
  • 🔍 搜索代码 - 在仓库文档中搜索关键词
  • 🌟 发现仓库 - 浏览热门榜单、搜索优质项目
  • 📥 导出文档 - 批量导出仓库文档到本地，生成 llms.txt 和 llms-full.txt（CLI 专属）
  • 🤖 AI 问答 - 向仓库 AI 助手提问（需登录账号的免费 Token）
  • 📄 查看源码 - 读取源代码文件内容
  • 🔌 MCP 集成 - 与 AI 助手无缝集成

运行示例

帮助信息
zread -h

zread help 		文档目录
zread ls openclaw/openclaw

zread ls 		查看文档页
zread cat openclaw/openclaw

zread cat wiki 		查看 GitHub 文件
zread cat facebook/react README.md

zread cat github
搜索仓库
zread find ai sandbox

zread find repo 		搜索文档
zread find openclaw/openclaw gateway

zread find wiki 		热门仓库
zread top

zread top 		随机推荐
zread rand agent-skills

zread rand
单轮 AI 提问
zread ai openclaw/openclaw 介绍这个库 简单讲讲

zread ai ask 		交互式 AI 对话
zread ai openclaw/openclaw

zread ai chat 		导出仓库文档
zread cp openclaw/openclaw

zread cp 		MCP HTTP 服务
zread mcp http :8080

zread mcp http

快速启动

命令行工具

# 使用 uvx 运行
uvx zread

# 或使用 pipx
pipx run zread

MCP 服务器

# stdio 模式
uvx zread mcp

# HTTP 模式
uvx zread mcp http

AI 问答

AI 问答功能需要登录 Zread.ai 账号获取免费 Token。

配置 Token：

# 设置环境变量
export ZREAD_TOKEN=your-token

用法：

# 连续问答：进入交互模式，随时追问
zread ai openclaw/openclaw

# 单次对话：直接提问
zread ai facebook/react "这个项目的代码结构是怎样的"

CLI 命令

# 启动 MCP 服务器
zread mcp [stdio|http|sse] [address] [options]

# 获取仓库文档目录结构
zread ls <repo> [-l zh|en] [-j] [-p]

# 获取指定页面内容或源代码文件
zread cat <repo> [slug_or_path] [-l zh|en] [-j] [-p]
#
# 自动识别参数类型：
# - 第一个参数只有 repo，第二个参数是 slug/序号(如: 1-overview, 1): 读取 zread 文档页面
# - 其他格式(如: README.md, owner/repo/README.md#L1-10, github.com/owner/repo/README.md#L1-10): 读取 GitHub 文件内容

# 搜索
zread find <query>                        # 搜索 GitHub 仓库
zread find <repo> <query>                 # 在仓库文档内搜索

# 发现推荐仓库
zread rand [topic] [-l zh|en] [-j] [-p]

# 获取热门仓库榜单
zread top [weeks] [-l zh|en] [-j] [-p]

# 获取仓库信息
zread stat <repo> [-l zh|en] [-j] [-p]

# 向仓库 AI 提问（需要登录账号的免费 Token）
zread ai <repo> [question] [-l zh|en] [-t token] [-p] [-j] [-m model]


# 导出仓库文档到本地（CLI 专属，生成 llms.txt 和 llms-full.txt）
zread cp <repo> [output_dir] [-l zh|en] [-c concurrency]

全局选项

命令行支持纯文本与 JSON 输出，兼容管道工具流：

选项 说明
-l, --lang {zh,en} 语言（优先级：--lang > ZREAD_LANG > 系统locale，默认 en）
-j, --json JSON 格式输出
-p, --plain 纯文本输出
-t, --token ZREAD_TOKEN
-h, --help 显示帮助
-v, --version 显示版本

命令示例

# MCP 服务器
uvx zread mcp                          # stdio 模式（默认）
uvx zread mcp http                     # HTTP 模式
uvx zread mcp http :8080               # 指定端口
uvx zread mcp http 0.0.0.0:3000/custom # 自定义地址和路径

# 文档相关
uvx zread ls golang/go                 # 查看文档目录
uvx zread cat vuejs/vue                # 查看 zread 首页
uvx zread cat vuejs/vue 1              # zread 文档（使用序号）
uvx zread cat vuejs/vue 1-overview     # zread 文档（使用 slug）
uvx zread cat golang/go README.md      # 查看 GitHub 文件
uvx zread cat python/cpython Lib/http/client.py
uvx zread cat github.com/facebook/react/README.md#L1-10
uvx zread cat facebook/react/README.md#L1-10
uvx zread cat facebook/react README.md 5 10
uvx zread cat facebook/react README.md 5-10
uvx zread cat facebook/react README.md 5~
uvx zread cat facebook/react/README.md 5:
uvx zread find facebook/react hooks

# 仓库发现
uvx zread top                          # 本周热门
uvx zread top 4                        # 最近4周
uvx zread rand python                  # Python 项目
uvx zread rand awesome-list            # 精选资源

# 仓库信息
uvx zread stat torvalds/linux

# AI 问答（需要登录账号的免费 Token）
uvx zread ai golang/go "channel 和 mutex 怎么选择" -t your-token
uvx zread ai python/cpython --model claude-sonnet-4.5 -t your-token
uvx zread ai rust-lang/rust            # 进入交互模式

# 导出文档
uvx zread cp golang/go                          # 导出到当前目录
uvx zread cp python/cpython -l zh               # 指定语言
uvx zread cp vuejs/vue -c 20                    # 调整并发数

MCP 客户端配置

在支持 MCP 的客户端中添加以下配置：

{
  "mcpServers": {
    "zread": {
      "command": "uvx",
      "args": ["--env", "ZREAD_TOKEN=your-token", "zread", "mcp"]
    }
  }
}

MCP 工具

工具 说明
read_doc 获取指定文档页面内容
search_wiki 在仓库文档中搜索关键词
get_doc_outline 获取仓库文档目录结构
discover_repo 随机发现推荐仓库
get_trending 热门仓库榜单
get_repo_info 获取仓库信息和索引状态
read_source_file 获取源代码文件内容
ask_ai 向仓库 AI 智能问答（需 Token），支持 glm-4.7 和 claude-sonnet-4.5 模型

获取 Token

AI 问答功能需要登录 Zread.ai 账号获取免费的 JWT Token：

  1. 访问 https://zread.ai 并登录
  2. 按 F12 打开浏览器控制台
  3. 粘贴运行： 
    prompt(
  "复制token",
  JSON.parse(localStorage.getItem("CGX_AUTH_STORAGE")).state.token,
);
  4. 复制弹窗中的 Token

环境变量

变量 说明
ZREAD_TOKEN zread.ai 登录账号的免费 JWT Token，仅 AI 问答功能需要
ZREAD_LANG 默认语言 (zh / en)，优先级低于 --lang，高于系统locale

配置文件

你也可以使用配置文件来配置 zread。优先级为：命令行参数 > 环境变量 > 配置文件。

配置文件路径：

  • macOS: ~/.config/zread/zread.toml
  • Linux: ~/.config/zread/zread.toml（或 $XDG_CONFIG_HOME/zread/zread.toml）
  • Windows: %APPDATA%\zread\zread.toml

配置文件格式（TOML）：

[zread]
token = "your-token-here"
lang = "zh"  # 可选，默认为 "zh"

贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解如何参与。

许可证

MIT License - 详见 LICENSE 文件