Overview

Relevant source files

• README.md
• img/market_marked.png
• src/plugin.json

This document provides a high-level introduction to CatchFishIfYouCan, a uTools plugin for finding missing names from reference lists. It explains what the plugin does, its key features, and the overall technical architecture. For details on the problem domain and use cases, see Use Case and Motivation. For architectural deep-dive, see High-Level Architecture.

---

What is CatchFishIfYouCan

CatchFishIfYouCan (漏网之鱼) is a productivity plugin for the uTools desktop platform that solves a specific comparison problem: given a reference list of names and an input text (e.g., survey responses, attendance records), identify which names from the reference list are missing from the input text.

The plugin eliminates the need for manual Excel sorting or VLOOKUP formulas by providing a one-click solution accessible through uTools' quick panel and super panel interfaces. Users can select text from any source (including Excel cells), invoke the plugin with a keyboard shortcut, and immediately see which names are missing.

Key terminology:

• Namelist (名单): A stored reference list containing names
• 漏网之鱼 (Fish): The missing names—names present in the reference list but absent from the input text
• Query text: The input text to be compared against the reference lists

Sources: README.md5-49 src/plugin.json1-36

---

Key Features

The plugin provides two primary feature sets, exposed through three uTools commands defined in plugin.json:

Feature Code	Command	Description
catch	"查找漏网之鱼"	Find missing names by comparing input text against selected namelists
set	"设置名单"	Open configuration modal to manage existing namelists
new	"新建名单"	Create a new namelist from selected text or file input

Finding Missing Names (catch feature):

• Accepts input via selected text (including Excel cells) or direct text entry
• Supports single or multiple namelist selection
• Handles name disambiguation (e.g., "张三丰" vs "张三" by prioritizing longer matches)
• Configurable output separators for the result list
• Export functionality for both missing names and the full merged namelist

Namelist Management (set and new features):

• Automatic name recognition using Unicode-aware regex patterns
• Support for loading namelists from text files (.txt, .csv, .md, .markdown)
• Create, update, and delete operations with real-time validation
• Names automatically deduplicated and sorted

Sources: README.md22-32 src/plugin.json5-35

---

Technical Stack

CatchFishIfYouCan is built using the following technologies:

Core dependencies:

• Vue.js 3: Reactive UI framework using Composition API with ref and computed
• Bulma CSS: Provides responsive grid, modal, form, and button styling
• Font Awesome: Icon library for UI elements
• uTools Platform: Provides quick panel entry points, database storage (utools.dbStorage), native dialogs, and lifecycle events

The application runs in an Electron-based environment where uTools provides both the platform APIs and the runtime container.

Sources: README.md63 src/plugin.json2-4

---

System Architecture Overview

The plugin follows a layered architecture with clear separation between platform integration, application logic, UI components, and data persistence.

Architecture Layers

Key architectural components:

Layer	Component	Primary Responsibility
Platform	uTools Entry Points	Capture user actions (text selection, command invocation)
Platform	utools.dbStorage	Persist namelists with key pattern names_*
Application	app.js	Initialize Vue app, manage shared state (query, isModalOpen, paraNames)
Application	plugin.json	Define three features: catch, set, new
Component	MainWindowComp	Display results, handle findFish() workflow
Component	ConfigModalComp	Manage namelist CRUD operations
Data	store.js	Provide reactive allLists ref, CRUD methods, findFish() algorithm
Data	preload.js	Securely expose createReadStream, statSync, writeFile to renderer

Sources: Diagrams 1, 2, 3, 4 from system architecture analysis

---

Core Component Relationships

This diagram maps the actual code entities and their communication patterns:

Data flow patterns:

1. Read-heavy path (Finding missing names):

   • User invokes catch feature → app.js receives query → MainWindowComp reads store.allLists → computes allNamesArray → calls store.findFish() → displays results

2. Write-heavy path (Managing namelists):

   • User invokes set or new feature → ConfigModalComp opens → user creates/updates/deletes → calls store.setList()/store.removeList() → persists to utools.dbStorage → triggers store.updateAllLists() → updates reactive allLists ref

3. File I/O path:

   • User clicks file upload/export button → component calls utools.showOpenDialog() or utools.showSaveDialog() → user selects file → component calls window.preload.createReadStream() or window.preload.writeFile() → preload script executes Node.js fs operations

Sources: Diagram 4 from system architecture analysis

---

Key Algorithms

The findFish Algorithm

The core business logic is implemented in the findFish() function within store.js. This algorithm identifies missing names by:

1. Reverse iteration: Processes names from longest to shortest to prevent substring false positives
2. Marking strategy: Replaces found names with | characters to prevent duplicate matching
3. Custom sorting: Returns missing names sorted by length (shortest first), then alphabetically

Example: Given allNames = ["张三", "张三丰", "李四"] and namesString = "张三丰李四":

1. First checks "张三丰" (longest) → found → marks as "|李四"
2. Then checks "李四" → found → marks as "||"
3. Finally checks "张三" → not found → adds to fish
4. Returns ["张三"]

This prevents "张三" from matching the substring within "张三丰".

Sources: Diagram 5 from system architecture analysis

---

Entry Points and Plugin Features

The plugin exposes three distinct entry points configured in plugin.json:

Feature configuration details:

• catch feature (src/plugin.json7-15):

  • Type: over (requires text selection)
  • Minimum selection length: 1 character
  • Payload: Selected text becomes the query
  • Target: MainWindowComp displays with query pre-filled

• set feature (src/plugin.json18-22):

  • Type: Command-based (no text selection required)
  • Target: Opens ConfigModalComp for managing existing lists

• new feature (src/plugin.json24-34):

  • Type: over (requires text selection)
  • Minimum selection length: 1 character
  • Payload: Selected text becomes initial content for new namelist
  • Target: ConfigModalComp opens in creation mode with paraNames set

Sources: src/plugin.json5-35

---

Data Persistence Model

Namelists are stored using the uTools database with a namespaced key pattern:

Storage schema:

• Key: names_<title> where <title> is the user-defined namelist name
• Value: {title: string, data: string[]} where data is the array of names

The store.updateAllLists() function synchronizes the reactive allLists ref with the database by:

1. Fetching all keys from utools.dbStorage
2. Filtering for keys starting with names_
3. Loading each namelist's value
4. Updating the allLists ref to trigger Vue reactivity

This pattern ensures that all components observing allLists automatically re-render when namelists change.

Sources: Diagram 3 from system architecture analysis

---

Related Documentation

For more detailed information on specific aspects of the system:

• Use Case and Motivation: Background on the problem domain and why this plugin was created
• High-Level Architecture: Detailed architectural diagrams and component interactions
• Main Window Component: Deep dive into the MainWindowComp and the finding workflow
• Configuration Modal Component: Details on namelist CRUD operations in ConfigModalComp
• State Management (store.js): Complete reference for store.js APIs and algorithms
• Finding Missing Names Workflow: Step-by-step user workflow documentation