ZTools工具箱基本技术信息

ZTools工具箱基本技术信息

【概述段（词条首段简介）】

ZTools工具箱（简称：ZTools）是一款开源的跨平台桌面效率启动器与插件中枢软件，支持 Windows、macOS 等桌面操作系统。该软件采用“轻量 TypeScript 宿主 + 预编译 Rust 原生侧车（Sidecar）”的解耦架构，结合双模态交互界面（悬浮搜索栏与大主界面工作台）以及声明式 UI 渲染引擎，为用户提供本地应用快速启动、硬件级文件检索、剪贴板历史管理、快捷短语扩展、窗口分屏调度以及 AI 模型接入等功能。

ZTools工具箱的核心宿主基于 GNU General Public License v3.0（GPL-3.0）协议开源，其扩展生态与兼容层组件库基于 MIT 协议开源。
Github地址 :https://github.com/codingmuse/ZTools 欢迎开发者大家一起共创
官方网站 : www.ztools.cn

---

字段名称	填写内容
中文名	ZTools工具箱
外文名	ZTools
软件类型	桌面效率工具、快速启动器、插件管理平台
运行平台	Windows 10/11、macOS（规划支持 Linux）
开发语言	TypeScript、Rust、Vue 3
核心框架	Electron、Vue 3、SQLite
开源协议	GPL-3.0（核心宿主）、MIT（插件生态）
软件版本	1.0.0
主要功能	文件快速检索、剪贴板管理、快捷短语、窗口管理、AI助手、插件扩展

---

一、 开发背景与设计理念

随着桌面操作系统的功能日益复杂，开发者与办公人群对于高频操作（如文件查找、跨应用文本处理、系统窗口调度、日常开发辅助等）的键盘交互效率提出了更高要求。传统的桌面工具往往面临两类问题：一是功能单一，缺乏统一的扩展标准；二是采用多语言混合打包或允许插件自由操作原生 DOM/CSS，导致安装包体积庞大、内存占用高以及界面风格割裂。

ZTools工具箱在设计上吸纳了现代桌面启动器（如 Raycast）的声明式交互范式，并针对跨平台工程化进行了架构重构：

1. 声明式 UI 隔离：限制扩展直接操作原生 HTML DOM 或编写自定义 CSS，统一通过语义化组件描述符渲染界面，保障视觉风格统一与运行稳定性。
2. 宿主与底层能力解耦：将界面交互交由前端框架处理，将耗时的磁盘索引与系统特权操作下沉至独立的 Rust 原生进程。
3. 本地优先（Local-First）：核心个人数据（剪贴板记录、便签、快捷指令、文件索引）默认存储于本地 SQLite 数据库中，不强制依赖云端账号体系。

---

二、 系统架构

ZTools工具箱采用四层解耦的系统架构设计：

1. 双模态渲染层（Renderer）
   基于 Vue 3 构建，包含“极客悬浮窗（Launcher）”与“大主界面工作台（Dashboard）”两种形态，二者共享同一个本地搜索内核与声明式视图舞台（DeclarativeView），支持通过快捷键（Ctrl/Cmd + M）切换。
2. 主进程微内核（Main Process）
   基于 Electron 与 TypeScript 构建，负责生命周期管理、全局快捷键分发、拼音首字母与 Frecency（频度衰减）排序检索、内置核心套件调度以及本地 SQLite WAL（预写式日志）数据库存储。
3. 隔离扩展宿主（Extension Host）
   基于独立子进程（utilityProcess）与工作线程（worker_threads）运行第三方插件，单命令运行于受限内存配额的独立线程中，并内置 @ztools/raycast-compat 兼容层运行时，实现插件故障与主界面的物理隔离。
4. 预编译原生侧车（Native Sidecar）
   通过标准输入输出（Stdio）或命名管道与主进程通信的独立预编译二进制程序：
   • 索引侧车（ztools-indexer）：在 Windows 平台下直接解析 NTFS 文件系统的主文件表（MFT）并监听 USN Journal 增量日志，在 macOS 平台对接 Spotlight 接口，实现低延迟的本地文件检索。
   • 特权穿透侧车（ztools-privilege / ztools-uiaccess）：在 Windows 平台利用 UIAccess 机制穿透用户界面特权隔离（UIPI），在 macOS 平台基于 Accessibility API（AXUIElement），实现跨权限窗口的选中文本抓取、活动浏览器标签页 URL 读取及窗口分屏控制。

---

三、 核心功能模块

