Agent 工具速查
Nephele 的 Agent 是一个工具调用循环（Tool-calling Loop）：理解你的需求 → 选择合适的工具 → 执行 → 根据结果继续推理，直到任务完成。以下是当前版本中 53 个已注册工具的完整清单，覆盖 core/agent_tools/ 下全部工具文件。
你不需要记住这些。Agent 会根据你的自然语言描述自动选择工具。这份速查表面向想深入理解 Nephele 工作原理、或编写 Skill 时引用工具名的进阶用户。
搜索与参考
| 工具名 | 用途 | 关键参数 |
|---|---|---|
find_references | 跨平台搜索参考图（Pixiv + Eagle + Pinterest 并行） | keywords 搜索词, site 指定站点, sources 来源过滤 |
eagle_search | 在 Eagle 资源库内搜索素材 | keyword 关键词, ext 扩展名, tags 标签数组, star 评分, folders 文件夹, limit 数量 |
find_similar_by_image | 以图搜相似图 | image_path 本地图片路径, eagle_id Eagle 素材 ID（二选一）, top_k 返回数量 |
search_files | 按 Glob 模式搜索本地文件 | pattern 匹配模式, path 搜索目录, max_results 上限, offset 分页偏移 |
reverse_image_search | 反向图片搜索（追查图片来源） | image_path 图片路径, mode 模式（默认/resolve） |
resolve_source_url | 解析图片原始出处 URL | url 待解析的链接 |
show_reference_picker | 弹出参考图选择器（供用户挑选和钉图） | source_page 来源页面 URL（可选） |
补充说明：
find_references内部已经并行搜索多个平台，不要用delegate_tasks把它拆成多个子任务。show_reference_picker通常在browser_extract(type="images")之后调用，图片列表自动从浏览器缓存读取。
信息获取
| 工具名 | 用途 | 关键参数 |
|---|---|---|
web_search | 互联网搜索（Bing 优先，DuckDuckGo 备选） | query 关键词, max_results 数量（默认 5，最多 10） |
web_fetch | 获取网页内容并转为 Markdown | url 目标地址, extract_images 是否提取页面图片 |
cloud_search | 云端时效性搜索（新闻/价格/近期事件，CloudMAX 模式） | query 关键词 |
download_url | 下载 URL 文件到本地缓存 | url 下载地址, filename 可选文件名 |
补充说明：
web_fetch有 15 分钟缓存，支持 SSL 错误自动重试。cloud_search仅在 CloudMAX 模式下可用，调用 Nephele API 的 grounding 搜索。
文件系统
| 工具名 | 用途 | 关键参数 |
|---|---|---|
read_file | 读取文件内容 | path 文件路径, offset 起始行, limit 最大行数 |
write_file | 写入文件 | path 路径, content 内容, append 是否追加 |
edit_file | 编辑文件（查找替换） | path 路径, old_text 原文, new_text 新文本, replace_all 是否全部替换 |
list_dir | 列出目录内容 | path 目录路径, show_hidden 是否显示隐藏文件 |
grep_content | 在文件内容中搜索文本/正则 | pattern 搜索内容, path 目录, glob_filter 文件过滤, max_results 上限, context_lines 上下文行数 |
安全限制： 所有文件操作受白名单约束，无法访问系统敏感目录。grep_content 自动跳过二进制文件和大于 1MB 的文件。
Eagle 资源库管理
| 工具名 | 用途 | 关键参数 |
|---|---|---|
eagle_import | 导入文件到 Eagle | path 文件路径, name 名称, tags 标签数组, folder_id 目标文件夹, annotation 备注 |
eagle_auto_tag | 搜索素材并批量自动打标签 | keyword 关键词, ext 扩展名, tags 要添加的标签, folder_id 文件夹, limit 数量, apply_star 是否评分 |
eagle_library_info | 获取 Eagle 库信息 | library_path 库路径, action 操作类型 |
eagle_update | 更新素材元数据（标签/评分/备注） | ids 素材 ID 数组（或 item_id 单个）, tags 标签, tag_mode 模式(add/remove/replace), star 评分, annotation 备注, folder_id 文件夹 |
eagle_organize | 搜索并批量整理素材 | keyword 关键词, tags_filter 标签过滤, ext 扩展名, action 操作(add_tags/remove_tags/move_to_folder/trash), tags 标签, folder_id 文件夹, limit 数量 |
eagle_folder_create | 创建 Eagle 文件夹 | name 文件夹名, parent_id 父文件夹 ID（可选） |
eagle_tag_manage | 管理标签（重命名/合并/列表） | action 操作(list/rename/merge), old_name 原标签, new_name 新标签 |
浏览器自动化
| 工具名 | 用途 | 关键参数 |
|---|---|---|
browser_navigate | 导航到指定 URL | url 地址, timeout 超时秒数 |
browser_action | 执行浏览器动作 | action 动作(click/fill/scroll/hover/screenshot), ref_id 元素标识, text 填充文本, direction 滚动方向 |
browser_snapshot | 获取当前页面快照 | interactive_only 仅交互元素, annotated 是否标注 |
browser_extract | 提取页面内容 | type 类型(images/links/text), min_size 图片最小尺寸 |
AI 评估与分析
| 工具名 | 用途 | 关键参数 |
|---|---|---|
evaluate_image | AI 多维度评估图片质量 | image_path 图片路径, custom_prompt 自定义评估维度, style_description 风格描述, work_category 作品类别 |
analyze_style | 分析画风基因（StyleDNA） | image_path 图片路径 |
detect_ai | 鉴别图片是否由 AI 生成 | image_path 图片路径 |
发布与打包
| 工具名 | 用途 | 关键参数 |
|---|---|---|
pack_image | 打包交付文件（加水印/裁剪/格式转换） | input_path 输入路径, watermark_path 水印路径, output_dir 输出目录, watermark_mode 水印模式 |
generate_publish_package | 生成多平台发布包 | image_path 图片路径, platforms 目标平台数组 |
generate_copy | 生成社交媒体文案 | image_path 图片路径, custom_prompt 自定义提示 |
upload_web | 上传 Godot Web 导出到 play.arisfusion.com | export_dir 导出目录（含 index.html）, project_name 项目名 |
工程处理
| 工具名 | 用途 | 关键参数 |
|---|---|---|
clean_psd | 清洗 PSD 文件（去空图层/隐藏图层） | file_path 文件路径, remove_hidden 删除隐藏图层, remove_empty 删除空图层 |
export_godot | 导出 Godot 项目为 exe 或 Web | project_path 项目目录, format 格式(exe/web), output_path 输出路径（可选） |
确权与存证
| 工具名 | 用途 | 关键参数 |
|---|---|---|
timestamp_files | 为文件生成可信时间戳 | file_paths 文件路径数组, output_dir 输出目录 |
verify_timestamp | 验证时间戳证书 | file_path 证书路径 |
protect_works | 作品维权保护流程 | file_paths 作品路径数组, author_name 作者名, output_dir 输出目录 |
系统与通用
| 工具名 | 用途 | 关键参数 |
|---|---|---|
run_python | 执行 Python 代码 | code 代码字符串, script_path 脚本路径（二选一）, description 描述 |
open_app | 打开外部应用程序 | name 应用名称 |
open_url | 在系统浏览器中打开网页 | url 网址 |
open_path | 打开文件夹或文件 | path 文件或文件夹路径 |
UI 控制（内部）
这组工具让 Agent 能够直接操作 Nephele 自身的界面，用户可以在屏幕上实时看到界面变化。
| 工具名 | 用途 | 关键参数 |
|---|---|---|
ui_navigate | 切换界面视图 | view 视图名 |
ui_set_field | 设置界面元素属性 | object_name 元素名, property 属性, value 值 |
ui_click | 点击界面按钮 | object_name 元素名 |
ui_read_state | 读取界面状态 | object_name 元素名, property 属性 |
ui_wait_for | 等待界面状态变化 | object_name 元素名, property 属性, expected 期望值, timeout 超时（秒） |
navigate_to_tool | 打开软件内置工具页面 | tool_name 工具名(ai_detect/ai_copywrite/ai_evaluate/cleaner/packer), file_path 预加载文件（可选） |
任务管理与协调
| 工具名 | 用途 | 关键参数 |
|---|---|---|
delegate_tasks | 并行执行多个独立子任务 | tasks 任务数组（每项含 description 描述和可选 tools 工具白名单） |
progress_update | 报告多步任务进度 | steps 步骤数组（每项含 name 名称和 status 状态）, title 任务标题 |
tool_search | 动态加载未激活工具的完整 Schema | query 查询（select:工具名 精确加载或关键词搜索）, max_results 数量 |
补充说明：
delegate_tasks最多支持 6 个并行子任务，单个超时 120 秒。CloudMAX 模式下真正并行，本地模式串行执行。tool_search是 Nephele 的延迟加载机制：初始只加载核心工具，需要时通过此工具动态加载其他工具的完整参数定义，节省 Token。
用户体验
| 工具名 | 用途 | 关键参数 |
|---|---|---|
memory_update | 记住用户偏好设置 | key 偏好类别, value 具体内容 |
权限级别
每个工具都有权限标签，Agent 在调用前会进行校验：
| 权限 | 说明 | 代表工具 |
|---|---|---|
READ | 只读文件系统 | read_file, list_dir, grep_content |
WRITE | 读写文件 | write_file, edit_file |
NETWORK | 网络访问 | web_search, web_fetch, download_url, upload_web |
EXECUTE | 执行外部程序 | run_python, open_app, export_godot |
工具选择小贴士
找参考图： 直接用 find_references，不要拆词。它内部已经并行搜索 Pixiv + Eagle + Pinterest。
查图片出处： reverse_image_search 追查来源 → resolve_source_url 解析原始页面。
整理 Eagle： eagle_organize 适合"搜索+批量操作"的一站式整理；eagle_update 适合已知 ID 的精确更新。
写代码/脚本： run_python 是 Agent 的"瑞士军刀"，可以执行任何 Python 代码来处理数据、转换格式、批量重命名等。
浏览器流程： browser_navigate → browser_extract → show_reference_picker 是从网页批量收集参考图的标准链路。