铃阅时讯
❌

阅读视图

从多模态大模型中「拆」出音频向量模型

原创 Jina AI 2026-03-12 15:03 新加坡

把任意多模态大模型变成小型音频向量模型

Google 最近发了 Gemini Embedding 2,他们第一个原生多模态向量模型。文本、图像、视频、音频、文档,全部映射到同一个 3072 维向量空间。这是 Omni Embedding(全模态向量模型)的大趋势:一个架构吃下所有模态,从 jina-embeddings-v4 到 Omni-Embed-Nemotron 再到 Omni-5,大家都在往这个方向收敛。

去年 EMNLP BoF 上我讲过:Omni 模型是 2026 年 Dense Retrieval 的关键方向之一。
去年 EMNLP BoF 上我讲过:Omni 模型是 2026 年 Dense Retrieval 的胜负手。

真正引起我们注意的是音频。大多数人听到多模态 Embedding 首先想到的是图像,顶多再加个视频。音频是被遗忘的模态:数据难采、标注难做、做的人少。

过去一段时间,我们 Jina AI 团队恰好在啃这块硬骨头:如何在 1.2B 规模内做出高性能的音频向量模型?这也是我们通向全模态愿景的关键一步。

趁着 Gemini Embedding 2 发布的节点,把我们一路上踩的坑和学到的东西分享给大家。

音频向量是什么

音频向量就是把一段音频压成一个定长向量。输入原始波形,模型输出一个稠密向量(通常 768 到 3072 维),编码了这段声音的语义内容。语义相似的两段音频,向量也相近;一段音频和它的文本描述,在共享向量空间中距离很短。这是 Omni Embedding 拼图里的一块:一旦音频能和文本、图像映射到同一个向量空间,跨模态检索就打通了。

2022 年以来的主流方案是 Contrastive Language-Audio Pretraining(CLAP),本质上就是把 CLIP 搬到音频域。思路很直接:一个音频编码器,一个文本编码器,中间用对比学习拉近配对的音频-文本、推远不配对的。LAION-CLAP 在这个基础上用 630K 对数据加 Feature Fusion 做了放大。当前最强变体(Elizalde et al., 2023)在 4.6M 对数据上训练,音频编码器横跨 22 种音频任务,配合自回归解码器,250M 参数量在 AudioCaps 上做到 42.0 cvR@5。

CLAP 的问题在哪?它从零开始学习音频和文本之间的对齐。这意味着你需要海量的配对数据去建立跨模态桥梁,460 万数据对不是白烧的。

我们走了一条完全不同的路:把已经听懂音频的多模态 LLM,直接改造成 Embedding 模型。 桥梁已经在预训练中建好了,我们要做的只是把它从生成模型重塑为向量模型。

模型架构

先说输入输出。输入是原始音频波形,从 WAV/MP3/FLAC 解码后重采样到 16kHz 单声道。音频编码器先转成 128-bin log-mel 频谱图,再处理成特征 token 序列,大约每秒 150 个 token。一段 10 秒音频约 1500 token。最大输入 30 秒,更长的需要切片。输出是单个稠密向量,维度在 896 到 3584 之间,取决于 LLM backbone 的规模。

起点是 Qwen2.5-Omni,一个原生音频理解的多模态 LLM。三个组件:

  • 音频编码器(约 0.6-0.8B 参数):把波形转成特征向量,中间有一个约 4.5M 参数的线性投影层。这个投影层虽小,却至关重要,它是音频特征空间到 LLM 表示空间的桥梁,负责把音频编码器输出的特征维度对齐到 LLM 的输入维度。

  • LLM backbone(0.5-7B 参数):每个 Transformer 层约 0.2B 参数,同时处理音频特征和文本 token。

  • 池化层:对最后一层 hidden state 做 mean pooling,输出最终向量。

两个模态共享同一个 LLM backbone。这不是我们做的对齐,是 Qwen2.5-Omni 在预训练时就建立的。音频特征和文本 token 经过同一堆 Transformer 层处理,在表示空间里天然就有一定程度的对齐。我们要做的是把这种隐式对齐显式化为一个向量模型。

架构对比
架构对比

左边是标准做法,端到端微调整个 MLLM(3-7B 参数)。右边是我们的模块化组合做法,把预训练音频编码器接到一个更小的 LLM backbone 上。共享 backbone 同时处理音频特征和文本 token,在同一个向量空间中生成 Embedding。

训练目标是 InfoNCE 对比损失。两个模态各自独立编码,双向计算 loss 后取平均:

deftraining_step(audio_batch, text_batch):
    audio_embeds = model.encode_audio(audio_batch)  # [B, D]
    text_embeds = model.encode_text(text_batch)      # [B, D]
    audio_embeds = F.normalize(audio_embeds, dim=-1)
    text_embeds = F.normalize(text_embeds, dim=-1)
    sim = audio_embeds @ text_embeds.T / temperature  # [B, B]
    labels = torch.arange(len(sim), device=sim.device)
    loss = (F.cross_entropy(sim, labels) +
            F.cross_entropy(sim.T, labels)) / 2
return loss

训练数据

五个音频-文本配对数据集,共 181K 样本:

数据集

样本量

说明

AudioSetStrong

108K

时序标注事件,GPT 生成字幕(AudioSet 子集)

FSD50K

41K

人工标注声音事件,200 类

