@sophiacyl/dsh-plugin-waves 0.0.0-stage → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "@sophiacyl/dsh-plugin-waves",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "license": "GPL-3.0",
+  "type": "module",
+  "description": "鸣潮 dsh-go 原生测试适配：查询、面板、练度与设置；基于 Loping151/dsh-plugin-waves",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "locale",
+    "cordis.patch.yml",
+    "install.sh",
+    "install.ps1",
+    "ICON.png",
+    "service/rover",
+    "service/tools",
+    "service/ai",
+    "service/knowledge",
+    "service/pyproject.toml",
+    "service/ICON.png",
+    "service/plugins/__init__.py",
+    "DSH-GO-VERIFICATION.md",
+    "tests"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "dshGo": {
+    "v": 1,
+    "title": {
+      "zh": "鸣潮",
+      "en": "Waves"
+    },
+    "icon": "star",
+    "assets": "service/data/media",
+    "capabilities": [
+      "files"
+    ],
+    "contributes": {
+      "composer.actions": [
+        {
+          "id": "waves-open",
+          "label": "鸣潮",
+          "icon": "star",
+          "effect": {
+            "type": "open",
+            "page": "panel:waves-home"
+          }
+        }
+      ],
+      "panels": [
+        {
+          "id": "waves-home",
+          "title": "鸣潮查询",
+          "icon": "star",
+          "placement": [
+            "session.tab",
+            "features",
+            "chat.panel"
+          ]
+        },
+        {
+          "id": "waves-settings",
+          "title": "鸣潮设置",
+          "icon": "settings",
+          "placement": [
+            "features"
+          ]
+        },
+        {
+          "id": "waves-edit",
+          "title": "修改设置",
+          "icon": "edit",
+          "placement": [
+            "session.tab"
+          ]
+        }
+      ]
+    },
+    "minApp": "1.0.13"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.2.0-rc.2 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7 || ^0.2.0-rc.2 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7 || ^0.2.0-rc.2 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.7 || ^0.2.0-rc.2 || 0.2.2-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-attachment": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.2.0",
+    "dsh": "^0.1.0-rc.7 || ^0.2.0-rc.2 || 0.2.2-rc.1"
+  },
+  "icon": "./ICON.png",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "beta"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sophiacyl/dsh-plugin-waves.git"
+  },
+  "homepage": "https://github.com/Sophiacyl/dsh-plugin-waves/tree/release/npm",
+  "bugs": {
+    "url": "https://github.com/Sophiacyl/dsh-plugin-waves/issues"
+  }
+}

package/service/ai/AI_DATA.md

