shield_lock
JinDaGe
← Back to skills
extension
Category: Productivity & OfficeAPI key requirement unconfirmed

quicker-connector

与 Quicker 自动化工具集成，读取、搜索和执行 Quicker 动作列表。支持 CSV 和数据库双数据源，智能匹配用户需求并调用本地 QuickerStarter 执行。同时提供数据维护能力：解析维护工具全量备份（export 目录）、按配置映射定位/读取/修改快捷键、轮盘、手势、组合键等所有配置。

personAuthor: wangnew2013hubOpenAPI
downloadDownload package

Quicker Connector 技能

📋 概述

Quicker Connector 是一个专业的 Quicker 集成工具，让你能够通过 AI 助手直接检索、匹配和执行 Quicker 软件中的自动化动作。支持两种数据源模式，智能语义匹配，准确理解用户意图。

✨ 核心特性

| 特性 | 说明 | |------|------| | 📊 双数据源 | 同时支持 CSV 导出文件和 SQLite 数据库 | | 🔍 多字段搜索 | 按名称、描述、类型、面板等字段搜索 | | 🧠 智能匹配 | 基于关键词提取和语义分析的自动匹配 | | 🎯 精确执行 | 支持同步/异步、参数传递、等待结果 | | 🔧 编码自适应 | 自动检测 UTF-8/GBK 等多种编码 | | 📈 统计信息 | 完整动作分类和面板分布统计 | | 📤 JSON 导出 | 一键导出完整动作列表 | | 🖼️ Excel 导出（含真实图标） | 「图标」列嵌入真实图标图片，离线可用，并自动压缩重复图片媒体 | | 📦 批量导出图标文件 | 一次导出全部动作图标为独立 PNG（去重 + 并发 + 本地缓存优先），附 icons_manifest.json |

🚀 快速开始

1️⃣ 首次初始化

运行引导脚本配置 CSV 路径：

python scripts/init_quicker.py

按提示操作：

  • 在 Quicker 中导出动作列表（工具 → 导出动作列表(CSV)）
  • 将 CSV 文件保存到任意位置
  • 输入完整路径完成配置

配置将保存在 config.json。

2️⃣ 验证安装

python scripts/test_quicker_connector.py

预期看到：

  • ✅ 编码检测通过
  • ✅ CSV 读取成功，动作数量 > 0
  • ✅ 搜索和匹配功能正常
  • ✅ QuickerStarter 路径检测

3️⃣ 基本使用

from quicker_connector import QuickerConnector

# 创建连接器
connector = QuickerConnector(source="csv")

# 读取所有动作
actions = connector.read_actions()
print(f"共 {len(actions)} 个动作")

# 搜索动作
results = connector.search_actions("截图")
for action in results:
    print(f"- {action.name}")

# 智能匹配
matches = connector.match_actions("帮我翻译这段文字", top_n=3)
for m in matches:
    print(f"{m['action'].name} (分数: {m['score']:.2f})")

# 执行动作
result = connector.execute_action(
    action_id="xxxx",
    wait_for_result=True,
    timeout=10
)
print(f"执行结果: {result.success}, 输出: {result.output}")

🎯 触发示例

| 用户输入 | 行为 | |---------|------| | "用 quicker 截图" | 搜索并推荐截图类动作 | | "帮我翻译这段文字" | 匹配翻译相关动作 | | "列出所有 quicker 动作" | 返回完整列表和分类统计 | | "quicker 执行 ID 为 xxx 的动作" | 直接执行指定动作 |

📊 数据结构

QuickerAction

@dataclass
class QuickerAction:
    id: str                    # 唯一标识
    name: str                  # 动作名称
    description: str           # 描述
    icon: str                  # 图标路径/URL
    action_type: str           # 类型: XAction/SendKeys/RunProgram...
    uri: str                   # 执行 URI (quicker:runaction:xxx)
    panel: str                 # 所属面板/分类
    exe: str                   # 关联程序名
    associated_exe: str        # 关联可执行文件
    position: str              # 在面板中的位置
    size: str                  # 大小
    create_time: str           # 创建时间
    update_time: str           # 更新时间
    source: str                # 来源动作

QuickerActionResult