Clotho

19K

音频字幕,详细描述

UrbanSound8K

9K

城市声音分类

MACS

4K

城市声学场景

CLAP 用了完整 AudioSet(200 万+音频)加上其他来源,总计 460 万对。我们只用了 AudioSetStrong 约 10 万条,数据量差了 25 倍。

为什么能少这么多?因为 CLAP 需要从零建立跨模态对齐,460 万对数据大部分精力花在教模型"什么声音对应什么文字"。而我们的起点是一个已经听懂音频的 MLLM,跨模态的桥已经造好了,训练只需要把这座桥从"生成"重新校准到"向量检索"。这是一个 fine-grained calibration,不是 from-scratch alignment。

defload_sample(audio_path, caption):
    waveform, sr = torchaudio.load(audio_path)
    waveform = torchaudio.transforms.Resample(sr, 16000)(waveform)
    audio_inputs = processor.feature_extractor(
        waveform, sampling_rate=16000, return_tensors="pt"
    )
    text_inputs = processor.tokenizer(caption, padding=True, return_tensors="pt")
return audio_inputs, text_inputs

四条路,三条半死胡同

我们的目标很明确:参数量压到 1.2B 以下,性能超过 CLAP。我们试了四种做法,前三种各有各的问题,在第四种拿到了结果,但过程本身比结果更有价值。

路径一:全模型微调

Qwen2.5-Omni-7B 直接在音频-文本对上做对比学习微调,结果不出意外地好:AudioCaps T2A cvR@5 = 63.2,Clotho T2A = 39.2。这个分数远超 CLAP 的 42.0,证明了思路本身是对的。但 7B 参数量摆在那里,推理成本和延迟都不现实。这条路的价值是给后面所有实验画了一条上限。

值得对比的是其他团队的类似尝试:Tevatron 2.0 也做全模型微调,但只用 AudioCaps 一个数据集,AudioCaps 上拿了 61.2,Clotho 上暴跌到 11.9。单数据集训练在分布内表现好看,出了分布立刻垮掉,这是向量模型老生常谈的问题了。还有 ColQwen-Omni,在视觉文档任务上微调、零音频数据,纯靠跨模态迁移拿到了 37.4。逼近 CLAP 但没超过。零数据能做到这一步,本身也说明 MLLM 的跨模态对齐的能力。

路径二:层剪枝

既然 7B 太大,能不能直接砍层?每个 Transformer 层约 0.2B 参数,从 28 层砍到 10 层就剩 3.5B,砍到 5 层剩 2.3B。

随 Transformer 层数减少的性能变化。
随 Transformer 层数减少的性能变化。

AudioCaps(红线)从 20 层的 63.2 降到 5 层的 56.0 cvR@5。所有配置仍然高于 CLAP baseline(虚线)。但即使砍到 5 层(2.3B 参数),离 1B 目标差了一倍多。

层数

参数量

AudioCaps T2A cvR@5

Clotho T2A cvR@5

20

5.8B

63.2

39.2

10

3.5B

58.2

36.5

5

2.3B

56.0

36.0

性能下降是平滑的,说明信息在各层间分布比较均匀,没有哪几层是可以无痛摘掉的。

另外一个有意思的观察是 Batch size(32、64、128)几乎没有影响最终性能。大 batch 在训练初期有优势,但后期可能过拟合负样本分布,batch 128 在 2K 步时 Clotho NDCG 打到 31.3,到 10K 步反而掉到 29.3。这说明在数据量有限的情况下,大 batch 带来的 hard negative 数量优势敌不过分布偏移的风险。

层剪枝的根本限制是:音频编码器本身就有 0.6-0.8B,加上投影层和 Embedding 层的固定开销,即使 LLM backbone 砍到零,模型也至少 1B 起步。此路不通。

路径三:纯文本模态迁移

这个思路更激进:完全不用任何音频-文本配对数据,只用纯文本 NLI 数据集(MultiNLI、SNLI、FEVER、SciFact)做微调。逻辑是这样的,MLLM 预训练时已经建立了音频和文本的对齐,那我只训练文本侧的向量质量,音频侧应该能搭上便车。

在完整 7B 上,这个赌注居然赢了:AudioCaps 46.1,超过了 CLAP 的 42.0。零音频训练数据,纯靠文本 NLI 就能做出一个比 CLAP 更好的音频向量模型,这本身就很说明问题,MLLM 预训练建立的跨模态对齐做得很深,不是表面功夫。

但在剪枝后的 10 层模型上,同样的做法直接塌了:cvR@5 = 5.9,几乎等于随机。

这里的 insight 很重要:跨模态对齐不是一个集中存储在某几层的对齐模块,而是分布在整个网络的每一层中。28 层的完整网络里,每一层都参与了音频和文本表示的渐进对齐。你砍掉大部分层,对齐就碎了。文本侧靠 NLI 数据还能补回来,但音频侧没有任何数据兜底,直接归零。

这条路教会我们的是:模态迁移的可行性和模型压缩的可行性是矛盾的。你不能同时既要又要。

路径四:模块组合

前三条路的共同问题是都从同一个 7B 模型出发往小了做。路径四我们换了一个思路:不从大模型上减,从小组件上加。 从一个模型里摘出音频编码器,从另一个模型里拿一个小 LLM backbone,拼在一起,甚至可以跨模型家族拼装。

