ProFind

ProFind macOS 文件搜索技能 — 毫秒级索引搜索、文件内容全文检索、按大小/日期/类型筛选、批量操作

Security Scan

此技能的行为与其描述一致——它封装并自动化 macOS 上的 ProFind 应用；没有发现与描述不符的外部网络回连或隐蔽代码注入，但包含会对本地文件执行操作的脚本，安装前应确认信任 ProFind 与这些脚本。

Purpose & Capability

技能名称、描述与包含的文件/脚本一致：全部围绕 macOS ProFind 的 AppleScript、URL scheme、Shell 封装与本地 Media Server（localhost）API。要求与操作（打开 profind: URL、运行本地脚本、查询本地 UPnP SOAP 端口）都属于该用途范围。

Instruction Scope

SKILL.md 和脚本仅指示与 ProFind 相关的本地操作：使用 osascript 唤起 ProFind、在本机上调用 localhost:54812、以及可由脚本钩子执行的文件操作（移动、重命名、复制路径、发邮件等）。需注意：install.sh 会读取本地 TCC 数据库（~/Library/Application Support/com.apple.TCC/TCC.db）以检测完全磁盘访问权限；这属于权限检查用途，但会接触到隐私授权信息。脚本示例能够修改/移动/删除用户文件（例如 mv、Move To Trash），这是与技能目的一致但需要用户谨慎授权的能力。

Install Mechanism

无远程下载或不明 URL；仅提供本地安装脚本（install.sh）和命令行封装脚本。install.sh 会打开 App Store 页面（官方 id）并将 SKILL.md 复制到用户 OpenClaw 配置目录。没有从未知主机抓取可执行代码或使用 URL 短链等高风险操作。

Credentials

技能不要求任何环境变量或外部凭据。唯一的敏感本地访问是检查并提示授予 ProFind 的“完全磁盘访问”（通过 sqlite3 查询 TCC.db），这与让 ProFind 能够搜索文件的需求相符。

Persistence & Privilege

技能没有设置 always:true，也未尝试修改其他技能或系统级配置（仅复制 SKILL.md 到用户的 OpenClaw 技能目录并创建 ~/Library/Scripts/ProFind）。代理可自主调用技能是平台默认行为，不构成额外问题。

Assessment

要点与建议： - 这项技能只是对已存在的 macOS 应用 ProFind 的自动化封装：它通过 AppleScript (osascript)、profind: URL scheme 和本地 HTTP（localhost:54812）与 ProFind 交互。若你不安装或不信任 ProFind，则不应安装此技能。 - 安装脚本会查询本地 TCC 数据库以判断是否授予了“完全磁盘访问”，并会提示你去系统偏好手动授予该权限。授予后 ProFind（以及使用它的脚本）将能访问系统上的任意文件——仅在你信任该应用及脚本时再授予。 - 技能包含可执行的 sample 脚本（重命名、移动到废纸篓、发送邮件、在 VS Code 中打开等）。这些脚本会对本地文件做修改或触发邮件/外部应用，安装前请审阅这些脚本：不要运行你不理解的脚本或将未经审核的脚本放入 ~/Library/Scripts/ProFind/。 - 一个小问题/代码质量提示：profind-cli.sh 使用了名为 PATH 的变量作为参数占位（覆盖了环境变量 PATH），这是个潜在的脚本错误，可能导致命令查找异常。建议在运行前打开脚本检查或修正（改为其他变量名如 PROPATH）。 - 如果你接受该技能的行为：可安全安装；否则，拒绝安装或仅手动将 SKILL.md 放入配置目录并不要运行 install.sh/prifind-cli.sh。若想更高信心，建议在隔离环境（非关键账户）先运行并检查实际行为。

ProFind 技能

macOS 文件搜索工具封装 — 支持 AppleScript 自动化、Shell 脚本钩子、URL Scheme 唤起和内置 HTTP API。

适用场景： 深度文件搜索、文件名/内容/元数据查询、按大小/日期/类型筛选、批量操作。

---

核心概念

ProFind 是 macOS 上的增强搜索工具，同时支持：

• Spotlight 索引搜索（毫秒级）
• 文件系统扫描搜索（覆盖未索引位置）
• AppleScript 自动化（与脚本钩子联动）
• 内置 HTTP API（程序化搜索）
• URL Scheme（从其他应用唤起）

ProFind 安装检查

if [ -d "/Applications/ProFind.app" ]; then
    echo "ProFind 已安装: $(defaults read /Applications/ProFind.app/Contents/Info.plist CFBundleShortVersionString 2>/dev/null)"
