dsh-history-fictionologists · 虚构史学家

基于《崩坏：星穹铁道》官方世界观进行二次创作的 DSH 插件。 触发命令：/gs。风格基调：太空轻喜剧 + 一本正经地胡说八道。

核心参考游戏内「差分宇宙 · 方程一览」的想象力与命名逻辑： 用最严肃的格式包装最离谱的内容。

---

能力清单（前置条件）

能力	触发方式	前置条件
/gs 三步交互入口	在 DSH Web 输入框输入 /gs	插件已装入 profile 的 bundles，进程已重启
gs_setup 缓存状态与更新建议	模型调用（/gs 第 2 步）	无
gs_update 增量抓取 12 个 Wiki 数据源	模型调用	需要联网；本机可访问 wiki.biligame.com
gs_read 读取世界观条目	模型调用	至少成功抓取过一次（缓存存在）
gs_missions 既有故事目录（避让冲突）	模型调用	工作区存在 hsr-missions/
gs_digest 命名逻辑 / 书架风格 / 播报格式素材	模型调用	equation、broadcast-template 需缓存；mission-digest、book-digest 需 hsr-missions/
gs_planets 「星球列表」（原始 27 颗 + 已并入）	模型调用（功能 4 第 1 步）	无（原始列表编译在插件里，不需要网络）
gs_planet_save 把新星球并入列表	模型调用（用户答「加入」后）	工作区可写
gs_planet_reset 重置回原始 27 颗	模型调用（用户确认后带 confirm: true）	工作区可写；不带 confirm 只报告状态
gs_equation_save 虚构差分方程落盘（逐条校验后写入）	模型调用（功能 5）	工作区可写；既有方程缓存存在时叠加重名检查
gs_save 成品落盘	模型调用	工作区可写
系统提示「语言风格总则 + 星神纪律」	自动注入	无

降级行为（已实测）：缓存目录不存在时 gs_setup / gs_read 仍返回合法结果（hasCache:false、 recommendation:"update"），不会抛错；/gs 在缺少子模块时仍能启动并如实报告状态； planet-list.json 缺失、损坏或字段非法时，星球列表一律退回插件内置的 27 颗原始列表并在 warnings 里说明（test/planets.test.mjs 覆盖）。

---

安装

本插件通过 GitHub / AtomGit 仓库与 Release 附件 双平台分发。它不在 npm registry 上—— package.json 里的 private: true 是刻意留的，防止这份二创包被误发到公共 registry。

# 方式 A（推荐）：下载 Release 附件里的 tarball，再从本地路径安装
dsh plugin --profile web add C:\Users\<你>\Downloads\dsh-history-fictionologists-0.3.0.tgz

# 方式 B：AtomGit 仓库直装（国内网络更稳）
dsh plugin --profile web add https://atomgit.com/Scombriformes/dsh-history-fictionologists

# 方式 C：GitHub 仓库直装
dsh plugin --profile web add github:Kaede0614/dsh-history-fictionologists

# 方式 D：本地开发（junction 安装，改源码立即生效）
dsh plugin --profile web add link:<你的仓库路径>

AtomGit 是分发镜像，不是主仓：package.json 的 repository / homepage / bugs 仍指向 GitHub。发布流程与两个平台的 API 差异见 docs/atomgit-description.md。

dsh plugin 是 profile 目录下 pnpm 的透传封装，所以本地 tarball 路径、github: 简写 都由 pnpm 解析；dsh plugin add ... 会重解析整棵依赖树，装进一个干净 profile 最稳。

安装后 必须进程级重启 DSH（新增 bundles 行只在启动时组合；Ctrl+Shift+R 热重载不生效）。

验证是否装载：

dsh --profile web --dump-config | Select-String history-fictionologists

应当看到一行 - id: dsh-history-fictionologists。

仓库里有什么 / 没有什么

	内容
