dsh-plugin-trpg · TRPG 跑团智囊

给 DSH 用的国内外 TRPG 跑团咨询插件：装上之后模型就能查规则、选模组、掷骰判定、随机车卡、盯新上架的规则书/模组、跟混沌元素社（Chaosium）动态、看中英跑团社区在聊什么，并把这些内容渲染成中文图文卡片发到 QQ。

定位：QQ 机器人里的「跑团桌边助手」。回答优先用本地中文知识库（快、可离线），行业动态和社区热帖走实时抓取，抓不到时退本地快照并明确标注来源，不编造价格与标题。

一、17 个工具

工具	什么时候用	说明
trpg_help	用户问「你能干嘛」「菜单」「怎么用」	能力菜单与示例问法
trpg_search	名字/关键词不确定是英雄、模组、术语还是规则	全库模糊搜索（模组/规则/系统/游戏/术语/指南/社区/职业）
trpg_dtrpg	「DriveThruRPG 最近有什么新东西」「有什么免费模组」「便宜的好货」	解析 DriveThruRPG / DMs Guild 的 RSS（固定最新 25 条），支持 free（只看免费）/cheap（≤$10）/keyword
trpg_chaosium	「COC 母公司最近有什么新书/新消息」	Chaosium 官方博客：实时抓取 → Node 直连 → 本地快照三级降级
trpg_news	「TRPG 圈最近有什么新闻」「D&D/Pathfinder 官方动态」	EN World 新闻区 + Paizo 官方博客 + Modiphius 新闻，按日期合并
trpg_community	「最近跑团圈在聊什么」「国外玩家在讨论啥」「去哪找中文跑团社区」	StackExchange RPG 热问 + EN World 讨论区（国际）+ 机核跑团标签（中文）；channels:true 时返回中文/英文社区渠道清单
trpg_modules	「推荐个新手模组」「COC 有什么经典战役」「免费短团」	按系统/免费/低价/难度/关键词筛本地模组库（31 个，含经典与免费入门）
trpg_module	「《鬼屋》怎么样」「奈亚拉托提普的面具值得跑吗」	单个模组详情：人数、时长、难度、简介、为什么值得玩、主持提示
trpg_game	「三角机构是什么」「XX 规则最近有什么新东西」「这个系统的模组去哪买/有没有免费」	按规则名查：规则简介、为什么值得玩、新手怎么上手、官方入口、商店与价格、模组/扩展/免费材料链接、玩家社区、该规则专属实时资讯源（RSS / Flarum 讨论区）。内置 Triangle Agency、COC 7e、D&D 5e 等；数据在 data/games.json
trpg_rules	「奖惩骰怎么算」「大成功大失败是多少」「重伤规则」	COC 7e + D&D 5e + 通用规则的速查 Q&A（39 条）
trpg_dice	「帮我掷个侦查」「理智检定」「奖励骰」「d20 优势」「4d6 取高 3」	COC 判定/理智/对抗、D&D d20 优劣势、任意骰式（NdM±K、kh/kl），带中文判定等级
trpg_investigator	「随机来个调查员」「roll 个记者」	COC 7e 随机车卡：3d6×5 属性、HP/MP/SAN/MOV/DB、职业技能点与信用评级、姓名背景
trpg_glossary	「KP 是什么」「SAN 值」「幕间」	跑团术语速查（40 条，中英对照）
trpg_guide	「怎么入坑」「怎么当 KP」「第一次开团准备什么」	入坑/KP/开团/线上团指南（12 篇）
trpg_systems	「COC 和 DND 哪个适合我」「有什么规则系统推荐」	规则系统选型（12 个系统：风格、难度、中文支持、入门路径）
trpg_card	用户要「图 / 图文 / 卡片」	1080 宽深色 PNG 卡片，kind 覆盖 dtrpg/chaosium/news/community/module/modules/game/rule/dice/investigator/systems/help/meta。每张卡都有卡片级中文概括（intro）与逐条中文导读（zh），模型可用同名参数覆盖成自己的话；生成后由模型调用 qqbot_send_file 发出
trpg_meta	「数据是最新的吗」「插件有什么数据」	数据版本、条数、缺文件诊断、抓取缓存状态

二、数据源与边界（诚实版）

实时可抓（Node 直连）

• DriveThruRPG rss.php / DMs Guild rss.php：官方 RSS，只给最新 25 条、忽略所有查询参数；价格靠 <strong>Price</strong> 本地过滤。
• Paizo 官方博客 https://paizo.com/blog/?feed=rss；EN World forums/news.3/index.rss 等讨论区；Modiphius blogs/news.atom；StackExchange RPG API（匿名配额，尊重 backoff）；机核 gapi/v1/tags/3896/articles（跑团标签，需 Accept: application/vnd.api+json）。

需要宿主 web 服务

• Chaosium 官方博客：Node 直连会吃 Cloudflare 403（甚至返回 200 的挑战页）；DSH 的 web 服务返回的是「HTML→markdown」，所以 Chaosium 走宿主 web.fetch 解析 markdown，失败再退 data/chaosium-snapshot.json。

明确抓不到、只用本地库/渠道清单

• DMs Guild 商品页、Free League、Goodman、Mongoose、RPG.net、BoardGameGeek、D&D Beyond 列表、Reddit、纯美苹果园（trow.cc）、知乎、B 站搜索接口：本机网络被墙或反爬。
• 中文模组/团录库 dicecho.com 只作为「社区渠道」推荐，不做站内抓取（无列表 API + robots 要求 crawl-delay 5）。

