Agent 工具速查
Nephele 的 Agent 是一个工具调用循环（Tool-calling Loop）：理解你的需求 → 选择合适的工具 → 执行 → 根据结果继续推理，直到任务完成。当前版本约有 66 个已注册工具，进入 Cloud MAX 模式后再增加 cloud_search、delegate_tasks 两个云端专属工具。工具按需动态加载——初始只发核心工具，其余在你需要时由 tool_search 拉取。
你不需要记住这些。Agent 会根据你的自然语言描述自动选择工具。这份速查表面向想深入理解 Nephele 工作原理、或编写 Skill 时引用工具名的进阶用户。
搜索与参考
| 工具名 | 用途 | 关键参数 |
|---|
find_references | 跨平台搜索参考图，来源覆盖 Pixiv / Konachan / Pinterest / 花瓣 / ArtStation / Wikimedia / 本地 Eagle | keywords 搜索词, site 指定站点, sources 来源过滤（默认只搜 Eagle，联网源需显式开启） |
eagle_search | 在 Eagle 资源库内搜索素材 | keyword 关键词, ext 扩展名, tags 标签数组, star 评分, folders 文件夹, limit 数量 |
find_similar_by_image | 以图搜相似图（本地 Eagle，EVA02 tagger 嵌入） | image_path 本地图片路径, eagle_id Eagle 素材 ID（二选一）, top_k 返回数量 |
find_by_text | 文搜图：一句英文描述在 Eagle 里找视觉最接近的参考（CLIP 文-图空间） | query 英文描述（必填）, top_k 返回数量（默认 30，最多 60） |
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 把它拆成多个子任务。默认只搜本地 Eagle，联网来源（Pixiv 等）需要在 sources 里显式开启。show_reference_picker 通常在 browser_extract(type="images") 之后调用，图片列表自动从浏览器缓存读取。
信息获取
| 工具名 | 用途 | 关键参数 |
|---|
web_fetch | 获取网页内容并转为 Markdown | url 目标地址, extract_images 是否提取页面图片 |
cloud_search | 云端时效性搜索（新闻/价格/近期事件，Cloud MAX 模式） | query 关键词 |
download_url | 下载 URL 文件到本地缓存 | url 下载地址, filename 可选文件名 |
补充说明：
web_fetch 有 15 分钟缓存，支持 SSL 错误自动重试。它是 Agent 主要的联网取数手段。cloud_search 仅在 Cloud MAX 模式下可用，调用 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_library_info | 获取 Eagle 库信息 | library_path 库路径, action 操作类型 |
eagle_update | 更新素材元数据（标签/评分/备注/移动文件夹） | ids 素材 ID 数组（或 item_id 单个）, tags 标签, tag_mode 模式(add/remove/replace), star 评分, annotation 备注, folder_id 文件夹 |
eagle_folder_create | 创建 Eagle 文件夹 | name 文件夹名, parent_id 父文件夹 ID（可选） |
eagle_artist_trace | 批量追溯 Eagle 素材的画师，用零成本信号（来源 URL / 文件名）回写「画师:」标签 | folder_id 文件夹, keyword 关键词, limit 数量, apply 是否写回（默认 true）, max_network 联网上限（默认 300） |
浏览器自动化
| 工具名 | 用途 | 关键参数 |
|---|
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 图片路径 |
画师与作品探索（Cloud MAX）
这组工具帮你顺着一位画师或一张作品往外探索灵感，多数走联网、属于 Cloud MAX 专属。
| 工具名 | 用途 | 关键参数 |
|---|
find_artist_works | 拉取某画师近期约 12 张作品供学习（Pixiv 优先，X 兜底），强制走来源溯源、禁止再分发 | artist_name, pixiv_user_id, twitter_handle（均可选） |
find_similar_artists | 通过 Pixiv 推荐图谱发现 12 位画风相似的画师 | artist 或 illust_url, limit（默认 12，最多 20） |
find_similar_works | 给定一张 Pixiv 作品，返回 12-18 张画风/构图相似的作品（跨画师） | illust_url（必填）, limit（默认 12，最多 18） |
wiki_art_context | 用 Wikidata 查艺术史脉络：流派、影响关系、代表作、生卒，或由流派反查代表画师 | query 或 wikidata_id |
explore_related_concepts | 用 Wikipedia 摘要 + 相关概念做灵感发散，产出新的搜索/氛围板种子 | concept（必填） |
launch_wisp_browser | 当 find_references 报告 Wisp 未连接时，拉起 Edge 并等待扩展就绪 | wait_seconds（默认 10，最多 20） |
参考板与氛围板
让 Agent 直接读写置顶参考板、自动拼氛围板。
| 工具名 | 用途 | 关键参数 |
|---|
get_board_state | 读取当前参考板：每个条目的 id、类型和可视坐标框 | 无 |
annotate_board | 往参考板追加标注：箭头/线/矩形/椭圆、文字卡，或构图叠加（三分法等，需 targetId） | annotations 标注数组 |
build_moodboard | 把一组参考拼成氛围板：视觉层级 + 提取的色卡 + 注脚，落到参考板并导出合成 PNG | eagle_ids[], image_paths[], caption, intent, board_name, target_count（默认 12） |
创作者数据与约稿市场
| 工具名 | 用途 | 关键参数 |
|---|
get_dashboard_stats | 查询创作者数据中心：library（Eagle 素材库画像）或 snapshot/history/works（各平台战绩） | action（library/snapshot/history/works）, platform, metric_key, days, sort_key, limit |
mihuashi_fetch | 拉取米画师公开数据（只读）：约稿企划 / 详情 / 市场行情 / 橱窗 | action（projects/detail/market/showcase）, query, project_id, page, max_pages（最多 5） |
发布与打包
| 工具名 | 用途 | 关键参数 |
|---|
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_evaluate/packer/eagletagger), file_path 预加载文件（可选） |
picker_context | 读取参考图选择器的精简状态（首图/选中/预览图的来源、画师、Eagle id、路径），处理选择器后续操作时优先用它 | action(summary/item/selected/preview/list), target, index, limit, offset |
request_demo | 触发软件内的分步演示/教程（仅 pilot 构建） | tool_name 演示名（如 packer_demo / first_run） |
任务管理与协调
| 工具名 | 用途 | 关键参数 |
|---|
delegate_tasks | 并行执行多个独立子任务（Cloud MAX 专属） | tasks 任务数组（每项含 description 描述和可选 tools 工具白名单） |
progress_update | 报告多步任务进度 | steps 步骤数组（每项含 name 名称和 status 状态）, title 任务标题 |
ask_user_question | 暂停循环，弹出 1-4 道选择题让用户拍板 | questions 问题数组（每题含 question、header、options、multiSelect） |
tool_search | 动态加载未激活工具的完整 Schema | query 查询（select:工具名 精确加载或关键词搜索）, max_results 数量 |
补充说明：
delegate_tasks 是 Cloud MAX 专属工具，最多支持 6 个并行子任务，单个超时 120 秒，真正并行执行。tool_search 是 Nephele 的延迟加载机制：初始只加载核心工具，需要时通过此工具动态加载其他工具的完整参数定义，节省 Token。
记忆系统
| 工具名 | 用途 | 关键参数 |
|---|
memory_write | 写入一条跨会话的持久记忆（同名覆盖） | name, type(user/workflow/project/reference/correction), description, body |
memory_load | 按名称读取某条记忆的完整内容 | name |
memory_delete | 按名称删除某条记忆 | name |
权限级别
每个工具都有权限标签，Agent 在调用前会进行校验：
| 权限 | 说明 | 代表工具 |
|---|
READ | 只读文件系统 | read_file, list_dir, grep_content |
WRITE | 读写文件 | write_file, edit_file |
NETWORK | 网络访问 | web_fetch, download_url, cloud_search, upload_web |
EXECUTE | 执行外部程序 | run_python, open_app, export_godot |
工具选择小贴士
找参考图： 直接用 find_references，不要拆词。它内部已经并行搜索多个平台（默认只搜本地 Eagle，联网源需在 sources 里开启）。
查图片出处： reverse_image_search 追查来源 → resolve_source_url 解析原始页面。
整理 Eagle： eagle_search 找出目标 → eagle_update 按 ID 批量改标签/评分/移动文件夹；想批量回填画师标签用 eagle_artist_trace。
写代码/脚本： run_python 是 Agent 的"瑞士军刀"，可以执行任何 Python 代码来处理数据、转换格式、批量重命名等。
浏览器流程： browser_navigate → browser_extract → show_reference_picker 是从网页批量收集参考图的标准链路。
最后更新 2026年6月21日·对应版本 v0.5.2-beta