有	lib/（插件本体）、test/（204 个离线用例）、scripts/check.mjs、docs/、_evidence/（自证与独立复核证据）、BRIEF.md（实现规格）、cordis.patch.yml、hsr-worldview-cache/user-canon.json（手工维护的裁定层）
没有	hsr-missions/（游戏原始剧本文本，约 20 MB，版权归米哈游）、hsr-worldview-cache/*.json（gs_update 可重新抓取）、_probe/（4.9 MB 原始渲染 HTML）、hsr-stories/ 与 hsr-broadcasts/（本机成品）

被忽略的目录仍留在你的工作区里，只是不进版本库（见 .gitignore）。

功能 2 / 3 依赖工作区的 hsr-missions/：没有它插件照样装载， gs_missions 会如实降级报告「目录缺失」，gs_digest 的 mission-digest / book-digest 同理 （这条降级有 test/missions.test.mjs 覆盖）。要用全功能，请自备并放到 <工作区>/hsr-missions/：

trailblaze_missions.json          5 幕 / 18 系列 / 147 个开拓任务
adventure_other_tasks_full.json   7 章 / 33 个冒险任务
books_without_amphoreus.json      498 本书（「书架」风格参考）
sr-开拓续闻-完整/                  7 个系列 / 52 个开拓续闻任务

---

怎么触发

1. 在 DSH Web 的输入框输入 /gs（可以附带主题，例如 /gs 欢愉命途的荒诞点子）。
2. 插件会：
   • 本地读取缓存与既有故事状态，不发一次模型请求；
   • 把「三步交互协议」作为一条 plugin 来源的用户消息交给当前 agent；
   • 返回一行简短回执。
3. 模型据此依次弹出：
   • 第 1 步 · 功能选择：1 神人制造机 / 2 构史文集 / 3 星际构史播报 / 4 星球制造机（单选弹窗）；
   • 第 2 步 · 世界观数据更新策略：Y 访问网页重新抓取 / N 使用本地缓存；
   • 第 3 步 · 执行所选功能。功能 4 执行完还会再问两件事（见下）。

第 2 步的引导规则

• 本地无缓存 → 不问 Y/N，直接抓取，并告知「本地无缓存，已自动抓取」。
• 缓存较新（距上次更新 < recentGuardDays，默认 7 天）→ 即使选 Y，也先确认一句 「数据较新，确认需要重新抓取吗？」。
• 选 Y → gs_update 增量更新：先比对页面 revid，没变化的数据集直接跳过。
• 抓取失败（网络异常 / 被反爬拦截）→ 自动回退本地缓存，并明确告知 「更新失败，已使用缓存数据」。

---

五种功能

功能 1 · 神人制造机

生成 3–5 条全新科幻灵感（默认 4 条），输出格式（与功能 5 的方程共用同一套 Markdown 版式）：

## 灵感名称

〔人物·职业/身份〕命途归属：〈主命途〉/〈次命途〉

详细设定：……（约 100–200 字，须带荒诞感。首句就交代「谁 / 在哪 / 干什么」，
原「一句话简介」并入本段，不再单列）

可能的故事方向：……

版式修订：名称写成 ## 二级标题、不再用【】包裹（功能 5 的校验器把方括号判为游戏机制语言）； 名称与后面三段之间各空一行；「一句话简介」取消，其内容并入「详细设定」首句—— 两个功能各一套版式时，落盘文件里的标题层级也跟着乱；统一后功能 1 的灵感与功能 5 的方程 可以直接拼进同一份文档。

星神纪律（0.1.1）：命途归属只是气质标签——星神与令使不出场，只能是背景、传闻与缺席； 已陨/失踪的星神（贪饕、繁育、秩序、不朽、纯美、开拓）绝不写成在世、现身或归来。 正文写神人自己的职业、麻烦与出路：荒诞来自「命途概念 × 市井生活」的错位，不是「他和星神很熟」。

功能 2 · 构史文集

先读 hsr-missions 的既有故事避免冲突，参考「书架」书籍风格，默认约 2000 字短篇 （可指定字数）。荒诞但不轻浮，喜剧底色下可有一丝温情或哲思。

功能 3 · 星际构史播报

约 800–1200 字、3–5 条新闻，格式固定（报头人声随机，其余逐字照用）：

（音乐）

〈报头人声，女声或男声随机〉：这里是星际和平播报，观众朋友们晚上好。
〈另一位〉：晚上好。
〈报头人声〉：欢迎收听今天的星际和平播报节目：

〈另一位〉：……
〈报头人声〉：……
〈另一位〉：……

〈轮到的那一位〉：本次播报到此结束，请在指定时间收听下一周期的星际和平播报。
（音乐）

口径：不写「第X条消息」这类序号前缀；「晚上好」之后必须有过渡句；报头人声可女声可男声（随机）， 选定后全篇严格交替；报道对象是星球、地区、派系与它们身上发生的事件，不是某个普通个人的轶事。 虚构文本必须足够科幻、足够太空、充满想象力——不是对已有故事的重组。

功能 4 · 星球制造机（0.3.0）

参照「星球列表」造新的星球：列表里的星球只提供世界观坐标与语感，新星球不得与其重名， 也不得把既有星球改个说法再交一遍。默认 3 颗（config.planetCount 可调，范围 1–10）。输出格式：

【星域名（English Name）】
一句话简介：……（不超过 40 字，写成「地点词条」而不是广告词）
详细设定：……（约 60–160 字：靠什么活着、谁在管事、当地人最大的麻烦是什么）
可能的故事方向：……（一到两句话）

生成结束后固定问两件事（模型不会替你决定）：

询问	答「要」时发生什么	答「不要」时发生什么
① 是否把这批新星球加入「星球列表」，供下次参考？	gs_planet_save 把这批星球并入列表，下次生成会看到它们	不写盘，本次结果不影响以后的生成
② 是否把「星球列表」重置回原始 27 颗（清除已并入的新星球）？	gs_planet_reset(confirm=true) 清空增量，满意与不满意的批次一起清掉	什么也不做

「重置」是破坏性操作：gs_planet_reset 不带 confirm: true 时只回报当前状态、绝不改文件， 所以模型必须先经你确认才能真的清空。清除的粒度为「全部新增」——只想清掉一部分，请手工编辑 planet-list.json 的 added 数组（见下一节）。

「星球列表」是什么

• **原始列表（27 颗）**编译在插件里（lib/planets.mjs 的 PLANET_BASELINE_SOURCE），所以「重置回原始」永远拿得回底本——即使工作区文件被删掉或写坏。
• 已并入的新星球写在 <工作区>/hsr-worldview-cache/planet-list.json 的 added[]， 与 user-canon.json 同理：gs_update 只重写 <数据集>.json，永不碰这个文件。
• 判定重名按「星球名或英文名去空格后同名、且英文名不区分大小写」，且原始列表优先： 与原始列表同名的候选会被拒绝并在 rejected 里说明撞的是哪一颗（例如 ARIVANTA 撞「阿丽万塔」， 或候选的 en 字段撞上原始英文名）；不会覆写你的原始设定。与已有增量同名的条目会被更新， 便于修正上一轮不满意的描述。
• 一次最多并入 20 颗（MAX_BATCH）。超出的候选不会写入，但会出现在返回值的 overflow: {count, names} 与 warnings 里——模型必须如实转告你，而不是说「都加进去了」。 增量列表总上限 200 颗，到顶后拒绝写入并提示先重置。
• 「出处」标注（visited 已探访 / mentioned 文本提及 / ruined 已毁或失去开拓意义 / unknown / other）是本插件加的，只用于给模型分组参考，不改变用户原文一个字。

功能 5 · 虚构差分方程（0.5.0 新增；0.6.0 修订版式与配额）

写法与版式完全同「神人制造机」（## 名称 + 〔主题类别〕命途归属 + 详细设定 + 可能的故事方向）。 区别只有一条——叙事对象不限于人物，五类主题大致均分：

主题类别	既有 212 条方程里的占比	本功能的目标
人物·职业/身份	59.0%（125 条）	不再是主体，每批最多 1–2 条
生物·物种/衍生体	14.6%（31 条）	每批至少 1 条，条数不设上限（鱼鸟比例不作要求）
装置·器物/场所	9.4%（20 条）	每批至少 1 条
抽象概念·现象/事件	9.0%（19 条）	每批至少 1 条
派系·机构/组织	8.0%（17 条）	每批至少 1 条，且必须新造机构名

默认 6 条（config.equationCount，3–10）；推荐配额是 人物 1 / 生物 2 / 装置 1 / 概念 1 / 派系 1——生物类条数不设上限，想多写生物就把份额分给它 （5 条同样合法：每类各 1 条）。输出格式：

## 方程名称

〔主题类别〕命途归属：〈主命途〉/〈次命途〉

详细设定：……（约 120–220 字，须带荒诞感）

可能的故事方向：……（一到两句话）

• 正文不写游戏机制：不出现方括号符号、百分比、暴击 / 护盾 / 战技点 / 终结技 / 削韧 / 回合等 机制语言（校验器会拒收）。
• 命途白名单 14 个（0.6.0 起含 贪饕）：欢愉 / 智识 / 繁育 / 毁灭 / 虚无 / 巡猎 / 记忆 / 存护 / 丰饶 / 同谐 / 贪饕 / 均衡 / 开拓 / 终末。加命途只为可写吞噬、饥饿、永无餍足这类题材， 不放宽星神纪律——奥博洛斯 仍在拒收词表里，只能以旧传闻 / 遗物 / 过期教条出现。
• 生物类专项：名字不少于 3 字，不得沿用既有构词（蠧役 / 残嗣 / 虫帝 / 王虫 / 巨人 …）； 生物类条数不设上限（五类里唯一豁免「单类 ≤2」的类别）；鱼类 / 鸟类的数量与比例 不作任何要求（2026-09-30 删除鱼鸟比重限制）；只剩「虫类 ≤ 四成」一条提示级口径。
• 落盘：gs_equation_save 逐条校验后写入 <工作区>/hsr-stories/equations/， 同一目录里再写一份 -equations.md 自检记录（五类配比、生物构成、被拒原因）。 与既有 212 条方程的重名检查依赖缓存；缓存缺失时降级为「跳过重名检查」并在 warnings 里说明。
• 规则实现集中在 lib/equations.mjs，完整口径见 docs/fiction-equation.md。

---

世界观数据

已发生的故事（本地，无需抓取）

工作区 hsr-missions/：

文件	内容
sr-开拓续闻-完整/	7 个系列 / 52 个「开拓续闻」任务（含完整台词稿）
trailblaze_missions.json	5 幕 / 18 系列 / 147 个开拓任务
adventure_other_tasks_full.json	7 章 / 33 个冒险任务
books_without_amphoreus.json	498 本书（「书架」风格参考）

功能 2 / 3 生成前必须读它，避免与既有事件冲突（功能 1 与功能 4 不需要）。

背景设定（12 个 Wiki 数据源，需联网抓取）

id	页面	抓取内容	过滤
relics	遗器图鉴	每套遗器的「遗器来历」（各部位 *故事）	—
lightcones	光锥图鉴	每个光锥的「光锥故事」	—
consumables	消耗品筛选	每个消耗品的「介绍」	排除所属地区=翁法罗斯
decorations	装饰一览	每个装饰的「介绍」	—
aeons	星神	每个星神的介绍	—
factions	派系	每个派系的内容	—
terms	专有名词	每个专有名词的内容	—
simuniverse	模拟宇宙	「模拟宇宙图鉴 → 星神」里的开发日志	—
curios	奇物一览（差分）	每个奇物的介绍/效果	—
events	事件一览	每个事件的内容	排除模式含「千面英雄」
equations	方程一览	每个方程的内容（效果全文）	排除模式含「千面英雄」
broadcast	星际和平播报	全部内容	—

抓取礼仪：相邻请求间隔 ≥ requestIntervalMs（默认 2000 ms），带浏览器 UA 与 Referer， 非 JSON 响应（WAF 会返回 HTTP 567 的错误页）走指数退避重试，重试耗尽则保留旧缓存并如实上报。

---

缓存目录

<工作区>/hsr-worldview-cache/

hsr-worldview-cache/
├── index.json          # 每个数据集的状态：lastUpdated / count / revisionId / ok / error
├── equations.json      # 每个数据集一个文件，字段见下
├── aeons.json
├── factions.json
├── terms.json
├── relics.json
├── lightcones.json
├── consumables.json
├── decorations.json
├── curios.json
├── events.json
├── simuniverse.json
├── broadcast.json
├── user-canon.json     # 用户设定补充（手工维护，抓取永不改写）
└── planet-list.json    # 「星球列表」增量（功能 4 写入；重置=清空 added[]）

planet-list.json 结构（baseline 是原始 27 颗的快照，仅供人工核对；程序只读 added[]）：

{
  "schema": "dsh-history-fictionologists/planet-list@1",
  "updatedAt": "2026-09-27T10:00:00.000Z",
  "baselineCount": 27,
  "addedCount": 1,
  "baseline": [ { "name": "阿丽万塔", "en": "Arivanta", "description": "…", "source": "visited" } ],
  "added": [
    { "id": "added-1", "name": "洛珂萨", "en": "Loxa", "description": "…", "source": "mentioned",
      "addedAt": "2026-09-27T10:00:00.000Z" }
  ]
}

单个缓存文件结构：

{
  "dataset": "equations",
  "title": "方程一览",
  "url": "https://wiki.biligame.com/sr/方程一览",
  "lastUpdated": "2026-09-26T02:00:00.000Z",
  "revisionId": 12345,
  "pageSha": "…",
  "count": 212,
  "excludedCount": 112,
  "entries": [ { "name": "…", "content": "…" } ],
  "warnings": []
}

提示：每个缓存文件都带 lastUpdated 时间戳。删掉整个目录就是彻底重置； 想强制重抓某一天数据，用 gs_update 的 force: true（或删掉对应的单个 json 文件）。

工作区解析优先级：插件 config.workspace → DSH_HISTORY_FICTIONOLOGISTS_WORKSPACE → DSH_WORKSPACE → 当前工作目录（或其上层含 hsr-missions 的目录）→ 插件包所在目录。

用户设定补充（user-canon.json）

缓存是「抓来的事实」，你自己的设定裁定是另一层——它优先于缓存。

• 位置：<工作区>/hsr-worldview-cache/user-canon.json，手工维护。gs_update 只重写 <数据集>.json，永远不会碰这个文件（所以裁定不会被下一次抓取抹掉）。
• 生效方式：gs_read 结果末尾附上「用户设定补充」区块，并明确标注「冲突时以此为准」； gs_setup 报告条数与更新时间；系统提示的「语言风格总则」也写明了它的优先级。
• 作用域：dataset 写数据集 id 时只在该数据集生效（aeons / aeon 都认）， 写 "*" 或省略则对全部数据集生效；match 是触发关键词（命中 gs_read 的 query， 或与该数据集返回的条目同屏出现时带出）；query 为空时，该数据集名下的裁定一律带出。
• note 必填：没有 note 的条目会被忽略并告警——空口裁定不算设定。

{
  "schema": "dsh-history-fictionologists/user-canon@1",
  "updatedAt": "2026-09-26T03:30:00.000Z",
  "entries": [
    {
      "dataset": "aeons",
      "match": ["贪饕", "奥博洛斯"],
      "name": "「贪饕」，奥博洛斯",
      "status": "已镇压（不得写成在世／失踪待返／即将归来）",
      "note": "奥博洛斯早已四分五裂、被镇压。缓存里的「已失踪无影」只是旧传闻，不得当作现状。",
      "source": "用户评审（2026-09-26）"
    }
  ]
}

文件缺失 = 没有裁定（正常状态）；文件损坏或 JSON 非法 = 降级为「0 条 + 告警」， 不影响缓存读取与其它工具。读取逻辑在 lib/usercanon.mjs， 测试在 test/usercanon.test.mjs。

---

成品落在哪

类型	目录
短篇小说（功能 2）	<工作区>/hsr-stories/<时间戳>-<标题>.md
星际和平播报（功能 3）	<工作区>/hsr-broadcasts/<时间戳>-<标题>.md
灵感（功能 1）	<工作区>/hsr-stories/inspirations/<时间戳>-<标题>.md

文件带 YAML front-matter（kind / title / createdAt / generator）。 把 config.saveOutputs 设为 false 可关闭落盘。

---

配置项

在 profile 的 cordis.patch.yml 里按 id 覆盖（整行 config 会被替换，所以要把需要的键都写上）：

- id: dsh-history-fictionologists
  config:
    workspace: ''            # 留空自动解析
    requestIntervalMs: 2000  # 相邻 Wiki 请求最小间隔（毫秒）
    requestTimeoutMs: 30000
    maxRetries: 3
    staleAfterDays: 7        # 超过该天数即建议重新抓取
    recentGuardDays: 7       # 不足该天数时，选 Y 也先确认一次
    defaultStoryWords: 2000
    defaultBroadcastWords: 1000
    inspirationCount: 4      # 3–5
    planetCount: 3           # 星球制造机默认颗数（1–10）
    equationCount: 6         # 虚构差分方程默认条数（3–10；生物类不设上限，其余四类单类最多 2 条）
    saveOutputs: true
    userAgent: 'Mozilla/5.0 …'

---

目录结构（插件本体）

dsh-history-fictionologists/
├── package.json            # dsh.bundle.patch 指向 cordis.patch.yml；main = lib/shell.js
├── cordis.patch.yml        # bundle 挂载声明
├── lib/
│   ├── shell.js            # 插件外壳：/gs 命令、10 个工具、风格提示词、Config（包入口）
│   ├── resolve.js          # @deepseek-ai/* 可选依赖的多 base 解析链
│   ├── paths.js            # 工作区 / 缓存 / 成品目录解析
│   ├── missions.js         # hsr-missions 读取与索引
│   ├── digest.js           # 命名逻辑 / 书架风格 / 播报格式素材
│   ├── usercanon.mjs       # 用户设定补充（优先于抓取缓存）
│   ├── planets.mjs         # 原始 27 颗星球底本 + 增量列表读写/重置
│   └── wiki/               # 12 个数据源的抓取与解析
│       ├── datasets.mjs    # 数据源登记表（含单复数 id 别名）
│       ├── client.mjs      # 限流 / 重试 / WAF 识别
│       ├── html.mjs        # 通用 HTML 解析
│       ├── wikitext.mjs    # {{模板|字段=值}} 解析
│       ├── extract.mjs     # 12 个抽取器
│       ├── cache.mjs       # 原子缓存 + revid 短路
│       └── index.mjs       # status / update / read / sampleAll
├── test/                   # node:test：离线重放 + mock ctx + 宿主校验器一致性（无网络）
├── docs/DESIGN.md          # 数据源结构实测记录（抓取选择器依据）
└── CHANGELOG.md

入口文件叫 lib/shell.js 而不是惯用的 lib/index.js：一次编辑事故把后者写成了非 UTF-8 字节，文件系统观察策略（正确地）拒绝再覆写一个读不出来的路径，于是安全修复是换一个 干净文件名并把 package.json 的 main/exports 指过去。行为与 index.js 完全等价。

---

故障排查

现象	原因 / 处理
输入 /gs 没有补全、没有反应	bundles 行未生效：确认 --dump-config 里有该行，然后进程级重启
--dump-config 报告跳过该 bundle	报的是原因（多半是解析不到包）。确认 node_modules/dsh-history-fictionologists 链接或已 dsh plugin add
--dump-config 报错、整棵插件树崩	Config 被导出成普通对象（本插件已规避；若你改过 lib/shell.js 请检查）
工具「静默消失」	@deepseek-ai/* 解析失败。node -e "import('./lib/resolve.js').then(m=>console.log(m.resolutionReport()))" 看解析链
工具报 returned invalid output	某个工具返回值违反了它自己声明的 schema（例如可选键出现了 null）。跑 node --test test/host-validator.test.mjs 会直接指出是哪一个
抓取全部失败	网络不通，或请求过于频繁被 WAF（HTTP 567）拦截。调大 requestIntervalMs 后重试
模型说「未读取到数据」	先跑一次 gs_update；或检查 config.workspace 是否指向了正确的工作区
想看抓取细节	缓存目录的 index.json 里有每个数据集的 ok / error / count / revisionId
功能 4 生成的星球没进列表	看 gs_planet_save 返回里的 rejected：与原始 27 颗重名的候选会被拒绝（故意不覆写原始设定）
「星球列表」被清空或写坏	原始 27 颗编译在插件里，不会丢：调用 gs_planet_reset(confirm=true) 即可重建文件
模型没问「是否并入 / 是否重置」	这两问同时写在系统提示与 /gs 协议文本里；直接提醒它「按功能 4 的收尾问两件事」

自检命令

cd <你的仓库路径>
node scripts/check.mjs    # 首选：语法检查全部模块 + 跑全套测试（约 1.5 秒）
node --test               # 只跑测试（Node 自动发现 test/ 下所有 *.test.mjs）
node _evidence/e2e-wiring.mjs     # 真实 Wiki 上跑通工具接线（会联网，约 15 秒）
node _evidence/run-extract.mjs --live   # 12 个数据源真机抓取取证（会联网，约 60 秒）
node _evidence/verify-gs-e2e.mjs  # 隔离实例里端到端验证 /gs（约 15 秒）

为什么不用 npm test：这台机器上 PATH 里只有 npm.ps1，而 PowerShell 执行策略禁止运行它， 所以 npm test 在 PowerShell 里直接报 running scripts is disabled（用 cmd /c "npm test" 可以跑通）。 另外 node --test test/ 这种带斜杠的写法在 Node 24 上会失败（Cannot find module ...\test： Node 不会替 npm script 展开 glob），所以 package.json 的 test 用的是裸 node --test 自动发现。 为了让自检不依赖 npm，才把检查逻辑放进 scripts/check.mjs。

测试分层（每一层都补上一层的盲区）：

层	文件	能证明什么	证明不了什么
契约	test/plugin.test.mjs	注册物齐全（10 工具 / 1 命令 / 1 section）、/gs handler 在异常与降级输入下不抛、规范 JSON	返回值是否符合 output.schema（mock 不校验）
宿主校验	test/host-validator.test.mjs	用宿主自己的 validateJsonSchemaValue 校验全部工具（含新增的功能 5）的降级路径；含元测试证明该断言会失败；含 args 层拒绝、卸载/重载与 stub 接缝的隔离断言	真实进程内的注册成功
解析	test/wiki.test.mjs	12 个抽取器对真实 HTML 的选择器正确性（离线重放）+ revid 短路 + WAF 重试 + 注入时钟的确定性限流断言	真机网络行为
连续性	test/missions.test.mjs	hsr-missions 三种 JSON 的读取、截断上界、缺失降级	—
星球列表（0.3.0）	test/planets.test.mjs	原始 27 颗与用户原文逐条一致、读取降级、重名规则（原始优先 + 星球名/英文名 + 大小写不敏感）、超限候选不静默丢弃、截断有告警、原子写、重置、上限、三个星球工具的 schema/渲染/无损 JSON、/gs 协议的两问	真机上模型是否照做（那取决于模型）
虚构差分方程（0.5.0；0.6.0 修订）	test/equations.test.mjs	五类配比（每类 ≥1；非生物类 ≤2，生物类不设上限）、鱼鸟比例已无任何判定、命途白名单含贪饕且点名奥博洛斯仍被拒、生物命名（≥3 字 / 不得沿用既有构词）、星神纪律、机制语言拒收、与既有 212 条方程的重名、逐条落盘与自检记录、saveOutputs=false 与缓存缺失降级	真机上模型是否照做（那取决于模型）

全部离线（每个 new WikiClient 都注入了假 fetch，套件里 globalThis.fetch 一次都不会被调用）。 需要联网的验证在 _evidence/（run-extract.mjs --live、cache-roundtrip.mjs、e2e-wiring.mjs）。

在哪台机器上跑得出什么

test/ 里有一层用例重放本地夹具（_probe/html/*.html）与真实语料（hsr-missions/）—— 这两份数据按体积与版权考虑不进版本库（见 .gitignore）。所以同一套用例在不同检出里给出的数字不同：

检出	命令	结果
作者工作区（_probe/ 与 hsr-missions/ 都在）	node --test	204 用例 / 203 pass / 0 fail / 1 skip（2026-10-01 实测；唯一 skip 是「缓存已存在时不再跑降级断言」）
全新克隆（两者都不在）	node --test	用例总数相同，其中「重放 _probe/ 夹具 / 依赖 hsr-missions/」的那些显式 skip（每一条都带原因）

第一行那个数字在本机（受限沙箱）是由逐文件 node test/<name>.test.mjs 直跑汇总的： 沙箱禁止 node --test 为每个测试文件 spawn 子进程（EPERM）。跑的是同一批文件、同一套断言。

夹具/语料缺失导致的每一条 skip 都带原因，直接印在输出里，例如：

﹣ update: unknown ids and a broken client degrade into failed[] # _probe/html/遗器图鉴.html,
  _probe/html/光锥图鉴.html, _probe/html/消耗品筛选.html, _probe/html/装饰一览.html (+8 more)
  are not in this checkout (see .gitignore)

设计口径：夹具缺失 → 显式 skip；从不静默通过，也从不弱化断言。 所有与磁盘无关的用例（client: 限流与 WAF 重试、HTML/wikitext 解析、合成缓存降级、 gs_* 工具输出的规范 JSON 与宿主校验器一致性、test/planets.test.mjs 的全部 22 条、 test/equations.test.mjs 的全部 27 条……） 在任何检出里都照跑。

唯一的例外是 test/host-validator.test.mjs：这一层要解析宿主的 validateJsonSchemaValue，所以前置条件是本机装过 dsh（解析基座见 lib/resolve.js）。没装时它是硬失败而不是 skip—— 实测 10 fail / 2 pass / 0 skip。这是刻意的：这一层存在的意义正是证明其余断言不是恒真的， 让它静默跳过就等于把「已验证」变成一句空话。装上 dsh 后这 10 条照跑。

想要全量（含夹具与语料层）：把 _probe/（docs/DESIGN.md 里有每个页面的抓取依据）与 hsr-missions/ 准备好，或直接在作者工作区里跑。

最关键的一条产品证据（可复现）：node _evidence/check-prompt-section.mjs

它从隔离实例的真实会话日志里解析出注入记录，证明模型确实收到了这份指导，而不只是「插件注册成功」：

record type=system/message  role=system  chars=3500   <- 整条组装后的系统提示
风格总则本体 = 725 字符（= 抓取当次的 __internals.STYLE_GUIDE.length，与日志内容逐字节一致）
gs_* tools in the request tool list: gs_digest, gs_missions, gs_read, gs_save, gs_setup, gs_update
  YES  章节标题 / 风格总则 / 功能 1 四个字段 / 功能 2（2000 字·荒诞但不轻浮）
  YES  功能 3（女声·男声·（音乐）·结束语·800–1200 字）/「不得凭空编造与既有设定冲突的事实」

即：风格总则（本体 725 字，0.1.0 版）与当时三个功能的逐字格式进入了那条 3500 字的组装后系统提示， 6 个 gs_* 工具同时出现在请求的工具列表里。 输出在 _evidence/prompt-section-injection.txt。

口径提醒（复核者 R3-5 纠正，我先前表述有夸大）：3500 是整条系统提示的长度，不是风格总则的长度。 复核者另做了更强的一致性检查：日志里的风格文本 includes(STYLE_GUIDE) === true，即与抓取当次的源码逐字节一致。

版本提醒：上面这段是 0.1.0 的快照，当时 STYLE_GUIDE 为 725 字符。此后每次改提示词长度都会变： 0.1.1（加入「星神纪律」）为 1161 字符 / 55 行，0.2.1 为 1291 字符 / 57 行， 当前源码（0.3.0，加入「星球制造机」格式与两问纪律）为 1748 字符 / 72 行。 _evidence/prompt-section-injection.txt 仍是 0.1.0 那次抓取，对 0.3.0 已过期； 要刷新它需要在隔离实例里重跑 node _evidence/check-prompt-section.mjs（本机日常实例不重启）。 0.3.0 这条链路由 test/planets.test.mjs 的两条离线断言兜底：系统提示总则里必须出现星球格式与两问， /gs 协议文本里必须出现四个功能与两问。

开发/取证目录（不属于插件运行时，不随包发布）

目录	内容
_probe/	抓取前的结构侦察产物：12 个页面的原始渲染 HTML、结构普查文本、真实 wikitext 样本。是 docs/DESIGN.md 里每条选择器的原始证据
_evidence/	自证与复核证据：离线重放报告、真机抓取日志、缓存往返日志、接线检查、端到端验证脚本与输出、独立复核报告 review-shell.md
BRIEF.md	实现规格（数据源结构实测记录 + 接口契约）。有勘误表，见文件头的回填说明

隔离实例端到端验证（绝不动你自己的 ~/.dsh）：

node _evidence/verify-gs-e2e.mjs          # 默认路径，约 15 秒
node _evidence/verify-gs-e2e.mjs --model  # 额外让模型真调一次 gs_setup（隔离 home 无模型路由，会超时）
# 1) 建一个临时 DSH_HOME + web profile（bundles 含本插件）
# 2) 起 dsh --profile web --port 3081 --no-open
# 3) 用启动 token 换签名 cookie
# 4) session/create → commands/list（确认 /gs 出现）→ commands/execute "/gs"
# 5) 收尾：taskkill 自己的子进程树 + 杀掉「测试端口」的持有者

诚实边界：--model 那一步在隔离 home 里必然超时——启动 token 与模型路由都属于你自己的实例， 隔离 home 两者都没有（实测：prompt 被接受后 180 秒内会话日志始终为空）。该契约因此由 test/host-validator.test.mjs（用宿主同一个校验函数，离线）与你实例里那次真实调用共同覆盖： 插件首次装好后模型确实调到了 gs_setup，而正是那一次暴露了 lastUpdated: null 的 schema bug。

⚠️ 收尾只用 taskkill /PID <自己的子进程> /T 加「测试端口持有者」。不要改成 Get-Process node | Stop-Process——开发过程中这么写了一次，把用户正在使用的 dsh 实例 一起杀掉了（已修正，教训记在 _evidence/verify-gs-e2e.ps1 文件头与脚本注释里）。

---

版权

插件源代码与文档以 MIT 许可发布，见 LICENSE。 NOTICE 另外声明了第三方归属：《崩坏：星穹铁道》的游戏文本与世界观设定版权归 米哈游（HoYoverse），Wiki 页面文本版权归 Bwiki 编辑者；MIT 不覆盖这些素材。

原始文本版权归米哈游（HoYoverse）及 Bwiki 编辑者所有。本插件产出的内容属于非营利性二创， 米哈游对二创持开放态度。仅供个人学习、检索与研究使用。