单页版（全部章节）

1. 选择版本并下载

QuickFind 1.0.0 提供三种发行形态，功能完全一致：

2. 安装

• 双击 Setup 安装包，按向导选择安装位置（默认在用户目录下）
• 安装完成后运行 QuickFind；安装版可在「设置 → 关于」查看版本与检查更新
• 索引数据保存在用户数据目录，卸载后即清除

3. 登录（可选）

核心搜索不需要账号，访客模式即可使用文件名、拼音、正则、全文与自然语言搜索。登录后可以：

• 使用 Pro / Team 权益（OCR、云盘索引、代码符号、AI 助手、自动化与团队能力）
• 在用户中心管理订阅、订单与电子发票
• 查看并撤回登录设备，或自助注销账号

4. 认识主界面

• 顶部：搜索框，右侧有「全文」开关与语法提示标签
• 左侧：分类筛选与索引目录导航（全部 / 文档 / 图片 / 代码 / 视频…）
• 中间：结果列表，可用列表 / 网格视图切换，显示路径、修改时间与大小
• 右侧：预览面板，文件详情与内容摘要
• 底部：索引状态与结果数量；右上角：设置（齿轮）与账号菜单

5. 添加索引文件夹

第一次启动会索引你的用户主目录。在「设置 → 索引」中可以：

• 添加任意本地文件夹，包括移动硬盘（挂载期间增量更新）
• 修改默认排除项，例如 node_modules、.git、$Recycle.Bin、Windows、Program Files
• 设置单文件正文解析上限（默认 5 MB，超过则不解析正文，仍可按文件名搜到）
• 按需加入网络共享路径 —— 可用但受网络速度影响，不建议作为主力索引

6. 等待首次索引

索引全程在本机后台进行，耗时取决于文件数量、磁盘类型以及是否开启 OCR 与符号索引，下表只是粗略参考：

7. 呼出搜索框

全局热键默认如下，全部可在「设置」中修改；注册失败或与其他软件冲突时应用会给出提示。

8. 第一次搜索

• 输入即搜（约 300 毫秒防抖），文件名、路径与正文同时参与匹配
• 多个词用空格分隔表示「并且」：「合同 pdf」要求两者都出现
• 英文双引号做精确短语：「季度报告 最终版」
• 拼音首字母：wj 命中「文件」；全拼 fapiao 命中「发票」
• ↑ / ↓ 选择结果，Enter 打开；Ctrl+Enter 在资源管理器中定位

9. 试试自然语言搜索

像跟同事说话一样描述，系统会在本机把它拆成时间、类型、动作与关键词条件：

• 「上周改的合同」→ 时间 + 文档 + 已修改 + 合同
• 「昨天下载的安装包」→ 时间 + 可执行文件 + 安装包
• 「最近三个月的发票」→ 时间范围 + 表格/文档
• 「不是我发的截图」→ 排除条件 + 图片
• 解析结果显示为条件标签，可以点掉其中任意一个；识别不了时会回退为普通关键词搜索

10. 收藏与预览

在结果上右键可以打开文件、定位所在文件夹、复制路径或加入收藏；收藏在「设置 → 收藏」中管理，登录后可跨设备同步。选中结果按空格可打开快速预览，不必调用外部程序。

推荐的初始设置

• 在「设置 → 常规」选择关闭窗口的行为（询问 / 最小化到托盘 / 直接退出），托盘常驻可保持增量索引实时
• 确认排除项包含 node_modules、.git、系统还原目录
• 按需在「设置 → 智能与自动化」开启 OCR 与代码符号索引
• 在「设置 → 关于」选择更新通道（稳定版 / 测试版）

实战场景演练

• 找上周改的合同 → 直接输入「上周改的合同」
• 找截图里的一句话 → 开启 OCR 后直接搜那句话
• 找某个函数定义 → 输入函数名，结果给出文件与行号
• 给下载目录里的安装包归档 → 用「大文件归档」规则先预览再执行

下一步

• 阅读：搜索语法完整指南
• 查阅：快捷键大全
• 了解：免费版与 Pro 的差异
• 遇到问题：技术支持与常见问题

Windows（已发布）

Linux（已发布）

文件系统

