dsh-pixiv-scroll

DSH 插件：按你的口味刷 Pixiv —— 搜、筛、看图精选，存到本地或发给你。

⚠️ 前提：你的机器得能上 pixiv。 插件不内置代理、不代你绕过网络限制 —— 详见 装之前必须知道的一件事。

设置页和插件面板里显示的名字是 dsh-pixi-scroll；包名仍是 dsh-pixiv-scroll。 两者不一样是故意的（显示名是另外指定的写法，包名跟站点名对齐更好认）。

和「刷B站」是同一套路子的姊妹插件。区别在于 Pixiv 是图片，所以多了一层 「真的把图看一眼再挑」。

零配置就能用（在你能上 pixiv 的前提下），不需要登录。 想更贴合口味可以选开登录（拿关注流和个性化推荐）。

---

它做什么

• 按关键词 / 排行榜找候选，按标签权重、画质、新鲜度打分排序
• 元数据先粗筛（分级、页数、分辨率、排除标签、判重），再读图精选
• 存成 <根>/<画师>/<标题>_<ID>/001.jpg … + metadata.json（含 sha256、来源、判定理由）
• 发给你（走投递通道；没配通道就只落盘，默认永远能用）
• 可选定时刷（谷时自跑）
• 可选登录（多拿关注流 + 个性化推荐）

---

装之前必须知道的一件事：这个插件不能帮你翻墙

硬前提：你的机器得能上 pixiv

插件不内置代理、不内置节点、不代你绕过任何网络限制。它做的事是 「你已经能上 pixiv 了，我帮你把刷这件事做得更聪明」。

能不能上 pixiv 是你自己的事，插件只负责在你能上的前提下把活干好。

如果你上不了 pixiv，这个插件对你没用 —— 这不是我们没做好，是下面这条链子断在第一步：

环节	需要什么	上不了 pixiv 时
发现图片（搜索 / 排行 / 推荐）	pixiv 的元数据接口	❌ 只有官方有，镜像站一个都没有
取图片字节	i.pximg.net	⚠️ 镜像站能代替
但「取哪一张」	得先知道作品 ID	❌ 而知道 ID 本身就意味着你已经能发现它了

所以「爬不了墙也能刷」这件事做不到。 镜像站（pixiv.re 这类）的定位是 「已知 ID 时帮你取图」，它假设你已经能上官方站——它替代的是图片域名， 不是元数据接口。发现图片这一步绕不过去。

