> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具全表

> 专家可调用的全部工具及其参数签名，按插件分组

# 工具全表

这一页穷举专家在对话中可以调用的每个工具及其参数。工具是模型的**动作接口**——模型看不到工具就调不了，工具没在本轮激活就等于不存在。

阅读方式：先在 [插件全表](/zh/documentation/reference/plugins-catalog) 确认某个插件本轮是否激活，再来这里查它注入了哪些工具、参数怎么传。

<Info>
  多数工具用 **action 复用签名**（一个 `browser` 工具承载 12 个动作），而不是拆成十几个独立工具。原因是工具数量直接吃系统提示词的上下文预算，且工具越多模型选错的概率越高。代价是参数表变长且大部分参数对某个具体 action 无意义。
</Info>

## 沙箱工具（不属于任何插件）

沙箱模式非 `none` 时**始终可用**，不需要勾任何插件。这是最常被误解的一组——用户以为"没开插件就不会动文件"，实际上文件读写是基础能力。

| 工具       | 参数                                                                          | 说明                                                                                                                   |
| -------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `write`  | `file_path`（绝对路径）、`content`（默认 `""`，**不能为空**）                               | 整文件覆写                                                                                                                |
| `read`   | `file_path`、`offset`（默认 0）、`limit`（默认 **2000** 行）                           | 按行读取，超长文件自动截断                                                                                                        |
| `edit`   | `file_path`、`old_string`（**必须精确匹配**）、`new_string`、`replace_all`（默认 `false`） | 字符串替换；默认只替换第一处                                                                                                       |
| `bash`   | `command`、`timeout`（默认 **120** 秒）                                           | 执行 Shell 命令                                                                                                          |
| `grep`   | `pattern`（正则）、`path`、`include`（glob）、`max_results`（默认 **50**）               | 按内容搜索                                                                                                                |
| `glob`   | `pattern`、`path`                                                            | 按文件名搜索                                                                                                               |
| `insert` | `file_path`、`line`（**0 = 文件开头**）、`content`                                  | 在指定行后插入                                                                                                              |
| `lsp`    | `operation`、`file_path`、`line`、`character`、`query`、`paths`                  | 代码智能：`diagnostics` / `definition` / `references` / `hover` / `document_symbols` / `workspace_symbols` / `read_lints` |

<Warning>
  `edit` 的 `old_string` 必须与文件内容**逐字符精确匹配**，包括缩进和空白。模型改大文件时最常见的失败就是这里——它凭记忆拼 `old_string` 而不是先 `read`。你看到反复的 edit 失败重试，多半是这个原因。

  `lsp` 的 `read_lints` 在 `paths` 留空时，检查**本轮会话写过或改过的每个文件**。
</Warning>

### 计划模式专属

| 工具                  | 参数   | 说明                                                                 |
| ------------------- | ---- | ------------------------------------------------------------------ |
| `plan_write`        | 计划正文 | 只在 `permission_mode="plan"` 下存在。**路径不是参数**——永远覆写会话工作目录下的 `plan.md` |
| `suggest_plan_mode` | —    | 建议用户切到计划模式                                                         |

`plan_write` 的路径不可配置是刻意的：计划模式滤掉了所有写世界的工具，如果 `plan_write` 能指定路径，它立刻退化成一个通用写入口，模式隔离就破了。

## 浏览器（`profy-browser`）

| 工具        | 参数                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------- |
| `browser` | `action`、`url`、`html`、`file_path`、`selector`、`ref`、`text`、`key`、`direction`、`amount`、`tab_action` |

`action` 取值：`navigate`、`screenshot`、`snapshot`、`click`、`type`、`fill`、`scroll`、`press_key`、`tabs`、`set_html`、`evaluate`、`go_back`。

传错会拿到：

```
Error: Unknown browser action 'xxx'. Valid actions: navigate, screenshot,
snapshot, click, type, fill, scroll, press_key, tabs, set_html, evaluate, go_back
```

`ref` 是 `snapshot` 返回的元素句柄，**只对那次快照有效**。页面一变就必须重新 snapshot 取新 ref，否则点到错的元素或直接失败。

细粒度变体（`browser_click` / `browser_fill` / `browser_navigate` / `browser_press_key` / `browser_scroll` / `browser_snapshot` / `browser_tabs` / `browser_take_screenshot` / `browser_type`）在部分链路里单独暴露，参数与聚合版一致。

## Chrome 扩展（`profy-chrome`）

需要 `chrome_connected: true`。

