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 实验建议从这个最小注册表开始：

list_dir
read_file
write_file
edit_file
glob_search
grep_search
ask_user_question
tool_search

原型阶段可选 MCP 桥接：

mcp_list_resources
mcp_read_resource
mcp_list_tools
mcp_call_tool

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

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。
• 工具权限应与数据治理动作对齐，而不只是与底层执行机制对齐。