zk-data-agent/docs/data_agent_tool_inventory.md

# Data Agent 工具清单

本文档是当前 `claw-code-agent` 工具能力面的工作清单，用于未来的数据 Agent 改造。

范围：

* 源注册表：`src.agent_tools.default_tool_registry()`
* 工具形态：`AgentTool(name, description, parameters, handler)`
* 运行时执行：模型输出 `tool_calls`，随后 `LocalCodingAgent` 执行匹配的 handler，并把结果作为 tool message 写回。

## 当前工具生命周期

1. `default_tool_registry()` 构建基础注册表。
2. 在 `LocalCodingAgent.__post_init__` 阶段，可能会把插件别名和虚拟工具合并进注册表。
3. 每个 `AgentTool` 会通过 `to_openai_tool()` 转换成 OpenAI 兼容的 function schema。
4. 模型接收 `messages` 和 `tool_specs`。
5. 如果模型返回 `tool_calls`，运行时会执行每个指定名称的工具。
6. 工具 handler 接收 `(arguments, ToolExecutionContext)`。
7. handler 返回字符串，或返回 `(content, metadata)`。
8. 运行时序列化结果，并把它作为 `role="tool"` 的消息追加进去，供下一轮模型调用使用。

## Data-Agent 处置标记说明

* `Keep`：适合首版 data-agent MVP 使用。
* `Candidate`：可能有用，但应只在具体数据工作流需要时启用。
* `Wrap`：能力有用，但应该通过数据专用工具名或更窄的 schema 暴露。
* `Defer`：首版 data-agent MVP 暂不需要。
* `Disable`：对首版 data-agent MVP 来说太宽泛，或过于面向代码。
* `Special`：由 agent loop 特殊处理，不是普通业务工具。

## 工作区与文件工具

| 工具              | 当前描述                                                    | Data-Agent 处置 | 备注                                              |
| --------------- | ------------------------------------------------------- | ------------- | ----------------------------------------------- |
| `list_dir`      | 列出 workspace 路径下的文件和目录。                                 | Keep          | 用于任务工作区检查。                                      |
| `read_file`     | 读取 workspace 内 UTF-8 文本文件内容。                            | Keep          | Markdown 优先流程和 artifact 读取的核心工具。                |
| `write_file`    | 在 workspace 内完整写入文件；必要时创建父目录。                           | Keep          | 用于 `goal.md`、memory 文件、报告、JSONL artifact。需要写权限。 |
| `edit_file`     | 使用精确字符串匹配替换 workspace 文件中的文本。                           | Keep          | 适合增量更新 memory / artifact。                       |
| `notebook_edit` | 通过替换或追加 source 来编辑 `.ipynb` 文件中的 Jupyter notebook cell。 | Defer         | data-agent MVP 应优先使用 Markdown、JSONL、CSV 和报告。    |
| `glob_search`   | 在 workspace 内查找匹配 glob pattern 的文件。                     | Keep          | 用于发现任务文件和 skill 文件。                             |
| `grep_search`   | 在 workspace 文件中搜索字符串或正则表达式。                             | Keep          | 用于本地标签定义、历史笔记和 skill 查找。                        |

## Shell 与代码智能工具

| 工具     | 当前描述                      | Data-Agent 处置 | 备注                                      |
| ------ | ------------------------- | ------------- | --------------------------------------- |
| `bash` | 在 workspace 内运行 shell 命令。 | Disable       | 对 data-agent MVP 来说过于宽泛。优先使用专用数据工具和校验器。 |
| `LSP`  | 使用本地 LSP 风格的代码智能能力。       | Disable       | 面向代码的能力；数据任务不需要。                        |

## Web 与搜索工具

| 工具                         | 当前描述                            | Data-Agent 处置 | 备注                                       |
| -------------------------- | ------------------------------- | ------------- | ---------------------------------------- |
| `web_fetch`                | 从 HTTP、HTTPS 或 file URL 获取文本资源。 | Defer         | 可能用于文档读取，但不是核心数据工作流。                     |
| `search_status`            | 显示本地搜索运行时摘要。                    | Candidate     | 仅当在线 session / 搜索 provider 被建模为搜索运行时时有用。 |
| `search_list_providers`    | 列出已配置的本地搜索 provider。            | Candidate     | 同上。                                      |
| `search_activate_provider` | 设置当前激活的本地搜索 provider。           | Defer         | 属于配置动作，不应是普通 agent 任务行为。                 |
| `web_search`               | 通过已配置后端执行真实 Web 搜索。             | Defer         | 外部 Web 搜索不同于内部数据挖掘。                      |
| `tool_search`              | 搜索当前激活的工具注册表。                   | Keep          | 在工具面持续演进时有用。之后进入严格生产模式可以移除。              |
| `sleep`                    | 暂停执行一小段时间。                      | Defer         | 适合轮询，但在存在异步任务之前不需要。                      |