@dataclass
class QuickerActionResult:
    success: bool              # 是否成功
    output: str                # 标准输出
    error: Optional[str]       # 错误信息
    exit_code: Optional[int]   # 退出码

⚙️ 配置说明

配置文件 config.json（自动生成）：

{
  "csv_path": "/path/to/QuickerActions.csv",
  "initialized": true
}

高级设置（通过技能设置界面）：

| 设置项 | 类型 | 默认 | 说明 | |--------|------|------|------| | auto_select_threshold | float | 0.8 | 自动执行阈值，低于此值会询问用户 | | max_results | int | 10 | 最大返回结果数量 | | default_source | string | "csv" | 数据源类型（csv/db） |

🛠️ 高级功能

导出 JSON

将完整动作列表导出为 JSON：

connector.export_to_json("actions.json")

导出 Excel（含真实图标）

把动作列表导出为 .xlsx，「图标」列写入真实图标图片（非文字）：

# 命令行（读取 config.json 的 csv_path）
python scripts/export_actions_excel.py -o quicker_actions.xlsx --size 48

# 注意：需用带依赖的解释器运行，本机为：
# C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe

connector = QuickerConnector(source="csv")
stats = connector.export_to_excel("quicker_actions.xlsx", icon_size=48)
# => {"total": 357, "with_icon": 350, "no_icon": 7, "output": "...", "resolver_stats": {...}}

批量导出图标文件

把每个动作的图标导出为独立 PNG 文件（去重 + 并发 + 本地缓存优先），并生成清单 icons_manifest.json：

# 命令行（读取 config.json 的 csv_path）
python scripts/icon_exporter.py --out ./icons --size 48 --workers 8
python scripts/icon_exporter.py --out ./icons --no-manifest      # 不生成清单

connector = QuickerConnector(source="csv")
stats = connector.export_icons("./icons", size=48, max_workers=8)
# => {"total": 357, "unique": 239, "files": 350, "from_cache": 238, "downloaded": 0,
#     "rendered": 0, "local": 0, "missing": 1, "elapsed_sec": 1.9, "out_dir": "...",
#     "resolver_stats": {...}, "items": [...]}

产出：

| 产物 | 说明 | |---|---| | <三位序号>_<动作名>_<图标短key>.png | 每个动作一个图标文件，动作名已去除 Windows 非法字符并截断到 40 字符 | | icons_manifest.json | [{id, name, icon, icon_file, source, ok}, ...]，source 为 url_cache/url_download/fa_cache/fa_render/local_file/miss |

Excel 的三种图标模式（icon_mode）

| icon_mode | 「图标」列内容 | Excel 体积 | 适用场景 | |---|---|---|---| | embedded（默认） | 嵌入真实 PNG 图片（同一 PNG 只存一份媒体） | 中等（本机 357 动作 ≈ 627.5 KB） | 需要直接看到图标 | | path | 只写图标文件的相对路径 | 很小（≈ 65.5 KB） | 图标另存为文件、Excel 只做索引 | | none | 不处理图标 | 最小（≈ 62 KB） | 只要数据 |

# 嵌图（默认，先批量导出图标文件到 --icons-dir，再生成 Excel）
python scripts/export_actions_excel.py -o actions.xlsx --icon-mode embedded --icons-dir actions_icons

# 只写路径（Excel 极小，图标按行对应 icons 目录）
python scripts/export_actions_excel.py -o actions.xlsx --icon-mode path --icons-dir actions_icons

# 只要图标文件，不生成 Excel
python scripts/export_actions_excel.py -o actions.xlsx --icons-only --icons-dir actions_icons

# 不处理图标
python scripts/export_actions_excel.py -o actions.xlsx --icon-mode none

# 关闭图片媒体去重（体积 ≈903.3 KB，媒体条目回到 350，与去重版功能等价，仅用于排查/对比）
python scripts/export_actions_excel.py -o actions.xlsx --icon-mode embedded --no-dedupe

connector.export_to_excel("actions.xlsx", icon_mode="path", icons_dir="actions_icons")
connector.export_to_excel("actions.xlsx", icon_mode="embedded")   # 默认，等价旧行为

性能说明（本机实测：357 个动作 / 350 个图标）