为什么这也能行呢? 因为 Qwen2.5-Omni 的训练分了三阶段:1. 冻结 LLM,只训练音频/视觉编码器的投影层;2. 全参数解冻联合训练;3. 扩展到 32K 上下文。

关键在于第一阶段,音频编码器学会了如何把波形转成 LLM 能读懂的 token。这种说 LLM 语言的能力是通用的,不绑定某一个特定的 LLM。所以我们大胆假设:一个在第一阶段训练好的音频编码器,应该能直接插到任何 Qwen 系列的小 LLM 上。

我们测试了四种组合:

配置

音频编码器

LLM

参数量

M1

Qwen3-Omni(0.6B,stage-1 之前)

Qwen2.5-0.5B

1.1B

M2

Qwen3-Omni(0.6B,stage-1 之前)

Qwen2.5-3B

3.6B

M3

Qwen2.5-Omni-3B(0.8B,stage-3 之后)

Qwen2.5-3B

3.8B

M4

Qwen2.5-Omni-3B(完整)

完整 3B

3.8B

实现细节上有个坑,Qwen3-Omni 用的是 Qwen3OmniMoePreTrainedModel,standalone Qwen3 用的是 Qwen3ForCausalLM,两者的模型壳子不一样。我们的做法是初始化一个维度匹配的 Omni 模型壳子,然后把权重拷贝到对应位置。

各配置在 AudioCaps 和 Clotho T2A cvR@5 上的表现
各配置在 AudioCaps 和 Clotho T2A cvR@5 上的表现

用 stage-3 之后对齐更好的音频编码器效果更好(M3 vs M2:AudioCaps +4.2)。LLM 预训练的 stage 2-3 对 Embedding 质量影响不大(M3 vs M4 在误差范围内)。

结果里有三个发现:

第一,M1(1.1B)在 AudioCaps 上就打到了 49.7,超过 CLAP 的 42.0 整整 18%。 我们目标达成:参数量 1.1B,低于 1.2B 的目标线,性能大幅领先 CLAP,并且只用了 CLAP 1/25 的训练数据。

第二,音频编码器的对齐质量决定上限。 M3 用的是第三阶段之后完整训练过的音频编码器,M2 用的是 stage-1 之前的初始版本,两者 LLM backbone 相同(Qwen2.5-3B),但 M3 在 AudioCaps 上比 M2 高了 4.2 个点。这说明音频编码器在多阶段训练中获得的对齐精度直接传导到了最终的 Embedding 质量。

第三,LLM 的 stage 2-3 训练对 Embedding 质量几乎没有影响。 M3(拼装的 LLM)和 M4(原装完整 3B)的性能在误差范围内。这也意味着 LLM backbone 在 stage 2-3 学到的那些能力:更好的指令跟随、更长的上下文处理,对向量化任务没有贡献。向量模型需要的是表示能力,不是生成能力。

评测

音频 Embedding 的评测本质上就是看检索质量:给一段文本 query,能不能找到对的音频?

难点在于对的定义因数据集而异。

AudioCaps 的描述很具象("一个男人说话,然后门关上了"),这种描述和声学特征是一一对应的,模型只要记住声学 pattern 就能得分。

而 Clotho 的描述更抽象("安静的氛围中远处有隆隆声")。这需要模型理解场景级别的语义,而不只是频谱特征。一个只记住表面声学特征的模型在 AudioCaps 上跑分好看,到 Clotho 上就原形毕露。我们最看重的是跨描述风格的泛化能力,这才能反映模型真正理解了什么。

CV-Recall@5(cvR@5):对每个文本 query,看 top-5 结果中是否命中正确音频。二值打分,所有 query 取平均。这是 MTEB 音频检索的标准 metric。

defevaluate_cvr_at_k(model, dataset, k=5):
    audio_embeds = model.encode_audio(dataset.audio_clips)
    text_embeds = model.encode_text(dataset.text_queries)
    sim = F.normalize(audio_embeds) @ F.normalize(text_embeds).T
    hits = 0
for i in range(len(dataset.text_queries)):
        top_k = sim[:, i].argsort(descending=True)[:k]
if dataset.ground_truth[i] in top_k:
            hits += 1
return hits / len(dataset.text_queries)

三个评测集均来自 MTEB:AudioCaps(视频衍生,人工字幕)、AudioSetStrong(时序标注,GPT 描述)、Clotho(多样化,抽象字幕)。CLAP 用了完整 AudioSet(200 万+),我们只用了 AudioSetStrong 约 10 万条,这在一定程度上解释了 CLAP 在该 benchmark 上的优势。

所有配置在 AudioCaps、AudioSetStrong、Clotho T2A 检索上的横向对比
所有配置在 AudioCaps、AudioSetStrong、Clotho T2A 检索上的横向对比

红色虚线为 CLAP baseline。模块组合方案(绿色)以远远更小的模型尺寸取得了有强竞争力的结果。全量微调的 7B 模型(深蓝)是性能上限。

应用场景

传统的音频检索里,输入文字找音效当然是最直接的场景。但更值得关注的是音频 Embedding 在 Agentic 系统中的角色。当语音成为 Agent 的主要输入方式时,第一步往往是 ASR 转文字再处理。但 ASR 有延迟、会丢失语气语调信息、还依赖转写质量。如果 Agent 能直接对语音输入做向量化,根据语义相似度分发到正确的工具或子 Agent,就跳过了 ASR 这个瓶颈。不是所有语音输入都需要逐字转写,很多时候你只需要知道"这段话的意图是什么"。