## 人工评审与决策工具

| 工具                  | 当前描述                         | Data-Agent 处置 | 备注             |
| ------------------- | ---------------------------- | ------------- | -------------- |
| `ask_user_question` | 向本地 ask-user runtime 请求用户回答。 | Keep          | 对边界澄清和人工裁决很重要。 |

## 账号与配置工具

| 工具                      | 当前描述                                 | Data-Agent 处置 | 备注                                |
| ----------------------- | ------------------------------------ | ------------- | --------------------------------- |
| `account_status`        | 显示本地账号运行时摘要。                         | Candidate     | 如果数据系统需要账号 profile，会有用。           |
| `account_list_profiles` | 列出已配置的本地账号 profile。                  | Candidate     | 用于调试访问配置。                         |
| `account_login`         | 激活本地账号 profile 或临时身份。                | Defer         | 不应出现在常规自主数据任务循环里。                 |
| `account_logout`        | 清空当前激活账号 session 状态。                 | Defer         | 运维动作。                             |
| `config_list`           | 列出合并后的或特定来源的 workspace 配置 key。       | Candidate     | 用于检查 data-agent 配置。               |
| `config_get`            | 通过 dotted key path 读取 workspace 配置值。 | Candidate     | 用于 data-agent policy / config 查询。 |
| `config_set`            | 写入 workspace 配置值。                    | Disable       | 配置变更应由人控制。                        |

## MCP 工具

| 工具                   | 当前描述                            | Data-Agent 处置 | 备注                                                                      |
| -------------------- | ------------------------------- | ------------- | ----------------------------------------------------------------------- |
| `mcp_list_resources` | 列出本地 MCP resources。             | Candidate     | 适合 skill / resource 发现或内部文档读取。                                          |
| `mcp_read_resource`  | 通过 URI 读取本地 MCP resource。       | Candidate     | 如果标签、策略或历史决策以 resource 形式暴露，会有用。                                        |
| `mcp_list_tools`     | 列出已配置 MCP server 暴露的 MCP tools。 | Candidate     | 用于发现数据系统工具。                                                             |
| `mcp_call_tool`      | 调用已配置 MCP server 暴露的 MCP tool。  | Wrap          | 这是强大的通用桥接能力。常规 agent 使用时，应优先使用 `search_online_sessions` 这类数据专用 wrapper。 |

## Remote、Worktree、Workflow 与 Trigger 工具

| 工具                     | 当前描述                             | Data-Agent 处置 | 备注                                |
| ---------------------- | -------------------------------- | ------------- | --------------------------------- |
| `remote_status`        | 显示本地 remote 运行时摘要。               | Defer         | 运维相关。                             |
| `remote_list_profiles` | 列出已配置的本地 remote profile。         | Defer         | 运维相关。                             |
| `remote_connect`       | 激活本地 remote target / profile。    | Disable       | 对 data-agent 自主模式来说过于宽泛。          |
| `remote_disconnect`    | 清空当前激活 remote connection。        | Disable       | 运维变更。                             |
| `worktree_status`      | 显示当前受管 git worktree session 状态。  | Disable       | 面向代码。                             |
| `worktree_enter`       | 创建并进入隔离 git worktree。            | Disable       | 面向代码。                             |
| `worktree_exit`        | 离开当前受管 worktree session。         | Disable       | 面向代码。                             |
| `workflow_list`        | 列出本地 workflow 定义。                | Candidate     | 如果数据 pipeline 以 workflow 表示，可能有用。 |
| `workflow_get`         | 显示某个本地 workflow 定义。              | Candidate     | 同上。                               |
| `workflow_run`         | 记录并渲染一次 workflow 执行请求。           | Wrap          | 应变成明确的数据动作，而不是任意 workflow 执行。     |
| `remote_trigger`       | 列出、查看、创建、更新或运行本地 remote trigger。 | Defer         | 更偏自动化，首版 data-agent MVP 暂不需要。     |

## Planning、Task、Team 与后台工具