缓存与降级

• 实时源统一缓存（lib/live/cache.js：资讯 30 分钟、规则专属资讯 20 分钟）；失败回退上一次结果，再失败退 data/*-snapshot.json，输出里标注「当前为本地快照」。
• 改了抓取/拼链接逻辑要同时 bump 缓存键版本（如 game-live:v2:），否则宿主进程会继续吃旧缓存。
• 实时抓取失败时仍返回稳定内容，不会因为一个源挂了整条回复失败。

按规则名查询（trpg_game）的数据边界

• 规则库 data/games.json 目前收录 10 个系统（三角机构、COC 7e、D&D 5e、PF2e、Delta Green、Blades in the Dark、Cyberpunk RED、Mothership、FIST Ultra、Vaesen）；每条带 stores（商店/价格）、files（模组、扩展、免费材料直链）、community（社区）、live（该规则专属实时源）。
• 三角机构的可用实时源：Kickstarter posts.atom、BO3 论坛 forum.bo3studio.com Flarum filter[tag]=triangle-agency、Modiphius Atom、Haunted Table 商城 products.json；官方 hauntedtable.com 已下线，商城是唯一官方入口。
• 定价陷阱：Haunted Table / Arc Dream / TKG 的 Shopify 店对中文区按 CNY 返回价格（465.00 指 ¥465，不是 $46.50）；数据里统一写 ¥，报价时必须带币种。
• 免费材料实测可用：cdn.shopify.com/s/files/1/0581/0464/3719/files/*.pdf（样张、两篇完整任务、可填写角色表、第三方授权）；该 CDN 只支持 GET，不要用 HEAD 探测。
• 社区渠道库 data/community.json 已扩到 33 条（中文 12 / 国际 21），trpg_community(channels:true) 分 🇨🇳/🌍 两块、每块默认各列 10 条并提示剩余数量。

三、安装

本插件是标准 DSH 原生插件（package.json 的 dsh.bundle.patch + cordis.patch.yml + index.js 的 apply(ctx)），安装方式：

plugin_manager { action: "install_bundle", target: "C:\\Users\\aorii\\Documents\\deepseek-harness\\default-workspace\\dsh-plugin-trpg" }

装好后 17 个 trpg_* 工具进工具表，同时通过 systemPrompt.section 注入一段中文提示（告诉模型什么场景用哪个工具、要图时生成卡片后调用 qqbot_send_file）。卸载用 remove_bundle，失败诊断看 trpg_meta。

四、开发与自测

node dsh-plugin-trpg/scripts/smoke.mjs        # 17 工具 21 用例契约冒烟（不依赖宿主服务）
node dsh-plugin-trpg/scripts/cards-smoke.mjs  # 5 张卡片渲染冒烟（Node + System.Drawing）
node dsh-plugin-trpg/scripts/preview.mjs      # 打印社区/新闻/DTRPG 的真实返回文本
node dsh-plugin-trpg/scripts/cards-preview.mjs # 生成带中文导读的 dtrpg/community/game 三张卡
node dsh-plugin-trpg/scripts/card-game-preview.mjs # 单独渲染「三角机构」整张卡（含 3 条实时动态）
node dsh-plugin-trpg/scripts/check-game-live.mjs   # 打印某个规则的实时源抓取结果，排查链接/缓存问题
node dsh-plugin-trpg/scripts/sanitize-games-notes.mjs # 把 games.json 里的维护者备注洗成玩家向短注

目录：

dsh-plugin-trpg/
├─ index.js              # 插件入口：apply(ctx) 注册工具 + 注入系统提示
├─ cordis.patch.yml      # bundle patch（insert dsh-plugin-trpg）
├─ lib/
│  ├─ core.js            # defineTool 兼容层、fetch/文本工具（沿用 outlast 插件骨架）
│  ├─ store.js           # 本地知识库加载 + 模糊搜索（含 games 规则库）
│  ├─ dice.js            # COC/DND 掷骰与判定
│  ├─ investigator.js    # COC 7e 随机车卡
│  ├─ render.js          # 各工具的中文文本渲染（QQ 长度控制）
│  ├─ cards.js           # 1080 宽 PNG 卡片（中文概括 intro + 逐条导读 zh；零依赖排版 + PowerShell System.Drawing 落盘）
│  ├─ tools.js           # 17 个工具定义
│  └─ live/              # 实时源适配器：dtrpg / chaosium / news / community / gamefeeds / feed / cache
├─ data/                 # 中文知识库 8 个 JSON + 3 个降级快照（含 games.json 规则名查询库）
├─ locale/               # zh / en 插件名称与描述
└─ scripts/              # smoke / cards-smoke / preview / cards-preview / 快照生成

五、已知限制

• DriveThruRPG 商品详情页被 Cloudflare 403，所以「折扣力度/评价/详情介绍」拿不到，只给标题、出版商、价格、RSS 简介与链接。
• Chaosium 实时抓取依赖宿主 web 服务；纯 Node 环境会走快照。
• 机核跑团标签更新不频繁（可能几个月前的帖子），界面里都带日期，不会伪装成「今天热门」。
• 卡片走 Windows PowerShell + System.Drawing，因此需要 Windows 与中文字体；其它平台会明确报错而不是静默出空白图。
• trpg_game 的「最新资讯」来自 data/games.json 里为该规则声明的源（RSS / Flarum 讨论区 API），没声明源的规则只给官方入口与社区列表。