实测（2026-11-05）：pixiv.re 的 16 条路径穷举结果 —— 只有 /<作品ID>.jpg 返回图片，其余（/ajax/*、/ranking.php、/api/*、/search/*、/<id>.json） 全部 404。同批探测的 pixiv.nl / pixiv.cat / pixiviz.xyz / pixiv.moe / pixivel.moe / pixivic 没有一家提供搜索或排行。

那插件还能做什么

一旦你能上 pixiv（不管是自己挂了代理、还是本来就在墙外），插件会在四条路里自己挑：

路	什么时候用
外部源	你填了 externalApi —— 优先级最高，见下
直连	你的机器本来就能通（比如挂了 TUN 模式的代理）
代理	你填了 proxyUrl（如 http://127.0.0.1:7897 这类本地代理）
镜像	前三都拿不到元数据时，用 pixiv.re 取图（只有图）

判定方式是实际探测（并行试外部源/直连/代理，看谁真能拿到数据），不是按 IP 猜。 实测数据：同一台机器十分钟内 TUN 时通时不通、裸直连整体超时、走代理 3/3 通 —— 所以「通不通」是探测出来的，不是写死的。

---

「外部源」——接你自己能上 pixiv 的东西

这是给"上不去 pixiv"准备的唯一出口。

如果你的机器上已经有任何能访问 pixiv 的东西 —— 自建反代、自己的服务器、 某个能上 pixiv 的客户端 —— 把它的地址填进 externalApi，插件就走它。

怎么填

设置页 → 网络 → 外部源，填一个地址：

http://127.0.0.1:8080              # 本机跑的
https://你的反代.example.com        # 自己的反代
https://你的服务器.com/api/pixiv    # 带子路径也行

约定：那个地址要兼容 pixiv 官方接口形态。 插件保持官方路径不变，只换 origin：

https://www.pixiv.net/ranking.php?mode=daily
      ↓  换成你的地址
https://你的反代.example.com/ranking.php?mode=daily

也就是说，只要你的反代把 pixiv 的路径原样转发，插件就能用它 —— 搜索走 /ajax/search/artworks/*、排行走 /ranking.php、详情走 /ajax/illust/*。

插件不做什么

插件不内置代理、不做任何绕过网络限制的事。 那个能力得你自己提供：

• 插件只负责「按官方路径去调一个 HTTP 地址」
• 那个地址背后是什么（反代 / 服务器 / 客户端），插件不关心也不实现

为什么不做：那类技术（内置节点、伪造/加密 SNI）的唯一用途就是绕过网络封锁， 把它放进一个要开源的插件里不合适 —— 承担责任的是使用者，不是写代码的。

参考：PixEz 的「免代理直连」用的是硬编码 pixiv 真实 IP + DoH （lib/er/hoster.dart）或 ECH 加密 SNI（lib/network/network_mode.dart）。 那是它的实现、用户自己的选择；插件只是留个口子，谁来接都行。

优先级

外部源 > 直连 > 代理。 你填了外部源就是明确说了走它 —— 插件不会自作主张绕开它去直连（那等于无视你的配置）。

插件会在设置页和工具返回里如实告诉你现在处在哪一档，不会让你对着"搜到 0 条"猜：

官方直连 ✓ · 镜像 ✓          ← 全功能
官方经代理 ✓ · 镜像 ✗        ← 全功能
官方 ✗ · 镜像 ✓
  → 只能按作品 ID 取图，不能搜索/排行（镜像没有元数据接口）
官方 ✗ · 镜像 ✗
  → 完全打不通 pixiv。检查代理是否在跑（当前：…）

2. DSH 的聊天框不支持助手发图

这不是插件的限制，是宿主的：官方 dsh-attachment 只做用户 → 模型的单向传递， assistant 侧的图片输出目前只是 forward-compatibility，生产适配器只声明 text-only。

所以「发给你」只能走投递通道：

通道	说明
local	默认，永远可用。存到 saveRoot，并报告绝对路径
qq	可选。需要你自己装 QQ 机器人（见下）

设计上刻意做成通道接口：QQ 只是其中一个适配器。 别人没装 QQ 机器人也能用，默认那条「存到本地」不依赖任何外部配置。

3. QQ 通道的两条限制

• 插件不带任何凭证，appId / appSecret 全靠你自己配
• QQ 机器人默认没有主动消息权限：不带宽内 msg_id 直接发会被拒（HTTP 400 / code 40034105）。 只能在收到消息后约 5 分钟内的「被动窗口」里回。 窗口过了插件就只落盘，并如实说明原因 —— 不会假装发出去了。

---

安装

# 从 GitHub
dsh plugin --profile <你的profile> add github:<user>/dsh-pixiv-scroll

# 或者本地目录开发（改代码即时生效）
dsh plugin --profile <你的profile> add link:<插件目录>

装完必须重启一次 DSH（bundle 层要重启才组装，客户端 bundle 也只在启动时读）。

dsh plugin 会自动做三件事，不用手改 profile 的配置文件：

1. 用 pnpm 把包装进 $DSH_HOME/profiles/<profile>
2. 因为本包声明了 dsh.bundle，把它加进 profile 的 dsh.profile.bundles
3. 启动时应用包内自带的 cordis.patch.yml

桌面版注意

桌面版（Electron）里 dsh 不在 PATH 上。要手动跑命令的话用：

<安装目录>\resources\runtime\cli\bin\dsh.cmd

这个包装内部已经设好 ELECTRON_RUN_AS_NODE 并带上 --expose-internals。

定时刷也需要它 —— 在设置页把 dshBin 指到这个路径。

---

设置页

装好后进 设置 → dsh-pixi-scroll。里面分几组：

组	有什么
总开关	一键停用（定时轮也停）
网络	代理地址、图片镜像，和一个 「测一下」 按钮
找什么	关键词（回车加入，点 ✕ 移除）、排行榜池塘
口味	排除标签、必须标签、收藏下限、时间窗
分级	收 R-18（默认关）、过滤 AI 生成
登录（可选）	开关、刷哪些池子、贴 token、查看状态、退出
存放	保存根目录、目录模板
额度	每天最多存 / 每轮最多挑 / 单件最多几页
发到哪	存到本地 / 发到 QQ
定时	间隔分钟数、谷时开关（中午 / 晚上）
状态	家目录、配置文件路径、全面自检

「测一下」 会告诉你当前的实际情况，比如：

网络：官方经代理 ✓ · 镜像 ✗
登录：未使用登录（游客模式）
额度：今天已存 3/6，还能 3
通道：存到本地 ✓  发到 QQ ✗（没窗口）
存到：D:\Pixiv

配置真值在 $DSH_HOME/pixiv-scroll/config.json，改动即时生效（不用重启）。

⚠️ 为什么不写 profile：profile 里 entry 的 config 段不进插件 user 层， 宿主那边始终是 schema 默认值。所以改 profile 对运行期无效，改设置页才有效。

---

登录（可选，默认关）

不登录也能用（游客模式：排行榜 + 搜索）。登录后能多拿两样：

• 关注流 —— 你关注的人的新作
• 个性化推荐 —— 这个才是"更符合喜好"的正主

为什么走 App API 而不是网页登录

实测（2026-11-04）用网页 cookie 请求这些接口全是 404：

我的关注流 / 我的收藏 / 推荐 / 为你推荐 / 我的资料

所以登录走 app-api.pixiv.net + Bearer token，需要你提供一个 refresh_token。

三条安全线

项	做法
权限	只申请 readonly —— 从权限上就不可能点赞/收藏/关注/评论
存放	token 只写 credential.json，不进配置、不进日志、不回显
轮换	pixiv 每次刷新换发新 token（旧的立即失效）→ 刷新后立刻落盘 + 文件锁

代码里有两道闸门挡着凭证：HTTP 接口层删一次，saveConfig 里 SECRET_KEYS 再删一次。 自检里还有一条断言专门验「client.js 没往 localStorage 写东西」。

怎么拿 refresh_token

插件不做账号密码登录 —— 那要起浏览器过 reCAPTCHA，在国内网络下成功率不高， 而且会让你的密码经过插件。请自行获取 refresh_token 后贴进设置页。

⚠️ 如果你在别的地方也用了同一个 token，两边会互相踢掉（因为轮换）。 踢掉了就重新贴一个。

登录坏了会怎样

不影响刷图。 登录是可选的，它出问题只是少两个池子。 自检里有一条断言专门验这个：打桩让关注流和推荐双双失败，pixiv_search 仍然正常出结果，只是如实报告"这两个池子为什么没成"。

---

给 Agent 用的工具

工具	干什么
pixiv_status	网络走哪条路、登录态、口味画像、今天存了几件、额度剩多少、通道哪些可用
pixiv_taste	看 / 调口味画像（自动学出来的偏好）。默认关；开关它、改权重、清空重学都在这儿
pixiv_search	找候选（含打分与为什么；画像开着时会按口味反搜）
pixiv_pick	下缩略图到本地，好让模型 read_image 真的看一眼再挑
pixiv_works	取原图（只下载，不占额度）
pixiv_save	正式收进图库（唯一占额度的操作，过分级/判重/额度闸门）
pixiv_send	投递出去（落盘 / QQ）

推荐的用法顺序：

pixiv_status → pixiv_search → pixiv_pick（读图精选）→ pixiv_save → pixiv_send

pixiv_pick 需要有视觉能力的模型。纯文本模型读不了图，那就跳过这一步， 直接按 pixiv_search 的打分选，并在报告里说明这轮没读图。

---

定时刷

设置页把 intervalMin 设成大于 0（单位分钟）就会定时跑。

谷时规则：工作日 9–12 / 14–18 是高峰，其余（含周末）都算谷时， 由 peakValley / noon / night 三个开关控制。

一轮具体做什么写在 prompts/duty.md 里 —— 那份用户可以改， 升级插件不会覆盖你改过的内容（新版会落到 duty.md.new）。

---

它怎么工作

pixiv_search ──► taste.mjs（分级过滤 + 打分排序）
     │             ↑ 登录时额外并入 关注流 / 个性化推荐
     ▼
pixiv_pick ────► 模型 read_image 看一眼，挑出真正好的
     │
     ▼
pixiv_save ────► 闸门（判重 / 额度 / 分级 / 页数）──► save.mjs（落盘 + metadata）
     │                                                seen.mjs（台账）
     ▼
pixiv_send ────► deliver.mjs（local 通道 / qq 通道）

文件	职责
index.js	宿主入口：装配工具、定时器、设置页接口（双通道注册）
client.js	设置页 UI（非 ESM，自注册到 settings.section）
lib/transport.mjs	传输：直连 / 代理两模式，自拆 chunked、自跟 301、硬超时
lib/route.mjs	三级探测：按实际连通性选路，不按 IP 猜
lib/pxclient.mjs	pixiv 读取（搜索 / 排行 / 详情 / 页 / 取图 / 关注流 / 推荐）
lib/auth.mjs	可选登录：token 刷新轮换、文件锁、凭证存放
lib/taste.mjs	口味漏斗：分级过滤 + 打分排序（纯函数，好测）
lib/save.mjs	命名清洗、原子落盘、metadata
lib/seen.mjs	JSONL 台账：判重与额度的唯一真相源
lib/deliver.mjs	投递通道接口（local / qq）
lib/config.mjs	配置归一化 + 双层读写 + 凭证闸门
lib/toolset.mjs	工具契约与策略闸门
lib/shrink.mjs	缩图调度（shell 出去调 Python）
lib/shrink.py	图片缩放本体（Python + Pillow）
prompts/duty.md	一轮章程（用户可改）

为什么传输层是手搓的

运行时里没有 undici 也没有 sharp（都只在 app.asar 里，require 和 fs 都进不去）。 所以：

• 传输层自己 CONNECT 隧道 + 自己 TLS 握手 + 自己拆 chunked
• 缩图 shell 出去走 Python/Pillow

顺手绕开的坑（都写了注释，别改回去）：

• socket.setTimeout() 只在 socket 空闲时触发 —— 连接卡在建连阶段时永不触发， 会永久挂死。必须有独立硬超时。
• TLS 握手期间就要 track() socket，否则每次失败漏 2 个连接。
• _inflight 存了已 reject 的 promise 会变成 unhandled rejection，默认直接杀进程。

---

自检

node selfcheck.mjs           # 网络层 / 口味 / 传输（离线）
node selfcheck.mjs --net     # 上面 + 真的打一次 pixiv
node selfcheck-io.mjs        # 落盘 / 台账 / 投递
node selfcheck-tools.mjs     # 配置分层 / 工具 / 闸门 / 登录隔离
node selfcheck-host.mjs      # 宿主装配（假 ctx）
node selfcheck-auth.mjs      # 登录 / 凭证 / 降级 / token 不泄漏
node selfcheck-client.mjs    # 设置页注册与渲染（vm 桩跑）
node selfcheck-docs.mjs      # README 里写的东西跟代码对得上
node selfcheck-external.mjs  # **外部源**端到端（起个假源，看插件认不认）
node selfcheck-shell.mjs     # 包外壳 / 凭证泄漏检查
node selfcheck-taste.mjs     # 口味画像（默认关 / 学习 / 衰减 / 冷启动 / 脏数据）

全过才算好（当前 422 条断言）。其中两条对开源特别要紧：

• selfcheck-shell.mjs 的零凭证泄漏检查
• selfcheck-docs.mjs 会核对 README 里每个可验证的承诺 —— 文档写了代码没做，比不写还糟

---

已知限制（如实写，不粉饰）

• 🔴 上不了 pixiv 就用不了。插件不翻墙、不内置节点、不代你绕过限制。 「发现图片」需要官方元数据接口，而全世界的镜像站都不提供这个 —— 这不是没做完，是这条路不存在。详见开头那节。
• 镜像只能按 ID 取图。pixiv.re 实测 16 条路径，只有 /<作品ID>.jpg 通， /ajax/*、/ranking.php、/api/*、/search/* 全 404。所以镜像对 「先搜索再刷」这件事帮不上忙 —— 它只替代图片域名，不替代元数据接口。
• R-18 过滤是尽力而为。默认只做元数据层过滤（标签 + 内容标记）， 不逐张读图复查。排行榜原始数据里本来就混着露骨封面的作品 （实测 daily 前 50 条里有 5 条带性内容标记），所以会有漏网。
• QQ 发图受被动窗口限制。见上文。
• 登录需要自己搞 refresh_token。插件不代你登录，也不碰你的密码。
• 定时刷需要一个 dshBin 路径。桌面版 dsh 不在 PATH，要在设置里指过去。
• 代理不在时会连不上。本机代理软件（Clash 之类）没在跑就通不了， 插件会报人话而不是静默失败。
• 探测结果受本机网络环境影响。同一台机器可能十分钟内三种结果 （TUN 通 / 直连超时 / 代理通）—— 插件按「实际能不能拿到数据」选路， 而不是按 IP 段猜。

---

依赖与致谢

• 零运行时依赖（纯 Node 内置模块）。
• Pillow —— 图片缩放（发 QQ 前压缩）
• pixiv.re —— 图片镜像兜底（仅图片，无元数据）
• 架构参考 dsh-bili-scroll（MIT）

安全问题

这个插件会处理 efresh_token（只在本地 credential.json，不进配置/日志/prompt）。 如果你发现凭证可能泄漏、或者任何绕过那条红线的路径， 请开 issue 或用 GitHub 的私密漏洞报告（Security → Report a vulnerability）。

许可证

MIT。下载内容的版权归原作者（画师）所有，本插件面向个人收藏设计， 请勿二次分发或商用。

插件只通过公开接口读取作品，不进行点赞、收藏、关注、评论等任何写操作。