| 工具              | 当前描述                          | Data-Agent 处置 | 备注                                     |
| --------------- | ----------------------------- | ------------- | -------------------------------------- |
| `plan_get`      | 显示当前本地运行时 plan。               | Candidate     | 对结构化长周期数据任务有用。                         |
| `update_plan`   | 替换当前运行时 plan。                 | Candidate     | 有用，但不能替代任务 workspace memory。           |
| `plan_clear`    | 清空当前运行时 plan。                 | Defer         | 运维动作。                                  |
| `task_next`     | 显示下一批可执行 runtime task。        | Candidate     | 之后可映射到数据任务 backlog。                    |
| `task_list`     | 列出本地存储的 runtime task。         | Candidate     | 可支持数据任务状态。                             |
| `task_get`      | 通过 id 显示本地存储的 runtime task。   | Candidate     | 同上。                                    |
| `task_create`   | 创建本地存储的 runtime task。         | Defer         | 优先使用 task workspace。                   |
| `task_update`   | 更新本地存储的 runtime task。         | Defer         | 优先使用 task workspace。                   |
| `task_start`    | 标记任务为进行中。                     | Defer         | 优先使用 task workspace。                   |
| `task_complete` | 标记任务为完成。                      | Defer         | 优先使用 task workspace。                   |
| `task_block`    | 标记任务被阻塞。                      | Defer         | 优先使用 `open_questions.md`。              |
| `task_cancel`   | 标记任务被取消。                      | Defer         | 运维动作。                                  |
| `team_list`     | 列出本地配置的协作团队。                  | Defer         | 非核心 MVP。                               |
| `team_get`      | 显示某个本地配置的协作团队。                | Defer         | 非核心 MVP。                               |
| `team_create`   | 创建本地存储的协作团队。                  | Disable       | 非核心 MVP；属于变更动作。                        |
| `team_delete`   | 删除本地存储的协作团队。                  | Disable       | 破坏性运维动作。                               |
| `send_message`  | 发送本地协作消息。                     | Defer         | 之后在评审路由中可能有用。                          |
| `team_messages` | 显示已记录的协作消息。                   | Defer         | 之后在评审路由中可能有用。                          |
| `todo_write`    | 用结构化 todo list 替换当前本地运行时任务列表。 | Candidate     | 可用于 agent 自组织；但 task workspace 仍应是事实源。 |
| `TaskOutput`    | 通过 ID 获取后台任务输出。               | Defer         | 等异步数据任务存在后有用。                          |
| `TaskStop`      | 通过 ID 停止运行中的后台任务。             | Defer         | 等异步数据任务存在后有用。                          |

## Loop 特殊工具

| 工具               | 当前描述                | Data-Agent 处置 | 备注                                        |
| ---------------- | ------------------- | ------------- | ----------------------------------------- |
| `EnterPlanMode`  | 进入 plan mode。       | Special       | coding-agent 行为；可能会被 data-agent 任务规划指导替代。 |
| `ExitPlanMode`   | 退出 plan mode。       | Special       | 同上。                                       |
| `Agent`          | 为复杂任务启动一个新 agent。   | Defer         | 之后可用于并行挖掘 / 评审，但首版 MVP 应保持单 agent loop。   |
| `delegate_agent` | 旧版：把子任务委托给嵌套 agent。 | Disable       | 如果之后需要委托，优先使用 `Agent`。                    |
| `Skill`          | 在主对话中执行 skill。      | Special       | 作为概念入口保留，但基于目录的数据 skills 需要单独设计。          |

## 建议的 MVP Data Tool Registry

首版 data-agent 实验建议从这个最小注册表开始：

```text
list_dir
read_file
write_file
edit_file
glob_search
grep_search
ask_user_question
tool_search
```

原型阶段可选 MCP 桥接：

```text
mcp_list_resources
mcp_read_resource
mcp_list_tools
mcp_call_tool
```

当内部数据工具准备好后，应优先添加窄口径的数据专用工具，而不是暴露宽泛工具：

```text
search_online_sessions
sample_top_queries
find_similar_cases
mine_by_pattern
mine_by_model_disagreement
cluster_and_dedup
generate_eval_candidates
validate_eval_jsonl
run_router_eval
run_online_replay
create_annotation_queue
read_human_review_result
persist_dataset_artifact
```

## Data-Agent 改造实现说明

* 新增 `default_data_tool_registry()`，不要直接修改 `default_tool_registry()`。
* 第一阶段保留文件工具、人工评审工具，以及可选的 MCP discovery。
* 内部数据系统应通过稳定、可审计的数据工具暴露，而不是通过 `bash`、原始 SQL 或通用 `mcp_call_tool` 暴露。
* 将 `mcp_call_tool` 视为开发桥接；生产 data-agent 流程应使用面向目的构建的 wrapper tools。
* 工具权限应与数据治理动作对齐，而不只是与底层执行机制对齐。