工业场景里的声音事件分类也是一个被低估的方向。设备异响检测、安防系统、智能家居,这些场景需要的不是转写,而是"这个声音像什么",这正是 Embeddings 的强项。

更远一步看,当 Omni Embedding 做成了,文本、图像、音频、视频都在一个向量空间里,Agent 就获得了一个统一的感知接口。不管输入是什么模态,都转成向量后统一检索、比较、推理。这是多模态 Agent 能真正 scale 的前提。

而这一切有个硬性前提:模型要够小,能在端侧跑。 语音交互容不下云端传输带来的延迟损耗,而且语音数据的隐私敏感度远高于文本。所以高性能的小模型不是加分项,而是入场券。这也是我们把目标定在 1.2B 以下的原因。

结论

预训练 MLLM 是做新模态 Embedding 最大的杠杆。 它一次性提供了跨模态对齐、强文本编码器和能力不错的音频编码器。

模块化组合是目前最有前景的方向。 从不同模型、不同训练阶段里拆出组件自由拼装,我们在音频向量任务上验证了可行性。实验结果也指向了一个清晰优先级:音频编码器的对齐质量是第一位的(stage-3 vs pre-stage-1 差了 4.2 个点),LLM backbone 的生成能力对向量化任务没有贡献(stage 2-3 训练前后没有差异)。这也意味着构建向量模型时,选组件的优先级是:编码器对齐 > LLM 的表示能力 > LLM 的其他能力。

跨模态迁移和模型压缩不能既要又要。 文本模态迁移在完整 7B 上漂亮地跑通了(46.1 vs CLAP 42.0),但在 10 层剪枝模型上直接归零(5.9)。对齐分布在整个网络中,压缩就碎。

AudioCaps 领跑不代表问题解决了。 我们模型在 AudioCaps 上大幅领先 CLAP,但在更依赖抽象语义的 Clotho 榜单上只是持平。暴露了模型的场景级语义理解不够。只看 AudioCaps 你会觉得模型已经很好了;加上 Clotho 就知道还差得远。

这项工作是我们迈向 Omni Embedding(全模态向量模型)的关键一步,模块化组合让我们找到了无需大规模烧数据即可开启新模态的方法,但 Clotho 的结果提醒我们:光靠复用预训练组件还不够,数据质量和多样性仍然是底层硬约束。

接下来我们会探索 MoE 架构把激活参数压到 500M 以下,尝试模块组合和模态迁移的深度结合,引入 WavCaps、MusicCaps 和语音数据集做数据扩充,重点补上抽象描述的短板。

我们开源社区见!https://github.com/jina-ai/audio-embedding-kickstarter

阅读原文

跳转微信打开

  •  

CLI is All Agents Need — *nix Agent 设计宝典

原创 yan5xu 2026-03-12 11:55 北京

oi! 这真的是我觉得最好的 agent 架构啊啊啊啊啊,真的不要来看看吗!!!

Why a single run(command) outperforms sprawling tool catalogs

当所有人在为 Agent 设计复杂的函数调用框架时,我发现:一个 run(command="...") 就够了。

本文由 AI Agent 协作完成,但每一个设计决策、每一次生产踩坑、以及把它们提炼成原则的思考过程,都是本人完成的。

为什么是 *nix

Unix 在 50 年前做了一个设计决策:一切皆文本流。 程序之间不交换复杂的二进制结构,不共享内存对象——它们通过文本管道沟通。小工具各司其职,通过 | 组合成强大的工作流。程序用 --help 描述自己,用 exit code 报告成败,用 stderr 传递错误上下文。

LLM 在 50 年后做了一个几乎相同的决策:一切皆 token。 它只理解文本,只输出文本。它的"思考"是文本,它的"行动"是文本,它从世界获得的反馈也必须是文本。

这两个决策跨越半个世纪,从完全不同的出发点,收敛到了同一个接口模型。Unix 为人类终端操作者设计的文本系统——cat、grep、pipe、exit code、man page——对 LLM 来说不是"也能用",而是天然适配。LLM 在工具使用这件事上,本质就是一个终端操作者,只不过它比任何人类都快,而且它的训练数据里有大量 shell 命令与 CLI 用例。

这就是 *nix Agent 的核心哲学:不发明新的工具接口,把 Unix 已经验证了 50 年的设计直接交给 LLM。

为什么只有一个 run

单工具假说

主流 Agent 框架给 LLM 一堆独立工具:

tools: [search_web, read_file, write_file, run_code, send_email, ...]

LLM 每次调用前要做工具选择——用哪个?参数怎么填?工具越多,选择越难,准确率越低。认知负荷花在了"选工具"上,而不是"解决问题"上。

我的做法:一个 run(command="..."),所有能力通过 CLI 命令暴露。

run(command="cat notes.md")
run(command="cat log.txt | grep ERROR | wc -l")
run(command="see screenshot.png")
run(command="memory search 'deployment issue'")
run(command="clip sandbox bash 'python3 analyze.py'")

