im0o
6b2e167e69
One `npx skills add ssh://gitea/agent-skills/skills` now offers all five skills in a grouped multi-select list. Groups come from .claude-plugin/marketplace.json: writing-clarity, windows-tools, image-to-data. skills/ holds real copies rather than submodules or pointers. The installer clones without --recurse-submodules (git.ts:241), so a submodule directory would arrive empty, and it skips remote sources declared in a marketplace manifest (plugin-manifest.ts:89), so only in-repo paths are resolvable. Grouping applies only to skills listed explicitly under a plugin's skills array with a ./-prefixed path (plugin-manifest.ts:147-151); anything not listed falls into "Other". think-twice and teach-me share a group because teach-me's SKILL.md points at double-check.md, self-contain.md and style.md inside the think-twice directory. Installing teach-me alone leaves those pointers unresolved. Syncing from the five upstream repos is manual for now.
130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
---
|
||
name: everything-file-search
|
||
description: >
|
||
Windows 上基于 Everything 的超快速文件发现工具。用于按文件名、扩展名或路径模式定位文件和目录，适合磁盘范围大、项目很大或搜索范围不明确的场景；支持 Everything 1.4 classic IPC 和 1.5/1.5a SDK3 named-pipe IPC。只负责文件发现，不负责全文搜索或代码语义搜索。
|
||
---
|
||
|
||
# Everything 文件搜索
|
||
|
||
本 skill 用于 Windows 上的快速文件发现。它通过 bundled CLI 调用 [Everything](https://www.voidtools.com/) 的官方 SDK IPC，按文件名、路径和 Everything 查询语法定位候选文件或目录。CLI 支持 Everything 1.5/1.5a 的 SDK3 named-pipe IPC，并保留 Everything 1.4 classic IPC fallback。
|
||
|
||
它不负责：
|
||
- 全文搜索
|
||
- 代码语义搜索
|
||
- 替代 `Grep` / `Read` 的内容验证工作
|
||
|
||
如果用户要“查内容”或“找某段代码在哪”，且搜索范围很大或候选路径未知，可先用本 skill 缩小候选路径，再用 `Grep` 或 `Read` 验证。若范围很小或目标是明确的函数、类、代码片段，优先直接用 `Grep`。
|
||
|
||
CLI 的完整参数说明在 [CLI_USAGE.md](CLI_USAGE.md)。
|
||
|
||
## 何时优先使用
|
||
|
||
以下情况优先选择本 skill，而不是直接用 `Glob` 或 `rg --files`：
|
||
|
||
- 用户请求本质是“找文件”“定位路径”“where is”“locate”“search for files”。
|
||
- 项目或磁盘范围很大，遍历成本高。
|
||
- 用户不确定文件在哪个目录，搜索范围可能跨盘或跨多个项目。
|
||
- 需要先产出候选路径，再交给 `Read`、`Grep` 或其他工具继续处理。
|
||
|
||
## 何时不使用
|
||
|
||
以下情况不要优先使用本 skill：
|
||
|
||
- 用户要搜索文件内容、函数名、类名或代码语义。
|
||
- 用户只在很小的目录树内找文件，且当前仓库的 `Glob` 已经足够快。
|
||
- 用户明确要求全文搜索、正则搜索代码体、或搜索函数实现位置。
|
||
|
||
## 默认调用策略
|
||
|
||
agent 使用本 skill 时，默认按以下策略构造命令：
|
||
|
||
1. 优先调用 skill 内 bundled CLI，而不是假设命令已在 `PATH`：
|
||
```powershell
|
||
& "<skill-dir>\bin\everything-agent-find.exe" <query> [options]
|
||
```
|
||
|
||
2. 如果不确定 Everything 是否可用，先运行：
|
||
```powershell
|
||
& "<skill-dir>\bin\everything-agent-find.exe" --check
|
||
```
|
||
|
||
CLI 会自动先尝试 SDK3 main instance 和 `1.5a` instance，再回退 SDK2 classic IPC。只有需要强制指定 Everything 1.5 instance 时才使用 `--instance <name>`。
|
||
|
||
3. 只要用户请求有明确项目或目录范围，就带 `--workspace`。
|
||
|
||
4. 默认带 `--relative`，让输出结果在 workspace 内时同时给出 `relativePath`，更适合后续总结和展示。
|
||
|
||
5. 默认使用 `--files` 或 `--folders`；除非用户明确要两类结果，才同时省略。
|
||
|
||
6. 保持 `--max` 较小，通常 `20` 到 `50`。
|
||
|
||
7. 对常见噪声目录，默认建议使用 `--exclude`，例如：
|
||
- `node_modules`
|
||
- `.git`
|
||
- `dist`
|
||
- `build`
|
||
- `.venv`
|
||
|
||
8. 如果成功输出中出现 `truncated: true`，优先建议用户缩小查询范围；只在确实需要时再调大 `--limit-scan`。当 `ok: false` 时，先处理错误，不要根据 `truncated` 做范围判断。
|
||
|
||
## 推荐命令模板
|
||
|
||
```powershell
|
||
# 首选：workspace + files + relative
|
||
& "<skill-dir>\bin\everything-agent-find.exe" "*.ts" --workspace D:\project --files --relative --max 30
|
||
|
||
# 进一步排除噪声
|
||
& "<skill-dir>\bin\everything-agent-find.exe" "*.tsx" --workspace D:\project --files --relative --exclude node_modules --exclude .git --exclude dist --max 30
|
||
|
||
# 查找目录
|
||
& "<skill-dir>\bin\everything-agent-find.exe" "tests" --workspace D:\project --folders --relative --max 20
|
||
|
||
# 最近修改文件
|
||
& "<skill-dir>\bin\everything-agent-find.exe" "ext:md dm:thisweek" --workspace D:\project --files --sort modified --desc --relative
|
||
|
||
# regex 查询
|
||
& "<skill-dir>\bin\everything-agent-find.exe" "^test_.*\.ts$" --regex --workspace D:\project --files --relative --max 20
|
||
```
|
||
|
||
## 输出说明
|
||
|
||
CLI 始终向 stdout 输出 JSON。成功时主要字段包括：
|
||
|
||
- `ok`
|
||
- `results`
|
||
- `count`
|
||
- `scanned`
|
||
- `truncated`
|
||
- `elapsedMs`
|
||
|
||
每条 result 通常包含：
|
||
|
||
- `path`：绝对路径
|
||
- `relativePath`：仅在 `--relative` 且结果位于 `--workspace` 内时出现
|
||
- `type`
|
||
- `size`
|
||
- `modified`
|
||
|
||
典型错误输出：
|
||
|
||
```json
|
||
{"ok":false,"error":"ipc_unavailable","message":"Everything IPC not available. Is Everything running with the taskbar icon?","elapsedMs":3}
|
||
```
|
||
|
||
## 排查与回退
|
||
|
||
当返回 `ok: false` 或 `error: "ipc_unavailable"` 时，agent 应：
|
||
|
||
1. 告诉用户安装 Everything，或打开 Everything 桌面应用。
|
||
2. 说明需要运行的是带任务栏图标的用户进程，而不只是 Windows service。
|
||
3. 退回 `Glob`、`rg --files` 或 `Get-ChildItem -Recurse`。
|
||
4. 如果问题出现在查询构造上，可使用 `--debug-query` 检查实际发送给 Everything 的查询。
|
||
5. `--version` 只验证 CLI 和 DLL 可加载；判断 Everything IPC 是否可用必须使用 `--check`。
|
||
|
||
## 前置条件
|
||
|
||
- Windows
|
||
- 正在运行的 Everything 桌面进程
|
||
- Everything 1.5/1.5a：`Everything3_x64.dll` 与 exe 在同一目录，或设置 `EVERYTHING3_SDK_DLL`
|
||
- Everything 1.4 classic fallback：`Everything64.dll` 与 exe 在同一目录，或设置 `EVERYTHING_SDK_DLL`
|