else
    echo "ProFind 未安装，请从 App Store 下载：https://apps.apple.com/app/id1559203395"
fi

---

功能列表

功能	说明
find_files	按文件名搜索，支持 glob/正则
find_content	全文件内容搜索（支持 Spotlight 元数据）
find_advanced	高级组合搜索（大小/日期/类型/UTI/标签等）
run_script	执行 ProFind 脚本钩子处理搜索结果
open_search_window	打开 ProFind 搜索窗口（可预填查询词）
query_api	通过 HTTP API 程序化搜索

---

搜索策略选择

用户查询 → 自动判断使用哪种搜索 → 执行

情况	推荐策略
找已知名称的文件	find_files（Spotlight，毫秒级）
搜索文件内容/元数据	find_content
需要多条件组合	find_advanced
需要对结果批量操作	run_script
需要 UI 交互	open_search_window

---

功能详解

---

1. find_files — 文件名搜索

基于 Spotlight 索引，毫秒级返回。

# 基本搜索
osascript << 'EOF'
tell application "ProFind"
    activate
    open location "profind:search?name=test&path=~/Documents"
end tell
EOF

# 在指定路径搜索（使用 find 命令找 ProFind 窗口内路径）
# ProFind 支持通过 open location 唤起并传入搜索条件

URL Scheme 格式：

profind:search?name=<搜索词>&path=<路径>&scope=<范围>

参数	说明	示例
name	搜索文件名	test.txt、*.pdf
path	搜索根路径（可选）	~/Documents、/Users/Admin
scope	搜索范围	all、home、selected、hidden

---

2. find_content — 内容/元数据搜索

使用 Spotlight 查询引擎，支持按内容、作者、UTI、元数据搜索。

osascript << 'EOF'
tell application "ProFind"
    activate
    
    -- 搜索文件名含 "invoice" 且大小 > 1MB 的 PDF
    open location "profind:search?name=invoice&kind=PDF&size=larger:1MB"
    
    -- 搜索内容含关键字（Spotlight 元数据查询）
    open location "profind:search?name=meeting&meta=content:brainstorm"
    
    -- 按修改日期搜索（最近 7 天内）
    open location "profind:search?name=report&date=modified:~week"
    
    -- 按标签搜索
    open location "profind:search?name=doc&label=red"
end tell
EOF

URL 参数（内容/元数据搜索）：

参数	说明	示例
kind	文件类型	PDF、image、document、folder
meta	Spotlight 元数据查询	content:<词>、author:<人>
size	文件大小	larger:1MB、smaller:100KB、equal:5MB
date	日期范围	modified:~week、created:~month、~year、~3month
label	标签颜色	red、orange、yellow、green、blue、purple、gray
contains	文件内容包含	contains:text to find

---

3. find_advanced — 高级组合搜索

ProFind 支持的高级搜索条件，通过 AppleScript 脚本直接构建搜索窗口内容。

osascript << 'EOF'
tell application "ProFind"
    activate
    
    -- 打开搜索窗口
    set queryWin to make new query window with properties {search text:"*.swift"}
    
    -- 设置高级搜索参数（通过 GUI 脚本或直接参数）
    open location "profind:search?name=*.swift&path=/Users&size=larger:0&date=modified:~month&scope=home"
    
end tell
EOF

搜索条件速查：

条件	URL 值	说明
文件名包含	name=test	支持 glob *.pdf、正则 file[0-9]+
隐藏文件	scope=all	包含隐藏文件
仅应用	kind=application	只搜应用
仅文件夹	kind=folder	只搜文件夹
排除文件夹	exclude:/Volumes/Network	排除指定路径
正则搜索	name=regex:^doc_[0-9]{4}$	使用正则表达式
Spotlight 查询	kind=spotlightmetadata	直接写 mdimporter 查询

常用文件类型（Kind）：

PDF、document、image、movie、music、archive、code、application、folder

Spotlight 元数据类型：

content、author、comment、creator、title、subject、keyword、album、artist

---

4. run_script — 脚本钩子执行

ProFind 的"脚本钩子"（Script Actions）功能：搜索完成后对结果文件执行自定义脚本。

内置脚本钩子（Sample Scripts）：

/Applications/ProFind.app/Contents/Resources/Sample Scripts/

脚本	功能
Less In Terminal.scpt	在 Terminal 用 less 分页查看路径
Move To Trash.scpt	将选中文件移至废纸篓
Say Paths.scpt	朗读文件路径
Show Strings In Terminal.scpt	显示文件的字符串资源
Open in iTunes.scpt	在 iTunes 中打开音频文件
Word Count.shell	统计文件字数
Print Paths.shell	打印文件路径
mail.scpt	发送文件路径邮件
duckduckgo.scpt	用 DuckDuckGo 搜索文件名

