poi-plugin-compass 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# poi-plugin-compass
+
+舰队罗盘插件的通常海域 MVP。
+
+当前版本已包含 poi 运行时代码、纯规则引擎和通常海域地图目录。目标功能是：针对用户选定的舰队（当前默认第一舰队），展示海图、带路条件、各分歧点的路线概率和全局路径概率，并允许在能动分歧点手动选择路线。
+
+## 当前结论
+
+- 可行，但必须先建立统一的离线规范数据层；不让 poi 运行时依赖 Wiki、NGA 或 TsunKit 的可用性。
+- poi 内置 `fcd.map` 适合作为地图几何和数字节点到字母节点的主来源。当前本地快照版本为 `2026/07/28/02`，包含 136 个海图条目。
+- 带路规则应采用“来源快照 + 规则 AST + 置信度”的结构。无法求值时显示“未知”；只有已知存在多个出口但没有可靠分配概率时才按均等概率计算，并明确标记 `?`。
+- 敌舰实体统一用 master ID；敌方制空优先使用 TsunKit 已给出的门槛数组，同时保留敌舰装备 master ID 作为可复算和审计依据。
+- 第一版先覆盖通常海域；活动图、NGA 手工复核和外部模拟器导出分开推进。
+
+## 当前实现
+
+- 罗盘订阅 poi Redux 中舰队、舰娘、装备、司令部、服务器、master、出击状态和地图数据的引用变化，换编成（包括解除全部僚舰）、换装、补给等无需点击界面即可刷新；组件卸载时解除订阅。port 响应额外清除上一趟节点/航路记录并刷新，舰队仍以 poi 更新后的 Redux 为唯一来源。顶部索敌旁显示非零舰队制空值，熟练度不确定时显示最小～最大范围。
+
+- 非零概率可到访的昼战/航空战节点下方显示制空状态：AL（丧失）、AD（劣势）、AP（均势）、AS（优势）、AS+（确保）；多种可能显示最低/最高状态，分别着色。我方制空沿用 poi `getTyku` 的熟练度最小/最大范围，敌方使用本地 KCNav 全部正样本编成的四档门槛。双方均零时不显示，夜战节点不显示；缺失或不确定敌编成影响已知结果时标记问号，完全无数据时不伪造状态。所有节点使用同一当前舰队搭载快照，未模拟沿途损耗、陆航或支援，悬停状态可查看这一限制。
+
+- 顶部可选择舰队 1～4（默认 1），同步用于舰娘头像、编成摘要、poi 索敌、带路推演及两站模拟器导出；切换会清除旧舰队的手动路线和导出选择。四组索敌以 poi 电探装备图标显示，右下角描边数字为系数 1～4，对应索敌值在各图标旁常显。海域概览数值放大并区分制空/索敌颜色；侧栏及导出面板不显示解释性段落，仅保留精简状态和错误提示。选择空舰队时明确提示数据不可用，不回退到第一舰队。
+
+- `1-1`：完整录入起点到 A 点以及按舰队数量变化的 A 点分歧概率。
+- `1-2`、`1-3`、`1-4`、`1-5`、`1-6`、`2-1`、`2-2`、`2-3`、`2-4`、`3-1`、`3-2`、`3-3`、`3-4`、`3-5`、`4-1`、`4-2`、`4-3`、`4-4`、`4-5`、`5-1`～`5-6`、`6-1`～`6-5`、`7-1`～`7-5`：已加入当前来源中的节点规则和固定边，近似概率保留 `approximate` 标记。
+- `2-5`：已录入出发点、B/C/E/F/G/I/J/L 等节点规则；索敌区间中没有可靠固定分布的部分按均等概率显示并附 `?`。
+- 当前常规图目录覆盖 1-1～1-6、2-1～2-5、3-1～3-5、4-1～4-5、5-1～5-6、6-1～6-5、7-1～7-5。5-6 使用 P1/P2/P3 phase，分别从 1、2、2 起点开始，Boss 分别为 G、N、Z。
+- 地图几何从 poi 的 `fcd.map` 读取，UI 使用 SVG 绘制节点、边、当前节点和全局到达概率；概率直接写在线段中点，边不使用箭头，已经经过的边保持最低加粗线宽，节点下方不重复显示概率或未知。
+- 舰队状态从 poi 第一舰队和 master 数据读取；顶部用 `1BB 1CL 3DD` 形式显示舰种摘要。舰种、实例舰娘的有效速力 `api_soku`、运输桶、电探、大发系、特定舰名/舰娘和 poi 的 `getSaku33` 33 式索敌可参与求值。索敌装备按 poi 的 `api_slotnum`、补强槽 `api_slot_ex`、搭载量 `api_onslot` 组装，出击中已护卫舰按 poi selector 规则排除；舰队有效速力取 poi 舰队页同样使用的舰队最低速力，因此高速+／最速会计入提速装备。
+- 顶部索敌显示 poi 的四组 33 式结果 `C1/C2/C3/C4`，用 `/` 分隔；当前地图的分歧点系数和司令部系数记录在 `data/los-config.json`，并通过 hover 提示。没有索敌分歧的地图标为不适用，6-5 的司令部系数保留资料中的不确定标记。
+- poi 舰队、舰娘、装备或 33 式索敌数据不完整时，界面直接提示“poi 数据不可用”，不再执行本地索敌或其他 fallback。
+- 没有可靠概率但不是能动分歧的出口会按均等概率传播，并在受影响的局部/全局概率后显示 `?`；带有明确近似概率的分歧也会保留 `?` 标记。能动分歧在未选择时直接提示指定方向，不传播伪造的均等概率。
+- 7-2、7-3、7-5 已提供手动 phase 按钮并切换对应 boss 节点；7-2、7-3、7-5 的主要 phase 路径门已接入规则数据，细节条件仍需继续从来源数据拆分和复核。
+- 已核对并录入全部通常图能动分歧：4-5 的 A/C/I、5-3 的 O、5-5 的 F、6-3 的 A、7-4 的 F，以及 7-5 的 F/H/O。能动出口在图上可点击，也可在节点面板中选择；没有 phase 默认规则时，未选择前直接提示指定方向；7-5 等有 phase 默认规则的节点先应用当前 phase 规则，仍可手动覆盖。
+- 当前来源页面将 7-4 记为单一血条海图，暂未伪造 P1/P2 按钮；若后续来源确认存在独立阶段，再复用同一 phase 控件。
+- 规则引擎支持条件 AST、规则优先级、概率传播和手动路线覆盖；手动覆盖只影响当前推演，不修改游戏状态。
+- 界面采用窄标题栏、单行条件、状态图标/颜色和 hover popover，详细说明不占用常驻面板空间。
+- TsunKit 的 37 张通常海图背景已转换为质量 85 的 WebP，和 KCNav 节点图标一起下载到 `assets/kcnav/`；运行时不请求远程图片或路线 API。由于 KCNav 当前图片资源异常，节点图片暂时不在界面中显示。
+- 节点类型仍按 KCNav 的 `nodeTypes` 表映射到颜色和节点说明。37 张通常图的 KCNav 节点类型都已从本地 API 响应快照提取；若某张图未来缓存缺失，未知类型才显示为较小的可交互圆形节点和节点字母。
+- 中文 Wiki 的路线分歧原文已缓存到 `data/sources/kcwiki/routes/*.wiki`，`manifest.json` 同时记录页面标题、page/revision ID、修订时间、抓取时间、来源 URL 和 SHA-256。缓存是校对材料，不在运行时请求 Wiki；需要显式刷新时运行 `npm run cache:kcwiki`。
+- KCNav 地图 API 响应已提供构建期缓存脚本：`npm run cache:kcnav-maps` 会按地图逐张请求 `https://tsunkit.net/api/routing/maps/{mapId}/`，默认请求间隔 15 秒，原始 JSON 保存到 `data/sources/kcnav/maps/`，并从 `result.route[*][2]` 生成 `data/kcnav-node-types-by-map.json`。插件运行时不访问该 API。
+- 规则分类遵循来源原文：`CV系`/`CV*` 使用 `CV_ALL`（CV、CVB、CVL），明确的 `CV+CVB` 使用 `CV_MAIN`；`CL系` 使用 `CL_ALL`，明确的 `CL+CT` 使用 `CL` 与 `CT` 的组合；`BB系` 使用 `BB_ALL`，仅写 `BB` 使用 `BB`（BB/FBB）。
+
+## 本地验证
+
+节点面板支持显示本地 KCNav 敌编成、阵型、样本占比和空优/空确范围；展开可查看敌舰与装备 master ID、四档制空门槛及陆航门槛。数据只按最近一个自然月的日期范围筛选，不区分司令部等级、磨血、斩杀、血条或 phase；无样本与未缓存分别提示，未知制空不按零处理。
+
+运行 `npm run cache:kcnav-enemies` 按 15 秒间隔缓存全部可能战斗的节点，响应和清单保存在 `data/sources/kcnav/enemies/`；响应以紧凑 JSON 保存，结构和 SHA-256 校验不变。中断后重跑会保留原日期范围并跳过已校验文件；`npm run cache:kcnav-enemies -- --refresh` 显式开始刷新。运行时不请求远程接口。
+
+```sh
+npm test
+npm run check:syntax
+npm run compress:kcnav-maps
+npm run compress:kcnav-enemies
+npm run cache:kcwiki # 仅在需要更新 KCWiki 原文快照时运行
+npm run cache:kcnav-maps # 按 15 秒间隔更新 KCNav 地图快照
+```
+
+## 模拟器导出
+
+点击地图空白处取消节点选择，右侧显示地图概览（导出模式仍优先显示导出设置）。概览统计当前非零概率可到访节点的最高空优/空确，以及真正影响当前舰队分歧的最高索敌阈值、节点及地图系数；按路径历史求值，排除固定带路覆盖的索敌条件和零概率节点。未知或未指定分歧仅统计此前节点；敌编成缺缓存、无样本或装备不确定时明确标注制空统计不完整。
+
+布局为左侧地图、右侧带路条件；打开导出后右侧替换为模拟器设置，可再次点击工具栏「导出」或面板「关闭」返回。敌舰情报独立放在两栏下方，仍跟随所选节点。顶部第一舰队和敌舰列表显示圆形头像，沿用 poi 的 `getShipImgPath` 与 Avatar 裁剪参数；优先本地缓存，缺图时允许请求当前游戏服务器，并传入 shipgraph 图片版本。没有缓存且服务器信息未加载时显示 master ID。此远程访问例外仅限舰船头像，地图资源和敌编成仍使用本地数据。
+
+工具栏「导出」展开路线、我方阵型及 noro6 逐节点敌编成选择。默认优先当前阶段 Boss 路线，再按路线概率排序；未指定的能动分歧列为候选但不伪造概率，也不改变地图上的手动选择。noro6 默认选择每节点样本最多的编成；我方默认单纵，纯潜艇战单横，航空战轮形，均可修改。
+
+KC3Kai 使用 v2 备份的 LZMA/Base64 链接，保留所有敌编成样本权重；noro6 使用 v4 DeckBuilder `predeck` 链接，每节点一套敌编成。两者均携带第一舰队装备、改修、熟练度、当前搭载及补强槽；点击按钮才在外部浏览器打开，不自动操作游戏。
+
+罗盘插件不依赖 WCTF。`data/kc3kai-ship-stats.json` 缓存 KC3Kai 的 1778 个舰船条目的名称、舰种、回避/对潜/索敌成长字段及未知值标记，并记录来源、抓取时间和源文件 SHA-256。KC3Kai 导出省略我方回避、索敌，让目标站按等级推算；未对潜改修时也省略对潜。有对潜改修时使用本地 KC3Kai 成长区间计算裸值并加 `api_kyouka[6]`，缺对应成长数据时明确报错。noro6 同样不传回避/索敌，继续传 poi 的实际总对潜，由其导入器分离装备及额外强化。火雷空甲、运、耐久和装备状态仍保留，敌方 KCNav 面板不变。目标站更新后推算结果可能与本地快照略有差异；运行时不抓取这些数据库。
+
+限制：缺少本地敌编成缓存或本月无样本时不能导出。KC3Kai 限 9 战、每节点 12 套敌编成，超限会提示，不静默截断；其已知 master ID 快照记录于 `data/kc3kai-master-ids.json`，未知 ID 会阻止导出。noro6 按敌舰 master ID 使用目标站的默认装备，不采用缓存中的装备差异。未导出陆航、支援舰队或漩涡损耗，需在目标站设置。已用合成编成验证两站导入；尚未在 poi 实际舰队上做端到端验证。
+
+## 文档
+
+- [调研笔记](docs/research.md)
+- [来源清单与访问记录](docs/sources.md)
+
+## 工作边界
+
+本仓库不会自动出击、替用户点击游戏，也不会在运行时为了规则、敌编成、带路或图像信息抓取外部网站。通常海域规则目前通过 `data/maps.json` 离线维护；TsunKit 图片作为构建期下载的本地资源随插件分发。未来若加入刷新脚本，脚本应限速、保存原始响应摘要，并生成可审阅的规范数据。

package/air-status.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const states = [
+  { label: 'AL', color: '#ff8585' },
+  { label: 'AD', color: '#ffbd79' },
+  { label: 'AP', color: '#f4df8b' },
+  { label: 'AS', color: '#8fd7a3' },
+  { label: 'AS+', color: '#87d9ff' },
+]
+
+function airStateRange(air, data) {
+  if (!air || !Number.isFinite(air.min) || !Number.isFinite(air.max) || data.status !== 'ready') return null
+  const values = []
+  let uncertain = false
+  for (const row of data.rows.filter(row => row.count > 0)) {
+    if (!row.thresholds) { uncertain = true; continue }
+    uncertain ||= Boolean(row.uncertain)
+    const t = row.thresholds
+    for (const value of [air.min, air.max]) {
+      if (value === 0 && t.supremacy === 0) continue
+      values.push(value >= t.supremacy ? 4 : value >= t.superiority ? 3 : value >= t.parity ? 2 : value >= t.disadvantage ? 1 : 0)
+    }
+  }
+  if (!values.length) return null
+  return { states: [...new Set([Math.min(...values), Math.max(...values)])].map(index => states[index]), uncertain }
+}
+
+module.exports = { airStateRange }