docs: 重构调试模块说明

Author: kqcoxn

LocalBridge/internal/server/websocket.go

@@ -13,7 +13,7 @@ import (
 )
 
 // 通信协议版本
-const ProtocolVersion = "1.0.3"
+const ProtocolVersion = "1.0.4"
 
 // 版本握手路由
 const (

src/stores/configStore.ts

@@ -7,9 +7,9 @@ import { encryptApiKey } from "../utils/ai/crypto";
 export const globalConfig = {
   dev: true,
   version: `1.6.0`,
-  betaIteration: 3,
-  mfwVersion: "5.10.4",
-  protocolVersion: "1.0.3",
+  betaIteration: 4,
+  mfwVersion: "5.10.5",
+  protocolVersion: "1.0.4",
 };
 
 if (globalConfig.dev) {

src/wiki/entries/debug/prerequisites.ts

@@ -4,21 +4,22 @@ import { createModuleSearchIndex } from "../../searchHelpers";
 const module: WikiModule = {
   id: "prerequisites",
   title: "调试前置条件",
-  summary: "在点击运行前，先确认 LocalBridge、控制器、资源和截图来源是否就绪。",
+  summary:
+    "在点击运行前，先确认 LocalBridge、控制器、资源路径和截图来源是否就绪。",
   searchText:
-    "调试前置条件 LocalBridge 控制器 资源路径 截图 设备连接 调试不可用 MaaFramework 初始化",
+    "调试前置条件 LocalBridge 控制器 资源路径 截图 设备连接 调试不可用 MaaFramework 初始化 资源体检",
   steps: [
     {
-      id: "check-runtime",
-      title: "先确认本地运行时准备完成",
-      summary: "调试依赖 LocalBridge、控制器和资源，不是纯前端能力。",
+      id: "why-prerequisites",
+      title: "调试依赖本地运行时，不是纯前端能力",
+      summary: "调试需要 LocalBridge、控制器和资源三者同时就绪。",
       keywords: ["LocalBridge", "控制器", "资源路径", "MaaFramework"],
       searchText:
-        "LocalBridge 控制器 资源路径 调试前置条件 设备连接 调试不可用 MaaFramework 初始化",
+        "LocalBridge 控制器 资源路径 调试前置条件 设备连接 MaaFramework 本地运行时",
       blocks: [
         {
           type: "paragraph",
-          text: "流程调试依赖 LocalBridge、已连接的控制器，以及可被 MaaFramework 成功加载的资源。任一环节没有准备好，调试按钮就算显示出来，也不代表真正能运行。",
+          text: "FlowScope 的调试能力依赖 LocalBridge 提供的本地运行时。LocalBridge 负责与 MaaFramework 通信、管理控制器连接和资源加载。任一环节没有准备好，工作台会在顶部显示黄色警告并说明缺失项。",
         },
         {
           type: "callout",
@@ -31,7 +32,7 @@ const module: WikiModule = {
     {
       id: "checklist",
       title: "前置条件清单",
-      summary: "按顺序检查四项前置条件。",
+      summary: "按顺序检查四项前置条件，前一项未通过时后续项必然失败。",
       keywords: ["清单", "检查", "顺序"],
       searchText:
         "前置条件清单 检查顺序 LocalBridge启动 MaaFramework初始化 资源路径 Pipeline节点",
@@ -43,21 +44,35 @@ const module: WikiModule = {
         },
         {
           type: "paragraph",
-          text: "按此顺序逐项确认，前一项未通过时后续项必然失败。资源路径需要指向包含 Pipeline JSON 和图片资源的目录。",
+          text: "按此顺序逐项确认。资源路径需要指向包含 Pipeline JSON 和图片资源的目录，可以在调试配置面板中添加多个路径。",
+        },
+      ],
+    },
+    {
+      id: "resource-health",
+      title: "用资源体检面板快速定位问题",
+      summary: "资源体检面板会集中展示加载失败的具体线索。",
+      keywords: ["资源体检", "加载失败", "静态检查"],
+      searchText:
+        "资源体检 加载失败 静态检查 资源路径 resolution loading graph",
+      blocks: [
+        {
+          type: "paragraph",
+          text: "当资源加载失败时，不需要手动排查目录结构。切到资源体检面板，它会列出资源路径解析结果、加载诊断和当前图的静态检查结果，直接告诉你哪个文件或节点有问题。",
         },
       ],
     },
     {
       id: "read-unavailable",
       title: "遇到不可用先读原因，不要盲点重试",
-      summary: "工作台会明确告诉你缺的是连接、设备还是资源。",
-      keywords: ["不可用原因", "诊断", "资源预检"],
+      summary: "工作台顶部警告会明确告诉你缺的是什么。",
+      keywords: ["不可用原因", "诊断", "警告"],
       searchText:
-        "不可用原因 诊断 资源预检 设备未连接 LocalBridge 未连接 调试工作台 错误提示",
+        "不可用原因 诊断 警告 设备未连接 LocalBridge 未连接 调试工作台 错误提示",
       blocks: [
         {
           type: "paragraph",
-          text: "当工作台提示前置条件未满足时，先看描述里缺的是 LocalBridge、设备、资源，还是截图来源。按原因补齐，比反复点运行更省时间。",
+          text: "当工作台顶部出现「调试前置条件未满足」的黄色警告时，先看描述里缺的是 LocalBridge、设备、资源还是截图来源。按原因补齐，比反复点运行更省时间。",
         },
       ],
     },

src/wiki/entries/debug/runModes.ts

@@ -4,35 +4,56 @@ import { createModuleSearchIndex } from "../../searchHelpers";
 const module: WikiModule = {
   id: "run-modes",
   title: "运行方式",
-  summary: "根据问题粒度选择整图运行、从节点运行、单节点运行、仅识别或仅动作。",
+  summary:
+    "根据问题粒度选择从节点运行、单节点运行、仅识别或仅动作，把调试范围切到最小。",
   searchText:
-    "运行方式 从节点运行 单节点运行 仅识别 仅动作 固定图识别 full run run from node debug modes 完整运行",
+    "运行方式 从节点运行 单节点运行 仅识别 仅动作 回放 replay debug modes 运行模式 入口节点",
   steps: [
     {
       id: "choose-scope",
       title: "先决定你要验证的是全流程还是局部",
-      summary: "运行方式的区别，本质上是调试范围的区别。",
-      keywords: ["整图运行", "从节点运行", "单节点运行", "范围"],
+      summary: "运行方式的区别本质上是调试范围的区别。",
+      keywords: ["从节点运行", "单节点运行", "范围"],
       searchText:
-        "整图运行 从节点运行 单节点运行 调试范围 入口节点 局部验证 完整运行",
+        "从节点运行 单节点运行 调试范围 入口节点 局部验证",
       blocks: [
         {
           type: "paragraph",
-          text: "如果你怀疑的是整体流程，就从全图或入口节点开始；如果你只想验证某个节点的识别/动作行为，就直接选单节点运行、仅识别或仅动作。把范围切小，是调试闭环的核心思路。",
+          text: "如果你怀疑的是整体流程衔接，就从入口节点开始运行；如果你只想验证某个节点的识别或动作行为，就直接选单节点运行、仅识别或仅动作。把范围切小是调试闭环的核心思路。",
         },
       ],
     },
     {
-      id: "six-modes",
-      title: "六种运行方式速查",
+      id: "four-modes",
+      title: "四种运行方式速查",
       summary: "每种方式适合不同的验证目标。",
-      keywords: ["完整运行", "仅识别", "仅动作", "固定图识别"],
+      keywords: ["从节点运行", "单节点运行", "仅识别", "仅动作"],
       searchText:
-        "完整运行 从选中节点 单节点 仅识别 仅动作 固定图识别 六种 速查",
+        "从节点运行 单节点运行 仅测试识别 仅执行动作 四种 速查 run-from-node single-node-run recognition-only action-only",
       blocks: [
         {
           type: "markdown",
-          text: "| 方式 | 说明 | 适用场景 |\n|------|------|----------|\n| 完整运行 | 从入口节点开始执行全部流程 | 验证整体流程 |\n| 从选中节点 | 从指定节点开始，继续后续流程 | 跳过前置步骤 |\n| 单节点运行 | 只执行一个节点的识别+动作 | 验证单节点行为 |\n| 仅识别 | 只执行识别，不触发动作 | 确认识别是否命中 |\n| 仅动作 | 跳过识别，直接执行动作 | 验证动作效果 |\n| 固定图识别 | 用指定图片代替实时截图做识别 | 离线验证、复现问题 |",
+          text: "| 方式 | 说明 | 适用场景 |\n|------|------|----------|\n| 从节点运行 | 以选中节点作为入口运行后续 pipeline | 跳过前置步骤，验证后续流程 |\n| 单节点运行 | 对选中节点执行一次识别与动作组合 | 验证单节点完整行为 |\n| 仅测试识别 | 只验证选中节点的识别逻辑 | 确认识别是否命中 |\n| 仅执行动作 | 跳过识别，直接执行选中节点的动作 | 验证动作效果 |",
+        },
+        {
+          type: "callout",
+          calloutType: "info",
+          title: "回放模式",
+          text: "除了上述四种实时运行方式，FlowScope 还支持 Trace Replay（回放），可以对已有的运行记录按时间顺序逐步重放事件，无需再次连接设备。",
+        },
+      ],
+    },
+    {
+      id: "entry-node-selection",
+      title: "入口节点选择",
+      summary: "在中控台选择入口节点，决定运行起点。",
+      keywords: ["入口节点", "中控台", "选择"],
+      searchText:
+        "入口节点 中控台 选择 节点选择器 当前文件 所有节点",
+      blocks: [
+        {
+          type: "paragraph",
+          text: "在中控台的运行控制区域，通过节点选择器指定入口节点。默认只显示当前文件中的节点，勾选「包含所有节点」可以选择跨文件的节点。选好入口节点后，再选择运行方式即可发起运行。",
         },
       ],
     },
@@ -42,12 +63,12 @@ const module: WikiModule = {
       summary: "从小范围开始，逐步扩大。",
       keywords: ["验证顺序", "渐进", "调试策略"],
       searchText:
-        "验证顺序 渐进 调试策略 先仅识别 再单节点 再从节点 最后完整",
+        "验证顺序 渐进 调试策略 先仅识别 再单节点 再从节点",
       blocks: [
         {
           type: "code",
           language: "text",
-          text: "仅识别（确认能识别）→ 单节点（确认识别+动作）→ 从节点（确认后续流程）→ 完整运行",
+          text: "仅识别（确认能识别）→ 单节点（确认识别+动作）→ 从节点运行（确认后续流程）",
         },
         {
           type: "paragraph",

src/wiki/entries/debug/timelineArtifacts.ts

@@ -3,46 +3,61 @@ import { createModuleSearchIndex } from "../../searchHelpers";
 
 const module: WikiModule = {
   id: "timeline-artifacts",
-  title: "时间线与产物",
-  summary: "当节点线只能告诉你大概位置时，用事件线和图像产物继续向下追证据。",
+  title: "事件线与产物",
+  summary:
+    "当节点线只能告诉你大概位置时，用事件线按 seq 追踪顺序，用图像和产物核对证据。",
   searchText:
-    "时间线 事件线 产物 图像 调试证据 截图 识别详情 动作详情 detail artifact 原始图 绘制图 性能摘要 懒加载",
+    "时间线 事件线 产物 图像 调试证据 截图 识别详情 动作详情 artifact 原始图 绘制图 性能 懒加载 seq 回放",
   steps: [
     {
       id: "read-timeline-order",
-      title: "先用事件线确认发生顺序",
-      summary: "事件线适合回答“先发生了什么、后发生了什么”。",
-      keywords: ["时间线", "事件线", "顺序"],
+      title: "用事件线确认发生顺序",
+      summary: "事件线按 mfw seq 排列，适合回答「先发生了什么」。",
+      keywords: ["事件线", "seq", "顺序"],
       searchText:
-        "时间线 事件线 顺序 调试事件 mfw seq 先后顺序 运行轨迹",
+        "事件线 seq 顺序 调试事件 mfw 先后顺序 运行轨迹 timeline",
       blocks: [
         {
           type: "paragraph",
-          text: "节点线更适合定位“哪个节点有问题”，事件线更适合回答“问题是怎么一步步发生的”。当你需要判断识别、动作、节点事件的先后顺序时，优先切到事件线。",
+          text: "节点线适合定位「哪个节点有问题」，事件线适合回答「问题是怎么一步步发生的」。事件线按 MaaFramework 的 seq 编号排列所有事件（session、task、node、recognition、action、next-list、screenshot 等），当你需要判断事件的先后顺序时，优先切到事件线面板。",
         },
       ],
     },
     {
-      id: "artifact-types",
-      title: "了解产物类型",
-      summary: "不同类型的产物提供不同维度的证据。",
-      keywords: ["原始图", "绘制图", "动作详情", "性能摘要"],
+      id: "event-kinds",
+      title: "事件类型",
+      summary: "不同 kind 的事件提供不同维度的信息。",
+      keywords: ["session", "task", "node", "recognition", "action"],
       searchText:
-        "原始图 绘制图 动作详情 截图 性能摘要 批量识别摘要 产物类型",
+        "事件类型 session task node recognition action next-list screenshot diagnostic artifact log wait-freezes kind",
       blocks: [
         {
           type: "markdown",
-          text: "- **原始图（Raw）**：设备截图原图，确认画面是否正确\n- **绘制图（Draw）**：在截图上标注识别框和点击位置\n- **动作详情**：动作执行的具体参数和结果\n- **截图（Screenshot）**：运行过程中的关键帧\n- **性能摘要**：各节点耗时统计\n- **批量识别摘要**：多次识别的汇总结果",
+          text: "| 事件类型 | 含义 |\n|----------|------|\n| session | 会话生命周期（创建/销毁） |\n| task | 任务级别事件 |\n| node | 节点进入/退出 |\n| next-list | 节点的 next 列表执行 |\n| recognition | 识别执行及结果 |\n| action | 动作执行及结果 |\n| wait-freezes | 等待画面冻结 |\n| screenshot | 截图事件 |\n| diagnostic | 运行时诊断信息 |\n| artifact | 产物生成 |\n| log | 日志输出 |",
         },
       ],
     },
     {
-      id: "open-artifacts",
-      title: "产物按需加载，点击查看",
+      id: "images-panel",
+      title: "图像面板：截图和绘制图",
+      summary: "图像面板集中展示运行过程中的截图和识别绘制图。",
+      keywords: ["图像", "截图", "绘制图", "ROI"],
+      searchText:
+        "图像面板 截图 绘制图 识别图 ROI 原始图 draw raw screenshot images",
+      blocks: [
+        {
+          type: "paragraph",
+          text: "图像面板列出当前展示会话中所有的截图和识别绘制图。绘制图会在截图上标注识别框和点击位置，帮助你直观确认识别是否命中了正确区域。点击具体条目可以查看大图和 ROI 详情。",
+        },
+      ],
+    },
+    {
+      id: "artifact-lazy-load",
+      title: "产物按需加载",
       summary: "产物不会自动全部加载，需要点击具体条目触发。",
-      keywords: ["产物", "懒加载", "点击查看", "LocalBridge"],
+      keywords: ["产物", "懒加载", "LocalBridge"],
       searchText:
-        "产物 截图 识别详情 动作详情 图像面板 artifact detail screenshot 懒加载 点击加载",
+        "产物 懒加载 点击加载 artifact detail 按需加载 LocalBridge",
       blocks: [
         {
           type: "paragraph",
@@ -51,8 +66,8 @@ const module: WikiModule = {
         {
           type: "callout",
           calloutType: "info",
-          title: "临时回放",
-          text: "事件线支持临时回放功能，可以按时间顺序逐步重放事件，帮助理解运行过程中的状态变化。",
+          title: "Trace Replay",
+          text: "事件线支持 Trace Replay 功能，可以按时间顺序逐步重放事件，帮助理解运行过程中的状态变化。回放时可以控制速度和跳转到指定节点。",
         },
       ],
     },