• NTFS：以文件监听实现增量；以管理员身份运行时额外读取 USN 变更日志，但只覆盖卷根目录下的文件
• exFAT / FAT32：没有 USN，完全依赖文件监听（行为与 NTFS 上的常态一致）
• 网络共享：可索引，但速度取决于网络，官方不建议作为主力索引目录

macOS 与 Linux

Linux x64 已发布，提供 tar.xz 压缩包（AppImage / deb 暂未提供）。macOS 已完成桌面端适配，但尚未提供安装包（dmg / zip），发布前不会出现在下载页。

网络

核心搜索、OCR 与代码符号索引完全离线可用。需要联网的只有：注册登录、收藏与设置同步、订阅与发票、以及检查更新。OCR 语言包与语法文件随安装包分发，不会在运行时下载额外模型。

隐私与遥测

索引与文件解析在本机完成。匿名使用统计与崩溃上报可以在设置中逐项关闭，关闭后不影响任何搜索功能。

搜索方式总览

1. 普通关键词

• 直接输入即做子串匹配，大小写不敏感：「发票」命中「2026年发票汇总.pdf」
• 多个词以空格分隔表示「并且」：「合同 pdf」要求同时包含两者
• 英文双引号做精确短语匹配："季度报告 最终版"
• 默认同时匹配文件名、路径与正文；用搜索框右侧的「全文」开关可以临时只看文件名

2. 拼音首字母 / 全拼

无需切换中文输入法，直接敲拼音：

• 首字母：wj → 「文件」、bg → 「报告」、sh → 「设计」
• 全拼：fapiao、hetong 同样命中
• 多字组合：sjsb → 「数据申报」
• 仅对包含中文字符的文本做拼音匹配，纯英文文件名不参与拼音转换

3. 正则表达式

以 regex: 前缀进入正则模式（JavaScript 语法，不区分大小写），可匹配文件名、路径与正文：

• regex: 202[0-9]发票 — 匹配年份
• regex: \.(pdf|docx)$ — 限定后缀结尾
• regex: ^Q[1-3] — 文件名以 Q1~Q3 开头
• regex: report[-_ ]?v?\d+ — 匹配 report v2、report-v10 等
• 非法正则自动降级为普通关键词，不会中断搜索

4. 结构化过滤符

可以叠加在任意关键词前后，自由组合：

5. 时间表达

• date:today（今天）、date:yesterday（昨天）
• date:thisweek（本周一起）、date:>7d（最近 7 天内修改）
• 绝对日期与区间：date:>2026-01-01、date:2026-01-01..2026-06-30
• 自然语言中的「上周、昨天、最近三个月」同样会被解析为时间条件

6. 组合运算

• 排除：在关键词前加 -，例如 -临时 表示排除包含「临时」的结果
• 或：空格两侧加竖线，例如 合同 | 协议 表示命中其一即可
• 精确短语：英文双引号包裹，例如 "季度报告" 只按完整短语匹配
• 通配符：? 匹配单个字符，* 匹配任意长度，例如 *.docx

7. 大小单位

• 支持 b / kb / mb / gb，大小写不敏感
• 区间写法：size:500kb..5mb
• 比较写法：size:>=100mb、size:<50kb

8. 组合规则与优先级

• 多个条件之间是「并且」关系
• 自然语言解析出的条件与手动过滤符合并，重复条件去重
• 示例：「上周 pdf size:>5mb」= 上周修改 + PDF + 大于 5MB
• 命中排序会区分文件名、路径与正文命中，文件名命中优先

9. 自然语言搜索

像跟同事说话一样描述，解析在本机完成、不需要联网，免费版同样可用：

• 「上周改的合同」→ 时间 + 文档 + 已修改 + 合同
• 「昨天下载的 PDF」→ 时间 + PDF + 下载相关词
• 「最近 7 天的报告」→ 时间范围 + 报告
• 「不是我发的截图」→ 排除条件 + 图片
• 解析为可点 × 的条件标签；句子含 size:/kind:/date: 等操作符时按原样走结构化搜索，不做拆解

10. 文字搜索（OCR，Pro）

在「设置 → 智能与自动化」中可分别开启「图片 OCR」与「PDF OCR」（PDF 默认关闭）。开启后，截图、照片以及扫描版 PDF 中的文字都会在本机识别并写入内容索引，直接搜那句话即可命中：

