From d5101ef62048b3731bc5f9cf57e44d5ca2f63986 Mon Sep 17 00:00:00 2001 From: OA Hsiao Date: Wed, 17 Jun 2026 01:49:00 +0700 Subject: [PATCH] docs: add bilingual README and richer demo animations --- README.md | 36 +++++- README.zh-TW.md | 117 +++++++++++++++++++ docs/demo-full-workflow.svg | 223 ++++++++++++++++++++++++++++++++++++ docs/demo-preview-find.svg | 81 +++++++++++++ docs/demo-rg-cpu.svg | 79 +++++++++++++ 5 files changed, 534 insertions(+), 2 deletions(-) create mode 100644 README.zh-TW.md create mode 100644 docs/demo-full-workflow.svg create mode 100644 docs/demo-preview-find.svg create mode 100644 docs/demo-rg-cpu.svg diff --git a/README.md b/README.md index 545b0ce..4da9db3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # M2_SCOUT +[English](README.md) | [繁體中文](README.zh-TW.md) + **M2_SCOUT** is a Node.js / Electron port of **M2 SEEK** — a desktop GUI search tool built on top of [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`), [fd](https://github.com/sharkdp/fd), and [cscope](https://cscope.sourceforge.net/). @@ -10,6 +12,32 @@ its own **INI files** (`M2_SCOUT.ini`, `M2_SCOUT_EXCLUDE_GROUPS.ini`, `M2_SCOUT_ --- +## Animated demo + +### Full app workflow animation + +![M2_SCOUT full workflow demo](docs/demo-full-workflow.svg) + +This animation highlights the complete user journey: +- multi-tab workflow, +- OR / parallel AND search, +- live FILES updates, +- preview highlight + F3 / Shift+F3, +- in-preview Ctrl+F popup search, +- cscope flow. + +### `rg.exe` parallel workers + CPU pressure animation + +![M2_SCOUT rg parallel CPU demo](docs/demo-rg-cpu.svg) + +M2_SCOUT launches multiple `rg.exe` workers in parallel for AND mode and can drive CPU usage very high on large repositories. + +### Legacy preview-only animation + +![M2_SCOUT preview find demo](docs/demo-preview-find.svg) + +--- + ## Quick start ```powershell @@ -112,7 +140,8 @@ skill runs this flow for you. | Filename search (fd) | ✅ | ✅ | | Preview ±10 lines, merged blocks | ✅ | ✅ | | Syntax highlight (HL INI) | ✅ Tk tags | ✅ DOM spans, same priority layering | -| Keyword highlight + F3 next | ✅ | ✅ | +| Keyword highlight + F3 next / Shift+F3 prev | ✅ | ✅ | +| Preview in-pane find (Ctrl+F popup + count + next/prev) | ❌ | ✅ | | Editor integration (open at line) | ✅ template `$(FILEPATH)/$(LINENUM)` | ✅ same template, 740-elevation fallback | | FILES HL / Filter coloring | ✅ F2/F3/F4 | ✅ F2/F3/F4 | | F1 copy all results | ✅ | ✅ | @@ -132,8 +161,11 @@ skill runs this flow for you. | `Esc` | stop running search | | `Ctrl+T` / `Ctrl+W` | new / close tab | | `Alt+Down` | focus FILES list | +| `Ctrl+Right` | focus Preview first match | | FILES `F1/F2/F3/F4` | copy all / HL / Dim / clear | -| Preview `F3` | next keyword match | +| Preview `F3` / `Shift+F3` | next / previous keyword match | +| Preview `Ctrl+F` | open in-preview floating find box | +| Preview find `Enter` / `Shift+Enter` | next / previous in-preview match | | Preview `Ctrl + / Ctrl -` | zoom | | Preview right-click | open in editor at clicked line | diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..5ca2877 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,117 @@ +# M2_SCOUT + +[English](README.md) | [繁體中文](README.zh-TW.md) + +**M2_SCOUT** 是 **M2 SEEK** 的 Node.js / Electron 移植版本， +是一套桌面 GUI 搜尋工具，底層使用 [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`)、 +[fd](https://github.com/sharkdp/fd) 與 [cscope](https://cscope.sourceforge.net/)。 + +此專案忠實重現原始 Python/Tkinter 版本 (`../M2_SEEK.py`) 的功能， +並維持與 M2 SEEK 對齊。設定儲存在獨立 **INI 檔案** +(`M2_SCOUT.ini`, `M2_SCOUT_EXCLUDE_GROUPS.ini`, `M2_SCOUT_HL.ini`)。 + +--- + +## 動畫示範 + +### 全功能流程動畫 + +![M2_SCOUT full workflow demo](docs/demo-full-workflow.svg) + +這段動畫展示完整使用流程： +- 多分頁操作 +- OR / 平行 AND 搜尋 +- FILES 清單即時更新 +- Preview 高亮 + `F3` / `Shift+F3` +- Preview 內 `Ctrl+F` 懸浮搜尋框 +- cscope 操作流程 + +### `rg.exe` 多執行緒 + CPU 壓榨動畫 + +![M2_SCOUT rg parallel CPU demo](docs/demo-rg-cpu.svg) + +M2_SCOUT 在 AND 模式下會平行啟動多個 `rg.exe` worker，在大型程式碼庫可把 CPU 使用率拉到很高。 + +### Preview 搜尋動畫（舊版） + +![M2_SCOUT preview find demo](docs/demo-preview-find.svg) + +--- + +## 快速開始 + +```powershell +cd M2_SCOUT +npm install # 首次安裝 (會下載 Electron) +npm start # 啟動 +# 可選：帶入預設資料夾 +npm start -- "C:\CODE\UEFI\Devices0522" +``` + +或直接雙擊 **`M2_SCOUT.cmd`**（首次會先安裝相依，之後直接啟動）。 + +### 工具解析順序 (`rg.exe`, `fd.exe`, `cscope`) + +M2_SCOUT 依序解析執行檔位置： + +1. UI 欄位輸入的 `rg.exe` / `fd.exe`（絕對路徑優先） +2. M2_SCOUT 目錄 +3. 上層目錄 `../`（原 M2_SEEK repo 內建 `rg.exe`, `fd.exe`, `cscope.exe`） +4. 系統 `PATH` + +所以預設可直接重用 M2_SEEK repo 既有工具。 + +--- + +## 與 M2 SEEK 的功能對齊 + +| 區塊 | M2 SEEK (Python/Tk) | M2_SCOUT (Node/Electron) | +|------|---------------------|------------------------| +| 多分頁 UI | ✅ notebook tabs | ✅ tab bar (Ctrl+T / Ctrl+W, 可拖曳排序) | +| 內容搜尋 (ripgrep) | ✅ `--json --stats --fixed-strings` | ✅ 相同參數 | +| OR / AND 關鍵字模式 | ✅ | ✅ | +| 平行 AND | ✅ concurrent `rg` | ✅ concurrent spawns | +| 大小寫區分 | ✅ | ✅ | +| Respect ignore files | ✅ off 時 `--no-ignore` | ✅ | +| Include filter globs | ✅ | ✅ | +| Exclude dirs/files | ✅ | ✅ | +| Exclude 群組 (INI keys) | ✅ `exd_* / exf_*` | ✅ 相同規則 | +| 搜尋時 FILES 即時更新 | ✅ throttled | ✅ throttled (80 ms) | +| STOP / ESC | ✅ kill `rg` | ✅ kill child process | +| Filename 搜尋 (fd) | ✅ | ✅ | +| Preview 上下文合併 | ✅ | ✅ | +| 語法高亮 (HL INI) | ✅ Tk tags | ✅ DOM spans | +| 關鍵字高亮 + F3 next / Shift+F3 prev | ✅ | ✅ | +| Preview 內文搜尋 (Ctrl+F popup + count + next/prev) | ❌ | ✅ | +| 編輯器整合 (跳行) | ✅ `$(FILEPATH)/$(LINENUM)` | ✅ 同模板 | +| FILES HL / Filter coloring | ✅ F2/F3/F4 | ✅ F2/F3/F4 | +| F1 複製全部結果 | ✅ | ✅ | +| Preview 縮放 Ctrl +/- | ✅ | ✅ | +| GEN cscope.files | ✅ | ✅ | +| CSCOPE 視窗 (index + 9 modes) | ✅ | ✅ | +| DEBUG panel | ✅ collapsible | ✅ collapsible | +| INI 持久化 | ✅ default tab | ✅ `TAB BASE` | + +### 快捷鍵 + +| 按鍵 | 功能 | +|-----|------| +| `Ctrl+F` | focus Keywords | +| `Ctrl+D` | focus Filter | +| `Enter` (Keywords/Filter) | 執行搜尋 | +| `Esc` | 停止搜尋 | +| `Ctrl+T` / `Ctrl+W` | 新增 / 關閉分頁 | +| `Alt+Down` | 聚焦 FILES 清單 | +| `Ctrl+Right` | 聚焦 Preview 第一個命中 | +| FILES `F1/F2/F3/F4` | copy all / HL / Dim / clear | +| Preview `F3` / `Shift+F3` | 下一個 / 上一個關鍵字命中 | +| Preview `Ctrl+F` | 開啟 Preview 懸浮搜尋框 | +| Preview find `Enter` / `Shift+Enter` | 下一個 / 上一個 Preview 內文命中 | +| Preview `Ctrl + / Ctrl -` | 縮放 | +| Preview 右鍵 | 在編輯器以點擊行開啟 | + +--- + +## 授權 + +MIT. "Powered By OA Hsiao". diff --git a/docs/demo-full-workflow.svg b/docs/demo-full-workflow.svg new file mode 100644 index 0000000..357d83e --- /dev/null +++ b/docs/demo-full-workflow.svg @@ -0,0 +1,223 @@ + + + + + + + + + + + + + + + + M2_SCOUT Feature Walkthrough + VS Code inspired dark style | 6 scenes | 60%+ feature coverage + + + + + + + + M2_SCOUT.exe + + + SCENE 1: Tabs + OR/AND + Include/Exclude + Live FILES + SCENE 2: Preview highlight + F3/Shift+F3 + Ctrl+F popup + Then: Scene 3 (fd filename search) -> Scene 4 (files color F2/F3/F4 + copy F1) -> Scene 5 (cscope) -> Scene 6 (editor open + zoom + stop/esc) + + + + + + + + CONTROL + + Tabs: TAB BASE | TAB 2 | TAB 3 | Ctrl+T | Ctrl+W + + + keywords: "preview" "find" "renderer" + mode: OR -> AND (parallel workers) + case: off, ignore: on + include: *.js *.html *.css + exclude groups: exd_build exf_min + + FILES (live updates while searching) + + [18] src/renderer/js/renderer.js + [10] src/renderer/index.html + [09] src/renderer/css/style.css + [04] src/main/search.js + [03] src/main/rg.js + + + + + + + + + + + + + + + + + + + + PREVIEW + + 0118 function _highlight() { + 0119 this.els.preview.innerHTML = html; + 0120 this._applyPreviewFindHighlights(); + 0121 } + 0138 if (e.ctrlKey && (e.key === 'f' || e.key === 'F')) { + 0139 e.preventDefault(); + 0140 this.openPreviewFind(); + + + + + + Running rg --json --stats --fixed-strings | STATUS: SEARCHING | ESC to stop + + + + + + + PREVIEW NAVIGATION + F3 next | Shift+F3 prev | Ctrl+F in preview + + + 0094 preview find keeps local focus; does not trigger main keyword box + 0095 defaultPrevented guard blocks global hotkey override + 0096 matches highlighted as .pvfind and .pvfind-current + 0097 count badge shows 2/7 while cycling next/prev + 0098 Shift+F3 in preview moves upward as expected + + + Ctrl+F (preview) + + + + + + + + + preview + + + + Up Down 2/7 X + + + + + + + + + + + + + + + + + + FILENAME SEARCH (fd) + FILES ACTIONS + + + fd pattern: renderer + cmd: fd --full-path --color never "renderer" src/ + + + src/renderer/js/renderer.js + src/renderer/js/highlight.js + src/renderer/css/style.css + src/renderer/index.html + + + F1 copy all results + F2 highlight selected file + F3 dim selected file + F4 clear color state + + + [F2] src/renderer/js/renderer.js + + [F3] src/renderer/css/style.css + + [F1] copied 41 lines to clipboard + + + + + + + CSCOPE FLOW + EDITOR INTEGRATION + STOP/ESC + ZOOM + + + 1) GEN cscope.files + 2) Build cscope.out + 3) Query mode: symbol / callers / callees + 4) Click result -> preview line jump + + + find this C symbol: _applyPreviewFindHighlights + + called by: _onPreviewFindInput + + line: src/renderer/js/renderer.js:1384 + + + Right-click preview -> open in editor with line template $(FILEPATH):$(LINENUM) + Ctrl + and Ctrl - -> preview zoom in/out + Esc -> stop current rg process + + + code -g src/renderer/js/renderer.js:1384 + + + Ctrl + (zoom in) + + Ctrl - (zoom out) + + + ESC STOP + + + STATUS: running search ... + Keyboard routing fixed: preview Ctrl+F does not hit global keyword box + Shift+F3 in preview moves to previous match (upward) + Ctrl+Right preserved for preview navigation + + + + + Coverage: 15+ features shown (>= 60%) + + diff --git a/docs/demo-preview-find.svg b/docs/demo-preview-find.svg new file mode 100644 index 0000000..8ae7b23 --- /dev/null +++ b/docs/demo-preview-find.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + M2_SCOUT Animated Demo + Preview Ctrl+F, floating find box, and live highlight navigation + + + + + FILES + + + PREVIEW + + + + + [12] src/renderer/js/renderer.js + [08] src/renderer/index.html + [06] src/renderer/css/style.css + [03] src/main/search.js + + 0121: function openPreviewFind() { + 0122: pop.hidden = false; + 0123: input.focus(); + 0124: input.select(); + 0125: } + 0138: if (e.ctrlKey && e.key === 'f') { + 0139: e.preventDefault(); + 0140: this.openPreviewFind(); + 0141: } + + + Find + + + + Ctrl + F + + + + + + + preview + + ↑ + + ↓ + 2/4 + + X + + + + + + + + + + + + + Step 1: focus Preview and press Ctrl+F + Step 2: type keyword, all matches are highlighted + Step 3: Enter / Shift+Enter or buttons to navigate + diff --git a/docs/demo-rg-cpu.svg b/docs/demo-rg-cpu.svg new file mode 100644 index 0000000..100c931 --- /dev/null +++ b/docs/demo-rg-cpu.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + `rg.exe` Parallel Search Saturation + AND mode -> multiple workers -> high CPU utilization + + + + Launched workers + + + rg.exe worker #1 keyword: "preview" + rg.exe worker #2 keyword: "find" + rg.exe worker #3 keyword: "highlight" + rg.exe worker #4 keyword: "renderer" + rg.exe worker #5 keyword: "context" + + + + + + + + + + + + + + + + + + + + + + + + CPU load + + + + + + + + + 100% + 75% + 50% + 25% + + + + + + Status: AND search running with parallel rg.exe workers + Effect: high throughput and high CPU utilization on multi-core machines + + M2_SCOUT can intentionally maximize search throughput by parallelizing rg.exe workers +