LLM 仍然需要选择"用什么命令",但这和"从 15 个不同 schema 的工具中选一个"是完全不同的认知任务。命令选择是在一个统一的 namespace 里做字符串组合——而函数选择是在多个不相关的 API 间做模式切换。

LLM 的 CLI 母语

为什么 CLI 命令比结构化函数调用更适合 LLM?

因为 LLM 的训练数据里,CLI 是最密集的工具使用范式。GitHub 上数十亿行代码充满了:

# README 里的安装指南
pip install -r requirements.txt && python main.py
# CI/CD 里的构建脚本
make build && make test && make deploy
# Stack Overflow 里的解决方案
cat /var/log/syslog | grep "Out of memory" | tail -20

我不需要教 LLM 如何使用 CLI——它已经会了。这种熟悉度是概率性的、模型相关的,但在主流模型上经验证非常可靠。

对比两种方式完成同一个任务:

任务:读取日志文件,找出错误行数
函数调用方式(3 次 tool call):
  1. read_file(path="/var/log/app.log") → 返回完整文件
  2. search_text(text=<entire file>, pattern="ERROR") → 返回匹配行
  3. count_lines(text=<matched lines>) → 返回数字
CLI 方式(1 次 tool call):
  run(command="cat /var/log/app.log | grep ERROR | wc -l")
  → "42"

一次调用替代三次。不是因为做了特殊优化——而是 Unix 管道天然支持组合。

让管道和链式执行成为可能

光有一个 run 不够。如果 run 只能执行单条命令,LLM 还是要多次调用才能完成组合任务。所以我在命令路由层实现了一个链式解析器(parseChain),支持四种 Unix 操作符:

|   管道:前一个命令的 stdout 作为后一个的 stdin
&&  与链:前一个成功才执行后一个
||  或链:前一个失败才执行后一个
;   顺序:无论前一个成败都执行后一个

有了这个机制,LLM 的每一次 tool call 都可以是一个完整的工作流:

# 一次 tool call:下载 → 查看
curl -sL $URL -o data.csv && cat data.csv | head 5
# 一次 tool call:读文件 → 过滤 → 排序 → 取前 10
cat access.log | grep "500" | sort | head 10
# 一次 tool call:尝试 A,失败则尝试 B
cat config.yaml || echo "config not found, using defaults"

N 个命令 × 4 种操作符,组合空间急剧扩大。而在 LLM 看来,这只是一个字符串——它已经从训练数据里学会了怎么写。

命令行就是 LLM 的母语工具接口。

启发式设计:让 CLI 引导 Agent 顺滑工作

单工具 + CLI 解决了"用什么"的问题,但 Agent 还需要知道 "怎么用"。它没有搜索引擎,没有同事可以问。我通过三个递进的设计手段,让 CLI 自身成为 Agent 的导航系统。

手段一:渐进式 --help 自发现

一个设计良好的 CLI 工具,用户不需要读文档就能上手——因为 --help 告诉了一切。我把同样的理念用在 Agent 身上,并且做成了渐进式披露:Agent 不需要一次加载所有文档,而是按需逐层深入。

第零层:Tool Description → 命令列表注入

run 工具的 description 在每次对话开始时动态生成,列出当前所有已注册命令的一行摘要:

Available commands:
  cat    — Read a text file. For images use 'see'. For binary use 'cat -b'.
  see    — View an image (auto-attaches to vision)
  ls     — List files in current topic
  write  — Write file. Usage: write <path> [content] or stdin
  grep   — Filter lines matching a pattern (supports -i, -v, -c)
  memory — Search or manage memory
  clip   — Operate external environments (sandboxes, services)
  ...

Agent 从第一轮就知道有哪些能力,但不需要知道每个命令的所有参数——那会浪费上下文。

注: 命令列表全量注入 vs 按需发现,随着命令增多这里存在上下文预算的权衡。目前还在探索更优的平衡方式,欢迎讨论。

第一层:command(无参数)→ 命令用法

Agent 对某个命令感兴趣时,直接调用它。没给参数?命令返回自己的用法:

→ run(command="memory")
[error] memory: usage: memory search|recent|store|facts|forget
→ run(command="clip")
  clip list                              — list available clips
  clip <name>                            — show clip details and commands
  clip <name> <command> [args...]         — invoke a command
  clip <name> pull <remote-path> [name]   — pull file from clip to local
  clip <name> push <local-path> <remote>  — push local file to clip

现在 Agent 知道 memory 有五个子命令,clip 可以 list/pull/push。只花了一次调用,没有多余信息。

第二层:command subcommand(缺参数)→ 具体参数

Agent 决定用 memory search,但不确定参数格式?继续深入:

→ run(command="memory search")
[error] memory: usage: memory search <query> [-t topic_id] [-k keyword]
→ run(command="clip sandbox")
  Clip: sandbox
  Commands:
    clip sandbox bash <script>
    clip sandbox read <path>
    clip sandbox write <path>
  File transfer:
    clip sandbox pull <remote-path> [local-name]
    clip sandbox push <local-path> <remote-path>

渐进式披露:概览(注入)→ 用法(探索)→ 参数(深入)。 Agent 按需探索,每一层只获取当前需要的信息量。

这和把所有文档塞进 system prompt 是完全不同的思路。system prompt 里塞 3000 字的工具文档,大部分信息在大部分时候都用不到——白白占用上下文预算。渐进式 help 让 Agent 自己决定什么时候需要更多信息。