• 引擎为 tesseract.js，在本机运行，识别结果不上传
• 语言包随安装包分发：简体中文 + 英文
• 图片：超大图片先等比缩小到长边 2000 像素再识别，结果落盘缓存
• PDF：逐页处理，每页通常需要数秒；某一页识别失败不影响其余页，也不影响正文解析
• 仍不支持手写体，也不支持语言包之外的语种

11. 代码符号搜索（Pro）

开启符号索引后，直接输入函数、类、方法或变量名即可：

• 开启符号索引后，直接输入函数、类、方法或变量名即可
• 结果给出所在文件与行号，可与文件名、正文命中一起排序
• 抽取是语法级：不做跨文件引用图谱，也不区分定义与引用
• 具体覆盖的语言以应用内「设置 → 索引」中的符号语言列表为准

12. 常见问题与排查

• 搜不到明明存在的文件 → 检查所在文件夹是否在索引范围、排除规则是否命中、文件是否超过正文解析上限
• 只搜出旧文件 → 确认索引已完成（状态栏）；增量更新以文件监听为主，以管理员身份运行时 USN 日志只额外覆盖卷根目录下的文件
• 搜不到图片或扫描件里的文字 → 确认已在「设置 → 智能与自动化」开启图片 OCR / PDF OCR（PDF OCR 默认关闭），且账号为 Pro
• 正则没结果 → 检查转义；先去掉 regex: 用关键词验证，再逐步加正则

语法速查卡

• 空格 = 并且；英文双引号 = 精确短语
• regex: 正则；size: 大小；kind: 大类
• ext: 后缀；date: 日期；path: 目录；name: 文件名；content: 正文
• Ctrl+Alt+Space 呼出；Esc 关闭；Ctrl+, 打开设置；? 或 Ctrl+/ 看快捷键

1. 全局热键（可在设置中修改）

2. 搜索框内

3. 快速预览（Quick Look）

快速预览让你不离开列表就能看内容；图片、文本与文档都可以在预览面板中查看。

4. 快捷键速查表

记不住时按 ? 即可随时查看当前生效的全局热键。

5. 托盘与窗口行为

• 关闭主窗口的行为可在「设置 → 常规」选择：询问 / 最小化到托盘 / 直接退出
• 最小化到托盘后索引仍在后台增量更新，全局热键依然可以呼出搜索框
• 托盘图标右键菜单提供：显示 QuickFind、隐藏到托盘、重建索引、账号相关操作、退出

6. 自定义与冲突处理

• 在「设置」的快捷键区域点击任意动作后按下新组合即可修改
• 支持 Ctrl / Alt / Shift / Win 修饰键与普通键的组合
• 与系统或其他软件冲突时会提示注册失败，换一个组合即可
• 找不到合适组合时，可以先把不常用的动作留空

这套 API 能做什么

QuickFind 提供一组只读 HTTP 接口，让你用 API 密钥以程序方式读取账号侧数据：账号信息、收藏、搜索历史、登录设备与订阅状态。它不会、也无法读取你本机的文件索引或文件内容 —— 索引只保存在你的电脑上，服务器从未持有这些数据。

• 认证：请求头 Authorization: Bearer qf_live_…（API 密钥）
• 基础地址：https://www.quickfindapp.com
• 权限：只读（scopes 只有 read），没有任何写入接口
• 数据格式：JSON（UTF-8），每个响应都带 ok 字段
• 限流：按密钥与来源 IP 分别计数，默认 60 次/分钟、10000 次/天，来源 IP 600 次/分钟

1. 创建与撤销密钥

密钥在「用户中心 → API 密钥」中创建（需要先登录）。创建时返回的明文只显示这一次，之后任何接口都不会再返回它。

• 创建：POST /api/account/api-keys，body 为 {"name":"备份脚本"}（名称可省略，最长 40 字符）
• 上限：同一账号最多保留 10 个有效密钥，超出返回 409 too_many_keys
• 列表：GET /api/account/api-keys，只返回 id、名称、前缀、范围、创建与使用时间、调用次数
• 撤销：POST /api/account/api-keys/revoke，body 为 {"id":"密钥 id"}，撤销立即生效
• 管理接口用的是网站登录会话令牌（Authorization: Bearer 会话令牌），不是 API 密钥本身

2. 认证