| 工具                         | 参数                                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| `chrome`                   | `action`、`tab_id`、`url`、`selector`、`ref`、`text`、`key`、`code`、`direction`、`amount`、`full_page` |
| `chrome__match_workflow`   | 匹配已录制的工作流                                                                                     |
| `chrome__execute_workflow` | 回放工作流                                                                                         |
| `chrome__save_trajectory`  | 保存本次轨迹为工作流                                                                                    |

与 `profy-browser` 的关键差别：Chrome 操作的是**你自己的浏览器**，带你的登录态。所以它有四级权限门禁，涉及金融与账号操作一律阻断。

## 电脑操作（`profy-computer`）

需要 `desktop_connected: true`。

| 工具         | 参数                                                                                             |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `computer` | `action`、`x`、`y`、`text`、`keys`、`delivery_mode`、`path`、`direction`、`amount`、`from_x`、`from_y` 等 |

`action` 取值：`screenshot`、`click`、`double_click`、`type`、`scroll`、`drag`、`keypress`、`invoke_menu`、`move`、`wait`、`cursor_position`、`list_windows`、`get_window_state`、`launch_app`、`list_apps`、`get_accessibility_tree`、`bring_to_front`、`set_value`、`check_permissions`。

细粒度变体：`click`、`drag`、`key`、`mouse_move`、`screenshot`、`scroll`、`type_text`、`list_windows`、`get_window_state`。

`check_permissions` 值得先调一次——macOS 辅助功能权限没给的话，后面每个动作都会失败，而失败信息不一定指向权限。

## 创意生成（`profy-creative`）

自动可用，不需要勾选。

| 工具                    | 参数                                                                                                              | action                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `image`               | `action`、`prompt`、`image_urls`、`resolution`（默认 `1024x1024`）                                                     | `generate`、`generate_batch`、`read` |
| `video`               | `action`、`prompt`、`video_urls`、`resolution`（默认 `720p`）、`duration`（默认 `5.0`）、`reference_image_url`               | `generate`、`generate_batch`、`read` |
| `music`               | `action`、`prompt`、`lyrics`、`duration`（默认 `30.0`）、`is_instrumental`（默认 `true`）                                   | `generate`                         |
| `audio`               | `action`、`text`、`audio_url`、`voice_id`、`language`（默认 `zh`）                                                      | `tts`、`tts_batch`、`stt`            |
| `generate_3d_tool`    | `prompt`、`image_url`、`sketch_url`、`mode`（默认 `rapid`）、`format`（默认 `GLB`）、`face_count`、`pbr_materials`（默认 `true`） | —                                  |
| `postprocess_3d_tool` | `model_url`、`action`、`target_format`、`target_faces`、`animation_type`                                            | —                                  |
| `generate_world_tool` | `prompt`、`image_url`、`video_url`、`resolution`（默认 `512`）                                                         | —                                  |

`read` 这个 action 常被忽略：它让模型**看见已生成的图/视频**，是"生成 → 自检 → 重生成"闭环的关键一步。缺了它模型只能凭 prompt 想象产出效果。

计费按 [计费公式](/zh/documentation/reference/billing-formulas) 的 `per_call` 或 `duration_second` 计。

## 搜索（`profy-search`）

需要 `enable_web_search: true`。

| 工具           | 参数      |
| ------------ | ------- |
| `web_search` | `query` |
| `web_fetch`  | `url`   |

签名极简是有意的：搜索结果必须在返回前做**单条内容截断 + 结果数上限**，参数放开会让并行多次搜索直接把上下文打爆。

## 记忆（`profy-memory`）

需要 `enable_memory: true`。

| 工具       | 参数                                                                                |
| -------- | --------------------------------------------------------------------------------- |
| `memory` | `action`、`content`、`query`、`memory_type`、`scope`、`k`（默认 5）、`entity`、`depth`（默认 1） |

| action    | 必填               | 作用                |
| --------- | ---------------- | ----------------- |
| `add`     | `content`        | 写入长期记忆            |
| `search`  | `query`          | 检索相关记忆            |
| `explore` | `entity`         | 从某个实体出发遍历记忆图谱     |
| `dream`   | `scope="expert"` | 整理专家记忆（合并重复、归档陈旧） |

`memory_type` 取值：`preference`、`fact`、`skill`、`habit`、`event`、`context`、`constraint`、`decision`、`entity`。
`scope` 取值：`user`（个人）、`expert`（该专家专属）。

传错 action 会拿到：

```
❌ Invalid action 'xxx'. Must be 'add', 'search', 'explore', or 'dream'.
```