这也对命令设计提出了要求:每个命令、每个子命令都必须有完整的 help 输出。 不仅是给人看的,更是给 Agent 看的。一条好的 help 能让 Agent 一步到位,一条缺失的 help 意味着一次盲猜。

手段二:Error Message 纠偏

Agent 不可能永远走对路。关键不是阻止它犯错,而是让每个错误都指向正确方向。

传统 CLI 的错误信息给人看——人可以 Google。Agent 不能 Google。所以我要求每个错误同时包含"出了什么问题"和"该怎么做":

传统 CLI:
  $ cat photo.png
  cat: binary file (standard output)
  → 人会 Google "how to view image in terminal"
我的设计:
  [error] cat: binary image file (182KB). Use: see photo.png
  → Agent 直接调用 see,一步修正

更多例子:

[error] unknown command: foo
Available: cat, ls, see, write, grep, memory, clip, ...
→ Agent 立刻知道有哪些命令
[error] not an image file: data.csv (use cat to read text files)
→ Agent 从 see 切换到 cat
[error] clip "sandbox" not found. Use 'clip list' to see available clips
→ Agent 知道先列出 clips

手段一(help)解决"我能做什么"。手段二(error)解决"做错了怎么办"。两者配合,Agent 的试错成本极低——通常 1-2 步就能找到正确路径。

真实案例:stderr 被丢弃的代价

有段时间,我的代码在调用外部沙箱时,如果 stdout 非空就丢弃 stderr。Agent 运行 pip install pymupdf,exit code 127。stderr 里有 bash: pip: command not found,但 Agent 看不到。它只知道"失败了",不知道"为什么"——于是盲猜了 10 种包管理器:

pip install         → 127  (不存在)
python3 -m pip      → 1    (模块不存在)
uv pip install      → 1    (用法错误)
pip3 install        → 127
sudo apt install    → 127
... 又试了 5 种 ...
uv run --with pymupdf python3 script.py → 0 ✓  (第 10 次)

修复后 stderr 永远可见,Agent 第一次就看到 "pip: command not found",立刻换方向。

stderr 是 Agent 最需要的信息,恰恰在命令失败的时候。永远不要丢弃它。

手段三:Output Format 持续反馈

前两个手段解决了 Agent 的"发现"和"纠错"。第三个让 Agent 在持续执行过程中越来越懂系统。

我在每个 tool result 末尾追加一致的元数据:

file1.txt
file2.txt
dir1/
[exit:0 | 12ms]

LLM 从中提取两个信号:

退出码(Unix 约定,LLM 已掌握):

  • exit:0

     — 成功

  • exit:1

     — 一般错误

  • exit:127

     — 命令不存在

耗时(成本感知):

  • 12ms

     — 廉价操作,可以放心多调

  • 3.2s

     — 中等成本

  • 45s

     — 昂贵操作,需要谨慎

Agent 在对话中看到几十次 [exit:N | Xs] 后,内化了这个模式。它开始预判——看到 exit:1 就知道检查错误,看到耗时很长就减少调用。

一致的输出格式让 Agent 越用越聪明。不一致让每次都像第一次。

三个手段的递进关系:

--help       →  "我能做什么?"       →  主动发现
Error Msg    →  "做错了怎么办?"     →  被动纠偏
Output Fmt   →  "做得怎么样?"       →  持续学习

双层架构:把启发式设计落地的工程

上面讲了 CLI 如何在语义层面引导 Agent。但要真正落地,还需要解决一个工程问题:CLI 执行的原始输出,和 LLM 需要看到的结果,往往不是一回事。

LLM 的两个硬约束

约束 A:上下文窗口有限且昂贵。 每个 token 消耗金钱、注意力、推理速度。一个 10MB 文件全文塞进上下文,不仅浪费,还会把之前的对话挤出窗口——Agent "失忆"。

约束 B:LLM 只能处理文本。 二进制数据经过 tokenizer 产生高熵无意义的 token。它不仅浪费上下文,还会扰乱周围有效 token 的注意力,导致推理质量下降。

这两个约束决定了:命令的原始输出不能直接扔给 LLM——需要一个呈现层做加工。但加工不能影响命令的执行逻辑——否则管道会坏。所以需要分层。

执行层 vs 呈现层

┌─────────────────────────────────┐
│  Layer 2: LLM 呈现层             │  ← 为 LLM 认知约束设计
│  二进制拦截 | 截断+溢出 | 元数据    │
├─────────────────────────────────┤
│  Layer 1: Unix 执行层             │  ← 纯 Unix 语义
│  命令路由 | pipe | chain | exit   │
└─────────────────────────────────┘

当 cat bigfile.txt | grep error | head 10 执行时:

Layer 1 内部:
  cat 输出 → [500KB 原始文本] → grep 输入
  grep 输出 → [匹配的行] → head 输入
  head 输出 → [前 10 行]

如果在 Layer 1 截断 cat 的输出 → grep 只搜到前 200 行,结果不完整。如果在 Layer 1 加 [exit:0] → 它作为文本流入 grep,变成搜索内容。

所以 Layer 1 必须保持原始、无损、无元数据。加工只在 Layer 2 发生——管道链执行完毕,最终结果准备返回给 LLM 时。

Layer 1 服务于 Unix 语义。Layer 2 服务于 LLM 认知。分层不是设计偏好,是逻辑必然。