@@ -0,0 +1,221 @@
+# 鸣潮数据与脚本指南
+
+本地存了什么、怎么读、怎么用插件自带的评分内核自己算。
+出图和常规查询走 waves 工具下命令；要精确数值或跨角色统筹，按这份写脚本。
+
+## 铁律
+
+- **不改用户数据**。`service/data/` 只读，包括 `players/`、`*.db`、`config.json`、`show/`。
+  不要写、不要删、不要"顺手修一下"。改配置只能由用户在设置页点，改账号数据只能由用户发命令。
+- 要写东西就用 `wwdata.scratch()`（系统临时目录下的 `dsh-waves-scratch/`，会建好并返回路径）：
+  模拟数据、中间结果、脚本产物都落这里。沙箱只放行临时目录和工作区，别往 data 里写。
+- sqlite 只能只读打开：`sqlite3.connect("file:...?mode=ro&immutable=1", uri=True)`。
+  服务正在写这个库，用读写连接会把它写坏。
+- **数据旧了就先刷新再读**。每份数据都带时间戳，见下节。刷新靠跑命令，不是自己去动文件。
+
+## 数据新鲜度
+
+| 想要的东西 | 文件 | 刷新命令 |
+|---|---|---|
+| 角色面板 | `players/<uid>/rawData.json.gz` | `ww刷新面板`（全量，慢）/ `ww刷新<角色>面板` |
+| 账号概览 | `players/<uid>/baseInfo.json` | `ww查询` |
+| 矩阵 | `players/<uid>/matrixData.json.gz` | `ww矩阵` |
+| 深塔 | `players/<uid>/rover.json.gz` | `ww深塔` |
+| 冥海 | `players/<uid>/slashData.json.gz` | `ww海墟` |
+| 抽卡 | `players/<uid>/gacha_logs.json.gz` | `ww抽卡记录` |
+
+挑战数据里有 `record_time`（秒级时间戳），面板数据看文件 mtime。
+距离用户提及超过一两天、或者用户刚说"我又打了一轮"，先用 waves 工具跑一次对应命令读取拉取数据。
+
+## 起手式
+
+跑脚本用服务自己的解释器（Linux/macOS：`<service>/.venv/bin/python`，Windows：`<service>/.venv/Scripts/python.exe`），
+系统 python 缺依赖，评分相关的接口会直接报错。
+
+```python
+import sys; sys.path.insert(0, "<service>/tools")   # <service> 见工具说明里的绝对路径
+import wwdata as w
+
+uid = w.default_uid()          # 当前默认账号（wavesbind 里的第一个）
+w.bound_uids()                 # 绑过的全部账号
+w.base_info(uid)               # 名字/等级/世界等级/激活天数
+```
+
+`wwdata` 只读，且已经把 gzip、别名、评分模板这些琐事包好了。直接读 json 也行，但别绕过只读约束。
+
+跑脚本不需要沙箱升级：读 data、写 scratch 都在默认权限内，shell 工具别带
+`sandbox_permissions`/`justification` 参数（同级升级会被拒，空 justification 会报错）。
+Windows 下控制台输出中文会乱码：结果写成 UTF-8 文件到 `wwdata.scratch()` 再读回来，别依赖 stdout。
+
+## 角色与练度
+
+```python
+w.roster(uid)     # 紧凑一行式: "卡提希娅 Lv90 6链 不屈命定之冠5阶 声骸176.7"
+w.roster(uid, 10) # 只要练度最高的 10 个
+
+w.roles(uid)      # 完整结构, 需要逐项判断时才用
+# {'id','name','level','attribute','chain'(链数),'weapon':{'name','level','reson'},
+#  'skills':{'常态攻击':10,...},'echo_score','sonatas':{'沉日劫明':5}}
+```
+
+只想知道"有谁、练到什么程度"就用 `roster`；四五十个角色的 `roles` 全量结构没必要整份摊开。
+
+**练度不一是常态**，给建议前先看清：`level`、`chain`、`weapon.reson`（谐振阶数）、`skills`、`echo_score`。
+一个 0 链 90 级配专武的角色和一个 6 链 70 级配三星武器的，不能当同一个东西排。
+
+名字/别名（别自己猜简称）：
+
+```python
+w.resolve("洛可可")      # 别名 → 正式名，认不出返回 None
+w.resolve_sonata("暗套")  # 套装别名 → 正式名
+w.name(1507)             # 角色 id → 名字
+w.char_id("椿")          # 名字 → id
+w.id2name()              # 全表，够用就别再去读 alias 文件
+```
+
+别名原始表在 `data/XutheringWavesUID/alias/`（`char_alias.json`、`sonata_alias.json`、`echo_alias.json`、
+`weapon_alias.json`），只有 `w.resolve` 认不出来时才需要翻。
+
+角色图鉴（detail_json 的精简视图，富文本标记已剥掉，只传有效信息）：
+
+```python
+w.char_info("菲比")                  # 属性/武器型/星级/技能/共鸣链, 纯文本
+w.char_info("菲比", parts=["stats"]) # 附成长数值(还可加 "ascensions")
+w.detail_file("weapon", "苍鳞千嶂")   # char/weapon/echo/sonata 源文件路径
+w.clean_text(s)                      # 自己读源文件时剥 <span style=...> 等标记
+```
+
+要抠 `char_info` 没带出来的原始字段（成长曲线细节、技能树 param 等）才去读 `detail_file` 指向的源文件。
+
+用户话里出现别名时，插件会在上下文尾部补一条对照（"暗套→沉日劫明"这种）。那是按子串匹配来的，
+可能误命中，别当成用户已经确认的指代；拿不准就按用户原话问一句。
+
+## 声骸与评分
+
+```python
+w.echoes(uid)                          # 全部已装备声骸拉平成一张表
+w.echoes(uid, sonata="沉日劫明")        # 按套装筛
+w.echoes(uid, char="椿")               # 按角色筛
+# 每项: owner/owner_id/slot/cost/level/sonata/echo/main/subs/raw
+
+w.score(uid, "洛可可", echo)   # 把这件放到洛可可的评分模板下打分 → {score,grade,template,char}
+w.total_score(uid, "椿", echo_list)
+w.calc_temp(uid, "椿")        # 该角色当前的评分模板（词条权重）
+```
+
+分数来自插件自带的评分内核（各角色模板不同），**不是伤害模拟**。要伤害对比就跑 `ww<角色>伤害`。
+
+只有已装备的声骸会出现在数据里；仓库里没戴的读不到。
+
+## 场景一：优化矩阵配队
+
+```python
+ms = w.matrix_summary(uid)
+# {'record_time', 'reward', 'total_reward',
+#  'modes':[{'mode_id','rank','score','pass_boss','boss_count','round',
+#            'teams':[{'roles':['赞妮','菲比','白芷'],'pass_boss','boss_count','buffs':[...]}]}],
+#  'stage_roles': {'1_0': ['赞妮','菲比','白芷'], ...}}   # 各层实到阵容
+```
+
+做法：
+
+0. **先核对周期**：`w.challenge_periods()` 拿当期开始时间，与 `matrix_summary` 的 `record_time`
+   比对。record_time 早于当期 start = 上一期数据，只能当历史参考；`ww矩阵` 提示"暂无数据" =
+   已换期且新一期没打（不是 bug，见 kb"挑战周期"）。当期 boss/可多次上场角色**没有接口可查**
+   （矩阵接口只回个人战绩，wiki 活动说明只有时间条件）：用户没打新一期就把所缺信息一次列全
+   请用户从游戏里带出来，别拆成多轮。目标不用问，默认冲总分最高。配队硬约束见 kb"矩阵配队规则"。
+1. `matrix_summary` 看哪层卡住（`pass_boss < boss_count`）、当前用了谁、这层的 buff 是什么。
+2. `roles(uid)` 拿全部持有角色和练度，注意别推荐没有的角色，也别把低练度角色当核心。
+3. buff 描述里往往点名了机制（异常效应、虚湮、共鸣解放等），据此决定配队方向。
+4. 需要版本环境/流行配队时可以联网查，但**必须回到第 2 步过滤成用户真有的角色**，
+   并按练度给出"现在能上的"和"值得练的"两档。
+5. 想验证输出强度，对候选主 C 跑 `ww<角色>伤害` 看期望伤害。
+
+## 场景二：一套声骸在多角色间怎么分
+
+沉日劫明这类套装会被丹瑾、弗洛洛、椿、洛可可、坎特蕾拉、千咲等多人共用，但吃的词条不一样，
+所以同一件在不同人身上分数差很多，互换有可能双赢。但注意不是随便换，需要受到装配cost<=12且同套装（不论2、3还是5件套）内声骸不能重复，
+且注意部分角色使用3+2搭配等，比如千咲/弗洛洛可能只有2件是沉日劫明，另外3件由于跨套装一般不考虑更换
+
+```python
+w.sonata_pool(uid, "沉日劫明")     # {角色: [该套装的声骸...]}
+w.cross_scores(uid, "沉日劫明")    # 每件 × 每个候选角色的交叉分，按"换人能涨多少"排序
+w.swap_gains(uid, "沉日劫明")      # 直接给出总分净增益为正的两两互换（只在 cost 相同的件之间）
+```
+
+`cross_scores` 是证据，`swap_gains` 是结论。`swap_gains` 空不代表没优化空间——
+它只换 cost 相同的件；`cross_scores` 里 `gain_vs_owner` 高但换不动的，通常是槽位 cost 对不上，
+这种要在建议里说清楚（"这件在弗洛洛身上更值，但他没有 4c 槽"）。
+
+想把候选角色扩到还没戴这套的人：`w.cross_scores(uid, "沉日劫明", chars=["千咲", "坎特蕾拉"])`。
+
+### 把截图里的声骸也放进池子
+
+`ww评分 <角色><cost>c(主词条)` 带图（调 waves 工具时设 with_image=true）走远端识图评分，回的是一张卡片；
+卡片会被本地 OCR，词条名与数值就在返回的 summary"图片文字(OCR)"里。
+要让新声骸参与本地推演，把词条转录出来自己造一件——优先从评分卡的 OCR 文字里抄；
+OCR 缺漏或没走评分时，能读图的路由用读图工具读上下文提示给的暂存路径，都不行就让用户打字发来，
+别凭空编数值：
+
+```python
+new = w.make_echo(
+    cost=4, sonata="沉日劫明", echo_name="无冠者",
+    main=[("攻击", "18.0%"), ("暴击伤害", "44.0%")],
+    subs=[("暴击", "8.1%"), ("攻击", "11.6%"), ("共鸣效率", "8.4%"),
+          ("重击伤害加成", "9.9%"), ("攻击", "40")],
+)
+for c in ["椿", "洛可可", "弗洛洛"]:
+    print(c, w.score(uid, c, new))
+```
+
+词条名和值照抄面板原文（带 `%` 就带上）。
+
+### 重组出一张完整面板卡
+
+打分归打分，想让用户直观看到"换完之后面板长什么样"，用 `waves_panel` 工具（不是命令）：
+
+```json
+{ "char": "椿",
+  "echoes": [
+    { "slot": 1, "from": { "char": "洛可可", "slot": 2 } },
+    { "slot": 2, "name": "无冠者", "cost": 4, "sonata": "沉日劫明",
+      "main": [["暴击", "22.0%"], ["攻击", "150"]],
+      "subs": [["暴击伤害", "21.0%"], ["攻击", "11.6%"]] }
+  ],
+  "change": "换6链" }
+```
+
+- 没列到的槽位保持该角色当前装备；`from` 引用别人正在装备的那件，自定义件词条照抄原文。
+- cost 只能 1/3/4，总和 ≤12；`change` 走换装文本管线（换链/武器/等级/技能/主词条）。
+- 只在本地渲染出卡：不写 `players/`、不进总排行上传队列。别把假设数据说成用户真实面板。
+
+## 游戏常识知识库
+
+库洛 wiki 文本（图鉴/攻略/百科/活动/任务/剧情）已在本地，按"条目/小节"粒度存放，
+纯文本、图片以 `![名](url)` 内嵌——要展示图片直接把 url 给用户。
+
+```python
+w.kb("虚湮效应")                 # 词法检索小节 → [{id,entry,title,tags,score,snippet}]
+w.kb("配队", tags=["玩法攻略"])   # 按 tags/source 收窄
+w.kb_get("wiki-xxx#2")           # 小节 id → 该小节
+w.kb_get("wiki-xxx")             # entry id → 整条(全部小节)
+```
+
+先 `kb` 看 snippet 定位到小节，通常小节就够了；要上下文再用 entry id 取整条，别整库摊开。
+用户话里首次提到角色名/机制词时，插件会自动附带该条目的首个小节（每会话每条只附一次，
+标注"仅供参考"）；那只是字面命中，后续要引用细节自己再 `kb`/`kb_get`。
+
+## 直接读文件
+
+`wwdata` 没覆盖到的，自己读也行，路径都在 `data/XutheringWavesUID/`：
+
+- `resource/map/detail_json/char/<角色id>.json` 角色详情：技能树、共鸣链、成长曲线、属性
+- `resource/map/detail_json/` 下还有 `weapon`、`echo`、`sonata`、`forte`、`material`、`challenge`
+- `resource/map/CharId2Data.json`、`id2name.json`
+- `players/<uid>/state.json` 每个角色的查看/刷新次数（用户最近在关注谁）
+- `players/<uid>/gachaStats.json` 各卡池 `total/avg/remain/up_count`
+
+## 跑命令
+
+要刷新数据、要出图、要用插件已有的分析（伤害、优化建议、练度、排行），
+直接调 waves 工具下命令，别自己重写一遍。命令清单看 `ww帮助`，或工具说明里的常用列表。

