Prism Engine Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Prism Engine is a specialized rule and configuration enhancement system integrated into Zephyr. It extends the capabilities of the Mihomo (Clash Meta) core by providing declarative rule patches, smart node selection, and a secure script execution environment. The engine allows you to apply patches using a Domain Specific Language (DSL) that supports operations like appending, prepending, filtering, and overriding configuration fields based on conditions such as WiFi SSID.
Prism operates as a middleware layer between the raw subscription configurations and the Mihomo core. It manages a rule library, persistent key-value storage, and a plugin system with fine-grained permissions. This architecture ensures that complex routing logic remains decoupled from static configuration files.
Sources: README_en.md:76-85, FEATURES.md:65-73
Core Components and Rule Management
The engine handles rule files primarily in the .prism.yaml format. It provides utilities to sanitize filenames, detect source formats (such as Surge or Clash), and normalize these formats into Prism-compatible YAML.
Rule Lifecycle and Processing
The engine validates every rule file to ensure it follows the standard structure. It specifically looks for a rules: top-level key. Rules are typically sequence items starting with - and containing commas to separate types, values, and policies.
The diagram shows the workflow for importing and normalizing external rules into the Prism Engine format.
Sources: crates/core/src/config/prism_types.rs:136-193, apps/desktop/src-tauri/src/prism/types.rs:166-224
File Identification and Metadata
The engine tracks files using the RuleFileInfo structure, which captures the filename, rule count, and the origin (source) of the rules.
| Field | Type | Description |
|---|---|---|
filename | String | The sanitized name of the rule file ending in .prism.yaml. |
rule_count | u64 | The number of valid rule lines detected in the file. |
source | String | The origin of the file (e.g., "Manual", "Imported", "Extracted"). |
Sources: crates/core/src/config/prism_types.rs:15-20, apps/desktop/src-tauri/src/prism/types.rs:13-18
Security Design and Sandboxing
Security is a primary pillar of the Prism Engine. It implements a multi-layer defense strategy to prevent path traversal, SSRF, and malicious script execution.
Input Validation and Sanitization
The engine enforces a strict MAX_INPUT_SIZE of 10 MB for all user-supplied text inputs. Filenames are sanitized to allow only alphanumeric characters, hyphens, underscores, dots, spaces, CJK characters, and parentheses. Any path traversal components like .., /, or \ are stripped during pre-processing.
Sources: crates/core/src/config/prism_types.rs:8-12, 63-95, apps/desktop/src-tauri/src/prism/types.rs:8-10, 83-118
Script Sandbox (QuickJS)
Prism includes a JavaScript sandbox powered by QuickJS. It imposes nine resource limits and four permission controls to isolate untrusted scripts.
- Resource Limits: Includes execution time (100ms–300s), memory (1MB–512MB), loop iterations (1K–10M), and recursion depth (8–512).
- Permission Controls: Restricts access to the network, filesystem, child processes, and web workers.
- Auditing: Privilege elevations trigger specific audit logs and require UI-level confirmation.
Sources: FEATURES.md:77-80, apps/desktop/src/ui/plugins-smart.js:255-275
Smart Node Selection and Failover
The Smart Proxy Selector automates node management using adaptive algorithms. It tracks node performance and stability to ensure optimal connectivity.
EMA Scoring and Scheduling
The engine uses Exponential Moving Average (EMA) scoring based on three primary weights:
- Latency (P90): The 90th percentile response time.
- Success Rate: The ratio of successful connections to total attempts.
- Stability: The consistency of node performance over time.
Sources: FEATURES.md:68-69, apps/desktop/src/ui/plugins-smart.js:347-362
Failover Policy
Automatic failover triggers when a node crosses specific failure thresholds. The system supports configurable cooldown periods and fallback groups.
The sequence diagram illustrates how the Failover Manager interacts with the Smart Selector to recover from connection failures.
Sources: FEATURES.md:70-71, apps/desktop/src/ui/plugins-smart.js:401-415
Persistent Storage and Plugins
The Prism Engine provides a persistent Key-Value (KV) store and a plugin architecture for extending functionality without modifying the core.
KV Store
The KV store (backed by kv_store.db) allows scripts and plugins to persist data across restarts. It is accessible via IPC commands for setting, getting, deleting, and listing keys.
Sources: FEATURES.md:82, apps/desktop/src/ui/plugins-smart.js:154-190
Plugin System Lifecycle
Plugins go through a defined lifecycle managed by the engine:
- Discovery: Scans the
prism/plugins/directory for plugin folders. - Loading: Validates permissions and initializes the plugin environment.
- Hooks: Triggers lifecycle hooks (e.g.,
onStartup,onConfig) which plugins can subscribe to. - Execution: Runs entry scripts within the sandbox.
Sources: FEATURES.md:81, apps/desktop/src/ui/plugins-smart.js:77-110
Conclusion
The Prism Engine architecture enables Zephyr to transcend simple GUI wrappers by offering deep configuration manipulation and intelligent automation. By combining a secure QuickJS sandbox with a declarative YAML patching system and a performance-driven smart selector, the engine provides a robust framework for advanced proxy management while maintaining strict security boundaries through Rust-based validation and resource limiting.