| 场景 | 图标解析耗时 | 端到端耗时 | 产物 | |---|---|---|---| | 冷缓存（空 .cache/icons，含 96 个 FA 渲染 + 最多 4 个联网下载） | ≈1.0–1.5 s | Excel ≈2.6–2.9 s / 图标导出 ≈3.0–3.6 s | ≈627.5 KB | | 热缓存（239 个唯一图标全部命中本地缓存） | ≈0.03–0.10 s | Excel ≈1.1–1.4 s / 图标导出 ≈1.9–2.1 s | ≈627.5 KB | | --icon-mode path | — | ≈2 s（Excel 生成本身 < 0.3 s） | ≈65.5 KB | | --no-dedupe（关闭媒体压缩） | 同 embedded | 同 embedded | ≈903.3 KB |

耗时为本机参考值，随磁盘 IO 与网络状况波动。 体积/媒体数与缓存来源无关：冷缓存（4 个 URL 图标联网下载）与热缓存（0 下载）两种状态实测均为 ≈627.5 KB（媒体 350 → 232）。232 是 350 个图标文件中不同二进制内容的个数（238 个唯一图标取值中有 6 对产生了字节相同的 PNG），属确定性结果。

优化点：

  • 去重：357 个动作只有 239 个唯一图标取值，同一图标只解析/渲染/下载一次（resolver_stats.reused = 118）
  • 本地缓存优先：URL 图标优先命中 Quicker 本地 ImageCache（离线），命中即返回，完全不进线程池
  • 真并发：只有需要下载/渲染的取值才走 ThreadPoolExecutor（默认 8 线程，仅标准库）
  • 媒体压缩：embedded 模式下同一 PNG 在 xlsx 内只保留一份媒体（350 → 232，xlsx ≈627.5 KB；不去重则 ≈903.3 KB）
  • 可关闭：--no-dedupe 关闭媒体压缩（媒体条目回到 350、体积 ≈903.3 KB），与去重版功能完全等价，仅用于排查/对比
  • 参数校验：--size 必须为 ≥ 1 的整数（如 --size 0 会明确报错退出，不会静默产出 0 个图标）

图标解析规则（对应 CSV「图标」列的三种取值）：

| 图标取值 | 处理方式 | |---|---| | https://...png 等图片 URL | 优先命中 Quicker 本地缓存 %LOCALAPPDATA%\Quicker\ImageCache\<SHA1(完整URL)大写>.png（完全离线）；未命中再联网下载并缓存到 .cache/icons/url/ | | https://...svg（SVG 图标） | Quicker 缓存/下载后，用内置 SVG 栅格化器渲染成 PNG | | fa:Style_Name[:#AARRGGBB]（字体图标） | 读取 Quicker 自带 FontAwesomeIconsWpf.dll 的 SVG 路径数据（已预提取为 data/fontawesome5_svg_index.json.gz，5996 个图标，覆盖 Solid/Regular/Light/Brands），纯 Python 栅格化渲染；#AARRGGBB 为可选颜色 | | 空值 / 本地图片路径 | 留空 / 直接使用 |

依赖：openpyxl、Pillow（渲染无需 pythonnet / 网络）。

相关文件：

  • scripts/export_actions_excel.py —— Excel 生成（表头样式、冻结窗格、筛选、行高自适应图标、三种 icon_mode、xlsx 媒体去重）
  • scripts/icon_exporter.py —— 批量导出图标为独立 PNG + icons_manifest.json（去重 + 并发 + CLI）
  • scripts/icon_resolver.py —— 图标取值 → 本地 PNG；resolve() 单条 + resolve_many() 批量并发
  • scripts/svg_raster.py —— SVG path / SVG 文件 → PNG 纯 Python 栅格化（even-odd 填充、贝塞尔/圆弧、抗锯齿）
  • scripts/fa_icons.py —— FontAwesome5 图标数据访问层
  • scripts/build_fa_index.py —— 从 FontAwesomeIconsWpf.dll 重建全量索引（需 pythonnet，一次性）

获取统计信息

stats = connector.get_statistics()
print(f"总计: {stats['total']}")
print("类型分布:", stats['by_type'])
print("面板分布:", stats['by_panel'])

批量执行准备

actions = connector.read_actions()
xaction_only = [a for a in actions if a.action_type == 'XAction']
print(f"可执行 XAction: {len(xaction_only)} 个")