通过 ProFind 菜单配置脚本：

1. 打开 ProFind → Scripts 菜单（或右键结果文件）
2. 添加自定义脚本（AppleScript 或 Shell）
3. 脚本接收参数：fileItem（当前文件）和 fileList（所有选中文件）

脚本接收的 AppleScript 参数：

参数名	类型	说明
currentFile / fileItem	POSIX file	当前选中的文件路径
fileList	list of POSIX file	所有选中的文件路径列表
args / argsWithoutPaths	text	用户传入的额外参数（空格分隔）
urlArguments	text	解析后的 URL 参数
numberOfArgs	integer	参数个数

自定义脚本示例（Shell — 批量重命名）：

#!/bin/bash
# ProFind Shell Script Hook 示例
# 放在 ~/Library/Scripts/ProFind/ 下即可在 ProFind 中调用

for file in "$@"; do
    echo "处理文件: $file"
    # 替换空格为下划线
    newname=$(echo "$(basename "$file")" | sed 's/ /_/g')
    dir=$(dirname "$file")
    if [ "$newname" != "$(basename "$file")" ]; then
        mv "$file" "$dir/$newname"
        echo "重命名为: $newname"
    fi
done

自定义脚本示例（AppleScript — 发送邮件）：

-- 放在 ~/Library/Scripts/ProFind/MailFilePath.scpt
-- 使用方式：在 ProFind 中选中文件 → Scripts → MailFilePath
-- 参数格式：: mail "收件人" "主题"

on open theFiles
    tell application "Mail"
        set theMessage to make new outgoing message with properties ¬
            {subject:"ProFind 文件", content:"附件文件路径:" & linefeed}
        tell theMessage
            repeat with aFile in theFiles
                set content of theMessage to ¬
                    (content of theMessage) & (POSIX path of aFile) & linefeed
            end repeat
            set visible to true
            activate
        end tell
    end tell
end open

通过 run script 执行（AppleScript 调用）：

osascript << 'EOF'
-- 调用 ProFind 的 DuckDuckGo 脚本搜索文件名
tell application "ProFind"
    open location "profind:search?name=macOS Ventura&script=duckduckgo"
end tell
EOF

---

5. open_search_window — 打开搜索窗口

打开 ProFind 主窗口，支持预填充搜索条件。

# 打开 ProFind（全新窗口）
osascript -e 'tell application "ProFind" to activate'

# 带搜索条件打开
osascript << 'EOF'
tell application "ProFind"
    activate
    open location "profind:search?name=report&kind=PDF&path=~/Documents"
end tell
EOF

# 打开并显示高级搜索面板
osascript << 'EOF'
tell application "ProFind"
    activate
    -- 打开搜索窗口后通过菜单触发高级搜索
    tell process "ProFind"
        keystroke "f" using {command down, option down}
    end tell
end tell
EOF

ProFind 快捷键：

快捷键	功能
Cmd+F	新建搜索
Cmd+O	打开选中文件
Cmd+Return	打开选中项
Space	快速预览（QLGenerator）
Cmd+Shift+G	前往路径
Cmd+,	偏好设置

---

6. query_api — Media Server HTTP API

ProFind 内置 Media Server（UPnP/DLNA 媒体服务器），运行于 端口 54812，支持 SOAP 协议搜索。

⚠️ 重要说明： Media Server 是 ProFind 搜索结果的 UPnP 暴露接口，不是独立的文件索引 API。需要先在 ProFind UI 中执行搜索，结果才会出现在 Media Server 中。

启用方式： ProFind → 偏好设置 → Media Server → 勾选启用

协议： UPnP SOAP（非 REST），需通过 SOAP Action 调用：

PORT=54812

# ① 获取搜索能力
curl -s --max-time 10 -X POST "http://localhost:$PORT/ContentDirectory/control" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPACTION: "urn:schemas-upnp-org:service:ContentDirectory:1#GetSearchCapabilities"' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <s:Body>
    <u:GetSearchCapabilities xmlns:u="urn:schemas-upnp-org:service:ContentDirectory:1"/>
  </s:Body>
</s:Envelope>'