<Warning>
  开发者平台的终端用户（通过 `/v1/*` API 调用）**整个工具被拒绝**。原因是记忆按平台用户隔离，终端用户不是平台身份，写进去会串号。
</Warning>

## 知识库（`profy-knowledge`）

| 工具                   | 参数                                                                               | action                                                            |
| -------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `knowledge`          | `action`、`query`、`platform`、`source_id`、`doc_id`、`title`、`content`、`top_k`（默认 5） | `search`、`list_sources`、`list_documents`、`read`、`create`、`append` |
| `obsidian_knowledge` | `action`、`query`、`vault_path`、`source_id`、`top_k`（默认 10）                         | 同上（本地 Vault）                                                      |

`platform` 留空时**搜索全部已连接平台**。写操作（`create` / `append`）取决于该平台适配器是否实现，未实现会明确报能力不支持而不是静默失败。

## 技能（`profy-skill`）

| 工具             | 参数                                                                      | action                                                           |
| -------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `skill`        | `action`、`name`、`tag`、`resource_type`、`resource_name`、`script_args`     | `discover`、`activate`、`execute`                                  |
| `skill_manage` | `action`、`name`、`source`、`content`、`description`、`target_expert`、`path` | `catalog`、`install`、`install_batch`、`save_dir`、`create`、`update` |

`name` 用限定名：`builtin/docx`、`user/nuwa`、`expert/my-skill`。裸名在不冲突时自动解析。

`execute` 的 `resource_type` 取 `script` / `reference` / `asset` / `template` / `workflow`。**脚本是黑盒执行**——只回 stdout/stderr，源码不进上下文。这是刻意的：技能脚本动辄几百行，全塞进去会挤掉真正要处理的数据。

## 委托与调度

| 工具         | 参数                                                                                                                                           | 归属                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `delegate` | `expert_identifier`、`task`、`timeout`                                                                                                         | `profy-delegation`（需 `available_specialists`） |
| `schedule` | `action`、`title`、`prompt`、`task_type`、`scheduled_date`、`scheduled_time`、`repeat_type`、`timezone`、`depends_on`、`dependency_strategy`、`status` | `profy-schedule`                              |

`schedule` 的 action 只有 `add` 与 `search`：

* `add` 必填 `title` + `prompt` + `scheduled_date`（ISO，如 `2025-03-15`）+ `scheduled_time`（`HH:MM`）
* `repeat_type`：`no-repeat` / `daily` / `weekly` / `monthly`
* `dependency_strategy`：前置任务失败时 `skip` 或 `continue`
* `search` 的 `status` 过滤：`pending` / `running` / `completed` / `paused` / `all`

传错 action：`❌ Invalid action 'xxx'. Must be 'add' or 'search'.`

**没有 delete / update**。改定时任务要去产品界面，不能靠对话。

`delegate` 默认**分离执行**（detached）——发出去就不阻塞当前对话。

## 人机交互（`profy-message`）

| 工具    | 参数                              |
| ----- | ------------------------------- |
| `Ask` | `questions: List[dict]`、`title` |

专家需要你做选择时调它，前端渲染成选择卡片。这是**唯一**能中断执行等你回答的机制。

## 建站（`profy-sites`）

需要 `sandbox_mode != none`。

| 工具             | 参数                                                                                                                 | 说明                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `open_preview` | `title`（默认 `Website Preview`）、`template`                                                                           | 启动预览（懒启动 dev server）                               |
| `deploy`       | `slug`（3–63 位小写字母/数字/短横线）、`summary`                                                                                | **只是请求部署的信号**，返回 `awaiting_confirmation`，无构建与上传副作用 |
| `site_design`  | `mode`（`direction_selection` / `asset_authorization`）、`brief_summary`（1–4000 字符）、`directions`（恰好 3 个）、`asset_plan` | 设计方向确认                                             |
| `site_assets`  | `items`                                                                                                            | 素材写入；≤2MB 写沙箱返回 `path`，>2MB 或本地额度用尽走 COS 返回 `url`  |
| `browser`      | 同上                                                                                                                 | 预览自检                                               |

<Warning>
  `deploy` **不会发布**。真正的发布唯一入口是 UI 上的部署弹窗。专家调 `deploy` 只是把请求推给你确认——这是刻意的单向门，避免专家自作主张上线。
</Warning>

## 可视化（`profy-visualize`）

| 工具           | 参数                                                                                   |
| ------------ | ------------------------------------------------------------------------------------ |
| `visualize`  | `title`、`html`、`css`                                                                 |
| `render_ui`  | `components: list[dict]`、`surface_id`                                                |
| `inspect_3d` | `url`、`max_depth`（默认 5）、`include_materials`、`include_animations`、`performance_audit` |