🛠️ 数据维护（备份导出映射）

全量导出的路径（用户操作指导）

Quicker 的完整配置可以通过维护工具一键导出为纯文本 JSON 文件（不需要逐条手动复制）：

  1. 打开 Quicker → 点击设置（齿轮）→ 维护工具
  2. 点击 备份数据 → 备份全部数据
  3. 选择输出目录（本机为 G:\Data\Tools\Quicker\export）

官方文档：https://getquicker.net/KC/Manual/Doc/settings-BasicToolsSettingPage

该功能会：

  • 备份 quicker.db 并移除访问密码
  • 将所有动作页和动作拆开分别放入单独文件（这正是本技能数据维护的基础）

导出目录结构（映射）

export_root 下的文件类型与对应 Quicker 功能，完整机器可读映射见技能知识库：

export_root\
├── actionpage_<ID>.json              # 动作页（面板）布局
├── actions\action_<ID>_<名>.json     # 每个动作的完整定义（Data 为 JSON 字符串）
├── states\state_<ID>.json            # 动作状态变量快照
├── states\_action_adorn.json         # 动作徽标/角标/右键菜单装饰
├── common_exe_<程序>.json            # 按程序的轮盘/手势/按键增强/组合键监听
├── common_exe__global.json           # 全局公共触发配置（轮盘/手势/按键）
├── common_shared_subprogram_<ID>.json # 共享子程序
├── common_user_settings.json         # 全局设置（快捷键/触发/定时任务/WebSocket 等）
├── common_user_gestures.json         # 手势预设形状
├── common_user_mouseActions.json     # 鼠标动作
├── common_user_powerKeys.json        # PowerKeys 按键增强
├── common_user_preferences.json      # 界面偏好
└── common_user_favorBlocks.json      # 收藏步骤模块

使用映射定位与读写配置

技能知识库中的 data/quicker_export_map.json 提供「功能 → 文件 → 字段」三级映射。 scripts/quicker_connector.py 的 QuickerExportMap 类实现代码直接读取与修改：

from quicker_connector import QuickerExportMap

qm = QuickerExportMap()  # 默认读 data/quicker_export_map.json + config.json 的 export_root

# 1. 定位：某个配置在哪个文件哪个字段
info = qm.locate("扩展热键")
# => {"feature": "...", "file": "settings", "json_path": "HotKeysData.ActionHotkeys[]", ...}

# 2. 读取当前值
hotkeys = qm.read_config("扩展热键")

# 3. 修改并写回（自动备份原文件为 .bak）
qm.update_config("左键增强", new_left_button_plus_actions)

# 4. 动作相关
action = qm.find_action("视频旋转修复版")   # 按名称或 ID 定位 actions\ 文件
data = qm.read_action_data("767bc646-b61f-46ce-818f-0b89f38d40d5")  # 解析 Data JSON

修改 actions\*.json 的 Data（动作步骤/变量）属高风险操作，修改前会生成 .bak 备份； Quicker 正在运行时不会热加载这些文件，需通过 Quicker 的「导入动作」或重启后生效。

常见配置速查

| 功能 | 文件 | 字段 | |---|---|---| | 扩展热键 / 全局快捷键 | common_user_settings.json | HotKeysData（JSON 字符串） | | 轮盘菜单动作 | common_exe_<程序>.json | CircleMenuActions | | 轮盘开关 | common_user_settings.json | EnableCircleMenu 等 | | 手势绑定 | common_exe_<程序>.json | GestureActions | | 左键增强（组合键） | common_user_settings.json | LeftButtonPlusActions | | 按键连击/长按 | common_exe_<程序>.json | KeyActionItems | | 组合键监听 | common_exe_<程序>.json | HotkeyWatcherItems | | PowerKeys | common_user_powerKeys.json | 整个文件 | | 定时任务 | common_user_settings.json | AutoRunTaskList / TriggerTasks | | WebSocket 服务 | common_user_settings.json | WebsocketServerSettings |

按键格式为 "修饰码|虚拟键码"（如 "2|65" = Ctrl+A）；动作 Data 为 JSON 字符串需二次解析； 映射文件与清单的完整版见 data/quicker_export_map.json 和用户侧《Quicker配置映射清单.md》。

🔄 导回（导入）能力

