前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的设计，开发者可以通过插件扩展工具链。当智能体需要阅读贴吧内容时，爬虫脚本往往需要处理登录态、翻页、楼中楼、图片下载等细节，手动写成本高且难以维护。referiw/dsh-plugin-tieba 是一个只读贴吧的 DSH 插件，将上述流程封装成工具与配置，让智能体可以直接把贴吧帖子读成结构化材料。
它是什么¶
dsh-plugin-tieba 是一个由社区成员 referiw 维护的 DeepSeek Harness 插件，属于「联网工具」分类。它通过真实浏览器渲染贴吧页面，提取楼层、楼中楼、图片等结构化信息，输出为按楼层顺序排列的文本与图片路径，用于后续处理或写入知识库。
核心功能¶
插件提供三个主要工具：
tieba_bar：列出某个吧的帖子（最新/最热/精华），返回tid、标题、作者、回复数等。tieba_thread：读取一个帖子的全文，按楼层顺序返回，支持抽样、截断、图片下载。tieba_status：查看当前登录态（贴吧 ID、昵称、头像）。tieba_bars：列出当前账号关注的吧。
输出格式示例：
《示例帖子：一个关于融资的讨论》 楼主 用户甲 ｜ 发帖 2026-10-22 12:22 ｜ 全文 39 层 ｜ 抽取 39 层
【第 1 层 0% 用户甲 楼主】
示例帖子的主楼内容
[图1]
[图 …/.dsh-tieba/images/1234567890/f1_1.jpg 250x304 ｜ http://tiebapic.baidu.com/…jpg]
【第 3 层 5% 用户乙】
这是某一层楼的回复内容[表情:咧嘴笑]
└ 楼中楼 2 条:
· 用户丙: 这是楼中楼里的一条回复
功能特性：
- 按楼层排列：图片紧跟所属楼层，楼中楼挂在楼层下方；使用页面给出的
floor_num作为楼层号。 - 时间参考：顶部给出楼主发帖时间，相对时间归一为
YYYY-MM-DD HH:MM。 - 表情转中文：将表情 ID 转为文本描述，不读图。
- 省略无关元素：跳过头像、昵称挂件等上下文信息。
- 图片信息：每张图提供
thumb（本地缩略图）、original（原图，按需下载）、url（原图外链）。 - 路径样式：支持
DSH_TIEBA_PATH_STYLE配置，默认为绝对路径，可选rel（相对当前目录）或home（~开头）。
安装与启用¶
要求 DSH ≥ 0.2.0（插件在 package.json 中声明了 engines.dsh）。
使用官方安装命令：
dsh plugin --profile <profile> add dsh-plugin-tieba
<profile> 换成你在用的那个：跑 dsh web 就是 web，ls ~/.dsh/profiles 能看到全部。这条命令会同时写 dependencies 和 dsh.profile.bundles，不用手工编辑。装完重启 DSH，浏览器硬刷新一次。
桌面版注意：desktop profile 由 Electron 独占管理，命令行会直接拒绝。桌面用户请走「设置 → 插件」安装，或用 --profile web 起一个独立 profile。
典型用法¶
读取一个帖子：
tieba thread 1234567890
结构化输出：
tieba thread 1234567890 --json
下载原图（默认只下载缩略图）：
tieba thread 1234567890 --images both
列出吧内帖子：
tieba bar v
tieba bar v --tab 最热 --page 2
查看登录态：
tieba status
tieba 是包的 bin；没全局安装时用 node src/cli.mjs status 等效。
抽样策略¶
默认使用动态抽样：楼层越多比例越低，结果落在 [min, max] 区间内。楼主楼层始终补齐，不占抽样名额。匿名帖的第 1 层恒判为楼主。
动态抽样规则示例：
| 总楼层 | 抽取数量 | 比例 |
|---|---|---|
| ≤ 50 | 全读 | 100% |
| 100 | 65 | 65% |
| 300 | 125 | 42% |
| 1000 | 230 | 23% |
| > 1000 | 300（封顶） | < 30% |
抽样模式也可改为 fixed（指定层数）或 ratio（指定比例）。
配置¶
配置文件为 ~/.dsh-tieba/config.json，设置页也可修改，即时生效。
常用配置项：
| 键 | 默认值 | 说明 |
|---|---|---|
sampleMode |
dynamic |
抽样方式 |
sampleMin / sampleMax |
50 / 120 |
动态抽样的上下界 |
sampleFixed / sampleRatio |
50 / 0.2 |
fixed / ratio 模式的取值 |
truncateText |
true |
是否截断过长楼层 |
maxTextChars |
600 |
截断时每层保留字数 |
imageQuality |
thumb |
thumb 只下缩略图；original 下原图；both 都下 |
imageMaxArea |
1200000 |
图片像素面积上限 |
imageMaxWidth / imageMaxHeight |
1280 / 2000 |
图片尺寸上限 |
gapMs |
4000 |
请求间隔（毫秒） |
selectors |
见 README | 列表页的选择器配置 |
cacheTtlMs |
600000 |
全文缓存有效期 |
maxPages |
30 |
单帖最多抓多少页 |
安全与权限¶
插件以当前 DSH 进程的权限运行。安装前应检查源码与许可证（MIT）。
插件提供 HTTP 接口 /tieba/api/*，用于设置页的登录状态、抽样策略、输出截断、图片压缩、请求节流等配置。该接口沿用 DSH 自己 /api 的信任模型：认 Host，不认连接地址。
默认只接受回环地址（127.0.0.1 / ::1 / localhost）。sec-fetch-site: cross-site 一律拒绝；带 Origin 时必须与 Host 同源。
公网 / 反向代理 / 网关插件部署时，如果 DSH 本身已经用 --trusted-host <域名> 启动，插件会自动沿用那份白名单；否则需显式放行：
export DSH_TIEBA_TRUSTED_HOST=tieba.example.com
为什么必须用浏览器¶
贴吧对未登录请求一律返回「百度安全验证」页，普通 fetch / curl 无法拿到正文。模拟浏览器 TLS 指纹（如 curl_cffi）同样会被 403。
插件通过真实浏览器引擎绕过验证，并处理三个细节：
- 桌面版是前端二次渲染，经典选择器抓不到，必须走移动版接口；
- 翻页不能复用会话，同一上下文连翻多页会被判成机器人弹验证码，必须一页一个上下文；
pn是楼层偏移不是页码，写pn=2返回空页。
已知限制¶
- 贴吧没有可用的公开列表接口，列表页依赖 DOM 抓取。前端改版时需修改
config.selectors中的四个选择器：barRow/barTitleLink/barTitle/barAuthor。 - 原图下载必须走桌面页（带签名的
pic/item地址），移动页的?src=参数没有签名，取回的是占位图。代价是多开一次桌面页（约 +5 秒），且桌面页懒加载，个别图可能仍只给缩略图。 - 插件不发言、不点赞、不签到、不关注，仅做只读。
与 DSH 的集成方式¶
| 面向 | 用法 |
|---|---|
| 工具 | ctx.tools.register：注册 tieba_thread / tieba_status / tieba_bars |
| 设置页 | 客户端插件 ctx.slots.inject('settings.section', …) |
| HTTP | ctx.webServer 挂 /tieba/api/*（只服务设置页） |
| 装配 | dsh.bundle.patch 插入 id: tieba 一行 |
| 展示 | locale/*.json 的 meta.title / meta.description |
生态背景¶
DeepSeek Harness 的理念是「一切皆插件」，社区目录（https://www.skillhub.cn/plugins）与 DeepSeek 官方无从属关系。该插件由社区成员独立开发维护，非官方项目。
目录与源码¶
- 插件目录页：https://www.skillhub.cn/plugins/referiw/dsh-plugin-tieba
- 源码仓库：https://github.com/referiw/dsh-plugin-tieba
- npm 包：https://www.npmjs.com/package/dsh-plugin-tieba