ZTools工具箱将功能划分为“第一方内置套件”与“社区扩展插件”两部分。其中第一方内置套件涵盖 6 大分类共 38 项功能模块：

1. 核心生产力模块

• 剪贴板历史（Clipboard History）：基于本地 SQLite 持久化记录复制的文本、图片、文件与颜色代码，支持分类过滤、敏感密码自动脱敏及顺序流水粘贴（Paste Sequentially）。
• 快捷短语与宏（Snippets）：支持全局触发词监听与自动退格替换，内置 {clipboard}、{date}、{time}、{cursor} 等动态占位符。
• 文件快速检索（File Search）：调用底层索引引擎按文件名、路径或拼音首字母检索本地文件，支持多盘符过滤与快速预览。
• 窗口管理（Window Management）：提供左/右半屏、四分之一屏、最大化、窗口居中、跨显示器迁移等 15 种以上的分屏与布局指令。
• 智能计算器（Calculator）：在搜索框内实时计算数学表达式、单位换算、进制转换以及 HEX/RGB/HSL 色彩模型转换。
• 系统控制与脚本命令（System & Script Commands）：支持锁屏、睡眠、清空回收站、进程管理等系统操作，并支持解析带有 @raycast.* 头部注释的本地脚本（.ps1、.sh、.py、.js）。

2. 日常实用与网络联动模块

• 多语种划词翻译（Translator）：抓取当前活动窗口选中文本并进行多语言互译与结果回填。
• Emoji 与符号检索（Emoji Picker）：内置 Unicode 符号库，支持通过中文语义或拼音首字母检索表情符号。
• 轻量便签与离线词典（Notes & Dictionary）：基于 SQLite FTS5 全文检索的 Markdown 便签本与本地中英词典。
• 浏览器联动与快捷链接（Browser & Quicklinks）：检索主流浏览器已打开的标签页、书签与历史记录，支持带参数的 URL 模板快速跳转。

3. 开发者与宿主治理模块

• 扩展开发者工作台（Developer）：提供脚手架一键生成插件工程、挂载本地目录热重载调试以及工作线程内存诊断。
• 个人效率统计與设置中心（Settings & Wrapped）：管理全局热键、外观主题、扩展权限，并基于本地离线数据生成使用频度统计卡片。

4. AI 与多模态感知模块

• 统一大模型路由（AI Chat）：支持 BYOK（自带 API Key）接入 DeepSeek、OpenAI、Claude 等云端模型，同时支持自动探测本地 11434（Ollama）与 1234（LM Studio）端口直连离线大模型。
• 屏幕感知与语音输入（Screen Awareness & Dictation）：支持捕获活动窗口或框选区域画面发送至多模态模型进行解析，以及基于语音识别的听写输入。
• MCP 协议网关（Model Context Protocol）：内置 MCP 协议栈支持，可将本地文件检索、剪贴板读写、窗口控制等能力映射为标准工具供 AI 调用。

---

四、 插件生态与安全机制

ZTools工具箱采用“核心宿主仓（ZTools）+ 插件生态仓（ZTools-extensions）”的双仓协同模式：

1. 声明式组件 SDK：开发者使用 @ztools/raycast-compat 提供的标准组件（<List>、<Detail>、<Form>、<Grid>、<ActionPanel>、<Action>）编写业务逻辑，无需编写界面样式代码。
2. 全键盘交互规范：所有内置模块与第三方扩展共享统一的四级优先级快捷键体系（Enter 执行首要动作、Ctrl/Cmd + Enter 执行次要动作、Ctrl/Cmd + K 唤起动作面板、Esc 逐级返回）。
3. 安全审查机制：社区插件采用 GitOps 流程投稿，上架前需经过 plugin.schema.json 清单校验、抽象语法树（AST）静态安全扫描（拦截动态 eval()、代码混淆与未授权原生模块调用）、CI 源码构建与 SHA-256 哈希校验，并支持通过远程索引的 revoked 字段对问题插件执行下架禁用。
4. 端到端加密同步（E2EE）：支持通过 @ztools/sync-crypto 模块，利用 Argon2id 密钥派生算法与 AES-256-GCM 认证加密算法，将用户配置加密后同步至用户自建的 WebDAV 服务器或 GitHub Gist。

---

五、 运行环境

• 操作系统：Windows 10 / Windows 11（64位）、macOS 12.0 及以上版本（支持 Apple Silicon arm64 与 Intel x86_64 架构）。
• 开发环境要求：Node.js 20.0.0 及以上版本（推荐 Node.js 22+）。