package/service/knowledge/additional/manual.jsonl

@@ -0,0 +1,5 @@
+{"id": "add-cycle#0", "entry": "add-cycle", "entry_title": "挑战周期", "section_title": "周期规则", "title": "挑战周期/周期规则", "tags": ["游戏机制", "深塔", "冥歌海墟", "终焉矩阵"], "tier": "core", "source": "manual@2026-08-30", "triggers": ["挑战周期", "深塔周期", "海墟周期", "矩阵周期", "换期", "第几期"], "content": "深塔与冥歌海墟每 28 天一期，终焉矩阵名义 42 天一期但实际会提前几天、按锚点人工校准；换期边界都在当天 04:00（UTC+8）。基准锚点（与插件 wutheringwaves_abyss/period.py 同源，人工维护）：\n- 深塔：2025-11-10 04:00 = 第 29 期开始，此后每 28 天一期。\n- 冥歌海墟：2025-11-24 04:00 = 第 11 期开始，此后每 28 天一期。\n- 终焉矩阵：第4期 2026-05-07、第5期 2026-06-14、第6期 2026-07-17、第7期 2026-08-27（均 04:00 开始）；第 7 期之后按 42 天外推，实际可能提前，以游戏内为准。\n当前期号与起止时间用脚本取：w.challenge_periods() → {tower/slash/matrix: {period, start, next, days}}。"}
+{"id": "add-record-missing#0", "entry": "add-record-missing", "entry_title": "挑战记录缺失", "section_title": "含义与处理", "title": "挑战记录缺失/含义与处理", "tags": ["游戏机制", "深塔", "冥歌海墟", "终焉矩阵"], "tier": "core", "source": "manual@2026-08-30", "triggers": ["暂无数据", "记录缺失", "没有数据", "查不到记录", "没有记录"], "content": "查询深塔/海墟/矩阵时提示\"暂无数据\"、记录缺失或变空，通常不是故障，而是挑战已换期：官方接口只保留当期记录，旧一期数据在换期时清空，用户新一期还没打就是空的。此时应告知用户挑战已更新、打完新一期再查，不要当成 bug 去修。\n本地缓存（players/<uid>/matrixData 等）可能还是上一期的：先用 w.challenge_periods() 拿当期开始时间，与数据里的 record_time 比对——record_time 早于当期 start 就是上一期数据，只能当历史参考，绝不能当作当期现状来分析。当期的 boss/增幅回路/可多次上场角色没有接口可查（详见 kb\"矩阵配队规则\"），把所缺信息一次列全请用户从游戏里带出来。"}
+{"id": "add-tower-rules#0", "entry": "add-tower-rules", "entry_title": "深塔配队规则", "section_title": "规则", "title": "深塔配队规则/规则", "tags": ["游戏机制", "深塔", "配队"], "tier": "core", "source": "manual@2026-08-30", "triggers": ["深塔配队", "疲劳度", "疲劳机制"], "content": "深塔配队规则（人工维护）：\n- 角色有疲劳度机制：出战会累积疲劳，复用同一角色打多层/多塔要考虑疲劳带来的减益。\n- 声骸可以复用：不同队伍之间可以共用同一套声骸，配装不受队伍互斥限制。"}
+{"id": "add-slash-rules#0", "entry": "add-slash-rules", "entry_title": "海墟配队规则", "section_title": "规则", "title": "海墟配队规则/规则", "tags": ["游戏机制", "冥歌海墟", "配队"], "tier": "core", "source": "manual@2026-08-30", "triggers": ["海墟配队", "上下半场"], "content": "冥歌海墟配队规则（人工维护）：同一场的上下半场在开打前一次性选好角色，因此这 6 个角色互斥（上下半不能用同一人），且 6 人之间无法互换声骸和武器。给海墟配队建议时要按\"一场 6 个不同角色、装备各自固定\"来排。"}
+{"id": "add-matrix-rules#0", "entry": "add-matrix-rules", "entry_title": "矩阵配队规则", "section_title": "规则", "title": "矩阵配队规则/规则", "tags": ["游戏机制", "终焉矩阵", "配队"], "tier": "core", "source": "manual@2026-08-30", "triggers": ["上场两次", "上场次数", "多次上场", "当期矩阵", "矩阵配队"], "content": "终焉矩阵配队规则（人工维护）：\n- 所有队伍之间不能互换任何声骸和武器：一个角色带什么装备就全程固定，跨队共用装备不可行。\n- 同一角色默认整期只能上场一次；只有少数角色可以上场 2 次（当期指定，需要查当期信息确认是谁）。\n- 部分增幅回路（buff）也可能让角色获得当期多次上场的资格。\n- 因此矩阵配队是全局分配问题：主力角色和好声骸要在十几支队伍间统筹，不能按\"每队独立最优\"来排。当期可多次上场的角色名单以游戏内为准。\n- 目标不用问：矩阵默认奔着总分最高去，\"少队精打\"还是\"多队铺开\"是由练度和当期规则算出来的手段，不是要用户选的偏好。用户主动说了别的目标（如省时间）才改。\n- 当期特殊规则（本期 boss 及属性/抗性、可多次上场角色名单、当期增幅侧重）**没有接口可查**：矩阵接口只回个人战绩，wiki 活动说明也只有时间和开放条件。用户没打新一期时，直接说明\"这些要你从游戏里带出来\"，并把要问的内容一次列全，别拆成多轮追问。"}