poi-plugin-compass 0.1.0

package/docs/research.md

@@ -0,0 +1,445 @@
+# 罗盘插件调研笔记
+
+## 1. 目标与假设
+
+目标是为指定舰队（默认第一舰队）回答四类问题：
+
+1. 这张图每个节点可能往哪里走，当前舰队满足哪些带路条件。
+2. 在当前分歧规则下，每条边的局部条件概率和从起点传播后的全局到达概率是多少。
+3. 每个节点会遇到什么敌舰编成，敌方制空和当前舰队制空关系如何。
+4. 能否把当前舰队、当前路径和节点敌编成导出到 noro6 / KC3Kai 等外部工具。
+
+默认假设：插件是信息展示和计算工具，不自动替用户出击或点击路线；外部网站不可用时，已经缓存的数据仍然可以工作。
+
+## 2. 关键结论
+
+### 2.1 需要“规则引擎”，不是简单查表
+
+路线分歧并不只有舰种数量。日文 Wiki 的路线分歧总页明确列出以下条件类别：
+
+- 艦种、特定舰和史实舰；
+- 艦队数量、旗舰类型；
+- 索敌分数和分歧点系数；
+- 航速、装备数量；
+- 联合舰队类型；
+- 已经过的节点、地图机关、札、血条、难度和出击舰队枠。
+
+而且条件通常按页面顺序优先匹配；游戏是在按下进击按钮时依据当时状态给出路线。因此同一地图不能只保存“舰种组合 -> 目的地”，必须保存有优先级的规则序列，并在求值时保存“当前已经过的节点、当前舰队状态、地图阶段”等上下文。
+
+### 2.2 概率必须分层表达
+
+应同时保存三种不同含义的数字：
+
+- `ruleProbability`：规则明确给出的固定/偏向/随机概率；例如 Wiki 写明 80%/20%。
+- `observedProbability`：TsunDB/KCNav 等出击样本按条件筛选后的统计比例。
+- `reachProbability`：从起点概率质量传播到该节点或该边的结果。
+
+三者不能混成一个数字。规则缺失或舰队条件未知时，UI 显示 `unknown`；仅当非能动分歧出口存在但没有可靠概率时，才将出口按均等概率处理并加 `?`。能动分歧没有手动方向且没有可用 phase 默认规则时暂停概率传播并提示用户选择，不擅自采用统计结果替代规则结果。统计样本可以作为辅助提示，例如“规则未收录，近 N 次样本为……”，但必须显示样本量和过滤条件。
+
+### 2.3 最小可行架构：离线规范数据 + poi 实时状态
+
+推荐的运行边界：
+
+```text
+中文 Wiki / 日文 Wiki / NGA 人工复核 / TsunKit API
+                 │  建构期抓取、人工审阅、保留 sourceRefs
+                 ▼
+       normalized maps / rules / enemy-comps
+                 │  插件运行时只读
+                 ├── poi fcd.map + poi const/info state
+                 └── UI + probability engine + external exporters
+```
+
+不建议把网页 HTML 解析和运行时请求直接放进插件：NGA 当前直接访问就会返回 403，Wiki 页面格式也会变化，TsunKit API 也可能暂时不可用。将网络访问限制在显式的刷新脚本，并把源版本、抓取时间、响应 hash 和未解决项写入数据清单，更容易回归和人工复核。
+
+## 3. poi 本地数据和事件路径
+
+### 3.1 地图几何
+
+当前 checkout 的 `assets/data/fcd/map.json` 是单行 JSON，已检查到：
+
+- `meta.name = "map"`；
+- `meta.version = "2026/07/28/02"`；
+- `data` 有 136 个海图键；
+- 以 `1-1` 为例：`route` 是数字 cell 编号到 `[from, to]` 的映射，`spots` 是节点到 `[x, y, kind]`；
+- 以 `2-5` 为例，几何包含合流/分流的所有边，并保留每条边的数字编号。
+
+现有 `custom-plugins/poi-plugin-data-uploader/index.js` 已使用同一结构：
+
+```js
+const mapKey = `${Math.floor(mapId / 10)}-${mapId % 10}`
+const label = maps?.[mapKey]?.route?.[Number(cell)]?.[1]
+```
+
+因此第一版不需要重新下载地图坐标。插件运行时从 poi store 读取 `fcd.map`；该结构缺失时地图几何标为不可用，不从其他来源静默替代。
+
+### 3.2 当前舰队和 master ID
+
+现有插件代码已经验证了下面这组运行时输入足以组装计算行：
+
+- `info.fleets`：舰队槽位及 `api_ship` roster ID；
+- `info.ships`：舰娘实例、`api_ship_id`、HP、装备实例、当前搭载量、改修/熟练度；
+- `info.equips`：装备实例；
+- `const.$ships` / `const.$equips`：舰娘和装备 master 数据；
+- `const.$shipTypes`：舰种展示数据；
+- `info.basic.api_level`：司令部等级；
+- `sortie.combinedFlag`、`sortie.sortieMapId`、`sortie.currentNode`：当前出击上下文（字段的可用性需以当前 poi 版本实测为准）。
+
+索敌值已在当前 poi 源码中确认：`views/utils/game-utils.ts` 的 `getSaku33` 返回 `{ ship, item, teitoku, total }`，分别对应舰船项、装备项、提督等级惩罚和总值。插件运行时组装与 poi `fleet-stat` 相同的 `[舰船实例, 舰船 master]` 和装备数据并调用该函数：装备槽按 `api_slotnum` 截断，保留 `api_slot_ex` 作为最后一槽，并把 `api_onslot` 与补强槽的 0 传入；出击中已护卫舰也按 poi selector 规则排除。插件分别以 `mapModifier = 1/2/3/4` 调用 poi，顶部显示四个 `total` 值；地图规则用 `data/los-config.json` 选择对应的分歧点系数。master、装备、提督等级或任一 33 式结果缺失时直接报告 poi 数据不可用，不使用本地公式替代。
+
+根据当前提供的通常图表格，已记录的索敌分歧点系数 / 司令部系数为：1-6 `3/0.35`、2-5 `1/0.4`、3-5 `4/0.35`、4-5 `2/0.35`、5-2 `2/0.35`、5-4 `2/0.35`、5-5 `2/0.35`、5-6 `4/0.4?`、6-1 `4/0.35`、6-2 `3/0.35`、6-3 `3/0.35`、6-5 `3/0.4?`、7-2 `4/0.4`、7-4 `4/0.35`、7-5 `4/0.35`。5-6 的 KCWiki 页面明确给出分歧点系数 4，并说明页面索敌线按 120 级司令部记录，低于 120 级时建议额外提高 1，因此司令部系数暂标为近似。其余通常图在该表中没有索敌分歧线，配置记为不适用；这不代表可以把它们的系数猜成 1 或 0.4。
+
+所有规则求值都应基于 master ID、舰种 ID、装备 type2、速度值和当前实例数据；名称只用于显示和 source note。敌舰也用敌舰 master ID，不用翻译后的名字作为身份。
+
+当前实现还把装备 type2=12/13（poi 的小型/大型电探）归入 `radar` 舰数，用于 3-2 等通常图。poi 的 `getFleetSpeed` 从舰娘实例的 `api_soku` 取舰队最低速力；该实例字段就是 poi 舰队页展示的有效速力，插件据此区分普通高速、高速+和最速。
+
+规则引擎另外支持 `containsName` / `nameCount`，用于长门、陆奥、秋津洲、如月以及 7-3 的史实舰组合。这里的名称只作为当前 poi master 数据的匹配键，实际舰队对象仍保留 master ID。地图阶段通过手动 phase 选择传入上下文；7-3 一期/二期使用 `flag` 条件表达，其他多阶段图仍需继续拆分来源规则。
+
+出击路径会在插件状态中记录已经经过的节点，并通过 `visited` 条件支持 4-5 的“经过 E/F 点”规则。路径历史只用于当前出击过程，不写回游戏状态。
+
+### 3.3 事件监听
+
+现有 sibling plugin 使用 `window.addEventListener('game.response', ...)`，按 `event.detail.path` 分派：
+
+- `/kcsapi/api_req_map/start`：出击开始，响应里有 `api_maparea_id`、`api_mapinfo_no`、`api_cell_data`；
+- `/kcsapi/api_req_map/next`：前进到下一节点；
+- `/kcsapi/api_req_sortie/battleresult` 和 combined battle 对应路径：战斗结果/血条信息；
+- `game.response` 之后节流刷新 UI，避免每个 API 回包都触发完整渲染。
+
+罗盘第一版至少要监听 `api_req_map/start` 和 `api_req_map/next`，才能把“当前节点”和“用户选择/实际路线”同步到图上；不应在出击前假设舰队状态一直不变。
+
+## 4. 各数据源的具体研究
+
+### 4.1 中文 Wiki
+
+`https://zh.kcwiki.cn/wiki/1-1` 可直接读取，页面展示了：海域基本信息、路线分支表、舰种缩写定义、概率数值、索敌说明和原始 NGA 引用。
+
+`2-5` 页面更能说明数据复杂度：同一分歧点同时存在潜艇/舰种/运输桶/航速/索敌条件，且有固定、随机和“约”三种语义。页面还给出路线示例、索敌阈值和制空线。这个页面适合作为第一批规则 fixture，但不能把攻略文案直接当作机器规则。
+
+建议建构器只抽取明确的结构化候选，保留原文：
+
+```json
+{
+  "node": "G",
+  "priority": 30,
+  "predicate": { "kind": "los33", "coefficient": 1, "min": 41 },
+  "outcomes": [{ "to": "L", "probability": 1 }],
+  "sourceRefs": [{ "url": "...", "quote": "...", "checkedAt": "..." }],
+  "confidence": "verified"
+}
+```
+
+无法确定“约 80%”是否为长期规则、样本估计还是攻略近似时，应使用 `approximate` 或 `unknown`，并把原文保留到审阅队列。
+
+本轮已将通常海域 36 张 `/{带路条件}` 子页以及 5-6 主页面的原始 wikitext 缓存到 `data/sources/kcwiki/routes/`，并在 `manifest.json` 中记录 revision ID、修订时间和 SHA-256。规则校正以这批缓存为审阅入口：`CV系`/`CV*` 归入 `CV_ALL`，明确的 `CV+CVB` 归入 `CV_MAIN`；`CL系`、`CL+CT`、`BB系` 和单独 `BB` 也分别使用不同令牌，避免把 CVL、CT 或 BBV 静默漏掉或误计入。
+
+### 4.2 日文 Wiki
+
+`出撃` 总页列出通常海域并通过子页面链接到各海域；`ルート分岐` 总页提供路线条件分类、索敌公式和“梦美的常规图带路 & 出击配置”等交叉来源入口。
+
+它适合：
+
+- 查找中文页面没有同步的条件；
+- 统一日文舰种/装备术语；
+- 复核条件优先级、索敌公式和特殊地图状态。
+
+它不适合被当作单一真相：页面自己也建议多来源检查，而且有些条件只以攻略/讨论形式出现。解析器应保留 `raw` 和页面标题，而不是只保存最终中文文案。
+
+### 4.3 NGA：浏览器会话是可行的采集边界
+
+本次调研验证了用户的判断：直接 HTTP 请求仍返回 403，网页检索也不能稳定打开带查询串的页面；但在已经登录 NGA 的 Firefox 会话中，用户给出的主帖第 2～5 页和关联帖可以正常读取。因此“命令行抓取失败”不能作为“资料不可用”的结论，但也不适合把 NGA 变成插件运行时依赖。
+
+浏览器读取到的内容特征：
+
+- 主帖第 2 页包含 1-1、1-2、1-3、1-4、2-4、2-5 的路线说明、分歧条件、敌舰行、制空线和攻略注释；第 3～5 页继续覆盖 3-1 至 7-5。帖文是人工维护的半结构化 BBCode，不是稳定 JSON。
+- 2-5 的示例同时出现舰种/数量、全高速、索敌阈值、装备类别和低速等条件，说明它可以提供很有价值的规则原文，但解析器不能只依赖一个固定表格列。
+- 关联帖标题为“地图配置2.0”。第 1 页可见按海域/节点拆分的回复，例如 `pid=330412919` 的 1-1 敌方配置；回复中包含 `[table]`、`[dict]`、`[collapse]`，并给出敌舰 master ID、装备、阵型、经验值及制空劣势/均势/优势/确保门槛。主帖中的“敌方配置”链接会指向这些 PID。
+- 页面会显示帖子修改时间；主帖较新的页面和关联帖早期回帖混在一起，因此同一规则可能需要以 `tid`、`page`、`pid` 和帖子时间区分版本。
+
+建议的 NGA 工作流：
+
+1. 用户在已登录浏览器中打开指定页面，插件或辅助工具接收用户明确复制的 BBCode/纯文本；不在出击运行时自动访问 NGA。
+2. 预处理器先按 `[collapse]`、`[table]`、`[dict]`、`===地图/节点===` 分段，保留无法识别的原文。
+3. 将路线候选、敌编成和制空门槛写入待审阅规范数据；每条记录保存 `sourceRef = { tid, page, pid, url, fetchedAt }`，并由人工确认后才成为 `verified`。
+4. 若主帖只给出路线而敌舰细节来自关联帖，两个 PID 都写入同一条规范记录；不能只保留主帖 URL。
+
+这种设计既利用浏览器会话可以读取 NGA 的事实，也把登录状态、页面布局变化和帖子修改造成的不确定性隔离在建构期。不要增加绕过验证、代理或高频访问逻辑。
+
+### 4.4 TsunKit API
+
+当前实际请求到的地图 API（`2-5`）形状如下：
+
+```text
+GET /api/routing/maps/2-5/
+result.route: { cellNo: [from, to, ...] }
+result.spots: { nodeLabel: [x, y, kind] }
+result.mapSet: { map, frameSet, breakpoints }
+```
+
+敌编成 API（`2-5/O`）形状如下：
+
+```text
+GET /api/routing/maps/2-5/nodes/O/enemycomps/
+result.entryCount
+result.entries[]:
+  map, node, mainFleet, escortFleet, formation,
+  count, airpower, lbasAirpower,
+  uncertainAirpowerItems, masterId
+```
+
+`mainFleet` 的每艘敌舰包含 `id`、名字、等级、HP/火力/对空/装甲和 `equips` master ID。`masterId` 是整套编成的标识，`count` 可用于统计权重。
+
+调研中观察到 `airpower` 是四个制空门槛的数组，例如 `[10, 19, 42, 84]`；`lbasAirpower` 是另一组带陆航语义的门槛。实现时必须用已知敌编成手算值和 Wiki 表格建立映射测试，确认数组顺序后再显示中文档位。`uncertainAirpowerItems` 非空时，制空结论应降低置信度。
+
+推荐数据策略：
+
+1. TsunKit 的 `entries` 作为敌编成和敌方制空的优先来源；
+2. 用 `mainFleet[].id` / `equips` 保存可重算依据；
+3. Wiki 的敌编成/制空值用来交叉核对和补齐缺项；
+4. 未知或冲突的值同时保留 `sourceValues`，不静默覆盖。
+
+### 4.5 地图图像
+
+poi `fcd.map` 已有可用的节点坐标和边信息，仍作为路线绘制和数据可用性的主来源。进一步检查 TsunKit KCNav 前端后确认：地图背景使用 `https://tsunkit.net/api/assets/images/maps/{mapId}/background`；路线 API 的 `result.route[cell]` 第三个值是节点类型编号；KCNav 前端用该编号推导每个节点的 `nodeType`，再从 `map_main/{icon}` 或 `map_common/{icon}` 加载图标。
+
+插件沿用 KCNav 的节点类型表，把起点、Boss、运输、航空战、空袭、夜战、修理、能动分歧等类型映射到地图主图标和公共图标。由于路线 API 在连续请求时可能返回 `401 Unauthorized API automation detected`，当前实现把 37 张通常图背景提前转为质量 85 的 WebP，并把节点图标提前下载到 `assets/kcnav/`，运行时完全使用本地 `file://` 资源，不再请求远程；当前节点图标暂不渲染，仅保留样式数据。37 张通常图的地图 API 原始响应另缓存到 `data/sources/kcnav/maps/`，并从每条 `route` 的第三项生成各图节点类型表；只有缓存缺失的地图才会保留圆形节点和字母。
+
+## 5. 规范数据模型建议
+
+### 5.1 地图、边和节点
+
+```ts
+type MapId = string // "2-5"
+type NodeLabel = string // "O"
+
+interface CompassMap {
+  mapId: MapId
+  sourceSnapshot: SourceSnapshot
+  nodes: Record<NodeLabel, {
+    x: number
+    y: number
+    kind: 'start' | 'battle' | 'air' | 'resource' | 'boss' | 'unknown'
+    sourceRefs: SourceRef[]
+  }>
+  edges: Array<{
+    id: string
+    cellNo: number
+    from: NodeLabel | null
+    to: NodeLabel
+    sourceRefs: SourceRef[]
+  }>
+  rules: RouteRule[]
+}
+```
+
+边的 `cellNo` 必须保留，因为 poi API 的数字节点和实际地图字母节点都需要互相定位。
+
+### 5.2 带路规则
+
+规则建议采用小型 AST，不把自然语言直接拼成 JavaScript：
+
+```ts
+interface RouteRule {
+  node: NodeLabel
+  priority: number
+  predicate: Predicate
+  outcomes: Array<{
+    to: NodeLabel
+    probability: number | 'unknown'
+  }>
+  appliesWhen?: { difficulty?: string; gauge?: number; phase?: number }
+  sourceRefs: SourceRef[]
+  confidence: 'exact' | 'verified' | 'parsed' | 'approximate' | 'unknown'
+  raw?: string
+  unresolved?: string[]
+}
+```
+
+初始 predicate 集合只实现当前需求需要的部分：舰种/特定 master ID 计数、舰队数量、旗舰、速度、装备类别/数量、33 式索敌、联合舰队类型、已经过节点、地图阶段/难度/血条。没有匹配的表达式返回 `unknown`，不执行猜测。
+
+### 5.3 敌编成
+
+```ts
+interface EnemyComposition {
+  mapId: MapId
+  node: NodeLabel
+  masterId: number
+  count: number
+  formation: number
+  mainFleet: Array<{ masterId: number; equipMasterIds: number[]; stats?: object }>
+  escortFleet: Array<{ masterId: number; equipMasterIds: number[]; stats?: object }>
+  airpower?: {
+    source: 'tsunkit' | 'computed' | 'wiki' | 'unknown'
+    thresholds?: [number, number, number, number]
+    uncertainItems?: number[]
+  }
+  sourceRefs: SourceRef[]
+}
+```
+
+名称、舰种翻译和图标均是 presentation 层派生值。`masterId`、装备 ID 和来源快照才是数据层身份。
+
+## 6. 概率计算设计
+
+### 6.1 规则求值
+
+在节点 `N`：
+
+1. 按 `priority` 排序；
+2. 依次求值规则的 predicate；
+3. 取第一个确定匹配的规则；
+4. 若匹配规则产生多个出口，使用其明确权重；
+5. 若没有规则或规则含未知状态，返回 `unknown` 并附上原因。
+
+这里的“第一个”不是实现者猜测的优先级，而必须来自页面表格顺序或人工标注的 `priority`。
+
+### 6.2 概率质量传播
+
+从起点注入 `mass = 1`：
+
+```text
+reach(from) = incoming mass
+edgeMass(from -> to) = reach(from) × localProbability(from -> to)
+reach(to) += edgeMass(from -> to)
+```
+
+UI 同时显示：
+
+- 当前节点的到达率 `reachProbability`；
+- 当前边的局部概率 `localProbability`；
+- 当前边承载的全局概率 `edgeMass`。
+
+图中若有合流节点，应按路径状态合并“只读的可交换上下文”；若规则依赖曾经经过的节点或阶段，则保留路径上下文，不能只按节点字符串去重。对非能动分歧中完全没有可靠概率的出口，按均等概率传播并把不确定性沿全局路径传递，在概率后附加 `?`；能动分歧则要求手动方向或使用命中的 phase 默认规则。真正无法求值的舰队条件仍显示未知，不与概率估算混淆。
+
+### 6.3 能动分歧
+
+2026-09-11 全通常图拓扑复查：以本地 KCNav 响应交叉检查规则出口、遗漏续航和 Boss 类型。修正 2-4 的 A/D 为终点（E→D），7-5 的 M 为终点，补充 5-6 H→R 和 5-2 出发点其余编成→B。4-5 K 的随机去 M 条件此前误写 K→N，现按索敌 <60、60～70、≥70 分别列 M/L、M/T/L、M/T，未知分布均分并标记问号。6-1、6-2、7-1 Boss 为 K，5-1 为 J；1-6 没有 Boss。7-4 J 的缓存类型为 4，KCWiki 也说明该点发生含潜艇的战斗，保留该类型。
+
+明确终点规则使用 `terminal: true`，避免与 `outcomes: []` 的“规则未收录”混淆；存在分歧规则却没有命中时仍为未知。测试覆盖全部规则的实际出口和显式终点，仅排除 6-4/6-5 用于选择起点的虚拟 1→2 转移。节点颜色以 KCNav 缓存类型为准，旧 Boss 字段不覆盖已知类型；圆形节点不应用图片位置偏移，航空战圆半径与空袭一致为 15。基础路径为 4px 蓝色线，透明度 0.85。
+
+用户选择能动分歧后，对该节点加入临时 `manualOverride`：
+
+当前通常海域已核对的能动分歧点为：4-5（A、C、I）、5-3（O）、5-5（F）、6-3（A）、7-4（F）、7-5（F、H、O）。7-5 的 F/H/O 分别对应 G/J、I/K、P/Q 两个出口；有 phase 规则时先采用命中的 phase 默认出口，用户手动选择后再覆盖；没有 phase 默认规则的能动点必须由用户指定方向，不再默认均分。
+
+- 选中的边：`localProbability = 1`；
+- 其他边：`localProbability = 0`；
+- 原始规则概率保留，UI 以“手动选择覆盖”标识；
+- 下游所有 `reachProbability` 重新计算；
+- 到达实际游戏节点后，应清除已经经过节点的旧 override，避免跨出击污染。
+
+如果游戏里的分歧不是能动分歧，UI 只能展示规则，不应提供“选择路线”按钮。
+
+## 7. 制空实现建议
+
+### 7.1 当前舰队
+
+现有 `poi-plugin-sortie-checker` 的纯计算模块已经给出可复用的验证方向：
+
+- 按装备 type2 识别舰战、爆战、舰爆、舰攻、水战、水爆和喷式机；
+- 单格制空大致为 `floor((对空 + 改修补正) * sqrt(当前搭载) + 熟练度加成)`；
+- 舰战/水战/喷式战和水爆的熟练度加成不同；
+- `api_onslot` 必须取当前搭载，不应使用 master 最大搭载；
+- 扩张槽装备不贡献搭载制空，但应按游戏规则处理其对空效果。
+
+在本插件中应把公式移到独立纯函数，并用已知编成测试；不要把 HKGY 插件的 UI 或静态 mapdata 当成运行时依赖。
+
+### 7.2 敌方制空
+
+优先顺序：
+
+1. TsunKit 的 `airpower`/`lbasAirpower` 门槛数组；
+2. 有完整敌舰装备和 slot 数据时，按 master 数据重新计算；
+3. Wiki 明确列出的敌制空值；
+4. 否则显示“未知”。
+
+若多个来源冲突，显示来源对照和置信度，不直接取最大值掩盖冲突。`uncertainAirpowerItems` 出现时，制空档位可以显示，但必须带“装备不确定”提示。
+
+## 8. 外部模拟器链接
+
+### 8.1 KC3Kai：优先实现
+
+KC3Kai 的 import help 明确支持：
+
+- URL fragment 中直接放 JSON；
+- `fleetF.ships[]` 使用玩家舰船 master ID、等级、状态和 `equips[]`；
+- `nodes[]` 可放单个 `fleetE` 或带 `weight` 的 `fleetEComps`；
+- 每个节点可以指定 formation、夜战、空袭等行为。
+
+因此第一版 exporter 可以把“当前舰队 + 当前预测路径上的每个节点的一组敌编成”生成 JSON。TsunKit `count` 可转换为敌编成权重，但应标记为“样本权重”，不能表示官方概率。
+
+风险是 URL 长度和 simulator 对新 master ID 的支持。如果 simulator 数据库没有某个 master ID，import help 要求同时提供 stats；插件应捕获这个情况并允许只导出舰队或复制 JSON。
+
+2026-09-11 重新核对已部署的 `js/simulator-ui/ui-main.js`：URL hash 中的 `{ fleetF, nodes }` 会调用 `initSimImport`，直接执行 `SIM.runStats`，并非仅填充编辑界面。若按钮语义是“打开编辑”，应使用其 `#backup=`（LZMA + Base64）存档导入流程，或先验证其他编辑导入路径。`convert.js` 确认 `fleetEComps[].weight`、`NBOnly`、`airOnly`、`airRaid` 等字段。需要保留补给消耗、夜战和我方阵型的准确含义。
+
+### 8.2 noro6：DeckBuilder 可导入出击信息
+
+我方裸值来源修正：ship-info 无装备模式确实从 WCTF 成长数据计算，但本机及 npm 最新 WCTF 均为 20240308.0.1，缺少 #736 榧改等新舰，故最终移除该依赖。KC3Kai `FLEET_MODEL.getDefaultShip` 在传入等级时按 EVbase/EV、ASWbase/ASW、LOSbase/LOS 推算裸值，备份导入仅覆盖实际提供的字段，因此省略 EV/LOS 与未改修 ASW。对潜改修不能从等级推断，使用本地 `data/kc3kai-ship-stats.json` 成长快照补入；noro6 的 `convert.ts` 用 `s.asw`（总面板）反推出额外改修，因此保留 poi 实例总对潜。火雷空甲/运/耐久保留真实状态，敌方不删 KCNav 数据。已回归验证没有 WCTF 时 #736 可导出、175 级对潜改修、正常成长字段省略；不新增任何插件运行时远程数据库请求。
+
+2026-09-11 核对 [App.vue](https://github.com/noro6/kc-web/blob/main/src/App.vue) 与 [convert.ts](https://github.com/noro6/kc-web/blob/main/src/classes/convert.ts)：支持 `?predeck=<encodeURIComponent(JSON)>`，DeckBuilder v4 除玩家舰队之外还支持 `s: { a: 海域编号, i: 海图编号, c: 节点列表 }`，每个节点使用 `{ c: 数字cell, pf: 我方阵型, ef: 敌方阵型, f1: { s: 敌舰列表 }, f2?: { s: 护卫敌舰列表 } }`。节点数字 cell 应从当前选定路线的 KCNav/poi 边映射取得。
+
+限制：当前 `loadDeckBuilder` 按敌舰 master ID 调用 `Enemy.createEnemyFromMasterId`，没有读取敌舰 `items`；同一 master ID 的不同装备/属性配置不能通过这条路径精确保留。此外每个节点只接受一套敌编成，没有 `fleetEComps` 权重列表。第一版建议由玩家选择敌编成（可预选样本最多的一组），明确使用目标站默认敌舰数据；若要求忠实传递装备变体，再验证其内部 SaveData 导入格式。
+
+两者都导出一条具体路线，不把所有有非零概率的节点串成一条路线。当前 `exporters.js` 按路径历史逐分歧求值，排除零概率边，并在导出面板提供完整路线选择；默认优先当前阶段 Boss，再按概率排序。未选择的能动分歧列出候选但不显示伪造概率，命中的 phase 默认规则仍适用。noro6 每节点默认样本最多的一套，可单独修改；我方阵型亦可调整。
+
+2026-09-11 实施与验证：KC3Kai 采用 v2 `#backup=`，已在浏览器用合成舰队确认编辑界面恢复两套敌编成及 90%/10% 权重，没有自动运行模拟。源码 `ui-main.js` 限 9 战、每节点 12 编成，导出超限直接提示，不截断。master ID 快照用于拦截目标站不支持的舰娘/装备。noro6 浏览器确认恢复合成睦月 Lv50、改修装备、1-4 L 点和複縦陣；`f1.t=0` 必须用于通常舰队，`t=1` 会错误变成空母机动部队。noro6 导入页面会自行计算。单测覆盖链接编解码、补强槽/空槽、编成选择、phase 默认、能动候选和航空/夜战映射；尚未验证真实 poi 舰队端到端及完整多战航空损耗。陆航、支援和漩涡损耗不在本次导出范围。
+
+## 9. 分阶段实施计划
+
+### P0：研究仓库和样本（已完成）
+
+- 保存来源、访问结果、许可/署名注意事项；
+- 固定 `1-1`、`2-5`、至少一张含索敌和随机分歧的 fixture；
+- 定义 normalized schema、置信度和 unknown 语义。
+
+当前实现已在独立 `poi-plugin-compass` 仓库中落地规则 AST、来源引用、置信度和未知结果语义；首批 fixture 为 1-1、1-2、1-3、1-4、2-1、2-5 与 3-1。
+
+### P1：离线通常海域 MVP（进行中）
+
+- 从 poi store 读取第一舰队和 master 数据；
+- 使用 `fcd.map` 画节点/边；
+- 手工审阅并录入少量路线 AST；
+- 展示每个节点所有规则、当前匹配状态和路线质量传播；
+- 支持能动分歧 override；
+- 不接运行时网络，不复制第三方地图图片。
+
+已完成：CommonJS poi 插件壳、全部通常海域地图目录与 SVG 几何、第一舰队状态读取、1-1/1-2/1-3/1-4/2-1/2-5/3-1 规则样本、局部/全局概率传播、手动覆盖引擎，以及直接复用 poi `getSaku33` 的 33 式索敌读取。
+未完成：其余通常海域规则、敌编成/制空数据面板和联合舰队状态。
+
+### P2：敌编成和制空
+
+- 增加 TsunKit refresh 脚本、原始响应摘要、source hash 和 normalized cache；
+- 将敌舰/装备统一到 master ID；
+- 接入制空纯函数和 TsunKit 门槛数组；
+- 显示 `unknown`、`uncertain` 和来源冲突。
+
+### P3：活动图和人工来源
+
+- 加入难度、血条、阶段、札和已开点状态；
+- 为 NGA 文本提供人工导入审阅格式；
+- 活动图规则默认只展示已验证项，未验证项不参与自动概率传播。
+
+### P4：外部工具
+
+- 先实现 KC3Kai JSON fragment exporter；
+- 再做 noro6 manager JSON POC；
+- 增加 URL 长度检查、复制 JSON 备用按钮和外部版本兼容提示。
+
+## 10. 验收和测试边界
+
+- 单元测试：predicate 求值、规则优先级、固定/加权出口、unknown、概率质量和 manual override；
+- fixture 测试：1-1 的舰数随机分歧、2-5 的舰种/桶/速度/索敌组合；
+- 敌编成测试：TsunKit `mainFleet` 的 master ID 保持不变，`count` 权重不被误当成官方概率；
+- 制空测试：至少一组无空母、一组含舰载机、一组 `uncertainAirpowerItems`；
+- exporter 测试：KC3Kai JSON 能被 import-help schema 接受，Noro6 `?data=` 在浏览器中能恢复最小 fixture；
+- 运行时验证：poi 重载插件后切换编成、装备、联合舰队和实际推进节点，确认图和计算刷新；
+- 不把完整 poi 根目录 sweep 作为验收门槛。未来有运行时代码时，遵循 `custom-plugins` sibling plugin 的最小测试边界。
+
+## 11. 主要风险
+
+1. **规则漂移**：Wiki、NGA 帖子、TsunDB 统计和游戏实装可能不同。必须保留 sourceRefs、时间和置信度。
+2. **网络依赖**：NGA 已验证存在直接访问阻断；所有外部来源都应可脱网运行。
+3. **统计误读**：TsunKit 的 `count` 是样本数，不能直接改成规则概率。
+4. **门槛数组误读**：TsunKit 的 `airpower` 需要 fixture 验证四个元素的顺序；在确认前不应硬编码中文档位。
+5. **资源许可**：中文 Wiki 条款要求 BY-NC-SA；NGA、日文 Wiki、TsunKit 图像许可未确认。MVP 不复制图片和大段原文。
+6. **外部链接失效**：noro6/KC3Kai 的 URL 数据结构和 master 数据库会更新；导出器必须有版本/失败提示和复制原始 JSON 兜底。
+7. **poi 状态时序**：分歧判定使用的是进击按钮时的状态；退避、编成变化和联合舰队状态可能改变上下文，不能只依赖出击开始快照。

package/docs/sources.md

@@ -0,0 +1,85 @@
+# 来源清单与访问记录
+
+调研日期：2026-09-11（Asia/Shanghai）。URL 中的 `{mapId}` 表示类似 `1-1`、`2-5` 或活动图编号的海域标识；`{nodeLabel}` 表示字母节点。
+
+## 用户指定来源
+
+| 来源 | 用途 | 当前访问结果 | 计划角色 |
+| --- | --- | --- | --- |
+| [poi 内置 `assets/data/fcd/map.json`](https://github.com/poooi/poi/blob/master/assets/data/fcd/map.json) | 地图坐标、边、数字节点和字母节点 | 当前 checkout 已有本地快照 | 运行时地图几何主来源 |
+| [中文 Wiki 海域页](https://zh.kcwiki.cn/wiki/1-1) | 中文海域名、带路表、敌编成说明、制空和攻略注释 | 可访问；页面将条件表和来源链接一起展示 | 建构时规则/说明来源，保留来源引用 |
+| [日文 Wiki 出击总表](https://wikiwiki.jp/kancolle/%E5%87%BA%E6%92%83) | 海域列表及子页面入口 | 可访问；总表下含通常海域子页面入口 | 子页面发现入口，不直接作为唯一规则源 |
+| [日文 Wiki 路线分歧](https://wikiwiki.jp/kancolle/%E3%83%AB%E3%83%BC%E3%83%88%E5%88%86%E5%B2%90) | 带路条件语义、优先级、索敌公式、舰种/航速/装备等条件 | 可访问；明确说明进击时状态、条件优先级和未知因素 | 规则 DSL 设计和人工核对参考 |
+| [NGA 梦美帖第 2 页](https://bbs.nga.cn/read.php?tid=23451223&authorid=39227030&opt=262144&noBBCode&page=2) 至 [第 5 页](https://bbs.nga.cn/read.php?tid=23451223&authorid=39227030&opt=262144&noBBCode&page=5) | 常规海域带路和敌舰配置 | 直接 HTTP 仍返回 403；但在 Firefox 登录会话中已成功读取第 2～5 页 | 浏览器人工采集/复核来源；不得把网页访问器做成运行时高频依赖 |
+| [NGA 关联回复帖](https://bbs.nga.cn/read.php?tid=16820397&authorid=39227030&opt=262144&noBBCode) | 被上述带路和敌舰配置引用的回复 | Firefox 登录会话可读取；主题为“地图配置2.0”，第 1 页可见按地图/节点拆分的敌编成表、master ID、装备和制空门槛 | 浏览器人工采集/复核来源；以 `tid/page/pid` 建立可追溯引用 |
+| [TsunKit 地图 API](https://tsunkit.net/api/routing/maps/{mapId}/) | 路由、节点坐标、mapSet 素材元数据 | 当前调研用 `1-1`、`2-5` 请求成功；末尾 `/` 更稳定 | 建构时地图补充/校验，必要时缓存原始响应 |
+| [TsunKit 敌编成 API](https://tsunkit.net/api/routing/maps/{mapId}/nodes/{nodeLabel}/enemycomps/) | 敌舰 master ID、装备 ID、编成出现次数、制空门槛 | 当前调研用 `2-5/O`、`2-5/C`、`2-5/I` 请求成功 | 建构时敌编成主来源，运行时读取规范缓存 |
+| [TsunKit KCNav](https://tsunkit.net/nav/{mapId}) / [地图背景接口](https://tsunkit.net/api/assets/images/maps/{mapId}/background) | 地图和其他图像资源、人工交叉检查 | KCNav 前端实际使用背景接口；通常图背景源文件返回 `image/png`，约 1200×720 | 构建期下载后转换为质量 85 的 WebP，保存到插件本地 `assets/kcnav/`；运行时不请求远程 |
+| [TsunKit 路线 API / 图标接口](https://tsunkit.net/api/routing/maps/{mapId}/) | 节点类型编号、KCNav 节点图标 | `result.route[cell][2]` 与 KCNav `getNodeTypes` 一致；图标接口返回 `image/png`；路线 API 连续请求时曾返回 `401 Unauthorized API automation detected` | 构建期来源；图标和已核对的节点类型快照保存到插件本地，运行时不请求远程 |
+
+KCNav 地图路线响应由 `scripts/cache-kcnav-maps.js` 构建期获取，默认每次请求间隔 15 秒：
+
+```text
+data/sources/kcnav/maps/{mapId}.json
+data/sources/kcnav/maps/manifest.json
+data/kcnav-node-types-by-map.json
+```
+
+其中第一项保存完整的 `GET /api/routing/maps/{mapId}/` JSON 响应；节点类型表从 `result.route[*][2]` 提取，映射到本地 KCNav 节点类型 ID。刷新命令为 `npm run cache:kcnav-maps`，如需缩短本地测试间隔可显式传入 `--interval-ms`。
+
+## 外部集成和实现参考
+
+### 敌编成日期筛选（2026-09-11）
+
+核对 `https://tsunkit.net/nav/scripts/routing.js`：`startDate`/`endDate` 分别使用参数 `start`/`end`，格式为 `YYYY-MM-DD`；`enemies` 面板将同一组筛选参数传给节点的 `enemycomps` 接口。本插件固定本轮起止日期，仅发送这两个参数，不发送司令部等级、血条、phase、舰队或路线限制。最近一个月采用当天 UTC 日期向前一个日历月（月末截到上月末日）。
+
+`https://tsunkit.net/lang/en/kcnav.json` 的 `panelEnemiesAirPowerHeader` 顺序为 `termAirAD / termAirAP / termAirAS / termAirASPlus`；与前端 `airpower[0..3]` 对应，分别为劣势、均势、优势、确保。`lbasAirpower` 使用相同顺序但单独显示。原始响应按日期窗口/海图/节点保存，manifest 记录请求 URL、SHA-256、每节点抓取时间和完成状态。遇到请求失败即停止，保留进度供重跑；运行时只读取本地缓存。
+
+每个 API entry 原样保留舰船顺序、装备、阵型及编成 masterId；舰船实体用 `mainFleet[].id` / `escortFleet[].id`。界面按 `count` 降序显示，以本节点返回记录的 count 总和计算样本占比。零样本不生成百分比；四档制空缺失时显示未知；任何编成缺制空时，节点整体范围也显示未知。混合阶段和司令部等级的占比仅描述当前抓取样本。
+
+| 来源 | 发现 |
+| --- | --- |
+| [HKGY/poi-plugin-sortie-checker](https://github.com/HKGY/poi-plugin-sortie-checker) | 已有 MIT 许可的 poi 插件，覆盖当前舰队组装、制空值、33 式索敌和静态分歧检查；可作为公式与 fixture 参考，但本插件的路线概率图和交互式路径仍需独立设计。 |
+| [noro6/kc-web](https://github.com/noro6/kc-web) | 本插件采用 `?predeck=` 的 DeckBuilder v4 导入，包含出击节点和单套敌编成；通常舰队必须 `f1.t=0`。已用合成舰队浏览器验证；敌装备使用目标站默认值。 |
+| [noro6/kc-web 当前版本/发布页](https://github.com/noro6/kc-web/releases) | 2026-09-11 调研时可见最新发布为 `2.53.5`；外部版本变动不能作为插件运行时契约。 |
+| [KC3Kai simulator import help](https://kc3kai.github.io/kancolle-replay/simulator-import-help.html) | 原始 JSON fragment 会直接运行统计；本插件采用已部署 `js/simulator-ui/ui-main.js` 和 `convert.js` 的 v2 `#backup=` LZMA/Base64 编辑入口，保留全部敌编成权重。已浏览器验证两套编成 90%/10%；限制 9 战、每节点 12 编成。 |
+| [KC3Kai replay index](https://github.com/KC3Kai/kancolle-replay/blob/master/index.html) | 目前支持 `?s=` 模拟器短数据和 `?r=` replay 数据；插件不应假设可以匿名写入短链服务。 |
+| [poi 主仓库](https://github.com/poooi/poi) | 插件生态和主仓库参考；实际运行时以当前 checkout 的 poi API 和 sibling plugin 代码为准。 |
+
+## 本地快照和可复现信息
+
+### KCWiki 路线原文缓存
+
+通常海域目录中的 37 张地图，其中文 Wiki `/{带路条件}` 子页以及 5-6 主页面的原始 wikitext 保存在：
+
+```text
+data/sources/kcwiki/routes/{mapId}.wiki
+data/sources/kcwiki/routes/manifest.json
+```
+
+缓存脚本使用 KCWiki MediaWiki API 的 `revisions` 内容接口，保留页面标题、page ID、revision ID、修订时间、抓取时间、页面 URL、API URL 和 SHA-256。刷新命令为 `npm run cache:kcwiki`；它是建构/校对步骤，插件运行时不访问 Wiki。原文缓存与规范化规则分开保存，后者仍需人工审阅后才可进入 `data/maps.json` 或 `data/normal-maps.json`。
+
+缓存内容可能受中文 Wiki 的 BY-NC-SA 条款约束，发布或分发前应继续保留来源和许可说明，并确认是否需要缩减为内部校对快照。
+
+- `assets/data/fcd/map.json`：`meta.version = 2026/07/28/02`，当前 JSON 的海图键数量为 136。
+- poi 现有 `custom-plugins/poi-plugin-data-uploader/index.js` 已验证 `fcd.map[mapKey].route[cell][1]` 可把出击 API 的数字节点映射为字母节点。
+- NGA 主帖的第 2～5 页在浏览器会话中可读，内容是按海域组织的半结构化 BBCode：路线说明、分歧条件、敌舰配置、制空线、攻略注释、图片/回帖链接混在同一帖文中；第 2 页覆盖 1-1、1-2、1-3、1-4、2-4、2-5，第 3～5 页继续覆盖 3-1 至 7-5 的常规图内容。
+- NGA 关联帖“地图配置2.0”第 1 页可见 `pid=330412919` 等按海域/节点拆分的回复；回复中直接带 `[table]`、`[dict]`、`[collapse]` 等 BBCode，并包含敌舰 master ID、装备、阵型和制空劣势/均势/优势/确保门槛。主帖链接到这些回复的 PID，因此导入时必须保存 `tid`、`page`、`pid`，而不是只保存一个主题 URL。
+- NGA 浏览器读取依赖已有登录会话；本次没有提交表单或绕过验证。TsunKit 图片资源已在构建期下载到插件本地；未来若做采集器，应优先采用用户在浏览器中触发的人工导入/复制文本流程，并为每份规范数据记录 `fetchedAt`、来源 PID、原文 hash 和人工复核状态。
+- TsunKit `GET /api/routing/maps/2-5/` 的结果顶层为 `result.route`、`result.spots`、`result.mapSet`；KCNav 前端的地图背景请求为 `GET /api/assets/images/maps/{mapId}/background`，当前 `5-3` 返回 1200×720 PNG。KCNav `flowchart.js` 的 `getNodeTypes` 使用 `result.route[cell][2]`，数值图标通过 `/api/assets/images/spritesheets/map_main/{icon}` 加载，`map_common/{icon}` 字符串则通过 `/api/assets/images/spritesheets/{icon}` 加载。
+- TsunKit `GET /api/routing/maps/2-5/nodes/O/enemycomps/` 的结果顶层为 `result.entryCount`、`result.entries`；entry 当前观察到的字段为 `map`、`node`、`mainFleet`、`escortFleet`、`formation`、`count`、`airpower`、`lbasAirpower`、`uncertainAirpowerItems`、`masterId`。
+- `airpower` 观察到类似 `[10, 19, 42, 84]` 的四档门槛数组；必须在实现时用已知 Wiki 数值写测试，确认数组顺序后再给用户显示“劣势/均衡/优势/确保”标签。
+
+## 许可、署名和数据处理
+
+- 中文 Wiki 条款要求遵守 BY-NC-SA 并尽量署名出处；若把其文字或结构化内容纳入仓库，必须保留来源、抓取时间、许可说明和修改记录，不能把这些内容包装成 MIT 数据。
+- 日文 Wiki、NGA、TsunKit 的具体内容/图片许可不能从本次调研中推断。当前已将 TsunKit 的通常图背景和 KCNav 图标复制到插件 `assets/kcnav/` 以满足离线运行；后续发布前需要补充 TsunKit 图片资源的许可/署名确认，也不把未确认的网页内容作为已验证规则发布。
+- 第三方响应原文只适合作为建构期审计材料；未来若提交仓库，需要先明确体积、许可、缓存期限和是否只保存摘要/规范化结果。
+
+## 当前通常图规则录入
+
+本轮通过中文 Wiki 的 MediaWiki API 读取各海域的 `/{带路条件}` 子页面，并把规则按地图拆入 `data/normal-maps.json`；来源页面同时保留对应 NGA 回复 PID。已录入并通过几何出边覆盖检查的地图为：
+
+`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 的路线分支直接记录在海域主页面 `南方海域/5-6`，因此缓存脚本对该图使用主页面标题，而其他通常图继续使用 `/{带路条件}` 子页。
+
+其中带有“约”“随机但未给比例”“原文带问号”或依赖分歧点系数/司令部系数的条件，使用 `approximate` 或 `unknown`；这类记录仍提供可能出口，但不产生伪造的全局百分比。后续继续补录时，先以同一 API 子页取得规则原文，再用日文 Wiki 或浏览器中的 NGA 页面复核有冲突的条件。

package/enemies.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const cacheRoot = path.join(__dirname, 'data/sources/kcnav/enemies')
+const files = new Map()
+
+function readLocalJson(file) {
+  const stat = fs.statSync(file)
+  const cached = files.get(file)
+  if (cached?.mtime === stat.mtimeMs && cached.size === stat.size) return cached.value
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'))
+  files.set(file, { mtime: stat.mtimeMs, size: stat.size, value })
+  return value
+}
+
+function thresholds(values) {
+  return Array.isArray(values) && values.length === 4
+    && values.every((value) => Number.isFinite(value) && value >= 0)
+    ? { disadvantage: values[0], parity: values[1], superiority: values[2], supremacy: values[3] }
+    : null
+}
+
+function summarizeEntries(entries) {
+  const total = entries.reduce((sum, entry) => sum + entry.count, 0)
+  const rows = entries.map((entry) => ({
+    ...entry,
+    share: total > 0 ? entry.count / total : null,
+    thresholds: thresholds(entry.airpower),
+    lbasThresholds: thresholds(entry.lbasAirpower),
+    uncertain: Boolean(entry.uncertainAirpowerItems?.length),
+  })).sort((a, b) => b.count - a.count)
+  function range(key) {
+    if (!rows.length || rows.some((row) => !row.thresholds)) return null
+    const values = rows.map((row) => row.thresholds[key])
+    return [Math.min(...values), Math.max(...values)]
+  }
+  return { rows, total, superiority: range('superiority'), supremacy: range('supremacy'), uncertain: rows.some((row) => row.uncertain) }
+}
+
+function loadEnemies(mapId, node) {
+  try {
+    const manifest = readLocalJson(path.join(cacheRoot, 'manifest.json'))
+    const source = manifest.nodes[`${mapId}/${node}`]
+    if (!source) return { status: 'missing', window: manifest.window }
+    const payload = readLocalJson(path.join(cacheRoot, source.file))
+    return { status: 'ready', window: manifest.window, source, ...summarizeEntries(payload.result.entries) }
+  } catch (error) {
+    return { status: error.code === 'ENOENT' ? 'missing' : 'invalid' }
+  }
+}
+
+const formations = { 1: '单纵', 2: '复纵', 3: '轮型', 4: '梯形', 5: '单横', 6: '警戒', 11: '第一警戒', 12: '第二警戒', 13: '第三警戒', 14: '第四警戒' }
+function formationLabel(id) { return formations[id] || `阵型 ${id}` }
+
+module.exports = { loadEnemies, summarizeEntries, thresholds, formationLabel }