每个 /api/v1/* 请求都必须带 API 密钥：

# 把 qf_live_… 换成你在用户中心创建的密钥
        curl -s "https://www.quickfindapp.com/api/v1/me" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"

3. 端点总览

4. GET /api/v1/me

返回账号信息、本次调用所用密钥的信息（含最近使用时间与累计调用次数）以及可用端点列表。

curl -s "https://www.quickfindapp.com/api/v1/me" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"
        
        # 响应 200（UUID、邮箱、密钥前缀为占位值；其余字段取自线上实测）
        {
          "ok": true,
          "user": { "id": "1f0e5b7a-4c2d-4a91-9c33-0f7b2d5e8a10", "email": "you@example.com", "email_confirmed": true },
          "key": {
            "id": "635f5e8b-92f0-480f-8a55-4441a2544682",
            "name": "备份脚本",
            "prefix": "qf_live_um6m6twr",
            "scopes": ["read"],
            "created_at": "2026-09-30T16:15:51.341071+00:00",
            "last_used_at": "2026-09-30T16:15:53.803206+00:00",
            "request_count": 1
          },
          "scopes": ["read"],
          "endpoints": ["/api/v1/me", "/api/v1/favorites", "/api/v1/history", "/api/v1/devices", "/api/v1/subscription"]
        }

5. GET /api/v1/favorites

返回你的收藏，按收藏时间倒序，最多 200 条。收藏里存的是本机文件路径与文件名（服务器没有文件内容）。

curl -s "https://www.quickfindapp.com/api/v1/favorites" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"
        
        # 响应 200
        {
          "ok": true,
          "count": 1,
          "favorites": [
            {
              "id": "8d37a604-048f-4585-b1e1-b2afa7ce98fc",
              "user_id": "1f0e5b7a-4c2d-4a91-9c33-0f7b2d5e8a10",
              "file_path": "D:\\工作\\2026年度合同\\技术服务合同_最终版.docx",
              "file_name": "技术服务合同_最终版.docx",
              "created_at": "2026-09-30T16:15:46.652126+00:00"
            }
          ]
        }

6. GET /api/v1/history

返回搜索历史，按时间倒序。limit 取 1..200，默认 50；超出范围会被截到边界，无法解析时退回默认值。

curl -s "https://www.quickfindapp.com/api/v1/history?limit=50" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"
        
        # 响应 200
        {
          "ok": true,
          "count": 1,
          "history": [
            {
              "id": "03eb49e5-0313-483d-a7c0-3aacb29a4fe1",
              "user_id": "1f0e5b7a-4c2d-4a91-9c33-0f7b2d5e8a10",
              "query": "上周改的合同",
              "result_count": 12,
              "device_id": "desktop-demo",
              "created_at": "2026-09-30T16:15:46.652126+00:00"
            }
          ]
        }

7. GET /api/v1/devices

返回官网登录会话（login_devices 表），按最后活跃时间倒序，最多 100 条。桌面端设备记录写在另一张表，本接口不读取；官网「登录设备」里的撤回会让该会话在网页端立即失效，桌面端在下次启动或心跳时也会被拒绝并要求重新登录。

curl -s "https://www.quickfindapp.com/api/v1/devices" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"
        
        # 响应 200
        {
          "ok": true,
          "count": 1,
          "devices": [
            {
              "id": "d59a707c-a090-4d48-9c3c-17b4e395b5c4",
              "device_name": "Windows 11 · Chrome",
              "device_type": "desktop",
              "os": "Windows 11",
              "browser": "Chrome 141",
              "ip": "203.0.113.9",
              "location": "Shanghai Shanghai China",
              "is_current": true,
              "last_active_at": "2026-09-30T16:15:46.652126+00:00",
              "created_at": "2026-09-30T16:15:46.652126+00:00",
              "revoked_at": null
            }
          ]
        }

8. GET /api/v1/subscription

返回当前订阅与权益。字段口径来自服务端唯一的权益实现，与官网定价页、桌面端判断一致。

curl -s "https://www.quickfindapp.com/api/v1/subscription" \
          -H "Authorization: Bearer qf_live_YOUR_API_KEY"
        
        # 响应 200（免费账号线上实测）
        {
          "ok": true,
          "contract": "entitlement/1",
          "subscription": {
            "plan": "free",
            "status": "none",
            "billing_cycle": null,
            "seats": 1,
            "current_period_end": null,
            "source": "purchase",
            "granted": false,
            "entitled": false
          },
          "entitlement": {
            "plan": "free",
            "status": "none",
            "seats": 1,
            "expires_at": null,
            "current_period_end": null,
            "billing_cycle": null,
            "source": null,
            "granted": false,
            "expired": false,
            "entitled": false,
            "reason": "no_subscription",
            "entitled_features": ["filename_search", "fulltext_search"]
          },
          "entitled_features": ["filename_search", "fulltext_search"]
        }

9. 权限范围（scopes）

每个密钥的范围都是 read，这也是当前唯一存在的范围。

• 可以读取上面五个端点的账号侧数据
• 没有任何写入、删除或执行接口：API 不能修改你的收藏、设置、设备或订阅
• API 拿不到本机文件索引、文件内容、OCR 结果与代码符号 —— 这些数据只存在于你的电脑上
• 请求被拒绝时也不会顺便告诉你"密钥是否存在"（401 只有两种错误码）

10. 限流

两个维度分别计数，任意一个超限就返回 429：

• 密钥维度：60 次 / 分钟、10000 次 / 天（每个密钥独立计数）
• 来源 IP 维度：600 次 / 分钟（同一出口 IP 上的所有密钥合计）
• 计数发生在密钥校验之后：无效密钥直接回 401，不占用密钥配额；同一 IP 的试错探测由 IP 守卫（600 次/分钟，早于密钥校验）挡住
• 每个响应都带 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset、RateLimit-Scope，告诉你当前生效的是哪个桶

# 超限时的响应（HTTP 429）
        {
          "ok": false,
          "error": "rate_limited",
          "scope": "key_minute",
          "limit": 60,
          "window_seconds": 60,
          "retry_after": 37
        }
        
        # 同时给出的响应头
        RateLimit-Limit: 60
        RateLimit-Remaining: 0
        RateLimit-Reset: 37
        RateLimit-Scope: key_minute
        Retry-After: 37

11. 错误码

所有失败响应的形状都是 {"ok":false,"error":"…"}，可能再带少量补充字段。

12. 管理密钥的接口

创建、列表与撤销用的是网站登录会话令牌，并且服务端会校验该令牌的签名与有效期：伪造、篡改或过期的令牌一律 401。这几条路由按来源 IP 限流：创建 10 次/分钟、撤销 20 次/分钟。

# 创建（示例为 POSIX shell；PowerShell 请把单引号换成双引号并转义）
        curl -s -X POST "https://www.quickfindapp.com/api/account/api-keys" \
          -H "Authorization: Bearer SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name":"备份脚本"}'
        
        # 响应 201：secret 只在这里出现一次
        {
          "ok": true,
          "key": {
            "id": "635f5e8b-92f0-480f-8a55-4441a2544682",
            "name": "备份脚本",
            "prefix": "qf_live_um6m6twr",
            "created_at": "2026-09-30T16:15:51.341071+00:00",
            "scopes": ["read"]
          },
          "secret": "qf_live_um6m6twr9x2c4v7b1n5m8k3j6h0g4d2s",
          "notice": "secret_shown_once"
        }
        
        # 撤销（id 取自列表接口）
        curl -s -X POST "https://www.quickfindapp.com/api/account/api-keys/revoke" \
          -H "Authorization: Bearer SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"id":"635f5e8b-92f0-480f-8a55-4441a2544682"}'
        
        # 响应 200
        { "ok": true, "revoked": "635f5e8b-92f0-480f-8a55-4441a2544682" }

13. 安全建议

密钥等同于你的账号读取凭证，按下面几条处理：

• 明文只在创建时显示一次：存进密码管理器或密钥管理工具，不要提交到代码仓库、不要写进前端页面
• 接口允许任意来源的跨域调用（Access-Control-Allow-Origin: *），所以浏览器里调用会把密钥暴露给该页面的所有脚本 —— 请只在服务端或本机脚本中使用
• 怀疑泄露：在用户中心撤销该密钥并重新创建，撤销立即生效，无需重启任何服务
• 一个集成用一个密钥：用户中心的列表会显示每个密钥的最近使用时间与调用次数，便于单独撤销与排查

下一步

• 创建第一个密钥：用户中心 → API 密钥
• 想了解权益字段：对照定价页与上面的 /api/v1/subscription 示例
• 还有其他问题：联系我们，我们会在 1–2 个工作日内回复