工具 / 插件命令 !

1. 概述

! 前缀是一个面向高级用户的"逃生舱"：在对话 REPL 中直接运行 agent 的某个工具，或某个已安装插件的 CLI——无需让模型代劳。它仅在 chat 模式下生效（在 SQL/bash 模式下，开头的 ! 属于语句本身，例如 shell 的历史展开）。

!<tool> [args...]        # 直接运行一个 agent 工具
!<plugin> <args...>      # 运行某个已安装插件的 CLI（datus <plugin> ...）

优先匹配工具。 若首个 token 命中某个在线工具，则按工具执行；否则若命中某个已安装且已激活的插件，则分发到该插件的 CLI；两者都不命中时，报错并给出用法提示。

单独输入 ! 可列出可用的工具与插件。

2. 运行工具

!list_tables
!search_table user purchase --top_n=5
!describe_table orders

• 参数语法很简单：按 schema 顺序的位置参数，加上 --key=value 具名覆盖（裸 --flag 等价于 --flag=true）。列表支持 --items=a,b,c 或 --items=['a','b']。
• !<tool> --help 会打印该工具的参数 schema（名称 / 类型 / 是否必填 / 描述）。
• 每次调用都会经过与 LLM 驱动调用完全相同的权限管线：只读工具无需确认即可运行，而写操作（含 INSERT/DDL 的 execute_sql、bash、文件写入等）在当前权限档位下需要确认。被拒绝的调用不会执行（也不会发给模型）。
• 调用与结果会渲染为一个执行 turn（带样式的块，和 SQL/bash 模式一样）并喂给模型：本次执行进入对话上下文并触发一次回复，你可以紧接着追问相关内容。

自动补全

• 输入 ! 会弹出补全菜单，先列工具、后列插件，并在描述列标注类型。
• 在工具名之后输入 -- 可补全该工具的参数 flag 以及 --help。
• 选定工具/插件名后，输入行尾会以浅灰色显示 <必填> [--可选] 提示，随输入进度提示剩余参数名。

3. 运行插件 CLI

!hello sync orders --limit=100
!hello status

• !<plugin> <args...> 会以子进程方式运行 datus <plugin> <args...>。该命令像普通 bash 命令一样受权限门控，并且插件自身的 CLI 权限在子进程内同样生效。其输出会作为执行 turn 喂给模型（与 !<tool> 一致），进入对话并触发一次回复。
• 如果插件提供了命令信息，!<plugin> 补全器会列出可用命令并提示参数。补全也会 沿命令层级逐步展开，例如输入 !airflow dags 后，可以继续选择 list 或 trigger。

4. 说明

• ! 只在 chat 模式下运行。若要执行 SQL / shell，请用 Tab 循环切换输入模式（chat → sql → bash）。
• 工具命令与 Datus-CLI 进程同权限运行；权限档位（/permission）决定哪些工具操作会弹确认或被阻止。
• 插件执行受 agent.plugins_enabled 和项目级插件激活控制——只有已安装且已激活的插件才能通过 ! 访问。