## 画布（`profy-canvas`）

| 工具                            | 关键参数                                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canvas_node_operation`       | `action`（`create`/`update`/`delete`/`duplicate`）、`node_type`（`text`/`image`/`imageEdit`/`video`/`storyboard`）、`node_ids`、`label`、`config`、`position`、`remix_from_node_id`、`parent_id` |
| `canvas_connection_operation` | `action`（`connect`/`disconnect`/`reconnect`）、`source_node_id`、`target_node_id`、`edge_id`、`connections`                                                                                |
| `canvas_run_dag`              | `node_id`、`concurrency`（默认 **1，串行**）                                                                                                                                                  |
| `canvas_get_nodes`            | `filter_type`、`label`                                                                                                                                                                 |
| `canvas_auto_layout`          | `scope`（`canvas`/`topLevelGroups`/`group`）、`target_group_id`、`focus_node_id`                                                                                                          |

`concurrency` 默认 1 是保守选择——并发跑 DAG 会同时触发多个计费生成任务。

## 视频制作（`profy-movie`）

`exclusive: true`，开启时其他插件不加载。

| 工具              | 参数                     |
| --------------- | ---------------------- |
| `movie`         | `action`、`data`（结构化载荷） |
| `timeline_edit` | `action`、`params`      |

`movie` 的 action 是流水线阶段：`brief` → `script` → `storyboard` → `strategy` → `assemble` → `caption` → `export`。
`timeline_edit` 的 action：`insert_clip`、`remove_clip`、`trim`、`split` 等。

## 飞书（`profy-feishu`）

需要 `has_feishu_client: true`。

| 工具                    | 覆盖       |
| --------------------- | -------- |
| `feishu_tool`         | 日历、任务、日程 |
| `feishu_doc_tool`     | 文档读写     |
| `feishu_bitable_tool` | 多维表格     |

写操作需要用户授权，未授权时返回授权标记引导你发 `/auth`。详见 [飞书工具集](/zh/documentation/plugins/feishu-tools)。

## 报关（`profy-customs`）

| 工具                    | 参数                                                     |
| --------------------- | ------------------------------------------------------ |
| `customs_ocr`         | `file_url`、`pages`（默认 `all`）                           |
| `customs_code_lookup` | `table`、`query`、`direction`（默认 `name_to_code`）、`fuzzy` |
| `customs_validate`    | `fields_json`                                          |

## 录制回放（`profy-record-and-replay`）

需要 `desktop_connected: true`。

| 工具                                                                 | 参数  |
| ------------------------------------------------------------------ | --- |
| `event_stream_start` / `event_stream_stop` / `event_stream_status` | 无参数 |

## 蒸馏与进化（内部）

| 工具               | 归属                                            | 可见性                |
| ---------------- | --------------------------------------------- | ------------------ |
| `distill_manage` | `profy-distill`（需 `target_expert_identifier`） | 仅蒸馏对话              |
| `evolution_log`  | `profy-evolution`（需 `is_internal_invoke`）     | 仅平台内部调用，**外部无法触发** |

`evolution_log` 的参数：`action`（只能是 `suggest_skill_improvement`）、`skill_name`、`summary`、`diff_summary`、`improved_content`、`before_scores`、`after_scores`、`improved_dimensions`。评分规则见 [自进化](/zh/documentation/how-it-works/darwin-evolution)。

## 四个 office 插件没有工具

`profy-docx` / `profy-pdf` / `profy-pptx` / `profy-xlsx` 的 manifest 里 tools 为空。它们通过技能文档 + 沙箱预装库工作，专家用 `bash` 执行脚本。查具体方法见各自单页。

## 相关页面

<CardGroup cols={2}>
  <Card title="插件全表" icon="puzzle-piece" href="/zh/documentation/reference/plugins-catalog">
    哪些工具本轮会被激活
  </Card>

  <Card title="技能目录" icon="book" href="/zh/documentation/reference/skills-catalog">
    工具之外的方法层
  </Card>

  <Card title="限额表" icon="gauge" href="/zh/documentation/reference/limits">
    超时、条数、体积上限
  </Card>

  <Card title="计费公式" icon="calculator" href="/zh/documentation/reference/billing-formulas">
    工具调用怎么计费
  </Card>
</CardGroup>

<Note>
  核对日期 2026-08-11。来源：`services/agent-runtime/src/base/tools/sandbox.py`、`services/agent-runtime/src/plugins/builtin/*/tools/*.py`。默认值直接取自各工具的 `Field(default=...)`。
</Note>