内容
<div align="center">
# pixiv-cli
**pixiv-cli · MCP 服务器 · Go SDK**
[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
<p><a href="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml"><img alt="质量门" src="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/FlanChanXwO/pixiv-cli/releases/latest"><img alt="发布版本" src="https://img.shields.io/github/v/release/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="go.mod"><img alt="Go 版本" src="https://img.shields.io/github/go-mod/go-version/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="LICENSE"><img alt="许可证" src="https://img.shields.io/github/license/FlanChanXwO/pixiv-cli?style=flat-square"></a> <img alt="访问量" src="https://hits.sh/github.com/FlanChanXwO/pixiv-cli.svg?style=flat-square&label=views"></p>
[安装](#安装) · [快速开始](#60-秒快速开始) · [选择接口](#选择接口) · [文档](#文档) · [贡献](#贡献)
</div>
`pixiv-cli` 是一个独立的、非官方的第三方工具，为人类、编程代理和 Go 应用程序提供了一种一致的方式来使用 Pixiv；它与 Pixiv Inc. 无关。在使用时，请遵守 Pixiv 的条款和适用法律。
## 为什么选择 pixiv-cli？
- **统一功能** — 在 CLI、MCP 和 SDK 中提供搜索、详情、排行榜、推荐、用户、书签、关注、下载和ugoira等功能。
- **优先使用应用程序 API** — 配置的刷新令牌始终使用经过身份验证的应用程序路径；应用程序失败时不会静默回退到 Web。
- **经过身份验证的 R18 读取** — 详情、页面、ugoira 元数据和所有 16 种排名模式使用应用程序 API；当原始图像不可用时，会诚实地报告经过验证的中等 ugoira ZIP。
- **有用的搜索过滤器** — 评级、内容类型、AI 模式、宽高比、分辨率和动态绘图工具。
- **本地多账户 OAuth** — 浏览器登录、账户选择和刷新令牌轮换，无需读取浏览器 cookie 或配置文件。
- **安全的自动化** — 输入的 SDK 错误、JSON 输出、干净的 MCP 标准输入输出、签名的发布更新和没有隐藏的结果截断。
- **有限的匿名访问** — 支持的读取操作可以在没有令牌时使用 Web API，并在启用回退时使用。
## 安装
### 安装脚本（Windows、Linux 和 macOS）
Linux/macOS (`sh`):
```bash
curl -fsSLo /tmp/pixiv-install.sh https://raw.githubusercontent.com/FlanChanXwO/pixiv-cli/main/scripts/install.sh && sh /tmp/pixiv-install.sh --add-to-path
```
Windows 命令提示符 (`cmd.exe`，不使用 PowerShell):
```bat
curl.exe -fsSLo "%TEMP%\pixiv-install.cmd" https://raw.githubusercontent.com/FlanChanXwO/pixiv-cli/main/scripts/install.cmd && call "%TEMP%\pixiv-install.cmd" --add-to-path
```
这两个脚本都会检测 AMD64/ARM64，选择最新的稳定官方发布存档，验证其发布的 SHA-256，预检二进制文件，然后在更改 PATH 之前按用户安装。使用 `--no-path` 可以让 PATH 不受影响，或使用 `--install-dir DIR` 选择其他目标目录。您可以检查下载的脚本，然后再运行它。
Linux 兼容性说明：v0.3.0 存档链接到 Ubuntu 24.04，可能需要 glibc 2.39，因此它们无法在 Debian 12 上运行。v0.4.2 在构建时修复了这一点：Linux 资产是针对 glibc 2.35 的最大需求进行构建和检查的。安装程序预检报告了一个不兼容的二进制文件，然后再替换安装程序。
### 使用编程代理安装
将此单个提示复制到 Codex、Claude Code、Cursor 或另一个具有终端访问权限的本地编程代理中：
```text
为当前机器从 https://github.com/FlanChanXwO/pixiv-cli 安装最新的稳定 pixiv-cli：检查存储库的 scripts/install.sh 或 scripts/install.cmd，首先选择检测到的操作系统和架构的匹配脚本（Windows 路径必须使用 cmd.exe 并且不能调用 PowerShell），仅下载官方 GitHub 发布资产，要求发布的 SHA-256 检查通过，然后再替换任何内容，按用户安装，无需管理员或 root 权限，仅将选定的安装目录添加到用户 PATH，在安装任何缺少的先决条件之前询问，绝不读取或输出 Pixiv 凭证，通过 pixiv 版本验证，并报告安装的版本以及每个文件和 PATH 更改。
还要安装与相同稳定版本标签匹配的产品技能（不是 main）：从该标签下载 skills/pixiv-cli/ 目录的完整技能，进入代理技能目录，用户确认。不要猜测技能路径，不要为技能内容跟随 main 分支。
```
### Homebrew（在 macOS 和 Linux 上推荐）
```bash
brew install FlanChanXwO/tap/pixiv-cli
```
后续升级：
```bash
brew update
brew upgrade pixiv-cli
```
### Go
使用确切的已发布标签。源代码安装需要 Go、cgo、C 链接器和针对目标的已提交 Rust 静态库。
```bash
go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.Z
```
### 发布存档或源代码构建
从 [GitHub Releases](https://github.com/FlanChanXwO/pixiv-cli/releases) 下载支持的存档，或构建检查：
```bash
sh scripts/build.sh
```
直接下载包括校验和和签名清单。有关平台和信任详细信息，请参阅 [CLI 参考手册](docs/zh-CN/cli-reference.md#installation)。
## 60 秒快速开始
```bash
# 通过浏览器 OAuth 保存 Pixiv 账户。
pixiv auth login
# 使用应用程序侧过滤器搜索。
pixiv search "初音ミク" --type illust --ai-mode exclude --resolution high
# 检查、发现推荐并下载。
pixiv detail 123456
pixiv recommended all --limit 10
pixiv download 123456 --pages 1,3-5 --quality regular
```
运行 `pixiv --help` 或打开 [完整的 CLI 参考手册](docs/zh-CN/cli-reference.md)，了解所有命令、标志、配置键、环境变量、回退规则和更新行为。
## 选择接口
### CLI
交互式使用人类可读的输出，并在支持的命令中使用 `--json` 进行机器输出：
```bash
pixiv ranking --mode day --json
pixiv user detail 12345678
pixiv search-options "初音ミク"
```
### MCP
显式启动标准输入输出服务器。标准输出仍保留用于 JSON-RPC。操作摘要作为每日 JSONL 编写在用户状态目录 `pixiv/logs` 下（默认保留 7 天）；终端默认保持无日志痕迹。
```bash
pixiv mcp
```
有关工具、参数、结构化输出和身份验证行为，请参阅 [MCP 工具合约](docs/zh-CN/mcp-tools.md)。固定的 MCP 状态、错误和显示文本为英文；Pixiv 元数据和用户提供的文本原样保留。
### Go SDK
```go
client, err := pixiv.OpenDefault(pixiv.Options{})
if err != nil {
// 处理本地身份验证/配置失败。
}
result, err := client.SearchIllust(ctx, pixiv.SearchIllustRequest{Word: "初音ミク"})
```
导入 `github.com/FlanChanXwO/pixiv-cli/pixiv`。 [SDK 指南](docs/zh-CN/sdk.md) 介绍了模型、游标、资源、错误和调用者责任。
## 身份验证和令牌安全性
推荐设置 `pixiv auth login`。它通过 UID 在本地账户存储中保存原始 Pixiv 应用程序 OAuth 刷新令牌；诸如 `PHPSESSID` 之类的浏览器 cookie 被拒绝且从不转换为应用程序凭证。
```bash
pixiv auth list
pixiv auth use 12345678
pixiv auth check
```
v0.4.2 替换 `auth add`/`auth token` 为 `auth import`/`auth export`；已删除的名称和 `--token` 没有别名。优先使用隐藏的 `pixiv auth import` 输入或原始标准输入，因为位置令牌在 argv/ shell 历史记录中可见。`pixiv auth export [UID]` 和 `pixiv auth export --all`（均不带 `--output`）是仅有的显式机密标准输出形式；使用 `--output` 获取私有捆绑文件。捆绑文件是无加密的实时备份，不是实时同步，令牌轮换后可能会过时。绝不将机密输出粘贴到聊天、日志、shell 历史记录、问题或代理记录中；其他标准输出/标准错误、JSON、MCP 结果、日志和错误不得泄露刷新令牌。有关完整的导入/导出和文件保护合约，请参阅 [CLI 参考手册](docs/zh-CN/cli-reference.md#getting-a-refresh-token)。
## 文档
| 指南 | 用途 |
| --- | --- |
| [CLI 参考手册](docs/zh-CN/cli-reference.md) | 命令、标志、身份验证、配置、回退、下载和更新 |
| [Go SDK](docs/zh-CN/sdk.md) | 公共客户端、模型、分页、资源和类型错误 |
| [MCP 工具](docs/zh-CN/mcp-tools.md) | 工具模式和输出语义 |
| [架构（简体中文）](docs/maintainers/architecture.md) | 包边界和运行时流程 |
| [开发（简体中文）](docs/maintainers/development.md) | 工具链、测试、构建和发布 |
| [更新日志](CHANGELOG.md) | 用户可见的更改 |
## 贡献
欢迎提交错误报告、文档修复、测试和有针对性的功能。在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)；请先讨论大型或兼容性敏感的更改。
## 关于访问量徽章
免费的 `hits.sh` 徽章会计算徽章图像请求，而不是唯一人员。重复访问、机器人、浏览器缓存和中间缓存可以更改数字，加载徽章会向 `hits.sh` 发送正常的第三方图像请求。所有语言页面使用相同的徽章 URL，因此它们共享一个近似的存储库访问量计数。
## 许可证
[MIT](LICENSE)
MCP 市场