# ② 搜索文件（dc:title = 文件名）
curl -s --max-time 15 -X POST "http://localhost:$PORT/ContentDirectory/control" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPACTION: "urn:schemas-upnp-org:service:ContentDirectory:1#Search"' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <s:Body>
    <u:Search xmlns:u="urn:schemas-upnp-org:service:ContentDirectory:1">
      <ContainerID>0</ContainerID>
      <SearchCriteria>(dc:title contains "keyword")</SearchCriteria>
      <SortCriteria></SortCriteria>
    </u:Search>
  </s:Body>
</s:Envelope>'

# ③ 浏览目录结构
curl -s --max-time 10 -X POST "http://localhost:$PORT/ContentDirectory/control" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPACTION: "urn:schemas-upnp-org:service:ContentDirectory:1#Browse"' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <s:Body>
    <u:Browse xmlns:u="urn:schemas-upnp-org:service:ContentDirectory:1">
      <ObjectID>0</ObjectID>
      <BrowseFlag>BrowseDirectChildren</BrowseFlag>
      <Filter>*</Filter>
      <StartingIndex>0</StartingIndex>
      <RequestedCount>20</RequestedCount>
      <SortCriteria></SortCriteria>
    </u:Browse>
  </s:Body>
</s:Envelope>'

SOAP Action 速查：

Action	说明	端口
GetSearchCapabilities	获取支持的元数据字段	54812
Search	按文件名/元数据搜索	54812
Browse	浏览索引目录结构	54812

---

使用模式

模式一：Shell 脚本封装（推荐）

所有搜索操作通过 osascript + URL Scheme 执行：

profind_search() {
    local query="$1"
    local kind="${2:-}"
    local path="${3:-}"
    
    local url="profind:search?name=${query}"
    [ -n "$kind" ] && url="${url}&kind=${kind}"
    [ -n "$path" ] && url="${url}&path=${path}"
    
    osascript -e "tell application \"ProFind\" to open location \"$url\"" &
}

模式二：AppleScript 脚本

处理 ProFind 脚本钩子：

cat > ~/Library/Scripts/ProFind/MyScript.scpt << 'APPLESCRIPT'
on open theFiles
    repeat with aFile in theFiles
        -- 处理每个文件
        do shell script "echo " & (POSIX path of aFile)
    end repeat
end open
APPLESCRIPT

---

完整示例

示例 1：搜索近一个月修改的 PDF 报告

profind_search() {
    local query="$1"
    local url="profind:search?name=${query}&kind=PDF&date=modified:~month"
    osascript -e "tell application \"ProFind\" to open location \"$url\""
}
profind_search "report"

示例 2：搜索大于 10MB 的视频文件

osascript << 'EOF'
tell application "ProFind"
    activate
    open location "profind:search?name=*&kind=movie&size=larger:10MB&scope=all"
end tell
EOF

示例 3：搜索代码仓库中的 Swift 文件（排除 node_modules）

osascript << 'EOF'
tell application "ProFind"
    activate
    open location "profind:search?name=*.swift&path=/Users/Admin/Projects&exclude:/Users/Admin/Projects/node_modules"
end tell
EOF

示例 4：带脚本钩子的搜索（批量操作）

# 先用 Spotlight 快速定位，再用脚本批量处理
osascript << 'EOF'
tell application "ProFind"
    activate
    open location "profind:search?name=*.log&size=larger:1MB&path=/Users/Admin"
end tell
EOF
# 用户在 ProFind 界面中选择文件 → Scripts → "Move To Trash" 批量删除

---

错误处理

错误	原因	解决方案
Application isn't running	ProFind 未安装/启动	open /Applications/ProFind.app
URL could not be opened	URL Scheme 格式错误	检查 profind: 参数格式
Permission denied	权限不足	系统偏好设置 → 隐私与安全性 → 完全磁盘访问
No results	Spotlight 索引为空	运行 mdutil -s / 重建索引
Script error	脚本钩子执行失败	检查脚本语法和参数

---

系统要求

• macOS 10.14+
• ProFind 1.0+（App Store 下载）
• 完全磁盘访问权限（系统偏好设置 → 隐私与安全性 → 完全磁盘访问）
  • ProFind 需要此权限才能搜索系统文件夹

---

相关文件路径

文件	路径
ProFind 应用	/Applications/ProFind.app
示例脚本	/Applications/ProFind.app/Contents/Resources/Sample Scripts/
用户脚本	~/Library/Scripts/ProFind/
偏好设置	~/Library/Preferences/com.zeroonetwenty.ProFind.plist
日志	~/Library/Logs/ProFind/
索引数据库	~/.ProFind/

---

快捷命令（CLI 封装）

# 在 ~/.zshrc 中添加 alias：
alias profind='open -a ProFind'
alias profind-search='profind_search'  # 见上方函数定义'