Layer 2 的四个机制

机制 A:二进制守卫(应对约束 B)

在返回给 LLM 之前,检查内容是否为文本:

检测到 null byte → 二进制
UTF-8 校验失败 → 二进制
控制字符比例 > 10% → 二进制
如果是图片:[error] binary image (182KB). Use: see photo.png
如果是其他:[error] binary file (1.2MB). Use: cat -b file.bin

LLM 永远不会收到它无法处理的数据。

机制 B:溢出模式(应对约束 A)

输出 > 200 行 或 > 50KB?
  → 截断到前 200 行(rune-safe,不切断 UTF-8)
  → 完整输出写入 /tmp/cmd-output/cmd-{n}.txt
  → 返回给 LLM:
    [前 200 行内容]
    --- output truncated (5000 lines, 245.3KB) ---
    Full output: /tmp/cmd-output/cmd-3.txt
    Explore: cat /tmp/cmd-output/cmd-3.txt | grep <pattern>
             cat /tmp/cmd-output/cmd-3.txt | tail 100
    [exit:0 | 1.2s]

关键洞察:LLM 已经知道如何用 grep、head、tail 导航文件。溢出模式把"大数据探索"转化为 LLM 已掌握的技能。

机制 C:元数据脚注

actual output here
[exit:0 | 1.2s]

退出码 + 耗时,追加在 Layer 2 的最后一行。给 Agent 判断成败和感知成本的依据,同时不污染 Layer 1 的管道数据。

机制 D:stderr 附加

命令失败且有 stderr 时:
  output + "\n[stderr] " + stderr
确保 Agent 能看到错误原因,不会盲目重试。

实现:agent-clip 核心代码

以下为简化的伪代码,突出架构骨架。完整实现见源码仓库。

单工具定义

// LLM 只看到一个工具:run(command, stdin?)
// 所有命令及帮助文本列在 description 里
func RunToolDef(commands map[string]string) ToolDef {
    desc := "Execute commands via run(command=\"...\").\n"
    desc += "Supports chaining: cmd1 && cmd2, cmd1 | cmd2.\n\n"
    for name, help := range commands {
        desc += "  " + name + " — " + help + "\n"
    }
    return ToolDef{
        Name: "run",
        Description: desc,
        Parameters: { command: string, stdin?: string },
    }
}

Layer 1:命令路由与管道

// Exec 解析命令链,执行管道,返回原始输出 + 退出码
// 这里是纯 Unix 语义——没有截断,没有元数据,没有二进制检测
func (r *Registry) Exec(command, stdin string) (string, int) {
    segments := parseChain(command)  // 按 &&, ||, |, ; 分割
    for i, seg := range segments {
        if prevOp == OpAnd && lastExitCode != 0 { continue }
        if prevOp == OpOr && lastExitCode == 0  { continue }
        if prevOp == OpPipe { stdin = lastOutput }
        lastOutput, lastExitCode = r.execSingle(seg, stdin)
    }
    return lastOutput, lastExitCode
}
func (r *Registry) execSingle(command, stdin string) (string, int) {
    name, args := tokenize(command)
    handler, ok := r.handlers[name]
    if !ok {
        return "[error] unknown command: " + name + "\nAvailable: ...", 127
    }
    output, err := handler(args, stdin)
    if err != nil {
        return "[error] " + name + ": " + err.Error(), 1
    }
    return output, 0
}

Layer 2:LLM 呈现层

// execToolCall 把 Layer 1 的原始结果加工成 LLM 能理解的格式
// 所有的截断、溢出、元数据包装都在这里发生
func execToolCall(registry *Registry, tc ToolCall) string {
    command, stdin := parseToolCallArgs(tc)
    // Layer 1: 纯执行
    start := time.Now()
    rawOutput, exitCode := registry.Exec(command, stdin)
    duration := time.Since(start)
    metadata := fmt.Sprintf("[exit:%d | %s]", exitCode, duration)
    // 失败时直接返回(execSingle 已加 [error] 前缀 + stderr)
    if exitCode != 0 {
        return rawOutput + "\n" + metadata
    }
    // 截断检查(仅超限时才持久化到 /tmp)
    result := rawOutput
    if tooLarge(rawOutput) {
        truncated := first200LinesRuneSafe(rawOutput)
        file := persistToTmp(rawOutput)
        result = truncated + "\n--- truncated ---\nFull output: " + file
    }
    return result + "\n" + metadata
}

二进制守卫

func fsCat(args []string, stdin string) (string, error) {
    data := readFile(path)
    // 二进制守卫:拦截 LLM 无法处理的数据,引导到正确命令
    if !base64Flag && isBinary(data) {
        if isImage(path) {
            return error("binary image (%s). Use: see %s", size, path)
        }
        return error("binary file (%s). Use: cat -b %s", size, path)
    }
    return string(data), nil
}
func isBinary(data []byte) bool {
    sample := data[:min(8192, len(data))]
    if containsNull(sample)       { return true }  // null byte = 一定是二进制
    if !utf8.Valid(sample)        { return true }  // 非法 UTF-8 = 大概率二进制
    if controlRatio(sample) > 0.1 { return true }  // 控制字符太多
    return false
}

Vision 自动挂载

