DuckDB CLI 中的 Agent 模式DuckDB 团队2026-10-06 | 11 分钟TL;DRDuckDB v2.0 CLI 有一个 agent 模式能让 AI 编程代理更快、用更少 token 得到正确结果。当 CLI 检测到 agent 时它会打印紧凑的 Markdown 表格而不是带填充的方框明确说明结果何时被截断尽早停止失控查询并以 JSON 报告错误。长查询会在开始前公布其预期成本以便 agent 决定是否等待。DuckDB CLI 是为坐在终端前的人构建的。它的默认渲染器会填充列以便对齐在结果周围画边框并在列名下方打印列类型┌────────────┬───────┬────────┬───────────────┐ │ name │ n │ total │ avg_amount │ │ varchar │ int64 │ int128 │ decimal(10,2) │ ├────────────┼───────┼────────┼───────────────┤ │ customer_0 │ 3 │ 777 │ 259.00 │ │ customer_1 │ 3 │ 888 │ 296.00 │ └────────────┴───────┴────────┴───────────────┘对于大型结果它会显示前 20 行和后 20 行中间用一行点表示省略┌───────────────┬───────┬────────┬───────────────┐ │ name │ n │ total │ avg_amount │ │ varchar │ int64 │ int128 │ decimal(10,2) │ ├───────────────┼───────┼────────┼───────────────┤ │ customer_0 │ 3 │ 777 │ 259.00 │ │ customer_1 │ 3 │ 888 │ 296.00 │ │ · │ · │ · │ · │ │ · │ · │ · │ · │ │ customer_4998 │ 4 │ 1203 │ 300.75 │ │ customer_4999 │ 2 │ 510 │ 255.00 │ ├───────────────┴───────┴────────┴───────────────┤ │ 5000 rows (40 shown) 4 columns │ └────────────────────────────────────────────────┘人看到那些点和(40 shown)页脚就知道有行缺失。如今许多 CLI 调用根本不是来自人。像 Claude Code、Codex、Cursor、Gemini CLI 和 GitHub Copilot 这样的编程代理每次 shell 调用都会运行一次duckdb -c ...通过管道捕获 stdout并把文本传给语言模型。这已经迅速成为使用 DuckDB 的一种常见方式。这个读者与人有一些不同它没有终端所以没有滚动也没有分页器。它无法要求更多。打印出来的就是它看到的全部。它为读到的每一个 token 付费包括填充和边框字符。它通过对文本进行模式匹配来处理错误。对这个读者来说方框渲染器并不合适。对齐填充消耗 token而且对模型不携带任何信息。被截断的结果看起来也很像完整结果。页脚写着(40 shown)但模型可能扫过那一行然后从它从未看到的数据中得出结论。Agent 模式为这个读者改变了 CLI 的默认行为。本文描述 CLI 如何检测 agent、输出有什么变化以及如何尝试。注意Agent 模式随 DuckDB v2.0 一起发布。检测 AgentAgent 会用环境变量标记它们运行的命令。目前还没有单一约定因此 shell 会检查一个列表变量设置者AI_AGENT、AGENTClaude Code、Goose、AmpCLAUDECODEClaude CodeCODEX_CI、CODEX_SANDBOX、CODEX_THREAD_IDCodexCURSOR_AGENTCursorGEMINI_CLIGemini CLICOPILOT_AGENT、COPILOT_CLI、COPILOT_AGENT_SESSION_IDGitHub Copilot当三件事同时为真时agent 模式会开启这些变量之一被设置、stdout 不是终端并且命令行上没有给出输出格式。如果你传入-csv、-json或-markdown你要求了特定格式agent 模式就不会介入。有两个标志可以覆盖检测。-agent强制开启该模式-no-agent强制关闭。这两个标志可以与格式标志组合因此duckdb -agent -csv保留 agent 行为只改变行的打印方式。.show命令会报告该模式是否激活以及检测到了哪个 agentagent: claude-code并非每个 agent 都会设置变量。对于这些情况只要没有识别出 agent 且两个标志都未给出一次在写入管道时失败的运行会在 stderr 上打印一行提示hint: -agent renders errors as JSON and results compactly for AI coding agents (duckdb -help lists all options)一个没人告知该模式的 agent可以在第一次出错时通过这种方式发现它。Agent 模式中有什么变化以下所有内容都是默认值。诸如.mode、.maxrows、EXPLAIN (FORMAT ...)或你.duckdbrc中的任何显式设置仍然优先。紧凑表格结果以 Markdown 表格打印没有对齐填充列类型放在表头单元格中| name:VARCHAR | n:BIGINT | total:HUGEINT | avg_amount:DECIMAL(10,2) | |---|---|---|---| | customer_0 | 3 | 777 | 259.00 | | customer_1 | 3 | 888 | 296.00 |模型能读懂|分隔符不需要列对齐。由于这仍然是有效的 Markdown阅读 agent 记录的人会看到渲染后的表格。在典型结果上这种格式比方框输出小 25% 到 65%在宽结果上节省最多。大型结果打印每一行可以避免静默截断但一百万行在管道上就是 17 MB。Agent 模式会完整打印最多 1,000 行和 10,000 字节的结果。任何更大的结果都会变成前 20 行和后 20 行的样本中间有一个显式标记行页脚说明发生了什么| 19 | customer_19 | 13.3 | | … 4960 rows omitted … | | 4980 | customer_30 | 86.0 | ... first 20 and last 20 of 5000 rows (.maxbytes 0 for all), hash 7389c2f5ff3cefb6页脚还会告诉读者如何获取其余部分。限制可以用.maxrows N和.maxbytes N更改其中-1或0表示无限制。长单元格值会在 500 个字符处截断并带有可见标记例如…(4500 chars)可用.maxcellwidth N调整。尽早停止紧凑表格不需要列宽因此结果可以流式输出。一旦达到上限剩余行只被计数和哈希。再经过 100,000 行后查询被停止计数报告为下界。例如FROM range(1_000_000_000);这会在 30 毫秒内返回页脚为first 20 of at least 102400 rows (query stopped early; .maxrows -1 for all)。结果的哈希页脚包含整个结果的哈希覆盖上限之后的行。该哈希不依赖于行顺序并且区分NULL和字符串NULL。想要知道编辑后结果是否变化的 agent可以比较两个页脚而不必打印两次结果。页脚会在空结果、10 行或更多行的结果以及输出被截断时打印。当查询被提前停止时会省略它因为哈希无法覆盖整个结果。错误以 JSON 表示错误以 JSON 形式发送到 stderr使用现有的errors_as_json设置。由 shell 自身引发的错误例如未知的点命令也会被包装在同样的结构中{exception_type:Binder,exception_message:Referenced column \foo\ not found in FROM clause!\nCandidate bindings: \bar\,error_subtype:COLUMN_NOT_FOUND,location:[7,3],position:7,name:foo}Shell 会丢弃candidates字段因为消息中已经列出了候选者。如果没有这一改动单个“no matching function”错误就重达 2.7 kB。紧凑查询计划EXPLAIN默认使用一种新的紧凑格式每行一个运算符按深度缩进。估计值、实际行数和耗时放在括号中后面是运算符的属性UNGROUPED_AGGREGATE (est1) Aggregates: count_star() HASH_JOIN (est0) Join Type: INNER; Conditions: range range FILTER (est2) Expression: (r 2) RANGE (est10) Function: RANGE FILTER (est1) Expression: (s 2) RANGE (est5) Function: RANGEEXPLAIN ANALYZE以一行摘要开始例如QUERY (time0.0012s, read1.2 MB)。这是一种常规格式因此你也可以在 agent 模式之外使用EXPLAIN (FORMAT compact)。成本估计与进度当规划器预计某条语句要读取一百万行或更多时它的估计会在执行开始前发送到 stderrestimate: ~7501215 rows read (lineitem ~6001215, orders ~1500000), ~4 rows returned然后 agent 可以决定是等待还是中断并重写查询。较小的查询不会打印任何内容因为那行只会是噪音。当长查询运行时终端进度条被替换为每 5 秒在 stderr 上打印的一行纯文本progress: 42% (elapsed 12.0s, remaining ~16.5s) progress: done (elapsed 28.7s)列出表.tables每张表打印一行带有近似行数和列memory.main.t1 (table, ~15 rows): a INTEGER PK, b VARCHAR通常的方框布局通过管道很难阅读而这种格式让 agent 在一次调用中就获得 schema。启动行当 agent 模式通过检测开启时shell 会在运行任何内容之前在 stderr 上打印一行duckdb agent mode on: CLAUDECODE is set and stdout is not a terminal; -no-agent turns it off, .help agent explains the output这一行说明模式为何开启以及如何关闭它。第一个版本在每次运行时打印三行解释634 字节。那比大多数查询结果还大而且模型会在运行之间保留上下文所以它只需要解释一次。更长的文本可通过.help agent获取。它描述输出规则和设置并指出一些 agent 可能自己发现不了的功能SET max_execution_time ms为查询运行时间设置上限DESCRIBE query在不运行查询的情况下获取结果列SUMMARIZE快速分析表或查询.tables获取 schemaduckdb_functions()获取函数文档如果你不想要启动行请在~/.duckdbrc中添加.startup_text none。尝试一下如果你使用编程代理不需要配置任何东西。像 Claude Code、Codex、Cursor、Gemini CLI 和 GitHub Copilot 这样的 agent 已经设置了上表中的一个环境变量而且它们通过管道而不是终端捕获命令输出。这就是 agent 模式三个条件中的两个。因此只要 agent 路径上的 duckdb 二进制文件是 v2.0 或更新版本并且 agent 没有用-csv、-json或-markdown之类的标志请求特定输出格式该模式就会自行开启。格式标志被视为一种刻意选择因此它会关闭 agent 模式CLI 假定你想要正是那种格式不会覆盖它。要查看 agent 看到的内容请在设置了标志的情况下通过管道运行查询duckdb -agent -c SUMMARIZE FROM my_data.parquet | cat效果如何我们让 Claude 测量 agent 模式的效果。在实验中Claude Code 在一个规模因子为 100 的数据集上回答了 22 个 TPC-H 问题。问题用平实的英语表述没有任何 SQL。每个问题用 agent 模式回答三次用-no-agent回答三次。全部 132 次运行都产生了正确答案。使用 agent 模式时模型读取的 DuckDB 输出从 123.6k token 降到 50.8k token减少了 59%。Claude 对结果的总结如下“Agent 模式修复了终端 shell 中那些会悄悄误导模型的问题。当我通过 DuckDB CLI 回答 22 个 TPC-H 问题时agent 模式将我读回的 token 削减了 60%而且每个答案仍然正确。”—— Claude Fable 5.1节省并没有体现在总成本或运行时间上。每一轮都会重新读取 agent 的系统提示它比查询输出大得多因此节省的 token 约占总输入量的 0.5%。agent 模式的运行还稍微多花了几个回合237 对 224。Claude 在一份报告中写下了设置、完整结果和一个后续实验。结论使用 agent 模式agent 每次调用花费更少 token并且不会把部分结果当作完整结果来行动。这意味着得到正确结果的步骤更少。当前行为是第一次尝试围绕 agent 的约定仍在发展中。如果你的 agent 没有被检测到或者输出让它困惑请提交 issue 或在 pull request 下评论。agent 被困惑的记录尤其有用。进一步阅读Shellagent 模式当检测到 AI 编程代理时为其渲染pull request #26167Shell添加.mode llm的提案Carlo Piovesan 的提案字节预算和提前停止的基础