核心原则：限制导入影响范围

用户修改配置后需要导回 Quicker 时，先判断该配置能否单文件导回：

  • 能单文件导回的 → 只导回该文件，不影响其它配置
  • 不能单文件导回的（设置类）→ 引导走批量分享导入，且只勾选最小必要数据

注意前提：export 目录只是备份快照，Quicker 运行时不读它，修改后必须通过下方导入通道生效。

决策表（按修改的文件类型）

| 修改的文件 | 导入模式 | 导入方法 | |---|---|---| | actions\action_*.json（动作） | single | 将 JSON 复制到剪贴板，面板空白格右键 → 粘贴动作；或动作右键 → 信息 → 导入动作定义（文件/剪贴板） | | states\state_*.json / _action_adorn.json | single | 动作右键 → 信息 → 动作数据 → 从云端恢复（仅该动作） | | common_shared_subprogram_*.json | single | 子程序管理 → 导入子程序文件（.qka） | | actionpage_*.json（动作页） | batch | 批量分享 → 导入动作页数据，只勾选该动作页 | | common_user_settings.json（快捷键/轮盘参数/文本指令/定时任务等） | batch | 批量分享 → 导入常规数据（覆盖式） | | common_exe_*.json（按程序的轮盘/手势/按键增强） | batch | 批量分享 → 导入常规数据（覆盖式） | | common_user_gestures/mouseActions/powerKeys/preferences/favorBlocks.json | batch | 批量分享 → 导入常规数据（覆盖式） |

完整对应关系已写入映射（data/quicker_export_map.json 每项的 import_mode / import_method）。

批量导入流程（必须先导出再导入）

  1. 先导出、保住现状：设置 → 维护工具 → 备份数据（全量备份到 export 目录）；或先用批量分享把当前数据分享给自己留底
  2. 打开批量分享的导入链接（或自己分享给自己后打开）
  3. 只勾选必要数据：常规数据（个人设置/手势/轮盘等）按需勾选；动作页只勾本次涉及的
  4. 不要勾选"清空本地数据"（否则删除本账号所有现有设置）
  5. 导入后核对改动生效、其它设置未受影响；异常时用第 1 步备份恢复

官方说明：批量导入常规数据时，同账号已有设置会被覆盖，所以必须先导出再导入。

代码入口（按修改内容自动判断）

qm = QuickerExportMap()
plan = qm.get_import_plan(["扩展热键"])                      # 功能关键词 → batch（设置类）
plan = qm.get_import_plan(["actions\\action_5479d192-...json"])  # 文件 → single（动作）
plan = qm.get_import_plan(["视频旋转修复版"])                 # 动作名 → single
# => {"mode": "single"|"batch", "plans": [...], "steps": [...], "impact": "...", "warning": "..."}

📝 CSV 格式规范

Quicker 导出的 CSV 文件格式：

sep=,
Id,名称,说明,图标,类型,Uri,动作页,EXE,关联Exe,位置,大小,创建或安装时间,最后更新,来源动作
123,动作名称,动作说明,图标URL,XAction,quicker:runaction:123,默认页,,,0,0,2024-01-01 10:00:00,2024-01-01 10:00:00,

关键字段：

  • 类型：XAction、SendKeys、RunProgram 等
  • Uri：quicker:runaction:<动作ID> 格式
  • 动作页：动作所属面板/分类

⚠️ 系统要求

  • 操作系统: Windows（Quicker 仅支持 Windows）
  • Quicker 版本: v2.0+
  • 权限: 需要访问 QuickerStarter.exe
  • Python: 3.8+

🔒 安全说明

  • 所有文件操作仅访问用户指定的路径
  • subprocess 调用严格限制为 QuickerStarter.exe
  • 不收集或传输任何用户数据
  • 无网络访问权限
  • 配置文件中不存储敏感信息

🐛 故障排除

| 问题 | 解决方案 | |------|----------| | FileNotFoundError | 检查 CSV/DB 路径是否正确 | | 编码错误 | 在设置中调整 encodings 顺序 | | QuickerStarter 未找到 | 手动配置 starter_path | | 动作执行失败 | 检查动作 ID 和权限，确保 Quicker 正在运行 |

📚 参考资料

📄 许可证

MIT License - 详见 LICENSE 文件（如有）