// Agent 不需要显式请求"看图"——see 返回的 URL 被自动挂载到 vision 通道
func extractImagesFromResult(result string) []ImageData {
    urls := findImageURLs(result)  // 匹配 pinix-data://...png
    for _, url := range urls {
        data := readFile(urlToPath(url))
        images = append(images, ImageData{
            Base64:   base64Encode(data),
            MimeType: detectMIME(url),
        })
    }
    return images  // 附加到下一轮 LLM 调用的 vision 内容
}

Agentic Loop

func RunLoop(config, context, registry, output) {
    // 不设硬性迭代上限。LLM 不调用工具时循环自然结束。
    // 如果 Agent 还在调工具,说明它认为任务没完成——
    // 我通过前面的启发式设计(help / error / output format)
    // 让它更快到达终点,而不是粗暴截断它的执行。
    //
    // 实际安全边界由外部机制保障:沙箱隔离、API 预算、用户取消。
    for {
        response := callLLM(context)
        if response.hasToolCalls() {
            for _, tc := range response.toolCalls {
                result := execToolCall(registry, tc)      // Layer 2 包装
                images := extractImagesFromResult(result)  // vision 挂载
                context.append(toolResult(result, images))
            }
            continue
        }
        // LLM 没有调用工具 = 任务完成
        return response.content
    }
}

经验教训:来自生产的故事

故事 1:一张 PNG 引发的 20 轮崩溃

用户上传了一张架构图。Agent 用 cat 读取,收到 182KB 的 PNG 原始字节。LLM 的 tokenizer 把这些字节变成数千个无意义的 token,塞进上下文。LLM 完全无法理解,开始反复尝试不同的读取方式——每次都返回同样的乱码。20 轮后进程被强制终止。

根因:cat 没有二进制检测,Layer 2 没有拦截。修复:isBinary() 守卫 + 错误引导 Use: see photo.png。教训: Tool result 是 Agent 的眼睛。返回垃圾 = Agent 失明。

故事 2:沉默的 stderr 与 10 次盲猜

Agent 需要读取一个 PDF。它尝试 pip install pymupdf,exit code 127。但 stderr(bash: pip: command not found)被代码丢弃了——因为有一小段 stdout,代码逻辑是"有 stdout 就忽略 stderr"。

Agent 只看到"失败了",不知道"为什么"。接下来是漫长的试错:

pip install         → 127  (不存在)
python3 -m pip      → 1    (模块不存在)
uv pip install      → 1    (用法错误)
pip3 install        → 127
sudo apt install    → 127
... 又试了 5 种 ...
uv run --with pymupdf python3 script.py → 0 ✓

10 次调用,每次 ~5 秒推理。如果第一次 stderr 可见,1 次就够了。

根因:InvokeClip 在有 stdout 时静默丢弃 stderr。修复: 失败时永远附加 stderr。教训: stderr 是 Agent 最需要的信息,恰恰在命令失败的时候。

故事 3:溢出模式的价值

Agent 分析一个 5000 行的日志文件。没有截断时,5000 行全文(~200KB)塞进上下文,LLM 的注意力被淹没,回答质量骤降,还把之前的对话挤出了上下文窗口。

加了溢出模式后:

[前 200 行日志内容]
--- output truncated (5000 lines, 198.5KB) ---
Full output: /tmp/cmd-output/cmd-3.txt
Explore: cat /tmp/cmd-output/cmd-3.txt | grep <pattern>
         cat /tmp/cmd-output/cmd-3.txt | tail 100
[exit:0 | 45ms]

Agent 看到前 200 行,了解了文件结构,然后用 grep 精准定位——总共 3 次调用,上下文占用不到 2KB。

教训: 给 Agent 一个"地图"比给它"全部领土"有效得多。

边界与局限

CLI 不是银弹。以下场景中,typed API 可能是更好的选择:

  • 强类型交互

    :数据库查询、GraphQL API 等需要结构化输入输出的场景,schema 验证比字符串解析更可靠。

  • 高安全要求

    :CLI 的字符串拼接天然带有注入风险。在不可信输入场景中,typed parameters 比命令字符串更安全。agent-clip 通过沙箱隔离来缓解这个问题。

  • 多模态原生

    :纯音视频处理等需要二进制流的场景,CLI 的文本管道是瓶颈。

此外,"不设迭代上限"不意味着没有安全边界。实际安全由外部机制保障:

  • 沙箱隔离

    :命令在 BoxLite 容器内执行,无法逃逸

  • API 预算

    :LLM 调用有账户级别的费用上限

  • 用户取消

    :前端提供取消按钮,后端支持 graceful shutdown

把 Unix 哲学交给执行层,把 LLM 的认知约束交给呈现层,用 help、error message 和 output format 构建三个递进的启发式导航手段。

CLI is all agents need.

以上所有设计在 agent-clip 中均有完整实现。核心代码对应关系:

  • 单工具命令路由 → internal/tools.go

  • 管道与链式执行 → internal/chain.go

  • 双层 agentic loop → internal/loop.go

  • 文件系统与二进制守卫 → internal/fs.go

  • 外部环境调用与 stderr 处理 → internal/clip.go

  • 浏览器自动化与 vision 挂载 → internal/browser.go

  • 语义记忆与向量搜索 → internal/memory.go

Built with Go. Powered by Unix. Designed for LLMs.

阅读原文

跳转微信打开

  •  
❌